cursedbelt 0.0.0 → 2.3.0

package/src/react/components/DataTable/DataTable.tsx

@@ -0,0 +1,1506 @@
+import {
+  type ColumnDef,
+  type ColumnFiltersState,
+  flexRender,
+  getCoreRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  type OnChangeFn,
+  type PaginationState,
+  type Row,
+  type RowData,
+  type SortingState,
+  useReactTable,
+  type VisibilityState,
+} from '@tanstack/react-table';
+import type { CSSProperties, DragEvent, Dispatch, ReactNode, SetStateAction } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useScrollEdgeFade } from '../../hooks/useScrollEdgeFade';
+import { cn } from '../../lib/cn';
+import { CardTapTarget } from '../CardTapTarget';
+import type { DropdownMenuItem } from '../DropdownMenu';
+import { EmptyState } from '../EmptyState';
+import { Skeleton } from '../Skeleton';
+import { Surface } from '../Surface';
+import { CardView } from './CardView';
+import { CellRenderer } from './cells/CellRenderer';
+import {
+  EMPTY_FILTER_QUERY,
+  evaluateFilterQuery,
+  filterableText,
+  type FilterQuery,
+} from './filterQuery';
+import { TablePagination } from './Pagination';
+import { RowActions } from './RowActions';
+import { type RowDragPayload, writeRowDrag } from './rowDrag';
+import { SortHeader } from './SortHeader';
+import { TableToolbar } from './Toolbar';
+import type { ColDef, TableViewMode } from './types';
+import { resolveColumnAlign } from './types';
+
+// TanStack's header is a render fn (we build a sortable button), so its column has no
+// string header for the ViewOptionsMenu to label a toggle with. Carry the label on
+// `meta` instead — augmenting the base interface so it's typed everywhere.
+declare module '@tanstack/react-table' {
+  interface ColumnMeta<TData extends RowData, TValue> {
+    label?: string;
+    align?: 'left' | 'right';
+    /** ColDef.width verbatim (px number or CSS string, e.g. `'15%'`) — TanStack's
+     *  own `size` is number-only, so proportional tracks ride meta instead. */
+    width?: number | string;
+    minWidth?: number;
+  }
+  interface TableMeta<TData extends RowData> {
+    /** {@link DataTableControls} — see its doc for why it rides on the table. */
+    cbControls?: DataTableControls;
+  }
+}
+
+export type { ColDef } from './types';
+
+/**
+ * The search box's state: the text AND the columns it covers.
+ *
+ * 🔴 They travel together as ONE value because that is the only place TanStack
+ * will notice the scope changing. `getFilteredRowModel` memoizes on exactly
+ * `[preFilteredRowModel, columnFilters, globalFilter]` — the column definitions
+ * are NOT in that list, so expressing the scope as each column's
+ * `enableGlobalFilter` produced a control that moved and results that did not:
+ * you narrow the search to Title, the menu ticks Title, and the table keeps
+ * showing artist matches until something unrelated happens to invalidate the
+ * model. Measured while building this (`tableSystem.spec.tsx`, "narrowing the
+ * scope changes what a search matches"). Putting the scope in the filter VALUE
+ * makes the invalidation structural rather than something to remember.
+ *
+ * `scope: null` is every column — see `SearchBox` for why it stays null.
+ */
+export interface TableSearchState {
+  text: string;
+  scope: string[] | null;
+}
+
+/**
+ * Everything the toolbar needs that TanStack itself does not model: the filter
+ * QUERY (item 3), the use-time search SCOPE (item 6), the sort STACK as a
+ * dismissable list (item 1), and the rows ⇄ cards choice (item 4).
+ *
+ * 🔴 It rides on the table instance's `meta` rather than being passed as props,
+ * and that is what makes the new capabilities reach the tables that already
+ * exist. Dozens of callers across ~17 consumer repos render
+ * `toolbar={(table) => <TableToolbar table={table} onAdd={…} />}`; if the search
+ * scope and the filter builder were extra props on `TableToolbar`, every one of
+ * those call sites would have to be edited before the owner could search a
+ * subset of columns anywhere — which is the same "one app gets it, the next does
+ * not" divergence this unit exists to end. Hanging the state off the table means
+ * the caller keeps composing its own toolbar and gets the controls anyway.
+ */
+export interface DataTableControls {
+  /** The live search text — read this, not `table.getState().globalFilter`,
+   *  which now carries {@link TableSearchState} rather than a bare string. */
+  searchText: string;
+  setSearchText: (text: string) => void;
+  filterQuery: FilterQuery;
+  setFilterQuery: (next: FilterQuery) => void;
+  /** Columns the builder may filter on. */
+  filterColumns: { key: string; label: string }[];
+  searchScope: string[] | null;
+  setSearchScope: (next: string[] | null) => void;
+  /** Columns the search box MAY cover — `ColDef.filterable` decided this. */
+  searchColumns: { key: string; label: string }[];
+  sorting: SortingState;
+  clearSorting: () => void;
+  removeSortKey: (id: string) => void;
+  toggleSortDirection: (id: string) => void;
+  labelOf: (id: string) => string;
+  viewMode?: TableViewMode;
+  setViewMode?: (mode: TableViewMode) => void;
+}
+
+export interface DataTableProps<TRow extends Record<string, unknown>> {
+  columns: ColDef<TRow>[];
+  data: TRow[];
+  /** Stable row id (selection/keys). Falls back to the row index. */
+  getRowId?: (row: TRow) => string;
+  /** Click a row — typically opens the record `Drawer`. */
+  onRowClick?: (row: TRow) => void;
+  /** Trailing per-row Edit action (renders the actions column). */
+  onRowEdit?: (row: TRow) => void;
+  /** Trailing per-row Delete action (renders the actions column). */
+  onRowDelete?: (row: TRow) => void;
+  /** Extra per-row operations behind a trailing kebab (`⋯`) menu — return the items for
+   *  one row (empty array ⇒ no kebab on that row). Renders the actions column. */
+  rowMenu?: (row: TRow) => DropdownMenuItem[];
+  loading?: boolean;
+  /** Shown when there are no rows (default: a plain "No results"). */
+  emptyState?: ReactNode;
+  /** A toolbar; the function form receives the live table instance (recommended, since
+   *  the table is created inside this component — see {@link TableToolbar}). */
+  toolbar?: ReactNode | ((table: ReturnType<typeof useReactTable<TRow>>) => ReactNode);
+  pageSize?: number;
+  /** Offer a rows-per-page selector in the pager. */
+  pageSizeOptions?: number[];
+  /** Hide the built-in pager (e.g. a short list that always fits one page). */
+  hidePagination?: boolean;
+  /** Accessible `<caption>` (visually hidden) describing the table. */
+  caption?: string;
+  className?: string;
+
+  /** Keep the header row pinned while the table's scroll container scrolls (deep
+   *  lists must never strand the reader without column context — STANDARDS §5c).
+   *  Works inside any vertical scroll ancestor (`ScrollArea`). */
+  stickyHeader?: boolean;
+  /**
+   * Freeze the FIRST visible column so it stays on screen while the rest of the
+   * table scrolls sideways (owner, 2026-08-15, on auth's people matrix: *"if the
+   * table still requires horizontal scrolling to see the final columns the first
+   * column should be frozen so I can see it while I look at the final columns.
+   * Otherwise I just see the words like 'Allowed' on a bunch of rows and cannot
+   * associate each with a user"*).
+   *
+   * 🔴 The frozen cell paints an OPAQUE background computed from the row's own
+   * zebra step, not a Tailwind class. A `bg-muted/50` zebra is semi-transparent,
+   * and a semi-transparent sticky cell shows the columns sliding underneath it —
+   * which reads as a rendering fault rather than as a frozen column.
+   */
+  stickyFirstColumn?: boolean;
+  /**
+   * Full-width accordion detail panel: when a row's id equals `expandedRowId`, this
+   * renders directly UNDER that row, spanning every column (`colspan`), so the table
+   * grid above stays intact — never swap a row's cells for detail content. Controlled:
+   * the app owns which row is open (typically toggled from `onRowClick` or a name cell).
+   */
+  renderExpanded?: (row: TRow) => ReactNode;
+  /** Id (per `getRowId`) of the single expanded row, or `null` for none. */
+  expandedRowId?: string | null;
+  /** Extra classes for a body row (e.g. tint nested child rows so hierarchy reads
+   *  as a block, not just an indent). Applied to the grid `<tr>` AND the phone card. */
+  rowClassName?: (row: TRow) => string | undefined;
+  /**
+   * Drop columns whose value is empty (`null`/`''`/`[]`) in EVERY row — a column of
+   * `—` placeholders is dead horizontal space that squeezes the columns carrying real
+   * data. Off by default (an always-visible column can be a deliberate affordance).
+   */
+  hideEmptyColumns?: boolean;
+  /**
+   * Lock the wide-tier grid to rigid column tracks (`table-layout: fixed`): every
+   * `ColDef.width` is honored exactly and one width-less column (typically the
+   * title) absorbs the remainder — the CSS-grid `[1fr 110px 90px …]` discipline,
+   * as a table. Auto layout lets content nudge column widths, which reads as
+   * header/row track drift under an adversarial eye (owner final judgments part 2,
+   * 2026-07-15). Off by default: content-sized columns are right for tables whose
+   * cells vary wildly and that never claimed fixed lanes.
+   */
+  fixedLayout?: boolean;
+  /**
+   * EXTRA freeze floor for the wide grid (px): below this the columns stop
+   * compressing and the wrapper scrolls horizontally instead — the design
+   * manual's 832px boundary-freeze rule (grid-layout/minimum-pixel-floors).
+   *
+   * Rarely needed. Under `fixedLayout` the table already derives its own floor
+   * from the tracks the columns declare (see {@link declaredTrackFloor}), so
+   * this is only for pushing the freeze point HIGHER than the sum of the
+   * tracks — e.g. a table of width-less columns that still wants a minimum
+   * canvas. A value BELOW the declared sum is ignored rather than obeyed: it
+   * used to be the thing that crushed the columns.
+   */
+  minTableWidth?: number;
+  /**
+   * Make the table body its OWN scroll container (both axes) instead of relying
+   * on an ancestor ScrollArea. This is what makes `stickyHeader` actually stick:
+   * a `position: sticky` header pins to its nearest scroll container, and the
+   * wide tier's horizontal-scroll wrapper becomes that container — if vertical
+   * scrolling lives on an ancestor instead, the header silently never pins.
+   * Pair with a height-bounded parent (the table claims `flex-1 min-h-0`).
+   */
+  scrollBody?: boolean;
+  /**
+   * Render only the rows on screen, inside a spacer sized from the whole result set.
+   *
+   * ── Why this exists (owner, 2026-08-25) ───────────────────────────────────
+   * *"use a cb table for tracklists so I can filter columns and sort"* — asked of
+   * apps/music, whose library is 5,409 rows. Until now the answer had to be no: this
+   * table PAGINATES, so a list that scrolls continuously could not use it, and music
+   * kept a bespoke windowed list carrying four separate owner bug reports in its own
+   * arithmetic. Every app in that position wrote its own; this is the shared answer.
+   *
+   * 🔴 It IMPLIES `scrollBody`. A virtualizer measures a scroll container, and if
+   * vertical scrolling lives on an ancestor instead it measures a box that never
+   * scrolls — the window stays at row 0 for ever while the page scrolls past it. The
+   * component turns `scrollBody` on rather than warning, because the failure is silent
+   * and looks like "virtualization does not work".
+   *
+   * 🔴 It also turns PAGINATION off. A page control over a virtual window is two
+   * different answers to "where am I", and the scrollbar is the honest one.
+   *
+   * Rows are MEASURED, not assumed: `estimateSize` seeds the spacer and each rendered
+   * row reports its real height back, so a wrapping cell, a `renderExpanded` panel and
+   * the `compact` density all work without the caller computing anything. Pass a number
+   * to seed a better first estimate for an unusual row height.
+   */
+  virtualize?: boolean | { estimateRowHeight?: number; overscan?: number };
+  /**
+   * Adaptive narrow layouts (container-query based, not viewport — a table inside
+   * a narrow split pane or a tablet's sidebar-flanked content area adapts too):
+   *
+   *   container < 36rem  → stacked cards (title zone, labeled value pairs,
+   *                        actions footer) — a phone never gets a clipped grid.
+   *   36rem – 48rem      → a compact LIST: one divided panel, title + path left,
+   *                        the remaining values inline right (no repeated
+   *                        uppercase labels, no card-per-row inflation — owner
+   *                        tablet teardown 2026-07-15).
+   *   ≥ 48rem            → the full data grid.
+   *
+   * Default `true`; pass `false` only for tables that are genuinely narrow
+   * enough to fit anywhere.
+   */
+  mobileCards?: boolean;
+
+  /** Server-driven sort/filter/pagination: the table renders `data` verbatim and reports
+   *  state changes up via the callbacks; supply `pageCount`/`rowCount` for the pager. */
+  serverSide?: boolean;
+  pageCount?: number;
+  rowCount?: number;
+  onSortingChange?: (sorting: SortingState) => void;
+  onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
+  onGlobalFilterChange?: (value: string) => void;
+  onPaginationChange?: (pagination: PaginationState) => void;
+  /** Initial sort applied before any user interaction (e.g. `[{ id: 'updatedAt', desc: true }]`).
+   *  Only seeds the initial state — click-to-sort still fully controls `sorting` afterward. */
+  defaultSort?: SortingState;
+  /**
+   * Wide-grid row density (design manual, grid-layout/ — "high-density data tables
+   * over empty visual widgets"):
+   *   `'comfortable'` (default) — the established ~44px rows (`py-2.5`); every
+   *     existing table stays pixel-stable.
+   *   `'compact'` — denser ~36px rows (`py-1.5`) for scan-heavy operational grids
+   *     that trade breathing room for more rows on screen.
+   * Affects only the ≥48rem data-grid tier; the stacked-card / compact-list tiers
+   * keep their own thumb-friendly spacing.
+   */
+  density?: 'comfortable' | 'compact';
+
+  /**
+   * Which of the two VIEWS this table is showing — the rows-and-columns grid,
+   * or the same data as a card grid ({@link CardView}).
+   *
+   * 🔴 It lives here, in the table, rather than in each app, because the owner
+   * asked for it everywhere at once (2026-08-23): *"The tables can have a
+   * switcher from table view to other view like roms app has where I can see
+   * the roms list as a compact table or as a set of cards for each entry."* A
+   * per-app switcher is the shape that produces the divergence he keeps
+   * reporting — one app grows a good version, the next re-implements a worse
+   * one, and a fix to either helps nobody else.
+   *
+   * Controlled: the caller owns the value, so the choice can be persisted
+   * wherever that app already persists view state. **Do not add a second
+   * memory for it inside this component** — unit `45-cursedbelt-tables` wires
+   * it to the existing per-account `deep-link` resume, which is what makes the
+   * choice survive a different device. Uncontrolled (`undefined`) keeps the
+   * grid, exactly as before.
+   *
+   * The card tier is the SAME data, columns and cell renderers the grid uses —
+   * so a filter, a sort, a page and a hidden column all carry across the
+   * switch. That is the property a bolted-on card list in an app never has.
+   *
+   * The CONTROL that flips it is {@link TableViewToggle}, which the caller puts
+   * in the toolbar's `extraActions`. Two pieces rather than one because the
+   * toolbar is the caller's to compose — `DataTable` never renders a toolbar it
+   * was not given, and it is not about to start for one button.
+   */
+  viewMode?: TableViewMode;
+  /**
+   * Notified when the built-in toolbar's rows ⇄ cards toggle is used. Passing it
+   * is what makes {@link TableViewToggle} appear without composing a toolbar —
+   * pair it with `useTableViewMode` and the choice survives a reload and a
+   * different device, through the existing per-account `deep-link` resume.
+   */
+  onViewModeChange?: (mode: TableViewMode) => void;
+  /** Minimum card width before the card grid reflows. */
+  cardMinWidth?: string;
+
+  /**
+   * 🔴 A cursedbelt table has a SEARCH BOX by default. Pass `false` to opt out.
+   *
+   * The owner, 2026-08-23: *"I should be able to search as an additional way to
+   * filter … similar to how I can search for music app tracks with a search bar
+   * except it will apply to cb tables."* `TableToolbar`'s `enableSearch` has
+   * defaulted true for a long time, and it was never the thing that decided —
+   * almost nothing passed a `toolbar` at all, so almost nothing had a search
+   * box. Present-by-default means the DEFAULT TOOLBAR renders when the caller
+   * gave none, which is the only form of "by default" that reaches the tables
+   * he already has in front of him.
+   *
+   * A caller that DOES pass `toolbar` owns that line: the default is not added
+   * on top (two search boxes is the one outcome the unit rules out), and
+   * `TableToolbar` renders the same controls from {@link DataTableControls}.
+   */
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  /**
+   * Multi-column sort: each header click puts that column at the FRONT of the
+   * stack and keeps the previous keys behind it as tie-breakers, so the owner's
+   * example works exactly as written — *"I sort by date created, then sort by
+   * artist and I get a list ordered by artist with their tracks still sorted by
+   * date created."* Clicking a column already in the stack cycles it
+   * ascending → descending → out, without disturbing the others.
+   *
+   * Default `true`. `false` restores the old one-key-at-a-time behaviour.
+   */
+  multiSort?: boolean;
+  /**
+   * The filter builder's query, controlled. Omit and the table owns it
+   * internally (which is what every caller wants — the builder is a view
+   * control, not app state). Under `serverSide` the table never applies it
+   * itself; it only reports it here.
+   */
+  filterQuery?: FilterQuery;
+  onFilterQueryChange?: (next: FilterQuery) => void;
+
+  /**
+   * Make each row a DRAG SOURCE for a drop target OUTSIDE the table — the
+   * owner's folder rail. Return the payload for one row, or `null` for a row
+   * that may not be dragged.
+   *
+   * The protocol is `rowDrag.ts`, and `FilterRail`'s own drop targets speak it:
+   * `...rowDropTargetProps((payload) => …)` on a rail item is the whole
+   * consumer side. Applies to every tier — the grid row, the tablet list row,
+   * the phone card and the card view — because a table that can only be dragged
+   * from at one width is a feature that disappears on the device you would use
+   * it on.
+   */
+  getRowDrag?: (row: TRow) => RowDragPayload | null;
+  /** Identifies this table in the drag payload, so a target can refuse rows
+   *  from a table it does not serve. */
+  dragSourceId?: string;
+}
+
+/** Build an OnChangeFn that updates local state AND notifies an optional listener. */
+function chainUpdater<T>(
+  set: Dispatch<SetStateAction<T>>,
+  notify?: (next: T) => void,
+): OnChangeFn<T> {
+  return (updater) =>
+    set((prev) => {
+      const next = typeof updater === 'function' ? (updater as (p: T) => T)(prev) : (updater as T);
+      notify?.(next);
+      return next;
+    });
+}
+
+/** Like {@link chainUpdater}, but also snaps pagination back to page 1 — for the
+ *  filter/sort setters, where landing on a page that no longer exists (or that no
+ *  longer matches the new criteria) would strand the reader. */
+function chainUpdaterResettingPage<T>(
+  set: Dispatch<SetStateAction<T>>,
+  setPagination: Dispatch<SetStateAction<PaginationState>>,
+  notify?: (next: T) => void,
+): OnChangeFn<T> {
+  return (updater) =>
+    set((prev) => {
+      const next = typeof updater === 'function' ? (updater as (p: T) => T)(prev) : (updater as T);
+      setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
+      notify?.(next);
+      return next;
+    });
+}
+
+/**
+ * Px floor for a width-less column under `fixedLayout`. `table-layout: fixed`
+ * divides the leftover canvas between such columns, and the leftover can be
+ * zero — this is the share below which the division stops and the table
+ * overflows its wrapper instead.
+ */
+export const AUTO_TRACK_FLOOR_PX = 120;
+/** The trailing row-actions column is a fixed `w-20`. */
+const ACTIONS_TRACK_PX = 80;
+
+/**
+ * The narrowest width at which a `fixedLayout` table still honors the tracks its
+ * columns declared: the sum of every visible column's floor (`minWidth`, else a
+ * numeric `width`, else {@link AUTO_TRACK_FLOOR_PX}).
+ *
+ * 🔴 Why this is derived and not a prop the caller maintains, and what actually
+ * breaks without it. `table-layout: fixed` does NOT clamp at the declared
+ * widths, and `min-width` on a `<th>` is advisory in that algorithm — so the
+ * only thing bounding the canvas is the table's own `min-width`.
+ *
+ * 🔴 MEASURED IN CHROMIUM, 2026-08-14 (this comment used to say the browser
+ * "scales every track down proportionally", which is NOT what it does, and the
+ * difference is the whole failure mode). A fixed-layout table's used width is at
+ * least the SUM of its EXPLICITLY-declared column widths: those tracks survive
+ * and the table simply overflows its wrapper. What collapses is the WIDTH-LESS
+ * column — it is handed whatever is left over, and once the explicit widths
+ * alone exceed the canvas the leftover is ZERO. Its header text then paints on
+ * top of the next header's and its cell content over the next cell's: the column
+ * is gone but nothing clipped, so the table reads as a rendering bug rather than
+ * a sizing one. That is exactly orch's fleet table on 2026-08-11 (11 columns,
+ * ~1450px of tracks, `minTableWidth={880}`) — ten sized columns intact and the
+ * task column crushed to nothing.
+ *
+ * So the load-bearing term below is {@link AUTO_TRACK_FLOOR_PX} / `minWidth` for
+ * a width-less column: it is the part Chromium's own floor does not count, and
+ * therefore the part that has to be counted here. `minTableWidth` was the guard,
+ * but as a hand-kept number it had to be re-derived every time a column was
+ * added. The sum is a fact about the columns, so the table computes it.
+ *
+ * A percentage/CSS-string `width` contributes only its `minWidth` (or the auto
+ * floor): a share of the canvas cannot bound the canvas.
+ *
+ * 🔴 This is now GATED IN A BROWSER, not just asserted here: `e2e/table-layout.spec.ts`
+ * mounts an 11-column fixture at 1440/1180/1024 and fails on any cell ink that
+ * escapes its own track or any clipped header label. Mutating this function to
+ * drop the width-less column's contribution turns that gate red at all three
+ * widths — verified 2026-08-14. happy-dom computes no layout, so no `bun test`
+ * spec here can see it.
+ */
+export function declaredTrackFloor(
+  columns: readonly { width?: number | string; minWidth?: number }[],
+  hasActions = false,
+): number {
+  const columnsTotal = columns.reduce((sum, col) => {
+    if (col.minWidth != null) return sum + col.minWidth;
+    if (typeof col.width === 'number') return sum + col.width;
+    return sum + AUTO_TRACK_FLOOR_PX;
+  }, 0);
+  return columnsTotal + (hasActions ? ACTIONS_TRACK_PX : 0);
+}
+
+/**
+ * What one header click does to the sort STACK.
+ *
+ * 🔴 The new key goes to the FRONT, and that is the whole feature. The owner
+ * described the behaviour by its result — *"I sort by date created, then sort by
+ * artist and I get a list ordered by artist with their tracks still sorted by
+ * date created"* — which is a stack in click order where the LATEST click is the
+ * primary key and everything clicked before it survives as a tie-breaker.
+ * TanStack's own multi-sort appends instead (the first key stays primary and
+ * the new one becomes the tie-break), which produces the opposite list and needs
+ * a shift-click nobody discovers. So the stack is computed here.
+ *
+ * A column already in the stack cycles ascending → descending → out, in place:
+ * flipping a tie-breaker's direction must not promote it over the key above it,
+ * and a third click has to be able to remove a key or the stack is a one-way
+ * accumulator.
+ *
+ * Stability comes for free and is not an accident: `Array.prototype.sort` has
+ * been required to be stable since ES2019 and TanStack's sorted row model uses
+ * it, so rows that tie on every key in the stack keep the order they arrived in.
+ */
+export function nextSortStack(
+  current: SortingState,
+  id: string,
+  multi: boolean,
+): SortingState {
+  const existing = current.find((sort) => sort.id === id);
+  if (!existing) {
+    const ascending = { id, desc: false };
+    return multi ? [ascending, ...current] : [ascending];
+  }
+  if (!existing.desc) {
+    const flipped = current.map((sort) => (sort.id === id ? { id, desc: true } : sort));
+    return multi ? flipped : [{ id, desc: true }];
+  }
+  return multi ? current.filter((sort) => sort.id !== id) : [];
+}
+
+/**
+ * Read a `ColDef.key` off a row, honouring the dot-notation `ColDef` documents.
+ * TanStack's own `accessorKey` does this for the cells; the filter builder runs
+ * BEFORE TanStack (see `filteredData`) and so needs the same reading, or a
+ * nested column would filter on `undefined` and match nothing.
+ */
+function readPath(row: unknown, key: string): unknown {
+  if (!key.includes('.')) return (row as Record<string, unknown>)?.[key];
+  return key.split('.').reduce<unknown>((value, part) => {
+    if (value == null || typeof value !== 'object') return undefined;
+    return (value as Record<string, unknown>)[part];
+  }, row);
+}
+
+/** True when a cell value carries nothing worth a column: null/undefined/''/[]. */
+function isEmptyCellValue(v: unknown): boolean {
+  if (v == null) return true;
+  if (typeof v === 'string') return v.trim() === '';
+  if (Array.isArray(v)) return v.length === 0;
+  return false;
+}
+
+/**
+ * The one data-table primitive — a headless TanStack Table v8 instance with our markup.
+ * Sorting, global filtering, column visibility, and pagination all live in TanStack
+ * state; cells dispatch through the {@link CellRenderer} registry (so rich types render
+ * everywhere). Dynamic/user-defined columns are first-class: pass a runtime `ColDef[]`.
+ * A record create/edit flow is a `Drawer` (task 10) opened from `onRowClick`/toolbar add.
+ *
+ * Commercial-grade defaults (owner mandate 2026-07-15): metadata-styled header row
+ * (uppercase/tracked/muted — headers must read as chrome, not data), an always-on row
+ * hover wash so wide rows can be traced, optional pinned header for deep lists, a
+ * full-width accordion detail row that never breaks column alignment, and an automatic
+ * stacked-card layout under `sm` so phones are never handed a clipped grid.
+ */
+export function DataTable<TRow extends Record<string, unknown>>({
+  columns,
+  data,
+  getRowId,
+  onRowClick,
+  onRowEdit,
+  onRowDelete,
+  rowMenu,
+  loading,
+  emptyState,
+  toolbar,
+  pageSize = 50,
+  pageSizeOptions,
+  hidePagination,
+  caption,
+  className,
+  stickyHeader,
+  stickyFirstColumn,
+  renderExpanded,
+  expandedRowId,
+  rowClassName,
+  hideEmptyColumns,
+  fixedLayout,
+  minTableWidth,
+  scrollBody,
+  virtualize,
+  mobileCards = true,
+  serverSide,
+  pageCount,
+  rowCount,
+  onSortingChange,
+  onColumnFiltersChange,
+  onGlobalFilterChange,
+  onPaginationChange,
+  defaultSort,
+  density = 'comfortable',
+  viewMode,
+  onViewModeChange,
+  cardMinWidth,
+  searchable = true,
+  searchPlaceholder,
+  multiSort = true,
+  filterQuery: filterQueryProp,
+  onFilterQueryChange,
+  getRowDrag,
+  dragSourceId,
+}: DataTableProps<TRow>) {
+  // Vertical cell padding for the wide grid tier — the one lever the density knob
+  // pulls (headers + body cells stay aligned by sharing it).
+  const cellPadY = density === 'compact' ? 'py-1.5' : 'py-2.5';
+  const [sorting, setSorting] = useState<SortingState>(defaultSort ?? []);
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+  const [globalFilter, setGlobalFilter] = useState('');
+
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(() =>
+    Object.fromEntries(columns.filter((c) => c.hidden).map((c) => [c.key, false])),
+  );
+  const [pagination, setPagination] = useState<PaginationState>({ pageIndex: 0, pageSize });
+  // `null` = every column, and it STAYS null as columns come and go — see SearchBox.
+  const [searchScope, setSearchScope] = useState<string[] | null>(null);
+  // Text + scope as ONE value — see TableSearchState for why they cannot be two.
+  // `undefined` when there is nothing typed, so TanStack skips global filtering
+  // entirely rather than running a predicate that always answers true.
+  const search = useMemo<TableSearchState | undefined>(
+    () => (globalFilter.trim() === '' ? undefined : { text: globalFilter, scope: searchScope }),
+    [globalFilter, searchScope],
+  );
+  const [ownFilterQuery, setOwnFilterQuery] = useState<FilterQuery>(EMPTY_FILTER_QUERY);
+  const filterQuery = filterQueryProp ?? ownFilterQuery;
+  const setFilterQuery = useCallback(
+    (next: FilterQuery) => {
+      if (filterQueryProp === undefined) setOwnFilterQuery(next);
+      setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
+      onFilterQueryChange?.(next);
+    },
+    [filterQueryProp, onFilterQueryChange],
+  );
+  const setSearchText = useCallback(
+    (text: string) => {
+      setGlobalFilter(text);
+      setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
+      onGlobalFilterChange?.(text);
+    },
+    [onGlobalFilterChange],
+  );
+  // Which row's expansion has already been scrolled into view — scroll once per
+  // expansion, never on the polling re-renders that follow.
+  const scrolledExpansionRef = useRef<string | null>(null);
+
+  // Empty-column pruning happens BEFORE the TanStack translation so headers, body
+  // cells, and the mobile cards all agree on the live column set. `alwaysVisible`
+  // columns are exempt — a renderer-only column (e.g. an actions column) has no
+  // matching row field, so a data-driven emptiness check would always drop it.
+  const liveColumns = useMemo(
+    () =>
+      hideEmptyColumns
+        ? columns.filter(
+            (col) => col.alwaysVisible || data.some((row) => !isEmptyCellValue(row[col.key])),
+          )
+        : columns,
+    [columns, data, hideEmptyColumns],
+  );
+
+  /**
+   * The filter BUILDER is applied to the rows before TanStack ever sees them,
+   * and that is deliberate: it is what makes the builder AND with the search box
+   * and the per-column filters instead of competing with them. TanStack already
+   * ANDs its own `globalFilter` and `columnFilters`; a third mechanism layered
+   * as another column filter would have had to invent a precedence rule between
+   * the three. Pre-filtering means there is nothing to decide — the builder
+   * narrows the dataset, the rest narrows what is left, and the sort stack
+   * re-applies to whatever survives.
+   */
+  const filteredData = useMemo(
+    () =>
+      serverSide
+        ? data
+        : data.filter((row) => evaluateFilterQuery(row, filterQuery, (r, key) => readPath(r, key))),
+    [data, filterQuery, serverSide],
+  );
+
+  /**
+   * Every write to the sort stack goes through here, so a header click, a chip's
+   * direction flip and a chip's `×` all take the same page-reset and fire the
+   * same `onSortingChange` — three code paths for one piece of state is how a
+   * server-side table ends up sorted differently from what its chips say.
+   */
+  const applySorting = useCallback(
+    (next: (prev: SortingState) => SortingState) => {
+      setSorting((prev) => {
+        const value = next(prev);
+        setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
+        onSortingChange?.(value);
+        return value;
+      });
+    },
+    [onSortingChange],
+  );
+  const toggleSortKey = useCallback(
+    (id: string) => applySorting((prev) => nextSortStack(prev, id, multiSort)),
+    [applySorting, multiSort],
+  );
+
+  const tsColumns = useMemo<ColumnDef<TRow>[]>(
+    () =>
+      liveColumns.map((col) => ({
+        id: col.key,
+        accessorKey: col.key,
+        // DESIGN.md §1 makes right-alignment a requirement for numeric values, not a
+        // preference — `resolveColumnAlign` derives it; an explicit `align` overrides.
+        meta: {
+          label: col.label,
+          align: resolveColumnAlign(col),
+          width: col.width,
+          minWidth: col.minWidth,
+        },
+        size: typeof col.width === 'number' ? col.width : undefined,
+        enableSorting: col.sortable ?? false,
+        enableHiding: !col.alwaysVisible,
+        // `filterable` is the AUTHORING decision — an internal id nobody means
+        // to match is out of the search universe entirely. The reader's USE-TIME
+        // choice within what is left rides the filter VALUE instead, because a
+        // column-config change does not invalidate TanStack's row model (see
+        // {@link TableSearchState}).
+        enableGlobalFilter: col.filterable ?? true,
+        // 🔴 Every column is filterable now (was `?? false`). The unit's item 2
+        // is one line — *"Every column filterable"* — and a per-column filter
+        // that only exists where somebody remembered to set a flag is the same
+        // "one table has it, the next does not" divergence as the search box.
+        enableColumnFilter: col.filterable ?? true,
+        // `table` (not the closed-over `sorting`) is what makes the ordinal
+        // badge live without putting the sort state in this memo's deps —
+        // rebuilding every ColumnDef on every sort click would throw away
+        // TanStack's column instances mid-interaction.
+        header: ({ column, table: t }) => {
+          const stack = t.getState().sorting;
+          return (
+            <SortHeader
+              column={column}
+              label={col.label}
+              sortable={col.sortable}
+              sortIndex={stack.length > 1 ? stack.findIndex((s) => s.id === col.key) : -1}
+              onSort={() => toggleSortKey(col.key)}
+            />
+          );
+        },
+        cell: ({ getValue, row }) => (
+          <CellRenderer
+            col={col}
+            value={getValue()}
+            row={row.original}
+            onEdit={onRowEdit ? () => onRowEdit(row.original) : undefined}
+          />
+        ),
+      })),
+    [liveColumns, onRowEdit, toggleSortKey],
+  );
+
+  const labelOf = useCallback(
+    (id: string) => liveColumns.find((col) => col.key === id)?.label ?? id,
+    [liveColumns],
+  );
+  const controls = useMemo<DataTableControls>(
+    () => ({
+      searchText: globalFilter,
+      setSearchText,
+      filterQuery,
+      setFilterQuery,
+      // `alwaysVisible` columns are exempt from HIDING, not from filtering — the
+      // builder's universe is every column that carries data.
+      filterColumns: liveColumns.map((col) => ({ key: col.key, label: col.label })),
+      searchScope,
+      setSearchScope,
+      searchColumns: liveColumns
+        .filter((col) => col.filterable ?? true)
+        .map((col) => ({ key: col.key, label: col.label })),
+      sorting,
+      clearSorting: () => applySorting(() => []),
+      removeSortKey: (id) => applySorting((prev) => prev.filter((sort) => sort.id !== id)),
+      toggleSortDirection: (id) =>
+        applySorting((prev) => prev.map((sort) => (sort.id === id ? { ...sort, desc: !sort.desc } : sort))),
+      labelOf,
+      viewMode,
+      setViewMode: onViewModeChange,
+    }),
+    [
+      applySorting,
+      filterQuery,
+      globalFilter,
+      setSearchText,
+      labelOf,
+      liveColumns,
+      onViewModeChange,
+      searchScope,
+      setFilterQuery,
+      sorting,
+      viewMode,
+    ],
+  );
+
+  /*
+   * ── Virtualization ────────────────────────────────────────────────────────
+   *
+   * 🔴 It IMPLIES `scrollBody` and it SUPPRESSES pagination, and both are silent
+   * corrections rather than warnings because both failures look like "virtualization
+   * does not work": a virtualizer measures a scroll container, so if vertical scrolling
+   * lives on an ancestor it measures a box that never scrolls and the window stays at
+   * row 0 while the page scrolls past it; and a page control over a virtual window is a
+   * second, disagreeing answer to "where am I" when the scrollbar already gives the
+   * honest one.
+   *
+   * 🔴 Suppressing pagination means the ROW MODEL, not only the pager. Left paginated,
+   * the virtualizer is handed one page's worth of rows, so its spacer describes 50 rows
+   * while the data has 5,000 — the scrollbar lies and the list simply ends. That is a
+   * failure the pager's absence hides rather than reveals, which is why it is tested by
+   * measuring `scrollHeight` in a real browser.
+   */
+  const virtualOptions = virtualize === true ? {} : virtualize || null;
+  const virtualEnabled = virtualOptions !== null;
+  const bodyScrolls = scrollBody || virtualEnabled;
+  const paginationHidden = hidePagination || virtualEnabled;
+
+  const table = useReactTable({
+    data: filteredData,
+    columns: tsColumns,
+    getRowId,
+    state: { sorting, columnFilters, globalFilter: search, columnVisibility, pagination },
+    onSortingChange: chainUpdaterResettingPage(setSorting, setPagination, onSortingChange),
+    onColumnFiltersChange: chainUpdaterResettingPage(setColumnFilters, setPagination, onColumnFiltersChange),
+    // TanStack hands the updater whatever `state.globalFilter` is, which is now
+    // a TableSearchState; the toolbar sets TEXT, so normalise both shapes.
+    onGlobalFilterChange: (updater) => {
+      const next = typeof updater === 'function' ? updater(search) : updater;
+      const text = typeof next === 'string' ? next : ((next as TableSearchState | undefined)?.text ?? '');
+      setSearchText(text);
+    },
+    onColumnVisibilityChange: chainUpdater(setColumnVisibility),
+    onPaginationChange: chainUpdater(setPagination, onPaginationChange),
+    // 🔴 Not `'includesString'` any more. That built-in is `String(value)`, and
+    // `String(new Date())` / `String(['rock','80s'])` are not the text the
+    // reader can see in the cell — a date column answered nothing at all for a
+    // typed year, which is the owner's own *"'199' in the date created"* case.
+    // `filterableText` is the SAME normalisation the filter builder uses, so a
+    // search and a `contains` condition on one column agree by construction
+    // rather than by two implementations happening to match.
+    globalFilterFn: (row, columnId, value) => {
+      // A bare string is still accepted: an app that calls
+      // `table.setGlobalFilter('x')` directly keeps working, unscoped.
+      const { text, scope } =
+        typeof value === 'string' ? { text: value, scope: null } : (value as TableSearchState);
+      if (!text) return true;
+      if (scope && !scope.includes(columnId)) return false;
+      return filterableText(row.getValue(columnId)).toLowerCase().includes(text.toLowerCase());
+    },
+    manualSorting: serverSide,
+    manualFiltering: serverSide,
+    manualPagination: serverSide,
+    pageCount: serverSide ? pageCount : undefined,
+    rowCount: serverSide ? rowCount : undefined,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: serverSide ? undefined : getSortedRowModel(),
+    getFilteredRowModel: serverSide ? undefined : getFilteredRowModel(),
+    // 🔴 `virtualEnabled` too, not only `serverSide`. See the note where the flag is
+    // computed: a paginated virtualizer sizes its spacer from one PAGE.
+    getPaginationRowModel: serverSide || virtualEnabled ? undefined : getPaginationRowModel(),
+    // TanStack's built-in auto-reset fires `resetPageIndex()` on EVERY `data`
+    // identity change (see `getCoreRowModel`'s memo deps), not just on filter/sort
+    // changes — any live-polling table (this one included: rows are re-derived
+    // every tick for a running duration column) got its page index silently
+    // stomped back to 0 mid-navigation. We own page resets explicitly above
+    // (sort/filter change) instead of trusting the library's blanket default.
+    autoResetPageIndex: false,
+    meta: { cbControls: controls },
+  });
+
+  /**
+   * The drag-source props for one row, or `{}` when this table is not a drag
+   * source. Every tier calls it — grid row, tablet list row, phone card, card
+   * view — so a row is draggable at every width rather than only in the grid.
+   *
+   * `preventDefault()` on a row the app refuses is the correct refusal: it
+   * cancels the drag before it starts, so there is no ghost image following the
+   * cursor to a drop that would be ignored.
+   */
+  const dragPropsFor = (
+    row: TRow,
+  ): { draggable?: boolean; onDragStart?: (event: DragEvent<HTMLElement>) => void } => {
+    if (!getRowDrag) return {};
+    return {
+      draggable: true,
+      onDragStart: (event) => {
+        const payload = getRowDrag(row);
+        if (!payload) {
+          event.preventDefault();
+          return;
+        }
+        writeRowDrag(event, { source: dragSourceId, ...payload });
+      },
+    };
+  };
+
+  const rows = table.getRowModel().rows;
+
+  const estimateRowHeight =
+    virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44);
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const rowVirtualizer = useVirtualizer({
+    count: virtualEnabled ? rows.length : 0,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => estimateRowHeight,
+    overscan: virtualOptions?.overscan ?? 8,
+    // 🔴 MEASURED, not assumed. A wrapping cell, an expanded detail panel and the
+    // `compact` density all change a row's height, and a caller cannot be asked to
+    // compute any of them. `estimateSize` only seeds the spacer before first paint.
+    measureElement: (el) => el.getBoundingClientRect().height,
+  });
+  /**
+   * 🔴 Invalidate the measurement cache when the row height changes.
+   *
+   * `measureElement` covers a row that is CURRENTLY rendered, and that is what makes
+   * this look finished. It says nothing about the rows already measured and scrolled
+   * out of view: `@tanstack/react-virtual` keeps their heights in its measurement
+   * list, and a new `estimateSize` does not invalidate one — only `measure()` does.
+   *
+   * So toggling `density` re-renders the visible rows at 36px while every row the
+   * viewer has already scrolled past is still placed at 44px. Rows overlap or leave
+   * gaps, nothing throws, and the symptom points at the layout code rather than at
+   * the virtualizer. `VirtualCardGrid` paid for that investigation once already and
+   * grew the same effect keyed on its own `rowHeight`; `virtualizerMeasure.spec.ts`
+   * exists so the third virtualizer does not pay for it a third time — and it is
+   * what caught this one.
+   */
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `estimateRowHeight` is the POINT of this effect, not a value it reads — re-running when it changes is what invalidates the cached offsets. Dropping it makes the measure fire once and never again, which is the bug.
+  useEffect(() => {
+    rowVirtualizer.measure();
+  }, [rowVirtualizer, estimateRowHeight]);
+  const virtualRows = virtualEnabled ? rowVirtualizer.getVirtualItems() : [];
+  /** The rows to render, and the two spacers that keep the scrollbar honest about the
+   *  ones that are not. Off, this is every row and no spacers — byte-identical output. */
+  const bodyRows = virtualEnabled ? virtualRows.map((v) => rows[v.index]!) : rows;
+  const padTop = virtualEnabled ? (virtualRows[0]?.start ?? 0) : 0;
+  const padBottom = virtualEnabled
+    ? rowVirtualizer.getTotalSize() - (virtualRows.at(-1)?.end ?? 0)
+    : 0;
+  const hasActions = !!(onRowEdit || onRowDelete || rowMenu);
+  const toolbarNode =
+    typeof toolbar === 'function'
+      ? toolbar(table)
+      : (toolbar ??
+        // 🔴 Present by DEFAULT, opted out of explicitly — the half of item 6
+        // that was actually missing. `enableSearch` has defaulted true forever
+        // and reached nothing, because a table with no `toolbar` rendered no
+        // toolbar at all. Only ONE toolbar is ever rendered: a caller that
+        // passes its own gets exactly that, and `TableToolbar` reads the same
+        // controls off `table.options.meta`, so composing a toolbar is never
+        // the thing that costs you the search box.
+        (searchable ? <TableToolbar table={table} searchPlaceholder={searchPlaceholder} /> : null));
+  const visibleColumnCount = table.getVisibleLeafColumns().length + (hasActions ? 1 : 0);
+  // Cards track the SAME live visibility state as the grid (ViewOptionsMenu toggles
+  // apply to both) — not just the ColDefs' initial `hidden` flags.
+  const cardColumns = liveColumns.filter((c) => table.getColumn(c.key)?.getIsVisible() ?? true);
+  // The freeze point: never below the tracks the visible columns declared (see
+  // `declaredTrackFloor`), and never below an explicit `minTableWidth` on top.
+  // Hiding a column through the view-options menu narrows it, so the table stops
+  // scrolling as soon as the reader has made it fit.
+  // "There is more table this way." A rigid grid that refuses to compress has to
+  // say so at the cut edge, or a narrow pane reads as a table with its right-hand
+  // columns missing rather than one that scrolls (`useScrollEdgeFade`).
+  const gridFade = useScrollEdgeFade();
+  const tableMinWidth = fixedLayout
+    ? Math.max(minTableWidth ?? 0, declaredTrackFloor(cardColumns, hasActions))
+    : minTableWidth;
+
+  return (
+    // `@container`: the card/grid switch below keys off THIS element's width, so the
+    // right layout appears in a narrow pane on a wide screen, not just on phones.
+    <div className={cn('@container flex min-h-0 flex-col', className)}>
+      {toolbarNode}
+
+      {loading ? (
+        <div className='flex flex-col gap-2 p-4'>
+          {Array.from({ length: 5 }).map((_, i) => (
+            // biome-ignore lint/suspicious/noArrayIndexKey: fixed-length loading placeholder rows that never reorder
+            <Skeleton key={`dt-skeleton-${i}`} className='h-10 w-full' />
+          ))}
+        </div>
+      ) : rows.length === 0 ? (
+        <div className='p-2'>{emptyState ?? <EmptyState title='No results' />}</div>
+      ) : (
+        // scrollBody makes the table body the one scroll container for BOTH axes —
+        // required for stickyHeader to pin (see the prop doc); ScrollArea's
+        // vertical-only flex model can't own horizontal table scroll.
+        // guardrails-ignore no-raw-overflow: dual-axis table scroll container — sticky header pins to it; ScrollArea cannot own horizontal table scroll.
+        <div ref={scrollRef} className={cn(bodyScrolls && 'min-h-0 flex-1 overflow-auto')}>
+          {/* ── The CARD view (opt-in via `viewMode`) — the same rows the grid
+              would show, after the same filter/sort/page, through the same cell
+              renderers. It replaces all three width tiers rather than sitting
+              beside them: a card grid already reflows, so a second breakpoint
+              ladder inside it would only fight the container query. ── */}
+          {viewMode === 'card' ? (
+            <CardView
+              columns={cardColumns}
+              data={rows.map((row) => row.original)}
+              getRowId={getRowId}
+              onRowClick={onRowClick}
+              dragPropsFor={getRowDrag ? dragPropsFor : undefined}
+              cardMinWidth={cardMinWidth}
+              className='p-2'
+            />
+          ) : (
+          <>
+          {/* ── Phone container (<36rem): stacked cards (a compressed grid clips columns + strands actions) ── */}
+          {mobileCards && (
+            <div data-cb-table-cards='' className='flex flex-col gap-3 @xl:hidden'>
+              {rows.map((row) => (
+                <MobileRowCard
+                  key={row.id}
+                  row={row}
+                  columns={cardColumns}
+                  className={rowClassName?.(row.original)}
+                  onRowClick={onRowClick}
+                  dragProps={dragPropsFor(row.original)}
+                  actions={
+                    hasActions ? (
+                      <RowActions
+                        row={row.original}
+                        onEdit={onRowEdit}
+                        onDelete={onRowDelete}
+                        menu={rowMenu?.(row.original)}
+                      />
+                    ) : null
+                  }
+                  expanded={
+                    renderExpanded && expandedRowId != null && row.id === expandedRowId
+                      ? renderExpanded(row.original)
+                      : null
+                  }
+                />
+              ))}
+            </div>
+          )}
+
+          {/* ── Tablet container (36–48rem): one divided list panel — no card-per-row
+              inflation, no repeated uppercase labels; values (pills/badges) sit
+              inline right where they explain themselves. ── */}
+          {mobileCards && (
+            <div data-cb-table-list='' className='hidden @xl:block @3xl:hidden'>
+              {(() => {
+                const [title, ...rest] = cardColumns;
+                // ONE shared grid template for every row — parent and child rows
+                // lock into identical column slots, so the status/ports/actions
+                // lanes stay razor-straight regardless of row content ("ragged
+                // right" defect, owner tablet re-judgment 2026-07-15). Columns
+                // reuse their ColDef width when set (px or proportional string,
+                // floored by minWidth); the trailing slot is the row-actions kebab.
+                const trackOf = (c: (typeof rest)[number]): string => {
+                  const share =
+                    c.width == null ? null : typeof c.width === 'number' ? `${c.width}px` : c.width;
+                  if (share == null) return 'max-content';
+                  return c.minWidth != null ? `minmax(${c.minWidth}px, ${share})` : share;
+                };
+                // The kebab track is a FIXED 32px, never max-content: the header
+                // strip and each row are separate grid containers, so a
+                // max-content track resolves differently where the kebab is
+                // absent (the header) and every preceding lane drifts ~32px off
+                // its label — the v4 judge's tablet misalignment finding.
+                const template = [
+                  'minmax(0,1fr)',
+                  ...rest.map(trackOf),
+                  ...(hasActions ? ['32px'] : []),
+                ].join(' ');
+                const header = (
+                  // The compact list keeps its column-context header — shedding the
+                  // labels on tablet left ports/status floating in unexplained space
+                  // (owner v3 teardown §6 "ghost columns"). Same template as the
+                  // rows below, so labels are structurally locked over their data.
+                  <div
+                    data-cb-table-list-header=''
+                    className='grid items-center gap-3 border-b border-border px-4 py-2 text-caption font-bold uppercase tracking-wider text-muted-foreground'
+                    style={{ gridTemplateColumns: template }}
+                  >
+                    <span>{title?.label ?? ''}</span>
+                    {rest.map((col) => (
+                      <span key={col.key} className={cn(resolveColumnAlign(col) === 'right' && 'text-right')}>
+                        {col.label}
+                      </span>
+                    ))}
+                    {hasActions ? <span aria-hidden /> : null}
+                  </div>
+                );
+                const body = rows.map((row) => {
+                  const isExpanded =
+                    renderExpanded != null && expandedRowId != null && row.id === expandedRowId;
+                  return (
+                    <Fragment key={row.id}>
+                      <div
+                        {...dragPropsFor(row.original)}
+                        className={cn(
+                          'grid items-center gap-3 px-4 py-3 transition-colors hover:bg-muted/40',
+                          getRowDrag && 'cursor-grab active:cursor-grabbing',
+                          rowClassName?.(row.original),
+                        )}
+                        style={{ gridTemplateColumns: template }}
+                      >
+                        <div className='min-w-0'>
+                          {title ? (
+                            <CellRenderer
+                              col={title}
+                              value={row.original[title.key]}
+                              row={row.original}
+                            />
+                          ) : null}
+                        </div>
+                        {rest.map((col) => (
+                          <div
+                            key={col.key}
+                            className={cn(resolveColumnAlign(col) === 'right' && 'justify-self-end text-right')}
+                          >
+                            <CellRenderer
+                              col={col}
+                              value={row.original[col.key]}
+                              row={row.original}
+                            />
+                          </div>
+                        ))}
+                        {hasActions ? (
+                          <RowActions
+                            row={row.original}
+                            onEdit={onRowEdit}
+                            onDelete={onRowDelete}
+                            menu={rowMenu?.(row.original)}
+                          />
+                        ) : null}
+                      </div>
+                      {isExpanded ? (
+                        <div className='bg-muted/20 px-4 pt-1 pb-3'>
+                          <div className='rounded-lg border border-border bg-card p-3 shadow-raised'>
+                            {renderExpanded(row.original)}
+                          </div>
+                        </div>
+                      ) : null}
+                    </Fragment>
+                  );
+                });
+                return (
+                  <>
+                    {header}
+                    <div className='divide-y divide-border'>{body}</div>
+                  </>
+                );
+              })()}
+            </div>
+          )}
+
+          {/* ── Wide container: the data grid ───────────────────────────────────── */}
+          {/* horizontal-only scroll sized to the table's own content (not a flex-1
+              vertical page region) — ScrollArea's keyboard-/safe-area-aware flex-1 +
+              trailing-spacer semantics are built for the page's main vertical scroll
+              container and would stretch/pad this content-sized row. */}
+          <div
+            ref={bodyScrolls ? undefined : gridFade.ref}
+            onScroll={bodyScrolls ? undefined : gridFade.onScroll}
+            style={bodyScrolls ? undefined : gridFade.maskStyle}
+            // guardrails-ignore no-raw-overflow: content-sized horizontal table scroll, not a page-level vertical scroll region — see reasoning above. Under scrollBody the OUTER wrapper owns both axes (a nested overflow ancestor would un-stick the sticky header).
+            className={cn(!bodyScrolls && 'overflow-x-auto', mobileCards && 'hidden @3xl:block')}
+          >
+            <table
+              className={cn('w-full border-collapse text-sm', fixedLayout && 'table-fixed')}
+              style={tableMinWidth != null ? { minWidth: tableMinWidth } : undefined}
+            >
+              {caption ? <caption className='sr-only'>{caption}</caption> : null}
+              <thead>
+                {table.getHeaderGroups().map((hg) => (
+                  <tr key={hg.id}>
+                    {hg.headers.map((h, headerIndex) => {
+                      const sorted = h.column.getIsSorted();
+                      const meta = h.column.columnDef.meta;
+                      const width = meta?.width ?? h.column.columnDef.size;
+                      const align = meta?.align;
+                      const frozen = stickyFirstColumn === true && headerIndex === 0;
+                      return (
+                        <th
+                          key={h.id}
+                          scope='col'
+                          aria-sort={
+                            sorted === 'asc'
+                              ? 'ascending'
+                              : sorted === 'desc'
+                                ? 'descending'
+                                : undefined
+                          }
+                          style={
+                            width != null || meta?.minWidth != null
+                              ? { width, minWidth: meta?.minWidth }
+                              : undefined
+                          }
+                          className={cn(
+                            // Metadata treatment: headers are chrome, not data — small,
+                            // bold, uppercase, tracked, muted (STANDARDS §5c) — via the
+                            // explicit secondary token, never an opacity fade (the
+                            // design manual bans opacity-blended text). The border
+                            // rides the <th> (not the <tr>) so it pins with stickyHeader.
+                            'border-b border-border px-4 text-caption font-bold uppercase tracking-wider text-muted-foreground',
+                            cellPadY,
+                            align === 'right' ? 'text-right' : 'text-left',
+                            // Sticky pins per-<th> (a <tr> can't stick); needs its own
+                            // near-opaque bg so rows scrolling beneath never bleed through.
+                            stickyHeader &&
+                              'sticky top-0 z-10 bg-card/95 backdrop-blur-sm',
+                            // The corner cell must outrank BOTH pinned axes, or the
+                            // next header slides over the frozen one. It is opaque
+                            // for the same reason the body cells are.
+                            frozen &&
+                              'sticky left-0 bg-card shadow-[1px_0_0_0_var(--color-border)]',
+                            frozen && (stickyHeader ? 'z-30' : 'z-20'),
+                          )}
+                        >
+                          {h.isPlaceholder
+                            ? null
+                            : flexRender(h.column.columnDef.header, h.getContext())}
+                        </th>
+                      );
+                    })}
+                    {hasActions ? (
+                      <th
+                        className={cn(
+                          'w-20 border-b border-border px-2',
+                          stickyHeader && 'sticky top-0 z-10 bg-card/95 backdrop-blur-sm',
+                        )}
+                        aria-label='Row actions'
+                      />
+                    ) : null}
+                  </tr>
+                ))}
+              </thead>
+              <tbody>
+                {/* The rows above the window, as ONE row of the right height. A
+                    `<tr>` with a height and no cells is the only padding a
+                    `<table>` accepts without breaking the column grid — a wrapper
+                    div inside tbody is invalid and browsers hoist it out. */}
+                {padTop > 0 ? (
+                  <tr aria-hidden style={{ height: padTop }}>
+                    <td colSpan={visibleColumnCount} />
+                  </tr>
+                ) : null}
+                {bodyRows.map((row, sliceIndex) => {
+                  /* 🔴 The ZEBRA index is the row's ABSOLUTE position, not its
+                     position in the rendered slice. Off by that, the stripes
+                     would repaint themselves every time the window moved — the
+                     rhythm inverting mid-scroll, which reads as a rendering
+                     fault rather than as a guide. */
+                  const rowIndex = virtualEnabled ? virtualRows[sliceIndex]!.index : sliceIndex;
+                  const isExpanded =
+                    renderExpanded != null && expandedRowId != null && row.id === expandedRowId;
+                  return (
+                    <Fragment key={row.id}>
+                      <tr
+                        // 🔴 The virtualizer reads its real height back off this node, and
+                        // `data-index` is how it knows WHICH row it measured — without it
+                        // every measurement lands on index 0 and the spacer never grows.
+                        {...(virtualEnabled
+                          ? { ref: rowVirtualizer.measureElement, 'data-index': rowIndex }
+                          : {})}
+                        data-expanded={isExpanded || undefined}
+                        {...dragPropsFor(row.original)}
+                        className={cn(
+                          getRowDrag && 'cursor-grab active:cursor-grabbing',
+                          // Always-on hover wash: wide rows need a trace line for the
+                          // eye even when the row itself isn't clickable. Zebra fill on
+                          // every second row gives the eye a guide path across wide
+                          // columns (design manual §4 zebra-vs-outline rule) — indexed
+                          // off the DATA row, not DOM position, so an expansion row
+                          // never flips the rhythm.
+                          'border-b border-border transition-colors last:border-0 hover:bg-muted',
+                          rowIndex % 2 === 1 && 'bg-muted/50',
+                          rowClassName?.(row.original),
+                          isExpanded && 'border-0 bg-muted/30',
+                          onRowClick &&
+                            'cursor-pointer hover:bg-muted focus-visible:bg-muted focus-visible:outline-none',
+                        )}
+                        tabIndex={onRowClick ? 0 : undefined}
+                        onClick={onRowClick ? () => onRowClick(row.original) : undefined}
+                        onKeyDown={
+                          onRowClick
+                            ? (e) => {
+                                if (e.key === 'Enter') onRowClick(row.original);
+                              }
+                            : undefined
+                        }
+                      >
+                        {row.getVisibleCells().map((cell, cellIndex) => {
+                          const frozen = stickyFirstColumn === true && cellIndex === 0;
+                          return (
+                          <td
+                            key={cell.id}
+                            style={
+                              frozen
+                                ? ({
+                                    // The zebra step, made OPAQUE — see the prop doc.
+                                    // A custom property rather than `background:`
+                                    // directly, so the value survives any CSS parser
+                                    // that has not learned `color-mix` (happy-dom) and
+                                    // the gate can read it back.
+                                    '--cb-frozen-bg':
+                                      rowIndex % 2 === 1
+                                        ? 'color-mix(in srgb, var(--color-muted) 50%, var(--color-card))'
+                                        : 'var(--color-card)',
+                                  } as CSSProperties)
+                                : undefined
+                            }
+                            className={cn(
+                              'px-4 align-middle',
+                              cellPadY,
+                              frozen &&
+                                'sticky left-0 z-10 bg-[var(--cb-frozen-bg)] shadow-[1px_0_0_0_var(--color-border)]',
+                              // A rigid track cannot widen for its content, so an
+                              // unbreakable token (a task id, a path, a hash) would
+                              // otherwise run straight across the next column's value.
+                              // Break inside the word instead — the row grows taller,
+                              // which is recoverable; overlapping text is not. Not
+                              // `overflow: hidden`: a cell may host a menu/tooltip that
+                              // has to escape its bounds.
+                              fixedLayout && '[overflow-wrap:anywhere]',
+                              (cell.column.columnDef.meta as { align?: 'left' | 'right' } | undefined)
+                                ?.align === 'right' && 'text-right',
+                            )}
+                          >
+                            {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                          </td>
+                          );
+                        })}
+                        {hasActions ? (
+                          <td className='px-2 py-2'>
+                            <RowActions
+                              row={row.original}
+                              onEdit={onRowEdit}
+                              onDelete={onRowDelete}
+                              menu={rowMenu?.(row.original)}
+                            />
+                          </td>
+                        ) : null}
+                      </tr>
+                      {isExpanded ? (
+                        <tr
+                          className='border-b border-border bg-muted/20'
+                          ref={(el) => {
+                            if (el && scrolledExpansionRef.current !== row.id) {
+                              scrolledExpansionRef.current = row.id;
+                              // A row expanded near the fold must reveal its panel.
+                              el.scrollIntoView({ block: 'nearest' });
+                            }
+                          }}
+                        >
+                          <td colSpan={visibleColumnCount} className='p-0'>
+                            {/* The detail renders as an INSET sub-shelf — a bordered
+                                panel nested inside the row block's padding — so the
+                                expansion reads as contained within the table card
+                                instead of a full-bleed band that fractures the pane
+                                (owner final judgments part 2, detail §1). */}
+                            <div className='animate-in fade-in slide-in-from-top-1 px-4 pt-1 pb-3 duration-200'>
+                              <div className='rounded-lg border border-border bg-card p-3 shadow-raised'>
+                                {renderExpanded(row.original)}
+                              </div>
+                            </div>
+                          </td>
+                        </tr>
+                      ) : null}
+                    </Fragment>
+                  );
+                })}
+                {padBottom > 0 ? (
+                  <tr aria-hidden style={{ height: padBottom }}>
+                    <td colSpan={visibleColumnCount} />
+                  </tr>
+                ) : null}
+              </tbody>
+            </table>
+          </div>
+          </>
+          )}
+
+          {bodyScrolls && (
+            <div
+              aria-hidden
+              className='pointer-events-none sticky bottom-0 -mt-6 h-6 w-full bg-gradient-to-t from-card to-transparent'
+            />
+          )}
+        </div>
+      )}
+
+      {!loading && rows.length > 0 && !paginationHidden ? (
+        <TablePagination table={table} pageSizeOptions={pageSizeOptions} />
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * One row rendered as a phone card: first visible column = the title zone (unlabeled,
+ * full width), labeled columns = compact label/value pairs, empty-labeled columns
+ * (an actions column) + the row-actions kebab = the bordered footer row, actions
+ * anchored bottom-right inside the card bounds. Values render through the SAME
+ * {@link CellRenderer} registry as the grid, so a custom cell shows identically here.
+ */
+function MobileRowCard<TRow extends Record<string, unknown>>({
+  row,
+  columns,
+  className,
+  onRowClick,
+  dragProps,
+  actions,
+  expanded,
+}: {
+  row: Row<TRow>;
+  columns: ColDef<TRow>[];
+  className?: string;
+  onRowClick?: (row: TRow) => void;
+  dragProps?: { draggable?: boolean; onDragStart?: (event: DragEvent<HTMLElement>) => void };
+  actions: ReactNode;
+  expanded: ReactNode;
+}) {
+  const visible = columns.filter((c) => !c.hidden);
+  const [title, ...rest] = visible;
+  const footer = rest.filter((c) => c.cardFooter || c.label === '');
+  const detail = rest.filter(
+    (c) => !footer.includes(c) && c.label !== '' && c.cardLabel !== false,
+  );
+  // Self-describing values (cardLabel: false) flow into ONE inline strip under the
+  // title — repeating uppercase labels per card destroys vertical flow.
+  const inline = rest.filter(
+    (c) => !footer.includes(c) && c.label !== '' && c.cardLabel === false,
+  );
+
+  // The manual's card blueprint (mobile-responsive/): the FIRST self-describing
+  // value (typically a status pill) floats at the title row's right edge — one
+  // glance pairs identity with state; the rest of the inline strip flows below.
+  const [titleSideCol, ...restInline] = inline;
+  const body = (
+    <div className={cn('flex flex-col gap-2', actions && 'pr-10')}>
+      {title ? (
+        <div className='flex items-start justify-between gap-2 text-sm'>
+          <div className='min-w-0 flex-1'>
+            <CellRenderer col={title} value={row.original[title.key]} row={row.original} />
+          </div>
+          {titleSideCol ? (
+            <span className='shrink-0'>
+              <CellRenderer
+                col={titleSideCol}
+                value={row.original[titleSideCol.key]}
+                row={row.original}
+              />
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+      {restInline.length > 0 && (
+        <div className='flex flex-wrap items-center gap-2'>
+          {restInline.map((col) => (
+            <CellRenderer key={col.key} col={col} value={row.original[col.key]} row={row.original} />
+          ))}
+        </div>
+      )}
+      {detail.length > 0 && (
+        <dl className='flex flex-col gap-1.5'>
+          {detail.map((col) => (
+            <div key={col.key} className='flex items-baseline justify-between gap-3'>
+              <dt className='cb-meta-label shrink-0'>{col.label}</dt>
+              <dd className='min-w-0 text-right text-sm'>
+                <CellRenderer col={col} value={row.original[col.key]} row={row.original} />
+              </dd>
+            </div>
+          ))}
+        </dl>
+      )}
+    </div>
+  );
+
+  return (
+    // `relative isolate`: the kebab cluster is absolutely positioned inline with the
+    // title (top-right), and isolate keeps it from painting over the NEXT card
+    // (CardTapTarget's documented iPhone tap-eater pairing).
+    // pad `sm`: phone cards are a scanning surface — `md`'s 16-20px frame capped the
+    // viewport at under two rows per screen (owner v3 mobile teardown §4 "padding
+    // inefficiency"); `sm` keeps a clear frame at roughly three rows per screen.
+    <Surface
+      level='raised'
+      pad='sm'
+      radius='lg'
+      {...dragProps}
+      className={cn('relative isolate', dragProps?.draggable && 'cursor-grab', className)}
+    >
+      {/* Context/kebab actions ride the top-right corner inline with the title —
+          parking them in the footer left a dead whitespace ocean mid-card (owner
+          final judgments part 2, mobile §2). Outside the tap target in the DOM, so
+          opening the menu never doubles as the row click. Inset a full 12px from
+          the card edge (misclick buffer, owner v3 mobile teardown) with a ≥44px
+          coarse-pointer hit box on the kebab itself (RowActions). */}
+      {actions ? <div className='absolute top-3 right-3 z-10'>{actions}</div> : null}
+      {onRowClick ? (
+        // Navigation affordance over the card body only — the actions footer stays
+        // OUTSIDE this region so tapping Stop/Start never also fires the row click.
+        <CardTapTarget
+          onClick={() => onRowClick(row.original)}
+          className='-m-1 rounded-md p-1 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring'
+        >
+          {body}
+        </CardTapTarget>
+      ) : (
+        body
+      )}
+      {/* Primary row actions (an actions column) sit in a bordered footer strip
+          contained inside the card bounds — the one hairline a card carries (owner
+          final judgments part 2, mobile card template). */}
+      {footer.length > 0 && (
+        <div className='mt-3 flex items-center justify-end gap-2 border-t border-border/60 pt-3'>
+          {footer.map((col) => (
+            <CellRenderer key={col.key} col={col} value={row.original[col.key]} row={row.original} />
+          ))}
+        </div>
+      )}
+      {expanded ? <div className='mt-4'>{expanded}</div> : null}
+    </Surface>
+  );
+}