@dxos/diagram 0.11.1 → 0.13.0

package/src/extension/complete.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type CompletionContext, type CompletionResult, autocompletion } from '@codemirror/autocomplete';
+import { syntaxTree } from '@codemirror/language';
+import { type Extension } from '@codemirror/state';
+import { type SyntaxNode } from '@lezer/common';
+
+import {
+  type AttrSpec,
+  DIAGRAM_ATTRS,
+  EDGE_ATTRS,
+  ELEMENT_ATTRS,
+  ELEMENT_KINDS,
+  type ElementKind,
+  GROUP_ATTRS,
+  NODE_ATTRS,
+  OBJECT_ATTRS,
+  RELATION_WORDS,
+  STATEMENT_KEYWORDS,
+} from '../dsl/vocabulary.ts';
+
+/** What a semantic statement accepts after its id: attributes, plus relations or edge clauses. */
+const SEMANTIC: Record<string, { attrs: readonly AttrSpec[]; words: readonly string[] }> = {
+  DiagramDecl: { attrs: DIAGRAM_ATTRS, words: [] },
+  GroupDecl: { attrs: GROUP_ATTRS, words: [...RELATION_WORDS, 'compact'] },
+  NodeDecl: { attrs: NODE_ATTRS, words: RELATION_WORDS },
+  EdgeDecl: { attrs: EDGE_ATTRS, words: ['via', 'bus'] },
+};
+
+const attributeOptions = (attrs: readonly AttrSpec[]) =>
+  attrs.map(({ name, type }) => ({
+    label: name,
+    type: 'property',
+    detail: type === 'enum' ? undefined : type,
+    apply: `${name}=`,
+  }));
+
+/** The element kind a completion is inside, read off the tree rather than re-lexing the line. */
+const enclosingKind = (context: CompletionContext, pos: number): ElementKind | undefined => {
+  let node = syntaxTree(context.state).resolveInner(pos, -1);
+  while (node.parent) {
+    if (node.name === 'Element') {
+      const shape = node.firstChild;
+      const keyword = shape && (shape.getChild('BoxKind') ?? shape.getChild('PathKind'))?.firstChild;
+      const word = context.state.doc.sliceString(
+        (keyword ?? shape?.firstChild)?.from ?? 0,
+        (keyword ?? shape?.firstChild)?.to ?? 0,
+      );
+      return ELEMENT_KINDS.find((kind) => kind === word);
+    }
+    if (node.name === 'ObjectDecl' || node.name === 'ElementsDecl') {
+      // Inside the declaration but outside any element: the object's own attributes.
+      return undefined;
+    }
+    node = node.parent;
+  }
+  return undefined;
+};
+
+/** Node names from the cursor out to the document, so a position is classified by where it sits. */
+const ancestorsOf = (context: CompletionContext, pos: number): string[] => {
+  const names: string[] = [];
+  for (let node: SyntaxNode | null = syntaxTree(context.state).resolveInner(pos, -1); node; node = node.parent) {
+    names.push(node.name);
+  }
+  return names;
+};
+
+const source = (context: CompletionContext): CompletionResult | null => {
+  const word = context.matchBefore(/[\w-]*/);
+  if (!word || (word.from === word.to && !context.explicit)) {
+    return null;
+  }
+
+  const ancestors = ancestorsOf(context, context.pos);
+  // Inside a semantic statement the innermost one decides; a group's body holds nodes and edges.
+  const innermost = ancestors.find((name) => name in SEMANTIC || name === 'GroupBody');
+  if (innermost === 'GroupBody') {
+    return { from: word.from, options: ['node', 'edge'].map((label) => ({ label, type: 'keyword' })) };
+  }
+  if (innermost) {
+    const { attrs, words } = SEMANTIC[innermost];
+    return {
+      from: word.from,
+      options: [...words.map((label) => ({ label, type: 'keyword' })), ...attributeOptions(attrs)],
+    };
+  }
+  // Outside any declaration only a statement can start.
+  if (!ancestors.includes('ObjectDecl') && !ancestors.includes('ElementsDecl')) {
+    return { from: word.from, options: STATEMENT_KEYWORDS.map((label) => ({ label, type: 'keyword' })) };
+  }
+
+  // A `Body` holds elements and nothing else, so an empty position in one wants a kind; inside an
+  // element it wants that kind's attributes, and in the header it wants the object's.
+  const kind = enclosingKind(context, context.pos);
+  if (!kind && ancestors.includes('Body')) {
+    return { from: word.from, options: ELEMENT_KINDS.map((label) => ({ label, type: 'keyword' })) };
+  }
+
+  return { from: word.from, options: attributeOptions(kind ? ELEMENT_ATTRS[kind] : OBJECT_ATTRS) };
+};
+
+export const diagramComplete: Extension = autocompletion({ override: [source] });

