@diagrammo/dgmo 0.8.18 → 0.8.20

package/src/utils/arrows.ts

@@ -5,6 +5,24 @@
 // Labeled arrow syntax (always left-to-right):
 //   Sync:  `-label->`
 //   Async: `~label~>`
+//
+// In-arrow label character-set contract (see docs/dgmo-language-spec.md
+// §"In-Arrow Message Labels"):
+//   - Allowed: any codepoint except the forbidden substrings and forbidden
+//     control characters below.
+//   - Forbidden substrings: "->", "~>" (arrow-token lookalikes inside labels).
+//     Use the post-colon form for labels that need these symbols:
+//       `A -> B: uses -> to chain`
+//   - Forbidden characters: C0 control chars U+0000–U+001F EXCEPT U+0009 (tab),
+//     and U+007F (DEL).
+//   - Whitespace: leading/trailing trimmed; internal runs (incl. tab, NBSP,
+//     ZWSP) preserved — never collapsed.
+//   - Plain text only: no markdown interpretation. `*`, `_`, backticks,
+//     `[`, `]`, `{`, `}` are literal characters.
+
+import type { DgmoError } from '../diagnostics';
+import { makeDgmoError } from '../diagnostics';
+import { RECOGNIZED_COLOR_NAMES } from '../colors';
 
 interface ParsedArrow {
   from: string;
@@ -13,6 +31,160 @@ interface ParsedArrow {
   async: boolean;
 }
 
+// ============================================================
+// Diagnostic codes (TD-16)
+// ============================================================
+
+/**
+ * Stable diagnostic codes for in-arrow label parsing errors.
+ *
+ * **Active codes** — emitted by the parser pipeline today:
+ *   - `ARROW_SUBSTRING_IN_LABEL` (TD-13)
+ *   - `CONTROL_CHAR_IN_LABEL` (TD-14)
+ *
+ * **Reserved codes** — declared but NOT currently emitted. These are
+ * placeholders for future tightening of the arrow-tokenization rules
+ * described in TD-9. Today's chart parsers catch these cases through
+ * their own regex machinery with different diagnostics. A follow-up
+ * spec that introduces a dedicated tokenizer can start emitting them
+ * without changing the public code shape:
+ *   - `TRAILING_ARROW_TEXT` — extra `->`/`~>` after the primary arrow
+ *   - `MIXED_ARROW_DELIMITERS` — opening delim type doesn't match arrow
+ *
+ * See `docs/dgmo-language-spec-decisions.md` → TD-16 for the rationale.
+ */
+export const ARROW_DIAGNOSTIC_CODES = {
+  /** Active: label contains `->` or `~>` substring (TD-13). */
+  ARROW_SUBSTRING_IN_LABEL: 'E_ARROW_SUBSTRING_IN_LABEL',
+  /** Active: label contains a forbidden control character (TD-14). */
+  CONTROL_CHAR_IN_LABEL: 'E_CONTROL_CHAR_IN_LABEL',
+  /** Reserved: not currently emitted by any parser. See JSDoc above. */
+  TRAILING_ARROW_TEXT: 'E_TRAILING_ARROW_TEXT',
+  /** Reserved: not currently emitted by any parser. See JSDoc above. */
+  MIXED_ARROW_DELIMITERS: 'E_MIXED_ARROW_DELIMITERS',
+} as const;
+
+// ============================================================
+// validateLabelCharacters (TD-13, TD-14)
+// ============================================================
+
+/**
+ * Validate an in-arrow label against the TD-13 and TD-14 character-set
+ * contract. Returns diagnostics (possibly empty). Does NOT mutate the label —
+ * callers that want a normalized label should trim before calling.
+ *
+ * TD-13: label must not contain the substrings "->" or "~>".
+ * TD-14: label must not contain C0 control chars other than tab, and no DEL.
+ */
+export function validateLabelCharacters(
+  label: string,
+  lineNumber: number
+): DgmoError[] {
+  const out: DgmoError[] = [];
+
+  // TD-13: forbidden substrings
+  if (label.includes('->') || label.includes('~>')) {
+    out.push(
+      makeDgmoError(
+        lineNumber,
+        'Arrow symbols (-> or ~>) are not allowed inside a label. ' +
+          'Move the label after the arrow: "A -> B: uses -> to chain". ' +
+          'See "In-Arrow Message Labels" → Forbidden.',
+        'error',
+        ARROW_DIAGNOSTIC_CODES.ARROW_SUBSTRING_IN_LABEL
+      )
+    );
+  }
+
+  // TD-14: control chars (iterate codepoints to handle surrogate pairs)
+  for (const ch of label) {
+    const cp = ch.codePointAt(0)!;
+    const isC0 = cp >= 0x00 && cp <= 0x1f && cp !== 0x09; // allow tab
+    const isDel = cp === 0x7f;
+    if (isC0 || isDel) {
+      const hex = cp.toString(16).toUpperCase().padStart(4, '0');
+      out.push(
+        makeDgmoError(
+          lineNumber,
+          `Label contains a control character (U+${hex}). ` +
+            'Remove it and use plain text.',
+          'error',
+          ARROW_DIAGNOSTIC_CODES.CONTROL_CHAR_IN_LABEL
+        )
+      );
+      break; // one diagnostic per label is enough
+    }
+  }
+
+  return out;
+}
+
+// ============================================================
+// parseInArrowLabel (TD-1, TD-8, TD-10, TD-13, TD-14)
+// ============================================================
+
+export interface ParseInArrowLabelResult {
+  /** Cleaned label (trimmed; `undefined` if empty after trim per TD-10). */
+  label: string | undefined;
+  diagnostics: DgmoError[];
+}
+
+/**
+ * Normalize and validate a raw in-arrow label.
+ *
+ * Behavior:
+ *   - Trims leading/trailing whitespace (TD-8: internal whitespace preserved).
+ *   - Empty-after-trim → `{ label: undefined }` (TD-10 normalization).
+ *   - TD-13: emits `E_ARROW_SUBSTRING_IN_LABEL` if `->` or `~>` is present.
+ *   - TD-14: emits `E_CONTROL_CHAR_IN_LABEL` for forbidden control chars.
+ *
+ * This helper is intentionally chart-agnostic: it operates on an already
+ * extracted label string, leaving each chart's existing arrow-finding
+ * tokenization in place. TD-11 color-parens is handled inside the
+ * flowchart and state `parseArrowToken` functions because those are the
+ * only charts that interpret `-(color)->` as a colored edge; they use
+ * `matchColorParens()` from this module for the shared lookup.
+ */
+export function parseInArrowLabel(
+  rawLabel: string,
+  lineNumber: number
+): ParseInArrowLabelResult {
+  const trimmed = rawLabel.trim();
+
+  // TD-10: empty/whitespace-only label normalizes to undefined
+  if (trimmed.length === 0) {
+    return { label: undefined, diagnostics: [] };
+  }
+
+  // TD-13 / TD-14 validation
+  const diagnostics = validateLabelCharacters(trimmed, lineNumber);
+
+  return { label: trimmed, diagnostics };
+}
+
+// ============================================================
+// matchColorParens — shared TD-11 helper for flowchart and state
+// ============================================================
+
+/**
+ * Test whether a string matches the TD-11 color-parens form `(colorName)`
+ * where `colorName` is one of the 11 recognized palette color names from
+ * `src/colors.ts:RECOGNIZED_COLOR_NAMES`. Returns the lowercase color name
+ * on a match, or `null` on fall-through (whole string becomes a label).
+ *
+ * Used by flowchart and state parsers to keep the color-parens recognition
+ * rule in one place — do NOT re-implement the regex in chart parsers.
+ */
+export function matchColorParens(content: string): string | null {
+  const m = content.match(/^\(([A-Za-z]+)\)$/);
+  if (!m) return null;
+  const candidate = m[1].toLowerCase();
+  if ((RECOGNIZED_COLOR_NAMES as readonly string[]).includes(candidate)) {
+    return candidate;
+  }
+  return null;
+}
+
 // Forward (call) patterns — participant names may contain spaces, so use non-greedy (.+?)
 const SYNC_LABELED_RE = /^(.+?)\s*-(.+)->\s*(.+)$/;
 const ASYNC_LABELED_RE = /^(.+?)\s*~(.+)~>\s*(.+)$/;
@@ -23,8 +195,6 @@ const RETURN_ASYNC_LABELED_RE = /^(.+?)\s*<~(.+)~\s*(.+)$/;
 const BIDI_SYNC_RE = /^(.+?)\s*<-(.+)->\s*(.+)$/;
 const BIDI_ASYNC_RE = /^(.+?)\s*<~(.+)~>\s*(.+)$/;
 
-const ARROW_CHARS = ['->', '~>'];
-
 /**
  * Try to parse a labeled arrow from a trimmed line.
  *
@@ -32,6 +202,14 @@ const ARROW_CHARS = ['->', '~>'];
  *  - `ParsedArrow` if matched and valid
  *  - `{ error: string }` if matched but invalid (deprecated syntax)
  *  - `null` if not a labeled arrow (caller should fall through to bare patterns)
+ *
+ * Note: arrow-char-in-label validation (TD-13) is NOT performed here —
+ * callers must route the returned `label` through `parseInArrowLabel` or
+ * `validateLabelCharacters` to get the unified `E_ARROW_SUBSTRING_IN_LABEL`
+ * diagnostic with the correct code. In practice this path is unreachable
+ * because arrow regexes are greedy enough to absorb inner `->`/`~>` tokens
+ * into the source/destination captures, but the check remains at the
+ * validator level for defense in depth.
  */
 export function parseArrow(
   line: string
@@ -73,15 +251,6 @@ export function parseArrow(
     // Empty label (e.g. `--> B`) — fall through to plain arrow handling
     if (!label) return null;
 
-    // Validate: no arrow chars inside label
-    for (const arrow of ARROW_CHARS) {
-      if (label.includes(arrow)) {
-        return {
-          error: 'Arrow characters (->, ~>) are not allowed inside labels',
-        };
-      }
-    }
-
     return {
       from: m[1],
       to: m[3],

package/src/utils/d3-types.ts

@@ -0,0 +1,4 @@
+export interface D3ExportDimensions {
+  width?: number;
+  height?: number;
+}

package/src/utils/legend-constants.ts

@@ -16,10 +16,6 @@ export const LEGEND_EYE_SIZE = 14;
 export const LEGEND_EYE_GAP = 6;
 export const LEGEND_ICON_W = 20;
 
-// ── Spacing constants (centralized legend system) ───────────
-export const LEGEND_TOP_PAD = 12;
-export const LEGEND_TITLE_GAP = 8;
-export const LEGEND_CONTENT_GAP = 12;
 export const LEGEND_MAX_ENTRY_ROWS = 3;
 
 // ── Proportional text measurement ────────────────────────────
@@ -54,3 +50,14 @@ export const EYE_OPEN_PATH =
   'M1 7s2.5-5 6-5 6 5 6 5-2.5 5-6 5-6-5-6-5z M7 9.5a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5z';
 export const EYE_CLOSED_PATH =
   'M2.5 2.5l9 9 M1.5 7s2.2-4 5.5-4c1.2 0 2.2.5 3 1.1 M12.5 7s-2.2 4-5.5 4c-1.2 0-2.2-.5-3-1.1';
+
+// ── Controls group constants ────────────────────────────────
+// Gear/cog icon (14×14 viewBox) — 6 flat teeth with center hole
+// Computed from polar coordinates: outerR=5.5, innerR=3.5, holeR=2, center=(7,7)
+// Uses evenodd fill-rule for the center hole
+export const CONTROLS_ICON_PATH =
+  'M5.6 1.7L8.4 1.7L7.9 3.6L9.5 4.5L10.9 3.1L12.3 5.6L10.4 6.1L10.4 7.9L12.3 8.4L10.9 10.9L9.5 9.5L7.9 10.4L8.4 12.3L5.6 12.3L6.1 10.4L4.5 9.5L3.1 10.9L1.7 8.4L3.6 7.9L3.6 6.1L1.7 5.6L3.1 3.1L4.5 4.5L6.1 3.6Z' +
+  'M5 7a2 2 0 1 0 4 0a2 2 0 1 0-4 0Z';
+export const LEGEND_TOGGLE_DOT_R = LEGEND_DOT_R;
+export const LEGEND_TOGGLE_OFF_OPACITY = 0.4;
+export const LEGEND_GEAR_PILL_W = 14 + LEGEND_PILL_PAD; // gear icon (14) + padding

package/src/utils/legend-d3.ts

@@ -9,6 +9,9 @@ import {
   LEGEND_DOT_R,
   LEGEND_ENTRY_FONT_SIZE,
   LEGEND_ENTRY_DOT_GAP,
+  LEGEND_TOGGLE_DOT_R,
+  LEGEND_TOGGLE_OFF_OPACITY,
+  CONTROLS_ICON_PATH,
   measureLegendText,
 } from './legend-constants';
 import { computeLegendLayout } from './legend-layout';
@@ -24,6 +27,7 @@ import type {
   LegendPillLayout,
   LegendCapsuleLayout,
   LegendControlLayout,
+  ControlsGroupLayout,
   D3Sel,
 } from './legend-types';
 
@@ -83,6 +87,19 @@ export function renderLegendD3(
       renderPill(legendG, pill, palette, groupBg, callbacks);
     }
 
+    // Render controls group (gear pill / capsule)
+    if (currentLayout.controlsGroup) {
+      renderControlsGroup(
+        legendG,
+        currentLayout.controlsGroup,
+        palette,
+        groupBg,
+        pillBorder,
+        callbacks,
+        config
+      );
+    }
+
     // Render controls
     for (const ctrl of currentLayout.controls) {
       renderControl(
@@ -398,3 +415,157 @@ function renderControl(
     g.on('click', () => onClick());
   }
 }
+
+// ── Controls group (gear pill / capsule) ───────────────────
+
+function renderControlsGroup(
+  parent: D3Sel,
+  layout: ControlsGroupLayout,
+  palette: LegendPalette,
+  groupBg: string,
+  pillBorder: string,
+  callbacks?: LegendCallbacks,
+  config?: LegendConfig
+): void {
+  const g = parent
+    .append('g')
+    .attr('transform', `translate(${layout.x},${layout.y})`)
+    .attr('data-legend-controls', layout.expanded ? 'expanded' : 'collapsed')
+    .attr('data-export-ignore', 'true')
+    .style('cursor', 'pointer');
+
+  if (!layout.expanded) {
+    // Collapsed: gear pill
+    g.append('rect')
+      .attr('width', layout.width)
+      .attr('height', layout.height)
+      .attr('rx', layout.height / 2)
+      .attr('fill', groupBg);
+
+    // Gear icon centered
+    const iconSize = 14;
+    const iconX = (layout.width - iconSize) / 2;
+    const iconY = (layout.height - iconSize) / 2;
+    g.append('path')
+      .attr('d', CONTROLS_ICON_PATH)
+      .attr('transform', `translate(${iconX},${iconY})`)
+      .attr('fill', palette.textMuted)
+      .attr('fill-rule', 'evenodd')
+      .attr('pointer-events', 'none');
+
+    if (callbacks?.onControlsExpand) {
+      const cb = callbacks.onControlsExpand;
+      g.on('click', () => cb());
+    }
+  } else {
+    // Expanded: capsule with gear pill + toggle entries
+    const pill = layout.pill;
+
+    // Outer capsule background
+    g.append('rect')
+      .attr('width', layout.width)
+      .attr('height', layout.height)
+      .attr('rx', LEGEND_HEIGHT / 2)
+      .attr('fill', groupBg);
+
+    // Inner gear pill
+    const pillG = g
+      .append('g')
+      .attr('class', 'controls-gear-pill')
+      .style('cursor', 'pointer');
+
+    pillG
+      .append('rect')
+      .attr('x', pill.x)
+      .attr('y', pill.y)
+      .attr('width', pill.width)
+      .attr('height', pill.height)
+      .attr('rx', pill.height / 2)
+      .attr('fill', palette.bg);
+
+    pillG
+      .append('rect')
+      .attr('x', pill.x)
+      .attr('y', pill.y)
+      .attr('width', pill.width)
+      .attr('height', pill.height)
+      .attr('rx', pill.height / 2)
+      .attr('fill', 'none')
+      .attr('stroke', pillBorder)
+      .attr('stroke-width', 0.75);
+
+    // Gear icon inside pill
+    const iconSize = 14;
+    const iconX = pill.x + (pill.width - iconSize) / 2;
+    const iconY = pill.y + (pill.height - iconSize) / 2;
+    pillG
+      .append('path')
+      .attr('d', CONTROLS_ICON_PATH)
+      .attr('transform', `translate(${iconX},${iconY})`)
+      .attr('fill', palette.text)
+      .attr('fill-rule', 'evenodd')
+      .attr('pointer-events', 'none');
+
+    // Click on gear pill collapses
+    if (callbacks?.onControlsExpand) {
+      const cb = callbacks.onControlsExpand;
+      pillG.on('click', (event: Event) => {
+        event.stopPropagation();
+        cb();
+      });
+    }
+
+    // Toggle entries
+    const toggles = config?.controlsGroup?.toggles ?? [];
+    for (const tl of layout.toggles) {
+      const toggle = toggles.find((t) => t.id === tl.id);
+      const entryG = g
+        .append('g')
+        .attr('data-controls-toggle', tl.id)
+        .style('cursor', 'pointer');
+
+      if (tl.active) {
+        // Filled dot
+        entryG
+          .append('circle')
+          .attr('cx', tl.dotCx)
+          .attr('cy', tl.dotCy)
+          .attr('r', LEGEND_TOGGLE_DOT_R)
+          .attr('fill', palette.primary ?? palette.text);
+      } else {
+        // Hollow dot
+        entryG
+          .append('circle')
+          .attr('cx', tl.dotCx)
+          .attr('cy', tl.dotCy)
+          .attr('r', LEGEND_TOGGLE_DOT_R)
+          .attr('fill', 'none')
+          .attr('stroke', palette.textMuted)
+          .attr('stroke-width', 1);
+      }
+
+      // Label
+      entryG
+        .append('text')
+        .attr('x', tl.textX)
+        .attr('y', tl.textY)
+        .attr('dominant-baseline', 'central')
+        .attr('font-size', LEGEND_ENTRY_FONT_SIZE)
+        .attr('fill', palette.textMuted)
+        .attr('opacity', tl.active ? 1 : LEGEND_TOGGLE_OFF_OPACITY)
+        .attr('font-family', FONT_FAMILY)
+        .text(tl.label);
+
+      // Click on toggle entry
+      if (callbacks?.onControlsToggle && toggle) {
+        const cb = callbacks.onControlsToggle;
+        const id = tl.id;
+        const newActive = !tl.active;
+        entryG.on('click', (event: Event) => {
+          event.stopPropagation();
+          cb(id, newActive);
+        });
+      }
+    }
+  }
+}