@svgrid/grid 3.0.2 → 3.0.4

package/src/chart-flow.ts

@@ -0,0 +1,286 @@
+/**
+ * Flow layouts: waterfall, funnel and sankey.
+ */
+import type { ChartBar, ChartLine, ChartAxisTick, ChartCategoryTick, ChartFunnelSegment, ChartSankeyNode, ChartSankeyLink, ChartGeometry, LayoutCtx } from './chart-types'
+import { round, niceScale, formatChartValue, pickContrastText, DEFAULT_PALETTE } from './chart-scale'
+
+// ---- Waterfall ----------------------------------------------------
+// First series provides the values. Each non-total bar starts at the
+// running cumulative sum; total bars (waterfallTotals[i]) span from 0 to
+// that sum, and a total with a value of its own sets the sum to it first
+// (the opening balance of a bridge, or a subtotal supplied by the caller).
+// Color is derived from sign + total flag, with optional palette overrides
+// via spec.waterfallColors.
+/** @internal Lay out the waterfall family. Called by buildChart. */
+export function layoutWaterfall(ctx: LayoutCtx): ChartGeometry {
+  const { spec, series, width, height, empty, frame, axes } = ctx
+  const src = series[0]
+  if (!src) return { ...empty }
+  const colors = spec.waterfallColors ?? {}
+  const positive = colors.positive ?? '#16a34a'
+  const negative = colors.negative ?? '#ef4444'
+  const total    = colors.total    ?? '#475569'
+
+  const maxLabel = spec.categories.reduce((m, c) => Math.max(m, c.length), 0)
+  const padL = 48 + (axes.y.title ? 16 : 0)
+  const padR = 12
+  const padT = 10 + frame.top
+  const plotW = Math.max(1, width - padL - padR)
+  // The same rule as a bar chart: labels tilt when the widest does not fit
+  // its slot. Judged by count alone, nine categories on a 900px chart were
+  // flagged as rotated with no angle to go with it, and drew truncated.
+  const xLabelRotated = typeof axes.x.labelRotation === 'number' ? axes.x.labelRotation !== 0 : maxLabel * 6.2 + 8 > plotW / Math.max(1, spec.categories.length)
+  const xLabelAngle = typeof axes.x.labelRotation === 'number' ? axes.x.labelRotation : xLabelRotated ? -40 : 0
+  const padB = (xLabelRotated ? 54 : 28) + (axes.x.title ? 16 : 0) + frame.bottom
+  const plotH = Math.max(1, height - padT - padB)
+  const plot = { x: padL, y: padT, w: plotW, h: plotH }
+
+  // Compute the running cumulative + per-bar (from, to) pairs.
+  const totals = spec.waterfallTotals ?? []
+  const pairs: Array<{ from: number; to: number; value: number; isTotal: boolean }> = []
+  let cum = 0
+  spec.categories.forEach((_, i) => {
+    const v = src.values[i] ?? 0
+    const isTotal = !!totals[i]
+    if (isTotal) {
+      // An opening "Revenue 4300" is a total with a value: it anchors the
+      // running sum. Read as a computed subtotal it drew as zero and every
+      // bar after it hung below the axis.
+      if (Number.isFinite(v) && v !== 0) cum = v
+      pairs.push({ from: 0, to: cum, value: cum, isTotal: true })
+    } else {
+      pairs.push({ from: cum, to: cum + v, value: v, isTotal: false })
+      cum += v
+    }
+  })
+  // Y-axis domain spans every visited level (including 0).
+  let dMin = 0, dMax = 0
+  for (const p of pairs) {
+    if (p.from < dMin) dMin = p.from
+    if (p.to   < dMin) dMin = p.to
+    if (p.from > dMax) dMax = p.from
+    if (p.to   > dMax) dMax = p.to
+  }
+  const dom = niceScale(dMin, dMax)
+  const yOfW = (v: number) => round(padT + plotH - ((v - dom.min) / (dom.max - dom.min || 1)) * plotH)
+
+  const slotW = plotW / Math.max(1, spec.categories.length)
+  const barPad = slotW * 0.2
+  const barW = Math.max(1, slotW - barPad)
+  const bars: ChartBar[] = pairs.map((p, i) => {
+    const yTop = yOfW(Math.max(p.from, p.to))
+    const yBot = yOfW(Math.min(p.from, p.to))
+    const x = padL + slotW * i + barPad / 2
+    const color = p.isTotal ? total : p.value >= 0 ? positive : negative
+    return {
+      x: round(x), y: yTop, w: round(barW), h: Math.max(1, yBot - yTop),
+      color, label: spec.categories[i] ?? String(i), series: src.label, value: p.value, index: i,
+    }
+  })
+  // Thin connector lines between bar tops -> running total reads cleanly.
+  const connectors: ChartLine[] = [{
+    path: pairs
+      .map((p, i) => {
+        const x0 = padL + slotW * i + barPad / 2 + barW
+        const y  = yOfW(p.to)
+        const x1 = padL + slotW * (i + 1) + barPad / 2
+        // Skip the final connector beyond the last bar.
+        return i < pairs.length - 1 ? `M${x0},${y} L${x1},${y}` : ''
+      })
+      .filter(Boolean)
+      .join(' '),
+    areaPath: '',
+    color: 'var(--sg-muted, #94a3b8)',
+    label: '',
+    points: [],
+  }]
+  const xTicks: ChartCategoryTick[] = spec.categories.map((label, i) => ({
+    label,
+    x: round(padL + slotW * i + slotW / 2),
+  }))
+  const yTicks: ChartAxisTick[] = dom.ticks.map((value) => ({
+    value, y: yOfW(value), label: formatChartValue(value, spec.valueFormat, spec),
+  }))
+  return {
+    ...empty,
+    plot,
+    bars,
+    lines: connectors,
+    yTicks,
+    xTicks,
+    xLabelRotated,
+    xLabelAngle,
+  }
+}
+
+// ---- Funnel -------------------------------------------------------
+// One series of strictly-decreasing values gets rendered as a stack
+// of horizontal trapezoids: each level's width is proportional to its
+// value relative to the largest, slope automatically links level N+1
+// narrower than level N. Labels show value, conversion vs. top, and
+// step drop-off.
+/** @internal Lay out the funnel family. Called by buildChart. */
+export function layoutFunnel(ctx: LayoutCtx): ChartGeometry {
+  const { spec, series, width, height, empty, frame } = ctx
+  const src = series[0]
+  if (!src || !src.values.length) return { ...empty }
+  const padL = 20, padR = 20, padT = 16 + frame.top, padB = 16 + frame.bottom
+  const plotW = Math.max(1, width - padL - padR)
+  const plotH = Math.max(1, height - padT - padB)
+  const plot = { x: padL, y: padT, w: plotW, h: plotH }
+  const n = src.values.length
+  const stepH = plotH / n
+  const valMax = Math.max(...src.values.map((v) => (Number.isFinite(v) ? v : 0)))
+  const top = src.values[0] ?? 0
+  const widthAt = (v: number) => (valMax > 0 ? (v / valMax) * plotW : 0)
+  const cx = padL + plotW / 2
+  const palette = spec.palette ?? DEFAULT_PALETTE
+  const shape = spec.funnelShape ?? 'trapezoid'
+  const segments: ChartFunnelSegment[] = src.values.map((v, i) => {
+    const next = src.values[i + 1] ?? v * 0.8   // taper to a point on the last level
+    const y0 = padT + stepH * i
+    const y1 = y0 + stepH
+    let path: string
+    if (shape === 'pyramid') {
+      // Widest at the bottom: a pyramid of levels, each a slice of one big
+      // triangle. The top level is the point.
+      const wTop = (plotW * i) / n
+      const wBot = (plotW * (i + 1)) / n
+      path = `M${cx - wTop / 2},${y0} L${cx + wTop / 2},${y0} L${cx + wBot / 2},${y1} L${cx - wBot / 2},${y1} Z`
+    } else if (shape === 'cone') {
+      // One triangle, sliced: the width at each level follows its share of
+      // the height, so the whole funnel is a cone that tapers to a point.
+      const wTop = plotW * (1 - i / n)
+      const wBot = plotW * (1 - (i + 1) / n)
+      path = `M${cx - wTop / 2},${y0} L${cx + wTop / 2},${y0} L${cx + wBot / 2},${y1} L${cx - wBot / 2},${y1} Z`
+    } else {
+      const w0 = widthAt(v)
+      const w1 = widthAt(next)
+      path = `M${cx - w0 / 2},${y0} L${cx + w0 / 2},${y0} L${cx + w1 / 2},${y1} L${cx - w1 / 2},${y1} Z`
+    }
+    const color = src.color ?? palette[i % palette.length]!
+    return {
+      path, color,
+      label: spec.categories[i] ?? src.label,
+      value: v,
+      conversion: top > 0 ? v / top : 0,
+      dropoff: i === 0 ? 0 : (src.values[i - 1] ?? v) > 0 ? 1 - v / (src.values[i - 1] ?? v) : 0,
+      cx,
+      cy: (y0 + y1) / 2,
+      textColor: pickContrastText(color),
+    }
+  })
+  return {
+    ...empty,
+    plot,
+    funnelSegments: segments,
+  }
+}
+
+// ---- Sankey -------------------------------------------------------
+// Multi-column flow layout. Each node assigned to a column by longest
+// path from any source. Within a column, nodes are stacked vertically;
+// height proportional to max(totalIn, totalOut). Links render as
+// bezier ribbons whose width is the link value (in pixels).
+/** @internal Lay out the sankey family. Called by buildChart. */
+export function layoutSankey(ctx: LayoutCtx): ChartGeometry {
+  const { spec, width, height, empty, frame } = ctx
+  const nodes = spec.sankeyNodes ?? []
+  const links = spec.sankeyLinks ?? []
+  if (!nodes.length || !links.length) return { ...empty }
+  const padL = 10, padR = 10, padT = 14 + frame.top, padB = 14 + frame.bottom
+  const plotW = Math.max(1, width - padL - padR)
+  const plotH = Math.max(1, height - padT - padB)
+  const plot = { x: padL, y: padT, w: plotW, h: plotH }
+  const palette = spec.palette ?? DEFAULT_PALETTE
+  const nodeById = new Map(nodes.map((n) => [n.id, n]))
+  // Column = longest path from any node with no incoming edges.
+  const targets = new Set(links.map((l) => l.target))
+  const sources = nodes.filter((n) => !targets.has(n.id))
+  const column = new Map<string, number>()
+  function visit(id: string, depth: number, seen: Set<string>) {
+    if (seen.has(id)) return
+    seen.add(id)
+    const cur = column.get(id) ?? 0
+    if (depth > cur || !column.has(id)) column.set(id, depth)
+    for (const l of links) if (l.source === id) visit(l.target, depth + 1, seen)
+    seen.delete(id)
+  }
+  for (const s of sources) visit(s.id, 0, new Set())
+  // Cover any nodes with no path from a source (orphan rings).
+  for (const n of nodes) if (!column.has(n.id)) column.set(n.id, 0)
+  const maxCol = Math.max(...column.values())
+  const cols = maxCol + 1
+  const nodeW = 14
+  const gapBetweenColumns = cols > 1 ? (plotW - nodeW * cols) / (cols - 1) : 0
+  // Totals per node.
+  const totalIn = new Map<string, number>()
+  const totalOut = new Map<string, number>()
+  for (const l of links) {
+    totalIn.set(l.target, (totalIn.get(l.target) ?? 0) + l.value)
+    totalOut.set(l.source, (totalOut.get(l.source) ?? 0) + l.value)
+  }
+  // Per-column groups + max total in that column.
+  const byCol: Map<number, string[]> = new Map()
+  for (const n of nodes) {
+    const c = column.get(n.id) ?? 0
+    const arr = byCol.get(c) ?? []
+    arr.push(n.id); byCol.set(c, arr)
+  }
+  // Per-column total height + node height scale.
+  let maxColTotal = 0
+  for (const ids of byCol.values()) {
+    const t = ids.reduce((s, id) => s + Math.max(totalIn.get(id) ?? 0, totalOut.get(id) ?? 0), 0)
+    if (t > maxColTotal) maxColTotal = t
+  }
+  if (maxColTotal === 0) return { ...empty, plot }
+  const nodeGapPx = 8
+  const heightScale = (plotH - nodeGapPx * 8) / maxColTotal  // leave gap room
+  const placed: ChartSankeyNode[] = []
+  for (const [c, ids] of byCol) {
+    const heights = ids.map((id) => Math.max(8, Math.max(totalIn.get(id) ?? 0, totalOut.get(id) ?? 0) * heightScale))
+    const totalH = heights.reduce((s, h) => s + h, 0) + nodeGapPx * (ids.length - 1)
+    let yCursor = padT + (plotH - totalH) / 2
+    const xCol = padL + c * (nodeW + gapBetweenColumns)
+    ids.forEach((id, idx) => {
+      const node = nodeById.get(id)!
+      const h = heights[idx]!
+      placed.push({
+        id,
+        label: node.label ?? id,
+        color: node.color ?? palette[(placed.length) % palette.length]!,
+        x: xCol, y: yCursor, w: nodeW, h,
+        column: c,
+        totalIn: totalIn.get(id) ?? 0,
+        totalOut: totalOut.get(id) ?? 0,
+      })
+      yCursor += h + nodeGapPx
+    })
+  }
+  const placedById = new Map(placed.map((n) => [n.id, n]))
+  // Per-node sub-cursor so multiple links from one node stack vertically.
+  const inCursor = new Map<string, number>()
+  const outCursor = new Map<string, number>()
+  const builtLinks: ChartSankeyLink[] = []
+  // Sort links so wider ribbons render first (so thin ribbons stack on top).
+  const sortedLinks = links.slice().sort((a, b) => b.value - a.value)
+  for (const link of sortedLinks) {
+    const a = placedById.get(link.source)
+    const b = placedById.get(link.target)
+    if (!a || !b) continue
+    const linkH = Math.max(1, link.value * heightScale)
+    const aY = a.y + (outCursor.get(a.id) ?? 0) + linkH / 2
+    const bY = b.y + (inCursor.get(b.id) ?? 0) + linkH / 2
+    outCursor.set(a.id, (outCursor.get(a.id) ?? 0) + linkH)
+    inCursor.set(b.id, (inCursor.get(b.id) ?? 0) + linkH)
+    const x0 = a.x + a.w
+    const x1 = b.x
+    const mid = (x0 + x1) / 2
+    const path = `M${x0},${aY} C${mid},${aY} ${mid},${bY} ${x1},${bY}`
+    builtLinks.push({
+      path, color: link.color ?? a.color, width: linkH,
+      source: link.source, target: link.target, value: link.value,
+    })
+  }
+  return { ...empty, plot, sankeyNodes: placed, sankeyLinks: builtLinks }
+}

