cursedbelt 5.23.0 → 5.26.0

package/dist/react/components/DataTable/DataTable.js

@@ -1,22 +1,52 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { flexRender, getCoreRowModel, getFilteredRowModel, getPaginationRowModel, getSortedRowModel, useReactTable, } from '@tanstack/react-table';
 import { useVirtualizer } from '@tanstack/react-virtual';
-import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Fragment, 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 { 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 { EMPTY_FILTER_QUERY, evaluateFilterQuery, filterableText, } from './filterQuery.js';
-import { TablePagination } from './Pagination.js';
-import { RowActions } from './RowActions.js';
+import { preloadRowMenu, RowActions } from './RowActions.js';
 import { writeRowDrag } from './rowDrag.js';
 import { SortHeader } from './SortHeader.js';
-import { TableToolbar } from './Toolbar.js';
 import { resolveColumnAlign } from './types.js';
+import { lazyPart } from './lazyPart.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));
+const PaginationPart = lazyPart(() => import('./Pagination.js').then((m) => m.TablePagination));
+/**
+ * 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() {
+    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 (_jsx("div", { "data-cb-table-toolbar-pending": '', "aria-hidden": true, className: 'border-b border-border px-2 py-2', children: _jsx("div", { className: cn('h-9', TAP_TARGET_HEIGHT) }) }));
+}
+/** Where the pager will be, the height it will be. */
+function PaginationPlaceholder() {
+    return (_jsx("div", { "data-cb-table-pagination-pending": '', "aria-hidden": true, className: 'border-t border-border px-4 py-2.5', children: _jsx("div", { className: cn('h-8', TAP_TARGET_HEIGHT) }) }));
+}
 /** Build an OnChangeFn that updates local state AND notifies an optional listener. */
 function chainUpdater(set, notify) {
     return (updater) => set((prev) => {
@@ -45,6 +75,8 @@ function chainUpdaterResettingPage(set, setPagination, notify) {
 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
  * columns declared: the sum of every visible column's floor (`minWidth`, else a
@@ -115,15 +147,16 @@ export function declaredTrackFloor(columns, hasActions = false) {
  * 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, id, multi) {
+export function nextSortStack(current, id, multi, options = {}) {
+    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) : [];
 }
@@ -142,6 +175,48 @@ function readPath(row, key) {
         return value[part];
     }, 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',
+};
+/**
+ * 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(own, extra) {
+    if (!extra)
+        return own;
+    const merged = { ...own, ...extra };
+    if (own.className || extra.className)
+        merged.className = cn(own.className, extra.className);
+    if (own.style || extra.style)
+        merged.style = { ...own.style, ...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) => {
+            mine(event);
+            handler(event);
+        };
+    }
+    return merged;
+}
 /** True when a cell value carries nothing worth a column: null/undefined/''/[]. */
 function isEmptyCellValue(v) {
     if (v == null)
@@ -165,11 +240,15 @@ function isEmptyCellValue(v) {
  * 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({ 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, }) {
+export function DataTable({ 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, serverWindow, handleRef, scrollClassName, mobileCards = true, serverSide, pageCount, rowCount, onSortingChange, onColumnFiltersChange, onGlobalFilterChange, onPaginationChange, defaultSort, sorting: sortingProp, enableSortingRemoval = true, sortDisabledReason, density = 'comfortable', viewMode, onViewModeChange, cardMinWidth, searchable = true, searchPlaceholder, multiSort = true, filterQuery: filterQueryProp, onFilterQueryChange, getRowDrag, dragSourceId, selectedIds, onSelectionChange, isRowSelectable, unselectableReason, selectionLabel, selectionSummary, selectAll, getRowProps, }) {
     // 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(defaultSort ?? []);
+    const [ownSorting, setOwnSorting] = useState(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([]);
     const [globalFilter, setGlobalFilter] = useState('');
     const [columnVisibility, setColumnVisibility] = useState(() => Object.fromEntries(columns.filter((c) => c.hidden).map((c) => [c.key, false])));
@@ -223,14 +302,17 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
      * server-side table ends up sorted differently from what its chips say.
      */
     const applySorting = useCallback((next) => {
-        setSorting((prev) => {
-            const value = next(prev);
-            setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
-            onSortingChange?.(value);
-            return value;
-        });
-    }, [onSortingChange]);
-    const toggleSortKey = useCallback((id) => applySorting((prev) => nextSortStack(prev, id, multiSort)), [applySorting, multiSort]);
+        // 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, sortingProp]);
+    const sortDescFirstOf = useCallback((id) => columns.find((col) => col.key === id)?.sortDescFirst ?? false, [columns]);
+    const toggleSortKey = useCallback((id) => applySorting((prev) => nextSortStack(prev, id, multiSort, { descFirst: sortDescFirstOf(id), removable: enableSortingRemoval })), [applySorting, enableSortingRemoval, multiSort, sortDescFirstOf]);
     const tsColumns = useMemo(() => liveColumns.map((col) => ({
         id: col.key,
         accessorKey: col.key,
@@ -241,6 +323,8 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
             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,
@@ -262,10 +346,10 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
         // TanStack's column instances mid-interaction.
         header: ({ column, table: t }) => {
             const stack = t.getState().sorting;
-            return (_jsx(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) }));
+            return (_jsx(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), disabledReason: sortDisabledReason }));
         },
         cell: ({ getValue, row }) => (_jsx(CellRenderer, { col: col, value: getValue(), row: row.original, onEdit: onRowEdit ? () => onRowEdit(row.original) : undefined })),
-    })), [liveColumns, onRowEdit, toggleSortKey]);
+    })), [liveColumns, onRowEdit, sortDisabledReason, toggleSortKey]);
     const labelOf = useCallback((id) => liveColumns.find((col) => col.key === id)?.label ?? id, [liveColumns]);
     const controls = useMemo(() => ({
         searchText: globalFilter,
@@ -317,16 +401,28 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
      * 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) => 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.
@@ -354,14 +450,16 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
                 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(),
@@ -399,17 +497,94 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
         };
     };
     const rows = table.getRowModel().rows;
-    const estimateRowHeight = virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44);
+    /**
+     * 🔴 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 = fixedRowHeight ?? virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44);
     const scrollRef = useRef(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(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(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.
@@ -433,13 +608,118 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
     }, [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 = 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) => 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 = selectedFilteredCount === 0
+        ? false
+        : selectedFilteredCount === selectableFilteredIds.length
+            ? true
+            : 'indeterminate';
+    const toggleRowSelected = (id) => {
+        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) => {
+        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) => {
+        if (!selectedIds)
+            return null;
+        const selectable = canSelect(row.original);
+        const box = (_jsx(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 (_jsx(Tooltip, { content: unselectableReason?.(row.original) ?? "This row can't be selected", mobile: 'tap', children: _jsx("span", { "data-cb-unselectable": '', className: 'inline-flex', children: box }) }));
+    };
+    /**
+     * 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) => ({
+        'data-cb-select-cell': '',
+        onClick: (event) => {
+            event.stopPropagation();
+            if (event.target.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) => event.stopPropagation(),
+    });
+    const headerCheckbox = (label) => selectAll ? (_jsx(Tooltip, { content: selectAll.label, children: _jsx("span", { className: 'inline-flex', children: _jsx(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' }) }) })) : (_jsx(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)
         : (toolbar ??
@@ -450,8 +730,8 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
             // 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 ? _jsx(TableToolbar, { table: table, searchPlaceholder: searchPlaceholder }) : null));
-    const visibleColumnCount = table.getVisibleLeafColumns().length + (hasActions ? 1 : 0);
+            (searchable ? (_jsx(ToolbarPart, { table: table, searchPlaceholder: searchPlaceholder, fallback: _jsx(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);
@@ -464,9 +744,16 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
     // 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 (_jsxs("div", { className: cn('@container flex min-h-0 flex-col', className), children: [toolbarNode, loading ? (_jsx("div", { className: 'flex flex-col gap-2 p-4', children: Array.from({ length: 5 }).map((_, i) => (_jsx(Skeleton, { className: 'h-10 w-full' }, `dt-skeleton-${i}`))) })) : rows.length === 0 ? (_jsx("div", { className: 'p-2', children: emptyState ?? _jsx(EmptyState, { title: 'No results' }) })) : (_jsxs("div", { ref: scrollRef, className: cn(bodyScrolls && 'min-h-0 flex-1 overflow-auto'), children: [viewMode === 'card' ? (_jsx(CardView, { columns: cardColumns, data: rows.map((row) => row.original), getRowId: getRowId, onRowClick: onRowClick, dragPropsFor: getRowDrag ? dragPropsFor : undefined, cardMinWidth: cardMinWidth, className: 'p-2' })) : (_jsxs(_Fragment, { children: [mobileCards && (_jsx("div", { "data-cb-table-cards": '', className: 'flex flex-col gap-3 @xl:hidden', children: rows.map((row) => (_jsx(MobileRowCard, { row: row, columns: cardColumns, className: rowClassName?.(row.original), onRowClick: onRowClick, dragProps: dragPropsFor(row.original), actions: hasActions ? (_jsx(RowActions, { row: row.original, onEdit: onRowEdit, onDelete: onRowDelete, menu: rowMenu?.(row.original) })) : null, expanded: renderExpanded && expandedRowId != null && row.id === expandedRowId
+    return (_jsxs("div", { className: cn('@container flex min-h-0 flex-col', className), children: [toolbarNode, summaryNode != null ? (_jsx("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', children: summaryNode })) : null, loading ? (_jsx("div", { className: 'flex flex-col gap-2 p-4', children: Array.from({ length: 5 }).map((_, i) => (_jsx(Skeleton, { className: 'h-10 w-full' }, `dt-skeleton-${i}`))) })) : rows.length === 0 && windowTotal === 0 ? (_jsx("div", { className: 'p-2', children: emptyState ?? _jsx(EmptyState, { title: 'No results' }) })) : (_jsxs("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), children: [selectionEnabled && (viewMode === 'card' || mobileCards) ? (_jsx("div", { "data-cb-table-select-all": '', className: cn('flex items-center px-2 py-1', viewMode !== 'card' && '@xl:hidden'), children: headerCheckbox('Select all') })) : null, viewMode === 'card' ? (_jsx(CardView, { columns: cardColumns, data: rows.map((row) => row.original), 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' })) : (_jsxs(_Fragment, { children: [mobileCards && (_jsx("div", { "data-cb-table-cards": '', className: 'flex flex-col gap-3 @xl:hidden', children: rows.map((row) => (_jsx(MobileRowCard, { row: row, columns: cardColumns, className: rowClassName?.(row.original), onRowClick: onRowClick, dragProps: mergeRowProps(dragPropsFor(row.original), getRowProps?.(row.original, windowStart + row.index)), select: selectionEnabled ? rowCheckbox(row) : undefined, actions: hasActions ? (_jsx(RowActions, { row: row.original, onEdit: onRowEdit, onDelete: onRowDelete, menu: rowMenu?.(row.original) })) : null, expanded: renderExpanded && expandedRowId != null && row.id === expandedRowId
                                         ? renderExpanded(row.original)
                                         : null }, row.id))) })), mobileCards && (_jsx("div", { "data-cb-table-list": '', className: 'hidden @xl:block @3xl:hidden', children: (() => {
                                     const [title, ...rest] = cardColumns;
@@ -488,49 +775,67 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
                                     // 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'] : []),
                                     ].join(' ');
-                                    const header = (_jsxs("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 }, children: [_jsx("span", { children: title?.label ?? '' }), rest.map((col) => (_jsx("span", { className: cn(resolveColumnAlign(col) === 'right' && 'text-right'), children: col.label }, col.key))), hasActions ? _jsx("span", { "aria-hidden": true }) : null] }));
+                                    const header = (_jsxs("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 }, children: [selectionEnabled ? _jsx("span", { className: 'flex justify-center', children: headerCheckbox() }) : null, _jsx("span", { children: title?.label ?? '' }), rest.map((col) => (_jsx("span", { className: cn(resolveColumnAlign(col) === 'right' && 'text-right'), children: col.label }, col.key))), hasActions ? _jsx("span", { "aria-hidden": true }) : null] }));
                                     const body = rows.map((row) => {
                                         const isExpanded = renderExpanded != null && expandedRowId != null && row.id === expandedRowId;
-                                        return (_jsxs(Fragment, { children: [_jsxs("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 }, children: [_jsx("div", { className: 'min-w-0', children: title ? (_jsx(CellRenderer, { col: title, value: row.original[title.key], row: row.original })) : null }), rest.map((col) => (_jsx("div", { className: cn(resolveColumnAlign(col) === 'right' && 'justify-self-end text-right'), children: _jsx(CellRenderer, { col: col, value: row.original[col.key], row: row.original }) }, col.key))), hasActions ? (_jsx(RowActions, { row: row.original, onEdit: onRowEdit, onDelete: onRowDelete, menu: rowMenu?.(row.original) })) : null] }), isExpanded ? (_jsx("div", { className: 'bg-muted/20 px-4 pt-1 pb-3', children: _jsx("div", { className: 'rounded-lg border border-border bg-card p-3 shadow-raised', children: renderExpanded(row.original) }) })) : null] }, row.id));
+                                        return (_jsxs(Fragment, { children: [_jsxs("div", { ...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)), children: [selectionEnabled ? (_jsx("div", { ...selectCellProps(row), className: '-my-3 flex self-stretch items-center justify-center', children: rowCheckbox(row) })) : null, _jsx("div", { className: 'min-w-0', children: title ? (_jsx(CellRenderer, { col: title, value: row.original[title.key], row: row.original })) : null }), rest.map((col) => (_jsx("div", { className: cn(resolveColumnAlign(col) === 'right' && 'justify-self-end text-right'), children: _jsx(CellRenderer, { col: col, value: row.original[col.key], row: row.original }) }, col.key))), hasActions ? (_jsx(RowActions, { row: row.original, onEdit: onRowEdit, onDelete: onRowDelete, menu: rowMenu?.(row.original) })) : null] }), isExpanded ? (_jsx("div", { className: 'bg-muted/20 px-4 pt-1 pb-3', children: _jsx("div", { className: 'rounded-lg border border-border bg-card p-3 shadow-raised', children: renderExpanded(row.original) }) })) : null] }, row.id));
                                     });
                                     return (_jsxs(_Fragment, { children: [header, _jsx("div", { className: 'divide-y divide-border', children: body })] }));
                                 })() })), _jsx("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'), children: _jsxs("table", { className: cn('w-full border-collapse text-sm', fixedLayout && 'table-fixed'), style: tableMinWidth != null ? { minWidth: tableMinWidth } : undefined, children: [caption ? _jsx("caption", { className: 'sr-only', children: caption }) : null, _jsx("thead", { children: table.getHeaderGroups().map((hg) => (_jsxs("tr", { children: [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 (_jsx("th", { 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')), children: h.isPlaceholder
-                                                                ? null
-                                                                : flexRender(h.column.columnDef.header, h.getContext()) }, h.id));
-                                                    }), hasActions ? (_jsx("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] }, hg.id))) }), _jsxs("tbody", { children: [padTop > 0 ? (_jsx("tr", { "aria-hidden": true, style: { height: padTop }, children: _jsx("td", { colSpan: visibleColumnCount }) })) : null, bodyRows.map((row, sliceIndex) => {
+                                className: cn(!bodyScrolls && 'overflow-x-auto', mobileCards && 'hidden @3xl:block'), children: _jsxs("table", { className: cn('w-full border-collapse text-sm', fixedLayout && 'table-fixed'), style: tableMinWidth != null ? { minWidth: tableMinWidth } : undefined, children: [caption ? _jsx("caption", { className: 'sr-only', children: caption }) : null, _jsx("thead", { children: table.getHeaderGroups().map((hg) => (_jsxs("tr", { children: [(() => {
+                                                        // `ColDef.leading` columns sit BEFORE the checkbox column; see its doc.
+                                                        const renderHeader = (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 (_jsx("th", { 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 &&
+                                                                    (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]), children: h.isPlaceholder
+                                                                    ? null
+                                                                    : flexRender(h.column.columnDef.header, h.getContext()) }, h.id));
+                                                        };
+                                                        const isLeading = (h) => h.column.columnDef.meta?.leading === true;
+                                                        return (_jsxs(_Fragment, { children: [hg.headers.filter(isLeading).map((h) => renderHeader(h, -1)), selectionEnabled ? (_jsx("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')), children: headerCheckbox() })) : null, hg.headers.filter((h) => !isLeading(h)).map(renderHeader)] }));
+                                                    })(), hasActions ? (_jsx("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] }, hg.id))) }), _jsxs("tbody", { children: [padTop > 0 ? (_jsx("tr", { "aria-hidden": true, style: { height: padTop }, children: _jsx("td", { colSpan: visibleColumnCount }) })) : 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 (_jsx("tr", { "data-index": index, "data-cb-placeholder": '', "aria-hidden": true, className: cn('border-b border-border', index % 2 === 1 && 'bg-muted/50'), style: { height: estimateRowHeight }, children: _jsx("td", { colSpan: visibleColumnCount, className: 'px-3', children: _jsx(Skeleton, { className: 'h-3', style: { width: '40%' } }) }) }, `cb-placeholder-${index}`));
+                                                    }
                                                     /* 🔴 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
@@ -538,53 +843,78 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
                                                        fault rather than as a guide. */
                                                     const rowIndex = virtualEnabled ? virtualRows[sliceIndex].index : sliceIndex;
                                                     const isExpanded = renderExpanded != null && expandedRowId != null && row.id === expandedRowId;
