@diagrammo/dgmo 0.47.0 → 0.48.0

package/src/treemap/treemap-shared.ts

@@ -1,309 +0,0 @@
-// ============================================================
-// Treemap — Geometry-independent shared helpers
-// ============================================================
-//
-// Color resolution, the depth-tint ramp, value/percent compaction, and legend
-// assembly are geometry-neutral: the rectangular renderer (`renderer.ts`) and
-// the radial/sunburst renderer (`renderer-radial.ts`) both consume them so the
-// two modes share ONE color engine and ONE tint ramp (no drift — the outer-ring
-// wash-out the tint floor guards against can only be fixed in one place).
-
-import { scaleLinear } from 'd3-scale';
-import { resolveColor } from '../colors';
-import { mix } from '../palettes/color-utils';
-import { resolveTagColor, tagAttrKey } from '../utils/tag-groups';
-import type { TagGroup } from '../utils/tag-groups';
-import type { LegendGroupData } from '../utils/legend-types';
-import type { PaletteColors } from '../palettes';
-import type { ParsedTreemap, TreemapColorMode, TreemapNode } from './types';
-
-/** Fill for cells with no resolvable color (missing heat / tag / node). */
-export const MUTED_FILL = '#cbd5e1';
-
-// ============================================================
-// Depth-tint ramp (branch mode) — with a FLOORED lightness
-// ============================================================
-
-/**
- * Branch-mode depth tint: the top-level hue, progressively lightened toward the
- * background the deeper a cell sits. `mix` keeps a PERCENTAGE of the first color
- * (0–100), so deeper cells retain less hue. The keep-percent is FLOORED at 55 so
- * the outermost ring/leaf stays clearly saturated instead of washing out into
- * the background (protects legibility of deep radial trees + deep rect trees).
- */
-export function depthTint(hue: string, depth: number, bg: string): string {
-  if (depth <= 1) return hue;
-  const keepPct = Math.max(55, 100 - (depth - 1) * 18);
-  return mix(hue, bg, keepPct);
-}
-
-// ============================================================
-// Color mode resolution
-// ============================================================
-
-export function resolveColorMode(
-  parsed: ParsedTreemap,
-  override?: TreemapColorMode
-): TreemapColorMode {
-  let mode = override ?? parsed.defaultColorMode;
-  if (mode === 'tag' && parsed.tagGroups.length === 0) {
-    mode = parsed.hasHeat ? 'heat' : 'branch';
-  }
-  if (mode === 'heat' && !parsed.hasHeat) mode = 'branch';
-  return mode;
-}
-
-// ============================================================
-// Per-cell color resolution (was the `colorOf` closure in renderer.ts)
-// ============================================================
-
-/** Geometry-neutral subset of a cell needed to resolve its color. Both
- *  `TreemapCell` (rect) and `RadialCell` (sunburst) are structurally assignable. */
-export interface ColorCell {
-  readonly node: TreemapNode | null;
-  readonly label: string;
-  readonly depth: number;
-  readonly heat?: number;
-  readonly topIndex: number;
-  readonly path: readonly string[];
-}
-
-/** Everything the cell-color resolver needs that is NOT on the cell itself. */
-export interface CellColorContext {
-  readonly mode: TreemapColorMode;
-  readonly heat: HeatScale | null;
-  readonly tagGroups: readonly TagGroup[];
-  readonly activeGroup: string | null;
-  /** Top-level label → source-order index (drives the branch hue). */
-  readonly rootIndexByLabel: Map<string, number>;
-  readonly seriesColors: string[];
-  readonly colorOffset: number;
-  /** Palette background, for the depth-tint mix. */
-  readonly bg: string;
-}
-
-/**
- * Resolve a cell's base color for the active mode:
- *  - heat: the data-aware ramp keyed off `cell.heat`.
- *  - tag:  the cell's tagged ancestor color.
- *  - branch: the top-level hue (source order), tinted lighter with depth.
- * Only the branch tail touches `cell.depth`; nothing here touches geometry.
- */
-export function resolveCellColor(
-  cell: ColorCell,
-  ctx: CellColorContext
-): string {
-  if (ctx.mode === 'heat') {
-    return cell.heat !== undefined && ctx.heat
-      ? ctx.heat.scale(cell.heat)
-      : MUTED_FILL;
-  }
-  if (ctx.mode === 'tag') {
-    if (!cell.node) return MUTED_FILL;
-    return (
-      resolveTagColor(
-        cell.node.metadata,
-        ctx.tagGroups as TagGroup[],
-        ctx.activeGroup
-      ) ?? MUTED_FILL
-    );
-  }
-  // branch: top-level hue, lightened slightly with depth (floored).
-  const topLabel = cell.path[0] ?? cell.label;
-  const idx =
-    (ctx.rootIndexByLabel.get(topLabel) ?? cell.topIndex) + ctx.colorOffset;
-  const hue = ctx.seriesColors[idx % ctx.seriesColors.length]!;
-  return depthTint(hue, cell.depth, ctx.bg);
-}
-
-// ============================================================
-// Heat scale (data-aware color-by-value ramp)
-// ============================================================
-
-export interface HeatScale {
-  scale: (v: number) => string;
-  min: number;
-  max: number;
-  stops: string[];
-  signed: boolean;
-}
-
-export function buildHeatScale(
-  parsed: ParsedTreemap,
-  palette: PaletteColors
-): HeatScale | null {
-  if (!parsed.hasHeat) return null;
-  const values: number[] = [];
-  const collect = (nodes: readonly TreemapNode[]): void => {
-    for (const n of nodes) {
-      if (typeof n.heat === 'number') values.push(n.heat);
-      collect(n.children);
-    }
-  };
-  collect(parsed.roots);
-  if (values.length === 0) return null;
-
-  const min = Math.min(...values);
-  const max = Math.max(...values);
-  const signed = min < 0 && max > 0;
-
-  const neutral = palette.surface;
-  const explicit = parsed.options.heatColors
-    .map((c) => resolveColor(c, palette) ?? c)
-    .filter((c): c is string => !!c);
-
-  let stops: string[];
-  let domain: number[];
-
-  if (explicit.length >= 2) {
-    // Two endpoints → low · neutral · high (wide-hue auto-midpoint).
-    stops = [explicit[0]!, neutral, explicit[1]!];
-    const mid = signed ? 0 : (min + max) / 2;
-    domain = [min, mid, max];
-  } else if (explicit.length === 1) {
-    stops = [neutral, explicit[0]!];
-    domain = [min, max];
-  } else if (signed) {
-    // Data-aware default: diverging, midpoint pinned at 0.
-    stops = [palette.colors.red, neutral, palette.colors.green];
-    domain = [min, 0, max];
-  } else {
-    // Data-aware default: sequential neutral → accent.
-    stops = [neutral, palette.primary];
-    domain = [min, max];
-  }
-
-  // Guard against a degenerate (single-value) domain.
-  if (domain[0] === domain[domain.length - 1]) {
-    const last = stops[stops.length - 1]!;
-    return { scale: () => last, min, max, stops, signed };
-  }
-
-  const linear = scaleLinear<string, string>()
-    .domain(domain)
-    .range(stops)
-    .clamp(true);
-  // d3 interpolates to `rgb(...)` strings; normalize to hex so downstream
-  // helpers (mix/contrastText) that expect hex work on heat fills too.
-  return { scale: (v: number) => toHex(linear(v)), min, max, stops, signed };
-}
-
-/** Normalize a CSS color (`rgb(...)` or hex) to a `#rrggbb` hex string. */
-function toHex(c: string): string {
-  if (c.startsWith('#')) return c;
-  const m = c.match(/rgba?\(([^)]+)\)/);
-  if (!m) return c;
-  const parts = m[1]!.split(',').map((s) => Math.round(parseFloat(s)));
-  const h = (n: number): string =>
-    Math.max(0, Math.min(255, n || 0))
-      .toString(16)
-      .padStart(2, '0');
-  return `#${h(parts[0] ?? 0)}${h(parts[1] ?? 0)}${h(parts[2] ?? 0)}`;
-}
-
-// ============================================================
-// Value / percent formatting
-// ============================================================
-
-/** Auto-compact like the map (1.2M, 940k); plain for small numbers. */
-export function compactNumber(v: number): string {
-  const abs = Math.abs(v);
-  if (abs >= 1e9) return strip(v / 1e9) + 'B';
-  if (abs >= 1e6) return strip(v / 1e6) + 'M';
-  if (abs >= 1e3) return strip(v / 1e3) + 'k';
-  return strip(Math.round(v * 100) / 100);
-}
-
-export function strip(n: number): string {
-  return parseFloat(
-    n.toFixed(n < 10 && !Number.isInteger(n) ? 1 : 0)
-  ).toString();
-}
-
-export function formatPct(frac: number): string {
-  const pct = frac * 100;
-  if (pct >= 10) return `${Math.round(pct)}%`;
-  if (pct >= 1) return `${pct.toFixed(0)}%`;
-  return `${pct.toFixed(1)}%`;
-}
-
-// ============================================================
-// Legend assembly — one group per applicable color mode.
-// ============================================================
-
-export interface TreemapLegend {
-  groups: LegendGroupData[];
-  activeGroup: string | null;
-  /** Legend group name → the color mode it selects (for the click callback). */
-  modeByName: Map<string, TreemapColorMode>;
-}
-
-/**
- * Build one legend group per APPLICABLE color mode (tag if tags exist, heat if
- * heat data exists, branch always). The active mode's group renders as the open
- * capsule; the others render as clickable pills that switch mode — i.e. the
- * mode switcher IS the legend (the active-group pattern used elsewhere).
- */
-export function buildLegend(
-  activeMode: TreemapColorMode,
-  parsed: ParsedTreemap,
-  heat: HeatScale | null,
-  seriesColors: string[],
-  colorOffset: number
-): TreemapLegend {
-  const groups: LegendGroupData[] = [];
-  const modeByName = new Map<string, TreemapColorMode>();
-  let activeGroup: string | null = null;
-
-  // ── Tag ──────────────────────────────────────────────────
-  if (parsed.tagGroups.length > 0) {
-    const tg = parsed.tagGroups[0]!;
-    const used = new Set<string>();
-    const collect = (nodes: readonly TreemapNode[]): void => {
-      for (const n of nodes) {
-        const v = n.metadata[tagAttrKey(tg.name)];
-        if (v) used.add(v.toLowerCase());
-        collect(n.children);
-      }
-    };
-    collect(parsed.roots);
-    groups.push({
-      name: tg.name,
-      entries: tg.entries
-        .filter((e) => used.has(e.value.toLowerCase()))
-        .map((e) => ({ value: e.value, color: e.color })),
-    });
-    modeByName.set(tg.name, 'tag');
-    if (activeMode === 'tag') activeGroup = tg.name;
-  }
-
-  // ── Heat ─────────────────────────────────────────────────
-  if (heat) {
-    const name = parsed.options.heatLabel ?? 'Value';
-    groups.push({
-      name,
-      entries: [],
-      gradient: {
-        min: heat.min,
-        max: heat.max,
-        low: heat.stops[0]!,
-        high: heat.stops[heat.stops.length - 1]!,
-      },
-    });
-    modeByName.set(name, 'heat');
-    if (activeMode === 'heat') activeGroup = name;
-  }
-
-  // ── Branch (always) ──────────────────────────────────────
-  groups.push({
-    name: 'Branch',
-    entries: parsed.roots.map((r, i) => ({
-      value: r.label,
-      color: seriesColors[(i + colorOffset) % seriesColors.length]!,
-    })),
-  });
-  modeByName.set('Branch', 'branch');
-  if (activeMode === 'branch' || activeGroup === null) activeGroup = 'Branch';
-
-  return { groups, activeGroup, modeByName };
-}

