@brightlocal/ui-components 2.6.0 → 2.7.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,7 +11,7 @@
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`,
14
+ * - Helpers: `DataTableSearch`, `DataTablePagination`,
15
15
  * `DataTableColumnHeader`, `DataTableRowActions`,
16
16
  * `DataTableSelectAllCheckbox`, `DataTableSelectRowCheckbox`.
17
17
  *
@@ -28,7 +28,6 @@ import {
28
28
  type RowSelectionState,
29
29
  type SortingState,
30
30
  type Table as TanStackTable,
31
- createColumnHelper,
32
31
  flexRender,
33
32
  getCoreRowModel,
34
33
  getExpandedRowModel,
@@ -44,6 +43,7 @@ import {
44
43
  ArrowUpDown,
45
44
  Ellipsis,
46
45
  Search,
46
+ X,
47
47
  } from "@brightlocal/icons";
48
48
 
49
49
  import { cn } from "@brightlocal/ui-components/lib/utils";
@@ -84,7 +84,7 @@ import {
84
84
  * -----------------------------------------------------------------------------------------------*/
85
85
 
86
86
  /**
87
- * Small controlled/uncontrolled helper.
87
+ * Controlled/uncontrolled state helper.
88
88
  *
89
89
  * Resolves a "controlled or internal" value and returns a setter compatible
90
90
  * with TanStack Table's `SetStateAction<T>` updater signature. When the
@@ -100,7 +100,6 @@ function useControllable<T>(
100
100
  const [internal, setInternal] = React.useState<T>(initialValue);
101
101
  const value = controlled !== undefined ? controlled : internal;
102
102
 
103
- // Keep ref in sync so the setter always reads the latest value.
104
103
  const valueRef = React.useRef(value);
105
104
  React.useEffect(() => {
106
105
  valueRef.current = value;
@@ -447,48 +446,14 @@ export function DataTable<TData>({
447
446
  return (
448
447
  <div
449
448
  aria-busy={isLoading || undefined}
450
- className={cn("border-border rounded-md border", className)}
449
+ className={cn("border-border overflow-auto rounded-md border", className)}
451
450
  data-hook={dataHook}
452
451
  data-slot="data-table-view"
453
452
  data-tracking-el={trackingEl}
454
453
  data-tracking-label={trackingLabel}
455
454
  >
456
455
  <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>
456
+ <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
492
457
  <TableBody>
493
458
  {isLoading ? (
494
459
  <>
@@ -530,6 +495,56 @@ export function DataTable<TData>({
530
495
 
531
496
  DataTable.displayName = "DataTable";
532
497
 
498
+ /**
499
+ * Internal: render all header groups with `aria-sort` attributes.
500
+ * Shared between `DataTable` and `VirtualizedDataTable`.
501
+ */
502
+ function DataTableHeaderRows<TData>({
503
+ table,
504
+ stickyHeader,
505
+ }: {
506
+ table: TanStackTable<TData>;
507
+ stickyHeader: boolean;
508
+ }) {
509
+ return (
510
+ <TableHeader
511
+ className={cn(stickyHeader && "bg-background sticky top-0 z-10")}
512
+ >
513
+ {table.getHeaderGroups().map((headerGroup) => (
514
+ <TableRow key={headerGroup.id}>
515
+ {headerGroup.headers.map((header) => {
516
+ const sortDirection = header.column.getCanSort()
517
+ ? header.column.getIsSorted()
518
+ : false;
519
+ const ariaSort =
520
+ sortDirection === "asc"
521
+ ? "ascending"
522
+ : sortDirection === "desc"
523
+ ? "descending"
524
+ : header.column.getCanSort()
525
+ ? "none"
526
+ : undefined;
527
+ return (
528
+ <TableHead
529
+ key={header.id}
530
+ aria-sort={ariaSort}
531
+ colSpan={header.colSpan}
532
+ >
533
+ {header.isPlaceholder
534
+ ? null
535
+ : flexRender(
536
+ header.column.columnDef.header,
537
+ header.getContext()
538
+ )}
539
+ </TableHead>
540
+ );
541
+ })}
542
+ </TableRow>
543
+ ))}
544
+ </TableHeader>
545
+ );
546
+ }
547
+
533
548
  /**
534
549
  * Internal: render a single data (or pinned) row.
535
550
  * Kept internal because pinned rows share the same visual contract as data rows.
@@ -683,41 +698,7 @@ export function VirtualizedDataTable<TData>({
683
698
  style={height != null ? { height } : undefined}
684
699
  >
685
700
  <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>
701
+ <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
721
702
  <TableBody>
722
703
  {isLoading ? (
723
704
  <>
@@ -936,140 +917,6 @@ export function DataTableRowActions<TData>({
936
917
 
937
918
  DataTableRowActions.displayName = "DataTableRowActions";
938
919
 
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
920
  /* -------------------------------------------------------------------------------------------------
1074
921
  * DataTableSearch (filter input)
1075
922
  * -----------------------------------------------------------------------------------------------*/
@@ -1115,7 +962,10 @@ export function DataTableSearch<TData>({
1115
962
  };
1116
963
 
1117
964
  return (
1118
- <InputGroup {...inputGroupProps}>
965
+ <InputGroup data-slot="data-table-search" {...inputGroupProps}>
966
+ <InputGroupAddon className="pl-3">
967
+ <Search />
968
+ </InputGroupAddon>
1119
969
  <InputGroupInput
1120
970
  aria-label={ariaLabel}
1121
971
  placeholder={placeholder}
@@ -1123,15 +973,298 @@ export function DataTableSearch<TData>({
1123
973
  value={filterValue}
1124
974
  onChange={(event) => handleFilterChange(event.target.value)}
1125
975
  />
1126
- <InputGroupAddon className="pr-3">
1127
- <Search />
1128
- </InputGroupAddon>
976
+ {filterValue && (
977
+ <InputGroupAddon className="pr-1">
978
+ <Button
979
+ aria-label="Clear search"
980
+ className="h-auto p-1"
981
+ data-slot="data-table-search-clear"
982
+ dataHook={`${inputGroupProps.dataHook}-clear`}
983
+ variant="ghost"
984
+ onClick={() => handleFilterChange("")}
985
+ >
986
+ <X size={14} />
987
+ </Button>
988
+ </InputGroupAddon>
989
+ )}
1129
990
  </InputGroup>
1130
991
  );
1131
992
  }
1132
993
 
1133
994
  DataTableSearch.displayName = "DataTableSearch";
1134
995
 
996
+ /* -------------------------------------------------------------------------------------------------
997
+ * useDataTablePagination (hook)
998
+ * -----------------------------------------------------------------------------------------------*/
999
+
1000
+ /** Pagination info returned by `useDataTablePagination`. */
1001
+ interface DataTablePaginationInfo {
1002
+ /** Current 0-based page index. */
1003
+ pageIndex: number;
1004
+ /** Number of rows per page. */
1005
+ pageSize: number;
1006
+ /** Total rows across all pages. */
1007
+ totalRows: number;
1008
+ /** Total page count. */
1009
+ totalPages: number;
1010
+ /** First visible row (1-based, 0 when empty). */
1011
+ startRow: number;
1012
+ /** Last visible row. */
1013
+ endRow: number;
1014
+ /** Current page (1-based). */
1015
+ currentPage: number;
1016
+ /** Whether a previous page exists. */
1017
+ canPrev: boolean;
1018
+ /** Whether a next page exists. */
1019
+ canNext: boolean;
1020
+ /** Navigate to a 1-based page number. */
1021
+ goToPage: (page: number) => void;
1022
+ /** Navigate to the next page. */
1023
+ nextPage: () => void;
1024
+ /** Navigate to the previous page. */
1025
+ previousPage: () => void;
1026
+ /** Set page size (resets to page 1). */
1027
+ setPageSize: (size: number) => void;
1028
+ }
1029
+
1030
+ /**
1031
+ * Derives pagination state from a TanStack Table instance.
1032
+ *
1033
+ * Use when you need pagination metadata in a custom location (toolbar header,
1034
+ * sticky footer) without rendering `DataTablePagination`. The component itself
1035
+ * is built on this hook.
1036
+ *
1037
+ * @example
1038
+ * const { startRow, endRow, totalRows, canNext, nextPage } = useDataTablePagination(table);
1039
+ */
1040
+ function useDataTablePagination<TData>(
1041
+ table: TanStackTable<TData>
1042
+ ): DataTablePaginationInfo {
1043
+ const { pageIndex, pageSize } = table.getState().pagination;
1044
+ const totalRows = table.getRowCount();
1045
+ const totalPages = table.getPageCount();
1046
+ const canPrev = table.getCanPreviousPage();
1047
+ const canNext = table.getCanNextPage();
1048
+
1049
+ const currentPage = pageIndex + 1;
1050
+ const startRow = totalRows === 0 ? 0 : pageIndex * pageSize + 1;
1051
+ const endRow = Math.min(currentPage * pageSize, totalRows);
1052
+
1053
+ const goToPage = React.useCallback(
1054
+ (page: number) => table.setPageIndex(page - 1),
1055
+ [table]
1056
+ );
1057
+ const nextPageFn = React.useCallback(() => table.nextPage(), [table]);
1058
+ const previousPage = React.useCallback(() => table.previousPage(), [table]);
1059
+ const setPageSize = React.useCallback(
1060
+ (size: number) => table.setPageSize(size),
1061
+ [table]
1062
+ );
1063
+
1064
+ return React.useMemo(
1065
+ () => ({
1066
+ pageIndex,
1067
+ pageSize,
1068
+ totalRows,
1069
+ totalPages,
1070
+ startRow,
1071
+ endRow,
1072
+ currentPage,
1073
+ canPrev,
1074
+ canNext,
1075
+ goToPage,
1076
+ nextPage: nextPageFn,
1077
+ previousPage,
1078
+ setPageSize,
1079
+ }),
1080
+ [
1081
+ pageIndex,
1082
+ pageSize,
1083
+ totalRows,
1084
+ totalPages,
1085
+ startRow,
1086
+ endRow,
1087
+ currentPage,
1088
+ canPrev,
1089
+ canNext,
1090
+ goToPage,
1091
+ nextPageFn,
1092
+ previousPage,
1093
+ setPageSize,
1094
+ ]
1095
+ );
1096
+ }
1097
+
1098
+ /* -------------------------------------------------------------------------------------------------
1099
+ * DataTablePaginationContext (compositional sub-components)
1100
+ * -----------------------------------------------------------------------------------------------*/
1101
+
1102
+ interface DataTablePaginationContextValue {
1103
+ info: DataTablePaginationInfo;
1104
+ }
1105
+
1106
+ const DataTablePaginationContext =
1107
+ React.createContext<DataTablePaginationContextValue | null>(null);
1108
+
1109
+ function useDataTablePaginationContext() {
1110
+ const context = React.useContext(DataTablePaginationContext);
1111
+ if (!context) {
1112
+ throw new Error(
1113
+ "DataTablePagination sub-components must be used within <DataTablePagination>"
1114
+ );
1115
+ }
1116
+ return context;
1117
+ }
1118
+
1119
+ /* -------------------------------------------------------------------------------------------------
1120
+ * DataTablePaginationRowCount
1121
+ * -----------------------------------------------------------------------------------------------*/
1122
+
1123
+ /** Info passed to row-count render functions. */
1124
+ export interface RowCountRenderInfo {
1125
+ /** First visible row (1-based, 0 when empty). */
1126
+ startRow: number;
1127
+ /** Last visible row. */
1128
+ endRow: number;
1129
+ /** Total rows across all pages. */
1130
+ totalRows: number;
1131
+ /** Current 0-based page index. */
1132
+ pageIndex: number;
1133
+ /** Number of rows per page. */
1134
+ pageSize: number;
1135
+ }
1136
+
1137
+ export interface DataTablePaginationRowCountProps {
1138
+ /**
1139
+ * Render the row-count text. Receives pagination numbers; you control
1140
+ * wording, pluralization, and order. Return `null` to hide.
1141
+ * @default Renders "{startRow}-{endRow} of {totalRows}" or nothing when empty.
1142
+ */
1143
+ renderText?: (info: RowCountRenderInfo) => React.ReactNode;
1144
+ /** Additional class name. */
1145
+ className?: string;
1146
+ }
1147
+
1148
+ /**
1149
+ * Row-count label for `DataTablePagination`.
1150
+ *
1151
+ * Renders "start–end of total" by default. Pass `renderText` for i18n-friendly
1152
+ * custom text with full control over wording, pluralization, and order.
1153
+ *
1154
+ * Must be rendered inside `<DataTablePagination>`.
1155
+ */
1156
+ function DataTablePaginationRowCount({
1157
+ renderText,
1158
+ className,
1159
+ }: DataTablePaginationRowCountProps) {
1160
+ const { info } = useDataTablePaginationContext();
1161
+ const { startRow, endRow, totalRows, pageIndex, pageSize } = info;
1162
+
1163
+ const content = renderText
1164
+ ? renderText({ startRow, endRow, totalRows, pageIndex, pageSize })
1165
+ : totalRows === 0
1166
+ ? null
1167
+ : `${startRow}-${endRow} of ${totalRows}`;
1168
+
1169
+ if (content == null) return null;
1170
+
1171
+ return (
1172
+ <span
1173
+ className={cn("text-muted-foreground text-sm", className)}
1174
+ data-slot="data-table-pagination-row-count"
1175
+ >
1176
+ {content}
1177
+ </span>
1178
+ );
1179
+ }
1180
+
1181
+ DataTablePaginationRowCount.displayName = "DataTablePaginationRowCount";
1182
+
1183
+ /* -------------------------------------------------------------------------------------------------
1184
+ * DataTablePaginationNav
1185
+ * -----------------------------------------------------------------------------------------------*/
1186
+
1187
+ export interface DataTablePaginationNavProps {
1188
+ /** Accessible label for the nav landmark. @default "Table pagination" */
1189
+ ariaLabel?: string;
1190
+ /** Data hook for the nav element. */
1191
+ dataHook?: string;
1192
+ /** Additional class name. */
1193
+ className?: string;
1194
+ }
1195
+
1196
+ /**
1197
+ * Pagination navigation for `DataTablePagination`.
1198
+ *
1199
+ * Renders previous/next buttons and page links. Must be rendered inside
1200
+ * `<DataTablePagination>`.
1201
+ */
1202
+ function DataTablePaginationNav({
1203
+ ariaLabel = "Table pagination",
1204
+ dataHook,
1205
+ className,
1206
+ }: DataTablePaginationNavProps) {
1207
+ const { info } = useDataTablePaginationContext();
1208
+
1209
+ const paginationItems = usePagination({
1210
+ page: info.currentPage,
1211
+ totalPages: info.totalPages,
1212
+ siblingCount: 1,
1213
+ boundaryCount: 1,
1214
+ });
1215
+
1216
+ return (
1217
+ <Pagination
1218
+ ariaLabel={ariaLabel}
1219
+ className={cn("mx-0 w-auto justify-end", className)}
1220
+ dataHook={dataHook ?? "pagination-nav"}
1221
+ >
1222
+ <PaginationContent>
1223
+ {paginationItems.map((item, index) => {
1224
+ if (item === "previous") {
1225
+ return (
1226
+ <PaginationItem key="previous">
1227
+ <PaginationPrevious
1228
+ disabled={!info.canPrev}
1229
+ onClick={() => info.previousPage()}
1230
+ />
1231
+ </PaginationItem>
1232
+ );
1233
+ }
1234
+ if (item === "next") {
1235
+ return (
1236
+ <PaginationItem key="next">
1237
+ <PaginationNext
1238
+ disabled={!info.canNext}
1239
+ onClick={() => info.nextPage()}
1240
+ />
1241
+ </PaginationItem>
1242
+ );
1243
+ }
1244
+ if (item === "ellipsis") {
1245
+ return (
1246
+ <PaginationItem key={`ellipsis-${index}`}>
1247
+ <PaginationEllipsis />
1248
+ </PaginationItem>
1249
+ );
1250
+ }
1251
+ return (
1252
+ <PaginationItem key={item}>
1253
+ <PaginationLink
1254
+ isActive={item === info.currentPage}
1255
+ page={item}
1256
+ onClick={() => info.goToPage(item)}
1257
+ />
1258
+ </PaginationItem>
1259
+ );
1260
+ })}
1261
+ </PaginationContent>
1262
+ </Pagination>
1263
+ );
1264
+ }
1265
+
1266
+ DataTablePaginationNav.displayName = "DataTablePaginationNav";
1267
+
1135
1268
  /* -------------------------------------------------------------------------------------------------
1136
1269
  * DataTablePagination (pagination controls)
1137
1270
  * -----------------------------------------------------------------------------------------------*/
@@ -1144,117 +1277,153 @@ DataTableSearch.displayName = "DataTableSearch";
1144
1277
  * - Client-side: `enablePagination: true`
1145
1278
  * - Server-side: `manualPagination: true` + `rowCount` (or `pageCount`)
1146
1279
  * + controlled `pagination` / `onPaginationChange`
1280
+ *
1281
+ * **Compositional mode:** pass children (`DataTablePaginationRowCount`,
1282
+ * `DataTablePaginationNav`) for full layout control. Without children the
1283
+ * component renders its default layout.
1147
1284
  */
1148
1285
  export interface DataTablePaginationProps<TData> {
1149
1286
  /** TanStack Table instance. */
1150
1287
  table: TanStackTable<TData>;
1151
1288
  /** Data hook for automated testing (REQUIRED). */
1152
1289
  dataHook: string;
1290
+ /**
1291
+ * Show the row count text in the default (non-compositional) layout.
1292
+ * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
1293
+ * @default true
1294
+ */
1295
+ showRowCount?: boolean;
1296
+ /**
1297
+ * Render the row-count text. Receives pagination numbers; you control
1298
+ * wording, pluralization, and order. Return `null` to hide.
1299
+ * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
1300
+ * @default Renders "{startRow}-{endRow} of {totalRows}" or nothing when empty.
1301
+ */
1302
+ renderRowCount?: ((info: RowCountRenderInfo) => React.ReactNode) | null;
1153
1303
  /** Analytics element identifier. */
1154
1304
  trackingEl?: string;
1155
1305
  /** Analytics label. */
1156
1306
  trackingLabel?: string;
1157
1307
  /** Additional class name. */
1158
1308
  className?: string;
1159
- /** Accessible label for the nav landmark. @default "Table pagination" */
1309
+ /** Accessible label for the nav landmark (default layout only). @default "Table pagination" */
1160
1310
  ariaLabel?: string;
1311
+ /**
1312
+ * Compositional children. When provided, the component acts as a context
1313
+ * provider and renders children instead of the default layout.
1314
+ * Use `<DataTablePaginationRowCount>` and `<DataTablePaginationNav>`
1315
+ * as children.
1316
+ */
1317
+ children?: React.ReactNode;
1161
1318
  }
1162
1319
 
1163
1320
  /**
1164
- * Pagination controls with row count info for a DataTable.
1321
+ * Pagination controls for a DataTable.
1322
+ *
1323
+ * **Default mode** (no children): renders previous/next/page links and an
1324
+ * optional "start–end of total" row count label. Use `renderRowCount` for
1325
+ * i18n-friendly text.
1165
1326
  *
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()`.
1327
+ * **Compositional mode** (with children): acts as a context provider.
1328
+ * Compose `DataTablePaginationRowCount` and `DataTablePaginationNav`
1329
+ * in any order/layout.
1170
1330
  *
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.
1331
+ * @example
1332
+ * // Default mode
1333
+ * <DataTablePagination table={table} dataHook="pagination" />
1334
+ *
1335
+ * @example
1336
+ * // Default mode with i18n
1337
+ * <DataTablePagination
1338
+ * table={table}
1339
+ * dataHook="pagination"
1340
+ * renderRowCount={({ startRow, endRow, totalRows }) =>
1341
+ * t('pagination.caption', { from: startRow, to: endRow, total: totalRows })
1342
+ * }
1343
+ * />
1344
+ *
1345
+ * @example
1346
+ * // Compositional mode
1347
+ * <DataTablePagination table={table} dataHook="pagination">
1348
+ * <DataTablePaginationRowCount />
1349
+ * <DataTablePaginationNav />
1350
+ * </DataTablePagination>
1174
1351
  */
