@diagrammo/dgmo 0.37.0 → 0.38.0

package/docs/ai-integration.md

@@ -143,6 +143,7 @@ Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply
 | `quadrant` | 2×2 positioning matrix |
 | `pyramid` | stacked hierarchy of layers (Maslow, DIKW) |
 | `ring` | concentric rings of nested categories |
+| `treemap` | nested rectangles sized by value (budgets, disk usage, portfolios) |
 | `map` | geographic concept map: regions, points, routes |
 | `wireframe` | low-fidelity UI layout with panels and controls |
 | `bar` | categorical comparisons |

package/docs/language-reference.md

@@ -129,6 +129,7 @@ Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply
 | `quadrant` | 2×2 positioning matrix |
 | `pyramid` | stacked hierarchy of layers (Maslow, DIKW) |
 | `ring` | concentric rings of nested categories |
+| `treemap` | nested rectangles sized by value (budgets, disk usage, portfolios) |
 | `map` | geographic concept map: regions, points, routes |
 | `wireframe` | low-fidelity UI layout with panels and controls |
 | `bar` | categorical comparisons |
@@ -3089,6 +3090,100 @@ When ring band thickness would force the in-band label below the readable floor
 
 ---
 
+## 24C. Treemaps
+
+<!-- TYPE:treemap -->
+
+<!-- TIPS start -->
+**Styling tips:** Put the unit in the title (`Cloud Spend ($)`) — there is no currency/format directive. Reach for `depth N` once a tree goes past ~3 levels (deeper subtrees collapse to a drillable block) and `other-below N` to fold a long tail of tiny categories into one **Other** box. Pick the color mode to match intent: tags for categories, `heat` for a gain/loss heatmap, branch for zero-config structure.
+<!-- TIPS end -->
+
+Nested rectangles sized by value — the canonical way to show a hierarchy's proportions at a glance (budgets, disk usage, portfolios, taxonomies). Indentation is the hierarchy; a bare trailing number on a leaf is its size; parents auto-sum their children. Built on a squarified layout so cells keep good aspect ratios.
+
+### Declaration
+
+```
+treemap [Title with units, e.g. "Cloud Spend ($)"]
+
+Branch
+  Leaf 320
+  Leaf 180
+```
+
+### Example
+
+```
+treemap Q3 Budget
+
+tag Team as t
+  Eng blue
+  Sales green
+  Ops orange
+
+Engineering t: Eng
+  Platform 320
+  Mobile 180
+  Data 140
+Go-to-Market t: Sales
+  Ads 90
+  Field Sales 130
+Operations t: Ops
+  Cloud 110
+  Support 70
+```
+
+### Value & hierarchy
+
+- **Indentation** sets the hierarchy (same model as mindmap / org).
+- A **bare trailing number** on a leaf is its size (`Platform 320`) — the funnel/sankey idiom (§1.5). No thousands commas (`1_000` is fine).
+- **Parents auto-sum** their descendants; a trailing number on a branch line is ignored with a warning (auto-sum always wins).
+- To keep a label that genuinely ends in a digit, **quote it** (`"Region 5"`); unquoted `Region 5` parses as label `Region`, value `5`.
+
+### Color modes
+
+Three modes, with the source-declared default selected as **tag → heat → branch** (the desktop app adds a runtime switcher that previews the others without editing source):
+
+| Mode       | When it's the default       | Coloring                                                      |
+| ---------- | --------------------------- | ------------------------------------------------------------ |
+| **tag**    | a `tag` group is declared   | categorical color per tag value (legend hover-dims)          |
+| **heat**   | any `heat:` value / `heat` directive | value ramp over a second per-node `heat:` metric    |
+| **branch** | neither tags nor heat        | each top-level branch a distinct hue, tinted with depth      |
+
+### Tags
+
+Declare a `tag` group before content and apply it inline (`Engineering t: Eng`); children inherit the tag unless they override it. See §1.3.
+
+### Heat metric & ramp
+
+Add a per-node `heat:` number (a second metric, distinct from size; negatives/floats ok) and name the ramp with a `heat <Label> [low] [high]` directive. Colors are optional and **data-aware**: data that crosses zero defaults to a diverging `red·neutral·green` ramp with the midpoint pinned at 0; one-sign data defaults to a sequential `neutral·accent` ramp. One explicit color = `neutral→hue`; two = `low → high` (with a neutral midpoint). **Named palette colors only — no hex.** `heat:` is used instead of `score:` (which journey-map reserves for 1–5 emotion, §22).
+
+### Node Metadata
+
+| Key     | Type            | Default | Description                                  |
+| ------- | --------------- | ------- | -------------------------------------------- |
+| `heat`  | number          | —       | Color-by-value metric (signed / float ok)    |
+| `<tag>` | declared value  | —       | Tag value via the group's alias or name      |
+
+### Directives
+
+| Directive       | Effect                                                                                  |
+| --------------- | --------------------------------------------------------------------------------------- |
+| `heat <Label>`  | Name (and optionally color) the value ramp; pairs with the `heat:` key.                 |
+| `depth N`       | Render N levels; deeper subtrees collapse to a drillable solid block (a render budget).  |
+| `other-below N` | Roll children under N% of their parent into a single hatched **Other** bucket (opt-in).  |
+| `no-values`     | Hide value labels.                                                                       |
+| `no-percent`    | Hide percentage labels.                                                                  |
+| `no-headers`    | Hide parent header bars.                                                                 |
+| `no-legend`     | Hide the legend.                                                                         |
+
+Numbers auto-compact (1.2M, 940k). Units live in the title — there is no format/currency directive.
+
+### Interactivity vs export
+
+In the desktop app a treemap is interactive: click a parent to drill in (with a breadcrumb), hover for a tooltip (path / value / % / heat), and flip the color mode. Static SVG / PNG export is the clean, full tree with none of that chrome — the same interactive-vs-export split the map chart uses.
+
+---
+
 ## 24A. RACI Matrices (RACI / RASCI / DACI)
 
 <!-- TYPE:raci -->