package/src/treemap/types.ts

@@ -1,60 +0,0 @@
-import type { DgmoError } from '../diagnostics';
-import type { TagGroup } from '../utils/tag-groups';
-
-// ============================================================
-// Treemap — Parsed Types
-// ============================================================
-//
-// A treemap is a hierarchy (indentation) where each leaf carries a size
-// (the bare trailing number) and parents auto-sum their descendants. See the
-// treemap § of docs/dgmo-language-spec.md for the canonical grammar.
-
-/** Runtime color mode for a treemap. Default resolved from source; the app's
- *  legend/settings switcher overrides it live without editing source. */
-export type TreemapColorMode = 'tag' | 'heat' | 'branch';
-
-export interface TreemapNode {
-  readonly id: string;
-  readonly label: string;
-  /**
-   * Leaf size = the bare trailing number. `undefined` for branches (the layout
-   * auto-sums descendants) and for value-less leaves (treated as 0 + a warning).
-   */
-  value?: number;
-  /** Optional per-node heat metric (`heat:`), drives the color-by-value ramp. */
-  heat?: number;
-  readonly metadata: Record<string, string>;
-  readonly children: TreemapNode[];
-  readonly lineNumber: number;
-}
-
-export interface TreemapOptions {
-  /** Label for the heat ramp (`heat <Label> …`). */
-  heatLabel?: string;
-  /** Explicit ramp colors peeled from the `heat` directive (0–2, named only). */
-  readonly heatColors: string[];
-  /** `depth N` — render budget (interactive only); undefined = unlimited. */
-  maxDepth?: number;
-  noValues: boolean;
-  noPercent: boolean;
-  noHeaders: boolean;
-  noLegend: boolean;
-  solidFill: boolean;
-  /** `radial` — render as a sunburst (concentric rings) instead of rectangles. */
-  radial: boolean;
-}
-
-export interface ParsedTreemap {
-  readonly type: 'treemap';
-  readonly title: string | null;
-  readonly titleLineNumber: number | null;
-  readonly roots: TreemapNode[];
-  readonly tagGroups: TagGroup[];
-  /** True when any `heat:` value or a `heat` directive was declared. */
-  readonly hasHeat: boolean;
-  /** Source-declared default color mode (tag > heat > branch). */
-  readonly defaultColorMode: TreemapColorMode;
-  readonly options: TreemapOptions;
-  readonly diagnostics: DgmoError[];
-  readonly error: string | null;
-}