1175
1352
  export function DataTablePagination<TData>({
1176
1353
  table,
1177
1354
  dataHook,
1355
+ showRowCount = true,
1356
+ renderRowCount,
1178
1357
  trackingEl,
1179
1358
  trackingLabel,
1180
1359
  className,
1181
1360
  ariaLabel = "Table pagination",
1361
+ children,
1182
1362
  }: 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();
1363
+ const info = useDataTablePagination(table);
1188
1364
 
1189
- const currentPage = pageIndex + 1;
1190
- const startRow = totalRows === 0 ? 0 : pageIndex * pageSize + 1;
1191
- const endRow = Math.min(currentPage * pageSize, totalRows);
1365
+ const contextValue = React.useMemo<DataTablePaginationContextValue>(
1366
+ () => ({ info }),
1367
+ [info]
1368
+ );
1192
1369
 
1193
- const paginationItems = usePagination({
1194
- page: currentPage,
1195
- totalPages,
1196
- siblingCount: 1,
1197
- boundaryCount: 1,
1198
- });
1370
+ const wrapperDataAttrs = {
1371
+ "data-hook": dataHook,
1372
+ "data-slot": "data-table-pagination" as const,
1373
+ "data-tracking-el": trackingEl,
1374
+ "data-tracking-label": trackingLabel,
1375
+ };
1376
+
1377
+ if (children) {
1378
+ return (
1379
+ <DataTablePaginationContext.Provider value={contextValue}>
1380
+ <div
1381
+ className={cn("flex items-center gap-4", className)}
1382
+ {...wrapperDataAttrs}
1383
+ >
1384
+ {children}
1385
+ </div>
1386
+ </DataTablePaginationContext.Provider>
1387
+ );
1388
+ }
1389
+
1390
+ const rowCountContent = (() => {
1391
+ if (!showRowCount) return null;
1392
+ if (renderRowCount === null) return null;
1393
+ if (renderRowCount) {
1394
+ return renderRowCount({
1395
+ startRow: info.startRow,
1396
+ endRow: info.endRow,
1397
+ totalRows: info.totalRows,
1398
+ pageIndex: info.pageIndex,
1399
+ pageSize: info.pageSize,
1400
+ });
1401
+ }
1402
+ if (info.totalRows === 0) return null;
1403
+ return `${info.startRow}-${info.endRow} of ${info.totalRows}`;
1404
+ })();
1199
1405
 
1200
1406
  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`}
1407
+ <DataTablePaginationContext.Provider value={contextValue}>
1408
+ <div
1409
+ className={cn(
1410
+ "flex items-center gap-4",
1411
+ rowCountContent != null ? "justify-between" : "justify-end",
1412
+ className
1413
+ )}
1414
+ {...wrapperDataAttrs}
1215
1415
  >
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>
1416
+ {rowCountContent != null && (
1417
+ <span className="text-muted-foreground text-sm">
1418
+ {rowCountContent}
1419
+ </span>
1420
+ )}
1421
+ <DataTablePaginationNav
1422
+ ariaLabel={ariaLabel}
1423
+ dataHook={`${dataHook}-nav`}
1424
+ />
1425
+ </div>
1426
+ </DataTablePaginationContext.Provider>
1258
1427
  );
1259
1428
  }
1260
1429
 
@@ -1348,7 +1517,7 @@ DataTableSelectRowCheckbox.displayName = "DataTableSelectRowCheckbox";
1348
1517
  * Re-exported TanStack Table helpers
1349
1518
  * -----------------------------------------------------------------------------------------------*/
1350
1519
 
1351
- export { flexRender, createColumnHelper };
1520
+ export { DataTablePaginationRowCount, DataTablePaginationNav };
1352
1521
 
1353
1522
  export type {
1354
1523
  Column,