package/src/chart-format.ts

@@ -0,0 +1,67 @@
+/**
+ * Number formatting for chart values: the compact `1.2k` tick label and
+ * `formatChartValue`, which honours a spec's `valueFormat`, `locale` and
+ * `currency`.
+ *
+ * A leaf of its own, and deliberately small. The chart engine and the lazily
+ * loaded summary (chart-summary.ts) both need it, and a bundler hoists
+ * whatever the base chunk and a lazy chunk share into a third chunk. When
+ * that shared module was all of chart-scale.ts the hoist cost the base
+ * bundle a kilobyte of gzip locality for no new code; two functions cost a
+ * few dozen bytes. chart-scale.ts re-exports both, so importers of the old
+ * home keep working.
+ */
+import { getNumberFormatter } from './cell-formatting'
+import type { ChartFormatLocale, ChartValueFormat } from './chart-types'
+
+/** @internal Locale-free compact tick label (1.2k / 1.2M). */
+export function fmtTick(n: number): string {
+  const abs = Math.abs(n)
+  if (abs >= 1_000_000) return `${(n / 1_000_000).toFixed(abs % 1_000_000 ? 1 : 0)}M`
+  if (abs >= 1_000) return `${(n / 1_000).toFixed(abs % 1_000 ? 1 : 0)}k`
+  return String(Math.round(n * 100) / 100)
+}
+
+/**
+ * Format a numeric value for display, honouring an optional `valueFormat`.
+ *
+ * Two modes, on purpose. With no `locale` and no `currency` this is the original
+ * locale-free output: the compact `1.2k` / `1.2M` base, currency prefixed with
+ * `$` (sign outside), percent multiplied by 100 and suffixed `%`. Set either one
+ * and it switches to `Intl.NumberFormat`, so separators, the decimal mark and the
+ * compact suffixes all follow the locale.
+ *
+ * Keeping the old path as the default is deliberate rather than lazy. `Intl`'s
+ * compact notation is not the same string even for `en-US` (`1.2K`, capital),
+ * so formatting everything through it would silently restyle every axis in every
+ * existing chart. Opting in is the only version of this that is not a surprise.
+ */
+export function formatChartValue(
+  n: number,
+  format?: ChartValueFormat,
+  opts?: ChartFormatLocale,
+): string {
+  if (!Number.isFinite(n)) return ''
+  const localized = opts && (opts.locale || opts.currency)
+  if (localized) {
+    // Compact notation because these are axis ticks and data labels, where a
+    // full-precision number is what makes an axis unreadable.
+    const style = format === 'currency' ? 'currency' : format === 'percent' ? 'percent' : 'decimal'
+    const o: Intl.NumberFormatOptions = { notation: 'compact', maximumFractionDigits: 1 }
+    if (style === 'currency') {
+      o.style = 'currency'
+      // `style: 'currency'` throws without a code, so fall back to the symbol
+      // this used to hard-code rather than refusing to draw the chart.
+      o.currency = opts!.currency || 'USD'
+    } else if (style === 'percent') {
+      o.style = 'percent'
+    }
+    return getNumberFormatter(opts!.locale, o).format(n)
+  }
+  if (format === 'currency') return `${n < 0 ? '-' : ''}$${fmtTick(Math.abs(n))}`
+  if (format === 'percent') {
+    const p = n * 100
+    return `${Math.round(p * 10) / 10}%`
+  }
+  return fmtTick(n)
+}

