@brightlocal/ui-components 2.2.0 → 2.3.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.
@@ -1,303 +1,487 @@
1
- import { ColumnDef, ColumnOrderState, ColumnPinningState, ExpandedState, GroupingState, RowPinningState, SortingState, ColumnFiltersState, RowSelectionState, Table as TanStackTable, Column, Row } from '@tanstack/react-table';
1
+ import { Column, ColumnDef, ExpandedState, PaginationState, Row, RowSelectionState, SortingState, Table as TanStackTable, createColumnHelper, flexRender } from '@tanstack/react-table';
2
+ import { InputGroup } from '../input-group';
3
+ /**
4
+ * DataTable — composable data table primitives built on TanStack Table.
5
+ *
6
+ * Architecture:
7
+ * - `useDataTable` hook: owns TanStack Table wiring, feature toggles,
8
+ * and controlled/uncontrolled state orchestration.
9
+ * - `DataTable`: generic renderer for headers, rows, loading skeletons,
10
+ * and the empty state.
11
+ * - `VirtualizedDataTable`: drop-in alternative to `DataTable` that
12
+ * renders only visible rows via `@tanstack/react-virtual`. Use for large
13
+ * datasets (1 000+ rows) where full DOM rendering is too expensive.
14
+ * - Helpers: `DataTableToolbar`, `DataTableSearch`, `DataTablePagination`,
15
+ * `DataTableColumnHeader`, `DataTableRowActions`,
16
+ * `DataTableSelectAllCheckbox`, `DataTableSelectRowCheckbox`.
17
+ *
18
+ * Block composition example — see `apps/sandbox/components/audit-table.tsx`.
19
+ */
2
20
  import * as React from "react";
3
21
  /**
4
- * Re-export TanStack Table utilities for convenience
22
+ * Configuration for `useDataTable`.
23
+ *
24
+ * Props are tiered as:
25
+ * - **Common**: sorting, global filtering, row selection, pagination.
26
+ * - **Advanced**: column ordering, expanding.
27
+ *
28
+ * All feature flags default to `false` except `enableSorting` which defaults
29
+ * to `true` — tables are nearly always sortable.
30
+ *
31
+ * Every feature exposes an optional controlled state pair
32
+ * (`<feature>` + `on<Feature>Change`). Provide neither for internal state,
33
+ * both for fully controlled state, or just the callback to observe internal
34
+ * state changes.
35
+ *
36
+ * **Performance:** per TanStack's guidance, memoize `columns` and `data` in
37
+ * the parent component (e.g., `React.useMemo` or module-scope constants) to
38
+ * avoid re-creating the table instance on every render.
39
+ *
40
+ * **Server-side row selection:** pass `getRowId` to derive stable row IDs
41
+ * from your data. Without it, selection keys are row array indices, which
42
+ * become stale across server-side page changes or re-sorts.
5
43
  */
