@diagrammo/dgmo 0.5.4 → 0.6.0

package/docs/language-reference.md

@@ -116,9 +116,35 @@ Multi-series: comma-separated values matching the `series` list. Single series o
 
 Options: `series`, `xlabel`, `ylabel`, `labels`.
 
+**Era bands** — annotate named time periods with background shading:
+
+```
+chart: line
+title: U.S. Strategic Petroleum Reserve
+ylabel: Million Barrels
+
+era '81 -> '89: Reagan (red)
+era '89 -> '93: Bush (red)
+era '93 -> '01: Clinton (blue)
+
+'81: 230
+'85: 493
+'89: 580
+'93: 587
+'01: 550
+```
+
+Syntax: `era <start> -> <end>: <label> [(<color>)]`
+
+- `start` and `end` must exactly match category labels in the data
+- Color is optional; defaults to the palette's blue
+- Band label is hidden if the era spans fewer than 3 category slots
+- Works on `line`, `multi-line`, and `area` charts
+- Era boundary labels are always pinned visible on the x-axis even when auto-skip is active
+
 ### area
 
-Same syntax as `line`. Renders as a filled area chart.
+Same syntax as `line`, including era bands. Renders as a filled area chart.
 
 ### pie
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",

package/src/chart.ts

@@ -20,6 +20,13 @@ export interface ChartDataPoint {
   lineNumber: number;
 }
 
