@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/shell/option-switcher-menu.tsx

@@ -0,0 +1,72 @@
+import type { ReactNode } from "react";
+import { Check } from "lucide-react";
+import { HoverMenu } from "../components/hover-menu";
+import { TOPBAR_MENU_ITEM_CLASS, TOPBAR_TRIGGER_CLASS } from "./topbar-controls";
+import { Tooltip } from "../components/tooltip";
+
+export interface OptionSwitcherOption<T extends string> {
+  value: T;
+  label: ReactNode;
+}
+
+/**
+ * A top-bar hover menu that switches between a small set of options, with a
+ * check on the active one and an optional heading. Generic glue over
+ * {@link HoverMenu} — e.g. a dev role/impersonation switcher, an environment
+ * picker. Controlled: the app owns `value` and `onSelect`.
+ */
+export function OptionSwitcherMenu<T extends string>({
+  icon,
+  ariaLabel,
+  title,
+  heading,
+  options,
+  value,
+  onSelect,
+}: {
+  icon: ReactNode;
+  ariaLabel: string;
+  title?: string;
+  heading?: string;
+  options: OptionSwitcherOption<T>[];
+  value: T;
+  onSelect: (value: T) => void;
+}) {
+  return (
+    <HoverMenu
+      ariaLabel={ariaLabel}
+      trigger={({ toggle }) => (
+        <Tooltip label={title} portal>
+          <button type="button" onClick={toggle} aria-label={ariaLabel} className={TOPBAR_TRIGGER_CLASS}>
+            {icon}
+          </button>
+        </Tooltip>
+      )}
+    >
+      {(close) => (
+        <ul className="py-1">
+          {heading && (
+            <li className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+              {heading}
+            </li>
+          )}
+          {options.map((opt) => (
+            <li key={opt.value}>
+              <button
+                type="button"
+                onClick={() => {
+                  onSelect(opt.value);
+                  close();
+                }}
+                className={TOPBAR_MENU_ITEM_CLASS}
+              >
+                <span>{opt.label}</span>
+                {value === opt.value && <Check className="size-4 text-[var(--text-secondary)]" />}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </HoverMenu>
+  );
+}

package/src/shell/role-switcher.tsx

@@ -0,0 +1,46 @@
+import { FlaskConical } from "lucide-react";
+import { OptionSwitcherMenu } from "./option-switcher-menu";
+import { DEFAULT_TOP_BAR_LABELS, useKitLabels } from "../i18n/kit-labels";
+
+export interface RoleSwitcherProps<R extends string> {
+  roles: readonly R[];
+  value: R;
+  onChange: (role: R) => void;
+  /** Default: `topBar.switchRole` from the {@link UiKitProvider}, else English. */
+  ariaLabel?: string;
+  heading?: string;
+  /** The trigger's tooltip. Default: `topBar.role(value)`. */
+  title?: string;
+}
+
+/**
+ * A reusable user-role switcher (feedback #337): a thin wrapper over
+ * {@link OptionSwitcherMenu} with the standard flask icon, so an app drops it in
+ * the top bar with just the role list + current value + a handler. Typically
+ * dev-only / UI-only, but the app decides where and whether to render it.
+ *
+ * The flask wears `--warning` rather than a fixed `amber-500`: it is a caution
+ * marker — the app is not showing you your own role — and the token carries that
+ * amber across both themes instead of pinning one hue onto every palette.
+ */
+export function RoleSwitcher<R extends string>({
+  roles,
+  value,
+  onChange,
+  ariaLabel,
+  heading,
+  title,
+}: RoleSwitcherProps<R>) {
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { switchRole: ariaLabel });
+  return (
+    <OptionSwitcherMenu<R>
+      ariaLabel={labels.switchRole}
+      title={title ?? labels.role(value)}
+      heading={heading}
+      icon={<FlaskConical className="size-5 text-[var(--warning)]" />}
+      options={roles.map((r) => ({ value: r, label: r }))}
+      value={value}
+      onSelect={onChange}
+    />
+  );
+}

package/src/shell/top-bar.tsx

@@ -0,0 +1,39 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+/**
+ * `extends ComponentPropsWithoutRef<"header">` because this IS the `<header>`, and it is
+ * the `sticky top-0` element itself: a consumer cannot wrap it to add an attribute
+ * without the sticking moving to the wrapper. The one that matters most is `aria-label`
+ * — a `<header>` is a `banner` landmark, and a landmark with no name is how two of them
+ * become indistinguishable in a screen reader's landmark list.
+ */
+export interface TopBarProps extends ComponentPropsWithoutRef<"header"> {
+  brand: ReactNode;
+  actions?: ReactNode;
+  className?: string;
+}
+
+/**
+ * The sticky app header frame: a `brand` slot on the left and an `actions` slot
+ * on the right (theme/palette/language controls, account menu, etc.). Domain-free
+ * — each app composes its own actions from the shared controls plus its own menus.
+ */
+export function TopBar({ brand, actions, className, ...rest }: TopBarProps) {
+  return (
+    <header
+      {...rest}
+      className={cn(
+        // z-40 keeps the app header above sticky page content — notably the
+        // expanded transaction editor (z-30), which on mobile shares the page
+        // scroll and otherwise slid over the header while scrolling (feedback
+        // #320). Modals/tour (z-50/60) still sit above it.
+        "sticky top-0 z-40 flex h-12 items-center justify-between gap-2 border-b border-[var(--border)] bg-[var(--bg-surface)] px-3 md:px-6",
+        className,
+      )}
+    >
+      <div className="flex min-w-0 items-center gap-2">{brand}</div>
+      <div className="flex items-center gap-1">{actions}</div>
+    </header>
+  );
+}

package/src/shell/topbar-action-menu.tsx

@@ -0,0 +1,91 @@
+import type { ReactNode } from "react";
+import { Link } from "react-router";
+import { cn } from "../lib/cn";
+import { HoverMenu } from "../components/hover-menu";
+import { TOPBAR_MENU_ITEM_CLASS, TOPBAR_TRIGGER_CLASS } from "./topbar-controls";
+
+/**
+ * One row of a {@link TopBarActionMenu}. An `action` (default) runs `onSelect`, a
+ * `link` navigates via react-router, and a `divider` draws a rule. Non-divider
+ * rows close the menu automatically when chosen. `kind` may be omitted for
+ * actions, keeping the common case terse.
+ */
+export type TopBarMenuEntry =
+  | { kind?: "action"; key: string; icon?: ReactNode; label: ReactNode; trailing?: ReactNode; onSelect: () => void }
+  | { kind: "link"; key: string; icon?: ReactNode; label: ReactNode; trailing?: ReactNode; to: string }
+  | { kind: "divider"; key: string };
+
+/**
+ * A top-bar icon button that opens a {@link HoverMenu} of actions and/or links,
+ * with an optional uppercase heading and divider rules. Generic glue over the
+ * shared top-bar chrome — e.g. the feedback launcher or the guided-tours menu —
+ * so those call sites describe their rows as data instead of rebuilding the
+ * trigger + list markup. For a checkmarked value-switcher use
+ * {@link OptionSwitcherMenu} instead.
+ */
+export function TopBarActionMenu({
+  icon,
+  ariaLabel,
+  heading,
+  entries,
+  panelClassName,
+}: {
+  icon: ReactNode;
+  ariaLabel: string;
+  heading?: string;
+  entries: TopBarMenuEntry[];
+  panelClassName?: string;
+}) {
+  return (
+    <HoverMenu
+      ariaLabel={ariaLabel}
+      trigger={({ toggle }) => (
+        <button type="button" onClick={toggle} aria-label={ariaLabel} className={TOPBAR_TRIGGER_CLASS}>
+          {icon}
+        </button>
+      )}
+    >
+      {(close) => (
+        <ul className={cn("py-1", panelClassName)}>
+          {heading && (
+            <li className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+              {heading}
+            </li>
+          )}
+          {entries.map((entry) => {
+            if (entry.kind === "divider") {
+              return <li key={entry.key} className="my-1 border-t border-[var(--border)]" />;
+            }
+            const content = (
+              <span className="flex w-full items-center gap-2">
+                {entry.icon}
+                {entry.label}
+                {entry.trailing && <span className="ml-auto pl-2">{entry.trailing}</span>}
+              </span>
+            );
+            return (
+              <li key={entry.key}>
+                {entry.kind === "link" ? (
+                  <Link to={entry.to} onClick={close} className={TOPBAR_MENU_ITEM_CLASS}>
+                    {content}
+                  </Link>
+                ) : (
+                  <button
+                    type="button"
+                    onClick={() => {
+                      entry.onSelect();
+                      close();
+                    }}
+                    className={TOPBAR_MENU_ITEM_CLASS}
+                  >
+                    {content}
+                  </button>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </HoverMenu>
+  );
+}

package/src/shell/topbar-controls.tsx

@@ -0,0 +1,229 @@
+import { Check, Globe, Moon, Palette, Sun } from "lucide-react";
+import { cn } from "../lib/cn";
+import { HoverMenu } from "../components/hover-menu";
+import type { PalettePreset } from "../theme/palette-presets";
+import type { ThemeMode } from "../theme/theme-store";
+import { Tooltip } from "../components/tooltip";
+import { DEFAULT_TOP_BAR_LABELS, useKitLabels } from "../i18n/kit-labels";
+
+/** Shared square icon-button styling for top-bar triggers, so app-owned controls
+ *  (account/feedback menus) line up with the shared ones. */
+export const TOPBAR_TRIGGER_CLASS =
+  "size-9 rounded-md flex items-center justify-center text-[var(--text-secondary)] hover:text-[var(--text-primary)] hover:bg-[var(--bg-hover)]";
+
+/** Shared row styling for the top-bar hover-menu items. */
+export const TOPBAR_MENU_ITEM_CLASS =
+  "flex w-full items-center justify-between gap-3 px-3 py-2 text-sm text-left text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]";
+
+/** Sun/Moon toggle for the light/dark theme. Controlled: the app owns the mode. */
+export function ThemeToggle({
+  mode,
+  onToggle,
+  ariaLabel,
+  title,
+  className,
+}: {
+  mode: ThemeMode;
+  onToggle: () => void;
+  /** Default: `topBar.theme` from the {@link UiKitProvider}, else English. */
+  ariaLabel?: string;
+  title?: string;
+  className?: string;
+}) {
+  // This had no default at all, so a toggle rendered without `ariaLabel` was an
+  // icon button with no name — a reader heard "button" and nothing else.
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { theme: ariaLabel });
+  const Icon = mode === "dark" ? Moon : Sun;
+  return (
+    <Tooltip label={title} portal>
+      <button
+        type="button"
+        onClick={onToggle}
+        aria-label={labels.theme}
+        className={cn(TOPBAR_TRIGGER_CLASS, className)}
+      >
+        <Icon className="size-5" />
+      </button>
+    </Tooltip>
+  );
+}
+
+/** Appearance-preset switcher: a hover menu of palette presets with per-theme
+ *  colour swatches. Controlled — the app owns the active id and applies it. */
+export function PaletteMenu({
+  palettes,
+  activeId,
+  mode,
+  onSelect,
+  ariaLabel,
+  heading,
+}: {
+  palettes: PalettePreset[];
+  activeId: string;
+  mode: ThemeMode;
+  onSelect: (id: string) => void;
+  /** Default: `topBar.palette` from the {@link UiKitProvider}, else English. */
+  ariaLabel?: string;
+  /** Optional small heading row above the list. */
+  heading?: string;
+}) {
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { palette: ariaLabel });
+  const activeName = palettes.find((p) => p.id === activeId)?.name ?? activeId;
+  return (
+    <HoverMenu
+      ariaLabel={labels.palette}
+      trigger={({ toggle }) => (
+        <Tooltip label={activeName} portal>
+          <button
+            type="button"
+            onClick={toggle}
+            aria-label={labels.palette}
+            className={TOPBAR_TRIGGER_CLASS}
+          >
+            {/* A DATA colour, not a semantic one: the palette mark is the
+                "colour" control, so it carries a colour, and which hue is
+                arbitrary. `--chart-1` is the violet end of the CVD-safe
+                categorical ramp and flips per theme — a fixed `violet-500` did
+                not, and stayed a cool violet island on a warm page. */}
+            <Palette className="size-5 text-[var(--chart-1)]" />
+          </button>
+        </Tooltip>
+      )}
+    >
+      {(close) => (
+        <ul className="w-60 py-1">
+          {heading && (
+            <li className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+              {heading}
+            </li>
+          )}
+          {palettes.map((p) => {
+            const ts = p[mode];
+            const swatches = [ts.bgPage, ts.brand, ts.moneyIncome, ts.moneyExpense, ts.moneyNet];
+            return (
+              <li key={p.id}>
+                <button
+                  type="button"
+                  onClick={() => {
+                    onSelect(p.id);
+                    close();
+                  }}
+                  className={TOPBAR_MENU_ITEM_CLASS}
+                >
+                  <span className="flex min-w-0 items-center gap-2">
+                    <span className="flex shrink-0 gap-0.5">
+                      {/* Deliberately a neutral at 10% and not a token: this hairline
+                          sits on an ARBITRARY preset colour, so it has to read against
+                          whatever that preset paints, which no themed border does. */}
+                      {swatches.map((c, i) => (
+                        <span
+                          key={i}
+                          className="size-3.5 rounded-sm ring-1 ring-inset ring-black/10 dark:ring-white/10"
+                          style={{ background: c }}
+                        />
+                      ))}
+                    </span>
+                    <span className="flex min-w-0 flex-col text-left">
+                      <span className="truncate">{p.name}</span>
+                      <span className="truncate text-[11px] text-[var(--text-placeholder)]">
+                        {p.blurb}
+                      </span>
+                    </span>
+                  </span>
+                  {activeId === p.id && (
+                    <Check className="size-4 shrink-0 text-[var(--text-secondary)]" />
+                  )}
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </HoverMenu>
+  );
+}
+
+export interface LanguageOption {
+  code: string;
+  label: string;
+  /** ISO 3166-1 alpha-2 country code (lowercase) for the flag-icons flag. */
+  country: string;
+}
+
+/** Language switcher: a hover menu of options with flags and a check on the
+ *  active one. Controlled — the app owns the current code and change handler.
+ *
+ *  The trigger is the *active* option's flag, not an icon: lucide's `Languages`
+ *  glyph (文A) is the same mark Chrome puts in the omnibox for "translate this
+ *  page", so it read as machine-translation rather than "pick the UI language"
+ *  (Keksdose feedback #121). The flag also shows which language is currently on,
+ *  which no icon can, and costs the same width on a crowded mobile bar. A globe
+ *  covers the case where `current` matches nothing in `options`. */
+export function LanguageMenu({
+  options,
+  current,
+  onChange,
+  ariaLabel,
+}: {
+  options: LanguageOption[];
+  current: string | undefined;
+  onChange: (code: string) => void;
+  /** Default: `topBar.language` from the {@link UiKitProvider}, else English. */
+  ariaLabel?: string;
+}) {
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { language: ariaLabel });
+  const active = options.find((o) => o.code === current);
+  return (
+    <HoverMenu
+      ariaLabel={labels.language}
+      trigger={({ toggle }) => (
+        <Tooltip label={active?.label ?? labels.language} portal>
+          <button
+            type="button"
+            onClick={toggle}
+            aria-label={labels.language}
+            className={TOPBAR_TRIGGER_CLASS}
+          >
+            {active ? (
+              <span
+                aria-hidden
+                className={`fi fi-${active.country} inline-block h-[15px] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
+              />
+            ) : (
+              <Globe className="size-5" />
+            )}
+          </button>
+        </Tooltip>
+      )}
+    >
+      {(close) => (
+        <ul className="py-1">
+          {options.map((lang) => {
+            const isActive = lang.code === current;
+            return (
+              <li key={lang.code}>
+                <button
+                  type="button"
+                  onClick={() => {
+                    onChange(lang.code);
+                    close();
+                  }}
+                  className={TOPBAR_MENU_ITEM_CLASS}
+                >
+                  <span className="flex items-center gap-2">
+                    <span
+                      aria-hidden
+                      className={`fi fi-${lang.country} inline-block h-[15px] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
+                    />
+                    {lang.label}
+                  </span>
+                  {isActive && <Check className="size-4 text-[var(--text-secondary)]" />}
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </HoverMenu>
+  );
+}

package/src/shell.ts

@@ -0,0 +1,10 @@
+// `@eifi1/ui-kit/shell` — the composable app chrome.
+//
+// A re-slicing of the main barrel, not a new API. This entry point requires
+// `react-router`: AppShell renders NavLink and TopBarActionMenu renders Link.
+export * from "./shell/topbar-controls";
+export * from "./shell/top-bar";
+export * from "./shell/app-shell";
+export * from "./shell/option-switcher-menu";
+export * from "./shell/role-switcher";
+export * from "./shell/topbar-action-menu";

package/src/theme/chart-palette.ts

@@ -0,0 +1,145 @@
+// 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..9 = Paul Tol "Muted" (CVD-safe across protan/deutan/tritan).
+// 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";
+
+const PALETTE_SIZE = 9;
+
+/** CVD-safe categorical colour for series `index`, as a theme-aware CSS var. */
+export function paletteFor(index: number): string {
+  return `var(--chart-${(index % PALETTE_SIZE) + 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)",
+  assigned: "var(--brand)",
+  activity: "var(--money-expense)",
+} as const;
+
+// ── 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.
+export const PALETTE_HEX = {
+  light: ["#332288", "#88ccee", "#44aa99", "#117733", "#999933", "#ddcc77", "#cc6677", "#882255", "#aa4499"],
+  dark: ["#7e72d6", "#9fd8f2", "#5fc4b0", "#3fa45f", "#bfbf5e", "#e8dda0", "#e08c9a", "#c25a78", "#cc78be"],
+} 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. Teal = under/good, amber = over/spend = bad. */
+export const HEATMAP_HEX = {
+  light: {
+    neutral: "#f1e7d2", // the cream surface itself, not a cool grey
+    under: "#0b6650", // DEFAULT_PRESET.light.moneyIncome
+    over: "#9c6418", // DEFAULT_PRESET.light.moneyExpense, warmed to the page
+    seqLow: "#f6ecd0",
+    seqHigh: "#9c6418",
+    empty: "rgba(148,163,184,0.14)",
+  },
+  dark: {
+    neutral: "#363a5a", // one step above --border on the indigo-noir surface
+    under: "#22c3b6", // DEFAULT_PRESET.dark.moneyIncome
+    // Brighter than dark.moneyExpense (#e4b035) on purpose: a gradient endpoint is
+    // meant to be the loudest thing in its scale, and it is a fill, not a figure.
+    over: "#fbbf24",
+    seqLow: "#3a2c14", // dim amber, sits just above the page
+    seqHigh: "#fbbf24",
+    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;
+}