package/src/utils/arrow-markers.ts

@@ -1,51 +0,0 @@
-// ============================================================
-// Shared arrowhead <marker> defs
-// ============================================================
-// The flowchart and state renderers carried a byte-identical block
-// that appends a base arrowhead marker plus one per edge color. This
-// is the single source so they can't drift.
-
-import type { BaseType, Selection } from 'd3-selection';
-
-export interface ArrowheadMarkerOptions {
-  /** Marker id prefix, e.g. 'fc' → `fc-arrow`, `fc-arrow-<hex>`. */
-  idPrefix: string;
-  /** Marker width (already scaled by the caller's ScaleContext). */
-  width: number;
-  /** Marker height. */
-  height: number;
-  /** Fill for the base (uncolored) arrowhead. */
-  baseFill: string;
-  /** Edge colors needing their own tinted marker (hex strings). */
-  colors?: Iterable<string>;
-}
-
-/**
- * Append an arrowhead `<marker>` (id `${idPrefix}-arrow`) to `defs`, plus
- * one tinted marker per edge color (id `${idPrefix}-arrow-<hex-without-#>`).
- */
-export function appendArrowheadMarkers<GElement extends BaseType>(
-  defs: Selection<GElement, unknown, null, undefined>,
-  opts: ArrowheadMarkerOptions
-): void {
-  const { idPrefix, width, height, baseFill, colors } = opts;
-  const appendMarker = (id: string, fill: string): void => {
-    defs
-      .append('marker')
-      .attr('id', id)
-      .attr('viewBox', `0 0 ${width} ${height}`)
-      .attr('refX', width)
-      .attr('refY', height / 2)
-      .attr('markerWidth', width)
-      .attr('markerHeight', height)
-      .attr('orient', 'auto')
-      .append('polygon')
-      .attr('points', `0,0 ${width},${height / 2} 0,${height}`)
-      .attr('fill', fill);
-  };
-
-  appendMarker(`${idPrefix}-arrow`, baseFill);
-  for (const color of colors ?? []) {
-    appendMarker(`${idPrefix}-arrow-${color.replace('#', '')}`, color);
-  }
-}