+export interface ChartEra {
+  start: string;        // exact category label, e.g. "'77"
+  end: string;          // exact category label, e.g. "'81"
+  label: string;        // display name, e.g. "Carter"
+  color: string | null; // resolved CSS color, or null → palette default
+}
+
 import type { DgmoError } from './diagnostics';
 
 export interface ParsedChart {
@@ -36,6 +43,7 @@ export interface ParsedChart {
   label?: string;
   labels?: 'name' | 'value' | 'percent' | 'full';
   data: ChartDataPoint[];
+  eras?: ChartEra[];
   diagnostics: DgmoError[];
   error: string | null;
 }
@@ -87,9 +95,11 @@ export function parseChart(
   palette?: PaletteColors
 ): ParsedChart {
   const lines = content.split('\n');
+  const parsedEras: ChartEra[] = [];
   const result: ParsedChart = {
     type: 'bar',
     data: [],
+    eras: parsedEras,
     diagnostics: [],
     error: null,
   };
@@ -117,6 +127,18 @@ export function parseChart(
     // Skip comments
     if (trimmed.startsWith('//')) continue;
 
+    // Era line: must be matched before colon-split (era '77 -> '81: Carter has colons inside)
+    const eraMatch = trimmed.match(/^era\s+(.+?)\s*->\s*(.+?)\s*:\s*(.+?)(?:\s*\(([^)]+)\))?\s*$/);
+    if (eraMatch) {
+      parsedEras.push({
+        start: eraMatch[1].trim(),
+        end: eraMatch[2].trim(),
+        label: eraMatch[3].trim(),
+        color: eraMatch[4] ? resolveColor(eraMatch[4].trim(), palette) : null,
+      });
+      continue;
+    }
+
     // Parse key: value pairs
     const colonIndex = trimmed.indexOf(':');
     if (colonIndex === -1) continue;
@@ -214,6 +236,11 @@ export function parseChart(
     }
   }
 
+  // Eras are only valid for line, multi-line (aliased to 'line'), and area chart types
+  if (result.type !== 'line' && result.type !== 'area') {
+    result.eras = undefined;
+  }
+
   // Validation
   const setChartError = (line: number, message: string) => {
     const diag = makeDgmoError(line, message);

package/src/cli.ts

@@ -3,7 +3,7 @@ import { execSync } from 'node:child_process';
 import { resolve, basename, extname } from 'node:path';
 import { Resvg } from '@resvg/resvg-js';
 import { render } from './render';
-import { parseDgmo, DGMO_CHART_TYPE_MAP } from './dgmo-router';
+import { parseDgmo, getAllChartTypes } from './dgmo-router';
 import { parseDgmoChartType } from './dgmo-router';
 import { formatDgmoError } from './diagnostics';
 import { getPalette } from './palettes/registry';
@@ -276,7 +276,7 @@ async function main(): Promise<void> {
   }
 
   if (opts.chartTypes) {
-    const types = Object.keys(DGMO_CHART_TYPE_MAP);
+    const types = getAllChartTypes();
     if (opts.json) {
       const chartTypes = types.map((id) => ({
         id,

package/src/d3.ts

@@ -10,7 +10,7 @@ import { injectBranding } from './branding';
 // Types
 // ============================================================
 
-export type D3ChartType =
+export type VisualizationType =
   | 'slope'
   | 'wordcloud'
   | 'arc'
@@ -136,8 +136,8 @@ export interface D3ExportDimensions {
   height?: number;
 }
 
-export interface ParsedD3 {
-  type: D3ChartType | null;
+export interface ParsedVisualization {
+  type: VisualizationType | null;
   title: string | null;
   titleLineNumber: number | null;
   orientation: 'horizontal' | 'vertical';
@@ -328,8 +328,8 @@ export function addDurationToDate(
 /**
  * Parses D3 chart text format into structured data.
  */
-export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
-  const result: ParsedD3 = {
+export function parseVisualization(content: string, palette?: PaletteColors): ParsedVisualization {
+  const result: ParsedVisualization = {
     type: null,
     title: null,
     titleLineNumber: null,
@@ -367,7 +367,7 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
     error: null,
   };
 
-  const fail = (line: number, message: string): ParsedD3 => {
+  const fail = (line: number, message: string): ParsedVisualization => {
     const diag = makeDgmoError(line, message);
     result.diagnostics.push(diag);
     result.error = formatDgmoError(diag);
@@ -1301,7 +1301,7 @@ const SLOPE_CHAR_WIDTH = 8; // approximate px per character at 14px
  */
 export function renderSlopeChart(
   container: HTMLDivElement,
-  parsed: ParsedD3,
+  parsed: ParsedVisualization,
   palette: PaletteColors,
   isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
@@ -1690,7 +1690,7 @@ const ARC_MARGIN = { top: 60, right: 40, bottom: 60, left: 40 };
  */
 export function renderArcDiagram(
   container: HTMLDivElement,
-  parsed: ParsedD3,
+  parsed: ParsedVisualization,
   palette: PaletteColors,
   _isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
@@ -2809,7 +2809,7 @@ function buildEraTooltipHtml(era: TimelineEra): string {
  */
 export function renderTimeline(
   container: HTMLDivElement,
-  parsed: ParsedD3,
+  parsed: ParsedVisualization,
   palette: PaletteColors,
   isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
@@ -4446,7 +4446,7 @@ function getRotateFn(mode: WordCloudRotate): () => number {
  */
 export function renderWordCloud(
   container: HTMLDivElement,
-  parsed: ParsedD3,
+  parsed: ParsedVisualization,
   palette: PaletteColors,
   _isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
@@ -4526,7 +4526,7 @@ export function renderWordCloud(
 
 function renderWordCloudAsync(
   container: HTMLDivElement,
-  parsed: ParsedD3,
+  parsed: ParsedVisualization,
   palette: PaletteColors,
   _isDark: boolean,
   exportDims?: D3ExportDimensions
@@ -4790,7 +4790,7 @@ function regionCentroid(circles: Circle[], inside: boolean[]): Point {
 
 export function renderVenn(
   container: HTMLDivElement,
-  parsed: ParsedD3,
+  parsed: ParsedVisualization,
   palette: PaletteColors,
   isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
@@ -4890,8 +4890,6 @@ export function renderVenn(
       .attr('fill-opacity', 0.35)
       .attr('stroke', setColors[i])
       .attr('stroke-width', 2)
-      .attr('class', 'venn-fill-circle')
-      .attr('data-line-number', String(vennSets[i].lineNumber))
       .style('pointer-events', 'none') as d3Selection.Selection<
       SVGCircleElement,
       unknown,
@@ -4959,12 +4957,9 @@ export function renderVenn(
       .attr('fill', 'white')
       .attr('fill-opacity', 0)
       .attr('class', 'venn-region-overlay')
+      .attr('data-line-number', regionLineNumber != null ? String(regionLineNumber) : '0')
       .attr('clip-path', `url(#${clipId})`);
 
-    if (regionLineNumber != null) {
-      el.attr('data-line-number', String(regionLineNumber));
-    }
-
     if (excluded.length > 0) {
       // Mask subtracts excluded circles so only the exact region shape highlights
       const maskId = `vvm-${key}`;
@@ -4986,7 +4981,7 @@ export function renderVenn(
 
   const showRegionOverlay = (idxs: number[]) => {
     const key = [...idxs].sort((a, b) => a - b).join('-');
-    overlayEls.forEach((el, k) => el.attr('fill-opacity', k === key ? 0.3 : 0));
+    overlayEls.forEach((el, k) => el.attr('fill-opacity', k === key ? 0 : 0.55));
   };
   const hideAllOverlays = () => {
     overlayEls.forEach(el => el.attr('fill-opacity', 0));
@@ -5217,7 +5212,7 @@ type QuadrantPosition =
  */
 export function renderQuadrant(
   container: HTMLDivElement,
-  parsed: ParsedD3,
+  parsed: ParsedVisualization,
   palette: PaletteColors,
   isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
@@ -5776,7 +5771,7 @@ function finalizeSvgExport(
  * Renders a D3 chart to an SVG string for export.
  * Creates a detached DOM element, renders into it, extracts the SVG, then cleans up.
  */
-export async function renderD3ForExport(
+export async function renderForExport(
   content: string,
   theme: 'light' | 'dark' | 'transparent',
   palette?: PaletteColors,
@@ -5788,7 +5783,7 @@ export async function renderD3ForExport(
   },
   options?: { branding?: boolean; c4Level?: 'context' | 'containers' | 'components' | 'deployment'; c4System?: string; c4Container?: string; scenario?: string }
 ): Promise<string> {
-  // Flowchart and org chart use their own parser pipelines — intercept before parseD3()
+  // Flowchart and org chart use their own parser pipelines — intercept before parseVisualization()
   const { parseDgmoChartType } = await import('./dgmo-router');
   const detectedType = parseDgmoChartType(content);
 
@@ -6053,8 +6048,8 @@ export async function renderD3ForExport(
     return finalizeSvgExport(container, theme, effectivePalette, options);
   }
 
-  const parsed = parseD3(content, palette);
-  // Allow sequence diagrams through even if parseD3 errors —
+  const parsed = parseVisualization(content, palette);
+  // Allow sequence diagrams through even if parseVisualization errors —
   // sequence is parsed by its own dedicated parser (parseSequenceDgmo)
   // and may not have a "chart:" line (auto-detected from arrow syntax).
   if (parsed.error && parsed.type !== 'sequence') {

package/src/dgmo-router.ts

@@ -8,8 +8,8 @@ import { looksLikeState, parseState } from './graph/state-parser';
 import { looksLikeClassDiagram, parseClassDiagram } from './class/parser';
 import { looksLikeERDiagram, parseERDiagram } from './er/parser';
 import { parseChart } from './chart';
-import { parseEChart } from './echarts';
-import { parseD3 } from './d3';
+import { parseExtendedChart } from './echarts';
+import { parseVisualization } from './d3';
 import { parseOrg, looksLikeOrg } from './org/parser';
 import { parseKanban } from './kanban/parser';
 import { parseC4 } from './c4/parser';
@@ -19,18 +19,15 @@ import { parseInfra } from './infra/parser';
 import type { DgmoError } from './diagnostics';
 
 /**
- * Framework identifiers used by the .dgmo router.
- * Maps to the existing preview components and export paths.
+ * Framework identifiers used by the .dgmo router internally.
+ * Not part of the public API — use RenderCategory instead.
  */
-export type DgmoFramework = 'echart' | 'd3' | 'mermaid';
+type DgmoFramework = 'echart' | 'd3' | 'mermaid';
 
 /**
- * Maps every supported chart type string to its backing framework.
- *
- * ECharts:  standard chart types (bar, line, pie, etc.), scatter, flow/relationship diagrams, math, heatmap
- * D3:       slope, wordcloud, arc diagram, timeline
+ * Maps every supported chart type string to its backing framework (internal).
  */
-export const DGMO_CHART_TYPE_MAP: Record<string, DgmoFramework> = {
+const DGMO_CHART_TYPE_MAP: Record<string, DgmoFramework> = {
   // Standard charts (via ECharts)
   bar: 'echart',
   line: 'echart',
@@ -71,9 +68,10 @@ export const DGMO_CHART_TYPE_MAP: Record<string, DgmoFramework> = {
 };
 
 /**
- * Returns the framework for a given chart type, or `null` if unknown.
+ * Returns the internal framework for a given chart type, or `null` if unknown.
+ * Internal only — use getRenderCategory() for public dispatch.
  */
-export function getDgmoFramework(chartType: string): DgmoFramework | null {
+function getDgmoFramework(chartType: string): DgmoFramework | null {
   return DGMO_CHART_TYPE_MAP[chartType.toLowerCase()] ?? null;
 }
 
@@ -107,13 +105,69 @@ export function parseDgmoChartType(content: string): string | null {
   return null;
 }
 
-/** Standard chart types parsed by parseChart (then rendered via ECharts). */
-export const STANDARD_CHART_TYPES = new Set([
+// ============================================================
+// Public render-category API
+// ============================================================
+
+/** User-visible rendering category for dispatch and routing. */
+export type RenderCategory = 'data-chart' | 'visualization' | 'diagram';
+
+const DATA_CHART_TYPES = new Set([
+  'bar', 'line', 'pie', 'doughnut', 'area', 'polar-area', 'radar',
+  'bar-stacked', 'multi-line', 'scatter', 'sankey', 'chord', 'function',
+  'heatmap', 'funnel',
+]);
+const VISUALIZATION_TYPES = new Set([
+  'slope', 'wordcloud', 'arc', 'timeline', 'venn', 'quadrant',
+]);
+const DIAGRAM_TYPES = new Set([
+  'sequence', 'flowchart', 'class', 'er', 'org', 'kanban', 'c4',
+  'initiative-status', 'state', 'sitemap', 'infra',
+]);
+const EXTENDED_CHART_TYPES = new Set([
+  'scatter', 'sankey', 'chord', 'function', 'heatmap', 'funnel',
+]);
+
+/**
+ * Returns the render category for a given chart type, or `null` if unknown.
+ * Use this instead of the internal framework map for dispatch in consumers.
+ */
+export function getRenderCategory(chartType: string): RenderCategory | null {
+  const type = chartType.toLowerCase();
+  if (DATA_CHART_TYPES.has(type)) return 'data-chart';
+  if (VISUALIZATION_TYPES.has(type)) return 'visualization';
+  if (DIAGRAM_TYPES.has(type)) return 'diagram';
+  return null;
+}
+
+/**
+ * Returns true if the chart type is an extended chart type
+ * handled by parseExtendedChart (scatter, sankey, chord, function, heatmap, funnel).
+ * Returns false for standard chart types and all other types.
+ */
+export function isExtendedChartType(chartType: string): boolean {
+  return EXTENDED_CHART_TYPES.has(chartType.toLowerCase());
+}
+
+/** Standard chart types parsed by parseChart (then rendered via ECharts). Internal use. */
+const STANDARD_CHART_TYPES = new Set([
   'bar', 'line', 'multi-line', 'area', 'pie', 'doughnut',
   'radar', 'polar-area', 'bar-stacked',
 ]);
 
-// ECharts-native types parsed by parseEChart
+/**
+ * Returns all supported chart type identifiers.
+ * Useful for CLI enumeration and autocomplete.
+ */
+export function getAllChartTypes(): string[] {
+  return [
+    ...DATA_CHART_TYPES,
+    ...VISUALIZATION_TYPES,
+    ...DIAGRAM_TYPES,
+  ];
+}
+
+// ECharts-native types parsed by parseExtendedChart
 const ECHART_TYPES = new Set([
   'scatter', 'sankey', 'chord', 'function', 'heatmap', 'funnel',
 ]);
@@ -141,8 +195,8 @@ export function parseDgmo(content: string): { diagnostics: DgmoError[] } {
   const chartType = parseDgmoChartType(content);
 
   if (!chartType) {
-    // No chart type detected — try D3 parser as fallback (it handles missing chart: line)
-    return { diagnostics: parseD3(content).diagnostics };
+    // No chart type detected — try visualization parser as fallback (it handles missing chart: line)
+    return { diagnostics: parseVisualization(content).diagnostics };
   }
 
   const directParser = PARSE_DISPATCH.get(chartType);
@@ -152,9 +206,9 @@ export function parseDgmo(content: string): { diagnostics: DgmoError[] } {
     return { diagnostics: parseChart(content).diagnostics };
   }
   if (ECHART_TYPES.has(chartType)) {
-    return { diagnostics: parseEChart(content).diagnostics };
+    return { diagnostics: parseExtendedChart(content).diagnostics };
   }
 
-  // D3 types (slope, wordcloud, arc, timeline, venn, quadrant)
-  return { diagnostics: parseD3(content).diagnostics };
+  // Visualization types (slope, wordcloud, arc, timeline, venn, quadrant)
+  return { diagnostics: parseVisualization(content).diagnostics };
 }