@elabs-ai/components-data 4.0.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elabs-ai/components-data",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,6 +24,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@dnd-kit/core": "6.3.1",
+    "@dnd-kit/sortable": "10.0.0",
+    "@dnd-kit/utilities": "3.2.2",
     "@tanstack/react-table": "^8.20.6",
     "@tanstack/react-virtual": "^3.14.2",
     "lucide-react": "^0.577.0"
@@ -31,9 +34,9 @@
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
-    "@elabs-ai/components-icons": "4.0.0",
-    "@elabs-ai/components-ui": "4.0.0",
-    "@elabs-ai/components-tokens": "4.0.0"
+    "@elabs-ai/components-icons": "4.2.0",
+    "@elabs-ai/components-tokens": "4.2.0",
+    "@elabs-ai/components-ui": "4.2.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
@@ -49,10 +52,10 @@
     "typescript": "^5.7.3",
     "vitest": "^3.0.2",
     "@elabs-ai/components-eslint-config": "0.1.0",
-    "@elabs-ai/components-icons": "4.0.0",
-    "@elabs-ai/components-tokens": "4.0.0",
+    "@elabs-ai/components-icons": "4.2.0",
+    "@elabs-ai/components-tokens": "4.2.0",
     "@elabs-ai/components-typescript-config": "0.1.0",
