@dxos/diagram 0.11.1 → 0.13.0

package/src/semantic.ts

@@ -0,0 +1,278 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// The semantic diagram: what the DSL's `diagram`/`group`/`node`/`edge` statements say, before any
+// coordinate exists. Every hint is optional — a pin, a relation, an allowed side, a waypoint — and
+// `semantic-engine.ts` fills whatever is left open. Source ranges ride along so the engine can
+// report a contradiction against the statement that caused it.
+//
+
+import type * as Scene from './scene.ts';
+
+export type Range = { from: number; to: number };
+
+/** A problem the engine found in the intent, with the source range it belongs to. */
+export type Issue = Range & { severity: 'error' | 'warning'; message: string };
+
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+export const SIDES: readonly Side[] = ['top', 'bottom', 'left', 'right'];
+
+/** Which way edges should read; the placement prefers targets on this side of their sources. */
+export type Flow = 'down' | 'up' | 'right' | 'left';
+export const FLOWS: readonly Flow[] = ['down', 'up', 'right', 'left'];
+
+export type RelationKind = 'right-of' | 'left-of' | 'above' | 'below' | 'same-row' | 'same-col';
+export const RELATION_KINDS: readonly RelationKind[] = [
+  'right-of',
+  'left-of',
+  'above',
+  'below',
+  'same-row',
+  'same-col',
+];
+
+/** `right-of X`: same row as X and to its right; `~` makes it a preference instead of a rule. */
+export type Relation = { kind: RelationKind; target: string; soft: boolean; range: Range };
+
+/** `@ x,y` pins the box's top-left exactly, in scene units; `@cell(c,r)` pins its grid cell. */
+export type Pin = ({ kind: 'point'; x: number; y: number } | { kind: 'cell'; col: number; row: number }) & {
+  range: Range;
+};
+
+export type Node = {
+  id: string;
+  label: string;
+  group?: string;
+  ref?: string;
+  pin?: Pin;
+  relations: Relation[];
+  shape?: Scene.BoxKind;
+  color?: Scene.Color;
+  fill?: Scene.Fill;
+  stroke?: Scene.Stroke;
+  range: Range;
+};
+
+export type Group = {
+  id: string;
+  label: string;
+  relations: Relation[];
+  /** Extra clear space, in scene units, between this group and the groups it is placed relative to. */
+  gap?: number;
+  /** Most columns the group may span. */
+  maxWidth?: number;
+  /** Keep the group near-square rather than a strip. */
+  compact?: boolean;
+  color?: Scene.Color;
+  range: Range;
+};
+
+/** One coordinate or both; `cell` units are grid cells, where `n.5` is the channel after cell `n`. */
+export type Waypoint = { x?: number; y?: number; unit: 'scene' | 'cell'; range: Range };
+
+/** One end of an edge; `soft` makes its sides a preference the router weighs instead of a rule. */
+export type End = { node: string; sides?: readonly Side[]; soft?: boolean; range: Range };
+
+/**
+ * Relationship words an edge may use in place of `->`, each naming the scene relation it draws.
+ * The left end is the subtype, the whole, the owner, or the one side.
+ */
+export const RELATIONSHIPS: Readonly<Record<string, Scene.Relation>> = {
+  'extends': 'inheritance',
+  'implements': 'implementation',
+  'composes': 'composition',
+  'owns': 'aggregation',
+  'one-to-many': 'one-to-many',
+  'many-to-many': 'many-to-many',
+  'depends-on': 'dependency',
+};
+
+/** The id of the scene object that holds every connector, so no node or group may take it. */
+export const CONNECTORS = 'edges';
+
+/** Relations whose target is the abstraction, which reads best above its subtypes. */
+export const pointsUp = (relation: Scene.Relation | undefined): boolean =>
+  relation === 'inheritance' || relation === 'implementation';
+
+/**
+ * How strongly a connector's relation shapes the reading of a diagram, highest first; on a box face
+ * shared by several connectors the most significant takes the centre.
+ */
+export const SIGNIFICANCE: Readonly<Record<Scene.Relation, number>> = {
+  'inheritance': 4,
+  'implementation': 4,
+  'composition': 3,
+  'aggregation': 2,
+  'one-to-many': 2,
+  'many-to-many': 2,
+  'association': 1,
+  'dependency': 0,
+};
+
+/** The significance of an edge's relation; an untyped dashed edge reads as a dependency. */
+export const significance = (relation: Scene.Relation | undefined, stroke?: Scene.Stroke): number =>
+  SIGNIFICANCE[relation ?? (stroke === 'dashed' ? 'dependency' : 'association')];
+
+export type EdgeStyle = {
+  relation?: Scene.Relation;
+  head?: Scene.ArrowHead;
+  tail?: Scene.ArrowTail;
+  stroke?: Scene.Stroke;
+  color?: Scene.Color;
+};
+
+export type Edge = EdgeStyle & {
+  /** Scene id of the connector, unique in the diagram. */
+  id: string;
+  from: End;
+  to: End;
+  label?: string;
+  via: readonly Waypoint[];
+  /** Edges with the same bus key and hub share one trunk. */
+  bus?: string;
+  range: Range;
+};
+
+/**
+ * Edges merged into one trunk: the hub end is shared, each spoke ends at its own node. `out` fans
+ * from the hub to the spokes, `in` gathers the spokes into the hub.
+ */
+export type Bus = {
+  id: string;
+  hub: End;
+  direction: 'out' | 'in';
+  edges: readonly Edge[];
+  /** Text on the trunk, from a multi-target statement's label. */
+  label?: string;
+  /** Gathered by relation rather than by a `bus` statement, so the router may still split it. */
+  implicit?: boolean;
+};
+
+export type Size = { w: number; h: number };
+
+export type Diagram = {
+  flow: Flow;
+  origin: Scene.Point;
+  /** Cell pitch (box plus gutter), in scene units; measured from the boxes when absent. */
+  grid?: Size;
+  /** Box size; measured from the longest label when absent. */
+  box?: Size;
+  /** Preferred width over height of the whole drawing. */
+  aspect?: number;
+  nodes: Node[];
+  groups: Group[];
+  edges: Edge[];
+  /** Trunk labels by bus key (`<hub>|<name>|<direction>`), from multi-target statements. */
+  busLabels: Map<string, string>;
+  /** Whether any statement said how to place or route — when none did, the mermaid engine's search is also tried. */
+  hinted: boolean;
+};
+
+export const empty = (): Diagram => ({
+  flow: 'down',
+  origin: { x: 0, y: 0 },
+  nodes: [],
+  groups: [],
+  edges: [],
+  busLabels: new Map(),
+  hinted: false,
+});
+
+/** The key edges share a trunk under. */
+export const busKey = (hub: string, name: string, direction: Bus['direction']): string => `${hub}|${name}|${direction}`;
+
+/**
+ * The implicit bus key of an inheritance edge: subtypes of one abstraction share a trunk into it,
+ * unless the author routed the edge by hand.
+ */
+export const inheritanceKey = (edge: Edge): string | undefined =>
+  edge.bus === undefined &&
+  pointsUp(edge.relation) &&
+  edge.via.length === 0 &&
+  edge.from.sides === undefined &&
+  edge.to.sides === undefined &&
+  edge.from.node !== edge.to.node
+    ? `${edge.to.node}|${edge.relation}|in`
+    : undefined;
+
+/** The edges grouped into buses (two or more edges with one key) and the rest. */
+export const buses = (diagram: Diagram): { buses: Bus[]; single: Edge[] } => {
+  const byKey = new Map<string, { hub: End; direction: Bus['direction']; edges: Edge[]; implicit: boolean }>();
+  for (const edge of diagram.edges) {
+    const implicit = inheritanceKey(edge);
+    const key = edge.bus ?? (implicit === undefined ? undefined : `~${implicit}`);
+    if (key === undefined) {
+      continue;
+    }
+    const [hub, direction] = key.endsWith('|in') ? [edge.to, 'in' as const] : [edge.from, 'out' as const];
+    const entry = byKey.get(key) ?? { hub, direction, edges: [], implicit: edge.bus === undefined };
+    entry.edges.push(edge);
+    byKey.set(key, entry);
+  }
+  const result: Bus[] = [];
+  const merged = new Set<Edge>();
+  for (const [key, { hub, direction, edges, implicit }] of byKey) {
+    if (edges.length < 2) {
+      continue;
+    }
+    edges.forEach((edge) => merged.add(edge));
+    result.push({
+      id: `${hub.node}-bus-${result.length}`,
+      hub,
+      direction,
+      edges,
+      ...(diagram.busLabels.has(key) ? { label: diagram.busLabels.get(key) } : {}),
+      ...(implicit ? { implicit } : {}),
+    });
+  }
+  return { buses: result, single: diagram.edges.filter((edge) => !merged.has(edge)) };
+};
+
+/** The mermaid dialect's token per relation, so its layering ranks abstractions as ours does. */
+const MERMAID_TOKEN: Record<Scene.Relation, string> = {
+  'association': '-->',
+  'dependency': '-.->',
+  'inheritance': '--|>',
+  'implementation': '..|>',
+  'composition': 'o-->',
+  'aggregation': 'o-->',
+  'one-to-many': '--{',
+  'many-to-many': '-->',
+};
+
+const MERMAID_ID = /^[A-Za-z0-9_-]+$/;
+const MERMAID_TEXT = /^[^[\]|"\n]*$/;
+
+/**
+ * The diagram as a mermaid flowchart, for the engine's own search when nothing was hinted; undefined
+ * when an id or label cannot be written in the mermaid subset.
+ */
+export const toMermaid = (diagram: Diagram): string | undefined => {
+  const direction = { down: 'TB', up: 'BT', right: 'LR', left: 'RL' }[diagram.flow];
+  const node = (entry: Node) => `${entry.id}[${entry.label}]`;
+  const writable =
+    diagram.nodes.every((entry) => MERMAID_ID.test(entry.id) && MERMAID_TEXT.test(entry.label)) &&
+    diagram.groups.every((group) => MERMAID_ID.test(group.id) && MERMAID_TEXT.test(group.label)) &&
+    diagram.edges.every((edge) => edge.label === undefined || MERMAID_TEXT.test(edge.label));
+  if (!writable) {
+    return undefined;
+  }
+  const lines = [`flowchart ${direction}`];
+  for (const group of diagram.groups) {
+    lines.push(`  subgraph ${group.id} [${group.label}]`);
+    diagram.nodes.filter((entry) => entry.group === group.id).forEach((entry) => lines.push(`    ${node(entry)}`));
+    lines.push('  end');
+  }
+  diagram.nodes.filter((entry) => entry.group === undefined).forEach((entry) => lines.push(`  ${node(entry)}`));
+  for (const edge of diagram.edges) {
+    lines.push(
+      `  ${edge.from.node} ${MERMAID_TOKEN[edge.relation ?? 'association']}${edge.label ? `|${edge.label}|` : ''} ${edge.to.node}`,
+    );
+  }
+  diagram.nodes.forEach(
+    (entry) => entry.ref && !/\s/.test(entry.ref) && lines.push(`  %% ref ${entry.id} ${entry.ref}`),
+  );
+  return lines.join('\n');
+};

package/src/typings.d.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const text: string;
+  export default text;
+}

