@dxos/diagram 0.11.1

package/src/uml-engine.ts

@@ -0,0 +1,146 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Engine-backed placement for the grid UML dialect: dagre or ELK replace the hand-rolled
+// lane/column pass (proper crossing minimization and straightness-seeking coordinate
+// assignment), while parsing, cell measurement, grid snapping, routing, and emission stay
+// shared with `uml-grid.ts`. See `docs/DESIGN.md`.
+//
+
+import { layout as dagreLayout, graphlib } from '@dagrejs/dagre';
+import ELK from 'elkjs/lib/elk.bundled.js';
+
+import type * as Scene from './scene.ts';
+import {
+  type Cell,
+  GRID,
+  type CompileOptions as GridCompileOptions,
+  type Rect,
+  emit,
+  measureCell,
+} from './uml-grid.ts';
+import { type Direction, type UmlModel, parse, relationRanks } from './uml.ts';
+
+export type Engine = 'dagre' | 'elk';
+
+export type CompileOptions = Omit<GridCompileOptions, 'route'> & {
+  /** Placement engine (default 'elk'). */
+  engine?: Engine;
+};
+
+const GAP_MAIN = GRID * 4;
+const GAP_CROSS = GRID * 4;
+
+const snap = (value: number) => Math.round(value / GRID) * GRID;
+
+type PlaceOptions = {
+  cell: Cell;
+  gapMain: number;
+  gapCross: number;
+  direction: Direction;
+};
+
+const DAGRE_DIRECTION: Record<Direction, string> = { TB: 'TB', BT: 'BT', LR: 'LR', RL: 'RL' };
+const ELK_DIRECTION: Record<Direction, string> = { TB: 'DOWN', BT: 'UP', LR: 'RIGHT', RL: 'LEFT' };
+
+/**
+ * Edges oriented for layering: inheritance, realization, and dependency point at abstractions,
+ * which rank ABOVE their sources — so those edges are reversed for the engine (which lays out
+ * source-above-target), matching `relationRanks`.
+ */
+const orientedEdges = (model: UmlModel): { from: string; to: string }[] =>
+  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 },
+  );
+
+/** Snap engine output to the document grid and normalize the top-left to (0, 0). */
+const snapRects = (rects: Map<string, Rect>): Map<string, Rect> => {
+  const snapped = new Map([...rects].map(([id, rect]) => [id, { ...rect, x: snap(rect.x), y: snap(rect.y) }]));
+  const minX = Math.min(...[...snapped.values()].map((rect) => rect.x), 0);
+  const minY = Math.min(...[...snapped.values()].map((rect) => rect.y), 0);
+  return new Map([...snapped].map(([id, rect]) => [id, { ...rect, x: rect.x - minX, y: rect.y - minY }]));
+};
+
+/** dagre: network-simplex layering + median-sweep crossing minimization. Sync. */
+const dagrePlace = (model: UmlModel, { cell, gapMain, gapCross, direction }: PlaceOptions): Map<string, Rect> => {
+  const graph = new graphlib.Graph();
+  graph.setGraph({
+    rankdir: DAGRE_DIRECTION[direction],
+    ranker: 'network-simplex',
+    ranksep: gapMain,
+    nodesep: gapCross,
+    edgesep: gapCross / 2,
+  });
+  graph.setDefaultEdgeLabel(() => ({}));
+  for (const entry of model.classes) {
+    graph.setNode(entry.id, { width: cell.w, height: cell.h });
+  }
+  for (const edge of orientedEdges(model)) {
+    graph.setEdge(edge.from, edge.to);
+  }
+  dagreLayout(graph);
+
+  // dagre reports node centers.
+  const rects = new Map<string, Rect>(
+    model.classes.map((entry) => {
+      const node = graph.node(entry.id);
+      return [entry.id, { x: node.x - cell.w / 2, y: node.y - cell.h / 2, w: cell.w, h: cell.h }];
+    }),
+  );
+  return snapRects(rects);
+};
+
+/** ELK layered: layer-sweep crossing minimization + Brandes-Köpf placement. Async. */
+const elkPlace = async (
+  model: UmlModel,
+  { cell, gapMain, gapCross, direction }: PlaceOptions,
+): Promise<Map<string, Rect>> => {
+  const elk = new ELK();
+  const result = await elk.layout({
+    id: 'root',
+    layoutOptions: {
+      'elk.algorithm': 'layered',
+      'elk.direction': ELK_DIRECTION[direction],
+      'elk.layered.spacing.nodeNodeBetweenLayers': String(gapMain),
+      'elk.spacing.nodeNode': String(gapCross),
+      // Favors long straight chains over balanced centering — fewer jagged connectors.
+      'elk.layered.nodePlacement.strategy': 'BRANDES_KOEPF',
+      // Keeps declaration order among otherwise-unconstrained siblings, so peers stay gathered.
+      'elk.layered.considerModelOrder.strategy': 'PREFER_NODES',
+    },
+    children: model.classes.map((entry) => ({ id: entry.id, width: cell.w, height: cell.h })),
+    edges: orientedEdges(model).map((edge, index) => ({
+      id: `edge-${index}`,
+      sources: [edge.from],
+      targets: [edge.to],
+    })),
+  });
+
+  const rects = new Map<string, Rect>(
+    (result.children ?? []).map((child) => [child.id, { x: child.x ?? 0, y: child.y ?? 0, w: cell.w, h: cell.h }]),
+  );
+  return snapRects(rects);
+};
+
+/**
+ * Compile a mermaid class diagram with engine-backed placement; identical output structure to
+ * `UmlGrid.compile` (equal-size grid cells, orthogonal Z-routed connectors), but node positions
+ * come from dagre/ELK. Async because ELK is.
+ */
+export const compile = async (source: string, options: CompileOptions = {}): Promise<Scene.Command[]> => {
+  const { origin, scale, maxWidth = GRID * 6, engine = 'elk' } = options;
+  const model = parse(source);
+  const cell = measureCell(model, { maxWidth, cell: options.cell, titleHeight: options.titleHeight });
+  const place: PlaceOptions = {
+    cell,
+    gapMain: snap(options.gapMain ?? GAP_MAIN),
+    gapCross: snap(options.gapCross ?? GAP_CROSS),
+    direction: model.direction,
+  };
+  const rects = engine === 'dagre' ? dagrePlace(model, place) : await elkPlace(model, place);
+  return emit({ model, cell, rects, ranks: relationRanks(model) }, { origin, scale });
+};

