cursedbelt 5.25.0 → 5.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/dist/react/components/Badge.d.ts +6 -6
  2. package/dist/react/components/Badge.d.ts.map +1 -1
  3. package/dist/react/components/Badge.js +13 -5
  4. package/dist/react/components/Badge.js.map +1 -1
  5. package/dist/react/components/DataTable/DataTable.d.ts +125 -5
  6. package/dist/react/components/DataTable/DataTable.d.ts.map +1 -1
  7. package/dist/react/components/DataTable/DataTable.js +335 -121
  8. package/dist/react/components/DataTable/DataTable.js.map +1 -1
  9. package/dist/react/components/DataTable/RowActions.d.ts +3 -1
  10. package/dist/react/components/DataTable/RowActions.d.ts.map +1 -1
  11. package/dist/react/components/DataTable/RowActions.js +9 -2
  12. package/dist/react/components/DataTable/RowActions.js.map +1 -1
  13. package/dist/react/components/DataTable/SortHeader.d.ts +4 -1
  14. package/dist/react/components/DataTable/SortHeader.d.ts.map +1 -1
  15. package/dist/react/components/DataTable/SortHeader.js +7 -1
  16. package/dist/react/components/DataTable/SortHeader.js.map +1 -1
  17. package/dist/react/components/DataTable/cells/CellRenderer.d.ts.map +1 -1
  18. package/dist/react/components/DataTable/cells/CellRenderer.js +4 -1
  19. package/dist/react/components/DataTable/cells/CellRenderer.js.map +1 -1
  20. package/dist/react/components/DataTable/index.d.ts +2 -2
  21. package/dist/react/components/DataTable/index.d.ts.map +1 -1
  22. package/dist/react/components/DataTable/index.js +1 -1
  23. package/dist/react/components/DataTable/index.js.map +1 -1
  24. package/dist/react/components/DataTable/lazyPart.d.ts +27 -0
  25. package/dist/react/components/DataTable/lazyPart.d.ts.map +1 -0
  26. package/dist/react/components/DataTable/lazyPart.js +46 -0
  27. package/dist/react/components/DataTable/lazyPart.js.map +1 -0
  28. package/dist/react/components/DataTable/types.d.ts +106 -0
  29. package/dist/react/components/DataTable/types.d.ts.map +1 -1
  30. package/dist/react/components/DataTable/types.js.map +1 -1
  31. package/dist/react/components/auth/SignInCard.d.ts +49 -0
  32. package/dist/react/components/auth/SignInCard.d.ts.map +1 -0
  33. package/dist/react/components/auth/SignInCard.js +21 -0
  34. package/dist/react/components/auth/SignInCard.js.map +1 -0
  35. package/dist/react/components/auth/index.d.ts +1 -0
  36. package/dist/react/components/auth/index.d.ts.map +1 -1
  37. package/dist/react/components/auth/index.js +1 -0
  38. package/dist/react/components/auth/index.js.map +1 -1
  39. package/dist/react/index.d.ts +1 -1
  40. package/dist/react/index.d.ts.map +1 -1
  41. package/dist/react/index.js +1 -1
  42. package/dist/react/index.js.map +1 -1
  43. package/dist/styles-areas/analytics.css +9 -6
  44. package/dist/styles-areas/core.css +8 -7
  45. package/dist/styles-areas/data-table.css +8 -5
  46. package/dist/styles-utilities.css +75 -0
  47. package/package.json +2 -2
  48. package/src/react/components/Badge.capsule.spec.ts +178 -0
  49. package/src/react/components/Badge.tsx +13 -5
  50. package/src/react/components/DataTable/DataTable.spec.tsx +6 -2
  51. package/src/react/components/DataTable/DataTable.tsx +518 -104
  52. package/src/react/components/DataTable/RowActions.tsx +18 -10
  53. package/src/react/components/DataTable/SortHeader.tsx +19 -0
  54. package/src/react/components/DataTable/cells/CellRenderer.tsx +2 -0
  55. package/src/react/components/DataTable/index.ts +10 -1
  56. package/src/react/components/DataTable/lazyPart.spec.tsx +99 -0
  57. package/src/react/components/DataTable/lazyPart.tsx +58 -0
  58. package/src/react/components/DataTable/rowHooks.spec.tsx +289 -0
  59. package/src/react/components/DataTable/selection.spec.tsx +6 -2
  60. package/src/react/components/DataTable/tableSystem.spec.tsx +6 -2
  61. package/src/react/components/DataTable/types.ts +110 -0
  62. package/src/react/components/DataTable/virtualize.spec.tsx +38 -2
  63. package/src/react/components/auth/SignInCard.spec.tsx +48 -0
  64. package/src/react/components/auth/SignInCard.tsx +90 -0
  65. package/src/react/components/auth/index.ts +1 -0
  66. package/src/react/index.ts +5 -0
  67. package/src/styles-areas/analytics.css +9 -6
  68. package/src/styles-areas/core.css +8 -7
  69. package/src/styles-areas/data-table.css +8 -5
  70. package/src/styles-utilities.css +75 -0
@@ -24,9 +24,10 @@ import type {
24
24
  SetStateAction,
25
25
  } from 'react';
26
26
  import { useVirtualizer } from '@tanstack/react-virtual';
