@dxos/diagram 0.11.1

package/src/uml.test.ts

@@ -0,0 +1,172 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import type * as Scene from './scene.ts';
+import { CLASS_DIAGRAM } from './testing.ts';
+import { compile, isClassDiagram, parse } from './uml.ts';
+
+const objectsOf = (commands: Scene.Command[]) =>
+  commands.flatMap((command) => (command.op === 'upsert-object' ? [command.object] : []));
+
+describe('uml', () => {
+  test('detects class diagrams', ({ expect }) => {
+    expect(isClassDiagram(CLASS_DIAGRAM)).toBe(true);
+    expect(isClassDiagram('flowchart TB\nA --> B')).toBe(false);
+  });
+
+  test('parses classes, members and stereotypes', ({ expect }) => {
+    const model = parse(CLASS_DIAGRAM);
+
+    expect(model.direction).toBe('TB');
+    expect(model.classes.map((entry) => entry.id).sort()).toEqual([
+      'Animal',
+      'Bone',
+      'Dog',
+      'Leg',
+      'Owner',
+      'Serializable',
+    ]);
+
+    const animal = model.classes.find((entry) => entry.id === 'Animal')!;
+    expect(animal.stereotype).toBe('abstract');
+    expect(animal.attributes).toEqual(['+name: string']);
+    expect(animal.methods).toEqual(['+move() void']);
+
+    // Classes first mentioned in a relation are auto-declared, empty.
+    const bone = model.classes.find((entry) => entry.id === 'Bone')!;
+    expect(bone.attributes).toEqual([]);
+    expect(bone.methods).toEqual([]);
+  });
+
+  test('normalizes relations to subtype → supertype and whole → part', ({ expect }) => {
+    const { relations } = parse(CLASS_DIAGRAM);
+    const byKind = (kind: string) => relations.filter((relation) => relation.kind === kind);
+
+    // `Animal <|-- Dog`: the arrow renders from the subtype to its parent.
+    expect(byKind('inheritance')).toEqual([{ from: 'Dog', to: 'Animal', kind: 'inheritance' }]);
+    expect(byKind('realization')).toEqual([{ from: 'Dog', to: 'Serializable', kind: 'realization' }]);
+    expect(byKind('composition')).toEqual([{ from: 'Dog', to: 'Leg', kind: 'composition' }]);
+    expect(byKind('aggregation')).toEqual([
+      { from: 'Owner', to: 'Dog', kind: 'aggregation', label: 'owns', fromCardinality: '1', toCardinality: '*' },
+    ]);
+    expect(byKind('dependency')).toEqual([{ from: 'Dog', to: 'Bone', kind: 'dependency', label: 'chews' }]);
+  });
+
+  test('renders generics from tilde syntax', ({ expect }) => {
+    const model = parse(['classDiagram', 'class List~T~', 'List~T~ o-- Item'].join('\n'));
+    expect(model.classes.find((entry) => entry.id === 'List~T~')?.label).toBe('List<T>');
+  });
+
+  test('compiles one object per class with compartments, plus an edges object', ({ expect }) => {
+    const objects = objectsOf(compile(CLASS_DIAGRAM));
+
+    expect(objects.map((object) => object.id).sort()).toEqual([
+      'Animal',
+      'Bone',
+      'Dog',
+      'Leg',
+      'Owner',
+      'Serializable',
+      'edges',
+    ]);
+
+    const dog = objects.find((object) => object.id === 'Dog')!;
+    expect(dog.elements.map((element) => element.id)).toEqual(['title', 'attributes', 'methods']);
+    const [title, attributes, methods] = dog.elements as Scene.Box[];
+    expect(title.text).toBe('Dog');
+    expect(attributes.text).toBe('+breed: string');
+    expect(methods.text).toBe('+bark() void');
+    // Compartments stack flush: each starts where the previous one ends.
+    expect(attributes.y).toBe(title.h);
+    expect(methods.y).toBe(title.h + attributes.h);
+    expect(new Set([title.w, attributes.w, methods.w]).size).toBe(1);
+
+    // A memberless class is just its title compartment.
+    const leg = objects.find((object) => object.id === 'Leg')!;
+    expect(leg.elements.map((element) => element.id)).toEqual(['title']);
+
+    // Stereotypes render as a guillemet line above the name.
+    const serializable = objects.find((object) => object.id === 'Serializable')!;
+    expect((serializable.elements[0] as Scene.Box).text).toBe('«interface»\nSerializable');
+  });
+
+  test('layers supertypes and dependency targets above, parts below', ({ expect }) => {
+    const objects = objectsOf(compile(CLASS_DIAGRAM));
+    const y = (id: string) => objects.find((object) => object.id === id)!.origin!.y;
+
+    expect(y('Animal')).toBeLessThan(y('Dog'));
+    expect(y('Serializable')).toBeLessThan(y('Dog'));
+    // Dog's parts sit below it; what it depends on sits above, so the arrow reads upward.
+    expect(y('Dog')).toBeLessThan(y('Leg'));
+    expect(y('Bone')).toBeLessThan(y('Dog'));
+  });
+
+  test('binds arrows to the compartments facing the peer, with UML styling', ({ expect }) => {
+    const edges = objectsOf(compile(CLASS_DIAGRAM)).find((object) => object.id === 'edges')!;
+    const arrows = edges.elements as Scene.Arrow[];
+
+    expect(arrows.every((arrow) => arrow.kind === 'arrow')).toBe(true);
+    // Dog sits below Animal: the arrow leaves Dog's top compartment and meets Animal's bottom
+    // one, so the visible segment stays in the rank gap instead of crossing Animal's members.
+    const inheritance = arrows.find((arrow) => arrow.from === 'Dog/title' && arrow.to === 'Animal/methods')!;
+    expect(inheritance.stroke).toBeUndefined();
+    const realization = arrows.find((arrow) => arrow.to === 'Serializable/methods')!;
+    expect(realization.stroke).toBe('dashed');
+    const aggregation = arrows.find((arrow) => arrow.from === 'Owner/title')!;
+    expect(aggregation.to).toBe('Dog/title');
+    expect(aggregation.text).toBe('1 owns *');
+    // Memberless classes below Dog bind to their only compartment; Dog faces them with its last.
+    const composition = arrows.find((arrow) => arrow.to === 'Leg/title')!;
+    expect(composition.from).toBe('Dog/methods');
+    expect(composition.text).toBe('◆');
+  });
+
+  test('wraps long member lines into taller compartments, capped at maxWidth', ({ expect }) => {
+    const diagram = (member: string) => ['classDiagram', 'class A {', `  +${member}`, '}'].join('\n');
+    const short = objectsOf(compile(diagram('id() string')))[0];
+    const long = objectsOf(
+      compile(diagram('reallyQuiteLongMethodName(withSomeArguments, andMoreArguments, andEvenMore) ReturnType')),
+    )[0];
+
+    const shortMethods = short.elements.find((element) => element.id === 'methods') as Scene.Box;
+    const longMethods = long.elements.find((element) => element.id === 'methods') as Scene.Box;
+    expect(longMethods.w).toBeLessThanOrEqual(400);
+    expect(longMethods.h).toBeGreaterThan(shortMethods.h);
+
+    // A tighter maxWidth narrows the box and wraps into even more lines.
+    const narrow = objectsOf(
+      compile(diagram('reallyQuiteLongMethodName(withSomeArguments, andMoreArguments, andEvenMore) ReturnType'), {
+        maxWidth: 240,
+      }),
+    )[0];
+    const narrowMethods = narrow.elements.find((element) => element.id === 'methods') as Scene.Box;
+    expect(narrowMethods.w).toBeLessThanOrEqual(240);
+    expect(narrowMethods.h).toBeGreaterThan(longMethods.h);
+  });
+
+  test('gap options spread the layout', ({ expect }) => {
+    const compact = objectsOf(compile(CLASS_DIAGRAM));
+    const spread = objectsOf(compile(CLASS_DIAGRAM, { gapMain: 200, gapCross: 150 }));
+    const origin = (objects: Scene.WorldObject[], id: string) => objects.find((object) => object.id === id)!.origin!;
+
+    expect(origin(spread, 'Dog').y - origin(spread, 'Animal').y).toBeGreaterThan(
+      origin(compact, 'Dog').y - origin(compact, 'Animal').y,
+    );
+    expect(Math.abs(origin(spread, 'Serializable').x - origin(spread, 'Animal').x)).toBeGreaterThan(
+      Math.abs(origin(compact, 'Serializable').x - origin(compact, 'Animal').x),
+    );
+  });
+
+  test('ignores comments and tolerates unknown syntax', ({ expect }) => {
+    const model = parse(
+      ['classDiagram', '%% a comment', 'class A', 'A <|-- B', 'note for A "irrelevant"', 'style A fill:#f9f'].join(
+        '\n',
+      ),
+    );
+    expect(model.classes.map((entry) => entry.id)).toEqual(['A', 'B']);
+    expect(model.relations).toEqual([{ from: 'B', to: 'A', kind: 'inheritance' }]);
+  });
+});