package/src/extension/extension.test.ts

@@ -0,0 +1,135 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { HighlightStyle } from '@codemirror/language';
+import { highlightTree } from '@lezer/highlight';
+import { vscodeDarkStyle, vscodeLightStyle } from '@uiw/codemirror-theme-vscode';
+import { describe, test } from 'vitest';
+
+import { printCommands } from '../dsl/print.ts';
+import { diagramHighlightStyle } from './highlight.ts';
+import { diagram } from './language.ts';
+import { diagramDiagnostics } from './lint.ts';
+import { diagramLanguage } from './syntax.ts';
+
+describe('diagram language', () => {
+  test('the mode composes without an editor', ({ expect }) => {
+    expect(diagram({ layout: true })).toBeDefined();
+    expect(diagramLanguage.name).toEqual('diagram');
+  });
+
+  test('highlighting comes off the tree, not a regex', ({ expect }) => {
+    const source = 'object A @ 0,0 {\n  rect box 0,0 10x10 "hi" color=red\n}\n';
+    const tree = diagramLanguage.parser.parse(source);
+    const names: string[] = [];
+    const cursor = tree.cursor();
+    do {
+      names.push(cursor.name);
+    } while (cursor.next());
+    expect(names).toContain('ObjectDecl');
+    expect(names).toContain('BoxElement');
+    expect(names).toContain('AttrName');
+    expect(names).not.toContain('⚠');
+  });
+
+  //
+  // The tags are standard so the theme colours most of a document, but `vscode*Style` defines
+  // neither `attributeValue` nor `null` — enum values and the unbound arrow end rendered plain
+  // until `diagramHighlightStyle` filled them. Asserting against the real theme is what catches
+  // the next tag added to `styleTags` with nothing to colour it.
+  //
+  for (const [mode, themeStyle] of [
+    ['light', vscodeLightStyle],
+    ['dark', vscodeDarkStyle],
+  ] as const) {
+    test(`every token is coloured under the ${mode} theme`, ({ expect }) => {
+      expect(uncoloured(SAMPLE, themeStyle)).toEqual([]);
+    });
+
+    test(`every semantic token is coloured under the ${mode} theme`, ({ expect }) => {
+      expect(uncoloured(SEMANTIC_SAMPLE, themeStyle)).toEqual([]);
+    });
+  }
+});
+
+/** Every element kind, both arrow forms, a quoted id, a comment — one of each tag the grammar emits. */
+const SAMPLE = `# comment
+object pkgA @ -24,-24 scale=1 index="a1" {
+  rect frame 0,0 248x172 "Package A" color=grey stroke=dashed
+  line path 0,0 10,10 closed=true
+  arc smile 50,50 20 0..180
+  arrow e1 A/box#left -> B/box "extends" head=triangle
+  arrow e2 10,20 -> _
+  portal "1st" 0,0 10x10 ref="dxn:echo:@:01"
+}
+`;
+
+/** The semantic statements, with soft sides, a compact group, an aspect ratio and a fan-in bus. */
+const SEMANTIC_SAMPLE = `diagram flow=down aspect=4:3
+group g "G" compact max-width=2 ~right-of h { node A  node B below A }
+group h { node C }
+edge A:~left|top, B -> C "joins" bus
+`;
+
+/** Non-whitespace runs that no highlighter claimed, as `offset:"text"`. */
+const uncoloured = (source: string, themeStyle: Parameters<typeof HighlightStyle.define>[0]): string[] => {
+  const covered = new Uint8Array(source.length);
+  for (const style of [HighlightStyle.define(themeStyle), diagramHighlightStyle()]) {
+    highlightTree(diagramLanguage.parser.parse(source), style, (from, to, classes) => {
+      if (classes) {
+        covered.fill(1, from, to);
+      }
+    });
+  }
+
+  const gaps: string[] = [];
+  let run = '';
+  let start = 0;
+  for (let index = 0; index <= source.length; index++) {
+    const bare = index < source.length && !covered[index] && !/\s/.test(source[index]);
+    if (bare) {
+      if (!run) {
+        start = index;
+      }
+      run += source[index];
+    } else if (run) {
+      gaps.push(`${start}:${JSON.stringify(run)}`);
+      run = '';
+    }
+  }
+  return gaps;
+};
+
+describe('diagram lint', () => {
+  test('a clean document reports nothing', ({ expect }) => {
+    expect(diagramDiagnostics('object A @ 0,0 {\n  rect box 0,0 10x10\n}\n', { layout: true })).toEqual([]);
+  });
+
+  test('parse problems carry a range inside the document', ({ expect }) => {
+    const source = 'object A @ 0,0 {\n  rect box 0,0 10x10 colour=red\n}\n';
+    const [diagnostic, ...rest] = diagramDiagnostics(source);
+    expect(rest).toEqual([]);
+    expect(diagnostic.message).toContain('colour');
+    expect(source.slice(diagnostic.from, diagnostic.to)).toEqual('colour=red');
+  });
+
+  test('a layout error points at the object that caused it, not the top of the file', ({ expect }) => {
+    // Two boxes on the same spot — `node-overlap`, which `Diagnostics` reports against both refs.
+    const source = printCommands([
+      { op: 'upsert-object', object: { id: 'A', origin: { x: 0, y: 0 }, elements: [box('a')] } },
+      { op: 'upsert-object', object: { id: 'B', origin: { x: 0, y: 0 }, elements: [box('b')] } },
+    ]);
+    const overlaps = diagramDiagnostics(source, { layout: true }).filter(({ source: code }) => code === 'node-overlap');
+    expect(overlaps.length).toBeGreaterThan(0);
+    expect(overlaps[0].from).toBeGreaterThan(0);
+    expect(source.slice(overlaps[0].from, overlaps[0].to)).toContain('rect');
+  });
+
+  test('layout is not analysed while the document has a syntax error', ({ expect }) => {
+    const diagnostics = diagramDiagnostics('object A @ 0,0 {\n  rect box 0,0\n}\n', { layout: true });
+    expect(diagnostics.every(({ source }) => source === undefined)).toBe(true);
+  });
+});
+
+const box = (id: string) => ({ kind: 'rect', id, x: 0, y: 0, w: 100, h: 50 }) as const;

