@diagrammo/dgmo 0.25.5 → 0.27.0

package/src/raci/renderer.ts

@@ -43,6 +43,11 @@ import type {
 import { allTasks } from './parser';
 import { VARIANTS } from './variants';
 import { ScaleContext } from '../utils/scaling';
+import {
+  measureText,
+  truncateText,
+  wrapTextToWidth,
+} from '../utils/text-measure';
 
 /**
  * Group `parsed.diagnostics` per task, so the renderer can paint a
@@ -253,7 +258,8 @@ const ROLE_HEADER_FONT = 12;
 const PHASE_FONT = 13;
 
 // Cell-fill tint percentage of the marker color over surface bg.
-const TINT_PCT = 28;
+// 25 = the canonical `shapeFill` tint used by every other chart type.
+const TINT_PCT = 25;
 /**
  * Marker rect stroke + radius — matches the codebase's node styling
  * convention (flowchart `NODE_STROKE_WIDTH = 1.5`, kanban
@@ -515,6 +521,12 @@ export function renderRaci(
   const colBottomY = cursorY + sColumnBottomPad;
   const totalHeight = colBottomY + sVMargin;
 
+  // Export renders a fixed canvas (e.g. 1200×800); a short matrix would
+  // otherwise reserve a tall band of dead space below the last row. Size the
+  // export canvas to the content height. The interactive preview keeps the
+  // `max(pane, content)` behaviour so a short matrix still fills the pane.
+  const svgHeight = exportDims ? totalHeight : Math.max(height, totalHeight);
+
   // ── SVG root ───────────────────────────────────────────────
 
   const svg = d3Selection
@@ -522,8 +534,8 @@ export function renderRaci(
     .append('svg')
     .attr('xmlns', 'http://www.w3.org/2000/svg')
     .attr('width', width)
-    .attr('height', Math.max(height, totalHeight))
-    .attr('viewBox', `0 0 ${width} ${Math.max(height, totalHeight)}`)
+    .attr('height', svgHeight)
+    .attr('viewBox', `0 0 ${width} ${svgHeight}`)
     .attr('preserveAspectRatio', 'xMidYMin meet')
     .attr('font-family', FONT_FAMILY)
     .style('background', 'transparent');
@@ -544,20 +556,21 @@ export function renderRaci(
 
   // Size full-mode chips to actually fit the longest label without truncation.
   // chip = 4 pad + 24 slab + 8 gap + label + 8 right pad.
-  const longestLabel = legendMarkers.reduce(
-    (n, m) => Math.max(n, (variantLabels[m] ?? '').length),
+  const longestLabelPx = legendMarkers.reduce(
+    (n, m) =>
+      Math.max(n, measureText(variantLabels[m] ?? '', sLegendLabelFont)),
     0
   );
   const fullChipW = Math.max(
     sLegendChipLabelMin,
-    Math.ceil(4 + 24 + 8 + longestLabel * sLegendLabelFont * 0.6 + 8)
+    Math.ceil(4 + 24 + 8 + longestLabelPx + 8)
   );
   const fullLegendW = numChips * fullChipW + chipGapTotal;
   const letterLegendW = numChips * sLegendLetterChipW + chipGapTotal;
 
-  // Estimate title pixel width with the same heuristic used in truncateForWidth.
+  // Estimate title pixel width using the shared glyph measurer.
   const titleEstW =
-    parsed.title && !hideTitle ? parsed.title.length * sTitleFontSize * 0.6 : 0;
+    parsed.title && !hideTitle ? measureText(parsed.title, sTitleFontSize) : 0;
 
   // Pick legend mode: full chips if everything fits, else letter-only.
   // If even letters won't fit beside the title, the title is truncated below.
@@ -590,7 +603,7 @@ export function renderRaci(
       .attr('font-size', sTitleFontSize)
       .attr('font-weight', TITLE_FONT_WEIGHT)
       .attr('fill', palette.text)
-      .text(truncateForWidth(parsed.title, titleMaxW, sTitleFontSize));
+      .text(truncateText(parsed.title, sTitleFontSize, titleMaxW));
   }
 
   // Legend — right-aligned in the same row.
@@ -708,10 +721,10 @@ export function renderRaci(
       .attr('font-weight', 600)
       .attr('fill', palette.text)
       .text(
-        truncateForWidth(
+        truncateText(
           parsed.roleDisplayNames[i] ?? '',
-          roleColW - 2 * sCellPad,
-          sRoleHeaderFont
+          sRoleHeaderFont,
+          roleColW - 2 * sCellPad
         )
       );
   });
@@ -925,7 +938,7 @@ function renderLegend(
     if (mode === 'letters') {
       // Compact: a single colored pill with just the marker letter.
       // The full label moves to a native tooltip so hover still teaches it.
-      const fill = solid ? rawColor : mix(rawColor, surfaceBg, 28);
+      const fill = solid ? rawColor : mix(rawColor, surfaceBg, TINT_PCT);
       const stroke = solid ? mix(rawColor, surfaceBg, 70) : rawColor;
       chipG
         .append('rect')
@@ -960,7 +973,7 @@ function renderLegend(
     }
 
     // Full mode: bordered chip with a letter slab on the left and label text.
-    const fill = solid ? rawColor : mix(rawColor, surfaceBg, 28);
+    const fill = solid ? rawColor : mix(rawColor, surfaceBg, TINT_PCT);
     const stroke = mix(rawColor, surfaceBg, 70);
 
     chipG
@@ -1020,10 +1033,10 @@ function renderLegend(
       .attr('font-weight', 600)
       .attr('fill', palette.text)
       .text(
-        truncateForWidth(
+        truncateText(
           labelText,
-          chipW - slabW - slabPad * 2 - 12,
-          sLegendLabelFont
+          sLegendLabelFont,
+          chipW - slabW - slabPad * 2 - 12
         )
       );
   });
@@ -1117,7 +1130,7 @@ function renderPhaseBar(
     // can see at a glance what's in the rolled-up phase.
     const taskCount = phase.tasks.length;
     if (taskCount > 0) {
-      const labelTextWidth = phase.displayName.length * sPhaseFont * 0.6;
+      const labelTextWidth = measureText(phase.displayName, sPhaseFont);
       phaseG
         .append('text')
         .attr('x', x + 26 + labelTextWidth + 10)
@@ -1166,7 +1179,7 @@ function renderPhaseBar(
         // corner radius. Stroke width is a touch thinner than
         // NODE_STROKE_WIDTH because at the smaller summary scale the
         // full 1.5 reads as too heavy.
-        const fill = solid ? rawColor : mix(rawColor, surfaceBg, 28);
+        const fill = solid ? rawColor : mix(rawColor, surfaceBg, TINT_PCT);
         const stroke = solid ? mix(rawColor, surfaceBg, 70) : rawColor;
         const chipG = phaseG.append('g').attr('class', 'raci-phase-summary');
         chipG
@@ -1452,7 +1465,7 @@ function renderTaskRow(
       // ("Responsible") instead of the bare letter. Same primitive as the
       // legend chip, so cells and legend read as the same UI element.
       const fullLabel = variantLabels[m] ?? m;
-      const labelPx = fullLabel.length * sLegendLabelFont * 0.6;
+      const labelPx = measureText(fullLabel, sLegendLabelFont);
       const showFullLabel = labelPx + 16 <= sliceW;
       const textContent = showFullLabel ? fullLabel : m;
       const textFont = showFullLabel ? sLegendLabelFont : sMarkerFont;
@@ -1505,45 +1518,6 @@ function renderTaskRow(
 
 // ── Helpers ──────────────────────────────────────────────────
 
-/**
- * Greedy word-wrap to a per-line character cap. Whitespace runs that
- * happen to fall at a wrap point are dropped (no leading-space lines).
- * Words longer than the cap are hard-split so the output never exceeds.
- */
-function wordWrap(s: string, charsPerLine: number): string[] {
-  if (charsPerLine <= 0 || s.length <= charsPerLine) return [s];
-  const out: string[] = [];
-  const tokens = s.split(/(\s+)/);
-  let cur = '';
-  for (const tok of tokens) {
-    if (!tok) continue;
-    const isSpace = /^\s+$/.test(tok);
-    if (cur.length + tok.length <= charsPerLine) {
-      cur += tok;
-      continue;
-    }
-    if (cur.trimEnd().length > 0) out.push(cur.trimEnd());
-    if (!isSpace && tok.length > charsPerLine) {
-      let chunk = tok;
-      while (chunk.length > charsPerLine) {
-        out.push(chunk.slice(0, charsPerLine));
-        chunk = chunk.slice(charsPerLine);
-      }
-      cur = chunk;
-    } else {
-      cur = isSpace ? '' : tok;
-    }
-  }
-  if (cur.trimEnd().length > 0) out.push(cur.trimEnd());
-  return out.length > 0 ? out : [''];
-}
-
-function wrapText(s: string, maxPx: number, fontSize: number): string[] {
-  const charPx = fontSize * 0.6;
-  const cap = Math.max(8, Math.floor(maxPx / charPx));
-  return wordWrap(s, cap);
-}
-
 /**
  * Wrapped text content for a task row plus the height that fits it.
  * Pre-computed once per task and reused by both the y-cursor layout
@@ -1575,13 +1549,17 @@ function prepareRowContent(
   sStackTopGap = STACK_TOP_GAP,
   sViolationLineHeight = VIOLATION_LINE_HEIGHT
 ): RowContent {
-  const nameLines = wrapText(task.displayName, labelMaxW, sLabelFont);
+  const nameLines = wrapTextToWidth(task.displayName, sLabelFont, labelMaxW, {
+    hardBreak: true,
+  });
   const description = task.description?.trim() ?? '';
   const descLines =
     description.length > 0
       ? description
           .split('\n')
-          .flatMap((line) => wrapText(line, labelMaxW, sDescFont))
+          .flatMap((line) =>
+            wrapTextToWidth(line, sDescFont, labelMaxW, { hardBreak: true })
+          )
       : [];
   const violations: RowContent['violations'] = [];
   if (bucket) {
@@ -1595,7 +1573,9 @@ function prepareRowContent(
           severity,
           sourceLine: e.line,
           text,
-          lines: wrapText(text, labelMaxW, sLabelFont - 2),
+          lines: wrapTextToWidth(text, sLabelFont - 2, labelMaxW, {
+            hardBreak: true,
+          }),
         });
       }
     };
@@ -1621,14 +1601,6 @@ function prepareRowContent(
   return { nameLines, descLines, violations, rowHeight };
 }
 
-function truncateForWidth(s: string, maxPx: number, fontSize: number): string {
-  // Conservative: 0.6 em per char for sans-serif at this weight.
-  const charPx = fontSize * 0.6;
-  const cap = Math.max(3, Math.floor(maxPx / charPx));
-  if (s.length <= cap) return s;
-  return s.substring(0, cap - 1) + '…';
-}
-
 /**
  * Split a diagnostic message at single-quoted spans so the renderer can
  * paint the quoted name (role / task) as a bold tspan with no quotes.

package/src/render.ts

@@ -130,7 +130,7 @@ export async function render(
   }
 ): Promise<{ svg: string; diagnostics: DgmoError[] }> {
   const theme = options?.theme ?? 'light';
-  const paletteName = options?.palette ?? 'nord';
+  const paletteName = options?.palette ?? 'slate';
 
   const paletteColors =
     getPalette(paletteName)[theme === 'dark' ? 'dark' : 'light'];

package/src/ring/renderer.ts

@@ -16,6 +16,7 @@ import {
 } from '../palettes/color-utils';
 import { resolveColor } from '../colors';
 import { renderInlineText } from '../utils/inline-markdown';
+import { CHAR_WIDTH_RATIO } from '../utils/text-measure';
 import {
   wrapDescriptionLines,
   type WrappedDescLine,
@@ -41,8 +42,6 @@ const DESC_GAP = 28;
 const DESC_ACCENT_WIDTH = 3;
 /** Gap between accent bar and description text. */
 const DESC_ACCENT_GAP = 12;
-/** Approximate ratio of average glyph width to font size (sans-serif). */
-const CHAR_WIDTH_RATIO = 0.55;
 /** Pixel offset between bullet glyph column and body-text column. */
 const BULLET_BODY_INDENT = 10;
 /** Outer-edge stroke width per ring (Decision 14 — adjacent-ring contrast). */

package/src/sequence/parser.ts

@@ -5,6 +5,7 @@
 import { inferParticipantType } from './participant-inference';
 import type { Brand, Writable } from '../utils/brand';
 import type { DgmoError } from '../diagnostics';
+import type { PaletteColors } from '../palettes/types';
 import {
   akaRemovedMessage,
   formatDgmoError,
@@ -14,6 +15,7 @@ import {
   nameMergedMessage,
   participantTypeRemovedMessage,
   pipeOperatorRemovedMessage,
+  sequenceBarePositionRemovedMessage,
   suggest,
 } from '../diagnostics';
 import { normalizeName, displayName } from '../utils/name-normalize';
@@ -245,11 +247,14 @@ export interface ParsedSequenceDgmo {
 // "Name is a type" pattern — e.g. "Auth Server is a database"
 // Participant names may contain spaces; [^:]+? stops at colons so that
 // note lines like "note right of A: this is an actor" are not falsely matched.
-// Remainder after type is parsed separately for `position N` modifier.
+// Remainder after type carries the optional `as <alias>` modifier.
 const IS_A_PATTERN = /^([^:]+?)\s+is\s+an?\s+(\w+)(?:\s+(.+))?$/i;
 
-// Standalone "Name position N" pattern — e.g. "DB position -1"
-const POSITION_ONLY_PATTERN = /^([^:]+?)\s+position\s+(-?\d+)$/i;
+// Legacy bare-keyword "Name position N" detector — e.g. "DB position -1".
+// Position is now colon-keyed metadata (`position: N`, §2.2); a surviving
+// bare `position N` raises E_SEQUENCE_BARE_POSITION_REMOVED. Group 1 is the
+// participant name (so it can still register), group 2 the offending number.
+const BARE_POSITION_PATTERN = /^([^:]+?)\s+position\s+(-?\d+)$/i;
 
 // Colored participant declaration — e.g. "Tapin2(green)", "API(blue)"
 // Scoped to recognized 11-name palette colors only (§1.5) so legitimate
@@ -488,7 +493,10 @@ function resolveParticipantAndText(
 /**
  * Parse a .dgmo file with `chart: sequence` into a structured representation.
  */
-export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
+export function parseSequenceDgmo(
+  content: string,
+  palette?: PaletteColors
+): ParsedSequenceDgmo {
   // Diagram-level options accumulator (Readonly<Record<...>> on the public
   // type; mutated locally during parse and assigned back via `result.options`).
   const optionsAccumulator: Record<string, string> = {};
@@ -637,7 +645,11 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       type: extras?.type ?? inferParticipantType(name),
       lineNumber,
       ...(extras?.position !== undefined ? { position: extras.position } : {}),
-      ...(extras?.metadata ? { metadata: extras.metadata } : {}),
+      // takePosition() may have emptied the metadata record (position was
+      // its only key) — don't attach an empty object.
+      ...(extras?.metadata && Object.keys(extras.metadata).length > 0
+        ? { metadata: extras.metadata }
+        : {}),
     });
     return trimmed;
   };
@@ -674,7 +686,7 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
   const splitPipe = (
     text: string,
     ln?: number
-  ): { core: string; meta?: Record<string, string> } => {
+  ): { core: string; meta?: Record<string, string>; alias?: string } => {
     const idx = text.indexOf('|');
     if (idx >= 0) {
       if (ln !== undefined) {
@@ -709,11 +721,41 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       );
     }
     if (Object.keys(split.meta).length > 0) {
-      return { core: split.name, meta: split.meta };
+      // splitNameAndMeta peels a trailing `as <alias>` off the name region
+      // when same-line metadata is present (the alias must precede the meta,
+      // which runs to EOL). Propagate it so callers can register the alias —
+      // the no-meta branch below leaves `as <alias>` in `core` for the
+      // caller's own peeling.
+      return {
+        core: split.name,
+        meta: split.meta,
+        ...(split.alias !== undefined && { alias: split.alias }),
+      };
     }
     return { core: text };
   };
 
+  /**
+   * Pull the layout-order `position:` key out of a participant's
+   * parsed metadata (§2.2). Position is a layout directive, not display
+   * metadata, so it is *removed* from the record after extraction. A
+   * non-integer value raises an error and yields no position.
+   */
+  const takePosition = (
+    meta: Record<string, string> | undefined,
+    ln: number
+  ): number | undefined => {
+    if (meta?.['position'] === undefined) return undefined;
+    const raw = meta['position'];
+    delete meta['position'];
+    const n = parseInt(raw, 10);
+    if (!/^-?\d+$/.test(raw.trim()) || Number.isNaN(n)) {
+      pushError(ln, `'position: ${raw}' must be an integer slot index`);
+      return undefined;
+    }
+    return n;
+  };
+
   // Block parsing state — blocks are built mutably during parse, then
   // assigned back into the readonly-typed `ParsedSequenceDgmo`.
   const blockStack: {
@@ -906,7 +948,7 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       const { text: cleanEntry, isDefault } = stripDefaultModifier(trimmed);
       const { label, color } = extractColor(
         cleanEntry,
-        undefined,
+        palette,
         result.diagnostics,
         lineNumber
       );
@@ -1070,7 +1112,11 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     // Handling makes aliasing unnecessary because forgiving normalization
     // handles casing/whitespace differences automatically.
     // Skip lines starting with 'note' — handled by note parsing below.
-    const { core: isACore, meta: isAMeta } = splitPipe(trimmed, lineNumber);
+    const {
+      core: isACore,
+      meta: isAMeta,
+      alias: isAAlias,
+    } = splitPipe(trimmed, lineNumber);
     const isAMatch = !/^note(\s|$)/i.test(trimmed)
       ? isACore.match(IS_A_PATTERN)
       : null;
@@ -1115,11 +1161,14 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
         continue;
       }
 
-      // TD-18: extract trailing `as <alias>` from the remainder and
-      // register it. Order on the line is `Name is a TYPE [position N] as <alias>`.
-      // The leading `(.*?)\s*\b` allows the remainder to be just
-      // `as <alias>` (empty prefix) — the canonical example writes
-      // `Alice is an actor as a` where the entire remainder is `as a`.
+      // TD-18: extract trailing `as <alias>` and register it. Order on the
+      // line is `Name is a TYPE as <alias> [position: N]`. When same-line
+      // metadata is present, splitPipe already peeled the alias (it must
+      // precede the metadata) and handed it back as `isAAlias`; otherwise
+      // the alias is still in `remainder` for us to peel here.
+      if (isAAlias !== undefined) {
+        nameAliasMap.set(isAAlias, id);
+      }
       const asInRemainder = remainder.match(
         /^(.*?)\s*\bas\s+([A-Za-z][A-Za-z0-9_]{0,11})\s*$/
       );
@@ -1129,9 +1178,21 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
         remainder = asInRemainder[1]!.trim();
       }
 
-      const posMatch = remainder.match(/\bposition\s+(-?\d+)/i);
-      // Capture group 1 guaranteed present after successful match.
-      const position = posMatch ? parseInt(posMatch[1]!, 10) : undefined;
+      // Position is colon-keyed metadata (§2.2) — pull it from the parsed
+      // meta. A bare `position N` surviving in the remainder is the retired
+      // form: flag it and drop the token (participant still registers).
+      const position = takePosition(isAMeta, lineNumber);
+      const baretail = remainder.match(/^position\s+(-?\d+)$/i);
+      if (baretail) {
+        result.diagnostics.push(
+          makeDgmoError(
+            lineNumber,
+            sequenceBarePositionRemovedMessage(baretail[1]!),
+            'error',
+            METADATA_DIAGNOSTIC_CODES.SEQUENCE_BARE_POSITION_REMOVED
+          )
+        );
+      }
 
       // Avoid duplicate participant declarations
       const key = addParticipant(id, lineNumber, {
@@ -1157,17 +1218,26 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       continue;
     }
 
-    // Parse standalone "Name position N" (no "is a" type)
+    // Reject the retired standalone bare-keyword "Name position N"
+    // (no "is a" type). Position is now colon-keyed `position: N` (§2.2),
+    // which flows through the bare-participant path below. The participant
+    // still registers (without an order override) so message refs resolve.
     const { core: posCore, meta: posMeta } = splitPipe(trimmed, lineNumber);
-    const posOnlyMatch = posCore.match(POSITION_ONLY_PATTERN);
+    const posOnlyMatch = posCore.match(BARE_POSITION_PATTERN);
     if (posOnlyMatch) {
       contentStarted = true;
       // Capture groups 1 and 2 guaranteed present after successful match.
       const id = posOnlyMatch[1]!;
-      const position = parseInt(posOnlyMatch[2]!, 10);
+      result.diagnostics.push(
+        makeDgmoError(
+          lineNumber,
+          sequenceBarePositionRemovedMessage(posOnlyMatch[2]!),
+          'error',
+          METADATA_DIAGNOSTIC_CODES.SEQUENCE_BARE_POSITION_REMOVED
+        )
+      );
 
       const key = addParticipant(id, lineNumber, {
-        position,
         ...(posMeta !== undefined && { metadata: posMeta }),
       });
       // Track group membership
@@ -1222,7 +1292,11 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     // Bare participant name — either inside an active group (indented) or top-level declaration
     // Supports pipe metadata: "  API | c: Gateway" or "Tapin2 | l:Park"
     {
-      const { core: bareCore, meta: bareMeta } = splitPipe(trimmed, lineNumber);
+      const {
+        core: bareCore,
+        meta: bareMeta,
+        alias: bareAlias,
+      } = splitPipe(trimmed, lineNumber);
       const inGroup = activeGroup && measureIndent(raw) > 0;
       if (
         /^\S+$/.test(bareCore) &&
@@ -1231,7 +1305,11 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       ) {
         contentStarted = true;
         const id = bareCore;
+        if (bareAlias !== undefined) nameAliasMap.set(bareAlias, id);
+        // Colon-keyed `position: N` (§2.2) arrives as metadata here.
+        const position = takePosition(bareMeta, lineNumber);
         const key = addParticipant(id, lineNumber, {
+          ...(position !== undefined && { position }),
           ...(bareMeta !== undefined && { metadata: bareMeta }),
         });
         if (activeGroup && !activeGroup.participantIds.includes(key)) {