@brightlocal/ui-components 2.6.1 → 2.8.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.
@@ -11,9 +11,12 @@
11
11
  * - `VirtualizedDataTable`: drop-in alternative to `DataTable` that
12
12
  * renders only visible rows via `@tanstack/react-virtual`. Use for large
13
13
  * datasets (1 000+ rows) where full DOM rendering is too expensive.
14
- * - Helpers: `DataTableToolbar`, `DataTableSearch`, `DataTablePagination`,
15
- * `DataTableColumnHeader`, `DataTableRowActions`,
16
- * `DataTableSelectAllCheckbox`, `DataTableSelectRowCheckbox`.
14
+ * - Helpers: `DataTableSearch`, `DataTablePagination`,
15
+ * `DataTableColumnHeader`, `DataTableSelectAllCheckbox`,
16
+ * `DataTableSelectRowCheckbox`.
17
+ * - Layout: `DataTableToolbar`, `DataTableToolbarLeft`,
18
+ * `DataTableToolbarRight` — responsive flex container for search +
19
+ * pagination above (or below) the table.
17
20
  *
18
21
  * Block composition example — see `apps/sandbox/components/audit-table.tsx`.
19
22
  */
@@ -28,7 +31,6 @@ import {
28
31
  type RowSelectionState,
29
32
  type SortingState,
30
33
  type Table as TanStackTable,
31
- createColumnHelper,
32
34
  flexRender,
33
35
  getCoreRowModel,
34
36
  getExpandedRowModel,
@@ -38,22 +40,11 @@ import {
38
40
  useReactTable,
39
41
  } from "@tanstack/react-table";
40
42
  import { useVirtualizer } from "@tanstack/react-virtual";
41
- import {
42
- ArrowDown,
43
- ArrowUp,
44
- ArrowUpDown,
45
- Ellipsis,
46
- Search,
47
- } from "@brightlocal/icons";
43
+ import { ArrowDown, ArrowUp, ArrowUpDown, Search, X } from "@brightlocal/icons";
48
44
 
49
45
  import { cn } from "@brightlocal/ui-components/lib/utils";
50
46
  import { Button } from "../components/button";
51
47
  import { Checkbox } from "../components/checkbox";
52
- import {
53
- DropdownMenu,
54
- DropdownMenuContent,
55
- DropdownMenuTrigger,
56
- } from "../components/dropdown-menu";
57
48
  import {
58
49
  InputGroup,
59
50
  InputGroupAddon,
@@ -84,7 +75,7 @@ import {
84
75
  * -----------------------------------------------------------------------------------------------*/
85
76
 
86
77
  /**
87
- * Small controlled/uncontrolled helper.
78
+ * Controlled/uncontrolled state helper.
88
79
  *
89
80
  * Resolves a "controlled or internal" value and returns a setter compatible
90
81
  * with TanStack Table's `SetStateAction<T>` updater signature. When the
@@ -100,7 +91,6 @@ function useControllable<T>(
100
91
  const [internal, setInternal] = React.useState<T>(initialValue);
101
92
  const value = controlled !== undefined ? controlled : internal;
102
93
 
103
- // Keep ref in sync so the setter always reads the latest value.
104
94
  const valueRef = React.useRef(value);
105
95
  React.useEffect(() => {
106
96
  valueRef.current = value;
@@ -447,48 +437,14 @@ export function DataTable<TData>({
447
437
  return (
448
438
  <div
449
439
  aria-busy={isLoading || undefined}
450
- className={cn("border-border rounded-md border", className)}
440
+ className={cn("border-border overflow-auto rounded-md border", className)}
451
441
  data-hook={dataHook}
452
442
  data-slot="data-table-view"
453
443
  data-tracking-el={trackingEl}
454
444
  data-tracking-label={trackingLabel}
455
445
  >
456
446
  <Table dataHook={`${dataHook}-table`}>
457
- <TableHeader
458
- className={cn(stickyHeader && "bg-background sticky top-0 z-10")}
459
- >
460
- {table.getHeaderGroups().map((headerGroup) => (
461
- <TableRow key={headerGroup.id}>
462
- {headerGroup.headers.map((header) => {
463
- const sortDirection = header.column.getCanSort()
464
- ? header.column.getIsSorted()
465
- : false;
466
- const ariaSort =
467
- sortDirection === "asc"
468
- ? "ascending"
469
- : sortDirection === "desc"
470
- ? "descending"
471
- : header.column.getCanSort()
472
- ? "none"
473
- : undefined;
474
- return (
475
- <TableHead
476
- key={header.id}
477
- aria-sort={ariaSort}
478
- colSpan={header.colSpan}
479
- >
480
- {header.isPlaceholder
481
- ? null
482
- : flexRender(
483
- header.column.columnDef.header,
484
- header.getContext()
485
- )}
486
- </TableHead>
487
- );
488
- })}
489
- </TableRow>
490
- ))}
491
- </TableHeader>
447
+ <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
492
448
  <TableBody>
493
449
  {isLoading ? (
494
450
  <>
@@ -530,6 +486,56 @@ export function DataTable<TData>({
530
486
 
531
487
  DataTable.displayName = "DataTable";
532
488
 
489
+ /**
490
+ * Internal: render all header groups with `aria-sort` attributes.
491
+ * Shared between `DataTable` and `VirtualizedDataTable`.
492
+ */
493
+ function DataTableHeaderRows<TData>({
494
+ table,
495
+ stickyHeader,
496
+ }: {
497
+ table: TanStackTable<TData>;
498
+ stickyHeader: boolean;
499
+ }) {
500
+ return (
501
+ <TableHeader
502
+ className={cn(stickyHeader && "bg-background sticky top-0 z-10")}
503
+ >
504
+ {table.getHeaderGroups().map((headerGroup) => (
505
+ <TableRow key={headerGroup.id}>
506
+ {headerGroup.headers.map((header) => {
507
+ const sortDirection = header.column.getCanSort()
508
+ ? header.column.getIsSorted()
509
+ : false;
510
+ const ariaSort =
511
+ sortDirection === "asc"
512
+ ? "ascending"
513
+ : sortDirection === "desc"
514
+ ? "descending"
515
+ : header.column.getCanSort()
516
+ ? "none"
517
+ : undefined;
518
+ return (
519
+ <TableHead
520
+ key={header.id}
521
+ aria-sort={ariaSort}
522
+ colSpan={header.colSpan}
523
+ >
524
+ {header.isPlaceholder
525
+ ? null
526
+ : flexRender(
527
+ header.column.columnDef.header,
528
+ header.getContext()
529
+ )}
530
+ </TableHead>
531
+ );
532
+ })}
533
+ </TableRow>
534
+ ))}
535
+ </TableHeader>
536
+ );
537
+ }
538
+
533
539
  /**
534
540
  * Internal: render a single data (or pinned) row.
535
541
  * Kept internal because pinned rows share the same visual contract as data rows.
@@ -683,41 +689,7 @@ export function VirtualizedDataTable<TData>({
683
689
  style={height != null ? { height } : undefined}
684
690
  >
685
691
  <Table dataHook={`${dataHook}-table`}>
686
- <TableHeader
687
- className={cn(stickyHeader && "bg-background sticky top-0 z-10")}
688
- >
689
- {table.getHeaderGroups().map((headerGroup) => (
690
- <TableRow key={headerGroup.id}>
691
- {headerGroup.headers.map((header) => {
692
- const sortDirection = header.column.getCanSort()
693
- ? header.column.getIsSorted()
694
- : false;
695
- const ariaSort =
696
- sortDirection === "asc"
697
- ? "ascending"
698
- : sortDirection === "desc"
699
- ? "descending"
700
- : header.column.getCanSort()
701
- ? "none"
702
- : undefined;
703
- return (
704
- <TableHead
705
- key={header.id}
706
- aria-sort={ariaSort}
707
- colSpan={header.colSpan}
708
- >
709
- {header.isPlaceholder
710
- ? null
711
- : flexRender(
712
- header.column.columnDef.header,
713
- header.getContext()
714
- )}
715
- </TableHead>
716
- );
717
- })}
718
- </TableRow>
719
- ))}
720
- </TableHeader>
692
+ <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
721
693
  <TableBody>
722
694
  {isLoading ? (
723
695
  <>
@@ -877,199 +849,6 @@ export function DataTableColumnHeader<TData, TValue>({
877
849
 
878
850
  DataTableColumnHeader.displayName = "DataTableColumnHeader";
879
851
 
880
- /* -------------------------------------------------------------------------------------------------
881
- * DataTableRowActions (row ellipsis menu)
882
- * -----------------------------------------------------------------------------------------------*/
883
-
884
- /**
885
- * Props for `DataTableRowActions` — the standard row ellipsis actions menu.
886
- */
887
- export interface DataTableRowActionsProps<TData> {
888
- /** TanStack row instance (from the `cell` render slot). */
889
- row: Row<TData>;
890
- /** Data hook for automated testing. */
891
- dataHook?: string;
892
- /** Analytics element identifier. */
893
- trackingEl?: string;
894
- /** Analytics label. */
895
- trackingLabel?: string;
896
- /** Accessible label for the trigger. @default "Open row actions menu" */
897
- ariaLabel?: string;
898
- /** `DropdownMenuItem`s to render inside the menu. */
899
- children?: React.ReactNode;
900
- }
901
-
902
- /**
903
- * Row-level ellipsis dropdown menu. Pass `DropdownMenuItem`s as children.
904
- */
905
- export function DataTableRowActions<TData>({
906
- row,
907
- dataHook,
908
- trackingEl,
909
- trackingLabel,
910
- ariaLabel = "Open row actions menu",
911
- children,
912
- }: DataTableRowActionsProps<TData>) {
913
- return (
914
- <DropdownMenu>
915
- <DropdownMenuTrigger asChild data-slot="data-table-row-actions">
916
- <Button
917
- aria-label={ariaLabel}
918
- dataHook={dataHook || `row-actions-${row.id}`}
919
- size="sm"
920
- trackingEl={trackingEl}
921
- trackingLabel={trackingLabel}
922
- variant="ghost"
923
- >
924
- <Ellipsis />
925
- </Button>
926
- </DropdownMenuTrigger>
927
- <DropdownMenuContent
928
- align="end"
929
- dataHook={dataHook ? `${dataHook}-menu` : `row-actions-${row.id}-menu`}
930
- >
931
- {children}
932
- </DropdownMenuContent>
933
- </DropdownMenu>
934
- );
935
- }
936
-
937
- DataTableRowActions.displayName = "DataTableRowActions";
938
-
939
- /* -------------------------------------------------------------------------------------------------
940
- * DataTableToolbar (layout container)
941
- * -----------------------------------------------------------------------------------------------*/
942
-
943
- /**
944
- * Props for the root `DataTableToolbar` container.
945
- */
946
- export interface DataTableToolbarProps {
947
- /** Data hook for automated testing. */
948
- dataHook?: string;
949
- /** Analytics element identifier. */
950
- trackingEl?: string;
951
- /** Analytics label. */
952
- trackingLabel?: string;
953
- /** Additional class name. */
954
- className?: string;
955
- /** Toolbar content — usually `<DataTableToolbarLeft>` / `<DataTableToolbarRight>`. */
956
- children?: React.ReactNode;
957
- }
958
-
959
- /**
960
- * Props for `DataTableToolbarLeft`.
961
- */
962
- export interface DataTableToolbarLeftProps {
963
- /** Data hook for automated testing. */
964
- dataHook?: string;
965
- /** Analytics element identifier. */
966
- trackingEl?: string;
967
- /** Analytics label. */
968
- trackingLabel?: string;
969
- /** Additional class name. */
970
- className?: string;
971
- /** Content to render on the left side. */
972
- children?: React.ReactNode;
973
- }
974
-
975
- /**
976
- * Props for `DataTableToolbarRight`.
977
- */
978
- export interface DataTableToolbarRightProps {
979
- /** Data hook for automated testing. */
980
- dataHook?: string;
981
- /** Analytics element identifier. */
982
- trackingEl?: string;
983
- /** Analytics label. */
984
- trackingLabel?: string;
985
- /** Additional class name. */
986
- className?: string;
987
- /** Content to render on the right side. */
988
- children?: React.ReactNode;
989
- }
990
-
991
- export function DataTableToolbarLeft({
992
- dataHook,
993
- trackingEl,
994
- trackingLabel,
995
- className,
996
- children,
997
- }: DataTableToolbarLeftProps) {
998
- return (
999
- <div
1000
- className={cn("flex items-center gap-2", className)}
1001
- data-hook={dataHook}
1002
- data-slot="data-table-toolbar-left"
1003
- data-tracking-el={trackingEl}
1004
- data-tracking-label={trackingLabel}
1005
- >
1006
- {children}
1007
- </div>
1008
- );
1009
- }
1010
-
1011
- DataTableToolbarLeft.displayName = "DataTableToolbarLeft";
1012
-
1013
- export function DataTableToolbarRight({
1014
- dataHook,
1015
- trackingEl,
1016
- trackingLabel,
1017
- className,
1018
- children,
1019
- }: DataTableToolbarRightProps) {
1020
- return (
1021
- <div
1022
- className={cn("flex items-center gap-2", className)}
1023
- data-hook={dataHook}
1024
- data-slot="data-table-toolbar-right"
1025
- data-tracking-el={trackingEl}
1026
- data-tracking-label={trackingLabel}
1027
- >
1028
- {children}
1029
- </div>
1030
- );
1031
- }
1032
-
1033
- DataTableToolbarRight.displayName = "DataTableToolbarRight";
1034
-
1035
- /**
1036
- * Flexible two-column toolbar for composing DataTable UIs.
1037
- *
1038
- * @example
1039
- * <DataTableToolbar dataHook="toolbar">
1040
- * <DataTableToolbarLeft>
1041
- * <DataTableSearch table={table} dataHook="search" />
1042
- * </DataTableToolbarLeft>
1043
- * <DataTableToolbarRight>
1044
- * <DataTablePagination table={table} dataHook="pagination" />
1045
- * </DataTableToolbarRight>
1046
- * </DataTableToolbar>
1047
- */
1048
- export function DataTableToolbar({
1049
- dataHook,
1050
- trackingEl,
1051
- trackingLabel,
1052
- className,
1053
- children,
1054
- }: DataTableToolbarProps) {
1055
- return (
1056
- <div
1057
- className={cn(
1058
- "flex flex-wrap items-center justify-between gap-2 py-4",
1059
- className
1060
- )}
1061
- data-hook={dataHook}
1062
- data-slot="data-table-toolbar"
1063
- data-tracking-el={trackingEl}
1064
- data-tracking-label={trackingLabel}
1065
- >
1066
- {children}
1067
- </div>
1068
- );
1069
- }
1070
-
1071
- DataTableToolbar.displayName = "DataTableToolbar";
1072
-
1073
852
  /* -------------------------------------------------------------------------------------------------
1074
853
  * DataTableSearch (filter input)
1075
854
  * -----------------------------------------------------------------------------------------------*/
@@ -1115,7 +894,10 @@ export function DataTableSearch<TData>({
1115
894
  };
1116
895
 
1117
896
  return (
1118
- <InputGroup {...inputGroupProps}>
897
+ <InputGroup data-slot="data-table-search" {...inputGroupProps}>
898
+ <InputGroupAddon className="pl-3">
899
+ <Search />
900
+ </InputGroupAddon>
1119
901
  <InputGroupInput
1120
902
  aria-label={ariaLabel}
1121
903
  placeholder={placeholder}
@@ -1123,15 +905,298 @@ export function DataTableSearch<TData>({
1123
905
  value={filterValue}
1124
906
  onChange={(event) => handleFilterChange(event.target.value)}
1125
907
  />
1126
- <InputGroupAddon className="pr-3">
1127
- <Search />
1128
- </InputGroupAddon>
908
+ {filterValue && (
909
+ <InputGroupAddon className="pr-1">
910
+ <Button
911
+ aria-label="Clear search"
912
+ className="h-auto p-1"
913
+ data-slot="data-table-search-clear"
914
+ dataHook={`${inputGroupProps.dataHook}-clear`}
915
+ variant="ghost"
916
+ onClick={() => handleFilterChange("")}
917
+ >
918
+ <X size={14} />
919
+ </Button>
920
+ </InputGroupAddon>
921
+ )}
1129
922
  </InputGroup>
1130
923
  );
1131
924
  }
1132
925
 
1133
926
  DataTableSearch.displayName = "DataTableSearch";
1134
927
 
928
+ /* -------------------------------------------------------------------------------------------------
929
+ * useDataTablePagination (hook)
930
+ * -----------------------------------------------------------------------------------------------*/
931
+
932
+ /** Pagination info returned by `useDataTablePagination`. */
933
+ interface DataTablePaginationInfo {
934
+ /** Current 0-based page index. */
935
+ pageIndex: number;
936
+ /** Number of rows per page. */
937
+ pageSize: number;
938
+ /** Total rows across all pages. */
939
+ totalRows: number;
940
+ /** Total page count. */
941
+ totalPages: number;
942
+ /** First visible row (1-based, 0 when empty). */
943
+ startRow: number;
944
+ /** Last visible row. */
945
+ endRow: number;
946
+ /** Current page (1-based). */
947
+ currentPage: number;
948
+ /** Whether a previous page exists. */
949
+ canPrev: boolean;
950
+ /** Whether a next page exists. */
951
+ canNext: boolean;
952
+ /** Navigate to a 1-based page number. */
953
+ goToPage: (page: number) => void;
954
+ /** Navigate to the next page. */
955
+ nextPage: () => void;
956
+ /** Navigate to the previous page. */
957
+ previousPage: () => void;
958
+ /** Set page size (resets to page 1). */
959
+ setPageSize: (size: number) => void;
960
+ }
961
+
962
+ /**
963
+ * Derives pagination state from a TanStack Table instance.
964
+ *
965
+ * Use when you need pagination metadata in a custom location (toolbar header,
966
+ * sticky footer) without rendering `DataTablePagination`. The component itself
967
+ * is built on this hook.
968
+ *
969
+ * @example
970
+ * const { startRow, endRow, totalRows, canNext, nextPage } = useDataTablePagination(table);
971
+ */
972
+ function useDataTablePagination<TData>(
973
+ table: TanStackTable<TData>
974
+ ): DataTablePaginationInfo {
975
+ const { pageIndex, pageSize } = table.getState().pagination;
976
+ const totalRows = table.getRowCount();
977
+ const totalPages = table.getPageCount();
978
+ const canPrev = table.getCanPreviousPage();
979
+ const canNext = table.getCanNextPage();
980
+
981
+ const currentPage = pageIndex + 1;
982
+ const startRow = totalRows === 0 ? 0 : pageIndex * pageSize + 1;
983
+ const endRow = Math.min(currentPage * pageSize, totalRows);
984
+
985
+ const goToPage = React.useCallback(
986
+ (page: number) => table.setPageIndex(page - 1),
987
+ [table]
988
+ );
989
+ const nextPageFn = React.useCallback(() => table.nextPage(), [table]);
990
+ const previousPage = React.useCallback(() => table.previousPage(), [table]);
991
+ const setPageSize = React.useCallback(
992
+ (size: number) => table.setPageSize(size),
993
+ [table]
994
+ );
995
+
996
+ return React.useMemo(
997
+ () => ({
998
+ pageIndex,
999
+ pageSize,
1000
+ totalRows,
1001
+ totalPages,
1002
+ startRow,
1003
+ endRow,
1004
+ currentPage,
1005
+ canPrev,
1006
+ canNext,
1007
+ goToPage,
1008
+ nextPage: nextPageFn,
1009
+ previousPage,
1010
+ setPageSize,
1011
+ }),
1012
+ [
1013
+ pageIndex,
1014
+ pageSize,
1015
+ totalRows,
1016
+ totalPages,
1017
+ startRow,
1018
+ endRow,
1019
+ currentPage,
1020
+ canPrev,
1021
+ canNext,
1022
+ goToPage,
1023
+ nextPageFn,
1024
+ previousPage,
1025
+ setPageSize,
1026
+ ]
1027
+ );
1028
+ }
1029
+
1030
+ /* -------------------------------------------------------------------------------------------------
1031
+ * DataTablePaginationContext (compositional sub-components)
1032
+ * -----------------------------------------------------------------------------------------------*/
1033
+
1034
+ interface DataTablePaginationContextValue {
1035
+ info: DataTablePaginationInfo;
1036
+ }
1037
+
1038
+ const DataTablePaginationContext =
1039
+ React.createContext<DataTablePaginationContextValue | null>(null);
1040
+
1041
+ function useDataTablePaginationContext() {
1042
+ const context = React.useContext(DataTablePaginationContext);
1043
+ if (!context) {
1044
+ throw new Error(
1045
+ "DataTablePagination sub-components must be used within <DataTablePagination>"
1046
+ );
1047
+ }
1048
+ return context;
1049
+ }
1050
+
1051
+ /* -------------------------------------------------------------------------------------------------
1052
+ * DataTablePaginationRowCount
1053
+ * -----------------------------------------------------------------------------------------------*/
1054
+
1055
+ /** Info passed to row-count render functions. */
1056
+ export interface RowCountRenderInfo {
1057
+ /** First visible row (1-based, 0 when empty). */
1058
+ startRow: number;
1059
+ /** Last visible row. */
1060
+ endRow: number;
1061
+ /** Total rows across all pages. */
1062
+ totalRows: number;
1063
+ /** Current 0-based page index. */
1064
+ pageIndex: number;
1065
+ /** Number of rows per page. */
1066
+ pageSize: number;
1067
+ }
1068
+
1069
+ export interface DataTablePaginationRowCountProps {
1070
+ /**
1071
+ * Render the row-count text. Receives pagination numbers; you control
1072
+ * wording, pluralization, and order. Return `null` to hide.
1073
+ * @default Renders "{startRow}-{endRow} of {totalRows}" or nothing when empty.
1074
+ */
1075
+ renderText?: (info: RowCountRenderInfo) => React.ReactNode;
1076
+ /** Additional class name. */
1077
+ className?: string;
1078
+ }
1079
+
1080
+ /**
1081
+ * Row-count label for `DataTablePagination`.
1082
+ *
1083
+ * Renders "start–end of total" by default. Pass `renderText` for i18n-friendly
1084
+ * custom text with full control over wording, pluralization, and order.
1085
+ *
1086
+ * Must be rendered inside `<DataTablePagination>`.
1087
+ */
1088
+ function DataTablePaginationRowCount({
1089
+ renderText,
1090
+ className,
1091
+ }: DataTablePaginationRowCountProps) {
1092
+ const { info } = useDataTablePaginationContext();
1093
+ const { startRow, endRow, totalRows, pageIndex, pageSize } = info;
1094
+
1095
+ const content = renderText
1096
+ ? renderText({ startRow, endRow, totalRows, pageIndex, pageSize })
1097
+ : totalRows === 0
1098
+ ? null
1099
+ : `${startRow}-${endRow} of ${totalRows}`;
1100
+
1101
+ if (content == null) return null;
1102
+
1103
+ return (
1104
+ <span
1105
+ className={cn("text-muted-foreground text-sm", className)}
1106
+ data-slot="data-table-pagination-row-count"
1107
+ >
1108
+ {content}
1109
+ </span>
1110
+ );
1111
+ }
1112
+
1113
+ DataTablePaginationRowCount.displayName = "DataTablePaginationRowCount";
1114
+
1115
+ /* -------------------------------------------------------------------------------------------------
1116
+ * DataTablePaginationNav
1117
+ * -----------------------------------------------------------------------------------------------*/
1118
+
1119
+ export interface DataTablePaginationNavProps {
1120
+ /** Accessible label for the nav landmark. @default "Table pagination" */
1121
+ ariaLabel?: string;
1122
+ /** Data hook for the nav element. */
1123
+ dataHook?: string;
1124
+ /** Additional class name. */
1125
+ className?: string;
1126
+ }
1127
+
1128
+ /**
1129
+ * Pagination navigation for `DataTablePagination`.
1130
+ *
1131
+ * Renders previous/next buttons and page links. Must be rendered inside
1132
+ * `<DataTablePagination>`.
1133
+ */
1134
+ function DataTablePaginationNav({
1135
+ ariaLabel = "Table pagination",
1136
+ dataHook,
1137
+ className,
1138
+ }: DataTablePaginationNavProps) {
1139
+ const { info } = useDataTablePaginationContext();
1140
+
1141
+ const paginationItems = usePagination({
1142
+ page: info.currentPage,
1143
+ totalPages: info.totalPages,
1144
+ siblingCount: 1,
1145
+ boundaryCount: 1,
1146
+ });
1147
+
1148
+ return (
1149
+ <Pagination
1150
+ ariaLabel={ariaLabel}
1151
+ className={cn("mx-0 w-auto justify-end", className)}
1152
+ dataHook={dataHook ?? "pagination-nav"}
1153
+ >
1154
+ <PaginationContent>
1155
+ {paginationItems.map((item, index) => {
1156
+ if (item === "previous") {
1157
+ return (
1158
+ <PaginationItem key="previous">
1159
+ <PaginationPrevious
1160
+ disabled={!info.canPrev}
1161
+ onClick={() => info.previousPage()}
1162
+ />
1163
+ </PaginationItem>
1164
+ );
1165
+ }
1166
+ if (item === "next") {
1167
+ return (
1168
+ <PaginationItem key="next">
1169
+ <PaginationNext
1170
+ disabled={!info.canNext}
1171
+ onClick={() => info.nextPage()}
1172
+ />
1173
+ </PaginationItem>
1174
+ );
1175
+ }
1176
+ if (item === "ellipsis") {
1177
+ return (
1178
+ <PaginationItem key={`ellipsis-${index}`}>
1179
+ <PaginationEllipsis />
1180
+ </PaginationItem>
1181
+ );
1182
+ }
1183
+ return (
1184
+ <PaginationItem key={item}>
1185
+ <PaginationLink
1186
+ isActive={item === info.currentPage}
1187
+ page={item}
1188
+ onClick={() => info.goToPage(item)}
1189
+ />
1190
+ </PaginationItem>
1191
+ );
1192
+ })}
1193
+ </PaginationContent>
1194
+ </Pagination>
1195
+ );
1196
+ }
1197
+
1198
+ DataTablePaginationNav.displayName = "DataTablePaginationNav";
1199
+
1135
1200
  /* -------------------------------------------------------------------------------------------------
1136
1201
  * DataTablePagination (pagination controls)
1137
1202
  * -----------------------------------------------------------------------------------------------*/
@@ -1144,117 +1209,153 @@ DataTableSearch.displayName = "DataTableSearch";
1144
1209
  * - Client-side: `enablePagination: true`
1145
1210
  * - Server-side: `manualPagination: true` + `rowCount` (or `pageCount`)
1146
1211
  * + controlled `pagination` / `onPaginationChange`
1212
+ *
1213
+ * **Compositional mode:** pass children (`DataTablePaginationRowCount`,
1214
+ * `DataTablePaginationNav`) for full layout control. Without children the
1215
+ * component renders its default layout.
1147
1216
  */
1148
1217
  export interface DataTablePaginationProps<TData> {
1149
1218
  /** TanStack Table instance. */
1150
1219
  table: TanStackTable<TData>;
1151
1220
  /** Data hook for automated testing (REQUIRED). */
1152
1221
  dataHook: string;
1222
+ /**
1223
+ * Show the row count text in the default (non-compositional) layout.
1224
+ * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
1225
+ * @default true
1226
+ */
1227
+ showRowCount?: boolean;
1228
+ /**
1229
+ * Render the row-count text. Receives pagination numbers; you control
1230
+ * wording, pluralization, and order. Return `null` to hide.
1231
+ * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
1232
+ * @default Renders "{startRow}-{endRow} of {totalRows}" or nothing when empty.
1233
+ */
1234
+ renderRowCount?: ((info: RowCountRenderInfo) => React.ReactNode) | null;
1153
1235
  /** Analytics element identifier. */
1154
1236
  trackingEl?: string;
1155
1237
  /** Analytics label. */
1156
1238
  trackingLabel?: string;
1157
1239
  /** Additional class name. */
1158
1240
  className?: string;
1159
- /** Accessible label for the nav landmark. @default "Table pagination" */
1241
+ /** Accessible label for the nav landmark (default layout only). @default "Table pagination" */
1160
1242
  ariaLabel?: string;
1243
+ /**
1244
+ * Compositional children. When provided, the component acts as a context
1245
+ * provider and renders children instead of the default layout.
1246
+ * Use `<DataTablePaginationRowCount>` and `<DataTablePaginationNav>`
1247
+ * as children.
1248
+ */
1249
+ children?: React.ReactNode;
1161
1250
  }
1162
1251
 
1163
1252
  /**
1164
- * Pagination controls with row count info for a DataTable.
1253
+ * Pagination controls for a DataTable.
1254
+ *
1255
+ * **Default mode** (no children): renders previous/next/page links and an
1256
+ * optional "start–end of total" row count label. Use `renderRowCount` for
1257
+ * i18n-friendly text.
1258
+ *
1259
+ * **Compositional mode** (with children): acts as a context provider.
1260
+ * Compose `DataTablePaginationRowCount` and `DataTablePaginationNav`
1261
+ * in any order/layout.
1165
1262
  *
1166
- * Displays "start–end of total" plus previous/next/page links. Derives all
1167
- * state from the TanStack Table instance — uses `table.getRowCount()`,
1168
- * `table.getPageCount()`, `table.getCanPreviousPage()`,
1169
- * `table.getCanNextPage()`, and `table.setPageIndex()`.
1263
+ * @example
1264
+ * // Default mode
1265
+ * <DataTablePagination table={table} dataHook="pagination" />
1266
+ *
1267
+ * @example
1268
+ * // Default mode with i18n
1269
+ * <DataTablePagination
1270
+ * table={table}
1271
+ * dataHook="pagination"
1272
+ * renderRowCount={({ startRow, endRow, totalRows }) =>
1273
+ * t('pagination.caption', { from: startRow, to: endRow, total: totalRows })
1274
+ * }
1275
+ * />
1170
1276
  *
1171
- * Works transparently in both client-side and server-side (manual) modes
1172
- * because TanStack Table handles the distinction internally when
1173
- * `manualPagination` + `rowCount` are set on the hook.
1277
+ * @example
1278
+ * // Compositional mode
1279
+ * <DataTablePagination table={table} dataHook="pagination">
1280
+ * <DataTablePaginationRowCount />
1281
+ * <DataTablePaginationNav />
1282
+ * </DataTablePagination>
1174
1283
  */
1175
1284
  export function DataTablePagination<TData>({
1176
1285
  table,
1177
1286
  dataHook,
1287
+ showRowCount = true,
1288
+ renderRowCount,
1178
1289
  trackingEl,
1179
1290
  trackingLabel,
1180
1291
  className,
1181
1292
  ariaLabel = "Table pagination",
1293
+ children,
1182
1294
  }: DataTablePaginationProps<TData>) {
1183
- const { pageIndex, pageSize } = table.getState().pagination;
1184
- const totalRows = table.getRowCount();
1185
- const totalPages = table.getPageCount();
1186
- const canPrev = table.getCanPreviousPage();
1187
- const canNext = table.getCanNextPage();
1295
+ const info = useDataTablePagination(table);
1188
1296
 
1189
- const currentPage = pageIndex + 1;
1190
- const startRow = totalRows === 0 ? 0 : pageIndex * pageSize + 1;
1191
- const endRow = Math.min(currentPage * pageSize, totalRows);
1297
+ const contextValue = React.useMemo<DataTablePaginationContextValue>(
1298
+ () => ({ info }),
1299
+ [info]
1300
+ );
1192
1301
 
1193
- const paginationItems = usePagination({
1194
- page: currentPage,
1195
- totalPages,
1196
- siblingCount: 1,
1197
- boundaryCount: 1,
1198
- });
1302
+ const wrapperDataAttrs = {
1303
+ "data-hook": dataHook,
1304
+ "data-slot": "data-table-pagination" as const,
1305
+ "data-tracking-el": trackingEl,
1306
+ "data-tracking-label": trackingLabel,
1307
+ };
1308
+
1309
+ if (children) {
1310
+ return (
1311
+ <DataTablePaginationContext.Provider value={contextValue}>
1312
+ <div
1313
+ className={cn("flex w-full items-center gap-4", className)}
1314
+ {...wrapperDataAttrs}
1315
+ >
1316
+ {children}
1317
+ </div>
1318
+ </DataTablePaginationContext.Provider>
1319
+ );
1320
+ }
1321
+
1322
+ const rowCountContent = (() => {
1323
+ if (!showRowCount) return null;
1324
+ if (renderRowCount === null) return null;
1325
+ if (renderRowCount) {
1326
+ return renderRowCount({
1327
+ startRow: info.startRow,
1328
+ endRow: info.endRow,
1329
+ totalRows: info.totalRows,
1330
+ pageIndex: info.pageIndex,
1331
+ pageSize: info.pageSize,
1332
+ });
1333
+ }
1334
+ if (info.totalRows === 0) return null;
1335
+ return `${info.startRow}-${info.endRow} of ${info.totalRows}`;
1336
+ })();
1199
1337
 
1200
1338
  return (
1201
- <div
1202
- className={cn("flex items-center justify-end gap-4", className)}
1203
- data-hook={dataHook}
1204
- data-slot="data-table-pagination"
1205
- data-tracking-el={trackingEl}
1206
- data-tracking-label={trackingLabel}
1207
- >
1208
- <span className="text-muted-foreground text-sm">
1209
- {totalRows === 0 ? "0 of 0" : `${startRow}-${endRow} of ${totalRows}`}
1210
- </span>
1211
- <Pagination
1212
- ariaLabel={ariaLabel}
1213
- className="mx-0 w-auto justify-end"
1214
- dataHook={`${dataHook}-nav`}
1339
+ <DataTablePaginationContext.Provider value={contextValue}>
1340
+ <div
1341
+ className={cn(
1342
+ "flex w-full items-center gap-4",
1343
+ rowCountContent != null ? "justify-between" : "justify-end",
1344
+ className
1345
+ )}
1346
+ {...wrapperDataAttrs}
1215
1347
  >
1216
- <PaginationContent>
1217
- {paginationItems.map((item, index) => {
1218
- if (item === "previous") {
1219
- return (
1220
- <PaginationItem key="previous">
1221
- <PaginationPrevious
1222
- disabled={!canPrev}
1223
- onClick={() => table.previousPage()}
1224
- />
1225
- </PaginationItem>
1226
- );
1227
- }
1228
- if (item === "next") {
1229
- return (
1230
- <PaginationItem key="next">
1231
- <PaginationNext
1232
- disabled={!canNext}
1233
- onClick={() => table.nextPage()}
1234
- />
1235
- </PaginationItem>
1236
- );
1237
- }
1238
- if (item === "ellipsis") {
1239
- return (
1240
- <PaginationItem key={`ellipsis-${index}`}>
1241
- <PaginationEllipsis />
1242
- </PaginationItem>
1243
- );
1244
- }
1245
- return (
1246
- <PaginationItem key={item}>
1247
- <PaginationLink
1248
- isActive={item === currentPage}
1249
- page={item}
1250
- onClick={() => table.setPageIndex(item - 1)}
1251
- />
1252
- </PaginationItem>
1253
- );
1254
- })}
1255
- </PaginationContent>
1256
- </Pagination>
1257
- </div>
1348
+ {rowCountContent != null && (
1349
+ <span className="text-muted-foreground text-sm">
1350
+ {rowCountContent}
1351
+ </span>
1352
+ )}
1353
+ <DataTablePaginationNav
1354
+ ariaLabel={ariaLabel}
1355
+ dataHook={`${dataHook}-nav`}
1356
+ />
1357
+ </div>
1358
+ </DataTablePaginationContext.Provider>
1258
1359
  );
1259
1360
  }
1260
1361
 
@@ -1344,11 +1445,142 @@ export function DataTableSelectRowCheckbox<TData>({
1344
1445
 
1345
1446
  DataTableSelectRowCheckbox.displayName = "DataTableSelectRowCheckbox";
1346
1447
 
1448
+ /* -------------------------------------------------------------------------------------------------
1449
+ * DataTableToolbar (layout container)
1450
+ * -----------------------------------------------------------------------------------------------*/
1451
+
1452
+ /**
1453
+ * Props for `DataTableToolbar` — a responsive flex container for laying out
1454
+ * search, filters, pagination, and actions above (or below) a DataTable.
1455
+ */
1456
+ export interface DataTableToolbarProps {
1457
+ /** Data hook for automated testing (REQUIRED). */
1458
+ dataHook: string;
1459
+ /** Additional class name (merged after defaults via `cn`). */
1460
+ className?: string;
1461
+ /** Toolbar contents — typically `DataTableToolbarLeft` and `DataTableToolbarRight`. */
1462
+ children: React.ReactNode;
1463
+ }
1464
+
1465
+ /**
1466
+ * Responsive toolbar container for DataTable companion controls.
1467
+ *
1468
+ * Stacks vertically on mobile (< 640 px) and switches to a horizontal
1469
+ * row on `sm:` and up. Layout-only — no dependency on a TanStack Table
1470
+ * instance, so it works for table footers or any search-plus-pagination row.
1471
+ *
1472
+ * @example
1473
+ * <DataTableToolbar dataHook="locations-toolbar">
1474
+ * <DataTableToolbarLeft>
1475
+ * <DataTableSearch table={table} dataHook="search" />
1476
+ * </DataTableToolbarLeft>
1477
+ * <DataTableToolbarRight>
1478
+ * <DataTablePagination table={table} dataHook="pagination" />
1479
+ * </DataTableToolbarRight>
1480
+ * </DataTableToolbar>
1481
+ */
1482
+ export function DataTableToolbar({
1483
+ dataHook,
1484
+ className,
1485
+ children,
1486
+ }: DataTableToolbarProps) {
1487
+ return (
1488
+ <div
1489
+ className={cn(
1490
+ "flex flex-col gap-3 py-4 sm:flex-row sm:items-center",
1491
+ className
1492
+ )}
1493
+ data-hook={dataHook}
1494
+ data-slot="data-table-toolbar"
1495
+ >
1496
+ {children}
1497
+ </div>
1498
+ );
1499
+ }
1500
+
1501
+ DataTableToolbar.displayName = "DataTableToolbar";
1502
+
1503
+ /* -------------------------------------------------------------------------------------------------
1504
+ * DataTableToolbarLeft (search / filters slot)
1505
+ * -----------------------------------------------------------------------------------------------*/
1506
+
1507
+ /**
1508
+ * Props for `DataTableToolbarLeft` — the left slot inside a `DataTableToolbar`.
1509
+ */
1510
+ export interface DataTableToolbarLeftProps {
1511
+ /** Additional class name (merged after defaults via `cn`). */
1512
+ className?: string;
1513
+ /** Slot contents — typically `DataTableSearch` and filter controls. */
1514
+ children: React.ReactNode;
1515
+ }
1516
+
1517
+ /**
1518
+ * Left slot of `DataTableToolbar`. Grows to fill remaining space on
1519
+ * desktop; full-width on mobile. `min-w-0` lets long inputs shrink
1520
+ * instead of overflowing on narrow viewports.
1521
+ */
1522
+ export function DataTableToolbarLeft({
1523
+ className,
1524
+ children,
1525
+ }: DataTableToolbarLeftProps) {
1526
+ return (
1527
+ <div
1528
+ className={cn(
1529
+ "flex w-full min-w-0 items-center gap-2 sm:w-auto sm:flex-1",
1530
+ className
1531
+ )}
1532
+ data-slot="data-table-toolbar-left"
1533
+ >
1534
+ {children}
1535
+ </div>
1536
+ );
1537
+ }
1538
+
1539
+ DataTableToolbarLeft.displayName = "DataTableToolbarLeft";
1540
+
1541
+ /* -------------------------------------------------------------------------------------------------
1542
+ * DataTableToolbarRight (pagination / actions slot)
1543
+ * -----------------------------------------------------------------------------------------------*/
1544
+
1545
+ /**
1546
+ * Props for `DataTableToolbarRight` — the right slot inside a `DataTableToolbar`.
1547
+ */
1548
+ export interface DataTableToolbarRightProps {
1549
+ /** Additional class name (merged after defaults via `cn`). */
1550
+ className?: string;
1551
+ /** Slot contents — typically `DataTablePagination` or action buttons. */
1552
+ children: React.ReactNode;
1553
+ }
1554
+
1555
+ /**
1556
+ * Right slot of `DataTableToolbar`. Collapses to content width and
1557
+ * right-aligns on desktop; full-width with `justify-end` on mobile so
1558
+ * pagination controls don't jump when stacking.
1559
+ */
1560
+ export function DataTableToolbarRight({
1561
+ className,
1562
+ children,
1563
+ }: DataTableToolbarRightProps) {
1564
+ return (
1565
+ <div
1566
+ className={cn(
1567
+ "flex w-full items-center justify-end gap-2 sm:w-auto",
1568
+ className
1569
+ )}
1570
+ data-slot="data-table-toolbar-right"
1571
+ >
1572
+ {children}
1573
+ </div>
1574
+ );
1575
+ }
1576
+
1577
+ DataTableToolbarRight.displayName = "DataTableToolbarRight";
1578
+
1347
1579
  /* -------------------------------------------------------------------------------------------------
1348
1580
  * Re-exported TanStack Table helpers
1349
1581
  * -----------------------------------------------------------------------------------------------*/
1350
1582
 
1351
- export { flexRender, createColumnHelper };
1583
+ export { DataTablePaginationRowCount, DataTablePaginationNav };
1352
1584
 
1353
1585
  export type {
1354
1586
  Column,