cursedbelt 0.0.0 → 2.3.0

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

@@ -1,13 +1,22 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { useMemo, useState } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useScrollEdgeFade } from '../../hooks/useScrollEdgeFade';
 import { cn } from '../../lib/cn';
+import { CardTapTarget } from '../CardTapTarget';
 import { EmptyState } from '../EmptyState';
 import { Skeleton } from '../Skeleton';
+import { Surface } from '../Surface';
+import { CardView } from './CardView';
 import { CellRenderer } from './cells/CellRenderer';
+import { EMPTY_FILTER_QUERY, evaluateFilterQuery, filterableText, } from './filterQuery';
 import { TablePagination } from './Pagination';
 import { RowActions } from './RowActions';
+import { writeRowDrag } from './rowDrag';
 import { SortHeader } from './SortHeader';
+import { TableToolbar } from './Toolbar';
+import { resolveColumnAlign } from './types';
 /** Build an OnChangeFn that updates local state AND notifies an optional listener. */
 function chainUpdater(set, notify) {
     return (updater) => set((prev) => {
@@ -16,42 +25,335 @@ function chainUpdater(set, notify) {
         return next;
     });
 }
+/** Like {@link chainUpdater}, but also snaps pagination back to page 1 — for the
+ *  filter/sort setters, where landing on a page that no longer exists (or that no
+ *  longer matches the new criteria) would strand the reader. */
+function chainUpdaterResettingPage(set, setPagination, notify) {
+    return (updater) => set((prev) => {
+        const next = typeof updater === 'function' ? updater(prev) : updater;
+        setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
+        notify?.(next);
+        return next;
+    });
+}
+/**
+ * Px floor for a width-less column under `fixedLayout`. `table-layout: fixed`
+ * divides the leftover canvas between such columns, and the leftover can be
+ * zero — this is the share below which the division stops and the table
+ * overflows its wrapper instead.
+ */
+export const AUTO_TRACK_FLOOR_PX = 120;
+/** The trailing row-actions column is a fixed `w-20`. */
+const ACTIONS_TRACK_PX = 80;
+/**
+ * The narrowest width at which a `fixedLayout` table still honors the tracks its
+ * columns declared: the sum of every visible column's floor (`minWidth`, else a
+ * numeric `width`, else {@link AUTO_TRACK_FLOOR_PX}).
+ *
+ * 🔴 Why this is derived and not a prop the caller maintains, and what actually
+ * breaks without it. `table-layout: fixed` does NOT clamp at the declared
+ * widths, and `min-width` on a `<th>` is advisory in that algorithm — so the
+ * only thing bounding the canvas is the table's own `min-width`.
+ *
+ * 🔴 MEASURED IN CHROMIUM, 2026-08-14 (this comment used to say the browser
+ * "scales every track down proportionally", which is NOT what it does, and the
+ * difference is the whole failure mode). A fixed-layout table's used width is at
+ * least the SUM of its EXPLICITLY-declared column widths: those tracks survive
+ * and the table simply overflows its wrapper. What collapses is the WIDTH-LESS
+ * column — it is handed whatever is left over, and once the explicit widths
+ * alone exceed the canvas the leftover is ZERO. Its header text then paints on
+ * top of the next header's and its cell content over the next cell's: the column
+ * is gone but nothing clipped, so the table reads as a rendering bug rather than
+ * a sizing one. That is exactly orch's fleet table on 2026-08-11 (11 columns,
+ * ~1450px of tracks, `minTableWidth={880}`) — ten sized columns intact and the
+ * task column crushed to nothing.
+ *
+ * So the load-bearing term below is {@link AUTO_TRACK_FLOOR_PX} / `minWidth` for
+ * a width-less column: it is the part Chromium's own floor does not count, and
+ * therefore the part that has to be counted here. `minTableWidth` was the guard,
+ * but as a hand-kept number it had to be re-derived every time a column was
+ * added. The sum is a fact about the columns, so the table computes it.
+ *
+ * A percentage/CSS-string `width` contributes only its `minWidth` (or the auto
+ * floor): a share of the canvas cannot bound the canvas.
+ *
+ * 🔴 This is now GATED IN A BROWSER, not just asserted here: `e2e/table-layout.spec.ts`
+ * mounts an 11-column fixture at 1440/1180/1024 and fails on any cell ink that
+ * escapes its own track or any clipped header label. Mutating this function to
+ * drop the width-less column's contribution turns that gate red at all three
+ * widths — verified 2026-08-14. happy-dom computes no layout, so no `bun test`
+ * spec here can see it.
+ */
+export function declaredTrackFloor(columns, hasActions = false) {
+    const columnsTotal = columns.reduce((sum, col) => {
+        if (col.minWidth != null)
+            return sum + col.minWidth;
+        if (typeof col.width === 'number')
+            return sum + col.width;
+        return sum + AUTO_TRACK_FLOOR_PX;
+    }, 0);
+    return columnsTotal + (hasActions ? ACTIONS_TRACK_PX : 0);
+}
+/**
+ * What one header click does to the sort STACK.
+ *
+ * 🔴 The new key goes to the FRONT, and that is the whole feature. The owner
+ * described the behaviour by its result — *"I sort by date created, then sort by
+ * artist and I get a list ordered by artist with their tracks still sorted by
+ * date created"* — which is a stack in click order where the LATEST click is the
+ * primary key and everything clicked before it survives as a tie-breaker.
+ * TanStack's own multi-sort appends instead (the first key stays primary and
+ * the new one becomes the tie-break), which produces the opposite list and needs
+ * a shift-click nobody discovers. So the stack is computed here.
+ *
+ * A column already in the stack cycles ascending → descending → out, in place:
+ * flipping a tie-breaker's direction must not promote it over the key above it,
+ * and a third click has to be able to remove a key or the stack is a one-way
+ * accumulator.
+ *
+ * Stability comes for free and is not an accident: `Array.prototype.sort` has
+ * been required to be stable since ES2019 and TanStack's sorted row model uses
+ * it, so rows that tie on every key in the stack keep the order they arrived in.
+ */
+export function nextSortStack(current, id, multi) {
+    const existing = current.find((sort) => sort.id === id);
+    if (!existing) {
+        const ascending = { id, desc: false };
+        return multi ? [ascending, ...current] : [ascending];
+    }
+    if (!existing.desc) {
+        const flipped = current.map((sort) => (sort.id === id ? { id, desc: true } : sort));
+        return multi ? flipped : [{ id, desc: true }];
+    }
+    return multi ? current.filter((sort) => sort.id !== id) : [];
+}
+/**
+ * Read a `ColDef.key` off a row, honouring the dot-notation `ColDef` documents.
+ * TanStack's own `accessorKey` does this for the cells; the filter builder runs
+ * BEFORE TanStack (see `filteredData`) and so needs the same reading, or a
+ * nested column would filter on `undefined` and match nothing.
+ */
+function readPath(row, key) {
+    if (!key.includes('.'))
+        return row?.[key];
+    return key.split('.').reduce((value, part) => {
+        if (value == null || typeof value !== 'object')
+            return undefined;
+        return value[part];
+    }, row);
+}
+/** True when a cell value carries nothing worth a column: null/undefined/''/[]. */
+function isEmptyCellValue(v) {
+    if (v == null)
+        return true;
+    if (typeof v === 'string')
+        return v.trim() === '';
+    if (Array.isArray(v))
+        return v.length === 0;
+    return false;
+}
 /**
  * The one data-table primitive — a headless TanStack Table v8 instance with our markup.
  * Sorting, global filtering, column visibility, and pagination all live in TanStack
  * state; cells dispatch through the {@link CellRenderer} registry (so rich types render
  * everywhere). Dynamic/user-defined columns are first-class: pass a runtime `ColDef[]`.
  * A record create/edit flow is a `Drawer` (task 10) opened from `onRowClick`/toolbar add.
+ *
+ * Commercial-grade defaults (owner mandate 2026-07-15): metadata-styled header row
+ * (uppercase/tracked/muted — headers must read as chrome, not data), an always-on row
+ * hover wash so wide rows can be traced, optional pinned header for deep lists, a
+ * full-width accordion detail row that never breaks column alignment, and an automatic
+ * stacked-card layout under `sm` so phones are never handed a clipped grid.
  */
-export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRowDelete, loading, emptyState, toolbar, pageSize = 50, pageSizeOptions, hidePagination, caption, className, serverSide, pageCount, rowCount, onSortingChange, onColumnFiltersChange, onGlobalFilterChange, onPaginationChange, }) {
-    const [sorting, setSorting] = useState([]);
+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, }) {
+    // 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 [columnFilters, setColumnFilters] = useState([]);
     const [globalFilter, setGlobalFilter] = useState('');
     const [columnVisibility, setColumnVisibility] = useState(() => Object.fromEntries(columns.filter((c) => c.hidden).map((c) => [c.key, false])));
     const [pagination, setPagination] = useState({ pageIndex: 0, pageSize });
-    const tsColumns = useMemo(() => columns.map((col) => ({
+    // `null` = every column, and it STAYS null as columns come and go — see SearchBox.
+    const [searchScope, setSearchScope] = useState(null);
+    // Text + scope as ONE value — see TableSearchState for why they cannot be two.
+    // `undefined` when there is nothing typed, so TanStack skips global filtering
+    // entirely rather than running a predicate that always answers true.
+    const search = useMemo(() => (globalFilter.trim() === '' ? undefined : { text: globalFilter, scope: searchScope }), [globalFilter, searchScope]);
+    const [ownFilterQuery, setOwnFilterQuery] = useState(EMPTY_FILTER_QUERY);
+    const filterQuery = filterQueryProp ?? ownFilterQuery;
+    const setFilterQuery = useCallback((next) => {
+        if (filterQueryProp === undefined)
+            setOwnFilterQuery(next);
+        setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
+        onFilterQueryChange?.(next);
+    }, [filterQueryProp, onFilterQueryChange]);
+    const setSearchText = useCallback((text) => {
+        setGlobalFilter(text);
+        setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
+        onGlobalFilterChange?.(text);
+    }, [onGlobalFilterChange]);
+    // Which row's expansion has already been scrolled into view — scroll once per
+    // expansion, never on the polling re-renders that follow.
+    const scrolledExpansionRef = useRef(null);
+    // Empty-column pruning happens BEFORE the TanStack translation so headers, body
+    // cells, and the mobile cards all agree on the live column set. `alwaysVisible`
+    // columns are exempt — a renderer-only column (e.g. an actions column) has no
+    // matching row field, so a data-driven emptiness check would always drop it.
+    const liveColumns = useMemo(() => hideEmptyColumns
+        ? columns.filter((col) => col.alwaysVisible || data.some((row) => !isEmptyCellValue(row[col.key])))
+        : columns, [columns, data, hideEmptyColumns]);
+    /**
+     * The filter BUILDER is applied to the rows before TanStack ever sees them,
+     * and that is deliberate: it is what makes the builder AND with the search box
+     * and the per-column filters instead of competing with them. TanStack already
+     * ANDs its own `globalFilter` and `columnFilters`; a third mechanism layered
+     * as another column filter would have had to invent a precedence rule between
+     * the three. Pre-filtering means there is nothing to decide — the builder
+     * narrows the dataset, the rest narrows what is left, and the sort stack
+     * re-applies to whatever survives.
+     */
+    const filteredData = useMemo(() => serverSide
+        ? data
+        : data.filter((row) => evaluateFilterQuery(row, filterQuery, (r, key) => readPath(r, key))), [data, filterQuery, serverSide]);
+    /**
+     * Every write to the sort stack goes through here, so a header click, a chip's
+     * direction flip and a chip's `×` all take the same page-reset and fire the
+     * same `onSortingChange` — three code paths for one piece of state is how a
+     * server-side table ends up sorted differently from what its chips say.
+     */
+    const applySorting = useCallback((next) => {
+        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]);
+    const tsColumns = useMemo(() => liveColumns.map((col) => ({
         id: col.key,
         accessorKey: col.key,
-        meta: { label: col.label },
-        size: col.width,
+        // DESIGN.md §1 makes right-alignment a requirement for numeric values, not a
+        // preference — `resolveColumnAlign` derives it; an explicit `align` overrides.
+        meta: {
+            label: col.label,
+            align: resolveColumnAlign(col),
+            width: col.width,
+            minWidth: col.minWidth,
+        },
+        size: typeof col.width === 'number' ? col.width : undefined,
         enableSorting: col.sortable ?? false,
         enableHiding: !col.alwaysVisible,
+        // `filterable` is the AUTHORING decision — an internal id nobody means
+        // to match is out of the search universe entirely. The reader's USE-TIME
+        // choice within what is left rides the filter VALUE instead, because a
+        // column-config change does not invalidate TanStack's row model (see
+        // {@link TableSearchState}).
         enableGlobalFilter: col.filterable ?? true,
-        enableColumnFilter: col.filterable ?? false,
-        header: ({ column }) => (_jsx(SortHeader, { column: column, label: col.label, sortable: col.sortable })),
+        // 🔴 Every column is filterable now (was `?? false`). The unit's item 2
+        // is one line — *"Every column filterable"* — and a per-column filter
+        // that only exists where somebody remembered to set a flag is the same
+        // "one table has it, the next does not" divergence as the search box.
+        enableColumnFilter: col.filterable ?? true,
+        // `table` (not the closed-over `sorting`) is what makes the ordinal
+        // badge live without putting the sort state in this memo's deps —
+        // rebuilding every ColumnDef on every sort click would throw away
+        // TanStack's column instances mid-interaction.
+        header: ({ column, table: t }) => {
+            const stack = t.getState().sorting;
+            return (_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) }));
+        },
         cell: ({ getValue, row }) => (_jsx(CellRenderer, { col: col, value: getValue(), row: row.original, onEdit: onRowEdit ? () => onRowEdit(row.original) : undefined })),
-    })), [columns, onRowEdit]);
+    })), [liveColumns, onRowEdit, toggleSortKey]);
+    const labelOf = useCallback((id) => liveColumns.find((col) => col.key === id)?.label ?? id, [liveColumns]);
+    const controls = useMemo(() => ({
+        searchText: globalFilter,
+        setSearchText,
+        filterQuery,
+        setFilterQuery,
+        // `alwaysVisible` columns are exempt from HIDING, not from filtering — the
+        // builder's universe is every column that carries data.
+        filterColumns: liveColumns.map((col) => ({ key: col.key, label: col.label })),
+        searchScope,
+        setSearchScope,
+        searchColumns: liveColumns
+            .filter((col) => col.filterable ?? true)
+            .map((col) => ({ key: col.key, label: col.label })),
+        sorting,
+        clearSorting: () => applySorting(() => []),
+        removeSortKey: (id) => applySorting((prev) => prev.filter((sort) => sort.id !== id)),
+        toggleSortDirection: (id) => applySorting((prev) => prev.map((sort) => (sort.id === id ? { ...sort, desc: !sort.desc } : sort))),
+        labelOf,
+        viewMode,
+        setViewMode: onViewModeChange,
+    }), [
+        applySorting,
+        filterQuery,
+        globalFilter,
+        setSearchText,
+        labelOf,
+        liveColumns,
+        onViewModeChange,
+        searchScope,
+        setFilterQuery,
+        sorting,
+        viewMode,
+    ]);
+    /*
+     * ── Virtualization ────────────────────────────────────────────────────────
+     *
+     * 🔴 It IMPLIES `scrollBody` and it SUPPRESSES pagination, and both are silent
+     * corrections rather than warnings because both failures look like "virtualization
+     * does not work": a virtualizer measures a scroll container, so if vertical scrolling
+     * lives on an ancestor it measures a box that never scrolls and the window stays at
+     * row 0 while the page scrolls past it; and a page control over a virtual window is a
+     * second, disagreeing answer to "where am I" when the scrollbar already gives the
+     * honest one.
+     *
+     * 🔴 Suppressing pagination means the ROW MODEL, not only the pager. Left paginated,
+     * the virtualizer is handed one page's worth of rows, so its spacer describes 50 rows
+     * while the data has 5,000 — the scrollbar lies and the list simply ends. That is a
+     * failure the pager's absence hides rather than reveals, which is why it is tested by
+     * measuring `scrollHeight` in a real browser.
+     */
+    const virtualOptions = virtualize === true ? {} : virtualize || null;
+    const virtualEnabled = virtualOptions !== null;
+    const bodyScrolls = scrollBody || virtualEnabled;
+    const paginationHidden = hidePagination || virtualEnabled;
     const table = useReactTable({
-        data,
+        data: filteredData,
         columns: tsColumns,
         getRowId,
-        state: { sorting, columnFilters, globalFilter, columnVisibility, pagination },
-        onSortingChange: chainUpdater(setSorting, onSortingChange),
-        onColumnFiltersChange: chainUpdater(setColumnFilters, onColumnFiltersChange),
-        onGlobalFilterChange: chainUpdater(setGlobalFilter, (v) => onGlobalFilterChange?.(String(v ?? ''))),
+        state: { sorting, columnFilters, globalFilter: search, columnVisibility, pagination },
+        onSortingChange: chainUpdaterResettingPage(setSorting, setPagination, onSortingChange),
+        onColumnFiltersChange: chainUpdaterResettingPage(setColumnFilters, setPagination, onColumnFiltersChange),
+        // TanStack hands the updater whatever `state.globalFilter` is, which is now
+        // a TableSearchState; the toolbar sets TEXT, so normalise both shapes.
+        onGlobalFilterChange: (updater) => {
+            const next = typeof updater === 'function' ? updater(search) : updater;
+            const text = typeof next === 'string' ? next : (next?.text ?? '');
+            setSearchText(text);
+        },
         onColumnVisibilityChange: chainUpdater(setColumnVisibility),
         onPaginationChange: chainUpdater(setPagination, onPaginationChange),
-        globalFilterFn: 'includesString',
+        // 🔴 Not `'includesString'` any more. That built-in is `String(value)`, and
+        // `String(new Date())` / `String(['rock','80s'])` are not the text the
+        // reader can see in the cell — a date column answered nothing at all for a
+        // typed year, which is the owner's own *"'199' in the date created"* case.
+        // `filterableText` is the SAME normalisation the filter builder uses, so a
+        // search and a `contains` condition on one column agree by construction
+        // rather than by two implementations happening to match.
+        globalFilterFn: (row, columnId, value) => {
+            // A bare string is still accepted: an app that calls
+            // `table.setGlobalFilter('x')` directly keeps working, unscoped.
+            const { text, scope } = typeof value === 'string' ? { text: value, scope: null } : value;
+            if (!text)
+                return true;
+            if (scope && !scope.includes(columnId))
+                return false;
+            return filterableText(row.getValue(columnId)).toLowerCase().includes(text.toLowerCase());
+        },
         manualSorting: serverSide,
         manualFiltering: serverSide,
         manualPagination: serverSide,
@@ -60,27 +362,250 @@ export function DataTable({ columns, data, getRowId, onRowClick, onRowEdit, onRo
         getCoreRowModel: getCoreRowModel(),
         getSortedRowModel: serverSide ? undefined : getSortedRowModel(),
         getFilteredRowModel: serverSide ? undefined : getFilteredRowModel(),
-        getPaginationRowModel: serverSide ? undefined : getPaginationRowModel(),
+        // 🔴 `virtualEnabled` too, not only `serverSide`. See the note where the flag is
+        // computed: a paginated virtualizer sizes its spacer from one PAGE.
+        getPaginationRowModel: serverSide || virtualEnabled ? undefined : getPaginationRowModel(),
+        // TanStack's built-in auto-reset fires `resetPageIndex()` on EVERY `data`
+        // identity change (see `getCoreRowModel`'s memo deps), not just on filter/sort
+        // changes — any live-polling table (this one included: rows are re-derived
+        // every tick for a running duration column) got its page index silently
+        // stomped back to 0 mid-navigation. We own page resets explicitly above
+        // (sort/filter change) instead of trusting the library's blanket default.
+        autoResetPageIndex: false,
+        meta: { cbControls: controls },
     });
+    /**
+     * The drag-source props for one row, or `{}` when this table is not a drag
+     * source. Every tier calls it — grid row, tablet list row, phone card, card
+     * view — so a row is draggable at every width rather than only in the grid.
+     *
+     * `preventDefault()` on a row the app refuses is the correct refusal: it
+     * cancels the drag before it starts, so there is no ghost image following the
+     * cursor to a drop that would be ignored.
+     */
+    const dragPropsFor = (row) => {
+        if (!getRowDrag)
+            return {};
+        return {
+            draggable: true,
+            onDragStart: (event) => {
+                const payload = getRowDrag(row);
+                if (!payload) {
+                    event.preventDefault();
+                    return;
+                }
+                writeRowDrag(event, { source: dragSourceId, ...payload });
+            },
+        };
+    };
     const rows = table.getRowModel().rows;
-    const hasActions = !!(onRowEdit || onRowDelete);
-    const toolbarNode = typeof toolbar === 'function' ? toolbar(table) : toolbar;
-    return (_jsxs("div", { className: cn('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' }) })) : (_jsx("div", { className: 'overflow-x-auto', children: _jsxs("table", { className: 'w-full border-collapse text-sm', children: [caption ? _jsx("caption", { className: 'sr-only', children: caption }) : null, _jsx("thead", { children: table.getHeaderGroups().map((hg) => (_jsxs("tr", { className: 'border-b border-border', children: [hg.headers.map((h) => {
-                                        const sorted = h.column.getIsSorted();
-                                        const width = h.column.columnDef.size;
-                                        return (_jsx("th", { scope: 'col', "aria-sort": sorted === 'asc'
-                                                ? 'ascending'
-                                                : sorted === 'desc'
-                                                    ? 'descending'
-                                                    : undefined, style: width != null ? { width } : undefined, className: 'px-4 py-2.5 text-left font-medium text-muted-foreground', children: h.isPlaceholder
-                                                ? null
-                                                : flexRender(h.column.columnDef.header, h.getContext()) }, h.id));
-                                    }), hasActions ? _jsx("th", { className: 'w-20 px-2', "aria-label": 'Row actions' }) : null] }, hg.id))) }), _jsx("tbody", { children: rows.map((row) => (_jsxs("tr", { className: cn('border-b border-border transition-colors last:border-0', onRowClick &&
-                                    'cursor-pointer hover:bg-muted/50 focus-visible:bg-muted/50 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) => (_jsx("td", { className: 'px-4 py-2.5 align-middle', 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 }) })) : null] }, row.id))) })] }) })), !loading && rows.length > 0 && !hidePagination ? (_jsx(TablePagination, { table: table, pageSizeOptions: pageSizeOptions })) : null] }));
+    const estimateRowHeight = virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44);
+    const scrollRef = useRef(null);
+    const rowVirtualizer = useVirtualizer({
+        count: virtualEnabled ? rows.length : 0,
+        getScrollElement: () => scrollRef.current,
+        estimateSize: () => estimateRowHeight,
+        overscan: virtualOptions?.overscan ?? 8,
+        // 🔴 MEASURED, not assumed. A wrapping cell, an expanded detail panel and the
+        // `compact` density all change a row's height, and a caller cannot be asked to
+        // compute any of them. `estimateSize` only seeds the spacer before first paint.
+        measureElement: (el) => el.getBoundingClientRect().height,
+    });
+    /**
+     * 🔴 Invalidate the measurement cache when the row height changes.
+     *
+     * `measureElement` covers a row that is CURRENTLY rendered, and that is what makes
+     * this look finished. It says nothing about the rows already measured and scrolled
+     * out of view: `@tanstack/react-virtual` keeps their heights in its measurement
+     * list, and a new `estimateSize` does not invalidate one — only `measure()` does.
+     *
+     * So toggling `density` re-renders the visible rows at 36px while every row the
+     * viewer has already scrolled past is still placed at 44px. Rows overlap or leave
+     * gaps, nothing throws, and the symptom points at the layout code rather than at
+     * the virtualizer. `VirtualCardGrid` paid for that investigation once already and
+     * grew the same effect keyed on its own `rowHeight`; `virtualizerMeasure.spec.ts`
+     * exists so the third virtualizer does not pay for it a third time — and it is
+     * what caught this one.
+     */
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `estimateRowHeight` is the POINT of this effect, not a value it reads — re-running when it changes is what invalidates the cached offsets. Dropping it makes the measure fire once and never again, which is the bug.
+    useEffect(() => {
+        rowVirtualizer.measure();
+    }, [rowVirtualizer, estimateRowHeight]);
+    const virtualRows = virtualEnabled ? rowVirtualizer.getVirtualItems() : [];
+    /** The rows to render, and the two spacers that keep the scrollbar honest about the
+     *  ones that are not. Off, this is every row and no spacers — byte-identical output. */
+    const bodyRows = virtualEnabled ? virtualRows.map((v) => rows[v.index]) : rows;
+    const padTop = virtualEnabled ? (virtualRows[0]?.start ?? 0) : 0;
+    const padBottom = virtualEnabled
+        ? rowVirtualizer.getTotalSize() - (virtualRows.at(-1)?.end ?? 0)
+        : 0;
+    const hasActions = !!(onRowEdit || onRowDelete || rowMenu);
+    const toolbarNode = typeof toolbar === 'function'
+        ? toolbar(table)
+        : (toolbar ??
+            // 🔴 Present by DEFAULT, opted out of explicitly — the half of item 6
+            // that was actually missing. `enableSearch` has defaulted true forever
+            // and reached nothing, because a table with no `toolbar` rendered no
+            // toolbar at all. Only ONE toolbar is ever rendered: a caller that
+            // passes its own gets exactly that, and `TableToolbar` reads the same
+            // controls off `table.options.meta`, so composing a toolbar is never
+            // the thing that costs you the search box.
+            (searchable ? _jsx(TableToolbar, { table: table, searchPlaceholder: searchPlaceholder }) : null));
+    const visibleColumnCount = table.getVisibleLeafColumns().length + (hasActions ? 1 : 0);
+    // Cards track the SAME live visibility state as the grid (ViewOptionsMenu toggles
+    // apply to both) — not just the ColDefs' initial `hidden` flags.
+    const cardColumns = liveColumns.filter((c) => table.getColumn(c.key)?.getIsVisible() ?? true);
+    // The freeze point: never below the tracks the visible columns declared (see
+    // `declaredTrackFloor`), and never below an explicit `minTableWidth` on top.
+    // Hiding a column through the view-options menu narrows it, so the table stops
+    // scrolling as soon as the reader has made it fit.
+    // "There is more table this way." A rigid grid that refuses to compress has to
+    // say so at the cut edge, or a narrow pane reads as a table with its right-hand
+    // columns missing rather than one that scrolls (`useScrollEdgeFade`).
+    const gridFade = useScrollEdgeFade();
+    const tableMinWidth = fixedLayout
+        ? Math.max(minTableWidth ?? 0, declaredTrackFloor(cardColumns, hasActions))
+        : minTableWidth;
+    return (_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
+                                        ? renderExpanded(row.original)
+                                        : null }, row.id))) })), mobileCards && (_jsx("div", { "data-cb-table-list": '', className: 'hidden @xl:block @3xl:hidden', children: (() => {
+                                    const [title, ...rest] = cardColumns;
+                                    // ONE shared grid template for every row — parent and child rows
+                                    // lock into identical column slots, so the status/ports/actions
+                                    // lanes stay razor-straight regardless of row content ("ragged
+                                    // right" defect, owner tablet re-judgment 2026-07-15). Columns
+                                    // reuse their ColDef width when set (px or proportional string,
+                                    // floored by minWidth); the trailing slot is the row-actions kebab.
+                                    const trackOf = (c) => {
+                                        const share = c.width == null ? null : typeof c.width === 'number' ? `${c.width}px` : c.width;
+                                        if (share == null)
+                                            return 'max-content';
+                                        return c.minWidth != null ? `minmax(${c.minWidth}px, ${share})` : share;
+                                    };
+                                    // The kebab track is a FIXED 32px, never max-content: the header
+                                    // strip and each row are separate grid containers, so a
+                                    // max-content track resolves differently where the kebab is
+                                    // absent (the header) and every preceding lane drifts ~32px off
+                                    // its label — the v4 judge's tablet misalignment finding.
+                                    const template = [
+                                        'minmax(0,1fr)',
+                                        ...rest.map(trackOf),
+                                        ...(hasActions ? ['32px'] : []),
+                                    ].join(' ');
+                                    const header = (_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 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: [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) => {
+                                                    /* 🔴 The ZEBRA index is the row's ABSOLUTE position, not its
+                                                       position in the rendered slice. Off by that, the stripes
+                                                       would repaint themselves every time the window moved — the
+                                                       rhythm inverting mid-scroll, which reads as a rendering
+                                                       fault rather than as a guide. */
+                                                    const rowIndex = virtualEnabled ? virtualRows[sliceIndex].index : sliceIndex;
+                                                    const isExpanded = renderExpanded != null && expandedRowId != null && row.id === expandedRowId;
+                                                    return (_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) => {
+                                                                    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] }));
+}
+/**
+ * One row rendered as a phone card: first visible column = the title zone (unlabeled,
+ * full width), labeled columns = compact label/value pairs, empty-labeled columns
+ * (an actions column) + the row-actions kebab = the bordered footer row, actions
+ * anchored bottom-right inside the card bounds. Values render through the SAME
+ * {@link CellRenderer} registry as the grid, so a custom cell shows identically here.
+ */
+function MobileRowCard({ row, columns, className, onRowClick, dragProps, actions, expanded, }) {
+    const visible = columns.filter((c) => !c.hidden);
+    const [title, ...rest] = visible;
+    const footer = rest.filter((c) => c.cardFooter || c.label === '');
+    const detail = rest.filter((c) => !footer.includes(c) && c.label !== '' && c.cardLabel !== false);
+    // Self-describing values (cardLabel: false) flow into ONE inline strip under the
+    // title — repeating uppercase labels per card destroys vertical flow.
+    const inline = rest.filter((c) => !footer.includes(c) && c.label !== '' && c.cardLabel === false);
+    // The manual's card blueprint (mobile-responsive/): the FIRST self-describing
+    // value (typically a status pill) floats at the title row's right edge — one
+    // glance pairs identity with state; the rest of the inline strip flows below.
+    const [titleSideCol, ...restInline] = inline;
+    const body = (_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] }));
 }
 //# sourceMappingURL=DataTable.js.map