cursedbelt 5.23.0 → 5.26.0

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

@@ -14,16 +14,27 @@ import {
   useReactTable,
   type VisibilityState,
 } from '@tanstack/react-table';
-import type { CSSProperties, DragEvent, Dispatch, ReactNode, SetStateAction } from 'react';
+import type {
+  CSSProperties,
+  DragEvent,
+  Dispatch,
+  KeyboardEvent,
+  MouseEvent,
+  ReactNode,
+  SetStateAction,
+} from 'react';
 import { useVirtualizer } from '@tanstack/react-virtual';
-import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { type ComponentType, Fragment, type Ref, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import { useScrollEdgeFade } from '../../hooks/useScrollEdgeFade.js';
 import { cn } from '../../lib/cn.js';
+import { TAP_TARGET_HEIGHT } from '../../lib/tapTarget.js';
 import { CardTapTarget } from '../CardTapTarget.js';
+import { Checkbox } from '../Checkbox.js';
 import type { DropdownMenuItem } from '../DropdownMenu.js';
 import { EmptyState } from '../EmptyState.js';
 import { Skeleton } from '../Skeleton.js';
 import { Surface } from '../Surface.js';
+import { Tooltip } from '../Tooltip.js';
 import { CardView } from './CardView.js';
 import { CellRenderer } from './cells/CellRenderer.js';
 import {
@@ -32,13 +43,71 @@ import {
   filterableText,
   type FilterQuery,
 } from './filterQuery.js';
-import { TablePagination } from './Pagination.js';
-import { RowActions } from './RowActions.js';
+import { preloadRowMenu, RowActions } from './RowActions.js';
 import { type RowDragPayload, writeRowDrag } from './rowDrag.js';
 import { SortHeader } from './SortHeader.js';
-import { TableToolbar } from './Toolbar.js';
-import type { ColDef, TableViewMode } from './types.js';
+import type {
+  ColDef,
+  DataTableHandle,
+  DataTableRowProps,
+  DataTableSelectAll,
+  DataTableServerWindow,
+  TableViewMode,
+} from './types.js';
 import { resolveColumnAlign } from './types.js';
+import { lazyPart } from './lazyPart.js';
+import type { TablePaginationProps } from './Pagination.js';
+import type { TableToolbarProps } from './Toolbar.js';
+
+// 🔴 The toolbar and the pager load only when a table DRAWS them (forge task 2309).
+// Between them they reach Radix's Select, Menu and Popover — ~20 kB gzip that a
+// read-only list (`searchable={false}`, `serverWindow`, no row menu) never opens.
+// Measured on apps/music's track list: 67 kB gzip over its entry ceiling, most of
+// it these two parts' dependencies. A static import made every consumer pay for
+// them. The row kebab's menu is lazy the same way, inside `RowActions`; all three
+// are loaded ahead by `preloadDataTableParts`. `lazyPart` erases the component's
+// type parameter, so each is given back its own signature.
+const ToolbarPart = lazyPart(() =>
+  import('./Toolbar.js').then((m) => m.TableToolbar as ComponentType<TableToolbarProps<unknown>>),
+) as unknown as (<TRow>(props: TableToolbarProps<TRow> & { fallback?: ReactNode }) => ReactNode) & {
+  preload: () => Promise<void>;
+};
+const PaginationPart = lazyPart(() =>
+  import('./Pagination.js').then(
+    (m) => m.TablePagination as ComponentType<TablePaginationProps<unknown>>,
+  ),
+) as unknown as (<TRow>(props: TablePaginationProps<TRow> & { fallback?: ReactNode }) => ReactNode) & {
+  preload: () => Promise<void>;
+};
+
+/**
+ * Load the table's lazy parts — the toolbar, the pager, the row kebab's menu — now,
+ * so every table mounted after this resolves draws them on its first render. For a
+ * spec setup that queries them synchronously after `render(…)`, and for an app about
+ * to show a table with a toolbar. Never required: without it they arrive a tick late,
+ * into a placeholder of their own height.
+ */
+export async function preloadDataTableParts(): Promise<void> {
+  await Promise.all([ToolbarPart.preload(), PaginationPart.preload(), preloadRowMenu()]);
+}
+
+/** Where the toolbar will be, the height it will be — so its arrival shifts nothing. */
+function ToolbarPlaceholder() {
+  return (
+    <div data-cb-table-toolbar-pending='' aria-hidden className='border-b border-border px-2 py-2'>
+      <div className={cn('h-9', TAP_TARGET_HEIGHT)} />
+    </div>
+  );
+}
+
+/** Where the pager will be, the height it will be. */
+function PaginationPlaceholder() {
+  return (
+    <div data-cb-table-pagination-pending='' aria-hidden className='border-t border-border px-4 py-2.5'>
+      <div className={cn('h-8', TAP_TARGET_HEIGHT)} />
+    </div>
+  );
+}
 
 // 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
@@ -51,6 +120,8 @@ declare module '@tanstack/react-table' {
      *  own `size` is number-only, so proportional tracks ride meta instead. */
     width?: number | string;
     minWidth?: number;
+    hideBelow?: 'sm' | 'md' | 'lg';
+    leading?: boolean;
   }
   interface TableMeta<TData extends RowData> {
     /** {@link DataTableControls} — see its doc for why it rides on the table. */
@@ -124,7 +195,7 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
   /** 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;
+  onRowClick?: (row: TRow, event?: MouseEvent<HTMLElement>) => void;
   /** Trailing per-row Edit action (renders the actions column). */
   onRowEdit?: (row: TRow) => void;
   /** Trailing per-row Delete action (renders the actions column). */
@@ -238,8 +309,59 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
    * 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.
+   *
+   * It virtualizes the rows it is GIVEN. A list whose rows live on a SERVER — a spacer
+   * sized from the server's count, pages loading as they scroll into view, a scrollbar
+   * that can be dragged to a row nobody has fetched — is {@link serverWindow}, which
+   * implies this.
    */
   virtualize?: boolean | { estimateRowHeight?: number; overscan?: number };
+  /**
+   * SERVER-WINDOWED rows: `data` is only a WINDOW of a result set the server holds —
+   * rows `[start, start + data.length)` of `total`. Implies {@link virtualize}.
+   *
+   * ── Why (forge task 2300) ─────────────────────────────────────────────────
+   * apps/music's library is 5,409 tracks and its list is the surface the owner "spends
+   * all their time in". It pages from the server, and four of its owner-reported bugs
+   * were each a way of getting that arithmetic wrong — so the arithmetic lives here once:
+   *
+   * - The spacer is sized from `total`, so the scrollbar describes the whole result set
+   *   while only a window is in memory. Rows outside the window render as placeholder
+   *   rows (`data-cb-placeholder`) of the estimated height.
+   * - `onReachEnd` / `onReachStart` fire as the viewport nears either edge of the LOADED
+   *   window (never of the spacer — measured against `scrollHeight`, a 1,808-row folder
+   *   stopped paging at row 100 because the trigger sat 1,700 rows past the last real
+   *   row). `onReachStart` only for a window that does not begin at row 0.
+   * - `onNeedWindow(firstVisibleRow)` fires when the viewport comes to REST wholly
+   *   outside the window — the scrollbar was dragged, or a flick outran paging. Paging
+   *   cannot catch up from there; the caller fetches ONE window around the row instead.
+   *   🔴 Only at rest (`settleMs`): a smooth scroll to a revealed row passes over
+   *   hundreds of unloaded rows on its way, and acting on each would fetch a window
+   *   around wherever the animation happened to be.
+   *
+   * Pair it with {@link handleRef}'s `scrollToIndex` to reveal or follow a row by its
+   * row number over the whole result set. Pagination, client-side sort and client-side filtering are off:
+   * the server orders and filters, and a window cannot be re-sorted locally.
+   */
+  serverWindow?: DataTableServerWindow;
+  /**
+   * The table's imperative handle — `scrollToIndex(absoluteRow, { align, behavior })`
+   * and the `scrollElement` itself (for a scroll-memory hook or a caller telling its
+   * own scrolls from the reader's). Only meaningful with {@link virtualize} or
+   * {@link serverWindow}, where the table owns the scroll container.
+   */
+  handleRef?: Ref<DataTableHandle>;
+  /**
+   * Classes for the box that SCROLLS — under {@link scrollBody}, {@link virtualize} or
+   * {@link serverWindow}, the table's own scroll container; otherwise the same wrapper,
+   * which then merely holds the rows. `className` is the OUTER box (toolbar, table and pager).
+   *
+   * 🔴 Why (forge task 2302): an app's styles and its browser suites address "the list that
+   * scrolls" — apps/music measures `.track-list`'s `scrollHeight` against its spacer in eleven
+   * places, because that chain is where its worst owner report lived. With the scroller inside
+   * the table, only the table can put a name on it.
+   */
+  scrollClassName?: string;
   /**
    * 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):
@@ -269,6 +391,28 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
   /** 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;
+  /**
+   * The sort, CONTROLLED. A header click reports the next stack through `onSortingChange` and
+   * the table shows whatever comes back here. Omit it and the table owns the sort (seeded by
+   * `defaultSort`), exactly as before.
+   *
+   * For a list the SERVER orders (`serverSide`, `serverWindow`), whose sort lives in the app's
+   * query and URL: the header then says what the rows are actually sorted by, never what the
+   * table last guessed.
+   */
+  sorting?: SortingState;
+  /**
+   * `false`: a click on the only-remaining sort key flips it back to its first direction
+   * instead of removing it — for a list that always HAS an order (a server `ORDER BY`), where
+   * "unsorted" is not a state the rows can be in. Default `true` (asc → desc → out).
+   */
+  enableSortingRemoval?: boolean;
+  /**
+   * Sorting is unavailable right now, and this is why — the sortable headers stay VISIBLE but
+   * inert, with this sentence on hover (the owner-UI rule: disabled with the reason, never
+   * hidden). apps/music: *"The list is in play order — turn shuffle off to sort it."*
+   */
+  sortDisabledReason?: string;
   /**
    * Wide-grid row density (design manual, grid-layout/ — "high-density data tables
    * over empty visual widgets"):
@@ -374,6 +518,72 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
   /** Identifies this table in the drag payload, so a target can refuse rows
    *  from a table it does not serve. */
   dragSourceId?: string;
+
+  /**
+   * ROW SELECTION, controlled. Passing `selectedIds` is what turns it on: a
+   * leading checkbox column in the grid, a box per row in the tablet list, the
+   * phone cards and the card view, and a tri-state select-all in the header (a
+   * "Select all" strip on the tiers that have no header row). Omit it and the
+   * table renders exactly as it did before the feature existed.
+   *
+   * Ids are the table's row ids — `getRowId`, which you should pass: without it
+   * the id is the row's index in `data`, which moves when `data` does.
+   *
+   * 🔴 Select-all covers the FILTERED rows — every row the search box, the
+   * per-column filters and the filter builder leave standing — across ALL pages,
+   * not only the page on screen. That is Gmail's "select all N matching" without
+   * the second click: the header states what the reader can see the table is
+   * showing ("these 38 matches"), and a pager is a viewport over that set, not a
+   * boundary of it. Rows hidden by the filter are never added or removed by it,
+   * so narrowing the search to pick a few more never drops earlier picks.
+   * Under `serverSide` the table only knows the rows it was given, so that is
+   * the set.
+   */
+  selectedIds?: ReadonlySet<string>;
+  /** The whole next selection (a new Set) after a row or select-all toggle. */
+  onSelectionChange?: (next: ReadonlySet<string>) => void;
+  /**
+   * The header's select-all box, owned by the CALLER — its state, its name, what a press does.
+   *
+   * 🔴 For a table that holds only part of what "all" means. Under `serverWindow` the table
+   * has a window of a hundred rows out of thousands, so its own select-all could only ever tick
+   * the hundred — a lie about the list on screen. apps/music's "all" is every track the VIEW
+   * matches, fetched as ids from the server; only the caller can know that set, so the caller
+   * owns the box. The row boxes are unchanged (`selectedIds` / `onSelectionChange`).
+   */
+  selectAll?: DataTableSelectAll;
+  /**
+   * Attributes and handlers for one body ROW, merged onto it after the table's own —
+   * `className` joins, `style` spreads, and a handler the table also sets runs AFTER the
+   * table's (a caller can still `preventDefault()`/`stopPropagation()` for everything later).
+   *
+   * 🔴 Why (forge task 2302): a row is more than its cells. apps/music's track row carries its
+   * identity (`data-track-id` — a windowed row's POSITION is not an identity, and every browser
+   * suite addresses rows by it), `aria-current` for the playing track, double-click and Enter to
+   * play, its own drag payload for the rail, and drop handling to reorder a playlist. None of
+   * that is a cell. `rowIndex` is the row's number over the whole result set (a `serverWindow`
+   * row's absolute position).
+   *
+   * Applied to the grid row, the tablet list row and the phone card.
+   */
+  getRowProps?: (row: TRow, rowIndex: number) => DataTableRowProps;
+  /** `false` renders that row's checkbox DISABLED (still visible) and keeps the
+   *  row out of select-all. Pair with {@link unselectableReason}. */
+  isRowSelectable?: (row: TRow) => boolean;
+  /** Why a row cannot be selected — shown on hover/tap of its disabled box
+   *  (default "This row can't be selected"). A disabled control that does not
+   *  say why is the thing the owner UI rule forbids. */
+  unselectableReason?: (row: TRow) => string;
+  /** The per-row checkbox's accessible name (default: `Select <first column's
+   *  text>`). */
+  selectionLabel?: (row: TRow) => string;
+  /**
+   * A strip under the toolbar for the selection's summary and its bulk actions —
+   * `(rows) => rows.length ? <>{rows.length} games · 38 MB <Button …/></> : null`.
+   * Receives every selected row present in `data` (filtered out or not), in
+   * `data` order. Return `null` and no strip renders.
+   */
+  selectionSummary?: (selectedRows: TRow[]) => ReactNode;
 }
 
 /** Build an OnChangeFn that updates local state AND notifies an optional listener. */
@@ -415,6 +625,8 @@ function chainUpdaterResettingPage<T>(
 export const AUTO_TRACK_FLOOR_PX = 120;
 /** The trailing row-actions column is a fixed `w-20`. */
 const ACTIONS_TRACK_PX = 80;
+/** The leading row-selection column is a fixed `w-11` (44px — a full tap target). */
+const SELECT_TRACK_PX = 44;
 
 /**
  * The narrowest width at which a `fixedLayout` table still honors the tracks its
@@ -492,15 +704,23 @@ export function nextSortStack(
   current: SortingState,
   id: string,
   multi: boolean,
+  options: {
+    /** The column's FIRST direction is descending (`ColDef.sortDescFirst`). */
+    descFirst?: boolean;
+    /** `false`: the last click of the cycle flips back instead of removing the key
+     *  (`enableSortingRemoval`). Default `true`. */
+    removable?: boolean;
+  } = {},
 ): SortingState {
+  const first = options.descFirst ?? false;
   const existing = current.find((sort) => sort.id === id);
   if (!existing) {
-    const ascending = { id, desc: false };
-    return multi ? [ascending, ...current] : [ascending];
+    const started = { id, desc: first };
+    return multi ? [started, ...current] : [started];
   }
-  if (!existing.desc) {
-    const flipped = current.map((sort) => (sort.id === id ? { id, desc: true } : sort));
-    return multi ? flipped : [{ id, desc: true }];
+  if (existing.desc === first || options.removable === false) {
+    const flipped = { id, desc: !existing.desc };
+    return multi ? current.map((sort) => (sort.id === id ? flipped : sort)) : [flipped];
   }
   return multi ? current.filter((sort) => sort.id !== id) : [];
 }
@@ -519,6 +739,49 @@ function readPath(row: unknown, key: string): unknown {
   }, row);
 }
 
