@bmsuisse/datagrid 0.23.0

package/dist/index.d.ts

@@ -0,0 +1,1027 @@
+import { ReactNode, ReactElement, ComponentType } from 'react';
+import { ColumnSizingState, RowData } from '@tanstack/react-table';
+export { ColumnSizingState } from '@tanstack/react-table';
+
+/**
+ * Shared filter/sort contract for @bmsuisse/datagrid.
+ *
+ * This shape is intentionally mirrored byte-for-byte (field names and operator
+ * set) by the Python package `bmsdna.datagrid` (see `bmsdna/datagrid/filters.py`)
+ * so that a `GridState` produced by the grid in "server" mode can be serialized
+ * as JSON and handed directly to a FastAPI endpoint that turns it into SQL or a
+ * Meilisearch filter string.
+ */
+/** The full set of operators supported by any FilterDescriptor. */
+type FilterOperator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte" | "in" | "notIn" | "contains" | "doesNotContain" | "startsWith" | "endsWith" | "isEmpty" | "isNotEmpty" | "isNull" | "isNotNull" | "between";
+/**
+ * A single leaf filter condition.
+ *
+ * `field` is either a plain field name, or a pre-qualified path (e.g.
+ * `["c", "customer_name"]` for `c.customer_name` in a join) — the grid never
+ * infers joins, callers pre-qualify ambiguous fields themselves.
+ *
+ * `value` is an array for `in`/`notIn`/`between`, and is omitted entirely for
+ * unary operators like `isNull`/`isNotNull`/`isEmpty`/`isNotEmpty`.
+ */
+interface FilterDescriptor {
+    field: string | string[];
+    operator: FilterOperator;
+    value?: unknown;
+    ignoreCase?: boolean;
+}
+/** Combines two or more filters (leaf or nested composite) with AND/OR logic. */
+interface CompositeFilterDescriptor {
+    logic: "and" | "or";
+    filters: (FilterDescriptor | CompositeFilterDescriptor)[];
+}
+interface SortDescriptor {
+    field: string;
+    dir: "asc" | "desc";
+}
+/** The full sort/filter/pagination state a <DataGrid> tracks and can emit. */
+interface GridState {
+    filter: CompositeFilterDescriptor | null;
+    sort: SortDescriptor[];
+    page: number;
+    pageSize: number;
+}
+/** True for a leaf `FilterDescriptor`, false for a `CompositeFilterDescriptor`. */
+declare function isFilterDescriptor(node: FilterDescriptor | CompositeFilterDescriptor): node is FilterDescriptor;
+/** True for a `CompositeFilterDescriptor`, false for a leaf `FilterDescriptor`. */
+declare function isCompositeFilterDescriptor(node: FilterDescriptor | CompositeFilterDescriptor): node is CompositeFilterDescriptor;
+/** Operators that never carry a `value` (unary presence/absence checks). */
+declare const UNARY_OPERATORS: ReadonlySet<FilterOperator>;
+/** Renders a `field` (string or pre-qualified path) as a single dotted key, for use as a stable id/key. */
+declare function fieldKey(field: string | string[]): string;
+
+/**
+ * Evaluates a filter tree (leaf or composite, or `null`/`undefined` for "no
+ * filter") against a single row. Used by `<DataGrid>` in `"client"` mode;
+ * `"server"` mode never calls this — it trusts the caller already applied
+ * the equivalent filter server-side.
+ */
+declare function evaluateFilter<TRow>(row: TRow, filter: CompositeFilterDescriptor | FilterDescriptor | null | undefined): boolean;
+
+/**
+ * Contract every built-in filter widget implements. `TColumn` is narrowed to
+ * the specific column shape the widget knows how to render (e.g. `EnumColumn`
+ * for `EnumFilter`) — the grid picks the right widget by `column.type` before
+ * handing it a column, so the widget itself never has to branch on `type`.
+ *
+ * `value` is the current FilterDescriptor for this column, or undefined when
+ * no filter is applied. `onChange(undefined)` clears the filter entirely.
+ */
+interface FilterWidgetProps<TColumn> {
+    column: TColumn;
+    value: FilterDescriptor | undefined;
+    onChange: (next: FilterDescriptor | undefined) => void;
+}
+
+/** Horizontal alignment used for a column's cell content and header. */
+type ColumnAlign = "left" | "center" | "right";
+/** Fields shared by every column type, independent of `type`. */
+interface BaseColumn<TRow> {
+    id: string;
+    accessorKey?: keyof TRow & string;
+    accessorFn?: (row: TRow) => unknown;
+    header: string;
+    width?: number;
+    /** Opt-in: defaults to false — must be explicitly set to true to show a sort toggle in the header. */
+    sortable?: boolean;
+    /**
+     * Opt-in: defaults to false, meaning a first click sorts ascending. Set true for a
+     * column whose "interesting" direction is descending — revenue, risk scores, backlog —
+     * so a first click surfaces the highest/most-urgent values first instead of the
+     * lowest/safest ones. Cycles desc -> asc -> none instead of the default asc -> desc -> none.
+     */
+    sortDescFirst?: boolean;
+    /** Opt-in: defaults to false — must be explicitly set to true to show a filter icon/widget in the header. */
+    filterable?: boolean;
+    pinned?: "left" | "right";
+    /** Overrides the default type-based renderer. */
+    cell?: (value: unknown, row: TRow) => ReactNode;
+    /** Free-text group label for <ColumnSelector>; columns sharing a group are shown together. Ungrouped when omitted. */
+    group?: string;
+    /**
+     * Free-text label for a spanning header cell in `<DataGrid>`'s own thead —
+     * unlike `group` above (which only affects `<ColumnSelector>`), this
+     * changes the grid's rendered markup. Contiguous *visible* columns sharing
+     * the same `headerGroup` string get merged under one `colSpan`'d label
+     * cell in an extra row above the normal per-column header row; a column
+     * with no `headerGroup` instead spans both header rows itself (via
+     * `rowSpan`), so it reads as a single ungrouped column rather than leaving
+     * a blank cell above it. Two columns with the same `headerGroup` that
+     * AREN'T adjacent in the visible column order (e.g. a differently-grouped
+     * or ungrouped column sits between them) form two separate spanning cells
+     * with the same label, rather than one — grouping is purely positional,
+     * matching how a caller would read the columns left-to-right.
+     */
+    headerGroup?: string;
+    /**
+     * Overrides the default type-based filter widget (see
+     * `renderDefaultFilterWidget`) for this column. Receives the same
+     * `(value, onChange)` pair the default widget would, plus the grid's full
+     * current `GridState.filter` (every column's combined filter) as a third
+     * argument — needed for a widget like `NumberHistogramFilter`, whose
+     * `allValues` prop must be computed via `facetedNumberValues(data, column,
+     * filter)` to respect every OTHER active filter while excluding this
+     * column's own (see `facetedNumberValues`'s own doc for why). Set this to
+     * close over whatever extra data (e.g. the full unfiltered `data`) the
+     * custom widget needs.
+     */
+    renderFilter?: (value: FilterDescriptor | undefined, onChange: (next: FilterDescriptor | undefined) => void, filter: CompositeFilterDescriptor | null) => ReactNode;
+    /**
+     * Where this column's filter control renders. Defaults to `"popover"`: a
+     * filter-icon button in the header that opens the widget in a popover,
+     * same as every column gets automatically today. `"row"` renders the
+     * widget's content directly, inline, in an additional filter row under
+     * the header instead — needed for a wide control (e.g.
+     * `NumberHistogramFilter`'s slider/histogram) that doesn't fit well
+     * collapsed into the header's compact trigger button. The filter row
+     * itself is entirely opt-in: it only renders at all if at least one
+     * visible, filterable column sets `filterDisplay: "row"`.
+     */
+    filterDisplay?: "popover" | "row";
+    /**
+     * Overrides the plain-text `header` rendering *inside* the header cell's
+     * sort toggle `<button>` (the sort caret still renders alongside it, and
+     * still inside that same button). Use this for a header that needs a
+     * tooltip, an info icon, a loading spinner tied to a separate
+     * batch-hydration fetch, or any other rich content — `header` itself
+     * stays a plain string (used for the filter icon's `aria-label` and by
+     * `<ColumnSelector>`, neither of which can work off a ReactNode).
+     *
+     * Whatever this returns is nested inside a real `<button>` — don't return
+     * another focusable/interactive element (a nested `<button>`, a link, a
+     * tooltip trigger that itself renders as a `<button>`) or the browser will
+     * split the outer button apart, breaking click-to-sort for that column.
+     * If the return value is non-textual (an icon with no visible label), the
+     * button's accessible name is whatever text content survives inside it —
+     * add your own `aria-label` inside the returned content if there isn't
+     * any, since `<DataGrid>` has no way to tell your content lacks one.
+     */
+    renderHeader?: (column: BaseColumn<TRow>) => ReactNode;
+}
+type StringColumn<TRow> = BaseColumn<TRow> & {
+    type: "string";
+};
+type NumberColumn<TRow> = BaseColumn<TRow> & {
+    type: "number" | "currency";
+    currency?: string;
+};
+type DateColumn<TRow> = BaseColumn<TRow> & {
+    type: "date" | "datetime";
+};
+type BooleanColumn<TRow> = BaseColumn<TRow> & {
+    type: "boolean";
+};
+interface EnumOption {
+    value: string;
+    label: string;
+}
+type EnumColumn<TRow> = BaseColumn<TRow> & {
+    type: "enum";
+    options: EnumOption[];
+};
+/** Discriminated union of every supported column shape, keyed on `type`. */
+type ColumnDef<TRow> = StringColumn<TRow> | NumberColumn<TRow> | DateColumn<TRow> | BooleanColumn<TRow> | EnumColumn<TRow>;
+/** Resolves a column's raw cell value from a row, via `accessorFn` or `accessorKey`. */
+declare function getColumnValue<TRow>(column: ColumnDef<TRow>, row: TRow): unknown;
+/** True only if a column explicitly opts in (`sortable: true`) — the default is false. */
+declare function isSortable<TRow>(column: ColumnDef<TRow>): boolean;
+/** True only if a column explicitly opts in (`filterable: true`) — the default is false. */
+declare function isFilterable<TRow>(column: ColumnDef<TRow>): boolean;
+
+/**
+ * Default filter widget for `type: "boolean"` columns: a 3-way All/Yes/No
+ * select.
+ *
+ * `bare` (default `false`) skips this component's own Popover/trigger
+ * Button, rendering just the select directly — see `EnumFilter`'s identical
+ * `bare` doc for why (`renderDefaultFilterWidget` passes this automatically
+ * outside `filterDisplay: "row"`).
+ */
+declare function BooleanFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<BooleanColumn<TRow>> & {
+    bare?: boolean;
+}): ReactElement;
+
+/**
+ * Default filter widget for `type: "date"` / `type: "datetime"` columns: a
+ * date-range picker with Today / Last 7 days / This month presets, plus a
+ * calendar for a custom range. Always emits the `between` operator
+ * (inclusive both ends, matching evaluateFilter/sql.py/meili.py semantics).
+ *
+ * `today` defaults to the real current date; it's exposed as a prop purely
+ * so tests can pin preset computation to a fixed date without mocking the
+ * system clock (and the timer machinery that comes with that).
+ *
+ * `bare` (default `false`) skips this component's own Popover/trigger
+ * Button, rendering just the presets + calendar directly — see
+ * `EnumFilter`'s identical `bare` doc for why (`renderDefaultFilterWidget`
+ * passes this automatically outside `filterDisplay: "row"`).
+ */
+declare function DateRangeFilter<TRow>({ column, value, onChange, today, bare, }: FilterWidgetProps<DateColumn<TRow>> & {
+    today?: Date;
+    bare?: boolean;
+}): ReactElement;
+
+/**
+ * Default filter widget for `type: "enum"` columns: a single Excel-style
+ * checkbox list, regardless of how many `column.options` there are (no
+ * short-list/long-list branch) —
+ *
+ * - a search input filters which options *render* below via a plain
+ *   substring match against each option's label; it never touches the
+ *   committed filter on its own.
+ * - a tri-state "Select all" checkbox acts on whatever subset is currently
+ *   visible after that search, not the full option set — matching Excel's
+ *   own column-filter behavior ("select all of what's shown").
+ * - every visible option gets its own plain checkbox + label row (a real
+ *   shadcn `Checkbox`, not a menu item), inside a scrollable list so long
+ *   option lists don't blow up the popover's height.
+ * - every toggle emits the updated `FilterDescriptor` immediately — there's
+ *   no OK/Cancel step, matching every other filter widget in this package.
+ *
+ * `bare` (default `false`) skips this component's own Popover/trigger
+ * Button, rendering just the search input + option list directly — for a
+ * caller that already provides its own popover/collapsible (this is what
+ * `renderDefaultFilterWidget` passes automatically outside `filterDisplay:
+ * "row"`, so `<DataGrid>`'s own header-icon popover isn't nested inside a
+ * second one of this component's own).
+ */
+declare function EnumFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<EnumColumn<TRow>> & {
+    bare?: boolean;
+}): ReactElement;
+
+/**
+ * An Excel-style alternative to the default `NumberRangeFilter`: an operator
+ * dropdown (Greater than / Less than / Equals / ... / Between) plus one
+ * number input (two for `Between`), instead of a plain always-visible
+ * min/max range. Not wired up as any column type's automatic default —
+ * `NumberRangeFilter` still is, so existing columns keep their current
+ * behavior. Use this directly as a column's custom filter UI (see
+ * `BaseColumn.renderFilter`) for a numeric column where users think in
+ * terms of "greater than X" rather than "between X and Y".
+ *
+ * Local `operator`/text state (rather than deriving straight from `value`
+ * on every render, the way `StringFilter` does) is what lets `Between` hold
+ * a partially-typed pair — deriving directly would wipe whatever's in the
+ * OTHER box the instant the first box's own edit clears `value` back to
+ * `undefined` (no filter is emitted until both bounds parse), and would
+ * reset the operator dropdown back to the default the same way. The effect
+ * below only resyncs from `value` when it changed for some reason other
+ * than this widget's own last `onChange` call (an external clear-all, or
+ * restoring a saved view) — the same pattern `NumberRangeFilter` uses for
+ * the same reason.
+ *
+ * `bare` (default `true`) skips this component's own Popover/trigger
+ * Button, rendering just the operator + input(s) directly — correct under
+ * the default `filterDisplay: "popover"`, where `<DataGrid>` already
+ * supplies the header filter icon and popover; passing `false` there would
+ * nest a second, redundant one inside it. Pass `bare={false}` only when the
+ * column also sets `filterDisplay: "row"`, where nothing else provides a
+ * trigger — see `NumberHistogramFilter`'s identical `bare` doc for why.
+ */
+declare function NumberComparisonFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<NumberColumn<TRow>> & {
+    bare?: boolean;
+}): ReactElement;
+
+/**
+ * Default filter widget for `type: "number"` / `type: "currency"` columns: a
+ * min/max range. Emits `between` when both bounds are set (reordered so the
+ * lower bound is always <= the upper bound), or `gte`/`lte` when only one
+ * is — all three are evaluated identically by evaluateFilter and sql.py/
+ * meili.py.
+ *
+ * The two input boxes track their own local text rather than deriving
+ * straight from `value` on every render. If they derived from `value`
+ * directly, reordering an inverted min/max (see above) would relocate
+ * whatever the user just typed into the *other* box on the very next
+ * render — so typing "99" into Min then "9" then "9" into Max (intending
+ * "99") would see Max flip to "99" after the first "9" (since a swap makes
+ * it the new max), and the second "9" would land in the now-relocated box,
+ * producing "909" instead of "99". Keeping local text means what's on
+ * screen always matches exactly what was typed, independent of how the
+ * emitted FilterDescriptor's bounds get reordered.
+ *
+ * `bare` (default `false`) skips this component's own Popover/trigger
+ * Button, rendering just the two inputs directly — see `EnumFilter`'s
+ * identical `bare` doc for why (`renderDefaultFilterWidget` passes this
+ * automatically outside `filterDisplay: "row"`). Under `filterDisplay:
+ * "row"`, the min/max boxes are always visible at their natural width
+ * regardless of a narrower column — wrapping them in a compact trigger
+ * (bare: false) is what keeps a plain numeric column from forcing its whole
+ * column wider than its data ever needs.
+ */
+declare function NumberRangeFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<NumberColumn<TRow>> & {
+    bare?: boolean;
+}): ReactElement;
+
+type NumberHistogramValuesProps = {
+    /**
+     * The full set of values to compute the histogram and slider domain
+     * from.
+     *
+     * MUST be computed excluding this column's OWN active filter (every
+     * other active filter is fine, even expected — see
+     * `facetedNumberValues`, which computes exactly this). Passing values
+     * already narrowed by this same filter reproduces the bug this
+     * component's design exists to prevent: the domain shrinks every time
+     * the user adjusts the range, so they can never widen it back out, and
+     * (if the same "all rows" array is reused across multiple numeric
+     * columns) filtering one column warps every other numeric column's
+     * histogram too.
+     *
+     * Use this (not `loadValues`) whenever the full, facet-safe row set is
+     * already in memory — e.g. `<DataGrid>` in `"client"` mode.
+     */
+    allValues: (number | null | undefined)[];
+    loadValues?: never;
+} | {
+    allValues?: never;
+    /**
+     * Fetches the histogram/slider domain values on demand, called every
+     * time the popover opens (not cached across opens, since every OTHER
+     * active filter — which the fetch should itself respect — may have
+     * changed since the last time it was open).
+     *
+     * Use this instead of `allValues` whenever the facet-safe row set
+     * ISN'T already in memory — the standard case for `<DataGrid>` in
+     * `"server"` mode, where the rows the grid holds are just the current
+     * page, already narrowed by every active filter (including this
+     * column's own), and therefore never safe to pass as `allValues`
+     * directly. Typically this closes over a caller's own "fetch facet
+     * values for this column, given every other active filter" endpoint.
+     */
+    loadValues: () => Promise<(number | null | undefined)[]>;
+};
+type NumberHistogramFilterProps<TRow> = FilterWidgetProps<NumberColumn<TRow>> & NumberHistogramValuesProps & {
+    /** Formats a bound for display. Defaults to `toLocaleString()`. */
+    format?: (value: number) => string;
+    /** Number of histogram bars. Defaults to 24. */
+    buckets?: number;
+    /**
+     * Set this to `false` only when the column also sets `filterDisplay:
+     * "row"` — there, nothing else provides a trigger, so this needs its
+     * own Popover + Button to avoid permanently expanding the histogram
+     * inline in the filter row. Defaults to `true` (bare: no own Popover/
+     * Button, just the histogram/slider/inputs/clear content) because a
+     * custom `BaseColumn.renderFilter` is normally reached for under the
+     * *default* `filterDisplay: "popover"`, where `<DataGrid>` already
+     * renders a header filter icon that opens a popover around whatever
+     * `renderFilter` returns — passing `false` there nests a second,
+     * redundant Popover+Button inside the first, so opening the header
+     * icon shows nothing but another filter icon to click, not the
+     * histogram. There's no `open`/`onOpenChange` state at this level in
+     * bare mode — the component simply renders as always-open; the
+     * caller's own popover is what mounts/unmounts it.
+     */
+    bare?: boolean;
+};
+/**
+ * A richer alternative to the default `NumberRangeFilter`: a log-scale
+ * histogram behind a dual-thumb range slider, plus min/max text inputs.
+ * Not wired up as any column type's automatic default (unlike
+ * `NumberRangeFilter`) — it needs `allValues`/`loadValues` (see above),
+ * which the grid itself doesn't have a way to supply automatically yet, so
+ * use it directly as a column's custom filter UI (see `BaseColumn.renderFilter`).
+ * By default (`bare` unset) this renders bare — just the histogram/slider/
+ * inputs, no own trigger/popover — correct under the default `filterDisplay:
+ * "popover"`, where `<DataGrid>` already supplies the header filter icon and
+ * popover. Pass `bare={false}` when the column also sets `filterDisplay:
+ * "row"`, where nothing else provides a trigger. Compute `allValues` via
+ * `facetedNumberValues(data, column, filter)` in client mode, or supply
+ * `loadValues` to fetch the facet from the server in server mode.
+ */
+declare function NumberHistogramFilter<TRow>({ column, value, onChange, allValues, loadValues, format, buckets, bare, }: NumberHistogramFilterProps<TRow>): ReactElement;
+
+type FilterNode = FilterDescriptor | CompositeFilterDescriptor;
+/**
+ * Computes the correct `allValues` input for `NumberHistogramFilter` bound
+ * to `column`: `data` filtered by every OTHER currently-active filter, with
+ * `column`'s own filter excluded, then that column's values extracted.
+ *
+ * This exists to prevent a specific, easy-to-reach bug: computing a filter
+ * widget's own histogram/slider domain from a row set that's already been
+ * narrowed BY that same filter means the domain shrinks every time the user
+ * adjusts the range — they can never widen it back out — and if one "all
+ * values" computation is naively reused across multiple numeric columns
+ * (e.g. from `table.getFilteredRowModel()`), setting a filter on column A
+ * also warps column B's histogram, since B's domain was computed from rows
+ * A already excluded. This is the standard "faceted search" fix: a filter's
+ * own facet should reflect "what could I select if I changed just this
+ * filter," never a result set that filter has already narrowed.
+ *
+ * `filter` is the grid's full `GridState.filter` (every column's combined
+ * filter) — pass it as-is; this function does the excluding.
+ */
+declare function facetedNumberValues<TRow>(data: readonly TRow[], column: ColumnDef<TRow>, filter: FilterNode | null | undefined): (number | null)[];
+
+/**
+ * Default filter widget for `type: "string"` columns: a text input plus an
+ * operator dropdown.
+ *
+ * `bare` (default `false`) skips this component's own Popover/trigger
+ * Button, rendering just the operator + input directly — see `EnumFilter`'s
+ * identical `bare` doc for why (`renderDefaultFilterWidget` passes this
+ * automatically outside `filterDisplay: "row"`).
+ */
+declare function StringFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<StringColumn<TRow>> & {
+    bare?: boolean;
+}): ReactElement;
+
+/**
+ * Picks and renders the default filter widget for a column, based purely on
+ * `column.type`. This is what makes filtering "just work" without a column
+ * having to configure anything — the discriminated union on `type` lets each
+ * branch narrow `column` to the exact widget it needs.
+ *
+ * Every default widget has its own self-contained Popover+trigger Button
+ * (needed under `filterDisplay: "row"`, where nothing else provides one) —
+ * everywhere else, `<DataGrid>`'s own header filter icon already opens a
+ * popover around whatever this function returns, so passing `bare: true`
+ * there (this function is `<DataGrid>`'s only caller, and always knows
+ * `column.filterDisplay` already) is what keeps that from nesting a second
+ * popover inside the first.
+ */
+declare function renderDefaultFilterWidget<TRow>(column: ColumnDef<TRow>, value: FilterDescriptor | undefined, onChange: (next: FilterDescriptor | undefined) => void): ReactElement;
+
+/** The default horizontal alignment for a column, based purely on its `type`. */
+declare function defaultAlign<TRow>(column: ColumnDef<TRow>): ColumnAlign;
+/** The literal Tailwind class for a column's default alignment; see `defaultAlign`. */
+declare function alignClassName<TRow>(column: ColumnDef<TRow>): string;
+/**
+ * Renders a raw cell value as a display string, using the type-appropriate
+ * default formatter for `column.type`. Columns with a custom `cell` render
+ * function bypass this entirely — it only backs the built-in renderer.
+ */
+declare function defaultFormat<TRow>(column: ColumnDef<TRow>, value: unknown): string;
+
+/**
+ * Column visibility keyed by `ColumnDef.id`. A missing key means visible —
+ * this matches TanStack Table's own `VisibilityState` convention, so a
+ * `ColumnVisibility` value can be handed straight to a TanStack table's
+ * `state.columnVisibility` if a consumer ever needs to.
+ */
+type ColumnVisibility = Record<string, boolean>;
+
+interface ColumnSelectorProps<TRow> {
+    columns: ColumnDef<TRow>[];
+    visibility: ColumnVisibility;
+    onVisibilityChange: (visibility: ColumnVisibility) => void;
+    /** If set: restore from localStorage on mount, and persist on every subsequent change. */
+    persistKey?: string;
+    /** Optional custom trigger; defaults to a "Columns" icon button. */
+    trigger?: ReactNode;
+    /** Optional controlled open state, for callers that want their own trigger entirely. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * Controlled column-visibility selector: a modal listing every column,
+ * grouped by `column.group` into side-by-side columns (ungrouped columns
+ * first, unlabeled, matching `groupColumns`' own ordering), wrapping onto a
+ * new row rather than growing the dialog past a reasonable width. Each named
+ * group's header is a plain muted label — no bulk-select affordance of any
+ * kind lives there (an earlier version had a tri-state checkbox, then an
+ * "All"/"None" link pair, both dropped; see AGENTS.md for why). Purely
+ * controlled by `visibility`/`onVisibilityChange` — `persistKey`
+ * layers an optional localStorage sync on top (restore once on mount, write
+ * on every change), it never becomes the source of truth in place of the
+ * `visibility` prop.
+ *
+ * Not rendered inside `<DataGrid>` automatically — wire it up next to the
+ * grid yourself, e.g.:
+ *
+ * ```tsx
+ * const [visibility, setVisibility] = useState<ColumnVisibility>({});
+ * <ColumnSelector columns={columns} visibility={visibility} onVisibilityChange={setVisibility} persistKey="orders" />
+ * <DataGrid columns={columns} columnVisibility={visibility} onColumnVisibilityChange={setVisibility} ... />
+ * ```
+ */
+declare function ColumnSelector<TRow>({ columns, visibility, onVisibilityChange, persistKey, trigger, open, onOpenChange, }: ColumnSelectorProps<TRow>): ReactElement;
+
+/** A missing key means visible, matching TanStack's own VisibilityState convention. */
+declare function isColumnVisible(visibility: ColumnVisibility, columnId: string): boolean;
+/** How many of `columns` are currently visible under `visibility`. */
+declare function countVisible<TRow>(columns: readonly ColumnDef<TRow>[], visibility: ColumnVisibility): number;
+interface ColumnGroup<TRow> {
+    /** undefined for the ungrouped section, which is always listed first. */
+    group: string | undefined;
+    columns: ColumnDef<TRow>[];
+}
+/**
+ * Groups columns by `column.group`, preserving each group's first-seen order
+ * and each column's original order within its group. The ungrouped section
+ * (columns with no `group`) is always returned first, regardless of where
+ * ungrouped columns actually fall in the input order.
+ */
+declare function groupColumns<TRow>(columns: readonly ColumnDef<TRow>[]): ColumnGroup<TRow>[];
+/** Whether toggling `columnId` off is currently allowed (must leave at least one column visible). */
+declare function canHideColumn<TRow>(columns: readonly ColumnDef<TRow>[], visibility: ColumnVisibility, columnId: string): boolean;
+/** Whether hiding every column in `groupColumnIds` at once is currently allowed. */
+declare function canHideGroup<TRow>(columns: readonly ColumnDef<TRow>[], visibility: ColumnVisibility, groupColumnIds: readonly string[]): boolean;
+
+declare function storageKeyFor(persistKey: string): string;
+
+/** The row/selection context a menu item's visible/disabled/onSelect handlers are evaluated against. */
+interface MenuItemContext<TRow> {
+    row?: TRow;
+    selectedRows?: TRow[];
+}
+/**
+ * A single entry in a row-actions (per-row kebab menu) or header-actions
+ * (toolbar) menu. `rowActions` items are evaluated with `ctx.row` set;
+ * `headerActions` items are evaluated with `ctx.selectedRows` set (whatever
+ * the grid's current selection is, possibly empty).
+ */
+interface MenuItem<TRow> {
+    id: string;
+    label: string;
+    icon?: ComponentType;
+    danger?: boolean;
+    /** Defaults to always visible when omitted. */
+    visible?: (ctx: MenuItemContext<TRow>) => boolean;
+    /** Defaults to always enabled when omitted. */
+    disabled?: (ctx: MenuItemContext<TRow>) => boolean;
+    onSelect: (ctx: MenuItemContext<TRow>) => void;
+}
+
+/** A `MenuItem` with its `visible`/`disabled` predicates already evaluated against a context. */
+interface ResolvedMenuItem<TRow> extends MenuItem<TRow> {
+    isDisabled: boolean;
+}
+/**
+ * Evaluates each item's `visible`/`disabled` predicates against `ctx` (both
+ * default to "always" when omitted), dropping items that aren't visible and
+ * annotating the rest with `isDisabled`. Pure and UI-free on purpose, so the
+ * gating logic itself — as opposed to the DropdownMenu rendering built on
+ * top of it — can be unit-tested directly.
+ */
+declare function resolveMenuItems<TRow>(items: readonly MenuItem<TRow>[], ctx: MenuItemContext<TRow>): ResolvedMenuItem<TRow>[];
+
+interface ActionsMenuProps<TRow> {
+    items: readonly MenuItem<TRow>[];
+    ctx: MenuItemContext<TRow>;
+    /** Accessible label for the trigger button, e.g. "Row actions" or "Bulk actions". */
+    triggerLabel: string;
+}
+/**
+ * Shared rendering for both `rowActions` (per-row kebab menu) and
+ * `headerActions` (toolbar menu) — they differ only in what `ctx` they're
+ * evaluated against (`{ row }` vs `{ selectedRows }`) and the trigger's
+ * accessible label, so <DataGrid> passes those in rather than this module
+ * having two near-identical components.
+ */
+declare function ActionsMenu<TRow>({ items, ctx, triggerLabel }: ActionsMenuProps<TRow>): ReactElement | null;
+
+/**
+ * `"client"`: the grid owns filtering/sorting/pagination and evaluates them
+ * in-memory against the full `data` array (via `evaluateFilter`).
+ *
+ * `"server"`: `data` is just the current page, already filtered/sorted by
+ * the caller; the grid calls `onStateChange` on every sort/filter/page
+ * change (debounced ~300ms for filter changes) and trusts the result — it
+ * never re-filters/re-sorts server-mode data itself.
+ */
+type DataSource<TRow> = {
+    mode: "client";
+    data: TRow[];
+} | {
+    mode: "server";
+    data: TRow[];
+    rowCount: number;
+    loading?: boolean;
+    onStateChange: (state: GridState) => void;
+};
+interface DataGridVirtualizeOptions {
+    /** Enables row virtualization once the row count exceeds this threshold. Defaults to 100. Set to 0 to always virtualize, or Infinity to never. */
+    threshold?: number;
+    /** Fixed row height estimate in pixels, used by the virtualizer. Defaults to 40. */
+    estimatedRowHeight?: number;
+    /** Max height of the scrollable table body in pixels. Required for virtualization to have a viewport to scroll within. Defaults to 480. */
+    maxBodyHeight?: number;
+    /** Extra rows rendered beyond the viewport on each side. Defaults to 10. */
+    overscan?: number;
+    /**
+     * Called once when scrolling reaches the last currently loaded row — the
+     * caller's job to fetch more and grow `dataSource.data`; `<DataGrid>`
+     * doesn't own pagination state in this mode (works with `"client"` and
+     * `"server"` `DataSource` alike, since it's purely about *rendering*, not
+     * fetching). Won't fire again for the same `data` length — only once
+     * `data` actually grows (or shrinks and regrows) does another scroll to
+     * the end re-fire it.
+     */
+    onEndReached?: () => void;
+    /** Whether more rows exist beyond what's currently loaded. `onEndReached` never fires while this is `false`. Defaults to `true`. */
+    hasMore?: boolean;
+}
+interface DataGridProps<TRow> {
+    columns: ColumnDef<TRow>[];
+    dataSource: DataSource<TRow>;
+    getRowId: (row: TRow) => string;
+    /**
+     * Shows a full-overlay spinner over the grid's scrollable body, positioned as a
+     * sibling of it (not a child) so it stays fixed over the visible viewport instead of
+     * scrolling away with the table content. Independent of `dataSource.mode === "server"`'s
+     * own `loading` flag (which only affects the empty-state text) — this works for
+     * `"client"` mode too, for a caller whose own `data` array is still being fetched.
+     * The two are OR'd together if both happen to be set. Defaults to `false`.
+     */
+    loading?: boolean;
+    /** Per-row kebab menu. Evaluated with `ctx.row` set to that row. */
+    rowActions?: MenuItem<TRow>[];
+    /** Toolbar menu above the table. Evaluated with `ctx.selectedRows` set. */
+    headerActions?: MenuItem<TRow>[];
+    /** Allows shift-click to add a secondary sort column instead of replacing. Defaults to false. */
+    enableMultiSort?: boolean;
+    /** Initial sort/filter/page/pageSize, e.g. restored from a URL. Defaults to no filter, no sort, page 0, pageSize 20. Only read once, at mount — see `gridState` to push updates in afterward. */
+    initialState?: Partial<GridState>;
+    /**
+     * Pushes a full `GridState` into the grid from outside, overriding
+     * whatever it currently has — the one way to change sort/filter/page
+     * programmatically after mount without remounting `<DataGrid>` (e.g. via
+     * a changing `key`). Omit entirely for the grid to fully own its own
+     * state, seeded once from `initialState`. Typical server-mode usage
+     * mirrors every `dataSource.onStateChange` call into your own state and
+     * passes that same value back in here — a fresh object literal recreated
+     * on every render instead re-triggers this resync every render, so don't
+     * inline a new one; pass the state variable you're already keeping in
+     * sync from `onStateChange`. Like a controlled `<input>`: decide once
+     * whether a given `<DataGrid>` is controlled this way and stay there for
+     * its whole lifetime — toggling this to `undefined` later doesn't hand
+     * control back, it just stops resyncing.
+     */
+    gridState?: GridState;
+    /**
+     * Controlled column visibility, e.g. driven by a `<ColumnSelector>` next
+     * to the grid. Both must be supplied together to actually hide columns —
+     * <DataGrid> never owns this state itself, matching how it never owns
+     * GridState's persistence either.
+     */
+    columnVisibility?: ColumnVisibility;
+    onColumnVisibilityChange?: (visibility: ColumnVisibility) => void;
+    /**
+     * Enables an expand/collapse chevron in a dedicated leftmost column; when
+     * a row is expanded, its result is rendered directly below that row, in
+     * its own full-width `<tr>`. Omit entirely to disable — no chevron column
+     * renders at all. Multiple rows can be expanded simultaneously (there's
+     * no single-row-at-a-time constraint). Combined with `virtualize`: only
+     * the row's own height is dynamically measured, not the expanded detail
+     * panel's — size `virtualize.estimatedRowHeight` generously if rows are
+     * commonly expanded in a virtualized grid, or expect some visual overlap.
+     */
+    renderDetail?: (row: TRow) => ReactNode;
+    /**
+     * Enables row virtualization (`@tanstack/react-virtual`) once the row
+     * count crosses `threshold`. Omit entirely for a plain, fully-rendered
+     * `<table>` (the default) — most grids never need this; it's for the ones
+     * with hundreds+ of rows where rendering every `<tr>` becomes the
+     * bottleneck.
+     */
+    virtualize?: DataGridVirtualizeOptions;
+    /**
+     * Opt-in: defaults to false. When true, every column gets a drag handle
+     * on its trailing edge to resize it, and every column (not just ones with
+     * an explicit `width`) gets a concrete pixel width — TanStack Table's own
+     * `size: 150` default for any column that doesn't set one, same as if you
+     * typed `width: 150` yourself. That's an intentional trade of "natural,
+     * content-driven column widths" for "every column resizable," so only
+     * turn this on for a grid that actually needs manual column resizing.
+     */
+    enableColumnResizing?: boolean;
+    /** `"onChange"` (default) commits width live while dragging; `"onEnd"` commits once on release. */
+    columnResizeMode?: "onChange" | "onEnd";
+    /**
+     * Controlled column widths, e.g. persisted the same way `columnVisibility`
+     * might be. Both must be supplied together to actually drive sizing —
+     * omit both to let `<DataGrid>` manage resize state internally.
+     */
+    columnSizing?: ColumnSizingState;
+    onColumnSizingChange?: (sizing: ColumnSizingState) => void;
+    /**
+     * Renders the built-in Previous/Next pagination footer. Defaults to true.
+     * Set to false when a caller renders its own pagination UI instead (e.g.
+     * one with specific `data-testid`s an existing test suite depends on) —
+     * `<DataGrid>` itself never conditions any other behavior on this, it just
+     * stops rendering that one footer.
+     */
+    showPagination?: boolean;
+    /**
+     * Controlled row selection, e.g. so a caller can build its own toolbar
+     * (a bulk-export button, a "N selected" count) elsewhere on the page
+     * instead of only reacting to selection via `headerActions`' `onSelect`
+     * closure. Both must be supplied together to actually control it — omit
+     * both to let `<DataGrid>` manage selection state internally (the
+     * default, unchanged from before this existed).
+     */
+    selectedIds?: ReadonlySet<string>;
+    onSelectedIdsChange?: (ids: ReadonlySet<string>) => void;
+    /**
+     * Extra props (className, onClick, data-* attributes, etc.) spread onto a
+     * row's own `<tr>`. Applied AFTER `<DataGrid>`'s own `data-testid`/
+     * `data-index`/`ref`, so those stay intact even if this returns keys that
+     * would otherwise collide — use it to make a whole row clickable (an
+     * `onClick` `<DataGrid>` has no other way to express — `rowActions` is a
+     * kebab menu, not a row-wide click target), or to attach a `className`/
+     * other `data-*` attribute an existing test suite already depends on. A
+     * `data-testid` returned here specifically is NOT one of those — see
+     * `getRowTestId` below for overriding that one. Typed
+     * as a plain `Record` (not `HTMLAttributes<HTMLTableRowElement>`) since
+     * that interface has no index signature — a return value with only
+     * `data-*` keys and no standard HTML attributes would fail TypeScript's
+     * "no properties in common" excess-property check against it.
+     *
+     * `onClick` specifically is safe to combine with `renderDetail`'s expand
+     * chevron, a `rowActions` kebab, or `selectedIds`' checkbox — each of
+     * those controls stops its own click from bubbling up to this `onClick`.
+     * That guard only covers `click`, though: an `onMouseDown`/`onDoubleClick`/
+     * `onContextMenu` returned here would still fire from inside any of those
+     * controls too, since nothing stops those event types from bubbling.
+     */
+    getRowProps?: (row: TRow) => Record<string, unknown>;
+    /**
+     * Overrides the per-row `data-testid` (default `row-${getRowId(row)}`).
+     * Note this is NOT something `getRowProps` above can do despite what its
+     * own doc says about "a caller-specific data-testid" — `<DataGrid>` always
+     * re-applies its own `data-testid` after spreading `getRowProps`'s result,
+     * specifically so a colliding key there can't accidentally break e2e
+     * selectors depending on the default `row-${id}` convention. Use this prop
+     * instead when a consumer's existing test suite selects rows by a
+     * different, entity-specific convention (e.g. `import-row-${id}`) that
+     * predates adopting `<DataGrid>` — lets that suite need zero changes.
+     */
+    getRowTestId?: (row: TRow) => string;
+    /**
+     * `data-testid` for the table's own scrollable container (the element
+     * `virtualize.maxBodyHeight` actually applies to, and — with or without
+     * virtualization — the element horizontal overflow scrolls within). Omit
+     * for no attribute at all. Useful for an e2e test that needs to scroll
+     * this specific grid or assert on its scroll position; the outer
+     * `data-testid="datagrid"` wrapper isn't it, and isn't unique per grid on
+     * a page with more than one.
+     */
+    testId?: string;
+}
+
+/**
+ * A single React Table component covering both client- and server-driven
+ * data: filtering, sorting, and pagination all flow through one `GridState`,
+ * with `dataSource.mode` deciding whether the grid computes the visible page
+ * itself (`"client"`) or trusts a page the caller already computed
+ * (`"server"`). Column filter UI defaults to the type-appropriate widget
+ * from `src/filter` unless a column supplies its own `cell` renderer.
+ */
+declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, }: DataGridProps<TRow>): ReactElement;
+
+interface GridStateController {
+    state: GridState;
+    /** Per-column FilterDescriptor, keyed by column id. */
+    filtersByColumn: ReadonlyMap<string, FilterDescriptor>;
+    setColumnFilter: (columnId: string, next: FilterDescriptor | undefined) => void;
+    /**
+     * Cycles a column's sort: none -> asc -> desc -> none, or none -> desc -> asc -> none
+     * when `descFirst` is true (see `BaseColumn.sortDescFirst`) — for a column whose
+     * "interesting" direction is descending (revenue, risk scores, backlog), so a first
+     * click surfaces the highest/most-urgent values instead of the lowest/safest ones.
+     * Adds/replaces per `enableMultiSort`.
+     */
+    toggleSort: (columnId: string, additive: boolean, descFirst?: boolean) => void;
+    setPage: (page: number) => void;
+    setPageSize: (pageSize: number) => void;
+}
+/**
+ * Owns `GridState` (filter/sort/page/pageSize) for `<DataGrid>` and, in
+ * `"server"` mode, calls `dataSource.onStateChange` on every change —
+ * debounced ~300ms for filter changes (typing), immediately for sort/page
+ * changes. In `"client"` mode `onStateChange` doesn't exist and is never
+ * called; the grid re-filters/re-sorts the in-memory array itself instead.
+ *
+ * Deliberately takes no `columns` and enforces no `sortable`/`filterable`
+ * policy itself — `toggleSort`/`setColumnFilter` will happily act on any
+ * column id passed to them. `<DataGrid>` is the only place that consults
+ * `isSortable`/`isFilterable` (in its rendered header, gating the sort
+ * button's `onClick` and whether a filter icon renders at all), because this
+ * hook is a generic state container, not a per-column-policy enforcer. A
+ * caller that imports this hook directly (bypassing <DataGrid>'s UI
+ * entirely) is responsible for applying that same policy itself before
+ * calling these setters, the same way it's responsible for its own markup.
+ *
+ * `externalState`, when given (from the very first render on), makes this
+ * fully caller-controlled: whenever it changes identity, internal `state`
+ * is overwritten to match (restoring a saved filter, clearing everything at
+ * once, applying a URL-restored state — all without remounting
+ * `<DataGrid>`). Pass the *same* value back in that a server-mode
+ * `dataSource.onStateChange` call just handed you (mirror it into your own
+ * state and pass that straight through) — a fresh object literal recreated
+ * every render re-triggers this resync every render too. Like a controlled
+ * `<input>`, don't switch between passing `externalState` and omitting it
+ * across the component's lifetime — start controlled and stay controlled,
+ * or start uncontrolled and stay uncontrolled; toggling to `undefined`
+ * later does not hand ownership back, it just stops resyncing.
+ */
+declare function useGridState<TRow>(dataSource: DataSource<TRow>, initialState?: Partial<GridState>, externalState?: GridState): GridStateController;
+
+interface ClientProcessingResult<TRow> {
+    rows: TRow[];
+    rowCount: number;
+}
+/**
+ * Applies a `GridState` to an in-memory row array: filter (via
+ * `evaluateFilter`, matching sql.py/meili.py semantics), then multi-column
+ * sort, then pagination. This is the entire implementation of `"client"`
+ * DataSource mode — `"server"` mode skips this and trusts the caller.
+ */
+declare function processClientData<TRow>(data: readonly TRow[], state: GridState): ClientProcessingResult<TRow>;
+
+interface DebouncedCallback<TArgs extends unknown[]> {
+    /** Schedules `callback`, resetting the timer if one is already pending. */
+    run: (...args: TArgs) => void;
+    /**
+     * Discards any pending scheduled call without invoking it. Callers that
+     * also have an immediate, non-debounced path to the same effect (see
+     * `<DataGrid>`'s `useGridState`, where sort/page changes call the
+     * underlying callback immediately) need this to prevent an
+     * already-in-flight debounced call from firing later with stale state and
+     * overwriting the immediate one.
+     */
+    cancel: () => void;
+}
+/**
+ * Returns a stable `{ run, cancel }` pair. `run` delays invoking `callback`
+ * until `delayMs` has elapsed since the last call, resetting the timer on
+ * every call in between (standard trailing-edge debounce). Used by
+ * `<DataGrid>` in `"server"` mode to avoid firing `onStateChange` on every
+ * keystroke while a filter widget is being typed into.
+ */
+declare function useDebouncedCallback<TArgs extends unknown[]>(callback: (...args: TArgs) => void, delayMs: number): DebouncedCallback<TArgs>;
+
+/**
+ * Accessor-based node shape, matching `<DataGrid>`'s `getRowId` convention
+ * rather than requiring `TRow` to carry specific field names.
+ *
+ * `hasChildren` and `getChildren` are deliberately independent, mirroring
+ * a consuming app's contract tree model (`has_children: boolean` distinct
+ * from an optional `children` array): a node can know it *has* children the backend
+ * hasn't sent yet. A node only needs lazy-loading (`onLoadChildren` gets
+ * called) when `hasChildren(row)` is true AND `getChildren(row)` returns
+ * nothing usable yet.
+ */
+interface TreeAccessors<TRow> {
+    getRowId: (row: TRow) => string;
+    /** Already-loaded children, if any — from eager data or a prior `onLoadChildren` call. */
+    getChildren: (row: TRow) => TRow[] | undefined;
+    /**
+     * Whether this node has children at all, independent of whether they're
+     * loaded yet. Defaults to `(row) => (getChildren(row)?.length ?? 0) > 0`
+     * when omitted — i.e. purely eager trees (no lazy loading) don't need to
+     * supply this.
+     */
+    hasChildren?: (row: TRow) => boolean;
+}
+interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
+    columns: ColumnDef<TRow>[];
+    /** Root-level rows. */
+    data: TRow[];
+    /**
+     * The column whose cell gets the depth indentation + expand/collapse
+     * chevron prepended. Defaults to the first column in `columns`.
+     */
+    treeColumnId?: string;
+    /**
+     * Fetches a node's children on demand. Omit this entirely for a fully
+     * eager tree (all children already present via `getChildren`) — a node
+     * with `hasChildren(row)` true but no `onLoadChildren` is treated as a
+     * dead end (chevron renders, but expanding it just shows "No children.").
+     * Results are cached per node id for the component's lifetime: collapsing
+     * and re-expanding a node never refetches.
+     */
+    onLoadChildren?: (row: TRow) => Promise<TRow[]>;
+    /** How many levels to auto-expand on first render (0 = collapsed root only). Defaults to 0. */
+    initialExpandedLevel?: number;
+    /** Controlled expanded state, keyed by node id. Omit for the grid to own this itself. */
+    expanded?: Record<string, boolean>;
+    onExpandedChange?: (expanded: Record<string, boolean>) => void;
+    /** Pixels of left padding added per depth level to the tree column's cell. Defaults to 20. */
+    indentSize?: number;
+    /**
+     * Extra props (className, onClick, data-* attributes, etc.) spread onto a
+     * row's own `<tr>`. Applied AFTER `<TreeDataGrid>`'s own `data-testid`/
+     * `ref`, so those stay intact even if this returns keys that would
+     * otherwise collide — use it to make a whole row clickable (an `onClick`
+     * `<TreeDataGrid>` has no other way to express — `rowActions` is a kebab
+     * menu, not a row-wide click target), or to attach a `className`/other
+     * `data-*` attribute an existing test suite already depends on. A
+     * `data-testid` returned here specifically is NOT one of those — see
+     * `getRowTestId` below for overriding that one. `depth` and `index` are
+     * the row's tree depth and its position among the currently visible
+     * (flattened) rows, e.g. for depth-aware indentation or index-aware
+     * striping. Typed as a plain `Record` (not `HTMLAttributes<HTMLTableRowElement>`)
+     * since that interface has no index signature — a return value with only
+     * `data-*` keys and no standard HTML attributes would fail TypeScript's
+     * "no properties in common" excess-property check against it.
+     *
+     * `onClick` specifically is safe to combine with the expand/collapse
+     * chevron or a `rowActions` kebab — each of those controls stops its own
+     * click from bubbling up to this `onClick`. That guard only covers
+     * `click`, though: an `onMouseDown`/`onDoubleClick`/`onContextMenu`
+     * returned here would still fire from inside either control too, since
+     * nothing stops those event types from bubbling.
+     */
+    getRowProps?: (row: TRow, depth: number, index: number) => Record<string, unknown>;
+    /**
+     * Overrides the per-row `data-testid` (default `tree-row-${getRowId(row)}`).
+     * Note this is NOT something `getRowProps` above can do despite what its
+     * own doc says about "a caller-specific data-testid" — `<TreeDataGrid>`
+     * always re-applies its own `data-testid` after spreading `getRowProps`'s
+     * result, specifically so a colliding key there can't accidentally break
+     * e2e selectors depending on the default convention. Use this prop instead
+     * when a consumer's existing test suite selects rows by a different,
+     * entity-specific convention that predates adopting `<TreeDataGrid>`.
+     */
+    getRowTestId?: (row: TRow) => string;
+    /** Per-row kebab menu — same `MenuItem` contract as `<DataGrid>`'s `rowActions`. */
+    rowActions?: MenuItem<TRow>[];
+    /**
+     * Enables row virtualization once the flattened (visible) row count
+     * exceeds this threshold. Defaults to 100 — small trees just render every
+     * row directly (simpler DOM, no virtualizer overhead); large/deep trees
+     * switch to `@tanstack/react-virtual`. Set to `0` to always virtualize, or
+     * `Infinity` to never.
+     */
+    virtualizeThreshold?: number;
+    /** Fixed row height estimate in pixels, used by the virtualizer. Defaults to 40. */
+    estimatedRowHeight?: number;
+    /** Max height of the scrollable table body in pixels. Required for virtualization to have a viewport to scroll within. Defaults to 480. */
+    maxBodyHeight?: number;
+}
+
+/**
+ * A lazy-loading tree grid: generalizes a consuming app's contract tree list
+ * (a from-scratch hand-rolled hierarchy table with no shared abstraction)
+ * into a reusable component on top of the same `ColumnDef<TRow>` system
+ * `<DataGrid>` uses. Deliberately does NOT support sorting or client-side
+ * filtering — that original hierarchy table has neither (hierarchy order
+ * comes from the backend; "filtering" there means asking the server for a
+ * differently-shaped tree, which is an app-level concern, not something
+ * this component can generalize).
+ *
+ * Row indentation + the expand/collapse chevron are prepended to whichever
+ * column's cell matches `treeColumnId` (defaults to `columns[0]`); every
+ * other column renders exactly like it would in `<DataGrid>`.
+ */
+declare function TreeDataGrid<TRow>({ columns, data, treeColumnId, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, }: TreeDataGridProps<TRow>): ReactElement;
+
+interface FlatTreeRow<TRow> {
+    row: TRow;
+    id: string;
+    depth: number;
+    hasChildren: boolean;
+    isExpanded: boolean;
+}
+/**
+ * Depth-first flatten of `roots` into the currently *visible* rows only —
+ * a collapsed node's descendants never enter the output at all, matching
+ * `ContractTreelist`'s `flattenContractTree` (the function this generalizes).
+ *
+ * `childrenOverride` (a node id -> loaded children map) takes priority over
+ * `getChildren(row)` when both exist, since it reflects the most recently
+ * fetched batch for a lazily-loaded node — `getChildren` may still return a
+ * stale/partial eager batch for the same node.
+ */
+declare function flattenTree<TRow>(roots: TRow[], accessors: TreeAccessors<TRow>, expanded: Record<string, boolean>, childrenOverride: ReadonlyMap<string, TRow[]>): FlatTreeRow<TRow>[];
+
+interface TreeStateController<TRow> {
+    expanded: Record<string, boolean>;
+    childrenMap: ReadonlyMap<string, TRow[]>;
+    loadingIds: ReadonlySet<string>;
+    /** Node id -> the message from its most recent failed `onLoadChildren` call. */
+    errorIds: ReadonlyMap<string, string>;
+    toggleExpand: (row: TRow) => void;
+    /** Re-attempts `onLoadChildren` for a node currently in `errorIds`. */
+    retry: (row: TRow) => void;
+    /** Expands every node from the roots down to (but not including) `level`, fetching lazy children along the way. */
+    expandToLevel: (level: number) => Promise<void>;
+}
+interface UseTreeStateOptions<TRow> extends TreeAccessors<TRow> {
+    data: TRow[];
+    onLoadChildren?: (row: TRow) => Promise<TRow[]>;
+    expanded?: Record<string, boolean>;
+    onExpandedChange?: (expanded: Record<string, boolean>) => void;
+}
+/**
+ * Owns everything `<TreeDataGrid>` needs beyond plain rendering: expand
+ * state (controlled or internal, same pattern as `<ColumnSelector>`'s
+ * `visibility`/`onVisibilityChange`), a per-node lazy-children cache, and
+ * per-node loading/error tracking.
+ *
+ * Deliberately does NOT reset any of this when `data` changes identity —
+ * unlike `ContractTreelist`, which resets `expanded`/`childrenMap` on every
+ * filter change because filtering there reshapes the whole tree server-side.
+ * This hook has no opinion on why `data` changed; a caller that wants a full
+ * reset (e.g. switching to a different root entity entirely) should remount
+ * `<TreeDataGrid>` via a `key` prop rather than rely on implicit magic here.
+ */
+declare function useTreeState<TRow>({ data, getRowId, getChildren, hasChildren, onLoadChildren, expanded: controlledExpanded, onExpandedChange, }: UseTreeStateOptions<TRow>): TreeStateController<TRow>;
+
+export { ActionsMenu, type BaseColumn, type BooleanColumn, BooleanFilter, type ClientProcessingResult, type ColumnAlign, type ColumnDef, type ColumnGroup, ColumnSelector, type ColumnSelectorProps, type ColumnVisibility, type CompositeFilterDescriptor, DataGrid, type DataGridProps, type DataSource, type DateColumn, DateRangeFilter, type DebouncedCallback, type EnumColumn, EnumFilter, type EnumOption, type FilterDescriptor, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type MenuItem, type MenuItemContext, type NumberColumn, NumberComparisonFilter, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type ResolvedMenuItem, type SortDescriptor, type StringColumn, StringFilter, type TreeAccessors, TreeDataGrid, type TreeDataGridProps, type TreeStateController, UNARY_OPERATORS, type UseTreeStateOptions, alignClassName, canHideColumn, canHideGroup, countVisible, defaultAlign, defaultFormat, evaluateFilter, facetedNumberValues, fieldKey, flattenTree, getColumnValue, groupColumns, isColumnVisible, isCompositeFilterDescriptor, isFilterDescriptor, isFilterable, isSortable, processClientData, renderDefaultFilterWidget, resolveMenuItems, storageKeyFor, useDebouncedCallback, useGridState, useTreeState };