@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/token-spotlight/token-spotlight.tsx

@@ -0,0 +1,379 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../../lib/cn";
+import { formatColorAsOklch, formatLengthAsPx } from "./token-value-format";
+import "./token-spotlight.css";
+
+/** One chip: a semantic token plus its display label. */
+export interface TokenSpotlightToken {
+  /** The CSS custom property name, including its leading `--` (e.g. `--primary`). */
+  token: string;
+  /** Display label for the chip — supply your own to localize. */
+  label: string;
+}
+
+export interface TokenSpotlightLabels {
+  /** Accessible name of the chip row (`role="group"`). */
+  row: string;
+  /** sr-only text appended to each chip's accessible name, describing what hovering does. */
+  hint: string;
+}
+
+export const DEFAULT_TOKEN_SPOTLIGHT_LABELS: TokenSpotlightLabels = {
+  row: "Design tokens",
+  hint: "Highlights every element on this page that uses this token.",
+};
+
+/** Hard cap on elements a single scan pass examines (wave-4 ruling 26). */
+export const TOKEN_SPOTLIGHT_SCAN_LIMIT = 2000;
+/** Elements examined per idle slice before yielding back to the browser. */
+const SCAN_CHUNK_SIZE = 150;
+/** `data-token-consumer` marks written per idle slice, so the restyle + outline paint they cause
+ * is spread over several frames instead of landing in one long task (#583). */
+const MARK_CHUNK_SIZE = 40;
+
+const BORDER_SIDES = ["Top", "Right", "Bottom", "Left"] as const;
+/** SVG elements that paint their own `fill`/`stroke`; containers (`svg`, `g`) only pass it on. */
+const SVG_PAINTING_ELEMENTS = new Set([
+  "circle",
+  "ellipse",
+  "line",
+  "path",
+  "polygon",
+  "polyline",
+  "rect",
+  "text",
+  "textPath",
+  "tspan",
+]);
+
+/** True when `el` has a direct, non-whitespace text node — i.e. it paints glyphs in its own
+ * `color`, rather than merely inheriting a `color` it never uses. */
+function hasOwnText(el: Element): boolean {
+  for (const node of Array.from(el.childNodes)) {
+    if (node.nodeType === 3 && node.nodeValue?.trim()) return true;
+  }
+  return false;
+}
+
+/**
+ * The element that visibly CONSUMES `matchValue`, or `null` (#583). Only real paint counts:
+ * - `background-color` on the element itself;
+ * - a border side's colour only where that side's width is > 0 (the base layer gives every element
+ *   `border-color: var(--border)` at width 0 — that is not a consumer);
+ * - `color` only on an element with its own non-empty text node (inherited `color` is not use);
+ * - `fill`/`stroke` only on SVG shapes and text that paint (`stroke` needs a width > 0), reported
+ *   as their owning `<svg>` so an icon or chart is one outline, not one per path.
+ */
+function consumerOf(el: Element, style: CSSStyleDeclaration, matchValue: string): Element | null {
+  if (el instanceof SVGElement) {
+    if (!SVG_PAINTING_ELEMENTS.has(el.localName)) return null;
+    const paints =
+      style.fill === matchValue ||
+      (style.stroke === matchValue && parseFloat(style.strokeWidth) > 0);
+    return paints ? (el.ownerSVGElement ?? el) : null;
+  }
+  if (style.backgroundColor === matchValue) return el;
+  for (const side of BORDER_SIDES) {
+    if (style[`border${side}Color`] === matchValue && parseFloat(style[`border${side}Width`]) > 0) {
+      return el;
+    }
+  }
+  if (style.color === matchValue && hasOwnText(el)) return el;
+  return null;
+}
+
+type IdleDeadline = { timeRemaining: () => number; didTimeout: boolean };
+
+/** `requestIdleCallback` where it exists; a same-shaped `setTimeout` fallback otherwise (Safari). */
+function scheduleIdle(callback: (deadline: IdleDeadline) => void): () => void {
+  const w = window as Window & {
+    requestIdleCallback?: (cb: (d: IdleDeadline) => void, opts?: { timeout: number }) => number;
+    cancelIdleCallback?: (handle: number) => void;
+  };
+  if (typeof w.requestIdleCallback === "function") {
+    const handle = w.requestIdleCallback(callback, { timeout: 100 });
+    return () => w.cancelIdleCallback?.(handle);
+  }
+  const handle = window.setTimeout(
+    () => callback({ timeRemaining: () => 50, didTimeout: true }),
+    0,
+  );
+  return () => window.clearTimeout(handle);
+}
+
+/**
+ * Resolves `token`'s CURRENT value the same way the browser will compare it: an off-screen probe
+ * element takes `background-color: var(token)`, so whatever colour-space normalisation the
+ * browser applies happens identically for the probe and for every candidate element below —
+ * string equality holds regardless of how a theme authored the value (oklch, rgb, …).
+ */
+export function resolveTokenMatchValue(token: string, doc: Document = document): string {
+  const probe = doc.createElement("span");
+  probe.style.cssText =
+    "position:fixed;inset:0;width:0;height:0;overflow:hidden;visibility:hidden;pointer-events:none;" +
+    `background-color:var(${token});`;
+  doc.body.appendChild(probe);
+  const value = getComputedStyle(probe).backgroundColor;
+  doc.body.removeChild(probe);
+  return value;
+}
+
+const supportsCss = (property: string, value: string): boolean =>
+  typeof CSS !== "undefined" && typeof CSS.supports === "function" && CSS.supports(property, value);
+
+/** `property: var(token)` on an off-screen probe inside `host`, read back as the browser's
+ * computed value — so `calc()`, `rem`, named colours and `color-mix()` arrive resolved. Lengths go
+ * through `letter-spacing`: an absolute computed length (negatives allowed) that, unlike `width`,
+ * is never quantised to layout units (`1.6px`, not `1.59375px`). */
+function probeComputed(host: Element, property: "color" | "letter-spacing", token: string): string {
+  const doc = host.ownerDocument;
+  const probe = doc.createElement("span");
+  probe.style.cssText =
+    "position:fixed;inset:0;height:0;overflow:hidden;visibility:hidden;pointer-events:none;" +
+    `${property}:var(${token});`;
+  host.appendChild(probe);
+  const value = getComputedStyle(probe).getPropertyValue(property);
+  host.removeChild(probe);
+  return value;
+}
+
+/**
+ * What a chip shows a person for `token` on `root` (#585): a colour as a rounded `oklch(L C H)`
+ * — never the `lab()` a CSS build may have transpiled it to — and a length as resolved px, never
+ * a raw `calc()`. Anything else (a font stack, a shadow) is shown as authored. `""` when there is
+ * no `document` yet (SSR — the component fills it in after mount).
+ */
+export function resolveTokenDisplayValue(token: string, root?: HTMLElement): string {
+  const target = root ?? (typeof document === "undefined" ? undefined : document.documentElement);
+  if (!target) return "";
+  const raw = getComputedStyle(target).getPropertyValue(token).trim();
+  if (!raw) return "";
+  const direct = formatColorAsOklch(raw);
+  if (direct) return direct;
+  // The probe must inherit `root`'s custom properties: `<html>` itself cannot host it visibly.
+  const host = target === target.ownerDocument.documentElement ? target.ownerDocument.body : target;
+  if (supportsCss("color", raw)) {
+    return formatColorAsOklch(probeComputed(host, "color", token)) ?? raw;
+  }
+  if (supportsCss("width", raw)) {
+    return formatLengthAsPx(probeComputed(host, "letter-spacing", token)) ?? raw;
+  }
+  return raw;
+}
+
+const isEmptyMatchValue = (value: string) =>
+  value === "" || value === "rgba(0, 0, 0, 0)" || value === "transparent";
+
+/**
+ * Scans `root` in idle-time chunks for elements that visibly paint `matchValue` (from
+ * {@link resolveTokenMatchValue}) — a background, a border side with width, their own text, or an
+ * SVG shape's fill/stroke (reported as its `<svg>`) — capped at `limit` elements EXAMINED. Never a
+ * long task, never inline styles (callers add/remove a `data-token-consumer` attribute instead).
+ * Returns a canceller for effect cleanup.
+ */
+export function scanForConsumers(
+  root: ParentNode,
+  matchValue: string,
+  limit: number,
+  onDone: (elements: HTMLElement[]) => void,
+): () => void {
+  if (isEmptyMatchValue(matchValue)) {
+    onDone([]);
+    return () => {};
+  }
+  const candidates = Array.from(root.querySelectorAll("*")).slice(0, limit);
+  const found = new Set<Element>();
+  let index = 0;
+  let cancelled = false;
+  let cancelIdle = () => {};
+
+  const step = (deadline: IdleDeadline) => {
+    if (cancelled) return;
+    let examinedInSlice = 0;
+    while (
+      index < candidates.length &&
+      examinedInSlice < SCAN_CHUNK_SIZE &&
+      (deadline.timeRemaining() > 0 || deadline.didTimeout)
+    ) {
+      const el = candidates[index++];
+      examinedInSlice++;
+      if (!(el instanceof HTMLElement) && !(el instanceof SVGElement)) continue;
+      const consumer = consumerOf(el, getComputedStyle(el), matchValue);
+      if (consumer) found.add(consumer);
+    }
+    if (index < candidates.length) {
+      cancelIdle = scheduleIdle(step);
+    } else {
+      // An SVG consumer is its `<svg>` root — typed `HTMLElement[]` as before for compatibility.
+      onDone(Array.from(found) as HTMLElement[]);
+    }
+  };
+  cancelIdle = scheduleIdle(step);
+  return () => {
+    cancelled = true;
+    cancelIdle();
+  };
+}
+
+/**
+ * Writes `data-token-consumer="<name>"` onto `elements` in idle slices of {@link MARK_CHUNK_SIZE},
+ * pushing each marked element onto `written` as it goes so the caller can always clear exactly
+ * what landed — even mid-way. Returns a canceller that stops further slices (#583).
+ */
+function writeMarksInSlices(elements: Element[], name: string, written: Element[]): () => void {
+  let index = 0;
+  let cancelled = false;
+  let cancelIdle = () => {};
+  const step = () => {
+    if (cancelled) return;
+    const end = Math.min(index + MARK_CHUNK_SIZE, elements.length);
+    for (const el of elements.slice(index, end)) {
+      el.setAttribute("data-token-consumer", name);
+      written.push(el);
+    }
+    index = end;
+    if (index < elements.length) cancelIdle = scheduleIdle(step);
+  };
+  if (elements.length > 0) cancelIdle = scheduleIdle(step);
+  return () => {
+    cancelled = true;
+    cancelIdle();
+  };
+}
+
+/** Tracks one attribute of `document.documentElement`, so a change re-renders. */
+function useRootAttribute(name: "data-theme" | "data-decoration"): string {
+  const [value, setValue] = React.useState<string>(() =>
+    typeof document === "undefined" ? "" : (document.documentElement.getAttribute(name) ?? ""),
+  );
+  React.useEffect(() => {
+    if (typeof MutationObserver === "undefined") return;
+    const root = document.documentElement;
+    const observer = new MutationObserver(() => {
+      setValue(root.getAttribute(name) ?? "");
+    });
+    observer.observe(root, { attributes: true, attributeFilter: [name] });
+    return () => observer.disconnect();
+  }, [name]);
+  return value;
+}
+
+export interface TokenSpotlightProps extends Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  "onSelect"
+> {
+  /** Chips to render, in order. */
+  tokens: readonly TokenSpotlightToken[];
+  /** Fires with the token on hover/focus, and `null` when the spotlight clears. */
+  onSpotlight?: (token: string | null) => void;
+  /** Upper bound on elements a scan pass examines. Default {@link TOKEN_SPOTLIGHT_SCAN_LIMIT}. */
+  scanLimit?: number;
+  labels?: Partial<TokenSpotlightLabels>;
+}
+
+/**
+ * A row of token chips (concept §4.5, §5a "Scroll choreography 5"): hovering or focusing one sets
+ * `data-token-spotlight` on `<html>` and marks every element on the page that resolves to the
+ * same colour with `data-token-consumer` (never an inline style), so a stylesheet can draw the
+ * highlight. `onSpotlight` lets the host tint an `AmbientField` to match. Each chip shows the
+ * token's own resolved value, re-read on every theme change.
+ */
+export const TokenSpotlight = React.forwardRef<HTMLDivElement, TokenSpotlightProps>(
+  function TokenSpotlight(
+    {
+      tokens,
+      onSpotlight,
+      scanLimit = TOKEN_SPOTLIGHT_SCAN_LIMIT,
+      labels: labelsProp,
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    const labels = { ...DEFAULT_TOKEN_SPOTLIGHT_LABELS, ...labelsProp };
+    const theme = useRootAttribute("data-theme");
+    const decoration = useRootAttribute("data-decoration");
+    const [active, setActive] = React.useState<string | null>(null);
+    const consumersRef = React.useRef<Element[]>([]);
+    // Read once after mount and again on every theme or decoration switch (a decoration-scaled
+    // token like `--radius` changes with `data-decoration`, #585) — never during SSR/hydration,
+    // so the server and the first client render agree (both start from `{}`).
+    const [displayValues, setDisplayValues] = React.useState<Record<string, string>>({});
+    React.useEffect(() => {
+      const next: Record<string, string> = {};
+      for (const { token } of tokens) next[token] = resolveTokenDisplayValue(token);
+      setDisplayValues(next);
+    }, [theme, decoration, tokens]);
+
+    const clearConsumers = React.useCallback(() => {
+      for (const el of consumersRef.current) el.removeAttribute("data-token-consumer");
+      consumersRef.current = [];
+    }, []);
+
+    React.useEffect(() => {
+      const root = document.documentElement;
+      if (!active) {
+        delete root.dataset.tokenSpotlight;
+        clearConsumers();
+        onSpotlight?.(null);
+        return;
+      }
+      const bareToken = active.replace(/^--/, "");
+      root.dataset.tokenSpotlight = bareToken;
+      onSpotlight?.(active);
+      const matchValue = resolveTokenMatchValue(active);
+      let cancelMarks = () => {};
+      const cancelScan = scanForConsumers(document.body, matchValue, scanLimit, (elements) => {
+        clearConsumers();
+        cancelMarks = writeMarksInSlices(elements, bareToken, consumersRef.current);
+      });
+      return () => {
+        cancelScan();
+        cancelMarks();
+        clearConsumers();
+        delete root.dataset.tokenSpotlight;
+      };
+      // `theme` re-runs the scan on a theme switch (Acceptance: "re-scans consumers"); `onSpotlight`
+      // and `clearConsumers` are stable identities the caller/`useCallback` control.
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- see comment above
+    }, [active, theme, scanLimit]);
+
+    return (
+      <div
+        ref={ref}
+        role="group"
+        aria-label={labels.row}
+        data-slot="token-spotlight"
+        className={cn("flex flex-wrap items-center gap-2", className)}
+        {...props}
+      >
+        {tokens.map(({ token, label }) => (
+          <button
+            key={token}
+            type="button"
+            data-slot="token-spotlight-chip"
+            data-active={active === token ? "" : undefined}
+            className={cn(
+              "focus-ring inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 text-meta font-medium",
+              "bg-card text-foreground transition-colors",
+              active === token ? "border-ring" : "border-border-strong",
+            )}
+            onMouseEnter={() => setActive(token)}
+            onMouseLeave={() => setActive((current) => (current === token ? null : current))}
+            onFocus={() => setActive(token)}
+            onBlur={() => setActive((current) => (current === token ? null : current))}
+          >
+            <span aria-hidden="true" className="font-mono text-code">
+              {token}
+            </span>
+            <span className="text-muted-foreground">{displayValues[token] || "—"}</span>
+            <span className="sr-only">{` — ${label}. ${labels.hint}`}</span>
+          </button>
+        ))}
+      </div>
+    );
+  },
+);
+TokenSpotlight.displayName = "TokenSpotlight";

package/src/components/token-spotlight/token-value-format.ts

@@ -0,0 +1,205 @@
+/**
+ * Pure formatters behind `TokenSpotlight`'s chip values (#585). A chip shows a person what a token
+ * resolves to, so a colour always reads as a rounded `oklch(L C H)` — whatever colour space the
+ * CSS build or the browser serialised it in (`lab()`, `rgb()`, `color(srgb …)`, …) — and a length
+ * reads as resolved px, never a raw `calc()`. DOM-free: the component feeds these the strings it
+ * reads from `getComputedStyle`.
+ *
+ * Conversion math: CSS Color 4 §"Sample code for color conversions" (matrices and the Lab/OKLab
+ * definitions are the spec's own, public domain).
+ */
+
+type Vec3 = [number, number, number];
+type Mat3 = [Vec3, Vec3, Vec3];
+
+const mul = (m: Mat3, [a, b, c]: Vec3): Vec3 => [
+  m[0][0] * a + m[0][1] * b + m[0][2] * c,
+  m[1][0] * a + m[1][1] * b + m[1][2] * c,
+  m[2][0] * a + m[2][1] * b + m[2][2] * c,
+];
+
+const LINEAR_SRGB_TO_XYZ_D65: Mat3 = [
+  [0.41239079926595934, 0.357584339383878, 0.1804807884018343],
+  [0.21263900587151027, 0.715168678767756, 0.07219231536073371],
+  [0.01933081871559182, 0.11919477979462598, 0.9505321522496607],
+];
+const LINEAR_P3_TO_XYZ_D65: Mat3 = [
+  [0.4865709486482162, 0.26566769316909306, 0.1982172852343625],
+  [0.2289745640697488, 0.6917385218365064, 0.079286914093745],
+  [0, 0.04511338185890264, 1.043944368900976],
+];
+/** Bradford chromatic adaptation, D50 → D65. */
+const XYZ_D50_TO_D65: Mat3 = [
+  [0.955473421488075, -0.02309845494876471, 0.06325924320057072],
+  [-0.0283697093338637, 1.0099953980813041, 0.021041441191917323],
+  [0.012314014864481998, -0.020507649298898964, 1.330365926242124],
+];
+const XYZ_D65_TO_LMS: Mat3 = [
+  [0.819022437996703, 0.3619062600528904, -0.1288737815209879],
+  [0.0329836539323885, 0.9292868615863434, 0.0361446663506424],
+  [0.0481771893596242, 0.2642395317527308, 0.6335478284694309],
+];
+const LMS_CBRT_TO_OKLAB: Mat3 = [
+  [0.210454268309314, 0.7936177747023054, -0.0040720430116193],
+  [1.9779985324311684, -2.42859224204858, 0.450593709617411],
+  [0.0259040424655478, 0.7827717124575296, -0.8086757549230774],
+];
+const D50_WHITE: Vec3 = [0.3457 / 0.3585, 1, (1 - 0.3457 - 0.3585) / 0.3585];
+
+const srgbToLinear = (c: number) => {
+  const abs = Math.abs(c);
+  return abs <= 0.04045 ? c / 12.92 : Math.sign(c) * ((abs + 0.055) / 1.055) ** 2.4;
+};
+
+function labToXyzD50([l, a, b]: Vec3): Vec3 {
+  const kappa = 24389 / 27;
+  const epsilon = 216 / 24389;
+  const f1 = (l + 16) / 116;
+  const f0 = a / 500 + f1;
+  const f2 = f1 - b / 200;
+  const x = f0 ** 3 > epsilon ? f0 ** 3 : (116 * f0 - 16) / kappa;
+  const y = l > kappa * epsilon ? f1 ** 3 : l / kappa;
+  const z = f2 ** 3 > epsilon ? f2 ** 3 : (116 * f2 - 16) / kappa;
+  return [x * D50_WHITE[0], y * D50_WHITE[1], z * D50_WHITE[2]];
+}
+
+function xyzD65ToOklab(xyz: Vec3): Vec3 {
+  const [l, m, s] = mul(XYZ_D65_TO_LMS, xyz);
+  return mul(LMS_CBRT_TO_OKLAB, [Math.cbrt(l), Math.cbrt(m), Math.cbrt(s)]);
+}
+
+const polarToRect = (c: number, hDeg: number): [number, number] => [
+  c * Math.cos((hDeg * Math.PI) / 180),
+  c * Math.sin((hDeg * Math.PI) / 180),
+];
+
+/** One channel token: a number, a percentage, an angle, or `none` (→ 0). `null` when unreadable. */
+function readChannel(raw: string, percentScale: number): number | null {
+  if (raw === "none") return 0;
+  const match = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(%|deg|rad|grad|turn)?$/i.exec(raw);
+  if (!match) return null;
+  const n = Number(match[1]);
+  switch (match[2]?.toLowerCase()) {
+    case "%":
+      return (n / 100) * percentScale;
+    case "rad":
+      return (n * 180) / Math.PI;
+    case "grad":
+      return n * 0.9;
+    case "turn":
+      return n * 360;
+    default:
+      return n;
+  }
+}
+
+interface ParsedColor {
+  /** OKLab. */
+  lab: Vec3;
+  alpha: number;
+}
+
+/** Parses the colour serialisations browsers and CSS builds emit into OKLab. `null` if unknown. */
+function parseCssColor(value: string): ParsedColor | null {
+  const fn = /^([a-z-]+)\(\s*(.*?)\s*\)$/i.exec(value.trim());
+  if (!fn?.[1] || fn[2] === undefined) return null;
+  const name = fn[1].toLowerCase();
+  const [channelPart = "", alphaPart] = fn[2].split("/").map((part) => part.trim());
+  let args = channelPart.split(/[\s,]+/).filter(Boolean);
+  let alphaRaw = alphaPart;
+  let space = "";
+  if (name === "color") {
+    space = (args.shift() ?? "").toLowerCase();
+  }
+  if ((name === "rgb" || name === "rgba") && args.length === 4 && alphaRaw === undefined) {
+    alphaRaw = args[3]; // legacy `rgba(r, g, b, a)`
+    args = args.slice(0, 3);
+  }
+  if (args.length !== 3) return null;
+  const alpha = alphaRaw === undefined ? 1 : readChannel(alphaRaw, 1);
+  if (alpha === null) return null;
+
+  const read = (scales: Vec3): Vec3 | null => {
+    const out = args.map((arg, i) => readChannel(arg, scales[i] ?? 1));
+    return out.every((n): n is number => n !== null) ? (out as Vec3) : null;
+  };
+
+  let lab: Vec3 | null = null;
+  switch (name) {
+    case "rgb":
+    case "rgba": {
+      const rgb = read([255, 255, 255]);
+      if (rgb) {
+        const linear = rgb.map((c) => srgbToLinear(c / 255)) as Vec3;
+        lab = xyzD65ToOklab(mul(LINEAR_SRGB_TO_XYZ_D65, linear));
+      }
+      break;
+    }
+    case "lab": {
+      const cie = read([100, 125, 125]);
+      if (cie) lab = xyzD65ToOklab(mul(XYZ_D50_TO_D65, labToXyzD50(cie)));
+      break;
+    }
+    case "lch": {
+      const lch = read([100, 150, 1]);
+      if (lch) {
+        const [a, b] = polarToRect(lch[1], lch[2]);
+        lab = xyzD65ToOklab(mul(XYZ_D50_TO_D65, labToXyzD50([lch[0], a, b])));
+      }
+      break;
+    }
+    case "oklab":
+      lab = read([1, 0.4, 0.4]);
+      break;
+    case "oklch": {
+      const lch = read([1, 0.4, 1]);
+      if (lch) lab = [lch[0], ...polarToRect(lch[1], lch[2])];
+      break;
+    }
+    case "color": {
+      const c = read([1, 1, 1]);
+      if (!c) break;
+      if (space === "srgb")
+        lab = xyzD65ToOklab(mul(LINEAR_SRGB_TO_XYZ_D65, c.map(srgbToLinear) as Vec3));
+      else if (space === "srgb-linear") lab = xyzD65ToOklab(mul(LINEAR_SRGB_TO_XYZ_D65, c));
+      else if (space === "display-p3")
+        lab = xyzD65ToOklab(mul(LINEAR_P3_TO_XYZ_D65, c.map(srgbToLinear) as Vec3));
+      else if (space === "xyz" || space === "xyz-d65") lab = xyzD65ToOklab(c);
+      else if (space === "xyz-d50") lab = xyzD65ToOklab(mul(XYZ_D50_TO_D65, c));
+      break;
+    }
+  }
+  return lab ? { lab, alpha } : null;
+}
+
+/** Rounds to `digits` decimals and drops trailing zeros (`0.250` → `0.25`, `-0` → `0`). */
+function trimNumber(n: number, digits: number): string {
+  const rounded = Number(n.toFixed(digits));
+  return String(Object.is(rounded, -0) ? 0 : rounded);
+}
+
+/**
+ * Re-encodes any CSS colour string this module can parse as a rounded `oklch(L C H)` — L and C to
+ * 3 decimals, H to whole degrees (`0` for an achromatic colour), ` / A` only when translucent.
+ * `null` when the string is not a colour it understands (the caller falls back to the raw value).
+ *
+ * @example formatColorAsOklch("lab(98.2553% -.143647 -.74234)") // "oklch(0.985 0.002 257)"
+ */
+export function formatColorAsOklch(value: string): string | null {
+  const parsed = parseCssColor(value);
+  if (!parsed) return null;
+  const [l, a, b] = parsed.lab;
+  const chroma = Math.hypot(a, b);
+  const lightness = trimNumber(Math.min(Math.max(l, 0), 1), 3);
+  const c = trimNumber(chroma, 3);
+  const hue =
+    c === "0" ? "0" : trimNumber(((((Math.atan2(b, a) * 180) / Math.PI) % 360) + 360) % 360, 0);
+  const alpha = parsed.alpha < 1 ? ` / ${trimNumber(Math.max(parsed.alpha, 0), 2)}` : "";
+  return `oklch(${lightness} ${c} ${hue === "360" ? "0" : hue}${alpha})`;
+}
+
+/** A resolved px length (`"4px"`, `"4.5px"`) rounded to 2 decimals. `null` for anything else. */
+export function formatLengthAsPx(value: string): string | null {
+  const match = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)px$/i.exec(value.trim());
+  return match ? `${trimNumber(Number(match[1]), 2)}px` : null;
+}

