@diagrammo/dgmo 0.26.0 → 0.27.0

package/gallery/fixtures/map-tagged-legs.dgmo

@@ -0,0 +1,16 @@
+map Smuggler's Run
+
+tag Leg as l
+  Sail blue
+  March green
+  Row orange
+
+poi 20.05 -72.82 as tor label: Tortuga
+poi 23.13 -82.38 as hav label: Havana
+poi 18.02 -76.79 as cove label: Pirate's Cove
+poi 25.06 -77.35 as nas label: Nassau
+
+tor ~> hav l: Sail
+hav ~> cove l: Sail
+cove -> nas l: March
+nas ~> tor l: Row

package/gallery/fixtures/map-undirected-edges.dgmo

@@ -0,0 +1,12 @@
+map Sister Ports of the Spanish Main
+flow-metric Shared cargo runs
+
+poi Tortuga
+poi Port Royal
+poi Nassau
+poi Havana
+
+Tortuga -ferry- Port Royal value: 18
+Port Royal ~cable~ Nassau
+Nassau -- Havana
+Havana -ships-> Tortuga value: 30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {

package/src/advanced.ts

@@ -585,6 +585,7 @@ export type {
   BoundaryTopology,
   RegionName,
   RegionNames,
+  AirportData,
 } from './map/data/types';
 
 export type { RaciDragSource, RaciInteractionHandlers } from './raci';
@@ -728,18 +729,12 @@ export {
   contrastText,
   // Palette definitions
   nordPalette,
-  solarizedPalette,
   catppuccinPalette,
-  rosePinePalette,
-  gruvboxPalette,
   tokyoNightPalette,
-  oneDarkPalette,
   atlasPalette,
   blueprintPalette,
   slatePalette,
   tidewaterPalette,
-  draculaPalette,
-  monokaiPalette,
 } from './palettes';
 
 export type { PaletteConfig, PaletteColors } from './palettes';

package/src/auto/index.ts

@@ -46,7 +46,7 @@ declare const __DGMO_VERSION__: string;
 
 const DEFAULTS: Required<AutoConfig> = {
   theme: 'auto',
-  palette: 'nord',
+  palette: 'slate',
   showSource: true,
   showEditorLink: true,
 };

package/src/boxes-and-lines/layout.ts

@@ -10,6 +10,13 @@
 
 import ELK from 'elkjs/lib/elk.bundled.js';
 import type { ParsedBoxesAndLines, BLNode, BLGroup } from './types';
+import { measureText, wrapTextToWidth } from '../utils/text-measure';
+import {
+  resolveNotes,
+  buildPlacedNotes,
+  noteCanvasShift,
+  type PlacedNote,
+} from '../utils/notes';
 
 // ── Constants ──────────────────────────────────────────────
 const MARGIN = 40;
@@ -31,6 +38,11 @@ const MAX_DESC_LINES = 6;
 const MAX_LABEL_LINES = 3;
 const LABEL_LINE_HEIGHT = 1.3;
 const LABEL_PAD = 12;
+// Bottom value-row reserved on a DESCRIBED node under `show-values`: a thin
+// divider + a "Metric: value" footer line (replaces the old corner badge).
+const VALUE_ROW_FONT = 11;
+const VALUE_ROW_H =
+  SEPARATOR_GAP + VALUE_ROW_FONT * DESC_LINE_HEIGHT + DESC_PADDING;
 
 // ── Result types ───────────────────────────────────────────
 
@@ -40,6 +52,8 @@ export interface BLLayoutNode {
   readonly y: number;
   readonly width: number;
   readonly height: number;
+  /** A note floated beside this box (never moves the box). */
+  readonly note?: PlacedNote;
 }
 
 export interface BLLayoutEdge {
@@ -113,15 +127,14 @@ function estimateLabelLines(label: string, nodeWidth = NODE_WIDTH): number {
     if (!part) continue;
     words.push(...splitCamelCase(part));
   }
+  const maxTextWidth = nodeWidth - 24;
   for (let fontSize = 13; fontSize >= 9; fontSize--) {
-    const charWidth = fontSize * 0.6;
-    const maxChars = Math.floor((nodeWidth - 24) / charWidth);
-    if (maxChars < 2) continue;
+    if (maxTextWidth < measureText('MM', fontSize)) continue;
     let lines = 1;
     let current = '';
     for (const word of words) {
       const test = current ? `${current} ${word}` : word;
-      if (test.length <= maxChars) {
+      if (measureText(test, fontSize) <= maxTextWidth) {
         current = test;
       } else {
         lines++;
@@ -133,35 +146,31 @@ function estimateLabelLines(label: string, nodeWidth = NODE_WIDTH): number {
   return MAX_LABEL_LINES;
 }
 
-function computeNodeSize(node: BLNode): { width: number; height: number } {
+function computeNodeSize(
+  node: BLNode,
+  reserveValueRow: boolean
+): { width: number; height: number } {
   if (!node.description || node.description.length === 0) {
     return { width: NODE_WIDTH, height: NODE_HEIGHT };
   }
   const w = DESC_NODE_WIDTH;
   const labelLines = estimateLabelLines(node.label, w);
   const labelHeight = labelLines * 13 * LABEL_LINE_HEIGHT + LABEL_PAD;
-  const charsPerLine = Math.floor((w - 24) / (DESC_FONT_SIZE * 0.6));
+  const maxTextWidth = w - 24;
   let totalRenderedLines = 0;
   for (const line of node.description) {
-    if (line.length <= charsPerLine) {
+    if (measureText(line, DESC_FONT_SIZE) <= maxTextWidth) {
       totalRenderedLines += 1;
     } else {
-      const words = line.split(/\s+/);
-      let current = '';
-      let lineCount = 0;
-      for (const word of words) {
-        const fitted =
-          word.length > charsPerLine ? word.slice(0, charsPerLine) : word;
-        const test = current ? `${current} ${fitted}` : fitted;
-        if (test.length <= charsPerLine) {
-          current = test;
-        } else {
-          if (current) lineCount++;
-          current = fitted;
+      // Hard-break long words to match the renderer's slicing behaviour.
+      totalRenderedLines += wrapTextToWidth(
+        line,
+        DESC_FONT_SIZE,
+        maxTextWidth,
+        {
+          hardBreak: true,
         }
-      }
-      if (current) lineCount++;
-      totalRenderedLines += lineCount;
+      ).length;
     }
   }
   totalRenderedLines = Math.min(totalRenderedLines, MAX_DESC_LINES);
@@ -172,7 +181,8 @@ function computeNodeSize(node: BLNode): { width: number; height: number } {
     SEPARATOR_GAP +
     DESC_PADDING +
     descriptionHeight +
-    DESC_PADDING;
+    DESC_PADDING +
+    (reserveValueRow ? VALUE_ROW_H : 0);
   return { width: w, height: Math.max(NODE_HEIGHT, totalHeight) };
 }
 
@@ -394,7 +404,10 @@ export async function layoutBoxesAndLines(
     collapsedChildCounts: Map<string, number>;
     originalGroups: readonly BLGroup[];
   },
-  layoutOptions?: { hideDescriptions?: boolean }
+  layoutOptions?: {
+    hideDescriptions?: boolean;
+    collapsedNotes?: ReadonlySet<number>;
+  }
 ): Promise<BLLayoutResult> {
   const hideDescriptions = layoutOptions?.hideDescriptions ?? false;
   const direction = parsed.direction === 'TB' ? 'DOWN' : 'RIGHT';
@@ -423,7 +436,7 @@ export async function layoutBoxesAndLines(
   for (const node of parsed.nodes) {
     const size = hideDescriptions
       ? { width: NODE_WIDTH, height: NODE_HEIGHT }
-      : computeNodeSize(node);
+      : computeNodeSize(node, parsed.showValues === true);
     nodeSizes.set(node.label, size);
     if (!hideDescriptions && node.description && node.description.length > 0) {
       maxDescHeight = Math.max(maxDescHeight, size.height);
@@ -728,5 +741,112 @@ export async function layoutBoxesAndLines(
       bestScore = s;
     }
   }
-  return best;
+
+  return attachNotes(best, parsed, layoutOptions?.collapsedNotes);
+}
+
+/**
+ * Float notes beside their boxes on the chosen layout (runs after variant
+ * selection — notes don't affect scoring). `no-notes` opts out. A note placed
+ * above/left can land off-canvas, so the whole layout is shifted to fit.
+ * Un-annotated diagrams are returned unchanged (min coords stay ≥ 0).
+ */
+function attachNotes(
+  layout: BLLayoutResult,
+  parsed: ParsedBoxesAndLines,
+  collapsedNotes?: ReadonlySet<number>
+): BLLayoutResult {
+  const notesSuppressed = parsed.options?.['no-notes'] === 'on';
+  const noteByNode =
+    notesSuppressed || !parsed.notes
+      ? new Map()
+      : resolveNotes(
+          parsed.notes,
+          parsed.nodes.map((n) => ({ id: n.label, label: n.label }))
+        );
+  if (noteByNode.size === 0) return layout;
+
+  const placed = buildPlacedNotes(
+    layout.nodes.map((n) => ({
+      id: n.label,
+      x: n.x,
+      y: n.y,
+      width: n.width,
+      height: n.height,
+    })),
+    noteByNode,
+    parsed.direction === 'TB' ? 'TB' : 'LR',
+    collapsedNotes
+  );
+  const notedNodes: BLLayoutNode[] = layout.nodes.map((n) => {
+    const note = placed.get(n.label);
+    return note ? { ...n, note } : n;
+  });
+
+  // Content bbox over nodes (+ their floated notes) and groups — matches the
+  // prior max-extent computation plus the notes.
+  let bbMinX = Infinity;
+  let bbMinY = Infinity;
+  let bbMaxX = -Infinity;
+  let bbMaxY = -Infinity;
+  const extend = (l: number, t: number, r: number, b: number): void => {
+    if (l < bbMinX) bbMinX = l;
+    if (t < bbMinY) bbMinY = t;
+    if (r > bbMaxX) bbMaxX = r;
+    if (b > bbMaxY) bbMaxY = b;
+  };
+  for (const n of notedNodes) {
+    extend(
+      n.x - n.width / 2,
+      n.y - n.height / 2,
+      n.x + n.width / 2,
+      n.y + n.height / 2
+    );
+    if (n.note && !n.note.collapsed) {
+      extend(
+        n.x + n.note.x,
+        n.y + n.note.y,
+        n.x + n.note.x + n.note.width,
+        n.y + n.note.y + n.note.height
+      );
+    }
+  }
+  for (const grp of layout.groups) {
+    extend(
+      grp.x - grp.width / 2,
+      grp.y - grp.height / 2,
+      grp.x + grp.width / 2,
+      grp.y + grp.height / 2
+    );
+  }
+  if (!Number.isFinite(bbMinX)) return { ...layout, nodes: notedNodes };
+
+  const { shiftX, shiftY } = noteCanvasShift(bbMinX, bbMinY);
+  const shifted = shiftX !== 0 || shiftY !== 0;
+  const finalNodes = shifted
+    ? notedNodes.map((n) => ({ ...n, x: n.x + shiftX, y: n.y + shiftY }))
+    : notedNodes;
+  const finalEdges = shifted
+    ? layout.edges.map((e) => ({
+        ...e,
+        points: e.points.map((pt) => ({ x: pt.x + shiftX, y: pt.y + shiftY })),
+        ...(e.labelX !== undefined && { labelX: e.labelX + shiftX }),
+        ...(e.labelY !== undefined && { labelY: e.labelY + shiftY }),
+      }))
+    : layout.edges;
+  const finalGroups = shifted
+    ? layout.groups.map((grp) => ({
+        ...grp,
+        x: grp.x + shiftX,
+        y: grp.y + shiftY,
+      }))
+    : layout.groups;
+
+  return {
+    nodes: finalNodes,
+    edges: finalEdges,
+    groups: finalGroups,
+    width: bbMaxX + shiftX + MARGIN,
+    height: bbMaxY + shiftY + MARGIN,
+  };
 }

package/src/boxes-and-lines/parser.ts

@@ -26,7 +26,7 @@ import {
   extractColor,
   parseFirstLine,
   OPTION_NOCOLON_RE,
-  peelTrailingColorName,
+  peelRampColors,
   splitNameAndMeta,
   tryParseSharedOption,
   warnUnknownMetaKeys,
@@ -35,6 +35,8 @@ import {
   BOXES_AND_LINES_REGISTRY,
   withTagAliases,
 } from '../utils/reserved-key-registry';
+import { tryCollectNote, resolveNotes, type DiagramNote } from '../utils/notes';
+import type { PaletteColors } from '../palettes';
 
 const MAX_GROUP_DEPTH = 2;
 
@@ -113,8 +115,12 @@ type MutBLGroup = Omit<Writable<BLGroup>, 'metadata' | 'children'> & {
   children: string[];
 };
 
-export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
+export function parseBoxesAndLines(
+  content: string,
+  palette?: PaletteColors
+): ParsedBoxesAndLines {
   const options: Record<string, string> = {};
+  const notes: DiagramNote[] = [];
   const initialHiddenTagValues = new Map<string, Set<string>>();
   const nodes: MutBLNode[] = [];
   const edges: MutBLEdge[] = [];
@@ -305,11 +311,10 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
         const metricMatch = trimmed.match(/^box-metric\s+(.+)$/i);
         if (metricMatch) {
           // Regex capture group present after successful match.
-          const { label, colorName } = peelTrailingColorName(
-            metricMatch[1]!.trim()
-          );
+          const { label, low, high } = peelRampColors(metricMatch[1]!.trim());
           result.boxMetric = label;
-          if (colorName !== undefined) result.boxMetricColor = colorName;
+          if (high !== undefined) result.boxMetricColor = high;
+          if (low !== undefined) result.boxMetricLowColor = low;
           continue;
         }
         if (/^show-values$/i.test(trimmed)) {
@@ -336,6 +341,24 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
       }
     }
 
+    // Note annotation (top-level): `note <Box> [inline body]` + an optional
+    // indented body. Checked before tag/group/node/edge matching so a note is
+    // never mistaken for a box; gated to indent 0. `note -> X` is excluded.
+    if (indent === 0) {
+      const noteResult = tryCollectNote(
+        lines,
+        i,
+        indent,
+        palette,
+        result.diagnostics
+      );
+      if (noteResult) {
+        if (noteResult.note) notes.push(noteResult.note);
+        i = noteResult.lastIndex;
+        continue;
+      }
+    }
+
     // Tag group heading — must be checked BEFORE group/node/edge matching
     const tagBlockMatch = matchTagBlockHeading(trimmed);
     if (tagBlockMatch && indent === 0) {
@@ -721,6 +744,17 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
   }
   result.edges = validEdges;
 
+  // Resolve note refs against box labels (forward refs OK). The id→note
+  // binding is recomputed in layout; this pass surfaces diagnostics.
+  if (notes.length > 0) {
+    result.notes = notes;
+    resolveNotes(
+      notes,
+      result.nodes.map((n) => ({ id: n.label, label: n.label })),
+      result.diagnostics
+    );
+  }
+
   // Post-parse: inject default tag metadata and validate tag values
   if (result.tagGroups.length > 0) {
     injectDefaultTagMetadata(result.nodes, result.tagGroups);
@@ -1007,8 +1041,9 @@ function parseEdgeLine(
     };
   }
 
-  // Check for labeled arrow: `Source -label-> Target`
-  const labeledMatch = trimmed.match(/^(.+?)\s+-(.+)->\s*(.+)$/);
+  // Check for labeled arrow: `Source -label-> Target` (label lazy → split
+  // at the first arrow, consistent with the other parsers).
+  const labeledMatch = trimmed.match(/^(.+?)\s+-(.+?)->\s*(.+)$/);
   if (labeledMatch) {
     // Regex capture groups present after successful match.
     const rawSource = labeledMatch[1]!.trim();