@diagrammo/dgmo 0.26.0 → 0.27.0

package/src/utils/notes/build.ts

@@ -0,0 +1,131 @@
+// ============================================================
+// Generic diagram note — layout assembly
+// ============================================================
+//
+// Turns resolved notes + positioned anchor rects into render-ready
+// {@link PlacedNote}s (box geometry LOCAL to each node's center, or a
+// collapsed flag). A chart's layout calls this once, attaches each
+// PlacedNote to its layout node, then extends its content bbox with the
+// note rects and applies `noteCanvasShift`. Keeps every adopting chart's
+// note wiring to a few lines.
+
+import { noteBoxSize } from '../note-box';
+import type { WrappedDescLine } from '../wrapped-desc';
+import { placeNotes, type NoteSide, type PlaceableNode } from './place';
+import type { DiagramNote } from './model';
+
+/** A resolved, placed note ready for the note-box drawer. */
+export interface PlacedNote {
+  /** Box left, LOCAL to the node center (add node.x). Unused if collapsed. */
+  readonly x: number;
+  /** Box top, LOCAL to the node center (add node.y). Unused if collapsed. */
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly side: NoteSide;
+  /** Resolved hex accent (border + faded fill); default yellow if absent. */
+  readonly color?: string;
+  readonly lines: readonly WrappedDescLine[];
+  readonly lineNumber: number;
+  readonly endLineNumber: number;
+  /** Collapsed → renderer draws a corner badge; box geometry is unused. */
+  readonly collapsed?: boolean;
+}
+
+/** A positioned anchor node: its id plus its center rect. */
+export interface NoteAnchor extends PlaceableNode {
+  readonly id: string;
+}
+
+/**
+ * Build a map of node id → {@link PlacedNote} for every anchor that has a
+ * resolved note. Measures each note, runs the shared collision placer, and
+ * assembles render-ready geometry. Collapsed notes (lineNumber ∈
+ * `collapsedNotes`) reserve no space.
+ */
+export function buildPlacedNotes(
+  anchors: readonly NoteAnchor[],
+  noteByNode: ReadonlyMap<string, DiagramNote>,
+  direction: 'TB' | 'LR',
+  collapsedNotes?: ReadonlySet<number>
+): Map<string, PlacedNote> {
+  const placed = new Map<string, PlacedNote>();
+  if (noteByNode.size === 0) return placed;
+
+  interface Geom {
+    readonly noteW: number;
+    readonly noteH: number;
+    readonly color?: string;
+    readonly lines: readonly WrappedDescLine[];
+    readonly lineNumber: number;
+    readonly endLineNumber: number;
+  }
+  const geoms = new Map<string, Geom>();
+  const requests: {
+    key: string;
+    node: PlaceableNode;
+    noteW: number;
+    noteH: number;
+    collapsed: boolean;
+  }[] = [];
+
+  for (const a of anchors) {
+    const note = noteByNode.get(a.id);
+    if (!note) continue;
+    const size = noteBoxSize(note.body);
+    geoms.set(a.id, {
+      noteW: size.width,
+      noteH: size.height,
+      ...(note.color && { color: note.color }),
+      lines: size.lines,
+      lineNumber: note.lineNumber,
+      endLineNumber: note.endLineNumber,
+    });
+    requests.push({
+      key: a.id,
+      node: { x: a.x, y: a.y, width: a.width, height: a.height },
+      noteW: size.width,
+      noteH: size.height,
+      collapsed: collapsedNotes?.has(note.lineNumber) ?? false,
+    });
+  }
+
+  const placements = placeNotes(
+    anchors.map((a) => ({ x: a.x, y: a.y, width: a.width, height: a.height })),
+    requests,
+    direction
+  );
+
+  for (const [id, g] of geoms) {
+    const p = placements.get(id)!;
+    placed.set(
+      id,
+      p.collapsed
+        ? {
+            x: 0,
+            y: 0,
+            width: 0,
+            height: 0,
+            side: 'right',
+            ...(g.color && { color: g.color }),
+            lines: [],
+            lineNumber: g.lineNumber,
+            endLineNumber: g.endLineNumber,
+            collapsed: true,
+          }
+        : {
+            x: p.x,
+            y: p.y,
+            width: g.noteW,
+            height: g.noteH,
+            side: p.side,
+            ...(g.color && { color: g.color }),
+            lines: g.lines,
+            lineNumber: g.lineNumber,
+            endLineNumber: g.endLineNumber,
+          }
+    );
+  }
+
+  return placed;
+}