package/src/components/tooltip/tooltip.tsx

@@ -14,9 +14,10 @@ export const TooltipContent = forwardRef<
     <TooltipPrimitive.Portal>
       <TooltipPrimitive.Content
         ref={ref}
+        data-slot="tooltip-content"
         sideOffset={sideOffset}
         className={cn(
-          "z-50 overflow-hidden rounded-md bg-foreground px-2.5 py-1.5 text-xs text-background shadow-md",
+          "z-50 overflow-hidden rounded-md bg-foreground px-2.5 py-1.5 text-meta text-background shadow-md",
           "data-[state=delayed-open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95",
           className,
         )}

package/src/components/top-nav/top-nav.test.tsx

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { TopNav } from "./top-nav";
+
+describe("TopNav", () => {
+  it("renders the original start/children/end flex row unchanged when center is not passed", () => {
+    const { container } = render(
+      <TopNav
+        start={<span data-testid="start">Start</span>}
+        end={<span data-testid="end">End</span>}
+      >
+        <span data-testid="children">Children</span>
+      </TopNav>,
+    );
+    expect(screen.getByTestId("start")).toBeInTheDocument();
+    expect(screen.getByTestId("children")).toBeInTheDocument();
+    expect(screen.getByTestId("end")).toBeInTheDocument();
+    // No grid layout — the plain flex row this shipped with.
+    expect(container.querySelector('[data-slot="top-nav-center"]')).toBeNull();
+    const header = container.querySelector("header") as HTMLElement;
+    expect(header.className).not.toContain("grid");
+  });
+
+  it("switches to the 3-column centred grid when center is passed, and drops children", () => {
+    const { container } = render(
+      <TopNav
+        start={<span data-testid="start">Start</span>}
+        center={<span data-testid="center">Center</span>}
+        end={<span data-testid="end">End</span>}
+      >
+        <span data-testid="children">Children</span>
+      </TopNav>,
+    );
+    expect(screen.getByTestId("start")).toBeInTheDocument();
+    expect(screen.getByTestId("center")).toBeInTheDocument();
+    expect(screen.getByTestId("end")).toBeInTheDocument();
+    // `children` is documented as ignored once `center` is supplied.
+    expect(screen.queryByTestId("children")).not.toBeInTheDocument();
+
+    const startSlot = container.querySelector('[data-slot="top-nav-start"]');
+    const centerSlot = container.querySelector('[data-slot="top-nav-center"]');
+    const endSlot = container.querySelector('[data-slot="top-nav-end"]');
+    expect(startSlot).not.toBeNull();
+    expect(centerSlot).not.toBeNull();
+    expect(endSlot).not.toBeNull();
+    expect(startSlot?.contains(screen.getByTestId("start"))).toBe(true);
+    expect(centerSlot?.contains(screen.getByTestId("center"))).toBe(true);
+    expect(endSlot?.contains(screen.getByTestId("end"))).toBe(true);
+
+    const grid = centerSlot?.parentElement;
+    expect(grid?.className).toContain("grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)]");
+
+    // DOM order: start, then center, then end — the reading order the grid's
+    // column order is supposed to match.
+    const slots = Array.from(grid?.children ?? []);
+    expect(slots.indexOf(startSlot as Element)).toBeLessThan(slots.indexOf(centerSlot as Element));
+    expect(slots.indexOf(centerSlot as Element)).toBeLessThan(slots.indexOf(endSlot as Element));
+  });
+});