@elabs-ai/components-data 4.1.0 → 5.0.0

package/src/data-table/card-layout.test.tsx

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { DataTableCard, DataTableCardList } from "./card-layout";
+
+describe("card-layout", () => {
+  it("renders one list item per card with a <dl> of term → detail pairs", () => {
+    render(
+      <DataTableCardList aria-label="Cities">
+        <DataTableCard
+          fields={[
+            { id: "city", term: "City", value: "Oslo" },
+            { id: "pop", term: "Population", value: "709,000" },
+          ]}
+        />
+      </DataTableCardList>,
+    );
+    expect(screen.getByRole("list", { name: "Cities" })).toBeInTheDocument();
+    expect(screen.getAllByRole("listitem")).toHaveLength(1);
+    const terms = screen.getAllByRole("term");
+    expect(terms.map((t) => t.textContent)).toEqual(["City", "Population"]);
+    expect(screen.getAllByRole("definition").map((d) => d.textContent)).toEqual([
+      "Oslo",
+      "709,000",
+    ]);
+  });
+});

package/src/data-table/card-layout.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { forwardRef, type HTMLAttributes, type LiHTMLAttributes, type ReactNode } from "react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+/**
+ * card-layout.tsx — `DataTable`'s transposed card rows (RM-123, `layout`).
+ *
+ * Under the table's `narrow` breakpoint (`layout="auto"`) or always
+ * (`layout="cards"`), each row renders as one card: a `<dl>` whose terms are
+ * the column headers and whose details are the row's cells. Only the markup
+ * changes — the TanStack model (sorting, filtering, paging, selection) is the
+ * same instance the table uses, so the toolbar and pager keep working.
+ */
+
+/** One term / detail pair of a card. */
+export interface DataTableCardField {
+  /** Stable key: the column id. */
+  id: string;
+  term: ReactNode;
+  value: ReactNode;
+  /** Extra classes / style for the detail (alignment, a colour wash). */
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+/** The list that holds the cards. Rows are separated by a strong divider. */
+export const DataTableCardList = forwardRef<HTMLUListElement, HTMLAttributes<HTMLUListElement>>(
+  function DataTableCardList({ className, ...props }, ref) {
+    return (
+      <ul
+        ref={ref}
+        data-slot="data-table-card-list"
+        className={cn("divide-y divide-border-strong", className)}
+        {...props}
+      />
+    );
+  },
+);
+
+export interface DataTableCardProps extends LiHTMLAttributes<HTMLLIElement> {
+  fields: readonly DataTableCardField[];
+  /** Content above the fields (the selection checkbox, the rank, the row action). */
+  lead?: ReactNode;
+  /** `compact` tightens the padding, like the table's `density="compact"`. */
+  density?: "default" | "compact";
+}
+
+/** One row as a card: a `<dl>` of header → cell pairs. */
+export const DataTableCard = forwardRef<HTMLLIElement, DataTableCardProps>(function DataTableCard(
+  { fields, lead, density = "default", className, ...props },
+  ref,
+) {
+  return (
+    <li
+      ref={ref}
+      data-slot="data-table-card"
+      className={cn("px-3", density === "compact" ? "py-2" : "py-3", className)}
+      {...props}
+    >
+      {lead}
+      <dl className="grid grid-cols-[minmax(0,2fr)_minmax(0,3fr)] gap-x-3 gap-y-1.5">
+        {fields.map((field) => (
+          <div key={field.id} data-slot="data-table-card-field" className="contents">
+            <dt className="min-w-0 break-words text-meta text-muted-foreground">{field.term}</dt>
+            <dd className={cn("min-w-0 break-words", field.className)} style={field.style}>
+              {field.value}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </li>
+  );
+});

package/src/data-table/cell-scales.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import {
+  barDomain,
+  barGeometry,
+  computeColumnScales,
+  extentOf,
+  heatmapColorScaleSpec,
+  labelBoxCh,
+  seriesEnds,
+  seriesValues,
+} from "./cell-scales";
+
+const rows = [
+  { a: 10, b: -5, cat: "x", s1: 1, s2: 4 },
+  { a: 40, b: 20, cat: "y", s1: 2, s2: 8 },
+  { a: 20, b: 5, cat: "x", s1: 3, s2: 2 },
+].map((original) => ({
+  original,
+  getValue: (id: string) => (original as Record<string, unknown>)[id],
+}));
+
+describe("cell-scales", () => {
+  it("extentOf ignores non-finite values", () => {
+    expect(extentOf([3, "x", null, Number.NaN, -1, 7])).toEqual({ min: -1, max: 7 });
+    expect(extentOf(["x"])).toBeNull();
+  });
+
+  it("labelBoxCh reserves the column's longest label, so tracks match down the column", () => {
+    expect(labelBoxCh(["+12.5 %", "-4.2 %", "+0.4 %"])).toBe(7);
+    expect(labelBoxCh([])).toBe(0);
+    // Code points, not UTF-16 units: an astral glyph counts once.
+    expect(labelBoxCh(["1 🚲"])).toBe(3);
+  });
+
+  it("seriesEnds takes the first and last finite values", () => {
+    expect(seriesEnds([null, 2, null, 9, null])).toEqual([2, 9]);
+    expect(seriesEnds([5])).toEqual([5, 5]);
+    expect(seriesEnds([null, null])).toBeNull();
+  });
+
+  it("barDomain always contains zero; a fixed range wins", () => {
+    expect(barDomain("column", { min: 10, max: 40 }, null)).toEqual([0, 40]);
+    expect(barDomain("column", { min: -5, max: 20 }, null)).toEqual([-5, 20]);
+    expect(barDomain("table", { min: 10, max: 40 }, { min: -5, max: 60 })).toEqual([-5, 60]);
+    expect(barDomain([0, 100], { min: 10, max: 40 }, null)).toEqual([0, 100]);
+  });
+
+  it("barGeometry is proportional to the domain and grows left of zero when negative", () => {
+    expect(barGeometry(20, [0, 40])).toMatchObject({ start: 0, size: 50, negative: false });
+    expect(barGeometry(40, [0, 40]).size).toBe(100);
+    // zero sits at 20% of [-5, 20]; -5 spans 0…20%.
+    const neg = barGeometry(-5, [-5, 20]);
+    expect(neg).toMatchObject({ start: 0, size: 20, zero: 20, negative: true });
+    const pos = barGeometry(10, [-5, 20]);
+    expect(pos.start).toBe(20);
+    expect(pos.size).toBeCloseTo(40);
+    // Never negative, never NaN.
+    expect(barGeometry(Number.NaN, [0, 10]).size).toBe(0);
+    expect(barGeometry(5, [0, 0]).size).toBe(0);
+  });
+
+  it("seriesValues reads keys in order, null where a key holds no number", () => {
+    expect(seriesValues({ a: 1, b: "x", c: 3 }, ["c", "b", "a"])).toEqual([3, null, 1]);
+  });
+
+  it("heatmapColorScaleSpec maps the table methods onto colorScaleFor", () => {
+    expect(heatmapColorScaleSpec({ type: "stepped" })).toMatchObject({
+      type: "stepped",
+      method: "equidistant",
+    });
+    expect(heatmapColorScaleSpec({ type: "stepped", method: "jenks", steps: 4 })).toMatchObject({
+      type: "stepped",
+      method: "jenks",
+      steps: 4,
+    });
+    expect(heatmapColorScaleSpec({ type: "continuous", method: "jenks" })).toMatchObject({
+      type: "continuous",
+      method: "natural",
+    });
+    expect(
+      heatmapColorScaleSpec({ type: "continuous", method: "quantile", steps: 4 }),
+    ).toMatchObject({ type: "continuous", method: "quartiles" });
+    expect(
+      heatmapColorScaleSpec({ type: "continuous", method: "custom", breaks: [1, 2] }),
+    ).toMatchObject({ type: "stepped", method: "custom", breaks: [1, 2] });
+  });
+
+  it("computeColumnScales: column + table bar ranges, shared series extent, pooled heatmaps, categories", () => {
+    const scale = { type: "stepped" as const, steps: 3 };
+    const scales = computeColumnScales(
+      [
+        { id: "a", meta: { visual: { kind: "bar", range: "table" } } },
+        { id: "b", meta: { visual: { kind: "bar", range: "table" } } },
+        { id: "s", meta: { visual: { kind: "sparkline", keys: ["s1", "s2"], range: "column" } } },
+        { id: "a2", meta: { visual: { kind: "heatmap", scale } } },
+        { id: "b2", meta: { visual: { kind: "heatmap", scale } } },
+        { id: "cat", meta: { colorBy: { key: "cat", target: "background" } } },
+        { id: "plain", meta: { numeric: true } },
+      ],
+      rows.map((r) => ({
+        ...r,
+        getValue: (id: string) => r.getValue(id === "a2" ? "a" : id === "b2" ? "b" : id),
+      })),
+    );
+    expect(scales.get("a")?.barDomain).toEqual([-5, 40]);
+    expect(scales.get("b")?.barDomain).toEqual([-5, 40]);
+    expect(scales.get("s")?.seriesExtent).toEqual({ min: 1, max: 8 });
+    // Identical heatmap specs pool their values into ONE shared scale.
+    expect(scales.get("a2")?.heatmap).toBe(scales.get("b2")?.heatmap);
+    expect(scales.get("a2")?.heatmap?.domain).toEqual([-5, 40]);
+    expect(scales.get("a2")?.heatmap?.colorOf(40)).toMatch(/^var\(--chart-seq-\d\)$/);
+    expect(scales.get("cat")?.category?.colorOf("x")).toMatch(/^var\(--chart-\d+\)$/);
+    expect(scales.get("cat")?.category?.colorOf("x")).not.toBe(
+      scales.get("cat")?.category?.colorOf("y"),
+    );
+    expect(scales.has("plain")).toBe(false);
+  });
+});

package/src/data-table/cell-scales.ts

@@ -0,0 +1,246 @@
+/**
+ * cell-scales.ts — the shared scales behind `DataTable`'s in-cell visuals
+ * (RM-123). Pure: no React, no DOM.
+ *
+ * Every visual cell reads ONE scale per column, computed once over the full
+ * data (never the current page, filter or sort), so a bar, a sparkline or a
+ * heatmap colour means the same thing on every page and after every sort.
+ * Colour decisions (heatmap ramps, categories) come from `colorScaleFor`
+ * (`@elabs-ai/components-ui`) — the one value → colour-token scale `charts`,
+ * `data` and `maps` share — so colours are `var(--chart-…)` references.
+ */
+import { colorScaleFor, type ColorScale, type ColorScaleSpec } from "@elabs-ai/components-ui";
+import type { DataTableBarVisual, DataTableColumnMeta, DataTableHeatmapScale } from "./column-meta";
+
+/** `[min, max]` of the finite numbers in a set. */
+export interface NumericExtent {
+  min: number;
+  max: number;
+}
+
+/** The finite numbers in `values`, ignoring everything else. */
+export function finiteNumbers(values: readonly unknown[]): number[] {
+  return values.filter((v): v is number => typeof v === "number" && Number.isFinite(v));
+}
+
+/** The extent of the finite numbers in `values`; `null` when there are none. */
+export function extentOf(values: readonly unknown[]): NumericExtent | null {
+  const nums = finiteNumbers(values);
+  if (nums.length === 0) return null;
+  return { min: Math.min(...nums), max: Math.max(...nums) };
+}
+
+/** The union of two extents (either may be `null`). */
+export function unionExtent(
+  a: NumericExtent | null,
+  b: NumericExtent | null,
+): NumericExtent | null {
+  if (!a) return b;
+  if (!b) return a;
+  return { min: Math.min(a.min, b.min), max: Math.max(a.max, b.max) };
+}
+
+/** A bar domain always contains zero, so a bar is always measured from zero. */
+export function barDomain(
+  range: DataTableBarVisual["range"],
+  column: NumericExtent | null,
+  table: NumericExtent | null,
+): readonly [number, number] {
+  const source =
+    Array.isArray(range) && range.length === 2
+      ? { min: Math.min(range[0], range[1]), max: Math.max(range[0], range[1]) }
+      : range === "table"
+        ? table
+        : column;
+  return [Math.min(0, source?.min ?? 0), Math.max(0, source?.max ?? 0)];
+}
+
+/**
+ * Where a bar sits inside its track, as percentages of the track width:
+ * `start` is the inline-start edge, `size` the length. Negative values grow
+ * toward inline-start from zero. Both are clamped to 0…100.
+ */
+export function barGeometry(
+  value: number,
+  domain: readonly [number, number],
+): { start: number; size: number; zero: number; negative: boolean } {
+  const [lo, hi] = domain;
+  const span = hi - lo;
+  if (!Number.isFinite(value) || span <= 0) return { start: 0, size: 0, zero: 0, negative: false };
+  const pct = (v: number) => Math.min(100, Math.max(0, ((v - lo) / span) * 100));
+  const zero = pct(0);
+  const end = pct(value);
+  return {
+    start: Math.min(zero, end),
+    size: Math.max(0, Math.abs(end - zero)),
+    zero,
+    negative: value < 0,
+  };
+}
+
+/**
+ * How much room a column reserves for a printed label, in `ch`: the longest
+ * label's length in code points.
+ *
+ * A visual cell draws in what its printed value leaves over, so the text box
+ * must be a COLUMN-wide constant. Sized per row instead, a row with a shorter
+ * number gets a longer track and therefore draws a longer bar for a smaller
+ * value, and a diverging column's zero rule lands on a different pixel in every
+ * row. `tabular-nums` makes every digit exactly `1ch` and the separators
+ * narrower, so a reservation of the longest label's character count holds it.
+ */
+export function labelBoxCh(labels: readonly string[]): number {
+  let widest = 0;
+  for (const label of labels) widest = Math.max(widest, [...label].length);
+  return widest;
+}
+
+/** The first and last finite values of a series; `null` when it has none. */
+export function seriesEnds(
+  values: readonly (number | null)[],
+): readonly [first: number, last: number] | null {
+  const present = values.filter((v): v is number => v !== null);
+  const first = present[0];
+  const last = present[present.length - 1];
+  return first === undefined || last === undefined ? null : [first, last];
+}
+
+/** A row's numbers for `keys`, `null` where a key holds no finite number. */
+export function seriesValues(original: unknown, keys: readonly string[]): (number | null)[] {
+  const record = (original ?? {}) as Record<string, unknown>;
+  return keys.map((key) => {
+    const v = record[key];
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+  });
+}
+
+/** The `ColorScaleSpec` a heatmap scale asks `colorScaleFor` for. */
+export function heatmapColorScaleSpec(scale: DataTableHeatmapScale): ColorScaleSpec {
+  const base = {
+    ...(scale.domain ? { domain: scale.domain } : null),
+    ...(scale.palette ? { palette: scale.palette } : null),
+  };
+  const method = scale.method ?? "linear";
+  if (scale.type === "stepped" || method === "custom") {
+    return {
+      ...base,
+      type: "stepped",
+      method: method === "linear" ? "equidistant" : method,
+      ...(scale.steps !== undefined ? { steps: scale.steps } : null),
+      ...(scale.breaks ? { breaks: scale.breaks } : null),
+    };
+  }
+  if (method === "jenks") {
+    return { ...base, type: "continuous", method: "natural", steps: scale.steps ?? 5 };
+  }
+  if (method === "quantile") {
+    const steps = scale.steps ?? 5;
+    const quantile =
+      steps <= 2 ? "median" : steps <= 4 ? "quartiles" : steps <= 5 ? "quintiles" : "deciles";
+    return { ...base, type: "continuous", method: quantile };
+  }
+  return { ...base, type: "continuous", method: "linear" };
+}
+
+/** Everything a column's visual cells share. Only the parts the column uses are set. */
+export interface DataTableColumnScale {
+  /** Extent of the column's own values. */
+  extent: NumericExtent | null;
+  /** Bar visual: the resolved `[lo, hi]` (always contains zero). */
+  barDomain?: readonly [number, number];
+  /** Bar `colorBy`: the category → colour scale. */
+  barCategory?: ColorScale;
+  /** Sparkline / columns: extent of every row's series values. */
+  seriesExtent?: NumericExtent | null;
+  /**
+   * Heatmap: the value → ramp-colour scale. Heatmap columns with an identical
+   * `scale` spec SHARE one scale over all their values (one heatmap across
+   * several columns); `heatmapGroup` names it.
+   */
+  heatmap?: ColorScale;
+  heatmapGroup?: string;
+  /** `meta.colorBy`: the category → colour scale. */
+  category?: ColorScale;
+}
+
+/** A minimal row: what `computeColumnScales` needs from a TanStack row. */
+export interface ScaleRow {
+  original: unknown;
+  getValue: (columnId: string) => unknown;
+}
+
+/** A minimal column: its id and meta. */
+export interface ScaleColumn {
+  id: string;
+  meta: DataTableColumnMeta | undefined;
+}
+
+function categoryValues(rows: readonly ScaleRow[], key: string): (string | number | null)[] {
+  return rows.map((row) => {
+    const v = ((row.original ?? {}) as Record<string, unknown>)[key];
+    return typeof v === "string" || (typeof v === "number" && Number.isFinite(v)) ? v : null;
+  });
+}
+
+function categoryScale(rows: readonly ScaleRow[], key: string): ColorScale {
+  return colorScaleFor(categoryValues(rows, key), { type: "stepped", palette: "categorical" });
+}
+
+/**
+ * One scale per column that needs one (a `visual` or a `colorBy`), over ALL
+ * `rows`. Columns with neither are absent from the map.
+ */
+export function computeColumnScales(
+  columns: readonly ScaleColumn[],
+  rows: readonly ScaleRow[],
+): Map<string, DataTableColumnScale> {
+  const scales = new Map<string, DataTableColumnScale>();
+  let tableBarExtent: NumericExtent | null = null;
+  const heatmapValues = new Map<string, number[]>();
+  for (const { id, meta } of columns) {
+    if (!meta?.visual && !meta?.colorBy) continue;
+    const values = rows.map((row) => row.getValue(id));
+    const scale: DataTableColumnScale = { extent: extentOf(values) };
+    const visual = meta.visual;
+    if (visual?.kind === "bar" && visual.range === "table") {
+      tableBarExtent = unionExtent(tableBarExtent, scale.extent);
+    }
+    if (visual?.kind === "bar" && visual.colorBy) {
+      scale.barCategory = categoryScale(rows, visual.colorBy);
+    }
+    if (visual?.kind === "sparkline" || visual?.kind === "columns") {
+      scale.seriesExtent = extentOf(rows.flatMap((row) => seriesValues(row.original, visual.keys)));
+    }
+    if (visual?.kind === "heatmap") {
+      const group = JSON.stringify(visual.scale);
+      scale.heatmapGroup = group;
+      const pooled = heatmapValues.get(group) ?? [];
+      pooled.push(...finiteNumbers(values));
+      heatmapValues.set(group, pooled);
+    }
+    if (meta.colorBy) scale.category = categoryScale(rows, meta.colorBy.key);
+    scales.set(id, scale);
+  }
+  // Bar domains and heatmap scales resolve last: `range: "table"` needs every
+  // bar column's extent, a heatmap group every member column's values.
+  const heatmapScales = new Map<string, ColorScale>();
+  for (const { id, meta } of columns) {
+    const scale = scales.get(id);
+    if (!scale) continue;
+    if (meta?.visual?.kind === "bar") {
+      scale.barDomain = barDomain(meta.visual.range, scale.extent, tableBarExtent);
+    }
+    if (meta?.visual?.kind === "heatmap" && scale.heatmapGroup !== undefined) {
+      let shared = heatmapScales.get(scale.heatmapGroup);
+      if (!shared) {
+        shared = colorScaleFor(
+          heatmapValues.get(scale.heatmapGroup) ?? [],
+          heatmapColorScaleSpec(meta.visual.scale),
+        );
+        heatmapScales.set(scale.heatmapGroup, shared);
+      }
+      scale.heatmap = shared;
+    }
+  }
+  return scales;
+}

package/src/data-table/cells/bar-cell.test.tsx

@@ -0,0 +1,158 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import { oklchToHex } from "@elabs-ai/components-tokens";
+import { BAR_CELL_NEGATIVE_COLOR, BAR_CELL_POSITIVE_COLOR, BarCell } from "./bar-cell";
+
+describe("BarCell", () => {
+  it("keeps the printed value and sizes the bar against the domain", () => {
+    const { container, getByText } = render(
+      <BarCell value={20} label="20" domain={[0, 40]} track />,
+    );
+    expect(getByText("20")).toBeInTheDocument();
+    const bar = container.querySelector<HTMLElement>('[data-slot="bar-cell-bar"]');
+    expect(bar?.style.width).toBe("50%");
+    expect(bar?.style.backgroundColor).toBe(BAR_CELL_POSITIVE_COLOR);
+    expect(container.querySelector('[data-slot="bar-cell-track"]')).toHaveClass("bg-muted");
+  });
+  it("paints a negative value in the negative token, left of zero, with a zero rule", () => {
+    const { container } = render(<BarCell value={-5} label="-5" domain={[-5, 20]} />);
+    const bar = container.querySelector<HTMLElement>('[data-slot="bar-cell-bar"]');
+    expect(bar?.style.backgroundColor).toBe(BAR_CELL_NEGATIVE_COLOR);
+    expect(bar?.style.insetInlineStart).toBe("0%");
+    expect(bar?.style.width).toBe("20%");
+    expect(container.querySelector('[data-slot="bar-cell-zero"]')).not.toBeNull();
+    expect(container.querySelector('[data-slot="bar-cell"]')).toHaveAttribute(
+      "data-negative",
+      "true",
+    );
+  });
+  it("reserves one value box per column, so a shorter number gets no longer bar", () => {
+    // Same reservation, different label lengths: the track (and therefore every
+    // bar drawn in it) is the same length on both rows.
+    const box = (label: string) => {
+      const { container } = render(
+        <BarCell value={10} label={label} domain={[0, 40]} labelWidth={7} />,
+      );
+      return container.querySelector<HTMLElement>('[data-slot="bar-cell-value"]')?.style.width;
+    };
+    expect(box("+12.5 %")).toBe("7ch");
+    expect(box("-4.2 %")).toBe("7ch");
+    // A slim bar sits UNDER its value and spans the cell: nothing to reserve.
+    const { container } = render(
+      <BarCell value={10} label="-4.2 %" domain={[0, 40]} variant="slim" labelWidth={7} />,
+    );
+    expect(container.querySelector<HTMLElement>('[data-slot="bar-cell-value"]')?.style.width).toBe(
+      "",
+    );
+  });
+  it("keeps the slim track off the column flex axis, so the mark has height", () => {
+    // `flex-1` is `flex: 1 1 0%`: in the slim variant the parent is a COLUMN,
+    // so that would resolve the track's HEIGHT to 0 and paint nothing.
+    const { container } = render(
+      <BarCell value={10} label="25 %" domain={[0, 40]} variant="slim" track />,
+    );
+    const slim = container.querySelector('[data-slot="bar-cell-track"]');
+    expect(slim).toHaveClass("h-1", "w-full", "shrink-0");
+    expect(slim).not.toHaveClass("flex-1");
+    const { container: regular } = render(
+      <BarCell value={10} label="25 %" domain={[0, 40]} track />,
+    );
+    const row = regular.querySelector('[data-slot="bar-cell-track"]');
+    expect(row).toHaveClass("h-3", "flex-1");
+  });
+  it("uses a category colour for positive bars; negative: false keeps it on negatives", () => {
+    const { container } = render(
+      <BarCell
+        value={-2}
+        label="-2"
+        domain={[-5, 5]}
+        fillColor="var(--chart-3)"
+        negativeColor={false}
+      />,
+    );
+    expect(
+      container.querySelector<HTMLElement>('[data-slot="bar-cell-bar"]')?.style.backgroundColor,
+    ).toBe("var(--chart-3)");
+  });
+});
+
+/**
+ * b-4 — an in-cell bar is a mark whose LENGTH is the message, so it is a
+ * "graphical object required to understand the content" (WCAG 1.4.11, ≥ 3:1)
+ * and the house status-rung rule asks the same of a fill that IS the mark, in
+ * EVERY theme. Before this test the positive fill was `--chart-1`, a
+ * categorical token with no contrast guarantee that measures 1.42:1 on `--card`
+ * in `light` (a signed-off palette exemption — see `CHART_1411_EXEMPT` in
+ * packages/tokens/src/charts-contrast.test.ts). The token is not the bug; using
+ * a token that carries no guarantee for a mark that needs one is.
+ *
+ * Reads the shipped theme stylesheets rather than a copied number, so a retune
+ * that drops either fill below the bar fails here instead of shipping.
+ */
+describe("BarCell — the fills clear the 1.4.11 mark bar in every theme", () => {
+  const THEMES = ["light", "dark"] as const;
+
+  /** The shipped stylesheet for `theme`, found by walking up from the cwd. */
+  function themeCssPath(theme: (typeof THEMES)[number]): string {
+    let dir = process.cwd();
+    for (let up = 0; up < 6; up++) {
+      const candidate = join(dir, "packages/tokens/src/themes", `${theme}.css`);
+      if (existsSync(candidate)) return candidate;
+      dir = dirname(dir);
+    }
+    throw new Error(`No theme stylesheet found for "${theme}" above ${process.cwd()}`);
+  }
+
+  function themeTokens(theme: (typeof THEMES)[number]): Map<string, string> {
+    const css = readFileSync(themeCssPath(theme), "utf8");
+    const map = new Map<string, string>();
+    for (const [, name, value] of css.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) {
+      map.set(name as string, (value as string).trim());
+    }
+    return map;
+  }
+
+  /** `var(--x)` → the token's own oklch value in `theme`, following aliases. */
+  function resolve(tokens: Map<string, string>, ref: string): string {
+    let value = ref;
+    for (let hop = 0; hop < 8 && value.startsWith("var("); hop++) {
+      value = tokens.get(value.slice(4, value.indexOf(")")).trim()) ?? "";
+    }
+    return value;
+  }
+
+  /** WCAG 2.x relative luminance of `#rrggbb`. */
+  function luminance(hex: string): number {
+    const channel = (i: number) => {
+      const c = parseInt(hex.slice(1 + i * 2, 3 + i * 2), 16) / 255;
+      return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * channel(0) + 0.7152 * channel(1) + 0.0722 * channel(2);
+  }
+
+  function contrast(a: string, b: string): number {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [number, number];
+    return (hi + 0.05) / (lo + 0.05);
+  }
+
+  it.each(THEMES)("%s: both bar fills are ≥ 3:1 on --card and on the bg-muted track", (theme) => {
+    const tokens = themeTokens(theme);
+    const card = oklchToHex(resolve(tokens, "var(--card)"));
+    const track = oklchToHex(resolve(tokens, "var(--muted)"));
+    expect(card, `${theme}: --card`).not.toBeNull();
+    expect(track, `${theme}: --muted`).not.toBeNull();
+    for (const fill of [BAR_CELL_POSITIVE_COLOR, BAR_CELL_NEGATIVE_COLOR]) {
+      const hex = oklchToHex(resolve(tokens, fill));
+      expect(hex, `${theme}: ${fill}`).not.toBeNull();
+      expect(contrast(hex as string, card as string), `${fill} on --card`).toBeGreaterThanOrEqual(
+        3,
+      );
+      expect(
+        contrast(hex as string, track as string),
+        `${fill} on the --muted track`,
+      ).toBeGreaterThanOrEqual(3);
+    }
+  });
+});