@dxos/diagram 0.11.1 → 0.14.0

package/src/mermaid.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, test } from 'vitest';
 
-import { compile, parse } from './mermaid.ts';
+import { compile, markers, parse } from './mermaid.ts';
 import type * as Scene from './scene.ts';
 
 /** Exercises node declarations, a labelled-blank subgraph, fan-out, and a `C <-> Y` cycle. */
@@ -55,6 +55,22 @@ describe('mermaid', () => {
     ]);
   });
 
+  test('reads the relation tokens as kinds with their UML markers', ({ expect }) => {
+    const graph = parse(
+      ['flowchart TB', '  B ..|> A', '  C -.-> D', '  E o--> F', '  G --{ H', '  I --|> J', '  K --> L'].join('\n'),
+    );
+    expect(graph.edges.map(({ kind }) => kind)).toEqual([
+      'implements',
+      'creates',
+      'contains',
+      'hasMany',
+      'inheritance',
+      'reference',
+    ]);
+    expect(markers('implements')).toEqual({ relation: 'implementation', stroke: 'dashed' });
+    expect(markers('creates')).toEqual({ relation: 'dependency', stroke: 'dashed' });
+  });
+
   test('compiles to one object per node plus a frame and an edge object', ({ expect }) => {
     const objects = objectsOf(compile(FLOWCHART));
 

package/src/mermaid.ts

@@ -29,7 +29,7 @@ export type MermaidGroup = {
 };
 
 /** Relationship kind, from the edge token; drawn with the UML end markers in `markers`. */
-export type RelationKind = 'reference' | 'inheritance' | 'hasMany' | 'contains';
+export type RelationKind = 'reference' | 'inheritance' | 'implements' | 'hasMany' | 'contains' | 'creates';
 
 export type MermaidEdge = {
   from: string;
@@ -39,23 +39,30 @@ export type MermaidEdge = {
 };
 
 /**
- * Edge tokens: mermaid's own arrows read as references; the classDiagram-style `--|>` (hollow
- * triangle) and ER-style `--{` (crow's foot) and `o-->` (circle at the source) extend the flowchart
- * grammar with the UML kinds, at the cost of mermaid.js rejecting those lines.
+ * Edge tokens: mermaid's own arrows read as references, except the dotted `-.->`, which reads as
+ * creation (UML's dashed «create» dependency). The classDiagram-style `--|>` (hollow triangle) and
+ * `..|>` (dashed hollow triangle) and ER-style `--{` (crow's foot) and `o-->` (circle at the owner)
+ * extend the flowchart grammar with the UML kinds, at the cost of mermaid.js rejecting those lines.
  */
 const EDGE_KINDS: Record<string, RelationKind> = {
   '-->': 'reference',
   '---': 'reference',
-  '-.->': 'reference',
   '==>': 'reference',
+  '-.->': 'creates',
   '--|>': 'inheritance',
+  '..|>': 'implements',
   '--{': 'hasMany',
   'o-->': 'contains',
 };
 
 /** Reference-render labels for the UML kinds, used when the edge carries none of its own. */
-const UML_LABELS: Record<string, string> = { '--|>': 'extends', '--{': 'has many', 'o-->': 'contains' };
-const UML_EDGE = /^(\s*\S+)\s*(o-->|--\|>|--\{)\s*(?:\|(.*?)\|\s*)?(\S+)\s*$/;
+const UML_LABELS: Record<string, string> = {
+  '--|>': 'extends',
+  '..|>': 'implements',
+  '--{': 'has many',
+  'o-->': 'contains',
+};
+const UML_EDGE = /^(\s*\S+)\s*(o-->|--\|>|\.\.\|>|--\{)\s*(?:\|(.*?)\|\s*)?(\S+)\s*$/;
 
 /**
  * Rewrite the UML edge tokens into mermaid-legal labelled arrows, for rendering the source with
@@ -72,15 +79,19 @@ export const toStandard = (source: string): string =>
     })
     .join('\n');
 
-/** Scene arrow markers for a relationship kind. */
-export const markers = (kind: RelationKind): Pick<Scene.Arrow, 'head' | 'tail'> => {
+/** The scene relation a relationship kind draws as, with the dash its line needs; a plain reference stays a plain arrow. */
+export const markers = (kind: RelationKind): Pick<Scene.Arrow, 'relation' | 'stroke'> => {
   switch (kind) {
     case 'inheritance':
-      return { head: 'triangle' };
+      return { relation: 'inheritance' };
+    case 'implements':
+      return { relation: 'implementation', stroke: 'dashed' };
     case 'hasMany':
-      return { head: 'crowsfoot' };
+      return { relation: 'one-to-many' };
     case 'contains':
-      return { tail: 'circle' };
+      return { relation: 'aggregation' };
+    case 'creates':
+      return { relation: 'dependency', stroke: 'dashed' };
     default:
       return {};
   }
@@ -97,8 +108,9 @@ const DIRECTIONS: Direction[] = ['TB', 'BT', 'LR', 'RL'];
 
 // `A[Label]`, `A(Label)`, `A{Label}` or a bare `A`.
 const NODE = /^([A-Za-z0-9_-]+)(?:\[(.*?)\]|\((.*?)\)|\{(.*?)\})?$/;
-// `A --> B`, `A-->|label|B`, `A --- B`, plus the UML kinds `B --|> A`, `X --{ Y`, `A o--> B`.
-const EDGE = /^(.+?)\s*(o-->|--\|>|--\{|-->|---|-\.->|==>)\s*(?:\|(.*?)\|\s*)?(.+)$/;
+// `A --> B`, `A-->|label|B`, `A --- B`, `A -.-> B`, plus the UML kinds `B --|> A`, `B ..|> A`, `X --{ Y`
+// and `A o--> B`.
+const EDGE = /^(.+?)\s*(o-->|--\|>|\.\.\|>|--\{|-->|---|-\.->|==>)\s*(?:\|(.*?)\|\s*)?(.+)$/;
 const SUBGRAPH = /^subgraph\s+([A-Za-z0-9_-]+)(?:\s*\[(.*?)\])?\s*$/;
 
 // `%% ref A packages/core/echo` — a comment to mermaid proper, so sources stay portable.
@@ -114,7 +126,7 @@ export const parse = (source: string): MermaidGraph => {
   let direction: Direction = 'TB';
   const stack: string[] = [];
 
-  const declare = (token: string): string | undefined => {
+  const declareNode = (token: string): string | undefined => {
     const match = NODE.exec(token.trim());
     if (!match) {
       return undefined;
@@ -172,8 +184,8 @@ export const parse = (source: string): MermaidGraph => {
     const edge = EDGE.exec(line);
     if (edge) {
       const [, from, token, label, to] = edge;
-      const fromId = declare(from);
-      const toId = declare(to);
+      const fromId = declareNode(from);
+      const toId = declareNode(to);
       if (fromId && toId) {
         edges.push({
           from: fromId,
@@ -185,7 +197,7 @@ export const parse = (source: string): MermaidGraph => {
       continue;
     }
 
-    declare(line);
+    declareNode(line);
   }
 
   // Directives may precede or follow the node they name.

package/src/nudge.test.ts

@@ -0,0 +1,186 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { nudge } from './nudge.ts';
+import type * as Scene from './scene.ts';
+import { type Rect } from './uml-grid.ts';
+
+const orthogonal = (points: readonly Scene.Point[]) =>
+  points.slice(1).every((point, index) => point.x === points[index].x || point.y === points[index].y);
+
+/** Whether two orthogonal polylines share a collinear stretch of positive length. */
+const overlapping = (first: readonly Scene.Point[], second: readonly Scene.Point[]) => {
+  const segments = (points: readonly Scene.Point[]) =>
+    points.slice(1).map((end, index) => [points[index], end] as const);
+  return segments(first).some(([a0, a1]) =>
+    segments(second).some(([b0, b1]) => {
+      if (a0.x === a1.x && b0.x === b1.x && a0.x === b0.x) {
+        const lo = Math.max(Math.min(a0.y, a1.y), Math.min(b0.y, b1.y));
+        const hi = Math.min(Math.max(a0.y, a1.y), Math.max(b0.y, b1.y));
+        return hi - lo > 0;
+      }
+      if (a0.y === a1.y && b0.y === b1.y && a0.y === b0.y) {
+        const lo = Math.max(Math.min(a0.x, a1.x), Math.min(b0.x, b1.x));
+        const hi = Math.min(Math.max(a0.x, a1.x), Math.max(b0.x, b1.x));
+        return hi - lo > 0;
+      }
+      return false;
+    }),
+  );
+};
+
+const onBorder = (point: Scene.Point, rect: Rect) =>
+  ((point.y === rect.y || point.y === rect.y + rect.h) && point.x >= rect.x && point.x <= rect.x + rect.w) ||
+  ((point.x === rect.x || point.x === rect.x + rect.w) && point.y >= rect.y && point.y <= rect.y + rect.h);
+
+describe('nudge', () => {
+  const source: Rect = { x: 0, y: 0, w: 128, h: 64 };
+  const left: Rect = { x: 0, y: 200, w: 128, h: 64 };
+  const right: Rect = { x: 200, y: 200, w: 128, h: 64 };
+  // A fork: both leave the same port and run down x = 64 together before one turns right.
+  const straight = {
+    points: [
+      { x: 64, y: 64 },
+      { x: 64, y: 200 },
+    ],
+    source,
+    target: left,
+  };
+  const turning = {
+    points: [
+      { x: 64, y: 64 },
+      { x: 64, y: 132 },
+      { x: 264, y: 132 },
+      { x: 264, y: 200 },
+    ],
+    source,
+    target: right,
+  };
+
+  test('two edges sharing a vertical run are separated and stay orthogonal', ({ expect }) => {
+    const [first, second] = nudge([straight, turning], { obstacles: [source, left, right] });
+    expect(orthogonal(first)).toBe(true);
+    expect(orthogonal(second)).toBe(true);
+    // The edge that turns right takes the right-hand lane, so its turn-off does not cut the other.
+    expect(second[0].x - first[0].x).toBeGreaterThanOrEqual(8);
+    expect(second[1].x).toBe(second[0].x);
+    expect(onBorder(first[0], source) && onBorder(second[0], source)).toBe(true);
+    expect(first[first.length - 1]).toEqual({ x: first[0].x, y: 200 });
+    expect(second[second.length - 1]).toEqual({ x: 264, y: 200 });
+  });
+
+  test('a fork sharing a vertical run and then a horizontal run is fully separated', ({ expect }) => {
+    const far: Rect = { x: 400, y: 200, w: 128, h: 64 };
+    const near = {
+      points: [
+        { x: 64, y: 64 },
+        { x: 64, y: 132 },
+        { x: 264, y: 132 },
+        { x: 264, y: 200 },
+      ],
+      source,
+      target: right,
+    };
+    const away = {
+      points: [
+        { x: 64, y: 64 },
+        { x: 64, y: 132 },
+        { x: 464, y: 132 },
+        { x: 464, y: 200 },
+      ],
+      source,
+      target: far,
+    };
+    const [first, second] = nudge([near, away], { obstacles: [source, right, far] });
+    expect(orthogonal(first) && orthogonal(second)).toBe(true);
+    expect(overlapping(first, second)).toBe(false);
+  });
+
+  test('a fixed bus never moves; the edge lying on it is pushed off', ({ expect }) => {
+    const bus = [
+      { x: 100, y: 100 },
+      { x: 200, y: 100 },
+    ];
+    const edge = {
+      points: [
+        { x: 64, y: 64 },
+        { x: 64, y: 100 },
+        { x: 264, y: 100 },
+        { x: 264, y: 200 },
+      ],
+      source,
+      target: right,
+    };
+    const fixed = [bus];
+    const [moved] = nudge([edge], { obstacles: [source, right], fixed });
+    expect(fixed[0]).toEqual(bus);
+    expect(Math.abs(moved[1].y - 100)).toBeGreaterThanOrEqual(8);
+    expect(moved[0]).toEqual({ x: 64, y: 64 });
+    expect(orthogonal(moved)).toBe(true);
+  });
+
+  test('ports stay put when separation would leave the box side', ({ expect }) => {
+    const narrow: Rect = { x: 0, y: 0, w: 16, h: 64 };
+    const below: Rect = { x: 0, y: 200, w: 16, h: 64 };
+    const path = {
+      points: [
+        { x: 8, y: 64 },
+        { x: 8, y: 200 },
+      ],
+      source: narrow,
+      target: below,
+    };
+    const result = nudge([path, path], { obstacles: [narrow, below] });
+    expect(result).toEqual([path.points, path.points]);
+  });
+
+  test('a run is never pushed through a box', ({ expect }) => {
+    // Both lanes beside the shared run are blocked by boxes hugging it.
+    const wall = (x: number): Rect => ({ x, y: 80, w: 40, h: 100 });
+    const edge = (y: number) => ({
+      points: [
+        { x: 64, y: 64 },
+        { x: 64, y: 200 },
+      ],
+      source,
+      target: { x: 0, y, w: 128, h: 64 },
+    });
+    const obstacles = [source, wall(20), wall(68), { x: 0, y: 200, w: 128, h: 64 }];
+    const result = nudge([edge(200), edge(200)], { obstacles });
+    expect(result.map((points) => points[0].x)).toEqual([64, 64]);
+  });
+
+  test('separates a shared run even when that costs one crossing', ({ expect }) => {
+    // Both leave the left side of one box; the line from the upper port turns off first, so either order crosses once.
+    const box: Rect = { x: 100, y: 0, w: 100, h: 40 };
+    const near: Rect = { x: 300, y: 80, w: 100, h: 40 };
+    const far: Rect = { x: 300, y: 180, w: 100, h: 40 };
+    const result = nudge([
+      {
+        points: [
+          { x: 100, y: 10 },
+          { x: 50, y: 10 },
+          { x: 50, y: 100 },
+          { x: 300, y: 100 },
+        ],
+        source: box,
+        target: near,
+      },
+      {
+        points: [
+          { x: 100, y: 30 },
+          { x: 50, y: 30 },
+          { x: 50, y: 200 },
+          { x: 300, y: 200 },
+        ],
+        source: box,
+        target: far,
+      },
+    ]);
+    expect(overlapping(result[0], result[1])).toBe(false);
+    expect(result.every(orthogonal)).toBe(true);
+  });
+});