package/src/uml-grid.ts

@@ -528,7 +528,12 @@ export const emit = (
       const style = relationStyle(relation.kind);
       // The final segment renders as an arrow for the head; earlier waypoints as a polyline.
       if (points.length > 2) {
-        elements.push({ kind: 'line', id: `${id}-path`, points: points.slice(0, -1), ...style });
+        elements.push({
+          kind: 'line',
+          id: `${id}-path`,
+          points: points.slice(0, -1),
+          ...(style.stroke ? { stroke: style.stroke } : {}),
+        });
       }
       elements.push({
         kind: 'arrow',

package/src/uml.test.ts

@@ -113,15 +113,19 @@ describe('uml', () => {
     // 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();
+    expect(inheritance.relation).toBe('inheritance');
     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 *');
+    expect(aggregation.relation).toBe('aggregation');
     // 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('◆');
+    // The diamond is the relation's marker at the whole's end, not a glyph in the label.
+    expect(composition.relation).toBe('composition');
+    expect(composition.text).toBeUndefined();
   });
 
   test('wraps long member lines into taller compartments, capped at maxWidth', ({ expect }) => {

package/src/uml.ts

@@ -87,7 +87,7 @@ export const parse = (source: string): UmlModel => {
   let direction: Direction = 'TB';
   let open: UmlClass | undefined;
 
-  const declare = (id: string): UmlClass => {
+  const declareClass = (id: string): UmlClass => {
     let entry = classes.get(id);
     if (!entry) {
       entry = { id, label: genericLabel(id), attributes: [], methods: [] };
@@ -134,7 +134,7 @@ export const parse = (source: string): UmlModel => {
     const cls = CLASS.exec(line);
     if (cls) {
       const [, id, label, brace] = cls;
-      const entry = declare(id);
+      const entry = declareClass(id);
       if (label) {
         entry.label = label;
       }
@@ -147,8 +147,8 @@ export const parse = (source: string): UmlModel => {
     const relation = RELATION.exec(line);
     if (relation) {
       const [, left, leftCardinality, token, rightCardinality, right, label] = relation;
-      declare(left);
-      declare(right);
+      declareClass(left);
+      declareClass(right);
       const [, kind, leftIsTarget] = RELATIONS.find(([candidate]) => candidate === token)!;
       const [from, to] = leftIsTarget ? [right, left] : [left, right];
       const [fromCardinality, toCardinality] = leftIsTarget
@@ -168,7 +168,7 @@ export const parse = (source: string): UmlModel => {
     const inline = INLINE_MEMBER.exec(line);
     if (inline) {
       const [, id, member] = inline;
-      addMember(declare(id), member);
+      addMember(declareClass(id), member);
     }
   }
 
@@ -218,14 +218,27 @@ const measure = (entry: UmlClass, maxWidth: number): ClassBox => {
   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' } : {};
+const SCENE_RELATION: Record<RelationKind, Scene.Relation | undefined> = {
+  inheritance: 'inheritance',
+  realization: 'implementation',
+  composition: 'composition',
+  aggregation: 'aggregation',
+  association: undefined,
+  dependency: 'dependency',
+};
+
+/** Arrow styling per relation kind: the scene relation sets the markers; dependency and realization dash, as in UML. */
+export const relationStyle = (kind: RelationKind): Pick<Scene.Arrow, 'relation' | 'stroke'> => {
+  const relation = SCENE_RELATION[kind];
+  return {
+    ...(relation ? { relation } : {}),
+    ...(kind === 'dependency' || kind === 'realization' ? { stroke: 'dashed' as const } : {}),
+  };
+};
 
-/** Mid-arrow label: cardinalities and the diamond glyph UML puts at the whole end. */
+/** Mid-arrow label: the cardinalities around the label; the diamond at the whole end is a marker now. */
 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(' ');
+  const text = [relation.fromCardinality, relation.label, relation.toCardinality].filter(Boolean).join(' ');
   return text || undefined;
 };
 

package/src/view.test.ts

@@ -0,0 +1,139 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import type * as Scene from './scene.ts';
+import { ascii, coordinates, extract, rows } from './view.ts';
+
+const node = (id: string, label: string, x: number, y: number): Scene.WorldObject => ({
+  id,
+  origin: { x, y },
+  elements: [{ kind: 'rect', id: 'frame', x: 0, y: 0, w: 128, h: 64, text: label }],
+});
+
+// Two boxes side by side, one below the first, and connectors A → B (right) and A → C (down).
+const SCENE: Scene.WorldObject[] = [
+  node('a', 'Alpha', 0, 0),
+  node('b', 'Beta', 256, 0),
+  node('c', 'Gamma', 0, 192),
+  {
+    id: 'ab',
+    elements: [
+      {
+        kind: 'line',
+        id: 'ab-path',
+        points: [
+          { x: 128, y: 32 },
+          { x: 200, y: 32 },
+        ],
+      },
+      { kind: 'arrow', id: 'ab', start: { x: 200, y: 32 }, end: { x: 256, y: 32 } },
+      { kind: 'text', id: 'ab-label', x: 180, y: 16, text: 'calls' },
+    ],
+  },
+  {
+    id: 'ac',
+    elements: [{ kind: 'arrow', id: 'ac', start: { x: 64, y: 64 }, end: { x: 64, y: 192 } }],
+  },
+];
+
+describe('view', () => {
+  test('extract resolves each connector to the boxes at its ends', ({ expect }) => {
+    const { boxes, paths, bounds } = extract(SCENE);
+    expect(boxes.map(({ label }) => label)).toEqual(['Alpha', 'Beta', 'Gamma']);
+    expect(paths.map(({ from, to, label }) => [from?.label, to?.label, label])).toEqual([
+      ['Alpha', 'Beta', 'calls'],
+      ['Alpha', 'Gamma', undefined],
+    ]);
+    expect(bounds).toEqual({ x: 0, y: 0, w: 384, h: 256 });
+  });
+
+  test('coordinates lists positions in grid cells', ({ expect }) => {
+    const text = coordinates(SCENE);
+    expect(text).toContain('canvas 12 × 8 cells');
+    expect(text).toContain('box "Gamma": top-left (0, 6), size 4 × 2');
+    expect(text).toContain('arrow "Alpha" → "Beta" labelled "calls": (4, 1) → (6.3, 1) → (8, 1)');
+  });
+
+  test('ascii draws boxes, labels and arrowheads where a reader expects them', ({ expect }) => {
+    const lines = ascii(SCENE).split('\n');
+    const [alpha] = lines.flatMap((line, row) => (line.includes('Alpha') ? [row] : []));
+    expect(lines[alpha]).toMatch(/Alpha.*▶.*Beta/);
+    const gamma = lines.findIndex((line) => line.includes('Gamma'));
+    expect(gamma).toBeGreaterThan(alpha);
+    expect(lines.slice(alpha, gamma).some((line) => line.includes('▼'))).toBe(true);
+  });
+
+  test('a connector routed outside every box stays on the canvas', ({ expect }) => {
+    const around: Scene.WorldObject = {
+      id: 'ba',
+      elements: [
+        {
+          kind: 'line',
+          id: 'ba-path',
+          points: [
+            { x: 320, y: 0 },
+            { x: 320, y: -64 },
+            { x: 64, y: -64 },
+          ],
+        },
+        { kind: 'arrow', id: 'ba', start: { x: 64, y: -64 }, end: { x: 64, y: 0 } },
+      ],
+    };
+    const scene = [...SCENE, around];
+    expect(extract(scene).bounds.y).toBe(-64);
+    expect(() => ascii(scene)).not.toThrow();
+    expect(coordinates(scene)).not.toMatch(/\(-/);
+  });
+
+  test('connectors with the same element id in different objects stay distinct', ({ expect }) => {
+    const edge = (id: string, from: Scene.Point, to: Scene.Point, text: string): Scene.WorldObject => ({
+      id,
+      elements: [
+        { kind: 'arrow', id: 'edge', start: from, end: to },
+        { kind: 'text', id: 'edge-label', x: 0, y: 0, text },
+      ],
+    });
+    const scene = [
+      ...SCENE.slice(0, 3),
+      edge('ab', { x: 128, y: 32 }, { x: 256, y: 32 }, 'calls'),
+      edge('ac', { x: 64, y: 64 }, { x: 64, y: 192 }, 'owns'),
+    ];
+    expect(extract(scene).paths.map(({ ref, to, label }) => [ref, to?.label, label])).toEqual([
+      ['ab/edge', 'Beta', 'calls'],
+      ['ac/edge', 'Gamma', 'owns'],
+    ]);
+  });
+
+  test("rows names an arrow's markers and line style", ({ expect }) => {
+    const [a, b] = SCENE;
+    const implementsArrow: Scene.WorldObject = {
+      id: 'ba',
+      elements: [
+        {
+          kind: 'arrow',
+          id: 'ba',
+          start: { x: 256, y: 32 },
+          end: { x: 128, y: 32 },
+          head: 'triangle',
+          stroke: 'dashed',
+        },
+      ],
+    };
+    expect(rows([a, b, implementsArrow])).toContain(
+      'arrow "Beta" → "Alpha" (dashed, hollow triangle head) runs left, row 1 to row 1',
+    );
+  });
+
+  test('rows reads boxes top to bottom and says which way each arrow runs', ({ expect }) => {
+    expect(rows(SCENE).split('\n')).toEqual([
+      'row 1 (top), left to right: "Alpha", "Beta"',
+      'row 2 (bottom), left to right: "Gamma"',
+      'arrow "Alpha" → "Beta" labelled "calls" runs right, row 1 to row 1, 1 bends',
+      'arrow "Alpha" → "Gamma" runs down, row 1 to row 2',
+      'no arrows cross',
+    ]);
+  });
+});