package/src/chart-grid.ts

@@ -0,0 +1,179 @@
+/**
+ * Grid layouts: heatmap and the calendar heatmap.
+ */
+import type { ChartAxisTick, ChartCategoryTick, ChartCalendarCell, ChartHeatmapCell, ChartGeometry, LayoutCtx } from './chart-types'
+import { round, formatChartValue, resolveColorScale, sampleGradient, pickContrastText, thinCategoryTicks } from './chart-scale'
+
+// ---- Calendar heatmap --------------------------------------------
+// GitHub-style year-of-days view: 7 rows (Sun..Sat) x N weeks. Each
+// cell is a small square shaded by `calendarValues[i].value` via the
+// sequential color scale. Days with no value render blank (border only)
+// so missing data is visually obvious.
+/** @internal Lay out the calendar family. Called by buildChart. */
+export function layoutCalendar(ctx: LayoutCtx): ChartGeometry {
+  const { spec, width, height, theme, empty, frame } = ctx
+  const values = spec.calendarValues ?? []
+  if (!values.length && !spec.calendarStart) return { ...empty }
+  // Build a value lookup + figure out the date range.
+  const valueByDate = new Map<string, number>()
+  let vMin = Infinity, vMax = -Infinity
+  for (const v of values) {
+    valueByDate.set(v.date, v.value)
+    if (Number.isFinite(v.value)) {
+      if (v.value < vMin) vMin = v.value
+      if (v.value > vMax) vMax = v.value
+    }
+  }
+  if (vMin === Infinity) { vMin = 0; vMax = 1 }
+  if (vMin === vMax) vMax = vMin + 1
+  const stops = resolveColorScale(spec.colorScale, vMin, vMax, theme)
+  const colorAt = (v: number) => sampleGradient(stops, (v - vMin) / (vMax - vMin))
+  // Determine date range. If calendarStart/End set, use them, otherwise
+  // span the data + round to whole weeks (Sun..Sat).
+  const sorted = values.map((v) => v.date).sort()
+  const startStr = spec.calendarStart ?? sorted[0] ?? '2026-01-01'
+  const endStr   = spec.calendarEnd   ?? sorted[sorted.length - 1] ?? startStr
+  const start = new Date(startStr + 'T00:00:00Z')
+  const end   = new Date(endStr + 'T00:00:00Z')
+  // Roll start back to its Sunday, end forward to its Saturday.
+  start.setUTCDate(start.getUTCDate() - start.getUTCDay())
+  end.setUTCDate(end.getUTCDate() + (6 - end.getUTCDay()))
+  const totalDays = Math.round((end.getTime() - start.getTime()) / 86_400_000) + 1
+  const weeks = Math.ceil(totalDays / 7)
+  const padL = 36, padR = 80, padT = 26 + frame.top, padB = 16 + frame.bottom
+  const plotW = Math.max(1, width - padL - padR)
+  const plotH = Math.max(1, height - padT - padB)
+  // Cell size: fit weeks across width, 7 rows down height.
+  const cellW = Math.floor(plotW / weeks)
+  const cellH = Math.floor(plotH / 7)
+  const cellSize = Math.max(6, Math.min(cellW, cellH))
+  const plot = { x: padL, y: padT, w: cellSize * weeks, h: cellSize * 7 }
+  const cells: ChartCalendarCell[] = []
+  let lastMonth = -1
+  const monthTicks: ChartCategoryTick[] = []
+  for (let i = 0; i < totalDays; i += 1) {
+    const day = new Date(start.getTime() + i * 86_400_000)
+    const col = Math.floor(i / 7)
+    const row = i % 7
+    const date = day.toISOString().slice(0, 10)
+    const has = valueByDate.has(date)
+    const v = valueByDate.get(date) ?? 0
+    cells.push({
+      x: padL + col * cellSize,
+      y: padT + row * cellSize,
+      size: cellSize,
+      date, value: v,
+      defined: has,
+      color: has ? colorAt(v) : 'transparent',
+    })
+    // A month label only for a month inside the range: the end is rolled
+    // forward to its Saturday, and a December that ends on a Thursday used
+    // to pick up a "Jan" for the two padding days of the next year.
+    if (day.getUTCDate() === 1 && day.getUTCMonth() !== lastMonth && date >= startStr && date <= endStr) {
+      lastMonth = day.getUTCMonth()
+      monthTicks.push({
+        label: day.toLocaleDateString(undefined, { month: 'short' }),
+        x: padL + col * cellSize,
+      })
+    }
+  }
+  const legend = Array.from({ length: 5 }, (_, i) => {
+    const t = i / 4
+    const value = legendValue(vMin, vMax, t)
+    return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat, spec) }
+  })
+  return {
+    ...empty,
+    plot,
+    calendarCells: cells,
+    calendarMonthTicks: monthTicks,
+    calendarLegend: legend,
+  }
+}
+
+// ---- Heatmap ------------------------------------------------------
+// Each series is one row, series.values are the cells across categories.
+// Color comes from a sequential/diverging/custom palette mapped to the
+// global value range. Cell text contrasts black/white against the cell.
+/**
+ * A legend step between the extremes, rounded to the precision the range
+ * earns: whole numbers when the steps are a unit or more apart, so a count
+ * legend reads "20, 94, 167" rather than "20, 93.5, 167", and enough
+ * decimals to tell the steps apart when they are not.
+ */
+function legendValue(vMin: number, vMax: number, t: number): number {
+  const raw = vMin + (vMax - vMin) * t
+  const step = Math.abs(vMax - vMin) / 4
+  if (!(step > 0)) return raw
+  const decimals = step >= 1 ? 0 : Math.min(6, Math.ceil(-Math.log10(step)) + 1)
+  return Number(raw.toFixed(decimals))
+}
+
+/** @internal Lay out the heatmap family. Called by buildChart. */
+export function layoutHeatmap(ctx: LayoutCtx): ChartGeometry {
+  const { spec, series, width, height, theme, empty, frame } = ctx
+  if (!series.length || !spec.categories.length) return { ...empty, plot: { x: 0, y: 0, w: width, h: height } }
+  // Layout: left gutter for row labels, bottom for column labels.
+  const maxRowLabel = series.reduce((m, s) => Math.max(m, s.label.length), 0)
+  const padL = 12 + Math.min(180, Math.max(60, maxRowLabel * 7))
+  const padR = 64   // room for the right-side legend bar
+  const padT = 12 + frame.top
+  const padB = 32 + frame.bottom
+  const plotW = Math.max(1, width - padL - padR)
+  const plotH = Math.max(1, height - padT - padB)
+  const plot = { x: padL, y: padT, w: plotW, h: plotH }
+  const cellW = plotW / spec.categories.length
+  const cellH = plotH / series.length
+  // Resolve value range across the whole matrix.
+  let vMin = Infinity, vMax = -Infinity
+  for (const s of series) for (const v of s.values) {
+    if (!Number.isFinite(v)) continue
+    if (v < vMin) vMin = v
+    if (v > vMax) vMax = v
+  }
+  if (vMin === Infinity) { vMin = 0; vMax = 1 }
+  if (vMin === vMax) vMax = vMin + 1
+  // Pick the palette stops.
+  const stops = resolveColorScale(spec.colorScale, vMin, vMax, theme)
+  const colorAt = (v: number) => sampleGradient(stops, (v - vMin) / (vMax - vMin))
+  const heatmapCells: ChartHeatmapCell[] = []
+  series.forEach((s, ri) => {
+    s.values.forEach((v, ci) => {
+      if (!Number.isFinite(v)) return
+      const color = colorAt(v)
+      heatmapCells.push({
+        x: round(padL + cellW * ci),
+        y: round(padT + cellH * ri),
+        w: round(cellW),
+        h: round(cellH),
+        color,
+        textColor: pickContrastText(color),
+        value: v,
+        rowLabel: s.label,
+        colLabel: spec.categories[ci] ?? '',
+      })
+    })
+  })
+  const heatmapRowTicks: ChartAxisTick[] = series.map((s, i) => ({
+    value: i,
+    y: round(padT + cellH * i + cellH / 2),
+    label: s.label,
+  }))
+  // Column labels thin out the way a bar chart's do: twenty-four hours at
+  // 33px a cell wrote "00:0001:0002:00" across the foot of the matrix.
+  const heatmapColTicks: ChartCategoryTick[] = thinCategoryTicks(spec.categories, (i) => round(padL + cellW * i + cellW / 2), cellW, false)
+  // Legend: sample 5 stops across the range.
+  const heatmapLegend = Array.from({ length: 5 }, (_, i) => {
+    const t = i / 4
+    const value = legendValue(vMin, vMax, t)
+    return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat, spec) }
+  })
+  return {
+    ...empty,
+    plot,
+    heatmapCells,
+    heatmapRowTicks,
+    heatmapColTicks,
+    heatmapLegend,
+  }
+}