-                                                    return (_jsxs(Fragment, { children: [_jsxs("tr", { ...(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, children: [row.getVisibleCells().map((cell, cellIndex) => {
-                                                                        const frozen = stickyFirstColumn === true && cellIndex === 0;
-                                                                        return (_jsx("td", { 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)',
-                                                                                }
-                                                                                : 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
-                                                                                ?.align === 'right' && 'text-right'), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id));
-                                                                    }), hasActions ? (_jsx("td", { className: 'px-2 py-2', children: _jsx(RowActions, { row: row.original, onEdit: onRowEdit, onDelete: onRowDelete, menu: rowMenu?.(row.original) }) })) : null] }), isExpanded ? (_jsx("tr", { className: 'border-b border-border bg-muted/20', ref: (el) => {
+                                                    return (_jsxs(Fragment, { children: [_jsxs("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.
+                                                                // (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
+                                                                    // 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 ? (event) => onRowClick(row.original, event) : undefined,
+                                                                    onKeyDown: onRowClick
+                                                                        ? (e) => {
+                                                                            if (e.key === 'Enter')
+                                                                                onRowClick(row.original);
+                                                                        }
+                                                                        : undefined,
+                                                                }, getRowProps?.(row.original, rowIndex)), children: [(() => {
+                                                                        const cells = row.getVisibleCells();
+                                                                        const isLeading = (cell) => cell.column.columnDef.meta?.leading === true;
+                                                                        const renderCell = (cell, cellIndex) => {
+                                                                            const frozen = stickyFirstColumn === true && cellIndex === 0;
+                                                                            return (_jsx("td", { 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)',
+                                                                                    }
+                                                                                    : undefined, className: cn('px-4 align-middle', cellPadY, frozen &&
+                                                                                    (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.
+                                                                                // 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?.align === 'right' && 'text-right', cell.column.columnDef.meta?.hideBelow &&
+                                                                                    HIDE_BELOW_CLASS[cell.column.columnDef.meta.hideBelow]), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id));
+                                                                        };
+                                                                        return (_jsxs(_Fragment, { children: [cells.filter(isLeading).map((cell) => renderCell(cell, -1)), selectionEnabled ? (_jsx("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)',
+                                                                                        }
+                                                                                        : undefined, className: cn('w-11 cursor-pointer px-0 text-center align-middle', stickyFirstColumn && 'sticky left-0 z-10 bg-[var(--cb-frozen-bg)]'), children: rowCheckbox(row) })) : null, cells.filter((cell) => !isLeading(cell)).map(renderCell)] }));
+                                                                    })(), hasActions ? (_jsx("td", { className: 'px-2 py-2', children: _jsx(RowActions, { row: row.original, onEdit: onRowEdit, onDelete: onRowDelete, menu: rowMenu?.(row.original) }) })) : null] }), isExpanded ? (_jsx("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' });
                                                                     }
                                                                 }, children: _jsx("td", { colSpan: visibleColumnCount, className: 'p-0', children: _jsx("div", { className: 'animate-in fade-in slide-in-from-top-1 px-4 pt-1 pb-3 duration-200', children: _jsx("div", { className: 'rounded-lg border border-border bg-card p-3 shadow-raised', children: renderExpanded(row.original) }) }) }) })) : null] }, row.id));
