@zuilib/data-grid 0.3.0

package/README.md

@@ -0,0 +1,129 @@
+# @zuilib/data-grid
+
+A server-driven enterprise data grid on [TanStack Table](https://tanstack.com/table),
+built from the `@zuilib/components` primitives and styled only through ZUI tokens.
+
+```bash
+pnpm add @zuilib/data-grid @zuilib/components @zuilib/tokens @tanstack/react-table @headlessui/react
+```
+
+```tsx
+import DataGrid, { defaultDataGridState, toQuery, toQueryKey } from '@zuilib/data-grid'
+
+const [state, setState] = useState(defaultDataGridState)
+const key = toQueryKey(state) // changes only when the request would
+useEffect(() => { fetch(toQuery(state)).then(setPage) }, [key])
+
+<DataGrid columns={columns} rows={page} rowCount={total} state={state} onStateChange={setState} loading={loading}>
+  <DataGrid.Toolbar />
+</DataGrid>
+```
+
+Leave `state` out and the grid keeps it itself, starting from `defaultState`; `onStateChange` still reports every change. Controlled, every emission is the `state` prop plus one change: apply it, or ignore it to reject it.
+
+## Exports
+
+| Subpath | Exports |
+|---------|---------|
+| `@zuilib/data-grid` | Everything below in one entry; `DataGrid` is the default export |
+| `@zuilib/data-grid/data-grid` | `DataGrid` (default) with `DataGrid.Toolbar`, plus the column, label, filter and selection-action types |
+| `@zuilib/data-grid/use-data-grid` | `useDataGrid` — the TanStack table wiring without the layout, for composing the parts yourself |
+| `@zuilib/data-grid/server-adapter` | `toQuery`, `fromQuery`, `toQueryKey`, `toServerState`, `toColumnState`, `fromColumnState` |
+| `@zuilib/data-grid/cells` | `dateCell`, `dateTimeCell`, `textColumn`, `twoValuesColumn` |
+
+## Component API
+
+### DataGrid — `@zuilib/data-grid`
+
+| Prop | Type | Default |
+|------|------|---------|
+| `columns` | `DataGridColumnDef<TData>[]` | required — TanStack column defs plus the ZUI extras below |
+| `rows` | `TData[]` | required — the current page of rows, rendered as given |
+| `rowCount` | `number` | required — total rows on the server (all pages); drives the page count and the range text. Ignored with `manualPagination={false}`: the rows that pass the filters are counted instead |
+| `state` / `defaultState` / `onStateChange` | `Partial<DataGridState>` | controlled or uncontrolled — `onStateChange` receives the whole next state on every interaction |
+| `manualPagination` / `manualSorting` / `manualFiltering` | `boolean` | `true` — the server answers the state; `false` pages, sorts or filters `rows` client-side |
+| `getRowId` | `(row, index, parent?) => string` | row index |
+| `enableRowSelection` | `boolean \| (row) => boolean` | `true` — adds the leading checkbox column |
+| `enableColumnResizing` | `boolean` | `true` |
+| `loading` | `boolean` | `false` — renders skeleton rows (keeping the layout) and marks the table busy |
+| `skeletonWhileRefreshing` | `boolean` | `false` — show skeleton rows while `loading` even when rows are already displayed |
+| `error` | `ReactNode` | — a string gets the danger Alert; with no rows it replaces the body, with rows it sits above them as a banner |
+| `emptyState` | `ReactNode` | — replaces the default "No results" empty state |
+| `density` | `'compact' \| 'comfortable'` | `'comfortable'` |
+| `stickyHeader` | `boolean` | `false` — pins the header row to the top of the scroll container (bound it with `scrollAreaClassName`) |
+| `onRowClick` | `(row, event) => void` | — |
+| `onCellCommit` | `(commit: DataGridCellCommit) => void` | — commit of an inline edit (`enableInlineEdit` on a column) |
+| `commitOnBlur` | `boolean` | `true` — an inline edit that loses focus is committed; `false` drops it instead |
+| `renderExpanded` | `(row) => ReactNode` | — content of the full-width row under an expanded row; setting it adds the chevron column |
+| `getRowCanExpand` | `(row) => boolean` | every row when `renderExpanded` is set |
+| `selectionActions` | `DataGridSelectionAction[]` | `[]` — buttons in the bar that appears while rows are selected |
+| `selectAllMatching` | `boolean` | `true` — offer "Select all N" once every row on the page is selected and more rows match |
+| `showPagination` | `boolean` | `true` — render the pagination footer |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` |
+| `labels` | `Partial<DataGridLabels>` | English — every string the grid renders (`defaultDataGridLabels` lists them) |
+| `locale` | `string` | user's locale — BCP 47 tag for the numbers the grid formats |
+| `aria-label` | `string` | `'Data grid'` |
+| `tableOptions` | `Partial<TableOptions>` | — anything else TanStack accepts (`defaultColumn`, `meta`, …) |
+| `children` | `ReactNode` | — `<DataGrid.Toolbar>` and anything else to render above the table |
+| `className` / `tableClassName` / `scrollAreaClassName` | `string` | root / `<table>` / scrolling wrapper |
+
+`DataGridSelectionAction` is `{ id, label, variant?, tone?, onSelect }` — `variant` and `tone` are the
+`@zuilib/components` Button axes (`ButtonVariant` / `ButtonTone`); `onSelect(selectedIds, { allMatching, rowCount })`
+receives the selected row ids.
+
+### DataGrid.Toolbar
+
+| Prop | Type | Default |
+|------|------|---------|
+| `showSearch` | `boolean` | `true` — the global search field, debounced into the `search` state |
+| `searchPlaceholder` | `string` | `labels.searchPlaceholder` |
+| `searchDebounceMs` | `number` | `300` — ms between the last keystroke and the `search` change |
+| `showFilterChips` | `boolean` | `true` — a removable chip per active column filter |
+| `showColumnManager` | `boolean` | `true` — visibility, order and pinning in one popover |
+| `addableColumns` | `DataGridAddableField[]` | — fields offered under "Add column" |
+| `onAddColumn` | `(id: string) => void` | — the consumer appends the column def |
+| `children` | `ReactNode` | — rendered between the chips and the column manager |
+
+### Columns
+
+`DataGridColumnDef` is a TanStack `ColumnDef` plus the ZUI extras — on the def itself or on `meta`:
+
+| Extra | Type | Effect |
+|-------|------|--------|
+| `align` | `'start' \| 'center' \| 'end'` | Head and cell alignment; `'end'` for numbers |
+| `width` | `number` | Initial width in px; the user resizes from there |
+| `filter` | `{ control: 'text' } \| { control: 'select', options } \| { control: 'date-range' }` | Declares the column's filter popover |
+| `enableInlineEdit` | `boolean` | Double-click or Enter turns the cell into an input; see `onCellCommit` |
+| `meta.label` | `string` | The column's name in the column manager, filter chips and pin labels when `header` is not a string |
+
+### State
+
+`DataGridState` holds `pagination`, `sorting`, `columnFilters`, `search` (the free-text search),
+`columnVisibility`, `columnOrder`, `columnPinning` (`{ start, end }` — logical directions),
+`rowSelection`, `expanded`, `allMatching` and optionally `columnSizing`.
+
+### Server adapter — `@zuilib/data-grid/server-adapter`
+
+Pure functions between `DataGridState` and your API: `toQuery(state)` builds the request (`{ page, pageSize, sort, filters, search, allMatching }`, 1-based page, filters keyed in column-id order) and `fromQuery(query)` restores the state from one; `toQueryKey(state)` is a stable string that changes only when the server request would (drop it in a `useEffect` dependency or a react-query key); `toServerState(state)` strips the UI-only keys; `toColumnState` / `fromColumnState` pack the saved-view keys (visibility, order, pinning) for persistence.
+
+### Cells — `@zuilib/data-grid/cells`
+
+Column helpers for the common enterprise shapes: `dateCell` / `dateTimeCell` (locale-formatted presets of `createDateCell(options)`), `textColumn` (accessor + header + sorting in one call, on one row `field`), `twoValuesColumn` (primary line + muted secondary line, each a `{ field, render? }`).
+
+### Headless — `@zuilib/data-grid/use-data-grid`
+
+`useDataGrid(options)` is the state and TanStack wiring without the layout: it returns `{ table, state, setState, replaceState }` so the toolbar, selection bar, body and pagination can be composed differently. `<DataGrid>` is this hook plus the default layout (`DataGrid.Toolbar`, `DataGrid.SelectionBar`, `DataGrid.Body`, `DataGrid.Pagination`, `DataGrid.ColumnManager`).
+
+## Keyboard
+
+The grid is one tab stop (the row, cell or head last focused). ArrowUp / ArrowDown move between rows, ArrowRight enters the cells and the arrows move between them (ArrowUp from the first row reaches the header); Enter / Space on a cell act on its checkbox or chevron, start an inline edit, or click the row. Shift+ArrowRight / Shift+ArrowLeft open / close an expandable row.
+
+## Localisation
+
+`labels` overrides any string (`defaultDataGridLabels` lists them); `locale` formats the numbers.
+
+## Bulk selection
+
+Once every row on the page is selected, "Select all N" sets `allMatching` in the state; `toQuery` passes it on and selection actions receive `{allMatching, rowCount}`.
+
+Docs: the "Data grid" section of the ZUI documentation site.

package/dist/cells.d.ts

@@ -0,0 +1,61 @@
+import { CellContext } from '@tanstack/react-table';
+import { ReactNode } from 'react';
+import { b as DataGridColumnDef } from './columns-Def2RYjD.js';
+
+interface DateCellOptions {
+    /** BCP 47 tag(s); the browser's locale when left out. */
+    locale?: string | string[];
+    /** Passed to `Intl.DateTimeFormat`. */
+    format?: Intl.DateTimeFormatOptions;
+    /** Rendered for `null`, `undefined`, `''` and invalid dates. @default '-' */
+    empty?: ReactNode;
+}
+type DateCellValue = string | number | Date | null | undefined;
+/** A cell renderer for `cell:`; `dateCell` and `dateTimeCell` are the two presets. */
+type DataGridCellRenderer<TData = unknown, TValue = unknown> = (context: CellContext<TData, TValue>) => ReactNode;
+/**
+ * Builds a locale-aware date cell: a `<time dateTime>` holding the formatted
+ * value, or `empty` when there is nothing to show. The formatter is created
+ * once per column, not per row.
+ */
+declare function createDateCell({ locale, format, empty }?: DateCellOptions): DataGridCellRenderer<any, any>;
+/** `cell: dateCell` renders the date part in the user's locale (`Intl` `dateStyle: 'medium'`). */
+declare const dateCell: DataGridCellRenderer<any, any>;
+/** `cell: dateTimeCell` renders date and time in the user's locale (`dateStyle: 'medium', timeStyle: 'short'`). */
+declare const dateTimeCell: DataGridCellRenderer<any, any>;
+interface TextColumnOptions<TData> extends Omit<DataGridColumnDef<TData, any>, 'id' | 'accessorKey' | 'accessorFn' | 'header'> {
+    /** The row field (also the column id). */
+    field: keyof TData & string;
+    header: string;
+    /** @default true */
+    enableSorting?: boolean;
+}
+/**
+ * A plain text column on one field. Sortable by default; every other ZUI
+ * and TanStack column option (`filter`, `width`, `align`, `cell`, ...) passes through.
+ */
+declare function textColumn<TData>({ field, header, cell, enableSorting, ...rest }: TextColumnOptions<TData>): DataGridColumnDef<TData, any>;
+interface TwoValuesColumnField<TData> {
+    /** The row field. */
+    field: keyof TData & string;
+    /** Replaces the raw field; receives the row's cell context. */
+    render?: (context: CellContext<TData, any>) => ReactNode;
+}
+interface TwoValuesColumnOptions<TData> extends Omit<DataGridColumnDef<TData, any>, 'id' | 'accessorKey' | 'accessorFn' | 'header' | 'cell'> {
+    /** @default primary.field */
+    id?: string;
+    header: string;
+    /** The top line, medium weight. Sorting and filtering read this field. */
+    primary: TwoValuesColumnField<TData>;
+    /** The second line, small and muted. */
+    secondary: TwoValuesColumnField<TData>;
+    /** @default false */
+    enableSorting?: boolean;
+}
+/**
+ * A column stacking two fields of the row: the primary value on top, a
+ * muted secondary under it (a name over an email, a title over a reference).
+ */
+declare function twoValuesColumn<TData>({ id, header, primary, secondary, enableSorting, ...rest }: TwoValuesColumnOptions<TData>): DataGridColumnDef<TData, any>;
+
+export { type DataGridCellRenderer, type DateCellOptions, type DateCellValue, type TextColumnOptions, type TwoValuesColumnField, type TwoValuesColumnOptions, createDateCell, dateCell, dateTimeCell, textColumn, twoValuesColumn };

package/dist/cells.js

@@ -0,0 +1,60 @@
+"use client";
+
+// src/cells.tsx
+import { cn } from "@zuilib/components/lib/cn";
+import { jsx, jsxs } from "react/jsx-runtime";
+function toDate(value) {
+  if (value === null || value === void 0 || value === "") return null;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+function createDateCell({ locale, format, empty = "-" } = {}) {
+  const formatter = new Intl.DateTimeFormat(locale, format);
+  return (context) => {
+    const date = toDate(context.getValue());
+    if (!date) {
+      return /* @__PURE__ */ jsx("span", { "data-slot": "data-grid-date-cell", "data-empty": "", className: "text-muted-foreground", children: empty });
+    }
+    return /* @__PURE__ */ jsx("time", { "data-slot": "data-grid-date-cell", dateTime: date.toISOString(), children: formatter.format(date) });
+  };
+}
+var dateCell = createDateCell({ format: { dateStyle: "medium" } });
+var dateTimeCell = createDateCell({ format: { dateStyle: "medium", timeStyle: "short" } });
+function textColumn({ field, header, cell, enableSorting = true, ...rest }) {
+  return {
+    ...rest,
+    id: field,
+    accessorKey: field,
+    header,
+    enableSorting,
+    cell: cell ?? ((context) => /* @__PURE__ */ jsx("span", { "data-slot": "data-grid-text-cell", children: context.getValue() }))
+  };
+}
+function twoValuesColumn({
+  id,
+  header,
+  primary,
+  secondary,
+  enableSorting = false,
+  ...rest
+}) {
+  const value = (row, field) => row[field];
+  return {
+    ...rest,
+    id: id ?? primary.field,
+    accessorKey: primary.field,
+    header,
+    enableSorting,
+    cell: (context) => /* @__PURE__ */ jsxs("div", { "data-slot": "data-grid-two-values", className: cn("flex min-w-0 flex-col gap-0.5"), children: [
+      /* @__PURE__ */ jsx("span", { "data-slot": "data-grid-two-values-primary", className: "truncate font-medium", children: primary.render ? primary.render(context) : value(context.row.original, primary.field) }),
+      /* @__PURE__ */ jsx("span", { "data-slot": "data-grid-two-values-secondary", className: "truncate text-xs text-muted-foreground", children: secondary.render ? secondary.render(context) : value(context.row.original, secondary.field) })
+    ] })
+  };
+}
+export {
+  createDateCell,
+  dateCell,
+  dateTimeCell,
+  textColumn,
+  twoValuesColumn
+};

package/dist/columns-Def2RYjD.d.ts

@@ -0,0 +1,51 @@
+import { ColumnDef } from '@tanstack/react-table';
+
+type DataGridAlign = 'start' | 'center' | 'end';
+/** A text filter: one string, matched however the server matches it. */
+interface DataGridFilterText {
+    control: 'text';
+    placeholder?: string;
+}
+/** A facet filter: a list of options, of which any number may be picked. */
+interface DataGridFilterSelect {
+    control: 'select';
+    options: readonly {
+        value: string;
+        label?: string;
+    }[];
+}
+/** A date range: ISO `YYYY-MM-DD` bounds, either side optional. */
+interface DataGridFilterDateRange {
+    control: 'date-range';
+}
+/** Discriminated on `control`: the widget the filter popover renders. */
+type DataGridFilter = DataGridFilterText | DataGridFilterSelect | DataGridFilterDateRange;
+interface DataGridDateRange {
+    from?: string;
+    to?: string;
+}
+/** The ZUI extras on a TanStack column definition. */
+interface DataGridColumnExtras {
+    /** Double-click or Enter on a cell turns it into an input; see `onCellCommit`. */
+    enableInlineEdit?: boolean;
+    /** Horizontal alignment of the head and the cells; `end` for numbers. */
+    align?: DataGridAlign;
+    /** Initial width in px (TanStack `size`); the user can resize from there. */
+    width?: number;
+    /** Declares the column's filter popover. */
+    filter?: DataGridFilter;
+}
+type DataGridColumnDef<TData, TValue = unknown> = ColumnDef<TData, TValue> & DataGridColumnExtras;
+/** The extras may also be declared on `meta` (the TanStack way of extending a column). */
+interface DataGridColumnMeta extends DataGridColumnExtras {
+    /** The column's name in the column manager, the filter chips and the pin labels, when `header` is not a string. */
+    label?: string;
+}
+/** The payload of `onCellCommit`: an inline edit the user committed. */
+interface DataGridCellCommit {
+    rowId: string;
+    columnId: string;
+    value: string;
+}
+
+export type { DataGridAlign as D, DataGridCellCommit as a, DataGridColumnDef as b, DataGridColumnExtras as c, DataGridColumnMeta as d, DataGridDateRange as e, DataGridFilter as f, DataGridFilterDateRange as g, DataGridFilterSelect as h, DataGridFilterText as i };

package/dist/data-grid.d.ts

@@ -0,0 +1,309 @@
+import { Row, Table, Updater } from '@tanstack/react-table';
+import * as react from 'react';
+import { MouseEvent, ReactNode, ComponentPropsWithoutRef } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { a as DataGridCellCommit } from './columns-Def2RYjD.js';
+export { D as DataGridAlign, b as DataGridColumnDef, c as DataGridColumnExtras, d as DataGridColumnMeta, e as DataGridDateRange, f as DataGridFilter, g as DataGridFilterDateRange, h as DataGridFilterSelect, i as DataGridFilterText } from './columns-Def2RYjD.js';
+import { e as DataGridState, b as DataGridDensity, c as DataGridSelectionAction } from './state-9r5WYKo_.js';
+export { D as DEFAULT_PAGE_SIZE, a as DataGridColumnPinning, d as DataGridSelectionActionContext, f as defaultDataGridState, r as resolveDataGridState } from './state-9r5WYKo_.js';
+import { UseDataGridOptions } from './use-data-grid.js';
+export { DataGridStateChangeHandler, UseDataGridResult, normalizeColumnState, default as useDataGrid } from './use-data-grid.js';
+export { DataGridColumnState, DataGridQuery, DataGridServerState, fromColumnState, fromQuery, toColumnState, toQuery, toQueryKey, toServerState } from './server-adapter.js';
+import '@zuilib/components/button';
+
+/** A field the grid could show but has no column for yet. */
+interface DataGridAddableField {
+    /** Becomes the argument of `onAddColumn`. */
+    id: string;
+    label: string;
+}
+interface DataGridColumnManagerProps {
+    /** Text of the trigger button. @default labels.columns ('Columns') */
+    label?: string;
+    className?: string;
+    /**
+     * Fields the consumer could turn into columns — an "Add column" section
+     * under the list. The grid can't build a column definition itself, so
+     * picking one only calls `onAddColumn`; the consumer appends the column def
+     * (the `@zuilib/views` preset does this from the dataset schema).
+     */
+    addable?: readonly DataGridAddableField[];
+    /** Called with the picked field's `id`. Required for `addable` to render. */
+    onAddColumn?: (id: string) => void;
+}
+/**
+ * A popover listing every column: a checkbox for visibility, up / down to
+ * reorder, pin to either edge. Changes go out as `columnVisibility`,
+ * `columnOrder` and `columnPinning` state.
+ */
+declare function DataGridColumnManager({ label: labelProp, className, addable, onAddColumn }: DataGridColumnManagerProps): react_jsx_runtime.JSX.Element;
+
+interface DataGridBodyProps<TData> {
+    /** Accessible name of the table. */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /** Pin the header row to the top of the scroll container (bound it with `scrollAreaClassName="max-h-96"`). */
+    stickyHeader?: boolean;
+    onRowClick?: (row: Row<TData>, event: MouseEvent<HTMLTableRowElement>) => void;
+    /** With no rows it replaces the body; with rows it sits above them as a banner. */
+    error?: ReactNode;
+    /** Show skeleton rows while loading even when rows are already displayed. @default false */
+    skeletonWhileRefreshing?: boolean;
+    emptyState?: ReactNode;
+    className?: string;
+    scrollAreaClassName?: string;
+}
+/**
+ * The `<table>` itself: sortable, filterable, resizable heads; selectable,
+ * keyboard-operable rows and cells; skeleton rows while loading; an error or
+ * an empty state spanning every column. Rendered by `<DataGrid>` after its children.
+ *
+ * `aria-colcount` / `aria-colindex` count the visible leaf columns: a hidden
+ * column is removed from the grid (the column manager, not the grid, knows
+ * about it), so the visible set is the whole set the grid presents.
+ */
+declare function DataGridBody<TData>({ stickyHeader, onRowClick, error, skeletonWhileRefreshing, emptyState, className, scrollAreaClassName, ...aria }: DataGridBodyProps<TData>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Every string the grid renders or announces, overridable for another
+ * language. A `{name}` placeholder is replaced with the value named.
+ */
+interface DataGridLabels {
+    /** @default 'Pin to start' */
+    pinStart: string;
+    /** @default 'Pin to end' */
+    pinEnd: string;
+    /** @default 'Unpin' */
+    unpin: string;
+    /** @default 'Expand row' */
+    expandRow: string;
+    /** @default 'Collapse row' */
+    collapseRow: string;
+    /** The sr-only head of the expand column. @default 'Expand' */
+    expandColumn: string;
+    /** Selection bar: the count of selected rows. `{count}` is replaced. @default '{count} selected' */
+    selectedCount: string;
+    /** Selection bar: the count when every matching row is selected. `{count}` is replaced. @default 'All {count} selected' */
+    allMatchingSelected: string;
+    /** Selection bar: the button that selects every matching row. `{count}` is replaced. @default 'Select all {count}' */
+    selectAllMatching: string;
+    /** @default 'Clear selection' */
+    clearSelection: string;
+    /** The selection bar's region name. @default 'Bulk actions' */
+    selectionActions: string;
+    /** The head checkbox. @default 'Select all rows on this page' */
+    selectAllOnPage: string;
+    /** A row checkbox. @default 'Select row' */
+    selectRow: string;
+    /** The footer's `<nav>` name. @default 'Pagination' */
+    pagination: string;
+    /** @default 'Rows per page' */
+    rowsPerPage: string;
+    /** The range text while loading. @default 'Loading…' */
+    loading: string;
+    /** The range text. `{first}`, `{last}` and `{total}` are replaced. @default '{first}–{last} of {total}' */
+    range: string;
+    /** @default 'First page' */
+    firstPage: string;
+    /** @default 'Previous page' */
+    previousPage: string;
+    /** @default 'Next page' */
+    nextPage: string;
+    /** @default 'Last page' */
+    lastPage: string;
+    /** The toolbar search field's name. @default 'Search' */
+    search: string;
+    /** The toolbar search field's placeholder. @default 'Search…' */
+    searchPlaceholder: string;
+    /** The filter chip list's name. @default 'Active filters' */
+    activeFilters: string;
+    /** A chip's remove button. `{column}` is replaced. @default 'Remove {column} filter' */
+    removeFilter: string;
+    /** The column manager button and its list. @default 'Columns' */
+    columns: string;
+    /** `{column}` is replaced. @default 'Move {column} up' */
+    moveUp: string;
+    /** `{column}` is replaced. @default 'Move {column} down' */
+    moveDown: string;
+    /** The column manager's addable-fields section. @default 'Add column' */
+    addColumnSection: string;
+    /** An addable field's button. `{column}` is replaced. @default 'Add {column}' */
+    addColumn: string;
+    /** The funnel button. `{column}` is replaced. @default 'Filter {column}' */
+    filterColumn: string;
+    /** The funnel button while a filter is set. `{column}` is replaced. @default 'Filter {column} (active)' */
+    filterColumnActive: string;
+    /** The text filter input. @default 'Filter value' */
+    filterValue: string;
+    /** The text filter placeholder when the column declares none. @default 'Contains…' */
+    filterPlaceholder: string;
+    /** The facet filter's checkbox group. @default 'Options' */
+    filterOptions: string;
+    /** @default 'From' */
+    from: string;
+    /** @default 'To' */
+    to: string;
+    /** @default 'Clear' */
+    clear: string;
+    /** @default 'Apply' */
+    apply: string;
+    /** A date-range chip with only a lower bound. `{date}` is replaced. @default 'from {date}' */
+    rangeFrom: string;
+    /** A date-range chip with only an upper bound. `{date}` is replaced. @default 'until {date}' */
+    rangeUntil: string;
+    /** The resize handle. `{column}` is replaced. @default 'Resize {column}' */
+    resizeColumn: string;
+    /** The inline edit input. `{column}` is replaced. @default 'Edit {column}' */
+    editColumn: string;
+    /** The default empty state's title. @default 'No results' */
+    noResults: string;
+    /** The default empty state's description. @default 'Try a different search or clear the filters.' */
+    noResultsDescription: string;
+}
+declare const defaultDataGridLabels: DataGridLabels;
+
+interface DataGridPaginationProps extends Omit<ComponentPropsWithoutRef<'nav'>, 'className'> {
+    /** BCP 47 tag for the range numbers; the grid's `locale`, then the user's, when left out. */
+    locale?: string;
+    className?: string;
+}
+/**
+ * The footer: page size, `1–25 of 1,240`, first / previous / next / last.
+ * Reads `pagination` and `rowCount`; emits `pagination`.
+ */
+declare function DataGridPagination({ locale: localeProp, className, ...props }: DataGridPaginationProps): react_jsx_runtime.JSX.Element;
+
+interface DataGridSelectionBarProps extends Omit<ComponentPropsWithoutRef<'div'>, 'className'> {
+    className?: string;
+}
+/**
+ * Appears while rows are selected: the count, one button per
+ * `selectionActions` entry (called with the selected row ids) and a clear
+ * button. Once every row on the page is selected and more rows match,
+ * "Select all N" sets `allMatching` in the state; the actions then receive
+ * `{allMatching: true}`.
+ */
+declare function DataGridSelectionBar({ className, ...props }: DataGridSelectionBarProps): react_jsx_runtime.JSX.Element | null;
+
+interface DataGridToolbarProps extends Omit<ComponentPropsWithoutRef<'div'>, 'className'> {
+    /** Show the global search field. @default true */
+    showSearch?: boolean;
+    /** @default labels.searchPlaceholder ('Search…') */
+    searchPlaceholder?: string;
+    /** Milliseconds between the last keystroke and the `search` change. @default 300 */
+    searchDebounceMs?: number;
+    /** Show a removable chip per active column filter. @default true */
+    showFilterChips?: boolean;
+    /** Show the column manager button. @default true */
+    showColumnManager?: boolean;
+    /** Fields the column manager offers under "Add column" — see `DataGridColumnManagerProps.addable`. */
+    addableColumns?: readonly DataGridAddableField[];
+    /** Called with a picked addable field's `id`; the consumer appends the column def. */
+    onAddColumn?: (id: string) => void;
+    /** Rendered between the chips and the column manager. */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * The bar above the table: a debounced global search (emits `search`),
+ * a removable chip per active column filter, the column manager and any
+ * children. Rendered by the consumer as a child of `<DataGrid>`.
+ */
+declare function DataGridToolbar({ showSearch, searchPlaceholder, searchDebounceMs, showFilterChips, showColumnManager, addableColumns, onAddColumn, children, className, ...props }: DataGridToolbarProps): react_jsx_runtime.JSX.Element;
+
+interface DataGridContextValue<TData = unknown> {
+    table: Table<TData>;
+    state: DataGridState;
+    /** `useDataGrid`'s `setState`: replaces one key and emits. Optional; without it the selection bar has no "Select all N". */
+    setState?: <K extends keyof DataGridState>(key: K, updater: Updater<DataGridState[K]>) => void;
+    loading: boolean;
+    density: DataGridDensity;
+    onCellCommit?: (commit: DataGridCellCommit) => void;
+    /** The content of the full-width row under an expanded row. */
+    renderExpanded?: (row: Row<TData>) => ReactNode;
+    selectionActions: readonly DataGridSelectionAction[];
+    pageSizeOptions: readonly number[];
+    rowCount: number;
+    labels: DataGridLabels;
+    /** BCP 47 tag for the numbers the grid formats (the range text, the counts); the user's locale when left out. */
+    locale?: string;
+    /** An inline edit that loses focus is committed (`true`) or dropped (`false`). */
+    commitOnBlur: boolean;
+    /** Offer "Select all N" in the selection bar once every row on the page is selected. */
+    selectAllMatching: boolean;
+}
+declare const DataGridContext: react.Context<DataGridContextValue<unknown> | null>;
+/** The grid a part sits in. Throws outside `<DataGrid>`: every part needs the table. */
+declare function useDataGridContext<TData = unknown>(part: string): DataGridContextValue<TData>;
+
+declare const SELECT_COLUMN_ID = "__select";
+
+declare const EXPAND_COLUMN_ID = "__expand";
+
+declare const DEFAULT_PAGE_SIZE_OPTIONS: readonly number[];
+interface DataGridProps<TData> extends Omit<UseDataGridOptions<TData>, 'enableRowSelection' | 'fixedColumnIds'>, Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'className' | 'onError'> {
+    /** Total rows on the server (all pages). Drives the page count and the range text. Ignored with `manualPagination={false}`: the rows that pass the filters are counted instead. */
+    rowCount: number;
+    /** Renders skeleton rows (keeping the layout) and marks the table busy. */
+    loading?: boolean;
+    /**
+     * An error message (a string gets the danger Alert). With no rows it
+     * replaces the body; with rows it sits above them as a banner.
+     */
+    error?: ReactNode;
+    /** Show skeleton rows while `loading` even when rows are already displayed. @default false */
+    skeletonWhileRefreshing?: boolean;
+    /** Overrides the grid's own strings (`defaultDataGridLabels` lists them all). */
+    labels?: Partial<DataGridLabels>;
+    /** Replaces the default "No results" empty state. */
+    emptyState?: ReactNode;
+    /** @default 'comfortable' */
+    density?: DataGridDensity;
+    /** Pin the header row to the top of the scroll container (bound it with `scrollAreaClassName`). */
+    stickyHeader?: boolean;
+    onRowClick?: (row: Row<TData>, event: React.MouseEvent<HTMLTableRowElement>) => void;
+    /** Commit of an inline edit (`enableInlineEdit` on a column). */
+    onCellCommit?: (commit: DataGridCellCommit) => void;
+    /** An inline edit that loses focus (a click elsewhere, Tab) is committed; `false` drops it instead. @default true */
+    commitOnBlur?: boolean;
+    /** Offer "Select all N" in the selection bar once every row on the page is selected and more rows match; sets `allMatching` in the state. @default true */
+    selectAllMatching?: boolean;
+    /** BCP 47 tag for the numbers the grid formats (the range text, the selection counts). The user's locale when left out or invalid. Text comes from `labels`. */
+    locale?: string;
+    /**
+     * Content of the full-width row shown under an expanded row. Setting it
+     * adds the chevron column after the selection column; `expanded` in the
+     * state records which rows are open.
+     */
+    renderExpanded?: (row: Row<TData>) => ReactNode;
+    /** Buttons in the bar that appears while rows are selected. */
+    selectionActions?: readonly DataGridSelectionAction[];
+    /** Adds the leading checkbox column. @default true */
+    enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
+    /** @default [10, 25, 50, 100] */
+    pageSizeOptions?: readonly number[];
+    /** Render the pagination footer. @default true */
+    showPagination?: boolean;
+    /** Accessible name of the table. @default 'Data grid' */
+    'aria-label'?: string;
+    /** `<DataGrid.Toolbar>` and anything else to render above the table. */
+    children?: ReactNode;
+    /** Merged last onto the root. */
+    className?: string;
+    /** Merged last onto the `<table>`. */
+    tableClassName?: string;
+    /** Merged last onto the scrolling wrapper around the table. */
+    scrollAreaClassName?: string;
+}
+interface DataGridComponent {
+    <TData>(props: DataGridProps<TData>): React.JSX.Element;
+    displayName: string;
+    Toolbar: typeof DataGridToolbar;
+    ColumnManager: typeof DataGridColumnManager;
+    SelectionBar: typeof DataGridSelectionBar;
+    Body: typeof DataGridBody;
+    Pagination: typeof DataGridPagination;
+}
+declare const DataGrid: DataGridComponent;
+
+export { DEFAULT_PAGE_SIZE_OPTIONS, type DataGridAddableField, DataGridBody, type DataGridBodyProps, DataGridCellCommit, DataGridColumnManager, type DataGridColumnManagerProps, DataGridContext, DataGridDensity, type DataGridLabels, DataGridPagination, type DataGridPaginationProps, type DataGridProps, DataGridSelectionAction, DataGridSelectionBar, type DataGridSelectionBarProps, DataGridState, DataGridToolbar, type DataGridToolbarProps, EXPAND_COLUMN_ID, SELECT_COLUMN_ID, UseDataGridOptions, DataGrid as default, defaultDataGridLabels, useDataGridContext };