@lovett/ui 0.0.11 → 0.2.0

package/src/__tests__/chart-math.test.ts

@@ -0,0 +1,922 @@
+// @vitest-environment node
+//
+// Pure arithmetic — no DOM, no React, no clock, no randomness.
+/**
+ * Contract tests for `lib/chart.ts` (ADR-146 D6).
+ *
+ * The edge cases ARE the job here. ADR-146 accepts the cost of hand-rolled
+ * SVG explicitly: "we own the axis edge cases (a single data point, all-zero
+ * series, negative values, one-category donut) that a library would have
+ * handled. Each is a named test case." This file is that list.
+ *
+ * The failure mode being defended against is not a wrong number — it is a
+ * `NaN` or an `Infinity` reaching an SVG attribute, which does not throw and
+ * does not warn: the browser drops the element and the chart renders blank
+ * with typecheck, lint, build and every other test green. So on top of the
+ * per-function cases, `never emits NaN or Infinity` walks every function with
+ * a shared table of hostile inputs.
+ *
+ * Float assertions go through `near()` (epsilon), never `toBe` (CLAUDE.md §7).
+ * Path strings compare exactly on purpose — `linePath` rounds to a fixed 2dp
+ * precisely so its output is assertable.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  arcGeometry,
+  arcSegments,
+  areaPath,
+  bandScale,
+  clampPct,
+  estimateTextWidth,
+  fitLabelCount,
+  fitTickCount,
+  fitTicks,
+  linePath,
+  linearScale,
+  monthDomain,
+  niceTicks,
+  normalizeToMax,
+  ringDash,
+  stackFractions,
+  stackTotals,
+  strideIndices,
+  type NumericInput,
+  type Point,
+} from '../lib/chart'
+
+const EPS = 1e-9
+
+/** Epsilon float assertion. Never `==`. */
+function near(actual: number, expected: number, eps = EPS): void {
+  expect(Math.abs(actual - expected)).toBeLessThanOrEqual(eps)
+}
+
+/** Every hostile scalar a caller can realistically hand us. */
+const HOSTILE: readonly NumericInput[] = [
+  NaN,
+  Infinity,
+  -Infinity,
+  null,
+  undefined,
+  0,
+  -0,
+  -1,
+  Number.MAX_VALUE,
+  Number.MIN_VALUE,
+  -Number.MAX_VALUE,
+]
+
+describe('linearScale', () => {
+  it('maps a domain onto a range', () => {
+    const scale = linearScale([0, 100], [0, 200])
+    near(scale(0), 0)
+    near(scale(50), 100)
+    near(scale(100), 200)
+    near(scale(12.5), 25)
+  })
+
+  it('supports an inverted range (SVG y grows downward)', () => {
+    const scale = linearScale([0, 10], [100, 0])
+    near(scale(0), 100)
+    near(scale(5), 50)
+    near(scale(10), 0)
+  })
+
+  it('does not clamp — an out-of-domain value maps out of the range', () => {
+    const scale = linearScale([0, 10], [0, 100])
+    near(scale(15), 150)
+    near(scale(-5), -50)
+  })
+
+  it('handles a negative domain', () => {
+    const scale = linearScale([-50, 50], [0, 100])
+    near(scale(-50), 0)
+    near(scale(0), 50)
+    near(scale(50), 100)
+  })
+
+  it('min === max: every value maps to the middle of the range', () => {
+    const scale = linearScale([7, 7], [0, 200])
+    near(scale(7), 100)
+    near(scale(-1000), 100)
+    near(scale(1000), 100)
+  })
+
+  it('a single-datum domain still plots inside the range', () => {
+    const only = 42
+    const scale = linearScale([only, only], [120, 0])
+    near(scale(only), 60)
+  })
+
+  it('non-finite input maps to the range start, never NaN', () => {
+    const scale = linearScale([0, 10], [5, 105])
+    for (const bad of [NaN, Infinity, -Infinity, null, undefined] as const) {
+      near(scale(bad), 5)
+    }
+  })
+
+  it('non-finite domain and range bounds are read as zero', () => {
+    near(linearScale([NaN, 10], [0, 100])(5), 50)
+    near(linearScale([0, 10], [Infinity, 100])(10), 100)
+  })
+
+  it('returns the range start rather than overflowing to Infinity', () => {
+    const scale = linearScale([0, Number.MIN_VALUE], [0, Number.MAX_VALUE])
+    const out = scale(1e300)
+    expect(Number.isFinite(out)).toBe(true)
+    near(out, 0)
+  })
+})
+
+describe('bandScale', () => {
+  it('splits a width into centred bands with the gap shared evenly', () => {
+    const scale = bandScale(4, 100, 0.2)
+    near(scale.step, 25)
+    near(scale.band, 20)
+    near(scale.at(0), 2.5)
+    near(scale.at(3), 77.5)
+    near(scale.center(0), 12.5)
+    near(scale.center(3), 87.5)
+  })
+
+  it('a one-category chart is a legal chart', () => {
+    const scale = bandScale(1, 200, 0.2)
+    near(scale.step, 200)
+    near(scale.band, 160)
+    near(scale.at(0), 20)
+    near(scale.center(0), 100)
+  })
+
+  it('count 0 collapses to zeros instead of dividing by zero', () => {
+    const scale = bandScale(0, 100, 0.2)
+    expect(scale.band).toBe(0)
+    expect(scale.step).toBe(0)
+    expect(scale.at(0)).toBe(0)
+    expect(scale.center(3)).toBe(0)
+  })
+
+  it('width 0 collapses to zeros', () => {
+    const scale = bandScale(5, 0, 0.2)
+    expect(scale.band).toBe(0)
+    expect(scale.step).toBe(0)
+    expect(scale.at(2)).toBe(0)
+  })
+
+  it('padding 0 makes bands touch; padding 1 makes them vanish', () => {
+    const flush = bandScale(4, 100, 0)
+    near(flush.band, flush.step)
+    near(flush.at(0), 0)
+
+    const empty = bandScale(4, 100, 1)
+    near(empty.band, 0)
+    near(empty.step, 25)
+  })
+
+  it('clamps paddingRatio into 0..1', () => {
+    near(bandScale(4, 100, -3).band, bandScale(4, 100, 0).band)
+    near(bandScale(4, 100, 9).band, bandScale(4, 100, 1).band)
+    near(bandScale(4, 100, NaN).band, bandScale(4, 100, 0).band)
+  })
+
+  it('clamps and floors the index instead of returning NaN', () => {
+    const scale = bandScale(4, 100, 0.2)
+    near(scale.at(-99), scale.at(0))
+    near(scale.at(99), scale.at(3))
+    near(scale.at(1.9), scale.at(1))
+    near(scale.at(NaN), scale.at(0))
+    near(scale.at(null), scale.at(0))
+    near(scale.center(Infinity), scale.center(0))
+  })
+
+  it('non-finite count or width collapses to zeros', () => {
+    expect(bandScale(NaN, 100).step).toBe(0)
+    expect(bandScale(4, Infinity).step).toBe(0)
+    expect(bandScale(-4, 100).step).toBe(0)
+  })
+})
+
+describe('niceTicks', () => {
+  it('rounds a 0..100 axis onto the 1/2/5 ladder', () => {
+    const ticks = niceTicks(0, 100, 5)
+    expect(ticks).toHaveLength(6)
+    ticks.forEach((t, i) => near(t, i * 20))
+  })
+
+  it('does not emit float noise on a fractional axis', () => {
+    const ticks = niceTicks(0, 1, 5)
+    expect(ticks).toHaveLength(6)
+    ticks.forEach((t, i) => near(t, i * 0.2))
+    // The 0.30000000000000004 defect: every tick must survive a round-trip
+    // through 6dp unchanged.
+    for (const t of ticks) near(t, Number(t.toFixed(6)), 1e-12)
+  })
+
+  it('does not open a phantom tick below the domain (the floor/float trap)', () => {
+    // `0.3 / 0.1` is 2.9999999999999996, so an unguarded Math.floor starts
+    // this axis at 0.2 — a gridline below data that does not exist.
+    const ticks = niceTicks(0.3, 0.7, 5)
+    expect(ticks).toHaveLength(5)
+    ticks.forEach((t, i) => near(t, 0.3 + i * 0.1))
+  })
+
+  it('a domain of one value yields exactly one tick', () => {
+    expect(niceTicks(5, 5, 5)).toEqual([5])
+    expect(niceTicks(0, 0, 5)).toEqual([0])
+    expect(niceTicks(-3.5, -3.5, 5)).toEqual([-3.5])
+  })
+
+  it('swaps reversed bounds', () => {
+    expect(niceTicks(100, 0, 5)).toEqual(niceTicks(0, 100, 5))
+  })
+
+  it('spans negatives through zero', () => {
+    const ticks = niceTicks(-50, 50, 5)
+    expect(ticks.some((t) => Math.abs(t) < EPS)).toBe(true)
+    expect(ticks[0] ?? 0).toBeLessThanOrEqual(-50)
+    expect(ticks[ticks.length - 1] ?? 0).toBeGreaterThanOrEqual(50)
+  })
+
+  it('always covers the requested domain and stays monotonic', () => {
+    const cases: readonly (readonly [number, number])[] = [
+      [0, 1],
+      [0, 7],
+      [3, 9],
+      [-12, -2],
+      [-1, 1],
+      [0.004, 0.017],
+      [1e-9, 5e-9],
+      [1e12, 3e12],
+      [0, Number.MAX_SAFE_INTEGER],
+    ]
+    for (const [lo, hi] of cases) {
+      const ticks = niceTicks(lo, hi, 5)
+      expect(ticks.length).toBeGreaterThanOrEqual(2)
+      const first = ticks[0] ?? 0
+      const last = ticks[ticks.length - 1] ?? 0
+      expect(first).toBeLessThanOrEqual(lo + Math.abs(lo) * 1e-9)
+      expect(last).toBeGreaterThanOrEqual(hi - Math.abs(hi) * 1e-9)
+      for (let i = 1; i < ticks.length; i++) {
+        expect(ticks[i] ?? 0).toBeGreaterThan(ticks[i - 1] ?? 0)
+      }
+    }
+  })
+
+  it('reads non-finite bounds as zero', () => {
+    expect(niceTicks(NaN, NaN, 5)).toEqual([0])
+    expect(niceTicks(null, undefined, 5)).toEqual([0])
+    expect(niceTicks(Infinity, -Infinity, 5)).toEqual([0])
+  })
+
+  it('forces a minimum of two ticks however small the target count', () => {
+    for (const count of [1, 0, -5, NaN, null, undefined] as const) {
+      expect(niceTicks(0, 10, count).length).toBeGreaterThanOrEqual(2)
+    }
+  })
+
+  it('caps the emitted count so no input allocates without bound', () => {
+    expect(niceTicks(0, 1e6, 1e9).length).toBeLessThanOrEqual(1001)
+  })
+
+  it('every tick is finite for every hostile pairing', () => {
+    for (const lo of HOSTILE) {
+      for (const hi of HOSTILE) {
+        for (const t of niceTicks(lo, hi, 5)) {
+          expect(Number.isFinite(t)).toBe(true)
+        }
+      }
+    }
+  })
+})
+
+describe('linePath', () => {
+  const p = (x: number, y: number): Point => ({ x, y })
+
+  it('empty data renders nothing', () => {
+    expect(linePath([])).toBe('')
+  })
+
+  it('a single point renders a dot-length segment, not a blank path', () => {
+    expect(linePath([p(10, 20)])).toBe('M10,20 L10,20')
+  })
+
+  it('emits M then L for a polyline', () => {
+    expect(linePath([p(0, 0), p(10, 5), p(20, 0)])).toBe('M0,0 L10,5 L20,0')
+  })
+
+  it('rounds coordinates to 2dp and normalises -0', () => {
+    expect(linePath([p(1.234, 2.567), p(-0, 0)])).toBe('M1.23,2.57 L0,0')
+  })
+
+  it('drops unplottable points rather than voiding the whole path', () => {
+    expect(linePath([p(0, 0), p(NaN, 5), p(10, 10)])).toBe('M0,0 L10,10')
+    expect(linePath([p(0, 0), p(5, Infinity), p(10, 10)])).toBe('M0,0 L10,10')
+  })
+
+  it('all points unplottable renders nothing', () => {
+    expect(linePath([p(NaN, NaN), p(Infinity, 0)])).toBe('')
+  })
+
+  it('never emits NaN in path data', () => {
+    const points = HOSTILE.map((v, i) => p(finiteish(v), finiteish(HOSTILE[i]) + i))
+    expect(linePath(points)).not.toMatch(/NaN|Infinity/)
+  })
+})
+
+describe('areaPath', () => {
+  const p = (x: number, y: number): Point => ({ x, y })
+
+  it('empty data renders nothing', () => {
+    expect(areaPath([], 100)).toBe('')
+  })
+
+  it('a single point has no area', () => {
+    expect(areaPath([p(10, 20)], 100)).toBe('')
+  })
+
+  it('closes the polyline down to the baseline', () => {
+    expect(areaPath([p(0, 0), p(10, 5)], 100)).toBe('M0,0 L10,5 L10,100 L0,100 Z')
+  })
+
+  it('reads a non-finite baseline as zero', () => {
+    expect(areaPath([p(0, 4), p(10, 5)], NaN)).toBe('M0,4 L10,5 L10,0 L0,0 Z')
+    expect(areaPath([p(0, 4), p(10, 5)], null)).toBe('M0,4 L10,5 L10,0 L0,0 Z')
+  })
+
+  it('closes from the first and last PLOTTABLE point', () => {
+    expect(areaPath([p(NaN, 1), p(2, 3), p(8, 6), p(9, Infinity)], 50)).toBe(
+      'M2,3 L8,6 L8,50 L2,50 Z',
+    )
+  })
+})
+
+describe('arcGeometry', () => {
+  it('puts the centreline half a stroke inside the outer edge', () => {
+    const g = arcGeometry(50, 10)
+    near(g.radius, 45)
+    near(g.circumference, 2 * Math.PI * 45)
+  })
+
+  it('reproduces CompletionRing’s (size - strokeWidth) / 2', () => {
+    const size = 30
+    const strokeWidth = 3
+    near(arcGeometry(size / 2, strokeWidth).radius, (size - strokeWidth) / 2)
+  })
+
+  it('a stroke wider than the ring clamps to zero, never negative', () => {
+    const g = arcGeometry(4, 20)
+    expect(g.radius).toBe(0)
+    expect(g.circumference).toBe(0)
+  })
+
+  it('absorbs non-finite and negative inputs', () => {
+    for (const bad of HOSTILE) {
+      const g = arcGeometry(bad, 2)
+      expect(Number.isFinite(g.radius)).toBe(true)
+      expect(Number.isFinite(g.circumference)).toBe(true)
+      expect(g.radius).toBeGreaterThanOrEqual(0)
+    }
+  })
+})
+
+describe('arcSegments', () => {
+  const C = 2 * Math.PI * 45 // arcGeometry(50, 10)
+
+  it('empty data yields no segments', () => {
+    expect(arcSegments([], 50, 10)).toEqual([])
+  })
+
+  it('a one-category donut is a single complete ring', () => {
+    const [only] = arcSegments([12], 50, 10)
+    expect(only).toBeDefined()
+    if (only === undefined) return
+    near(only.fraction, 1)
+    near(only.startFraction, 0)
+    expect(only.dasharray).toBe(`${round3(C)} 0`)
+    expect(only.dashoffset).toBe(0)
+  })
+
+  it('lays slices head to tail', () => {
+    const segments = arcSegments([50, 30, 20], 50, 10)
+    expect(segments).toHaveLength(3)
+    near(segments[0]?.fraction ?? 0, 0.5)
+    near(segments[1]?.fraction ?? 0, 0.3)
+    near(segments[2]?.fraction ?? 0, 0.2)
+    near(segments[0]?.startFraction ?? -1, 0)
+    near(segments[1]?.startFraction ?? -1, 0.5)
+    near(segments[2]?.startFraction ?? -1, 0.8)
+    expect(segments[0]?.dashoffset).toBe(0)
+    near(segments[1]?.dashoffset ?? 0, -0.5 * C, 1e-3)
+    near(segments[2]?.dashoffset ?? 0, -0.8 * C, 1e-3)
+    near(
+      segments.reduce((sum, s) => sum + s.fraction, 0),
+      1,
+    )
+  })
+
+  it('an all-zero series renders an empty ring instead of dividing by zero', () => {
+    const segments = arcSegments([0, 0, 0], 50, 10)
+    expect(segments).toHaveLength(3)
+    for (const s of segments) {
+      expect(s.fraction).toBe(0)
+      expect(s.dasharray).toBe(`0 ${round3(C)}`)
+      expect(s.dashoffset).toBe(0)
+    }
+  })
+
+  it('clamps negative values to zero and excludes them from the total', () => {
+    const segments = arcSegments([10, -5, 10], 50, 10)
+    near(segments[0]?.fraction ?? 0, 0.5)
+    expect(segments[1]?.fraction).toBe(0)
+    near(segments[2]?.fraction ?? 0, 0.5)
+  })
+
+  it('reads non-finite values as zero', () => {
+    const segments = arcSegments([NaN, null, undefined, Infinity, 10], 50, 10)
+    near(segments[4]?.fraction ?? 0, 1)
+    for (const s of segments.slice(0, 4)) expect(s.fraction).toBe(0)
+  })
+
+  it('keeps fractions correct at zero radius so a legend stays right', () => {
+    const segments = arcSegments([1, 1], 0, 0)
+    near(segments[0]?.fraction ?? 0, 0.5)
+    expect(segments[0]?.dasharray).toBe('0 0')
+    expect(segments[1]?.dashoffset).toBe(0)
+  })
+
+  it('never emits NaN in a dash value', () => {
+    for (const radius of HOSTILE) {
+      for (const s of arcSegments(HOSTILE, radius, 2)) {
+        expect(s.dasharray).not.toMatch(/NaN|Infinity/)
+        expect(Number.isFinite(s.dashoffset)).toBe(true)
+        expect(Number.isFinite(s.fraction)).toBe(true)
+      }
+    }
+  })
+})
+
+describe('ringDash', () => {
+  it('0% leaves the whole turn unpainted, 100% paints all of it', () => {
+    const empty = ringDash(0, 15, 3)
+    near(empty.dashoffset, empty.dasharray, 1e-3)
+    const full = ringDash(100, 15, 3)
+    expect(full.dashoffset).toBe(0)
+  })
+
+  it('50% leaves half the turn unpainted', () => {
+    const half = ringDash(50, 15, 3)
+    near(half.dashoffset, half.dasharray / 2, 1e-3)
+  })
+
+  it('clamps out-of-range and non-finite percentages', () => {
+    expect(ringDash(-20, 15, 3).dashoffset).toBe(ringDash(0, 15, 3).dashoffset)
+    expect(ringDash(140, 15, 3).dashoffset).toBe(ringDash(100, 15, 3).dashoffset)
+    for (const bad of [NaN, Infinity, null, undefined] as const) {
+      expect(ringDash(bad, 15, 3).dashoffset).toBe(ringDash(0, 15, 3).dashoffset)
+    }
+  })
+
+  it('matches the arithmetic CompletionRing inlined', () => {
+    const size = 38
+    const strokeWidth = 3
+    const percent = 80
+    const r = (size - strokeWidth) / 2
+    const circ = 2 * Math.PI * r
+    const ring = ringDash(percent, size / 2, strokeWidth)
+    near(ring.radius, r)
+    near(ring.circumference, circ)
+    near(ring.dashoffset, circ * (1 - percent / 100), 1e-3)
+  })
+})
+
+describe('clampPct', () => {
+  it('passes an in-range value through', () => {
+    near(clampPct(42.5), 42.5)
+    expect(clampPct(0)).toBe(0)
+    expect(clampPct(100)).toBe(100)
+  })
+
+  it('clamps out of range', () => {
+    expect(clampPct(-20)).toBe(0)
+    expect(clampPct(1e9)).toBe(100)
+  })
+
+  it('reads non-finite as zero, never NaN', () => {
+    for (const bad of [NaN, Infinity, -Infinity, null, undefined] as const) {
+      expect(clampPct(bad)).toBe(0)
+    }
+  })
+})
+
+describe('normalizeToMax', () => {
+  it('empty data yields no fractions', () => {
+    expect(normalizeToMax([])).toEqual([])
+  })
+
+  it('divides by the largest value', () => {
+    const out = normalizeToMax([1, 2, 4])
+    near(out[0] ?? 0, 0.25)
+    near(out[1] ?? 0, 0.5)
+    near(out[2] ?? 0, 1)
+  })
+
+  it('an all-zero series is a flat empty strip', () => {
+    expect(normalizeToMax([0, 0, 0])).toEqual([0, 0, 0])
+  })
+
+  it('identical values are all full height', () => {
+    expect(normalizeToMax([7, 7, 7])).toEqual([1, 1, 1])
+  })
+
+  it('clamps negatives to zero', () => {
+    const out = normalizeToMax([-5, 10, -1])
+    expect(out[0]).toBe(0)
+    near(out[1] ?? 0, 1)
+    expect(out[2]).toBe(0)
+  })
+
+  it('an all-negative series renders empty rather than inverted', () => {
+    expect(normalizeToMax([-1, -2, -3])).toEqual([0, 0, 0])
+  })
+
+  it('reads non-finite entries as zero', () => {
+    const out = normalizeToMax([NaN, null, undefined, Infinity, 8])
+    expect(out.slice(0, 4)).toEqual([0, 0, 0, 0])
+    near(out[4] ?? 0, 1)
+  })
+
+  it('does not rescale a sub-1 series against a phantom maximum', () => {
+    // The inlined `Math.max(...values, 1)` flattened this to [0.1, 0.2].
+    const out = normalizeToMax([0.1, 0.2])
+    near(out[0] ?? 0, 0.5)
+    near(out[1] ?? 0, 1)
+  })
+
+  it('every fraction lands inside 0..1', () => {
+    for (const f of normalizeToMax([...HOSTILE, 3, 9, 0.5])) {
+      expect(f).toBeGreaterThanOrEqual(0)
+      expect(f).toBeLessThanOrEqual(1)
+      expect(Number.isFinite(f)).toBe(true)
+    }
+  })
+
+  it('walks a large array instead of spreading it', () => {
+    const big = Array.from({ length: 200_000 }, (_, i) => i)
+    const out = normalizeToMax(big)
+    expect(out).toHaveLength(200_000)
+    near(out[199_999] ?? 0, 1)
+    expect(out[0]).toBe(0)
+  })
+})
+
+describe('stackTotals', () => {
+  it('empty input yields no columns', () => {
+    expect(stackTotals([])).toEqual([])
+    expect(stackTotals([[], []])).toEqual([])
+  })
+
+  it('sums each column', () => {
+    expect(
+      stackTotals([
+        [1, 2, 3],
+        [4, 5, 6],
+      ]),
+    ).toEqual([5, 7, 9])
+  })
+
+  it('tolerates ragged rows', () => {
+    expect(stackTotals([[1, 2, 3], [10]])).toEqual([11, 2, 3])
+  })
+
+  it('excludes negatives and non-finite entries', () => {
+    expect(stackTotals([[5, NaN, -3], [null, 4, undefined]])).toEqual([5, 4, 0])
+  })
+
+  it('an all-zero column totals zero, not one', () => {
+    expect(stackTotals([[0, 5], [0, 5]])).toEqual([0, 10])
+  })
+})
+
+describe('stackFractions', () => {
+  it('preserves shape, including raggedness', () => {
+    const out = stackFractions([[1, 2, 3], [1]])
+    expect(out).toHaveLength(2)
+    expect(out[0]).toHaveLength(3)
+    expect(out[1]).toHaveLength(1)
+  })
+
+  it('each populated column sums to one', () => {
+    const series = [
+      [10, 1, 4],
+      [30, 3, 0],
+      [60, 6, 0],
+    ]
+    const out = stackFractions(series)
+    for (let column = 0; column < 3; column++) {
+      const sum = out.reduce((acc, row) => acc + (row[column] ?? 0), 0)
+      near(sum, 1)
+    }
+    near(out[0]?.[0] ?? 0, 0.1)
+    near(out[2]?.[0] ?? 0, 0.6)
+  })
+
+  it('an all-zero column stays empty instead of becoming a full bar', () => {
+    const out = stackFractions([[0, 5], [0, 5]])
+    expect(out[0]?.[0]).toBe(0)
+    expect(out[1]?.[0]).toBe(0)
+    near(out[0]?.[1] ?? 0, 0.5)
+  })
+
+  it('a single series fills its column', () => {
+    expect(stackFractions([[3, 9]])).toEqual([[1, 1]])
+  })
+
+  it('reads negatives and non-finite entries as zero', () => {
+    const out = stackFractions([[-4, NaN], [8, 2]])
+    expect(out[0]).toEqual([0, 0])
+    expect(out[1]).toEqual([1, 1])
+  })
+
+  it('every fraction is finite and inside 0..1', () => {
+    for (const row of stackFractions([HOSTILE, HOSTILE])) {
+      for (const f of row) {
+        expect(Number.isFinite(f)).toBe(true)
+        expect(f).toBeGreaterThanOrEqual(0)
+        expect(f).toBeLessThanOrEqual(1)
+      }
+    }
+  })
+})
+
+describe('monthDomain', () => {
+  it('a single month is a one-entry domain', () => {
+    expect(monthDomain('2026-03-01', '2026-03-28')).toEqual(['2026-03-01'])
+  })
+
+  it('walks across a year boundary', () => {
+    expect(monthDomain('2025-11-01', '2026-02-01')).toEqual([
+      '2025-11-01',
+      '2025-12-01',
+      '2026-01-01',
+      '2026-02-01',
+    ])
+  })
+
+  it('is timezone-free — the same strings on any machine', () => {
+    const months = monthDomain('2026-01-01', '2026-12-31')
+    expect(months).toHaveLength(12)
+    expect(months[0]).toBe('2026-01-01')
+    expect(months[11]).toBe('2026-12-01')
+  })
+
+  it('an inverted range yields nothing', () => {
+    expect(monthDomain('2026-06-01', '2026-01-01')).toEqual([])
+  })
+
+  it('unparseable bounds yield nothing', () => {
+    expect(monthDomain('', '2026-01-01')).toEqual([])
+    expect(monthDomain('nope', 'also nope')).toEqual([])
+    expect(monthDomain('2026-13-01', '2026-14-01')).toEqual([])
+    expect(monthDomain('2026-00-01', '2026-02-01')).toEqual([])
+  })
+
+  it('caps an absurd span instead of allocating without bound', () => {
+    expect(monthDomain('0001-01-01', '9999-12-01')).toHaveLength(1200)
+  })
+})
+
+describe('never emits NaN or Infinity', () => {
+  it('holds across every function for every hostile input', () => {
+    for (const a of HOSTILE) {
+      for (const b of HOSTILE) {
+        const scale = linearScale([toNumber(a), toNumber(b)], [0, 100])
+        expect(Number.isFinite(scale(a))).toBe(true)
+        expect(Number.isFinite(scale(b))).toBe(true)
+
+        const band = bandScale(a, b, 0.2)
+        expect(Number.isFinite(band.band)).toBe(true)
+        expect(Number.isFinite(band.step)).toBe(true)
+        expect(Number.isFinite(band.at(a))).toBe(true)
+        expect(Number.isFinite(band.center(b))).toBe(true)
+
+        expect(Number.isFinite(clampPct(a))).toBe(true)
+
+        const ring = ringDash(a, b, 2)
+        expect(Number.isFinite(ring.radius)).toBe(true)
+        expect(Number.isFinite(ring.dasharray)).toBe(true)
+        expect(Number.isFinite(ring.dashoffset)).toBe(true)
+
+        expect(linePath([{ x: toNumber(a), y: toNumber(b) }])).not.toMatch(
+          /NaN|Infinity/,
+        )
+        expect(
+          areaPath([{ x: 0, y: 0 }, { x: toNumber(a), y: toNumber(b) }], a),
+        ).not.toMatch(/NaN|Infinity/)
+      }
+    }
+  })
+})
+
+/* ── test-local helpers ──────────────────────────────────────────────── */
+
+/** `Number` view of a hostile scalar, for feeding tuple-typed parameters. */
+function toNumber(value: NumericInput): number {
+  return typeof value === 'number' ? value : NaN
+}
+
+/** A plottable coordinate derived from a hostile scalar. */
+function finiteish(value: NumericInput): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+/** The module's own 3dp path rounding, mirrored for dash assertions. */
+function round3(value: number): number {
+  return Math.round(value * 1000) / 1000
+}
+
+/* ── axis fitting (the 2026-09-06 axis-legibility fixes) ─────────────── */
+
+describe('estimateTextWidth', () => {
+  it('is at least as wide as the browser measured, and not wildly wider', () => {
+    // Chromium, off the shipped gallery, 2026-09-06. The estimate must never
+    // come in UNDER these — an under-estimate ships the overlap the
+    // collision pass exists to prevent — and must stay within ~15% so it
+    // does not drop labels that would have fitted.
+    const measured: readonly (readonly [string, number, number])[] = [
+      ['Wk 1', 14, 32.33],
+      ['Wk 10', 14, 40.91],
+      ['8,240', 12, 34.28],
+      ['13,390', 12, 42.05],
+      ['96.2%', 12, 38.58],
+      ['$17,460', 12, 49.86],
+    ]
+    for (const [text, size, actual] of measured) {
+      const estimate = estimateTextWidth(text, size)
+      expect(estimate).toBeGreaterThanOrEqual(actual)
+      expect(estimate).toBeLessThan(actual * 1.15)
+    }
+  })
+
+  it('is total: empty text and hostile sizes are 0, never NaN', () => {
+    expect(estimateTextWidth('', 14)).toBe(0)
+    expect(estimateTextWidth('abc', 0)).toBe(0)
+    expect(estimateTextWidth('abc', Number.NaN)).toBe(0)
+    expect(estimateTextWidth('abc', -14)).toBe(0)
+    expect(Number.isFinite(estimateTextWidth('abc', Number.POSITIVE_INFINITY))).toBe(
+      true,
+    )
+  })
+})
+
+describe('fitTickCount', () => {
+  it('gives a tall axis the count it asked for', () => {
+    // 5 ticks over 400px are 100px apart, well clear of the 42px floor.
+    expect(fitTickCount(400, 42, 5)).toBe(5)
+  })
+
+  it('shortens the ladder when the plot is short — the 390 defect', () => {
+    // The measured failure: five $50,000-shaped labels in a plot barely
+    // taller than one of them. 84px holds three (42px apart); 40px holds
+    // the floor of two, and never fewer.
+    expect(fitTickCount(84, 42, 5)).toBe(3)
+    expect(fitTickCount(40, 42, 5)).toBe(2)
+    expect(fitTickCount(0.5, 42, 5)).toBe(2)
+  })
+
+  it('never draws more than six, however many are requested', () => {
+    expect(fitTickCount(4000, 42, 12)).toBe(6)
+  })
+
+  it('leaves an unmeasured axis exactly as requested', () => {
+    // Before the ResizeObserver lands. Collapsing to two and then visibly
+    // re-expanding is worse than one frame of the requested ladder.
+    expect(fitTickCount(0, 42, 5)).toBe(5)
+    expect(fitTickCount(400, 0, 5)).toBe(5)
+    expect(fitTickCount(Number.NaN, 42, 5)).toBe(5)
+  })
+
+  it('clamps a nonsense request into [2, 6]', () => {
+    expect(fitTickCount(400, 42, 0)).toBe(2)
+    expect(fitTickCount(400, 42, -3)).toBe(2)
+    expect(fitTickCount(400, 42, Number.NaN)).toBe(5)
+  })
+})
+
+describe('fitTicks', () => {
+  it('keeps a six-rung ladder when six rungs fit', () => {
+    // niceTicks(0, 1, 5) legitimately returns SIX ticks — it rounds the
+    // domain outward. Rejecting that when it fits was the first version's
+    // bug: the target and the limit are different numbers.
+    expect(fitTicks(0, 1, 260, 42, 5)).toEqual([0, 0.2, 0.4, 0.6, 0.8, 1])
+  })
+
+  it('searches down until the RETURNED ladder fits, not the target', () => {
+    const ticks = fitTicks(0, 1, 143, 42, 5)
+    // 143px holds four rungs at 42px apart.
+    expect(ticks.length).toBeLessThanOrEqual(4)
+    expect(ticks[0]).toBe(0)
+    expect(ticks[ticks.length - 1]).toBe(1)
+  })
+
+  it('is exactly niceTicks when the plot is unmeasured', () => {
+    expect(fitTicks(0, 1, 0, 42, 5)).toEqual(niceTicks(0, 1, 5))
+  })
+
+  it('never returns fewer than two ticks for a real range', () => {
+    expect(fitTicks(0, 50000, 5, 42, 5).length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('still collapses a flat domain to one tick', () => {
+    expect(fitTicks(7, 7, 400, 42, 5)).toEqual([7])
+  })
+
+  it('subsamples when even the two-tick target overshoots', () => {
+    // `niceTicks(-50000, 50000, 2)` rounds out to a 100,000 step and returns
+    // THREE rungs. In a 33px plot that painted
+    // "$50,000 / $0 / -$50,000" overlapping by 4.4px, because the downward
+    // search had already bottomed out at the two-tick floor.
+    expect(niceTicks(-50000, 50000, 2)).toHaveLength(3)
+    const fitted = fitTicks(-50000, 50000, 33, 42, 5)
+    expect(fitted).toHaveLength(2)
+    // The DRAWN domain is unchanged — only gridlines are dropped.
+    expect(fitted[0]).toBe(-100000)
+    expect(fitted[1]).toBe(100000)
+  })
+})
+
+describe('fitLabelCount', () => {
+  it('divides the axis by the label extent', () => {
+    expect(fitLabelCount(608, 53, 8)).toBe(8)
+    expect(fitLabelCount(234, 53, 8)).toBe(4)
+  })
+
+  it('never goes below the floor, and never above the request', () => {
+    expect(fitLabelCount(20, 53, 8)).toBe(2)
+    expect(fitLabelCount(4000, 53, 8)).toBe(8)
+  })
+
+  it('leaves an unmeasured axis as requested', () => {
+    expect(fitLabelCount(0, 53, 8)).toBe(8)
+    expect(fitLabelCount(608, 0, 8)).toBe(8)
+  })
+
+  it('can answer "not even two fit" when the floor is 0', () => {
+    // A 26px-wide plot holds no 32px label, and two of them overlapped by
+    // 10px until the caller could ask this question.
+    expect(fitLabelCount(26, 54, 8, 0)).toBe(0)
+    expect(fitLabelCount(120, 54, 8, 0)).toBe(2)
+  })
+})
+
+describe('strideIndices', () => {
+  it('thins 12 positions to a UNIFORM stride, first and last kept', () => {
+    // The defect: `round(i / (max - 1) * last)` produced
+    // [0, 2, 3, 5, 6, 8, 9, 11] — 3&4, 6&7 and 9&10 adjacent while 2, 5, 8
+    // and 11 were skipped, so the axis read as irregular DATA.
+    expect(strideIndices(12, 8)).toEqual([0, 2, 4, 6, 8, 11])
+  })
+
+  it('drops the second-to-last, never an interior one, when the end collides', () => {
+    const kept = strideIndices(12, 8)
+    expect(kept).toContain(0)
+    expect(kept).toContain(11)
+    expect(kept).not.toContain(10)
+    // Every interior gap is the same stride.
+    const gaps = kept.slice(1, -1).map((v, i) => v - (kept[i] ?? 0))
+    expect(new Set(gaps).size).toBe(1)
+  })
+
+  it('keeps everything when it already fits', () => {
+    expect(strideIndices(5, 8)).toEqual([0, 1, 2, 3, 4])
+    expect(strideIndices(8, 8)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
+  })
+
+  it('appends the last index when it does not collide', () => {
+    // 13 positions, max 8 → stride 2 → 0,2,4,6,8,10,12: the last IS on the
+    // stride, so nothing is dropped.
+    expect(strideIndices(13, 8)).toEqual([0, 2, 4, 6, 8, 10, 12])
+  })
+
+  it('never exceeds the cap, at any size', () => {
+    for (const n of [9, 13, 30, 90, 365, 1000]) {
+      for (const max of [2, 3, 5, 8]) {
+        const kept = strideIndices(n, max)
+        expect(kept.length).toBeLessThanOrEqual(max)
+        expect(kept[0]).toBe(0)
+        expect(kept[kept.length - 1]).toBe(n - 1)
+        // Strictly ascending, no duplicates.
+        for (let i = 1; i < kept.length; i++) {
+          expect(kept[i]).toBeGreaterThan(kept[i - 1] ?? -1)
+        }
+      }
+    }
+  })
+
+  it('is total on hostile input', () => {
+    expect(strideIndices(0, 8)).toEqual([])
+    expect(strideIndices(-4, 8)).toEqual([])
+    expect(strideIndices(Number.NaN, 8)).toEqual([])
+    expect(strideIndices(5, 0)).toEqual([0, 4])
+    expect(strideIndices(5, Number.NaN)).toEqual([0, 4])
+  })
+})