@diagrammo/dgmo 0.39.0 → 0.41.0

package/docs/language-reference.md

@@ -2399,6 +2399,23 @@ tag Genre as g
 - **Tag** — trailing same-line metadata (`g: Pop`), like timeline; colors the dot, leader, and card.
 - **Description** — bare indented body lines (like `pyramid`/`ring`); `- ` makes a bullet; inline markdown (`**bold**`, `*italic*`, `` `code` ``) supported.
 
+#### Eras
+
+Group a run of events into a labeled section with a `[Name]` bracket, then **indent the events beneath it** (the org / version-control nesting idiom). An event belongs to the era it is indented under; its description sits one level deeper still. An event at indent 0 sits **outside** any era.
+
+```
+[The Early Web]
+  1991 WorldWideWeb  t: Protocol
+    Tim Berners-Lee publishes the first site.
+  1993 Mosaic  t: Browser
+
+[The App Era] collapsed: true
+  2005 Ajax  t: Platform
+```
+
+- **Trailing metadata** after `]` — optional `collapsed: true` and/or a named color (`[The 1960s] collapsed: true blue`).
+- **`collapsed: true`** folds the era into a single summary card (its name + a bulleted list of member events) while a bracket stays on the spine; in the app a reader toggles it live.
+
 #### Directives
 
 - `no-scale` — space events evenly instead of by date (dates become captions).

package/gallery/fixtures/block.dgmo

@@ -0,0 +1,16 @@
+block Web Service Architecture
+
+tag Layer as l
+  Edge blue
+  Service green
+  Data orange
+
+[Clients] l: Edge
+  [Browser] [Mobile] [CLI]
+
+[Backend] l: Service
+  [Auth] [Orders]
+  [Inventory] [Billing]
+
+[Data] l: Data collapsed
+  [Postgres] [Redis]

package/gallery/fixtures/event-line.dgmo

@@ -0,0 +1,26 @@
+event-line A Short History of the Web
+no-scale
+
+tag Theme as t
+  Protocol blue
+  Browser green
+  Platform purple
+  Standard orange
+
+[The Early Web]
+  1991 WorldWideWeb  t: Protocol
+    Tim Berners-Lee publishes the first website at **CERN**.
+  1993 Mosaic  t: Browser
+    The first popular *graphical* browser.
+
+[The Standards Era] collapsed: true
+  1995 JavaScript  t: Platform
+    Brendan Eich writes the language in ten days.
+  1996 CSS  t: Standard
+    Styling splits from structure.
+
+[The App Era]
+  2005 Ajax  t: Platform
+    `XMLHttpRequest` updates pages without a reload.
+  2014 HTML5  t: Standard
+    The living standard — video, canvas, semantics.

package/package.json

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

package/src/echarts.ts

@@ -283,6 +283,9 @@ const CHART_BASE: Pick<
   tooltip: { show: false },
 };
 const CHART_BORDER_WIDTH = 2;
+// Scatter bubbles render semi-transparent so overlapping points stay visible.
+// Emphasis bumps back to full opacity on hover (see emphasisConfig).
+const SCATTER_FILL_OPACITY = 0.65;
 
 // ============================================================
 // Parser
@@ -1930,6 +1933,7 @@ function buildScatterOption(
           }),
           borderColor: catColor,
           borderWidth: CHART_BORDER_WIDTH,
+          opacity: SCATTER_FILL_OPACITY,
         },
         label: labelConfig,
         emphasis: emphasisConfig,