27
- import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
27
+ import { type ComponentType, Fragment, type Ref, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
28
28
  import { useScrollEdgeFade } from '../../hooks/useScrollEdgeFade.js';
29
29
  import { cn } from '../../lib/cn.js';
30
+ import { TAP_TARGET_HEIGHT } from '../../lib/tapTarget.js';
30
31
  import { CardTapTarget } from '../CardTapTarget.js';
31
32
  import { Checkbox } from '../Checkbox.js';
32
33
  import type { DropdownMenuItem } from '../DropdownMenu.js';
@@ -42,13 +43,71 @@ import {
42
43
  filterableText,
43
44
  type FilterQuery,
44
45
  } from './filterQuery.js';
45
- import { TablePagination } from './Pagination.js';
46
- import { RowActions } from './RowActions.js';
46
+ import { preloadRowMenu, RowActions } from './RowActions.js';
47
47
  import { type RowDragPayload, writeRowDrag } from './rowDrag.js';
48
48
  import { SortHeader } from './SortHeader.js';
49
- import { TableToolbar } from './Toolbar.js';
50
- import type { ColDef, TableViewMode } from './types.js';
49
+ import type {
50
+ ColDef,
51
+ DataTableHandle,
52
+ DataTableRowProps,
53
+ DataTableSelectAll,
54
+ DataTableServerWindow,
55
+ TableViewMode,
56
+ } from './types.js';
51
57
  import { resolveColumnAlign } from './types.js';
58
+ import { lazyPart } from './lazyPart.js';
59
+ import type { TablePaginationProps } from './Pagination.js';
60
+ import type { TableToolbarProps } from './Toolbar.js';
61
+
62
+ // 🔴 The toolbar and the pager load only when a table DRAWS them (forge task 2309).
63
+ // Between them they reach Radix's Select, Menu and Popover — ~20 kB gzip that a
64
+ // read-only list (`searchable={false}`, `serverWindow`, no row menu) never opens.
65
+ // Measured on apps/music's track list: 67 kB gzip over its entry ceiling, most of
66
+ // it these two parts' dependencies. A static import made every consumer pay for
67
+ // them. The row kebab's menu is lazy the same way, inside `RowActions`; all three
68
+ // are loaded ahead by `preloadDataTableParts`. `lazyPart` erases the component's
69
+ // type parameter, so each is given back its own signature.
70
+ const ToolbarPart = lazyPart(() =>
71
+ import('./Toolbar.js').then((m) => m.TableToolbar as ComponentType<TableToolbarProps<unknown>>),
72
+ ) as unknown as (<TRow>(props: TableToolbarProps<TRow> & { fallback?: ReactNode }) => ReactNode) & {
73
+ preload: () => Promise<void>;
74
+ };
75
+ const PaginationPart = lazyPart(() =>
76
+ import('./Pagination.js').then(
77
+ (m) => m.TablePagination as ComponentType<TablePaginationProps<unknown>>,
78
+ ),
79
+ ) as unknown as (<TRow>(props: TablePaginationProps<TRow> & { fallback?: ReactNode }) => ReactNode) & {
80
+ preload: () => Promise<void>;
81
+ };
82
+
83
+ /**
84
+ * Load the table's lazy parts — the toolbar, the pager, the row kebab's menu — now,
85
+ * so every table mounted after this resolves draws them on its first render. For a
86
+ * spec setup that queries them synchronously after `render(…)`, and for an app about
87
+ * to show a table with a toolbar. Never required: without it they arrive a tick late,
88
+ * into a placeholder of their own height.
89
+ */
90
+ export async function preloadDataTableParts(): Promise<void> {
91
+ await Promise.all([ToolbarPart.preload(), PaginationPart.preload(), preloadRowMenu()]);
92
+ }
93
+
94
+ /** Where the toolbar will be, the height it will be — so its arrival shifts nothing. */
95
+ function ToolbarPlaceholder() {
96
+ return (
97
+ <div data-cb-table-toolbar-pending='' aria-hidden className='border-b border-border px-2 py-2'>
98
+ <div className={cn('h-9', TAP_TARGET_HEIGHT)} />
99
+ </div>
100
+ );
101
+ }
102
+
103
+ /** Where the pager will be, the height it will be. */
104
+ function PaginationPlaceholder() {
105
+ return (
106
+ <div data-cb-table-pagination-pending='' aria-hidden className='border-t border-border px-4 py-2.5'>
107
+ <div className={cn('h-8', TAP_TARGET_HEIGHT)} />
108
+ </div>
109
+ );
110
+ }
52
111
 
53
112
  // TanStack's header is a render fn (we build a sortable button), so its column has no
54
113
  // string header for the ViewOptionsMenu to label a toggle with. Carry the label on
@@ -61,6 +120,8 @@ declare module '@tanstack/react-table' {
61
120
  * own `size` is number-only, so proportional tracks ride meta instead. */
62
121
  width?: number | string;
63
122
  minWidth?: number;
123
+ hideBelow?: 'sm' | 'md' | 'lg';
124
+ leading?: boolean;
64
125
  }
65
126
  interface TableMeta<TData extends RowData> {
66
127
  /** {@link DataTableControls} — see its doc for why it rides on the table. */
@@ -134,7 +195,7 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
134
195
  /** Stable row id (selection/keys). Falls back to the row index. */
135
196
  getRowId?: (row: TRow) => string;
136
197
  /** Click a row — typically opens the record `Drawer`. */
137
- onRowClick?: (row: TRow) => void;
198
+ onRowClick?: (row: TRow, event?: MouseEvent<HTMLElement>) => void;
138
199
  /** Trailing per-row Edit action (renders the actions column). */
139
200
  onRowEdit?: (row: TRow) => void;
140
201
  /** Trailing per-row Delete action (renders the actions column). */
@@ -248,8 +309,59 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
248
309
  * row reports its real height back, so a wrapping cell, a `renderExpanded` panel and
249
310
  * the `compact` density all work without the caller computing anything. Pass a number
250
311
  * to seed a better first estimate for an unusual row height.
312
+ *
313
+ * It virtualizes the rows it is GIVEN. A list whose rows live on a SERVER — a spacer
314
+ * sized from the server's count, pages loading as they scroll into view, a scrollbar
315
+ * that can be dragged to a row nobody has fetched — is {@link serverWindow}, which
316
+ * implies this.
251
317
  */
252
318
  virtualize?: boolean | { estimateRowHeight?: number; overscan?: number };
319
+ /**
320
+ * SERVER-WINDOWED rows: `data` is only a WINDOW of a result set the server holds —
321
+ * rows `[start, start + data.length)` of `total`. Implies {@link virtualize}.
322
+ *
323
+ * ── Why (forge task 2300) ─────────────────────────────────────────────────
324
+ * apps/music's library is 5,409 tracks and its list is the surface the owner "spends
325
+ * all their time in". It pages from the server, and four of its owner-reported bugs
326
+ * were each a way of getting that arithmetic wrong — so the arithmetic lives here once:
327
+ *
328
+ * - The spacer is sized from `total`, so the scrollbar describes the whole result set
329
+ * while only a window is in memory. Rows outside the window render as placeholder
330
+ * rows (`data-cb-placeholder`) of the estimated height.
331
+ * - `onReachEnd` / `onReachStart` fire as the viewport nears either edge of the LOADED
332
+ * window (never of the spacer — measured against `scrollHeight`, a 1,808-row folder
333
+ * stopped paging at row 100 because the trigger sat 1,700 rows past the last real
334
+ * row). `onReachStart` only for a window that does not begin at row 0.
335
+ * - `onNeedWindow(firstVisibleRow)` fires when the viewport comes to REST wholly
336
+ * outside the window — the scrollbar was dragged, or a flick outran paging. Paging
337
+ * cannot catch up from there; the caller fetches ONE window around the row instead.
338
+ * 🔴 Only at rest (`settleMs`): a smooth scroll to a revealed row passes over
339
+ * hundreds of unloaded rows on its way, and acting on each would fetch a window
340
+ * around wherever the animation happened to be.
341
+ *
342
+ * Pair it with {@link handleRef}'s `scrollToIndex` to reveal or follow a row by its
343
+ * row number over the whole result set. Pagination, client-side sort and client-side filtering are off:
344
+ * the server orders and filters, and a window cannot be re-sorted locally.
345
+ */
346
+ serverWindow?: DataTableServerWindow;
347
+ /**
348
+ * The table's imperative handle — `scrollToIndex(absoluteRow, { align, behavior })`
349
+ * and the `scrollElement` itself (for a scroll-memory hook or a caller telling its
350
+ * own scrolls from the reader's). Only meaningful with {@link virtualize} or
351
+ * {@link serverWindow}, where the table owns the scroll container.
352
+ */
353
+ handleRef?: Ref<DataTableHandle>;
354
+ /**
355
+ * Classes for the box that SCROLLS — under {@link scrollBody}, {@link virtualize} or
356
+ * {@link serverWindow}, the table's own scroll container; otherwise the same wrapper,
357
+ * which then merely holds the rows. `className` is the OUTER box (toolbar, table and pager).
358
+ *
359
+ * 🔴 Why (forge task 2302): an app's styles and its browser suites address "the list that
360
+ * scrolls" — apps/music measures `.track-list`'s `scrollHeight` against its spacer in eleven
361
+ * places, because that chain is where its worst owner report lived. With the scroller inside
362
+ * the table, only the table can put a name on it.
363
+ */
364
+ scrollClassName?: string;
253
365
  /**
254
366
  * Adaptive narrow layouts (container-query based, not viewport — a table inside
255
367
  * a narrow split pane or a tablet's sidebar-flanked content area adapts too):
@@ -279,6 +391,28 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
279
391
  /** Initial sort applied before any user interaction (e.g. `[{ id: 'updatedAt', desc: true }]`).
280
392
  * Only seeds the initial state — click-to-sort still fully controls `sorting` afterward. */
281
393
  defaultSort?: SortingState;
394
+ /**
395
+ * The sort, CONTROLLED. A header click reports the next stack through `onSortingChange` and
396
+ * the table shows whatever comes back here. Omit it and the table owns the sort (seeded by
397
+ * `defaultSort`), exactly as before.
398
+ *
399
+ * For a list the SERVER orders (`serverSide`, `serverWindow`), whose sort lives in the app's
400
+ * query and URL: the header then says what the rows are actually sorted by, never what the
401
+ * table last guessed.
402
+ */
403
+ sorting?: SortingState;
404
+ /**
405
+ * `false`: a click on the only-remaining sort key flips it back to its first direction
406
+ * instead of removing it — for a list that always HAS an order (a server `ORDER BY`), where
407
+ * "unsorted" is not a state the rows can be in. Default `true` (asc → desc → out).
408
+ */
409
+ enableSortingRemoval?: boolean;
410
+ /**
411
+ * Sorting is unavailable right now, and this is why — the sortable headers stay VISIBLE but
412
+ * inert, with this sentence on hover (the owner-UI rule: disabled with the reason, never
413
+ * hidden). apps/music: *"The list is in play order — turn shuffle off to sort it."*
414
+ */
415
+ sortDisabledReason?: string;
282
416
  /**
283
417
  * Wide-grid row density (design manual, grid-layout/ — "high-density data tables
284
418
  * over empty visual widgets"):
@@ -408,6 +542,31 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
408
542
  selectedIds?: ReadonlySet<string>;
409
543
  /** The whole next selection (a new Set) after a row or select-all toggle. */
410
544
  onSelectionChange?: (next: ReadonlySet<string>) => void;
545
+ /**
546
+ * The header's select-all box, owned by the CALLER — its state, its name, what a press does.
547
+ *
548
+ * 🔴 For a table that holds only part of what "all" means. Under `serverWindow` the table
549
+ * has a window of a hundred rows out of thousands, so its own select-all could only ever tick
550
+ * the hundred — a lie about the list on screen. apps/music's "all" is every track the VIEW
551
+ * matches, fetched as ids from the server; only the caller can know that set, so the caller
552
+ * owns the box. The row boxes are unchanged (`selectedIds` / `onSelectionChange`).
553
+ */
554
+ selectAll?: DataTableSelectAll;
555
+ /**
556
+ * Attributes and handlers for one body ROW, merged onto it after the table's own —
557
+ * `className` joins, `style` spreads, and a handler the table also sets runs AFTER the
558
+ * table's (a caller can still `preventDefault()`/`stopPropagation()` for everything later).
559
+ *
560
+ * 🔴 Why (forge task 2302): a row is more than its cells. apps/music's track row carries its
561
+ * identity (`data-track-id` — a windowed row's POSITION is not an identity, and every browser
562
+ * suite addresses rows by it), `aria-current` for the playing track, double-click and Enter to
563
+ * play, its own drag payload for the rail, and drop handling to reorder a playlist. None of
564
+ * that is a cell. `rowIndex` is the row's number over the whole result set (a `serverWindow`
565
+ * row's absolute position).
566
+ *
567
+ * Applied to the grid row, the tablet list row and the phone card.
568
+ */
569
+ getRowProps?: (row: TRow, rowIndex: number) => DataTableRowProps;
411
570
  /** `false` renders that row's checkbox DISABLED (still visible) and keeps the
412
571
  * row out of select-all. Pair with {@link unselectableReason}. */
413
572
  isRowSelectable?: (row: TRow) => boolean;
@@ -545,15 +704,23 @@ export function nextSortStack(
545
704
  current: SortingState,
546
705
  id: string,
547
706
  multi: boolean,
707
+ options: {
708
+ /** The column's FIRST direction is descending (`ColDef.sortDescFirst`). */
709
+ descFirst?: boolean;
710
+ /** `false`: the last click of the cycle flips back instead of removing the key
711
+ * (`enableSortingRemoval`). Default `true`. */
712
+ removable?: boolean;
713
+ } = {},
548
714
  ): SortingState {
715
+ const first = options.descFirst ?? false;
549
716
  const existing = current.find((sort) => sort.id === id);
550
717
  if (!existing) {
551
- const ascending = { id, desc: false };
552
- return multi ? [ascending, ...current] : [ascending];
718
+ const started = { id, desc: first };
719
+ return multi ? [started, ...current] : [started];
553
720
  }
554
- if (!existing.desc) {
555
- const flipped = current.map((sort) => (sort.id === id ? { id, desc: true } : sort));
556
- return multi ? flipped : [{ id, desc: true }];
721
+ if (existing.desc === first || options.removable === false) {
722
+ const flipped = { id, desc: !existing.desc };
723
+ return multi ? current.map((sort) => (sort.id === id ? flipped : sort)) : [flipped];
557
724
  }
558
725
  return multi ? current.filter((sort) => sort.id !== id) : [];
559
726
  }
@@ -572,6 +739,49 @@ function readPath(row: unknown, key: string): unknown {
572
739
  }, row);
573
740
  }
574
741
 
742
+ /**
743
+ * `ColDef.hideBelow` as the container-query classes that do it. Literal strings, so the style
744
+ * generators (`scripts/generate*Styles.ts`) find them in the source.
745
+ *
746
+ * 🔴 The column COLLAPSES — zero width, no padding, its content removed — rather than
747
+ * `display: none`. A hidden cell is not a column, but the rows that SPAN the table (the
748
+ * virtualizer's spacers, a server window's placeholder rows, an expanded panel) still say
749
+ * `colSpan={every column}`, and a span wider than the table's real columns makes the missing
750
+ * ones up: they took the width the hidden columns gave back, so the table's rows stopped short
751
+ * of its right edge and the title — the one width-less column — was crushed to "S…". Measured
752
+ * on apps/music at 390px and 1100px, forge task 2302. Collapsed, the column count never moves,
753
+ * and every span stays true. (`[&>*]:hidden` takes the content out of the accessibility tree
754
+ * too, so a collapsed cell reads as nothing, not as a value nobody can see.)
755
+ */
756
+ const HIDE_BELOW_CLASS = {
757
+ sm: '@max-2xl:w-0! @max-2xl:min-w-0! @max-2xl:p-0! @max-2xl:border-0 @max-2xl:[&>*]:hidden',
758
+ md: '@max-4xl:w-0! @max-4xl:min-w-0! @max-4xl:p-0! @max-4xl:border-0 @max-4xl:[&>*]:hidden',
759
+ lg: '@max-6xl:w-0! @max-6xl:min-w-0! @max-6xl:p-0! @max-6xl:border-0 @max-6xl:[&>*]:hidden',
760
+ } as const;
761
+
762
+ /**
763
+ * The table's own props for a row, with the caller's `getRowProps` merged on top: classes join,
764
+ * styles spread, and a handler both set runs the table's first, then the caller's.
765
+ */
766
+ export function mergeRowProps<T extends Record<string, unknown>>(
767
+ own: T,
768
+ extra: DataTableRowProps | undefined,
769
+ ): T & DataTableRowProps {
770
+ if (!extra) return own as T & DataTableRowProps;
771
+ const merged: Record<string, unknown> = { ...own, ...extra };
772
+ if (own.className || extra.className) merged.className = cn(own.className as string | undefined, extra.className);
773
+ if (own.style || extra.style) merged.style = { ...(own.style as CSSProperties | undefined), ...extra.style };
774
+ for (const [key, handler] of Object.entries(extra)) {
775
+ const mine = own[key];
776
+ if (!key.startsWith('on') || typeof handler !== 'function' || typeof mine !== 'function') continue;
777
+ merged[key] = (event: unknown) => {
778
+ (mine as (e: unknown) => void)(event);
779
+ (handler as (e: unknown) => void)(event);
780
+ };
781
+ }
782
+ return merged as T & DataTableRowProps;
783
+ }
784
+
575
785
  /** True when a cell value carries nothing worth a column: null/undefined/''/[]. */
576
786
  function isEmptyCellValue(v: unknown): boolean {
577
787
  if (v == null) return true;
@@ -619,6 +829,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
619
829
  minTableWidth,
620
830
  scrollBody,
621
831
  virtualize,
832
+ serverWindow,
833
+ handleRef,
834
+ scrollClassName,
622
835
  mobileCards = true,
623
836
  serverSide,
624
837
  pageCount,
@@ -628,6 +841,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
628
841
  onGlobalFilterChange,
629
842
  onPaginationChange,
630
843
  defaultSort,
844
+ sorting: sortingProp,
845
+ enableSortingRemoval = true,
846
+ sortDisabledReason,
631
847
  density = 'comfortable',
632
848
  viewMode,
633
849
  onViewModeChange,
@@ -645,11 +861,17 @@ export function DataTable<TRow extends Record<string, unknown>>({
645
861
  unselectableReason,
646
862
  selectionLabel,
647
863
  selectionSummary,
864
+ selectAll,
865
+ getRowProps,
648
866
  }: DataTableProps<TRow>) {
649
867
  // Vertical cell padding for the wide grid tier — the one lever the density knob
650
868
  // pulls (headers + body cells stay aligned by sharing it).
651
869
  const cellPadY = density === 'compact' ? 'py-1.5' : 'py-2.5';
652
- const [sorting, setSorting] = useState<SortingState>(defaultSort ?? []);
870
+ const [ownSorting, setOwnSorting] = useState<SortingState>(defaultSort ?? []);
871
+ const sorting = sortingProp ?? ownSorting;
872
+ /** The sort as of THIS render, for a write that has to start from it (see `applySorting`). */
873
+ const sortingRef = useRef(sorting);
874
+ sortingRef.current = sorting;
653
875
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
654
876
  const [globalFilter, setGlobalFilter] = useState('');
655
877
 
@@ -728,18 +950,26 @@ export function DataTable<TRow extends Record<string, unknown>>({
728
950
  */
729
951
  const applySorting = useCallback(
730
952
  (next: (prev: SortingState) => SortingState) => {
731
- setSorting((prev) => {
732
- const value = next(prev);
733
- setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
734
- onSortingChange?.(value);
735
- return value;
736
- });
953
+ // Computed OUTSIDE a state updater: under a controlled `sorting` there is no state to
954
+ // update, and a notify inside an updater fires twice in StrictMode.
955
+ const value = next(sortingRef.current);
956
+ sortingRef.current = value;
957
+ if (sortingProp === undefined) setOwnSorting(value);
958
+ setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));
959
+ onSortingChange?.(value);
737
960
  },
738
- [onSortingChange],
961
+ [onSortingChange, sortingProp],
962
+ );
963
+ const sortDescFirstOf = useCallback(
964
+ (id: string) => columns.find((col) => col.key === id)?.sortDescFirst ?? false,
965
+ [columns],
739
966
  );
740
967
  const toggleSortKey = useCallback(
741
- (id: string) => applySorting((prev) => nextSortStack(prev, id, multiSort)),
742
- [applySorting, multiSort],
968
+ (id: string) =>
969
+ applySorting((prev) =>
970
+ nextSortStack(prev, id, multiSort, { descFirst: sortDescFirstOf(id), removable: enableSortingRemoval }),
971
+ ),
972
+ [applySorting, enableSortingRemoval, multiSort, sortDescFirstOf],
743
973
  );
744
974
 
745
975
  const tsColumns = useMemo<ColumnDef<TRow>[]>(
@@ -754,6 +984,8 @@ export function DataTable<TRow extends Record<string, unknown>>({
754
984
  align: resolveColumnAlign(col),
755
985
  width: col.width,
756
986
  minWidth: col.minWidth,
987
+ hideBelow: col.hideBelow,
988
+ leading: col.leading,
757
989
  },
758
990
  size: typeof col.width === 'number' ? col.width : undefined,
759
991
  enableSorting: col.sortable ?? false,
@@ -782,6 +1014,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
782
1014
  sortable={col.sortable}
783
1015
  sortIndex={stack.length > 1 ? stack.findIndex((s) => s.id === col.key) : -1}
784
1016
  onSort={() => toggleSortKey(col.key)}
1017
+ disabledReason={sortDisabledReason}
785
1018
  />
786
1019
  );
787
1020
  },
@@ -794,7 +1027,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
794
1027
  />
795
1028
  ),
796
1029
  })),
