@diagrammo/dgmo 0.47.0 → 0.48.0

package/src/timeline/types.ts

@@ -1,33 +0,0 @@
-export type TimelineSort = 'time' | 'group' | 'tag';
-
-export interface TimelineEvent {
-  date: string;
-  endDate: string | null;
-  label: string;
-  group: string | null;
-  metadata: Record<string, string>;
-  lineNumber: number;
-  uncertain?: boolean;
-}
-
-export interface TimelineGroup {
-  name: string;
-  color: string | null;
-  metadata: Record<string, string>;
-  lineNumber: number;
-}
-
-export interface TimelineEra {
-  startDate: string;
-  endDate: string;
-  label: string;
-  color: string | null;
-  lineNumber: number;
-}
-
-export interface TimelineMarker {
-  date: string;
-  label: string;
-  color: string | null;
-  lineNumber: number;
-}

package/src/timeline/viz-parser.ts

@@ -1,21 +0,0 @@
-// ============================================================
-// Timeline parser door — Story 109.2 (arch-review).
-//
-// Separate from timeline/parser.ts (which holds the date helpers +
-// parseTimelineEventLine that visualizations/parse.ts imports) — keeping the
-// door here avoids a timeline/parser <-> visualizations/parse import cycle.
-// This is timeline's typed entry point into the shared parse state machine,
-// returning the narrowed ParsedTimeline shape; the registry binds 'timeline'
-// to it.
-// ============================================================
-
-import type { PaletteColors } from '../palettes';
-import { parseVisualization } from '../visualizations/parse';
-import type { ParsedTimeline } from '../visualizations/types';
-
-export function parseTimeline(
-  content: string,
-  palette?: PaletteColors
-): ParsedTimeline {
-  return parseVisualization(content, palette) as ParsedTimeline;
-}

package/src/treemap/diagnostics.ts

@@ -1,62 +0,0 @@
-// ============================================================
-// Treemap — Diagnostic Registry
-// ============================================================
-//
-// Declarative catalog of treemap-specific diagnostics. This is ADDITIVE
-// metadata that mirrors the codes/wording emitted by `parser.ts` (see
-// `TREEMAP_DIAGNOSTIC_CODES` and the value-resolution post-pass). The
-// parser is the source of truth for what actually fires; this array is
-// what the CLI `diagnostics` subcommand, the console error-review
-// surface, MCP `validate_diagram`, and the spec docs enumerate.
-//
-// Message builders mirror the parser's exact wording. They tolerate being
-// called with `{}` so the catalog can render a representative message
-// without live params.
-//
-// Note: the parser also emits the UNIVERSAL code `E_TAG_DECLARED_AFTER_CONTENT`
-// (declared in `METADATA_DIAGNOSTIC_CODES`); that is not a treemap-owned code
-// and is intentionally excluded here.
-
-import type { DiagnosticSpec } from '../diagnostics';
-
-/** Keyed specs — referenced by the parser's `emit()` call sites. */
-export const TREEMAP_DX = {
-  NEGATIVE_VALUE: {
-    code: 'E_TREEMAP_NEGATIVE_VALUE',
-    severity: 'error',
-    chartType: 'treemap',
-    title: 'Negative leaf value',
-    message: (p) =>
-      `Leaf "${(p.label as string) ?? 'X'}" has a negative value (${
-        (p.value as number | string) ?? -5
-      }) — treemap sizes must be ≥ 0`,
-    hint: 'Segment magnitude must be zero or greater — use a value of 0 or more.',
-    example: 'treemap T\nA\n  Bad -5',
-  },
-  LEAF_NO_VALUE: {
-    code: 'W_TREEMAP_LEAF_NO_VALUE',
-    severity: 'warning',
-    chartType: 'treemap',
-    title: 'Leaf has no value',
-    message: (p) =>
-      `Leaf "${
-        (p.label as string) ?? 'Lonely'
-      }" has no value — it renders with zero size`,
-    hint: 'Add a trailing number (e.g. `Lonely 40`) so the leaf gets a size.',
-    example: 'treemap T\nA\n  Lonely',
-  },
-  BRANCH_VALUE_IGNORED: {
-    code: 'W_TREEMAP_BRANCH_VALUE_IGNORED',
-    severity: 'warning',
-    chartType: 'treemap',
-    title: 'Branch value ignored',
-    message: (p) =>
-      `"${
-        (p.label as string) ?? 'Operations'
-      }" is a branch — its trailing number is ignored; the size is the auto-sum of its children`,
-    hint: "Remove the trailing number from a branch — a parent's size is the sum of its children.",
-    example: 'treemap T\nOperations 999\n  Cloud 110\n  Support 70',
-  },
-} satisfies Record<string, DiagnosticSpec>;
-
-export const TREEMAP_DIAGNOSTICS: DiagnosticSpec[] = Object.values(TREEMAP_DX);