package/src/uml-grid.test.ts

@@ -0,0 +1,175 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import type * as Scene from './scene.ts';
+import { CLASS_DIAGRAM } from './testing.ts';
+import { GRID, type Router, compile } from './uml-grid.ts';
+
+const objectsOf = (commands: Scene.Command[]) =>
+  commands.flatMap((command) => (command.op === 'upsert-object' ? [command.object] : []));
+
+const nodesOf = (objects: Scene.WorldObject[]) => objects.filter((object) => object.id !== 'edges');
+
+const frameOf = (node: Scene.WorldObject) => node.elements.find((element) => element.id === 'frame') as Scene.Box;
+
+describe('uml-grid', () => {
+  test('every class renders as an equal-size frame with a top-rounded header', ({ expect }) => {
+    const nodes = nodesOf(objectsOf(compile(CLASS_DIAGRAM)));
+
+    expect(nodes).toHaveLength(6);
+    const sizes = new Set(
+      nodes.map((node) => {
+        const [frame, title] = node.elements as Scene.Box[];
+        expect(frame.id).toBe('frame');
+        expect(title.id).toBe('title');
+        expect(title.corners).toBe('top');
+        expect(title.w).toBe(frame.w);
+        // Members render as free text inside the frame, not a third bordered rect.
+        const body = node.elements.find((element) => element.id === 'body');
+        if (body) {
+          expect(body.kind).toBe('text');
+        }
+        return `${frame.w}x${frame.h}`;
+      }),
+    );
+    expect(sizes.size).toBe(1);
+  });
+
+  test('cells and positions align to the grid', ({ expect }) => {
+    const nodes = nodesOf(objectsOf(compile(CLASS_DIAGRAM)));
+
+    for (const node of nodes) {
+      expect(node.origin!.x % GRID).toBe(0);
+      expect(node.origin!.y % GRID).toBe(0);
+      const frame = frameOf(node);
+      expect(frame.w % GRID).toBe(0);
+      expect(frame.h % GRID).toBe(0);
+    }
+  });
+
+  test('connectors are orthogonal: every segment is axis-aligned', ({ expect }) => {
+    const edges = objectsOf(compile(CLASS_DIAGRAM)).find((object) => object.id === 'edges')!;
+
+    const segments: [Scene.Point, Scene.Point][] = [];
+    for (const element of edges.elements) {
+      if (element.kind === 'line') {
+        element.points.forEach((point, index) => {
+          if (index > 0) {
+            segments.push([element.points[index - 1], point]);
+          }
+        });
+      } else if (element.kind === 'arrow') {
+        segments.push([element.start!, element.end!]);
+      }
+    }
+
+    expect(segments.length).toBeGreaterThan(0);
+    for (const [head, tail] of segments) {
+      expect(head.x === tail.x || head.y === tail.y).toBe(true);
+    }
+  });
+
+  test('arrowheads terminate on the target cell edge and labels float alongside', ({ expect }) => {
+    const objects = objectsOf(compile(CLASS_DIAGRAM));
+    const edges = objects.find((object) => object.id === 'edges')!;
+    const animal = objects.find((object) => object.id === 'Animal')!;
+    const frame = frameOf(animal);
+
+    // `Animal <|-- Dog` renders upward: the head lands on Animal's bottom edge.
+    const inheritance = edges.elements.find(
+      (element): element is Scene.Arrow => element.kind === 'arrow' && element.id.startsWith('Dog-Animal'),
+    )!;
+    expect(inheritance.end!.y).toBe(animal.origin!.y + frame.h);
+
+    const labels = edges.elements.filter((element) => element.kind === 'text');
+    expect(labels.map((element) => (element as Scene.Text).text)).toEqual(
+      expect.arrayContaining(['1 owns *', 'chews']),
+    );
+  });
+
+  test('dashed styling carries onto routed paths', ({ expect }) => {
+    const edges = objectsOf(compile(CLASS_DIAGRAM)).find((object) => object.id === 'edges')!;
+    const realization = edges.elements.find(
+      (element): element is Scene.Arrow => element.kind === 'arrow' && element.id.startsWith('Dog-Serializable'),
+    )!;
+    expect(realization.stroke).toBe('dashed');
+  });
+
+  test('a custom router controls the path', ({ expect }) => {
+    const route: Router = ({ from, to }) => [
+      { x: from.x, y: from.y },
+      { x: from.x, y: -100 },
+      { x: to.x, y: -100 },
+      { x: to.x, y: to.y },
+    ];
+    const edges = objectsOf(compile(CLASS_DIAGRAM, { route })).find((object) => object.id === 'edges')!;
+    const paths = edges.elements.filter((element): element is Scene.Polyline => element.kind === 'line');
+
+    expect(paths.length).toBeGreaterThan(0);
+    for (const path of paths) {
+      expect(path.points.some((point) => point.y === -100)).toBe(true);
+    }
+  });
+
+  test('default height clamps to the GRID-derived bounds', ({ expect }) => {
+    const members = Array.from({ length: 30 }, (_, index) => `  +field${index}: string`);
+    const source = ['classDiagram', 'class Big {', ...members, '}'].join('\n');
+    const [big] = nodesOf(objectsOf(compile(source)));
+
+    const frame = frameOf(big);
+    // Far shorter than the unclamped member stack, whatever the tuned MAX_H is.
+    expect(frame.h).toBeLessThan(30 * 26);
+    expect(frame.h % GRID).toBe(0);
+  });
+
+  test('cell and titleHeight options fix the node size', ({ expect }) => {
+    const snap = (value: number) => Math.ceil(value / GRID) * GRID;
+    const nodes = nodesOf(objectsOf(compile(CLASS_DIAGRAM, { cell: { w: 256, h: 480 }, titleHeight: 48 })));
+
+    for (const node of nodes) {
+      const [frame, title] = node.elements as Scene.Box[];
+      expect(frame.w).toBe(snap(256));
+      expect(frame.h).toBe(snap(480));
+      expect(title.h).toBe(48);
+    }
+  });
+
+  test('aligned columns straighten connectors', ({ expect }) => {
+    const source = ['classDiagram', 'class A', 'class B', 'A <|-- B'].join('\n');
+    const objects = objectsOf(compile(source));
+    const edges = objects.find((object) => object.id === 'edges')!;
+
+    // The sole subtype sits directly below its supertype, so the arrow runs straight: a single
+    // two-point segment, no polyline waypoints.
+    expect(edges.elements.filter((element) => element.kind === 'line')).toHaveLength(0);
+    const [arrow] = edges.elements as Scene.Arrow[];
+    expect(arrow.start!.x).toBe(arrow.end!.x);
+    const [a, b] = ['A', 'B'].map((id) => objects.find((object) => object.id === id)!);
+    expect(a.origin!.x).toBe(b.origin!.x);
+  });
+
+  test('parallel relations between the same lanes take separate channels', ({ expect }) => {
+    const source = [
+      'classDiagram',
+      'class A',
+      'class B',
+      'class C',
+      'class D',
+      'A --> C',
+      'A --> D',
+      'B --> C',
+      'B --> D',
+    ].join('\n');
+    const edges = objectsOf(compile(source)).find((object) => object.id === 'edges')!;
+    const paths = edges.elements.filter((element): element is Scene.Polyline => element.kind === 'line');
+
+    // Column alignment can straighten at most one of the crossing edges; the rest bend through
+    // the same gutter and their channel runs must not share a coordinate.
+    expect(paths.length).toBeGreaterThanOrEqual(2);
+    const channels = paths.map((path) => path.points[1].y);
+    expect(new Set(channels).size).toBe(paths.length);
+  });
+});