package/src/utils/notes/index.ts

@@ -0,0 +1,18 @@
+// ============================================================
+// Generic diagram notes — barrel
+// ============================================================
+//
+// One chart-neutral note pipeline: model → parse → resolve → place →
+// shift, plus the shared `note-box` drawer. A node-based chart adopts
+// notes by importing from here and supplying only an anchor list and the
+// per-chart layout wiring. See the cross-chart rollout tech spec.
+
+export * from './model';
+export * from './parse';
+export * from './resolve';
+export * from './place';
+export * from './build';
+export * from './bounds';
+
+// Re-export the drawer so charts have one import site for the whole feature.
+export * from '../note-box';

package/src/utils/notes/model.ts

@@ -0,0 +1,19 @@
+// ============================================================
+// Generic diagram note — chart-neutral model
+// ============================================================
+//
+// One annotation attachable to any node-based chart. The parser collects
+// raw `{ref, body, color?}`; a shared resolver binds `ref` to a concrete
+// node, and a shared placer + the `utils/note-box` drawer render it. Each
+// chart adds only a note-line handler + an anchor (id/label) list.
+
+export interface DiagramNote {
+  /** Author-typed node id/label the note attaches to. */
+  readonly ref: string;
+  /** Body text (inline + indented lines, joined with `\n`). */
+  readonly body: string;
+  /** Resolved hex accent (border + faded fill); default yellow if absent. */
+  readonly color?: string;
+  readonly lineNumber: number;
+  readonly endLineNumber: number;
+}

package/src/utils/notes/parse.ts

