@akshar-technosoft/ui 1.3.1 → 1.3.3

package/dist/components/data/data-table/data-table-types.d.cts

@@ -0,0 +1,536 @@
+import { ColumnDef, Table, Row } from '@tanstack/react-table';
+import { LucideIcon } from 'lucide-react';
+import { PersistGroupId, PersistSlotFor, PersistConfig } from './data-table-persist.cjs';
+import { TableExportView } from './data-table-export.cjs';
+
+type Paths<T, Prefix extends string = ''> = T extends object ? {
+    [K in keyof T]: K extends string ? T[K] extends object ? Paths<T[K], `${Prefix}${K}.`> | `${Prefix}${K}` : `${Prefix}${K}` : never;
+}[keyof T] : never;
+type NumericKeys<T> = {
+    [K in keyof T]: T[K] extends number ? K : never;
+}[keyof T];
+type AggregationConfigMap<TData> = {
+    [K in NumericKeys<TData>]?: AggregationConfig<TData>;
+} & {
+    [key: string]: AggregationConfig<TData> | undefined;
+};
+type AggregationFunction = 'sum' | 'average' | 'min' | 'max' | 'count' | 'unique' | 'median';
+type AggregationConfig<TData> = {
+    enabled: boolean;
+    functions?: AggregationFunction[];
+    format?: (value: any, func: AggregationFunction) => string;
+    accessor?: (row: TData) => number | null;
+};
+/** Fields shared by every filter control, independent of how it locates its value. `G` narrows
+ *  `shared` to one persist group's own slots — see `DataTableProps`'s `G` type param for how a
+ *  real value gets pinned instead of the default (every group's slots, undiscriminated). */
+type FilterControlConfig<G extends PersistGroupId | undefined = undefined> = {
+    /** Input placeholder and the filter's display label (also used on chips and the grouped picker). */
+    placeholder: string;
+    /**
+     * Which control to render and how the value is entered. Set it to match the field's shape so the
+     * user gets the right input:
+     *   `'text'` (the default) is a free text box, matched as a case insensitive contains.
+     *   `'select'` is a dropdown of fixed choices; it requires `options`, and the picked value is
+     *   matched as given (use it for status, yes/no, category style fields).
+     *   `'date'` is a single date picker; `'daterange'` is a from/to range picker. Both accept `dateFormat`.
+     *   `'number'` is a numeric input.
+     * @default "text"
+     */
+    type?: "text" | "select" | "date" | "daterange" | "number";
+    /** Choices for `type: "select"`. Each `value` is what the filter matches; `label` is what the
+     *  user sees. Required when `type` is `"select"`; ignored otherwise. */
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    /** Tailwind width class for the control wrapper (e.g. `"max-w-[150px]"`). */
+    width?: string;
+    /** Leading icon inside the control. */
+    icon?: LucideIcon;
+    /**
+     * Run this filter on the server instead of the local data. When set, the filter's value is NOT
+     * applied to the in-memory rows; instead it is collected and handed to `onExternalSearch(values)`
+     * so the parent can re-query the API. The call fires automatically at the control's natural commit
+     * point: a `select` on pick, a `date`/`daterange` on Apply, and a `text` box after a short debounce.
+     */
+    externalSearch?: boolean;
+    /** date-fns format string for displaying the selected date(s), e.g. "dd MMM yyyy". */
+    dateFormat?: string;
+    /**
+     * Where this filter's control is placed inside the toolbar. Both variants require
+     * `settings.showToolbar: true`, because every filter lives in the toolbar; with the toolbar off no
+     * filter renders at all, whatever its placement.
+     *
+     * `'bar'` (the default) sits inline on the toolbar's left row and is always visible. Use it for the
+     * few primary filters you combine constantly (for example product and category), so they stay side
+     * by side.
+     *
+     * `'menu'` keeps the control off the bar: it becomes an option in the global search's field
+     * picker (which appears automatically when `enableGlobalFilter` is on and any `'menu'` filter
+     * exists), and while it holds a value it shows as a removable chip on the bar. Use it so many
+     * filters don't fill the toolbar with boxes.
+     *
+     * @default 'bar'
+     */
+    placement?: "bar" | "menu";
+    /**
+     * Share this filter's VALUE across every page whose table has the same `persist.group`, under
+     * this slot name (e.g. `shared: "party"` — search a party on one page, the next page in the
+     * group opens already filtered to it). The slot stores only the value, so pages can bind it to
+     * different filter keys, or even to an `externalSearch` filter. Requires `persist.group`.
+     */
+    shared?: PersistSlotFor<G>;
+    /**
+     * Set false to exclude this one filter from persistence (scan boxes, one-shot searches) while
+     * the rest of the table persists. Inert without the table-level `persist` prop. @default true
+     */
+    persist?: boolean;
+};
+/**
+ * A filter bound to a real data field by its path. Use this form (the common one) whenever the value
+ * you filter on is a plain field on the row, flat or nested.
+ *
+ * `key` is a dot path into the row, validated against `T`, and doubles as the filter's identity. How
+ * it filters depends on whether a column already owns that path:
+ *   If a visible column has the same `accessorKey`, the filter drives that column with TanStack's
+ *   built in case insensitive contains match. This is the normal, zero setup case.
+ *   If no column owns the path (the field is only shown inside another cell, for example a "SKU and
+ *   Category" cell that prints three fields), the table auto generates a hidden, filter only column
+ *   for it so the same contains match still works. You do not touch the `columns` array.
+ *
+ * Reach for {@link CustomFilterConfig} instead only when the match is not a plain contains on one
+ * field, for example matching inside an array of objects or across several fields at once.
+ */
+type PathFilterConfig<T, G extends PersistGroupId | undefined = undefined> = FilterControlConfig<G> & {
+    /** Dot path into the row (validated against `T`). Serves as both the value source and the id. */
+    key: Paths<T>;
+    id?: never;
+    filterFn?: never;
+};
+/**
+ * A filter that owns its matching logic. Use this form when the value is not a plain field, for
+ * example a cell holding an array of objects, or when one control should match across several fields.
+ *
+ * You provide `filterFn(row, value)`, which receives the whole row (so it can read any field or
+ * array) and returns whether the row passes. The table wires it to an auto generated hidden, filter
+ * only column, so it runs inside TanStack's normal filtering and AND combines with every other
+ * filter; you never touch the `columns` array. `id` is any unique string that identifies this filter
+ * (it does not need to be a real field, because `filterFn` reads the row itself).
+ *
+ * @example
+ * // Match if ANY lot in the row's array has a matching number, and (separately) if any is urgent.
+ * const filters = [
+ *   { id: "lotNo", type: "text", placeholder: "Lot No",
+ *     filterFn: (row, v) => row.lots.some(l => String(l.lotNo).toLowerCase().includes(String(v).toLowerCase())) },
+ *   { id: "urgentOnly", type: "select", placeholder: "Urgent", options: [{ label: "Urgent", value: "1" }],
+ *     filterFn: (row, v) => !v || row.lots.some(l => l.isUrgent) },
+ * ];
+ */
+type CustomFilterConfig<T, G extends PersistGroupId | undefined = undefined> = FilterControlConfig<G> & {
+    /** Any unique string identifying this filter. Not required to be a real field, since `filterFn`
+     *  reads the row directly. */
+    id: string;
+    /** Predicate deciding whether a row passes. Receives the full row and the current filter value. */
+    filterFn: (row: T, value: any) => boolean;
+    key?: never;
+};
+/**
+ * One toolbar filter control. Pick the form by how the value is located:
+ *   {@link PathFilterConfig} — pass `key` (a real dot path). The common case: flat or nested fields.
+ *   {@link CustomFilterConfig} — pass `id` + `filterFn`. For arrays of objects or multi field matches.
+ * Either way the filtering runs through TanStack's model and AND combines; you never edit `columns`.
+ *
+ * `G` — the table's persist group, for narrowing `shared`'s autocomplete to that one group's
+ * slots. Left to its default almost everywhere; see `DataTableProps` for where it's actually set.
+ */
+type FilterConfig<T, G extends PersistGroupId | undefined = undefined> = PathFilterConfig<T, G> | CustomFilterConfig<T, G>;
+type PaginationConfig = {
+    /** Rows per page initially. @default 10 */
+    pageSize?: number;
+    /** Options in the "Rows" selector. `-1` renders "All". Pass `[]` to hide the selector.
+     *  @default [10, 25, 50, 100, -1] */
+    pageSizeOptions?: number[];
+    /** Show the "Showing X to Y of Z" range text. @default true */
+    showInfo?: boolean;
+    /** Show numbered page buttons (with ellipsis window); otherwise just prev/next. @default false */
+    showPageNumbers?: boolean;
+};
+/**
+ * Feature and presentation toggles for the table. Every field is optional and its default is noted.
+ * Many flags are inert unless a "master" flag is also on, and that coupling is the usual reason a
+ * setting appears to do nothing. The master relationships:
+ *
+ *   `showToolbar` owns everything drawn in the toolbar row (global search, the whole `filters` UI, the
+ *   Columns menu, the Aggregations menu, Export, Refresh, the bulk pin actions). The per column sort
+ *   and pin menus are drawn in the header instead, so they keep working when `showToolbar` is off.
+ *
+ *   `enableFiltering` owns the filter engine. `enableGlobalFilter` can still render its box but will
+ *   not remove any rows while `enableFiltering` is off.
+ *
+ *   `enableRowSelection` owns the select column. `selectionMode`, `showCheckbox`,
+ *   `enableHeaderCheckbox` and `fixedCheckboxColumn` are all inert without it.
+ *
+ *   `enableColumnPinning` owns pinning, which `fixedCheckboxColumn` depends on.
+ *
+ *   The global search's field picker appears automatically when `enableGlobalFilter` is on and
+ *   any filter has `placement: 'menu'` — there is no separate flag for it.
+ */
+type TableSettings = {
+    /**
+     * Render the column header row. Turning it off also removes sorting, the pin menu and resize
+     * handles (they live in the header) even when their flags are on. Suited to compact read-only
+     * lists.
+     * @default true
+     */
+    showHeader?: boolean;
+    /**
+     * Allow sorting. Clicking a sortable header cycles asc → desc → clear, and each header cell's "⋯"
+     * menu offers the same actions explicitly; an arrow at the header's right edge shows the active
+     * direction. Clicks on interactive elements inside custom JSX headers do not sort. The serial
+     * "No." column sorts on its display index, so sorting it is rarely meaningful.
+     * @default true
+     */
+    enableSorting?: boolean;
+    /**
+     * Render the toolbar row above the table. This is the largest master switch: with it off you lose
+     * the global search, the entire `filters` UI (both bar filters and the "Filters" menu), the Columns
+     * menu, the Aggregations menu, Export, Refresh and the bulk pin actions, because all of them are
+     * hosted here. The header's own per column menus are unaffected. Enable it for data heavy screens; leave it off for display-only tables.
+     * @default false
+     */
+    showToolbar?: boolean;
+    /**
+     * Placement of the toolbar relative to the card. `'default'` renders it outside and above the card.
+     * `'above-header'` and `'below-header'` render it inside the card as a sticky band that stacks with
+     * the optional `header` prop; the component measures these bands at runtime to compute the header's
+     * sticky offset. Only relevant while `toolbar` is on.
+     * @default 'default'
+     */
+    toolbarPosition?: 'above-header' | 'below-header' | 'default';
+    /**
+     * Install the filter row model. This is the engine both column filters and the global search run
+     * on, so it is the real on and off for filtering: with it off a search box can render but no rows
+     * are removed. Aggregations compute over the filtered rows, so they see the full data set when this
+     * is off.
+     * @default true
+     */
+    enableFiltering?: boolean;
+    /**
+     * Show the global search box. It matches a row's accessor columns only, with a case insensitive
+     * contains test, so a column rendered purely through `cell` with no `accessorKey` or `accessorFn`
+     * is invisible to it; give such a column an `accessorFn` to make it searchable. Needs `showToolbar` to
+     * appear and `enableFiltering` to actually narrow rows.
+     * @default true
+     */
+    enableGlobalFilter?: boolean;
+    /**
+     * Show the "Columns" menu that toggles column visibility. Columns marked `enableHiding: false` (the
+     * serial and select helpers) never appear in it, and grouped columns are listed under their group
+     * heading. It is part of the toolbar, so it needs `showToolbar` to be visible.
+     * @default true
+     */
+    enableColumnVisibility?: boolean;
+    /**
+     * Add the leading selection column and turn on row selection. Selection is enforced at the table
+     * level against `isRowSelectable`, so those rows cannot be caught even by select all, and
+     * `onRowSelectionChange` reports only genuinely selectable rows. Master for the whole
+     * selection group below.
+     * @default true
+     */
+    enableRowSelection?: boolean;
+    /**
+     * Allow the user to drag column widths. Resizing runs live and the handles sit on the right edge of
+     * each header cell, so `showHeader: false` removes the ability to resize. A pinned column is locked
+     * to its size, so if you also pin, resize the column first and pin afterwards.
+     * @default false
+     */
+    enableColumnResizing?: boolean;
+    /**
+     * Master switch for sticky pinned columns. The serial and select columns are always pinned left and
+     * re-pinned on every change so they cannot drift. Users pin one column from the header's "⋯" menu
+     * (works without the toolbar) or in bulk from the toolbar's settings menu. A pinned column is
+     * clamped to its rendered width so its content cannot push it wider and break the sticky offsets.
+     * @default true
+     */
+    enableColumnPinning?: boolean;
+    /**
+     * The header's select-all checkbox. Set false to grey it out while keeping per-row checkboxes
+     * usable (select-all too costly/dangerous, manual multi-select still wanted). Only meaningful
+     * in `'multiple'` mode.
+     * @default true
+     */
+    enableHeaderCheckbox?: boolean;
+    /**
+     * Lock the select column in place by hiding its pin menu so users cannot move or unpin it. Needs
+     * `enableRowSelection` and `enableColumnPinning`.
+     * @remarks Half wired today: `onColumnPinningChange` re-pins the select column to the left on every
+     * change regardless of this flag, so setting it `false` only exposes a pin menu whose Unpin has no
+     * effect.
+     * @default true
+     */
+    fixedCheckboxColumn?: boolean;
+    /**
+     * Show the leading "No." column. It prints the row's position in the current view (`index + 1`), so
+     * it renumbers as you sort, filter or page and is not a stable record id. When any aggregation is
+     * enabled its footer cell shows the total row count.
+     * @default true
+     */
+    showSerialNumbers?: boolean;
+    /**
+     * Zebra stripe alternate rows for readability. The stripe follows a row's position on the current
+     * page, so the pattern stays consistent as you page through the data.
+     * @default true
+     */
+    striped?: boolean;
+    /**
+     * Highlight the row under the cursor. Selected rows keep a stronger background of their own, so the
+     * hover and selected states stay distinguishable.
+     * @default true
+     */
+    hoverable?: boolean;
+    /**
+     * Compact density. Tightens the vertical padding across header, body and footer cells so more rows
+     * fit on screen. Turn it off for a roomier, more touch friendly layout.
+     * @default true
+     */
+    compact?: boolean;
+    /**
+     * Draw cell separators. Interior columns get a right border, while the last column and the last
+     * unpinned column before a right pinned group intentionally drop theirs, so the border never doubles
+     * against a pinned column's sticky separator.
+     * @default true
+     */
+    bordered?: boolean;
+    /**
+     * Let the table card flex to fill its parent's height, which only takes effect inside a parent that
+     * has a bounded height. Pair it with `maxHeight` so the body scrolls while the header and footer
+     * stay sticky. Use it for full page tables.
+     * @default false
+     */
+    fullHeight?: boolean;
+    /**
+     * Selection style. `'multiple'` shows checkboxes plus a select all header checkbox. `'single'` shows
+     * a radio, makes the whole row clickable, and selecting a row clears any previous selection. Needs
+     * `enableRowSelection`.
+     * @default "multiple"
+     */
+    selectionMode?: "single" | "multiple";
+    /**
+     * In `'single'` mode, whether to draw the radio control at all. With it `false` the radio is hidden
+     * but the row stays clickable, which suits designs that select by clicking the row itself. No effect
+     * in `'multiple'` mode.
+     * @default true
+     */
+    showCheckbox?: boolean;
+    /**
+     * Show removable chips on the toolbar for applied `placement: 'menu'` filters, so collapsed
+     * filters stay visible while active. Turn off if the bar gets cluttered — active menu filters
+     * are then only visible through their control in the search field picker.
+     * @default true
+     */
+    showFilterChips?: boolean;
+    /**
+     * Label on the global search's field picker while "all fields" is selected. The picker itself
+     * appears automatically when `enableGlobalFilter` is on and at least one filter has
+     * `placement: 'menu'`. @default "Global"
+     */
+    groupedFilterLabel?: string;
+};
+type ColumnFooter<TData> = {
+    content?: React.ReactNode | ((table: Table<TData>) => React.ReactNode);
+    align?: 'left' | 'center' | 'right';
+    className?: string;
+};
+type TableHeaderProps = {
+    content: React.ReactNode;
+    align?: 'left' | 'center' | 'right';
+    className?: string;
+    showOnEmpty?: boolean;
+};
+type GroupColumnDef<TData> = ColumnDef<TData> & {
+    columns?: GroupColumnDef<TData>[];
+    enablePinning?: boolean;
+    /**
+     * Per-column override for `settings.enableColumnVisibility` — hide capability, not visibility
+     * state. `false` keeps this column out of the toolbar's Columns menu and the header `⋯` menu's
+     * Hide entry entirely, even while table-wide visibility toggling stays on for the rest. Same
+     * effect as TanStack's native `enableHiding`, named to match the table-level setting — set
+     * either one, not both (an explicit `enableHiding` wins if both are present).
+     */
+    enableColumnVisibility?: boolean;
+    /**
+     * Set `false` to hide the header's "⋯" options menu on this column entirely, regardless of
+     * whether sorting/pinning/hiding would otherwise make it appear. Use this when a column
+     * shouldn't offer the menu at all (e.g. an actions column) rather than disabling sorting and
+     * pinning separately just to make the dots go away.
+     */
+    enableHeaderMenu?: boolean;
+    /**
+     * Reserve space on the right of the header for the sort chevron / "⋯" menu instead of letting
+     * them float as a hover-only overlay. The rest of the table intentionally keeps that area as a
+     * zero-width overlay so hovering never shifts layout — opt in here only for columns with a
+     * custom interactive `header` (e.g. a button of your own) that the overlay would otherwise sit
+     * on top of.
+     */
+    reserveMenuSpace?: boolean;
+    headerAlign?: 'left' | 'center' | 'right';
+    customFooter?: ColumnFooter<TData>;
+    /**
+     * Value this column contributes to an export (see `getTableExportView`). Without it the export
+     * uses the column's accessor value, which covers plain columns; provide it when the cell renders
+     * a JSX composite (several fields in one cell) so the export gets a flat printable value instead
+     * of losing the column, and on display-only columns (no accessor) that should still export.
+     * Return native types (number, Date…) so the writer can format cells properly.
+     * @example exportValue: (row) => `${row.RefNo} (${row.RefDate})`
+     */
+    exportValue?: (row: TData) => unknown;
+    /**
+     * Header text used in exports when `header` is JSX and therefore unprintable. A plain string
+     * `header` is used as-is and does not need this.
+     */
+    exportHeader?: string;
+    /**
+     * Pin this column by default, on mount. Applied once to the table's initial pinning state —
+     * a user's later manual pin/unpin (via the header "⋯" menu) is never overridden.
+     */
+    defaultPin?: 'left' | 'right';
+    /**
+     * Order among columns that default-pin to the same side. Lower sits closer to the table's
+     * outer edge. Defaults to declaration order when omitted. Inert without `defaultPin`.
+     */
+    pinIndex?: number;
+};
+/**
+ * `G` — this table's persist group, ONLY relevant for narrowing `filters[].shared`'s
+ * autocomplete/type-check to that one group's own slots (see `PersistSlotFor`). You never set it
+ * explicitly for an inline `<DataTable persist={{group:"QC"}} filters={[...]} />` call: TS infers
+ * it from `persist.group` and checks `filters` against it in the same pass, same as `TData`
+ * infers from `data`/`columns`.
+ *
+ * It DOES need spelling out when `filters` is a separately declared `const` (the common pattern —
+ * `const filters: DataTableProps<Row>["filters"] = [...]`), because that array gets its type at
+ * its own declaration, independent of a `persist` prop written later in the same file. Add the
+ * group there too: `DataTableProps<Row, "QC">["filters"]`.
+ */
+type DataTableProps<TData, G extends PersistGroupId | undefined = undefined> = {
+    /** Row data. Rendered client-side (filter/sort/paginate all in-memory unless server-driven). */
+    data: TData[];
+    /** Column definitions. TanStack `ColumnDef` plus a few extras; see {@link GroupColumnDef}. */
+    columns: GroupColumnDef<TData>[];
+    /** Toolbar filter controls (see {@link FilterConfig}); place each on the bar or behind the global
+     *  search's field picker via `FilterConfig.placement`. Debug: filters live in the toolbar, so none
+     *  render unless `settings.showToolbar: true`. */
+    filters?: FilterConfig<TData, G>[];
+    /** Pagination config — its presence enables pagination. Omit to render all rows. */
+    pagination?: PaginationConfig;
+    /** Feature and presentation toggles; see {@link TableSettings} for the full dependency map. */
+    settings?: TableSettings;
+    /** Title/header area above the table. Plain node, or {@link TableHeaderProps} for alignment control. */
+    header?: React.ReactNode | TableHeaderProps;
+    /** Sticky footer content (spans full width). */
+    footer?: React.ReactNode;
+    /** Extra class on the outer wrapper. */
+    className?: string;
+    /** Max height of the scroll container (enables sticky header/footer). @default "100%" */
+    maxHeight?: string;
+    /** Show the loading overlay. @default false */
+    loading?: boolean;
+    /** Error message. When set it replaces the table with an error card, which also offers Try Again
+     *  when `onRefresh` is given. */
+    error?: string;
+    /** Text shown when there are no rows. @default "No data available" */
+    emptyMessage?: string;
+    /** Fires with the selected row originals whenever selection changes. Requires `enableRowSelection`.
+     *  @remarks Unselectable rows (see `isRowSelectable`) are filtered out. */
+    onRowSelectionChange?: (selectedRows: TData[]) => void;
+    /**
+     * Called by the toolbar Export button. `data` is the filtered + sorted row originals (all pages,
+     * not just the visible one) and `view` is the ready-to-write snapshot of the visible columns and
+     * cell values (see `getTableExportView` — call it yourself via `onTableReady` for export buttons
+     * that live outside the toolbar). Feed `view` to the app's Excel/CSV writer.
+     */
+    onExport?: (data: TData[], view: TableExportView<TData>) => void;
+    /** Called by the toolbar Refresh button (and the error card's Try Again). */
+    onRefresh?: () => void;
+    /** Escape hatch that hands you the TanStack `table` instance for imperative control. */
+    onTableReady?: (table: Table<TData>) => void;
+    /** Render-prop for an action bar etc.; receives the `table` instance. */
+    children?: (table: Table<TData>) => React.ReactNode;
+    /** Return false to make a row unselectable: its checkbox greys out, select-all skips it and
+     *  `onRowSelectionChange` never reports it. The row itself stays fully visible and interactive. */
+    isRowSelectable?: (row: TData) => boolean;
+    /**
+     * Returns a **stable, unique id for a row**, derived from your own data. Forwarded straight to
+     * TanStack's `getRowId`. You are not assigning an id — you point at the field(s) that already
+     * uniquely identify the record, and TanStack calls this to read it.
+     *
+     * **Why it matters:** without it, selection (and expansion/pinning) is keyed by the row's *index in
+     * the `data` array*. That is fine as long as the array never changes, but the moment `data` is
+     * replaced or reordered — a refetch, a tab switch to a different list, an insert/delete that shifts
+     * everything after it — index `2` now points at a different record, so the wrong rows appear
+     * selected. With `getRowId`, selection is keyed by the record itself and survives all of that.
+     *
+     * (Client-side sort / filter / pagination alone do **not** need this — they don't mutate the `data`
+     * array, so index-based ids stay correct. It's specifically array replacement/reordering that breaks.)
+     *
+     * **When to pass it:** any table that has row selection *and* whose `data` can be refetched,
+     * reordered, or have rows added/removed. Also **required** for `defaultSelectedRows` to target rows
+     * reliably. Display-only or never-refetched tables can omit it.
+     *
+     * Pick field(s) guaranteed unique per row; combine with `-` when no single field is unique.
+     * @example getRowId={(row) => String(row.id)}
+     * @example getRowId={(row) => `${row.Code}-${row.Type}`}  // unique only as a pair
+     */
+    getRowId?: (row: TData, index: number) => string;
+    /**
+     * **Uncontrolled prefill.** Return `true` for rows that should start already selected. The table
+     * keeps owning selection state afterwards — this only seeds the initial value (same idea as
+     * `<input defaultChecked>`), so you do not have to manage a controlled selection yourself.
+     *
+     * **Timing:** seeded exactly once, after the first non-empty `data` load (so it works even when data
+     * arrives async). It is *not* re-run on later data changes — that would wipe the user's own
+     * selections on every refetch. To deliberately re-seed for a new dataset (e.g. switching tabs),
+     * remount the table with a React `key`.
+     *
+     * **Safety:** only rows the table considers selectable are seeded — a row failing `isRowSelectable`
+     * is skipped, so prefill can never select an unselectable row. Setting selection here
+     * flows through the normal path, so `onRowSelectionChange`, the action bar, and any
+     * "disable others once one is selected" logic react exactly as they do for a real user click.
+     *
+     * **Pair with `getRowId`** so the seeded rows are matched by record, not by array position.
+     * @example defaultSelectedRows={(row) => row.WasPreviouslyPicked}
+     */
+    defaultSelectedRows?: (row: TData) => boolean;
+    /** Server side search callback. Receives the staged external filter values when the Search button
+     *  is pressed; run your query here. */
+    onExternalSearch?: (filters: Record<string, any>) => void;
+    /** Column aggregations (footer sums / averages / counts …), parent-controlled. The footer row
+     *  appears whenever any column's config is `enabled`. Debug: the toolbar's Aggregations menu (to
+     *  toggle them from the UI) additionally needs `onAggregationChange` + `settings.showToolbar` + at
+     *  least one numeric column. @see AggregationConfigMap */
+    aggregations?: AggregationConfigMap<TData>;
+    /** Fires when the user toggles an aggregation in the toolbar menu; persist it into your
+     *  `aggregations` state (the component does not own it). Without this the toggle menu is hidden. */
+    onAggregationChange?: (columnId: string, config: AggregationConfig<TData>) => void;
+    /** Per-row className (e.g. status-based row colouring). */
+    rowClassName?: (row: Row<TData>) => string;
+    /**
+     * Persist this table's filters, global search, external filter values and pagination across
+     * unmount/back-navigation. In-memory by default (refresh = fresh); `local: true` adds
+     * localStorage. String shorthand = `{ key }`. Absent = no persistence (today's behaviour).
+     * Restore is synchronous (seeded before first render — no unfiltered flash); external filters
+     * are replayed through `onExternalSearch` on mount (see `readPersistedExternal` to seed the
+     * page's own query instead). Selection is never persisted. See {@link PersistConfig}.
+     *
+     * Setting `group` here is also what narrows every filter's `shared` (in the SAME `filters`
+     * array literal) to just this group's own slots instead of every group's — see `DataTableProps`'s
+     * `G` type param doc above for the one case (a separately-declared `filters` const) where you
+     * have to spell `G` out yourself for that to kick in.
+     * @example persist="qc-completed"
+     * @example persist={{ key: "qc-completed", group: "inhouse", local: true }}
+     */
+    persist?: string | PersistConfig<G>;
+};
+
+export type { AggregationConfig, AggregationConfigMap, AggregationFunction, ColumnFooter, CustomFilterConfig, DataTableProps, FilterConfig, GroupColumnDef, PaginationConfig, PathFilterConfig, TableHeaderProps, TableSettings };