@elabs-ai/components-data 4.1.0 → 5.0.0

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

@@ -537,6 +537,39 @@ describe("DataTable — virtualized a11y + composability", () => {
     expect(indexedRows.length).toBeLessThan(bigData.length);
   });
 
+  it("places sticky rows in the virtualized aria-rowindex sequence and counts them", () => {
+    // Sticky rows mount OUTSIDE the virtual window. Without an index of their
+    // own AT hears unplaced extra rows, and aria-rowcount (built from the
+    // centre row model) under-reports the table by exactly those rows.
+    const { container } = render(
+      <DataTable
+        columns={columns}
+        data={bigData}
+        enableRowVirtualization
+        stickyRows={(row) => {
+          if (row.name === "Row 0") return "top";
+          if (row.name === "Row 1") return "bottom";
+          return undefined;
+        }}
+      />,
+    );
+    // 98 centre + 1 top + 1 bottom + 1 header row.
+    expect(container.querySelector("table")).toHaveAttribute(
+      "aria-rowcount",
+      String(bigData.length + 1),
+    );
+    const mounted = [...container.querySelectorAll("tbody tr")].filter(
+      (tr) => tr.getAttribute("aria-hidden") !== "true",
+    );
+    // Every mounted, non-spacer row is placed — no row without an index.
+    expect(mounted.every((tr) => tr.hasAttribute("aria-rowindex"))).toBe(true);
+    const indexOf = (name: string) =>
+      mounted.find((tr) => tr.textContent?.includes(name))?.getAttribute("aria-rowindex");
+    // Header holds 1; the top-pinned row takes 2, the bottom-pinned row last.
+    expect(indexOf("Row 0")).toBe("2");
+    expect(indexOf("Row 1")).toBe(String(bigData.length + 1));
+  });
+
   it("makes the virtualized scroll region keyboard-focusable with a visible focus ring", () => {
     const { container } = render(
       <DataTable columns={columns} data={bigData} enableRowVirtualization />,
@@ -592,11 +625,35 @@ describe("DataTable — zebra striping (default) vs lines", () => {
     const rows = container.querySelectorAll("tbody tr");
     expect(rows.length).toBe(3);
     // 2nd row (index 1) is striped; 1st/3rd are not — the stripe is the cue.
-    expect(rows[0]?.className).not.toContain("bg-foreground/5");
-    expect(rows[1]?.className).toContain("bg-foreground/5");
-    expect(rows[2]?.className).not.toContain("bg-foreground/5");
-    // No row carries a divider (a border on a striped region would be redundant).
-    rows.forEach((r) => expect(r.className).not.toContain("border-b"));
+    expect(rows[0]?.className).not.toContain("bg-table-stripe");
+    expect(rows[1]?.className).toContain("bg-table-stripe");
+    expect(rows[2]?.className).not.toContain("bg-table-stripe");
+    // No row carries a fixed divider (a border on a striped region would be
+    // redundant). The only row rule is the theme-gated width, `0px` by default,
+    // for a theme that turns the stripe off.
+    rows.forEach((r) => {
+      const classes = r.className.split(/\s+/);
+      expect(classes).not.toContain("border-b");
+      expect(classes).toContain("border-b-(length:--table-row-rule-width)");
+    });
+  });
+
+  it("draws column dividers only when asked", () => {
+    const plain = render(<DataTable columns={columns} data={data} />);
+    plain.container
+      .querySelectorAll("th, td")
+      .forEach((c) => expect(c.className.split(/\s+/)).not.toContain("border-e"));
+    plain.unmount();
+
+    const { container } = render(<DataTable columns={columns} data={data} columnDividers />);
+    const cells = container.querySelectorAll("thead th, tbody td");
+    expect(cells.length).toBeGreaterThan(0);
+    cells.forEach((c) => {
+      const classes = c.className.split(/\s+/);
+      expect(classes).toContain("border-e");
+      expect(classes).toContain("border-rule");
+      expect(classes).toContain("last:border-e-0");
+    });
   });
 
   it("draws border-strong dividers and no stripes when zebra is disabled", () => {
@@ -605,7 +662,7 @@ describe("DataTable — zebra striping (default) vs lines", () => {
     rows.forEach((r) => {
       expect(r.className).toContain("border-b");
       expect(r.className).toContain("border-border-strong");
-      expect(r.className).not.toContain("bg-foreground/5");
+      expect(r.className).not.toContain("bg-table-stripe");
     });
     // Last row drops its divider so it doesn't double with the container border.
     expect(rows[rows.length - 1]?.className).toContain("last:border-b-0");
@@ -866,6 +923,32 @@ describe("DataTable — #330 the scroll tab stop exists only while the region ov
     simulateScrollMetrics(scrollRegion, { scrollWidth: 800, clientWidth: 900, scrollLeft: 0 });
     expect(scrollRegion).not.toHaveAttribute("tabindex");
   });
+
+  it('gains role="group" once it overflows — a named, non-landmark stop', () => {
+    const { container } = render(<DataTable columns={columns} data={data} />);
+    const scrollRegion = scrollRegionOf(container);
+    // `aria-label` on a plain `<div>` (role `generic`) is not guaranteed to
+    // produce an accessible name at all — the stop needs a naming-capable
+    // role, and `group` (not the `region` landmark, which collides under axe
+    // `landmark-unique` across tables) is it.
+    expect(scrollRegion).not.toHaveAttribute("role");
+    simulateScrollMetrics(scrollRegion, { scrollWidth: 800, clientWidth: 300, scrollLeft: 0 });
+    expect(scrollRegion).toHaveAttribute("role", "group");
+  });
+});
+
+describe("DataTable — virtualized scroll region has a naming-capable role", () => {
+  it('the always-focusable virtualized scroll container carries role="group"', () => {
+    const { container } = render(
+      <DataTable columns={columns} data={data} enableRowVirtualization />,
+    );
+    const scroll = container.querySelector(".overflow-auto");
+    expect(scroll).toHaveAttribute("tabindex", "0");
+    expect(scroll).toHaveAttribute("aria-label");
+    // Same reasoning as the non-virtualized branch above: `aria-label` alone
+    // on a role-less `<div>` is not guaranteed to compute an accessible name.
+    expect(scroll).toHaveAttribute("role", "group");
+  });
 });
 
 describe("DataTable — #330 horizontal-scroll edge-fade affordance", () => {
@@ -1177,7 +1260,7 @@ describe("DataTable — #337 onRowClick + rowClassName", () => {
     const betaRow = screen.getByText("Beta").closest("tr")!;
     expect(betaRow).toHaveClass("is-highlighted");
     // Beta is row index 1 — the zebra stripe class must still be present.
-    expect(betaRow.className).toContain("bg-foreground/5");
+    expect(betaRow.className).toContain("bg-table-stripe");
   });
 
   it("gives a clickable row a pointer cursor and a focus ring driven by its activation button", () => {
@@ -1393,10 +1476,10 @@ describe("DataTable — #333 pinned cells compose with the row wash, not overpai
     expect(odd!.className).toContain("bg-card");
     // Only the striped row re-applies the wash, on the decorative ::before layer
     // — this is the bug #333 reports: a single opaque fill erased the stripe.
-    expect(odd!.className).toContain("before:bg-foreground/5");
-    expect(even!.className).not.toContain("before:bg-foreground/5");
+    expect(odd!.className).toContain("before:bg-table-stripe");
+    expect(even!.className).not.toContain("before:bg-table-stripe");
     // Hover/selected are re-applied from the row group in both cases.
-    expect(even!.className).toContain("group-hover/row:before:bg-foreground/10");
+    expect(even!.className).toContain("group-hover/row:before:bg-table-row-hover");
     expect(container.querySelector("tbody tr")!.className).toContain("group/row");
   });
 
@@ -1411,7 +1494,7 @@ describe("DataTable — #333 pinned cells compose with the row wash, not overpai
     );
     for (const cell of pinned(container, "left")) {
       expect(cell.className).toContain("bg-card");
-      expect(cell.className).not.toContain("before:bg-foreground/5");
+      expect(cell.className).not.toContain("before:bg-table-stripe");
     }
     // The row divider is still the separation cue and is untouched by pinning.
     expect(container.querySelector("tbody tr")!.className).toContain("border-border-strong");
@@ -2875,3 +2958,456 @@ describe("DataTable — #13 row drag-reorder", () => {
     expect(describedByText).toMatch(/To pick up|space bar/i);
   });
 });
+
+// ─── Presentation layer: visuals, format, showAt, cards, sticky rows, ranks ──
+
+/** Every element measures `width` wide, so the table breakpoint resolves from it. */
+function mockTableWidth(width: number) {
+  return vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(
+    () =>
+      ({
+        width,
+        height: 40,
+        top: 0,
+        left: 0,
+        right: width,
+        bottom: 40,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      }) as DOMRect,
+  );
+}
+
+interface CityRow {
+  city: string;
+  rides: number;
+  change: number;
+  q1: number;
+  q2: number;
+  q3: number;
+  region: string;
+}
+
+const cities: CityRow[] = [
+  { city: "Oslo", rides: 20, change: -5, q1: 1, q2: 4, q3: 2, region: "North" },
+  { city: "Lyon", rides: 40, change: 20, q1: 8, q2: 3, q3: 5, region: "South" },
+  { city: "Graz", rides: 9, change: 5, q1: 2, q2: 2, q3: 8, region: "South" },
+  { city: "Average", rides: 23, change: 6.7, q1: 3.7, q2: 3, q3: 5, region: "All" },
+];
+
+describe("DataTable — presentation layer", () => {
+  it("no presentation prop: the default DOM is unchanged (table, no rank, no layout attr)", () => {
+    const { container } = render(<DataTable columns={columns} data={data} />);
+    expect(container.querySelector("table")).not.toBeNull();
+    expect(container.querySelector("dl")).toBeNull();
+    expect(container.querySelector("[data-layout]")).toBeNull();
+    expect(container.querySelector('[data-slot="data-table-rank-cell"]')).toBeNull();
+  });
+
+  it('layout="auto": <dl> cards under 450 px, a <table> above', () => {
+    const narrow = mockTableWidth(380);
+    const { container, unmount } = render(
+      <DataTable columns={columns} data={data} layout="auto" aria-label="Rows" />,
+    );
+    expect(container.querySelector('[data-layout="cards"]')).not.toBeNull();
+    expect(container.querySelector("table")).toBeNull();
+    expect(container.querySelectorAll('[data-slot="data-table-card"] dl')).toHaveLength(3);
+    expect(screen.getAllByRole("term").map((t) => t.textContent)).toContain("Name");
+    unmount();
+    narrow.mockRestore();
+    const wide = mockTableWidth(900);
+    const again = render(<DataTable columns={columns} data={data} layout="auto" />);
+    expect(again.container.querySelector('[data-layout="table"]')).not.toBeNull();
+    expect(again.container.querySelector("table")).not.toBeNull();
+    expect(again.container.querySelector("dl")).toBeNull();
+    wide.mockRestore();
+  });
+
+  it("cards keep sorting: the sort bar reorders the cards", () => {
+    const { container } = render(<DataTable columns={columns} data={data} layout="cards" />);
+    const firstName = () =>
+      container.querySelector('[data-slot="data-table-card"] dd')?.textContent ?? "";
+    expect(firstName()).toBe("Alpha");
+    // TanStack sorts a numeric column descending first.
+    fireEvent.click(screen.getByRole("button", { name: "Sort by Value, not sorted" }));
+    expect(firstName()).toBe("Alpha");
+    fireEvent.click(screen.getByRole("button", { name: "Sort by Value, descending" }));
+    expect(firstName()).toBe("Beta");
+  });
+
+  it("showAt { base: true, narrow: false } hides the column under 450 px only", () => {
+    const cols: ColumnDef<Row>[] = [
+      columns[0]!,
+      { ...columns[1]!, meta: { showAt: { base: true, narrow: false } } },
+    ];
+    const narrow = mockTableWidth(380);
+    const { unmount } = render(<DataTable columns={cols} data={data} />);
+    expect(screen.queryByRole("columnheader", { name: /Value/ })).toBeNull();
+    expect(screen.getAllByRole("columnheader")).toHaveLength(1);
+    unmount();
+    narrow.mockRestore();
+    const wide = mockTableWidth(900);
+    render(<DataTable columns={cols} data={data} />);
+    expect(screen.getByRole("columnheader", { name: /Value/ })).toBeInTheDocument();
+    wide.mockRestore();
+  });
+
+  it("warns once, instead of failing silently, when row reorder meets the card layout", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      { accessorKey: "rides", header: "Rides" },
+    ];
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const onRowReorder = vi.fn();
+    const { container, rerender } = render(
+      <DataTable
+        columns={cols}
+        data={cities}
+        enableRowReorder
+        layout="cards"
+        onRowReorder={onRowReorder}
+      />,
+    );
+    // No drag affordance is mounted in cards — no grip button, no drop target.
+    expect(screen.queryByRole("button", { name: /reorder|drag|move/i })).not.toBeInTheDocument();
+    expect(container.querySelector("[data-slot='data-table-card-region']")).not.toBeNull();
+    expect(onRowReorder).not.toHaveBeenCalled();
+    const reorderWarnings = () =>
+      warn.mock.calls.filter((c) => String(c[0]).includes("`enableRowReorder` is ignored"));
+    expect(reorderWarnings()).toHaveLength(1);
+    // Once per mount, not once per render.
+    rerender(
+      <DataTable
+        columns={cols}
+        data={cities}
+        enableRowReorder
+        layout="cards"
+        onRowReorder={onRowReorder}
+      />,
+    );
+    expect(reorderWarnings()).toHaveLength(1);
+    warn.mockRestore();
+  });
+
+  it("stickyRows keeps the average row on every page and after sorting", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      { accessorKey: "rides", header: "Rides", enableSorting: true },
+    ];
+    const { container } = render(
+      <DataTable
+        columns={cols}
+        data={cities}
+        enablePagination
+        pageSize={2}
+        stickyRows={(row) => (row.city === "Average" ? "bottom" : undefined)}
+      />,
+    );
+    const names = () =>
+      [...container.querySelectorAll("tbody tr")].map(
+        (tr) => tr.querySelector("td")?.textContent ?? "",
+      );
+    expect(names()).toEqual(["Oslo", "Lyon", "Average"]);
+    fireEvent.click(screen.getByRole("button", { name: /Next/i }));
+    expect(names()).toEqual(["Graz", "Average"]);
+    fireEvent.click(screen.getByRole("button", { name: /Previous/i }));
+    fireEvent.click(screen.getByRole("button", { name: "Sort by Rides, not sorted" }));
+    // Descending (numeric columns sort descending first): Lyon 40, Oslo 20 on
+    // page one — the average (23) is not sorted into them, it stays last.
+    expect(names()).toEqual(["Lyon", "Oslo", "Average"]);
+    fireEvent.click(screen.getByRole("button", { name: /Next/i }));
+    expect(names()).toEqual(["Graz", "Average"]);
+    expect(container.querySelector('tr[data-sticky="bottom"]')).toHaveTextContent("Average");
+  });
+
+  it("showRanks renders 1…n in data order, unaffected by sort (sticky rows unranked)", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      { accessorKey: "rides", header: "Rides", enableSorting: true },
+    ];
+    const { container } = render(
+      <DataTable
+        columns={cols}
+        data={cities}
+        showRanks
+        stickyRows={(row) => (row.city === "Average" ? "bottom" : undefined)}
+      />,
+    );
+    const ranked = () =>
+      [...container.querySelectorAll("tbody tr")].map((tr) => [
+        tr.querySelector('[data-slot="data-table-rank-cell"]')?.textContent ?? "",
+        tr.querySelectorAll("td")[1]?.textContent ?? "",
+      ]);
+    expect(ranked()).toEqual([
+      ["1", "Oslo"],
+      ["2", "Lyon"],
+      ["3", "Graz"],
+      ["", "Average"],
+    ]);
+    fireEvent.click(screen.getByRole("button", { name: "Sort by Rides, not sorted" }));
+    expect(ranked()).toEqual([
+      ["2", "Lyon"],
+      ["1", "Oslo"],
+      ["3", "Graz"],
+      ["", "Average"],
+    ]);
+    expect(screen.getAllByRole("columnheader")[0]).toHaveTextContent("#");
+  });
+
+  /**
+   * b-5 — the same table, read: the ranks are the DATA order, so after the
+   * sort above they read 2, 1, 3 beside a descending column. That is only
+   * honest if the table says which position it is printing, in BOTH channels
+   * — the header's accessible name for AT, and a printed key for everyone
+   * else. A bare "#" said it in neither.
+   */
+  it("showRanks says which position it prints — named for AT, printed as a key", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      { accessorKey: "rides", header: "Rides", enableSorting: true },
+    ];
+    const { container } = render(<DataTable columns={cols} data={cities} showRanks />);
+    expect(screen.getAllByRole("columnheader")[0]).toHaveAccessibleName(
+      "Position in the data as supplied",
+    );
+    const key = container.querySelector('[data-slot="data-table-rank-key"]');
+    expect(key).toHaveTextContent(
+      "# is each row’s position in the data as supplied, not its position in this view — sorting never renumbers it.",
+    );
+  });
+
+  it("showRanks: a caller's own rankLabel names the column and the key", () => {
+    const cols: ColumnDef<CityRow>[] = [{ accessorKey: "city", header: "City" }];
+    const { container } = render(
+      <DataTable columns={cols} data={cities} showRanks rankLabel="Rank in the 2024 census" />,
+    );
+    expect(screen.getAllByRole("columnheader")[0]).toHaveAccessibleName("Rank in the 2024 census");
+    expect(container.querySelector('[data-slot="data-table-rank-key"]')).toHaveTextContent(
+      "# — Rank in the 2024 census",
+    );
+  });
+
+  it("no ranks, no key: the rank key never renders for a table without showRanks", () => {
+    const cols: ColumnDef<CityRow>[] = [{ accessorKey: "city", header: "City" }];
+    const { container } = render(<DataTable columns={cols} data={cities} />);
+    expect(container.querySelector('[data-slot="data-table-rank-key"]')).toBeNull();
+    expect(container.querySelector('[data-slot="data-table-legends"]')).toBeNull();
+  });
+
+  it('searchMode="exact" matches whole, case-insensitive values only', () => {
+    const { container, rerender } = render(
+      <DataTable columns={columns} data={data} initialView={{ globalFilter: "et" }} />,
+    );
+    expect(container.querySelectorAll("tbody tr")).toHaveLength(1);
+    rerender(<DataTable columns={columns} data={data} globalFilter="beta" searchMode="exact" />);
+    expect(container.querySelectorAll("tbody tr")).toHaveLength(1);
+    expect(container.querySelector("tbody tr")).toHaveTextContent("Beta");
+    rerender(<DataTable columns={columns} data={data} globalFilter="bet" searchMode="exact" />);
+    expect(screen.queryByText("Beta")).toBeNull();
+  });
+
+  it("mergeEmptyHeaders spans an ungrouped column's header down the header rows", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      {
+        id: "quarters",
+        header: "Quarters",
+        columns: [
+          { accessorKey: "q1", header: "Q1" },
+          { accessorKey: "q2", header: "Q2" },
+        ],
+      },
+    ];
+    const { container, rerender } = render(<DataTable columns={cols} data={cities} />);
+    expect(container.querySelectorAll("thead tr")[0]?.querySelectorAll("th")).toHaveLength(2);
+    rerender(<DataTable columns={cols} data={cities} mergeEmptyHeaders />);
+    const [top, bottom] = [...container.querySelectorAll("thead tr")];
+    const city = [...(top?.querySelectorAll("th") ?? [])].find((th) => th.textContent === "City");
+    expect(city).toHaveAttribute("rowspan", "2");
+    expect(top?.querySelector("th[colspan='2']")).toHaveTextContent("Quarters");
+    expect([...(bottom?.querySelectorAll("th") ?? [])].map((th) => th.textContent)).toEqual([
+      "Q1",
+      "Q2",
+    ]);
+  });
+
+  it("heatmap: ramp-token backgrounds, values kept for AT, numeric sort", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      {
+        accessorKey: "rides",
+        header: "Rides",
+        enableSorting: true,
+        meta: {
+          numeric: true,
+          visual: { kind: "heatmap", scale: { type: "stepped", steps: 3 }, hideValue: true },
+        },
+      },
+    ];
+    const { container } = render(<DataTable columns={cols} data={cities.slice(0, 3)} />);
+    const tds = [...container.querySelectorAll("tbody td:nth-child(2)")] as HTMLElement[];
+    for (const td of tds) {
+      expect(td.style.backgroundColor).toMatch(/^var\(--chart-seq-\d\)$/);
+      expect(td.querySelector('[data-slot="heatmap-cell"]')).toHaveClass("sr-only");
+    }
+    expect(tds.map((td) => td.textContent)).toEqual(["20", "40", "9"]);
+    const order = () =>
+      [...container.querySelectorAll("tbody td:nth-child(2)")].map((td) => td.textContent);
+    // Numeric, not string, order both ways ("9" would sort after "40" as text).
+    fireEvent.click(screen.getByRole("button", { name: "Sort by Rides, not sorted" }));
+    expect(order()).toEqual(["40", "20", "9"]);
+    fireEvent.click(screen.getByRole("button", { name: "Sort by Rides, descending" }));
+    expect(order()).toEqual(["9", "20", "40"]);
+  });
+
+  it('bar: range "column" is proportional to the column max; negatives paint left of zero', () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      { accessorKey: "rides", header: "Rides", meta: { visual: { kind: "bar", track: true } } },
+      { accessorKey: "change", header: "Change", meta: { visual: { kind: "bar" } } },
+    ];
+    const { container } = render(<DataTable columns={cols} data={cities.slice(0, 3)} />);
+    const bars = (col: number) =>
+      [...container.querySelectorAll(`tbody td:nth-child(${col}) [data-slot="bar-cell-bar"]`)].map(
+        (el) => (el as HTMLElement).style,
+      );
+    expect(bars(2).map((s) => s.width)).toEqual(["50%", "100%", "22.5%"]);
+    expect(container.querySelector('[data-slot="bar-cell-track"]')).toHaveClass("bg-muted");
+    const [oslo] = bars(3);
+    expect(oslo?.backgroundColor).toBe("var(--chart-div-neg-2)");
+    expect(oslo?.insetInlineStart).toBe("0%");
+    // The printed value stays in the cell for AT.
+    expect(container.querySelector("tbody td:nth-child(3)")).toHaveTextContent("-5");
+  });
+
+  it("bar: one value box per column, so bar LENGTHS compare down the column", () => {
+    // Without a column-wide reservation the track is whatever each row's number
+    // leaves over, so "9" would draw a longer bar than its share of the column.
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      { accessorKey: "rides", header: "Rides", meta: { visual: { kind: "bar", track: true } } },
+      {
+        accessorKey: "change",
+        header: "Change",
+        meta: { format: { sign: "always", suffix: " %" }, visual: { kind: "bar" } },
+      },
+    ];
+    const { container } = render(<DataTable columns={cols} data={cities.slice(0, 3)} />);
+    const boxes = (col: number) =>
+      [
+        ...container.querySelectorAll(`tbody td:nth-child(${col}) [data-slot="bar-cell-value"]`),
+      ].map((el) => (el as HTMLElement).style.width);
+    // "20" / "40" / "9" → the column's longest label is 2 characters.
+    expect(boxes(2)).toEqual(["2ch", "2ch", "2ch"]);
+    // "-5 %" / "+20 %" / "+5 %" → 5, on every row including the short ones.
+    expect(boxes(3)).toEqual(["5ch", "5ch", "5ch"]);
+  });
+
+  it('sparkline + columns with range "column" share one y scale across rows', () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City" },
+      {
+        id: "trend",
+        header: "Trend",
+        meta: { visual: { kind: "sparkline", keys: ["q1", "q2", "q3"], range: "column" } },
+      },
+      {
+        id: "bars",
+        header: "Quarters",
+        meta: { visual: { kind: "columns", keys: ["q1", "q2", "q3"], range: "column" } },
+      },
+    ];
+    const { container } = render(<DataTable columns={cols} data={cities.slice(0, 3)} />);
+    const maxes = [...container.querySelectorAll('[data-slot="sparkline-cell-svg"]')].map((svg) =>
+      svg.getAttribute("data-y-max"),
+    );
+    expect(new Set(maxes)).toEqual(new Set(["8"]));
+    const colMaxes = [...container.querySelectorAll('[data-slot="columns-cell-svg"]')].map((svg) =>
+      svg.getAttribute("data-y-max"),
+    );
+    expect(new Set(colMaxes)).toEqual(new Set(["8"]));
+    // Each cell's numbers are in the accessible tree.
+    expect(container.querySelector("tbody tr td:nth-child(2)")).toHaveTextContent(/1.*4.*2/);
+  });
+
+  /**
+   * b-6 — a bar coloured by `region` in a table that prints no region column
+   * carried that category in hue alone: nothing named the groups, and two of
+   * the three categorical tokens are 5/255 apart in greyscale. The key names
+   * them (WCAG 1.4.1), once per source key however many columns use it.
+   */
+  it("a colorBy column draws a named category key, once per source key", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      {
+        accessorKey: "rides",
+        header: "Rides",
+        meta: { visual: { kind: "bar", colorBy: "region", legend: "Region" } },
+      },
+      {
+        accessorKey: "change",
+        header: "Change",
+        meta: { visual: { kind: "bar", colorBy: "region" } },
+      },
+    ];
+    render(<DataTable columns={cols} data={cities} />);
+    const key = screen.getByRole("group", { name: "Region" });
+    expect([...key.querySelectorAll("li")].map((li) => li.textContent)).toEqual([
+      "North",
+      "South",
+      "All",
+    ]);
+    expect(screen.getAllByRole("group", { name: "Region" })).toHaveLength(1);
+  });
+
+  it("legend: false opts a colorBy column out of the key", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      {
+        accessorKey: "rides",
+        header: "Rides",
+        meta: { visual: { kind: "bar", colorBy: "region", legend: false } },
+      },
+    ];
+    const { container } = render(<DataTable columns={cols} data={cities} />);
+    expect(container.querySelector('[data-slot="category-legend"]')).toBeNull();
+  });
+
+  it("meta.format formats the default cell; colorBy washes by category", () => {
+    const cols: ColumnDef<CityRow>[] = [
+      { accessorKey: "city", header: "City", meta: { colorBy: { key: "region", target: "text" } } },
+      {
+        accessorKey: "change",
+        header: "Change",
+        meta: { format: { sign: "always", suffix: " %" } },
+      },
+    ];
+    const { container } = render(<DataTable columns={cols} data={cities.slice(0, 2)} />);
+    expect(container.querySelector("tbody td:nth-child(2)")).toHaveTextContent("-5 %");
+    expect(container.querySelectorAll("tbody td:nth-child(2)")[1]).toHaveTextContent("+20 %");
+    const [oslo, lyon] = [...container.querySelectorAll("tbody td:nth-child(1)")] as HTMLElement[];
+    expect(oslo?.style.color).toMatch(/color-mix/);
+    expect(oslo?.style.color).not.toBe(lyon?.style.color);
+  });
+
+  it("hideHeader keeps the header row for AT but hides it visually", () => {
+    render(<DataTable columns={columns} data={data} hideHeader />);
+    expect(screen.getAllByRole("columnheader")).toHaveLength(2);
+    expect(
+      screen.getByRole("button", { name: "Sort by Name, not sorted" }).closest("span"),
+    ).toHaveClass("sr-only");
+  });
+
+  // RM-127 (a-5): WCAG 2.2 target size (2.5.8). The sort button is 16–20 px of
+  // text and used to clear the rule only through the space AROUND it — which
+  // `hideHeader` (`h-0 p-0`, 16 px between neighbours) and the card sort bar
+  // (`gap-y-1`, 4 px) both take away. Measured in Chromium at 380 px: the
+  // 11 card-bar buttons were 52.4 x 16 and axe reported 6 serious
+  // `target-size` nodes; they are 24 px tall now and axe passes on all 11.
+  it("sizes every sort button to the 24 px target floor, hidden header or card bar", () => {
+    const { unmount } = render(<DataTable columns={columns} data={data} />);
+    expect(screen.getByRole("button", { name: "Sort by Name, not sorted" })).toHaveClass("min-h-6");
+    unmount();
+    render(<DataTable columns={columns} data={data} hideHeader />);
+    expect(screen.getByRole("button", { name: "Sort by Name, not sorted" })).toHaveClass("min-h-6");
+  });
+});