package/src/uml.ts

@@ -0,0 +1,390 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Mermaid class-diagram dialect: parses the subset needed for UML class diagrams (class blocks
+// with members, stereotypes, and the standard relation arrows) and compiles it to scene commands
+// with a layered layout — supertypes above subtypes. Mermaid carries no coordinates, so the
+// dialect owns placement; see `dialect.ts` for the contract.
+//
+
+import * as Layout from './layout.ts';
+import type * as Scene from './scene.ts';
+
+export type Direction = 'TB' | 'BT' | 'LR' | 'RL';
+
+export type UmlClass = {
+  id: string;
+  label: string;
+  /** e.g. "interface", "abstract", "enumeration". */
+  stereotype?: string;
+  attributes: string[];
+  methods: string[];
+};
+
+export type RelationKind = 'inheritance' | 'realization' | 'composition' | 'aggregation' | 'association' | 'dependency';
+
+/** Rendered arrow direction: subtype → supertype, whole → part, source → target. */
+export type UmlRelation = {
+  from: string;
+  to: string;
+  kind: RelationKind;
+  label?: string;
+  fromCardinality?: string;
+  toCardinality?: string;
+};
+
+export type UmlModel = {
+  direction: Direction;
+  classes: UmlClass[];
+  relations: UmlRelation[];
+};
+
+const DIRECTIONS: Direction[] = ['TB', 'BT', 'LR', 'RL'];
+
+// `class Name`, `class Name["Label"]`, `class Name {`.
+const CLASS = /^class\s+([A-Za-z0-9_~<>-]+)(?:\s*\[\s*"(.*?)"\s*\])?\s*(\{)?\s*$/;
+// `Name : +member` inline member declaration.
+const INLINE_MEMBER = /^([A-Za-z0-9_~<>-]+)\s*:\s*(.+)$/;
+const STEREOTYPE = /^<<\s*(.*?)\s*>>$/;
+
+/**
+ * Relation arrows, normalized to (kind, whether the LEFT side is the arrow target).
+ * `A <|-- B` reads "B inherits A": the parent is on the flat side of the triangle.
+ */
+const RELATIONS: [token: string, kind: RelationKind, leftIsTarget: boolean][] = [
+  ['<|--', 'inheritance', true],
+  ['--|>', 'inheritance', false],
+  ['<|..', 'realization', true],
+  ['..|>', 'realization', false],
+  ['*--', 'composition', false],
+  ['--*', 'composition', true],
+  ['o--', 'aggregation', false],
+  ['--o', 'aggregation', true],
+  ['-->', 'association', false],
+  ['<--', 'association', true],
+  ['..>', 'dependency', false],
+  ['<..', 'dependency', true],
+  ['..', 'dependency', false],
+  ['--', 'association', false],
+];
+
+// `A "1" <|-- "many" B : label` — cardinalities and the trailing label are optional.
+const RELATION = new RegExp(
+  '^([A-Za-z0-9_~<>-]+)\\s*(?:"([^"]*)"\\s*)?' +
+    `(${RELATIONS.map(([token]) => token.replace(/[|*.>-]/g, '\\$&')).join('|')})` +
+    '\\s*(?:"([^"]*)"\\s*)?([A-Za-z0-9_~<>-]+)\\s*(?::\\s*(.+))?$',
+);
+
+/** Mermaid generics use `~T~`; render them as `<T>`. */
+const genericLabel = (id: string) => id.replace(/~([^~]*)~/g, '<$1>');
+
+/** Parse a mermaid class diagram into a neutral model. Unrecognised lines are ignored. */
+export const parse = (source: string): UmlModel => {
+  const classes = new Map<string, UmlClass>();
+  const relations: UmlRelation[] = [];
+  let direction: Direction = 'TB';
+  let open: UmlClass | undefined;
+
+  const declare = (id: string): UmlClass => {
+    let entry = classes.get(id);
+    if (!entry) {
+      entry = { id, label: genericLabel(id), attributes: [], methods: [] };
+      classes.set(id, entry);
+    }
+    return entry;
+  };
+
+  const addMember = (entry: UmlClass, raw: string) => {
+    const member = raw.trim();
+    const stereotype = STEREOTYPE.exec(member);
+    if (stereotype) {
+      entry.stereotype = stereotype[1];
+      return;
+    }
+    if (member) {
+      // A parameter list marks a method; everything else is an attribute.
+      (member.includes('(') ? entry.methods : entry.attributes).push(member);
+    }
+  };
+
+  for (const raw of source.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('%%') || /^classDiagram(-v2)?$/.test(line)) {
+      continue;
+    }
+
+    if (open) {
+      if (line === '}') {
+        open = undefined;
+      } else {
+        addMember(open, line);
+      }
+      continue;
+    }
+
+    const header = /^direction\s+([A-Za-z]{2})$/.exec(line);
+    if (header) {
+      const value = header[1].toUpperCase() as Direction;
+      direction = DIRECTIONS.includes(value) ? value : 'TB';
+      continue;
+    }
+
+    const cls = CLASS.exec(line);
+    if (cls) {
+      const [, id, label, brace] = cls;
+      const entry = declare(id);
+      if (label) {
+        entry.label = label;
+      }
+      if (brace) {
+        open = entry;
+      }
+      continue;
+    }
+
+    const relation = RELATION.exec(line);
+    if (relation) {
+      const [, left, leftCardinality, token, rightCardinality, right, label] = relation;
+      declare(left);
+      declare(right);
+      const [, kind, leftIsTarget] = RELATIONS.find(([candidate]) => candidate === token)!;
+      const [from, to] = leftIsTarget ? [right, left] : [left, right];
+      const [fromCardinality, toCardinality] = leftIsTarget
+        ? [rightCardinality, leftCardinality]
+        : [leftCardinality, rightCardinality];
+      relations.push({
+        from,
+        to,
+        kind,
+        ...(label ? { label: label.trim() } : {}),
+        ...(fromCardinality ? { fromCardinality } : {}),
+        ...(toCardinality ? { toCardinality } : {}),
+      });
+      continue;
+    }
+
+    const inline = INLINE_MEMBER.exec(line);
+    if (inline) {
+      const [, id, member] = inline;
+      addMember(declare(id), member);
+    }
+  }
+
+  return { direction, classes: [...classes.values()], relations };
+};
+
+/**
+ * Box geometry in scene units; text sizes come from the shared per-weight metrics table
+ * (`Layout.FONT_METRICS`): the title renders at the default weight (m), members at s.
+ */
+const TITLE_FONT = Layout.FONT_METRICS.m;
+const MEMBER_FONT = Layout.FONT_METRICS.s;
+const MIN_W = 160;
+const MAX_W = 400;
+const PAD_X = 24;
+const TITLE_PAD = 10;
+const SECTION_PAD = 14;
+const GAP_MAIN = 90;
+const GAP_CROSS = 60;
+
+type ClassBox = {
+  entry: UmlClass;
+  w: number;
+  h: number;
+  titleH: number;
+  attributesH: number;
+  methodsH: number;
+};
+
+/** Compartment sizes derived from member counts and line lengths, per compartment font. */
+const measure = (entry: UmlClass, maxWidth: number): ClassBox => {
+  const titleW = Math.max(entry.label.length, (entry.stereotype?.length ?? 0) + 2) * TITLE_FONT.charW;
+  const memberW =
+    Math.max(0, ...[...entry.attributes, ...entry.methods].map((line) => line.length)) * MEMBER_FONT.charW;
+  const w = Math.min(maxWidth, Math.max(MIN_W, Math.ceil(Math.max(titleW, memberW)) + PAD_X));
+  // Lines wider than the clamped box wrap in the renderer; count the extra lines so the
+  // compartment is tall enough and tldraw does not grow it over the one below.
+  const lines = (text: string, font: Layout.FontMetrics) =>
+    Math.max(1, Math.ceil((text.length * font.charW) / (w - PAD_X)));
+  const memberH = (members: string[]) =>
+    members.length
+      ? members.reduce((sum, line) => sum + lines(line, MEMBER_FONT), 0) * MEMBER_FONT.lineH + SECTION_PAD
+      : 0;
+  const titleH = (lines(entry.label, TITLE_FONT) + (entry.stereotype ? 1 : 0)) * TITLE_FONT.lineH + TITLE_PAD;
+  const attributesH = memberH(entry.attributes);
+  const methodsH = memberH(entry.methods);
+  return { entry, w, h: titleH + attributesH + methodsH, titleH, attributesH, methodsH };
+};
+
+/** Arrow styling per relation kind; dependency and realization render dashed, as in UML. */
+export const relationStyle = (kind: RelationKind): { stroke?: Scene.Stroke } =>
+  kind === 'dependency' || kind === 'realization' ? { stroke: 'dashed' } : {};
+
+/** Mid-arrow label: cardinalities and the diamond glyph UML puts at the whole end. */
+export const relationText = (relation: UmlRelation): string | undefined => {
+  const glyph = relation.kind === 'composition' ? '◆' : relation.kind === 'aggregation' ? '◇' : undefined;
+  const text = [relation.fromCardinality, relation.label ?? glyph, relation.toCardinality].filter(Boolean).join(' ');
+  return text || undefined;
+};
+
+/**
+ * Rank so arrows read upward where UML convention points at abstractions — inheritance,
+ * realization, and dependency targets sit above their sources; containment and association
+ * flow downward (whole/source above part/target).
+ */
+export const relationRanks = (model: UmlModel): Map<string, number> =>
+  Layout.rank(
+    model.classes.map((entry) => entry.id),
+    model.relations.map((relation) =>
+      relation.kind === 'inheritance' || relation.kind === 'realization' || relation.kind === 'dependency'
+        ? { from: relation.to, to: relation.from }
+        : { from: relation.from, to: relation.to },
+    ),
+  );
+
+export type CompileOptions = {
+  /** Canvas position of the diagram's top-left, in canvas px. */
+  origin?: Scene.Point;
+  /** Canvas px per scene unit. */
+  scale?: number;
+  /** Gap between ranks along the flow direction, in scene units (default 90). */
+  gapMain?: number;
+  /** Gap between classes within a rank, in scene units (default 60). */
+  gapCross?: number;
+  /** Maximum class-box width, in scene units (default 400); longer lines wrap. */
+  maxWidth?: number;
+};
+
+/**
+ * Compile a mermaid class diagram into scene commands: one world object per class (compartment
+ * rects `title`/`attributes`/`methods`) and an `edges` object holding the relations as bound
+ * arrows. Supertypes rank above subtypes, so inheritance reads downward.
+ */
+export const compile = (source: string, options: CompileOptions = {}): Scene.Command[] => {
+  const model = parse(source);
+  const { origin = { x: 0, y: 0 }, scale = 1, gapMain = GAP_MAIN, gapCross = GAP_CROSS, maxWidth = MAX_W } = options;
+  const horizontal = model.direction === 'LR' || model.direction === 'RL';
+
+  const ranks = relationRanks(model);
+
+  const boxes = new Map(model.classes.map((entry) => [entry.id, measure(entry, maxWidth)]));
+
+  // Group classes by rank, preserving declaration order within each lane.
+  const lanes = new Map<number, ClassBox[]>();
+  for (const entry of model.classes) {
+    const value = ranks.get(entry.id) ?? 0;
+    lanes.set(value, [...(lanes.get(value) ?? []), boxes.get(entry.id)!]);
+  }
+
+  const cross = (box: ClassBox) => (horizontal ? box.h : box.w);
+  const main = (box: ClassBox) => (horizontal ? box.w : box.h);
+  const laneSpan = (members: ClassBox[]) =>
+    members.reduce((sum, box) => sum + cross(box), 0) + (members.length - 1) * gapCross;
+  const widest = Math.max(...[...lanes.values()].map(laneSpan), 0);
+
+  // Lanes advance along the main axis by their tallest member; members center on the widest lane.
+  const positions = new Map<string, Scene.Point>();
+  let mainOffset = 0;
+  for (const lane of [...lanes.keys()].sort((left, right) => left - right)) {
+    const members = lanes.get(lane)!;
+    let crossOffset = (widest - laneSpan(members)) / 2;
+    for (const box of members) {
+      positions.set(box.entry.id, horizontal ? { x: mainOffset, y: crossOffset } : { x: crossOffset, y: mainOffset });
+      crossOffset += cross(box) + gapCross;
+    }
+    mainOffset += Math.max(...members.map(main)) + gapMain;
+  }
+
+  // Arrow terminals clip at the bound compartment, so each endpoint binds to the compartment
+  // nearest the peer's center — the arrow meets the box's outer edge instead of crossing the
+  // compartments between that edge and the title, and mid-arrow labels land in the rank gap.
+  const facing = (id: string, peerId: string): string => {
+    const box = boxes.get(id)!;
+    const peer = boxes.get(peerId)!;
+    const targetY = positions.get(peerId)!.y + peer.h / 2;
+    const baseY = positions.get(id)!.y;
+    const compartments: [elementId: string, centerY: number][] = [['title', box.titleH / 2]];
+    if (box.attributesH) {
+      compartments.push(['attributes', box.titleH + box.attributesH / 2]);
+    }
+    if (box.methodsH) {
+      compartments.push(['methods', box.titleH + box.attributesH + box.methodsH / 2]);
+    }
+    return compartments.reduce((best, candidate) =>
+      Math.abs(baseY + candidate[1] - targetY) < Math.abs(baseY + best[1] - targetY) ? candidate : best,
+    )[0];
+  };
+
+  const commands: Scene.Command[] = [];
+
+  for (const entry of model.classes) {
+    const box = boxes.get(entry.id)!;
+    const point = positions.get(entry.id)!;
+    const title = entry.stereotype ? `«${entry.stereotype}»\n${entry.label}` : entry.label;
+    const elements: Scene.Element[] = [
+      { kind: 'rect', id: 'title', x: 0, y: 0, w: box.w, h: box.titleH, text: title, fill: 'solid' },
+    ];
+    if (box.attributesH) {
+      elements.push({
+        kind: 'rect',
+        id: 'attributes',
+        x: 0,
+        y: box.titleH,
+        w: box.w,
+        h: box.attributesH,
+        text: entry.attributes.join('\n'),
+        weight: 's',
+      });
+    }
+    if (box.methodsH) {
+      elements.push({
+        kind: 'rect',
+        id: 'methods',
+        x: 0,
+        y: box.titleH + box.attributesH,
+        w: box.w,
+        h: box.methodsH,
+        text: entry.methods.join('\n'),
+        weight: 's',
+      });
+    }
+    commands.push({
+      op: 'upsert-object',
+      object: {
+        id: entry.id,
+        origin: { x: origin.x + point.x * scale, y: origin.y + point.y * scale },
+        scale,
+        elements,
+      },
+    });
+  }
+
+  if (model.relations.length > 0) {
+    commands.push({
+      op: 'upsert-object',
+      object: {
+        id: 'edges',
+        origin,
+        scale,
+        elements: model.relations.map((relation, index) => {
+          const text = relationText(relation);
+          return {
+            kind: 'arrow' as const,
+            id: `${relation.from}-${relation.to}-${index}`,
+            from: `${relation.from}/${facing(relation.from, relation.to)}`,
+            to: `${relation.to}/${facing(relation.to, relation.from)}`,
+            ...relationStyle(relation.kind),
+            ...(text ? { text } : {}),
+          };
+        }),
+      },
+    });
+  }
+
+  return commands;
+};
+
+/** True when the mermaid source declares a class diagram rather than a flowchart. */
+export const isClassDiagram = (source: string): boolean => /^\s*classDiagram(-v2)?\b/m.test(source);