package/src/treemap/layout-radial.ts

@@ -1,233 +0,0 @@
-// ============================================================
-// Treemap — Radial (sunburst) angle-partition layout (d3-hierarchy)
-// ============================================================
-//
-// Disjoint from the squarified `layout.ts`: a treemap encodes value as AREA
-// (2-D); a sunburst encodes value as ANGLE (1-D sweep) and radius encodes DEPTH
-// only (no magnitude). So this is a net-new angle-partition, not an adaptation
-// of the area-packing layout.
-//
-// Core invariant: `arc.sweep = node.value / root.value × 2π`; every child's arc
-// is nested within its parent's angular wedge. Children are laid out in SOURCE
-// ORDER (NO value-sort — deliberately unlike the rectangular treemap, which
-// value-sorts at layout.ts:129), clockwise from 12 o'clock. The synthetic
-// `__root` is the center disc (chart title holder, NOT drawn as a ring); its
-// children (`roots`) are ring 1, their descendants successive rings.
-//
-// Static export = FULL tree: no depth cap, no collapse bands, no "+N more".
-// `maxDepth` is accepted (defaults to Infinity) for the app to pass an
-// interactive render budget; dgmo static export never sets it.
-
-import {
-  hierarchy,
-  partition,
-  type HierarchyRectangularNode,
-} from 'd3-hierarchy';
-import type { TreemapNode } from './types';
-
-/** Internal datum fed to d3-hierarchy (carries the original node ref).
- *  Duplicated from `layout.ts` (which keeps it module-private) so this radial
- *  path needs no edit to the squarify layout. */
-interface LayoutDatum {
-  /** Original parsed node; undefined for the synthetic root. */
-  ref?: TreemapNode;
-  label: string;
-  /** Leaf size (only meaningful on leaves). */
-  value?: number;
-  heat?: number;
-  children?: LayoutDatum[];
-  /** Source line for click-to-source wiring (when available). */
-  lineNumber?: number;
-}
-
-/** A positioned sunburst arc. Reuses every geometry-NEUTRAL field of
- *  `TreemapCell`, swapping the 4 rect coords for polar `{start/endAngle,
- *  inner/outerR}`. */
-export interface RadialCell {
-  /** Original parsed node, or null for the synthetic root. */
-  readonly node: TreemapNode | null;
-  readonly label: string;
-  /** Radians, clockwise, 0 = 12 o'clock (d3.arc convention). */
-  readonly startAngle: number;
-  readonly endAngle: number;
-  readonly innerR: number;
-  readonly outerR: number;
-  /** 1-based depth (ring index; depth 1 = first ring outward from the disc). */
-  readonly depth: number;
-  readonly value: number;
-  /** Has children (drawn as an inner ring with its own outer rings). */
-  readonly isContainer: boolean;
-  /** Always false for static export (full tree); kept for TreemapCell parity. */
-  readonly isCollapsed: boolean;
-  /** Index of the top-level ancestor (drives branch-mode hue). */
-  readonly topIndex: number;
-  readonly pctOfRoot: number;
-  readonly pctOfParent: number;
-  /** Own heat, else the mean of descendant leaf heats; undefined if none. */
-  readonly heat?: number;
-  /** Path of labels from the laid-out root (for tooltips / data-node-path). */
-  readonly path: readonly string[];
-  readonly lineNumber?: number;
-}
-
-export interface RadialLayoutResult {
-  readonly cells: readonly RadialCell[];
-  /** Grand total (sum of all leaf values). */
-  readonly total: number;
-  /** Radius of the center disc (title + total holder). */
-  readonly discRadius: number;
-  /** Deepest ring depth actually present (0 when empty). */
-  readonly maxDepthReached: number;
-  /** True when `roots` exist but the grand total is 0 (all-zero leaves) —
-   *  the renderer draws an empty-state marker in the disc, no arcs. */
-  readonly isEmpty: boolean;
-}
-
-export interface RadialLayoutOptions {
-  /** Outer radius available for the whole sunburst (disc + rings). */
-  readonly radius: number;
-  /** Center disc radius; defaults to a sensible fraction of `radius`. */
-  readonly discRadius?: number;
-  /** Interactive render budget; static export leaves it Infinity (full tree). */
-  readonly maxDepth?: number;
-}
-
-/** Convert a parsed node into a layout datum (mirrors layout.ts `toDatum`). */
-function toDatum(node: TreemapNode): LayoutDatum {
-  if (node.children.length === 0) {
-    return {
-      ref: node,
-      label: node.label,
-      value: node.value ?? 0,
-      ...(node.heat !== undefined && { heat: node.heat }),
-      lineNumber: node.lineNumber,
-    };
-  }
-  return {
-    ref: node,
-    label: node.label,
-    ...(node.heat !== undefined && { heat: node.heat }),
-    lineNumber: node.lineNumber,
-    children: node.children.map((c) => toDatum(c)),
-  };
-}
-
-/** Mean heat across the leaves under a datum (mirrors layout.ts `datumHeat`). */
-function datumHeat(
-  node: HierarchyRectangularNode<LayoutDatum>
-): number | undefined {
-  if (node.data.heat !== undefined) return node.data.heat;
-  const xs: number[] = [];
-  for (const l of node.leaves()) {
-    if (l.data.heat !== undefined) xs.push(l.data.heat);
-  }
-  if (xs.length === 0) return undefined;
-  return xs.reduce((a, b) => a + b, 0) / xs.length;
-}
-
-/** Default center-disc radius. Pinned to a fraction of the outer radius, but
- *  capped to ~one ring's share when the tree is deep so the rings stay usable. */
-function defaultDiscRadius(radius: number, treeDepth: number): number {
-  const frac = radius * 0.32;
-  const share = radius / (Math.max(1, treeDepth) + 1);
-  return Math.min(frac, share);
-}
-
-export function layoutTreemapRadial(
-  roots: readonly TreemapNode[],
-  opts: RadialLayoutOptions
-): RadialLayoutResult {
-  const maxDepth = opts.maxDepth ?? Infinity;
-  const radius = Math.max(1, opts.radius);
-
-  const rootDatum: LayoutDatum = {
-    label: '__root',
-    children: roots.map((r) => toDatum(r)),
-  };
-
-  // NO `.sort()` — d3.hierarchy preserves input (source) order when sort is not
-  // called, which is exactly ADR-4's contract (unlike the rect layout).
-  const h = hierarchy<LayoutDatum>(rootDatum).sum((d) =>
-    d.children?.length ? 0 : (d.value ?? 0)
-  );
-
-  const total = h.value ?? 0;
-  // F5: `roots` exist but grand total is 0 (all-zero leaves) → empty-state, no
-  // divide-by-zero / NaN arcs. (The truly empty tree never reaches here.)
-  if (total <= 0) {
-    return {
-      cells: [],
-      total: 0,
-      discRadius: opts.discRadius ?? defaultDiscRadius(radius, 1),
-      maxDepthReached: 0,
-      isEmpty: true,
-    };
-  }
-
-  // Angle-partition: x0/x1 are ANGLES in [0, 2π] (radius axis normalized to
-  // [0,1]; we compute the actual radii ourselves so the disc keeps a fixed
-  // fraction regardless of tree depth).
-  const hroot = partition<LayoutDatum>().size([2 * Math.PI, 1])(h);
-
-  const treeDepth = hroot.height; // deepest level below the synthetic root
-  const discRadius = Math.min(
-    radius - 1,
-    opts.discRadius ?? defaultDiscRadius(radius, treeDepth)
-  );
-  const ringSpan = Math.max(1, radius - discRadius);
-  const ringWidth = ringSpan / Math.max(1, treeDepth);
-
-  // Tag each node with the index of its depth-1 ancestor (branch hue), matching
-  // the rect layout's `_topIndex` tagging.
-  (hroot.children ?? []).forEach((top, i) => {
-    top.each((d) => {
-      (d as { _topIndex?: number })._topIndex = i;
-    });
-  });
-
-  const cells: RadialCell[] = [];
-  let maxDepthReached = 0;
-
-  for (const d of hroot.descendants()) {
-    if (d.depth === 0) continue; // synthetic root = the disc, drawn separately
-    if (d.depth > maxDepth) continue; // beyond the (interactive) render window
-
-    const hasChildren = !!d.children && d.children.length > 0;
-    if (d.depth > maxDepthReached) maxDepthReached = d.depth;
-
-    const path: string[] = [];
-    let p: HierarchyRectangularNode<LayoutDatum> | null = d;
-    while (p && p.depth > 0) {
-      path.unshift(p.data.label);
-      p = p.parent;
-    }
-
-    const innerR = discRadius + (d.depth - 1) * ringWidth;
-    const outerR = discRadius + d.depth * ringWidth;
-    const heatVal = datumHeat(d);
-
-    cells.push({
-      node: d.data.ref ?? null,
-      label: d.data.label,
-      startAngle: d.x0,
-      endAngle: d.x1,
-      innerR,
-      outerR,
-      depth: d.depth,
-      value: d.value ?? 0,
-      isContainer: hasChildren,
-      isCollapsed: false,
-      topIndex: (d as { _topIndex?: number })._topIndex ?? 0,
-      pctOfRoot: total > 0 ? (d.value ?? 0) / total : 0,
-      pctOfParent:
-        d.parent && (d.parent.value ?? 0) > 0
-          ? (d.value ?? 0) / (d.parent.value ?? 1)
-          : 1,
-      ...(heatVal !== undefined && { heat: heatVal }),
-      path,
-      ...(d.data.lineNumber !== undefined && { lineNumber: d.data.lineNumber }),
-    });
-  }
-
-  return { cells, total, discRadius, maxDepthReached, isEmpty: false };
-}