package/src/extension/highlight.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { HighlightStyle } from '@codemirror/language';
+import { tags } from '@lezer/highlight';
+
+/**
+ * Fills the gaps the editor's own highlight style leaves. The grammar emits standard
+ * `@lezer/highlight` tags, so most of a document is coloured by whatever style the theme installs
+ * and inherits its palette — but `vscodeLightStyle`/`vscodeDarkStyle` define neither
+ * `attributeValue` nor `null`, which in this language are the enum values (`grey`, `dashed`,
+ * `triangle`) and the unbound arrow end. Those are the most scannable part of a diagram, so
+ * leaving them uncoloured is the one thing worth overriding.
+ *
+ * Classes are semantic theme tokens rather than hues, as in `mermaidHighlightStyle`, so light and
+ * dark follow the palette.
+ */
+export const diagramHighlightStyle = () =>
+  HighlightStyle.define([
+    { tag: tags.attributeValue, class: 'text-accent' },
+    { tag: tags.null, class: 'text-fg-subtle' },
+  ]);

package/src/extension/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { diagram, diagramBlockDescription } from './language.ts';
+export { type LintOptions, diagramDiagnostics, diagramLint } from './lint.ts';
+export { diagramComplete } from './complete.ts';
+export { diagramHighlightStyle } from './highlight.ts';
+export { diagramLanguage } from './syntax.ts';

package/src/extension/language.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { LanguageDescription, LanguageSupport, syntaxHighlighting } from '@codemirror/language';
+import { type Extension } from '@codemirror/state';
+
+import { diagramComplete } from './complete.ts';
+import { diagramHighlightStyle } from './highlight.ts';
+import { type LintOptions, diagramLint } from './lint.ts';
+import { diagramLanguage } from './syntax.ts';
+
+/**
+ * The fence dispatch point. Pass this alongside deus's `mdlBlockDescription` in
+ * `createMarkdownExtensions({ codeLanguages: [...] })` and a ```diagram block inside a `.mdl`
+ * document parses with the diagram grammar — a sibling of MDL's, not a nesting inside it. See
+ * `docs/DSL.md`.
+ */
+export const diagramBlockDescription = LanguageDescription.of({
+  name: 'diagram',
+  alias: ['dxd'],
+  support: new LanguageSupport(diagramLanguage),
+});
+
+/** The whole editing surface for a standalone DSL buffer: mode, highlighting, completion, lint. */
+export const diagram = (options: LintOptions = {}): Extension => [
+  new LanguageSupport(diagramLanguage),
+  syntaxHighlighting(diagramHighlightStyle()),
+  diagramComplete,
+  diagramLint(options),
+];