@@ -0,0 +1,131 @@
+// ============================================================
+// Generic diagram note — shared parsing
+// ============================================================
+
+import { makeDgmoError, type DgmoError } from '../../diagnostics';
+import type { PaletteColors } from '../../palettes';
+import { measureIndent, extractColor } from '../parsing';
+import type { DiagramNote } from './model';
+
+/**
+ * Split a `note` heading's remainder into a `ref` token and inline body.
+ * Quote the ref for multi-word labels:
+ *   `note Foo a comment`        → { ref: 'Foo', inlineBody: 'a comment' }
+ *   `note "Order Received" done` → { ref: 'Order Received', inlineBody: 'done' }
+ */
+export function parseNoteHeader(rest: string): {
+  ref: string;
+  inlineBody: string;
+} {
+  const t = rest.trim();
+  const quoted = t.match(/^"([^"]+)"\s*(.*)$/);
+  if (quoted) {
+    return { ref: quoted[1]!.trim(), inlineBody: quoted[2]!.trim() };
+  }
+  const m = t.match(/^(\S+)\s*(.*)$/);
+  if (m) {
+    return { ref: m[1]!, inlineBody: m[2]!.trim() };
+  }
+  return { ref: t, inlineBody: '' };
+}
+
+export interface CollectedNoteBody {
+  readonly body: string;
+  readonly endLineNumber: number;
+  /** 0-based index of the last source line consumed. */
+  readonly lastIndex: number;
+}
+
+/**
+ * Collect a note's multi-line body: following lines indented MORE than the
+ * note line. A blank line or a dedent terminates. Lines are trimmed and
+ * joined with `\n`; the inline body (if any) leads.
+ */
+export function collectNoteBody(
+  lines: readonly string[],
+  noteIndex: number,
+  noteIndent: number,
+  inlineBody: string
+): CollectedNoteBody {
+  const parts: string[] = [];
+  if (inlineBody) parts.push(inlineBody);
+
+  let lastIndex = noteIndex;
+  let endLineNumber = noteIndex + 1;
+
+  for (let j = noteIndex + 1; j < lines.length; j++) {
+    const raw = lines[j]!;
+    const trimmed = raw.trim();
+    if (!trimmed) break;
+    if (measureIndent(raw) <= noteIndent) break;
+    parts.push(trimmed);
+    lastIndex = j;
+    endLineNumber = j + 1;
+  }
+
+  return { body: parts.join('\n'), endLineNumber, lastIndex };
+}
+
+export interface TryCollectNoteResult {
+  /** Absent when the body was empty (a warning was pushed, line consumed). */
+  readonly note?: DiagramNote;
+  /** 0-based index of the last consumed source line. */
+  readonly lastIndex: number;
+}
+
+/**
+ * Try to parse a `note` line at `lines[index]` into a {@link DiagramNote},
+ * collecting any indented body and peeling a trailing color word. Returns
+ * `null` when the line is not a note (incl. `note -> X`, which a chart with
+ * bare-name nodes parses as an edge). On an empty body, emits a warning and
+ * returns `{ lastIndex }` with no note (the line is still consumed).
+ *
+ * Each chart calls this in its main loop:
+ *   const r = tryCollectNote(lines, i, indent, palette, diagnostics);
+ *   if (r) { if (r.note) notes.push(r.note); i = r.lastIndex; continue; }
+ */
+export function tryCollectNote(
+  lines: readonly string[],
+  index: number,
+  indent: number,
+  palette: PaletteColors | undefined,
+  diagnostics: DgmoError[]
+): TryCollectNoteResult | null {
+  const trimmed = lines[index]!.trim();
+  const m = trimmed.match(/^note\s+(.+)$/i);
+  if (!m || /^note\s+->/i.test(trimmed)) return null;
+
+  const lineNumber = index + 1;
+  // Trailing lowercase color word colors the note (§1.5); capitalize to
+  // keep it as literal body text.
+  const { label: headerNoColor, color } = extractColor(
+    m[1]!,
+    palette,
+    diagnostics,
+    lineNumber
+  );
+  const { ref, inlineBody } = parseNoteHeader(headerNoColor);
+  const collected = collectNoteBody(lines, index, indent, inlineBody);
+
+  if (!collected.body.trim()) {
+    diagnostics.push(
+      makeDgmoError(
+        lineNumber,
+        `Note on "${ref}" has no text — ignored.`,
+        'warning'
+      )
+    );
+    return { lastIndex: collected.lastIndex };
+  }
+
+  return {
+    note: {
+      ref,
+      body: collected.body,
+      ...(color && { color }),
+      lineNumber,
+      endLineNumber: collected.endLineNumber,
+    },
+    lastIndex: collected.lastIndex,
+  };
+}

package/src/utils/notes/place.ts