-    "@elabs-ai/components-ui": "4.0.0"
+    "@elabs-ai/components-ui": "4.2.0"
   },
   "scripts": {
     "build": "tsup",

package/src/__contract__/filter-chip.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for FilterChip (`packages/data/src/filter-bar/filter-chip.tsx`), derived from its
+ * `Default` story (packages/data/src/filter-bar/filter-chip.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../filter-bar/filter-chip.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `data-filterbar-filterchip--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("FilterChip contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="filter-chip" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="filter-chip"]')).not.toBeNull();
+  });
+});

package/src/column-picker/column-picker.tsx

@@ -9,6 +9,7 @@ import {
   DropdownMenuLabel,
   DropdownMenuSeparator,
   DropdownMenuTrigger,
+  useLocale,
 } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 
@@ -19,19 +20,21 @@ export interface ColumnPickerProps<TData> extends ButtonHTMLAttributes<HTMLButto
 }
 
 function ColumnPickerInner<TData>(
-  { table, label = "Columns", className, ...props }: ColumnPickerProps<TData>,
+  { table, label, className, ...props }: ColumnPickerProps<TData>,
   ref: Ref<HTMLButtonElement>,
 ) {
+  const { t } = useLocale();
+  const resolvedLabel = label ?? t("data.columnPicker.label");
   const columns = table.getAllColumns().filter((c) => c.getCanHide());
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
         <Button ref={ref} variant="outline" size="sm" className={cn(className)} {...props}>
-          {label}
+          {resolvedLabel}
         </Button>
       </DropdownMenuTrigger>
       <DropdownMenuContent align="end" className="min-w-[12rem]">
-        <DropdownMenuLabel>Toggle columns</DropdownMenuLabel>
+        <DropdownMenuLabel>{t("data.columnPicker.toggleColumns")}</DropdownMenuLabel>
         <DropdownMenuSeparator />
         {columns.map((column) => (
           <DropdownMenuItem

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

@@ -8,7 +8,7 @@ import type {
   ColumnFiltersState,
   VisibilityState,
 } from "@tanstack/react-table";
-import { DataTable } from "./data-table";
+import { DataTable, createSelectionColumn } from "./data-table";
 import type { DataTableServerArgs, DataTableViewState } from "./data-table";
 import { FilterBar } from "../filter-bar";
 import { SearchInput } from "../search-input";
@@ -45,7 +45,10 @@ const columns: ColumnDef<Deployment>[] = [
       return <Badge variant={statusVariant[s]}>{s}</Badge>;
     },
   },
-  { accessorKey: "latencyMs", header: "Latency (ms)" },
+  // #69: `meta.numeric` is the component seam — the header/body/skeleton
+  // renderers apply `tabular-nums` + end-alignment for free, instead of a
+  // per-story wrapper span.
+  { accessorKey: "latencyMs", header: "Latency (ms)", meta: { numeric: true } },
 ];
 
 // `columns` minus the Badge-rendering "Status" cell — for stories below whose
@@ -66,6 +69,8 @@ const meta = {
     docs: {
       description: {
         component:
+          "The INTERACTIVE grid; static markup you lay out yourself is `Data/Table` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
           "The full data grid (TanStack Table): sorting, filtering, pagination, virtualization, row " +
           "selection and column management. For a simple static table with no interaction, the lighter " +
           "Table primitive (see Data/Table, @elabs-ai/components-ui) is enough.",
@@ -93,6 +98,21 @@ export const Lines: Story = {
   render: () => <DataTable columns={columns} data={rows} zebra={false} />,
 };
 
+// ─── Column dividers ────────────────────────────────────────────────────────
+
+/**
+ * `columnDividers` adds a quiet `--rule` hairline between columns, in the header
+ * and the body. Off by default; pinned columns keep their own seam instead.
+ */
+export const ColumnDividers: Story = {
+  render: () => <DataTable columns={columns} data={rows} zebra={false} columnDividers />,
+  play: async ({ canvasElement }) => {
+    const header = canvasElement.querySelector("thead th");
+    await expect(header).not.toBeNull();
+    await expect(getComputedStyle(header as Element).borderInlineEndWidth).toBe("1px");
+  },
+};
+
 // ─── Sorted ───────────────────────────────────────────────────────────────────
 
 export const Sorted: Story = {
@@ -186,6 +206,16 @@ export const WithToolbar: Story = {
   // matching row should survive. Proves the render-prop toolbar and table share
   // one filter state.
   play: async ({ canvas, userEvent }) => {
+    // #69 — this IS the exact "data-datatable--with-toolbar" acceptance
+    // surface the issue names: the "Latency (ms)" column's `meta.numeric`
+    // must reach the REAL rendered header + cell (computed style, not just a
+    // class-name assertion) as `text-align: end` + `tabular-nums`.
+    const latencyHeader = canvas.getByRole("columnheader", { name: "Latency (ms)" });
+    await expect(getComputedStyle(latencyHeader).textAlign).toBe("end");
+    const latencyCell = canvas.getByRole("cell", { name: "82" });
+    await expect(getComputedStyle(latencyCell).textAlign).toBe("end");
+    await expect(getComputedStyle(latencyCell).fontVariantNumeric).toContain("tabular-nums");
+
     await expect(canvas.getByText("api-gateway")).toBeVisible();
     await userEvent.type(canvas.getByPlaceholderText(/Filter services/), "billing");
     await waitFor(() => expect(canvas.queryByText("api-gateway")).toBeNull());
@@ -565,6 +595,12 @@ export const ClickableRows: Story = {
     const rowAction = canvas.getByRole("button", { name: "search" });
     rowAction.focus();
     await expect(rowAction).toHaveFocus();
+    // #311: the row paints the deliberate compound focus indicator via
+    // `has-[[data-slot=data-table-row-action]:focus-visible]:…` — the proxy
+    // button itself must suppress its OWN native ring, or it leaks as a
+    // stray dot at the row's edge. Real browser (Playwright), so this
+    // actually resolves the Tailwind cascade, unlike the jsdom unit test.
+    await expect(getComputedStyle(rowAction).outlineStyle).toBe("none");
     await userEvent.keyboard("{Enter}");
     await expect(clickableRowsOnRowClick).toHaveBeenCalledTimes(2);
     await expect(clickableRowsOnRowClick.mock.calls[1]![0].original.service).toBe("search");
@@ -802,3 +838,461 @@ export const PinnedColumnsClassicLines: Story = {
     await expect(getComputedStyle(oddPinned.closest("tr")!).borderBottomWidth).toBe("1px");
   },
 };
+
+// ─── WithColumnResizing (#12) ───────────────────────────────────────────────────
+
+/**
+ * `enableColumnResizing` adds a drag handle to the end of every resizable header
+ * cell — a WAI-ARIA separator-as-slider, operable by pointer/touch (TanStack's own
+ * `getResizeHandler()`) or keyboard (ArrowLeft/ArrowRight while the handle is
+ * focused). `columnSizing`/`onColumnSizingChange` make it a controlled slice,
+ * exactly like sorting or column pinning; omit them to let the table manage its
+ * own widths. A resized column that is ALSO pinned keeps its sticky offset in
+ * sync for free — pinning already reads `column.getSize()`.
+ */
+export const WithColumnResizing: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`enableColumnResizing` lets a reader drag — or, with the handle focused, " +
+          "arrow-key — a column's edge to change its width.",
+      },
+    },
+  },
+  render: () => <DataTable columns={columnsNoBadge} data={rows} enableColumnResizing />,
+  play: async ({ canvas, userEvent }) => {
+    const serviceHeader = canvas.getAllByRole("columnheader")[0]!;
+    await expect(serviceHeader.style.width).toBe("150px");
+
+    const handle = canvas.getByRole("separator", { name: /Resize column, Service/i });
+
+    // #51 — the focus ring moved from the hit box itself onto the `after:`
+    // drawn-seam pseudo-element (`focus-visible:after:ring-2`), so the now-24px
+    // hit box doesn't draw a 24px focus rectangle over an 8px sliver's worth of
+    // approved contrast. Measure the REAL rendered ring via computed style on
+    // the pseudo-element — not a class-name string comparison — so a later
+    // refactor can't silently drop a visible focus indicator (WCAG 2.4.7)
+    // without failing this test.
+    await expect(getComputedStyle(handle, "::after").boxShadow).toBe("none");
+    handle.focus();
+    await expect(getComputedStyle(handle, "::after").boxShadow).not.toBe("none");
+
+    await expect(handle).toHaveAttribute("aria-valuenow", "150");
+
+    await userEvent.keyboard("{ArrowRight}");
+    await expect(handle).toHaveAttribute("aria-valuenow", "160");
+    await expect(serviceHeader.style.width).toBe("160px");
+
+    await userEvent.keyboard("{ArrowLeft}");
+    await expect(handle).toHaveAttribute("aria-valuenow", "150");
+    await expect(serviceHeader.style.width).toBe("150px");
+  },
+};
+
+/**
+ * #51 — the resize handle's hit box used to be `w-2` (8px), which is on the
+ * Tailwind SPACING scale (`calc(var(--spacing) * 2)`), so it shrank further
+ * under `data-density="compact"` (`--spacing` itself is what the density dial
+ * rescales — a jsdom class assertion can't see this, only real layout can). The
+ * fix reads a literal `w-[min(24px,50%)]`, which this play function measures
+ * with `getBoundingClientRect()` UNDER compact density specifically, since
+ * that is where the old value was worst (~7.1px) and where a regression would
+ * hide from a comfortable-only check.
+ */
+export const WithColumnResizingCompactDensity: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The resize handle's interactive hit box stays ~24px wide even under " +
+          '`data-density="compact"`, which shrinks every Tailwind spacing-scale ' +
+          "utility (the old `w-2` hit box shrank right along with it).",
+      },
+    },
+  },
+  render: () => (
+    <div data-density="compact">
+      <DataTable columns={columnsNoBadge} data={rows} enableColumnResizing />
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const handle = canvas.getByRole("separator", { name: /Resize column, Service/i });
+    const rect = handle.getBoundingClientRect();
+    // A real layout pass must have happened before this means anything.
+    await expect(rect.width).toBeGreaterThan(0);
+    // `min(24px, 50%)` on a 150px column resolves to a literal 24px — assert a
+    // tight tolerance so a regression back toward the old ~7px is caught, but
+    // allow for sub-pixel rounding.
+    await expect(rect.width).toBeGreaterThan(20);
+    await expect(rect.width).toBeLessThanOrEqual(24.5);
+  },
+};
+
+/**
+ * #82 gap 1 — the double-click-reset regression locks in `data-table.test.tsx`
+ * use jsdom's `fireEvent.doubleClick`, which dispatches ONLY a synthetic
+ * `dblclick` event — never the two real `mousedown`/`mouseup` pairs a browser
+ * fires for an actual double click, which `header.getResizeHandler()` (wired
+ * to `onMouseDown` on the SAME handle) also listens for. `userEvent.dblClick`
+ * DOES synthesize the full mousedown/mouseup ×2 + dblclick sequence, and this
+ * play function runs in a real browser (Storybook test runner), so it
+ * exercises the actual event path a user's double click takes — and asserts
+ * the column lands exactly at its declared size, with no partial resize left
+ * behind by whatever `getResizeHandler()`'s pointer-drag state machine did
+ * with those two extra mousedown/mouseup pairs.
+ */
+export const WithColumnResizingRealDoubleClick: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A REAL double-click (mousedown/mouseup ×2 + dblclick, not jsdom's " +
+          "synthetic dblclick-only event) resets a resized column to its " +
+          "declared size, with no partial resize left behind by the drag path.",
+      },
+    },
+  },
+  render: () => <DataTable columns={columnsNoBadge} data={rows} enableColumnResizing />,
+  play: async ({ canvas, userEvent }) => {
+    const serviceHeader = canvas.getAllByRole("columnheader")[0]!;
+    const handle = canvas.getByRole("separator", { name: /Resize column, Service/i });
+    await expect(serviceHeader.style.width).toBe("150px");
+
+    // Move away from the declared size first (keyboard path — already proven
+    // real-pointer-equivalent by the plain WithColumnResizing story above),
+    // so the double click below has something to reset FROM.
+    handle.focus();
+    await userEvent.keyboard("{ArrowRight}{ArrowRight}");
+    await expect(serviceHeader.style.width).toBe("170px");
+
+    // The real double click — the actual mousedown/mouseup ×2 + dblclick
+    // sequence, not jsdom's dblclick-only synthetic event.
+    await userEvent.dblClick(handle);
+    await expect(handle).toHaveAttribute("aria-valuenow", "150");
+    await expect(serviceHeader.style.width).toBe("150px");
+  },
+};
+
+/**
+ * #82 gap 2 — the resize handle's `min(24px, 50%)` hit box sits over the
+ * trailing edge of the SAME header cell a sortable column's own toggle
+ * button occupies. jsdom's `fireEvent.click` dispatches straight to a target
+ * node with no real hit-testing, so the regression lock in
+ * `data-table.test.tsx` can only prove the button RESPONDS to a click
+ * addressed to it — not that a real screen click at the button's own
+ * on-screen coordinates actually resolves to the button rather than the
+ * handle. `document.elementFromPoint` is the browser's real hit-test; this
+ * play function samples it right at the sort button's own trailing edge (the
+ * side nearest the handle) and asserts it resolves inside the button, then
+ * performs the click there and asserts the sort actually toggled.
+ *
+ * Sampled on TWO columns, not one, because the collision is alignment-
+ * dependent: a `start`-aligned header's button sits at the LEADING edge,
+ * nowhere near the handle, so it can't exercise the collision at all — round
+ * 1 review (independent real-Chromium validation) caught exactly this: the
+ * original version of this story sampled only "Service" (start-aligned,
+ * button ends 293px clear of the handle) and passed trivially, while
+ * "Latency (ms)" — numeric, so `meta.numeric` end-aligns it (#69) — pushes
+ * the SAME button's trailing edge 12px UNDER the handle's 24px hit box. The
+ * "Service" case is kept because a real regression here (e.g. the handle
+ * growing) should still be caught on the unproblematic column too.
+ */
+export const WithColumnResizingSortToggleHitTest: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The header's sort-toggle button stays hit-testable at its own " +
+          "coordinates when the column is ALSO resizable, i.e. when the " +
+          "24px resize handle is present on the same header cell — for both " +
+          "a start-aligned header and an end-aligned numeric one.",
+      },
+    },
+  },
+  render: () => <DataTable columns={columnsNoBadge} data={rows} enableColumnResizing />,
+  play: async ({ canvas, userEvent }) => {
+    async function assertSortButtonHitTestable(
+      accessibleName: string,
+      columnHeaderIndex: number,
+      // TanStack defaults a NUMBER-typed column to descending-first (largest
+      // first reads more useful than smallest-first for e.g. latency) — this
+      // is TanStack's own default heuristic, not something this story
+      // asserts against; the string-typed "Service" column defaults
+      // ascending-first as usual.
+      firstClickSortDirection: "ascending" | "descending",
+    ) {
+      const sortButton = canvas.getByRole("button", { name: accessibleName });
+      const rect = sortButton.getBoundingClientRect();
+      // A real layout pass must have happened before this means anything.
+      await expect(rect.width).toBeGreaterThan(0);
+
+      // The browser's REAL hit-test, sampled 2px inside the button's own
+      // trailing edge — the side nearest the resize handle — so the sample
+      // point can't land outside the button from sub-pixel rounding.
+      const x = rect.right - 2;
+      const y = rect.top + rect.height / 2;
+      const hit = document.elementFromPoint(x, y);
+      await expect(hit).not.toBeNull();
+      await expect(sortButton.contains(hit)).toBe(true);
+
+      const columnHeader = canvas.getAllByRole("columnheader")[columnHeaderIndex]!;
+      await expect(columnHeader).toHaveAttribute("aria-sort", "none");
+      await userEvent.click(hit!);
+      await expect(columnHeader).toHaveAttribute("aria-sort", firstClickSortDirection);
+    }
+
+    // Start-aligned — the button sits far from the handle; kept as the
+    // "nothing regressed on the easy case" control.
+    await assertSortButtonHitTestable("Sort by Service, not sorted", 0, "ascending");
+    // End-aligned numeric — the actual collision surface (#69's `meta.numeric`
+    // pushes this button's trailing edge under the resize handle).
+    await assertSortButtonHitTestable("Sort by Latency (ms), not sorted", 2, "descending");
+  },
+};
+
+// ─── Row selection (#11) ───────────────────────────────────────────────────────
+
+const selectableColumns: ColumnDef<Deployment>[] = [
+  createSelectionColumn<Deployment>(),
+  ...columnsNoBadge,
+];
+
+/**
+ * `createSelectionColumn()` drops a ready-made checkbox column onto any table:
+ * a header select-all (real `indeterminate` for a partial page selection) plus
+ * a per-row checkbox. Uncontrolled here — the table owns `rowSelection`
+ * internally; pass `rowSelection`/`onRowSelectionChange` to drive it from the
+ * app instead.
+ */
+export const RowSelectionUnselected: Story = {
+  render: () => <DataTable columns={selectableColumns} data={rows} />,
+  play: async ({ canvas }) => {
+    const selectAll = canvas.getAllByRole("checkbox")[0]!;
+    await expect(selectAll).toHaveAttribute("aria-checked", "false");
+  },
+};
+
+/** A controlled, partial selection: the header checkbox reads `indeterminate`. */
+export const RowSelectionPartial: Story = {
+  render: () => (
+    <DataTable
+      columns={selectableColumns}
+      data={rows}
+      rowSelection={{ "0": true, "2": true }}
+      onRowSelectionChange={fn()}
+    />
+  ),
+  play: async ({ canvas }) => {
+    const selectAll = canvas.getAllByRole("checkbox")[0]!;
+    await expect(selectAll).toHaveAttribute("aria-checked", "mixed");
+  },
+};
+
+/** A controlled, full-page selection: the header checkbox reads `checked`. */
+export const RowSelectionAllSelected: Story = {
+  render: () => (
+    <DataTable
+      columns={selectableColumns}
+      data={rows}
+      rowSelection={Object.fromEntries(rows.map((_, i) => [String(i), true]))}
+      onRowSelectionChange={fn()}
+    />
+  ),
+  play: async ({ canvas }) => {
+    const selectAll = canvas.getAllByRole("checkbox")[0]!;
+    await expect(selectAll).toHaveAttribute("aria-checked", "true");
+  },
+};
+
+/**
+ * A bulk-action toolbar is not a separate prop — `toolbar={(table) => …}`
+ * already hands the live table instance to the render-prop, so a consumer
+ * builds "N selected · Clear" from `table.getSelectedRowModel()` the same way
+ * `WithToolbar` builds a filter bar from the same instance.
+ */
+export const RowSelectionWithToolbar: Story = {
+  render: () => (
+    <DataTable
+      columns={selectableColumns}
+      data={rows}
+      toolbar={(table) => {
+        const selectedCount = table.getSelectedRowModel().rows.length;
+        if (selectedCount === 0) return null;
+        return (
+          <FilterBar
+            actions={
+              <Button
+                type="button"
+                size="sm"
+                variant="outline"
+                onClick={() => table.resetRowSelection()}
+              >
+                Clear selection
+              </Button>
+            }
+          >
+            <span className="text-body">{selectedCount} selected</span>
+          </FilterBar>
+        );
+      }}
+    />
+  ),
+  play: async ({ canvas, userEvent }) => {
+    await expect(canvas.queryByText(/selected$/)).toBeNull();
+    const rowCheckboxes = canvas.getAllByRole("checkbox").slice(1);
+    await userEvent.click(rowCheckboxes[0]!);
+    await userEvent.click(rowCheckboxes[1]!);
+    await expect(canvas.getByText("2 selected")).toBeVisible();
+    await userEvent.click(canvas.getByText("Clear selection"));
+    await expect(canvas.queryByText(/selected$/)).toBeNull();
+  },
+};
+
+/**
+ * Dark-theme pass for the same interaction + a11y coverage (#11 fix round —
+ * the light-only Storybook run isn't sufficient for the "both shipping
+ * themes" quality gate). Reuses `RowSelectionWithToolbar`'s render/play under
+ * `globals: { theme: "dark" }`, same pattern as `dialog.stories.tsx`'s
+ * `FocusRingClearanceDark`.
+ */
+export const RowSelectionWithToolbarDark: Story = {
+  name: "Row selection — with toolbar (dark)",
+  globals: { theme: "dark" },
+  render: RowSelectionWithToolbar.render,
+  play: async (context) => {
+    await waitFor(() => expect(document.documentElement.getAttribute("data-theme")).toBe("dark"));
+    await RowSelectionWithToolbar.play!(context);
+  },
+};
+
+// ─── RowReorder (#13) ───────────────────────────────────────────────────────
+
+/**
+ * Opt-in row drag-reorder. Fully controlled, like every other DataTable slice:
+ * `onRowReorder` reports the move as `(from, to, row)` and this story
+ * re-orders its own `data` in response — the component never mutates `data`
+ * itself.
+ *
+ * Try both ways to move a row: drag the grip handle with a mouse, or Tab to
+ * it and use the keyboard — Space/Enter picks a row up, Arrow Up/Down moves
+ * it, Space/Enter drops it, Escape cancels. Every position change is
+ * announced through a live region (WCAG 4.1.3).
+ */
+export const RowReorder: Story = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [items, setItems] = useState(rows);
+    return (
+      <DataTable
+        columns={columnsNoBadge}
+        data={items}
+        enableRowReorder
+        onRowReorder={(from, to) => {
+          setItems((current) => {
+            const next = current.slice();
+            const [moved] = next.splice(from, 1);
+            next.splice(to, 0, moved!);
+            return next;
+          });
+        }}
+      />
+    );
+  },
+  play: async ({ canvas, userEvent }) => {
+    // Keyboard flow — the mandatory path (issue #13 carries the
+    // `accessibility` label): pick up the first row ("api-gateway"), move it
+    // down one position, and drop.
+    const handle = canvas.getByRole("button", { name: "Reorder api-gateway" });
+    handle.focus();
+    await expect(handle).toHaveFocus();
+
+    await userEvent.keyboard(" ");
+    await expect(handle).toHaveAttribute("aria-pressed", "true");
+
+    // `KeyboardSensor.attach()` (`@dnd-kit/core`) defers attaching the
+    // listener for the subsequent move/drop keys by one real macrotask
+    // (`setTimeout(fn, 0)`) — the same tick the unit tests in
+    // `data-table.test.tsx` wait out.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    await userEvent.keyboard("{ArrowDown}");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    await userEvent.keyboard(" ");
+
+    await waitFor(() => {
+      const gripButtons = canvas.getAllByRole("button", { name: /^Reorder /i });
+      expect(gripButtons[0]).toHaveAccessibleName("Reorder billing");
+      expect(gripButtons[1]).toHaveAccessibleName("Reorder api-gateway");
+    });
+  },
+};
+
+/**
+ * `rowReorderHandle="row"` makes the whole row the drag activator — no extra
+ * grip column. Reach for this only when the row has no other primary
+ * interaction (no `onRowClick`), since the row itself and a click target
+ * would otherwise compete for the same surface.
+ */
+export const RowReorderWholeRow: Story = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [items, setItems] = useState(rows);
+    return (
+      <DataTable
+        columns={columnsNoBadge}
+        data={items}
+        enableRowReorder
+        rowReorderHandle="row"
+        onRowReorder={(from, to) => {
+          setItems((current) => {
+            const next = current.slice();
+            const [moved] = next.splice(from, 1);
+            next.splice(to, 0, moved!);
+            return next;
+          });
+        }}
+      />
+    );
+  },
+  play: async ({ canvas, userEvent }) => {
+    // Pointer drag — the other half of acceptance criterion "Pointer drag
+    // works (via @dnd-kit/sortable sensor)". This can only be verified in a
+    // REAL browser: `data-table.test.tsx` documents that jsdom has no
+    // `PointerEvent` constructor at all, so `PointerSensor`'s own activator
+    // gate rejects every synthetic pointerdown there regardless of test
+    // code. Storybook's interaction-test runner drives real Chromium, which
+    // has a genuine `PointerEvent`.
+    // Drags the whole first row ("api-gateway") past the second row
+    // ("billing") and drops.
+    const firstRow = canvas.getByText("api-gateway").closest("tr") as HTMLElement;
+    const secondRow = canvas.getByText("billing").closest("tr") as HTMLElement;
+    const from = firstRow.getBoundingClientRect();
+    const to = secondRow.getBoundingClientRect();
+    const startX = from.left + 20;
+    const startY = from.top + from.height / 2;
+
+    // `reorderSensors`'s `PointerSensor` uses `activationConstraint: { distance: 4 }`
+    // (data-table.tsx): dnd-kit's own `handleMove` treats the FIRST move past that
+    // threshold as arming the drag only — it calls `handleStart()` (recording the
+    // *initial* pointer-down position) and returns WITHOUT ever calling `onMove`, so
+    // that event never updates the tracked drag position. A single big pointer jump
+    // straight from the row to the drop target therefore "activates" the drag but
+    // reports no movement at all, and the row lands back where it started. A SECOND
+    // move — after activation — is required to actually report the target position,
+    // so the sequence below moves twice: once just past the 4px threshold, then once
+    // more to the real drop point.
+    await userEvent.pointer([
+      { keys: "[MouseLeft>]", target: firstRow, coords: { clientX: startX, clientY: startY } },
+      { coords: { clientX: startX, clientY: startY + 10 } },
+      { coords: { clientX: to.left + 20, clientY: to.bottom - 4 } },
+      { keys: "[/MouseLeft]" },
+    ]);
+
+    await waitFor(() => {
+      const cells = canvas.getAllByRole("cell");
+      expect(cells[0]).toHaveTextContent("billing");
+    });
+  },
+};