package/src/treemap/layout.ts

@@ -1,189 +0,0 @@
-// ============================================================
-// Treemap — Squarified Layout (d3-hierarchy)
-// ============================================================
-//
-// Pure geometry: takes the parsed roots + a rectangle and returns positioned
-// cells. Two data transforms happen here so the export renderer and the app's
-// interactive renderer share them:
-//   - `other-below N` rollup (per-parent, against the parent's summed total).
-//   - `depth N` windowing (collapse nodes at the cap into solid drillable blocks).
-
-import {
-  hierarchy,
-  treemap,
-  treemapSquarify,
-  type HierarchyRectangularNode,
-} from 'd3-hierarchy';
-import type { TreemapNode } from './types';
-
-/** Internal datum fed to d3-hierarchy (carries the original node ref). */
-interface LayoutDatum {
-  /** Original parsed node; undefined for the synthetic root. */
-  ref?: TreemapNode;
-  label: string;
-  /** Leaf size (only meaningful on leaves). */
-  value?: number;
-  heat?: number;
-  children?: LayoutDatum[];
-  /** Source line for click-to-source wiring (when available). */
-  lineNumber?: number;
-}
-
-export interface TreemapCell {
-  /** Original parsed node, or null for the synthetic root. */
-  readonly node: TreemapNode | null;
-  readonly label: string;
-  readonly x0: number;
-  readonly y0: number;
-  readonly x1: number;
-  readonly y1: number;
-  /** 1-based depth within the laid-out (post-drill) tree. */
-  readonly depth: number;
-  /** Summed value (d3 rollup). */
-  readonly value: number;
-  /** Has children AND is drawn as a container (depth below the cap). */
-  readonly isContainer: boolean;
-  /** Has children but sits AT the depth cap — a solid drillable block. */
-  readonly isCollapsed: boolean;
-  /** Index of the top-level ancestor (drives branch-mode hue). */
-  readonly topIndex: number;
-  readonly pctOfRoot: number;
-  readonly pctOfParent: number;
-  /** Own heat, else the mean of descendant leaf heats; undefined if none. */
-  readonly heat?: number;
-  /** Path of labels from the laid-out root (for tooltips / data-node-path). */
-  readonly path: readonly string[];
-  readonly lineNumber?: number;
-}
-
-export interface TreemapLayoutResult {
-  readonly cells: readonly TreemapCell[];
-  readonly total: number;
-}
-
-export interface TreemapLayoutOptions {
-  readonly width: number;
-  readonly height: number;
-  /** Top gutter reserved for parent header bars (0 when headers off). */
-  readonly headerH: number;
-  readonly paddingInner?: number;
-  readonly paddingOuter?: number;
-  /** Render budget; nodes at this depth collapse to solid blocks. */
-  readonly maxDepth?: number;
-}
-
-/** Summed value of a parsed node (leaf value or sum of descendants). */
-export function sumValue(node: TreemapNode): number {
-  if (node.children.length === 0) return node.value ?? 0;
-  let s = 0;
-  for (const c of node.children) s += sumValue(c);
-  return s;
-}
-
-/** Convert a parsed node into a layout datum. */
-function toDatum(node: TreemapNode): LayoutDatum {
-  if (node.children.length === 0) {
-    return {
-      ref: node,
-      label: node.label,
-      value: node.value ?? 0,
-      ...(node.heat !== undefined && { heat: node.heat }),
-      lineNumber: node.lineNumber,
-    };
-  }
-
-  return {
-    ref: node,
-    label: node.label,
-    ...(node.heat !== undefined && { heat: node.heat }),
-    lineNumber: node.lineNumber,
-    children: node.children.map((c) => toDatum(c)),
-  };
-}
-
-/** Mean heat across the leaves under a datum (own heat if it is a leaf). */
-function datumHeat(
-  node: HierarchyRectangularNode<LayoutDatum>
-): number | undefined {
-  if (node.data.heat !== undefined) return node.data.heat;
-  const xs: number[] = [];
-  for (const l of node.leaves()) {
-    if (l.data.heat !== undefined) xs.push(l.data.heat);
-  }
-  if (xs.length === 0) return undefined;
-  return xs.reduce((a, b) => a + b, 0) / xs.length;
-}
-
-export function layoutTreemap(
-  roots: readonly TreemapNode[],
-  opts: TreemapLayoutOptions
-): TreemapLayoutResult {
-  const maxDepth = opts.maxDepth ?? Infinity;
-  const rootDatum: LayoutDatum = {
-    label: '__root',
-    children: roots.map((r) => toDatum(r)),
-  };
-
-  const h = hierarchy<LayoutDatum>(rootDatum)
-    .sum((d) => (d.children?.length ? 0 : (d.value ?? 0)))
-    .sort((a, b) => (b.value ?? 0) - (a.value ?? 0));
-
-  const hroot = treemap<LayoutDatum>()
-    .tile(treemapSquarify)
-    .size([opts.width, opts.height])
-    .paddingOuter(opts.paddingOuter ?? 3)
-    .paddingTop(opts.headerH > 0 ? opts.headerH : (opts.paddingInner ?? 2))
-    .paddingInner(opts.paddingInner ?? 2)
-    .round(true)(h);
-
-  const total = hroot.value ?? 0;
-
-  // Tag each node with the index of its depth-1 ancestor (branch hue).
-  (hroot.children ?? []).forEach((top, i) => {
-    top.each((d) => {
-      (d as { _topIndex?: number })._topIndex = i;
-    });
-  });
-
-  const cells: TreemapCell[] = [];
-  for (const d of hroot.descendants()) {
-    if (d.depth === 0) continue; // skip synthetic root
-    if (d.depth > maxDepth) continue; // beyond the render window
-
-    const hasChildren = !!d.children && d.children.length > 0;
-    const isCollapsed = hasChildren && d.depth >= maxDepth;
-    const isContainer = hasChildren && !isCollapsed;
-
-    const path: string[] = [];
-    let p: HierarchyRectangularNode<LayoutDatum> | null = d;
-    while (p && p.depth > 0) {
-      path.unshift(p.data.label);
-      p = p.parent;
-    }
-
-    const heatVal = datumHeat(d);
-    cells.push({
-      node: d.data.ref ?? null,
-      label: d.data.label,
-      x0: d.x0,
-      y0: d.y0,
-      x1: d.x1,
-      y1: d.y1,
-      depth: d.depth,
-      value: d.value ?? 0,
-      isContainer,
-      isCollapsed,
-      topIndex: (d as { _topIndex?: number })._topIndex ?? 0,
-      pctOfRoot: total > 0 ? (d.value ?? 0) / total : 0,
-      pctOfParent:
-        d.parent && (d.parent.value ?? 0) > 0
-          ? (d.value ?? 0) / (d.parent.value ?? 1)
-          : 1,
-      ...(heatVal !== undefined && { heat: heatVal }),
-      path,
-      ...(d.data.lineNumber !== undefined && { lineNumber: d.data.lineNumber }),
-    });
-  }
-
-  return { cells, total };
-}