package/src/utils/arrows-diagnostics.ts

@@ -1,62 +0,0 @@
-// ============================================================
-// Arrow / Edge-Label Diagnostic Registry (TD-16)
-// ============================================================
-//
-// Declarative `DiagnosticSpec` metadata for the SHARED in-arrow /
-// edge-label diagnostics defined in `./arrows.ts`. These codes are not
-// owned by any single chart type — every edge-bearing graph chart
-// (sequence, flowchart, state, class, er, c4, infra, boxes-and-lines,
-// …) routes labels through the same validator — so each spec sets
-// `chartType: null`.
-//
-// This file is ADDITIVE metadata only: it re-describes the codes and
-// canonical wording that already live in `arrows.ts`. It does NOT change
-// parser behavior or emission. The wording below is transcribed verbatim
-// from `validateLabelCharacters()` so the catalog cannot drift from what
-// the parser actually emits.
-//
-// See `docs/dgmo-language-spec.md` → "In-Arrow Message Labels" and
-// `docs/dgmo-language-spec-decisions.md` → TD-13/TD-14/TD-16.
-
-import type { DiagnosticSpec } from '../diagnostics';
-import { ARROW_DIAGNOSTIC_CODES } from './arrows';
-
-export const ARROW_DIAGNOSTICS: DiagnosticSpec[] = [
-  // --- ACTIVE (TD-13): emitted by validateLabelCharacters ---
-  {
-    code: ARROW_DIAGNOSTIC_CODES.ARROW_SUBSTRING_IN_LABEL, // 'E_ARROW_SUBSTRING_IN_LABEL'
-    severity: 'error',
-    chartType: null,
-    title: 'Arrow symbol inside label',
-    // Verbatim from validateLabelCharacters (arrows.ts, TD-13).
-    message:
-      '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.',
-    hint: 'Put the label after the arrow with a colon: `A -> B: uses -> to chain`.',
-    // End-to-end trigger via a symbolic parser (class), whose label is
-    // everything after the target name, so the inner `~>` survives to the
-    // validator instead of being absorbed as a second arrow token.
-    example: 'class\nFoo\n  --|> Bar uses ~> chain',
-  },
-
-  // --- ACTIVE (TD-14): emitted by validateLabelCharacters ---
-  {
-    code: ARROW_DIAGNOSTIC_CODES.CONTROL_CHAR_IN_LABEL, // 'E_CONTROL_CHAR_IN_LABEL'
-    severity: 'error',
-    chartType: null,
-    title: 'Control character in label',
-    // Verbatim from validateLabelCharacters (arrows.ts, TD-14). The emitter
-    // interpolates the offending codepoint as a 4-digit upper-hex string
-    // (e.g. '0000'); tolerate `{}` for the param-less catalog view.
-    message: (p) =>
-      `Label contains a control character (U+${
-        typeof p.hex === 'string' ? p.hex : 'XXXX'
-      }). Remove it and use plain text.`,
-    hint: 'Delete the control character (C0 U+0000–U+001F except tab, or U+007F); use plain text.',
-    // `\u0000` is a literal NUL inside the label, which triggers
-    // E_CONTROL_CHAR_IN_LABEL end-to-end on any chain-tokenizing chart.
-    // (Escaped, not a raw NUL byte, to keep the source file text-safe.)
-    example: 'sequence\nA -has\u0000nul-> B',
-  },
-];