package/src/extension/lint.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Diagnostic, linter } from '@codemirror/lint';
+import { type Extension } from '@codemirror/state';
+import { type EditorView } from '@codemirror/view';
+
+import * as Diagnostics from '../diagnostics.ts';
+import { parse, read, toScene } from '../dsl/parse.ts';
+
+export type LintOptions = {
+  /**
+   * Also report the layout diagnostics — overlaps, a connector through a node, a label that does
+   * not fit. Off by default because a document being typed is briefly nonsense; the bench and the
+   * agent loop both want it on.
+   */
+  layout?: boolean;
+};
+
+/**
+ * What is wrong with a document: everything `parse` found, and optionally everything
+ * `Diagnostics.analyze` finds in the scene it produced, each carrying the range of the statement
+ * or element that produced it — a layout error is only actionable when it points at the box it is
+ * about. Separate from the CodeMirror wrapper so it needs no editor, which is also how the
+ * agent-facing path reports the same problems.
+ */
+export const diagramDiagnostics = (text: string, { layout = false }: LintOptions = {}): Diagnostic[] => {
+  // Laying out semantic statements is a search; without the layout report only the reading is needed.
+  const { commands, problems, ranges } = layout ? parse(text) : read(text);
+  const clamp = (value: number) => Math.max(0, Math.min(value, text.length));
+
+  const diagnostics: Diagnostic[] = problems.map(({ severity, message, from, to }) => ({
+    severity,
+    message,
+    from: clamp(from),
+    to: clamp(to),
+  }));
+
+  // A document with a syntax error has a scene that is missing pieces, so its layout report would
+  // be noise on top of an error the author is already fixing.
+  if (layout && !problems.some(({ severity }) => severity === 'error')) {
+    for (const diagnostic of Diagnostics.analyze(toScene(commands).objects).diagnostics) {
+      const range = diagnostic.refs.flatMap((ref) => ranges.get(ref) ?? []).at(0);
+      diagnostics.push({
+        severity: diagnostic.severity,
+        source: diagnostic.code,
+        message: diagnostic.message,
+        from: clamp(range?.from ?? 0),
+        to: clamp(range?.to ?? Math.min(1, text.length)),
+      });
+    }
+  }
+
+  return diagnostics.sort((left, right) => left.from - right.from);
+};
+
+/** The CodeMirror linter over {@link diagramDiagnostics}. */
+export const diagramLint = (options: LintOptions = {}): Extension =>
+  linter((view: EditorView): Diagnostic[] => diagramDiagnostics(view.state.doc.toString(), options));

package/src/extension/syntax.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { LRLanguage } from '@codemirror/language';
+import { styleTags, tags } from '@lezer/highlight';
+
+import { parser } from '../dsl/gen/diagram.ts';
+
+//
+// Unlike deus's MDL mode — which keeps highlighting on a regex ViewPlugin so prose inside a block
+// cannot trip LR error recovery — the diagram grammar covers its whole input, so highlighting comes
+// off the tree. The tags are the standard ones, so most of a document inherits the editor's own
+// palette; `highlight.ts` covers only the two the theme leaves undefined.
+//
+
+export const diagramLanguage = LRLanguage.define({
+  name: 'diagram',
+  parser: parser.configure({
+    props: [
+      styleTags({
+        'object elements move remove diagram group node edge': tags.definitionKeyword,
+        'cell via bus compact': tags.keyword,
+        // Relation words and sides are plain names the reader checks, so they are tagged by position.
+        'RelationKind Side': tags.keyword,
+        'Soft': tags.modifier,
+        'rect ellipse diamond triangle circle line curve arc text arrow portal': tags.keyword,
+        // A quoted id is still an id, not a string.
+        'Id/String': tags.variableName,
+        'Id': tags.variableName,
+        'Ref': tags.propertyName,
+        'Label': tags.string,
+        'String': tags.string,
+        'Number': tags.number,
+        'Size': tags.number,
+        'Ratio': tags.number,
+        'AttrName': tags.attributeName,
+        // On the leaf, not on `AttrValue`/`Unbound`: a named child with no tag of its own does not
+        // inherit its parent's, so tagging the wrapper colours nothing. A numeric or quoted value
+        // keeps its own number/string tag; this is the bare enum word (`grey`, `dashed`).
+        'Word': tags.attributeValue,
+        // `head=triangle`, `head=arrow`, `tail=circle`: schema literals that are also element-kind
+        // keywords, so without the path they would colour as keywords while every other enum value
+        // colours as a value. Listed in full, like the grammar's own `Word` alternation, so a
+        // literal that starts colliding later is already covered.
+        'Word/object Word/elements Word/move Word/remove Word/rect Word/ellipse Word/diamond Word/triangle Word/circle Word/line Word/curve Word/arc Word/text Word/arrow Word/portal Word/diagram Word/group Word/node Word/edge Word/cell Word/via Word/bus Word/compact':
+          tags.attributeValue,
+        '_': tags.null,
+        'Comment': tags.lineComment,
+        '-> <-> -- @ .. : | ~': tags.operator,
+        '( )': tags.paren,
+        '=': tags.definitionOperator,
+        ',': tags.separator,
+        '{ }': tags.brace,
+      }),
+    ],
+  }),
+  languageData: {
+    commentTokens: { line: '#' },
+    closeBrackets: { brackets: ['{', '"'] },
+  },
+});