package/src/chart-hierarchy.ts

@@ -0,0 +1,135 @@
+/**
+ * Hierarchy layouts: the squarified tree-map.
+ */
+import type { ChartTreemapCell, TreeNode, ChartGeometry, LayoutCtx } from './chart-types'
+import { round, pickContrastText, DEFAULT_PALETTE } from './chart-scale'
+
+// ---- Tree-map -----------------------------------------------------
+// Squarified tree-map (Bruls et al. 2000): each level recursively
+// partitions its rectangle in proportion to its children, picking the
+// split orientation that keeps aspect ratios closest to 1.
+/** @internal Lay out the treemap family. Called by buildChart. */
+export function layoutTreemap(ctx: LayoutCtx): ChartGeometry {
+  const { spec, width, height, empty, frame } = ctx
+  const root = spec.treemap ?? spec.tree
+  if (!root) return { ...empty }
+  const padL = 4, padR = 4, padT = 4 + frame.top, padB = 4 + frame.bottom
+  const plotW = Math.max(1, width - padL - padR)
+  const plotH = Math.max(1, height - padT - padB)
+  const plot = { x: padL, y: padT, w: plotW, h: plotH }
+  const palette = spec.palette ?? DEFAULT_PALETTE
+  const cells: ChartTreemapCell[] = []
+  function totalOf(n: TreeNode): number {
+    if (n.children?.length) return n.children.reduce((s, c) => s + totalOf(c), 0)
+    return Math.max(0, n.value ?? 0)
+  }
+  function squarify(items: TreeNode[], x: number, y: number, w: number, h: number, depth: number) {
+    if (!items.length || w <= 0 || h <= 0) return
+    const totals = items.map(totalOf)
+    const sum = totals.reduce((a, b) => a + b, 0)
+    if (sum <= 0) return
+    // Process largest-first so big items dominate the first row.
+    const ordered = items
+      .map((n, i) => ({ node: n, value: totals[i]! }))
+      .sort((a, b) => b.value - a.value)
+    let cx = x, cy = y, cw = w, ch = h, remaining = sum
+    let row: typeof ordered = []
+    const worstRatio = (vals: number[], shortSide: number, rowSum: number, scale: number): number => {
+      if (rowSum <= 0) return Infinity
+      const rowArea = rowSum * scale
+      const rowSide = rowArea / shortSide
+      let worst = 0
+      for (const v of vals) {
+        const cell = v * scale
+        const long = cell / rowSide
+        const r = Math.max(shortSide / long, long / shortSide)
+        if (r > worst) worst = r
+      }
+      return worst
+    }
+    function flushRow() {
+      if (!row.length) return
+      const rowSum = row.reduce((a, b) => a + b.value, 0)
+      const scale = (cw * ch) / remaining
+      const horizontal = cw >= ch
+      const shortSide = horizontal ? ch : cw
+      const rowSide = (rowSum * scale) / shortSide
+      let offset = 0
+      for (const it of row) {
+        const cellSize = (it.value * scale) / rowSide
+        const cx2 = horizontal ? cx : cx + offset
+        const cy2 = horizontal ? cy + offset : cy
+        const ww  = horizontal ? rowSide : cellSize
+        const hh  = horizontal ? cellSize : rowSide
+        const color = it.node.color ?? palette[(depth + cells.length) % palette.length]!
+        // Leaf: emit a cell. Branch: recurse into the rect minus a label gutter.
+        if (it.node.children?.length) {
+          cells.push({
+            x: round(cx2), y: round(cy2), w: round(ww), h: round(hh),
+            color, textColor: pickContrastText(color),
+            name: it.node.name, value: it.value, depth,
+          })
+          const labelH = Math.min(18, hh * 0.25)
+          squarify(it.node.children, cx2 + 1, cy2 + labelH, ww - 2, hh - labelH - 1, depth + 1)
+        } else {
+          cells.push({
+            x: round(cx2), y: round(cy2), w: round(ww), h: round(hh),
+            color, textColor: pickContrastText(color),
+            name: it.node.name, value: it.value, depth,
+          })
+        }
+        offset += cellSize
+      }
+      // Shrink the remaining strip.
+      if (horizontal) { cx += rowSide; cw -= rowSide } else { cy += rowSide; ch -= rowSide }
+      remaining -= rowSum
+      row = []
+    }
+    for (const it of ordered) {
+      const scale = (cw * ch) / remaining
+      const shortSide = Math.min(cw, ch)
+      const rowSum = row.reduce((a, b) => a + b.value, 0)
+      const currWorst = worstRatio(row.map((r) => r.value), shortSide, rowSum, scale)
+      const nextWorst = worstRatio([...row.map((r) => r.value), it.value], shortSide, rowSum + it.value, scale)
+      if (row.length && nextWorst > currWorst) {
+        flushRow()
+      }
+      row.push(it)
+    }
+    flushRow()
+  }
+  const seedItems = root.children ?? [root]
+  squarify(seedItems, padL, padT, plotW, plotH, 0)
+  return { ...empty, plot, treemapCells: cells }
+}
+
+/**
+ * The subtree at `path` (a list of node names from the root's children down),
+ * or the tree itself for an empty path. What a drilldown shows after each
+ * click: the clicked node becomes the root. Null when the path does not exist.
+ */
+export function drillTree(tree: TreeNode, path: ReadonlyArray<string>): TreeNode | null {
+  let node: TreeNode | undefined = tree
+  for (const name of path) {
+    node = node?.children?.find((c) => c.name === name)
+    if (!node) return null
+  }
+  return node ?? null
+}
+
+/**
+ * The path (node names from the root's children) to the first node called
+ * `name`, depth first, or null. What a click on a leaf's label needs.
+ */
+export function pathTo(tree: TreeNode, name: string): string[] | null {
+  const walk = (n: TreeNode, acc: string[]): string[] | null => {
+    for (const c of n.children ?? []) {
+      const next = [...acc, c.name]
+      if (c.name === name) return next
+      const deeper = walk(c, next)
+      if (deeper) return deeper
+    }
+    return null
+  }
+  return walk(tree, [])
+}