@@ -1961,6 +1965,7 @@ function buildScatterOption(
       {
         type: 'scatter' as const,
         data,
+        itemStyle: { opacity: SCATTER_FILL_OPACITY },
         label: labelConfig,
         emphasis: emphasisConfig,
         blur: blurConfig,

package/src/error-card.ts

@@ -0,0 +1,200 @@
+// ============================================================
+// Error Card — fallback image rendered when a diagram can't parse
+// ============================================================
+//
+// When `render(text, { onError: 'svg' })` (the default) hits parse errors,
+// hosts that embed dgmo — remark/astro/docusaurus/fumadocs, Obsidian, the
+// web editor — show whatever SVG we return in place of the diagram. A blank
+// or cryptic box is a dead end for the author, so we render a friendly card:
+// a frown mark, the dgmo wordmark, and per-error the line number, the
+// message, and the actual offending source line with a caret at the column.
+//
+// Pure string builder — no DOM, so it works in every consumer (SSR, browser,
+// resvg→PNG in the CLI). resvg has no color-mix(); all colors are pre-resolved.
+
+import { truncateText, measureText } from './utils/text-measure';
+import { FONT_FAMILY } from './fonts';
+import type { PaletteConfig } from './palettes/types';
+import type { Theme } from './themes';
+import type { DgmoError } from './diagnostics';
+
+const MONO_FAMILY =
+  "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace";
+
+const W = 660;
+const PAD = 24;
+const CONTENT_W = W - PAD * 2;
+const MAX_ERRORS = 4;
+// Monospace advance ≈ 0.6em — used to place the caret under the bad column.
+const MONO_CH = 0.6;
+const CODE_FS = 12.5;
+
+/**
+ * Render a self-contained SVG error card for a failed diagram parse.
+ *
+ * @param errors  Error-severity diagnostics (line-numbered).
+ * @param source  Original DGMO source, used to quote the offending lines.
+ */
+export function renderErrorCard(
+  errors: DgmoError[],
+  source: string,
+  palette: PaletteConfig,
+  theme?: Theme
+): string {
+  const c = palette[theme === 'dark' ? 'dark' : 'light'];
+  const isTransparent = theme === 'transparent';
+  const card = c.surface;
+  const codeBg = c.bg;
+  const border = c.border;
+  const danger = c.destructive ?? c.colors.red;
+  const text = c.text;
+  const muted = c.textMuted;
+  const srcLines = source.split('\n');
+
+  const shown = errors.slice(0, MAX_ERRORS);
+  const overflow = errors.length - shown.length;
+
+  const parts: string[] = [];
+  let y = PAD + 8;
+
+  // ── Header: frown mark + title, dgmo wordmark right ────────
+  parts.push(frownMark(PAD + 14, y + 12, danger));
+  parts.push(
+    `<text x="${PAD + 38}" y="${y + 11}" fill="${text}" font-family="${FONT_FAMILY}" font-size="16" font-weight="700">Couldn't render this diagram</text>`,
+    `<text x="${W - PAD}" y="${y + 10}" text-anchor="end" fill="${muted}" font-family="${FONT_FAMILY}" font-size="12" font-weight="600" letter-spacing="0.5">dgmo</text>`
+  );
+  y += 24;
+  const errLabel = errors.length === 1 ? '1 error' : `${errors.length} errors`;
+  parts.push(
+    `<text x="${PAD + 38}" y="${y + 4}" fill="${muted}" font-family="${FONT_FAMILY}" font-size="12.5">${errLabel} — fix the lines below and re-render</text>`
+  );
+  y += 22;
+  parts.push(
+    `<line x1="${PAD}" y1="${y}" x2="${W - PAD}" y2="${y}" stroke="${border}" stroke-width="1"/>`
+  );
+  y += 24;
+
+  // ── Per-error blocks ───────────────────────────────────────
+  for (const e of shown) {
+    const hasLine = e.line > 0;
+
+    // Line badge (skip when line is unknown / 0), with the message inline.
+    let msgX = PAD;
+    if (hasLine) {
+      const label = e.column ? `Line ${e.line}:${e.column}` : `Line ${e.line}`;
+      const badgeW = 14 + label.length * 7;
+      parts.push(
+        `<rect x="${PAD}" y="${y - 13}" width="${badgeW}" height="19" rx="4" fill="${danger}"/>`,
+        `<text x="${PAD + badgeW / 2}" y="${y + 1}" text-anchor="middle" fill="${c.bg}" font-family="${FONT_FAMILY}" font-size="11.5" font-weight="700">${escapeXml(label)}</text>`
+      );
+      msgX = PAD + badgeW + 12;
+    }
+
+    // Message: first line sits to the right of the badge, continuation lines
+    // wrap to the full content width on the rows below.
+    const lines = wrapMessage(e.message, CONTENT_W - (msgX - PAD), CONTENT_W);
+    lines.forEach((line, i) => {
+      parts.push(
+        `<text x="${i === 0 ? msgX : PAD}" y="${y + 1}" fill="${text}" font-family="${FONT_FAMILY}" font-size="13">${escapeXml(line)}</text>`
+      );
+      if (i < lines.length - 1) y += 18;
+    });
+    y += 24;
+
+    // Offending source line, monospace, with a caret under the column.
+    const raw = hasLine ? srcLines[e.line - 1] : undefined;
+    if (raw !== undefined && raw.trim().length > 0) {
+      const gutter = `${e.line}`;
+      const gutterW = gutter.length * CODE_FS * MONO_CH + 16;
+      const codeX = PAD + gutterW;
+      const codeMaxW = CONTENT_W - gutterW - 12;
+      const codeText = truncateText(
+        raw.replace(/\t/g, '  '),
+        CODE_FS,
+        codeMaxW
+      );
+      const hasCaret = e.column !== undefined && e.column > 0;
+      const blockH = hasCaret ? 40 : 26;
+      parts.push(
+        `<rect x="${PAD}" y="${y - 14}" width="${CONTENT_W}" height="${blockH}" rx="5" fill="${codeBg}" stroke="${border}" stroke-width="1"/>`,
+        `<line x1="${codeX - 8}" y1="${y - 14}" x2="${codeX - 8}" y2="${y - 14 + blockH}" stroke="${border}" stroke-width="1"/>`,
+        `<text x="${PAD + 8}" y="${y + 3}" fill="${muted}" font-family="${MONO_FAMILY}" font-size="${CODE_FS}">${escapeXml(gutter)}</text>`,
+        `<text x="${codeX}" y="${y + 3}" fill="${text}" font-family="${MONO_FAMILY}" font-size="${CODE_FS}" xml:space="preserve">${escapeXml(codeText)}</text>`
+      );
+      if (hasCaret) {
+        const caretX = codeX + (e.column! - 1) * CODE_FS * MONO_CH;
+        parts.push(
+          `<text x="${caretX}" y="${y + 17}" fill="${danger}" font-family="${MONO_FAMILY}" font-size="${CODE_FS}" font-weight="700">^</text>`
+        );
+        y += 14;
+      }
+      y += 24;
+    }
+
+    y += 14;
+  }
+
+  if (overflow > 0) {
+    parts.push(
+      `<text x="${PAD}" y="${y}" fill="${muted}" font-family="${FONT_FAMILY}" font-size="12.5" font-style="italic">+ ${overflow} more error${overflow === 1 ? '' : 's'}</text>`
+    );
+    y += 22;
+  }
+
+  const height = Math.round(y + PAD - 14);
+  const pageBg = isTransparent
+    ? ''
+    : `<rect width="100%" height="100%" fill="${c.bg}"/>`;
+
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${height}" viewBox="0 0 ${W} ${height}" font-family="${FONT_FAMILY}">`,
+    pageBg,
+    `<rect x="0.5" y="0.5" width="${W - 1}" height="${height - 1}" rx="10" fill="${card}" stroke="${border}" stroke-width="1"/>`,
+    parts.join(''),
+    `</svg>`,
+  ].join('');
+}
+
+// Greedy word-wrap where the first line is narrower (it shares its row with
+// the line badge) and continuation lines use the full content width.
+function wrapMessage(
+  message: string,
+  firstWidth: number,
+  fullWidth: number
+): string[] {
+  const words = message.split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [''];
+  const lines: string[] = [];
+  let cur = '';
+  for (const word of words) {
+    const limit = lines.length === 0 ? firstWidth : fullWidth;
+    const test = cur ? `${cur} ${word}` : word;
+    if (measureText(test, 13) <= limit || !cur) {
+      cur = test;
+    } else {
+      lines.push(cur);
+      cur = word;
+    }
+  }
+  if (cur) lines.push(cur);
+  return lines;
+}
+
+// Frown face: ringed circle, two eyes, a downturned mouth.
+function frownMark(cx: number, cy: number, color: string): string {
+  const r = 12;
+  return [
+    `<circle cx="${cx}" cy="${cy}" r="${r}" fill="none" stroke="${color}" stroke-width="2"/>`,
+    `<circle cx="${cx - 4.5}" cy="${cy - 3}" r="1.6" fill="${color}"/>`,
+    `<circle cx="${cx + 4.5}" cy="${cy - 3}" r="1.6" fill="${color}"/>`,
+    `<path d="M ${cx - 5} ${cy + 6} Q ${cx} ${cy + 1} ${cx + 5} ${cy + 6}" fill="none" stroke="${color}" stroke-width="2" stroke-linecap="round"/>`,
+  ].join('');
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/event-line/parser.ts

@@ -55,6 +55,7 @@ export const EVENT_LINE_DIAGNOSTIC_CODES = {
   NO_EVENTS: 'E_EVENT_LINE_NO_EVENTS',
   BAD_DATE: 'E_EVENT_LINE_BAD_DATE',
   UNSUPPORTED: 'E_EVENT_LINE_UNSUPPORTED',
+  ERA_DATE_ORDER: 'E_EVENT_LINE_ERA_DATE_ORDER',
 } as const;
 
 /** A non-ISO date attempt: leading digits with a slash or dot separator. */
@@ -113,6 +114,11 @@ export function parseEventLine(
   let currentTagGroup: Writable<TagGroup> | null = null;
   let currentEvent: Writable<EventLineEvent> | null = null;
   let currentEra: string | null = null;
+  // Indent of the open era's `[Name]` bracket; events must be indented deeper
+  // to belong to it. -1 ⇒ no era open (an indent-0 event is then era-less).
+  let eraIndent = -1;
+  // Indent of the current event; a line indented deeper is its description.
+  let currentEventIndent = 0;
   const aliasMap = new Map<string, string>();
 
   for (let i = 0; i < lines.length; i++) {
@@ -197,15 +203,17 @@ export function parseEventLine(
       continue;
     }
 
-    // ── Indented line in content phase = description body ──
-    if (indent > 0) {
-      if (!currentEvent) {
-        pushWarning(
-          lineNumber,
-          `Indented description "${trimmed}" has no event above it — add an event line first. (§28)`
-        );
-        continue;
-      }
+    // ── Content phase: indentation classifies each line. ──
+    //
+    // Eras are top-level `[Name]` section headers whose member events are
+    // INDENTED beneath them (the org §7 / version-control §29 idiom); an event
+    // at indent 0 sits OUTSIDE any era. A line indented deeper than its event
+    // is that event's description body (§28.4).
+
+    // Description body — any line indented deeper than its event. Checked
+    // before the era bracket so a bracketed prose line (`  [aside]`) under an
+    // event stays a description rather than opening a spurious era.
+    if (currentEvent && indent > currentEventIndent) {
       const descLine = trimmed.startsWith('- ')
         ? `• ${trimmed.substring(2)}`
         : trimmed;
@@ -213,47 +221,14 @@ export function parseEventLine(
       continue;
     }
 
-    // ── Indent-0 line: directive, reserved seam, or event ──
-    currentTagGroup = null;
-
-    if (trimmed.toLowerCase() === 'no-scale') {
-      options.scale = false;
-      continue;
-    }
-    const sideMatch = trimmed.match(SIDE_RE);
-    if (sideMatch) {
-      options.side = sideMatch[1]!.toLowerCase() as EventLineOptions['side'];
-      continue;
-    }
-    if (trimmed.toLowerCase() === 'no-box') {
-      options.noBox = true;
-      continue;
-    }
-    if (trimmed.toLowerCase() === 'no-legend') {
-      options.noLegend = true;
-      continue;
-    }
-    const dirMatch = trimmed.match(DIRECTION_RE);
-    if (dirMatch) {
-      const dir = dirMatch[1]!.toUpperCase();
-      if (dir !== 'LR') {
-        pushWarning(
-          lineNumber,
-          `event-line is horizontal-only in v1; \`direction ${dir}\` (vertical orientation) is a fast-follow.`,
-          EVENT_LINE_DIAGNOSTIC_CODES.UNSUPPORTED
-        );
-      }
-      continue;
-    }
-    if (tryParseSharedOption(trimmed, sharedOptions)) continue;
-
-    // ── Era run delimiter: `[Name]` opens a section that runs to the next
-    //    `[Name]` or EOF (§28.6a). NOT an indentation container — events stay at
-    //    indent 0, so flat bare-body descriptions are preserved. Optional trailing
-    //    `collapsed: true` and/or a color name tint/fold the era.
+    // ── Era run delimiter: `[Name]` (§28.6a) — a section header whose member
+    //    events are indented beneath it. Dedenting to (or past) the bracket's
+    //    own indent leaves the era. Optional trailing `collapsed: true` and/or
+    //    a color name tint/fold the era.
     const eraMatch = trimmed.match(ERA_RE);
     if (eraMatch) {
       contentStarted = true;
+      currentTagGroup = null;
       currentEvent = null;
       const name = eraMatch[1]!.trim();
       let rest = (eraMatch[2] ?? '').trim();
@@ -261,7 +236,9 @@ export function parseEventLine(
       const cm = rest.match(ERA_COLLAPSED_RE);
       if (cm) {
         collapsed = cm[1]!.toLowerCase() === 'true';
-        rest = (rest.slice(0, cm.index) + rest.slice(cm.index! + cm[0].length)).trim();
+        rest = (
+          rest.slice(0, cm.index) + rest.slice(cm.index! + cm[0].length)
+        ).trim();
       }
       let color: string | null = null;
       if (rest) {
@@ -280,19 +257,59 @@ export function parseEventLine(
       const era: EventLineEra = { name, color, collapsed, lineNumber };
       result.eras.push(era);
       currentEra = name;
+      eraIndent = indent;
       continue;
     }
 
-    if (SECTION_SEAM_RE.test(trimmed)) {
-      pushWarning(
-        lineNumber,
-        'Group events with `[Name]` era brackets (§28.6a), not `section`.',
-        EVENT_LINE_DIAGNOSTIC_CODES.UNSUPPORTED
-      );
-      continue;
+    // ── Top-level (indent 0) directives and reserved seams. ──
+    if (indent === 0) {
+      currentTagGroup = null;
+      if (trimmed.toLowerCase() === 'no-scale') {
+        options.scale = false;
+        continue;
+      }
+      const sideMatch = trimmed.match(SIDE_RE);
+      if (sideMatch) {
+        options.side = sideMatch[1]!.toLowerCase() as EventLineOptions['side'];
+        continue;
+      }
+      if (trimmed.toLowerCase() === 'no-box') {
+        options.noBox = true;
+        continue;
+      }
+      if (trimmed.toLowerCase() === 'no-legend') {
+        options.noLegend = true;
+        continue;
+      }
+      const dirMatch = trimmed.match(DIRECTION_RE);
+      if (dirMatch) {
+        const dir = dirMatch[1]!.toUpperCase();
+        if (dir !== 'LR') {
+          pushWarning(
+            lineNumber,
+            `event-line is horizontal-only in v1; \`direction ${dir}\` (vertical orientation) is a fast-follow.`,
+            EVENT_LINE_DIAGNOSTIC_CODES.UNSUPPORTED
+          );
+        }
+        continue;
+      }
+      if (tryParseSharedOption(trimmed, sharedOptions)) continue;
+      if (SECTION_SEAM_RE.test(trimmed)) {
+        pushWarning(
+          lineNumber,
+          'Group events with `[Name]` era brackets (§28.6a), not `section`.',
+          EVENT_LINE_DIAGNOSTIC_CODES.UNSUPPORTED
+        );
+        continue;
+      }
     }
 
     // ── Event line ──
+    // An event belongs to the open era only when indented beneath that era's
+    // bracket; an indent-0 event sits outside any era and closes the run
+    // (events outside eras are fully supported — they simply have `era: null`).
+    const inEra = currentEra !== null && indent > eraIndent;
+    if (!inEra) currentEra = null;
     contentStarted = true;
     const event = parseEventHeader(
       trimmed,
@@ -304,6 +321,7 @@ export function parseEventLine(
     );
     result.events.push(event);
     currentEvent = event;
+    currentEventIndent = indent;
   }
 
   options.noTitle = sharedOptions['no-title'] === 'on';
@@ -323,9 +341,91 @@ export function parseEventLine(
     );
   }
 
+  // Eras render as date-spanning brackets, so an event dated outside its era's
+  // chronological position makes adjacent era brackets overlap (§28.6a). Only
+  // meaningful when the date scale drives x-position.
+  if (options.scale) {
+    validateEraDateOrder(result.events, result.eras, pushWarning);
+  }
+
   return result;
 }
 
+/**
+ * Warn when a dated event sits in an era whose chronological run it breaks —
+ * i.e. it is dated after a later era begins, or before an earlier era ends.
+ * Eras are left-to-right date bands; a straggler makes their brackets overlap.
+ */
+function validateEraDateOrder(
+  events: readonly EventLineEvent[],
+  eras: readonly EventLineEra[],
+  pushWarning: (line: number, message: string, code?: string) => void
+): void {
+  if (eras.length < 2) return;
+  const order = new Map(eras.map((e, i) => [e.name, i]));
+  const dated = events.filter(
+    (e) => e.dateValue !== null && e.era !== null && order.has(e.era)
+  );
+  if (dated.length === 0) return;
+
+  // Earliest and latest dated event per era index.
+  const perEra = new Map<
+    number,
+    { min: EventLineEvent; max: EventLineEvent }
+  >();
+  for (const ev of dated) {
+    const idx = order.get(ev.era!)!;
+    const cur = perEra.get(idx);
+    if (!cur) {
+      perEra.set(idx, { min: ev, max: ev });
+    } else {
+      if (ev.dateValue! < cur.min.dateValue!) cur.min = ev;
+      if (ev.dateValue! > cur.max.dateValue!) cur.max = ev;
+    }
+  }
+
+  const n = eras.length;
+  // prefixMax[k] = the latest-dated event across eras with index < k.
+  // suffixMin[k] = the earliest-dated event across eras with index > k.
+  const prefixMax: (EventLineEvent | null)[] = new Array(n).fill(null);
+  const suffixMin: (EventLineEvent | null)[] = new Array(n).fill(null);
+  for (let k = 1; k < n; k++) {
+    const prev = perEra.get(k - 1)?.max ?? null;
+    const carried = prefixMax[k - 1] ?? null;
+    prefixMax[k] =
+      prev && (!carried || prev.dateValue! > carried.dateValue!)
+        ? prev
+        : carried;
+  }
+  for (let k = n - 2; k >= 0; k--) {
+    const next = perEra.get(k + 1)?.min ?? null;
+    const carried = suffixMin[k + 1] ?? null;
+    suffixMin[k] =
+      next && (!carried || next.dateValue! < carried.dateValue!)
+        ? next
+        : carried;
+  }
+
+  for (const ev of dated) {
+    const k = order.get(ev.era!)!;
+    const ahead = suffixMin[k];
+    const behind = prefixMax[k];
+    if (ahead && ev.dateValue! > ahead.dateValue!) {
+      pushWarning(
+        ev.lineNumber,
+        `"${ev.label}" (${ev.date}) is in era "${ev.era}" but dated after era "${ahead.era}" begins (${ahead.date}). event-line eras run left-to-right by date — fix the date or move it to the right era, or their brackets will overlap.`,
+        EVENT_LINE_DIAGNOSTIC_CODES.ERA_DATE_ORDER
+      );
+    } else if (behind && ev.dateValue! < behind.dateValue!) {
+      pushWarning(
+        ev.lineNumber,
+        `"${ev.label}" (${ev.date}) is in era "${ev.era}" but dated before era "${behind.era}" ends (${behind.date}). event-line eras run left-to-right by date — fix the date or move it to the right era, or their brackets will overlap.`,
+        EVENT_LINE_DIAGNOSTIC_CODES.ERA_DATE_ORDER
+      );
+    }
+  }
+}
+
 function parseEventHeader(
   trimmed: string,
   lineNumber: number,