+/**
+ * `ColDef.hideBelow` as the container-query classes that do it. Literal strings, so the style
+ * generators (`scripts/generate*Styles.ts`) find them in the source.
+ *
+ * 🔴 The column COLLAPSES — zero width, no padding, its content removed — rather than
+ * `display: none`. A hidden cell is not a column, but the rows that SPAN the table (the
+ * virtualizer's spacers, a server window's placeholder rows, an expanded panel) still say
+ * `colSpan={every column}`, and a span wider than the table's real columns makes the missing
+ * ones up: they took the width the hidden columns gave back, so the table's rows stopped short
+ * of its right edge and the title — the one width-less column — was crushed to "S…". Measured
+ * on apps/music at 390px and 1100px, forge task 2302. Collapsed, the column count never moves,
+ * and every span stays true. (`[&>*]:hidden` takes the content out of the accessibility tree
+ * too, so a collapsed cell reads as nothing, not as a value nobody can see.)
+ */
+const HIDE_BELOW_CLASS = {
+  sm: '@max-2xl:w-0! @max-2xl:min-w-0! @max-2xl:p-0! @max-2xl:border-0 @max-2xl:[&>*]:hidden',
+  md: '@max-4xl:w-0! @max-4xl:min-w-0! @max-4xl:p-0! @max-4xl:border-0 @max-4xl:[&>*]:hidden',
+  lg: '@max-6xl:w-0! @max-6xl:min-w-0! @max-6xl:p-0! @max-6xl:border-0 @max-6xl:[&>*]:hidden',
+} as const;
+
+/**
+ * The table's own props for a row, with the caller's `getRowProps` merged on top: classes join,
+ * styles spread, and a handler both set runs the table's first, then the caller's.
+ */
+export function mergeRowProps<T extends Record<string, unknown>>(
+  own: T,
+  extra: DataTableRowProps | undefined,
+): T & DataTableRowProps {
+  if (!extra) return own as T & DataTableRowProps;
+  const merged: Record<string, unknown> = { ...own, ...extra };
+  if (own.className || extra.className) merged.className = cn(own.className as string | undefined, extra.className);
+  if (own.style || extra.style) merged.style = { ...(own.style as CSSProperties | undefined), ...extra.style };
+  for (const [key, handler] of Object.entries(extra)) {
+    const mine = own[key];
+    if (!key.startsWith('on') || typeof handler !== 'function' || typeof mine !== 'function') continue;
+    merged[key] = (event: unknown) => {
+      (mine as (e: unknown) => void)(event);
+      (handler as (e: unknown) => void)(event);
+    };
+  }
+  return merged as T & DataTableRowProps;
+}
+
 /** True when a cell value carries nothing worth a column: null/undefined/''/[]. */
 function isEmptyCellValue(v: unknown): boolean {
   if (v == null) return true;
@@ -566,6 +829,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
   minTableWidth,
   scrollBody,
   virtualize,
+  serverWindow,
+  handleRef,
+  scrollClassName,
   mobileCards = true,
   serverSide,
   pageCount,
@@ -575,6 +841,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
   onGlobalFilterChange,
   onPaginationChange,
   defaultSort,
+  sorting: sortingProp,
+  enableSortingRemoval = true,
+  sortDisabledReason,
   density = 'comfortable',
   viewMode,
   onViewModeChange,
@@ -586,11 +855,23 @@ export function DataTable<TRow extends Record<string, unknown>>({
   onFilterQueryChange,
   getRowDrag,
   dragSourceId,
+  selectedIds,
+  onSelectionChange,
+  isRowSelectable,
+  unselectableReason,
+  selectionLabel,
+  selectionSummary,
+  selectAll,
+  getRowProps,
 }: 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 [ownSorting, setOwnSorting] = useState<SortingState>(defaultSort ?? []);
+  const sorting = sortingProp ?? ownSorting;
+  /** The sort as of THIS render, for a write that has to start from it (see `applySorting`). */
+  const sortingRef = useRef(sorting);
+  sortingRef.current = sorting;
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
   const [globalFilter, setGlobalFilter] = useState('');
 
@@ -669,18 +950,26 @@ export function DataTable<TRow extends Record<string, unknown>>({
    */
   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;
-      });
+      // Computed OUTSIDE a state updater: under a controlled `sorting` there is no state to
+      // update, and a notify inside an updater fires twice in StrictMode.
+      const value = next(sortingRef.current);
+      sortingRef.current = value;
+      if (sortingProp === undefined) setOwnSorting(value);
+      setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
+      onSortingChange?.(value);
     },
-    [onSortingChange],
+    [onSortingChange, sortingProp],
+  );
+  const sortDescFirstOf = useCallback(
+    (id: string) => columns.find((col) => col.key === id)?.sortDescFirst ?? false,
+    [columns],
   );
   const toggleSortKey = useCallback(
-    (id: string) => applySorting((prev) => nextSortStack(prev, id, multiSort)),
-    [applySorting, multiSort],
+    (id: string) =>
+      applySorting((prev) =>
+        nextSortStack(prev, id, multiSort, { descFirst: sortDescFirstOf(id), removable: enableSortingRemoval }),
+      ),
+    [applySorting, enableSortingRemoval, multiSort, sortDescFirstOf],
   );
 
   const tsColumns = useMemo<ColumnDef<TRow>[]>(
@@ -695,6 +984,8 @@ export function DataTable<TRow extends Record<string, unknown>>({
           align: resolveColumnAlign(col),
           width: col.width,
           minWidth: col.minWidth,
+          hideBelow: col.hideBelow,
+          leading: col.leading,
         },
         size: typeof col.width === 'number' ? col.width : undefined,
         enableSorting: col.sortable ?? false,
@@ -723,6 +1014,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
               sortable={col.sortable}
               sortIndex={stack.length > 1 ? stack.findIndex((s) => s.id === col.key) : -1}
               onSort={() => toggleSortKey(col.key)}
+              disabledReason={sortDisabledReason}
             />
           );
         },