797
- [liveColumns, onRowEdit, toggleSortKey],
1030
+ [liveColumns, onRowEdit, sortDisabledReason, toggleSortKey],
798
1031
  );
799
1032
 
800
1033
  const labelOf = useCallback(
@@ -856,7 +1089,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
856
1089
  * failure the pager's absence hides rather than reveals, which is why it is tested by
857
1090
  * measuring `scrollHeight` in a real browser.
858
1091
  */
859
- const virtualOptions = virtualize === true ? {} : virtualize || null;
1092
+ const virtualOptions = virtualize === true || (serverWindow && !virtualize) ? {} : virtualize || null;
860
1093
  const virtualEnabled = virtualOptions !== null;
861
1094
  const bodyScrolls = scrollBody || virtualEnabled;
862
1095
  const paginationHidden = hidePagination || virtualEnabled;
@@ -883,7 +1116,10 @@ export function DataTable<TRow extends Record<string, unknown>>({
883
1116
  columns: tsColumns,
884
1117
  getRowId: resolvedGetRowId,
885
1118
  state: { sorting, columnFilters, globalFilter: search, columnVisibility, pagination },
886
- onSortingChange: chainUpdaterResettingPage(setSorting, setPagination, onSortingChange),
1119
+ // Through `applySorting`, like every other write — so a controlled `sorting` is honoured
1120
+ // whether TanStack or a header asked for the change.
1121
+ onSortingChange: (updater) =>
1122
+ applySorting((prev) => (typeof updater === 'function' ? updater(prev) : updater)),
887
1123
  onColumnFiltersChange: chainUpdaterResettingPage(setColumnFilters, setPagination, onColumnFiltersChange),
888
1124
  // TanStack hands the updater whatever `state.globalFilter` is, which is now
889
1125
  // a TableSearchState; the toolbar sets TEXT, so normalise both shapes.
@@ -910,14 +1146,16 @@ export function DataTable<TRow extends Record<string, unknown>>({
910
1146
  if (scope && !scope.includes(columnId)) return false;
911
1147
  return filterableText(row.getValue(columnId)).toLowerCase().includes(text.toLowerCase());
912
1148
  },
913
- manualSorting: serverSide,
914
- manualFiltering: serverSide,
1149
+ // A server window is server-ordered and server-filtered by construction: a WINDOW
1150
+ // re-sorted locally would put row 4,000's neighbours next to row 12's.
1151
+ manualSorting: serverSide || !!serverWindow,
1152
+ manualFiltering: serverSide || !!serverWindow,
915
1153
  manualPagination: serverSide,
916
1154
  pageCount: serverSide ? pageCount : undefined,
917
1155
  rowCount: serverSide ? rowCount : undefined,
918
1156
  getCoreRowModel: getCoreRowModel(),
919
- getSortedRowModel: serverSide ? undefined : getSortedRowModel(),
920
- getFilteredRowModel: serverSide ? undefined : getFilteredRowModel(),
1157
+ getSortedRowModel: serverSide || serverWindow ? undefined : getSortedRowModel(),
1158
+ getFilteredRowModel: serverSide || serverWindow ? undefined : getFilteredRowModel(),
921
1159
  // 🔴 `virtualEnabled` too, not only `serverSide`. See the note where the flag is
922
1160
  // computed: a paginated virtualizer sizes its spacer from one PAGE.
923
1161
  getPaginationRowModel: serverSide || virtualEnabled ? undefined : getPaginationRowModel(),
@@ -959,18 +1197,90 @@ export function DataTable<TRow extends Record<string, unknown>>({
959
1197
 
960
1198
  const rows = table.getRowModel().rows;
961
1199
 
1200
+ /**
1201
+ * 🔴 A {@link serverWindow} row is FIXED-height, never measured. A measured list places
1202
+ * every unloaded row at the estimate and every loaded one at its real height, so the page
1203
+ * that arrives above the viewport re-sizes a hundred rows and moves everything under the
1204
+ * reader — measured in the gate: a smooth reveal of row 4,000 that paged in the rows above
1205
+ * it on arrival came to rest thirteen rows short. apps/music's own list held every row at
1206
+ * one height for the same reason ("Fixed row height is what makes the arithmetic jitter-free").
1207
+ */
1208
+ const fixedRowHeight = serverWindow
1209
+ ? (serverWindow.rowHeight ?? virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44))
1210
+ : null;
962
1211
  const estimateRowHeight =
963
- virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44);
1212
+ fixedRowHeight ?? virtualOptions?.estimateRowHeight ?? (density === 'compact' ? 36 : 44);
964
1213
  const scrollRef = useRef<HTMLDivElement | null>(null);
1214
+ /** Rows before the loaded window, and the size of the whole result set — both 0/`rows.length`
1215
+ * without a {@link serverWindow}, which makes every index below the same number as before. */
1216
+ const windowStart = serverWindow ? Math.max(0, serverWindow.start) : 0;
1217
+ const windowTotal = serverWindow ? Math.max(serverWindow.total, windowStart + rows.length) : rows.length;
1218
+ /** The caller's window callbacks, read at FIRE time: by the time a settle timer fires the
1219
+ * window may have moved, and the fresh handler is the one that knows. */
1220
+ const windowRef = useRef(serverWindow);
1221
+ windowRef.current = serverWindow;
1222
+ const loadedRef = useRef({ start: windowStart, end: windowStart + rows.length, total: windowTotal });
1223
+ loadedRef.current = { start: windowStart, end: windowStart + rows.length, total: windowTotal };
1224
+ const settleRef = useRef<ReturnType<typeof setTimeout> | null>(null);
1225
+ /** The `scrollTop` the last `onChange` saw. The virtualizer also calls `onChange` when its
1226
+ * is-scrolling flag resets and on every re-render; only a MOVE may arm the settle timer, or
1227
+ * the flag's own reset re-asks for the window that was just requested (measured: twice). */
1228
+ const lastTopRef = useRef<number | null>(null);
1229
+ useEffect(
1230
+ () => () => {
1231
+ if (settleRef.current) clearTimeout(settleRef.current);
1232
+ },
1233
+ [],
1234
+ );
965
1235
  const rowVirtualizer = useVirtualizer({
966
- count: virtualEnabled ? rows.length : 0,
1236
+ count: virtualEnabled ? windowTotal : 0,
967
1237
  getScrollElement: () => scrollRef.current,
968
1238
  estimateSize: () => estimateRowHeight,
969
1239
  overscan: virtualOptions?.overscan ?? 8,
1240
+ onChange: serverWindow
1241
+ ? (instance) => {
1242
+ const win = windowRef.current;
1243
+ const element = instance.scrollElement;
1244
+ if (!win || !element) return;
1245
+ const { start, end, total } = loadedRef.current;
1246
+ // Rows over the whole result set: the first one on screen, and the one after the last.
1247
+ const items = instance.getVirtualItems();
1248
+ if (items.length === 0) return;
1249
+ const top = element.scrollTop;
1250
+ const bottom = top + element.clientHeight;
1251
+ const firstShown = items.find((item) => item.end > top)?.index ?? items[0]!.index;
1252
+ const lastShown = (items.findLast((item) => item.start < bottom)?.index ?? items.at(-1)!.index) + 1;
1253
+ const moved = lastTopRef.current !== top;
1254
+ lastTopRef.current = top;
1255
+ // Nothing on screen is loaded. Hand the destination over once the scroll RESTS,
1256
+ // and do not also ask for a page — it would load rows nowhere near the reader.
1257
+ if (firstShown >= end || lastShown <= start) {
1258
+ if (!moved) return;
1259
+ if (settleRef.current) clearTimeout(settleRef.current);
1260
+ settleRef.current = setTimeout(() => {
1261
+ settleRef.current = null;
1262
+ // Read at FIRE time: the window may have arrived while the scroll rested.
1263
+ const loaded = loadedRef.current;
1264
+ if (firstShown < loaded.end && lastShown > loaded.start) return;
1265
+ windowRef.current?.onNeedWindow?.(firstShown);
1266
+ }, win.settleMs ?? 120);
1267
+ return;
1268
+ }
1269
+ if (settleRef.current) {
1270
+ clearTimeout(settleRef.current);
1271
+ settleRef.current = null;
1272
+ }
1273
+ // Against the end of the LOADED window, never the spacer's — see the prop doc.
1274
+ if (win.onReachEnd && end < total && end - lastShown < (win.reachRows ?? 20)) win.onReachEnd();
1275
+ // Tighter, and only off row 0: a reveal lands a few rows into a fresh window, and a
1276
+ // generous trigger here would fire on arrival and cascade back to the top.
1277
+ if (win.onReachStart && start > 0 && firstShown - start < (win.reachRowsUp ?? 8)) win.onReachStart();
1278
+ }
1279
+ : undefined,
970
1280
  // 🔴 MEASURED, not assumed. A wrapping cell, an expanded detail panel and the
971
1281
  // `compact` density all change a row's height, and a caller cannot be asked to
972
1282
  // compute any of them. `estimateSize` only seeds the spacer before first paint.
973
- measureElement: (el) => el.getBoundingClientRect().height,
1283
+ measureElement: (el) => fixedRowHeight ?? el.getBoundingClientRect().height,
974
1284
  });
975
1285
  /**
976
1286
  * 🔴 Invalidate the measurement cache when the row height changes.
@@ -994,8 +1304,30 @@ export function DataTable<TRow extends Record<string, unknown>>({
994
1304
  }, [rowVirtualizer, estimateRowHeight]);
995
1305
  const virtualRows = virtualEnabled ? rowVirtualizer.getVirtualItems() : [];
996
1306
  /** The rows to render, and the two spacers that keep the scrollbar honest about the
997
- * ones that are not. Off, this is every row and no spacers — byte-identical output. */
998
- const bodyRows = virtualEnabled ? virtualRows.map((v) => rows[v.index]!) : rows;
1307
+ * ones that are not. Off, this is every row and no spacers — byte-identical output.
1308
+ * `null` is a row a {@link serverWindow} has not loaded: a placeholder of the estimated
1309
+ * height, so the window can land anywhere in the spacer before its rows arrive. */
1310
+ const bodyRows: (Row<TRow> | null)[] = virtualEnabled
1311
+ ? virtualRows.map((v) => rows[v.index - windowStart] ?? null)
1312
+ : rows;
1313
+ useImperativeHandle(
1314
+ handleRef,
1315
+ () => ({
1316
+ get scrollElement() {
1317
+ return scrollRef.current;
1318
+ },
1319
+ scrollToIndex(index, options = {}) {
1320
+ const element = scrollRef.current;
1321
+ if (!element || !virtualEnabled) return null;
1322
+ const clamped = Math.max(0, Math.min(index, loadedRef.current.total - 1));
1323
+ const [offset] = rowVirtualizer.getOffsetForIndex(clamped, options.align ?? 'center') ?? [clamped * estimateRowHeight];
1324
+ const top = Math.max(0, Math.round(offset));
1325
+ element.scrollTo({ top, behavior: options.behavior ?? 'auto' });
1326
+ return top;
1327
+ },
1328
+ }),
1329
+ [estimateRowHeight, rowVirtualizer, virtualEnabled],
1330
+ );
999
1331
  const padTop = virtualEnabled ? (virtualRows[0]?.start ?? 0) : 0;
1000
1332
  const padBottom = virtualEnabled
1001
1333
  ? rowVirtualizer.getTotalSize() - (virtualRows.at(-1)?.end ?? 0)
@@ -1083,7 +1415,24 @@ export function DataTable<TRow extends Record<string, unknown>>({
1083
1415
  // Enter-to-open handler.
1084
1416
  onKeyDown: (event: KeyboardEvent<HTMLElement>) => event.stopPropagation(),
1085
1417
  });
1086
- const headerCheckbox = (label?: ReactNode) => (
1418
+ const headerCheckbox = (label?: ReactNode) =>
1419
+ selectAll ? (
1420
+ // The caller's box (see `selectAll`). 🔴 The Tooltip wraps a SPAN, never the Checkbox:
1421
+ // a Radix trigger clones its child with its own `data-state`, which would overwrite the
1422
+ // one the box paints its tick and its `Minus` from (apps/music measured it, 2026-09-19).
1423
+ <Tooltip content={selectAll.label}>
1424
+ <span className='inline-flex'>
1425
+ <Checkbox
1426
+ checked={selectAll.checked}
1427
+ disabled={selectAll.disabled}
1428
+ onCheckedChange={(checked) => selectAll.onChange(checked === true)}
1429
+ aria-label={selectAll.label}
1430
+ label={label}
1431
+ labelClassName={label == null ? undefined : 'text-xs text-muted-foreground'}
1432
+ />
1433
+ </span>
1434
+ </Tooltip>
1435
+ ) : (
1087
1436
  <Checkbox
1088
1437
  checked={headerChecked}
1089
1438
  disabled={selectableFilteredIds.length === 0}
@@ -1113,7 +1462,13 @@ export function DataTable<TRow extends Record<string, unknown>>({
1113
1462
  // passes its own gets exactly that, and `TableToolbar` reads the same
1114
1463
  // controls off `table.options.meta`, so composing a toolbar is never
1115
1464
  // the thing that costs you the search box.
1116
- (searchable ? <TableToolbar table={table} searchPlaceholder={searchPlaceholder} /> : null));
1465
+ (searchable ? (
1466
+ <ToolbarPart
1467
+ table={table}
1468
+ searchPlaceholder={searchPlaceholder}
1469
+ fallback={<ToolbarPlaceholder />}
1470
+ />
1471
+ ) : null));
1117
1472
  const visibleColumnCount =
1118
1473
  table.getVisibleLeafColumns().length + (hasActions ? 1 : 0) + (selectionEnabled ? 1 : 0);
1119
1474
  // Cards track the SAME live visibility state as the grid (ViewOptionsMenu toggles
@@ -1159,14 +1514,21 @@ export function DataTable<TRow extends Record<string, unknown>>({
1159
1514
  <Skeleton key={`dt-skeleton-${i}`} className='h-10 w-full' />
1160
1515
  ))}
1161
1516
  </div>
1162
- ) : rows.length === 0 ? (
1517
+ ) : rows.length === 0 && windowTotal === 0 ? (
1163
1518
  <div className='p-2'>{emptyState ?? <EmptyState title='No results' />}</div>
1164
1519
  ) : (
1165
1520
  // scrollBody makes the table body the one scroll container for BOTH axes —
1166
1521
  // required for stickyHeader to pin (see the prop doc); ScrollArea's
1167
1522
  // vertical-only flex model can't own horizontal table scroll.
1168
- // guardrails-ignore no-raw-overflow: dual-axis table scroll container — sticky header pins to it; ScrollArea cannot own horizontal table scroll.
1169
- <div ref={scrollRef} className={cn(bodyScrolls && 'min-h-0 flex-1 overflow-auto')}>
1523
+ // `data-cb-table-scroll` names the box when it IS the scroller — the table's own, the way
1524
+ // `ScrollArea` stamps `data-cb-scrollarea`, so a layout check can tell the design system's
1525
+ // scroller from a hand-rolled `overflow: auto` wearing the same class (forge task 2302).
1526
+ <div
1527
+ ref={scrollRef}
1528
+ data-cb-table-scroll={bodyScrolls ? '' : undefined}
1529
+ // guardrails-ignore no-raw-overflow: dual-axis table scroll container — sticky header pins to it; ScrollArea cannot own horizontal table scroll.
1530
+ className={cn(bodyScrolls && 'min-h-0 flex-1 overflow-auto', scrollClassName)}
1531
+ >
1170
1532
  {/* ── The CARD view (opt-in via `viewMode`) — the same rows the grid
1171
1533
  would show, after the same filter/sort/page, through the same cell
1172
1534
  renderers. It replaces all three width tiers rather than sitting
@@ -1212,7 +1574,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
1212
1574
  columns={cardColumns}
1213
1575
  className={rowClassName?.(row.original)}
1214
1576
  onRowClick={onRowClick}
1215
- dragProps={dragPropsFor(row.original)}
1577
+ dragProps={mergeRowProps(dragPropsFor(row.original), getRowProps?.(row.original, windowStart + row.index))}
1216
1578
  select={selectionEnabled ? rowCheckbox(row) : undefined}
1217
1579
  actions={
1218
1580
  hasActions ? (
@@ -1290,13 +1652,18 @@ export function DataTable<TRow extends Record<string, unknown>>({
1290
1652
  return (
1291
1653
  <Fragment key={row.id}>
1292
1654
  <div
1293
- {...dragPropsFor(row.original)}
1294
- className={cn(
1295
- 'grid items-center gap-3 px-4 py-3 transition-colors hover:bg-muted/40',
1296
- getRowDrag && 'cursor-grab active:cursor-grabbing',
1297
- rowClassName?.(row.original),
1655
+ {...mergeRowProps(
1656
+ {
1657
+ ...dragPropsFor(row.original),
1658
+ className: cn(
1659
+ 'grid items-center gap-3 px-4 py-3 transition-colors hover:bg-muted/40',
1660
+ getRowDrag && 'cursor-grab active:cursor-grabbing',
1661
+ rowClassName?.(row.original),
1662
+ ),
1663
+ style: { gridTemplateColumns: template },
1664
+ },
1665
+ getRowProps?.(row.original, windowStart + row.index),
1298
1666
  )}
1299
- style={{ gridTemplateColumns: template }}
1300
1667
  >
1301
1668
  {selectionEnabled ? (
1302
1669
  <div {...selectCellProps(row)} className='-my-3 flex self-stretch items-center justify-center'>
@@ -1373,20 +1740,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
1373
1740
  <thead>
1374
1741
  {table.getHeaderGroups().map((hg) => (
1375
1742
  <tr key={hg.id}>
1376
- {selectionEnabled ? (
1377
- <th
1378
- scope='col'
1379
- className={cn(
1380
- 'w-11 border-b border-border px-0 text-center',
1381
- stickyHeader && 'sticky top-0 z-10 bg-card/95 backdrop-blur-sm',
1382
- stickyFirstColumn && 'sticky left-0 bg-card',
1383
- stickyFirstColumn && (stickyHeader ? 'z-30' : 'z-20'),
1384
- )}
1385
- >
1386
- {headerCheckbox()}
1387
- </th>
1388
- ) : null}
1389
- {hg.headers.map((h, headerIndex) => {
1743
+ {(() => {
1744
+ // `ColDef.leading` columns sit BEFORE the checkbox column; see its doc.
1745
+ const renderHeader = (h: (typeof hg.headers)[number], headerIndex: number) => {
1390
1746
  const sorted = h.column.getIsSorted();
1391
1747
  const meta = h.column.columnDef.meta;
1392
1748
  const width = meta?.width ?? h.column.columnDef.size;
@@ -1429,6 +1785,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
1429
1785
  ? 'sticky left-11 bg-card shadow-[1px_0_0_0_var(--color-border)]'
1430
1786
  : 'sticky left-0 bg-card shadow-[1px_0_0_0_var(--color-border)]'),
1431
1787
  frozen && (stickyHeader ? 'z-30' : 'z-20'),
1788
+ meta?.hideBelow && HIDE_BELOW_CLASS[meta.hideBelow],
1432
1789
  )}
1433
1790
  >
1434
1791
  {h.isPlaceholder
@@ -1436,7 +1793,28 @@ export function DataTable<TRow extends Record<string, unknown>>({
1436
1793
  : flexRender(h.column.columnDef.header, h.getContext())}
1437
1794
  </th>
1438
1795
  );
1439
- })}
1796
+ };
1797
+ const isLeading = (h: (typeof hg.headers)[number]) => h.column.columnDef.meta?.leading === true;
1798
+ return (
1799
+ <>
1800
+ {hg.headers.filter(isLeading).map((h) => renderHeader(h, -1))}
1801
+ {selectionEnabled ? (
1802
+ <th
1803
+ scope='col'
1804
+ className={cn(
1805
+ 'w-11 border-b border-border px-0 text-center',
1806
+ stickyHeader && 'sticky top-0 z-10 bg-card/95 backdrop-blur-sm',
1807
+ stickyFirstColumn && 'sticky left-0 bg-card',
1808
+ stickyFirstColumn && (stickyHeader ? 'z-30' : 'z-20'),
1809
+ )}
1810
+ >
1811
+ {headerCheckbox()}
1812
+ </th>
1813
+ ) : null}
1814
+ {hg.headers.filter((h) => !isLeading(h)).map(renderHeader)}
1815
+ </>
1816
+ );
1817
+ })()}
1440
1818
  {hasActions ? (
1441
1819
  <th
1442
1820
  className={cn(
@@ -1460,6 +1838,25 @@ export function DataTable<TRow extends Record<string, unknown>>({
1460
1838
  </tr>
1461
1839
  ) : null}
1462
1840
  {bodyRows.map((row, sliceIndex) => {
1841
+ if (row === null) {
1842
+ // A row the server window has not loaded yet: the estimated height, so
1843
+ // the spacer arithmetic holds, and a skeleton line rather than a gap.
1844
+ const index = virtualRows[sliceIndex]!.index;
1845
+ return (
1846
+ <tr
1847
+ key={`cb-placeholder-${index}`}
1848
+ data-index={index}
1849
+ data-cb-placeholder=''
1850
+ aria-hidden
1851
+ className={cn('border-b border-border', index % 2 === 1 && 'bg-muted/50')}
1852
+ style={{ height: estimateRowHeight }}
1853
+ >
1854
+ <td colSpan={visibleColumnCount} className='px-3'>
1855
+ <Skeleton className='h-3' style={{ width: '40%' }} />
1856
+ </td>
1857
+ </tr>
1858
+ );
1859
+ }
1463
1860
  /* 🔴 The ZEBRA index is the row's ABSOLUTE position, not its
1464
1861
  position in the rendered slice. Off by that, the stripes
1465
1862
  would repaint themselves every time the window moved — the
@@ -1474,12 +1871,14 @@ export function DataTable<TRow extends Record<string, unknown>>({
1474
1871
  // 🔴 The virtualizer reads its real height back off this node, and
1475
1872
  // `data-index` is how it knows WHICH row it measured — without it
1476
1873
  // every measurement lands on index 0 and the spacer never grows.
1477
- {...(virtualEnabled
1478
- ? { ref: rowVirtualizer.measureElement, 'data-index': rowIndex }
1479
- : {})}
1480
- data-expanded={isExpanded || undefined}
1481
- {...dragPropsFor(row.original)}
1482
- className={cn(
1874
+ // (The ref stays OUT of the merge: `getRowProps` cannot take it.)
1875
+ ref={virtualEnabled && fixedRowHeight === null ? rowVirtualizer.measureElement : undefined}
1876
+ {...mergeRowProps({
1877
+ ...(virtualEnabled ? { 'data-index': rowIndex } : {}),
1878
+ style: fixedRowHeight === null ? undefined : { height: fixedRowHeight },
1879
+ 'data-expanded': isExpanded || undefined,
1880
+ ...dragPropsFor(row.original),
1881
+ className: cn(
1483
1882
  getRowDrag && 'cursor-grab active:cursor-grabbing',
1484
1883
  // Always-on hover wash: wide rows need a trace line for the
1485
1884
  // eye even when the row itself isn't clickable. Zebra fill on
@@ -1493,39 +1892,20 @@ export function DataTable<TRow extends Record<string, unknown>>({
1493
1892
  isExpanded && 'border-0 bg-muted/30',
1494
1893
  onRowClick &&
1495
1894
  'cursor-pointer hover:bg-muted focus-visible:bg-muted focus-visible:outline-none',
1496
- )}
1497
- tabIndex={onRowClick ? 0 : undefined}
1498
- onClick={onRowClick ? () => onRowClick(row.original) : undefined}
1499
- onKeyDown={
1500
- onRowClick
1501
- ? (e) => {
1502
- if (e.key === 'Enter') onRowClick(row.original);
1503
- }
1504
- : undefined
1505
- }
1506
- >
1507
- {selectionEnabled ? (
1508
- <td
1509
- {...selectCellProps(row)}
1510
- style={
1511
- stickyFirstColumn
1512
- ? ({
1513
- '--cb-frozen-bg':
1514
- rowIndex % 2 === 1
1515
- ? 'color-mix(in srgb, var(--color-muted) 50%, var(--color-card))'
1516
- : 'var(--color-card)',
1517
- } as CSSProperties)
1518
- : undefined
1895
+ ),
1896
+ tabIndex: onRowClick ? 0 : undefined,
1897
+ onClick: onRowClick ? (event: MouseEvent<HTMLElement>) => onRowClick(row.original, event) : undefined,
1898
+ onKeyDown: onRowClick
1899
+ ? (e: KeyboardEvent<HTMLElement>) => {
1900
+ if (e.key === 'Enter') onRowClick(row.original);
1519
1901
  }
1520
- className={cn(
1521
- 'w-11 cursor-pointer px-0 text-center align-middle',
1522
- stickyFirstColumn && 'sticky left-0 z-10 bg-[var(--cb-frozen-bg)]',
1523
- )}
1524
- >
1525
- {rowCheckbox(row)}
1526
- </td>
1527
- ) : null}
1528
- {row.getVisibleCells().map((cell, cellIndex) => {
1902
+ : undefined,
1903
+ }, getRowProps?.(row.original, rowIndex))}
1904
+ >
1905
+ {(() => {
1906
+ const cells = row.getVisibleCells();
1907
+ const isLeading = (cell: (typeof cells)[number]) => cell.column.columnDef.meta?.leading === true;
1908
+ const renderCell = (cell: (typeof cells)[number], cellIndex: number) => {
1529
1909
  const frozen = stickyFirstColumn === true && cellIndex === 0;
1530
1910
  return (
1531
1911
  <td
@@ -1560,14 +1940,43 @@ export function DataTable<TRow extends Record<string, unknown>>({
1560
1940
  // `overflow: hidden`: a cell may host a menu/tooltip that
1561
1941
  // has to escape its bounds.
1562
1942
  fixedLayout && '[overflow-wrap:anywhere]',
1563
- (cell.column.columnDef.meta as { align?: 'left' | 'right' } | undefined)
1564
- ?.align === 'right' && 'text-right',
1943
+ cell.column.columnDef.meta?.align === 'right' && 'text-right',
1944
+ cell.column.columnDef.meta?.hideBelow &&
1945
+ HIDE_BELOW_CLASS[cell.column.columnDef.meta.hideBelow],
1565
1946
  )}
1566
1947
  >
1567
1948
  {flexRender(cell.column.columnDef.cell, cell.getContext())}
1568
1949
  </td>
1569
1950
  );
1570
- })}
1951
+ };
1952
+ return (
1953
+ <>
1954
+ {cells.filter(isLeading).map((cell) => renderCell(cell, -1))}
1955
+ {selectionEnabled ? (
1956
+ <td
1957
+ {...selectCellProps(row)}
1958
+ style={
1959
+ stickyFirstColumn
1960
+ ? ({
1961
+ '--cb-frozen-bg':
1962
+ rowIndex % 2 === 1
1963
+ ? 'color-mix(in srgb, var(--color-muted) 50%, var(--color-card))'
1964
+ : 'var(--color-card)',
1965
+ } as CSSProperties)
1966
+ : undefined
1967
+ }
1968
+ className={cn(
1969
+ 'w-11 cursor-pointer px-0 text-center align-middle',
1970
+ stickyFirstColumn && 'sticky left-0 z-10 bg-[var(--cb-frozen-bg)]',
1971
+ )}
1972
+ >
1973
+ {rowCheckbox(row)}
1974
+ </td>
1975
+ ) : null}
1976
+ {cells.filter((cell) => !isLeading(cell)).map(renderCell)}
1977
+ </>
1978
+ );
1979
+ })()}
1571
1980
  {hasActions ? (
1572
1981
  <td className='px-2 py-2'>
1573
1982
  <RowActions
@@ -1628,7 +2037,11 @@ export function DataTable<TRow extends Record<string, unknown>>({
1628
2037
  )}
1629
2038
 
1630
2039
  {!loading && rows.length > 0 && !paginationHidden ? (
1631
- <TablePagination table={table} pageSizeOptions={pageSizeOptions} />
2040
+ <PaginationPart
2041
+ table={table}
2042
+ pageSizeOptions={pageSizeOptions}
2043
+ fallback={<PaginationPlaceholder />}
2044
+ />
1632
2045
  ) : null}
1633
2046
  </div>
1634
2047
  );
@@ -1655,7 +2068,8 @@ function MobileRowCard<TRow extends Record<string, unknown>>({
1655
2068
  columns: ColDef<TRow>[];
1656
2069
  className?: string;
1657
2070
  onRowClick?: (row: TRow) => void;
1658
- dragProps?: { draggable?: boolean; onDragStart?: (event: DragEvent<HTMLElement>) => void };
2071
+ /** The drag-source props and the caller's `getRowProps`, already merged. */
2072
+ dragProps?: DataTableRowProps;
1659
2073
  /** The row's selection checkbox, when the table selects — leads the card. */
1660
2074
  select?: ReactNode;
1661
2075
  actions: ReactNode;
@@ -1742,7 +2156,7 @@ function MobileRowCard<TRow extends Record<string, unknown>>({
1742
2156
  pad='sm'
1743
2157
  radius='lg'
1744
2158
  {...dragProps}
1745
- className={cn('relative isolate', dragProps?.draggable && 'cursor-grab', className)}
2159
+ className={cn('relative isolate', dragProps?.draggable && 'cursor-grab', className, dragProps?.className)}
1746
2160
  >
1747
2161
  {/* Context/kebab actions ride the top-right corner inline with the title —
1748
2162
  parking them in the footer left a dead whitespace ocean mid-card (owner