6
- export { type ColumnDef, type ColumnOrderState, type ColumnPinningState, type ExpandedState, type GroupingState, type RowPinningState, type SortingState, type ColumnFiltersState, type RowSelectionState, type Column, type Row, flexRender, } from '@tanstack/react-table';
7
- export { createColumnHelper } from '@tanstack/react-table';
8
- interface DataTableProps<TData, TValue> {
9
- /** Column definitions for the table */
10
- columns: ColumnDef<TData, TValue>[];
11
- /** Data array to display in the table */
44
+ export interface UseDataTableOptions<TData> {
45
+ /** Column definitions. Memoize in parent to avoid re-creating the table. */
46
+ columns: ColumnDef<TData, unknown>[];
47
+ /** Row data. Memoize in parent to avoid re-creating the table. */
12
48
  data: TData[];
13
- /** Data hook for automated testing (REQUIRED) */
14
- dataHook: string;
15
- /** Tracking element identifier for analytics */
16
- trackingEl?: string;
17
- /** Tracking label for analytics context */
18
- trackingLabel?: string;
19
- /** Enable row selection */
20
- enableRowSelection?: boolean;
21
- /** Enable sorting */
49
+ /**
50
+ * Derive a stable row ID from the row data. Required for server-side
51
+ * pagination with row selection — otherwise selection keys are array
52
+ * indices and become stale when the page changes.
53
+ * @example (row) => row.id
54
+ */
55
+ getRowId?: (originalRow: TData, index: number, parent?: Row<TData>) => string;
56
+ /** Enable column sorting. @default true */
22
57
  enableSorting?: boolean;
23
- /** Enable column filters */
24
- enableFiltering?: boolean;
25
- /** Enable global filtering */
58
+ /** Enable global text search across rows (substring match). @default false */
26
59
  enableGlobalFiltering?: boolean;
27
- /** Enable pagination */
60
+ /** Enable row selection via checkboxes. @default false */
61
+ enableRowSelection?: boolean;
62
+ /** Enable client-side pagination. @default false */
28
63
  enablePagination?: boolean;
29
- /** Enable column pinning */
30
- enableColumnPinning?: boolean;
31
- /** Enable row pinning */
32
- enableRowPinning?: boolean;
33
- /** Enable column ordering/reordering */
34
- enableColumnOrdering?: boolean;
35
- /** Enable grouping */
36
- enableGrouping?: boolean;
37
- /** Enable expanding rows */
38
- enableExpanding?: boolean;
39
- /** Enable faceted values (for filter dropdowns) */
40
- enableFaceting?: boolean;
41
- /** Initial page size for pagination */
64
+ /** Initial page size when pagination is enabled. @default 10 */
42
65
  pageSize?: number;
43
- /** Message to display when there are no results */
44
- noResultsMessage?: string;
45
- /** Show loading skeleton state */
46
- isLoading?: boolean;
47
- /** Number of skeleton rows to show when loading (defaults to pageSize) */
48
- skeletonRowCount?: number;
49
- /** Function to get sub-rows for expanding */
66
+ /**
67
+ * Skip client-side sorting — the server pre-sorts `data`.
68
+ * Sorting state and UI indicators still work; only the client-side
69
+ * `getSortedRowModel` transform is suppressed.
70
+ * @default false
71
+ */
72
+ manualSorting?: boolean;
73
+ /**
74
+ * Skip client-side filtering — the server pre-filters `data`.
75
+ * Global filter state still works; only the client-side
76
+ * `getFilteredRowModel` transform is suppressed.
77
+ * @default false
78
+ */
79
+ manualFiltering?: boolean;
80
+ /**
81
+ * Skip client-side pagination — the server pre-slices `data`.
82
+ * Pagination state still works; only the client-side
83
+ * `getPaginationRowModel` transform is suppressed.
84
+ * Pair with `rowCount` or `pageCount` so the table knows the total.
85
+ * @default false
86
+ */
87
+ manualPagination?: boolean;
88
+ /**
89
+ * Total row count across all server pages. Used to derive `pageCount`
90
+ * when `manualPagination` is enabled.
91
+ */
92
+ rowCount?: number;
93
+ /**
94
+ * Total page count. Takes precedence over the value derived from
95
+ * `rowCount`. Use `-1` when the total is unknown (infinite scroll).
96
+ */
97
+ pageCount?: number;
98
+ /** Advanced: enable expandable rows. @default false */
99
+ enableExpanding?: boolean;
100
+ /** Advanced: return sub-rows for tree/expanding tables. */
50
101
  getSubRows?: (originalRow: TData, index: number) => TData[] | undefined;
51
- /** Controlled sorting state */
102
+ /**
103
+ * Controlled pagination state. When provided, the consumer owns
104
+ * `pageIndex` and `pageSize`; the hook calls `onPaginationChange`
105
+ * instead of updating internal state. This is especially useful in
106
+ * manual pagination mode where the server drives page state.
107
+ *
108
+ * When omitted, pagination state is managed internally (seeded from
109
+ * the `pageSize` option, defaulting to page index 0).
110
+ */
111
+ pagination?: PaginationState;
112
+ /** Called when pagination state changes (page navigation or page size). */
113
+ onPaginationChange?: (pagination: PaginationState) => void;
52
114
  sorting?: SortingState;
53
- /** Callback when sorting changes */
54
115
  onSortingChange?: (sorting: SortingState) => void;
55
- /** Controlled column filters state */
56
- columnFilters?: ColumnFiltersState;
57
- /** Callback when column filters change */
58
- onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
59
- /** Controlled global filter state */
60
116
  globalFilter?: string;
61
- /** Callback when global filter changes */
62
117
  onGlobalFilterChange?: (filter: string) => void;
63
- /** Controlled row selection state */
64
118
  rowSelection?: RowSelectionState;
65
- /** Callback when row selection changes */
66
119
  onRowSelectionChange?: (selection: RowSelectionState) => void;
67
- /** Controlled column order state */
68
- columnOrder?: ColumnOrderState;
69
- /** Callback when column order changes */
70
- onColumnOrderChange?: (order: ColumnOrderState) => void;
71
- /** Controlled column pinning state */
72
- columnPinning?: ColumnPinningState;
73
- /** Callback when column pinning changes */
74
- onColumnPinningChange?: (pinning: ColumnPinningState) => void;
75
- /** Controlled row pinning state */
76
- rowPinning?: RowPinningState;
77
- /** Callback when row pinning changes */
78
- onRowPinningChange?: (pinning: RowPinningState) => void;
79
- /** Controlled grouping state */
80
- grouping?: GroupingState;
81
- /** Callback when grouping changes */
82
- onGroupingChange?: (grouping: GroupingState) => void;
83
- /** Controlled expanded state */
84
120
  expanded?: ExpandedState;
85
- /** Callback when expanded changes */
86
121
  onExpandedChange?: (expanded: ExpandedState) => void;
87
- /** Additional class name for the table container */
122
+ }
123
+ /**
124
+ * Core DataTable behavior hook.
125
+ *
126
+ * Owns the TanStack Table instance, feature enablement, and
127
+ * controlled/uncontrolled state orchestration. Return the table instance for
128
+ * consumers to pass into `DataTable`, `DataTablePagination`,
129
+ * `DataTableSearch`, etc.
130
+ *
131
+ * @example
132
+ * const table = useDataTable({
133
+ * columns,
134
+ * data,
135
+ * enableSorting: true,
136
+ * enablePagination: true,
137
+ * pageSize: 25,
138
+ * });
139
+ *
140
+ * return <DataTable table={table} dataHook="locations-table" />;
141
+ */
142
+ export declare function useDataTable<TData>(options: UseDataTableOptions<TData>): TanStackTable<TData>;
143
+ /**
144
+ * Props for `DataTable`.
145
+ *
146
+ * `DataTable` is the generic rendering layer for a DataTable. It takes an
147
+ * already-constructed TanStack Table instance (typically from
148
+ * `useDataTable`) and renders the primitives. It is purposefully
149
+ * rendering-focused — wire toolbars, pagination, and search components
150
+ * outside of it via composition.
151
+ */
152
+ export interface DataTableProps<TData> {
153
+ /** TanStack Table instance (usually returned from `useDataTable`). */
154
+ table: TanStackTable<TData>;
155
+ /** Data hook for automated testing (REQUIRED). */
156
+ dataHook: string;
157
+ /** Analytics element identifier. */
158
+ trackingEl?: string;
159
+ /** Analytics label. */
160
+ trackingLabel?: string;
161
+ /** Show skeleton rows instead of data while loading async data. */
162
+ isLoading?: boolean;
163
+ /** Number of skeleton rows when loading. Falls back to the table's page size, then 10. */
164
+ skeletonRowCount?: number;
165
+ /** Empty state message. @default "No results." */
166
+ noResultsMessage?: string;
167
+ /**
168
+ * Pin the `<thead>` to the top of the scroll container so column headers
169
+ * remain visible while scrolling. The header receives an opaque background
170
+ * (`bg-background`) to separate it from body rows.
171
+ * @default false
172
+ */
173
+ stickyHeader?: boolean;
174
+ /** Additional class name for the outer wrapper. */
88
175
  className?: string;
89
- /** Render function for custom table toolbar */
90
- renderToolbar?: (table: TanStackTable<TData>) => React.ReactNode;
91
- /** Render function for custom table footer (for summary rows, totals, etc.) */
92
- renderFooter?: (table: TanStackTable<TData>) => React.ReactNode;
93
- /** Render function for custom pagination controls */
94
- renderPagination?: (table: TanStackTable<TData>) => React.ReactNode;
176
+ /**
177
+ * Optional footer rendered inside the `<table>` element after `<tbody>`.
178
+ * Use for summary rows or totals. Pass a `<TableFooter>` with rows.
179
+ */
180
+ footer?: React.ReactNode;
181
+ }
182
+ /**
183
+ * Generic DataTable renderer.
184
+ *
185
+ * Renders header groups, body rows, loading skeletons, and empty state using
186
+ * the table primitives. Keep it focused on rendering — toolbars, search,
187
+ * pagination, etc. are composed around it.
188
+ *
189
+ * @example
190
+ * const table = useDataTable({ columns, data, enableSorting: true });
191
+ * return <DataTable table={table} dataHook="my-table" />;
192
+ */
193
+ export declare function DataTable<TData>({ table, dataHook, trackingEl, trackingLabel, isLoading, skeletonRowCount, noResultsMessage, stickyHeader, className, footer, }: DataTableProps<TData>): import("react/jsx-runtime").JSX.Element;
194
+ export declare namespace DataTable {
195
+ var displayName: string;
95
196
  }
96
197
  /**
97
- * DataTable component with forwardRef support for generic types
198
+ * Props for `VirtualizedDataTable`.
199
+ *
200
+ * Same contract as `DataTable` but renders only the visible rows using
201
+ * `@tanstack/react-virtual`. The outer wrapper becomes the scroll container,
202
+ * so a bounded `height` is required.
203
+ */
204
+ export interface VirtualizedDataTableProps<TData> extends DataTableProps<TData> {
205
+ /**
206
+ * Height of the scroll container in pixels. Required — virtualization
207
+ * needs a bounded viewport. Pass a CSS value via `className` instead
208
+ * if you need responsive heights (e.g. `className="h-[80vh]"`), and
209
+ * omit this prop.
210
+ */
211
+ height?: number;
212
+ /**
213
+ * Estimated height of a single row in pixels. The virtualizer uses this
214
+ * for initial layout before measuring real DOM nodes.
215
+ * @default 48
216
+ */
217
+ estimateSize?: number;
218
+ /**
219
+ * Number of rows to render outside the visible viewport. Higher values
220
+ * reduce blank-flash on fast scrolling at the cost of more DOM nodes.
221
+ * @default 5
222
+ */
223
+ overscan?: number;
224
+ }
225
+ /**
226
+ * Virtualized DataTable renderer for large datasets.
227
+ *
228
+ * Drop-in alternative to `DataTable` that renders only the rows visible
229
+ * in the scroll viewport (plus `overscan` extras). Uses
230
+ * `@tanstack/react-virtual` internally.
231
+ *
232
+ * @example
233
+ * const table = useDataTable({
234
+ * columns,
235
+ * data: largeDataset, // 10 000+ rows
236
+ * enableSorting: true,
237
+ * manualPagination: true, // skip client pagination
238
+ * });
239
+ *
240
+ * return (
241
+ * <VirtualizedDataTable
242
+ * table={table}
243
+ * dataHook="big-table"
244
+ * height={600}
245
+ * estimateSize={48}
246
+ * />
247
+ * );
98
248
  */
99
- declare const DataTable: <TData, TValue>(props: DataTableProps<TData, TValue> & {
100
- ref?: React.ForwardedRef<HTMLDivElement>;
101
- }) => React.ReactElement;
249
+ export declare function VirtualizedDataTable<TData>({ table, dataHook, trackingEl, trackingLabel, isLoading, skeletonRowCount, noResultsMessage, stickyHeader, className, footer, height, estimateSize, overscan, }: VirtualizedDataTableProps<TData>): import("react/jsx-runtime").JSX.Element;
250
+ export declare namespace VirtualizedDataTable {
251
+ var displayName: string;
252
+ }
102
253
  /**
103
- * DataTableColumnHeader - Sortable column header with sort indicator icons
104
- * Matches Figma TableHead/Button variant design
254
+ * Props for `DataTableColumnHeader` — a sortable column header with
255
+ * directional sort indicators. Matches the Figma TableHead/Button variant.
105
256
  */
106
- interface DataTableColumnHeaderProps<TData, TValue> extends React.HTMLAttributes<HTMLDivElement> {
257
+ export interface DataTableColumnHeaderProps<TData, TValue> extends React.HTMLAttributes<HTMLDivElement> {
258
+ /** TanStack column instance (from the `header` render slot). */
107
259
  column: Column<TData, TValue>;
260
+ /** Header label. */
108
261
  title: string;
262
+ /** Data hook for automated testing. */
109
263
  dataHook?: string;
110
- /** Tracking element identifier for analytics */
264
+ /** Analytics element identifier. */
111
265
  trackingEl?: string;
112
- /** Tracking label for analytics context */
266
+ /** Analytics label. */
113
267
  trackingLabel?: string;
114
- /** Align header content - matches cell alignment */
268
+ /** Alignment — should match the cell's alignment. @default "left" */
115
269
  align?: "left" | "center" | "right";
116
270
  }
117
- declare function DataTableColumnHeader<TData, TValue>({ column, title, className, dataHook, trackingEl, trackingLabel, align, }: DataTableColumnHeaderProps<TData, TValue>): import("react/jsx-runtime").JSX.Element;
118
- declare namespace DataTableColumnHeader {
271
+ /**
272
+ * Sortable column header with sort indicator icons.
273
+ *
274
+ * Falls back to a non-interactive label when the column is not sortable.
275
+ * Otherwise renders a ghost button that toggles sort on click, with an
276
+ * accessible label describing the current sort state.
277
+ */
278
+ export declare function DataTableColumnHeader<TData, TValue>({ column, title, className, dataHook, trackingEl, trackingLabel, align, }: DataTableColumnHeaderProps<TData, TValue>): import("react/jsx-runtime").JSX.Element;
279
+ export declare namespace DataTableColumnHeader {
119
280
  var displayName: string;
120
281
  }
121
282
  /**
122
- * DataTableRowActions - Action cell with ellipsis dropdown menu
123
- * Matches Figma TableCell/Action variant design
283
+ * Props for `DataTableRowActions` — the standard row ellipsis actions menu.
124
284
  */
125
- interface DataTableRowActionsProps<TData> {
285
+ export interface DataTableRowActionsProps<TData> {
286
+ /** TanStack row instance (from the `cell` render slot). */
126
287
  row: Row<TData>;
288
+ /** Data hook for automated testing. */
127
289
  dataHook?: string;
128
- /** Tracking element identifier for analytics */
290
+ /** Analytics element identifier. */
129
291
  trackingEl?: string;
130
- /** Tracking label for analytics context */
292
+ /** Analytics label. */
131
293
  trackingLabel?: string;
132
- /** Accessible label for the actions button */
294
+ /** Accessible label for the trigger. @default "Open row actions menu" */
133
295
  ariaLabel?: string;
296
+ /** `DropdownMenuItem`s to render inside the menu. */
134
297
  children?: React.ReactNode;
135
298
  }
136
- declare function DataTableRowActions<TData>({ row, dataHook, trackingEl, trackingLabel, ariaLabel, children, }: DataTableRowActionsProps<TData>): import("react/jsx-runtime").JSX.Element;
137
- declare namespace DataTableRowActions {
299
+ /**
300
+ * Row-level ellipsis dropdown menu. Pass `DropdownMenuItem`s as children.
301
+ */
302
+ export declare function DataTableRowActions<TData>({ row, dataHook, trackingEl, trackingLabel, ariaLabel, children, }: DataTableRowActionsProps<TData>): import("react/jsx-runtime").JSX.Element;
303
+ export declare namespace DataTableRowActions {
138
304
  var displayName: string;
139
305
  }
140
306
  /**
141
- * DataTableToolbar - Flexible toolbar container for DataTable
142
- * Provides a two-column layout with left and right content areas
143
- *
144
- * @example
145
- * // Simple usage with just children on the right
146
- * <DataTableToolbar dataHook="toolbar">
147
- * <DataTablePagination table={table} />
148
- * </DataTableToolbar>
149
- *
150
- * @example
151
- * // With search and filters on left, pagination on right
152
- * <DataTableToolbar dataHook="toolbar">
153
- * <DataTableToolbar.Left>
154
- * <DataTableSearch table={table} dataHook="search" column="name" />
155
- * <Button>Filters</Button>
156
- * </DataTableToolbar.Left>
157
- * <DataTableToolbar.Right>
158
- * <DataTablePagination table={table} />
159
- * </DataTableToolbar.Right>
160
- * </DataTableToolbar>
307
+ * Props for the root `DataTableToolbar` container.
161
308
  */
162
- interface DataTableToolbarProps {
163
- /** Data hook for automated testing */
309
+ export interface DataTableToolbarProps {
310
+ /** Data hook for automated testing. */
164
311
  dataHook?: string;
165
- /** Tracking element identifier for analytics */
312
+ /** Analytics element identifier. */
166
313
  trackingEl?: string;
167
- /** Tracking label for analytics context */
314
+ /** Analytics label. */
168
315
  trackingLabel?: string;
169
- /** Additional class name for styling */
316
+ /** Additional class name. */
170
317
  className?: string;
171
- /** Content to render in the toolbar */
318
+ /** Toolbar content — usually `<DataTableToolbarLeft>` / `<DataTableToolbarRight>`. */
172
319
  children?: React.ReactNode;
173
320
  }
174
- declare function DataTableToolbar({ dataHook, trackingEl, trackingLabel, className, children, }: DataTableToolbarProps): import("react/jsx-runtime").JSX.Element;
175
- declare namespace DataTableToolbar {
176
- var Left: typeof DataTableToolbarLeft;
177
- var Right: typeof DataTableToolbarRight;
178
- var displayName: string;
179
- }
180
321
  /**
181
- * DataTableToolbar.Left - Left section of the toolbar
182
- * Use for search, filters, and other primary actions
322
+ * Props for `DataTableToolbarLeft`.
183
323
  */
184
- interface DataTableToolbarLeftProps {
185
- /** Data hook for automated testing */
324
+ export interface DataTableToolbarLeftProps {
325
+ /** Data hook for automated testing. */
186
326
  dataHook?: string;
187
- /** Tracking element identifier for analytics */
327
+ /** Analytics element identifier. */
188
328
  trackingEl?: string;
189
- /** Tracking label for analytics context */
329
+ /** Analytics label. */
190
330
  trackingLabel?: string;
191
- /** Additional class name for styling */
331
+ /** Additional class name. */
192
332
  className?: string;
193
- /** Content to render on the left side */
333
+ /** Content to render on the left side. */
194
334
  children?: React.ReactNode;
195
335
  }
196
- declare function DataTableToolbarLeft({ dataHook, trackingEl, trackingLabel, className, children, }: DataTableToolbarLeftProps): import("react/jsx-runtime").JSX.Element;
197
- declare namespace DataTableToolbarLeft {
198
- var displayName: string;
199
- }
200
336
  /**
201
- * DataTableToolbar.Right - Right section of the toolbar
202
- * Use for pagination, view options, and secondary actions
337
+ * Props for `DataTableToolbarRight`.
203
338
  */
204
- interface DataTableToolbarRightProps {
205
- /** Data hook for automated testing */
339
+ export interface DataTableToolbarRightProps {
340
+ /** Data hook for automated testing. */
206
341
  dataHook?: string;
207
- /** Tracking element identifier for analytics */
342
+ /** Analytics element identifier. */
208
343
  trackingEl?: string;
209
- /** Tracking label for analytics context */
344
+ /** Analytics label. */
210
345
  trackingLabel?: string;
211
- /** Additional class name for styling */
346
+ /** Additional class name. */
212
347
  className?: string;
213
- /** Content to render on the right side */
348
+ /** Content to render on the right side. */
214
349
  children?: React.ReactNode;
215
350
  }
216
- declare function DataTableToolbarRight({ dataHook, trackingEl, trackingLabel, className, children, }: DataTableToolbarRightProps): import("react/jsx-runtime").JSX.Element;
217
- declare namespace DataTableToolbarRight {
351
+ export declare function DataTableToolbarLeft({ dataHook, trackingEl, trackingLabel, className, children, }: DataTableToolbarLeftProps): import("react/jsx-runtime").JSX.Element;
352
+ export declare namespace DataTableToolbarLeft {
353
+ var displayName: string;
354
+ }
355
+ export declare function DataTableToolbarRight({ dataHook, trackingEl, trackingLabel, className, children, }: DataTableToolbarRightProps): import("react/jsx-runtime").JSX.Element;
356
+ export declare namespace DataTableToolbarRight {
218
357
  var displayName: string;
219
358
  }
220
359
  /**
221
- * DataTableSearch - Search input for filtering table data
222
- * Can filter a specific column or use global filtering
360
+ * Flexible two-column toolbar for composing DataTable UIs.
361
+ *
362
+ * @example
363
+ * <DataTableToolbar dataHook="toolbar">
364
+ * <DataTableToolbarLeft>
365
+ * <DataTableSearch table={table} dataHook="search" />
366
+ * </DataTableToolbarLeft>
367
+ * <DataTableToolbarRight>
368
+ * <DataTablePagination table={table} dataHook="pagination" />
369
+ * </DataTableToolbarRight>
370
+ * </DataTableToolbar>
371
+ */
372
+ export declare function DataTableToolbar({ dataHook, trackingEl, trackingLabel, className, children, }: DataTableToolbarProps): import("react/jsx-runtime").JSX.Element;
373
+ export declare namespace DataTableToolbar {
374
+ var displayName: string;
375
+ }
376
+ /**
377
+ * Props for `DataTableSearch`.
378
+ *
379
+ * Extends `InputGroup` props — pass `className`, `size`, `error`, etc. to
380
+ * style the input. No custom styling is applied; appearance matches a
381
+ * default `InputGroup`.
223
382
  */
224
- interface DataTableSearchProps<TData> {
225
- /** TanStack Table instance */
383
+ export interface DataTableSearchProps<TData> extends Omit<React.ComponentPropsWithoutRef<typeof InputGroup>, "children" | "onChange"> {
384
+ /** TanStack Table instance. */
226
385
  table: TanStackTable<TData>;
227
- /** Data hook for automated testing (REQUIRED) */
228
- dataHook: string;
229
- /** Tracking element identifier for analytics */
230
- trackingEl?: string;
231
- /** Tracking label for analytics context */
232
- trackingLabel?: string;
233
- /** Accessible label for the search input (defaults to "Search table") */
386
+ /** Accessible label for the input. @default "Search table" */
234
387
  ariaLabel?: string;
235
- /** Placeholder text for the search input */
388
+ /** Input placeholder. @default "Search..." */
236
389
  placeholder?: string;
237
- /** Column ID to filter. If not provided, uses global filter. */
238
- column?: string;
239
- /** Width of the search input (e.g., "180px", "200px") */
240
- width?: string;
241
- /** Additional class name for styling */
242
- className?: string;
243
390
  }
244
- declare function DataTableSearch<TData>({ table, dataHook, trackingEl, trackingLabel, ariaLabel, placeholder, column, width, className, }: DataTableSearchProps<TData>): import("react/jsx-runtime").JSX.Element;
245
- declare namespace DataTableSearch {
391
+ /**
392
+ * Search input for filtering DataTable rows.
393
+ *
394
+ * Composes `InputGroup` + `InputGroupInput` + `InputGroupAddon` with a
395
+ * search icon. Inherits all `InputGroup` styling — pass `className` to
396
+ * customize width or shape.
397
+ *
398
+ * Uses the table's global filter (requires `enableGlobalFiltering` on the hook).
399
+ */
400
+ export declare function DataTableSearch<TData>({ table, ariaLabel, placeholder, ...inputGroupProps }: DataTableSearchProps<TData>): import("react/jsx-runtime").JSX.Element;
401
+ export declare namespace DataTableSearch {
246
402
  var displayName: string;
247
403
  }
248
404
  /**
249
- * DataTablePagination - Pagination controls with row count info
250
- * Uses the Pagination component for consistent styling
405
+ * Props for `DataTablePagination`.
406
+ *
407
+ * All pagination state is derived from the TanStack Table instance.
408
+ * Configure pagination behavior on `useDataTable`:
409
+ * - Client-side: `enablePagination: true`
410
+ * - Server-side: `manualPagination: true` + `rowCount` (or `pageCount`)
411
+ * + controlled `pagination` / `onPaginationChange`
251
412
  */
252
- interface DataTablePaginationProps<TData> {
413
+ export interface DataTablePaginationProps<TData> {
414
+ /** TanStack Table instance. */
253
415
  table: TanStackTable<TData>;
254
- /** Data hook for automated testing (REQUIRED) */
416
+ /** Data hook for automated testing (REQUIRED). */
255
417
  dataHook: string;
256
- /** Tracking element identifier for analytics */
418
+ /** Analytics element identifier. */
257
419
  trackingEl?: string;
258
- /** Tracking label for analytics context */
420
+ /** Analytics label. */
259
421
  trackingLabel?: string;
260
- /** Additional class name for styling */
422
+ /** Additional class name. */
261
423
  className?: string;
262
- /** Accessible label for the pagination navigation (for unique landmark identification) */
424
+ /** Accessible label for the nav landmark. @default "Table pagination" */
263
425
  ariaLabel?: string;
264
426
  }
265
- declare function DataTablePagination<TData>({ table, dataHook, trackingEl, trackingLabel, className, ariaLabel, }: DataTablePaginationProps<TData>): import("react/jsx-runtime").JSX.Element;
266
- declare namespace DataTablePagination {
427
+ /**
428
+ * Pagination controls with row count info for a DataTable.
429
+ *
430
+ * Displays "start–end of total" plus previous/next/page links. Derives all
431
+ * state from the TanStack Table instance — uses `table.getRowCount()`,
432
+ * `table.getPageCount()`, `table.getCanPreviousPage()`,
433
+ * `table.getCanNextPage()`, and `table.setPageIndex()`.
434
+ *
435
+ * Works transparently in both client-side and server-side (manual) modes
436
+ * because TanStack Table handles the distinction internally when
437
+ * `manualPagination` + `rowCount` are set on the hook.
438
+ */
439
+ export declare function DataTablePagination<TData>({ table, dataHook, trackingEl, trackingLabel, className, ariaLabel, }: DataTablePaginationProps<TData>): import("react/jsx-runtime").JSX.Element;
440
+ export declare namespace DataTablePagination {
267
441
  var displayName: string;
268
442
  }
269
443
  /**
270
- * DataTableSelectAllCheckbox - Header checkbox for selecting all rows
271
- * Matches Figma TableHead/Checkbox variant
444
+ * Props for `DataTableSelectAllCheckbox` — the header checkbox that selects
445
+ * all rows on the current page.
272
446
  */
273
- interface DataTableSelectAllCheckboxProps<TData> {
447
+ export interface DataTableSelectAllCheckboxProps<TData> {
448
+ /** TanStack Table instance. */
274
449
  table: TanStackTable<TData>;
450
+ /** Data hook for automated testing. @default "select-all-checkbox" */
275
451
  dataHook?: string;
276
- /** Tracking element identifier for analytics */
452
+ /** Analytics element identifier. */
277
453
  trackingEl?: string;
278
- /** Tracking label for analytics context */
454
+ /** Analytics label. */
279
455
  trackingLabel?: string;
280
456
  }
281
- declare function DataTableSelectAllCheckbox<TData>({ table, dataHook, trackingEl, trackingLabel, }: DataTableSelectAllCheckboxProps<TData>): import("react/jsx-runtime").JSX.Element;
282
- declare namespace DataTableSelectAllCheckbox {
457
+ /**
458
+ * Header checkbox for selecting all visible page rows. Renders as
459
+ * indeterminate when some (but not all) rows are selected.
460
+ */
461
+ export declare function DataTableSelectAllCheckbox<TData>({ table, dataHook, trackingEl, trackingLabel, }: DataTableSelectAllCheckboxProps<TData>): import("react/jsx-runtime").JSX.Element;
462
+ export declare namespace DataTableSelectAllCheckbox {
283
463
  var displayName: string;
284
464
  }
285
465
  /**
286
- * DataTableSelectRowCheckbox - Row checkbox for selecting individual rows
287
- * Matches Figma TableCell/Checkbox variant
466
+ * Props for `DataTableSelectRowCheckbox`.
288
467
  */
289
- interface DataTableSelectRowCheckboxProps<TData> {
468
+ export interface DataTableSelectRowCheckboxProps<TData> {
469
+ /** TanStack row instance. */
290
470
  row: Row<TData>;
471
+ /** Data hook for automated testing. @default `select-row-{row.id}` */
291
472
  dataHook?: string;
292
- /** Tracking element identifier for analytics */
473
+ /** Analytics element identifier. */
293
474
  trackingEl?: string;
294
- /** Tracking label for analytics context */
475
+ /** Analytics label. */
295
476
  trackingLabel?: string;
296
477
  }
297
- declare function DataTableSelectRowCheckbox<TData>({ row, dataHook, trackingEl, trackingLabel, }: DataTableSelectRowCheckboxProps<TData>): import("react/jsx-runtime").JSX.Element;
298
- declare namespace DataTableSelectRowCheckbox {
478
+ /**
479
+ * Row-level selection checkbox. Disabled when the row cannot be selected.
480
+ */
481
+ export declare function DataTableSelectRowCheckbox<TData>({ row, dataHook, trackingEl, trackingLabel, }: DataTableSelectRowCheckboxProps<TData>): import("react/jsx-runtime").JSX.Element;
482
+ export declare namespace DataTableSelectRowCheckbox {
299
483
  var displayName: string;
300
484
  }
301
- export { DataTable, DataTableColumnHeader, DataTableRowActions, DataTableToolbar, DataTableSearch, DataTablePagination, DataTableSelectAllCheckbox, DataTableSelectRowCheckbox, };
302
- export type { DataTableProps, DataTableColumnHeaderProps, DataTableRowActionsProps, DataTableToolbarProps, DataTableToolbarLeftProps, DataTableToolbarRightProps, DataTableSearchProps, DataTablePaginationProps, DataTableSelectAllCheckboxProps, DataTableSelectRowCheckboxProps, };
485
+ export { flexRender, createColumnHelper };
486
+ export type { Column, ColumnDef, ExpandedState, PaginationState, Row, RowSelectionState, SortingState, TanStackTable, };
303
487
  //# sourceMappingURL=data-table.d.ts.map