@@ -735,7 +1027,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
           />
         ),
       })),
-    [liveColumns, onRowEdit, toggleSortKey],
+    [liveColumns, onRowEdit, sortDisabledReason, toggleSortKey],
   );
 
   const labelOf = useCallback(
@@ -797,17 +1089,37 @@ export function DataTable<TRow extends Record<string, unknown>>({
    * 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 virtualOptions = virtualize === true || (serverWindow && !virtualize) ? {} : virtualize || null;
   const virtualEnabled = virtualOptions !== null;
   const bodyScrolls = scrollBody || virtualEnabled;
   const paginationHidden = hidePagination || virtualEnabled;
 
+  const selectionEnabled = selectedIds !== undefined;
+  /**
+   * Without `getRowId`, TanStack ids a row by its index in the array it was
+   * handed — which is `filteredData`, so the builder narrowing the rows would
+   * re-number them and a selection would silently move to other rows. When
+   * selection is on, the fallback id is the row's index in `data` instead.
+   * Off, TanStack's own default stands, untouched.
+   */
+  const dataIndex = useMemo(
+    () => (selectionEnabled && !getRowId ? new Map(data.map((row, i) => [row, i])) : null),
+    [data, getRowId, selectionEnabled],
+  );
+  const resolvedGetRowId = useMemo(
+    () => getRowId ?? (dataIndex ? (row: TRow) => String(dataIndex.get(row)) : undefined),
+    [dataIndex, getRowId],
+  );
+
   const table = useReactTable({
     data: filteredData,
     columns: tsColumns,
-    getRowId,
+    getRowId: resolvedGetRowId,
     state: { sorting, columnFilters, globalFilter: search, columnVisibility, pagination },
-    onSortingChange: chainUpdaterResettingPage(setSorting, setPagination, onSortingChange),
+    // Through `applySorting`, like every other write — so a controlled `sorting` is honoured
+    // whether TanStack or a header asked for the change.
+    onSortingChange: (updater) =>
+      applySorting((prev) => (typeof updater === 'function' ? updater(prev) : updater)),
     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.
@@ -834,14 +1146,16 @@ export function DataTable<TRow extends Record<string, unknown>>({
       if (scope && !scope.includes(columnId)) return false;
       return filterableText(row.getValue(columnId)).toLowerCase().includes(text.toLowerCase());
     },
-    manualSorting: serverSide,
-    manualFiltering: serverSide,
+    // A server window is server-ordered and server-filtered by construction: a WINDOW
+    // re-sorted locally would put row 4,000's neighbours next to row 12's.
+    manualSorting: serverSide || !!serverWindow,
+    manualFiltering: serverSide || !!serverWindow,
     manualPagination: serverSide,
     pageCount: serverSide ? pageCount : undefined,
     rowCount: serverSide ? rowCount : undefined,
     getCoreRowModel: getCoreRowModel(),
-    getSortedRowModel: serverSide ? undefined : getSortedRowModel(),
-    getFilteredRowModel: serverSide ? undefined : getFilteredRowModel(),
+    getSortedRowModel: serverSide || serverWindow ? undefined : getSortedRowModel(),
+    getFilteredRowModel: serverSide || serverWindow ? 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(),
@@ -883,18 +1197,90 @@ export function DataTable<TRow extends Record<string, unknown>>({
 
   const rows = table.getRowModel().rows;
 
+  /**
+   * 🔴 A {@link serverWindow} row is FIXED-height, never measured. A measured list places
+   * every unloaded row at the estimate and every loaded one at its real height, so the page
+   * that arrives above the viewport re-sizes a hundred rows and moves everything under the
+   * reader — measured in the gate: a smooth reveal of row 4,000 that paged in the rows above
+   * it on arrival came to rest thirteen rows short. apps/music's own list held every row at
+   * one height for the same reason ("Fixed row height is what makes the arithmetic jitter-free").
+   */
+  const fixedRowHeight = serverWindow
+    ? (serverWindow.rowHeight ?? virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44))
+    : null;
   const estimateRowHeight =
-    virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44);
+    fixedRowHeight ?? virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44);
   const scrollRef = useRef<HTMLDivElement | null>(null);
+  /** Rows before the loaded window, and the size of the whole result set — both 0/`rows.length`
+   *  without a {@link serverWindow}, which makes every index below the same number as before. */
+  const windowStart = serverWindow ? Math.max(0, serverWindow.start) : 0;
+  const windowTotal = serverWindow ? Math.max(serverWindow.total, windowStart + rows.length) : rows.length;
+  /** The caller's window callbacks, read at FIRE time: by the time a settle timer fires the
+   *  window may have moved, and the fresh handler is the one that knows. */
+  const windowRef = useRef(serverWindow);
+  windowRef.current = serverWindow;
+  const loadedRef = useRef({ start: windowStart, end: windowStart + rows.length, total: windowTotal });
+  loadedRef.current = { start: windowStart, end: windowStart + rows.length, total: windowTotal };
+  const settleRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  /** The `scrollTop` the last `onChange` saw. The virtualizer also calls `onChange` when its
+   *  is-scrolling flag resets and on every re-render; only a MOVE may arm the settle timer, or
+   *  the flag's own reset re-asks for the window that was just requested (measured: twice). */
+  const lastTopRef = useRef<number | null>(null);
+  useEffect(
+    () => () => {
+      if (settleRef.current) clearTimeout(settleRef.current);
+    },
+    [],
+  );
   const rowVirtualizer = useVirtualizer({
-    count: virtualEnabled ? rows.length : 0,
+    count: virtualEnabled ? windowTotal : 0,
     getScrollElement: () => scrollRef.current,
     estimateSize: () => estimateRowHeight,
     overscan: virtualOptions?.overscan ?? 8,
+    onChange: serverWindow
+      ? (instance) => {
+          const win = windowRef.current;
+          const element = instance.scrollElement;
+          if (!win || !element) return;
+          const { start, end, total } = loadedRef.current;
+          // Rows over the whole result set: the first one on screen, and the one after the last.
+          const items = instance.getVirtualItems();
+          if (items.length === 0) return;
+          const top = element.scrollTop;
+          const bottom = top + element.clientHeight;
+          const firstShown = items.find((item) => item.end > top)?.index ?? items[0]!.index;
+          const lastShown = (items.findLast((item) => item.start < bottom)?.index ?? items.at(-1)!.index) + 1;
+          const moved = lastTopRef.current !== top;
+          lastTopRef.current = top;
+          // Nothing on screen is loaded. Hand the destination over once the scroll RESTS,
+          // and do not also ask for a page — it would load rows nowhere near the reader.
+          if (firstShown >= end || lastShown <= start) {
+            if (!moved) return;
+            if (settleRef.current) clearTimeout(settleRef.current);
+            settleRef.current = setTimeout(() => {
+              settleRef.current = null;
+              // Read at FIRE time: the window may have arrived while the scroll rested.
+              const loaded = loadedRef.current;
+              if (firstShown < loaded.end && lastShown > loaded.start) return;
+              windowRef.current?.onNeedWindow?.(firstShown);
+            }, win.settleMs ?? 120);
+            return;
+          }
+          if (settleRef.current) {
+            clearTimeout(settleRef.current);
+            settleRef.current = null;
+          }
+          // Against the end of the LOADED window, never the spacer's — see the prop doc.
+          if (win.onReachEnd && end < total && end - lastShown < (win.reachRows ?? 20)) win.onReachEnd();
+          // Tighter, and only off row 0: a reveal lands a few rows into a fresh window, and a
+          // generous trigger here would fire on arrival and cascade back to the top.
+          if (win.onReachStart && start > 0 && firstShown - start < (win.reachRowsUp ?? 8)) win.onReachStart();
+        }
+      : undefined,
     // 🔴 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,
+    measureElement: (el) => fixedRowHeight ?? el.getBoundingClientRect().height,
   });
   /**
    * 🔴 Invalidate the measurement cache when the row height changes.
@@ -918,13 +1304,153 @@ export function DataTable<TRow extends Record<string, unknown>>({
   }, [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;
+   *  ones that are not. Off, this is every row and no spacers — byte-identical output.
+   *  `null` is a row a {@link serverWindow} has not loaded: a placeholder of the estimated
+   *  height, so the window can land anywhere in the spacer before its rows arrive. */
+  const bodyRows: (Row<TRow> | null)[] = virtualEnabled
+    ? virtualRows.map((v) => rows[v.index - windowStart] ?? null)
+    : rows;
+  useImperativeHandle(
+    handleRef,
+    () => ({
+      get scrollElement() {
+        return scrollRef.current;
+      },
+      scrollToIndex(index, options = {}) {
+        const element = scrollRef.current;
+        if (!element || !virtualEnabled) return null;
+        const clamped = Math.max(0, Math.min(index, loadedRef.current.total - 1));
+        const [offset] = rowVirtualizer.getOffsetForIndex(clamped, options.align ?? 'center') ?? [clamped * estimateRowHeight];
+        const top = Math.max(0, Math.round(offset));
+        element.scrollTo({ top, behavior: options.behavior ?? 'auto' });
+        return top;
+      },
+    }),
+    [estimateRowHeight, rowVirtualizer, virtualEnabled],
+  );
   const padTop = virtualEnabled ? (virtualRows[0]?.start ?? 0) : 0;
   const padBottom = virtualEnabled
     ? rowVirtualizer.getTotalSize() - (virtualRows.at(-1)?.end ?? 0)
     : 0;
   const hasActions = !!(onRowEdit || onRowDelete || rowMenu);
+
+  // ── Row selection (see the `selectedIds` prop doc) ──────────────────────────
+  const canSelect = (row: TRow) => isRowSelectable?.(row) ?? true;
+  // Select-all's universe: the FILTERED rows across every page, minus the ones
+  // that cannot be selected. `getFilteredRowModel` is pre-pagination by design.
+  const selectableFilteredIds = selectionEnabled
+    ? table
+        .getFilteredRowModel()
+        .rows.filter((row) => canSelect(row.original))
+        .map((row) => row.id)
+    : [];
+  const selectedFilteredCount = selectionEnabled
+    ? selectableFilteredIds.filter((id) => selectedIds.has(id)).length
+    : 0;
+  const headerChecked: boolean | 'indeterminate' =
+    selectedFilteredCount === 0
+      ? false
+      : selectedFilteredCount === selectableFilteredIds.length
+        ? true
+        : 'indeterminate';
+  const toggleRowSelected = (id: string) => {
+    if (!selectedIds) return;
+    const next = new Set(selectedIds);
+    if (next.has(id)) next.delete(id);
+    else next.add(id);
+    onSelectionChange?.(next);
+  };
+  const toggleAllSelected = () => {
+    if (!selectedIds) return;
+    const next = new Set(selectedIds);
+    if (headerChecked === true) for (const id of selectableFilteredIds) next.delete(id);
+    else for (const id of selectableFilteredIds) next.add(id);
+    onSelectionChange?.(next);
+  };
+  const labelForSelection = (row: TRow): string => {
+    if (selectionLabel) return selectionLabel(row);
+    const first = liveColumns[0];
+    const value = first ? readPath(row, first.key) : undefined;
+    const text = first?.displayValue ? first.displayValue(value, row) : filterableText(value);
+    return `Select ${text || 'row'}`;
+  };
+  const selectAllLabel = `Select all ${selectableFilteredIds.length} rows`;
+  /** One row's checkbox — the same control in every tier. */
+  const rowCheckbox = (row: Row<TRow>): ReactNode => {
+    if (!selectedIds) return null;
+    const selectable = canSelect(row.original);
+    const box = (
+      <Checkbox
+        checked={selectedIds.has(row.id)}
+        disabled={!selectable}
+        onCheckedChange={() => toggleRowSelected(row.id)}
+        aria-label={labelForSelection(row.original)}
+      />
+    );
+    if (selectable) return box;
+    // A disabled button fires no pointer events, so the reason hangs off a
+    // wrapper — visible and explained, never hidden (the owner UI rule).
+    return (
+      <Tooltip content={unselectableReason?.(row.original) ?? "This row can't be selected"} mobile='tap'>
+        <span data-cb-unselectable='' className='inline-flex'>
+          {box}
+        </span>
+      </Tooltip>
+    );
+  };
+  /**
+   * The whole cell toggles, not just the 16px box — generous hit target. A click
+   * that landed on the checkbox's own `<label>` has already toggled it, so only
+   * the padding around it is handled here. Propagation stops either way so a
+   * selection click is never also the row click.
+   */
+  const selectCellProps = (row: Row<TRow>) => ({
+    'data-cb-select-cell': '',
+    onClick: (event: MouseEvent<HTMLElement>) => {
+      event.stopPropagation();
+      if ((event.target as Element).closest('label')) return;
+      if (canSelect(row.original)) toggleRowSelected(row.id);
+    },
+    // Space/Enter on the focused checkbox must not bubble into the row's
+    // Enter-to-open handler.
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => event.stopPropagation(),
+  });
+  const headerCheckbox = (label?: ReactNode) =>
+    selectAll ? (
+      // The caller's box (see `selectAll`). 🔴 The Tooltip wraps a SPAN, never the Checkbox:
+      // a Radix trigger clones its child with its own `data-state`, which would overwrite the
+      // one the box paints its tick and its `Minus` from (apps/music measured it, 2026-09-19).
+      <Tooltip content={selectAll.label}>
+        <span className='inline-flex'>
+          <Checkbox
+            checked={selectAll.checked}
+            disabled={selectAll.disabled}
+            onCheckedChange={(checked) => selectAll.onChange(checked === true)}
+            aria-label={selectAll.label}
+            label={label}
+            labelClassName={label == null ? undefined : 'text-xs text-muted-foreground'}
+          />
+        </span>
+      </Tooltip>
+    ) : (
+    <Checkbox
+      checked={headerChecked}
+      disabled={selectableFilteredIds.length === 0}
+      onCheckedChange={toggleAllSelected}
+      aria-label={selectAllLabel}
+      label={label}
+      labelClassName={label == null ? undefined : 'text-xs text-muted-foreground'}
+    />
+  );
+  const summaryNode =
+    selectedIds && selectionSummary
+      ? selectionSummary(
+          resolvedGetRowId
+            ? data.filter((row) => selectedIds.has(resolvedGetRowId(row)))
+            : [],
+        )
+      : null;
+
   const toolbarNode =
     typeof toolbar === 'function'
       ? toolbar(table)
@@ -936,8 +1462,15 @@ export function DataTable<TRow extends Record<string, unknown>>({
         // 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);
+        (searchable ? (
+          <ToolbarPart
+            table={table}
+            searchPlaceholder={searchPlaceholder}
+            fallback={<ToolbarPlaceholder />}
+          />
+        ) : null));
+  const visibleColumnCount =
+    table.getVisibleLeafColumns().length + (hasActions ? 1 : 0) + (selectionEnabled ? 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);
@@ -950,7 +1483,10 @@ export function DataTable<TRow extends Record<string, unknown>>({
   // columns missing rather than one that scrolls (`useScrollEdgeFade`).
   const gridFade = useScrollEdgeFade();
   const tableMinWidth = fixedLayout
-    ? Math.max(minTableWidth ?? 0, declaredTrackFloor(cardColumns, hasActions))
+    ? Math.max(
+        minTableWidth ?? 0,
+        declaredTrackFloor(cardColumns, hasActions) + (selectionEnabled ? SELECT_TRACK_PX : 0),
+      )
     : minTableWidth;
 
   return (
@@ -959,6 +1495,18 @@ export function DataTable<TRow extends Record<string, unknown>>({
     <div className={cn('@container flex min-h-0 flex-col', className)}>
       {toolbarNode}
 
+      {summaryNode != null ? (
+        // The selection's own line of chrome: the app's "12 games · 38 MB" and
+        // its bulk actions. `aria-live` so the count is announced as it changes.
+        <div
+          data-cb-table-selection-summary=''
+          aria-live='polite'
+          className='flex min-h-11 flex-wrap items-center gap-3 border-b border-border px-4 py-2 text-sm'
+        >
+          {summaryNode}
+        </div>
+      ) : null}
+
       {loading ? (
         <div className='flex flex-col gap-2 p-4'>
           {Array.from({ length: 5 }).map((_, i) => (
@@ -966,19 +1514,36 @@ export function DataTable<TRow extends Record<string, unknown>>({
             <Skeleton key={`dt-skeleton-${i}`} className='h-10 w-full' />
           ))}
         </div>
-      ) : rows.length === 0 ? (
+      ) : rows.length === 0 && windowTotal === 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')}>
+        // `data-cb-table-scroll` names the box when it IS the scroller — the table's own, the way
+        // `ScrollArea` stamps `data-cb-scrollarea`, so a layout check can tell the design system's
+        // scroller from a hand-rolled `overflow: auto` wearing the same class (forge task 2302).
+        <div
+          ref={scrollRef}
+          data-cb-table-scroll={bodyScrolls ? '' : undefined}
+          // guardrails-ignore no-raw-overflow: dual-axis table scroll container — sticky header pins to it; ScrollArea cannot own horizontal table scroll.
+          className={cn(bodyScrolls && 'min-h-0 flex-1 overflow-auto', scrollClassName)}
+        >
           {/* ── 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. ── */}
+          {/* Select-all for the tiers with no header row to carry it: the phone
+              cards, and the card view at every width. */}
+          {selectionEnabled && (viewMode === 'card' || mobileCards) ? (
+            <div
+              data-cb-table-select-all=''
+              className={cn('flex items-center px-2 py-1', viewMode !== 'card' && '@xl:hidden')}
+            >
+              {headerCheckbox('Select all')}
+            </div>
+          ) : null}
           {viewMode === 'card' ? (
             <CardView
               columns={cardColumns}
@@ -986,6 +1551,14 @@ export function DataTable<TRow extends Record<string, unknown>>({
               getRowId={getRowId}
               onRowClick={onRowClick}
               dragPropsFor={getRowDrag ? dragPropsFor : undefined}
+              selectFor={
+                selectionEnabled
+                  ? (_row, index) => {
+                      const tsRow = rows[index];
+                      return tsRow ? rowCheckbox(tsRow) : null;
+                    }
+                  : undefined
+              }
               cardMinWidth={cardMinWidth}
               className='p-2'
             />
@@ -1001,7 +1574,8 @@ export function DataTable<TRow extends Record<string, unknown>>({
                   columns={cardColumns}
                   className={rowClassName?.(row.original)}
                   onRowClick={onRowClick}
-                  dragProps={dragPropsFor(row.original)}
+                  dragProps={mergeRowProps(dragPropsFor(row.original), getRowProps?.(row.original, windowStart + row.index))}
+                  select={selectionEnabled ? rowCheckbox(row) : undefined}
                   actions={
                     hasActions ? (
                       <RowActions
@@ -1047,6 +1621,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                 // absent (the header) and every preceding lane drifts ~32px off
                 // its label — the v4 judge's tablet misalignment finding.
                 const template = [
+                  ...(selectionEnabled ? ['44px'] : []),
                   'minmax(0,1fr)',
                   ...rest.map(trackOf),
                   ...(hasActions ? ['32px'] : []),
@@ -1061,6 +1636,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                     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 }}
                   >
+                    {selectionEnabled ? <span className='flex justify-center'>{headerCheckbox()}</span> : null}
                     <span>{title?.label ?? ''}</span>
                     {rest.map((col) => (
                       <span key={col.key} className={cn(resolveColumnAlign(col) === 'right' && 'text-right')}>
@@ -1076,14 +1652,24 @@ export function DataTable<TRow extends Record<string, unknown>>({
                   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),
+                        {...mergeRowProps(
+                          {
+                            ...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 },
+                          },
+                          getRowProps?.(row.original, windowStart + row.index),
                         )}
-                        style={{ gridTemplateColumns: template }}
                       >
+                        {selectionEnabled ? (
+                          <div {...selectCellProps(row)} className='-my-3 flex self-stretch items-center justify-center'>
+                            {rowCheckbox(row)}
+                          </div>
+                        ) : null}
                         <div className='min-w-0'>
                           {title ? (
                             <CellRenderer
@@ -1154,7 +1740,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
               <thead>
                 {table.getHeaderGroups().map((hg) => (
                   <tr key={hg.id}>
-                    {hg.headers.map((h, headerIndex) => {
+                    {(() => {
+                      // `ColDef.leading` columns sit BEFORE the checkbox column; see its doc.
+                      const renderHeader = (h: (typeof hg.headers)[number], headerIndex: number) => {
                       const sorted = h.column.getIsSorted();
                       const meta = h.column.columnDef.meta;
                       const width = meta?.width ?? h.column.columnDef.size;
@@ -1193,8 +1781,11 @@ export function DataTable<TRow extends Record<string, unknown>>({
                             // 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)]',
+                              (selectionEnabled
+                                ? 'sticky left-11 bg-card shadow-[1px_0_0_0_var(--color-border)]'
+                                : 'sticky left-0 bg-card shadow-[1px_0_0_0_var(--color-border)]'),
                             frozen && (stickyHeader ? 'z-30' : 'z-20'),
+                            meta?.hideBelow && HIDE_BELOW_CLASS[meta.hideBelow],
                           )}
                         >
                           {h.isPlaceholder
@@ -1202,7 +1793,28 @@ export function DataTable<TRow extends Record<string, unknown>>({
                             : flexRender(h.column.columnDef.header, h.getContext())}
                         </th>
                       );
-                    })}
+                    };
+                      const isLeading = (h: (typeof hg.headers)[number]) => h.column.columnDef.meta?.leading === true;
+                      return (
+                        <>
+                          {hg.headers.filter(isLeading).map((h) => renderHeader(h, -1))}
+                    {selectionEnabled ? (
+                      <th
+                        scope='col'
+                        className={cn(
+                          'w-11 border-b border-border px-0 text-center',
+                          stickyHeader && 'sticky top-0 z-10 bg-card/95 backdrop-blur-sm',
+                          stickyFirstColumn && 'sticky left-0 bg-card',
+                          stickyFirstColumn && (stickyHeader ? 'z-30' : 'z-20'),
+                        )}
+                      >
+                        {headerCheckbox()}
+                      </th>
+                    ) : null}
+                          {hg.headers.filter((h) => !isLeading(h)).map(renderHeader)}
+                        </>
+                      );
+                    })()}
                     {hasActions ? (
                       <th
                         className={cn(
@@ -1226,6 +1838,25 @@ export function DataTable<TRow extends Record<string, unknown>>({
                   </tr>
                 ) : null}
                 {bodyRows.map((row, sliceIndex) => {
+                  if (row === null) {
+                    // A row the server window has not loaded yet: the estimated height, so
+                    // the spacer arithmetic holds, and a skeleton line rather than a gap.
+                    const index = virtualRows[sliceIndex]!.index;
+                    return (
+                      <tr
+                        key={`cb-placeholder-${index}`}
+                        data-index={index}
+                        data-cb-placeholder=''
+                        aria-hidden
+                        className={cn('border-b border-border', index % 2 === 1 && 'bg-muted/50')}
+                        style={{ height: estimateRowHeight }}
+                      >
+                        <td colSpan={visibleColumnCount} className='px-3'>
+                          <Skeleton className='h-3' style={{ width: '40%' }} />
+                        </td>
+                      </tr>
+                    );
+                  }
                   /* 🔴 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
@@ -1240,12 +1871,14 @@ export function DataTable<TRow extends Record<string, unknown>>({
                         // 🔴 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(
+                        // (The ref stays OUT of the merge: `getRowProps` cannot take it.)
+                        ref={virtualEnabled && fixedRowHeight === null ? rowVirtualizer.measureElement : undefined}
+                        {...mergeRowProps({
+                        ...(virtualEnabled ? { 'data-index': rowIndex } : {}),
+                        style: fixedRowHeight === null ? undefined : { height: fixedRowHeight },
+                        '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
@@ -1259,18 +1892,20 @@ export function DataTable<TRow extends Record<string, unknown>>({
                           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
-                        }
+                        ),
+                        tabIndex: onRowClick ? 0 : undefined,
+                        onClick: onRowClick ? (event: MouseEvent<HTMLElement>) => onRowClick(row.original, event) : undefined,
+                        onKeyDown: onRowClick
+                          ? (e: KeyboardEvent<HTMLElement>) => {
+                              if (e.key === 'Enter') onRowClick(row.original);
+                            }
+                          : undefined,
+                        }, getRowProps?.(row.original, rowIndex))}
                       >
-                        {row.getVisibleCells().map((cell, cellIndex) => {
+                        {(() => {
+                          const cells = row.getVisibleCells();
+                          const isLeading = (cell: (typeof cells)[number]) => cell.column.columnDef.meta?.leading === true;
+                          const renderCell = (cell: (typeof cells)[number], cellIndex: number) => {
                           const frozen = stickyFirstColumn === true && cellIndex === 0;
                           return (
                           <td
@@ -1294,7 +1929,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
                               'px-4 align-middle',
                               cellPadY,
                               frozen &&
-                                'sticky left-0 z-10 bg-[var(--cb-frozen-bg)] shadow-[1px_0_0_0_var(--color-border)]',
+                                (selectionEnabled
+                                  ? 'sticky left-11 z-10 bg-[var(--cb-frozen-bg)] shadow-[1px_0_0_0_var(--color-border)]'
+                                  : '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.
@@ -1303,14 +1940,43 @@ export function DataTable<TRow extends Record<string, unknown>>({
                               // `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',
+                              cell.column.columnDef.meta?.align === 'right' && 'text-right',
+                              cell.column.columnDef.meta?.hideBelow &&
+                                HIDE_BELOW_CLASS[cell.column.columnDef.meta.hideBelow],
                             )}
                           >
                             {flexRender(cell.column.columnDef.cell, cell.getContext())}
                           </td>
                           );
-                        })}
+                        };
+                          return (
+                            <>
+                              {cells.filter(isLeading).map((cell) => renderCell(cell, -1))}
+                        {selectionEnabled ? (
+                          <td
+                            {...selectCellProps(row)}
+                            style={
+                              stickyFirstColumn
+                                ? ({
+                                    '--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(
+                              'w-11 cursor-pointer px-0 text-center align-middle',
+                              stickyFirstColumn && 'sticky left-0 z-10 bg-[var(--cb-frozen-bg)]',
+                            )}
+                          >
+                            {rowCheckbox(row)}
+                          </td>
+                        ) : null}
+                              {cells.filter((cell) => !isLeading(cell)).map(renderCell)}
+                            </>
+                          );
+                        })()}
                         {hasActions ? (
                           <td className='px-2 py-2'>
                             <RowActions
@@ -1371,7 +2037,11 @@ export function DataTable<TRow extends Record<string, unknown>>({
       )}
 
       {!loading && rows.length > 0 && !paginationHidden ? (
-        <TablePagination table={table} pageSizeOptions={pageSizeOptions} />
+        <PaginationPart
+          table={table}
+          pageSizeOptions={pageSizeOptions}
+          fallback={<PaginationPlaceholder />}
+        />
       ) : null}
     </div>
   );
@@ -1390,6 +2060,7 @@ function MobileRowCard<TRow extends Record<string, unknown>>({
   className,
   onRowClick,
   dragProps,
+  select,
   actions,
   expanded,
 }: {
@@ -1397,7 +2068,10 @@ function MobileRowCard<TRow extends Record<string, unknown>>({
   columns: ColDef<TRow>[];
   className?: string;
   onRowClick?: (row: TRow) => void;
-  dragProps?: { draggable?: boolean; onDragStart?: (event: DragEvent<HTMLElement>) => void };
+  /** The drag-source props and the caller's `getRowProps`, already merged. */
+  dragProps?: DataTableRowProps;
+  /** The row's selection checkbox, when the table selects — leads the card. */
+  select?: ReactNode;
   actions: ReactNode;
   expanded: ReactNode;
 }) {
@@ -1457,6 +2131,19 @@ function MobileRowCard<TRow extends Record<string, unknown>>({
     </div>
   );
 
+  const main = 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
+  );
+
   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
@@ -1469,7 +2156,7 @@ function MobileRowCard<TRow extends Record<string, unknown>>({
       pad='sm'
       radius='lg'
       {...dragProps}
-      className={cn('relative isolate', dragProps?.draggable && 'cursor-grab', className)}
+      className={cn('relative isolate', dragProps?.draggable && 'cursor-grab', className, dragProps?.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
@@ -1478,17 +2165,14 @@ function MobileRowCard<TRow extends Record<string, unknown>>({
           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
+      {select == null ? main : (
+        // The checkbox leads the card, OUTSIDE the tap target, so ticking a row
+        // never also opens it. `-mt-2 -ml-2` lets the 44px coarse-pointer target
+        // sit in the card's padding rather than pushing the title right.
+        <div className='flex items-start gap-1'>
+          <div className='-mt-2 -ml-2 shrink-0'>{select}</div>
+          <div className='min-w-0 flex-1'>{main}</div>
+        </div>
       )}
       {/* Primary row actions (an actions column) sit in a bordered footer strip
           contained inside the card bounds — the one hairline a card carries (owner