@inui/design-system 0.0.0-stage → 1.22.0

package/dist/components/ui/data-table.d.ts

@@ -0,0 +1,1026 @@
+/**
+ * DataTable — Table plus sorting, filtering, search, row selection,
+ * row actions, expandable rows, AI affordances, column management, and
+ * pagination.
+ *
+ * A composite over the existing `Table` primitive (unmodified) — state is
+ * owned by `@tanstack/react-table`, a headless logic-only library with no
+ * rendered markup of its own (same "headless engine, MMDS renders every
+ * pixel" shape as RichTextEditor's use of draft-js), not hand-rolled here.
+ * Every visible piece (checkboxes, buttons, the search field, filter
+ * popovers, the column menu, pagination, loading/empty states) is an
+ * existing MMDS primitive — Checkbox, Button, InputGroup, Input, Select,
+ * Popover, DropdownMenu, Skeleton, Empty, AISparkle.
+ */
+import * as React from "react";
+import { type ColumnDef, type Column, type Row, type SortingState, type VisibilityState, type RowSelectionState, type ColumnFiltersState, type ColumnOrderState, type ColumnPinningState, type ColumnSizingState, type ExpandedState, type PaginationState, type Table as TanstackTable } from "@tanstack/react-table";
+/** One resolved option for a `select`/`singleSelect`/`range` filter — see `meta.filterOptions`. */
+type FilterOption = {
+    value: string;
+    label?: React.ReactNode;
+    /** Plain-text stand-in for `label` — read by the trigger's comma-list and the search recipe below when `label` isn't already a plain string (an icon, a Badge, anything non-text). */
+    textValue?: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** A second, muted line under the label — a code, a subtitle, whatever extra context makes one option distinguishable from another that isn't worth its own column. Plain text only (unlike `label`), since it renders inside the same comma-list/search-text machinery `textValue` does. */
+    description?: string;
+    /** Options sharing a `group` render together under a `SelectMultipleLabel`/muted heading, in whatever order groups first appear in the resolved list. Ungrouped options (no `group` on any option in the list) render as one flat list — grouping only activates once at least one option opts in. */
+    group?: string;
+    disabled?: boolean;
+    /** Set internally when `showFilterCounts` is on — not meant to be supplied on a `filterOptions` entry yourself, since it's overwritten from `getFacetedUniqueValues()` regardless. */
+    count?: number;
+};
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TData, TValue> {
+        /**
+         * "text" (default): substring filter — pass a custom `filterFn` directly
+         * on the `ColumnDef` (checked first, ahead of everything here) for
+         * anything other than a case-insensitive substring match, e.g. TanStack's
+         * own `"equalsString"`/`"includesStringSensitive"` presets, or your own.
+         * "select": multi-select checklist of the column's unique values (via getFacetedUniqueValues).
+         * "singleSelect": same source, but only one value at a time.
+         * "bucket" (`"range"` also still accepted — see `rangeBucketSize`/`bucketSize`, deprecated
+         * in favor of it): multi-select checklist of fixed-size numeric buckets ("1-3", "4-6", ...),
+         * computed from the trailing number in each unique value — for id-like columns (invoice
+         * numbers, ticket numbers) where an exact substring match isn't the point.
+         */
+        filterVariant?: "text" | "select" | "singleSelect" | "range" | "bucket";
+        /** Bucket size for `filterVariant: "bucket"` — how many consecutive numeric values group into one bucket. Default 3. Deprecated alias: `rangeBucketSize`. */
+        bucketSize?: number;
+        /** @deprecated Use `bucketSize` — same option, `filterVariant: "bucket"`'s original name back when the variant itself was still called `"range"`. */
+        rangeBucketSize?: number;
+        /**
+         * Explicit options for a `select`/`singleSelect`/`range` column instead
+         * of deriving them from the column's own unique values — labels, icons,
+         * groups, and a fixed order none of that can express on its own. A
+         * function receives `column` (e.g. to read `getFacetedUniqueValues()`
+         * counts yourself, or vary options off something outside the table
+         * entirely). Every option's own `value` must still match what actually
+         * appears in the data for the filter to match anything.
+         */
+        filterOptions?: FilterOption[] | ((column: Column<TData, TValue>) => FilterOption[]);
+        /** Renders `Skeleton` rows in place of the option list while an async `filterOptions` source is still loading — DataTable never fetches anything itself, this only controls what renders meanwhile. */
+        filterOptionsLoading?: boolean;
+        /** How the resolved option list orders itself — default `"auto"`: a numeric-aware collator (so "2" sorts before "10"), applied whether the options came from facets or your own `filterOptions`. `"none"` keeps `filterOptions`' own array order (meaningless for facet-derived options, which have no other order). A comparator gets full control. */
+        filterOptionsSort?: "auto" | "none" | ((a: FilterOption, b: FilterOption) => number);
+        /**
+         * Per-column override of `DataTable`'s own `filterApplyMode` — e.g. one
+         * text column that should defer to an explicit Apply while the rest of
+         * the table applies immediately, or vice versa. Doesn't affect
+         * `select`/`range`: those are always deferred regardless (see
+         * `isMultiSelectFilterVariant`) — this can't force them immediate. Also
+         * meaningless for `singleSelect`, which closes on pick before an Apply
+         * step could ever matter.
+         */
+        filterApplyMode?: "immediate" | "deferred";
+        /**
+         * Escape hatch for a filter UI none of the built-in `filterVariant`s
+         * cover — a date-range picker, a numeric slider, a three-state
+         * toggle, a multi-field filter, anything a specific table's own
+         * use case calls for. This is the deliberate answer for those, not a
+         * gap: MMDS ships the primitives (`Calendar`, `Slider`, `ToggleGroup`,
+         * `Input`, ...) a designer composes into whatever shape that use case
+         * actually needs — a number-range Slider, a date-range Calendar, a
+         * Yes/No ToggleGroup — rather than DataTable guessing at one fixed
+         * shape/labeling/styling for everyone. Checked first, ahead of
+         * `filterVariant`, in every filter surface (header-icon popover,
+         * inline toolbar button, and the "All filters" pane) — same
+         * `value`/`onValueChange` shape those surfaces already pass to the
+         * built-in variants, and `value`/`onValueChange` carry a pending draft
+         * under `filterApplyMode="deferred"` in all three the same way, not
+         * just two of them: the inline toolbar button wraps a deferred custom
+         * render in a Popover + the shared Cancel/Apply footer of its own (it
+         * has no such popover otherwise, unlike `select`/`range`/text, which
+         * always get one); the pane — which has no popover for *any* variant,
+         * custom or built-in — gets an inline Cancel/Apply row directly under
+         * the rendered content instead. Immediate (the default), every surface
+         * renders it directly with no extra chrome, same as always. Read and
+         * write the real filter state yourself via `column` (e.g.
+         * `column.getFacetedUniqueValues()`, `column.getFacetedMinMaxValues()`
+         * — that one needs `getFacetedMinMaxValues` passed to the table's own
+         * options too, since DataTable only wires it up automatically for its
+         * own built-in variants) if the custom UI needs it beyond the one
+         * value being edited.
+         */
+        filterRender?: (props: {
+            column: Column<TData, TValue>;
+            value: unknown;
+            onValueChange: (value: unknown) => void;
+        }) => React.ReactNode;
+        /**
+         * Defines a column purely to filter on a data point that isn't shown
+         * anywhere in the table — the column itself (its `header`/`cell`) never
+         * renders, permanently, with no user-facing toggle to show it: it's
+         * excluded from the Columns menu entirely (not just its checkbox — from
+         * the reorder/pin list too, since there's no header cell to reorder or
+         * pin) rather than merely defaulting hidden the way a plain hideable
+         * column can. It still needs a real `accessorKey`/`accessorFn` (that's
+         * what its filter reads) and still shows up as a normal filterable
+         * column in the "All filters" pane — but never inline in the toolbar
+         * (no user-facing pin toggle for it there either, same reasoning as
+         * the Columns menu exclusion — there's no header cell for a toolbar
+         * chip to point back at), and its presence alone forces the pane to
+         * exist at all even if 3 or fewer *other* columns are filterable,
+         * since the pane is its only access point. Give it a `header` anyway
+         * (used as its filter's label) even though it's never rendered.
+         */
+        filterOnly?: boolean;
+        /**
+         * Merges other columns' filter fields into *this* column's own
+         * header-icon filter popover instead of each getting its own separate
+         * entry in the toolbar/pane — for a cell that already displays more
+         * than one filterable value at once (e.g. a "Patient" column whose
+         * custom `cell` renders a name plus an MRN below it), so filtering
+         * either reads as one decision made from one icon, not two unrelated
+         * ones. Each id listed here is excluded from `filterableColumns`
+         * (so it never *also* shows up on its own) and instead renders as its
+         * own labeled section inside this column's popover, stacked under a
+         * divider — typically `meta: { filterOnly: true }` columns, since the
+         * value they filter is usually already folded into this column's own
+         * `cell` rather than shown in a column of its own, but that's a
+         * convention, not a requirement: any filterable column id works. This
+         * column's own filter field always renders first, unlabeled; merged
+         * ones below it are labeled with their own `header` so it's clear
+         * which value each field filters. The header icon itself shows filled
+         * (and the Cancel/Apply footer under `filterApplyMode="deferred"`
+         * commits/discards) if *any* of them — this column or a merged one —
+         * has an active filter, not just this column's own.
+         */
+        filterMergeWith?: string[];
+        /**
+         * Overrides this column's position in the filter order — both the
+         * toolbar's pinned chips and the "All filters" pane render filterable
+         * columns sorted by this (ascending; ties broken by column order, then
+         * lower first), independent of the table's own column order. Omit to
+         * keep the default (this column's own position in column order, as
+         * today) — only set it on columns that actually need to jump out of
+         * that order.
+         */
+        filterOrder?: number;
+        /**
+         * Aligns this column's header and cell content — default `"left"`,
+         * the right fit for text. Set `"right"` for quantitative content
+         * (amounts, counts, percentages, anything meant to be scanned/summed
+         * down the column) — numbers read fastest when their digits line up
+         * on a shared right edge, which is why this is a per-column opt-in
+         * rather than something DataTable guesses from the data: it has no
+         * reliable way to tell "123 Main St" apart from "123" apart from a
+         * custom cell rendering a styled duration, so the convention is
+         * yours to apply, not DataTable's to infer. `"right"` also mirrors
+         * the header itself — the sort button's label right-aligns and the
+         * filter icon/`headerActions` cluster moves to the *left* of it,
+         * instead of both sitting to its right — so the controls stay off to
+         * the side the numbers don't occupy.
+         */
+        align?: "left" | "right";
+        /**
+         * This column's name wherever one is needed that isn't the rendered
+         * `header` itself — the Columns menu, the "All filters" pane, header
+         * tooltips/`aria-label`s, applied-filter copy. Only matters when
+         * `header` isn't a plain string (an icon-only header, a custom
+         * component) — DataTable has no reliable way to derive a name from
+         * arbitrary JSX, and falls back to the column's raw `id` (a dev-only
+         * console warning, once per column) rather than guessing.
+         */
+        label?: string;
+        /**
+         * Collapses this column's cell into one `rowSpan`-merged cell across
+         * however many consecutive rendered rows (post-sort/filter/page — the
+         * rows actually adjacent on screen, not the raw data) share the same
+         * `column.getValue()` — a spreadsheet-style vertical merge instead of
+         * repeating the value on every row. Only meaningful when those rows
+         * are actually adjacent because the table is sorted by (or the data is
+         * pre-grouped by) this column; otherwise every run is length 1 and
+         * nothing visibly merges. Equality is plain `===` — no custom
+         * comparator. Content is top-aligned inside the merged cell so it
+         * reads like a label for the rows below it, not vertically centered;
+         * override via the column's own `cell` if centered fits better.
+         */
+        mergeRepeatedValues?: boolean;
+        /** Sticks this column to the left/right edge during horizontal scroll. Seeds the *initial* pinned side only — the user can toggle it live from there (e.g. via `columnMenuActions` in `headerActions`), unless `pinLocked` is set. */
+        pin?: "left" | "right";
+        /** Suppresses `columnMenuActions`' Pin left/Pin right for this column, so pinning stays fully dev-controlled with no user-facing toggle. Doesn't stop a custom `headerActions` entry from calling `column.pin(...)` itself. */
+        pinLocked?: boolean;
+        /**
+         * Custom actions rendered in this column's header cell, next to the
+         * sort button and filter icon — hidden until the header cell is
+         * hovered or keyboard-focused, collapsing into an overflow menu past
+         * 2 actions (same `RowActions` component row actions use). A
+         * function, not a static array, so labels/icons can reflect live
+         * per-column state (e.g. "Pin left" flipping to "Unpin"). Takes the
+         * table too, since some actions (`columnMenuActions`' "Fit to
+         * content") need it. See `columnMenuActions`.
+         */
+        headerActions?: (column: Column<TData, unknown>, table: TanstackTable<TData>) => RowAction[];
+    }
+    interface TableMeta<TData> {
+        /** Internal — backs `columnMenuActions`' "Fit to content" measurement. Not meant to be set by consumers. */
+        getColumnCellElements?: (columnId: string) => HTMLElement[];
+    }
+}
+/**
+ * Wraps the substring of `text` matching `query` in a `<mark>`. Exported so a
+ * column with a custom `cell` can highlight matches itself — read the live
+ * query off `info.table.getState().globalFilter` inside that `cell`. Pass
+ * `startsWith` when the table's `searchMatch` is `"startsWith"`, so only
+ * word-start matches are marked.
+ */
+declare function HighlightMatch({ text, query, startsWith, }: {
+    text: string;
+    query: string;
+    startsWith?: boolean;
+}): React.JSX.Element;
+/** The committed (not live-dragging/previewing) column layout `onColumnLayoutChange` hands back — pair with `defaultColumnVisibility`/`Order`/`Pinning`/`Sizing` to persist and restore it. */
+type DataTableColumnLayout = {
+    visibility: VisibilityState;
+    order: ColumnOrderState;
+    pinning: ColumnPinningState;
+    sizing: ColumnSizingState;
+};
+type RowAction = {
+    label: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    onClick: () => void;
+    variant?: "default" | "destructive";
+    /**
+     * Passed straight through to the rendered control (an inline icon Button
+     * or, past the overflow threshold, a DropdownMenuItem) — both already
+     * forward arbitrary DOM props, so a hover-preview, focus-driven tooltip,
+     * or any other non-click interaction works the same regardless of which
+     * one ends up rendering this action.
+     */
+    onMouseEnter?: React.MouseEventHandler;
+    onMouseLeave?: React.MouseEventHandler;
+    onFocus?: React.FocusEventHandler;
+    onBlur?: React.FocusEventHandler;
+};
+/**
+ * Renders `actions` as inline icon buttons (≤2 actions) or an overflow
+ * menu (>2) — `mode` overrides the auto pick. Stops its own click from
+ * bubbling, so it composes safely inside a row that also has `onRowClick`.
+ */
+declare function RowActions({ actions, mode, revealClassName, onOpenChange, }: {
+    actions: RowAction[];
+    mode?: "inline" | "overflow" | "auto";
+    /**
+     * Hover/keyboard-focus-reveal classes for this cluster's own visibility
+     * (e.g. `revealColumnControlsOnHover`'s computed class) — applied here
+     * rather than by a wrapping `<div>` at the call site, so the overflow
+     * branch can force itself visible (via real React state, not a CSS
+     * selector) while its own menu is open, however the pointer got there.
+     * A modal Radix menu sets `pointer-events: none` on the rest of the
+     * page while open, which breaks *any* CSS-only `:hover` tracking for
+     * this cluster regardless of where the cursor physically is — hence
+     * `open` state, not `group-hover`, driving the override. Omit to
+     * always render visible (no hover-gating at all).
+     */
+    revealClassName?: string;
+    /** Fires when the overflow menu opens/closes — a sibling control in the
+     * same header cell (the filter icon) needs to know too, since it can't
+     * detect this itself: this menu is modal, so it sets `pointer-events:
+     * none` on the rest of the header while open, breaking that sibling's
+     * own `:hover` tracking regardless of where the pointer actually is. */
+    onOpenChange?: (open: boolean) => void;
+}): React.JSX.Element;
+/**
+ * A ready-made column-menu bundle for `headerActions` — Pin left, Pin
+ * right (via `pinActions`), Hide column, and Fit to content — each
+ * omitted when the column can't do it (`getCanPin()`/`getCanHide()`/
+ * `getCanResize()`, the last only true once `enableColumnResizing` is
+ * set). Typically 3-4 actions, so `RowActions`' own auto mode already
+ * renders it as a single overflow "more" menu — no need to force
+ * `mode="overflow"`.
+ */
+declare function columnMenuActions<TData>(column: Column<TData, unknown>, table: TanstackTable<TData>): RowAction[];
+declare function DataTable<TData, TValue = unknown>({ columns: userColumns, data, loading, error, errorDescription, emptyTitle, emptyDescription, searchPlaceholder, searchableColumnIds, searchMatch, filterApplyMode, defaultSorting, defaultColumnFilters, defaultGlobalFilter, defaultPageIndex, defaultColumnVisibility, defaultColumnOrder, defaultColumnPinning, defaultColumnSizing, defaultExpanded, onExpandedChange, tableRef, onColumnLayoutChange, defaultPinnedFilterIds, allowFilterPinning, showFilterCounts, stickyFilterSelectAll, clearFiltersOnHide, enableRowSelection, selectionScope, maxSelectedRows, defaultRowSelection, selectionBarPlacement, onRowSelectionChange, onStateChange, renderBulkActions, onRowClick, renderExpandedRow, getRowId, lockedColumnIds, enableColumnResizing, enableMultiSort, revealColumnControlsOnHover, striped, cellDividers, aiAction, actionButtons, aiRowPredicate, aiColumnIds, aiCellPredicate, pageSize, pageSizeOptions, showPageSizeSelector, paginationStyle, onLoadMore, loadMoreOffset, hasMore, showColumnToggle, loadingMore, maxHeight, stickyHeader, caption, captionHidden, size, className, "aria-label": ariaLabel, }: {
+    columns: ColumnDef<TData, TValue>[];
+    data: TData[];
+    /** Renders skeleton rows shaped like the real columns instead of `data`. */
+    loading?: boolean;
+    /** True renders the failure state (an Empty with `role="alert"`) instead of rows. Passing a string/node here still works but is deprecated — put the copy in `errorDescription` instead, so "is errored" and "what to say" are separate. */
+    error?: boolean | React.ReactNode;
+    /** Description shown in the failure state; defaults to "Something went wrong. Try again." Only read while `error` is truthy. */
+    errorDescription?: React.ReactNode;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    searchPlaceholder?: string;
+    /** Column ids the search box matches against. Defaults to the first two entries in `columns`. `"all"` matches every column with a real accessor (`accessorKey`/`accessorFn`) — an injected column (selection checkbox, expand toggle, AI marker) has neither, so this never accidentally includes those. */
+    searchableColumnIds?: string[] | "all";
+    /** How the search box matches — default `"contains"` (anywhere in the value). `"startsWith"` only matches where a word starts, so "nair" finds "Priya Nair" but not "Bernair". Matches are highlighted the same way. */
+    searchMatch?: "contains" | "startsWith";
+    /**
+     * Only affects the header-icon popover and inline toolbar's plain-text
+     * field — a multiselect filter (`"select"`/`"range"`, a checklist of
+     * several values at once) always requires Apply regardless of this
+     * prop, in every surface (see `isMultiSelectFilterVariant`), and
+     * `"singleSelect"` never does anywhere (closes on pick, before a footer
+     * could matter). `"immediate"` (default): a text pick applies to the
+     * real table as it's made, no confirmation step. `"deferred"` adds a
+     * Cancel/Apply step to that same text field instead — picks edit a
+     * local draft only, with no effect on the real table until Apply
+     * commits it; Cancel just closes and discards it. Table-wide, not
+     * per-column — a mix of immediate and deferred text filters in one
+     * toolbar would be confusing about which picks need a second step. Has
+     * no effect on the "All filters" pane at all — every field there is
+     * either always live (text, singleSelect) or always deferred with its
+     * own individual popover Apply/Cancel (select/range), never driven by
+     * this prop.
+     */
+    filterApplyMode?: "immediate" | "deferred";
+    /** Sort applied on first render — same shape as `@tanstack/react-table`'s `SortingState`. Uncontrolled from there on; the user's own header clicks take over. */
+    defaultSorting?: SortingState;
+    /** Column filters applied on first render — same shape as `@tanstack/react-table`'s `ColumnFiltersState` (`[{ id: "status", value: ["Paid"] }, ...]`, `value` shaped however that column's own filter variant expects it). Uncontrolled from there on; the user's own picks take over. Paired with `defaultGlobalFilter` and `defaultSorting`, this is what makes restoring table state after a round trip (e.g. from a URL query param, on the way back from a detail page) possible — `onStateChange` reads that same state back out live, but had nothing to feed a value back in with until these existed. */
+    defaultColumnFilters?: ColumnFiltersState;
+    /** Global search value applied on first render. Uncontrolled from there on — the user's own typing into the search box takes over. See `defaultColumnFilters`. */
+    defaultGlobalFilter?: string;
+    /** Page index applied on first render (0-based). Uncontrolled from there on — the user's own pagination clicks take over. Ignored with `onLoadMore` (infinite scroll has no page concept). */
+    defaultPageIndex?: number;
+    /** Column visibility applied on first render — same shape as `@tanstack/react-table`'s `VisibilityState`. Uncontrolled from there on; the Columns menu's own checkboxes take over. Also becomes the baseline "Reset to defaults" restores and `hasColumnCustomization` compares against, in place of "everything visible." */
+    defaultColumnVisibility?: VisibilityState;
+    /** Column order applied on first render — same shape as `@tanstack/react-table`'s `ColumnOrderState`, center (unpinned) columns only. Uncontrolled from there on; drag-reordering in the Columns menu takes over. Also becomes the "Reset to defaults" baseline in place of `columns`' own order. */
+    defaultColumnOrder?: ColumnOrderState;
+    /** Column pinning applied on first render — same shape as `@tanstack/react-table`'s `ColumnPinningState`. Wins over any per-column `meta.pin` when provided; uncontrolled from there on, same as `defaultColumnOrder`. Also becomes the "Reset to defaults" baseline in place of `meta.pin`-derived pinning. */
+    defaultColumnPinning?: ColumnPinningState;
+    /** Column widths applied on first render — same shape as `@tanstack/react-table`'s `ColumnSizingState`. Uncontrolled from there on; the user's own drag-resizing takes over. Also becomes what "Reset to defaults" restores widths to, in place of each column's own `size`. */
+    defaultColumnSizing?: ColumnSizingState;
+    /** Expanded rows applied on first render — same shape as `@tanstack/react-table`'s `ExpandedState`. Uncontrolled from there on; the row's own expand toggle takes over. Only meaningful alongside `renderExpandedRow` or `getSubRows`. */
+    defaultExpanded?: ExpandedState;
+    /** Fires after a row's expanded state changes, live — the `renderExpandedRow`/tree-data counterpart to `onRowSelectionChange`. Not controlled: there's no live two-way binding, but paired with `defaultExpanded` it round-trips the same way `onStateChange`/`defaultColumnFilters` do. */
+    onExpandedChange?: (expanded: ExpandedState) => void;
+    /** A read-mostly escape hatch onto the underlying `@tanstack/react-table` instance — for anything DataTable doesn't already expose a prop for (e.g. a CSV export reading `table.getFilteredRowModel()`, or `table.setColumnFilters(...)` from an external "saved views" picker). A callback, not a ref object — assign it to a ref of your own inside the callback (`tableRef={(table) => (myRef.current = table)}`) if you need to hold onto it; called after mount, and again with `null` on unmount. Treat table methods called from outside as one-off imperative actions, not a second source of truth to render from. */
+    tableRef?: (table: TanstackTable<TData> | null) => void;
+    /** Fires whenever committed (not live-dragging/live-previewing) column visibility, order, pinning, or sizing changes — after a resize ends, or a Columns-menu Apply/Reset, not on every intermediate drag pixel or menu preview tick. Pair with `defaultColumnVisibility`/`Order`/`Pinning`/`Sizing` to persist a user's layout (e.g. to `localStorage`) and restore it next session. */
+    onColumnLayoutChange?: (layout: DataTableColumnLayout) => void;
+    /** Which filterable columns start pinned/inline in the toolbar (with a pin toggle in the "All filters" pane to change it live, unless `allowFilterPinning` is off). Defaults to the first two filterable entries in `columns`, in column order — set this instead when the columns you want inline aren't already first. */
+    defaultPinnedFilterIds?: string[];
+    /** Whether the "All filters" pane's per-row pin/unpin toggle renders at all — default `true`. Set `false` for a designer-fixed toolbar: `defaultPinnedFilterIds` (or its first-two-columns default) becomes the permanent, non-user-changeable inline set, and every other filterable column lives only in the pane, with no way to move it out. The toggle itself is hover/keyboard-focus-revealed by default, same as the header cell's own controls — see `revealColumnControlsOnHover`. */
+    allowFilterPinning?: boolean;
+    /** Shows each option's `getFacetedUniqueValues()` count next to its label ("Paid (124)") across every `select`/`singleSelect`/`range` filter surface — the header-icon popover, the inline toolbar chip, and the pane. Off by default: a count only means something once a consumer actually wants "how many rows have this value" surfaced, and it costs a facet lookup per option on every render otherwise skipped. */
+    showFilterCounts?: boolean;
+    /** Whether "Select all" in a multi-select filter's option list (once past its own, lower option-count threshold — independent of the search box's) stays pinned above the list while it scrolls — default `false`: it's the first row inside the same scrolling area as the options themselves, same as a plain checkbox list where nothing else stays fixed either. Set `true` to keep it visible regardless of scroll position instead. */
+    stickyFilterSelectAll?: boolean;
+    /** Clears a column's filter the moment it's hidden via the Columns menu — default `false` (a hidden column's filter stays active, still visible in the pane with a muted "(hidden)" suffix, since hiding a column isn't the same action as clearing what it's filtered to). Set `true` if hiding a column should mean "I'm done filtering by this" instead. */
+    clearFiltersOnHide?: boolean;
+    /** Turns on the row-selection checkbox column. A function instead of a plain `true` makes specific rows unselectable — e.g. `(row) => row.original.status !== "Completed"` — the cell checkbox `disabled`s for those rows and neither the header nor "Select all" checkbox counts them. */
+    enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
+    /** What "selected" means once a filter hides some of the checked rows — default `"filtered"`: selection state itself never loses those rows (clearing the filter shows them checked again), but the count, `renderBulkActions`, and `onRowSelectionChange` all act only on rows that currently pass every filter, so a bulk action can never silently reach past what's on screen. `"all"` restores pre-1.x behavior, where a bulk action acts on every checked row regardless of the active filter — opt into this only if that's a deliberate multi-pass selection workflow. */
+    selectionScope?: "filtered" | "all";
+    /** Caps how many rows can be checked at once — every unselected checkbox (row, header, "Select all") disables once the cap is hit, so a user has to uncheck something before adding another. Already-checked rows stay checkable (to uncheck) past the cap. */
+    maxSelectedRows?: number;
+    /** Rows checked on first render — same shape as `@tanstack/react-table`'s `RowSelectionState` (`{ [rowId]: true }`). Uncontrolled from there on. Meaningless without `getRowId`: row identity otherwise defaults to render index, which this has no way to match against your data ahead of the first render. */
+    defaultRowSelection?: RowSelectionState;
+    /** Where the selection UI (count, "Select all", `renderBulkActions`) lives in paginated mode — default `"toolbar"` swaps search/filters out for it there; `"floating"` keeps search/filters mounted and shows the same floating pill infinite-scroll tables always use instead. No effect with `onLoadMore` set — infinite scroll has no footer to swap into, so it's always floating. */
+    selectionBarPlacement?: "toolbar" | "floating";
+    /** `details.hiddenByFilterCount` is how many additional rows are checked but excluded from `selectedRows` by `selectionScope="filtered"` (always `0` under `"all"`); `details.allSelectedRows` is the unfiltered full set regardless of scope. */
+    onRowSelectionChange?: (selectedRows: TData[], details: {
+        allSelectedRows: TData[];
+        hiddenByFilterCount: number;
+    }) => void;
+    /** Fires after sorting, column filters, search, pagination, expansion, or pinned-filter changes, live — a read-only escape hatch for syncing this internal state elsewhere (URL params, analytics, a server-driven refetch). Not a controlled-mode prop — there's no live two-way binding — but paired with `defaultSorting`/`defaultColumnFilters`/`defaultGlobalFilter`/`defaultPageIndex`/`defaultExpanded`/`defaultPinnedFilterIds` it's enough to round-trip state out to a URL and back in on next mount. */
+    onStateChange?: (state: {
+        sorting: SortingState;
+        columnFilters: ColumnFiltersState;
+        globalFilter: string;
+        pagination: PaginationState;
+        expanded: ExpandedState;
+        pinnedFilterIds: string[];
+    }) => void;
+    /** Product-configured actions shown while rows are selected — on an infinite-scroll table (`onLoadMore`), a pill that hovers over the table's own bottom edge (count + Select all on the left, this on the right of a divider, a close button after another); on a paginated table, search/filters in the toolbar are swapped out for the count, Select all, this, and a close button instead — no separate bar. Omit either way for just the count/Select all/close with no actions. */
+    renderBulkActions?: (selectedRows: TData[], clearSelection: () => void) => React.ReactNode;
+    /** Makes every row clickable/keyboard-activatable — e.g. navigating to a detail view. Combine with `enableRowSelection` freely; clicking the row checkbox never triggers this. */
+    onRowClick?: (row: TData) => void;
+    /** Renders below a row when expanded — a detail card, or more rows of its own. Injects a leading expand/collapse toggle on every row. */
+    renderExpandedRow?: (row: TData) => React.ReactNode;
+    /** A stable per-row id (e.g. `(row) => row.id`), passed straight through to `@tanstack/react-table`. Without it, a row's identity defaults to its index — fine for rendering, but meaningless across a sort/filter/pagination change, where identity is what row-selection/expansion state tracks against. */
+    getRowId?: (originalRow: TData, index: number) => string;
+    /** Column ids the Columns menu won't let the user reorder. Injected columns are always locked. */
+    lockedColumnIds?: string[];
+    /** Adds a drag handle to every resizable column's right border (injected columns never resize). Also required for `columnMenuActions`' "Fit to content" to render at all — it checks `column.getCanResize()`, same as the handle. Set `enableResizing: false` on a `ColumnDef` to exempt a specific column. */
+    enableColumnResizing?: boolean;
+    /** Shift-click a sortable header to add it to the existing sort instead of replacing it — `sorting` then holds more than one entry, in click order, and each sorted header shows a small 1/2/3 badge next to its arrow marking that order. `aria-sort` on any one header still only ever reflects that column's own direction (the attribute has no concept of rank), so the badge is the only place the *order* is actually conveyed. Default `false`. */
+    enableMultiSort?: boolean;
+    /** Whether the header-cell filter icon, `headerActions`/`columnMenuActions` menu, and the Columns-menu popover's own pin/move controls stay hidden until hovered or keyboard-focused, or render always-visible. Default `true` — set `false` for a consumer that wants every control visible up front instead of discovered on hover. */
+    revealColumnControlsOnHover?: boolean;
+    /** Tints every other body row for readability on wide/dense tables. */
+    striped?: boolean;
+    /** Adds a vertical rule between columns, for tables where column boundaries need to read clearly. */
+    cellDividers?: boolean;
+    /** Renders a `variant="ai"` action in the toolbar — table-level AI presence (e.g. "Summarize", "Ask AI"). There's no `ai` boolean/whole-table glow prop — DataTable's own outer surface never takes a border/shadow of its own; wrap it in a Card instead and put the glow + an `AILabel` on that, same as any other AI-marked surface. See the "WithAIWholeTable" story. */
+    aiAction?: {
+        label: string;
+        onClick: () => void;
+    };
+    /** Product-configured toolbar actions, rendered in order right before the Columns menu — persistent, unlike `renderBulkActions` (selection-scoped) or `aiAction` (always `variant="ai"`, rendered separately, and the one toolbar control that stays at `size` itself instead of the notch-below `controlSize`/`controlIconSize` every other toolbar control — including this one, every variant — renders at). Cap at 3: this is a designer call per table, not a user preference, and a toolbar reads as noise past that. `"primary"` maps to a filled `variant="default"` Button (keep this the artifact's only filled button — never pair two), `"secondary"` to `variant="outline"`, `"icon"` to an icon-only `variant="outline"` Button (needs `icon` set; `label` still required, used as its `aria-label` since there's no visible text). */
+    actionButtons?: {
+        label: string;
+        onClick: () => void;
+        variant?: "primary" | "secondary" | "icon";
+        icon?: React.ReactNode;
+        disabled?: boolean;
+    }[];
+    /** Rows this returns true for get a colored left edge (an inset box-shadow on the row's first cell — the table is `border-separate`, so a `<tr>` itself can never paint a border) plus a soft inward AI glow bleeding in from that same edge (`bg-ai-glow`, not a solid fill — echoes `aiColumnIds`' colored top rule, just on the row's left edge instead) and a leading `AILabel` — the very first thing in the row, ahead of the expand toggle and selection checkbox — row-level AI presence. */
+    aiRowPredicate?: (row: TData) => boolean;
+    /** Every cell in a column whose id is in this list gets the same left-glowing inward glow, tiling seamlessly down the whole column since every cell in it shares the same width; that column's header also gets a colored top rule and a leading `AILabel` (generic explanatory copy — compose `AILabel` directly into that column's own `header` instead of using this if you need column-specific text) — column-level AI presence. */
+    aiColumnIds?: string[];
+    /** Individual cells this returns true for get a trailing `AILabel` inline after the value — no glow at all, unlike row/column level — cell-level AI presence, for when only specific values (not a whole row or column) are AI-generated. */
+    aiCellPredicate?: (row: TData, columnId: string) => boolean;
+    pageSize?: number;
+    /** Choices shown in the footer's "items per page" control. */
+    pageSizeOptions?: number[];
+    /** Whether the "Items per page" control renders in the footer at all — a designer's call per table, not a user preference. Default true. */
+    showPageSizeSelector?: boolean;
+    /** How the footer's page indicator renders — default `"compact"`: a page-jump control (a `Select` past a plain click-through, or a number `Input` once page count passes `PAGE_SELECT_THRESHOLD`) plus "of N pages" text, next to Previous/Next icon buttons. `"numbered"`: `Pagination`'s own numbered links with ellipsis windowing around the current page, first/last page always reachable directly. */
+    paginationStyle?: "compact" | "numbered";
+    /** Switches to infinite scroll: every row in `data` renders (no client pagination, no footer at all), the table scrolls internally with a locked header (and locked pinned columns) instead of the page, and this is called when the user scrolls near the last row. Append the next page to `data` yourself; pair with `hasMore`/`loadingMore`. */
+    onLoadMore?: () => void;
+    /** How far (in px) from the bottom of the scroll area the next page starts loading — default `200`. Raise it to prefetch earlier on slow endpoints, `0` to load only when the last row is actually reached. Only relevant with `onLoadMore`. */
+    loadMoreOffset?: number;
+    /** Whether there's more to load — when false, the scroll trigger stops rendering (and observing) entirely. Only relevant with `onLoadMore`. */
+    hasMore?: boolean;
+    /** Shows the toolbar's "Columns" button (visibility, order and pinning) — default `true`. Set `false` for tables whose column set is fixed. */
+    showColumnToggle?: boolean;
+    /** Shows skeleton rows below the last real row while the next page is in flight, same shape as `loading`. Only relevant with `onLoadMore`. */
+    loadingMore?: boolean;
+    /** Caps how tall the internal scroll container can grow (any CSS size). In infinite-scroll mode (`onLoadMore`) this is the container's real height, defaulting to `"32rem"` — it has no other height source. In paginated mode it's an upper bound only, layered on top of whatever height the surrounding layout already gives the rows area (e.g. a fixed-height Card) — omit it there and nothing changes. */
+    maxHeight?: string;
+    /** Whether the header row sticks to the top of the scroll container instead of scrolling away with the body — default `true`. */
+    stickyHeader?: boolean;
+    /** An accessible-name fallback rendered as a real `TableCaption` — set this (or `aria-label`) so the table has *some* accessible name; a dev-only console warning fires when neither is given. `captionHidden` (default `true`) keeps it visually `sr-only` while still counting as the table's name; set `false` to actually show it above the rows. */
+    caption?: React.ReactNode;
+    captionHidden?: boolean;
+    size?: "default" | "sm" | "xs";
+    className?: string;
+    "aria-label"?: string;
+}): React.JSX.Element;
+export { DataTable, HighlightMatch, RowActions, columnMenuActions };
+export type { RowAction, DataTableColumnLayout, FilterOption };
+/**
+ * WHEN TO USE
+ * - Tabular data that needs sorting, search, column filters, selectable
+ *   rows with bulk actions, row actions, expandable detail rows, row-click
+ *   navigation, AI affordances, column management, or pagination handled
+ *   for you — an admin list, a resource picker, anything past "just render
+ *   some rows."
+ *
+ * NOT WHEN
+ * - A fixed, small table with no interaction beyond display — use Table
+ *   directly, it's lighter and this adds nothing over it.
+ * - You need virtualization or server-driven async fetching — neither is
+ *   built in this pass. Virtualization has no existing MMDS primitive to
+ *   lean on and would need a further headless dependency (e.g.
+ *   `@tanstack/react-virtual`) — out of scope here. (Column resize is
+ *   already built — `enableColumnResizing` — this isn't that.)
+ *
+ * KEY RULES
+ * - `columns`/`data` follow `@tanstack/react-table`'s `ColumnDef<TData>[]`
+ *   shape directly — this component doesn't wrap or reinvent that API, it
+ *   renders it. Read TanStack Table's own docs for `accessorKey`, custom
+ *   `cell` renderers, `enableSorting: false` per column, etc.
+ * - Sorting, filtering, search, selection, expansion, column order/
+ *   visibility, and pagination state all live inside DataTable (via
+ *   `useReactTable`) — an exception to MMDS's usual fully-uncontrolled
+ *   convention, because the whole point of this component is to own that
+ *   state so you don't have to. `onRowSelectionChange` is one escape
+ *   hatch, for wiring selection to something outside (a bulk delete call, a
+ *   parent form); `onStateChange` is another, firing sorting/columnFilters/
+ *   globalFilter live for the same reason (a URL param, analytics, a
+ *   server-driven refetch) — read-only, no live two-way binding, but
+ *   paired with `defaultSorting`/`defaultColumnFilters`/`defaultGlobalFilter`
+ *   (seeding each on first render) it's enough to round-trip state out to
+ *   a URL and back in on next mount. `defaultPinnedFilterIds` seeds the
+ *   toolbar's inline-filter set the same way — all four still fully
+ *   uncontrolled after first render, same as everything else here.
+ * - Columns render at a fixed width (`table-fixed` + a `<colgroup>` driven by
+ *   each column's `ColumnDef.size`, default 150) instead of auto-fitting to
+ *   content — set `size` per column for anything narrower/wider than that.
+ *   This trades content-driven auto-sizing for widths that stay put across
+ *   sorting, filtering, and pagination.
+ * - The toolbar carries the same edge-to-edge treatment as `Table` itself
+ *   (see Table's own KEY RULES) — its outer box matches the table's wider
+ *   footprint instead of looking narrower next to it, and its own padding
+ *   keeps search/filter/Columns content at the same inset as the table's
+ *   cell content. Automatic, no prop for it.
+ * - Toolbar controls (search, inline/"All filters" filters, Columns) and
+ *   footer controls (items-per-page, page-jump, Previous/Next) render one
+ *   size notch below `size` itself — "default" gets "sm" controls, "sm"
+ *   gets "xs", "xs" stays "xs" (already the floor). They're always-visible,
+ *   repetitive chrome, not row content competing for the same emphasis —
+ *   automatic, not a prop, and it scales with `size` rather than being
+ *   fixed at one density. The `aiAction` button is the deliberate exception
+ *   — it's meant to stand out, so it stays at `size` itself.
+ * - `loading` swaps every cell for a `Skeleton` shaped to the real columns —
+ *   don't also filter `data` to empty while loading, pass the real (stale
+ *   or previous) data and let `loading` cover it, or column widths jump.
+ * - `error` (a boolean) swaps the whole body for an Empty-based failure
+ *   state — same composition the error-state pattern uses elsewhere
+ *   (Patterns/UI States), just pre-wired here — and `errorDescription`
+ *   supplies its copy (default "Something went wrong. Try again."). Two
+ *   props on purpose: whether it failed and what to say are different
+ *   things; passing the copy as `error` itself still works but is
+ *   deprecated. A plain empty `data` array
+ *   (not loading, no error) renders the "no results" Empty state instead.
+ * - `enableRowSelection` injects a checkbox column automatically — don't
+ *   add your own selection column to `columns`.
+ * - Row actions are just a normal column whose `cell` renders the exported
+ *   `RowActions` helper (inline icon buttons for ≤2 actions, an overflow
+ *   menu past that) — there's no dedicated `actions` prop, this is the same
+ *   "put a Button in a cell" technique any custom `cell` already uses.
+ *   `RowActions` stops its own clicks from bubbling, so it's safe inside a
+ *   row that also sets `onRowClick`.
+ * - `renderExpandedRow` adds a leading expand/collapse toggle to every row;
+ *   expanding inserts a full-width row below it with whatever you return —
+ *   a detail card, or a nested table of its own. The toggle stops its click
+ *   from bubbling, so it composes with `onRowClick` too.
+ * - `onRowClick` makes the whole row clickable and keyboard-activatable
+ *   (Enter/Space), for row→detail navigation. It composes with
+ *   `enableRowSelection` — the selection checkbox stops its own click from
+ *   bubbling up, so checking a row never also triggers `onRowClick`. Any
+ *   other interactive element you put inside a cell (a button, a link)
+ *   needs its own `stopPropagation` the same way if it shouldn't also
+ *   trigger the row click.
+ * - `striped` and `cellDividers` are independent visual modifiers — zebra
+ *   row tinting and vertical column rules, respectively — for tables where
+ *   plain row/column boundaries are hard to scan.
+ * - AI presence has a distinct answer at each level, but DataTable's own
+ *   outer surface never takes a border/shadow of its own — there's no `ai`
+ *   boolean prop. For whole-table AI presence, the table just sits inside
+ *   an AI Card — the exact same recipe AI/Card's "BoundaryTreatments" story uses (a
+ *   `bg-gradient-to-r from-ai-wash to-ai-grad-from p-px` wrapper div, not
+ *   a one-off DataTable-specific border) — plus a soft inward glow rising
+ *   from the Card's own bottom edge (`bg-ai-glow-bottom`, fading out at 15%
+ *   of the Card's own height) as a plain Card className — a background-image,
+ *   so it layers over Card's own `bg-card` (`cn` registers the glow classes
+ *   as background-image utilities so tailwind-merge keeps both).
+ *   `AILabel` sits in the
+ *   Card's top corner (a `CardAction`) — see the "WithAIWholeTable" story.
+ *   The whole-table treatment is a boundary (gradient outline), an inward
+ *   bottom glow and a corner marker — not the row/column glow used below.
+ *   Below that: `aiAction` (table level)
+ *   renders a `variant="ai"` toolbar button; `aiRowPredicate` (row level)
+ *   puts a leading `AILabel` as the very first thing in the row — ahead
+ *   of the expand toggle and selection checkbox, its own leading slot —
+ *   plus a colored left edge (an inset box-shadow on the row's first
+ *   cell, not `border-l` on the `<tr>` — the table is `border-separate`
+ *   for pinned columns, and in that model a `<tr>` never paints borders)
+ *   and a soft inward glow (`bg-ai-glow`, fading out at 20% of the row's own
+ *   width, a background-image, not a solid fill) bleeding in from that
+ *   same left edge — plus a second copy of that same glow painted directly
+ *   on every left-pinned cell (however many — the injected AI column and a
+ *   genuinely pinned column can both land in that same sticky group, see
+ *   `effectiveColumnPinning` above), needed because pinning makes each
+ *   `position: sticky` with its own opaque background, so the `<tr>`'s copy
+ *   (anchored to the row's original, unscrolled left edge) would otherwise
+ *   end up hidden behind them once the table scrolls horizontally. Each
+ *   copy is sized via an explicit `backgroundSize` (the row's real total
+ *   width, from `table.getTotalSize()`, not that cell's own narrower one)
+ *   and shifted by `backgroundPositionX: -column.getStart("left")` so it
+ *   shows the exact slice of that same gradient that falls at its actual
+ *   position in the row — the whole pinned group reads as one continuous
+ *   glow, pixel-identical to the unpinned case, rather than a smaller
+ *   version of it; `aiColumnIds` (column level)
+ *   adds the same left-edge glow down the whole column, header cell
+ *   included (every cell in a column shares the same width, so 20% of it
+ *   resolves to the same px value down the whole column, tiling into one
+ *   continuous glow with no visible seam), a colored top rule on that
+ *   column's header cell
+ *   (mirrored by the row's own left edge above), and a leading
+ *   `AILabel` (generic copy) automatically in that header;
+ *   `aiCellPredicate` (cell level) adds just a trailing `AILabel` inline
+ *   after the value — no glow, no border, since a single AI-touched value
+ *   doesn't need its own boundary treatment, only the explainability
+ *   entry point. Every `AILabelTrigger` here follows DataTable's own
+ *   density prop — "default" at default density, "sm" at both sm and xs
+ *   — never AILabel's `iconOnly`, which is opt-in only for when a
+ *   designer explicitly asks for it. Give an AI-marked column enough
+ *   width for its title plus the visible "AI" marker (the header keeps
+ *   both; the title truncates first). Row/column backgrounds use
+ *   `background-image` rather than `box-shadow` specifically for the row
+ *   case — `box-shadow` doesn't paint reliably on `<tr>` in every
+ *   browser, `background-image` does. Compose `AILabel` directly into a
+ *   column's own `header`/`cell` instead of `aiColumnIds` when a column
+ *   needs its own specific explanation text.
+ * - `meta: { align: "left" | "right" }` (default `"left"`) aligns both a
+ *   column's header and its cell content — the guideline is quantitative
+ *   content (amounts, counts, percentages, anything meant to be compared
+ *   or summed down the column) gets `"right"`, text stays `"left"`. Cell
+ *   alignment uses `flex justify-end`, not just `text-align`, so it also
+ *   right-aligns a custom `cell` that renders its own Badge/icon cluster,
+ *   not only plain text. `"right"` mirrors the header too — the sort
+ *   button's label moves to that side and the filter icon/`headerActions`
+ *   cluster moves to the *other* side (`flex-row-reverse` on the same row,
+ *   not a second layout to maintain), so a numeric column's controls sit
+ *   off to the side its digits don't occupy.
+ * - Search matches only `searchableColumnIds` (default: the first two
+ *   entries in `columns`) — set it explicitly to widen/narrow the scope.
+ *   Matches highlight automatically for plain columns (no custom `cell`);
+ *   for a column with a custom `cell`, highlight it yourself with the
+ *   exported `HighlightMatch`, reading the query off
+ *   `info.table.getState().globalFilter`.
+ * - Every column gets a filter icon in its header cell. In the toolbar,
+ *   filters show inline right after search — all of them if there are 3 or
+ *   fewer filterable columns, otherwise just the pinned ones (the first two
+ *   by default, and however many the user pins from the pane after that —
+ *   uncapped, the row wraps onto more lines rather than overflowing) plus
+ *   an "All filters" button, shown whenever there are more than 3
+ *   filterable columns at all — regardless of how many are currently
+ *   pinned inline, even every one of them, since the pane is still the
+ *   only place to *unpin* one. That button opens a docked pane, not a
+ *   floating overlay — the table area (`flex-1`) shrinks to make room for
+ *   it on the surface DataTable sits on, instead of the pane covering the
+ *   table, and reaches that surface's true top/right/bottom edge (measured
+ *   in JS against the nearest Card, since a header/footer's height isn't a
+ *   fixed token) while never growing taller than that surface — its own
+ *   filter-list area is a `min-h-0` flex child so a long list scrolls
+ *   internally instead of pushing the pane past the surface's edge. While
+ *   the pane is open, the inline pinned filter buttons and the "All
+ *   filters" trigger both hide — every filterable column and its current
+ *   value already lives in the pane itself, each with a pin/unpin toggle
+ *   (hover/keyboard-focus-revealed by default, like the header cell's own
+ *   controls — see `revealColumnControlsOnHover`), so there's one place to
+ *   look, not two copies of the same control. `allowFilterPinning` (default
+ *   `true`) turns that toggle off entirely for a designer-fixed toolbar —
+ *   `defaultPinnedFilterIds` (or its first-two default) becomes the
+ *   permanent inline set, with no user-facing way to change which columns
+ *   those are; every other filterable column still lives in the pane, just
+ *   with nothing to move it out. Both the inline pinned chips and the pane
+ *   list order their filterable columns by the table's own column order by
+ *   default; set `meta: { filterOrder: N }` on a `ColumnDef` to decouple a
+ *   filter's display position from where its column currently sits — handy
+ *   when drag-and-drop/the Columns menu can reorder columns but a filter
+ *   should stay put regardless. Once
+ *   any filter is set, the toolbar shows "N filters applied" (every
+ *   applied filter, inline pinned ones included, not just pane-only ones)
+ *   next to a "Clear filters" button that clears all of them the same way
+ *   — the pane's own footer "Clear filters" does the same, just from
+ *   inside the pane. Default filter is text-contains; set
+ *   `meta: { filterVariant: "select" }` on a `ColumnDef` for a
+ *   multi-select filter instead — a checklist in the header icon's own
+ *   popover; a `SelectMultiple` for the inline pinned button (its
+ *   trigger's placeholder is the column label, its value only ever the
+ *   first selected value's label, `maxLabelChars={12}` ellipsis-truncating
+ *   that one past 12 characters even with just one selected, plus "+N"
+ *   once more than one is — so neither a single long value nor a long list
+ *   can run the toolbar out of room) and for the pane (which holds every
+ *   filterable column at once). A multiselect filter (`"select"` or
+ *   `"range"`) always requires a deliberate Apply — in every surface,
+ *   regardless of `filterApplyMode` — since checking several boxes is a
+ *   set to review before committing, not a single complete thought; picks
+ *   still show as checked/selected immediately, on the trigger and in the
+ *   list both — only the real filtering of the table's rows waits for
+ *   Apply, not the visible selection itself. Closed (nothing open to
+ *   preview into), the trigger always reflects whatever's actually
+ *   committed. Its Cancel/Apply footer always lives inside that one
+ *   field's own popover — the header icon's, the inline pinned button's,
+ *   or (in the pane) that field's own, not a pane-wide batch, even though
+ *   the pane holds every filterable column open at once; each field there
+ *   resolves independently, exactly like the toolbar's. `filterVariant:
+ *   "singleSelect"` picks exactly one value from that same kind of list —
+ *   `SelectMultiple` capped at one value (`closeOnSelect`), in every
+ *   surface including the pane, not a native-feeling dropdown — and,
+ *   since it closes the instant a pick is made, is never itself deferred
+ *   regardless of `filterApplyMode` (no open popover left by the time a
+ *   footer could matter). `meta: { filterRender: (props) => node }` is
+ *   the escape hatch past those four built-in shapes — a date-range
+ *   picker, a slider, a radio group, colored selection badges, anything a
+ *   designer's own filter needs — given the same `{ column, value,
+ *   onValueChange }` every built-in variant already receives. Deferred
+ *   under `filterApplyMode="deferred"` in every surface, not just the
+ *   header-icon popover: the inline toolbar button wraps it in a Popover +
+ *   the same shared Cancel/Apply footer text filters get there; the pane —
+ *   which has no popover for any variant — adds an inline Cancel/Apply row
+ *   directly under the rendered content instead. Immediate, every surface
+ *   renders it with no extra chrome, same as always.
+ * - `meta: { filterOnly: true }` defines a column purely to filter a data
+ *   point that isn't shown anywhere in the table — its `header`/`cell`
+ *   never render, and unlike a plain hidden column it has no checkbox
+ *   anywhere to show it (excluded from the Columns menu entirely, not just
+ *   defaulted off), while still showing up as a normal filterable column in
+ *   the "All filters" pane — never inline in the toolbar, and never
+ *   pinnable there either (no header cell for either to point back at).
+ *   Its presence alone forces the pane to exist even when 3 or fewer
+ *   *other* columns are filterable, since the pane is its only access
+ *   point.
+ * - `meta: { filterMergeWith: [...ids] }` folds other columns' filter
+ *   fields into *this* column's own header-icon popover instead of each
+ *   getting a separate toolbar/pane entry — for a cell whose custom `cell`
+ *   already displays more than one filterable value at once (e.g. a name
+ *   plus an MRN below it), so filtering either reads as one decision from
+ *   one icon. Pairs naturally with `filterOnly` on the merged column(s),
+ *   since the value being merged in is usually already folded into this
+ *   column's own `cell` rather than shown in a column of its own — but
+ *   that's a convention, not a requirement. Each merged field renders
+ *   below this column's own (always first, unlabeled), under a divider,
+ *   labeled with its own `header`. The icon fills, and the
+ *   `filterApplyMode="deferred"` footer commits/discards, based on any of
+ *   them having an active filter — not just this column's own.
+ * - Column reordering lives only in the Columns menu, not the header
+ *   cells themselves — drag a row there (a thin primary-colored line
+ *   marks exactly where it'll land) or use its Move left/Move right
+ *   buttons — real, individually focusable/clickable buttons, so no
+ *   custom keyboard handling is needed for them to be keyboard-operable,
+ *   unlike the mouse-only drag. They say left/right, not up/down, even
+ *   though the list itself is vertical — that's what the button actually
+ *   does to the real table, which is what the label should describe, not
+ *   the popover's own incidental layout. Every one of these buttons —
+ *   Move left/right, and (once a column can pin) Pin left/Pin right or
+ *   "Unpin" using the same icons `columnMenuActions` renders in the
+ *   header — is hover/keyboard-focus-revealed by default (see
+ *   `revealColumnControlsOnHover`) and carries its own Tooltip labelling
+ *   it. Once any column is pinned, the list splits into up to three
+ *   sections — pinned left, unpinned/center, pinned right, each separated
+ *   by its own divider — mirroring the same grouping the real header/body
+ *   cells render in; reordering (drag or the Move buttons) stays confined
+ *   to one section at a time, matching what a plain visual drag could
+ *   mean anyway. Moving a column *into* or *out of* a pinned section is
+ *   what the Pin left/Pin right/Unpin buttons are for instead. Past 10
+ *   manageable columns the list grows a search box and scrolls instead of
+ *   pushing the menu taller. Visibility, order, and pinning changes apply
+ *   live as you make them (so the menu's own rows and the real table
+ *   never disagree), but the menu's footer still offers Cancel (reverts
+ *   all three to whatever was committed when the menu opened, including
+ *   if you dismiss it by clicking outside or Escape) and Apply (disabled
+ *   until at least one of the three has actually changed since the menu
+ *   opened) — so the whole session reads as one reviewable batch of
+ *   changes, not silent live edits. "Reset to defaults" sits in that same
+ *   footer, only rendered once order, hidden columns, or pinning have
+ *   actually changed from default — a different comparison than Apply's
+ *   (against the dev-configured default, not against this session's own
+ *   starting point).
+ * - `lockedColumnIds` marks a column as fully static: the user can't
+ *   reorder it (shows a lock glyph instead of a drag handle, and isn't a
+ *   valid drop target) or hide it (the show/hide checkbox doesn't even
+ *   render — `enableHiding: false` is forced regardless of what the
+ *   column's own `ColumnDef` says). Every injected column (selection,
+ *   expand, AI) is always locked. Column-visibility control (the checkbox
+ *   on each row) also only lists columns that don't set
+ *   `enableHiding: false` themselves — non-hideable columns still show up
+ *   for reordering.
+ * - Column pinning: set `meta: { pin: "left" | "right" }` on a `ColumnDef`
+ *   to seed a column's *initial* pinned side. From there it's live,
+ *   user-togglable `@tanstack/react-table` state — wire the exported
+ *   `columnMenuActions` into `meta.headerActions` for a ready-made Pin
+ *   left/Pin right toggle (see below), or call `column.pin(...)` from any
+ *   custom action of your own. Any number of columns can pin to the same
+ *   side at once — they render as a contiguous group at that edge, in the
+ *   order they were pinned (reorderable afterward from the Columns menu,
+ *   confined to that group — see above), with a divider towards whichever
+ *   edge actually borders the scrollable/center columns (the left group's
+ *   right edge, the right group's left edge) on top of the solid
+ *   background every pinned cell already gets so scrolled content doesn't
+ *   show through it. Set `meta: { pinLocked: true }` to keep a column's
+ *   pin fully dev-controlled with no user-facing toggle (`columnMenuActions`
+ *   omits both Pin actions for it — a custom `headerActions` entry could
+ *   still call `column.pin()` on it directly, since this only suppresses
+ *   the built-in affordance, not the underlying state). A pinned column
+ *   renders `position: sticky` at the correct cumulative offset, so it
+ *   stays in view while the rest of the table scrolls horizontally —
+ *   hover/selected/striped row tinting won't show through a pinned cell
+ *   either, a known trade-off of frozen columns. Pinning a real column left
+ *   also pulls the injected AI/expand/selection columns (whichever are
+ *   present) into that same left-pinned group ahead of it, live — so they
+ *   stay genuinely first and sticky too, matching their own "leading slot"
+ *   documentation, instead of being pushed behind a real pinned column the
+ *   moment one exists. Only kicks in once something's actually pinned left;
+ *   otherwise these render exactly as before (unpinned, first in the
+ *   unpinned/center group by definition order — no sticky, no divider).
+ *   Nothing to configure — this is automatic and not itself user-togglable.
+ * - "Sticky first column" isn't its own prop — it's this same pinning
+ *   recipe, combined with `lockedColumnIds` so the user can't unpin or
+ *   reorder it away from that edge: `defaultColumnPinning={{ left: ["id"] }}`
+ *   plus `lockedColumnIds={["id"]}` (see `ColumnManagement`).
+ * - `meta.headerActions` adds custom actions to a column's header cell,
+ *   next to its sort button and filter icon — hidden until that header
+ *   cell is hovered or keyboard-focused (see `revealColumnControlsOnHover`
+ *   below), and rendered with the same exported `RowActions` helper row
+ *   actions use (inline for ≤2 actions, an overflow menu past that),
+ *   uniformly for every column including pinned ones. It's a function of
+ *   `(column, table)`, not a static array, so it can reflect live
+ *   per-column state. The exported `columnMenuActions` is the ready-made
+ *   bundle for this slot — Pin left/Pin right (each becomes "Unpin" once
+ *   pinned to that side, and both are omitted for a `pinLocked` column),
+ *   Hide column, and Fit to content, each omitted when the column can't
+ *   do it. Being 3-4 actions, it renders as a single overflow "more" menu
+ *   in practice — the same shape as a plain custom `headerActions`
+ *   function returning your own `RowAction[]` would, if you need
+ *   something `columnMenuActions` doesn't cover.
+ * - `revealColumnControlsOnHover` (default `true`) is the one knob for
+ *   whether the filter icon, `headerActions`/`columnMenuActions`, and the
+ *   Columns menu's own pin/move controls stay hidden until hovered or
+ *   keyboard-focused, or render always-visible — set `false` for a
+ *   consumer whose final UX calls for every control visible up front.
+ * - `enableColumnResizing` adds a drag handle to every resizable column's
+ *   right border (`ColumnDef.enableResizing: false` exempts one; injected
+ *   columns already are). It's also what unlocks `columnMenuActions`' "Fit
+ *   to content" — that action measures every currently-rendered cell in
+ *   the column (this page's rows, not the whole dataset) via `scrollWidth`
+ *   and sets the column to the widest one found.
+ * - Bulk actions while any row is selected land in one of two places,
+ *   never both:
+ *   - `onLoadMore` (infinite scroll, no footer): the toolbar stays
+ *     mounted and interactive (search, filters) — searching/filtering
+ *     the rows loaded so far while some of them are selected is exactly
+ *     the "load more, then narrow down what's loaded" flow this mode is
+ *     for. Instead, a floating bar hovers over the table's own bottom
+ *     edge (never the raw viewport). Three sections divided by a line:
+ *     count + "Select all" (every filtered row across everything loaded
+ *     so far, not just what's rendered), `renderBulkActions`'s own
+ *     product-configured actions in the middle, and a close button that
+ *     clears the selection. Scrolling to the last row while any row is
+ *     selected reveals extra bottom padding sized to the bar's own
+ *     height — otherwise the last row(s) would stay hidden behind it
+ *     permanently.
+ *   - Paginated (a real footer): no floating bar, and the toolbar's own
+ *     search/filter controls are swapped out in place for the selection
+ *     itself — count, "Select all" (every filtered row across every
+ *     page, not just the current one — same as infinite scroll's own),
+ *     `renderBulkActions`'s actions, then a close button. Search/filters
+ *     act on rows that may not even be the ones selected once paging is
+ *     involved, so showing both the selection and a still-live search
+ *     box read as two competing toolbars — this is the table's original
+ *     selection behavior, kept for exactly that reason.
+ * - `getRowId` (e.g. `(row) => row.id`) gives each row a stable identity
+ *   across a sort/filter/pagination change, passed straight through to
+ *   `@tanstack/react-table` — without it, a row's identity defaults to its
+ *   index, which is meaningless the moment the row set changes underneath
+ *   it (filtering 100 rows down to 30 shouldn't treat "row 3" before and
+ *   after as the same thing unless it actually is).
+ * - Footer is a full-width bar with the current range/total first, then
+ *   "Items per page" (`pageSizeOptions`, default `[10, 20, 30]`; set
+ *   `showPageSizeSelector={false}` to drop it — a design call for tables
+ *   where the consumer shouldn't be choosing page size, not a user
+ *   preference), and — past one page — a jump-to-page select plus
+ *   Previous/Next. It carries the same
+ *   edge-to-edge treatment as the toolbar and `Table` itself, but on all
+ *   three sides it borders — left, right, *and* bottom — so on a Card it
+ *   reads as that Card's own footer (same border-t/bg-muted/rounded-b-xl
+ *   look as a real CardFooter, and it borrows CardFooter's own
+ *   `data-slot` so a surrounding Card zeroes its bottom padding for it
+ *   too).
+ * - `onLoadMore` switches to infinite scroll instead of pagination: every
+ *   row in `data` renders (no client-side page slicing), there's no footer
+ *   at all, and the table scrolls inside its own `maxHeight`-bounded
+ *   container (default `32rem`) instead of the page — the header (and any
+ *   pinned columns) stay locked in place via `position: sticky` while the
+ *   body scrolls. `onLoadMore` fires once an invisible sentinel below the
+ *   last row scrolls near-into view. Fetch the next page and append it to
+ *   `data` yourself; `hasMore` stops rendering the sentinel once there's
+ *   nothing left, and `loadingMore` renders 3 skeleton rows below the last
+ *   real one — same shape as `loading`, not a spinner — while a fetch is
+ *   in flight. Sorting/filtering still run client-side over whatever's
+ *   currently loaded — an inherent limitation with partial data, not
+ *   something this mode solves.
+ *
+ * USAGE
+ * const columns: ColumnDef<Invoice>[] = [
+ *   { accessorKey: "id", header: "Invoice" },
+ *   { accessorKey: "amount", header: "Amount" },
+ *   { accessorKey: "status", header: "Status", meta: { filterVariant: "select" } },
+ * ]
+ *
+ * <DataTable columns={columns} data={invoices} aria-label="Invoices" />
+ *
+ * // Selectable rows with a bulk-delete action — the count (swapped
+ * // into the toolbar here, since this table paginates), "Select all",
+ * // and the close/clear button are all built in; this only fills the
+ * // actions themselves
+ * <DataTable
+ *   columns={columns}
+ *   data={invoices}
+ *   enableRowSelection
+ *   renderBulkActions={(selected, clear) => (
+ *     <Button size="sm" variant="ghost" onClick={() => { onDelete(selected); clear() }}>
+ *       <TrashIcon />
+ *       Delete
+ *     </Button>
+ *   )}
+ * />
+ *
+ * // Row actions (inline for ≤2, overflow menu for >2)
+ * const withActions: ColumnDef<Invoice>[] = [
+ *   ...columns,
+ *   {
+ *     id: "actions",
+ *     header: "",
+ *     size: 72,
+ *     enableSorting: false,
+ *     enableHiding: false,
+ *     enableColumnFilter: false,
+ *     cell: ({ row }) => (
+ *       <RowActions
+ *         actions={[
+ *           { label: "Edit", icon: PencilIcon, onClick: () => onEdit(row.original) },
+ *           { label: "Delete", icon: TrashIcon, variant: "destructive", onClick: () => onDelete(row.original) },
+ *         ]}
+ *       />
+ *     ),
+ *   },
+ * ]
+ *
+ * // Header-cell actions: a fully custom one, for anything columnMenuActions
+ * // doesn't cover
+ * const withHeaderActions: ColumnDef<Invoice>[] = columns.map((col) =>
+ *   col.id === "status"
+ *     ? {
+ *         ...col,
+ *         meta: {
+ *           ...col.meta,
+ *           headerActions: () => [
+ *             { label: "Search", icon: SearchIcon, onClick: () => openColumnSearch("status") },
+ *           ],
+ *         },
+ *       }
+ *     : col
+ * )
+ *
+ * // Column resizing (drag handles) plus the ready-made Pin left/Pin
+ * // right/Hide/Fit-to-content menu on every column
+ * const withColumnMenu: ColumnDef<Invoice>[] = columns.map((col) => ({
+ *   ...col,
+ *   meta: { ...col.meta, headerActions: columnMenuActions },
+ * }))
+ * <DataTable columns={withColumnMenu} data={invoices} enableColumnResizing />
+ *
+ * // Right-align a quantitative column — header and cells both flip
+ * const withAlignedAmount: ColumnDef<Invoice>[] = columns.map((col) =>
+ *   col.id === "amount"
+ *     ? { ...col, meta: { ...col.meta, align: "right" } }
+ *     : col
+ * )
+ *
+ * // Expandable detail row, striping, and column dividers
+ * <DataTable
+ *   columns={columns}
+ *   data={invoices}
+ *   renderExpandedRow={(invoice) => <InvoiceDetailCard invoice={invoice} />}
+ *   striped
+ *   cellDividers
+ * />
+ *
+ * // AI presence at every level (except whole-table — wrap in a Card for that, see below)
+ * <DataTable
+ *   columns={columns}
+ *   data={invoices}
+ *   aiAction={{ label: "Summarize", onClick: () => runAISummary(invoices) }}
+ *   aiRowPredicate={(invoice) => invoice.flaggedByAI}
+ *   aiColumnIds={["amount"]}
+ *   aiCellPredicate={(invoice, columnId) => columnId === "customer" && invoice.customerSuggestedByAI}
+ * />
+ *
+ * // Whole-table AI presence: the table just sits inside an AI Card (the
+ * // same recipe AI/Card's "BoundaryTreatments" story uses) plus a soft glow rising from
+ * // the Card's own bottom edge (bg-ai-glow-bottom, a plain Card className) —
+ * // AILabel in its top corner, never on DataTable's own surface
+ * <div className="rounded-xl bg-gradient-to-r from-ai-wash to-ai-grad-from p-px">
+ *   <Card className="w-full bg-ai-glow-bottom">
+ *     <CardHeader>
+ *       <CardTitle>Invoices</CardTitle>
+ *       <CardAction>
+ *         <AILabel>
+ *           <AILabelTrigger />
+ *           <AILabelContent>...</AILabelContent>
+ *         </AILabel>
+ *       </CardAction>
+ *     </CardHeader>
+ *     <CardContent>
+ *       <DataTable columns={columns} data={invoices} />
+ *     </CardContent>
+ *   </Card>
+ * </div>
+ *
+ * // Loading and error states
+ * <DataTable columns={columns} data={[]} loading />
+ * <DataTable columns={columns} data={[]} error errorDescription="Couldn't reach the server." />
+ *
+ * // Clickable rows (e.g. navigate to a detail view), a locked first column,
+ * // and a wider items-per-page range
+ * <DataTable
+ *   columns={columns}
+ *   data={invoices}
+ *   onRowClick={(invoice) => router.push(`/invoices/${invoice.id}`)}
+ *   lockedColumnIds={["id"]}
+ *   pageSizeOptions={[10, 25, 50]}
+ * />
+ *
+ * // Drop the "Items per page" control from the static footer — page size
+ * // stays fixed at whatever `pageSize` is, not something the user picks
+ * <DataTable columns={columns} data={invoices} showPageSizeSelector={false} />
+ *
+ * // Infinite scroll instead of pagination — no footer
+ * const [invoices, setInvoices] = useState(firstPage)
+ * const [loadingMore, setLoadingMore] = useState(false)
+ * <DataTable
+ *   columns={columns}
+ *   data={invoices}
+ *   hasMore={invoices.length < total}
+ *   loadingMore={loadingMore}
+ *   onLoadMore={async () => {
+ *     setLoadingMore(true)
+ *     setInvoices((current) => [...current, ...await fetchNextPage(current.length)])
+ *     setLoadingMore(false)
+ *   }}
+ * />
+ */
+//# sourceMappingURL=data-table.d.ts.map