@lovett/ui 0.0.11 → 0.2.0

package/src/lib/series.ts

@@ -0,0 +1,169 @@
+/**
+ * series.ts — the categorical chart palette, resolved by a frozen literal
+ * lookup and nothing else.
+ *
+ * Promoted in ADR-146 D8. Canonical home for the palette so `ChartLegend`,
+ * `ChartTooltip` and every chart primitive resolve a hue the same way.
+ * Re-exported from `chart-legend.tsx` for the barrel.
+ *
+ * CONSUMERS — measured 2026-09-06, real imports inside `@lovett/ui` (7):
+ * `chart-legend.tsx`, `chart-tooltip.tsx`, `line-chart.tsx`,
+ * `bar-chart.tsx`, `donut-chart.tsx`, `ranked-bars.tsx`, `sparkline.tsx`.
+ * `ChartFrame` does NOT import it — it renders chrome and takes an
+ * already-coloured legend node — so the earlier claim naming it was wrong.
+ *
+ * WHY A FROZEN ARRAY AND NOT A CONSTRUCTED NAME
+ * ----------------------------------------------
+ * `ENGINEERING-AXES.md:186` records the exact defect this shape exists to
+ * prevent. A constructed custom-property name (`--folder-${key}`) produced
+ * `--folder-folder-violet`, which is undefined, which makes the enclosing
+ * `rgb()` invalid, which the browser **silently discards**. Typecheck, lint,
+ * tests, build and the token gate were all green while white-on-white tiles
+ * shipped. There is no gate that reads source and can see it, because the
+ * source is syntactically perfect.
+ *
+ * So no primitive in this package ever composes `` `--series-${i}` ``. The
+ * mapping is the literal array below, the same shape as `metric-card.tsx`'s
+ * `TONE_COLOR`, and `__tests__/chart-series.test.ts` asserts — with a
+ * mutation proof that the guard fails in the failing direction — that every
+ * entry names a custom property that `tokens.css` actually declares.
+ *
+ * Token discipline: this module produces `rgb(var(--token))` strings only. It
+ * contains no colour literal, and every token it names is a **bare RGB
+ * triple** in `tokens.css`, so a call site may legally apply its own alpha —
+ * `rgb(var(--series-1) / 0.12)` for the area fill under a line. That is
+ * asserted too: a series token that grew a baked-in alpha would make every
+ * such call site invalid CSS.
+ *
+ * CALLERS PASS A SLOT INDEX, NEVER A COLOUR AND NEVER A TOKEN NAME.
+ */
+
+/**
+ * The eight categorical series colours, in ADR-146 D2's **measured** order —
+ * blue, green, violet, olive, pink, amber, teal, red.
+ *
+ * The order is load-bearing, not cosmetic:
+ *
+ *   • **Blue is slot 1, not red.** Slot 1 is the single-series default, so a
+ *     red slot 1 would paint every one-series chart in the product accent and
+ *     destroy accent scarcity.
+ *   • **Red is slot 8.** Red belongs to `--accent` and `--destructive`. It
+ *     enters a chart only at eight series.
+ *   • **Green (slot 2) and red (slot 8) sit far apart**, so a two-series
+ *     chart never accidentally reads as pass/fail.
+ *
+ * Worst adjacent pair is ΔE 13.2 (deutan) / 21.0 (normal), identical in both
+ * themes — the palette is theme-independent by construction.
+ */
+export const SERIES = [
+  'rgb(var(--series-1))',
+  'rgb(var(--series-2))',
+  'rgb(var(--series-3))',
+  'rgb(var(--series-4))',
+  'rgb(var(--series-5))',
+  'rgb(var(--series-6))',
+  'rgb(var(--series-7))',
+  'rgb(var(--series-8))',
+] as const
+
+/**
+ * The all-pairs palette, capped at three (ADR-146 D2).
+ *
+ * Scatter, bubble, choropleth and small-multiples let any two marks touch, so
+ * they take the harder all-pairs colour-blindness test instead of the
+ * adjacent-pairs one. **Our eight hues cannot pass it — no ordering can.**
+ * These three (`--series-1` blue, `--series-6` amber, `--series-7` teal) do,
+ * at worst ΔE 14.8 in both modes.
+ *
+ * A scatter-family chart with more than three series folds the remainder into
+ * "Other" or facets into small multiples. It never generates a ninth hue.
+ */
+export const SERIES_SCATTER = [SERIES[0], SERIES[5], SERIES[6]] as const
+
+/** How many slots the default palette has. */
+export const SERIES_SLOT_COUNT = SERIES.length
+
+/** How many slots the all-pairs (`scatter`) palette has. */
+export const SCATTER_SLOT_COUNT = SERIES_SCATTER.length
+
+/**
+ * A legal slot in the default palette.
+ *
+ * Typed as a union rather than `number` so an out-of-range slot is a **type
+ * error at the boundary** (ADR-146 D8) rather than a runtime `undefined` that
+ * becomes invalid CSS. Callers holding a plain `number` narrow with
+ * `isSeriesSlot` and decide explicitly what a ninth series does.
+ */
+export type SeriesSlot = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
+
+/** A legal slot in the `scatter` palette. */
+export type ScatterSlot = 0 | 1 | 2
+
+/** Which palette a chart draws from. `scatter` is the all-pairs, 3-slot one. */
+export type SeriesPalette = 'default' | 'scatter'
+
+/** Narrow a plain number to a default-palette slot. */
+export function isSeriesSlot(value: number): value is SeriesSlot {
+  return Number.isInteger(value) && value >= 0 && value < SERIES_SLOT_COUNT
+}
+
+/** Narrow a plain number to a `scatter`-palette slot. */
+export function isScatterSlot(value: number): value is ScatterSlot {
+  return Number.isInteger(value) && value >= 0 && value < SCATTER_SLOT_COUNT
+}
+
+/** The default-palette colour for a slot. Total — the union type guarantees it. */
+export function seriesColor(slot: SeriesSlot): string {
+  return SERIES[slot]
+}
+
+/** The `scatter`-palette colour for a slot. Total. */
+export function scatterColor(slot: ScatterSlot): string {
+  return SERIES_SCATTER[slot]
+}
+
+/**
+ * The colour for `slot` in `palette`, or `undefined` when the slot is outside
+ * that palette's cap.
+ *
+ * `undefined` is the deliberate answer rather than a wrap-around or a clamp:
+ * ADR-146 D2 says a fourth scatter series folds into "Other", and silently
+ * reusing slot 1's blue for slot 4 would draw two different entities in one
+ * hue — a wrong chart that no gate can see. Consumers render the "Other"
+ * treatment (a neutral swatch) when this returns `undefined`.
+ */
+export function paletteColor(
+  palette: SeriesPalette,
+  slot: number,
+): string | undefined {
+  if (palette === 'scatter') {
+    return isScatterSlot(slot) ? scatterColor(slot) : undefined
+  }
+  return isSeriesSlot(slot) ? seriesColor(slot) : undefined
+}
+
+/**
+ * A palette slot, or the explicit `'other'` fold.
+ *
+ * `'other'` is how a chart says "this mark is the remainder". ADR-146 D2 caps
+ * the palette at eight slots (three for `scatter`) and folds the rest rather
+ * than generating a ninth hue, so the fold has to be representable in the
+ * data — not improvised at render time.
+ */
+export type ChartSlot = SeriesSlot | 'other'
+
+/** The neutral swatch for the `'other'` fold — a grey, never a hue. */
+export const OTHER_SLOT_COLOR = 'rgb(var(--text-muted))'
+
+/**
+ * The rendered colour for a `ChartSlot`. Total: anything the palette cannot
+ * legally colour — the `'other'` fold, or a slot past a palette's cap — comes
+ * back as the neutral swatch rather than wrapping onto a hue already in use.
+ *
+ * Shared by `ChartLegend` and `ChartTooltip` so a series cannot be one colour
+ * in the legend and another in the readout.
+ */
+export function slotColor(slot: ChartSlot, palette: SeriesPalette): string {
+  if (slot === 'other') return OTHER_SLOT_COLOR
+  return paletteColor(palette, slot) ?? OTHER_SLOT_COLOR
+}