-                                                }), padBottom > 0 ? (_jsx("tr", { "aria-hidden": true, style: { height: padBottom }, children: _jsx("td", { colSpan: visibleColumnCount }) })) : null] })] }) })] })), bodyScrolls && (_jsx("div", { "aria-hidden": true, className: 'pointer-events-none sticky bottom-0 -mt-6 h-6 w-full bg-gradient-to-t from-card to-transparent' }))] })), !loading && rows.length > 0 && !paginationHidden ? (_jsx(TablePagination, { table: table, pageSizeOptions: pageSizeOptions })) : null] }));
+                                                }), padBottom > 0 ? (_jsx("tr", { "aria-hidden": true, style: { height: padBottom }, children: _jsx("td", { colSpan: visibleColumnCount }) })) : null] })] }) })] })), bodyScrolls && (_jsx("div", { "aria-hidden": true, className: 'pointer-events-none sticky bottom-0 -mt-6 h-6 w-full bg-gradient-to-t from-card to-transparent' }))] })), !loading && rows.length > 0 && !paginationHidden ? (_jsx(PaginationPart, { table: table, pageSizeOptions: pageSizeOptions, fallback: _jsx(PaginationPlaceholder, {}) })) : null] }));
 }
 /**
  * One row rendered as a phone card: first visible column = the title zone (unlabeled,
@@ -593,7 +923,7 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
  * 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({ row, columns, className, onRowClick, dragProps, actions, expanded, }) {
+function MobileRowCard({ row, columns, className, onRowClick, dragProps, select, actions, expanded, }) {
     const visible = columns.filter((c) => !c.hidden);
     const [title, ...rest] = visible;
     const footer = rest.filter((c) => c.cardFooter || c.label === '');
@@ -606,6 +936,7 @@ function MobileRowCard({ row, columns, className, onRowClick, dragProps, actions
     // glance pairs identity with state; the rest of the inline strip flows below.
     const [titleSideCol, ...restInline] = inline;
     const body = (_jsxs("div", { className: cn('flex flex-col gap-2', actions && 'pr-10'), children: [title ? (_jsxs("div", { className: 'flex items-start justify-between gap-2 text-sm', children: [_jsx("div", { className: 'min-w-0 flex-1', children: _jsx(CellRenderer, { col: title, value: row.original[title.key], row: row.original }) }), titleSideCol ? (_jsx("span", { className: 'shrink-0', children: _jsx(CellRenderer, { col: titleSideCol, value: row.original[titleSideCol.key], row: row.original }) })) : null] })) : null, restInline.length > 0 && (_jsx("div", { className: 'flex flex-wrap items-center gap-2', children: restInline.map((col) => (_jsx(CellRenderer, { col: col, value: row.original[col.key], row: row.original }, col.key))) })), detail.length > 0 && (_jsx("dl", { className: 'flex flex-col gap-1.5', children: detail.map((col) => (_jsxs("div", { className: 'flex items-baseline justify-between gap-3', children: [_jsx("dt", { className: 'cb-meta-label shrink-0', children: col.label }), _jsx("dd", { className: 'min-w-0 text-right text-sm', children: _jsx(CellRenderer, { col: col, value: row.original[col.key], row: row.original }) })] }, col.key))) }))] }));
-    return (_jsxs(Surface, { level: 'raised', pad: 'sm', radius: 'lg', ...dragProps, className: cn('relative isolate', dragProps?.draggable && 'cursor-grab', className), children: [actions ? _jsx("div", { className: 'absolute top-3 right-3 z-10', children: actions }) : null, onRowClick ? (_jsx(CardTapTarget, { onClick: () => onRowClick(row.original), className: '-m-1 rounded-md p-1 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring', children: body })) : (body), footer.length > 0 && (_jsx("div", { className: 'mt-3 flex items-center justify-end gap-2 border-t border-border/60 pt-3', children: footer.map((col) => (_jsx(CellRenderer, { col: col, value: row.original[col.key], row: row.original }, col.key))) })), expanded ? _jsx("div", { className: 'mt-4', children: expanded }) : null] }));
+    const main = onRowClick ? (_jsx(CardTapTarget, { onClick: () => onRowClick(row.original), className: '-m-1 rounded-md p-1 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring', children: body })) : (body);
+    return (_jsxs(Surface, { level: 'raised', pad: 'sm', radius: 'lg', ...dragProps, className: cn('relative isolate', dragProps?.draggable && 'cursor-grab', className, dragProps?.className), children: [actions ? _jsx("div", { className: 'absolute top-3 right-3 z-10', children: actions }) : null, select == null ? main : (_jsxs("div", { className: 'flex items-start gap-1', children: [_jsx("div", { className: '-mt-2 -ml-2 shrink-0', children: select }), _jsx("div", { className: 'min-w-0 flex-1', children: main })] })), footer.length > 0 && (_jsx("div", { className: 'mt-3 flex items-center justify-end gap-2 border-t border-border/60 pt-3', children: footer.map((col) => (_jsx(CellRenderer, { col: col, value: row.original[col.key], row: row.original }, col.key))) })), expanded ? _jsx("div", { className: 'mt-4', children: expanded }) : null] }));
 }
 //# sourceMappingURL=DataTable.js.map