package/gallery/fixtures/treemap-branch.dgmo

@@ -0,0 +1,15 @@
+treemap Cloud Spend ($)
+
+Compute
+  EC2 1240000
+  Lambda 180000
+  GPU 640000
+Storage
+  S3 420000
+  EBS 210000
+Network
+  Egress 380000
+  CDN 95000
+Data
+  Warehouse 540000
+  Streaming 160000

package/gallery/fixtures/treemap-heat.dgmo

@@ -0,0 +1,12 @@
+treemap Portfolio — today
+heat Day change %
+
+AAPL 180 heat: -2.4
+NVDA 220 heat: 4.1
+MSFT 160 heat: 0.8
+Energy
+  XOM 60 heat: -1.2
+  CVX 45 heat: -0.6
+Financials
+  JPM 70 heat: 1.9
+  BAC 40 heat: -3.1

package/gallery/fixtures/treemap-tag-heat.dgmo

@@ -0,0 +1,21 @@
+treemap Engineering Portfolio (effort, pts)
+
+tag Squad as sq
+  Platform blue
+  Product green
+  Infra orange
+
+heat Δ vs plan %
+
+Platform sq: Platform
+  API Gateway 120 heat: 4.0
+  Auth 80 heat: -6.5
+  Service Mesh 60 heat: 1.2
+Product sq: Product
+  Onboarding 140 heat: 8.1
+  Checkout 110 heat: -3.4
+  Search 70 heat: 0.5
+Infra sq: Infra
+  CI Pipeline 90 heat: -1.8
+  Observability 75 heat: 5.6
+  Cost Controls 50 heat: 2.3

package/gallery/fixtures/treemap-tags.dgmo

@@ -0,0 +1,18 @@
+treemap Q3 Budget
+
+tag Team as t
+  Eng blue
+  Sales green
+  Ops orange
+
+Engineering t: Eng
+  Platform 320
+  Mobile 180
+  Data 140
+Go-to-Market t: Sales
+  Ads 90
+  Field Sales 130
+  Events 40
+Operations t: Ops
+  Cloud 110
+  Support 70

package/package.json

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

package/src/advanced.ts

@@ -507,6 +507,17 @@ export { parseRing } from './ring/parser';
 export { renderRing, renderRingForExport } from './ring/renderer';
 export type { ParsedRing, RingLayer } from './ring/types';
 
+export { parseTreemap } from './treemap/parser';
+export { renderTreemap, renderTreemapForExport } from './treemap/renderer';
+export { layoutTreemap } from './treemap/layout';
+export type { TreemapCell, TreemapLayoutResult } from './treemap/layout';
+export type {
+  ParsedTreemap,
+  TreemapNode,
+  TreemapColorMode,
+  TreemapOptions,
+} from './treemap/types';
+
 // Map (§24B) — the interactive render surface for app/editor consumers. The
 // Node fs `loadMapData` is exported for completeness, but the browser supplies
 // `MapData` by DI (resolveMap/renderMap take it as an argument).

