@eifi1/ui-kit 0.54.0 → 0.55.0

package/src/theme/chart-palette.ts

@@ -1,232 +0,0 @@
-// Chart colour system. Single source of truth lives in the design tokens
-// (:root / .dark in tokens.css): brand = indigo, money = teal/amber/purple,
-// chart-1..8 = anyplot's "Imprint" hues (https://anyplot.ai/palette, 0.49 — Paul Tol
-// "Muted" before, still selectable as the `paul-tol` preset).
-// Returning CSS vars here makes every Recharts series theme-aware for free — the
-// SVG fill/stroke resolves --chart-N against the current light/dark token set.
-
-import { contrast, parseHex as parseRgbHex } from "./color";
-
-/** How many categorical slots `paletteFor` cycles through: anyplot's eight hues. Amber,
- *  anyplot's ninth colour, is a semantic warning anchor and not a series slot. A preset
- *  that carries more hues (Paul Tol's nine) still writes them as `--chart-N`, but the
- *  by-index ramp wraps after eight, so the same series keeps the same colour whichever
- *  preset is active. */
-export const PALETTE_SIZE = 8;
-
-/** anyplot's colour-vision-deficiency-optimal order over the eight slots — the order
- *  that keeps the FIRST n series furthest apart under protan/deutan/tritan simulation.
- *  An option (`paletteFor(i, { order: "cvd" })`), not the default: the default order is
- *  anyplot's own slot order, so series 1 is always the green. */
-export const CVD_ORDER = [0, 1, 7, 6, 4, 5, 2, 3] as const;
-
-export interface PaletteForOptions {
-  /** `"slot"` (default): anyplot's slot order. `"cvd"`: {@link CVD_ORDER}. */
-  order?: "slot" | "cvd";
-}
-
-/** CVD-safe categorical colour for series `index`, as a theme-aware CSS var.
- *
- *  The first series is always slot 0 (`--chart-1`, anyplot's green), and the ramp
- *  wraps after {@link PALETTE_SIZE}.
- *
- *  Wraps in both directions, the way `strokeDash` does: JS `%` keeps the sign,
- *  so `-1 % 8` is `-1` and the plain formula named `--chart-0`, a token that does not
- *  exist — a series with no stroke at all. A fractional index is truncated, and one
- *  that is not a number (NaN, ±Infinity — an `indexOf` miss divided by something)
- *  takes the first colour rather than `var(--chart-NaN)`. */
-export function paletteFor(index: number, options?: PaletteForOptions): string {
-  const i = Number.isFinite(index) ? Math.trunc(index) : 0;
-  const position = ((i % PALETTE_SIZE) + PALETTE_SIZE) % PALETTE_SIZE;
-  const slot = options?.order === "cvd" ? CVD_ORDER[position] : position;
-  return `var(--chart-${slot + 1})`;
-}
-
-/** Semantic money colours, theme-aware via tokens. Pair with +/- and arrow
-    cues at the call site so colour is never the only signal (CVD). */
-export const CHART_COLORS = {
-  income: "var(--money-income)",
-  expense: "var(--money-expense)",
-  net: "var(--money-net)",
-  neutral: "var(--money-neutral)",
-  assigned: "var(--brand)",
-  activity: "var(--money-expense)",
-  /** A generic total line — not money-coloured, the chart's neutral ink. */
-  total: "var(--chart-ink)",
-} as const;
-
-/**
- * What a chart draws that is NOT a series (anyplot's roles, 0.49). Two inks, which are
- * the only chart colours that change between light and dark — the eight hues do not:
- *
- * - `other` / `rest` / `disabled` and confidence-`band` fills → the MUTED ink. A
- *   treemap's "rest" bucket or a pie's "Other" slice takes this instead of wrapping
- *   round to a hue the reader will match to a real series.
- * - `total` / `baseline` / `outline` → the neutral INK.
- */
-export const CHART_ROLES = {
-  other: "var(--chart-muted)",
-  rest: "var(--chart-muted)",
-  disabled: "var(--chart-muted)",
-  band: "var(--chart-muted)",
-  total: "var(--chart-ink)",
-  baseline: "var(--chart-ink)",
-  outline: "var(--chart-ink)",
-} as const;
-
-/** `--chart-muted` per theme, as hex (tokens.css holds the same two). */
-export const CHART_MUTED_HEX = { light: "#6b6a63", dark: "#a8a79f" } as const;
-
-/** The 3:1 WCAG 1.4.11 asks of a filled graphical object against its surface. */
-export const EDGE_MIN_CONTRAST = 3;
-
-/**
- * The 1px edge a FILLED mark (a bar, an area, a treemap tile) needs, or `undefined`.
- *
- * anyplot's answer to hues that sit under 3:1 on the ground (cyan, lime, lavender, ochre
- * and green on cream; matte red and rose on the dark ground): outline the shape in ink,
- * so its boundary is legible while the fill keeps the hue that identifies the series.
- * Only those — a hue that clears 3:1 on every surface given stays unstroked, because an
- * outline on every bar is noise.
- *
- * `fill` must be a measurable `#rgb`/`#rrggbb`; `surfaces` are the grounds the mark can
- * sit on (the card and the page), and the WORST of them decides. Anything it cannot
- * measure gets no edge rather than a guessed one.
- */
-export function chartEdge(
-  fill: string,
-  surfaces: readonly string[],
-  ink: string = CHART_ROLES.outline,
-): string | undefined {
-  if (!parseRgbHex(fill)) return undefined;
-  const measurable = surfaces.filter((s) => parseRgbHex(s));
-  if (measurable.length === 0) return undefined;
-  const worst = Math.min(...measurable.map((s) => contrast(fill, s)));
-  return worst < EDGE_MIN_CONTRAST ? ink : undefined;
-}
-
-// ── Raw hex stops, by theme ────────────────────────────────────────────────
-// The heatmaps interpolate colours in JS (CSS vars can't be lerped), so they
-// need concrete hex per theme — i.e. the same colours DEFAULT_PRESET already
-// holds, written down a second time.
-//
-// They are duplicated rather than imported because these two objects are the whole
-// of the `@eifi1/ui-kit/chart` subpath's colour layer, and importing the preset bank
-// would pull every preset's full token set into that chunk to read two of them. What
-// keeps the copies together is `chart-palette.test.ts` — "has not drifted from
-// DEFAULT_PRESET" — which is not optional: they HAD drifted, five of the six light
-// heat stops, and the light `neutral` was still Tailwind's slate-100, a cool grey on
-// the warm cream page this theme has used since #328.
-//
-// 0.49: the same eight hues in both themes — anyplot does not re-tune a hue for the dark
-// ground, and neither does the kit any more; `chartEdge` outlines the two that fall
-// under 3:1 there (matte red, rose) instead of lifting them into different colours.
-const IMPRINT_HEX = ["#009e73", "#c475fd", "#4467a3", "#bd8233", "#ae3030", "#2abccd", "#954477", "#99b314"] as const;
-export const PALETTE_HEX = {
-  light: IMPRINT_HEX,
-  dark: IMPRINT_HEX,
-} as const;
-
-/** A heatmap's interpolation stops for one theme. Open string fields so any
-    palette preset (not just the built-in default) can supply its own stops. */
-export interface HeatStops {
-  neutral: string;
-  under: string;
-  over: string;
-  seqLow: string;
-  seqHigh: string;
-  empty: string;
-}
-
-/** Diverging (variance: under←0→over) and sequential (spending intensity)
-    heatmap stops, per theme — anyplot's scales (0.49). Sequential runs anyplot green →
-    blue; diverging runs blue (under) ↔ paper/ink (0, the midpoint) ↔ matte red (over).
-    The hues are the same in both themes; only the midpoint flips with the ground. */
-export const HEATMAP_HEX = {
-  light: {
-    neutral: "#faf8f1", // anyplot's light paper — the diverging scale's 0
-    under: "#4467a3",
-    over: "#ae3030",
-    seqLow: "#009e73",
-    seqHigh: "#4467a3",
-    empty: "rgba(148,163,184,0.14)",
-  },
-  dark: {
-    neutral: "#1a1a17", // anyplot's ink — the diverging scale's 0 on the dark ground
-    under: "#4467a3",
-    over: "#ae3030",
-    seqLow: "#009e73",
-    seqHigh: "#4467a3",
-    empty: "rgba(148,163,184,0.10)",
-  },
-} as const;
-
-/** Linear interpolate two #rrggbb hexes; `t` in [0,1]. Returns #rrggbb. */
-export function lerpHex(a: string, b: string, t: number): string {
-  const pa = parseHex(a) ?? UNREADABLE;
-  const pb = parseHex(b) ?? UNREADABLE;
-  const c = (i: number) => Math.round(pa[i] + (pb[i] - pa[i]) * clamp01(t));
-  return `#${[c(0), c(1), c(2)].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
-}
-
-/** The two inks a cell/treemap label can be set in. Near-black and near-white rather
-    than #000/#fff: at full black-on-full-white the label stops looking like part of the
-    same type system as the rest of the page. */
-const INK_DARK = "#1a1a1a";
-const INK_LIGHT = "#f8fafc";
-
-/** Pick a legible text colour (near-black / near-white) for a solid hex fill, by
-    MEASURING both against it and keeping the one that wins.
-
-    This used to flip on Rec.601 luma > 0.6, which is a brightness heuristic and not a
-    contrast measure — the two disagree on six of the eighteen default chart hues, a
-    third of the ramp, and on each of those the label got the worse of the two inks.
-    `#44aa99` is the plainest case: luma calls it dark, so it took white, which measures
-    2.69:1 on it; near-black measures 6.18:1. keksdose measured this too and forked the
-    function locally for its treemap, leaving its other two call sites on this one.
-
-    A fill this cannot read gets `currentColor` — inherit, i.e. whatever the
-    surrounding text already uses. That is the only answer that is right on both
-    themes, because an unreadable fill is usually a translucent one (`HEATMAP_HEX.*
-    .empty` is an `rgba()` string, and the variance heatmap does pass it here for any
-    category with zero assigned and positive activity — a refund). Picking a constant
-    instead is what produced the earlier bug: the unparsed fill fell through to the
-    light ink, near-white on a near-white cell, and the figure was invisible. */
-export function textOn(hex: string): string {
-  const rgb = parseRgbHex(hex);
-  if (!rgb) return "currentColor";
-  // Ties go to the dark ink: at equal measured contrast it is the one that keeps a
-  // small label looking like type rather than like a glow.
-  return contrast(rgb, INK_DARK) >= contrast(rgb, INK_LIGHT) ? INK_DARK : INK_LIGHT;
-}
-
-/** Mid-grey, for a stop {@link lerpHex} has to interpolate but cannot read. It has
- *  to return SOME valid colour, and a grey is the one that misleads least. */
-const UNREADABLE: [number, number, number] = [0x80, 0x80, 0x80];
-
-/**
- * `#rgb` or `#rrggbb` to components, or **null** when it is neither.
- *
- * A tuple-shaped shim over `color.ts`'s parser, which is the same function and is
- * already the one `contrast` validates with — so {@link lerpHex} and {@link textOn}
- * cannot disagree about what counts as a colour.
- *
- * The **null** is the whole point of it. This used to `parseInt` whatever it was given
- * and hand the NaNs on, and both callers propagated them silently: {@link lerpHex}
- * produced the literal string `"#nannannan"`, and {@link textOn} fell through to the
- * LIGHT label colour.
- *
- * That is not hypothetical — a non-hex value ships in this very module.
- * `HEATMAP_HEX.*.empty` is an `rgba(…)` string, and the variance heatmap paints a
- * figure on an `empty` cell whenever a category has zero assigned and positive
- * activity (a refund). On the light theme the cell is near-white and the label came
- * back near-white: the number was there, and unreadable.
- */
-function parseHex(hex: string): [number, number, number] | null {
-  const rgb = parseRgbHex(hex);
-  return rgb ? [rgb.r, rgb.g, rgb.b] : null;
-}
-
-function clamp01(t: number): number {
-  return t < 0 ? 0 : t > 1 ? 1 : t;
-}

package/src/theme/color.ts

@@ -1,272 +0,0 @@
-/**
- * Colour maths for the palette system: sRGB ↔ OKLab ↔ OKLCH, WCAG contrast, gamut
- * clipping, and colour-vision-deficiency simulation.
- *
- * Dependency-free on purpose. This package already ships 48MB of runtime dependencies
- * for a 1.4MB library, and a colour-space conversion is forty lines of arithmetic that
- * will not change — importing culori or chroma-js to get it would be the largest
- * dependency in the kit, paid for by every consumer, to avoid writing down formulas
- * that were published once and are now fixed.
- *
- * **Why OKLCH rather than HSL.** HSL's "lightness" is not lightness: `hsl(60 100% 50%)`
- * (yellow) and `hsl(240 100% 50%)` (blue) claim the same 50% and differ by a factor of
- * about twelve in perceived brightness. Any scheme that derives a palette by holding HSL
- * lightness constant therefore produces a set that looks wildly uneven, and any scheme
- * that solves for contrast in HSL has to solve separately per hue. OKLab is built so a
- * given L means the same apparent lightness at every hue, which is what makes "same
- * lightness, different hue" a usable rule and what makes a contrast solve converge.
- *
- * Reference: Björn Ottosson, "A perceptual color space for image processing" (2020).
- */
-
-export interface Rgb {
-  /** 0–255. */
-  r: number;
-  g: number;
-  b: number;
-}
-
-export interface Oklch {
-  /** Perceptual lightness, 0–1. */
-  l: number;
-  /** Chroma, 0–~0.4 in sRGB. */
-  c: number;
-  /** Hue angle in degrees, 0–360. */
-  h: number;
-}
-
-/* ── sRGB ─────────────────────────────────────────────────────────────────── */
-
-/** `#rgb` or `#rrggbb` → components, or null when it is neither. */
-export function parseHex(hex: string): Rgb | null {
-  const h = hex.trim().replace(/^#/, "");
-  const full =
-    h.length === 3
-      ? h
-          .split("")
-          .map((c) => c + c)
-          .join("")
-      : h;
-  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null;
-  return {
-    r: parseInt(full.slice(0, 2), 16),
-    g: parseInt(full.slice(2, 4), 16),
-    b: parseInt(full.slice(4, 6), 16),
-  };
-}
-
-export function toHex({ r, g, b }: Rgb): string {
-  const part = (v: number) =>
-    Math.max(0, Math.min(255, Math.round(v)))
-      .toString(16)
-      .padStart(2, "0");
-  return `#${part(r)}${part(g)}${part(b)}`;
-}
-
-/** sRGB 0–255 → linear-light 0–1. The transfer function, not a gamma of 2.2. */
-function toLinear(channel: number): number {
-  const c = channel / 255;
-  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
-}
-
-function fromLinear(channel: number): number {
-  const c = channel <= 0.0031308 ? 12.92 * channel : 1.055 * channel ** (1 / 2.4) - 0.055;
-  return c * 255;
-}
-
-/* ── OKLab / OKLCH ────────────────────────────────────────────────────────── */
-
-export function rgbToOklch(rgb: Rgb): Oklch {
-  const r = toLinear(rgb.r);
-  const g = toLinear(rgb.g);
-  const b = toLinear(rgb.b);
-
-  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
-  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
-  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
-
-  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
-  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
-  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
-
-  const c = Math.sqrt(A * A + B * B);
-  // Hue is meaningless at zero chroma; 0 keeps it stable rather than NaN-adjacent.
-  const h = c < 1e-6 ? 0 : ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360;
-  return { l: L, c, h };
-}
-
-/** OKLCH → sRGB, WITHOUT gamut clipping. May return components outside 0–255. */
-function oklchToRgbRaw({ l, c, h }: Oklch): Rgb {
-  const rad = (h * Math.PI) / 180;
-  const A = c * Math.cos(rad);
-  const B = c * Math.sin(rad);
-
-  const l_ = (l + 0.3963377774 * A + 0.2158037573 * B) ** 3;
-  const m_ = (l - 0.1055613458 * A - 0.0638541728 * B) ** 3;
-  const s_ = (l - 0.0894841775 * A - 1.291485548 * B) ** 3;
-
-  return {
-    r: fromLinear(4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_),
-    g: fromLinear(-1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_),
-    b: fromLinear(-0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_),
-  };
-}
-
-function inGamut({ r, g, b }: Rgb): boolean {
-  const ok = (v: number) => v >= -0.5 && v <= 255.5;
-  return ok(r) && ok(g) && ok(b);
-}
-
-/**
- * OKLCH → sRGB, reducing CHROMA until the colour fits.
- *
- * Clamping the channels instead — the obvious approach — shifts hue and lightness
- * together and unpredictably: a saturated blue that overflows clips to a different blue
- * that is also lighter. Holding L and h and giving up chroma keeps the colour
- * recognisably the one that was asked for, which matters when the whole point is to
- * derive a family at a fixed lightness.
- */
-export function oklchToRgb(target: Oklch): Rgb {
-  const direct = oklchToRgbRaw(target);
-  if (inGamut(direct)) return direct;
-
-  let lo = 0;
-  let hi = target.c;
-  // 20 halvings resolves chroma to ~4e-7, far below a perceptible step.
-  for (let i = 0; i < 20; i++) {
-    const mid = (lo + hi) / 2;
-    if (inGamut(oklchToRgbRaw({ ...target, c: mid }))) lo = mid;
-    else hi = mid;
-  }
-  return oklchToRgbRaw({ ...target, c: lo });
-}
-
-export function hexToOklch(hex: string): Oklch | null {
-  const rgb = parseHex(hex);
-  return rgb ? rgbToOklch(rgb) : null;
-}
-
-export function oklchToHex(lch: Oklch): string {
-  return toHex(oklchToRgb(lch));
-}
-
-/* ── WCAG contrast ────────────────────────────────────────────────────────── */
-
-/** WCAG 2.x relative luminance. */
-export function luminance(rgb: Rgb): number {
-  return 0.2126 * toLinear(rgb.r) + 0.7152 * toLinear(rgb.g) + 0.0722 * toLinear(rgb.b);
-}
-
-/** WCAG 2.x contrast ratio, 1–21. Order-independent. */
-export function contrast(a: Rgb | string, b: Rgb | string): number {
-  const ra = typeof a === "string" ? parseHex(a) : a;
-  const rb = typeof b === "string" ? parseHex(b) : b;
-  if (!ra || !rb) return 1;
-  const la = luminance(ra);
-  const lb = luminance(rb);
-  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
-}
-
-/**
- * The lightness at hue `h`, chroma `c` that hits `target` contrast against `against`.
- *
- * Binary search rather than algebra: OKLab lightness does not map to WCAG luminance in
- * closed form, and it is not even monotonic in the general case once gamut clipping
- * starts reducing chroma. It IS monotonic over the half-range we search — away from the
- * background — which is why the direction is chosen first.
- *
- * Returns the best lightness found. If the target is unreachable at this hue and chroma
- * (a saturated yellow cannot make 7:1 against white at any lightness without going grey)
- * it returns the extreme end, and the caller should check the contrast it actually got
- * rather than assuming success — `deriveTokenSet` does exactly that.
- */
-export function solveLightness(
-  target: number,
-  against: Rgb,
-  h: number,
-  c: number,
-  direction: "lighter" | "darker",
-): number {
-  // The half-range on the far side of the background from where we are heading.
-  // Going darker, that is [0, backgroundL]; going lighter, [backgroundL, 1]. Contrast is
-  // monotonic across each of those halves, which is what makes a binary search valid —
-  // it is NOT monotonic across the whole 0..1 range, because it turns around at the
-  // background's own lightness.
-  const bgL = rgbToOklch(against).l;
-  let lo = direction === "darker" ? 0 : bgL;
-  let hi = direction === "darker" ? bgL : 1;
-  // Measured on the HEX both colours are painted as, never on the float (round 0.34
-  // BUG-8): a solve that stopped on the float colour rounded to a hex just under the
-  // target — brand #000000's light income figure solved to 4.5000 and shipped at 4.49:1.
-  // Rounding keeps contrast monotonic in each half, so the bisection still holds, and
-  // the side it returns is the side whose hex clears the target.
-  const bg = toHex(against);
-
-  for (let i = 0; i < 24; i++) {
-    const mid = (lo + hi) / 2;
-    const got = contrast(toHex(oklchToRgb({ l: mid, c, h })), bg);
-    // Moving AWAY from the background raises contrast; which way that is depends on
-    // whether we are going lighter or darker.
-    if (got < target) {
-      if (direction === "darker") hi = mid;
-      else lo = mid;
-    } else if (direction === "darker") lo = mid;
-    else hi = mid;
-  }
-  return direction === "darker" ? lo : hi;
-}
-
-/* ── Colour-vision deficiency ─────────────────────────────────────────────── */
-
-export type CvdType = "protanopia" | "deuteranopia" | "tritanopia";
-
-/**
- * Brettel/Viénot-style dichromat simulation in linear RGB.
- *
- * An approximation, and a well-established one. It is here so the kit can FAIL a
- * categorical ramp that two of its series become indistinguishable under, rather than
- * asserting CVD-safety in a comment the way `chart-palette.ts` did — the audit found
- * four of the nine default light chart hues below the 3:1 they were claimed to hold.
- */
-const CVD_MATRIX: Record<CvdType, number[][]> = {
-  protanopia: [
-    [0.1705, 0.8295, 0],
-    [0.1705, 0.8295, 0],
-    [-0.0045, 0.0045, 1],
-  ],
-  deuteranopia: [
-    [0.33066, 0.66934, 0],
-    [0.33066, 0.66934, 0],
-    [-0.02785, 0.02785, 1],
-  ],
-  tritanopia: [
-    [1, 0.1273, -0.1273],
-    [0, 0.8739, 0.1261],
-    [0, 0.8739, 0.1261],
-  ],
-};
-
-export function simulateCvd(rgb: Rgb, type: CvdType): Rgb {
-  const m = CVD_MATRIX[type];
-  const [r, g, b] = [toLinear(rgb.r), toLinear(rgb.g), toLinear(rgb.b)];
-  return {
-    r: fromLinear(m[0][0] * r + m[0][1] * g + m[0][2] * b),
-    g: fromLinear(m[1][0] * r + m[1][1] * g + m[1][2] * b),
-    b: fromLinear(m[2][0] * r + m[2][1] * g + m[2][2] * b),
-  };
-}
-
-/**
- * Perceptual distance in OKLab, which is what that space is FOR: a Euclidean distance
- * in OKLab corresponds far more closely to "how different do these look" than one in
- * sRGB, where the same numeric gap is obvious among greens and invisible among blues.
- */
-export function deltaE(a: Rgb, b: Rgb): number {
-  const A = rgbToOklch(a);
-  const B = rgbToOklch(b);
-  const aA = A.c * Math.cos((A.h * Math.PI) / 180);
-  const aB = A.c * Math.sin((A.h * Math.PI) / 180);
-  const bA = B.c * Math.cos((B.h * Math.PI) / 180);
-  const bB = B.c * Math.sin((B.h * Math.PI) / 180);
-  return Math.hypot(A.l - B.l, aA - bA, aB - bB);
-}