@lovett/ui 0.0.11 → 0.2.0

package/src/lib/chart.ts

@@ -0,0 +1,866 @@
+/**
+ * chart.ts — the scale / tick / path arithmetic behind every chart primitive.
+ *
+ * Promoted in ADR-146 D6. Before this module the same seven pieces of
+ * arithmetic were inlined in seven places, each with its own edge-case
+ * behaviour (or none):
+ *
+ *   • `completion-ring.tsx:58-64`      circumference + dashoffset, and its clamp
+ *   • `allocation-sparkbar.tsx:40,48`  max-normalised bar height (`Math.max(...values, 1)`)
+ *   • `progress-bar.tsx:27`            the 0-100 clamp
+ *   • `spec/shell-charts.tsx:63-91`    the cumulative donut dasharray accumulator
+ *   • `spec/shell-charts.tsx:134,151`  ranked-bar + stacked-bar normalisation
+ *   • `spec/shell-charts.tsx:174`      stacked column totals (the `|| 1` divide guard)
+ *   • `spec/shell-charts.tsx:236-254`  linear scale, M/L path, area close, and the
+ *                                      literal `[0.25, 0.5, 0.75]` gridline list
+ *   • `budget-flighting/.../TimelineView.tsx:24-45`  the month band domain
+ *
+ * `niceTicks` is the one function with no ancestor in the repo: we have never
+ * had a tick generator, which is exactly why every y-axis today is either a
+ * hardcoded fraction list or absent. It is the point of the module.
+ *
+ * CONSUMERS — measured 2026-09-06, all seven verified as real imports inside
+ * `@lovett/ui`: `line-chart.tsx` (`LineChart` / `AreaChart`),
+ * `bar-chart.tsx`, `donut-chart.tsx`, `ranked-bars.tsx`, `sparkline.tsx`,
+ * `gauge-ring.tsx`, `chart-frame.tsx` (`niceTicks`). This module is not on
+ * the public barrel, so it has no product consumers by design.
+ *
+ * Pure functions. No React, no DOM, no dependencies, no clock, no randomness —
+ * every function is deterministic for a given input.
+ *
+ * Token discipline: this module produces NUMBERS and SVG PATH DATA only. It
+ * never produces, reads, names or composes a colour, a token, or a CSS custom
+ * property (ADR-146 D8 — a constructed token name is invalid CSS that the
+ * browser silently discards). Series colour is resolved by a frozen literal
+ * lookup in the primitive, never here.
+ *
+ * THE OUTPUT CONTRACT — the whole reason this module exists
+ * ---------------------------------------------------------
+ * A chart library would have handled the degenerate cases for us. Hand-rolled
+ * SVG means we own them, so every function here is total:
+ *
+ *   1. **No output is ever `NaN` or `±Infinity`.** Every numeric return is
+ *      finite. A `NaN` in an SVG attribute is not a visual bug — it drops the
+ *      whole element, silently, with every gate green.
+ *   2. **Nothing divides by zero.** An empty series, an all-zero series and a
+ *      `min === max` domain each have a documented, deliberate answer.
+ *   3. **Non-finite input is absorbed, not propagated.** `null`, `undefined`,
+ *      `NaN` and `±Infinity` are read as `0` (or dropped, where dropping is the
+ *      honest answer — see `linePath`).
+ *   4. **Negative values are clamped to zero in share/height maths**
+ *      (`normalizeToMax`, `arcSegments`, `stackTotals`) because a bar cannot be
+ *      shorter than nothing and an arc cannot sweep backwards. A chart that
+ *      genuinely spans zero uses `linearScale` with a domain that includes it.
+ */
+
+/** What a caller may realistically hand us for one datum. */
+export type NumericInput = number | null | undefined
+
+/** A plotted point in screen space (y grows downward, as in SVG). */
+export interface Point {
+  readonly x: number
+  readonly y: number
+}
+
+/** `[start, end]`. `end` may be less than `start` (an inverted axis is legal). */
+export type Extent = readonly [number, number]
+
+/** Maps a domain value to a range position. Always returns a finite number. */
+export type ScaleFn = (value: NumericInput) => number
+
+/* ── internals ───────────────────────────────────────────────────────── */
+
+/** Read a datum as a finite number, or fall back. The absorber for rule 3. */
+function finite(value: NumericInput, fallback = 0): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+}
+
+/**
+ * Round to `decimals` places without ever returning a non-finite number.
+ * Keeps path data compact and — more importantly — deterministic, so path
+ * strings can be asserted directly in tests.
+ */
+function roundTo(value: number, decimals: number): number {
+  const factor = 10 ** Math.max(0, Math.min(12, Math.trunc(decimals)))
+  const scaled = value * factor
+  if (!Number.isFinite(scaled)) return value
+  const out = Math.round(scaled) / factor
+  return out === 0 ? 0 : out // normalise -0, which stringifies inconsistently
+}
+
+/** One SVG path coordinate: finite, 2dp, no `-0`. */
+function coord(value: number): string {
+  return String(roundTo(finite(value), 2))
+}
+
+/** Drop points that cannot be plotted. See `linePath` for why dropping wins. */
+function plottable(points: readonly Point[]): Point[] {
+  const out: Point[] = []
+  for (const p of points) {
+    if (Number.isFinite(p.x) && Number.isFinite(p.y)) out.push(p)
+  }
+  return out
+}
+
+/**
+ * The "nice number" ladder: 1, 2, 5 × 10ⁿ (Heckbert). Given a rough step,
+ * returns the nearest nice step. Returns 0 for a non-positive input, which
+ * `niceTicks` treats as its degenerate branch.
+ */
+function niceStep(rough: number): number {
+  if (!(rough > 0) || !Number.isFinite(rough)) return 0
+  const exponent = Math.floor(Math.log10(rough))
+  const magnitude = 10 ** exponent
+  const fraction = rough / magnitude
+  const nice = fraction < 1.5 ? 1 : fraction < 3 ? 2 : fraction < 7 ? 5 : 10
+  return nice * magnitude
+}
+
+/** How many decimals a tick on `step` needs. Capped; see `niceTicks`. */
+function decimalsForStep(step: number): number {
+  if (!(step > 0)) return 0
+  return -Math.floor(Math.log10(step))
+}
+
+/* ── scales ──────────────────────────────────────────────────────────── */
+
+/**
+ * A continuous linear scale: `domain → range`.
+ *
+ * Not clamped — a value outside the domain maps outside the range, which is
+ * what an out-of-domain point should do (the caller decides whether to clip).
+ *
+ * Edge cases, all deliberate:
+ * - **`min === max` (every value identical, or a single datum):** there is no
+ *   span to scale against, so *every* input maps to the **midpoint of the
+ *   range**. A flat series draws through the middle of the plot rather than
+ *   pinned to an edge, and nothing divides by zero.
+ * - **Non-finite input value:** maps to `range[0]`. There is no honest
+ *   position for a missing datum; `range[0]` is finite and predictable.
+ *   Filter or drop such points before plotting if a gap is what you want.
+ * - **Non-finite domain or range bound:** read as `0`.
+ * - **Overflow:** if the arithmetic would produce `±Infinity` (an absurd
+ *   domain/range magnitude), returns `range[0]` rather than propagating.
+ */
+export function linearScale(domain: Extent, range: Extent): ScaleFn {
+  const d0 = finite(domain[0])
+  const d1 = finite(domain[1])
+  const r0 = finite(range[0])
+  const r1 = finite(range[1])
+
+  const span = d1 - d0
+  if (span === 0 || !Number.isFinite(span)) {
+    const mid = (r0 + r1) / 2
+    const flat = Number.isFinite(mid) ? mid : r0
+    return () => flat
+  }
+
+  const slope = (r1 - r0) / span
+  return (value: NumericInput): number => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return r0
+    const out = r0 + (value - d0) * slope
+    return Number.isFinite(out) ? out : r0
+  }
+}
+
+/** What `bandScale` hands back. `band` is the mark width; `step` includes the gap. */
+export interface BandScale {
+  /** Width of one mark (bar / column). Never negative, never non-finite. */
+  readonly band: number
+  /** Distance between the left edges of adjacent marks (`band` + gap). */
+  readonly step: number
+  /** Left edge of mark `index`. Index is clamped into `[0, count - 1]`. */
+  at(index: NumericInput): number
+  /** Centre of mark `index` — the x for a point/line over a categorical axis. */
+  center(index: NumericInput): number
+}
+
+/**
+ * A categorical band scale over `count` marks across `width` pixels.
+ *
+ * `step = width / count`, `band = step × (1 − paddingRatio)`, and each band is
+ * centred inside its step — so the gap is split evenly and the strip carries a
+ * half-gap of outer padding at each end. That is the layout every hand-rolled
+ * bar strip in the repo was approximating with `flex: 1` and a `gap`.
+ *
+ * Edge cases:
+ * - **`count <= 0`, or a non-finite `count`/`width`:** `band` and `step` are
+ *   `0` and `at`/`center` return `0`. An empty chart draws nothing; it does
+ *   not divide by zero.
+ * - **`count === 1`:** the single band takes the full width less its padding
+ *   and sits centred. A one-category bar chart is a legal chart.
+ * - **`paddingRatio`** is clamped to `[0, 1]`. At `1` the band is `0` wide —
+ *   that is what was asked for, not an error.
+ * - **`index` out of range, fractional, or non-finite:** floored and clamped
+ *   into `[0, count - 1]`. Never `NaN`.
+ */
+export function bandScale(
+  count: NumericInput,
+  width: NumericInput,
+  paddingRatio: NumericInput = 0.2,
+): BandScale {
+  const n = Math.max(0, Math.floor(finite(count)))
+  const w = Math.max(0, finite(width))
+  const padding = Math.max(0, Math.min(1, finite(paddingRatio)))
+
+  if (n === 0 || w === 0) {
+    return { band: 0, step: 0, at: () => 0, center: () => 0 }
+  }
+
+  const step = w / n
+  const band = step * (1 - padding)
+  const inset = (step - band) / 2
+
+  const clampIndex = (index: NumericInput): number =>
+    Math.max(0, Math.min(n - 1, Math.floor(finite(index))))
+
+  return {
+    band,
+    step,
+    at: (index) => clampIndex(index) * step + inset,
+    center: (index) => clampIndex(index) * step + inset + band / 2,
+  }
+}
+
+/* ── ticks ───────────────────────────────────────────────────────────── */
+
+/**
+ * Nice-number axis ticks over `[min, max]`, aiming for about `targetCount`.
+ *
+ * Steps come off the 1 / 2 / 5 × 10ⁿ ladder, and the first and last tick are
+ * the *rounded-out* bounds — so **the returned ticks may extend beyond `min`
+ * and `max`, and that is the point**: use `ticks[0]` and the last tick as the
+ * plot's actual domain and the gridlines land on round numbers.
+ *
+ * This replaces the literal `[0.25, 0.5, 0.75]` gridline fraction list.
+ *
+ * Edge cases:
+ * - **`min === max`** (a flat series, or a single datum): returns exactly
+ *   `[min]` — one gridline at the value. Matches `d3.ticks(x, x, n)`. It is
+ *   honest: there is no range to divide.
+ * - **`min > max`:** the bounds are swapped, then treated normally.
+ * - **Non-finite `min`/`max`:** read as `0`, so `niceTicks(NaN, NaN)` is
+ *   `[0]`.
+ * - **`targetCount` below 2, fractional, or non-finite:** clamped/floored to a
+ *   minimum of 2. An axis needs at least two ticks to have a step at all.
+ * - **Very small magnitudes:** ticks are rounded to the step's own decimal
+ *   place, so `0.1, 0.2, 0.30000000000000004` never happens. Below `1e-12`
+ *   rounding is skipped rather than collapsing distinct ticks onto each other.
+ * - **Very large magnitudes:** steps stay exact multiples; no rounding is
+ *   applied where it would be a no-op.
+ * - The emitted count is hard-capped at 1000 so no input can produce an
+ *   unbounded array.
+ */
+export function niceTicks(
+  min: NumericInput,
+  max: NumericInput,
+  targetCount: NumericInput = 5,
+): number[] {
+  const a = finite(min)
+  const b = finite(max)
+  const lo = Math.min(a, b)
+  const hi = Math.max(a, b)
+
+  if (lo === hi) return [lo]
+
+  const count = Math.max(2, Math.floor(finite(targetCount, 5)))
+  const step = niceStep((hi - lo) / (count - 1))
+  if (step <= 0 || !Number.isFinite(step)) return [lo, hi]
+
+  // The 1e-9 slack is load-bearing, not defensive. `0.3 / 0.1` is
+  // 2.9999999999999996 in IEEE 754, so a bare `Math.floor` reads 2 and the
+  // axis for a 0.3..0.7 domain starts at a phantom 0.2 tick. The ceiling
+  // carries the same slack for the symmetric case.
+  // Covered by the `0.3..0.7` case in chart-math.test.ts — remove either
+  // epsilon and that test goes red.
+  const start = Math.floor(lo / step + 1e-9) * step
+  const end = Math.ceil(hi / step - 1e-9) * step
+  const spanSteps = Math.round((end - start) / step)
+  if (!Number.isFinite(spanSteps) || spanSteps < 1) return [lo, hi]
+
+  const decimals = decimalsForStep(step)
+  const round = decimals <= 12
+  const total = Math.min(spanSteps, 1000)
+
+  const ticks: number[] = []
+  for (let i = 0; i <= total; i++) {
+    const raw = start + i * step
+    ticks.push(round ? roundTo(raw, decimals) : raw)
+  }
+  return ticks
+}
+
+/* ── paths ───────────────────────────────────────────────────────────── */
+
+/**
+ * SVG path data for a polyline through `points` (`M` then `L`s).
+ *
+ * Coordinates are rounded to 2dp — compact, and deterministic enough to
+ * assert a whole path string in a test.
+ *
+ * Edge cases:
+ * - **Empty input:** returns `''`. An empty `d` renders nothing, which is the
+ *   correct picture of no data. It is also the only value that cannot throw.
+ * - **A single point:** returns `M x,y L x,y` — a zero-length segment, which
+ *   with `stroke-linecap="round"` paints a dot. A one-datum series is visible
+ *   rather than silently blank (ADR-146 acceptance criterion 8).
+ * - **Points with a non-finite `x` or `y`:** dropped. The line closes over the
+ *   gap. Dropping beats emitting `NaN`, which would void the entire `<path>`.
+ *   A caller that wants a visible break should split the series and emit two
+ *   paths.
+ */
+export function linePath(points: readonly Point[]): string {
+  const pts = plottable(points)
+  const [first] = pts
+  if (first === undefined) return ''
+
+  const head = `M${coord(first.x)},${coord(first.y)}`
+  if (pts.length === 1) return `${head} L${coord(first.x)},${coord(first.y)}`
+
+  let d = head
+  for (let i = 1; i < pts.length; i++) {
+    const p = pts[i]
+    if (p === undefined) continue
+    d += ` L${coord(p.x)},${coord(p.y)}`
+  }
+  return d
+}
+
+/**
+ * SVG path data for the filled area between the polyline and `baselineY`
+ * (the line, then down to the baseline, back along it, and closed).
+ *
+ * Edge cases:
+ * - **Fewer than two plottable points:** returns `''`. A single point has no
+ *   area; the line path still renders its dot. This is deliberate rather than
+ *   emitting a zero-width sliver that reads as a stray tick.
+ * - **Non-finite `baselineY`:** read as `0`.
+ * - Same point-dropping rule as `linePath`.
+ */
+export function areaPath(points: readonly Point[], baselineY: NumericInput): string {
+  const pts = plottable(points)
+  if (pts.length < 2) return ''
+
+  const [first] = pts
+  const last = pts[pts.length - 1]
+  if (first === undefined || last === undefined) return ''
+
+  const base = coord(finite(baselineY))
+  return `${linePath(pts)} L${coord(last.x)},${base} L${coord(first.x)},${base} Z`
+}
+
+/* ── arcs ────────────────────────────────────────────────────────────── */
+
+/** The stroked-circle geometry a donut or ring arc is drawn on. */
+export interface ArcGeometry {
+  /** Centreline radius — what goes on the `<circle r>`. Never negative. */
+  readonly radius: number
+  /** `2πr` of the centreline: the dash length of a full turn. */
+  readonly circumference: number
+}
+
+/**
+ * Centreline radius and circumference for a ring of `outerRadius` drawn with a
+ * `strokeWidth` stroke. A stroke straddles its path, so the centreline sits
+ * half a stroke inside the outer edge — this is `completion-ring.tsx:60`'s
+ * `(size - sw) / 2`, generalised.
+ *
+ * Edge cases: negative or non-finite inputs read as `0`; a stroke wider than
+ * the ring clamps the radius to `0` (circumference `0`) instead of going
+ * negative and producing a backwards dash; and the radius is capped at the
+ * largest value whose circumference is still a finite double, so an absurd
+ * radius cannot hand `2πr === Infinity` to a `stroke-dasharray`.
+ */
+export function arcGeometry(
+  outerRadius: NumericInput,
+  strokeWidth: NumericInput = 0,
+): ArcGeometry {
+  const outer = Math.max(0, finite(outerRadius))
+  const stroke = Math.max(0, finite(strokeWidth))
+  const radius = Math.min(MAX_ARC_RADIUS, Math.max(0, outer - stroke / 2))
+  return { radius, circumference: 2 * Math.PI * radius }
+}
+
+/** Beyond this, `2πr` overflows to `Infinity` and every dash becomes `NaN`. */
+const MAX_ARC_RADIUS = Number.MAX_VALUE / (2 * Math.PI)
+
+/** One donut slice, ready to drop onto a `<circle>`. */
+export interface ArcSegment {
+  /** Share of the total, `0..1`. */
+  readonly fraction: number
+  /** Cumulative share *before* this slice, `0..1` — the slice's start angle. */
+  readonly startFraction: number
+  /** `stroke-dasharray`: `"<dash> <gap>"`. */
+  readonly dasharray: string
+  /** `stroke-dashoffset` — negative or zero, never `-0`. */
+  readonly dashoffset: number
+}
+
+/**
+ * The cumulative donut accumulator: one `stroke-dasharray` /
+ * `stroke-dashoffset` pair per slice, drawn on a single circle of
+ * `arcGeometry(outerRadius, strokeWidth)`. Written twice by hand before this
+ * (`shell-charts.tsx:63-91` and the geo ring).
+ *
+ * Slices are laid head-to-tail in input order; rotate the `<circle>` by -90°
+ * to start at twelve o'clock, exactly as the two hand-rolled versions did.
+ *
+ * Edge cases:
+ * - **Empty input:** `[]`.
+ * - **All values zero** (or all non-positive): every `fraction` is `0` and
+ *   every dash is `0` — the ring renders empty. It does **not** divide by
+ *   zero, and it does not silently split the ring evenly, which would invent
+ *   data that isn't there.
+ * - **One category:** a single slice with `fraction === 1`, `dasharray`
+ *   `"<C> 0"`, `dashoffset 0` — a complete ring.
+ * - **Negative values:** clamped to `0` and excluded from the total. An arc
+ *   cannot sweep backwards, and a share chart with negative shares is a
+ *   different chart.
+ * - **Non-finite values:** read as `0`.
+ * - **A zero or negative radius:** circumference `0`, so every dash is `0`.
+ *   Fractions are still correct, so a legend built off them stays right.
+ */
+export function arcSegments(
+  values: readonly NumericInput[],
+  outerRadius: NumericInput,
+  strokeWidth: NumericInput = 0,
+): ArcSegment[] {
+  const { circumference } = arcGeometry(outerRadius, strokeWidth)
+
+  const positive = values.map((value) => {
+    const v = finite(value)
+    return v > 0 ? v : 0
+  })
+
+  let total = 0
+  for (const v of positive) total += v
+
+  let cursor = 0
+  return positive.map((v) => {
+    const fraction = total > 0 ? v / total : 0
+    const dash = roundTo(fraction * circumference, 3)
+    const gap = roundTo(Math.max(0, circumference - fraction * circumference), 3)
+    const segment: ArcSegment = {
+      fraction,
+      startFraction: cursor,
+      dasharray: `${dash} ${gap}`,
+      dashoffset: cursor === 0 ? 0 : roundTo(-cursor * circumference, 3),
+    }
+    cursor += fraction
+    return segment
+  })
+}
+
+/** A single-arc progress ring: the whole `<circle>` dash contract. */
+export interface RingDash extends ArcGeometry {
+  /** `stroke-dasharray` — the full circumference. */
+  readonly dasharray: number
+  /** `stroke-dashoffset` — how much of the turn stays unpainted. */
+  readonly dashoffset: number
+}
+
+/**
+ * The one-arc case of `arcSegments`: a 0-100 progress ring
+ * (`completion-ring.tsx:58-64`, and its hand-rolled twin in the geo panel).
+ *
+ * Edge cases: `percent` runs through `clampPct`, so `NaN`, `null`, `-20` and
+ * `140` are `0`, `0`, `0` and `100`. A zero radius yields dashes of `0`.
+ */
+export function ringDash(
+  percent: NumericInput,
+  outerRadius: NumericInput,
+  strokeWidth: NumericInput = 0,
+): RingDash {
+  const geometry = arcGeometry(outerRadius, strokeWidth)
+  const pct = clampPct(percent)
+  return {
+    ...geometry,
+    dasharray: roundTo(geometry.circumference, 3),
+    dashoffset: roundTo(geometry.circumference * (1 - pct / 100), 3),
+  }
+}
+
+/* ── normalisation ───────────────────────────────────────────────────── */
+
+/**
+ * Clamp to `0..100`. Written three times before this
+ * (`progress-bar.tsx:27`, `completion-ring.tsx:58`, and the geo ring).
+ *
+ * Non-finite input — `NaN`, `±Infinity`, `null`, `undefined` — is `0`, not
+ * `NaN`. A progress bar with an unknown value reads as empty, never as a
+ * dropped element.
+ */
+export function clampPct(value: NumericInput): number {
+  const v = finite(value)
+  if (v < 0) return 0
+  if (v > 100) return 100
+  return v
+}
+
+/**
+ * Each value as a fraction `0..1` of the **largest** value in the array — the
+ * bar-height normalisation behind `allocation-sparkbar.tsx:40` and
+ * `shell-charts.tsx:134`, both of which used `Math.max(...values, 1)`.
+ *
+ * Two improvements over the inlined versions:
+ * - No spread. `Math.max(...values)` overflows the call stack on a large
+ *   array; this walks it.
+ * - No `, 1` fudge. That guard silently rescaled any series whose max was
+ *   below 1 (a set of ratios, a set of percentages-as-fractions) against a
+ *   phantom maximum, flattening the whole chart.
+ *
+ * Edge cases:
+ * - **Empty input:** `[]`.
+ * - **All values zero, or all non-positive:** every fraction is `0` — a flat
+ *   empty strip. No division happens.
+ * - **All values identical and positive:** every fraction is `1` — a flat
+ *   full strip, which is the truth.
+ * - **Negative values:** clamped to `0`. A bar cannot be shorter than nothing;
+ *   a series that genuinely crosses zero belongs on `linearScale` with a
+ *   domain that spans it.
+ * - **Non-finite values:** read as `0`.
+ * - Output is always within `0..1` inclusive.
+ */
+export function normalizeToMax(values: readonly NumericInput[]): number[] {
+  let max = 0
+  for (const value of values) {
+    const v = finite(value)
+    if (v > max) max = v
+  }
+  if (max <= 0) return values.map(() => 0)
+  return values.map((value) => {
+    const v = finite(value)
+    if (v <= 0) return 0
+    if (v >= max) return 1
+    return v / max
+  })
+}
+
+/**
+ * Column totals for a stacked chart — `shell-charts.tsx:174`, minus its
+ * `|| 1` divide guard (which quietly turned an empty column into a full-height
+ * one).
+ *
+ * `series` is row-major: one row per series, one entry per column. Rows may be
+ * ragged; the result is as long as the longest row, and a short row
+ * contributes nothing to the columns it does not reach.
+ *
+ * Negative and non-finite entries contribute `0`, for the same reason as
+ * `normalizeToMax`. An all-zero column totals `0` — see `stackFractions` for
+ * how that is then divided safely.
+ */
+export function stackTotals(series: readonly (readonly NumericInput[])[]): number[] {
+  let columns = 0
+  for (const row of series) {
+    if (row.length > columns) columns = row.length
+  }
+
+  const totals: number[] = new Array<number>(columns).fill(0)
+  for (const row of series) {
+    for (let i = 0; i < row.length; i++) {
+      const v = finite(row[i])
+      if (v > 0) totals[i] = (totals[i] ?? 0) + v
+    }
+  }
+  return totals
+}
+
+/**
+ * Each entry as its share `0..1` of its own column total — the 100%-stacked
+ * bar normalisation, with the divide-by-zero handled once instead of per call
+ * site.
+ *
+ * Shape is preserved exactly: same number of rows, each row the same length it
+ * came in as (ragged input stays ragged).
+ *
+ * Edge cases:
+ * - **An all-zero column:** every entry in it is `0`. The column renders
+ *   empty rather than being invented into a full bar by a `|| 1`.
+ * - **Negative / non-finite entries:** `0`, and excluded from the total.
+ * - Every column that has any positive value sums to `1` (within float
+ *   epsilon).
+ */
+export function stackFractions(
+  series: readonly (readonly NumericInput[])[],
+): number[][] {
+  const totals = stackTotals(series)
+  return series.map((row) =>
+    row.map((value, i) => {
+      const v = finite(value)
+      const total = totals[i] ?? 0
+      // `total <= 0` is unreachable while `stackTotals` sums this same array
+      // (a positive `v` is inside its own column total). It stays as a divide
+      // guard for the day the totals come from somewhere else — mutation
+      // testing confirms only the `v <= 0` arm is load-bearing today.
+      if (v <= 0 || total <= 0) return 0
+      return v >= total ? 1 : v / total
+    }),
+  )
+}
+
+/* ── temporal domain ─────────────────────────────────────────────────── */
+
+/**
+ * The inclusive month band domain between two `YYYY-MM-DD` dates, as
+ * `YYYY-MM-01` strings — the generator inlined at `TimelineView.tsx:24-45`.
+ *
+ * Parsed as integers off the string rather than through `new Date(...)`: the
+ * original relied on a `T00:00:00` suffix to dodge UTC parsing, which makes
+ * the result depend on the machine's timezone. This is timezone-free and
+ * therefore deterministic in tests and in every deployment region.
+ *
+ * Edge cases:
+ * - **Either bound unparseable** (wrong shape, month outside `01..12`):
+ *   returns `[]`. A chart with no domain draws its empty state.
+ * - **`start` after `end`:** `[]` — an inverted range is a caller bug, not a
+ *   reversed axis.
+ * - **`start` and `end` in the same month:** a single-entry domain.
+ * - Spans are capped at 1200 months (100 years) so a typo'd year cannot
+ *   allocate an unbounded array.
+ */
+export function monthDomain(startISO: string, endISO: string): string[] {
+  const start = monthIndex(startISO)
+  const end = monthIndex(endISO)
+  if (start === null || end === null || end < start) return []
+
+  const count = Math.min(end - start + 1, 1200)
+  const months: string[] = []
+  for (let i = 0; i < count; i++) {
+    const index = start + i
+    const year = Math.floor(index / 12)
+    const month = (index % 12) + 1
+    months.push(`${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-01`)
+  }
+  return months
+}
+
+/** `YYYY-MM-…` → months since year 0, or `null` if it is not a date we can read. */
+function monthIndex(iso: string): number | null {
+  const match = /^(\d{4})-(\d{2})/.exec(iso)
+  if (match === null) return null
+  const [, yearText, monthText] = match
+  if (yearText === undefined || monthText === undefined) return null
+  const year = Number(yearText)
+  const month = Number(monthText)
+  if (!Number.isFinite(year) || month < 1 || month > 12) return null
+  return year * 12 + (month - 1)
+}
+
+/* ── axis fitting ────────────────────────────────────────────────────── */
+
+/**
+ * TEXT WIDTH ESTIMATION — why it is an estimate, and why the estimate is
+ * deliberately generous.
+ *
+ * An SVG `<text>` has no layout box until it is in the document, and a tick
+ * label's width is not known until after the tick count has been chosen — so
+ * a chart cannot measure its way out of "how many labels fit" without a
+ * render pass whose only job is to be thrown away. Every advance below was
+ * MEASURED in Chromium off the shipped gallery (`getBoundingClientRect` on
+ * real labels, 2026-09-06) and then rounded UP, because the failure modes are
+ * asymmetric: over-estimating drops one label that would have fitted, while
+ * under-estimating ships the overlap this module exists to prevent.
+ *
+ *   14px, weight 400  "Wk 1"    32.33px    "Wk 10"   40.91px  → digit 8.58
+ *   12px, weight 600  "8,240"   34.28px    "13,390"  42.05px  → digit 7.77
+ *   12px, weight 600  "96.2%"   38.58px    "$17,460" 49.86px
+ *
+ * Ratios to font size, rounded up from those: a digit/letter runs ~0.61-0.65
+ * em, so 0.68; `,` and `.` ~0.27 em, so 0.32; `%` is the outlier at ~1.0 em,
+ * so 1.05. Checked back against every string above, the estimate is 0-6% HIGH
+ * in each case and never low.
+ */
+const ADVANCE_WIDE = 0.68
+const ADVANCE_PUNCT = 0.32
+const ADVANCE_PERCENT = 1.05
+const ADVANCE_SPACE = 0.3
+
+/**
+ * Approximate rendered width of `text` at `fontSizePx`, in pixels.
+ *
+ * Deterministic, font-independent and total: an empty string is `0`, a
+ * non-finite font size is `0`. See the block above for where the per-glyph
+ * advances come from and why they round up.
+ */
+export function estimateTextWidth(text: string, fontSizePx: NumericInput): number {
+  const size = Math.max(0, finite(fontSizePx))
+  if (size === 0 || text.length === 0) return 0
+
+  let em = 0
+  for (const char of text) {
+    if (char === '%') em += ADVANCE_PERCENT
+    else if (char === ',' || char === '.' || char === ':') em += ADVANCE_PUNCT
+    else if (char === ' ') em += ADVANCE_SPACE
+    else em += ADVANCE_WIDE
+  }
+  return em * size
+}
+
+/** Never fewer than two ticks: below that an axis has no step at all. */
+const MIN_AXIS_TICKS = 2
+
+/**
+ * Most ticks any axis will draw, however much room it has.
+ *
+ * Past about six the ladder stops being read as a ladder and starts being
+ * read as texture, and every extra gridline is one more rule competing with
+ * the marks. ADR-146 D3 makes the gridline a structure token precisely so it
+ * stays quiet; drawing twelve of them undoes that.
+ */
+const MAX_AXIS_TICKS = 6
+
+/**
+ * How many ticks fit along an axis of `availablePx` when adjacent ticks must
+ * sit at least `minSpacingPx` apart — the case where labels sit AT the tick,
+ * so the constraint is the SPACING between them, not their own width.
+ *
+ * `n` ticks spread over `available` are `available / (n - 1)` apart, so
+ * `n <= available / minSpacing + 1`.
+ *
+ * The caller owns what "far enough apart" means, because it differs by axis:
+ * a vertical ladder needs about two label line-heights
+ * (`Y_TICK_MIN_SPACING_PX`), while a horizontal strip needs one label WIDTH
+ * plus a gap. Baking one of those in would have made the other wrong.
+ *
+ * Edge cases:
+ * - **Unmeasured** (`availablePx <= 0`) or an unknown spacing
+ *   (`minSpacingPx <= 0`): returns `requested` unchanged. A first paint
+ *   before the ResizeObserver lands must not collapse the axis to two ticks
+ *   and then visibly re-expand.
+ * - The result is always within `[2, min(requested, 6)]`, so a caller asking
+ *   for fewer than two gets two, and one asking for twelve gets six.
+ */
+export function fitTickCount(
+  availablePx: NumericInput,
+  minSpacingPx: NumericInput,
+  requested: NumericInput = 5,
+): number {
+  const want = Math.max(
+    MIN_AXIS_TICKS,
+    Math.min(MAX_AXIS_TICKS, Math.floor(finite(requested, 5))),
+  )
+  const available = finite(availablePx)
+  const spacing = finite(minSpacingPx)
+  if (!(available > 0) || !(spacing > 0)) return want
+
+  const capacity = Math.floor(available / spacing) + 1
+  return Math.max(MIN_AXIS_TICKS, Math.min(want, capacity))
+}
+
+/**
+ * How many labels fit side by side along `availablePx` when each occupies
+ * `labelExtentPx` — the horizontal case, where labels sit BESIDE each other
+ * and the constraint is their own width plus a gap.
+ *
+ * Edge cases mirror `fitTickCount`: an unmeasured axis or an unknown label
+ * width returns `requested`, and the result never drops below `minCount`.
+ *
+ * `minCount` may be `0`, which is how a caller asks the honest question "do
+ * even two of these fit?" — a 26px-wide plot holds no 32px label, and two of
+ * them overlapped by 10px until the caller was able to find that out.
+ */
+export function fitLabelCount(
+  availablePx: NumericInput,
+  labelExtentPx: NumericInput,
+  requested: NumericInput,
+  minCount: NumericInput = 2,
+): number {
+  const floor = Math.max(0, Math.floor(finite(minCount, 2)))
+  const want = Math.max(floor, Math.floor(finite(requested, floor)))
+  const available = finite(availablePx)
+  const extent = finite(labelExtentPx)
+  if (!(available > 0) || !(extent > 0)) return want
+
+  return Math.max(floor, Math.min(want, Math.floor(available / extent)))
+}
+
+/**
+ * Nice-number ticks that ALSO fit the space they are drawn in.
+ *
+ * `niceTicks` aims for a target count but is allowed to overshoot it — it
+ * rounds the domain outward, so a target of 5 routinely returns 6. That
+ * overshoot is what put six 21px labels into a 190px gutter and made every
+ * adjacent pair touch. So the target is searched downward until the RETURNED
+ * ladder fits, rather than assumed to be honoured.
+ *
+ * `availablePx` is the axis's drawn length and `minSpacingPx` the room two
+ * adjacent labels need between them. Pass `0` for either — an unmeasured
+ * plot — and this is exactly `niceTicks(min, max, targetCount)`.
+ */
+export function fitTicks(
+  min: NumericInput,
+  max: NumericInput,
+  availablePx: NumericInput,
+  minSpacingPx: NumericInput,
+  targetCount: NumericInput = 5,
+): number[] {
+  // The TARGET and the LIMIT are two different numbers, and conflating them
+  // is a bug: a target of 5 that legitimately returns 6 ticks is fine when
+  // six fit, and only a problem when they do not. The limit is therefore
+  // purely physical — what the space holds — while the target is what the
+  // caller asked for, capped by that limit.
+  const limit = fitTickCount(availablePx, minSpacingPx, MAX_AXIS_TICKS)
+  let target = Math.max(
+    MIN_AXIS_TICKS,
+    Math.min(limit, Math.floor(finite(targetCount, 5))),
+  )
+
+  let ticks = niceTicks(min, max, target)
+  while (ticks.length > limit && target > MIN_AXIS_TICKS) {
+    target--
+    ticks = niceTicks(min, max, target)
+  }
+
+  // Even the two-tick target can overshoot: `niceTicks(-50000, 50000, 2)`
+  // rounds out to a 100,000 step and returns THREE rungs, which is how a
+  // 33px plot ended up with "$50,000 / $0 / -$50,000" overlapping by 4.4px
+  // after the search had already bottomed out. Subsampling by the same
+  // uniform stride the x axis uses keeps the FIRST and LAST rung — so the
+  // drawn domain is unchanged, and only gridlines are dropped.
+  if (ticks.length > limit) {
+    return strideIndices(ticks.length, limit).map((index) => ticks[index] ?? 0)
+  }
+  return ticks
+}
+
+/**
+ * Thin `count` positions down to at most `max` labels by a UNIFORM STRIDE,
+ * always keeping the first and the last.
+ *
+ * The predecessor rounded a fraction — `round(i / (max - 1) * last)` — which
+ * over 12 positions with `max` 8 produced 0, 2, 3, 5, 6, 8, 9, 11: an axis
+ * reading "Wk 1, Wk 3, Wk 4, Wk 6, Wk 7, Wk 9, Wk 10, Wk 12", with 2, 5, 8
+ * and 11 skipped while 3&4, 6&7 and 9&10 stayed ADJACENT. A reader sees an
+ * irregular axis and concludes, reasonably, that the DATA is irregular. A
+ * stride cannot do that: every gap is identical except, at most, the last.
+ *
+ * When the last position does not land on the stride, it replaces the
+ * previous kept index rather than being appended beside it — appending would
+ * leave two labels one step apart at the right-hand end, which is the same
+ * false signal in miniature. That is the "drop the second-to-last, never an
+ * interior one" rule.
+ *
+ * Returns the kept INDICES, ascending. Edge cases: a non-positive `count` is
+ * `[]`; `max` below 2 is read as 2; `count <= max` keeps everything.
+ */
+export function strideIndices(count: NumericInput, max: NumericInput): number[] {
+  const n = Math.max(0, Math.floor(finite(count)))
+  if (n === 0) return []
+  const cap = Math.max(MIN_AXIS_TICKS, Math.floor(finite(max, MIN_AXIS_TICKS)))
+  if (n <= cap) return Array.from({ length: n }, (_, i) => i)
+
+  const last = n - 1
+  const stride = Math.max(1, Math.ceil(last / (cap - 1)))
+
+  const kept: number[] = []
+  for (let i = 0; i <= last; i += stride) kept.push(i)
+
+  const tail = kept[kept.length - 1]
+  if (tail !== undefined && tail !== last) {
+    // Adjacent to the end: replace, so the final gap widens instead of
+    // collapsing to one step. Otherwise there is room for both.
+    if (kept.length > 1 && last - tail < stride) kept[kept.length - 1] = last
+    else kept.push(last)
+  }
+  return kept
+}