package/src/index.ts

@@ -4,12 +4,25 @@
 
 export * from './content.ts';
 export * from './dialect.ts';
+export * as Aesthetics from './aesthetics.ts';
+export * as Appeal from './appeal.ts';
+export * as Architecture from './architecture.ts';
 export * as Diagnostics from './diagnostics.ts';
+export * as Dsl from './dsl/index.ts';
+export * as DxSvg from './dx-svg.ts';
 export * as Layout from './layout.ts';
 export * as Mermaid from './mermaid.ts';
 export * as MermaidEngine from './mermaid-engine.ts';
+export * as Nudge from './nudge.ts';
 export * as Objective from './objective.ts';
+export * as Ports from './ports.ts';
+export * as Rules from './rules.ts';
 export * as Scene from './scene.ts';
+export * as Semantic from './semantic.ts';
+export * as SemanticEngine from './semantic-engine.ts';
+export * as SemanticPlace from './semantic-place.ts';
+export * as SemanticRoute from './semantic-route.ts';
+export * as Score from './score.ts';
 export * from './svg-handler.ts';
 export * as Ui from './ui.ts';
 export * as Uml from './uml.ts';
@@ -17,3 +30,4 @@ export * as UmlEngine from './uml-engine.ts';
 export * as UmlGrid from './uml-grid.ts';
 export * as UmlRules from './uml-rules.ts';
 export * as UmlSearch from './uml-search.ts';
+export * as View from './view.ts';

package/src/mermaid-engine.test.ts

@@ -119,7 +119,7 @@ describe('mermaid-engine', { timeout: 120_000 }, () => {
     expect(edges.filter(({ id }) => /-stub-\d$/.test(id))).toHaveLength(2);
     const labelled = edges.filter((element) => element.kind === 'text' && element.text === 'via mixin');
     expect(labelled).toHaveLength(1);
-    expect(edges.filter((element) => element.kind === 'arrow' && element.head === 'triangle')).toHaveLength(2);
+    expect(edges.filter((element) => element.kind === 'arrow' && element.relation === 'inheritance')).toHaveLength(2);
   });
 
   test('toStandard rewrites the UML tokens into mermaid-legal labelled arrows', ({ expect }) => {
@@ -181,10 +181,10 @@ describe('mermaid-engine', { timeout: 120_000 }, () => {
       .elements.flatMap((element) => (element.kind === 'arrow' ? [element] : []));
     const byId = (prefix: string) => arrows.find(({ id }) => id.startsWith(prefix))!;
 
-    expect(byId('B-A')).toMatchObject({ head: 'triangle' });
-    expect(byId('X-Y')).toMatchObject({ head: 'crowsfoot' });
-    expect(byId('P-Q')).toMatchObject({ tail: 'circle' });
-    expect(byId('R-S').head).toBeUndefined();
+    expect(byId('B-A')).toMatchObject({ relation: 'inheritance' });
+    expect(byId('X-Y')).toMatchObject({ relation: 'one-to-many' });
+    expect(byId('P-Q')).toMatchObject({ relation: 'aggregation' });
+    expect(byId('R-S').relation).toBeUndefined();
   });
 
   test('basic: no hard defects, every connector straight or one bend', async ({ expect }) => {
@@ -204,7 +204,7 @@ describe('mermaid-engine', { timeout: 120_000 }, () => {
     const edges = objects.find(({ id }) => id === 'edges')!.elements;
     expect(edges.find(({ id }) => id === 'A-bus')?.kind).toBe('line');
     expect(edges.filter(({ id }) => id.endsWith('-stub-0') || id.endsWith('-stub-1'))).toHaveLength(2);
-    expect(edges.filter((element) => element.kind === 'arrow' && element.head === 'triangle')).toHaveLength(1);
+    expect(edges.filter((element) => element.kind === 'arrow' && element.relation === 'inheritance')).toHaveLength(1);
     // Nothing else needs a second bend, and the three frames sit at equal gaps.
     expect(report.metrics.frameGapSpread).toBe(0);