@brightlocal/ui-components 3.0.0 → 3.2.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.
- package/README.md +7 -1
- package/component-meta.json +749 -53
- package/deprecations.json +114 -4
- package/dist/accordion.cjs +1 -1
- package/dist/accordion.d.ts +36 -0
- package/dist/accordion.d.ts.map +1 -1
- package/dist/accordion.js +74 -61
- package/dist/alert-dialog.cjs +1 -1
- package/dist/alert-dialog.d.ts +32 -3
- package/dist/alert-dialog.d.ts.map +1 -1
- package/dist/alert-dialog.js +61 -58
- package/dist/alert.cjs +1 -1
- package/dist/alert.d.ts.map +1 -1
- package/dist/alert.js +58 -57
- package/dist/badge.cjs +1 -1
- package/dist/badge.d.ts +9 -0
- package/dist/badge.d.ts.map +1 -1
- package/dist/badge.js +50 -30
- package/dist/banner.cjs +1 -0
- package/dist/banner.d.ts +81 -0
- package/dist/banner.d.ts.map +1 -0
- package/dist/banner.js +176 -0
- package/dist/blocks/empty-state.cjs +1 -1
- package/dist/blocks/empty-state.d.ts +4 -3
- package/dist/blocks/empty-state.d.ts.map +1 -1
- package/dist/blocks/empty-state.js +50 -57
- package/dist/blocks/progress-state.d.ts +2 -2
- package/dist/blocks/sidebar.cjs +1 -1
- package/dist/blocks/sidebar.d.ts +17 -0
- package/dist/blocks/sidebar.d.ts.map +1 -1
- package/dist/blocks/sidebar.js +8 -2
- package/dist/brand-illustration-motif.d.ts +1 -1
- package/dist/button-group.cjs +1 -0
- package/dist/button-group.d.ts +36 -0
- package/dist/button-group.d.ts.map +1 -0
- package/dist/button-group.js +47 -0
- package/dist/button.cjs +1 -1
- package/dist/button.js +1 -1
- package/dist/card.cjs +1 -1
- package/dist/card.d.ts +105 -7
- package/dist/card.d.ts.map +1 -1
- package/dist/card.js +198 -101
- package/dist/chart.cjs +3 -3
- package/dist/chart.d.ts +270 -24
- package/dist/chart.d.ts.map +1 -1
- package/dist/chart.js +497 -322
- package/dist/checkbox.cjs +1 -1
- package/dist/checkbox.d.ts +1 -1
- package/dist/checkbox.d.ts.map +1 -1
- package/dist/checkbox.js +2 -1
- package/dist/chip.cjs +1 -1
- package/dist/chip.d.ts +38 -4
- package/dist/chip.d.ts.map +1 -1
- package/dist/chip.js +95 -81
- package/dist/combobox.cjs +1 -1
- package/dist/combobox.js +2 -2
- package/dist/command.cjs +1 -1
- package/dist/command.d.ts +23 -1
- package/dist/command.d.ts.map +1 -1
- package/dist/command.js +251 -225
- package/dist/data-table.cjs +1 -1
- package/dist/data-table.d.ts +201 -23
- package/dist/data-table.d.ts.map +1 -1
- package/dist/data-table.js +712 -568
- package/dist/date-picker.cjs +1 -1
- package/dist/date-picker.d.ts +13 -5
- package/dist/date-picker.d.ts.map +1 -1
- package/dist/date-picker.js +54 -53
- package/dist/field.cjs +1 -1
- package/dist/field.d.ts +8 -1
- package/dist/field.d.ts.map +1 -1
- package/dist/field.js +79 -52
- package/dist/global-layout.cjs +1 -1
- package/dist/global-layout.d.ts +105 -13
- package/dist/global-layout.d.ts.map +1 -1
- package/dist/global-layout.js +146 -129
- package/dist/grid.d.ts +26 -3
- package/dist/grid.d.ts.map +1 -1
- package/dist/hooks/use-breakpoint.cjs +1 -1
- package/dist/hooks/use-breakpoint.d.ts +1 -1
- package/dist/hooks/use-breakpoint.d.ts.map +1 -1
- package/dist/hooks/use-breakpoint.js +1 -0
- package/dist/hooks/use-mobile.cjs +1 -0
- package/dist/hooks/use-mobile.js +8 -0
- package/dist/index.cjs +1 -1
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +594 -553
- package/dist/info-tooltip.cjs +1 -0
- package/dist/info-tooltip.d.ts +39 -0
- package/dist/info-tooltip.d.ts.map +1 -0
- package/dist/info-tooltip.js +41 -0
- package/dist/input-chip.cjs +1 -1
- package/dist/input-chip.js +1 -1
- package/dist/input-group.cjs +1 -1
- package/dist/input-group.d.ts +33 -2
- package/dist/input-group.d.ts.map +1 -1
- package/dist/input-group.js +167 -54
- package/dist/input-otp.cjs +1 -1
- package/dist/input-otp.js +9 -9
- package/dist/input-password.cjs +1 -1
- package/dist/input-password.d.ts +45 -15
- package/dist/input-password.d.ts.map +1 -1
- package/dist/input-password.js +31 -30
- package/dist/input.cjs +1 -1
- package/dist/input.js +10 -10
- package/dist/lib/block-illustration.cjs +1 -1
- package/dist/lib/block-illustration.d.ts +4 -1
- package/dist/lib/block-illustration.d.ts.map +1 -1
- package/dist/lib/block-illustration.js +12 -11
- package/dist/lib/empty-chip.cjs +1 -0
- package/dist/lib/empty-chip.d.ts +4 -0
- package/dist/lib/empty-chip.d.ts.map +1 -0
- package/dist/lib/empty-chip.js +13 -0
- package/dist/lib/utils.cjs +1 -1
- package/dist/lib/utils.d.ts.map +1 -1
- package/dist/lib/utils.js +4 -3
- package/dist/list.cjs +1 -1
- package/dist/list.js +1 -1
- package/dist/multi-select-filter.cjs +1 -0
- package/dist/multi-select-filter.d.ts +178 -0
- package/dist/multi-select-filter.d.ts.map +1 -0
- package/dist/multi-select-filter.js +463 -0
- package/dist/pagination.cjs +1 -1
- package/dist/pagination.d.ts +3 -0
- package/dist/pagination.d.ts.map +1 -1
- package/dist/pagination.js +57 -57
- package/dist/progress.cjs +1 -1
- package/dist/progress.d.ts +123 -16
- package/dist/progress.d.ts.map +1 -1
- package/dist/progress.js +89 -75
- package/dist/rating.cjs +1 -1
- package/dist/rating.js +18 -18
- package/dist/relative-date.cjs +1 -0
- package/dist/relative-date.d.ts +65 -0
- package/dist/relative-date.d.ts.map +1 -0
- package/dist/relative-date.js +128 -0
- package/dist/scroll-area.cjs +1 -1
- package/dist/scroll-area.d.ts +15 -6
- package/dist/scroll-area.d.ts.map +1 -1
- package/dist/scroll-area.js +38 -36
- package/dist/select.cjs +2 -2
- package/dist/select.d.ts +24 -3
- package/dist/select.d.ts.map +1 -1
- package/dist/select.js +130 -110
- package/dist/sheet.cjs +1 -1
- package/dist/sheet.d.ts +78 -2
- package/dist/sheet.d.ts.map +1 -1
- package/dist/sheet.js +192 -85
- package/dist/single-select-filter.cjs +1 -0
- package/dist/single-select-filter.d.ts +81 -0
- package/dist/single-select-filter.d.ts.map +1 -0
- package/dist/single-select-filter.js +226 -0
- package/dist/sonner.cjs +1 -1
- package/dist/sonner.d.ts.map +1 -1
- package/dist/sonner.js +22 -22
- package/dist/split-layout.cjs +1 -1
- package/dist/split-layout.d.ts +1 -1
- package/dist/split-layout.js +13 -13
- package/dist/table.cjs +1 -1
- package/dist/table.d.ts +45 -4
- package/dist/table.d.ts.map +1 -1
- package/dist/table.js +90 -73
- package/dist/tabs.cjs +1 -1
- package/dist/tabs.d.ts +12 -1
- package/dist/tabs.d.ts.map +1 -1
- package/dist/tabs.js +148 -126
- package/dist/textarea.cjs +1 -1
- package/dist/textarea.js +1 -1
- package/dist/tooltip.cjs +1 -1
- package/dist/tooltip.d.ts +38 -36
- package/dist/tooltip.d.ts.map +1 -1
- package/dist/tooltip.js +262 -73
- package/dist/typography-heading.cjs +1 -1
- package/dist/typography-heading.d.ts +13 -0
- package/dist/typography-heading.d.ts.map +1 -1
- package/dist/typography-heading.js +32 -21
- package/dist/typography-text.cjs +1 -1
- package/dist/typography-text.d.ts +15 -2
- package/dist/typography-text.d.ts.map +1 -1
- package/dist/typography-text.js +35 -24
- package/dist/typography.d.ts +1 -1
- package/package.json +5 -6
- package/src/blocks/empty-state.tsx +17 -24
- package/src/blocks/progress-state.tsx +2 -2
- package/src/blocks/sidebar.tsx +26 -2
- package/src/components/accordion.tsx +82 -27
- package/src/components/alert-dialog.tsx +50 -5
- package/src/components/alert.tsx +16 -8
- package/src/components/badge.tsx +40 -3
- package/src/components/banner.tsx +288 -0
- package/src/components/brand-illustration-motif.tsx +1 -1
- package/src/components/button-group.tsx +112 -0
- package/src/components/button.tsx +1 -1
- package/src/components/card.tsx +249 -27
- package/src/components/chart.tsx +586 -53
- package/src/components/checkbox.tsx +1 -1
- package/src/components/chip.tsx +83 -10
- package/src/components/combobox.tsx +2 -2
- package/src/components/command.tsx +56 -4
- package/src/components/data-table.tsx +842 -199
- package/src/components/date-picker.tsx +18 -7
- package/src/components/field.tsx +81 -12
- package/src/components/global-layout.tsx +176 -38
- package/src/components/grid.tsx +34 -3
- package/src/components/info-tooltip.tsx +94 -0
- package/src/components/input-chip.tsx +1 -1
- package/src/components/input-group.tsx +246 -11
- package/src/components/input-otp.tsx +1 -1
- package/src/components/input-password.tsx +56 -22
- package/src/components/input.tsx +1 -1
- package/src/components/list.tsx +1 -1
- package/src/components/multi-select-filter.tsx +912 -0
- package/src/components/pagination.tsx +10 -3
- package/src/components/progress.tsx +190 -31
- package/src/components/rating.tsx +1 -1
- package/src/components/relative-date.tsx +230 -0
- package/src/components/scroll-area.tsx +23 -10
- package/src/components/select.tsx +65 -11
- package/src/components/sheet.tsx +240 -4
- package/src/components/single-select-filter.tsx +443 -0
- package/src/components/sonner.tsx +16 -5
- package/src/components/split-layout.tsx +2 -2
- package/src/components/table.tsx +71 -11
- package/src/components/tabs.tsx +93 -46
- package/src/components/textarea.tsx +1 -1
- package/src/components/tooltip.tsx +440 -68
- package/src/components/typography-heading.tsx +24 -0
- package/src/components/typography-text.tsx +27 -3
- package/src/components/typography.tsx +1 -1
- package/src/hooks/use-breakpoint.ts +2 -1
- package/src/index.ts +6 -0
- package/src/lib/block-illustration.tsx +5 -1
- package/src/lib/empty-chip.ts +24 -0
- package/src/lib/utils.ts +1 -0
|
@@ -25,6 +25,7 @@ import {
|
|
|
25
25
|
type Column,
|
|
26
26
|
type ColumnDef,
|
|
27
27
|
type ExpandedState,
|
|
28
|
+
type Header,
|
|
28
29
|
type PaginationState,
|
|
29
30
|
type Row,
|
|
30
31
|
type RowData,
|
|
@@ -56,13 +57,18 @@ import {
|
|
|
56
57
|
ArrowUpDown,
|
|
57
58
|
ChevronRight,
|
|
58
59
|
Search,
|
|
59
|
-
X,
|
|
60
60
|
} from "@brightlocal/icons";
|
|
61
61
|
|
|
62
62
|
import { cn } from "@brightlocal/ui-components/lib/utils";
|
|
63
|
+
import { useIsBelowBreakpoint } from "@brightlocal/ui-components/hooks/use-breakpoint";
|
|
63
64
|
import { Button } from "./button";
|
|
64
65
|
import { Checkbox } from "./checkbox";
|
|
65
|
-
import {
|
|
66
|
+
import {
|
|
67
|
+
InputGroup,
|
|
68
|
+
InputGroupAddon,
|
|
69
|
+
InputGroupClear,
|
|
70
|
+
InputGroupInput,
|
|
71
|
+
} from "./input-group";
|
|
66
72
|
import {
|
|
67
73
|
Pagination,
|
|
68
74
|
PaginationContent,
|
|
@@ -74,6 +80,7 @@ import {
|
|
|
74
80
|
usePagination,
|
|
75
81
|
} from "./pagination";
|
|
76
82
|
import { Skeleton } from "./skeleton";
|
|
83
|
+
import { Spinner } from "./spinner";
|
|
77
84
|
import {
|
|
78
85
|
Table,
|
|
79
86
|
TableBody,
|
|
@@ -81,6 +88,7 @@ import {
|
|
|
81
88
|
TableHead,
|
|
82
89
|
TableHeader,
|
|
83
90
|
TableRow,
|
|
91
|
+
scrollRegionProps,
|
|
84
92
|
} from "./table";
|
|
85
93
|
import { TypographyMuted } from "./typography";
|
|
86
94
|
|
|
@@ -460,6 +468,22 @@ export function useDataTable<TData>(
|
|
|
460
468
|
* rendering-focused — wire toolbars, pagination, and search components
|
|
461
469
|
* outside of it via composition.
|
|
462
470
|
*/
|
|
471
|
+
/* -------------------------------------------------------------------------------------------------
|
|
472
|
+
* Internal: refetch context (DS-916)
|
|
473
|
+
*
|
|
474
|
+
* While a server-side refetch is in flight the rows on screen are stale.
|
|
475
|
+
* Selection controls rendered inside the table (`DataTableSelectAllCheckbox`,
|
|
476
|
+
* `DataTableSelectRowCheckbox`) read this context and block interaction:
|
|
477
|
+
* `aria-disabled` plus a guarded change handler (the checkbox is controlled,
|
|
478
|
+
* so a guarded handler stops pointer and keyboard alike). Not `inert` — that
|
|
479
|
+
* removes the checkbox from the accessibility tree, leaving the select-all
|
|
480
|
+
* `<th>` with no screen-reader-visible content (axe `empty-table-header`)
|
|
481
|
+
* and yanking focus from a user mid-interaction. The bulk-actions bar lives
|
|
482
|
+
* outside the table's subtree, so it takes its own `refetching` prop instead.
|
|
483
|
+
* -----------------------------------------------------------------------------------------------*/
|
|
484
|
+
|
|
485
|
+
const DataTableRefetchingContext = React.createContext(false);
|
|
486
|
+
|
|
463
487
|
export interface DataTableProps<TData> {
|
|
464
488
|
/** TanStack Table instance (usually returned from `useDataTable`). */
|
|
465
489
|
table: TanStackTable<TData>;
|
|
@@ -471,6 +495,32 @@ export interface DataTableProps<TData> {
|
|
|
471
495
|
trackingLabel?: string;
|
|
472
496
|
/** Show skeleton rows instead of data while loading async data. */
|
|
473
497
|
isLoading?: boolean;
|
|
498
|
+
/**
|
|
499
|
+
* Marks a server-side refetch (page, sort, filter or search change) as in
|
|
500
|
+
* flight. Unlike `isLoading` — the initial load, which swaps rows for
|
|
501
|
+
* skeletons — `refetching` never touches the rows: they stay rendered at
|
|
502
|
+
* full contrast (keep the stale data with TanStack Query's
|
|
503
|
+
* `placeholderData: keepPreviousData` or `useTransition`). The table sets
|
|
504
|
+
* `aria-busy` (never the wrapper — the live region must stay outside the
|
|
505
|
+
* busy subtree to be announced), a polite live region announces
|
|
506
|
+
* `refetchingLabel`, and the
|
|
507
|
+
* selection checkboxes (`DataTableSelectAllCheckbox`,
|
|
508
|
+
* `DataTableSelectRowCheckbox`) set `aria-disabled` and ignore toggles —
|
|
509
|
+
* selecting rows that are about to be replaced acts on stale data. The busy *visual* belongs to the
|
|
510
|
+
* control that requested the refetch (the pagination button, the sort
|
|
511
|
+
* header's or search field's `loading`), not to the body.
|
|
512
|
+
*
|
|
513
|
+
* Wrap a raw `isFetching` in `useDelayedPending` before passing it, so a
|
|
514
|
+
* refetch that resolves inside the flash threshold shows nothing at all.
|
|
515
|
+
* @default false
|
|
516
|
+
*/
|
|
517
|
+
refetching?: boolean;
|
|
518
|
+
/**
|
|
519
|
+
* What the polite live region announces to screen readers while
|
|
520
|
+
* `refetching` is set.
|
|
521
|
+
* @default "Loading results…"
|
|
522
|
+
*/
|
|
523
|
+
refetchingLabel?: string;
|
|
474
524
|
/** Number of skeleton rows when loading. Falls back to the table's page size, then 10. */
|
|
475
525
|
skeletonRowCount?: number;
|
|
476
526
|
/**
|
|
@@ -490,13 +540,38 @@ export interface DataTableProps<TData> {
|
|
|
490
540
|
*/
|
|
491
541
|
noResultsMessage?: React.ReactNode;
|
|
492
542
|
/**
|
|
493
|
-
* Pin the `<thead>` to the top of the scroll container
|
|
494
|
-
*
|
|
495
|
-
*
|
|
543
|
+
* Pin the `<thead>` to the top of the component's own scroll container
|
|
544
|
+
* (the outer wrapper) so column headers remain visible while the rows
|
|
545
|
+
* scroll. Bound the height through `className` — a fixed cap
|
|
546
|
+
* (`max-h-96`) or flex sizing inside a height-capped parent
|
|
547
|
+
* (`min-h-0 flex-1`) — and the header sticks while rows scroll beneath
|
|
548
|
+
* it (DS-912). The header keeps its opaque `bg-muted` background to
|
|
549
|
+
* separate it from body rows.
|
|
550
|
+
*
|
|
551
|
+
* Setting this also makes the outer wrapper a focusable scroll region
|
|
552
|
+
* (`role="region"` + `tabIndex`, labelled by `scrollRegionLabel`), so
|
|
553
|
+
* keyboard users can focus and scroll the rows — the height bound lives
|
|
554
|
+
* in `className`, which the component cannot inspect, so the sticky
|
|
555
|
+
* intent is the signal. For the same reason, don't set it on a table
|
|
556
|
+
* with no height bound: the wrapper never scrolls, and the region
|
|
557
|
+
* becomes an inert tab stop.
|
|
496
558
|
* @default false
|
|
497
559
|
*/
|
|
498
560
|
stickyHeader?: boolean;
|
|
499
|
-
/**
|
|
561
|
+
/**
|
|
562
|
+
* Additional class name for the outer wrapper — the component's single
|
|
563
|
+
* scroll container for both axes. Height bounds belong here: `max-h-*`
|
|
564
|
+
* for a fixed cap, or `min-h-0 flex-1` to fill a height-capped parent
|
|
565
|
+
* such as a dialog body.
|
|
566
|
+
*
|
|
567
|
+
* A height bound almost always wants `stickyHeader` with it — that also
|
|
568
|
+
* grants the keyboard-focusable scroll-region semantics. If you cap the
|
|
569
|
+
* height and deliberately let the header scroll away, pass
|
|
570
|
+
* `scrollRegionLabel` instead: it opts the wrapper into the same
|
|
571
|
+
* focusable scroll-region semantics without pinning the header, so the
|
|
572
|
+
* region semantics sit on the element that actually scrolls — keyboard
|
|
573
|
+
* arrow keys only scroll the focused element itself or an ancestor.
|
|
574
|
+
*/
|
|
500
575
|
className?: string;
|
|
501
576
|
/**
|
|
502
577
|
* Table layout algorithm.
|
|
@@ -517,8 +592,23 @@ export interface DataTableProps<TData> {
|
|
|
517
592
|
*/
|
|
518
593
|
minWidth?: string;
|
|
519
594
|
/**
|
|
520
|
-
* Accessible label for the scroll container region.
|
|
521
|
-
*
|
|
595
|
+
* Accessible label for the scroll container region (the outer wrapper).
|
|
596
|
+
* Applied whenever the wrapper is a focusable scroll region: `minWidth`
|
|
597
|
+
* is set (horizontal scrolling), `stickyHeader` is set (vertical
|
|
598
|
+
* scrolling under a pinned header), or always on `VirtualizedDataTable`
|
|
599
|
+
* (its viewport is bounded by definition).
|
|
600
|
+
*
|
|
601
|
+
* Passing it is also itself the opt-in for tables that scroll without
|
|
602
|
+
* either signal — a `className` height cap with the header deliberately
|
|
603
|
+
* left unpinned. The height bound lives in `className`, which the
|
|
604
|
+
* component cannot inspect, so the supplied label tells it the rows
|
|
605
|
+
* scroll and the wrapper becomes a focusable region. Don't pass it on a
|
|
606
|
+
* table that never scrolls: the region would be an inert tab stop.
|
|
607
|
+
*
|
|
608
|
+
* Give each table on a page a distinct label ("Invoices", "Team
|
|
609
|
+
* members") — several region landmarks sharing the default name violate
|
|
610
|
+
* axe's landmark-unique rule and are indistinguishable to screen-reader
|
|
611
|
+
* users.
|
|
522
612
|
* @default "Scrollable table"
|
|
523
613
|
*/
|
|
524
614
|
scrollRegionLabel?: string;
|
|
@@ -574,13 +664,15 @@ export interface DataTableProps<TData> {
|
|
|
574
664
|
*
|
|
575
665
|
* @example
|
|
576
666
|
* // One slot inside a gapped parent (dialog, card, page section).
|
|
577
|
-
* // min-h-0/flex-1 keep the table scrollable in height-capped parents
|
|
667
|
+
* // min-h-0/flex-1 keep the table scrollable in height-capped parents;
|
|
668
|
+
* // the outer wrapper is the scroll container, so stickyHeader keeps the
|
|
669
|
+
* // column headers visible while the rows scroll (DS-912).
|
|
578
670
|
* <div className="flex min-h-0 flex-1 flex-col">
|
|
579
671
|
* <DataTableToolbar dataHook="toolbar-top">
|
|
580
672
|
* <DataTableToolbarLeft>{heading or search}</DataTableToolbarLeft>
|
|
581
673
|
* <DataTableToolbarRight>{filters}</DataTableToolbarRight>
|
|
582
674
|
* </DataTableToolbar>
|
|
583
|
-
* <DataTable table={table} dataHook="my-table" className="min-h-0 flex-1
|
|
675
|
+
* <DataTable table={table} dataHook="my-table" stickyHeader className="min-h-0 flex-1" />
|
|
584
676
|
* <DataTableToolbar dataHook="toolbar-bottom">
|
|
585
677
|
* <DataTableToolbarLeft>{selection counter}</DataTableToolbarLeft>
|
|
586
678
|
* <DataTableToolbarRight>{pagination}</DataTableToolbarRight>
|
|
@@ -593,6 +685,8 @@ export function DataTable<TData>({
|
|
|
593
685
|
trackingEl,
|
|
594
686
|
trackingLabel,
|
|
595
687
|
isLoading = false,
|
|
688
|
+
refetching = false,
|
|
689
|
+
refetchingLabel,
|
|
596
690
|
skeletonRowCount,
|
|
597
691
|
noResultsMessage = "No results.",
|
|
598
692
|
stickyHeader = false,
|
|
@@ -608,78 +702,204 @@ export function DataTable<TData>({
|
|
|
608
702
|
const resolvedSkeletonCount =
|
|
609
703
|
skeletonRowCount ?? table.getState().pagination.pageSize ?? 10;
|
|
610
704
|
|
|
705
|
+
// A focusable scroll region whenever scrolling is part of the contract:
|
|
706
|
+
// minWidth (horizontal), stickyHeader, or an explicit scrollRegionLabel
|
|
707
|
+
// (the consumer bounds the height via className, which we cannot see,
|
|
708
|
+
// so the sticky intent — or the supplied label — is the signal that
|
|
709
|
+
// keyboard users must be able to focus and scroll the rows). One const
|
|
710
|
+
// gates both the focus classes and the region props so the two can
|
|
711
|
+
// never drift apart.
|
|
712
|
+
const isScrollRegion =
|
|
713
|
+
Boolean(minWidth) || stickyHeader || scrollRegionLabel !== undefined;
|
|
714
|
+
|
|
611
715
|
return (
|
|
612
716
|
<div
|
|
613
|
-
|
|
614
|
-
|
|
717
|
+
// `relative`: the sr-only live region below positions absolutely and
|
|
718
|
+
// must not escape to a distant containing block (double-scrollbar bug).
|
|
719
|
+
className={cn(
|
|
720
|
+
// `scrollbar` themes the native scrollbar with DS colors — the same
|
|
721
|
+
// treatment Command/Combobox lists use for bounded scroll containers.
|
|
722
|
+
"border-border scrollbar relative overflow-auto rounded-md border",
|
|
723
|
+
isScrollRegion && "focus-visible:shadow-default outline-none",
|
|
724
|
+
className
|
|
725
|
+
)}
|
|
615
726
|
data-hook={dataHook}
|
|
616
727
|
data-slot="data-table-view"
|
|
617
728
|
data-tracking-el={trackingEl}
|
|
618
729
|
data-tracking-label={trackingLabel}
|
|
730
|
+
{...(isScrollRegion ? scrollRegionProps(scrollRegionLabel) : undefined)}
|
|
619
731
|
>
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
>
|
|
626
|
-
<
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
732
|
+
{/* Always mounted so screen readers reliably announce the text change —
|
|
733
|
+
a live region inserted together with its content can be skipped. */}
|
|
734
|
+
<div aria-live="polite" className="sr-only" role="status">
|
|
735
|
+
{refetching ? (refetchingLabel ?? "Loading results…") : null}
|
|
736
|
+
</div>
|
|
737
|
+
<DataTableRefetchingContext.Provider value={refetching}>
|
|
738
|
+
<Table
|
|
739
|
+
// Busy on the table, never on the wrapper: `aria-busy` on an
|
|
740
|
+
// ancestor defers the live region above until the busy state clears,
|
|
741
|
+
// by which point its text is gone and nothing is announced.
|
|
742
|
+
aria-busy={isLoading || refetching || undefined}
|
|
743
|
+
dataHook={`${dataHook}-table`}
|
|
744
|
+
layout={layout}
|
|
745
|
+
minWidth={minWidth}
|
|
746
|
+
scrollOwner="parent"
|
|
747
|
+
>
|
|
748
|
+
<DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
|
|
749
|
+
<TableBody>
|
|
750
|
+
{isLoading ? (
|
|
751
|
+
<>
|
|
752
|
+
<LoadingRows
|
|
753
|
+
colCount={columnCount}
|
|
754
|
+
rowCount={resolvedSkeletonCount}
|
|
755
|
+
/>
|
|
756
|
+
<TableRow className="sr-only">
|
|
757
|
+
<TableCell colSpan={columnCount}>
|
|
758
|
+
<div aria-live="polite" role="status">
|
|
759
|
+
Loading data…
|
|
760
|
+
</div>
|
|
761
|
+
</TableCell>
|
|
762
|
+
</TableRow>
|
|
763
|
+
</>
|
|
764
|
+
) : (
|
|
765
|
+
<>
|
|
766
|
+
{table.getRowModel().rows.length > 0 ? (
|
|
767
|
+
table
|
|
768
|
+
.getRowModel()
|
|
769
|
+
.rows.map((row) => (
|
|
770
|
+
<DataTableRow
|
|
771
|
+
key={row.id}
|
|
772
|
+
columnCount={columnCount}
|
|
773
|
+
getRowClassName={getRowClassName}
|
|
774
|
+
renderExpandedContent={renderExpandedContent}
|
|
775
|
+
row={row}
|
|
776
|
+
/>
|
|
777
|
+
))
|
|
778
|
+
) : (
|
|
779
|
+
<TableRow>
|
|
780
|
+
<TableCell align="center" colSpan={columnCount} size="lg">
|
|
781
|
+
{/* Padded for a block, not for a line: an `EmptyState` passed
|
|
660
782
|
as the message needs the same room here that it gets
|
|
661
783
|
anywhere else, and a prop API gives the consumer nowhere
|
|
662
784
|
to add it. 24 rather than 32, because this sits inside
|
|
663
785
|
the cell's own 8: together they give the block its 32,
|
|
664
786
|
and a one-line message still measures under `size="lg"`'s
|
|
665
787
|
min-height, so the plain-string row does not move. */}
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
788
|
+
<div aria-live="polite" className="py-6" role="status">
|
|
789
|
+
{noResultsMessage}
|
|
790
|
+
</div>
|
|
791
|
+
</TableCell>
|
|
792
|
+
</TableRow>
|
|
793
|
+
)}
|
|
794
|
+
</>
|
|
795
|
+
)}
|
|
796
|
+
</TableBody>
|
|
797
|
+
{footer}
|
|
798
|
+
</Table>
|
|
799
|
+
</DataTableRefetchingContext.Provider>
|
|
677
800
|
</div>
|
|
678
801
|
);
|
|
679
802
|
}
|
|
680
803
|
|
|
681
804
|
DataTable.displayName = "DataTable";
|
|
682
805
|
|
|
806
|
+
/* -------------------------------------------------------------------------------------------------
|
|
807
|
+
* Internal: settled-sort override store (DS-916)
|
|
808
|
+
*
|
|
809
|
+
* During a server-side sort refetch, `DataTableColumnHeader` keeps announcing
|
|
810
|
+
* the settled sort order — the one the visible rows still reflect. ARIA
|
|
811
|
+
* requires `aria-sort` on the `<th>` (the columnheader element), which is
|
|
812
|
+
* rendered by `DataTableHeaderRows`, above the header button. This store is
|
|
813
|
+
* the single source of the per-column settled direction, with no consumer
|
|
814
|
+
* wiring: the button publishes every render from a layout effect (the live
|
|
815
|
+
* direction while idle, the held one while `loading`), the cell subscribes.
|
|
816
|
+
* Living at the table level, the value survives header remounts — the common
|
|
817
|
+
* wiring rebuilds the columns array when the fetching flag flips, which
|
|
818
|
+
* remounts every header through flexRender and would wipe header-local
|
|
819
|
+
* state. Outside a DataTable (no provider) both sides fall back to the live
|
|
820
|
+
* TanStack sort state.
|
|
821
|
+
* -----------------------------------------------------------------------------------------------*/
|
|
822
|
+
|
|
823
|
+
type SortOverride = "asc" | "desc" | false;
|
|
824
|
+
|
|
825
|
+
interface SortOverrideEntry {
|
|
826
|
+
/**
|
|
827
|
+
* What the header announces — the settled order while `loading`, the live
|
|
828
|
+
* one while idle.
|
|
829
|
+
*/
|
|
830
|
+
displayed: SortOverride;
|
|
831
|
+
/**
|
|
832
|
+
* The live TanStack direction at the same publish. It differs from
|
|
833
|
+
* `displayed` exactly while a settled order is being held, which is how the
|
|
834
|
+
* store identifies the column whose click requested the refetch.
|
|
835
|
+
*/
|
|
836
|
+
live: SortOverride;
|
|
837
|
+
}
|
|
838
|
+
|
|
839
|
+
interface SortOverrideStore {
|
|
840
|
+
set: (columnId: string, entry: SortOverrideEntry | null) => void;
|
|
841
|
+
get: (columnId: string) => SortOverrideEntry | null;
|
|
842
|
+
/**
|
|
843
|
+
* Whether any column is holding a settled order its live sort has moved
|
|
844
|
+
* away from — i.e. the in-flight refetch has an identifiable requesting
|
|
845
|
+
* column. When it does, only that column shows the spinner; when it does
|
|
846
|
+
* not (the flag flipped on a later render, e.g. wrapped in
|
|
847
|
+
* `useDelayedPending`), every sorted column falls back to showing it.
|
|
848
|
+
*/
|
|
849
|
+
anyHeld: () => boolean;
|
|
850
|
+
subscribe: (listener: () => void) => () => void;
|
|
851
|
+
}
|
|
852
|
+
|
|
853
|
+
const DataTableSortOverridesContext =
|
|
854
|
+
React.createContext<SortOverrideStore | null>(null);
|
|
855
|
+
|
|
856
|
+
const noopSubscribe = () => () => {};
|
|
857
|
+
|
|
858
|
+
function useSortOverrideStore(): SortOverrideStore {
|
|
859
|
+
const [store] = React.useState<SortOverrideStore>(() => {
|
|
860
|
+
const entries = new Map<string, SortOverrideEntry>();
|
|
861
|
+
const listeners = new Set<() => void>();
|
|
862
|
+
const read = (columnId: string): SortOverrideEntry | null =>
|
|
863
|
+
entries.get(columnId) ?? null;
|
|
864
|
+
return {
|
|
865
|
+
set: (columnId, entry) => {
|
|
866
|
+
const current = read(columnId);
|
|
867
|
+
if (
|
|
868
|
+
current === entry ||
|
|
869
|
+
(current !== null &&
|
|
870
|
+
entry !== null &&
|
|
871
|
+
current.displayed === entry.displayed &&
|
|
872
|
+
current.live === entry.live)
|
|
873
|
+
) {
|
|
874
|
+
return;
|
|
875
|
+
}
|
|
876
|
+
if (entry === null) {
|
|
877
|
+
entries.delete(columnId);
|
|
878
|
+
} else {
|
|
879
|
+
entries.set(columnId, entry);
|
|
880
|
+
}
|
|
881
|
+
listeners.forEach((listener) => listener());
|
|
882
|
+
},
|
|
883
|
+
get: read,
|
|
884
|
+
anyHeld: () => {
|
|
885
|
+
for (const entry of entries.values()) {
|
|
886
|
+
if (entry.displayed !== entry.live) {
|
|
887
|
+
return true;
|
|
888
|
+
}
|
|
889
|
+
}
|
|
890
|
+
return false;
|
|
891
|
+
},
|
|
892
|
+
subscribe: (listener) => {
|
|
893
|
+
listeners.add(listener);
|
|
894
|
+
return () => {
|
|
895
|
+
listeners.delete(listener);
|
|
896
|
+
};
|
|
897
|
+
},
|
|
898
|
+
};
|
|
899
|
+
});
|
|
900
|
+
return store;
|
|
901
|
+
}
|
|
902
|
+
|
|
683
903
|
/**
|
|
684
904
|
* Internal: render all header groups with `aria-sort` attributes.
|
|
685
905
|
* Shared between `DataTable` and `VirtualizedDataTable`.
|
|
@@ -691,43 +911,68 @@ function DataTableHeaderRows<TData>({
|
|
|
691
911
|
table: TanStackTable<TData>;
|
|
692
912
|
stickyHeader: boolean;
|
|
693
913
|
}) {
|
|
914
|
+
const sortOverrides = useSortOverrideStore();
|
|
694
915
|
return (
|
|
695
|
-
<
|
|
696
|
-
{
|
|
697
|
-
|
|
698
|
-
{headerGroup.
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
916
|
+
<DataTableSortOverridesContext.Provider value={sortOverrides}>
|
|
917
|
+
<TableHeader className={cn(stickyHeader && "sticky top-0 z-10")}>
|
|
918
|
+
{table.getHeaderGroups().map((headerGroup) => (
|
|
919
|
+
<TableRow key={headerGroup.id}>
|
|
920
|
+
{headerGroup.headers.map((header) => (
|
|
921
|
+
<DataTableHeadCell key={header.id} header={header} />
|
|
922
|
+
))}
|
|
923
|
+
</TableRow>
|
|
924
|
+
))}
|
|
925
|
+
</TableHeader>
|
|
926
|
+
</DataTableSortOverridesContext.Provider>
|
|
927
|
+
);
|
|
928
|
+
}
|
|
929
|
+
|
|
930
|
+
/**
|
|
931
|
+
* Internal: one `<th>` of the header row.
|
|
932
|
+
*
|
|
933
|
+
* `aria-sort` belongs on the columnheader element, but during a sort refetch
|
|
934
|
+
* the direction the rows still reflect is tracked inside
|
|
935
|
+
* `DataTableColumnHeader` (rendered below this cell). The cell subscribes to
|
|
936
|
+
* that settled direction through the override store, so the `<th>` and the
|
|
937
|
+
* sort button never announce two different orders (DS-916).
|
|
938
|
+
*/
|
|
939
|
+
function DataTableHeadCell<TData>({
|
|
940
|
+
header,
|
|
941
|
+
}: {
|
|
942
|
+
header: Header<TData, unknown>;
|
|
943
|
+
}) {
|
|
944
|
+
const overrides = React.useContext(DataTableSortOverridesContext);
|
|
945
|
+
const override = React.useSyncExternalStore(
|
|
946
|
+
overrides ? overrides.subscribe : noopSubscribe,
|
|
947
|
+
() =>
|
|
948
|
+
overrides ? (overrides.get(header.column.id)?.displayed ?? null) : null,
|
|
949
|
+
// Server render: no header has published yet — fall back to live state.
|
|
950
|
+
() => null
|
|
951
|
+
);
|
|
952
|
+
const canSort = header.column.getCanSort();
|
|
953
|
+
const sortDirection = canSort
|
|
954
|
+
? (override ?? header.column.getIsSorted())
|
|
955
|
+
: false;
|
|
956
|
+
const ariaSort =
|
|
957
|
+
sortDirection === "asc"
|
|
958
|
+
? "ascending"
|
|
959
|
+
: sortDirection === "desc"
|
|
960
|
+
? "descending"
|
|
961
|
+
: canSort
|
|
962
|
+
? "none"
|
|
963
|
+
: undefined;
|
|
964
|
+
const meta = header.column.columnDef.meta;
|
|
965
|
+
return (
|
|
966
|
+
<TableHead
|
|
967
|
+
aria-sort={ariaSort}
|
|
968
|
+
colSpan={header.colSpan}
|
|
969
|
+
minWidth={meta?.minWidth}
|
|
970
|
+
width={meta?.width}
|
|
971
|
+
>
|
|
972
|
+
{header.isPlaceholder
|
|
973
|
+
? null
|
|
974
|
+
: flexRender(header.column.columnDef.header, header.getContext())}
|
|
975
|
+
</TableHead>
|
|
731
976
|
);
|
|
732
977
|
}
|
|
733
978
|
|
|
@@ -898,6 +1143,8 @@ export function VirtualizedDataTable<TData>({
|
|
|
898
1143
|
trackingEl,
|
|
899
1144
|
trackingLabel,
|
|
900
1145
|
isLoading = false,
|
|
1146
|
+
refetching = false,
|
|
1147
|
+
refetchingLabel,
|
|
901
1148
|
skeletonRowCount,
|
|
902
1149
|
noResultsMessage = "No results.",
|
|
903
1150
|
stickyHeader = false,
|
|
@@ -940,74 +1187,99 @@ export function VirtualizedDataTable<TData>({
|
|
|
940
1187
|
return (
|
|
941
1188
|
<div
|
|
942
1189
|
ref={scrollContainerRef}
|
|
943
|
-
|
|
944
|
-
|
|
1190
|
+
// `relative`: the sr-only live region below positions absolutely and
|
|
1191
|
+
// must not escape to a distant containing block (double-scrollbar bug).
|
|
1192
|
+
className={cn(
|
|
1193
|
+
// `scrollbar` themes the native scrollbar with DS colors (the
|
|
1194
|
+
// Command/Combobox treatment for bounded scroll containers).
|
|
1195
|
+
"border-border scrollbar relative overflow-auto rounded-md border",
|
|
1196
|
+
// Always a focusable scroll region: virtualization requires a
|
|
1197
|
+
// bounded viewport (height or a className bound), so this wrapper
|
|
1198
|
+
// always scrolls vertically and keyboard users need to reach it.
|
|
1199
|
+
"focus-visible:shadow-default outline-none",
|
|
1200
|
+
className
|
|
1201
|
+
)}
|
|
945
1202
|
data-hook={dataHook}
|
|
946
1203
|
data-slot="data-table-view"
|
|
947
1204
|
data-tracking-el={trackingEl}
|
|
948
1205
|
data-tracking-label={trackingLabel}
|
|
949
1206
|
style={height != null ? { height } : undefined}
|
|
1207
|
+
{...scrollRegionProps(scrollRegionLabel)}
|
|
950
1208
|
>
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
>
|
|
957
|
-
<
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
1209
|
+
{/* Always mounted so screen readers reliably announce the text change —
|
|
1210
|
+
a live region inserted together with its content can be skipped. */}
|
|
1211
|
+
<div aria-live="polite" className="sr-only" role="status">
|
|
1212
|
+
{refetching ? (refetchingLabel ?? "Loading results…") : null}
|
|
1213
|
+
</div>
|
|
1214
|
+
<DataTableRefetchingContext.Provider value={refetching}>
|
|
1215
|
+
<Table
|
|
1216
|
+
// Busy on the table, never on the wrapper: `aria-busy` on an
|
|
1217
|
+
// ancestor defers the live region above until the busy state clears,
|
|
1218
|
+
// by which point its text is gone and nothing is announced.
|
|
1219
|
+
aria-busy={isLoading || refetching || undefined}
|
|
1220
|
+
dataHook={`${dataHook}-table`}
|
|
1221
|
+
layout={layout}
|
|
1222
|
+
minWidth={minWidth}
|
|
1223
|
+
scrollOwner="parent"
|
|
1224
|
+
>
|
|
1225
|
+
<DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
|
|
1226
|
+
<TableBody>
|
|
1227
|
+
{isLoading ? (
|
|
1228
|
+
<>
|
|
1229
|
+
<LoadingRows
|
|
1230
|
+
colCount={columnCount}
|
|
1231
|
+
rowCount={resolvedSkeletonCount}
|
|
1232
|
+
/>
|
|
1233
|
+
<TableRow className="sr-only">
|
|
1234
|
+
<TableCell colSpan={columnCount}>
|
|
1235
|
+
<div aria-live="polite" role="status">
|
|
1236
|
+
Loading data…
|
|
1237
|
+
</div>
|
|
1238
|
+
</TableCell>
|
|
1239
|
+
</TableRow>
|
|
1240
|
+
</>
|
|
1241
|
+
) : rows.length > 0 ? (
|
|
1242
|
+
<>
|
|
1243
|
+
{paddingTop > 0 && (
|
|
1244
|
+
<tr aria-hidden="true">
|
|
1245
|
+
<td colSpan={columnCount} style={{ height: paddingTop }} />
|
|
1246
|
+
</tr>
|
|
1247
|
+
)}
|
|
1248
|
+
{virtualItems.map((virtualItem) => {
|
|
1249
|
+
const row = rows[virtualItem.index]!;
|
|
1250
|
+
return (
|
|
1251
|
+
<DataTableRow
|
|
1252
|
+
key={row.id}
|
|
1253
|
+
columnCount={columnCount}
|
|
1254
|
+
getRowClassName={getRowClassName}
|
|
1255
|
+
row={row}
|
|
1256
|
+
/>
|
|
1257
|
+
);
|
|
1258
|
+
})}
|
|
1259
|
+
{paddingBottom > 0 && (
|
|
1260
|
+
<tr aria-hidden="true">
|
|
1261
|
+
<td
|
|
1262
|
+
colSpan={columnCount}
|
|
1263
|
+
style={{ height: paddingBottom }}
|
|
1264
|
+
/>
|
|
1265
|
+
</tr>
|
|
1266
|
+
)}
|
|
1267
|
+
</>
|
|
1268
|
+
) : (
|
|
1269
|
+
<TableRow>
|
|
1270
|
+
<TableCell align="center" colSpan={columnCount} size="lg">
|
|
1271
|
+
{/* Padded for a block — see the note on the non-virtualised
|
|
1272
|
+
table's no-results cell. */}
|
|
1273
|
+
<div aria-live="polite" className="py-6" role="status">
|
|
1274
|
+
{noResultsMessage}
|
|
969
1275
|
</div>
|
|
970
1276
|
</TableCell>
|
|
971
1277
|
</TableRow>
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
<td colSpan={columnCount} style={{ height: paddingTop }} />
|
|
978
|
-
</tr>
|
|
979
|
-
)}
|
|
980
|
-
{virtualItems.map((virtualItem) => {
|
|
981
|
-
const row = rows[virtualItem.index]!;
|
|
982
|
-
return (
|
|
983
|
-
<DataTableRow
|
|
984
|
-
key={row.id}
|
|
985
|
-
columnCount={columnCount}
|
|
986
|
-
getRowClassName={getRowClassName}
|
|
987
|
-
row={row}
|
|
988
|
-
/>
|
|
989
|
-
);
|
|
990
|
-
})}
|
|
991
|
-
{paddingBottom > 0 && (
|
|
992
|
-
<tr aria-hidden="true">
|
|
993
|
-
<td colSpan={columnCount} style={{ height: paddingBottom }} />
|
|
994
|
-
</tr>
|
|
995
|
-
)}
|
|
996
|
-
</>
|
|
997
|
-
) : (
|
|
998
|
-
<TableRow>
|
|
999
|
-
<TableCell align="center" colSpan={columnCount} size="lg">
|
|
1000
|
-
{/* Padded for a block — see the note on the non-virtualised
|
|
1001
|
-
table's no-results cell. */}
|
|
1002
|
-
<div aria-live="polite" className="py-6" role="status">
|
|
1003
|
-
{noResultsMessage}
|
|
1004
|
-
</div>
|
|
1005
|
-
</TableCell>
|
|
1006
|
-
</TableRow>
|
|
1007
|
-
)}
|
|
1008
|
-
</TableBody>
|
|
1009
|
-
{footer}
|
|
1010
|
-
</Table>
|
|
1278
|
+
)}
|
|
1279
|
+
</TableBody>
|
|
1280
|
+
{footer}
|
|
1281
|
+
</Table>
|
|
1282
|
+
</DataTableRefetchingContext.Provider>
|
|
1011
1283
|
</div>
|
|
1012
1284
|
);
|
|
1013
1285
|
}
|
|
@@ -1041,9 +1313,35 @@ export interface DataTableColumnHeaderProps<
|
|
|
1041
1313
|
/**
|
|
1042
1314
|
* Builds the accessible label for the sort button.
|
|
1043
1315
|
* Receives the column title and current sort direction (`"asc"`, `"desc"`, or `false`).
|
|
1316
|
+
* While `loading` is true the direction passed is the settled one — the
|
|
1317
|
+
* order the visible rows still reflect, not the one just requested.
|
|
1044
1318
|
* @default (title, dir) => `Sort by ${title}${dir ? `, currently ${dir === "asc" ? "ascending" : "descending"}` : ""}`
|
|
1045
1319
|
*/
|
|
1046
1320
|
getSortLabel?: (title: string, direction: "asc" | "desc" | false) => string;
|
|
1321
|
+
/**
|
|
1322
|
+
* Marks a server-side sort refetch as in flight. Pass the same fetching
|
|
1323
|
+
* flag to every column's header: every sort button sets `aria-busy` and
|
|
1324
|
+
* becomes inert — clicks are ignored to prevent a double-fetch — without a
|
|
1325
|
+
* disabled look, and the column whose click requested the refetch (the one
|
|
1326
|
+
* whose requested order differs from the settled one it still shows) swaps
|
|
1327
|
+
* its sort icon for a spinner. Icons, labels and the `<th>`'s `aria-sort`
|
|
1328
|
+
* keep describing the settled sort order — the order the visible rows still
|
|
1329
|
+
* reflect — until the flag clears.
|
|
1330
|
+
*
|
|
1331
|
+
* The settled order is captured when the sort change and this flag land in
|
|
1332
|
+
* the same render commit: a click handler that sets both, or React Query's
|
|
1333
|
+
* `isFetching` in the same batch — the normal wirings. It is tracked at the
|
|
1334
|
+
* table level, so it survives the columns array being rebuilt (and every
|
|
1335
|
+
* header remounting) when the flag flips. A flag that only flips on a later
|
|
1336
|
+
* render (e.g. wrapped in `useDelayedPending`) degrades gracefully to
|
|
1337
|
+
* announcing the requested order (the standard behavior of sortable
|
|
1338
|
+
* tables), with the spinner on the sorted column or columns — the
|
|
1339
|
+
* requesting one can no longer be told apart; button and `<th>` stay
|
|
1340
|
+
* consistent with each other either way. Rendered standalone (outside a
|
|
1341
|
+
* DataTable), the settled order is held in header-local state instead.
|
|
1342
|
+
* @default false
|
|
1343
|
+
*/
|
|
1344
|
+
loading?: boolean;
|
|
1047
1345
|
}
|
|
1048
1346
|
|
|
1049
1347
|
/**
|
|
@@ -1052,6 +1350,20 @@ export interface DataTableColumnHeaderProps<
|
|
|
1052
1350
|
* Falls back to a non-interactive label when the column is not sortable.
|
|
1053
1351
|
* Otherwise renders a ghost button that toggles sort on click, with an
|
|
1054
1352
|
* accessible label describing the current sort state.
|
|
1353
|
+
*
|
|
1354
|
+
* **First-click direction:** clicking an unsorted column starts ascending
|
|
1355
|
+
* (A–Z, lowest first). Numeric columns (counts, rates, scores) usually want
|
|
1356
|
+
* highest-first on the first click — opt in per column with TanStack's
|
|
1357
|
+
* `sortDescFirst` on the column def:
|
|
1358
|
+
*
|
|
1359
|
+
* ```tsx
|
|
1360
|
+
* { accessorKey: "score", sortDescFirst: true, header: ... }
|
|
1361
|
+
* ```
|
|
1362
|
+
*
|
|
1363
|
+
* Only an explicit `sortDescFirst` is honoured — TanStack's automatic
|
|
1364
|
+
* "numbers sort descending first" detection is deliberately not consulted,
|
|
1365
|
+
* so tables that do not opt in keep first-click-ascending. Once a column is
|
|
1366
|
+
* sorted, clicking again reverses the direction as before.
|
|
1055
1367
|
*/
|
|
1056
1368
|
export function DataTableColumnHeader<TData, TValue>({
|
|
1057
1369
|
column,
|
|
@@ -1062,7 +1374,74 @@ export function DataTableColumnHeader<TData, TValue>({
|
|
|
1062
1374
|
trackingLabel,
|
|
1063
1375
|
align = "left",
|
|
1064
1376
|
getSortLabel,
|
|
1377
|
+
loading = false,
|
|
1065
1378
|
}: DataTableColumnHeaderProps<TData, TValue>) {
|
|
1379
|
+
const currentSort = column.getIsSorted();
|
|
1380
|
+
// Clicking a header flips TanStack's sort state immediately, but during a
|
|
1381
|
+
// server-side refetch the rows still show the previous order. The settled
|
|
1382
|
+
// sort — what the visible rows actually reflect — lives in the table-level
|
|
1383
|
+
// override store, not in local state: the common wiring rebuilds the
|
|
1384
|
+
// columns array when the fetching flag flips, which remounts every header
|
|
1385
|
+
// through flexRender and would wipe component state. The store (owned by
|
|
1386
|
+
// DataTableHeaderRows) survives those remounts, and a remounting header
|
|
1387
|
+
// reads the previous value during render, before the old instance's
|
|
1388
|
+
// cleanup runs (DS-916).
|
|
1389
|
+
const sortOverrides = React.useContext(DataTableSortOverridesContext);
|
|
1390
|
+
const storedSort = React.useSyncExternalStore(
|
|
1391
|
+
sortOverrides ? sortOverrides.subscribe : noopSubscribe,
|
|
1392
|
+
() =>
|
|
1393
|
+
sortOverrides ? (sortOverrides.get(column.id)?.displayed ?? null) : null,
|
|
1394
|
+
() => null
|
|
1395
|
+
);
|
|
1396
|
+
// Standalone fallback: rendered outside a DataTable (no provider) the
|
|
1397
|
+
// settled order lives in local state instead — the previous-render-value
|
|
1398
|
+
// pattern. It cannot survive a header remount, but without the table there
|
|
1399
|
+
// is no DataTableHeaderRows rebuilding the columns array either, so the
|
|
1400
|
+
// remount hazard the store exists for does not apply.
|
|
1401
|
+
const [localSettled, setLocalSettled] = React.useState(currentSort);
|
|
1402
|
+
if (!sortOverrides && !loading && localSettled !== currentSort) {
|
|
1403
|
+
setLocalSettled(currentSort);
|
|
1404
|
+
}
|
|
1405
|
+
const settledSort = sortOverrides
|
|
1406
|
+
? (storedSort ?? currentSort)
|
|
1407
|
+
: localSettled;
|
|
1408
|
+
const displayedSort = loading ? settledSort : currentSort;
|
|
1409
|
+
|
|
1410
|
+
// The column whose click requested the refetch is the one holding a settled
|
|
1411
|
+
// order its live sort has moved away from — only it gets the spinner, so a
|
|
1412
|
+
// multi-sorted table never animates every sorted header at once. When no
|
|
1413
|
+
// column is held (the flag flipped on a later render — e.g. wrapped in
|
|
1414
|
+
// `useDelayedPending` — so the settled order was never captured), fall back
|
|
1415
|
+
// to showing the spinner on the sorted column(s).
|
|
1416
|
+
const heldSelf = displayedSort !== currentSort;
|
|
1417
|
+
const storeAnyHeld = React.useSyncExternalStore(
|
|
1418
|
+
sortOverrides ? sortOverrides.subscribe : noopSubscribe,
|
|
1419
|
+
() => (sortOverrides ? sortOverrides.anyHeld() : false),
|
|
1420
|
+
() => false
|
|
1421
|
+
);
|
|
1422
|
+
const anyHeld = sortOverrides ? storeAnyHeld : heldSelf;
|
|
1423
|
+
const sortRefetching =
|
|
1424
|
+
loading && (heldSelf || (!anyHeld && currentSort !== false));
|
|
1425
|
+
|
|
1426
|
+
// Publish what this header announces so the enclosing `<th>` mirrors it in
|
|
1427
|
+
// `aria-sort` — the two must never contradict each other. While idle the
|
|
1428
|
+
// store tracks the live sort (the rows reflect it); while loading it holds
|
|
1429
|
+
// the settled value. A layout effect flushes before paint, so no frame is
|
|
1430
|
+
// painted with the `<th>` and the button disagreeing. Rendered standalone
|
|
1431
|
+
// (no provider) the local fallback above holds the settled order instead.
|
|
1432
|
+
React.useLayoutEffect(() => {
|
|
1433
|
+
if (!sortOverrides) {
|
|
1434
|
+
return;
|
|
1435
|
+
}
|
|
1436
|
+
sortOverrides.set(column.id, {
|
|
1437
|
+
displayed: displayedSort,
|
|
1438
|
+
live: currentSort,
|
|
1439
|
+
});
|
|
1440
|
+
return () => {
|
|
1441
|
+
sortOverrides.set(column.id, null);
|
|
1442
|
+
};
|
|
1443
|
+
}, [sortOverrides, column.id, displayedSort, currentSort]);
|
|
1444
|
+
|
|
1066
1445
|
if (!column.getCanSort()) {
|
|
1067
1446
|
return (
|
|
1068
1447
|
<div
|
|
@@ -1082,12 +1461,19 @@ export function DataTableColumnHeader<TData, TValue>({
|
|
|
1082
1461
|
);
|
|
1083
1462
|
}
|
|
1084
1463
|
|
|
1085
|
-
|
|
1464
|
+
// First click on an unsorted column follows the column def's explicit
|
|
1465
|
+
// `sortDescFirst`; later clicks reverse the current direction. TanStack's
|
|
1466
|
+
// `getFirstSortDir()` is not used here — its automatic numeric detection
|
|
1467
|
+
// would silently flip existing tables to descending-first (DS-953).
|
|
1468
|
+
const nextSortDesc =
|
|
1469
|
+
currentSort === false
|
|
1470
|
+
? column.columnDef.sortDescFirst === true
|
|
1471
|
+
: currentSort === "asc";
|
|
1086
1472
|
const sortLabel = getSortLabel
|
|
1087
|
-
? getSortLabel(title,
|
|
1088
|
-
:
|
|
1473
|
+
? getSortLabel(title, displayedSort)
|
|
1474
|
+
: displayedSort === "desc"
|
|
1089
1475
|
? `Sort by ${title}, currently descending`
|
|
1090
|
-
:
|
|
1476
|
+
: displayedSort === "asc"
|
|
1091
1477
|
? `Sort by ${title}, currently ascending`
|
|
1092
1478
|
: `Sort by ${title}`;
|
|
1093
1479
|
|
|
@@ -1104,21 +1490,30 @@ export function DataTableColumnHeader<TData, TValue>({
|
|
|
1104
1490
|
data-tracking-label={trackingLabel}
|
|
1105
1491
|
>
|
|
1106
1492
|
<Button
|
|
1493
|
+
aria-busy={loading ? "true" : undefined}
|
|
1107
1494
|
aria-label={sortLabel}
|
|
1108
1495
|
className="text-muted-foreground text-label h-auto p-0 font-semibold"
|
|
1109
1496
|
dataHook={dataHook || `column-header-${column.id}`}
|
|
1110
1497
|
size="sm"
|
|
1111
1498
|
variant="ghost"
|
|
1112
|
-
onClick={() =>
|
|
1499
|
+
onClick={() => {
|
|
1500
|
+
// Inert while a refetch is in flight — busy, not disabled, so the
|
|
1501
|
+
// button keeps its look and stays focusable but cannot double-fetch.
|
|
1502
|
+
if (!loading) {
|
|
1503
|
+
column.toggleSorting(nextSortDesc);
|
|
1504
|
+
}
|
|
1505
|
+
}}
|
|
1113
1506
|
>
|
|
1114
1507
|
<span aria-hidden="true">{title}</span>
|
|
1115
1508
|
<span
|
|
1116
1509
|
aria-hidden="true"
|
|
1117
1510
|
className="flex size-3 items-center justify-center"
|
|
1118
1511
|
>
|
|
1119
|
-
{
|
|
1512
|
+
{sortRefetching ? (
|
|
1513
|
+
<Spinner size="sm" />
|
|
1514
|
+
) : displayedSort === "desc" ? (
|
|
1120
1515
|
<ArrowDown size={12} />
|
|
1121
|
-
) :
|
|
1516
|
+
) : displayedSort === "asc" ? (
|
|
1122
1517
|
<ArrowUp size={12} />
|
|
1123
1518
|
) : (
|
|
1124
1519
|
<ArrowUpDown size={12} />
|
|
@@ -1154,8 +1549,38 @@ export interface DataTableSearchProps<TData> extends Omit<
|
|
|
1154
1549
|
placeholder?: string;
|
|
1155
1550
|
/** Accessible label for the clear button. @default "Clear search" */
|
|
1156
1551
|
clearSearchAriaLabel?: string;
|
|
1552
|
+
/**
|
|
1553
|
+
* Search refetch in flight — the leading search icon swaps to a spinner
|
|
1554
|
+
* and the group sets `aria-busy`. The input stays fully editable, and the
|
|
1555
|
+
* clear button keeps its place in the trailing slot whenever there is a
|
|
1556
|
+
* value: the way out of a slow search never disappears.
|
|
1557
|
+
* @default false
|
|
1558
|
+
*/
|
|
1559
|
+
loading?: boolean;
|
|
1560
|
+
/**
|
|
1561
|
+
* Debounce between keystrokes and the table's global filter, in
|
|
1562
|
+
* milliseconds. The input echoes instantly; the filter (and any server
|
|
1563
|
+
* refetch keyed off it) only updates after the pause. Clearing via the
|
|
1564
|
+
* clear button skips the debounce.
|
|
1565
|
+
*
|
|
1566
|
+
* The default is derived from the table's filtering mode: `300` when the
|
|
1567
|
+
* table uses `manualFiltering` (server-side — one refetch per pause,
|
|
1568
|
+
* "debounce the request"), `0` for client-side filtering (rows keep
|
|
1569
|
+
* narrowing per keystroke, as before). Pass a value to override either mode.
|
|
1570
|
+
* @default table.options.manualFiltering ? 300 : 0
|
|
1571
|
+
*/
|
|
1572
|
+
debounceMs?: number;
|
|
1157
1573
|
}
|
|
1158
1574
|
|
|
1575
|
+
/**
|
|
1576
|
+
* How many of DataTableSearch's own unacknowledged filter writes are
|
|
1577
|
+
* remembered for telling them apart from external writes. Writes echo back
|
|
1578
|
+
* within a render or two even through a transition- or URL-synced filter, so
|
|
1579
|
+
* anything beyond this is a consumer that never echoes at all — the cap keeps
|
|
1580
|
+
* that wiring from growing the list forever.
|
|
1581
|
+
*/
|
|
1582
|
+
const MAX_TRACKED_FILTER_PUSHES = 10;
|
|
1583
|
+
|
|
1159
1584
|
/**
|
|
1160
1585
|
* Search input for filtering DataTable rows.
|
|
1161
1586
|
*
|
|
@@ -1164,48 +1589,170 @@ export interface DataTableSearchProps<TData> extends Omit<
|
|
|
1164
1589
|
* customize width or shape.
|
|
1165
1590
|
*
|
|
1166
1591
|
* Uses the table's global filter (requires `enableGlobalFiltering` on the hook).
|
|
1592
|
+
*
|
|
1593
|
+
* With `manualFiltering` (server-side search) keystrokes echo in the input
|
|
1594
|
+
* instantly while the global filter — and any server refetch keyed off it —
|
|
1595
|
+
* only updates after `debounceMs` of inactivity. Client-side filtering stays
|
|
1596
|
+
* synchronous: rows narrow per keystroke, exactly as the Filtering pattern
|
|
1597
|
+
* promises ("debounce the request, never the input").
|
|
1167
1598
|
*/
|
|
1168
1599
|
export function DataTableSearch<TData>({
|
|
1169
1600
|
table,
|
|
1170
1601
|
ariaLabel,
|
|
1171
1602
|
placeholder,
|
|
1172
1603
|
clearSearchAriaLabel,
|
|
1604
|
+
loading = false,
|
|
1605
|
+
debounceMs,
|
|
1173
1606
|
...inputGroupProps
|
|
1174
1607
|
}: DataTableSearchProps<TData>) {
|
|
1175
1608
|
const filterValue = (table.getState().globalFilter ?? "") as string;
|
|
1609
|
+
const [inputValue, setInputValue] = React.useState(filterValue);
|
|
1610
|
+
// manualFiltering is the consumer's own declaration that filter changes are
|
|
1611
|
+
// server requests — those get the 300ms debounce (DS-916). Without it the
|
|
1612
|
+
// filter is an in-memory narrowing the reader watches, so it stays
|
|
1613
|
+
// per-keystroke. An explicit debounceMs wins in either mode.
|
|
1614
|
+
const effectiveDebounceMs =
|
|
1615
|
+
debounceMs ?? (table.options.manualFiltering === true ? 300 : 0);
|
|
1616
|
+
|
|
1617
|
+
// The debounce is a plain timer owned by this component — no debounced
|
|
1618
|
+
// value lives in state. A remembered value is exactly what made clearing
|
|
1619
|
+
// and then retyping the same query silently skip its push (the memory
|
|
1620
|
+
// bailed out on the equal value and the filter never updated), and what
|
|
1621
|
+
// made a mode flip replay a stale value over the live filter.
|
|
1622
|
+
const pushTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
|
|
1623
|
+
const cancelPendingPush = React.useCallback(() => {
|
|
1624
|
+
if (pushTimerRef.current !== null) {
|
|
1625
|
+
clearTimeout(pushTimerRef.current);
|
|
1626
|
+
pushTimerRef.current = null;
|
|
1627
|
+
}
|
|
1628
|
+
}, []);
|
|
1629
|
+
React.useEffect(() => cancelPendingPush, [cancelPendingPush]);
|
|
1630
|
+
|
|
1631
|
+
// The latest input value, readable from the timer callback. Synced in a
|
|
1632
|
+
// passive effect (never during render); the shortest debounce that
|
|
1633
|
+
// schedules a timer still fires long after the commit's effects, so a
|
|
1634
|
+
// pending push always compares against the current value.
|
|
1635
|
+
const inputValueRef = React.useRef(inputValue);
|
|
1636
|
+
React.useEffect(() => {
|
|
1637
|
+
inputValueRef.current = inputValue;
|
|
1638
|
+
});
|
|
1639
|
+
|
|
1640
|
+
// `filter` mirrors the last observed table filter (the previous-render
|
|
1641
|
+
// value); `pushed` lists the values THIS component wrote that have not been
|
|
1642
|
+
// observed back yet, so a push's own echo is not mistaken for an external
|
|
1643
|
+
// write. Acknowledgment is by value and recency, not true write identity —
|
|
1644
|
+
// the filter is a plain string in table state, so there is no channel for a
|
|
1645
|
+
// revision token. That leaves one ambiguous case: an external write whose
|
|
1646
|
+
// value exactly equals an in-flight unacknowledged push is read as that
|
|
1647
|
+
// push's echo, and keystrokes typed since are kept rather than overwritten.
|
|
1648
|
+
// Every external write that differs from the in-flight pushes is adopted.
|
|
1649
|
+
// A list, not a single slot: with writes landing a render late (a
|
|
1650
|
+
// transition- or URL-synced filter) several pushes can be in flight at
|
|
1651
|
+
// once. Recorded via setState (not a ref) so render never touches a mutable
|
|
1652
|
+
// value, and batched with the table write itself.
|
|
1653
|
+
const [filterSync, setFilterSync] = React.useState<{
|
|
1654
|
+
filter: string;
|
|
1655
|
+
pushed: string[];
|
|
1656
|
+
}>({ filter: filterValue, pushed: [] });
|
|
1657
|
+
|
|
1658
|
+
// Write the filter and record the write — called from handlers and timer
|
|
1659
|
+
// callbacks only, never during render. The record is capped: a consumer
|
|
1660
|
+
// that never echoes pushes back (a controlled filter without a handler, or
|
|
1661
|
+
// one that normalizes values) must not grow it for the component's
|
|
1662
|
+
// lifetime, and more than a handful of unacknowledged writes can no longer
|
|
1663
|
+
// be meaningfully "in flight" anyway.
|
|
1664
|
+
const pushFilter = (next: string) => {
|
|
1665
|
+
if ((table.getState().globalFilter ?? "") === next) {
|
|
1666
|
+
return;
|
|
1667
|
+
}
|
|
1668
|
+
setFilterSync((sync) => ({
|
|
1669
|
+
filter: sync.filter,
|
|
1670
|
+
pushed: [...sync.pushed, next].slice(-MAX_TRACKED_FILTER_PUSHES),
|
|
1671
|
+
}));
|
|
1672
|
+
table.setGlobalFilter(next);
|
|
1673
|
+
};
|
|
1674
|
+
|
|
1675
|
+
const schedulePush = (next: string) => {
|
|
1676
|
+
cancelPendingPush();
|
|
1677
|
+
if (effectiveDebounceMs > 0) {
|
|
1678
|
+
pushTimerRef.current = setTimeout(() => {
|
|
1679
|
+
pushTimerRef.current = null;
|
|
1680
|
+
// An adopted external write (which replaces `inputValue` below) or a
|
|
1681
|
+
// clear supersedes this push — stale keystrokes never win over them.
|
|
1682
|
+
if (inputValueRef.current === next) {
|
|
1683
|
+
pushFilter(next);
|
|
1684
|
+
}
|
|
1685
|
+
}, effectiveDebounceMs);
|
|
1686
|
+
} else {
|
|
1687
|
+
pushFilter(next);
|
|
1688
|
+
}
|
|
1689
|
+
};
|
|
1690
|
+
|
|
1691
|
+
// Adopt filter changes made outside this input (a consumer reset, another
|
|
1692
|
+
// control writing the filter) — state adjusted during render. A pending
|
|
1693
|
+
// debounced push cannot write over the adopted value: its timer compares
|
|
1694
|
+
// against the adopted `inputValue` and skips itself.
|
|
1695
|
+
if (filterValue !== filterSync.filter) {
|
|
1696
|
+
// Acknowledge own pushes by identity: the observed value is the most
|
|
1697
|
+
// recent matching push, and everything pushed before it was superseded
|
|
1698
|
+
// (renders can skip intermediate states, so earlier entries may never be
|
|
1699
|
+
// observed on their own). An unmatched value is an external write; later
|
|
1700
|
+
// own pushes may still be observed, so the list is kept.
|
|
1701
|
+
const ackIndex = filterSync.pushed.lastIndexOf(filterValue);
|
|
1702
|
+
const isOwnPush = ackIndex !== -1;
|
|
1703
|
+
setFilterSync({
|
|
1704
|
+
filter: filterValue,
|
|
1705
|
+
pushed: isOwnPush
|
|
1706
|
+
? filterSync.pushed.slice(ackIndex + 1)
|
|
1707
|
+
: filterSync.pushed,
|
|
1708
|
+
});
|
|
1709
|
+
if (!isOwnPush && filterValue !== inputValue) {
|
|
1710
|
+
setInputValue(filterValue);
|
|
1711
|
+
}
|
|
1712
|
+
}
|
|
1176
1713
|
|
|
1177
|
-
const
|
|
1178
|
-
|
|
1714
|
+
const handleClear = () => {
|
|
1715
|
+
// Clearing skips the debounce — the filter resets immediately, and any
|
|
1716
|
+
// pending keystroke push is cancelled rather than resurrecting the query.
|
|
1717
|
+
cancelPendingPush();
|
|
1718
|
+
setInputValue("");
|
|
1719
|
+
pushFilter("");
|
|
1179
1720
|
};
|
|
1180
1721
|
|
|
1181
1722
|
return (
|
|
1182
|
-
<InputGroup
|
|
1723
|
+
<InputGroup
|
|
1724
|
+
aria-busy={loading ? "true" : undefined}
|
|
1725
|
+
data-slot="data-table-search"
|
|
1726
|
+
{...inputGroupProps}
|
|
1727
|
+
>
|
|
1183
1728
|
<InputGroupAddon className="pl-3">
|
|
1184
|
-
|
|
1729
|
+
{/* The spinner takes the search icon's slot, never the clear button's:
|
|
1730
|
+
the way out of a slow search must stay where it always is. */}
|
|
1731
|
+
{loading ? (
|
|
1732
|
+
<Spinner dataHook={`${inputGroupProps.dataHook}-loading`} />
|
|
1733
|
+
) : (
|
|
1734
|
+
<Search />
|
|
1735
|
+
)}
|
|
1185
1736
|
</InputGroupAddon>
|
|
1186
1737
|
<InputGroupInput
|
|
1187
1738
|
aria-label={ariaLabel ?? "Search table"}
|
|
1188
1739
|
placeholder={placeholder ?? "Search..."}
|
|
1189
1740
|
type="text"
|
|
1190
|
-
value={
|
|
1191
|
-
onChange={(event) =>
|
|
1741
|
+
value={inputValue}
|
|
1742
|
+
onChange={(event) => {
|
|
1743
|
+
const next = event.target.value;
|
|
1744
|
+
setInputValue(next);
|
|
1745
|
+
// Debounced (server-side) mode schedules the push; synchronous mode
|
|
1746
|
+
// pushes in the handler for same-keystroke narrowing.
|
|
1747
|
+
schedulePush(next);
|
|
1748
|
+
}}
|
|
1749
|
+
/>
|
|
1750
|
+
<InputGroupClear
|
|
1751
|
+
clearSearchAriaLabel={clearSearchAriaLabel}
|
|
1752
|
+
data-slot="data-table-search-clear"
|
|
1753
|
+
dataHook={`${inputGroupProps.dataHook}-clear`}
|
|
1754
|
+
onClear={effectiveDebounceMs > 0 ? handleClear : undefined}
|
|
1192
1755
|
/>
|
|
1193
|
-
{filterValue && (
|
|
1194
|
-
<InputGroupAddon className="pr-1">
|
|
1195
|
-
<Button
|
|
1196
|
-
aria-label={clearSearchAriaLabel ?? "Clear search"}
|
|
1197
|
-
/* Fixed square hit area — h-auto p-1 let the ghost hover hug the
|
|
1198
|
-
14px icon into a squashed pill. */
|
|
1199
|
-
className="size-6 p-0"
|
|
1200
|
-
data-slot="data-table-search-clear"
|
|
1201
|
-
dataHook={`${inputGroupProps.dataHook}-clear`}
|
|
1202
|
-
variant="ghost"
|
|
1203
|
-
onClick={() => handleFilterChange("")}
|
|
1204
|
-
>
|
|
1205
|
-
<X size={14} />
|
|
1206
|
-
</Button>
|
|
1207
|
-
</InputGroupAddon>
|
|
1208
|
-
)}
|
|
1209
1756
|
</InputGroup>
|
|
1210
1757
|
);
|
|
1211
1758
|
}
|
|
@@ -1369,6 +1916,8 @@ export interface DataTablePaginationRowCountProps {
|
|
|
1369
1916
|
*
|
|
1370
1917
|
* Renders "start–end of total" by default. Pass `renderText` for i18n-friendly
|
|
1371
1918
|
* custom text with full control over wording, pluralization, and order.
|
|
1919
|
+
* Renders nothing below the `sm` viewport breakpoint — on small screens the
|
|
1920
|
+
* label is removed so the page buttons get the full width (DS-998).
|
|
1372
1921
|
*
|
|
1373
1922
|
* Must be rendered inside `<DataTablePagination>`.
|
|
1374
1923
|
*/
|
|
@@ -1377,8 +1926,14 @@ function DataTablePaginationRowCount({
|
|
|
1377
1926
|
className,
|
|
1378
1927
|
}: DataTablePaginationRowCountProps) {
|
|
1379
1928
|
const { info } = useDataTablePaginationContext();
|
|
1929
|
+
const isMobile = useIsBelowBreakpoint("sm");
|
|
1380
1930
|
const { startRow, endRow, totalRows, pageIndex, pageSize } = info;
|
|
1381
1931
|
|
|
1932
|
+
// Below `sm` the label is removed so the page buttons get the full width
|
|
1933
|
+
// and centre (DS-998) — same rule as the default layout and
|
|
1934
|
+
// `PaginationControls`.
|
|
1935
|
+
if (isMobile) return null;
|
|
1936
|
+
|
|
1382
1937
|
const content = renderText
|
|
1383
1938
|
? renderText({ startRow, endRow, totalRows, pageIndex, pageSize })
|
|
1384
1939
|
: totalRows === 0
|
|
@@ -1389,7 +1944,10 @@ function DataTablePaginationRowCount({
|
|
|
1389
1944
|
|
|
1390
1945
|
return (
|
|
1391
1946
|
<span
|
|
1392
|
-
className={cn(
|
|
1947
|
+
className={cn(
|
|
1948
|
+
"text-body-sm text-muted-foreground whitespace-nowrap",
|
|
1949
|
+
className
|
|
1950
|
+
)}
|
|
1393
1951
|
data-slot="data-table-pagination-row-count"
|
|
1394
1952
|
>
|
|
1395
1953
|
{content}
|
|
@@ -1417,7 +1975,8 @@ export interface DataTablePaginationNavProps {
|
|
|
1417
1975
|
*
|
|
1418
1976
|
* Renders previous/next buttons and page links. Renders nothing when there
|
|
1419
1977
|
* is at most one page — navigation controls are noise when there is nowhere
|
|
1420
|
-
* to navigate.
|
|
1978
|
+
* to navigate. Below the `sm` viewport breakpoint the buttons centre in the
|
|
1979
|
+
* available width (DS-998). Must be rendered inside `<DataTablePagination>`.
|
|
1421
1980
|
*/
|
|
1422
1981
|
function DataTablePaginationNav({
|
|
1423
1982
|
ariaLabel = "Table pagination",
|
|
@@ -1425,6 +1984,7 @@ function DataTablePaginationNav({
|
|
|
1425
1984
|
className,
|
|
1426
1985
|
}: DataTablePaginationNavProps) {
|
|
1427
1986
|
const { info } = useDataTablePaginationContext();
|
|
1987
|
+
const isMobile = useIsBelowBreakpoint("sm");
|
|
1428
1988
|
|
|
1429
1989
|
const paginationItems = usePagination({
|
|
1430
1990
|
page: info.currentPage,
|
|
@@ -1438,7 +1998,9 @@ function DataTablePaginationNav({
|
|
|
1438
1998
|
return (
|
|
1439
1999
|
<Pagination
|
|
1440
2000
|
ariaLabel={ariaLabel}
|
|
1441
|
-
|
|
2001
|
+
// Below `sm` keep the base centred layout (the row count is removed
|
|
2002
|
+
// there); at `sm` and up hug the content and align right.
|
|
2003
|
+
className={cn(!isMobile && "mx-0 w-auto justify-end", className)}
|
|
1442
2004
|
dataHook={dataHook ?? "pagination-nav"}
|
|
1443
2005
|
>
|
|
1444
2006
|
<PaginationContent>
|
|
@@ -1551,6 +2113,20 @@ export interface DataTablePaginationProps<TData> {
|
|
|
1551
2113
|
* row count and the nav are empty, the component renders nothing — no
|
|
1552
2114
|
* consumer render gate needed.
|
|
1553
2115
|
*
|
|
2116
|
+
* **Responsive behaviour:** below the `sm` viewport breakpoint the row-count
|
|
2117
|
+
* label is removed and the page buttons centre in the available width — the
|
|
2118
|
+
* same rule `PaginationControls` follows for its caption. This applies to
|
|
2119
|
+
* both layouts: the default row count and `DataTablePaginationRowCount`
|
|
2120
|
+
* render nothing below `sm`, and `DataTablePaginationNav` centres itself.
|
|
2121
|
+
* From `sm` up the bar wraps inside narrow containers: when the row count
|
|
2122
|
+
* and the page buttons no longer fit on one line, the buttons move to their
|
|
2123
|
+
* own line below the row count — no consumer layout classes needed. The row
|
|
2124
|
+
* of page buttons itself does not wrap or shrink, so the **minimum supported
|
|
2125
|
+
* container width** is the width of the button row: **300px** below the `sm`
|
|
2126
|
+
* viewport breakpoint (compact five-slot list) and **388px** from `sm` up
|
|
2127
|
+
* (seven-slot list). Narrower containers than that are outside the
|
|
2128
|
+
* component's supported range (DS-998).
|
|
2129
|
+
*
|
|
1554
2130
|
* **Compositional mode** (with children): acts as a context provider.
|
|
1555
2131
|
* Compose `DataTablePaginationRowCount` and `DataTablePaginationNav`
|
|
1556
2132
|
* in any order/layout.
|
|
@@ -1588,6 +2164,7 @@ export function DataTablePagination<TData>({
|
|
|
1588
2164
|
children,
|
|
1589
2165
|
}: DataTablePaginationProps<TData>) {
|
|
1590
2166
|
const info = useDataTablePagination(table);
|
|
2167
|
+
const isMobile = useIsBelowBreakpoint("sm");
|
|
1591
2168
|
|
|
1592
2169
|
const contextValue = React.useMemo<DataTablePaginationContextValue>(
|
|
1593
2170
|
() => ({ info }),
|
|
@@ -1605,7 +2182,10 @@ export function DataTablePagination<TData>({
|
|
|
1605
2182
|
return (
|
|
1606
2183
|
<DataTablePaginationContext.Provider value={contextValue}>
|
|
1607
2184
|
<div
|
|
1608
|
-
className={cn(
|
|
2185
|
+
className={cn(
|
|
2186
|
+
"flex w-full flex-wrap items-center gap-x-4 gap-y-2",
|
|
2187
|
+
className
|
|
2188
|
+
)}
|
|
1609
2189
|
{...wrapperDataAttrs}
|
|
1610
2190
|
>
|
|
1611
2191
|
{children}
|
|
@@ -1615,6 +2195,9 @@ export function DataTablePagination<TData>({
|
|
|
1615
2195
|
}
|
|
1616
2196
|
|
|
1617
2197
|
const rowCountContent = (() => {
|
|
2198
|
+
// Below `sm` the label is removed so the page buttons get the full width
|
|
2199
|
+
// and centre (DS-998).
|
|
2200
|
+
if (isMobile) return null;
|
|
1618
2201
|
if (!showRowCount) return null;
|
|
1619
2202
|
if (renderRowCount === null) return null;
|
|
1620
2203
|
if (renderRowCount) {
|
|
@@ -1638,19 +2221,20 @@ export function DataTablePagination<TData>({
|
|
|
1638
2221
|
<DataTablePaginationContext.Provider value={contextValue}>
|
|
1639
2222
|
<div
|
|
1640
2223
|
className={cn(
|
|
1641
|
-
"flex min-h-9 w-full items-center gap-4",
|
|
2224
|
+
"flex min-h-9 w-full flex-wrap items-center gap-x-4 gap-y-2",
|
|
1642
2225
|
rowCountContent != null ? "justify-between" : "justify-end",
|
|
1643
2226
|
className
|
|
1644
2227
|
)}
|
|
1645
2228
|
{...wrapperDataAttrs}
|
|
1646
2229
|
>
|
|
1647
2230
|
{rowCountContent != null && (
|
|
1648
|
-
<span className="text-body-sm text-muted-foreground">
|
|
2231
|
+
<span className="text-body-sm text-muted-foreground whitespace-nowrap">
|
|
1649
2232
|
{rowCountContent}
|
|
1650
2233
|
</span>
|
|
1651
2234
|
)}
|
|
1652
2235
|
<DataTablePaginationNav
|
|
1653
2236
|
ariaLabel={ariaLabel}
|
|
2237
|
+
className="grow"
|
|
1654
2238
|
dataHook={`${dataHook}-nav`}
|
|
1655
2239
|
/>
|
|
1656
2240
|
</div>
|
|
@@ -1684,6 +2268,11 @@ export interface DataTableSelectAllCheckboxProps<TData> {
|
|
|
1684
2268
|
/**
|
|
1685
2269
|
* Header checkbox for selecting all visible page rows. Renders as
|
|
1686
2270
|
* indeterminate when some (but not all) rows are selected.
|
|
2271
|
+
*
|
|
2272
|
+
* While the surrounding `DataTable` is `refetching`, the checkbox is
|
|
2273
|
+
* `aria-disabled` and toggles are ignored (visually unchanged, still exposed
|
|
2274
|
+
* to screen readers so the select-all `<th>` never reads as empty): the rows
|
|
2275
|
+
* it would select are stale and about to be replaced (DS-916).
|
|
1687
2276
|
*/
|
|
1688
2277
|
export function DataTableSelectAllCheckbox<TData>({
|
|
1689
2278
|
table,
|
|
@@ -1692,8 +2281,10 @@ export function DataTableSelectAllCheckbox<TData>({
|
|
|
1692
2281
|
trackingLabel,
|
|
1693
2282
|
selectAllAriaLabel,
|
|
1694
2283
|
}: DataTableSelectAllCheckboxProps<TData>) {
|
|
2284
|
+
const refetching = React.useContext(DataTableRefetchingContext);
|
|
1695
2285
|
return (
|
|
1696
2286
|
<Checkbox
|
|
2287
|
+
aria-disabled={refetching || undefined}
|
|
1697
2288
|
aria-label={selectAllAriaLabel ?? "Select all"}
|
|
1698
2289
|
checked={
|
|
1699
2290
|
table.getIsAllPageRowsSelected() ||
|
|
@@ -1702,7 +2293,13 @@ export function DataTableSelectAllCheckbox<TData>({
|
|
|
1702
2293
|
dataHook={dataHook || "select-all-checkbox"}
|
|
1703
2294
|
trackingEl={trackingEl}
|
|
1704
2295
|
trackingLabel={trackingLabel}
|
|
1705
|
-
onCheckedChange={(value) =>
|
|
2296
|
+
onCheckedChange={(value) => {
|
|
2297
|
+
// The guard is the real block: the checkbox is controlled, so pointer
|
|
2298
|
+
// and keyboard toggles alike are ignored while refetching.
|
|
2299
|
+
if (!refetching) {
|
|
2300
|
+
table.toggleAllPageRowsSelected(!!value);
|
|
2301
|
+
}
|
|
2302
|
+
}}
|
|
1706
2303
|
/>
|
|
1707
2304
|
);
|
|
1708
2305
|
}
|
|
@@ -1727,6 +2324,11 @@ export interface DataTableSelectRowCheckboxProps<TData> {
|
|
|
1727
2324
|
|
|
1728
2325
|
/**
|
|
1729
2326
|
* Row-level selection checkbox. Disabled when the row cannot be selected.
|
|
2327
|
+
*
|
|
2328
|
+
* While the surrounding `DataTable` is `refetching`, the checkbox is
|
|
2329
|
+
* `aria-disabled` and toggles are ignored (visually unchanged, still exposed
|
|
2330
|
+
* to screen readers): the row it would select is stale and about to be
|
|
2331
|
+
* replaced (DS-916).
|
|
1730
2332
|
*/
|
|
1731
2333
|
export function DataTableSelectRowCheckbox<TData>({
|
|
1732
2334
|
row,
|
|
@@ -1735,15 +2337,23 @@ export function DataTableSelectRowCheckbox<TData>({
|
|
|
1735
2337
|
trackingLabel,
|
|
1736
2338
|
selectRowAriaLabel,
|
|
1737
2339
|
}: DataTableSelectRowCheckboxProps<TData>) {
|
|
2340
|
+
const refetching = React.useContext(DataTableRefetchingContext);
|
|
1738
2341
|
return (
|
|
1739
2342
|
<Checkbox
|
|
2343
|
+
aria-disabled={refetching || undefined}
|
|
1740
2344
|
aria-label={selectRowAriaLabel ?? "Select row"}
|
|
1741
2345
|
checked={row.getIsSelected()}
|
|
1742
2346
|
dataHook={dataHook || `select-row-${row.id}`}
|
|
1743
2347
|
disabled={!row.getCanSelect()}
|
|
1744
2348
|
trackingEl={trackingEl}
|
|
1745
2349
|
trackingLabel={trackingLabel}
|
|
1746
|
-
onCheckedChange={(value) =>
|
|
2350
|
+
onCheckedChange={(value) => {
|
|
2351
|
+
// The guard is the real block: the checkbox is controlled, so pointer
|
|
2352
|
+
// and keyboard toggles alike are ignored while refetching.
|
|
2353
|
+
if (!refetching) {
|
|
2354
|
+
row.toggleSelected(!!value);
|
|
2355
|
+
}
|
|
2356
|
+
}}
|
|
1747
2357
|
/>
|
|
1748
2358
|
);
|
|
1749
2359
|
}
|
|
@@ -1950,6 +2560,13 @@ export interface DataTableBulkActionsContextValue {
|
|
|
1950
2560
|
* `useDataTable` — the same option `DataTablePagination` relies on.
|
|
1951
2561
|
*/
|
|
1952
2562
|
totalCount: number;
|
|
2563
|
+
/**
|
|
2564
|
+
* Whether a server-side refetch is in flight (the bar's `refetching` prop).
|
|
2565
|
+
* `DataTableBulkActionsActions` goes inert on it; custom action parts built
|
|
2566
|
+
* on this context should do the same — the selection they would act on is
|
|
2567
|
+
* stale (DS-916).
|
|
2568
|
+
*/
|
|
2569
|
+
refetching: boolean;
|
|
1953
2570
|
}
|
|
1954
2571
|
|
|
1955
2572
|
const DataTableBulkActionsContext =
|
|
@@ -1996,6 +2613,16 @@ export interface DataTableBulkActionsProps<TData> {
|
|
|
1996
2613
|
* `DataTableBulkActionsActions`, and any custom parts in any order.
|
|
1997
2614
|
*/
|
|
1998
2615
|
children?: React.ReactNode;
|
|
2616
|
+
/**
|
|
2617
|
+
* Marks a server-side refetch as in flight — pass the same flag given to
|
|
2618
|
+
* the `DataTable`'s `refetching`. The bar sets `aria-busy` and
|
|
2619
|
+
* `DataTableBulkActionsActions` becomes inert (unfocusable and unclickable,
|
|
2620
|
+
* visually unchanged): bulk actions would act on stale rows about to be
|
|
2621
|
+
* replaced. The bar lives outside the table's subtree, so it cannot inherit
|
|
2622
|
+
* the flag from `DataTable` — it must be passed here too (DS-916).
|
|
2623
|
+
* @default false
|
|
2624
|
+
*/
|
|
2625
|
+
refetching?: boolean;
|
|
1999
2626
|
}
|
|
2000
2627
|
|
|
2001
2628
|
/**
|
|
@@ -2034,6 +2661,7 @@ export function DataTableBulkActions<TData>({
|
|
|
2034
2661
|
trackingLabel,
|
|
2035
2662
|
className,
|
|
2036
2663
|
children,
|
|
2664
|
+
refetching = false,
|
|
2037
2665
|
}: DataTableBulkActionsProps<TData>) {
|
|
2038
2666
|
const selectedCount = table.getFilteredSelectedRowModel().rows.length;
|
|
2039
2667
|
// getRowCount() = the rowCount option in manual mode, the filtered row
|
|
@@ -2041,8 +2669,8 @@ export function DataTableBulkActions<TData>({
|
|
|
2041
2669
|
const totalCount = table.getRowCount();
|
|
2042
2670
|
|
|
2043
2671
|
const contextValue = React.useMemo<DataTableBulkActionsContextValue>(
|
|
2044
|
-
() => ({ selectedCount, totalCount }),
|
|
2045
|
-
[selectedCount, totalCount]
|
|
2672
|
+
() => ({ selectedCount, totalCount, refetching }),
|
|
2673
|
+
[selectedCount, totalCount, refetching]
|
|
2046
2674
|
);
|
|
2047
2675
|
|
|
2048
2676
|
if (selectedCount === 0) return null;
|
|
@@ -2050,6 +2678,7 @@ export function DataTableBulkActions<TData>({
|
|
|
2050
2678
|
return (
|
|
2051
2679
|
<DataTableBulkActionsContext.Provider value={contextValue}>
|
|
2052
2680
|
<div
|
|
2681
|
+
aria-busy={refetching || undefined}
|
|
2053
2682
|
className={cn("flex items-center gap-2.5", className)}
|
|
2054
2683
|
data-hook={dataHook}
|
|
2055
2684
|
data-slot="data-table-bulk-actions"
|
|
@@ -2118,11 +2747,12 @@ export function DataTableBulkActionsSummary({
|
|
|
2118
2747
|
className,
|
|
2119
2748
|
children,
|
|
2120
2749
|
}: DataTableBulkActionsSummaryProps) {
|
|
2121
|
-
const
|
|
2750
|
+
const context = useDataTableBulkActionsContext();
|
|
2751
|
+
const { selectedCount, totalCount } = context;
|
|
2122
2752
|
|
|
2123
2753
|
let content: React.ReactNode;
|
|
2124
2754
|
if (typeof children === "function") {
|
|
2125
|
-
content = children(
|
|
2755
|
+
content = children(context);
|
|
2126
2756
|
} else if (children != null) {
|
|
2127
2757
|
content = children;
|
|
2128
2758
|
} else {
|
|
@@ -2170,17 +2800,26 @@ export interface DataTableBulkActionsActionsProps {
|
|
|
2170
2800
|
* Optional: a single action can sit directly inside
|
|
2171
2801
|
* `DataTableBulkActions`. Use this when you have several, or need them
|
|
2172
2802
|
* grouped and protected from shrinking.
|
|
2803
|
+
*
|
|
2804
|
+
* While the bar's `refetching` flag is set, the slot is `inert` — its buttons
|
|
2805
|
+
* cannot be clicked or focused (without a disabled look), because the
|
|
2806
|
+
* selection they would act on is stale (DS-916).
|
|
2173
2807
|
*/
|
|
2174
2808
|
export function DataTableBulkActionsActions({
|
|
2175
2809
|
dataHook = "data-table-bulk-actions-actions",
|
|
2176
2810
|
className,
|
|
2177
2811
|
children,
|
|
2178
2812
|
}: DataTableBulkActionsActionsProps) {
|
|
2813
|
+
// Read null-safely rather than via the throwing hook: the slot renders fine
|
|
2814
|
+
// outside the bar, it just has no refetch flag to honor there.
|
|
2815
|
+
const refetching =
|
|
2816
|
+
React.useContext(DataTableBulkActionsContext)?.refetching ?? false;
|
|
2179
2817
|
return (
|
|
2180
2818
|
<div
|
|
2181
2819
|
className={cn("flex shrink-0 items-center gap-2", className)}
|
|
2182
2820
|
data-hook={dataHook}
|
|
2183
2821
|
data-slot="data-table-bulk-actions-actions"
|
|
2822
|
+
inert={refetching || undefined}
|
|
2184
2823
|
>
|
|
2185
2824
|
{children}
|
|
2186
2825
|
</div>
|
|
@@ -2218,6 +2857,10 @@ export interface DataTableToolbarProps {
|
|
|
2218
2857
|
* note on `DataTable`. The built-in vertical padding provides the spacing
|
|
2219
2858
|
* between a toolbar and its table; don't add custom margins or padding.
|
|
2220
2859
|
*
|
|
2860
|
+
* Inside a Card with a header, filters that narrow what the card shows
|
|
2861
|
+
* (`DataTableSearch` included) go in the header's `CardToolbar`; this toolbar
|
|
2862
|
+
* keeps pagination beside the table. A report card uses both.
|
|
2863
|
+
*
|
|
2221
2864
|
* @example
|
|
2222
2865
|
* <DataTableToolbar dataHook="locations-toolbar">
|
|
2223
2866
|
* <DataTableToolbarLeft>
|