feat(library): italic abstract classes/methods and lowercase UML class keywords (#799)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

.changeset/class-abstract-and-keywords.md

@@ -0,0 +1,12 @@
+---
+"@tumaet/apollon": minor
+---
+
+Fix UML class-diagram notation and let methods be marked abstract.
+
+- **Abstract is now UML-correct.** An abstract class shows an _italic_ name instead of the invalid `«Abstract»` keyword — UML has no `«abstract»` keyword; abstractness is a property, not a stereotype (UML 2.5.1 §9.2.4). The italic is a real shipped Inter italic face, so it renders the same in the editor and in PNG, PDF, and PowerPoint exports — no more `{abstract}` text fallback for a slant that used to vanish on export.
+- **Metaclass keywords are lowercase.** Interfaces and enumerations render `«interface»` / `«enumeration»` — the exact UML keyword spelling (2.5.1 Table C.1) — instead of the capitalized forms.
+- **New: abstract methods.** Mark any method abstract from the class editor (a per-method toggle) to render its signature in italics. Attributes are deliberately not offered the control: UML attributes cannot be abstract. Closes #105.
+- **A single "Class type" picker.** The class editor now sets the classifier with one dropdown — `Class`, `Abstract Class`, `Interface`, `Enumeration` — mirroring the four palette tiles and the other node/edge "type" selects, with a notation preview on each option. It replaces a checkbox-plus-toggle pair that could produce invalid states (an italic `«interface»`, or an abstract enumeration); those states are now unrepresentable, and any earlier diagram carrying one self-heals on load.
+
+Diagrams saved earlier migrate automatically on load — a class stored with the old `"Abstract"` stereotype becomes `isAbstract`, `"Interface"` / `"Enumeration"` are lowercased to their keyword spelling, and a stray abstract modifier on a keyword is dropped.

.github/workflows/update-visual-baselines.yml

@@ -50,6 +50,9 @@ jobs:
         run: pnpm --filter @tumaet/webapp run test:visual:update
 
       - name: Commit and push refreshed baselines
+        # Force bash: the container otherwise runs this under dash, which rejects
+        # `set -o pipefail` and fails the step before it can push.
+        shell: bash
         env:
           REF: ${{ github.event.inputs.ref }}
         run: |
@@ -58,9 +61,12 @@ jobs:
           git config --global --add safe.directory "$GITHUB_WORKSPACE"
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          # Scope strictly to snapshot PNGs so a render bug can't smuggle other
-          # tree changes back onto the branch.
-          git add 'standalone/webapp/tests/**/*-snapshots/*.png'
+          # Scope strictly to generated snapshot PNGs so a render bug can't
+          # smuggle other tree changes back onto the branch. The how-to-use modal
+          # assets are regenerated by the same run (howto-assets project) but land
+          # under assets/images/, not a *-snapshots dir, so stage them explicitly.
+          git add 'standalone/webapp/tests/**/*-snapshots/*.png' \
+            'standalone/webapp/assets/images/how-to-use-*.png'
           if git diff --cached --quiet; then
             echo "Baselines already match — nothing to commit." >> "$GITHUB_STEP_SUMMARY"
             exit 0

library/lib/apollon-editor.tsx

@@ -14,6 +14,11 @@ import {
   getSVG,
   getRenderedDiagramBounds,
 } from "./utils"
+// Internal (not re-exported through the public `./utils` barrel): brings any
+// incoming model onto the current schema (e.g. legacy class stereotypes) at
+// every hydration boundary, since editor load does NOT route through the public
+// `importDiagram`.
+import { normalizeModel } from "./utils/versionConverter"
 import { UMLDiagramType } from "./types"
 import { createDiagramStore, type DiagramStore } from "@/store/diagramStore"
 import { createMetadataStore, type MetadataStore } from "@/store/metadataStore"
@@ -161,12 +166,13 @@ export class ApollonEditor {
       .updateMetaData(diagramName, parseDiagramType(diagramType))
 
     if (options?.model) {
-      const nodes = options.model.nodes || []
-      const edges = options.model.edges || []
-      const assessments = options.model.assessments || {}
+      const model = normalizeModel(options.model)
+      const nodes = model.nodes || []
+      const edges = model.edges || []
+      const assessments = model.assessments || {}
       this.diagramStore.getState().setNodesAndEdges(nodes, edges)
       this.diagramStore.getState().setAssessments(assessments)
-      this.diagramStore.getState().setInteractive(options.model.interactive)
+      this.diagramStore.getState().setInteractive(model.interactive)
     }
 
     if (options?.mode) {
@@ -498,6 +504,9 @@ export class ApollonEditor {
     model: Apollon.UMLModel,
     options?: Apollon.ExportOptions
   ): Promise<Apollon.SVG> {
+    // Off-screen render path bypasses the constructor, so normalize here too
+    // (in place) — otherwise a legacy model exports with the old stereotypes.
+    normalizeModel(model)
     const container = document.createElement("div")
     container.style.display = "flex"
     container.style.width = "4000px"
@@ -624,15 +633,20 @@ export class ApollonEditor {
       // Wait for webfonts to load before we measure: canvas text measurement
       // (used by the wrap layout) otherwise falls back to the generic-family
       // metrics and the exported SVG's wrap decisions would drift from the
-      // on-screen render. Explicitly load Inter — `document.fonts.ready` alone
-      // would not wait for the injected `@font-face` until a glyph requests it —
-      // then await `ready` for any other pending faces. Best-effort throughout
-      // (older browsers / jsdom may lack `document.fonts`).
+      // on-screen render. Explicitly load each Inter face — `document.fonts.ready`
+      // alone would not wait for an injected `@font-face` until a glyph requests
+      // it — then await `ready` for any other pending faces. The italic faces
+      // back abstract classes/methods; omitting them would measure/render that
+      // text in a fallback family. Best-effort throughout (older browsers / jsdom
+      // may lack `document.fonts`).
       if (typeof document !== "undefined" && document.fonts) {
         if (document.fonts.load) {
+          const size = DEFAULT_FONT_SIZE
           await Promise.all([
-            document.fonts.load(`400 ${DEFAULT_FONT_SIZE}px ${FONT_FAMILY}`),
-            document.fonts.load(`700 ${DEFAULT_FONT_SIZE}px ${FONT_FAMILY}`),
+            document.fonts.load(`400 ${size}px ${FONT_FAMILY}`),
+            document.fonts.load(`700 ${size}px ${FONT_FAMILY}`),
+            document.fonts.load(`italic 400 ${size}px ${FONT_FAMILY}`),
+            document.fonts.load(`italic 700 ${size}px ${FONT_FAMILY}`),
           ]).catch(() => {})
         }
         if (document.fonts.ready) {
@@ -906,7 +920,7 @@ export class ApollonEditor {
     const interactive = this.getInteractiveForSerialization()
     return {
       id: diagramId,
-      version: "4.0.0",
+      version: "4.1.0",
       title: diagramTitle,
       type: diagramType,
       nodes: nodes.map((node) => mapFromReactFlowNodeToApollonNode(node)),
@@ -916,7 +930,8 @@ export class ApollonEditor {
     }
   }
 
-  set model(model: Apollon.UMLModel) {
+  set model(incoming: Apollon.UMLModel) {
+    const model = normalizeModel(incoming)
     const { nodes, edges, assessments, interactive } = model
     // Every store action below routes its Yjs writes through the
     // shared `transactStore` helper that no-ops in preview mode, so

library/lib/assets/fonts/Inter-BoldItalic.ttf

@@ -1,12 +1,38 @@
-import { StereotypeButtonGroup, NodeStyleEditor } from "@/components"
+import { NodeStyleEditor } from "@/components"
 import { useDiagramStore } from "@/store"
-import { ClassNodeProps } from "@/types"
+import { ClassNodeProps, ClassStereotype } from "@/types"
+import { LAYOUT } from "@/constants"
 import { useShallow } from "zustand/shallow"
 import { EditableAttributeList } from "./EditableAttributesList"
 import { EditableMethodsList } from "./EditableMethodsList"
+import { ClassTypeSelect, type ClassKind } from "./ClassTypeSelect"
 import { PopoverProps } from "../types"
 import { PopoverLayout, PopoverSection } from "../PopoverLayout"
 
+// A kind maps to both fields at once. Writing both on every change keeps them
+// consistent: a plain class can't keep a stale `isAbstract`, and a keyword can't
+// carry the (invalid) abstract modifier.
+const KIND_TO_DATA: Record<
+  ClassKind,
+  { stereotype?: ClassStereotype; isAbstract: boolean }
+> = {
+  class: { stereotype: undefined, isAbstract: false },
+  abstract: { stereotype: undefined, isAbstract: true },
+  interface: { stereotype: ClassStereotype.Interface, isAbstract: false },
+  enumeration: { stereotype: ClassStereotype.Enumeration, isAbstract: false },
+}
+
+const hasKeyword = (kind: ClassKind) =>
+  kind === "interface" || kind === "enumeration"
+
+const kindOf = (data: ClassNodeProps): ClassKind => {
+  // Stereotype wins, so a stray `isAbstract` beside a keyword never surfaces.
+  if (data.stereotype === ClassStereotype.Enumeration) return "enumeration"
+  if (data.stereotype === ClassStereotype.Interface) return "interface"
+  if (data.isAbstract) return "abstract"
+  return "class"
+}
+
 export const ClassEditPopover: React.FC<PopoverProps> = ({ elementId }) => {
   const { nodes, setNodes } = useDiagramStore(
     useShallow((state) => ({
@@ -21,6 +47,7 @@ export const ClassEditPopover: React.FC<PopoverProps> = ({ elementId }) => {
   }
 
   const nodeData = node.data as ClassNodeProps
+  const currentKind = kindOf(nodeData)
 
   const handleDataFieldUpdate = (key: string, value: string) => {
     setNodes((nodes) =>
@@ -39,18 +66,42 @@ export const ClassEditPopover: React.FC<PopoverProps> = ({ elementId }) => {
     )
   }
 
+  const setKind = (next: ClassKind) => {
+    const mapped = KIND_TO_DATA[next]
+    // A keyword adds a header line; the abstract modifier (italics) does not.
+    const keywordLinePx =
+      LAYOUT.DEFAULT_HEADER_HEIGHT_WITH_STEREOTYPE -
+      LAYOUT.DEFAULT_HEADER_HEIGHT
+    const delta =
+      ((hasKeyword(next) ? 1 : 0) - (hasKeyword(currentKind) ? 1 : 0)) *
+      keywordLinePx
+    setNodes((nodes) =>
+      nodes.map((node) => {
+        if (node.id !== elementId) return node
+        const height = (node.height ?? 0) + delta
+        return {
+          ...node,
+          data: {
+            ...node.data,
+            stereotype: mapped.stereotype,
+            isAbstract: mapped.isAbstract,
+          },
+          height,
+          measured: { ...node.measured, height },
+        }
+      })
+    )
+  }
+
   return (
     <PopoverLayout title="Class">
       <NodeStyleEditor
         nodeData={nodeData}
         colorEditorLabel="class"
         handleDataFieldUpdate={handleDataFieldUpdate}
       />
-      <PopoverSection title="Stereotype" divider>
-        <StereotypeButtonGroup
-          nodeId={elementId}
-          selectedStereotype={nodeData.stereotype}
-        />
+      <PopoverSection divider>
+        <ClassTypeSelect value={currentKind} onChange={setKind} />
       </PopoverSection>
       <PopoverSection divider>
         <EditableAttributeList nodeId={elementId} />

library/lib/assets/fonts/Inter-BoldItalic.woff2

@@ -0,0 +1,80 @@
+import { useMemo } from "react"
+import { Select, type SelectOption } from "@/components/ui"
+import { ClassStereotype } from "@/types"
+import { stereotypeLabel } from "@/utils"
+
+/**
+ * The four class classifier kinds. They map onto `{stereotype, isAbstract}`; the
+ * two invalid combinations (abstract enumeration, redundant abstract interface)
+ * are unrepresentable here by design.
+ */
+export type ClassKind = "class" | "abstract" | "interface" | "enumeration"
+
+type KindDescriptor = {
+  value: ClassKind
+  label: string
+  /** Metaclass keyword shown as a `«…»` line, mirroring the header. */
+  keyword?: ClassStereotype
+  /** Abstract classifiers render their name in italics (UML 2.5.1 §9.2.4). */
+  italic?: boolean
+}
+
+const KINDS: readonly KindDescriptor[] = [
+  { value: "class", label: "Class" },
+  { value: "abstract", label: "Abstract Class", italic: true },
+  {
+    value: "interface",
+    label: "Interface",
+    keyword: ClassStereotype.Interface,
+  },
+  {
+    value: "enumeration",
+    label: "Enumeration",
+    keyword: ClassStereotype.Enumeration,
+  },
+]
+
+// Each row previews the notation: a `«keyword»` chip and/or an italic name.
+const KindRow = ({ label, keyword, italic }: KindDescriptor) => (
+  <span style={{ alignItems: "baseline", display: "flex", gap: 8 }}>
+    {keyword && (
+      <span style={{ fontSize: "0.85em", opacity: 0.6 }}>
+        {stereotypeLabel(keyword)}
+      </span>
+    )}
+    <span style={{ fontStyle: italic ? "italic" : "normal" }}>{label}</span>
+  </span>
+)
+
+interface ClassTypeSelectProps {
+  value: ClassKind
+  onChange: (value: ClassKind) => void
+}
+
+/**
+ * Single "Class type" picker; its value maps to `{stereotype, isAbstract}` in
+ * `ClassEditPopover`. A class is always exactly one kind, so there is no empty
+ * state.
+ */
+export const ClassTypeSelect = ({ value, onChange }: ClassTypeSelectProps) => {
+  const options: SelectOption[] = useMemo(
+    () =>
+      KINDS.map((kind) => ({
+        value: kind.value,
+        label: kind.label,
+        renderOption: () => <KindRow {...kind} />,
+        renderValue: () => <KindRow {...kind} />,
+      })),
+    []
+  )
+
+  return (
+    <Select
+      label="Class type"
+      aria-label="Class type"
+      value={value}
+      options={options}
+      onChange={(next) => onChange(next as ClassKind)}
+    />
+  )
+}

library/lib/assets/fonts/Inter-Italic.ttf

@@ -1,11 +1,11 @@
 import React, { useState, KeyboardEvent, ChangeEvent } from "react"
-import { GripVertical, Plus, Trash2 } from "lucide-react"
+import { GripVertical, Italic, Plus, Trash2 } from "lucide-react"
 import { IconButton, TextField, Typography } from "@/components/ui"
 import { NodeStyleEditor } from "@/components/styleEditor"
 import { generateUUID } from "@/utils"
 import { useDiagramStore } from "@/store"
 import { useShallow } from "zustand/shallow"
-import { ClassNodeProps } from "@/types"
+import { ClassNodeElement, ClassNodeProps } from "@/types"
 import {
   DndContext,
   closestCenter,
@@ -30,15 +30,17 @@ interface Props {
 
 interface SortableMethodRowProps {
   id: string
-  item: { id: string; name: string }
+  item: ClassNodeElement
   onMethodChange: (id: string, key: string, value: string) => void
+  onToggleAbstract: (id: string) => void
   onDelete: (id: string) => void
 }
 
 const SortableMethodRow: React.FC<SortableMethodRowProps> = ({
   id,
   item,
   onMethodChange,
+  onToggleAbstract,
   onDelete,
 }) => {
   const {
@@ -93,6 +95,21 @@ const SortableMethodRow: React.FC<SortableMethodRowProps> = ({
           onMethodChange(item.id, key, value)
         }
         sideElements={[
+          <IconButton
+            key={`abstract_${item.id}`}
+            ariaLabel={
+              item.isAbstract
+                ? "Unmark method as abstract"
+                : "Mark method as abstract"
+            }
+            tooltip="Abstract method (italic)"
+            aria-pressed={!!item.isAbstract}
+            data-state={item.isAbstract ? "on" : "off"}
+            className="apollon-abstract-toggle"
+            onClick={() => onToggleAbstract(item.id)}
+          >
+            <Italic width={16} height={16} aria-hidden="true" />
+          </IconButton>,
           <IconButton
             key={`delete_${item.id}`}
             ariaLabel="Delete method"
@@ -136,6 +153,14 @@ export const EditableMethodsList: React.FC<Props> = ({ nodeId }) => {
     )
   }
 
+  const handleToggleAbstract = (id: string) => {
+    patchMethods(
+      methods.map((item) =>
+        item.id === id ? { ...item, isAbstract: !item.isAbstract } : item
+      )
+    )
+  }
+
   const handleItemDelete = (id: string) => {
     setNodes((nodes) =>
       nodes.map((node) => {
@@ -211,6 +236,7 @@ export const EditableMethodsList: React.FC<Props> = ({ nodeId }) => {
               id={item.id}
               item={item}
               onMethodChange={handleMethodChange}
+              onToggleAbstract={handleToggleAbstract}
               onDelete={handleItemDelete}
             />
           ))}