@@ -0,0 +1,177 @@
+// ============================================================
+// Generic diagram note — collision-aware placement
+// ============================================================
+//
+// Floats each note beside its anchor node WITHOUT moving the node, so the
+// shape keeps its layout position and its edge connections. Ported verbatim
+// from the graph layout's "Collision-aware note placement" block so every
+// chart shares one placement policy. The caller supplies positioned node
+// rects (`obstacles`) and per-note requests; this returns a box position
+// LOCAL to each node's center (the renderer's translate origin).
+
+import { NOTE_GAP } from '../note-box';
+
+export type NoteSide = 'above' | 'below' | 'left' | 'right';
+
+/** A positioned rect (center + size) that a note must avoid overlapping. */
+export interface PlaceableNode {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface NotePlaceRequest {
+  /** Stable key (node id) the result map is keyed by. */
+  readonly key: string;
+  /** The anchor node the note floats beside. */
+  readonly node: PlaceableNode;
+  readonly noteW: number;
+  readonly noteH: number;
+  /** Collapsed notes reserve no space — drawn as a corner badge. */
+  readonly collapsed: boolean;
+}
+
+export interface NotePlacement {
+  readonly collapsed: boolean;
+  readonly side: NoteSide;
+  /** Box left/top, LOCAL to the node center (add node.x / node.y). */
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Clearance kept between a note and any obstacle (node or earlier note). */
+export const NOTE_CLEAR = 14;
+
+type Rect = { left: number; top: number; right: number; bottom: number };
+
+const intersects = (a: Rect, b: Rect, pad: number): boolean =>
+  !(
+    a.right + pad <= b.left ||
+    b.right + pad <= a.left ||
+    a.bottom + pad <= b.top ||
+    b.bottom + pad <= a.top
+  );
+
+/**
+ * Place each note beside its node. Try the default side (right for TB,
+ * below for LR); if it would overlap an obstacle flip to the opposite
+ * side; if both collide, push the default side outward past the blockers.
+ * Each placed note then becomes an obstacle for later notes, so notes keep
+ * a comfortable distance from every shape and from each other.
+ *
+ * Returns a map keyed by request `key`. The `x/y` are the box left/top
+ * relative to the node center; collapsed requests return `{collapsed:true,
+ * side:'right', x:0, y:0}`.
+ */
+export function placeNotes(
+  obstacles: readonly PlaceableNode[],
+  requests: readonly NotePlaceRequest[],
+  direction: 'TB' | 'LR'
+): Map<string, NotePlacement> {
+  const placements = new Map<string, NotePlacement>();
+
+  const occupied: Rect[] = obstacles.map((p) => ({
+    left: p.x - p.width / 2,
+    top: p.y - p.height / 2,
+    right: p.x + p.width / 2,
+    bottom: p.y + p.height / 2,
+  }));
+
+  for (const req of requests) {
+    if (req.collapsed) {
+      placements.set(req.key, {
+        collapsed: true,
+        side: 'right',
+        x: 0,
+        y: 0,
+      });
+      continue;
+    }
+
+    const p = req.node;
+    const cx = p.x;
+    const cy = p.y;
+    const nodeLeft = cx - p.width / 2;
+    const nodeRight = cx + p.width / 2;
+    const nodeTop = cy - p.height / 2;
+    const nodeBottom = cy + p.height / 2;
+    const { noteW, noteH } = req;
+
+    const rectFor = (side: NoteSide): Rect => {
+      switch (side) {
+        case 'right': {
+          const left = nodeRight + NOTE_GAP;
+          const top = cy - noteH / 2;
+          return { left, top, right: left + noteW, bottom: top + noteH };
+        }
+        case 'left': {
+          const right = nodeLeft - NOTE_GAP;
+          const top = cy - noteH / 2;
+          return { left: right - noteW, top, right, bottom: top + noteH };
+        }
+        case 'below': {
+          const left = cx - noteW / 2;
+          const top = nodeBottom + NOTE_GAP;
+          return { left, top, right: left + noteW, bottom: top + noteH };
+        }
+        case 'above':
+        default: {
+          const left = cx - noteW / 2;
+          const bottom = nodeTop - NOTE_GAP;
+          return { left, top: bottom - noteH, right: left + noteW, bottom };
+        }
+      }
+    };
+
+    const order: NoteSide[] =
+      direction === 'LR' ? ['below', 'above'] : ['right', 'left'];
+
+    let chosen: { rect: Rect; side: NoteSide } | null = null;
+    for (const side of order) {
+      const rect = rectFor(side);
+      if (!occupied.some((o) => intersects(rect, o, NOTE_CLEAR))) {
+        chosen = { rect, side };
+        break;
+      }
+    }
+
+    if (!chosen) {
+      // Both sides blocked — push the default side outward past blockers.
+      const side = order[0]!;
+      let rect = rectFor(side);
+      const axisIsY = side === 'above' || side === 'below';
+      const outward = side === 'below' || side === 'right' ? 1 : -1;
+      for (let guard = 0; guard < 50; guard++) {
+        const blockers = occupied.filter((o) =>
+          intersects(rect, o, NOTE_CLEAR)
+        );
+        if (blockers.length === 0) break;
+        if (axisIsY && outward > 0) {
+          const top = Math.max(...blockers.map((b) => b.bottom)) + NOTE_CLEAR;
+          rect = { ...rect, top, bottom: top + noteH };
+        } else if (axisIsY) {
+          const bottom = Math.min(...blockers.map((b) => b.top)) - NOTE_CLEAR;
+          rect = { ...rect, bottom, top: bottom - noteH };
+        } else if (outward > 0) {
+          const left = Math.max(...blockers.map((b) => b.right)) + NOTE_CLEAR;
+          rect = { ...rect, left, right: left + noteW };
+        } else {
+          const right = Math.min(...blockers.map((b) => b.left)) - NOTE_CLEAR;
+          rect = { ...rect, right, left: right - noteW };
+        }
+      }
+      chosen = { rect, side };
+    }
+
+    occupied.push(chosen.rect);
+    placements.set(req.key, {
+      collapsed: false,
+      side: chosen.side,
+      x: chosen.rect.left - p.x,
+      y: chosen.rect.top - p.y,
+    });
+  }
+
+  return placements;
+}

package/src/utils/notes/resolve.ts

@@ -0,0 +1,88 @@
+// ============================================================
+// Generic diagram note — shared resolver
+// ============================================================
+
+import { makeDgmoError, suggest, type DgmoError } from '../../diagnostics';
+import { normalizeName } from '../name-normalize';
+import type { DiagramNote } from './model';
+
+/** Minimal node shape a chart must expose for note resolution. */
+export interface NoteTarget {
+  readonly id: string;
+  readonly label: string;
+}
+
+/**
+ * Resolve each note's `ref` to a concrete node id (matched by normalized
+ * label). Returns a map keyed by node id — one note per node, first wins.
+ * When `diagnostics` is passed, emits an `error` for an unknown ref (with a
+ * suggest), a `warning` when a ref is ambiguous across nodes, and a
+ * `warning` when a node already has a note. Never silently drops.
+ */
+export function resolveNotes<T extends NoteTarget>(
+  notes: readonly DiagramNote[],
+  targets: readonly T[],
+  diagnostics?: DgmoError[]
+): Map<string, DiagramNote> {
+  const byNodeId = new Map<string, DiagramNote>();
+  if (notes.length === 0) return byNodeId;
+
+  const byNormLabel = new Map<string, T[]>();
+  for (const t of targets) {
+    const key = normalizeName(t.label);
+    const arr = byNormLabel.get(key);
+    if (arr) arr.push(t);
+    else byNormLabel.set(key, [t]);
+  }
+
+  for (const note of notes) {
+    const matches = byNormLabel.get(normalizeName(note.ref));
+
+    if (!matches || matches.length === 0) {
+      if (diagnostics) {
+        const hint = suggest(
+          note.ref,
+          targets.map((t) => t.label)
+        );
+        diagnostics.push(
+          makeDgmoError(
+            note.lineNumber,
+            `Note references unknown node id "${note.ref}".${
+              hint ? ' ' + hint : ''
+            }`,
+            'error'
+          )
+        );
+      }
+      continue;
+    }
+
+    const target = matches[0]!;
+    if (matches.length > 1 && diagnostics) {
+      diagnostics.push(
+        makeDgmoError(
+          note.lineNumber,
+          `Note ref "${note.ref}" matches ${matches.length} nodes; attaching to the first.`,
+          'warning'
+        )
+      );
+    }
+
+    if (byNodeId.has(target.id)) {
+      if (diagnostics) {
+        diagnostics.push(
+          makeDgmoError(
+            note.lineNumber,
+            `Multiple notes on node "${target.label}"; keeping the first.`,
+            'warning'
+          )
+        );
+      }
+      continue;
+    }
+
+    byNodeId.set(target.id, note);
+  }
+
+  return byNodeId;
+}

package/src/utils/number-format.ts

@@ -0,0 +1,36 @@
+// Shared compact number formatting. Used by the map region-value labels and the
+// gradient legend's ramp ends so the two read identically (a region printing
+// `39.5M` lines up with a legend that ends at `40M`).
+
+/** Compact display of a numeric value:
+ *  - integers and |n| < 1000 print bare (non-integers to 1 decimal, matching the
+ *    legend's legacy ramp formatting): `0`, `3.2`, `999`, `42`.
+ *  - |n| >= 1000 uses magnitude suffixes to 1 significant fraction digit:
+ *    `1.1K`, `39.5M`, `2.3B`, `1.4T`.
+ *  Negatives keep their sign (`-39.5M`). */
+export function compactNumber(n: number): string {
+  if (!Number.isFinite(n)) return String(n);
+  const abs = Math.abs(n);
+  if (abs < 1000) {
+    return Number.isInteger(n) ? String(n) : String(Math.round(n * 10) / 10);
+  }
+  const sign = n < 0 ? '-' : '';
+  const units: ReadonlyArray<[number, string]> = [
+    [1e12, 'T'],
+    [1e9, 'B'],
+    [1e6, 'M'],
+    [1e3, 'K'],
+  ];
+  for (const [factor, suffix] of units) {
+    if (abs >= factor) {
+      // 1 fraction digit, but drop a trailing `.0` (39.0M → 39M).
+      const scaled = Math.round((abs / factor) * 10) / 10;
+      const body = Number.isInteger(scaled)
+        ? String(scaled)
+        : scaled.toFixed(1);
+      return `${sign}${body}${suffix}`;
+    }
+  }
+  // Unreachable (abs >= 1000 always matches the 1e3 unit), but keep TS happy.
+  return String(n);
+}

package/src/utils/parsing.ts

@@ -146,6 +146,7 @@ export const OPTION_NOCOLON_RE = /^([a-z][a-z0-9-]*)\s+(.+)$/i;
 export const GLOBAL_BOOLEANS: ReadonlySet<string> = new Set([
   'solid-fill',
   'no-title',
+  'no-notes',
 ]);
 
 /**
@@ -511,6 +512,46 @@ export function peelTrailingColorName(label: string): {
   };
 }
 
+/**
+ * Peel up to TWO trailing recognized color names from a label region — the
+ * shared value-ramp coloring convention (`<metric> <low?> <high?>`). Peels from
+ * the right, stops at the first non-color token, peels AT MOST 2, and NEVER
+ * reduces the label to empty (a 2nd peel that would empty the label is left as
+ * label text).
+ *
+ * Mapping (locked): one peeled color ⇒ `{ high }` only (today's neutral→hue
+ * meaning); two peeled ⇒ first(left) = `low`, second(right) = `high`.
+ * Order-respecting — NO sorting, NO "did-you-mean" intent detection.
+ *
+ * Shared by any value-ramp chart type (map `region-metric`, b&l `box-metric`,
+ * and future ramps). `peelTrailingColorName` (single-token) stays untouched for
+ * the non-ramp callers (d3, sitemap, cycle, …).
+ */
+export function peelRampColors(label: string): {
+  label: string;
+  low?: string;
+  high?: string;
+} {
+  // Peel a single trailing recognized color, but only if a token remains in
+  // front of it (a lone token is never peeled — that would empty the label).
+  const peelOne = (s: string): { rest: string; color?: string } => {
+    const idx = Math.max(s.lastIndexOf(' '), s.lastIndexOf('\t'));
+    if (idx < 0) return { rest: s };
+    const trailing = s.substring(idx + 1);
+    if (!RECOGNIZED_COLOR_SET.has(trailing)) return { rest: s };
+    return { rest: s.substring(0, idx).trimEnd(), color: trailing };
+  };
+  // High (rightmost) first.
+  const first = peelOne(label);
+  if (first.color === undefined) return { label };
+  // Low (second-from-right) — only if a non-empty label still remains after.
+  const second = peelOne(first.rest);
+  if (second.color === undefined) {
+    return { label: first.rest, high: first.color };
+  }
+  return { label: second.rest, low: second.color, high: first.color };
+}
+
 /** Error message for multiple pipes on a single line. */
 export const MULTIPLE_PIPE_ERROR =
   'Use a single "|" to start metadata, then separate items with commas.';

package/src/utils/reserved-key-registry.ts

@@ -63,6 +63,10 @@ export const SEQUENCE_REGISTRY: ReservedKeyRegistry = staticRegistry([
   'description',
   'role',
   'collapsed',
+  // Participant layout-order override (§2.2). Colon-keyed `position: N`
+  // replaced the legacy bare-keyword `position N` form — a stray bare
+  // `position N` now raises E_SEQUENCE_BARE_POSITION_REMOVED.
+  'position',
 ]);
 
 export const INFRA_REGISTRY: ReservedKeyRegistry = staticRegistry([