package/src/boxes-and-lines/layout-search.ts

@@ -933,6 +933,17 @@ export async function layoutBoxesAndLinesSearch(
   const tick = onProgress
     ? (): Promise<void> => new Promise<void>((r) => setTimeout(r))
     : (): undefined => undefined;
+  // Yielding is only worth its cost once a search is genuinely slow. A typical
+  // diagram finishes its whole candidate pool in tens of ms; yielding (a
+  // setTimeout, clamped to ~4ms/turn in browsers) after every one of ~90
+  // candidates would turn a 30ms layout into ~1s — all to flash a throbber that
+  // never shows (the app only reveals it after 150ms). So we suppress yields
+  // until the search has burned through a budget, then throttle them: fast
+  // diagrams run flat-out, only truly heavy ones cede the main thread to paint.
+  const YIELD_AFTER_MS = 150;
+  const YIELD_EVERY_MS = 30;
+  const searchStart = performance.now();
+  let lastYield = searchStart;
 
   // collapsed group labels (shown as plain boxes) — mirrors the ELK path
   const collapsedGroupLabels = new Set<string>();
@@ -1514,7 +1525,14 @@ export async function layoutBoxesAndLinesSearch(
   const step = async (phase: string): Promise<void> => {
     if (!onProgress) return;
     onProgress(++progressDone, progressTotal, phase);
-    await tick();
+    const now = performance.now();
+    if (
+      now - searchStart > YIELD_AFTER_MS &&
+      now - lastYield > YIELD_EVERY_MS
+    ) {
+      lastYield = now;
+      await tick();
+    }
   };
 
   // Build the candidate pool.

package/src/chart-type-registry.ts

@@ -66,6 +66,7 @@ import { parseCycle } from './cycle/parser';
 import { parseJourneyMap } from './journey-map/parser';
 import { parsePyramid } from './pyramid/parser';
 import { parseRing } from './ring/parser';
+import { parseTreemap } from './treemap/parser';
 import { parseRaci, allTasks } from './raci/parser';
 import type { DgmoError } from './diagnostics';
 
@@ -451,6 +452,9 @@ export const CHART_TYPE_REGISTRY: readonly ChartTypeDescriptor[] = [
   { id: 'cycle', category: 'visualization', parse: parseCycle },
   { id: 'pyramid', category: 'visualization', parse: parsePyramid },
   { id: 'ring', category: 'visualization', parse: parseRing },
+  // Treemap: squarified hierarchy. No measure/minDims — a treemap fills whatever
+  // rectangle it's given and has no intrinsic aspect/size (F11).
+  { id: 'treemap', category: 'visualization', parse: parseTreemap },
 
   // ── Geographic map (own parser → resolver → layout → renderer) ──
   { id: 'map', category: 'visualization', parse: parseMap },

package/src/chart-types.ts

@@ -122,6 +122,11 @@ export const chartTypes: readonly ChartTypeMeta[] = [
     description:
       'Concentric rings showing nested or hierarchical categories (read core-out)',
   },
+  {
+    id: 'treemap',
+    description:
+      'Nested rectangles sized by value — show a hierarchy’s proportions (budgets, disk usage, portfolios) with color by category, value heatmap, or branch',
+  },
   {
     id: 'map',
     description:

package/src/completion.ts

@@ -521,6 +521,24 @@ export const COMPLETION_REGISTRY = new Map<string, DirectiveSpec>([
     // layer pipe-metadata, not directives — they live in PIPE_METADATA.
     withGlobals({}),
   ],
+  [
+    'treemap',
+    // Hierarchy sized by a bare trailing number; color modes + opt-outs.
+    withGlobals({
+      heat: {
+        description:
+          'Name the color-by-value ramp (`heat <Label> [low] [high]`); pairs with the per-node `heat:` key',
+      },
+      depth: {
+        description:
+          'Render N levels; deeper subtrees collapse to a drillable block',
+      },
+      'no-values': { description: 'Hide value labels' },
+      'no-percent': { description: 'Hide percentage labels' },
+      'no-headers': { description: 'Hide parent header bars' },
+      'no-legend': { description: 'Hide the legend' },
+    }),
+  ],
   [
     'map',
     // Geographic map directives (§24B.2/.7). Cosmetics are ON by default — the
@@ -695,6 +713,7 @@ export const STRUCTURAL_KEYWORDS = new Map<string, string[]>([
   ['infra', ['tag']],
   ['pert', ['tag']],
   ['mindmap', ['tag']],
+  ['treemap', ['tag']],
   ['boxes-and-lines', ['tag']],
   ['er', ['tag']],
   ['cycle', ['direction-counterclockwise', 'circle-nodes']],
@@ -1828,6 +1847,50 @@ function extractMindmapSymbols(docText: string): DiagramSymbols {
   return { kind: 'mindmap', entities };
 }
 
+// ============================================================
+// Treemap extractor
+// ============================================================
+
+function extractTreemapSymbols(docText: string): DiagramSymbols {
+  const lines = docText.split('\n');
+  const entities: string[] = [];
+  let pastFirstLine = false;
+  let inTagBlock = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('//')) continue;
+
+    if (!pastFirstLine) {
+      pastFirstLine = true;
+      continue;
+    }
+
+    // Directives and tag blocks are not node entities.
+    if (
+      /^(depth|heat|no-[a-z]+)\s/i.test(trimmed) ||
+      /^no-[a-z]+$/i.test(trimmed)
+    )
+      continue;
+    if (/^tag\s+/i.test(trimmed)) {
+      inTagBlock = true;
+      continue;
+    }
+    const indent = line.search(/\S/);
+    if (inTagBlock) {
+      if (indent > 0) continue;
+      inTagBlock = false;
+    }
+
+    // Node name: strip same-line metadata + the bare trailing value number.
+    let label = trimmed.split(/\s+\w+:/)[0]!.trim();
+    label = label.replace(/\s+-?\d[\d_,.]*$/, '').trim();
+    if (label && !entities.includes(label)) entities.push(label);
+  }
+
+  return { kind: 'treemap', entities };
+}
+
 // ============================================================
 // Pyramid extractor
 // ============================================================
@@ -2311,6 +2374,7 @@ registerExtractor('daci', extractRaciSymbols);
 registerExtractor('org', extractOrgSymbols);
 registerExtractor('kanban', extractKanbanSymbols);
 registerExtractor('mindmap', extractMindmapSymbols);
+registerExtractor('treemap', extractTreemapSymbols);
 registerExtractor('pyramid', extractPyramidSymbols);
 registerExtractor('ring', extractRingSymbols);
 registerExtractor('arc', extractArcSymbols);

package/src/d3.ts

@@ -117,6 +117,7 @@ export const DIAGRAM_EXPORT_HANDLERS: Record<string, DiagramExportHandler> = {
   map: exportMap,
   pyramid: exportPyramid,
   ring: exportRing,
+  treemap: exportTreemap,
   raci: exportRaci,
   rasci: exportRaci,
   daci: exportRaci,
@@ -962,12 +963,33 @@ async function exportRing(ctx: ExportContext): Promise<string> {
   if (ringParsed.error || ringParsed.layers.length === 0) return '';
 
   const container = createExportContainer(EXPORT_WIDTH, EXPORT_HEIGHT);
-  renderRingForExport(
+  renderRingForExport(container, ringParsed, effectivePalette, ctx.isDark, {
+    width: EXPORT_WIDTH,
+    height: EXPORT_HEIGHT,
+  });
+  return finalizeSvgExport(container, theme, effectivePalette);
+}
+
+async function exportTreemap(ctx: ExportContext): Promise<string> {
+  const { content, theme, palette } = ctx;
+  const { parseTreemap } = await import('./treemap/parser');
+  const { renderTreemapForExport } = await import('./treemap/renderer');
+
+  const effectivePalette = await resolveExportPalette(theme, palette);
+  const treemapParsed = parseTreemap(content, effectivePalette);
+  if (treemapParsed.error || treemapParsed.roots.length === 0) return '';
+
+  // Headless export: full tree (no depth window), source-declared color mode.
+  const container = createExportContainer(EXPORT_WIDTH, EXPORT_HEIGHT);
+  renderTreemapForExport(
     container,
-    ringParsed,
+    treemapParsed,
     effectivePalette,
     ctx.isDark,
-    { width: EXPORT_WIDTH, height: EXPORT_HEIGHT }
+    {
+      width: EXPORT_WIDTH,
+      height: EXPORT_HEIGHT,
+    }
   );
   return finalizeSvgExport(container, theme, effectivePalette);
 }
@@ -982,13 +1004,10 @@ async function exportRaci(ctx: ExportContext): Promise<string> {
   if (raciParsed.error) return '';
 
   const container = createExportContainer(EXPORT_WIDTH, EXPORT_HEIGHT);
-  renderRaciForExport(
-    container,
-    raciParsed,
-    effectivePalette,
-    ctx.isDark,
-    { width: EXPORT_WIDTH, height: EXPORT_HEIGHT }
-  );
+  renderRaciForExport(container, raciParsed, effectivePalette, ctx.isDark, {
+    width: EXPORT_WIDTH,
+    height: EXPORT_HEIGHT,
+  });
   return finalizeSvgExport(container, theme, effectivePalette);
 }
 
@@ -1091,14 +1110,7 @@ async function exportVenn(ctx: ExportContext): Promise<string> {
   if (parsed.error || parsed.vennSets.length < 2) return '';
   const effectivePalette = await resolveExportPalette(theme, palette);
   const { container, dims } = beginVizExport();
-  renderVenn(
-    container,
-    parsed,
-    effectivePalette,
-    ctx.isDark,
-    undefined,
-    dims
-  );
+  renderVenn(container, parsed, effectivePalette, ctx.isDark, undefined, dims);
   return finalizeSvgExport(container, theme, effectivePalette);
 }
 

package/src/editor/highlight-api.ts

@@ -213,6 +213,8 @@ export const ATTRIBUTE_KEYS = new Set([
   'value',
   'label',
   'style',
+  // Treemap color-by-value metric key
+  'heat',
   // Infra node behavior + edge colon-keys (§4) come from the single-source
   // directives registry — the parser accepts them only as `key: value` node
   // properties, so they render as `propertyName`. The dual-use top-level SLO

package/src/editor/keywords.ts

@@ -27,6 +27,7 @@ export const CHART_TYPES = new Set([
   'journey-map',
   'pyramid',
   'ring',
+  'treemap',
   'raci',
   'rasci',
   'daci',
@@ -91,6 +92,8 @@ export const METADATA_KEYS = new Set([
   'value',
   'label',
   'style',
+  // Treemap color-by-value metric key
+  'heat',
 ]);
 
 /** Tag declaration keyword. */

package/src/map/dimensions.ts

@@ -32,6 +32,13 @@ const TITLE_GAP = 16;
 //                       width:100% in a narrow note column stays sane.
 const ASPECT_MAX = 3.0;
 const ASPECT_MIN = 0.9;
+// Deliberate vertical boost for GLOBAL (whole-world) extents only. An honest
+// whole-world projection is ~2.4:1, which reads as a flat letterbox band. We emit
+// a canvas this fraction taller and let the global stretch-fill (layout.ts) fill
+// the extra height — the projected land stretches ~12% taller while POI radii and
+// label fonts (applied in the renderer, not here) stay un-squashed. US, regional,
+// and non-global extents are untouched (they keep their true projected aspect).
+const GLOBAL_HEIGHT_BOOST = 1.12;
 // Minimum px of actual map area (below the chrome band) — keeps a short canvas
 // (very wide extent) from being crowded out by the title/caption.
 const MIN_MAP_BAND = 200;
@@ -96,11 +103,21 @@ export function mapExportDimensions(
     Number.isFinite(aspectOverride) &&
     aspectOverride > 0;
   const raw = useOverride ? aspectOverride : mapContentAspect(resolved, data);
+  // Whole-world extents get the vertical boost (a taller canvas the global
+  // stretch-fill then fills). `fitIsGlobal` is the SAME classification the layout
+  // uses to decide stretch-fill vs contain, so the two always agree. The override
+  // path (app WYSIWYG) and non-global extents pass through at their true aspect.
+  const isGlobal =
+    !useOverride && buildMapProjection(resolved, data).fitIsGlobal;
+  // The target the renderer should hit BEFORE the pathological clamp: the boosted
+  // aspect for global views, the raw aspect otherwise. preferContain compares the
+  // clamp against THIS (not raw) so the deliberate boost never trips the letterbox.
+  const target = isGlobal ? raw / GLOBAL_HEIGHT_BOOST : raw;
   // The override is the user's on-screen aspect — honour it as-is (no clamp);
   // only the intrinsic path guards against pathological extents.
   const clamped = useOverride
     ? raw
-    : Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
+    : Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, target));
   const width = baseWidth;
   let height = Math.round(width / clamped);
 
@@ -128,6 +145,6 @@ export function mapExportDimensions(
   // contain-fit (letterbox) rather than stretch-distort. The WYSIWYG override is
   // exempt: it stretch-fills (mirroring the preview pane) unless the MIN_MAP_BAND
   // floor had to grow the canvas off-aspect.
-  const preferContain = useOverride ? floored : clamped !== raw || floored;
+  const preferContain = useOverride ? floored : clamped !== target || floored;
   return { width, height, preferContain };
 }