# AdaptTable — full documentation

> AdaptTable v3 documentation: a framework-neutral data engine in @adapttable/core, headless React bindings in @adapttable/react, and native table adapters for Mantine, MUI, Chakra UI, Ant Design, Radix Themes, Base UI, shadcn/ui and unstyled Tailwind. Individually imported features include filtering, grouping, pivot tables, formulas, editing, virtualization and export. Responsive mobile cards, URL state, i18n/RTL and optional provider-neutral AI sessions. MIT licensed; applications own data and persistence.

Start with getting-started and concepts for package ownership, then features for opt-in composition. Use the v2-to-v3 migration guide when upgrading; historical migration examples describe their named versions, not current import paths. Vue and Angular bindings are not shipped. This file is generated from the canonical guides; the linked index is at https://adapttable.orwamahmoud.com/llms.txt.


---

# Get started with AdaptTable — React table for your UI kit

▶ **Nothing to install yet — [open the live demo](https://adapttable.orwamahmoud.com/react/demo/) and use it.** Flip
between [Mantine](https://adapttable.orwamahmoud.com/react/demo/?kit=mantine) · [MUI](https://adapttable.orwamahmoud.com/react/demo/?kit=mui) ·
[Chakra](https://adapttable.orwamahmoud.com/react/demo/?kit=chakra) · [Ant Design](https://adapttable.orwamahmoud.com/react/demo/?kit=antd) ·
[Radix](https://adapttable.orwamahmoud.com/react/demo/?kit=radix) · [Base UI](https://adapttable.orwamahmoud.com/react/demo/?kit=base-ui) ·
[shadcn](https://adapttable.orwamahmoud.com/react/demo/?kit=shadcn) · [Tailwind](https://adapttable.orwamahmoud.com/react/demo/?kit=tailwind) on the same data,
and toggle grouping and inline editing while you are there.

<video src="https://adapttable.orwamahmoud.com/media/core/tour.mp4" poster="https://adapttable.orwamahmoud.com/media/core/poster.png?v=2" controls playsinline preload="none" width="1500" height="1065" style="width:100%;height:auto;aspect-ratio:1500/1065;border-radius:8px"></video>

AdaptTable is a headless, UI-agnostic React data table. Pick the adapter for
your design system and you get a styled, sortable, searchable, paginated
table with URL-synced state, RTL, and dark mode. Filters, selection with bulk
actions, and every other feature are opt-in imports composed in
`features={[...]}`.

## Install

The fastest path is the CLI — it detects your UI kit from `package.json`,
prints the install command, and scaffolds a starter `src/PeopleTable.tsx`:

```bash
npx @adapttable/cli init
```

Prefer zero install first? Open a live starter in
[StackBlitz (Mantine)](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine)
— or [any other kit](#try-it-in-stackblitz).

A plain adapter `DataTable` is 72–80 kB min+gzip (measured 2026-09-28 from
packed fixtures; React and the kit stay external). The [FAQ](./faq.md#how-big-is-it--is-it-tree-shakeable)
has the method and the rest of the grid.

Or install manually: `@adapttable/core`, the adapter for your kit, and the
kit's own packages (peer dependencies — skip what you already have).
`react` / `react-dom` 18 or 19 are peers everywhere.

```bash
# Mantine
pnpm add @adapttable/core @adapttable/mantine @mantine/core @mantine/hooks

# Material UI
pnpm add @adapttable/core @adapttable/mui @mui/material

# Chakra UI (v3)
pnpm add @adapttable/core @adapttable/chakra @chakra-ui/react @emotion/react

# Ant Design
pnpm add @adapttable/core @adapttable/antd antd

# Radix Themes
pnpm add @adapttable/core @adapttable/radix @radix-ui/themes

# Base UI
pnpm add @adapttable/core @adapttable/base-ui @base-ui/react

# shadcn/ui — one import, pre-wired with the shadcn class preset
pnpm add @adapttable/core @adapttable/shadcn

# Tailwind / unstyled — bring your own classes
pnpm add @adapttable/core @adapttable/unstyled
```

Every kit depends on `@adapttable/react`, so it is always installed — but a
package manager with a strict layout (pnpm by default) lets you import only
what your own `package.json` lists. Importing a hook such as
`useDensityUrlState` or `useHighlight` from `@adapttable/react` then needs it
added too:

```bash
pnpm add @adapttable/react
```

Keep it on the version your kit pins, which `pnpm why @adapttable/react`
shows.

## Supported versions

| Dependency        | Supported range                                                       |
| ----------------- | --------------------------------------------------------------------- |
| React / React DOM | `^18.0.0 \|\| ^19.0.0` (CI-tested on 18.3 / 19.0 / 19.2)              |
| Mantine           | `^7.2.0 \|\| ^8 \|\| ^9`                                              |
| MUI               | `^6.1.2 \|\| ^7 \|\| ^8 \|\| ^9`                                      |
| Chakra UI         | `^3.13.0`                                                             |
| Ant Design        | `^6`                                                                  |
| Radix Themes      | `^3`                                                                  |
| Base UI           | `^1.6.0`                                                              |
| Node.js           | `>=22.12.0` (packed releases are CI-tested on Node 22.12 and Node 24) |

Each floor is the lowest version the adapter actually runs on — verified
by automated install-and-render probes, not guesswork.

## Provider setup

Each adapter renders with its UI kit's own components, so your app needs that
kit's provider once at the root — exactly as the kit's docs describe.

**Mantine**

```tsx
// main.tsx — once per app, straight from Mantine's own setup guide.
import "@mantine/core/styles.css";
import { MantineProvider } from "@mantine/core";

<MantineProvider>
  <App />
</MantineProvider>;
```

**Material UI** — works with the default theme out of the box; wrap in
`ThemeProvider` to customize:

```tsx
import { createTheme, ThemeProvider } from "@mui/material";

<ThemeProvider theme={createTheme()}>
  <App />
</ThemeProvider>;
```

**Chakra UI** (v3) — the provider takes a system; use the built-in
`defaultSystem` or your own:

```tsx
import { ChakraProvider, defaultSystem } from "@chakra-ui/react";

<ChakraProvider value={defaultSystem}>
  <App />
</ChakraProvider>;
```

**Ant Design** — works without a provider; add `ConfigProvider` for theme or
locale:

```tsx
import { ConfigProvider } from "antd";

<ConfigProvider>
  <App />
</ConfigProvider>;
```

**Radix Themes** — import the Themes stylesheet and wrap in `<Theme>` (see
Radix Themes docs).

**Base UI** — no provider. Import `@adapttable/base-ui` (it side-effect-loads
minimal chrome CSS) or `@adapttable/base-ui/styles.css` once at the app entry.

**shadcn/ui** — no provider. `@adapttable/shadcn` is the unstyled adapter
pre-wired with the shadcn class preset, so it inherits your app's existing
shadcn/ui theme (its CSS variables + Tailwind config) automatically.

**Unstyled** — no provider. It renders semantic HTML with `data-*` and
`className` hooks for your own CSS or Tailwind.

## Your first table

Pass `data` and declare columns — that's the whole thing:

```tsx
// or import from "@adapttable/mui", "@adapttable/chakra", "@adapttable/antd",
// "@adapttable/radix", "@adapttable/base-ui", "@adapttable/shadcn",
// "@adapttable/unstyled" — same props everywhere.
import { DataTable } from "@adapttable/mantine";
import { filters } from "@adapttable/mantine/filters";

interface Person {
  id: string;
  name: string;
  role: string;
  status: string;
  hiredAt: string;
}

const PEOPLE: Person[] = [
  {
    id: "1",
    name: "Ada Lovelace",
    role: "Engineer",
    status: "active",
    hiredAt: "2021-03-01",
  },
  {
    id: "2",
    name: "Alan Turing",
    role: "Founder",
    status: "active",
    hiredAt: "2019-06-15",
  },
  {
    id: "3",
    name: "Grace Hopper",
    role: "Admiral",
    status: "retired",
    hiredAt: "2018-01-20",
  },
];

export function PeopleTable() {
  return (
    <DataTable
      data={PEOPLE}
      columns={[
        { key: "name", sortable: true },
        { key: "role" },
        { key: "status", filter: { type: "select", options: "auto" } },
        { key: "hiredAt", filter: "dateRange" },
      ]}
      rowKey={(r) => r.id}
      features={[filters([])]}
    />
  );
}
```

Column `filter` declarations need the filters feature — `filters([])` when
every filter lives on a column, or pass standalone defs to the factory (below).
See [feature composition](./features.md).

What you just got without writing any of it: search, sorting, pagination
(paged on desktop, infinite scroll on mobile), URL-synced state (reload-safe,
shareable links), empty/loading states, a mobile card layout, and a filter
form built from those `filter` declarations with kit-native widgets — each
filter also drives its own removable chip, URL parsing, and row predicate.

- Headers auto-derive from keys (`hiredAt` → "Hired At"); pass `header` to
  control the text in any language.
- Dot-path keys reach nested values: `{ key: "department.name" }`.
- Filters that aren't columns go in a table-level array:

```tsx
<DataTable
  data={PEOPLE}
  columns={columns}
  rowKey={(r) => r.id}
  features={[
    filters([
      {
        key: "companyId",
        type: "select",
        label: "Company",
        options: companies,
      },
      { key: "budget", type: "numberRange" },
    ]),
  ]}
/>
```

## Try it in StackBlitz

Prefer to try before installing? Each starter is a minimal Vite app — one table
on a demo dataset — that boots in the browser with no local setup. Every
starter composes the same features from its own kit: column filters with chips,
a drag-to-group panel with subtotals, the column menu, resizing, multi-column
sort, cell navigation, inline editing with undo and redo, and CSV export. Pick
your kit:

- [Mantine](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine)
- [Material UI](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mui)
- [Chakra UI](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/chakra)
- [Ant Design](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/antd)
- [Radix Themes](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/radix)
- [Base UI](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/base-ui)
- [shadcn/ui](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/shadcn)
- [Unstyled / Tailwind](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/unstyled)

The source for each lives in
[`starters/`](https://github.com/orwa-mahmoud/adapttable/tree/main/starters).

## Where next

- [Columns](./columns.md) — headers, custom cells, the Columns menu
  (show/hide, reorder, pin), resizing.
- [Inline cell editing](./cell-editing.md) — compose `editing()`, kit-native
  editors, keyboard flow.
- [Row reordering](./row-reordering.md) — opt-in `rowReorder()`, Space-lift
  keyboard, dataset-relative indices.
- [Row pinning](./row-pinning.md) — sticky top and bottom rows, `{ top, bottom }` ids
- [Pinned summary rows](./pinned-summary-rows.md) — host-owned totals outside the row model
- [Row and column spanning](./row-spanning.md) — `getCellSpan`, one cell list per row
- [Full-width and separator rows](./full-width-rows.md) — `extraRows`, host-injected slots
- [Row styling and heights](./row-styling.md) — `rowStyle`, `rowHeight`, variable-height virtualizer
- [Filtering](./filtering.md) — every filter type, options sources, chips,
  popover vs drawer.
- [Data tiers](./data-tiers.md) — server data without a query library
  (`onQueryChange`), or full control via `source` and TanStack Query.
- [Demo](https://adapttable.orwamahmoud.com/react/demo/) — every adapter,
  live.

Full surface: [API reference](./api.md) ·
[core concepts](./concepts.md).

---

# AdaptTable concepts — headless core, TableSource, adapters

▶ **See it working:** [the live demo](https://adapttable.orwamahmoud.com/react/demo/) — one dataset, one feature set, re-rendered by every real adapter.

## The `TableSource` contract

Everything in AdaptTable revolves around one idea: a **`TableSource<T>`** —
a uniform contract that a table consumes regardless of where its rows came
from. Every built-in source builder (`useFrontendData`, `useServerData`,
`useQuerySource`) fulfils it, and the table renders without knowing which
produced it.

```ts
interface TableSource<TRow> {
  // data
  rows: readonly TRow[];
  total: number;
  isLoading: boolean; // FIRST load only — refreshes never re-raise it
  isFetching: boolean; // any in-flight request
  isFetchingNextPage: boolean; // an append fetch (infinite mode)
  hasNextPage: boolean; // more rows can be APPENDED (always false when paged)
  fetchNextPage: () => void; // appends; no-op in paged mode
  error: Error | null;
  paginationMode: "infinite" | "paged";
  // state
  page: number;
  limit: number;
  defaultLimit: number; // page size when the URL names none
  search: string;
  sortBy: string | undefined;
  sortDir: "asc" | "desc" | undefined;
  sortLevels: readonly SortLevel[]; // multi-sort chain, empty when unused
  extra: ExtraFilters; // Record<string, string | string[] | number | undefined>
  groupBy: string | undefined; // comma-separated grouping keys
  // setters
  setPage: (next: number) => void;
  setLimit: (next: number) => void;
  setSort: (key: string | undefined, dir?: "asc" | "desc") => void;
  toggleSortLevel: (key: string) => void;
  setSearch: (next: string) => void;
  setExtra: (key: string, value: FilterValue) => void;
  setExtras: (updates: ExtraFilters) => void;
  setGroupBy: (key: string | undefined) => void;
  clearExtras: () => void;
  clearAll: () => void;
}
```

Optional members a source adds when it can: `refetch`, `allFilteredRows`,
`allSearchedRows`, `facets`, `filterTree` / `setFilterTree`, `capabilities`,
`groups`, `tableEngine`, `initializeGroupBy`, `setGroupAggregateOverrides`,
and the aggregate fields (`groupAggregateOverrides`, `groupAggregations`,
`queryAggregates`, `aggregateOperations`, `honorsAggregates`). The
[API reference](./api.md) has each one's type.

Because the table is agnostic to the source's origin, you can switch between
in-memory and server data — or [build a custom source](./custom-table-source.md) — without touching the
UI.

## Source builders

### `useFrontendData`

In-memory. Filters by a searchable-text projector, sorts by a column's
`sortValue` (or a custom `getSortValue`), and slices for the current page.

```ts
const source = useFrontendData({ data, columns, getSearchText, getSortValue });
```

### `useQuerySource`

Server-paginated. Wraps a caller-supplied `useInfiniteQuery` hook and maps
each page to rows via `selectPage`. Flattens pages in infinite mode, returns
the latest page in paged mode, and clamps out-of-range pages.

```ts
const source = useQuerySource({ usePaginatedQuery, selectPage, baseParams });
```

## Columns

```ts
interface ColumnDef<TRow> {
  key: string; // unique; also the backend sortBy value
  header?: ReactNode; // pre-translated; derived from `key` when omitted
  Cell?: ComponentType<{ row: TRow; rowIndex: number }>; // stable identity
  accessor?: (row: TRow) => ReactNode; // lightweight
  sortValue?: (row: TRow) => string | number | boolean | null | undefined;
  sortable?: boolean;
  width?: number | string;
  align?: "start" | "center" | "end";
  mobileLabel?: string;
  hideOnMobile?: boolean;
  hideOnDesktop?: boolean;
}
```

## Pagination modes

`"auto"` (the default) resolves to **infinite scroll on mobile** and
**paged on desktop**, by the same rule as the card layout: the 768px media
query, or your `mobileBreakpoint`, and `forceMobile` over both.
Force a mode with `paginationMode: "paged" | "infinite"`.

In infinite mode the adapters auto-load the next page when the bottom of the
list scrolls into view (via `IntersectionObserver`, prefetching ~200px
early), and also render an explicit **Load more** button as a keyboard- and
screen-reader-friendly fallback. The auto-load behaviour is packaged as a
headless hook, `useInfiniteScroll`, exported from `@adapttable/react` — attach
the returned ref to a sentinel element after your last row to get the same
behaviour in custom markup (`rootMargin` sets how early it fires, default
`"200px"`):

```tsx
const sentinelRef = useInfiniteScroll({
  hasNextPage: source.hasNextPage,
  isFetchingNextPage: source.isFetchingNextPage,
  fetchNextPage: source.fetchNextPage,
  itemCount: source.rows.length, // re-arms so short pages keep loading
  enabled: source.paginationMode === "infinite",
});
// …render rows…
<div ref={sentinelRef} />;
```

It is SSR- and test-safe: where `IntersectionObserver` is unavailable it
no-ops, leaving the Load more button as the path forward.

## Optional virtualization

Long infinite lists can opt into row/card windowing with the `virtualize()`
feature. `@adapttable/react` exports the underlying `useTableVirtualization`,
and the ready adapters wire it into their desktop rows and mobile cards. With
no `maxHeight` the window tracks the page scroll; add `maxHeight` and the same
feature virtualizes inside the scroll box instead — fifty thousand rows in a
380px panel stay a handful of DOM nodes. Ant Design maps the same
`virtualize()` feature to antd's native virtual table mode.

```tsx
import { DataTable } from "@adapttable/mantine";
import { virtualize } from "@adapttable/mantine/virtualize";

interface Person {
  id: string;
  name: string;
}

export function People({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      columns={[{ key: "name", sortable: true }]}
      rowKey={(row) => row.id}
      paginationMode="infinite"
      features={[virtualize({ estimateRowSize: 56, estimateCardSize: 140 })]}
    />
  );
}
```

Virtualization is optional. Leave it off for small lists or paged tables; turn
it on for long infinite lists.

## Responsive cards

Adapters automatically switch from table rows to mobile cards at
`mobileBreakpoint` (default 768px); `forceMobile` pins the card layout.
A card shows every column without `hideOnMobile`, so `hideOnMobile` on the
low-value columns is what shapes it; `hideOnDesktop` adds a field to cards
only. `renderCard` replaces a card's body while its shell — selection,
toggles, row actions — stays.

```tsx
const columns = [
  { key: "name" },
  { key: "team" },
  { key: "email", hideOnMobile: true },
];

<DataTable data={people} columns={columns} rowKey={(row) => row.id} />;
```

## The engine, and why it has no React in it

Filtering, sorting, paging and grouping are decisions about data, not about
the DOM. They live in `@adapttable/core` as a plain object with no
framework in its import graph, and `@adapttable/react` is the binding that
subscribes a component tree to one.

```ts
import { createTableEngine } from "@adapttable/core";

const engine = createTableEngine({
  data: people,
  columns: [{ key: "name", sortable: true }],
  rowKey: (row) => row.id,
  defaults: { limit: 25 },
});

engine.dispatch({ type: "setSearch", search: "ada" });
engine.rows("page"); // the rows that page shows
```

`CreateTableEngineOptions` is what you build one from. `data`, `columns`,
`rowKey`, `locale`, `paginationMode`, `filterFn` and `getSearchText` stay
live — change one and the engine follows. `tableId` and `defaults` are read
once, because an identity and a seed cannot be retroactively different.

`TableEngine` is the handle:

| Member                                                                  | What it gives you                                                                                                                              |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `snapshot()`                                                            | A `TableSnapshot`: the current query state, the page it is showing, `lastPage`, `selectedIds`, `capabilities`, and the four revision counters. |
| `rows(scope)`                                                           | A `TableRowScope` — `"page"`, `"visible"` or `"full"`.                                                                                         |
| `dispatch(operation)`                                                   | A `TableOperation` a person performed: `setSort`, `setSearch`, `setPage`, `setLimit`, `setFilters`, `setGroupBy`, `setSelection`.              |
| `configure(patch)`                                                      | A `TableEngineConfigPatch` — controlled state a binding replays. Pass `{ silent: true }` to move without waking subscribers.                   |
| `invalidate(axes, next)`                                                | Tell it the data or columns changed. `invalidate(["data"])` with no new array re-derives from the rows it already holds.                       |
| `subscribe(axes, listener)`                                             | Wake on a `TableRevisionAxis` — `data`, `view`, `schema` or `policy` — and nothing else.                                                       |
| `cellValue` / `rowByKey` / `rowKey` / `getColumn`                       | Read one cell, find a row, take a row's identity, look up a column.                                                                            |
| `stageCandidate` / `commitCandidate` / `discardCandidate` / `candidate` | Stage configuration and data privately, then publish or drop it. `candidate` reads the staged state; everything else reads the committed one.  |
| `tableId` / `dispose()`                                                 | The engine's identity, and releasing it.                                                                                                       |

`TableRevisions` carries those four counters. They are separate so a consumer
can wake on the one it cares about: a virtualizer on `data`, a toolbar on
`view`, an agent on `policy`.

`snapshot().page` is the page actually on screen. Ask for page 9 of a table
that shrank to three and it reports the last page, while `requestedPage`
remembers what you asked for — so restoring the rows restores the page,
instead of stranding a reader on page 1.

### Handing the engine to something that is not a table

`createNeutralTable(engine, tableId, binding)` wraps one as a `NeutralTable`:
the same rows and revisions plus an `operations` map saying which of them are
actually wired right now. That is the shape `@adapttable/ai` reads, and the
`NeutralTableBinding` is how a host tells it what the surrounding UI can do.
An operation that stops being wired disappears from the map, so nothing is
offered a capability the table can no longer perform.

## Features are imports

A `<DataTable>` with `columns`, `rowKey` and a data tier searches, sorts and
pages. Everything else — filters, grouping, editing, virtualization, bulk
actions, the column menu — is a factory imported from a kit subpath and
passed in `features`:

```tsx
import { DataTable } from "@adapttable/mantine";
import { filters } from "@adapttable/mantine/filters";
import { grouping } from "@adapttable/mantine/grouping";

interface Person {
  id: string;
  name: string;
  team: string;
}

export function People({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      columns={[
        { key: "name", sortable: true },
        { key: "team", filter: { type: "select", options: "auto" } },
      ]}
      rowKey={(row) => row.id}
      features={[filters([]), grouping("team")]}
    />
  );
}
```

The import is the switch: a table downloads a feature only when it names
one. Host plugins are the same `TableFeature` type in the same array.
[Feature composition](./features.md) lists every factory, the standard
preset, and the plugin hooks.

## The two ways to use it

1. **Batteries-included** — `import { DataTable } from "@adapttable/<kit>"`.
2. **Headless** — `import { useDataTable } from "@adapttable/react"` and render
   your own markup with the returned prop-getters — see
   [headless rendering](./headless.md).

---

# React table features — optional imports, presets and plugins

▶ **See it working:** [the Feature Lab](https://adapttable.orwamahmoud.com/react/demo/all-options/) — every opt-in, on every kit.

Every opt-in is an import and one entry in `features`. The import is the
switch, which is what lets a table pay only for what it named:

```tsx
import { applyRowReorder } from "@adapttable/react";
import { DataTable } from "@adapttable/mantine";
import { rowReorder } from "@adapttable/mantine/row-reorder";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    rowReorder((from, to) => setRows(applyRowReorder(rows, from, to))),
  ]}
/>;
```

A built-in factory and a host plugin are the same `TableFeature` type in the
same array — that is the public plugin surface, not a parallel API.

## What the import buys

A bundler follows imports, not prop values, so the import is the switch: a
table downloads a feature's implementation when it names it, and not before.
An adapter's `DataTable` carries the base contract — responsive rendering,
loading, error and empty states, accessibility, sorting, search and
pagination — for the weight the [FAQ's measured table](./faq.md#how-big-is-it--is-it-tree-shakeable)
reports. Everything else arrives with its own entry.

`<DataTable>` has no enabling props: `enableColumnMenu`, `bulkActions`,
`contextMenu`, `commandPalette`, `statusBar`, `sidePanel`, `findInTable` and
the rest are not `DataTable` props. The factory from the matching subpath turns
a feature on — see [migrating from v2](./migrate-from-v2.md).

## Kit subpaths

Every public adapter exports the same subpaths. **Kit** means the subpath binds
the factory to that kit's own components; **headless** means it re-exports the
`@adapttable/react/features` factory unchanged, because the feature draws no
control of its own.

| Import                                  | Exports                                                                                           | Draws    |
| --------------------------------------- | ------------------------------------------------------------------------------------------------- | -------- |
| `@adapttable/<kit>/row-reorder`         | `rowReorder`                                                                                      | kit      |
| `@adapttable/<kit>/row-pinning`         | `rowPinning`                                                                                      | headless |
| `@adapttable/<kit>/pinned-summary-rows` | `pinnedSummaryRows`                                                                               | headless |
| `@adapttable/<kit>/cell-span`           | `cellSpan`                                                                                        | headless |
| `@adapttable/<kit>/extra-rows`          | `extraRows`                                                                                       | headless |
| `@adapttable/<kit>/row-appearance`      | `rowAppearance`                                                                                   | headless |
| `@adapttable/<kit>/row-detail`          | `rowDetail`, `nestedTable`                                                                        | kit      |
| `@adapttable/<kit>/nested-table`        | `nestedTable`                                                                                     | kit      |
| `@adapttable/<kit>/row-actions`         | `rowActions`                                                                                      | headless |
| `@adapttable/<kit>/editing`             | `editing`, `rowEditing`, `batchEditing`, `editHistory`, `dirtyIndicators`, `undoRedoButtons`      | kit      |
| `@adapttable/<kit>/batch-editing`       | `batchEditing`                                                                                    | kit      |
| `@adapttable/<kit>/grouping`            | `grouping` — code-fixed grouping without the interactive panel                                    | kit      |
| `@adapttable/<kit>/grouping-panel`      | `groupingPanel`, `GroupingPanel` — grouping headers + interactive panel                           | kit      |
| `@adapttable/<kit>/tree`                | `tree`                                                                                            | kit      |
| `@adapttable/<kit>/virtualize`          | `virtualize`                                                                                      | headless |
| `@adapttable/<kit>/column-menu`         | `columnMenu`                                                                                      | kit      |
| `@adapttable/<kit>/resizable-columns`   | `resizableColumns`                                                                                | headless |
| `@adapttable/<kit>/fit-columns`         | `fitColumns`                                                                                      | headless |
| `@adapttable/<kit>/column-groups`       | `collapsibleColumnGroups`                                                                         | kit      |
| `@adapttable/<kit>/column-selection`    | `columnSelectionCheckbox`                                                                         | kit      |
| `@adapttable/<kit>/multi-sort`          | `multiSort`                                                                                       | headless |
| `@adapttable/<kit>/filters`             | `filters` (kit), `filterTypes` (headless)                                                         | kit      |
| `@adapttable/<kit>/header-filters`      | `headerFilters`                                                                                   | kit      |
| `@adapttable/<kit>/saved-views`         | `savedViews`                                                                                      | kit      |
| `@adapttable/<kit>/export`              | `exportCsv`                                                                                       | kit      |
| `@adapttable/<kit>/cell-navigation`     | `cellNavigation`                                                                                  | kit      |
| `@adapttable/<kit>/selection-stats`     | `selectionStats`                                                                                  | kit      |
| `@adapttable/<kit>/status-bar`          | `statusBar`, `selectionStats`                                                                     | kit      |
| `@adapttable/<kit>/find-in-table`       | `findInTable`                                                                                     | kit      |
| `@adapttable/<kit>/fullscreen`          | `fullscreen`                                                                                      | kit      |
| `@adapttable/<kit>/density`             | `densityChooser`                                                                                  | kit      |
| `@adapttable/<kit>/print`               | `print`                                                                                           | kit      |
| `@adapttable/<kit>/command-palette`     | `commandPalette`                                                                                  | kit      |
| `@adapttable/<kit>/context-menu`        | `contextMenu`                                                                                     | kit      |
| `@adapttable/<kit>/side-panel`          | `sidePanel`                                                                                       | kit      |
| `@adapttable/<kit>/bulk-actions`        | `bulkActions`                                                                                     | kit      |
| `@adapttable/<kit>/assistant`           | `tableAssistant`, `TableAssistant`                                                                | kit      |
| `@adapttable/<kit>/pivot`               | `PivotPanel` and the pivot engine (`pivot`, `pivotTableModel`, …)                                 | kit      |
| `@adapttable/<kit>/preset`              | `standardFeatures`, `StandardFeatureOptions`                                                      | kit      |
| `@adapttable/<kit>/features`            | the headless `@adapttable/react/features` surface: `applyTableFeatures`, `feature`, every factory | headless |

`<kit>` is `mantine`, `mui`, `chakra`, `antd`, `radix`, `base-ui`, `shadcn`,
or `unstyled`. `@adapttable/<kit>/features` forwards `@adapttable/react/features`
as it is, so a factory that draws kit UI — `columnMenu`, `filters`,
`headerFilters`, `collapsibleColumnGroups`, `rowReorder`, `groupingPanel`,
`exportCsv`, … — renders no controls when imported from there. Import each one
from its own `@adapttable/<kit>/<subpath>`.

The pivot engine stays a calculation — `import { pivot } from "@adapttable/core/pivot"`
— not a `<DataTable>` prop. The kit `/pivot` subpath is the panel plus that
engine, so a host that composes a pivot table still does it in one import.

## The standard preset — one import for a good table

```tsx
import { DataTable } from "@adapttable/mantine";
import { standardFeatures } from "@adapttable/mantine/preset";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(r) => r.id}
  features={standardFeatures()}
/>;
```

With no arguments it composes the features that work with nothing else
supplied: the Columns menu, the density chooser, CSV export, find-in-table
(Ctrl/Cmd+F after a click in the table), fit-columns, the fullscreen toggle, [header filters](./header-filters.md), multi-sort, resizable
columns and the status bar. Because `headerFilters()` is a member, filters
from the preset's `filters` option open from the column headers (`filtersMode`
resolves to `"header"`); compose the members individually for popover or drawer
filters.

Find draws no toolbar control by default. `standardFeatures({ findButton: true })`
adds the Find control after Export:

```tsx
features={standardFeatures({ findButton: true })}
```

Configurable preset members join only when you give them input — `grouping`,
`bulkActions`, `filters` and `savedViews`. Features outside the preset append to
the same ordinary array:

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

[
  ...standardFeatures({
    bulkActions: [{ key: "delete", label: "Delete", onClick: remove }],
    filters: [{ key: "team", type: "select", options: teams }],
    savedViews: { storageKey: "people-table-views" },
  }),
  groupingPanel("team"),
];
```

One factory is callable with no arguments and is still NOT a member: the
selection statistics feature needs a cell range — which needs `cellNavigation`
— while arming a row-selection column on its own. Import it directly when you
want it.

The result is an ordinary array. Append to it, filter it, or replace an entry:

```tsx
features={[...standardFeatures(), auditLog(), rowReorder(reorder)]}
```

Later entries win, so re-composing a member replaces it rather than doubling
it, and a duplicate id warns in development.

**The preset entry statically imports everything it can compose**, so its own
bundle contains the configurable members whether or not you pass their options.
That is the trade: one import instead of ten.

Measured on MUI, the table alone is 72 kB gzipped and the same table with
`standardFeatures()` composed is 127 kB.
A table counting every byte imports the individual features it uses instead,
and pays for those alone — `pnpm budget` measures both paths on every run.

## Types, and why no annotation is needed

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";
import { virtualize } from "@adapttable/mantine/virtualize";

<DataTable features={[groupingPanel("team"), virtualize()]} />;
```

A factory whose configuration says nothing about rows returns a
`StaticTableFeature` — the same feature whatever the table holds — and composes
into any `<DataTable>` with no type argument.

A factory that takes a row-typed callback returns `TableFeature<TRow>` and
infers the row from that callback: `rowReorder(handler)`, `editing(save)`. Put
one in a table of a different row type and the compiler refuses, naming the
feature's own row type.

A host plugin is the same object: `feature("audit-log", { statusBar: true })`,
or a `TableFeature` with `setup(host)` for live registration.

## Host plugins — `setup(host)`

A plugin registers on the same `TableFeature` the factories return —
`filterTypes`, an export writer, palette commands, context-menu items, a side
panel — so the registration surface is one array, one host, with lifecycle via
`onDispose` or a function returned from `setup`.

```tsx
import type { TableFeature } from "@adapttable/mantine/features";

const currencyFilter: TableFeature = {
  id: "currency-filter",
  setup(host) {
    host.registerFilterType({
      type: "currency",
      widget: "numberRange",
      ops: ["eq", "gt", "lt"],
      defaultOp: "eq",
      stateKeys: (def) => [def.key],
      match: () => true,
      chips: () => ({}),
      conditionToExtra: () => ({}),
    });
    return () => {
      /* table unmounted, or `features` changed */
    };
  },
};

<DataTable features={[currencyFilter, rowReorder(onReorder)]} … />;
```

The full filter-type contract is on [custom filter types](./custom-filter-types.md).

Every seam is a method on `TableFeatureHost`. Built-in factories that carry
extras (`filterTypes`, `exportCsv` with a writer, `commandPalette` with extra
commands, `contextMenu` with extra items, `sidePanel` panels) call the same
methods in `setup`, so a plugin is not a second API.

| Host method                | Same as                                       |
| -------------------------- | --------------------------------------------- |
| `registerFilterType`       | `filterTypes([spec])`                         |
| `extendFilterType`         | a custom feature's `host.extendFilterType(…)` |
| `registerEditor`           | `column.editor: { type: "custom", render }`   |
| `registerAggregator`       | `aggregate({ key: fn })`                      |
| `registerWriter`           | `exportCsv({ writer })`                       |
| `registerColumnMenuAction` | appended after the built-in Columns actions   |
| `registerPanel`            | `sidePanel({ panels, … })`                    |
| `registerCommand`          | `commandPalette({ commands, … })`             |
| `registerContextMenuItems` | `contextMenu({ items })`                      |
| `onDispose`                | cleanup when the table unmounts               |

A named editor is a string `column.editor` that is not a built-in (`"text"`,
`"number"`, …). `resolveCellEditor` turns it into `{ type: "custom", render }`
so adapters keep one custom-editor path. A named aggregator is a string
`aggregate()` looks up after the built-ins, when the mapper **runs** (inside
the table), not when `aggregate()` is called in the parent.

`registerPanel` appends to a composed `sidePanel()` dock — the feature still
owns `open` / `onOpenChange`. Registrations add content to their matching
composed feature; they do not pull command-palette, context-menu or side-panel
chrome into the base table.

The superseded `FilterTypeRegistry.register` / `extend` methods and the
`filterTypes` enabling prop are not part of the v3 API.

## Features that own hooks — `provider`

`apply` sets props and `setup(host)` registers values, but neither can add a
React hook. Hooks must be called in the same order on every render, so a table
that calls `useRowReorder` only when the feature is composed is not a table with
an optional feature — it is a crash. That is why the enabling props never saved
a byte: whatever the props said, the import was already in the graph.

A component is the answer, because mounting and unmounting one is the legal way
to add and remove hooks. A feature may carry a `provider` whose component wraps
the table, calls whatever hooks it needs, and publishes the result under a typed
key:

```tsx
import {
  FeatureStateScope,
  featureStateKey,
  type TableFeature,
  useFeatureState,
} from "@adapttable/react/adapter";
import { useEffect, useState } from "react";

export const AUDIT = featureStateKey<{ count: number }>("audit-log");

export const auditLog = (): TableFeature => ({
  id: "audit-log",
  provider: {
    Provider: ({ children }) => {
      const [count, setCount] = useState(0);
      useEffect(() => subscribe(() => setCount((n) => n + 1)), []);
      return (
        <FeatureStateScope stateKey={AUDIT} value={{ count }}>
          {children}
        </FeatureStateScope>
      );
    },
  },
});
```

Anything under the table reads it with `useFeatureState`, which returns
`undefined` when the feature is not composed — the ordinary answer for a table
that does not have it, not an error:

```tsx
const audit = useFeatureState(AUDIT);
if (!audit) return null;
return <span>{audit.count} changes</span>;
```

Both halves are typed: `featureStateKey<T>` fixes what the provider must publish
and what a reader gets back, so this is a contract rather than a bag of strings.

### Features that draw — `renders`

State is half of a feature; the other half is what the reader sees. A feature
fills named positions in the table, and the kit's own components are what it
fills them with:

```tsx
import {
  FeatureSlot,
  featureSlotKey,
  slotRender,
} from "@adapttable/react/adapter";

export const STATUS_BAR = featureSlotKey<{ total: number }>("status-bar");

export const statusBar = (): TableFeature => ({
  id: "status-bar",
  renders: [
    slotRender(STATUS_BAR, ({ total }) => <MyStatusBar total={total} />),
  ],
});
```

The table computes the props and asks; it never learns what was drawn:

```tsx
<FeatureSlot slot={STATUS_BAR} props={{ total }} />
```

`slotRender` is what keeps `total` typed at the call site; one feature can fill
several positions that take different props.

An unfilled slot renders nothing, so chrome around a position the reader does
not have simply is not there. `useFeatureSlotFilled` answers when a wrapper
must not be drawn around nothing.

Several features may fill one position — a toolbar takes more than one control
— so a slot keeps every answer and orders them by feature id, the same way
providers nest. Fillers belong to the table that composed them, so two tables
on a page never draw each other's controls.

This is why a kit's pixels stay out of the base graph: the adapter's table asks
for a position, and only the feature that was imported can answer.

### What the table guarantees

- **Order comes from the ids, not from your array.** Providers nest in
  feature-id order, so `[groupingPanel("team"), auditLog()]` and
  `[auditLog(), groupingPanel("team")]` build the identical tree. Moving a line
  never remounts a provider or discards what it was holding.
- **One provider per id.** A duplicate id warns in development and the last one
  wins, exactly as `apply` already resolves duplicates.
- **A provider mounts when its feature arrives and unmounts when it leaves**, and
  its cleanup runs once.
- **State belongs to its own table.** It travels by context, so two tables on a
  page — and a table nested in another table's row detail — never read each
  other's. A nested table shadows the outer value for its own subtree while
  everything the outer table published stays readable.

This is the same `TableFeature` in the same `features` array. There is no second
registry to learn and nothing global to collide over.

## Every factory

`rowReorder` · `rowPinning` · `pinnedSummaryRows` · `cellSpan` · `extraRows` · `rowAppearance` ·
`rowDetail` · `nestedTable` · `editing` · `rowEditing` · `batchEditing` ·
`editHistory` · `dirtyIndicators` · `grouping` · `groupingPanel` · `tree` ·
`virtualize` ·
`columnMenu` · `resizableColumns` · `collapsibleColumnGroups` · `exportCsv` ·
`cellNavigation` · `findInTable` · `fullscreen` · `commandPalette` ·
`contextMenu` · `sidePanel` · `bulkActions` · `filters` · `filterTypes` ·
`headerFilters` · `savedViews` · `selectionStats` · `densityChooser` ·
`print` · `statusBar` · `undoRedoButtons` · `multiSort` · `fitColumns` ·
`columnSelectionCheckbox` · `rowActions` · `feature` (ad-hoc patch) ·
`applyTableFeatures` (the merge used by every adapter) · `useTableFeatures`
(apply + `setup(host)`, the hook every adapter runs).

Host helpers are exported from `@adapttable/react/adapter`: `featureHostOf` /
`rememberFeatureHost` (the host of one table, never a sibling's) ·
`FeatureHostProvider` / `useFeatureHost` (hooks under that table) ·
`bindFeatureHostFn` (a mapper created outside the table still resolves names
for the table that invokes it).

---

# Client & server React table data — one TableSource API

One `<DataTable>`, three ways to feed it — from "here's an array" to full
query-library control. Search, sorting, filters, chips, and URL sync behave
identically in every tier.

## Example

### 1. Frontend — `data`

Pass the rows; the table filters, sorts, and pages them in memory.

```tsx
// or import from "@adapttable/mui", "@adapttable/chakra", "@adapttable/antd",
// "@adapttable/radix", "@adapttable/shadcn", "@adapttable/unstyled" — same props everywhere.
import { DataTable } from "@adapttable/mantine";

interface Person {
  id: string;
  name: string;
  role: string;
}

const PEOPLE: Person[] = [
  { id: "1", name: "Ada Lovelace", role: "Engineer" },
  { id: "2", name: "Alan Turing", role: "Founder" },
  { id: "3", name: "Grace Hopper", role: "Admiral" },
];

export function PeopleTable() {
  return (
    <DataTable
      data={PEOPLE}
      columns={[{ key: "name", sortable: true }, { key: "role" }]}
      rowKey={(r) => r.id}
    />
  );
}
```

### 2. Server — `data` + `total` + `loading` + `onQueryChange`

Your API paginates; the table owns the query state and tells you when to
fetch.

```tsx
import { useState } from "react";
// or import from "@adapttable/mui", "@adapttable/chakra", "@adapttable/antd",
// "@adapttable/radix", "@adapttable/shadcn", "@adapttable/unstyled" — same props everywhere.
import { DataTable } from "@adapttable/mantine";

interface Person {
  id: string;
  name: string;
  role: string;
}

export function PeopleTable() {
  const [rows, setRows] = useState<Person[]>([]);
  const [total, setTotal] = useState(0);
  const [loading, setLoading] = useState(false);

  return (
    <DataTable
      data={rows}
      total={total}
      loading={loading}
      onQueryChange={async (query, { signal }) => {
        setLoading(true);
        try {
          const params = new URLSearchParams({
            page: String(query.page),
            limit: String(query.limit),
            search: query.search,
          });
          // Forward `signal`: superseded requests abort at the source.
          const res = await fetch(`/api/people?${params}`, { signal });
          const body = (await res.json()) as { items: Person[]; total: number };
          setRows(body.items);
          setTotal(body.total);
        } finally {
          setLoading(false);
        }
      }}
      columns={[{ key: "name", sortable: true }, { key: "role" }]}
      rowKey={(r) => r.id}
    />
  );
}
```

#### What the query carries, and how it grows

Every server tier receives one consolidated `TableQuery`:

```ts
{
  (page, limit, search, sortBy, sortDir, sortLevels, filters);
}
```

That is the whole baseline, and it will not change. Capabilities beyond it —
grouping, aggregates, nested filter trees, facet counts, cursor pagination —
ride as **optional** fields that a source opts into by declaring what its
endpoint can answer:

```tsx
import { useServerData } from "@adapttable/react";

useServerData({
  rows,
  total,
  // this endpoint can group and count; it cannot do the rest yet
  supports: { grouping: true, facets: true },
  onQueryChange: async (query, { signal }) => {
    // query.groupBy → ["team"] when the user is grouping
    // query.facets  → ["status"] when a filter wants distinct-value counts
  },
});
```

Declare nothing and nothing changes: the query arrives with exactly the seven
baseline fields, so an endpoint written before a capability existed keeps
working untouched. Declare a capability and its field starts arriving.

If the table wants something the source has not declared, the field is
**omitted rather than sent and ignored** — a server should never receive a
field it never agreed to read — and development logs which capability would
unlock it. That warning is the intended way to discover the next thing your
backend could do, not an error.

| Field         | Capability   | Carries                                                                                                                                                                                                                        |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `groupBy`     | `grouping`   | Grouping keys, outermost first                                                                                                                                                                                                 |
| `aggregates`  | `aggregates` | `{ key, fn }` pairs to compute. Optional `supports.aggregateOperations` lists the ids the backend can answer; omit it and the five standard functions are assumed. Custom ids travel as strings, never as functions.           |
| `filterTree`  | `filterTree` | Nested AND/OR condition tree                                                                                                                                                                                                   |
| `facets`      | `facets`     | Column keys needing distinct-value counts. The response returns the same keys as `facets` on the page (`PaginatedResponse.facets` / `PageSelector.facets`) — counts for the filtered set with each facet's own filter removed. |
| `cursor`      | `cursor`     | Opaque cursor from the previous response                                                                                                                                                                                       |
| `expandedIds` | `tree`       | Open tree node ids, so the response can carry the children of every open branch                                                                                                                                                |

`cursor` and `expandedIds` need a source built with `useServerData` or
`useQuerySource` and passed as `source`: they take the `nextCursor` and
`expandedIds` options, which `<DataTable onQueryChange>` has no prop for.
`supports`, `facetKeys` and `facets` are props on every kit's `<DataTable>`
as well as options of those two hooks.

The flat `filters` bag is always populated, including when `filterTree` is
sent, so a server that only reads the simple form keeps working.

### 3. Full control — `source`

Build a `TableSource` yourself — `useQuerySource` over TanStack Query (shown
below; wrap your app in its `QueryClientProvider`), `useFrontendData` for
headless in-memory use, or a [hand-rolled object that fulfils the contract](./custom-table-source.md).

```tsx
import { keepPreviousData, useInfiniteQuery } from "@tanstack/react-query";
import type { PaginatedResponse, TableQueryParams } from "@adapttable/core";
// or import from "@adapttable/mui", "@adapttable/chakra", "@adapttable/antd",
// "@adapttable/radix", "@adapttable/shadcn", "@adapttable/unstyled" — same props everywhere.
import { DataTable, useQuerySource } from "@adapttable/mantine";

interface Person {
  id: string;
  name: string;
  role: string;
}

async function fetchPeople(
  params: Partial<TableQueryParams>
): Promise<PaginatedResponse<Person>> {
  const search = new URLSearchParams();
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined) search.set(key, String(value));
  }
  const res = await fetch(`/api/people?${search}`);
  return (await res.json()) as PaginatedResponse<Person>;
}

// Your query hook: fetch one page for the current params.
function usePeopleQuery(params: Partial<TableQueryParams>) {
  return useInfiniteQuery({
    queryKey: ["people", params],
    queryFn: ({ pageParam }) => fetchPeople({ ...params, page: pageParam }),
    initialPageParam: params.page ?? 1,
    getNextPageParam: (last) => (last.hasNextPage ? last.page + 1 : undefined),
    placeholderData: keepPreviousData,
  });
}

export function PeopleTable() {
  const source = useQuerySource<Person>({ usePaginatedQuery: usePeopleQuery });
  return (
    <DataTable
      source={source}
      columns={[{ key: "name", sortable: true }, { key: "role" }]}
      rowKey={(r) => r.id}
    />
  );
}
```

## Explicit `mode` — when inference isn't what you meant

The tier is inferred from what you pass (`data` alone → frontend;
`data` + `onQueryChange` → server; `source` → full control). The optional
`mode` prop pins it explicitly — and unlocks one combination inference
cannot express:

| I want…                                                           | Pass                                       | `onQueryChange` acts as…                                        |
| ----------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------- |
| The table to fetch nothing; my handler runs every query           | `mode="server"` (requires `onQueryChange`) | **the contract** — you fetch and hand back `data` + `total`     |
| The table to keep filtering/sorting/paging my `data`, but TELL me | `mode="frontend"` + `onQueryChange`        | **a pure notification** — fires per committed change, not mount |
| Today's inference exactly                                         | omit `mode`                                | contract when present, nothing otherwise                        |

`mode="server"` without `onQueryChange` does not compile; `mode` together
with `source` dev-warns and `source` wins.

## How it works

- Tier resolution is by what you pass: `source` wins; otherwise
  `onQueryChange` selects the server tier; otherwise `data` alone is the
  frontend tier. Mixing tiers dev-warns and uses `source`.
- **Frontend**: search, the declarative-filter predicate, sorting, and page
  slicing all run in memory. Pagination defaults to `"auto"` — paged on
  desktop, infinite scroll on mobile.
- **Server**: the table owns page, page size, debounced search, sort, and
  filter state (URL-synced), and emits ONE consolidated `TableQuery` —
  `{ page, limit, search, sortBy, sortDir, sortLevels, filters }` — per real
  change, **including once on mount with the URL-restored values**. Your only
  job is to fetch and hand back `data` + `total`.
- Server queries are value-keyed (`stableKey`), so identical re-renders never
  re-fire the same query; when a newer query
  supersedes an in-flight one, the previous call's `signal` aborts — forward
  it to `fetch` and out-of-order responses die at the source.
- **Full control**: every source builder returns the same
  [`TableSource`](./concepts.md) contract, so the table can't tell in-memory
  from server data — switch tiers without touching the UI.
- Column `filter` shorthands and the `filters` array drive widgets, chips,
  and URL parsing in **all three tiers**; only the frontend tier also applies
  the row predicate (the other tiers receive `query.filters` instead).

## What a source can do — `capabilities`

Some controls only work if the data layer behind them can answer. Exporting
everything needs every row; grouping needs either the whole filtered set or a
server that groups; "select all 2,431 matching" needs a source that can speak
for rows that are not on screen.

A source states what it supports:

```ts
const source: TableSource<Person> = {
  ...rest,
  capabilities: {
    fullDataset: false, // one page at a time
    grouping: "server", // the API returns group rows
    selectAcrossPages: true, // it can act on the whole match set
    exportScope: "all", // it permits a wired full-export route
    totalCount: "exact", // `total` counts matches, not what has loaded
  },
};
```

| Capability            | Values                          | What it permits                                                                                      | Off means                                                     |
| --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `fullDataset`         | `boolean`                       | Every row is reachable, not just the page on screen                                                  | The other four are decided independently                      |
| `grouping`            | `"client" \| "server" \| false` | `groupBy` groups in the browser, or renders the server's group rows                                  | `groupBy` is ignored, and the status bar says why             |
| `selectAcrossPages`   | `boolean`                       | The "select all N matching" banner after a full page is selected                                     | Selection stays the rows on screen                            |
| `exportScope`         | `"all" \| "page"`               | A source-owned `allFilteredRows` route may serve `scope: "all"`; it does not retrieve rows by itself | The Export button is disabled, with the reason on the control |
| `totalCount`          | `"exact" \| "loaded"`           | `total` is the match count                                                                           | `total` is what has arrived so far                            |
| `aggregateOperations` | `readonly string[]` (optional)  | The aggregate ids the backend computes                                                               | The five standard functions are assumed                       |

**Omit `capabilities` and nothing changes.** The table reads the same answers
off the source's shape, exactly as it always has: `allFilteredRows` present
means the full dataset, `groups` present means the server grouped, a non-zero
`total` means the count is real — which is why every source `useFrontendData`
and `useQuerySource` build already answers correctly without declaring
anything. Declare it when the shape is misleading in either direction: a paged
source whose backend permits full exports (with the actual request wired on
the export feature), or an in-memory slice that must not pretend to be the
whole set.

Capabilities describe support; they are not transport. `exportScope: "all"`
without rows or a retrieval handler leaves Export all disabled. A source-owned
route needs `allFilteredRows` to be present and the declaration to permit
`"all"`. A host that wires `exportCsv.onExportAll`, `exportCsv.request`, or
`exportCsv.fetchAll` supplies an independent executable route, so it can reach
the rest whatever the source can or cannot retrieve. `onExportAll` is the
server-built route: it receives the page-free current view, reports progress,
and supports cancellation without loading rows into the table. See
[browser and server-built exports](./exporting.md).

## Cache keys for TanStack Query and SWR

Wiring the table to a query library means turning the emitted `TableQuery` into
a cache key. Hand-rolling that fails in two ways that are hard to see: a key
built from an object literal changes whenever `filters` is rebuilt, so the
cache misses on every keystroke; and invalidation after a save either refetches
the whole endpoint or only the page on screen.

```tsx
import { useInfiniteQuery, useQueryClient } from "@tanstack/react-query";
import { tableQueryKey, tableQueryBaseKey } from "@adapttable/core";

// `query` is the `TableQuery` the table emitted; `fetchPeople` returns a
// `PaginatedResponse` for it.
const queryClient = useQueryClient();
const infinite = useInfiniteQuery({
  queryKey: tableQueryKey(query, { scope: "people" }),
  queryFn: ({ signal }) => fetchPeople(query, signal),
  initialPageParam: 1,
  getNextPageParam: (last) => (last.hasNextPage ? last.page + 1 : undefined),
});

// after a write — every page of this view, nothing else
queryClient.invalidateQueries({
  queryKey: tableQueryBaseKey(query, { scope: "people" }),
});
```

- **`tableQueryBaseKey`** covers what decides _which_ rows: search, filters,
  sort, grouping, page size.
- **`tableQueryKey`** appends _where_ in them the table is: page and cursor.

The full key starts with the base key, so a library that matches by prefix —
TanStack Query does — invalidates every page of a view from the base key alone.
Both are stable across renders and ignore the order a filter object was built
in, so an identical query always produces an identical key.

Pass `scope` when a page shows more than one table, so they never share an
entry. For SWR, hand `useSWR` the array directly or join it — the parts are
strings.

Neither library is imported or depended on here; these are plain arrays that
happen to be exactly what both expect. The options shape is exported as
`TableQueryKeyOptions`.

## Which requests actually fire

`onQueryChange` fires per real change, not per render. Four guarantees:

- **One request per query.** Queries are compared by value, so setting the same
  search term three times in a tick or an identical re-render collapses into a
  single call. Under StrictMode's development double-mount the handler runs
  twice and the first call's `signal` is already aborted, so forwarding
  `signal` to `fetch` leaves one live request.
- **Setting a value it already holds is not a change.** No request fires.
- **A superseded request aborts.** When a newer query replaces an in-flight
  one, the previous call's `signal` fires. Forward it to `fetch` and an
  out-of-order response dies at the source rather than overwriting fresher
  rows.
- **Returning to a value re-requests it.** Typing `a` → `ab` → `a` fires three
  times. The first `a` was aborted the moment `ab` superseded it, so collapsing
  the third call would leave the table with nothing in flight and nothing to
  show.

`refetch()` is the one deliberate exception: it asks for fresh data, so it
fires even though the query has not changed.

Using `useQuerySource` instead? Deduplication is your query library's, keyed
the way you configured it, and these guarantees do not apply.

## Options

| Prop            | Type                                                                                       | Default  | Description                                                                                                                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`          | `readonly TRow[]`                                                                          | —        | Frontend tier: all rows. Server tier: the current page, exactly as the server returned it.                                                                                                                                                     |
| `total`         | `number`                                                                                   | `0`      | Server tier: total row count across all pages (drives the pager).                                                                                                                                                                              |
| `loading`       | `boolean`                                                                                  | `false`  | Server tier: request in flight (skeleton when no rows yet, subtle refresh indicator otherwise).                                                                                                                                                |
| `onQueryChange` | `(query: TableQuery, info: { signal: AbortSignal; key: string }) => void \| Promise<void>` | —        | Server tier: fired per consolidated query change, once on mount included. `info.key` identifies the request; echo it back as `responseKey` to say which one the rows answer.                                                                   |
| `responseKey`   | `string`                                                                                   | —        | The `info.key` of the request the current `data` answers (see [Row grouping](./row-grouping.md#server-tiers)).                                                                                                                                 |
| `aggregates`    | `readonly QueryAggregate[]`                                                                | —        | Developer defaults sent as `query.aggregates`; sent only when the source declares `supports.aggregates` (a `useServerData` / `useQuerySource` option). Reader overrides overlay this; Restore defaults returns here, not to the last response. |
| `error`         | `Error \| null`                                                                            | `null`   | Forwarded error to display.                                                                                                                                                                                                                    |
| `source`        | `TableSource<TRow>`                                                                        | —        | Full control: a prebuilt source from `useFrontendData` / `useQuerySource` / your own.                                                                                                                                                          |
| `mode`          | `"frontend" \| "server"`                                                                   | inferred | Pins the tier; `"server"` requires `onQueryChange`, `"frontend"` turns it into a notification (see [Explicit `mode`](#explicit-mode--when-inference-isnt-what-you-meant)).                                                                     |

## Notes

- **Picking a tier**: rows already in memory (up to a few thousand) →
  frontend. A paginated API and no query library → server. Caching, infinite
  scroll, prefetching, or an existing TanStack Query setup → `source` with
  `useQuerySource`.
- The hooks behind the first two tiers — `useFrontendData` and
  `useServerData` — are exported for headless use; `useTableData` is the
  resolver that picks between them.
- `useQuerySource` accepts `selectPage` (a `PageSelector` — project your
  own page shape to `{ rows, total? }` when it isn't `PaginatedResponse`),
  `baseParams` (static params merged into every call, e.g. a parent scope
  id), and `sanitizeParams`. Its query argument is typed structurally as
  `InfiniteQueryLike`, so TanStack Query stays a type-only peer. See
  [`examples/mui-query-source.tsx`](../examples/mui-query-source.tsx) for a complete
  runnable version.
- `selectPage` is read through a ref: the projected rows recompute when
  fetched pages, pagination mode, or `selectorKey` change — not when the
  selector function's identity changes. Memoizing `selectPage` alone cannot
  trigger a re-projection. Pass the closed-over input as `selectorKey`
  when a memoized selector must re-run against unchanged fetched pages:

  ```tsx
  const selectPage = useCallback(
    (page: Page) => ({
      rows: page.items.map((row) => ({ ...row, name: `${row.name}${suffix}` })),
      total: page.pagination.total,
    }),
    [suffix]
  );
  const source = useQuerySource({
    usePaginatedQuery,
    selectPage,
    selectorKey: suffix,
  });
  ```

  `selectorKey` accepts only a stable `string` or `number`. An unmemoized
  inline selector that closes over changing values and omits the key will
  keep showing the previous projection until the next fetch.

- On the server tier, `source.refetch()` re-emits the current query;
  out-of-range pages and stale responses are handled for you via the abort
  signal.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

---

# React table headless rendering — useDataTable

`useDataTable` from `@adapttable/react` is the table without markup. Give it
a `TableSource` and your columns; it returns the rows to draw, the sort,
search, pagination and selection state, and prop-getters that put the right
roles, ARIA attributes and handlers on elements you render yourself. Search,
sorting, paging and URL state work exactly as they do under a kit's
`<DataTable>`.

```tsx
import {
  type ColumnDef,
  useDataTable,
  useFrontendData,
} from "@adapttable/react";

interface Person {
  id: string;
  name: string;
  team: string;
  salary: number;
}

const columns: ColumnDef<Person>[] = [
  { key: "name", header: "Name", sortable: true },
  { key: "team", header: "Team", sortable: true },
  {
    key: "salary",
    header: "Salary",
    align: "end",
    sortable: true,
    accessor: (row) => row.salary.toLocaleString(),
    sortValue: (row) => row.salary,
  },
];

export function PeopleTable({ people }: { people: Person[] }) {
  const source = useFrontendData({
    data: people,
    columns,
    paginationMode: "paged",
  });
  const table = useDataTable({ source, columns, rowKey: (row) => row.id });

  return (
    <div>
      <input {...table.getSearchInputProps()} />

      <table {...table.getTableProps()}>
        <thead>
          <tr {...table.getHeaderRowProps()}>
            {table.columns.map((column) => (
              <th key={column.key} {...table.getHeaderCellProps(column)}>
                {column.sortable ? (
                  <button {...table.getSortButtonProps(column)}>
                    {column.header}
                    {table.sortBy === column.key &&
                      (table.sortDir === "asc" ? " ▲" : " ▼")}
                  </button>
                ) : (
                  column.header
                )}
              </th>
            ))}
          </tr>
        </thead>
        <tbody>
          {table.rows.map((row, index) => (
            <tr key={table.getRowKey(row)} {...table.getRowProps(row, index)}>
              {table.columns.map((column) => (
                <td key={column.key} {...table.getCellProps(column)}>
                  {table.getCellContent(column, row, index)}
                </td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>

      {table.isEmpty && <p>{table.labels.noData}</p>}

      <nav aria-label="Pagination">
        <button
          type="button"
          disabled={source.page <= 1}
          onClick={() => source.setPage(source.page - 1)}
        >
          Previous
        </button>
        <span>
          {table.pagination.fromIndex}–{table.pagination.toIndex} of{" "}
          {source.total}
        </span>
        <button
          type="button"
          disabled={source.page >= table.pagination.totalPages}
          onClick={() => source.setPage(source.page + 1)}
        >
          Next
        </button>
      </nav>
    </div>
  );
}
```

That is a complete table: typing in the box searches after a 300 ms
debounce, a header button cycles its column ascending → descending →
cleared, and the page, search and sort live in the URL.

## How it works

Two hooks, two jobs:

1. **A source** owns the data and the query state — rows, total, page,
   limit, search, sort, filters, grouping — and the setters that change
   them. It is a `TableSource`, the same contract every kit consumes; see
   [Concepts](./concepts.md#the-tablesource-contract).
2. **`useDataTable`** reads the source and the columns and derives what
   rendering needs: the visible columns for the current layout, the
   debounced search value, pagination figures, selection, filter chips and
   the prop-getters.

`useDataTable` never renders and never fetches. Everything it returns is a
function of the source and the options, so the same hook drives a `<table>`,
a card list, a virtualized grid, or a design system's own components.

Columns are the React `ColumnDef` a kit takes. A column without a `header`
gets one humanized from its `key`, and a column without an `accessor` or
`Cell` reads the row by its key, exactly as under `<DataTable>`.

## Building a source

Every source builder returns a `TableSource`, and `useDataTable` cannot tell
them apart. Pick by where the rows live — the tiers themselves are covered in
[Data tiers](./data-tiers.md).

### In memory — `useFrontendData`

```tsx
import { useFrontendData } from "@adapttable/react";

const source = useFrontendData({ data: people, columns });
```

Search, sort and paging run in memory. Pass `columns` so sorting can read
each column's `sortValue`; `getSearchText`, `getSortValue` and `filterFn`
override the defaults, and `getRowId` defaults to `String(row.id)`.
`paginationMode` defaults to `"auto"` — infinite on viewports at or below
768 px, paged above — so set `"paged"` or `"infinite"` when your markup
renders only one of them.

### Your own fetch — `useServerData`

```tsx
import { useServerData } from "@adapttable/react";
import { useState } from "react";

interface Person {
  id: string;
  name: string;
}

export function usePeopleSource() {
  const [rows, setRows] = useState<Person[]>([]);
  const [total, setTotal] = useState(0);
  const [loading, setLoading] = useState(false);

  return useServerData({
    rows,
    total,
    loading,
    paginationMode: "paged",
    onQueryChange: async (query, { signal }) => {
      setLoading(true);
      try {
        const params = new URLSearchParams({
          page: String(query.page),
          limit: String(query.limit),
          search: query.search,
        });
        const res = await fetch(`/api/people?${params}`, { signal });
        const body = (await res.json()) as { items: Person[]; total: number };
        setRows(body.items);
        setTotal(body.total);
      } finally {
        setLoading(false);
      }
    },
  });
}
```

`onQueryChange` fires with one consolidated `TableQuery` whenever the query
changes, including once on mount with the URL-restored values, and aborts
the previous call's `signal` when a newer query supersedes it.
`supports` opts the query into the optional fields listed in
[What the query carries](./data-tiers.md#what-the-query-carries-and-how-it-grows);
`facetKeys`, `aggregates`, `nextCursor` and `expandedIds` supply their values.

### A query library — `useQuerySource`

`useQuerySource({ usePaginatedQuery })` wraps your `useInfiniteQuery`-style
query hook into the same contract: it flattens pages in infinite mode, shows the
latest page in paged mode, and clamps out-of-range pages. The full TanStack
Query example is in [Data tiers — Full control](./data-tiers.md#3-full-control--source).

## `useDataTable` options

| Option                  | Type                                | Default        | Description                                                                             |
| ----------------------- | ----------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `source`                | `TableSource<TRow>`                 | required       | The data and query state.                                                               |
| `columns`               | `ColumnDef<TRow>[]`                 | required       | Column definitions.                                                                     |
| `rowKey`                | `(row: TRow) => string`             | required       | Stable row identity; the React key and, by default, the selection id.                   |
| `tableLabel`            | `string`                            | `labels.table` | The table's accessible name.                                                            |
| `labels`                | `TableLabels`                       | English        | Label overrides, merged over the defaults.                                              |
| `locale`                | `string`                            | —              | Resolves per-column `i18n` data paths for bare-key columns.                             |
| `dir`                   | `"ltr" \| "rtl"`                    | `"ltr"`        | Written to the table element by `getTableProps`.                                        |
| `forceMobile`           | `boolean`                           | `false`        | Use the mobile column set; reported back as `isMobile`.                                 |
| `mobileIdentityColumns` | `number`                            | —              | Deprecated and ignored; removed in v4. `hideOnMobile` decides the mobile column set.    |
| `searchDebounceMs`      | `number`                            | `300`          | Delay between typing and `source.setSearch`.                                            |
| `multiSort`             | `boolean`                           | `false`        | Shift-press on a sort button adds or cycles a sort level instead of replacing the sort. |
| `bulkActions`           | `BulkAction[]`                      | —              | Any action turns selection on.                                                          |
| `selectionGetId`        | `(row: TRow) => string`             | `rowKey`       | Selection id when it differs from the row key.                                          |
| `selectedIds`           | `readonly string[]`                 | —              | Controlled selection.                                                                   |
| `onSelectedIdsChange`   | `(ids: string[]) => void`           | —              | Change handler for the controlled selection.                                            |
| `filterLabels`          | `Record<string, ChipLabelResolver>` | —              | Chip label per filter key; drives `filterChips`.                                        |
| `fitColumns`            | `boolean`                           | `false`        | Share the container width: `flex` columns get a percentage width.                       |
| `columnWidths`          | `Record<string, number>`            | —              | User widths (for example from a column layout); they win over `width` and `flex`.       |

## The result

| Field                                   | What it is                                                                                      |
| --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `rows`                                  | The rows for the current slice — the page, or everything loaded in infinite mode.               |
| `columns`                               | The columns to render for the current layout, with headers and accessors resolved.              |
| `isEmpty`                               | `true` when there are no rows and the first load is not in progress.                            |
| `isMobile`                              | The `forceMobile` value.                                                                        |
| `labels`                                | Every label, defaults merged with your overrides.                                               |
| `dir`                                   | The resolved direction.                                                                         |
| `pagination`                            | `{ totalPages, safePage, fromIndex, toIndex }`; the indices are 1-based and `0` when empty.     |
| `sortBy` / `sortDir`                    | The primary sort.                                                                               |
| `toggleSort(key)`                       | Advance a column through ascending → descending → cleared.                                      |
| `searchValue` / `setSearchValue`        | The input's immediate value and its setter; the source receives it after the debounce.          |
| `sortByOptions`                         | `{ value, label }` for every sortable column with a text label — the options for a sort select. |
| `selection`                             | `SelectionState` when `bulkActions` is non-empty, else `null`.                                  |
| `filterChips`                           | Removable `{ key, label, onRemove }` chips for active filters that have a `filterLabels` entry. |
| `activeFilterCount`                     | `filterChips.length`.                                                                           |
| `source`                                | The source you passed, for `setPage`, `setLimit`, `fetchNextPage` and the rest.                 |
| `getRowKey(row)`                        | The row's React key — `rowKey`, kept out of `getRowProps`.                                      |
| `getCellContent(column, row, rowIndex)` | The column's `Cell` component when set, else its `accessor` value, else `null`.                 |

Selection is keyed by id, so it survives page, sort and page-size changes; it
resets when the search, the filters or the grouping change the result set.

## Prop-getters

Each getter returns a plain object to spread on an element. Pass your own
props as the last argument and they are merged: `className` values are
joined, `style` objects are merged, event handlers (`on` followed by a
capital letter) both run — the getter's first — and any other key you pass
replaces the getter's value.

```tsx
<tr
  key={table.getRowKey(row)}
  {...table.getRowProps(row, index, {
    className: "people-row",
    onClick: () => openPerson(row.id),
  })}
/>
```

| Getter                               | Returns                                                                                                                                                                                   |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getTableProps(props?)`              | `role: "table"`, `dir`, `aria-label` (`tableLabel`, else `labels.table`).                                                                                                                 |
| `getHeaderRowProps(props?)`          | `role: "row"`.                                                                                                                                                                            |
| `getHeaderCellProps(column, props?)` | `role: "columnheader"`, `scope: "col"`, `aria-sort` (`"ascending"`, `"descending"` or `"none"` on sortable columns, absent otherwise), `data-sort-index`, `data-column-key`, and `style`. |
| `getSortButtonProps(column, props?)` | `type: "button"`, `disabled` (`true` when the column is not sortable), `onClick`, `data-sort-index`, and `aria-label` (`"Sort by: <header>"`).                                            |
| `getRowProps(row, index, props?)`    | `role: "row"`, `data-adapttable-part: "row"`, `data-row-id`, `data-index` (the `index` you pass), and `aria-selected` while selection is on. Never a `key`.                               |
| `getCellProps(column, props?)`       | `role: "cell"`, `data-column-key`, and `style`.                                                                                                                                           |
| `getSearchInputProps(props?)`        | `type: "search"`, `role: "searchbox"`, `value`, `placeholder` (`labels.searchPlaceholder`), `aria-label` (`labels.search`), and `onChange`.                                               |

The `style` on header and body cells carries `textAlign` from the column's
`align` (`start`, `center` or `end`, so it follows the writing direction) and,
when the column states any, `width`, `minWidth` and `maxWidth` — the user's
width from `columnWidths` first, then the column's `width`, then its `flex`
share under `fitColumns`.

`data-sort-index` is the column's 1-based place in a multi-column sort and is
present only while it is sorted. The sort button's `onClick` accepts the
click event: with `multiSort: true`, a Shift-press toggles the column's level
in the sort chain instead of replacing the sort.

`data-index` is also the attribute a virtualizer measures by, which is why
`getRowProps` takes the index: pass the row's position in the source rows,
not its position on screen.

## Selection

Pass `bulkActions` and `selection` becomes a `SelectionState`:

```tsx
import {
  type ColumnDef,
  useDataTable,
  useFrontendData,
} from "@adapttable/react";

interface Person {
  id: string;
  name: string;
}

const columns: ColumnDef<Person>[] = [{ key: "name" }];

export function SelectablePeople({
  people,
  onArchive,
}: {
  people: Person[];
  onArchive: (ids: string[]) => void;
}) {
  const source = useFrontendData({ data: people, columns });
  const table = useDataTable({
    source,
    columns,
    rowKey: (row) => row.id,
    bulkActions: [{ key: "archive", label: "Archive", onClick: onArchive }],
  });
  const selection = table.selection;

  return (
    <table {...table.getTableProps()}>
      <thead>
        <tr {...table.getHeaderRowProps()}>
          <th scope="col">
            <input
              type="checkbox"
              aria-label={table.labels.selectAll}
              checked={selection?.headerState === "all"}
              onChange={() => selection?.toggleAll()}
            />
          </th>
          {table.columns.map((column) => (
            <th key={column.key} {...table.getHeaderCellProps(column)}>
              {column.header}
            </th>
          ))}
        </tr>
      </thead>
      <tbody>
        {table.rows.map((row, index) => (
          <tr key={table.getRowKey(row)} {...table.getRowProps(row, index)}>
            <td>
              <input
                type="checkbox"
                aria-label={table.labels.selectRow}
                checked={selection?.isSelected(row.id) ?? false}
                onChange={() => selection?.toggle(row.id)}
              />
            </td>
            {table.columns.map((column) => (
              <td key={column.key} {...table.getCellProps(column)}>
                {table.getCellContent(column, row, index)}
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}
```

`selection` also carries `selectedIds`, `selectedCount`, `clear`,
`replace`, `selectAllMatching` and `allMatching` for a "select every match"
banner, and `headerState` (`"all"`, `"some"` or `"none"`) for an
indeterminate header box. `useBulkActionRunner` runs an action through a
confirm handler; see [Selection & bulk actions](./selection.md).

## Mobile cards

`useDataTable` does not watch the viewport. Read it with `useIsMobile()` —
a `(max-width: 768px)` media query by default, `useIsMobile(px)` for another
breakpoint — and pass the answer as `forceMobile`. `columns` then drops the
columns marked `hideOnMobile`, and mobile-only columns (`hideOnDesktop`)
appear.

```tsx
import {
  type ColumnDef,
  useDataTable,
  useFrontendData,
  useIsMobile,
} from "@adapttable/react";

interface Person {
  id: string;
  name: string;
  team: string;
  email: string;
}

const columns: ColumnDef<Person>[] = [
  { key: "name", header: "Name", sortable: true },
  { key: "team", header: "Team", sortable: true },
  { key: "email", header: "Email", hideOnMobile: true },
];

export function People({ people }: { people: Person[] }) {
  const isMobile = useIsMobile();
  const source = useFrontendData({
    data: people,
    columns,
    paginationMode: "paged",
  });
  const table = useDataTable({
    source,
    columns,
    rowKey: (row) => row.id,
    forceMobile: isMobile,
  });

  if (!table.isMobile) {
    // …the <table> from the first example
    return null;
  }

  return (
    <div>
      <label>
        {table.labels.sortBy}{" "}
        <select
          value={table.sortBy ?? ""}
          onChange={(event) =>
            source.setSort(event.currentTarget.value || undefined, "asc")
          }
        >
          <option value="">—</option>
          {table.sortByOptions.map((option) => (
            <option key={option.value} value={option.value}>
              {option.label}
            </option>
          ))}
        </select>
      </label>

      <ul aria-label={table.labels.table}>
        {table.rows.map((row, index) => (
          <li key={table.getRowKey(row)}>
            <dl>
              {table.columns.map((column) => (
                <div key={column.key}>
                  <dt>{column.mobileLabel ?? column.header}</dt>
                  <dd>{table.getCellContent(column, row, index)}</dd>
                </div>
              ))}
            </dl>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

A card has no header to click, so sorting moves to a select built from
`sortByOptions`. `getRowProps` returns `role: "row"`, which belongs inside a
table; a list item takes its key from `getRowKey` instead. Kit adapters make
the same switch at the same 768 px default — see
[Mobile cards](./mobile.md).

## Virtualization

`useTableVirtualization` windows any list of rows: it returns the slice to
mount and the space above and below it. It is exported from
`@adapttable/react` and uses `@tanstack/react-virtual`, a dependency of that
package.

```tsx
import {
  type ColumnDef,
  useDataTable,
  useFrontendData,
  useTableVirtualization,
} from "@adapttable/react";
import { useRef } from "react";

interface Reading {
  id: string;
  sensor: string;
  value: number;
}

const columns: ColumnDef<Reading>[] = [
  { key: "sensor", header: "Sensor", sortable: true },
  {
    key: "value",
    header: "Value",
    align: "end",
    accessor: (row) => row.value,
  },
];

export function Readings({ readings }: { readings: Reading[] }) {
  const scrollRef = useRef<HTMLDivElement>(null);
  const source = useFrontendData({
    data: readings,
    columns,
    paginationMode: "infinite",
  });
  const table = useDataTable({ source, columns, rowKey: (row) => row.id });
  const virtual = useTableVirtualization({
    rows: table.rows,
    rowKey: table.getRowKey,
    enabled: true,
    estimateSize: 40,
    getScrollElement: () => scrollRef.current,
    onEndReached: source.fetchNextPage,
  });

  return (
    <div ref={scrollRef} style={{ maxHeight: 400, overflow: "auto" }}>
      <table {...table.getTableProps()}>
        <thead>
          <tr {...table.getHeaderRowProps()}>
            {table.columns.map((column) => (
              <th key={column.key} {...table.getHeaderCellProps(column)}>
                {column.header}
              </th>
            ))}
          </tr>
        </thead>
        <tbody>
          {virtual.paddingTop > 0 && (
            <tr aria-hidden="true" style={{ height: virtual.paddingTop }}>
              <td colSpan={table.columns.length} />
            </tr>
          )}
          {virtual.rows.map(({ row, index, key }) => (
            <tr
              key={key}
              ref={virtual.measureElement}
              {...table.getRowProps(row, index)}
            >
              {table.columns.map((column) => (
                <td key={column.key} {...table.getCellProps(column)}>
                  {table.getCellContent(column, row, index)}
                </td>
              ))}
            </tr>
          ))}
          {virtual.paddingBottom > 0 && (
            <tr aria-hidden="true" style={{ height: virtual.paddingBottom }}>
              <td colSpan={table.columns.length} />
            </tr>
          )}
        </tbody>
      </table>
    </div>
  );
}
```

With `getScrollElement` the window tracks that element; without it, it tracks
the page, and `scrollMargin` is the list's offset from the top of the
document. Each mounted row is measured through `measureElement`, which reads
the `data-index` that `getRowProps` writes. `onEndReached` fires once each
time the window reaches the last loaded row, which is where an infinite
source loads more.

| Option             | Type                                    | Default  | Description                                                                       |
| ------------------ | --------------------------------------- | -------- | --------------------------------------------------------------------------------- |
| `rows`             | `readonly TRow[]`                       | required | The rows to window — usually `table.rows`.                                        |
| `rowKey`           | `(row: TRow) => string`                 | required | Stable row key.                                                                   |
| `enabled`          | `boolean`                               | `false`  | Off returns every row with no spacers, so one render path serves both cases.      |
| `estimateSize`     | `number \| ((index: number) => number)` | `56`     | Row height estimate in px, before measurement.                                    |
| `overscan`         | `number`                                | `8`      | Rows mounted beyond each edge of the visible window.                              |
| `getScrollElement` | `() => Element \| null`                 | —        | The scroll box to track; omit to track the page.                                  |
| `scrollMargin`     | `number`                                | `0`      | Page mode only: the list's offset from the top of the document.                   |
| `onEndReached`     | `() => void`                            | —        | Called when the window reaches the last row.                                      |
| `expandable`       | `boolean`                               | `false`  | Rows carry a detail row; each pair is measured together through `measureRowPair`. |

It returns `{ enabled, rows, paddingTop, paddingBottom, measureElement?,
measureRowPair? }`, where each entry of `rows` is `{ row, index, key,
virtualItem? }`. A windowed table mounts a fraction of its rows, so tell
assistive technology the real size: set `aria-rowcount` on the table and
`aria-rowindex` on each row, as the kit adapters do — see
[Virtualization](./virtualization.md) and
[Accessibility](./accessibility.md).

## URL state

The source builders keep their state in the query string through
`useTableUrlState`, so a headless table has shareable, reload-safe URLs with
no extra code. All three builders take the same URL options:

| Option            | Default     | Description                                                                         |
| ----------------- | ----------- | ----------------------------------------------------------------------------------- |
| `urlSync`         | `true`      | `false` keeps the state in component memory instead of the URL.                     |
| `urlKey`          | —           | Namespace for this table's params (`left.q`, `left.page`, …) when a URL holds two.  |
| `urlAdapter`      | History API | A `UrlStateAdapter` for your router.                                                |
| `defaults`        | —           | Initial `page`, `limit`, `search`, sort and `extra` values while the URL is silent. |
| `numberExtraKeys` | —           | Extra-filter keys parsed as numbers.                                                |
| `arrayExtraKeys`  | —           | Extra-filter keys parsed as comma-separated arrays.                                 |

State that is not a query field has its own hook, each returning a value and
a change handler to wire into your controls:

| Hook                       | Returns                                                             |
| -------------------------- | ------------------------------------------------------------------- |
| `useColumnLayoutUrlState`  | `{ layout, onLayoutChange }` — hidden, order, pinned, widths, names |
| `useDensityUrlState`       | `{ density, onDensityChange }`                                      |
| `useGroupCollapseUrlState` | `{ collapsedGroupIds, onCollapsedGroupIdsChange }`                  |
| `useRowPinningUrlState`    | `{ pinnedRowIds, onPinnedRowIdsChange }`                            |

Each takes `urlKey`, `urlSync` and `urlAdapter`. `createHistoryAdapter()`
and `createMemoryAdapter(initialSearch?)` build adapters; router adapters
for react-router, TanStack Router and Next.js, the param names, and the
format guarantees are in [URL state](./url-state.md).

## Headless or an adapter

`useDataTable` is the right level when the markup is yours: a design system
the kits do not cover, a card-first layout, or a table embedded in a larger
component. The prop-getters carry the semantics; the controls around them —
pagination, filter forms, column menus, toolbars — are yours to draw.

When the goal is a complete table for a UI kit that AdaptTable does not ship,
with the feature factories, slots and every built-in behaviour, write an
adapter on the `@adapttable/react/adapter` builder tier instead — see
[Building an adapter](./building-an-adapter.md). Using a kit AdaptTable
already supports, `<DataTable>` from `@adapttable/<kit>` is the shorter path;
its `classNames`, `slots` and `renderCard` cover most visual changes without
leaving it ([Customization](./customization.md)).

## Notes

- `useDataTable` does not apply filters on its own. `useFrontendData`
  filters through `filterFn` and `filterTreeFn`; server sources send the
  filter state in the query. Set filter values with `source.setExtra`.
- `getTableProps` always returns `role: "table"`. Keyboard grid navigation
  (`role="grid"`, roving focus, ranges) is `useGridFocus`; see
  [Cell navigation](./cell-navigation.md#headless).
- Infinite mode without virtualization pairs with `useInfiniteScroll`, a
  sentinel ref that calls `fetchNextPage` as the end of the list comes into
  view; see [Pagination modes](./concepts.md#pagination-modes).
- Export works headless too: `downloadTableCsv({ source, columns, writer })`
  from `@adapttable/core` builds and downloads the file the export button
  would, with any writer — see [Excel (XLSX) export](./export-xlsx.md).

---

# Custom React table data source — the TableSource contract

Every `<DataTable>` renders one `TableSource<TRow>`: the rows to show, the
view state that produced them, and the setters that change it. The built-in
builders — `useFrontendData`, `useServerData`, `useQuerySource` — each return
one. When none of them fits your data layer, build the object yourself and
pass it as `source`; the table cannot tell the difference.

**Related:** [Data tiers](./data-tiers.md) · [Concepts](./concepts.md) ·
[Realtime](./realtime.md) · [API](./api.md#source-capabilities)

## Pick a builder first

Most data fits a builder, and a builder already handles the edge cases this
page lists.

| Your data                                            | Use                                                                                          |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Rows already in memory                               | `data` alone, or `useFrontendData` headless — [data tiers](./data-tiers.md#1-frontend--data) |
| Rows pushed into memory by a socket or poll          | `data` plus `applyRowPatches` / `useRowPatchStream` — [realtime](./realtime.md)              |
| A paginated endpoint you call yourself               | `onQueryChange`, or `useServerData` headless                                                 |
| TanStack Query `useInfiniteQuery`, caching, prefetch | `useQuerySource` — [full control](./data-tiers.md#3-full-control--source)                    |

A hand-rolled source fits when:

- your data layer already speaks its own protocol — a socket that answers
  queries and pushes invalidations, an SDK with its own paging object — and
  mapping it onto the contract is shorter than routing it through
  `onQueryChange`;
- the view state (page, sort, filters) must live in a store you already own,
  because other parts of the app read and write it;
- a test or story needs a fixed source with exact flags.

## Example — a socket that answers queries

The server receives a query over a WebSocket, replies with one page, and sends
`changed` when the data moves. `useTableUrlState` supplies the whole state
half of the contract; the hook adds the data half.

```tsx
import { useEffect, useRef, useState } from "react";
// or import from "@adapttable/mui", "@adapttable/chakra", "@adapttable/antd",
// "@adapttable/radix", "@adapttable/shadcn", "@adapttable/unstyled" — same exports everywhere.
import {
  DataTable,
  type TableSource,
  useTableUrlState,
} from "@adapttable/mantine";

interface Trade {
  id: string;
  symbol: string;
  price: number;
}

/** What the server sends back over the socket. */
type ServerMessage =
  | { type: "page"; requestId: number; rows: Trade[]; total: number }
  | { type: "error"; requestId: number; message: string }
  | { type: "changed" };

/** Paged only: there is never a next page to append. */
function noNextPage(): void {}

export function useTradeSource(url: string): TableSource<Trade> {
  // The state half: page, limit, search, sort, filters, grouping and every
  // setter, URL-synced, with each visible-row change resetting to page 1.
  const state = useTableUrlState({ urlKey: "trades" });

  const socketRef = useRef<WebSocket | null>(null);
  const latestRequest = useRef(0);
  const [open, setOpen] = useState(false);
  const [revision, setRevision] = useState(0);
  const [rows, setRows] = useState<readonly Trade[]>([]);
  const [total, setTotal] = useState(0);
  const [loaded, setLoaded] = useState(false);
  const [fetching, setFetching] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    const socket = new WebSocket(url);
    socketRef.current = socket;
    socket.onopen = () => setOpen(true);
    socket.onclose = () => setOpen(false);
    socket.onerror = () => {
      setFetching(false);
      setError(new Error("The trades feed is unavailable."));
    };
    socket.onmessage = (event: MessageEvent<string>) => {
      const message = JSON.parse(event.data) as ServerMessage;
      if (message.type === "changed") {
        // The server says the data moved: ask for the same view again.
        setRevision((n) => n + 1);
        return;
      }
      // A reply to a superseded query is dropped.
      if (message.requestId !== latestRequest.current) return;
      setFetching(false);
      if (message.type === "error") {
        setError(new Error(message.message));
        return;
      }
      setRows(message.rows);
      setTotal(message.total);
      setError(null);
      setLoaded(true);
    };
    return () => {
      socket.close();
      socketRef.current = null;
    };
  }, [url]);

  const { page, limit, search, sortBy, sortDir, extra } = state;
  useEffect(() => {
    const socket = socketRef.current;
    if (!open || !socket) return;
    latestRequest.current += 1;
    setFetching(true);
    socket.send(
      JSON.stringify({
        type: "query",
        requestId: latestRequest.current,
        page,
        limit,
        search,
        sortBy,
        sortDir,
        filters: extra,
      })
    );
  }, [open, revision, page, limit, search, sortBy, sortDir, extra]);

  return {
    ...state,
    rows,
    total,
    isLoading: !loaded,
    isFetching: fetching,
    isFetchingNextPage: false,
    hasNextPage: false,
    fetchNextPage: noNextPage,
    error,
    refetch: () => setRevision((n) => n + 1),
    paginationMode: "paged",
    capabilities: {
      fullDataset: false,
      grouping: false,
      selectAcrossPages: true,
      exportScope: "page",
      totalCount: "exact",
    },
  };
}

export function TradesTable() {
  const source = useTradeSource("wss://example.com/trades");
  return (
    <DataTable
      source={source}
      columns={[
        { key: "symbol", sortable: true },
        { key: "price", sortable: true, align: "end" },
      ]}
      rowKey={(row) => row.id}
    />
  );
}
```

## How it works

- `source` wins tier resolution: the table uses the object as it is and does
  no filtering, sorting or paging of its own. Passing `data` or
  `onQueryChange` alongside it dev-warns.
- `useTableUrlState` returns every state field and every setter the contract
  needs (`UseTableUrlStateResult` extends `TableStateMutators`), so spreading
  it covers that half. Pass `urlSync: false` to keep the same state in memory
  instead of the URL.
- The source re-sends its query whenever a state value changes, and on
  `refetch()` or a server `changed` message. Each request carries an id, and a
  reply to an older id is dropped, so a slow answer never overwrites a newer
  one.
- `isLoading` is true until the first page arrives and never again;
  `isFetching` is true whenever a request is in flight. The table draws the
  skeleton while `isLoading` holds and no rows exist, and a non-blocking
  refresh indicator for every later request.
- `capabilities` says this source serves one page at a time and counts the
  full match set. Grouping is off, so a `groupBy` in the URL is ignored and the
  status bar says why.

## The contract

`TableSource<TRow>` is exported from `@adapttable/core` and re-exported by
every kit. The members below are required.

### Data

| Member               | Type                    | What the table does with it                                                                                                |
| -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `rows`               | `readonly TRow[]`       | Renders them — the current page, or every loaded row in infinite mode.                                                     |
| `total`              | `number`                | Drives the pager and the "select all N matching" banner.                                                                   |
| `isLoading`          | `boolean`               | First load only. With no rows, the body renders the skeleton. A background refresh never raises it again.                  |
| `isFetching`         | `boolean`               | Any request in flight. Without `isLoading` or `isFetchingNextPage`, the table shows its refresh indicator and `aria-busy`. |
| `isFetchingNextPage` | `boolean`               | An append started by `fetchNextPage` is in flight. Always `false` in paged mode.                                           |
| `hasNextPage`        | `boolean`               | Infinite mode shows Load more and arms the scroll sentinel. Always `false` in paged mode.                                  |
| `fetchNextPage`      | `() => void`            | Appends the next page. A no-op in paged mode, while an append is in flight, or when the data is exhausted.                 |
| `error`              | `Error \| null`         | Non-null replaces the body with the error state and hides the pager.                                                       |
| `paginationMode`     | `"paged" \| "infinite"` | The resolved mode — never `"auto"`. Paged shows the footer pager; infinite shows Load more.                                |

### View state

| Member         | Type                           | Meaning                                                                            |
| -------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
| `page`         | `number`                       | Current 1-based page.                                                              |
| `limit`        | `number`                       | Current page size.                                                                 |
| `defaultLimit` | `number`                       | The size the rows-per-page list keeps offering after the reader picks another one. |
| `search`       | `string`                       | Committed search term.                                                             |
| `sortBy`       | `string \| undefined`          | Active sort column key.                                                            |
| `sortDir`      | `"asc" \| "desc" \| undefined` | Active sort direction.                                                             |
| `sortLevels`   | `readonly SortLevel[]`         | The multi-sort chain; empty unless multi-sort is in use.                           |
| `extra`        | `ExtraFilters`                 | The filter bag: `Record<string, string \| string[] \| number \| undefined>`.       |
| `groupBy`      | `string \| undefined`          | Row-grouping keys, comma-separated.                                                |

### Setters — `TableStateMutators`

Every setter that changes which rows are visible also resets to page 1.

| Member            | Signature                                                 | Obligation                                                                             |
| ----------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `setPage`         | `(next: number) => void`                                  | Set the 1-based page. The only setter that does not reset the page.                    |
| `setLimit`        | `(next: number) => void`                                  | Set the page size; reset to page 1.                                                    |
| `setSort`         | `(key: string \| undefined, dir?: SortDirection) => void` | Set or clear the single-column sort; reset the multi-sort chain and the page.          |
| `toggleSortLevel` | `(key: string) => void`                                   | Cycle the key in the chain: absent → asc → desc → removed. New keys append at the end. |
| `setSearch`       | `(next: string) => void`                                  | Set or clear the search term; reset to page 1.                                         |
| `setExtra`        | `(key: string, value: FilterValue) => void`               | Set one filter; reset to page 1.                                                       |
| `setExtras`       | `(updates: ExtraFilters) => void`                         | Set several filters in one commit; reset to page 1.                                    |
| `clearExtras`     | `() => void`                                              | Clear every filter; keep search and sort; reset to page 1.                             |
| `clearAll`        | `() => void`                                              | Clear search, sort, grouping, page and every filter in one commit.                     |
| `setGroupBy`      | `(key: string \| undefined) => void`                      | Set or clear the grouping keys; reset to page 1.                                       |

The table's Clear filters action calls `clearExtras()`, then
`setFilterTree?.(undefined)`. The empty state reads "no results" rather than
"no data" when a filter chip is active, `extra` has a key, or `search` is
non-empty.

## Optional members

A source adds these when it can answer them. Leaving one out turns off what it
would have unlocked; nothing else changes.

| Member                                                   | Add it when                                                                                                                                                              |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `refetch`                                                | The source can re-run its fetch. The error state offers Retry only when this exists, and shows it as retrying while `isFetching` is true.                                |
| `allFilteredRows`                                        | Every row matching search, filters and sort is in hand, unpaginated. Client grouping, export of every matching row and select-across-pages read it.                      |
| `allSearchedRows`                                        | Rows after search, before filters. Facet counts start here so a checklist can exclude its own filter.                                                                    |
| `facets`                                                 | You computed distinct-value counts per filter key (`FacetMap`) — on a server, the counts for `query.facets`.                                                             |
| `filterTree` / `setFilterTree`                           | The source applies a nested AND/OR tree ([advanced filters](./filter-tree.md)).                                                                                          |
| `capabilities`                                           | The shape of the source would mislead the table — see below.                                                                                                             |
| `groups`                                                 | The server computed the groups (`QueryGroupRow<TRow>[]`) for the current `groupBy`. The table renders them instead of grouping the one page it holds.                    |
| `groupAggregations` / `queryAggregates`                  | With server groups: the operations the rows on screen were computed with, and the developer's original `query.aggregates`.                                               |
| `aggregateOperations`                                    | The backend names the aggregate ids it computes. Omitted, the five standard functions are assumed.                                                                       |
| `honorsAggregates`                                       | The source computes the `query.aggregates` it receives. On server groups the reader's aggregate controls are enabled only when this is `true`. Frontend sources omit it. |
| `groupAggregateOverrides` / `setGroupAggregateOverrides` | The source keeps the reader's per-session aggregate choices. `useTableUrlState` provides both.                                                                           |
| `initializeGroupBy`                                      | Set grouping only when no grouping state exists yet, so an explicit empty value still wins. `useTableUrlState` provides it.                                              |
| `tableEngine`                                            | The source is backed by a `TableEngine` — see [the engine and revisions](#the-engine-and-revisions).                                                                     |

## State that lives in your own store

When page, sort and filters must live in a store you own, implement the setters
yourself. This hook keeps the view in React state; the same functions map onto
any store's actions.

```ts
import { useState } from "react";
import type {
  ExtraFilters,
  SortLevel,
  TableSource,
  TableStateMutators,
} from "@adapttable/core";

/** The view a table reads and writes, held wherever your app keeps state. */
export type ViewState = TableStateMutators &
  Pick<
    TableSource<unknown>,
    | "page"
    | "limit"
    | "defaultLimit"
    | "search"
    | "sortBy"
    | "sortDir"
    | "extra"
    | "groupBy"
  >;

interface View {
  page: number;
  limit: number;
  search: string;
  sortLevels: readonly SortLevel[];
  extra: ExtraFilters;
  groupBy: string | undefined;
}

const DEFAULT_LIMIT = 25;
const INITIAL: View = {
  page: 1,
  limit: DEFAULT_LIMIT,
  search: "",
  sortLevels: [],
  extra: {},
  groupBy: undefined,
};

/** absent → asc → desc → removed; a new key joins the end of the chain. */
function cycleLevel(
  levels: readonly SortLevel[],
  key: string
): readonly SortLevel[] {
  const current = levels.find((level) => level.key === key);
  if (!current) return [...levels, { key, dir: "asc" }];
  if (current.dir === "asc") {
    return levels.map((level) =>
      level.key === key ? { key, dir: "desc" } : level
    );
  }
  return levels.filter((level) => level.key !== key);
}

export function useViewState(): ViewState {
  const [view, setView] = useState<View>(INITIAL);
  // Every change to which rows are visible starts again at page 1.
  const narrow = (next: (prev: View) => Partial<View>) =>
    setView((prev) => ({ ...prev, ...next(prev), page: 1 }));
  const head = view.sortLevels[0];

  return {
    ...view,
    defaultLimit: DEFAULT_LIMIT,
    sortBy: head?.key,
    sortDir: head?.dir,
    setPage: (page) => setView((prev) => ({ ...prev, page })),
    setLimit: (limit) => narrow(() => ({ limit })),
    setSort: (key, dir = "asc") =>
      narrow(() => ({ sortLevels: key ? [{ key, dir }] : [] })),
    toggleSortLevel: (key) =>
      narrow((prev) => ({ sortLevels: cycleLevel(prev.sortLevels, key) })),
    setSearch: (search) => narrow(() => ({ search })),
    setExtra: (key, value) =>
      narrow((prev) => ({ extra: { ...prev.extra, [key]: value } })),
    setExtras: (updates) =>
      narrow((prev) => ({ extra: { ...prev.extra, ...updates } })),
    clearExtras: () => narrow(() => ({ extra: {} })),
    clearAll: () => setView((prev) => ({ ...INITIAL, limit: prev.limit })),
    setGroupBy: (groupBy) => narrow(() => ({ groupBy })),
  };
}
```

Swap `useTableUrlState({ urlKey: "trades" })` in the socket example for
`useViewState()` and the rest of the source is unchanged. `sortBy` and
`sortDir` read the head of the chain, so single-column and multi-column
sorting stay one state.

## `capabilities` — what the source can do

Some controls need more than one page: exporting every row, grouping, "select
all 2,431 matching". `sourceCapabilities(source)` in `@adapttable/core` is the
one place the table decides what a source supports. A declared
`capabilities` object wins outright — it is used whole, not merged. Without
one, the answer is read off the source's shape:

| Capability          | Inferred as                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------ |
| `fullDataset`       | `true` when `allFilteredRows` is present.                                                        |
| `grouping`          | `"server"` when `groups` is present; otherwise `"client"` when `fullDataset`; otherwise `false`. |
| `selectAcrossPages` | `true` when `fullDataset`, or when `total` is greater than zero.                                 |
| `exportScope`       | `"all"` when `fullDataset`; otherwise `"page"`.                                                  |
| `totalCount`        | `"exact"` when `fullDataset`, or when `total` is greater than zero; otherwise `"loaded"`.        |

Declare `capabilities` when the shape says the wrong thing: a paged source
whose backend can export or select everything, or an in-memory slice that must
not pose as the whole set. A declaration describes support; it does not move
data. `exportScope: "all"` without `allFilteredRows` still needs an export
route on the export feature — see
[what a source can do](./data-tiers.md#what-a-source-can-do--capabilities) and
[browser and server-built exports](./exporting.md).

## The engine and revisions

`tableEngine` is optional, and only `useFrontendData` sets it among the
builders. When a source carries one, the table wraps it with
`createNeutralTable(engine, engine.tableId, binding)` and publishes the
resulting `NeutralTable` — the shape `@adapttable/ai` reads — alongside the
rows it renders. A source without an engine renders exactly the same.

Revisions belong to the engine, not to the source. `TableRevisions` carries
four counters — `data`, `view`, `schema`, `policy` — that a subscriber wakes on
through `engine.subscribe(axes, listener)`, and `revisionToken(revisions)`
folds them into one comparable string. `TableSource` has no counter of its
own: the table reads a source on every render, so a hand-rolled source signals
change the way any React value does. Publish a new `rows` array when the data
changes and keep the same one when it does not — derived views compare arrays
by identity.

To back a custom source with an engine, build it with `createTableEngine` from
`@adapttable/core` — see
[the engine, and why it has no React in it](./concepts.md#the-engine-and-why-it-has-no-react-in-it).

## Notes

- `groupBy` alone never groups a one-page source. Grouping needs
  `allFilteredRows` (client) or `groups` (server); without either, the table
  ignores it and the status bar carries the reason.
- In infinite mode, `rows` is every row loaded so far and `fetchNextPage`
  appends to it — the adapters call it when the bottom of the list scrolls
  into view and from the Load more button.
- `refetch` may return a promise or nothing. The table calls it from the error
  state's Retry and does not await it.
- The table never owns the data. Edits, adds, deletes and reorders reach your
  app through feature callbacks; a source reports the result through `rows`.
- `TableSource`, `TableStateMutators`, `TableSourceCapabilities`,
  `sourceCapabilities` and `capabilityReason` are exported from
  `@adapttable/core`; the [API reference](./api.md#source-capabilities) lists
  their types.

---

# Build a React table adapter for any UI kit

An adapter is a kit's `DataTable` plus one entry per feature, each drawn with
that kit's own components. Every built-in adapter is built from
`@adapttable/react/adapter` — the same public entry a new one uses, with the
same semver promise as the main entry. The shell behind it resolves the data
tier, runs filters, sorting, paging, selection and keyboard wiring, and hands
back state; the adapter renders it.

**Related:** [Concepts](./concepts.md) · [Feature composition](./features.md) ·
[Customization](./customization.md) ·
[The adapter contract](./api.md#the-adapter-contract)

## Two ways to reach a kit

| Your kit                                                                    | Build                                                                           | Reference                                                                                           |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| A class-based design system (utility classes, tokens, no component library) | A class map over `@adapttable/unstyled`, which renders native elements          | [`@adapttable/shadcn`](../packages/react/adapter-shadcn/src/DataTable.tsx)                          |
| A component library (buttons, inputs, menus, drawers as components)         | A full adapter on `useDataTableShell`, every control drawn with a kit component | [`@adapttable/unstyled`](../packages/react/adapter-unstyled/src/DataTable.tsx), and each themed kit |

The shadcn adapter is the whole of the first pattern: its `DataTable` passes
`shadcnClassNames` to the unstyled `DataTable`, merging a caller's
`classNames` over the preset per part, and each feature subpath re-exports the
unstyled one (`export * from "@adapttable/unstyled/density"`). The rest of this
page covers the second pattern.

## Example — the root table

`@acme/ui` stands for your kit. `DesktopTable`, `MobileCards` and `Pager` are
the adapter's own files (see [the worked reference](#the-worked-reference--adapttableunstyled)).

```ts
// src/types.ts
import type { TableSource } from "@adapttable/core";
import type { BaseDataTableProps, UrlStateAdapter } from "@adapttable/react";
import type { DataModeProps } from "@adapttable/react/adapter";
import type { ReactNode } from "react";

/** The five wrapper hooks every themed kit honours. */
export interface DataTableClassNames {
  root?: string;
  toolbar?: string;
  table?: string;
  card?: string;
  footer?: string;
}

export interface DataTableSlots {
  empty?: ReactNode;
  noResults?: ReactNode;
  skeleton?: ReactNode;
}

export interface DataTablePropsBase<TRow> extends Omit<
  BaseDataTableProps<TRow>,
  "source"
> {
  source?: TableSource<TRow>;
  data?: readonly TRow[];
  total?: number;
  loading?: boolean;
  error?: Error | null;
  urlAdapter?: UrlStateAdapter;
  urlSync?: boolean;
  urlKey?: string;
  classNames?: DataTableClassNames;
  slots?: DataTableSlots;
}

/** `mode="server"` requires `onQueryChange` at compile time. */
export type DataTableProps<TRow> = DataTablePropsBase<TRow> &
  DataModeProps<TRow>;
```

```tsx
// src/DataTable.tsx
import { Alert, Button, Spinner, TextInput } from "@acme/ui";
import {
  DataTableShellView,
  FeatureHostProvider,
  FeatureProviders,
  FeatureSlot,
  STATUS_BAR,
  TableStatusAnnouncer,
  TOOLBAR_EXTRAS,
  useDataTableShell,
  useTableFeatures,
} from "@adapttable/react/adapter";
import type { ReactNode } from "react";

import { DesktopTable } from "./components/DesktopTable";
import { MobileCards } from "./components/MobileCards";
import { Pager } from "./components/Pager";
import type { DataTableProps } from "./types";

function noAutoForm(): ReactNode {
  return null;
}

function DataTableContent<TRow>(incoming: Readonly<DataTableProps<TRow>>) {
  const props = useTableFeatures(incoming);
  const shell = useDataTableShell<TRow>(props, noAutoForm);

  return (
    <DataTableShellView shell={shell}>
      {(view) => {
        const { chrome, labels, source, table } = view;
        const body = {
          skeleton: props.slots?.skeleton ?? <Spinner label={labels.loading} />,
          empty: (chrome.emptyVariant === "noResults"
            ? props.slots?.noResults
            : undefined) ??
            props.slots?.empty ?? (
              <p data-adapttable-part="empty">
                {chrome.emptyVariant === "noResults"
                  ? labels.noResults
                  : labels.noData}
              </p>
            ),
          desktop: <DesktopTable {...view.tableProps} />,
          mobile: <MobileCards {...view.tableProps} />,
        }[chrome.body];

        return (
          <FeatureHostProvider host={view.featureHost}>
            <div
              ref={view.rootRef}
              dir={props.dir}
              data-adapttable-part="root"
              data-mobile={chrome.isMobile || undefined}
              aria-busy={chrome.isRefreshing || undefined}
              className={props.classNames?.root}
            >
              <TableStatusAnnouncer announcement={view.statusAnnouncement} />
              <div
                data-adapttable-part="toolbar"
                className={props.classNames?.toolbar}
              >
                {props.searchable !== false && (
                  <TextInput
                    {...table.getSearchInputProps()}
                    data-adapttable-part="search"
                  />
                )}
                <FeatureSlot
                  slot={TOOLBAR_EXTRAS}
                  props={{ ...view.toolbarProps, labels }}
                />
              </div>
              {chrome.errorState ? (
                <Alert tone="danger" data-adapttable-part="error">
                  {chrome.errorState.error.message}
                  {chrome.errorState.retry && (
                    <Button onClick={chrome.errorState.retry}>
                      {labels.retry}
                    </Button>
                  )}
                </Alert>
              ) : (
                body
              )}
              {chrome.showFooter && (
                <Pager
                  pagination={table.pagination}
                  source={source}
                  labels={labels}
                />
              )}
              <FeatureSlot
                slot={STATUS_BAR}
                props={{
                  enabled: props.statusBar === true,
                  notices: chrome.featureNotices,
                  shown: source.rows.length,
                  page: source.page,
                  limit: source.limit,
                  total: source.total,
                  selected: table.selection?.selectedCount ?? 0,
                  stats: view.selectionStats,
                  labels,
                  locale: props.locale,
                }}
              />
            </div>
          </FeatureHostProvider>
        );
      }}
    </DataTableShellView>
  );
}

/** Mount the providers the composed features contribute, then the table. */
export function DataTable<TRow>(incoming: Readonly<DataTableProps<TRow>>) {
  const props = useTableFeatures(incoming);
  return (
    <FeatureProviders props={props}>
      <DataTableContent<TRow> {...props} />
    </FeatureProviders>
  );
}
```

The skeleton leaves out the filters, saved views, column menu, bulk bar and
the other root slots; [where the table places slots](#where-the-table-places-slots)
lists each one and where the unstyled adapter puts it.

## Example — a feature entry

A feature that draws a control keeps the headless factory's behaviour and adds
the kit's component to a slot. This is the whole of a kit's
`/fullscreen` entry (`@acme/adapttable/fullscreen` in the package below):

```tsx
// src/fullscreen.tsx
import { IconButton } from "@acme/ui";
import {
  extendFeature,
  slotRender,
  type StaticTableFeature,
  TOOLBAR_EXTRAS,
  type ToolbarExtrasSlotProps,
} from "@adapttable/react/adapter";
import { fullscreen as core } from "@adapttable/react/features";

function FullscreenButton(props: Readonly<ToolbarExtrasSlotProps>) {
  const { onToggleFullscreen, isFullscreen, labels } = props;
  if (!onToggleFullscreen) return null;
  return (
    <IconButton
      aria-label={
        isFullscreen === true ? labels.exitFullscreen : labels.enterFullscreen
      }
      data-adapttable-part="fullscreen-toggle"
      onClick={onToggleFullscreen}
    >
      {isFullscreen === true ? "✕" : "⛶"}
    </IconButton>
  );
}

/** Take the table fullscreen, with this kit's own toolbar toggle. */
export function fullscreen(): StaticTableFeature {
  return extendFeature(core(), [
    slotRender(TOOLBAR_EXTRAS, (props) => <FullscreenButton {...props} />),
  ]);
}
```

## Example — a Chrome and its required slot

A `*Chrome` component owns structure, labels and wiring; the visible control
is a slot the adapter must fill. `ColumnGroupToggleChrome` takes one:

```tsx
// src/column-groups.tsx
import { IconButton } from "@acme/ui";
import {
  COLUMN_GROUP_TOGGLE,
  type ColumnGroupToggleButtonProps,
  ColumnGroupToggleChrome,
  type ColumnGroupToggleProps,
  extendFeature,
  slotRender,
  type StaticTableFeature,
} from "@adapttable/react/adapter";
import { collapsibleColumnGroups as core } from "@adapttable/react/features";

/** The one visible control the chrome needs — drawn with this kit. */
function ToggleButton({
  label,
  expanded,
  className,
  onClick,
}: Readonly<ColumnGroupToggleButtonProps>) {
  return (
    <IconButton
      type="button"
      data-adapttable-part="column-group-toggle"
      aria-expanded={expanded}
      aria-label={label}
      className={className}
      onClick={onClick}
    >
      {expanded ? "▼" : "▶"}
    </IconButton>
  );
}

export function ColumnGroupToggle(props: Readonly<ColumnGroupToggleProps>) {
  return (
    <ColumnGroupToggleChrome {...props} slots={{ Button: ToggleButton }} />
  );
}

/** Collapse a header group, with this kit's chevron. */
export function collapsibleColumnGroups(): StaticTableFeature {
  return extendFeature(core(), [
    slotRender(COLUMN_GROUP_TOGGLE, (props) => (
      <ColumnGroupToggle {...props} />
    )),
  ]);
}
```

The unstyled adapter fills the same slot with a `<button>` and Mantine with an
`ActionIcon`, both carrying `data-adapttable-part="column-group-toggle"` —
same model, each kit's pixels.

## How it works

- **Two components.** `DataTable` resolves `features` with `useTableFeatures`
  and mounts `FeatureProviders` above the body, because a feature that owns
  hooks owns a provider, and its state has to exist before the body reads it.
  `DataTableContent` does the rendering.
- **`useDataTableShell(props, renderAutoForm)`** resolves the tier
  (`source`, else `onQueryChange`, else `data`), builds the declarative-filter
  runtime, wires the chrome, and returns the `tableProps` and `toolbarProps`
  bundles. `renderAutoForm(defs, source, registry)` runs only when there are
  declarative filter definitions, and returns the kit's filter form.
- **`DataTableShellView`** mounts the live gates — edit history, the chrome
  extras, the chrome body, find, grid focus, export and fullscreen — and
  calls its child with the finished view. The hook alone holds inert
  stand-ins for those, so read `toolbarProps`, `gridFocus`, `find` and
  `fullscreen` from `view`, not from the hook's return value.
- **`chrome.body`** names the region to draw: `"skeleton"`, `"empty"`,
  `"desktop"` or `"mobile"`. `chrome.errorState` is set while the source
  reports an error, and carries `retry` only when the source can refetch.
- **`FeatureSlot`** draws whatever the composed features put in that slot, and
  nothing when none did. A three-prop table therefore renders no fullscreen
  button, and pays nothing for one, until a caller composes `fullscreen()`.

## The Chrome + slots contract

AdaptTable unifies the model, never the pixels:

- The `*Chrome` components on `@adapttable/react/adapter` own structure only —
  layout, recursion over groups, keyboard wiring, localized labels and
  `data-adapttable-part` names. The state machines behind them live in
  `@adapttable/core`; the binding's hooks adapt them to React.
- Every visible control — input, select, checkbox, button, anything a reader
  clicks — is a **required slot** the adapter fills with its own kit's
  component. Slot members are required in the types, so a missing one fails
  to compile:

  ```text
  Property 'Button' is missing in type '{}' but required in type 'ColumnGroupToggleSlots'.
  ```

- Slots have no native fallback. `@adapttable/unstyled` renders native
  controls because native HTML is its kit; the shadcn adapter builds on it.
- Invisible chrome — live regions, announcers, layout structure — ships with
  the binding and is used as is: `TableStatusAnnouncer`, `GridFocusAnnouncer`,
  `RowReorderAnnouncer`.
- When a kit's overlay or portal misbehaves inside the filter popover, the fix
  belongs in that adapter — `disablePortal`, `getPopupContainer`, or the kit's
  native select — never in the slot contract.

## Feature entries

Each feature ships as its own subpath, named after the feature id in kebab
case. [Kit subpaths](./features.md#kit-subpaths) lists every one and whether it
draws kit UI; `/features` forwards `@adapttable/react/features` unchanged and
`/preset` builds `standardFeatures`. An adapter fills each one in one of three
ways.

### Factory helpers

For features with several kit surfaces, a helper takes the components and
returns the finished factory.

| Helper                               | Returns                                                                                      | Components you supply                                                                                                                                                                                                              |
| ------------------------------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createAdapterFiltersFeature`        | `filters`                                                                                    | `FiltersForm`, `ActiveFilterChips`, `FilterDrawer`, `FilterPopover`                                                                                                                                                                |
| `createAdapterGroupingFeature`       | `grouping`                                                                                   | `GroupHeaderRow`, `GroupHeaderCard`                                                                                                                                                                                                |
| `createAdapterGroupingPanelFeature`  | `groupingPanel`                                                                              | `GroupHeaderRow`, `GroupHeaderCard`, `GroupingPanel`                                                                                                                                                                               |
| `createAdapterEditingFeatures`       | `editing`, `rowEditing`, `batchEditing`, `dirtyIndicators`, `editHistory`, `undoRedoButtons` | `EditableCell`, `RowEditActions`, `BatchEditBar`, `UndoRedoButtons`; optional `historyIncludesControls`                                                                                                                            |
| `createAdapterRowDetailFeatures`     | `rowDetail`, `nestedTable`                                                                   | `ExpandToggle`                                                                                                                                                                                                                     |
| `createAdapterRowReorderFeature`     | `rowReorder`                                                                                 | `RowReorderHandle`, `RowReorderButtons`                                                                                                                                                                                            |
| `createAdapterCommandPaletteFeature` | `commandPalette`                                                                             | one `CommandPalette` component; optional `Trigger` (`AdapterCommandPaletteTriggerProps`), drawn in the toolbar for `commandPalette({ button: true })`                                                                              |
| `createAdapterContextMenuFeature`    | `contextMenu`                                                                                | one `ContextMenu` component                                                                                                                                                                                                        |
| `createAdapterTableAssistantFeature` | a `StaticTableFeature` — the kit wraps it as `tableAssistant()`                              | one `TableAssistant` component                                                                                                                                                                                                     |
| `createAdapterAgentApprovalFeature`  | a `StaticTableFeature` — the kit wraps it as `agentApproval()`                               | one `AgentApproval` component                                                                                                                                                                                                      |
| `createAdapterStandardFeatures`      | `standardFeatures`                                                                           | the kit's own factories: `columnMenu`, `densityChooser`, `exportCsv`, `findInTable`, `fitColumns`, `fullscreen`, `headerFilters`, `multiSort`, `resizableColumns`, `statusBar`, `grouping`, `bulkActions`, `filters`, `savedViews` |

```tsx
// src/filters.tsx
import { createAdapterFiltersFeature } from "@adapttable/react/adapter";

import {
  FilterChips,
  FilterDrawer,
  FilterPopover,
  FiltersForm,
} from "./components/filterParts";

/** Declarative filters, drawn with this kit's form, chips and overlays. */
export const filters = createAdapterFiltersFeature({
  FiltersForm,
  ActiveFilterChips: FilterChips,
  FilterDrawer,
  FilterPopover,
});
```

Each component's props are exported beside the helper —
`FiltersFormSlotProps`, `ActiveFilterChipsSlotProps`, `FilterOverlaySlotProps`,
`GroupHeaderRowSlotProps`, `EditableCellRenderProps` and the rest.

### `extendFeature` + `slotRender`

For a feature with one surface, keep the headless factory and append the
kit's render, as in [the fullscreen example](#example--a-feature-entry).
`extendFeature` concatenates onto the factory's own `renders`; replacing
`renders` instead would drop the live slots the factory already fills.

| Slot                                  | Features                                             |
| ------------------------------------- | ---------------------------------------------------- |
| `TOOLBAR_EXTRAS`                      | `densityChooser`, `exportCsv`, `fullscreen`, `print` |
| `STATUS_BAR`                          | `statusBar`, `selectionStats`                        |
| `COLUMN_MENU`, `COLUMN_HEADER_RENAME` | `columnMenu`                                         |
| `COLUMN_GROUP_TOGGLE`                 | `collapsibleColumnGroups`                            |
| `COLUMN_SELECT`                       | `columnSelectionCheckbox`                            |
| `BULK_BAR`                            | `bulkActions`                                        |
| `FIND_BAR`                            | `findInTable`                                        |
| `FILTER_HEADER`                       | `headerFilters`                                      |
| `FILL_HANDLE`                         | `cellNavigation`                                     |
| `SAVED_VIEWS`                         | `savedViews`                                         |
| `SIDE_PANEL`                          | `sidePanel`                                          |
| `TREE_CELL`, `TREE_TOGGLE`            | `tree`                                               |

`findInTable({ button: true })` also appends `findButtonRender(FindButton)`,
which draws the kit's Find control in `TOOLBAR_EXTRAS` with
`AdapterFindButtonProps` — the toolbar props plus `onOpenFind` and `findOpen`
— and renders nothing outside a table that composed find. Another control reads
the same state with `useFindState()`. A kit that builds its own cell props when
`cellNavigation()` is not composed passes them through
`withFindMarks(base, find, firstRowIndex)`, so matches carry the same
`data-cell-match` / `data-cell-match-current` attributes the grid writes.

### Headless pass-through

A feature that draws no control of its own is re-exported unchanged:

```ts
// src/multi-sort.ts
export { multiSort } from "@adapttable/react/features";
```

`rowPinning`, `pinnedSummaryRows`, `cellSpan`, `extraRows`, `rowAppearance`,
`rowActions`, `virtualize`, `resizableColumns`, `fitColumns` and `multiSort`
take this form. The `/pivot` entry exports the kit's `PivotPanel` and
re-exports `@adapttable/core/pivot`.

## Where the table places slots

A feature fills a slot; the adapter decides where it sits. The unstyled root
places these in [`DataTable.tsx`](../packages/react/adapter-unstyled/src/DataTable.tsx):

| Region          | Slots                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Announcers      | `GRID_FOCUS_ANNOUNCER`, `ROW_REORDER_ANNOUNCER`                                                                                                |
| Toolbar         | `FIND_BAR`, `FILTER_POPOVER` (wrapping the Filters button in popover mode), `SAVED_VIEWS`, `COLUMN_MENU`, `TOOLBAR_EXTRAS`                     |
| Above the body  | `FILTER_DRAWER` (drawer mode), `ACTIVE_FILTER_CHIPS`, `BATCH_EDIT_BAR`, `AGENT_APPROVAL`, `BULK_BAR`, `COMMAND_PALETTE_LIVE`, `GROUPING_PANEL` |
| Around the body | `SIDE_PANEL` through `OptionalSidePanel`, then `STATUS_BAR` below the footer                                                                   |
| Filter form     | `FILTERS_FORM`, returned from the `renderAutoForm` callback                                                                                    |

The root is wrapped in `ContextMenuLiveGate`, which spreads the context-menu
region props onto it. Inside the desktop table and mobile cards,
[`components/featureSlots.tsx`](../packages/react/adapter-unstyled/src/components/featureSlots.tsx)
places `EDITABLE_CELL`, `TREE_CELL`, `TREE_TOGGLE`, `FILL_HANDLE`,
`EXPAND_TOGGLE`, `FILTER_HEADER`, `ROW_EDIT_ACTIONS`, `ROW_REORDER_HANDLE`,
`ROW_REORDER_BUTTONS`, `COLUMN_GROUP_TOGGLE`, `COLUMN_SELECT`,
`COLUMN_HEADER_RENAME`, `GROUP_HEADER_ROW` and `GROUP_HEADER_CARD`. Those
wrappers live in their own file so the table imports them instead of the kit
implementations — omitting a feature omits its components.

## Parts and `classNames`

`data-adapttable-part` names and their placement are public contract: the same
part lands on the same element in every adapter. Seven are guaranteed in every
kit that renders the shell —
[the structural parts](./customization.md#the-structural-parts-every-adapter-names):

| Part                        | Element                          |
| --------------------------- | -------------------------------- |
| `table` / `thead` / `tbody` | The `<table>` and its sections.  |
| `row` / `cell`              | One body `<tr>` and one `<td>`.  |
| `header-cell`               | One header `<th>`.               |
| `toolbar`                   | The toolbar row above the table. |

Beyond those, a part a kit renders carries the name the other kits use for it
— `column-group-toggle`, `fullscreen-toggle`, `filters-button`, and so on.
Take names from the unstyled adapter, which names every node it renders.

`classNames` follows the parts. A themed kit exposes the five wrapper keys
`root`, `toolbar`, `table`, `card` and `footer`; the unstyled adapter exposes a
key for every node, and each node's part name is the kebab-case form of its
key (`searchField` → `data-adapttable-part="search-field"`). A documented
key is honoured by every adapter that renders its part. When module-scope slot components need the class map, the unstyled
adapter publishes it through context
([`components/classNamesContext.tsx`](../packages/react/adapter-unstyled/src/components/classNamesContext.tsx))
rather than defining slots inside the render: a component defined in render is
a new type on every render, and React remounts it — an input loses focus
mid-keystroke.

## Parity

Parity means every feature exists in the kit **with the kit's own
components**. A shared look is not parity: copying another adapter's
raw-HTML control is the same defect as drawing it in core. For each feature:

- every subpath the other kits publish exists in this one;
- the mobile card layout is handled, or the behaviour on cards is stated;
- RTL mirrors correctly — pass `dir` through and use logical CSS properties;
- keyboard access and screen-reader announcements match the other kits;
- the header cell spreads core's header props whole (`...leaf.headerProps`),
  or hands `getHeaderCellProps` to a kit that builds its own `<th>`, so
  attributes core adds reach every kit;
- overlays use the kit's own primitive. `filtersMode="popover"` is an anchored
  card with no backdrop that closes on Escape and outside click, restores
  focus and sets `aria-expanded` on its trigger; `filtersMode="drawer"` is the
  kit's Drawer with a real backdrop.

The root `DataTable` imports neither another kit nor the `/features` barrel.
A feature reaches a table only through the `features` array, which is what
keeps a three-prop table's bundle free of every feature it did not name.

## The worked reference — `@adapttable/unstyled`

[`packages/react/adapter-unstyled/src`](../packages/react/adapter-unstyled/src) is the
complete adapter for native HTML. Its layout is the one to copy:

| File                               | Holds                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DataTable.tsx`                    | The root: `useTableFeatures`, `FeatureProviders`, `useDataTableShell`, `DataTableShellView`, the toolbar, body switch and slot placement.               |
| `types.ts`                         | `DataTableClassNames`, `DataTableSlots`, `DataTablePropsBase`, and `DataTableProps` intersected with `DataModeProps`.                                   |
| `index.ts`                         | `DataTable`, its types, and the re-exported builders and types an app needs without importing core.                                                     |
| `<feature>.tsx` / `<feature>.ts`   | One file per subpath: a helper call, an `extendFeature` wrap, or a pass-through re-export.                                                              |
| `features.ts` / `preset.ts`        | The `/features` forward and the `/preset` `standardFeatures`.                                                                                           |
| `components/DesktopTable.tsx`      | The desktop table, built on `useDesktopTableAssembly` and `createDesktopRow` — see [desktop table assembly](./customization.md#desktop-table-assembly). |
| `components/MobileCards.tsx`       | The card layout.                                                                                                                                        |
| `components/featureSlots.tsx`      | The lean `FeatureSlot` wrappers the table and cards import.                                                                                             |
| `components/kitControls.tsx`       | Chrome components with their slots filled: `ColumnGroupToggle`, `TreeCell`, `FindBar`, `RowReorderHandle`, and the rest.                                |
| `components/classNamesContext.tsx` | The per-table class map for module-scope slots.                                                                                                         |
| `tsdown.config.ts`                 | One build entry per subpath, a `"use client"` banner, and `react`, `react-dom` and `@adapttable/core` kept external.                                    |

Each themed kit (`packages/react/adapter-mantine`, `adapter-mui`, `adapter-chakra`,
`adapter-antd`, `adapter-radix`, `adapter-base-ui`) has the same shape with
its kit's components in place of native elements. Ant Design renders the
desktop table through antd's own `<Table>` instead of the shared assembly.

## Package exports and peer dependencies

The built-in adapters declare their kit (where there is one) and React as
peers, and the AdaptTable packages as dependencies pinned to exact versions:

```json
{
  "name": "@acme/adapttable",
  "type": "module",
  "sideEffects": false,
  "engines": { "node": ">=22.12.0" },
  "exports": {
    ".": {
      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    },
    "./fullscreen": {
      "import": {
        "types": "./dist/fullscreen.d.ts",
        "default": "./dist/fullscreen.js"
      },
      "require": {
        "types": "./dist/fullscreen.d.cts",
        "default": "./dist/fullscreen.cjs"
      }
    }
  },
  "peerDependencies": {
    "@acme/ui": "^3.0.0",
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0"
  },
  "dependencies": {
    "@adapttable/core": "3.0.0",
    "@adapttable/react": "1.0.0"
  }
}
```

- One `exports` entry per feature subpath, each with `import` and `require`
  conditions, so a bundler loads a feature only when a table names it.
- The kit is a peer: the app owns its version and its theme provider, and the
  adapter renders inside that theme.
- Exact pins keep `@adapttable/react` and `@adapttable/core` on the versions
  the adapter was built against, so an app installs the adapter alone.
- Built entries start with `"use client"`, so a Next.js App Router page can
  import the table without a client wrapper of its own.
- The built-in adapters also compile with the React Compiler, which is why
  they depend on `react-compiler-runtime`; an adapter built without it does
  not need that dependency.

## Testing

`@adapttable/core/conformance` is the suite every built-in adapter passes:
the structural parts, the table's accessible name, row and cell identity,
sorting and its `aria-sort`, right-to-left, mobile cards, the empty state, row
selection, the status region's announcements after a sort or a page, the
dataset size on a partial page, the host's labels in controls and
announcements, and keyboard cell navigation — the grid role, the roving tab
stop, arrow keys and the focus announcer. It asserts against the DOM and
depends on no test runner and no framework. A driver renders the kit's table
for each scenario; the runner registers the tests the suite returns:

```tsx
// src/conformance.test.tsx
import {
  type ConformanceDriver,
  type ConformanceRow,
  type ConformanceScenario,
  tableConformanceTests,
} from "@adapttable/core/conformance";
import { fireEvent, render, waitFor } from "@testing-library/react";
import { describe, expect, it } from "vitest";

import { bulkActions } from "./bulk-actions";
import { cellNavigation } from "./cell-navigation";
import { type ColumnDef, DataTable } from "./index";

function columnsFor(
  scenario: ConformanceScenario
): ColumnDef<ConformanceRow>[] {
  return scenario.columns.map((column) => ({
    key: column.key,
    header: column.header,
    sortable: column.sortable,
    accessor: (row: ConformanceRow) => row[column.key],
  }));
}

const driver: ConformanceDriver = {
  name: "acme",
  mount: (scenario) =>
    render(
      <DataTable
        data={[...scenario.rows]}
        columns={columnsFor(scenario)}
        rowKey={(row) => row.id}
        urlSync={false}
        tableLabel={scenario.tableLabel}
        dir={scenario.dir}
        forceMobile={scenario.mobile}
        defaults={
          scenario.pageSize === undefined
            ? undefined
            : { limit: scenario.pageSize }
        }
        labels={scenario.labels}
        features={[
          ...(scenario.selectable
            ? [
                bulkActions([
                  {
                    key: "archive",
                    label: "Archive",
                    onClick: () => undefined,
                  },
                ]),
              ]
            : []),
          ...(scenario.navigable ? [cellNavigation()] : []),
        ]}
      />
    ),
};

describe(`table conformance — ${driver.name}`, () => {
  for (const test of tableConformanceTests(driver, {
    expect,
    fireEvent,
    waitFor,
  })) {
    it(test.name, test.run);
  }
});
```

jsdom has no `matchMedia`; stub it with a non-matching implementation in the
test setup so the table renders its desktop layout.

A binding for another framework plugs in the same way. Its driver mounts the
binding's table component with that framework's test utilities — Vue Test
Utils' `mount` with `attachTo`, or Angular's `TestBed` — maps the scenario onto
the component's inputs, and returns the element it rendered into and a
function that unmounts it. The harness is the same: the runner's `expect` and
DOM Testing Library's `fireEvent` and `waitFor`, which dispatch real DOM events
whatever rendered the table. Nothing in the suite changes.

Beyond the suite, the built-in adapters are held to parity by:

- per-package unit tests — Vitest, Testing Library and `vitest-axe` — that
  render the kit's `DataTable` (the accessibility suite, for example, over
  `useFrontendData` with `createMemoryAdapter()`) and assert behaviour and
  zero axe violations;
- `pnpm check:parts` (`scripts/check-parts-parity.mjs`), which fails when a
  part is named by some shell kits and not others, or when one of the seven
  contract parts is missing from a kit;
- `pnpm check:features`, which among its checks requires every published kit
  to expose the same feature subpaths and pass core's header props through
  whole;
- Playwright specs in the showcase — `e2e/aria-parity.spec.ts` compares the
  ARIA shape every built kit produces, and `e2e/kit-classnames.spec.ts` checks
  the computed look of the class-map kits.

## Notes

- `@adapttable/react/adapter` is aimed at adapter authors; its exports are
  listed under [the adapter contract](./api.md#the-adapter-contract) and
  [the builder tier](./api.md#the-builder-tier).
- `DataModeProps` is the discriminated `mode` union: intersect it into the
  kit's props so `mode="server"` without `onQueryChange` fails to compile.
- Re-export the source builders and hooks (`useFrontendData`,
  `useServerData`, `useQuerySource`, `useTableUrlState`) and the common types
  from the kit's root, as the built-in adapters do, so an app imports from one
  package.
- Whether a feature draws kit UI, and which kit components it needs, is
  recorded once for every kit in
  [`scripts/feature-classification.json`](../scripts/feature-classification.json).
- Take visible text from the `labels` (`Required<TableLabels>`) or label
  props the chrome passes, rather than hard-coding it, so bundled locales and
  a caller's overrides reach the kit's controls.

---

# React table columns — ColumnDef, accessors, sorting, pinning & custom cells

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — this page's feature is the starter's whole `columns` array in `src/App.tsx`; edit it in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

Columns are plain objects — declare a `key` and the table renders the value, derives the header, and wires sorting and filtering around it. Everything beyond the key is an opt-in refinement.

## Example

```tsx
import { type CellProps, type ColumnDef, DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, shadcn, unstyled
import { Badge } from "@mantine/core";

interface Person {
  id: string;
  name: string;
  nameAr: string;
  department: { name: string };
  salary: number;
  status: "active" | "on-leave";
  hiredAt: string;
}

const people: Person[] = [
  {
    id: "1",
    name: "Amira Hassan",
    nameAr: "أميرة حسن",
    department: { name: "Engineering" },
    salary: 96000,
    status: "active",
    hiredAt: "2021-03-15",
  },
  {
    id: "2",
    name: "Tom Becker",
    nameAr: "توم بيكر",
    department: { name: "Design" },
    salary: 78000,
    status: "on-leave",
    hiredAt: "2022-11-01",
  },
  {
    id: "3",
    name: "Lina Park",
    nameAr: "لينا بارك",
    department: { name: "Engineering" },
    salary: 105000,
    status: "active",
    hiredAt: "2019-07-20",
  },
];

// Define Cell components at module level so their identity is stable.
function StatusCell({ row }: CellProps<Person>) {
  return (
    <Badge color={row.status === "active" ? "green" : "yellow"}>
      {row.status}
    </Badge>
  );
}

const columns: ColumnDef<Person>[] = [
  // Bare key: auto header "Name"; i18n swaps the data path when locale="ar".
  { key: "name", i18n: { ar: "nameAr" }, sortable: true },
  // Dot path reaches nested values; auto header "Department Name".
  { key: "department.name", header: "Department" },
  // accessor formats; sortValue keeps the column sortable by the raw number.
  {
    key: "salary",
    header: "Salary (USD)",
    accessor: (r) => r.salary.toLocaleString(),
    sortValue: (r) => r.salary,
    sortable: true,
    align: "end",
    width: 140,
  },
  // Cell: a full React component receiving { row, rowIndex }.
  { key: "status", Cell: StatusCell, mobileLabel: "Status" },
  { key: "hiredAt", hideOnMobile: true, meta: { exportFormat: "date" } },
];

export function People() {
  return (
    <DataTable
      data={people}
      columns={columns}
      rowKey={(r) => r.id}
      locale="en"
    />
  );
}
```

## How it works

- A bare `{ key }` is a complete column: the key doubles as the row's data path (dot paths reach nested values, `"department.name"`), and the header is auto-humanised (`hiredAt` → "Hired At"). An explicit `header` always wins, in any language.
- `renderHeader` replaces the caption only. The cell still owns sort, resize and the menu, and passes a `controller` (`label`, `sortDir`, `sortIndex`, `toggleSort({ shiftKey })`) so a custom caption can stay wired. `headerTooltip` is a native title; `headerActions` sit after the caption. `renderFooter` replaces one summary cell; `tableFooter` is a free slot under the table.
- Cell content resolves `Cell` → `accessor` → the key's data path. `Cell` is a React component receiving `{ row, rowIndex }`; `accessor` is the lighter function form. Mini charts are a separate import — see [sparkline columns](./sparkline.md).
- `sortable` opts a column into sorting; on frontend data the comparator reads `sortValue`, falling back to `formatValue`, `exportValue`, then the key's data path; a JSX `accessor` is never compared. See [sorting](./sorting.md).
- `i18n` maps locale tags to alternative data paths; the table's `locale` prop picks one (exact tag → primary subtag → `key`). The cell, client-side sort, row grouping, and the column's filter all follow the resolved path — header text does not.
- `renameable` opts a leaf into user naming when the table also provides
  `onColumnRename`. This changes display text, mobile and export labels while
  the key and localized data paths stay fixed. See
  [column management](./column-management.md).
- `hideOnMobile` / `hideOnDesktop` drop a column per layout; `mobileLabel` overrides the label on mobile cards.
- `key` is also the value sent to a backend as `sortBy`, so keep it API-stable.

## Options

| Prop                                                        | Type                                              | Default                                   | Description                                                                                                   |
| ----------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `key`                                                       | `string`                                          | required                                  | Unique id; data path for the cell value; the backend `sortBy` value.                                          |
| `header`                                                    | `ReactNode`                                       | humanised from `key`                      | Header content, pre-translated by the caller.                                                                 |
| `renderHeader`                                              | `(ctx) => ReactNode`                              | —                                         | Custom caption; receives a controller so sort/resize stay available.                                          |
| `renderFooter`                                              | `(ctx) => ReactNode`                              | —                                         | Custom summary-row cell.                                                                                      |
| `headerTooltip`                                             | `string`                                          | —                                         | Native tooltip on the caption.                                                                                |
| `headerActions`                                             | `ReactNode`                                       | —                                         | Host controls after the caption.                                                                              |
| `renameable`                                                | `boolean`                                         | `false`                                   | Allow a host-persisted user display name from the Columns menu.                                               |
| `accessor`                                                  | `(row) => ReactNode`                              | read the key's data path                  | Lightweight cell renderer.                                                                                    |
| `Cell`                                                      | `ComponentType<CellProps<TRow>>`                  | —                                         | Component per row, receives `{ row, rowIndex }`; wins over `accessor`.                                        |
| `sortable`                                                  | `boolean`                                         | `false`                                   | Enable sorting for this column.                                                                               |
| `sortValue`                                                 | `(row) => SortableValue`                          | `formatValue` → `exportValue` → data path | Primitive extractor for the client-side sort. See [sorting](./sorting.md).                                    |
| `formatValue`                                               | `(row) => string`                                 | —                                         | The cell as text, for screen readers, labels and copy. See below.                                             |
| `exportValue`                                               | `(row) => unknown`                                | the display value                         | Value written to a CSV export when the file should carry something other than the formatted cell.             |
| `align`                                                     | `"start" \| "center" \| "end"`                    | `"start"`                                 | Text alignment within the cell.                                                                               |
| `width`                                                     | `number \| string`                                | —                                         | Width passed through to the rendered header/cell.                                                             |
| `minWidth` / `maxWidth` / `flex`                            | `number`                                          | —                                         | Width bounds and a share of the leftover space. See [column management](./column-management.md).              |
| `lockPosition` / `lockVisibility` / `lockWidth` / `lockPin` | `boolean`                                         | `false`                                   | Disable the matching Columns-menu and resize controls for this column.                                        |
| `filter`                                                    | `FilterType \| Omit<FilterDef, "key" \| "label">` | —                                         | Declare this column's filter. See [filtering](./filtering.md).                                                |
| `editable` / `editor`                                       | `boolean \| (row) => boolean` / `CellEditor`      | —                                         | Inline editing for this column. See [cell editing](./cell-editing.md).                                        |
| `colSpan` / `rowSpan`                                       | `number \| (row) => number`                       | —                                         | Span every cell of this column. See [row spanning](./row-spanning.md).                                        |
| `groupShow`                                                 | `"open" \| "closed" \| "always"`                  | `"open"` under a collapsible group        | When this leaf shows under a collapsed group. See [column groups](./column-groups.md).                        |
| `responsivePriority`                                        | `number`                                          | —                                         | How readily the column is given up when the table is too narrow; priority 1 is kept longest.                  |
| `mobileLabel`                                               | `string`                                          | `header` (when a string)                  | Label on mobile card layouts.                                                                                 |
| `hideOnMobile`                                              | `boolean`                                         | `false`                                   | Hide the column entirely on mobile.                                                                           |
| `hideOnDesktop`                                             | `boolean`                                         | `false`                                   | Hide the column entirely on desktop.                                                                          |
| `aggregatable`                                              | `false \| true \| { default?, operations }`       | omitted                                   | Whether a reader may aggregate this column, and with which operations. See [row grouping](./row-grouping.md). |
| `formatAggregate`                                           | `(value, context) => DisplayValue`                | —                                         | How a group aggregate of this column reads. Presentation only.                                                |
| `group`                                                     | `string`                                          | —                                         | Spanning header above adjacent columns sharing the name. See below.                                           |
| `i18n`                                                      | `Record<string, string>`                          | —                                         | Per-locale data paths for the column's value.                                                                 |
| `meta`                                                      | `Record<string, unknown>`                         | —                                         | Free-form bag your own code can read back.                                                                    |
| `locale`                                                    | `string` (table prop)                             | —                                         | Active locale tag (`"ar"`, `"ar-EG"`); drives `i18n` path resolution.                                         |

## The cell as text

`accessor` returns a `ReactNode`, which is right for rendering and useless
everywhere else: a status badge is a React element, an avatar cell is a
component, and neither is a word. Anything that needs the cell as a **string** —
a screen-reader announcement, an `aria-label`, a tooltip, a clipboard copy —
has nothing to read.

`formatValue` is that string:

```tsx
{
  key: "status",
  accessor: (row) => <Badge color={tone(row)}>{row.status}</Badge>,
  formatValue: (row) => row.status,   // what a screen reader says
}
```

Text is always available, so `formatValue` only matters where it makes the text
_accurate_. `columnText(column, row)` resolves it in this order:

1. `formatValue` — the column stating its own text
2. `exportValue` — the underlying value, minus the formatting
3. `sortValue` — a primitive by definition
4. the key's data path

The first that yields a string, number, boolean or `Date` (read as its ISO day)
wins; nothing yields `""`. A React `accessor` or `Cell` is never consulted, so a
column whose rendered cell differs from its data path sets `formatValue` to say
what it shows.

## Computed columns

A total, a margin, a full name, days-until-due — columns whose value is derived
rather than stored. Writing the derivation into `accessor` works until the
column has to do anything else: sorting then compares the formatted string, so
`"$1,240.00"` sorts before `"$90.00"`; filtering has nothing to match; the
export carries the formatting; and the function runs again for every cell on
every render.

`computed` declares the derivation once and wires all four surfaces from it:

```tsx
import { computed } from "@adapttable/react";

const columns = [
  { key: "quantity" },
  { key: "unitPrice" },
  computed<Order, number>({
    key: "total",
    header: "Total",
    deps: (row) => [row.quantity, row.unitPrice],
    value: (row) => row.quantity * row.unitPrice,
    format: (total) => money.format(total),
    column: { sortable: true, align: "end" },
  }),
];
```

The screen shows `$1,240.00`; sorting, filtering and export all see `1240`.

- **`deps` is required, and listing them is the whole contract.** The value is
  recomputed when any dependency changes and reused when none do. A field the
  derivation reads but does not declare becomes a stale cell the moment the
  data changes underneath it.
- **The result is cached per row**, in a `WeakMap` keyed by the row object — a
  row that leaves the page takes its cached value with it, so a long-lived
  table cannot grow a cache it never releases.
- **`format` is display only.** Leave it out and primitives and dates render as text; any other value renders empty, since an object has no useful reading in a cell.
- **`column` carries everything else** a column can be — `sortable`, `align`,
  `width`, `filter`, `hideOnMobile`. `accessor`, `Cell`, `sortValue`,
  `exportValue` and `formatValue` are derived and cannot be set here, which is
  what keeps the four surfaces from disagreeing.

**Define the columns at module level, or memoise them.** The cache lives
inside the column `computed` returns, so rebuilding the column on every
render throws the cache away with it — values stay correct, nothing is
reused. It is the same rule `Cell` already asks for.

Rows must be objects, since the cache is keyed by row identity. `@adapttable/core` exports the same helper typed as a neutral `ColumnModel`, with its spec type `ComputedColumnSpec`, for headless and non-React callers.

## Grouped headers

Give adjacent columns the same `group` and they render under one spanning
header cell. A string is one level; a path stacks one header row per depth.
That shortcut is presentational — for collapse options and groups that stay
together through reorder, use a `ColumnGroupDef` parent with `children`.
See [column groups](./column-groups.md).

```tsx
const columns: ColumnDef<Person>[] = [
  { key: "firstName", header: "First", group: "Name" },
  { key: "lastName", header: "Last", group: "Name" },
  { key: "q1", header: "Q1", group: ["Finance", "2026"] },
  { key: "q2", header: "Q2", group: ["Finance", "2026"] },
  { key: "hiredAt", header: "Hired" },
];
```

```text
|      Name      |      Finance      |        |
|                |       2026        |        |
| First |  Last  |   Q1   |    Q2    | Hired  |
```

Columns without a `group` sit under a blank spanning cell, so the header rows
always line up. The grouping is **presentational and adjacency-based**: the
span is computed from the columns as they are currently ordered, so dragging a
column out of the middle of a group splits it into two spans rather than
pretending the layout is something it is not. Reorder them back together and
the group closes up again.

Compose `collapsibleColumnGroups()` from `@adapttable/<kit>/column-groups` and
each real group header gains a toggle. What
a collapsed group shows is that group's own options — an arrow stub by
default, a kept child via `collapsedKey`, or a cell via `collapsedRender`.
See [column groups](./column-groups.md). Collapse state lives on
`columnLayout.collapsedGroups` and the URL (`colGroupCollapse`); group ids are
`path.join("\u001f")` so a label may contain `/`. On mobile the card layout has
no header row, but the same visible-column filter applies — cards hide the same
leaves a collapsed group hid on desktop.

## Notes

- Define `Cell` components at module level (or memoise them) — an inline component re-mounts every render and defeats row memoisation.
- Path-derived cells render primitives only; a non-primitive value at the path renders nothing. Use `accessor` or `Cell` for objects.
- A column whose `accessor` returns JSX sorts by its data path unless it sets `sortValue` (or `formatValue` / `exportValue`); without `sortValue` a dev warning fires.
- `mobileLabel` only falls back to `header` when the header is a string; with a JSX header, set `mobileLabel` explicitly (it also names the column in the Columns menu).
- Duplicate column keys trigger a development warning — keys must be unique within the table.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

---

# React table column groups — spanning headers, collapsible

▶ **See it working:** [collapse column groups in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/column-groups/) — one table, three groups, open by default: Contact folds to a chevron, Assignment keeps Team, Delivery shows a money-for-days brief (`align: "start"`). Actions stays ungrouped at the end. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

A parent with `children` is a **column group**: one spanning header over its
leaves. Collapse is per group — each parent decides what remains. Without
`collapsibleColumnGroups()` the headers stay static.

This is not [row grouping](./row-grouping.md). Rows fold under `grouping("team")`;
columns span under a parent header.

**Related:** [Columns](./columns.md) · [Column management](./column-management.md)

## Tree columns

`columns` accepts a mix of leaf `ColumnDef`s and `ColumnGroupDef`
parents (`ColumnInput`). Tree groups default `marryChildren: true`, so a
reorder cannot split them.

```tsx
import { DataTable, type ColumnInput } from "@adapttable/mantine";
import { collapsibleColumnGroups } from "@adapttable/mantine/column-groups";

const columns: ColumnInput<Person>[] = [
  {
    header: "Contact",
    children: [
      { key: "name", header: "Name" },
      { key: "role", header: "Role" },
    ],
  },
  {
    header: "Assignment",
    collapsedKey: "team",
    children: [
      { key: "team", header: "Team" },
      { key: "status", header: "Status" },
    ],
  },
  {
    header: "Delivery",
    align: "start",
    collapsedRender: (row) => `${row.budget} for 35 days`,
    children: [
      { key: "timeline", header: "Timeline" },
      { key: "budget", header: "Budget" },
    ],
  },
];

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[collapsibleColumnGroups()]}
/>;
```

| `ColumnGroupDef` field | Type                           | Default | Description                                                    |
| ---------------------- | ------------------------------ | ------- | -------------------------------------------------------------- |
| `header`               | `string`                       | —       | Group caption; required.                                       |
| `children`             | `ColumnInput[]`                | —       | Leaves and nested groups; required.                            |
| `headerTooltip`        | `string`                       | —       | Native tooltip on the group caption.                           |
| `align`                | `"start" \| "center" \| "end"` | —       | Alignment of the group caption.                                |
| `collapsedKey`         | `string`                       | —       | Child that stays visible while collapsed.                      |
| `collapsedRender`      | `(row) => DisplayValue`        | —       | One cell shown while collapsed; wins over `collapsedKey`.      |
| `marryChildren`        | `boolean`                      | `true`  | Keep the children together; `false` lets a reorder split them. |

HTML-table kits (Mantine, MUI, Chakra, Radix, Base UI, unstyled) render the
same tree with `rowSpan` on ungrouped leaves, so Actions sits beside Delivery
and its children instead of under a blank group row. Ant uses native grouped
columns; `htmlGroupedHeaderPlan` is that tree flattened for `<th>`. HTML kits
draw the line under an open group with `groupedHeaderChildRule` so adjacent
groups do not share one stroke.

## Collapse

Compose `collapsibleColumnGroups()` from `@adapttable/<kit>/column-groups` and
each real group header gains a toggle. What
a collapsed group shows is that group's own options — there is no table-wide
mode.

| Result                                        | How                                                                     |
| --------------------------------------------- | ----------------------------------------------------------------------- |
| Thin **arrow stub** (chevron + hairline cell) | No `collapsedKey`, no `collapsedRender`, no child `groupShow: "closed"` |
| Keep one child                                | `collapsedKey: "timeline"` (or that leaf `groupShow: "closed"`)         |
| Custom one cell                               | `collapsedRender: (row) => …` (wins over `collapsedKey`)                |
| Always visible child                          | `groupShow: "always"`                                                   |
| Open-only child                               | `groupShow: "open"` (default under a collapsible group)                 |

A collapsed `collapsedRender` or stub group drops the child header row — the
title fills the header height, the same way an ungrouped leaf does.
`collapsedKey` keeps both rows: the group title and the stayed child's
header. Each group's rule under the title covers only that group's children;
adjacent groups do not share one stroke.

The stub hides the visible caption (`hideLabel`). The toggle's `aria-label`
still names the group (`Expand column group: Delivery`). The stub column is
locked to a chevron width so leftover table space cannot stretch it into a
blank data column.

`collapsedRender` wins over `collapsedKey`. State lives on
`columnLayout.collapsedGroups` and the URL (`colGroupCollapse`); group ids are
`path.join("\u001f")` (`columnGroupId`) so a label may contain `/`.

## The flat `group` shortcut

Adjacent leaves with the same `group` still span under one header. A string is
one level; a path stacks rows. That shortcut is **presentational**: a reorder
that breaks adjacency splits the span, and collapse (with `collapsibleColumnGroups()`) is an arrow
stub unless a child sets `groupShow`. Prefer a tree parent when the group has
collapse options or must stay married.

```tsx
const columns: ColumnDef<Person>[] = [
  { key: "firstName", header: "First", group: "Name" },
  { key: "lastName", header: "Last", group: "Name" },
  { key: "hiredAt", header: "Hired" },
];
```

## Mobile

The card layout has no header row. The same visible-column filter applies —
cards hide the leaves a collapsed group hid on desktop. The arrow stub itself
is `hideOnMobile`, so a collapsed Delivery does not become an empty card field.

## Helpers

`flattenColumnTree` turns a mixed `ColumnInput[]` into leaves plus a
`ColumnGroupRecord` map. `applyCollapsedColumnGroups` hides leaves under
collapsed ids and inserts a stub (`COLUMN_GROUP_STUB_PREFIX`,
`isColumnGroupStubKey`) or a `collapsedRender` column
(`COLUMN_GROUP_RENDER_PREFIX`, `isColumnGroupRenderKey`).
`marriedOrderHolds` rejects a reorder that would split a married tree group.
`columnGroupHeaderCaption` returns the visible caption, or `null` on a stub.
`htmlGroupedHeaderPlan` is the HTML-table rowspan plan (ungrouped leaves
beside the group band; a collapsed brief fills the header).
`groupedHeaderChildRule` is the inset hairline under an open group title.
`groupedHeaderCellStyle` applies that hairline and `columnGroupStubStyle`
(the 36px lock so a stub cannot stretch). `groupedHeaderLabelStyle` keeps
the collapse chevron on the same line as the group title so a one-child
group cannot wrap the arrow above the caption.
`isColumnGroup` narrows a `ColumnInput` to a parent.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/mantine/column-groups/).

---

# React table sparkline columns

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — import `@adapttable/react/sparkline`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [turn on the sparkline column in the Feature Lab](https://adapttable.orwamahmoud.com/react/demo/all-options/) — switch kits with it on and the chart is drawn by each one.

A sparkline is a mini chart in a cell: bar, line or area, drawn as inline
SVG. It ships as `@adapttable/react/sparkline` so a table that never
imports it never pays for it. No chart library.

```tsx
import { sparklineColumn } from "@adapttable/react/sparkline";
import { DataTable } from "@adapttable/mantine";

const columns = [
  sparklineColumn({
    key: "load",
    header: "Load",
    values: (row) => row.history,
    kind: "area",
  }),
];

<DataTable data={rows} columns={columns} rowKey={(row) => row.id} />;
```

`Sparkline` is the chart on its own, for a host `Cell` or `accessor`.
`sparklineColumn` wires the usual surfaces: the cell draws the SVG,
`sortValue` is the last finite number, and `exportValue` is the series
as `"1, 2, 3"` so CSV and xlsx get the numbers, not markup.

The SVG is a fixed size (80×28 by default). No `ResizeObserver`, so a
virtualized row can mount and unmount it without measuring. Mobile
cards render the same cell. Time stays left-to-right even under RTL —
mirroring a series would put "last" on the left. Pass a `label` for a
translated summary; the default is a numeric sentence (`3 values, min
1, max 4, last 2`).

| Option   | Type                                               | Default         | Description                                                     |
| -------- | -------------------------------------------------- | --------------- | --------------------------------------------------------------- |
| `key`    | `string`                                           | —               | Column key.                                                     |
| `values` | `(row: TRow) => readonly number[]`                 | —               | The series. Non-finite values are dropped before drawing.       |
| `kind`   | `"bar" \| "line" \| "area"`                        | `"line"`        | Chart form.                                                     |
| `header` | `ReactNode`                                        | —               | Column header.                                                  |
| `width`  | `number`                                           | `80`            | SVG width in CSS pixels.                                        |
| `height` | `number`                                           | `28`            | SVG height in CSS pixels.                                       |
| `color`  | `string`                                           | `currentColor`  | Fill and stroke colour.                                         |
| `label`  | `(values: readonly number[], row: TRow) => string` | numeric summary | Accessible name of the chart.                                   |
| `column` | `Partial<ColumnDef<TRow>>`                         | —               | Extra column fields (`width`, `sortable`, …) merged underneath. |

`<Sparkline>` takes `values`, `kind`, `width`, `height`, `color` and a string
`label`. The SVG carries `data-adapttable-part="sparkline"` and `data-kind`.
`sparklineSummary`, `sparklineExportValue` and `finiteSparklineValues` are the
default label, the export text and the finite-value filter on their own.

Omit the import and nothing is drawn and nothing is downloaded.

---

# React table sorting — multi-column, server-side & URL-synced

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — this page's feature is already wired in `src/App.tsx` (`sortable` columns + `multiSort()` — shift-click a second header); edit it in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

Mark a column `sortable` and header clicks cycle it ascending → descending → cleared, with the state kept in the URL so reloads and shared links restore the exact order. Multi-column sorting is one feature import: `multiSort()` from `@adapttable/<kit>/multi-sort`.

## Example

```tsx
import {
  type ColumnDef,
  DataTable,
  useFrontendData,
} from "@adapttable/mantine"; // or mui, chakra, antd, radix, shadcn, unstyled
import { multiSort } from "@adapttable/mantine/multi-sort";

interface Person {
  id: string;
  name: string;
  team: string;
  hiredAt: string;
  rating: number | null;
}

const people: Person[] = [
  {
    id: "1",
    name: "Amira Hassan",
    team: "Platform",
    hiredAt: "2021-03-15",
    rating: 4.6,
  },
  {
    id: "2",
    name: "Tom Becker",
    team: "Design",
    hiredAt: "2022-11-01",
    rating: null,
  },
  {
    id: "3",
    name: "Lina Park",
    team: "Platform",
    hiredAt: "2019-07-20",
    rating: 4.9,
  },
  {
    id: "4",
    name: "Sam Ortiz",
    team: "Design",
    hiredAt: "2023-02-08",
    rating: 4.1,
  },
];

const columns: ColumnDef<Person>[] = [
  { key: "name", sortable: true },
  { key: "team", sortable: true },
  // Formatted cell + sortValue: sort by the real date, not the display string.
  {
    key: "hiredAt",
    accessor: (r) => new Date(r.hiredAt).toLocaleDateString(),
    sortValue: (r) => r.hiredAt,
    sortable: true,
  },
  // null ratings always sort last, ascending or descending.
  { key: "rating", sortable: true },
];

export function People() {
  // `defaults` sets the initial sort; the URL overrides it once the user sorts.
  const source = useFrontendData({
    data: people,
    columns,
    defaults: { sortBy: "name", sortDir: "asc" },
  });
  return (
    <DataTable
      source={source}
      columns={columns}
      rowKey={(r) => r.id}
      features={[multiSort()]} // shift-click chains a second column
    />
  );
}
```

## How it works

- A header click cycles the column inactive → ascending → descending → cleared. A click on a different column starts it ascending.
- Frontend tier (`data` / `useFrontendData`): rows are compared by `sortValue`, falling back to `formatValue`, `exportValue`, then the key's data path. Numbers and booleans compare numerically, everything else by locale-aware string comparison; the sort is stable.
- `null` / `undefined` / `NaN` always sort last — in both directions. A descending sort never flips the blanks to the top.
- Sort state lives in the URL: `sortBy` + `sortDir` for a single sort, and the chain as `sort=name:asc,hiredAt:desc` with `multiSort()` composed. `defaults` apply only while the URL is silent; clearing a defaulted sort writes an empty `sortBy=` marker so it does not resurrect.
- `multiSort()` adds shift-click (or shift-Enter): each shift-click adds the column to the chain or advances it (asc → desc → removed). The first shift-click keeps the current sort as level one, so click Name then shift-click Salary sorts Name → Salary. Chained headers expose a 1-based `data-sort-index` for the order badge. A plain click resets the chain back to a single sort.
- Server tier (`onQueryChange` / `useQuerySource`): the table only emits the state — `query.sortBy`, `query.sortDir`, and `query.sortLevels` for a chain. Your backend does the comparing; `sortValue` is unused.

## Options

| Prop            | Type                                                       | Default                      | Description                                                                        |
| --------------- | ---------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------- |
| `sortable`      | `boolean` (per `ColumnDef`)                                | `false`                      | Enable sorting for the column.                                                     |
| `sortValue`     | `(row) => SortableValue` (per `ColumnDef`)                 | the generated accessor value | Primitive extractor for the client-side comparator. Unused for server-sorted data. |
| `multiSort()`   | factory from `@adapttable/<kit>/multi-sort`                | off                          | Multi-column sorting via shift-click / shift-Enter.                                |
| `getSortValue`  | `(row, columnKey) => SortableValue` (on `useFrontendData`) | —                            | One sort-key extractor for the whole row; wins over per-column `sortValue`.        |
| `defaults`      | `Partial<TableQueryParams> & { extra? }`                   | —                            | Initial sort (`sortBy`, `sortDir`) on the source builders; URL values win.         |
| `sortByOptions` | `SortByOption[]`                                           | —                            | Options for the mobile sort-by select.                                             |

## Notes

- `defaults` works both as a `<DataTable>` prop and as an option on the source builders — `defaults={{ sortBy: "name" }}` default-sorts the zero-ceremony `data` tier directly (ascending unless `sortDir` is given; explicit URL state wins).
- A column whose accessor returns JSX sorts by its data path unless it sets `sortValue` (or `formatValue` / `exportValue`); without `sortValue` a development warning fires. A `sortBy` that matches no column warns too.
- The plain-click reset of a multi-sort chain is deliberate: without it the chain would keep superseding the single sort and the click would appear dead.
- A hand-edited URL sort with no `sortDir` falls back to ascending.
- In multi-sort, ties at level N fall through to level N+1; rows that tie on every level keep their original order.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

---

# React table search — debounced, URL-synced and server-ready

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — the search box is already in `src/App.tsx` (`searchPlaceholder`); edit it in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

Every `DataTable` has a search box. It is part of the base table — no feature
import — and it narrows the rows to those that match: on frontend data the
table matches each row's searchable text, and on a server tier it hands the
term to your backend. The committed term lives in the URL as `q`, so a
reload or a shared link keeps it. Turn the box off with `searchable={false}`.

## Example

```tsx
import {
  type ColumnDef,
  DataTable,
  useFrontendData,
} from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled

interface Person {
  id: string;
  firstName: string;
  lastName: string;
  city: string;
  internalRef: string;
}

const people: Person[] = [
  {
    id: "1",
    firstName: "Amira",
    lastName: "Haddad",
    city: "Lisbon",
    internalRef: "EMP-0042",
  },
  {
    id: "2",
    firstName: "Jonas",
    lastName: "Weber",
    city: "Berlin",
    internalRef: "EMP-0107",
  },
  {
    id: "3",
    firstName: "Priya",
    lastName: "Nair",
    city: "Pune",
    internalRef: "EMP-0213",
  },
  {
    id: "4",
    firstName: "Sam",
    lastName: "Ortiz",
    city: "Bogotá",
    internalRef: "EMP-0350",
  },
];

const columns: ColumnDef<Person>[] = [
  {
    key: "name",
    header: "Name",
    accessor: (row) => `${row.firstName} ${row.lastName}`,
    sortable: true,
  },
  { key: "city", sortable: true },
];

export function PeopleDirectory() {
  const source = useFrontendData({
    data: people,
    columns,
    // Match the full name and the city; internalRef stays out of search.
    getSearchText: (row) => `${row.firstName} ${row.lastName} ${row.city}`,
  });
  return (
    <DataTable
      source={source}
      columns={columns}
      rowKey={(row) => row.id}
      searchPlaceholder="Search by name or city…"
      searchDebounceMs={200}
    />
  );
}
```

With the zero-ceremony `data` prop the box works as it is; build the source
with `useFrontendData` (or `useTableData`) when you want to choose what a row
is searched by.

## How it works

- **Typing is local, committing is debounced.** The input updates on every
  keystroke. After `searchDebounceMs` of quiet (300 ms by default) the trimmed
  term is committed to the source, which writes `q`, resets the page to 1 and
  re-queries. A change from outside — the back button, a link, a saved view —
  flows back into the input without clobbering a keystroke in flight.
- **Frontend matching.** On the `data` / `useFrontendData` tier a row matches
  when its searchable text contains the trimmed term, case-insensitively, as
  a plain substring. Search runs before the filters and the
  [AND/OR tree](./filter-tree.md); all of them must pass.
- **Searchable text.** `getSearchText(row)` projects a row to the string
  search reads. The default, `defaultSearchText`, joins the row's own
  top-level values with spaces; a nested object contributes its JSON text
  (keys included), and `null` / `undefined` contribute nothing. It reads the raw row, not the
  rendered cells, so a formatted date is found by its underlying value.
  Override it to reach nested fields, add computed text, or leave fields out.
  The projection is cached per row id until the `data` array changes, so
  keep it a pure function of the row.
- **Server tiers.** The table does not match anything; it sends the term.
  `useServerData`'s `onQueryChange(query)` receives it as `query.search` (an
  empty string when there is none), and `useQuerySource` passes it to your
  query as `params.search` on `TableQueryParams` (omitted when empty).
  `getSearchText` is unused there.
- **Empty results.** Zero rows under an active search render the "no
  results" state (`labels.noResults`) rather than the empty-data state.
  Clearing the filters leaves the search as it is.

## Options

| Option / prop       | Type                                   | Default                    | Description                                                                           |
| ------------------- | -------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------- |
| `searchable`        | `boolean`                              | `true`                     | `DataTable` prop. `false` removes the search box.                                     |
| `searchPlaceholder` | `string`                               | `labels.searchPlaceholder` | `DataTable` prop. Placeholder text; the built-in label is "Search…".                  |
| `searchDebounceMs`  | `number`                               | `300`                      | `DataTable` prop. Quiet time before the typed term commits to the source and the URL. |
| `getSearchText`     | `(row) => string`                      | `defaultSearchText`        | On `useFrontendData` / `useTableData`. The text a row is searched by.                 |
| `defaults.search`   | `string` (`Partial<TableQueryParams>`) | —                          | Initial term, on `DataTable` or a source builder. Applies while the URL has no `q`.   |
| `labels.search`     | `string`                               | `"Search"`                 | Accessible name of the search box.                                                    |

## Server-side search

A server source forwards the committed term and leaves the matching to the
backend:

```tsx
import { useState } from "react";
import { DataTable } from "@adapttable/mantine";

interface Person {
  id: string;
  name: string;
  city: string;
}

export function PeopleSearch() {
  const [rows, setRows] = useState<Person[]>([]);
  const [total, setTotal] = useState(0);

  return (
    <DataTable
      data={rows}
      total={total}
      onQueryChange={async (query, { signal }) => {
        const params = new URLSearchParams({
          page: String(query.page),
          limit: String(query.limit),
        });
        if (query.search) params.set("q", query.search);
        const res = await fetch(`/api/people?${params}`, { signal });
        const body = (await res.json()) as { items: Person[]; total: number };
        setRows(body.items);
        setTotal(body.total);
      }}
      columns={[{ key: "name" }, { key: "city" }]}
      rowKey={(row) => row.id}
      searchPlaceholder="Search people…"
    />
  );
}
```

On the backend, `parseTableQuery` from `@adapttable/server` reads `q` (under
`<urlKey>.` when set) and returns it as `search`, absent when the request has none —
see [server queries](./server-queries.md). Treat it like any user input:
parameterise it.

## Search is not find-in-table

Search and find answer different questions, and a table can have both.

|                   | Search                                        | Find in table                                          |
| ----------------- | --------------------------------------------- | ------------------------------------------------------ |
| Question          | "Show me only the rows that match"            | "Where does this appear in what I am looking at?"      |
| Rows              | Filters them; server tiers ask the server     | Leaves every row in place and walks the matching cells |
| Reads             | `getSearchText(row)` — the raw row            | What each cell shows                                   |
| Scope             | The whole dataset                             | The loaded rows — the current page, or what is fetched |
| URL               | `q`                                           | `find`                                                 |
| How to turn it on | Always there; `searchable={false}` removes it | `findInTable()` from `@adapttable/<kit>/find-in-table` |

Find works with or without `cellNavigation()`: **Ctrl/Cmd+F** opens it while
focus is inside the table or after a click in it, and with cell navigation
the walk moves focus from match to match.
[Keyboard & cell navigation](./cell-navigation.md#find-in-table) covers the
find bar.

## Notes

- **URL state.** `q` holds the committed, trimmed term and is written with
  replace-state, so typing does not fill the history. An empty term deletes
  the param; when `defaults.search` is set, clearing writes `q=` so the
  default does not come back. With `urlKey="people"` it is `people.q`.
  `searchable={false}` removes only the box: a `q` in the URL or in
  `defaults` still narrows the rows. See [URL state](./url-state.md).
- **Saved views** store `q` with the rest of the table state — see
  [saved views](./saved-views.md).
- **Mobile.** The search box stays in the toolbar above the cards and
  narrows them the same way. With the default `paginationMode`, the cards
  load more as you scroll instead of paging.
- **Keyboard and screen readers.** The box is an `<input type="search">`
  with `role="searchbox"`, named by `labels.search`. Translate `search` and
  `searchPlaceholder` through `labels` — see [i18n & RTL](./i18n-rtl.md).
- **Custom markup.** `useSearchInput(search, setSearch, debounceMs)` in
  `@adapttable/react` is the debounced input state behind the box, and
  `getSearchInputProps()` on `useDataTable` returns the input's props.

---

# React table filtering — multi-condition, chips, operators & URL-synced

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — the starter's column filters are already wired in `src/App.tsx` (`filter` on each column + `filters([])`), with chips and URL state; edit it in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

Declare a filter once and AdaptTable derives everything from it: the
kit-native widget, the `f_<key>` URL param, the removable chip, and (on
frontend data) the row predicate — no wiring. Nested AND/OR groups are
the [advanced filter tree](./filter-tree.md).

## Example

```tsx
// Needs your kit's provider once at the root (e.g. <MantineProvider>).
import { DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, shadcn, unstyled
import { filters } from "@adapttable/mantine/filters";

interface Person {
  id: string;
  name: string;
  department: { name: string };
  status: string;
  salary: number;
  hiredAt: string; // ISO date
}

const data: Person[] = [
  {
    id: "1",
    name: "Amira Haddad",
    department: { name: "Engineering" },
    status: "active",
    salary: 98000,
    hiredAt: "2021-03-15",
  },
  {
    id: "2",
    name: "Jonas Weber",
    department: { name: "Design" },
    status: "onleave",
    salary: 76000,
    hiredAt: "2019-11-02",
  },
  {
    id: "3",
    name: "Priya Nair",
    department: { name: "Engineering" },
    status: "active",
    salary: 112000,
    hiredAt: "2023-06-20",
  },
  {
    id: "4",
    name: "Sam Ortiz",
    department: { name: "Sales" },
    status: "left",
    salary: 64000,
    hiredAt: "2018-01-09",
  },
  {
    id: "5",
    name: "Lena Park",
    department: { name: "Design" },
    status: "active",
    salary: 89000,
    hiredAt: "2022-09-12",
  },
];

export function PeopleTable() {
  return (
    <DataTable
      data={data}
      rowKey={(r) => r.id}
      columns={[
        { key: "name", filter: "text", sortable: true },
        // "auto" derives the choices from the data (frontend tier).
        {
          key: "department.name",
          header: "Department",
          filter: { type: "select", options: "auto" },
        },
        // Async options — usually `async () => (await fetch("/api/statuses")).json()`.
        {
          key: "status",
          filter: {
            type: "multiSelect",
            options: async () => [
              { value: "active", label: "Active" },
              { value: "onleave", label: "On leave" },
              { value: "left", label: "Left" },
            ],
          },
        },
        { key: "salary", filter: "numberRange", sortable: true },
        { key: "hiredAt", filter: "dateRange" },
      ]}
      features={[
        filters([
          {
            key: "tenure",
            type: "numberRange",
            label: "Tenure (years)",
            getValue: (r) =>
              (Date.now() - new Date(r.hiredAt).getTime()) / 31_557_600_000,
          },
        ]),
      ]}
      filtersMode="popover" // the default; "drawer" or "header" — one mode, never stacked
    />
  );
}
```

Import `filters` from `@adapttable/<kit>/filters` — the import is the switch.
Column `filter` declarations still need that feature: pass `filters([])` when
every filter lives on a column, or pass standalone defs as above. See
[feature composition](./features.md).

## How it works

- Two declaration sites, merged column-first: the column `filter` shorthand
  (a bare type like `"dateRange"`, or a definition without `key`/`label` —
  both inherited from the column) and standalone entries passed to
  `filters([…])` for filters with no column. On a key collision the standalone
  definition wins and a development warning points at the duplicate.
- Seven built-in types (`FILTER_TYPES`): `text`, `select` (equals),
  `multiSelect` (wrapping multi-value chips),
  `checklist` (Excel-style distinct values with search, select-all and
  counts — from `source.facets` when present, otherwise
  `source.allFilteredRows`; a server page that omits both does not offer
  the widget), `boolean` (any / true / false — never a checkbox),
  `dateRange`, `numberRange`.
- Widgets are operator-first. Text offers equals / not equals / contains /
  not contains / starts with / ends with / empty / not empty. Numbers offer
  `=` `≠` `>` `≥` `<` `≤` between / in / not in. Dates offer before / after /
  on / on-or-after / on-or-before / between / relative / empty. The operator token is
  stored as `f_<key>Op` (readable, stable across releases) beside the value
  keys (`f_name`, `f_salaryMin`/`f_salaryMax`, `f_hiredAtFrom`/`f_hiredAtTo`).
  Links written before `Op` existed still work: text defaults to contains,
  and a Min/Max pair still infers at-least / at-most / between.
- `select`/`multiSelect` options come from a static `{ value, label }[]`,
  `"auto"` (distinct values derived from the frontend dataset, sorted,
  capped at `AUTO_OPTIONS_LIMIT` = 50, the same number as
  `FILTER_AI_OPTIONS_LIMIT`), or an async loader — one shared fetch
  serves both the form and the chip labels, and active chips re-label from
  raw values once it resolves.
- A definition's `key` doubles as the row's dot path for the client-side
  predicate (`"department.name"` reaches nested values); `getValue` overrides
  it for computed values.
- Active filters render as removable chips with a clear-all that resets every
  filter (and the page) while search and sort survive; `onClearFilters` is
  notified after the table clears them — supply `source.clearExtras` to replace
  the clear itself.

## Options

`FilterDef` (entries of `filters`, and the column `filter` object minus
`key`/`label`):

| Prop          | Type                                                        | Default               | Description                                                                                                                                                                                                                                                     |
| ------------- | ----------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | `string`                                                    | —                     | State key and `f_<key>` URL param. Doubles as the row's dot path unless `getValue` overrides it.                                                                                                                                                                |
| `type`        | `string`                                                    | —                     | Built-in `FilterType` or a custom type registered on `filterTypes`.                                                                                                                                                                                             |
| `label`       | `string`                                                    | humanized `key`       | Widget and chip label (`hiredAt` → "Hired At").                                                                                                                                                                                                                 |
| `options`     | `FilterOption[] \| "auto" \| () => Promise<FilterOption[]>` | —                     | Choices for `select` / `multiSelect`.                                                                                                                                                                                                                           |
| `getValue`    | `(row) => unknown`                                          | reads `key` as a path | Row-value extractor for the client-side predicate.                                                                                                                                                                                                              |
| `placeholder` | `string`                                                    | —                     | Placeholder for text-like inputs.                                                                                                                                                                                                                               |
| `column`      | `string`                                                    | `key`                 | Column whose header filter shows this widget.                                                                                                                                                                                                                   |
| `ai`          | `false \| FilterAiOptions`                                  | visible, options ≤ 50 | Assistant catalog. `false` hides the filter. `{ options: false }` keeps it and omits values. A number sends values only when the static list is that long or shorter (`FILTER_AI_OPTIONS_LIMIT`). `"auto"` and async loaders are never fetched into the prompt. |

| Factory / prop              | Type                                | Default     | Description                                                                                                                                                                  |
| --------------------------- | ----------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filters([…])`              | `FilterDef[] \| ReactNode`          | —           | Declarative array → the adapter builds the form; JSX → you draw it (escape hatch). Use `filters([])` when every filter is on a column.                                       |
| `filtersMode`               | `"popover" \| "drawer" \| "header"` | `"popover"` | One container. Popover: anchored card, no backdrop. Drawer: panel + backdrop. Header: the per-column funnel from `headerFilters()`, which alone already selects header mode. |
| `onClearFilters`            | `() => void`                        | —           | Notification after the table clears the filters (drawer, chip strip, no-results action).                                                                                     |
| `filterLabels`              | `Record<string, ChipLabelResolver>` | derived     | Per-key chip label resolvers. Derived automatically by declarative filters; needed only for JSX filters (or to override a derived label).                                    |
| `extraChips`                | `ActiveFilterChip[]`                | —           | Extra chips driven by non-URL state, merged with the derived chips.                                                                                                          |
| `activeFilterCount`         | `number`                            | chip count  | Overrides the Filters-button badge.                                                                                                                                          |
| `closeHeaderFilterOnSelect` | `boolean`                           | `false`     | Close a header-filter overlay after a finished single-control write (select/boolean, or a valueless operator). Off by default.                                               |
| `filterFields`              | `boolean`                           | `true`      | Mount the per-field form inside Filters; `false` leaves only the AND/OR tree.                                                                                                |
| `filterTypes([…])`          | `FilterTypeSpec[]`                  | built-ins   | Factory from `@adapttable/<kit>/filters`; extra or replacement filter types merged onto `defaultFilterRegistry`. Same `type` replaces.                                       |
| `headerFilters()`           | factory                             | off         | Factory from `@adapttable/<kit>/header-filters`; per-column header filter funnel. Composing it selects header mode. Desktop only. Never stacked with the popover or drawer.  |

## Headless filter primitives

The pieces behind the auto-built forms are exported for custom filter UIs:

- **Count filters** (the numeric operator + value pair, committed stable in
  [Versioning & stability](./versioning.md)): `COUNT_OPERATORS` is the operator
  list and `COUNT_OPERATOR_SYMBOL` the display symbol per `CountOperator`;
  `CountFilterState` is the widget state; `countFilterExtra` /
  `countFilterStateFromExtra` convert state to and from the filter bag;
  `isCountFilterComplete`, `clearCountFilterExtra`,
  `sanitizeCountFilterParams` and `countFilterChipLabel` handle validation,
  reset, outgoing params, and the chip text.
- **Operators**: `TEXT_OPS` / `NUMBER_OPS` / `DATE_OPS` are the stable URL
  tokens (`FilterOp`, `TextOp`, `NumberOp`, `DateOp`). `filterOpKey` /
  `FILTER_OP_SUFFIX` name the `f_<key>Op` slot; `parseTextOp` /
  `parseNumberOp` / `parseDateOp` / `readFilterOp` read it;
  `isValuelessFilterOp` / `isListFilterOp` / `isBetweenFilterOp` classify
  operand shape. `TEXT_OP_LABEL_KEYS` /
  `NUMBER_OP_LABEL_KEYS` / `DATE_OP_LABEL_KEYS` map each token to a
  `TableLabels` key. `formatFilterChip` / `filterOpLabel` / `isEmptyRowValue`
  / `parseListOperand` / `parseNumberList` / `isFilterOpKey` are the
  helpers. `useTextFilterWidget` returns a `TextFieldWidget`. Relative
  windows: `RELATIVE_NAMED` / `RELATIVE_PRESETS` /
  `RELATIVE_PRESET_LABEL_KEYS` / `RelativeDateToken` / `RelativeDateRange` /
  `RelativePreset` / `parseRelativeToken` / `isRelativeDateToken` /
  `countedRelativeToken` / `splitRelativeToken` / `joinRelativeToken` /
  `relativeTokenLabel` / `resolveRelativeRange`. AND/OR groups:
  `FILTER_TREE_PARAM` / `FILTER_TREE_VERSION` / `parseFilterTree` /
  `serializeFilterTree` / `isActiveFilterTree` / `evaluateFilterTree` /
  `conditionToExtra` over a `QueryFilterGroup` of `QueryCondition`s
  (`isFilterGroup` narrows a child). Each adapter's `FilterTreeBuilder`
  sits at the top of the Filters form when `source.setFilterTree` is
  set; `toolbarShowsFilters` keeps the toolbar button in header mode
  for that tree. The engine stores `ft=1.{…}` and evaluates the tree
  on the frontend tier (ANDed with the flat extra bag). `useTableData`
  wires `evaluateFilterTree` itself; a host that calls `useFrontendData`
  directly passes `filterTreeFn` over the same defs as `filterFn`. A
  server that declares `supports.filterTree` receives the same tree on
  `query.filterTree`. Tree leaves become chips via `useFilterTreeChips`;
  Clear all drops `ft`. See [filter-tree](./filter-tree.md).
- **Facet counts**: `computeFilterFacets` / `rowsExcludingFilter` /
  `FacetMap` / `FacetCounts` count what selecting a value _would_ keep —
  the filtered set with that facet's own filter removed. Frontend
  `useTableData` computes them from `allSearchedRows` (after search,
  before extras). A server that declares `supports.facets` receives
  `query.facets` (checklist keys) and returns the same map on the page;
  `useQuerySource` / `useServerData` surface it as `source.facets`.
  `useChecklistFilter` prefers that map over `allFilteredRows`.
- **Type registry**: `FilterTypeSpec` is one type — widget kind, operators,
  predicate, chips, tree projection, optional `render`. Built-ins
  (`builtInFilterSpecs` / `defaultFilterRegistry`) are the first
  consumers; `filterTypes([…])` (from `@adapttable/<kit>/filters`) merges extras via
  `resolveFilterRegistry` / `createFilterRegistry`. A custom type registers
  through `TableFeatureHost.registerFilterType` / `extendFilterType` in
  `feature.setup(host)`, or `features={[filterTypes(specs)]}`. `filterWidgetKind` / `filterTypeOps` /
  `filterTypeDefaultOp` / `filterTypeSpec` / `renderRegisteredFilter`
  look a spec up. A custom type with `widget: "text"` draws the text
  widget; `host.extendFilterType("text", { ops })` in a feature's `setup` adds
  operators to the AND/OR builder for that type; the field widgets keep their
  own operator menus. See [custom filter types](./custom-filter-types.md). `urlArray` persists a custom type's value as a
  comma-separated array in the URL; `urlNumberKeys` persists its range bounds
  as numbers.
  `emptyFilterRegistry` seeds a registry from scratch.
  `FilterTypeRegistry` / `FilterWidgetKind` / `FilterWidgetRenderProps`
  are the types.
- **Header filters**: compose `headerFilters()` and each filterable column
  header gains a funnel that opens that column's field; composing it selects
  header mode on its own and hides the toolbar Filters button unless the
  AND/OR tree needs it (`resolveFilterMode` / `FilterChromeMode`). See
  [header filters](./header-filters.md). `FilterHeaderRow` /
  `FilterHeaderControl` over `FilterHeaderChrome` / `FilterHeaderControlChrome`
  are the building blocks for a custom header. Helpers `filterDefForColumn`
  (core) and `headerFilterStickTop` (`@adapttable/react`). A def whose bag key
  differs from the column key sets `column` (`key: "name"` under
  `column: "person"`). Checklist / multiSelect open a closed menu of
  checkboxes, not a native `<select multiple>`. The funnel overlay stays open
  while you fill a multi-input field; nested kit dropdowns are not treated as
  outside clicks. Pass `closeHeaderFilterOnSelect` to dismiss after a finished
  single-control write (`useHeaderFilterOverlay` /
  `bindHeaderFilterDismiss` / `headerFilterFieldIsComplete` /
  `usePointerDismiss` / `HeaderFilterSessionProps` /
  `HeaderFilterOpenProvider` / `HeaderFilterOpenContext` /
  `HeaderFilterOpenHost`).
- **Range widgets**: `useRangeFilterWidget` is the kit-agnostic logic behind
  `numberRange` / `dateRange` fields — it returns a `RangeWidgetState` whose
  `RangeFieldWidget` entries carry the visible bounds, the active
  `RangeOp`, and a `RangeOpArity` (`none` / `one` / `two` / `list`);
  `RANGE_SUFFIXES` names the persisted key pair per type (`Min` / `Max` for
  `numberRange`, `From` / `To` for `dateRange`),
  `RANGE_OPS` is the historical four-operator set (`eq` / `gte` / `lte` /
  `between`), and `RANGE_OP_LABEL_KEYS` / `RangeOpLabelKeys` map each
  operator to its `TableLabels` key. `writeRangeFilter` persists the pair
  plus `f_<key>Op`.
- **Definitions and state**: `filterStateKeys` lists the state keys a
  definition reads and writes; `scalarFilterText` renders a scalar filter
  value as input text; `listFilterValues` normalizes a multi-select value
  list; `isDeclarativeFilters` narrows a `filters(…)` argument to its array form;
  `FilterFormSource` is the minimal source shape a filter form needs;
  `ResolvedFilterOptions` is the loaded state of a `filter`'s options
  (including `options: "auto"`); `FilterRuntime` is everything the engine
  derives from the resolved definitions (defs, chip labels, URL keys,
  predicate).
- **Search** ([page](./search.md)): `defaultSearchText` is the default searchable-text projector —
  it flattens a row's own values into the string the search box matches
  against. Replace it per source with `getSearchText`:

  ```tsx
  const source = useFrontendData({
    data: people,
    columns,
    // search the full name and the city, and nothing else
    getSearchText: (row) => `${row.firstName} ${row.lastName} ${row.city}`,
  });
  ```

  It is one projector for the whole row, not a per-column setting: search
  asks "does this row match?", so the row is what gets projected. Include a
  computed value here to make it searchable, or leave a field out to exclude
  it — an id column nobody searches by, say.

## Notes

- `"auto"` needs the full dataset, so it only works on the frontend tier
  (`data` without `onQueryChange`). On the server/source tiers it dev-warns
  and resolves to no options — pass an array or an async loader instead.
- The `dateRange` upper bound is inclusive end-of-day: "On or before
  2026-01-31" keeps that day's rows.
- Relative date filters (`DATE_OPS` token `relative`) store a **token**
  (`today`, `yesterday`, `tomorrow`, `thisWeek`, `thisMonth`,
  `previousMonth`, `last:N`, `next:N`) in `${key}From` plus
  `f_<key>Op=relative`. The URL and Saved Views never hold a resolved
  calendar day — a shared "last 7 days" link stays the last 7 days
  tomorrow. `resolveRelativeRange` is the only resolver; the frontend
  predicate and a server query both call it so they agree. Weeks are ISO
  (Monday–Sunday, local time).
- `Equal` writes the same value to both range keys; clearing a field clears
  its key, so half-filled widgets never leak stale bounds.
- Async loaders run once (the promise is cached); until they resolve, chips
  label with the raw value. A failed load dev-warns and yields no options.
- Passing JSX to `filters(…)` switches off every derivation — your controls
  update table state themselves (live by default), and you supply
  `filterLabels` / `extraChips` / `activeFilterCount` for the chips and badge.
- Changing any filter resets the page to 1. `multiSelect` URL values are
  comma-separated with each entry encoded, so values containing commas
  round-trip safely. With `urlKey="left"`, params become `left.f_status`, ….

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

---

# React table advanced filters — AND/OR filter tree

▶ **Try it live:** [Filtering in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/filtering/)
— open Filters; Advanced is the first block in the popover. Switch the page
to Drawer, or to Header (column icons for one field, Filters for the tree).
[Other UI kits →](./getting-started.md#try-it-in-stackblitz)

The simple filter form is one control per field. When a reader needs
"(Team is Core **or** Platform) **and** Budget ≥ 20k", that is a tree:
nested AND/OR groups, one kit-native builder, one `ft=1.{…}` URL param.

It lives in the **same** Filters popover or drawer as the field list — at
the top, not under it. Header mode keeps a Filters button for the tree
because a column icon cannot express a group.

## Example

```tsx
import { DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, shadcn, unstyled
import { filters } from "@adapttable/mantine/filters";

export function People({ rows }) {
  return (
    <DataTable
      data={rows}
      rowKey={(row) => row.id}
      columns={[
        { key: "name", filter: "text" },
        { key: "team", filter: { type: "select", options: "auto" } },
        { key: "budget", filter: "numberRange" },
      ]}
      features={[filters([])]}
      filtersMode="popover"
      urlKey="f"
    />
  );
}
```

Compose `filters(…)`: the `data` tier then evaluates the tree itself. A host
that builds its own source with `useFrontendData` passes `filterTreeFn`; a
server source declares `supports.filterTree`. Each adapter's
`FilterTreeBuilder` mounts at the top of the Filters form whenever the source
exposes `source.setFilterTree` (every built-in source does) and at least one
filter definition exists.

## How it works

- **Same chrome.** Popover and drawer are the field list's container. The
  builder is the first child of `data-adapttable-part="filters-form"`.
  Header icons filter one column; `toolbarShowsFilters` keeps the toolbar
  Filters button when the tree setter is on so Advanced is not trapped
  behind a column.
- **Model.** A `QueryFilterGroup` of `QueryCondition`s (`isFilterGroup`
  narrows a child). Combinators are `and` / `or`. Leaves name a field,
  an operator from that type's registry, and a value.
- **URL.** `ft=1.{…}` — versioned JSON. Unknown versions are dropped, never
  reinterpreted. Clear all drops `ft` with the flat `f_*` keys.
- **Chips.** Tree leaves become chips via `useFilterTreeChips`. Removing a
  chip rewrites that node; it does not flatten the group.
- **Tree only.** `filterFields={false}` removes the field list and opens the
  builder expanded.
- **Server.** A source that declares `supports.filterTree` receives the
  same tree on `query.filterTree`. The server must apply it all-or-nothing
  — dropping one condition out of an AND would lie.

The field widgets, operators and chips are on [filtering](./filtering.md).
The URL codec is on [url-state](./url-state.md).

---

# React table header filters — a funnel on every filtered column

▶ **See it working:** [Filtering in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/filtering/) — switch the layout to **Header**: each filtered column gets a funnel, and Filters keeps the AND/OR tree. The same page exists for every kit.

Header filters put each filter where its column is. Compose `headerFilters()`
from `@adapttable/<kit>/header-filters` and every column with a filter
definition shows a funnel button in its header cell. The funnel opens the same
kit-native field the Filters panel draws, bound to the same state, URL params
and chips. The filter definitions still come from `filters(…)`
([filtering](./filtering.md)); header filters only move where the fields open.

## Example

```tsx
import { DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { filters } from "@adapttable/mantine/filters";
import { headerFilters } from "@adapttable/mantine/header-filters";

interface Project {
  id: string;
  name: string;
  owner: { name: string };
  status: "active" | "paused" | "done";
  budget: number;
  dueAt: string; // ISO date
}

const projects: Project[] = [
  {
    id: "1",
    name: "Billing rewrite",
    owner: { name: "Amira Haddad" },
    status: "active",
    budget: 42000,
    dueAt: "2026-11-30",
  },
  {
    id: "2",
    name: "Search index",
    owner: { name: "Jonas Weber" },
    status: "paused",
    budget: 18000,
    dueAt: "2026-10-15",
  },
  {
    id: "3",
    name: "Design tokens",
    owner: { name: "Priya Nair" },
    status: "done",
    budget: 9500,
    dueAt: "2026-08-01",
  },
  {
    id: "4",
    name: "Audit log",
    owner: { name: "Amira Haddad" },
    status: "active",
    budget: 27000,
    dueAt: "2027-01-20",
  },
];

export function Projects() {
  return (
    <DataTable
      data={projects}
      rowKey={(row) => row.id}
      columns={[
        { key: "name", filter: "text", sortable: true },
        { key: "owner", header: "Owner", accessor: (row) => row.owner.name },
        {
          key: "status",
          filter: {
            type: "select",
            options: [
              { value: "active", label: "Active" },
              { value: "paused", label: "Paused" },
              { value: "done", label: "Done" },
            ],
          },
        },
        { key: "budget", filter: "numberRange", sortable: true },
        { key: "dueAt", header: "Due", filter: "dateRange" },
      ]}
      features={[
        filters([
          // The state key is a row path; `column` puts the funnel on "owner".
          { key: "owner.name", column: "owner", type: "text", label: "Owner" },
        ]),
        headerFilters(),
      ]}
      closeHeaderFilterOnSelect
    />
  );
}
```

Both features are required. `filters([…])` turns the column `filter`
declarations and the standalone definitions into a filter runtime;
`headerFilters()` draws a funnel for each of them.

## How it works

- **Composing it selects header mode.** The table resolves one filter
  container through `resolveFilterMode(filtersMode, headerFilters)` in
  `@adapttable/core`: header mode wins whenever `headerFilters()` is composed,
  whatever `filtersMode` says, so the toolbar popover or drawer and the header
  funnels are never mounted for the same fields. `filtersMode="header"`
  without the feature resolves to header mode too, but nothing draws the
  funnels — compose `headerFilters()`.
- **One funnel per column.** A column shows a funnel when a definition
  matches it: `filterDefForColumn` picks the first definition whose
  `column ?? key` equals the column key. A column `filter` declaration matches
  its own column. A standalone definition whose state key differs from the
  column key sets `FilterDef.column` — `key: "owner.name"` under
  `column: "owner"` above. A definition that matches no column gets no funnel.
- **The same field as the panel.** The funnel's overlay renders the kit's
  auto-built form for that single definition: the operator-first text,
  number and date widgets, selects, multi-selects, the checklist, and any
  custom type's `render` ([custom filter types](./custom-filter-types.md)).
  Writes go to the same extra bag, so the URL, chips, the page reset and (on
  frontend data) the row predicate behave exactly as they do from the panel.
- **Active state.** A funnel whose definition has any non-empty state key
  carries `data-active` and the kit's active styling.
- **Staying open.** The overlay stays open while a field is being filled —
  picking an operator, typing a term, toggling multi-select options. A
  dropdown the kit portals out of the overlay (a select menu, a date picker)
  is not treated as an outside click. A true outside press or **Escape**
  closes it.
- **`closeHeaderFilterOnSelect`.** Off by default. When set, the overlay also
  closes after a finished single-control write: a `select` or `boolean`
  value, or a valueless operator such as "Is empty". Typed text, range bounds
  and multi-value lists never close it, because another control is still
  waiting. The check reads the type's `widget`, so a custom type drawn as a
  `select` closes the same way.

## The Filters button and the AND/OR tree

In header mode the per-field list leaves the Filters panel — the funnels own
those fields. The toolbar keeps its Filters button only for the
[AND/OR filter tree](./filter-tree.md), which has no column of its own
(`toolbarShowsFilters`). Every built-in source exposes
`source.setFilterTree`, so the button stays and opens the tree builder
expanded.

## Options

| Option / prop               | Type                                | Default            | Description                                                                                                     |
| --------------------------- | ----------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `headerFilters()`           | factory, no arguments               | off                | From `@adapttable/<kit>/header-filters`. A funnel per filtered column; selects header mode. Needs `filters(…)`. |
| `closeHeaderFilterOnSelect` | `boolean` (`DataTable` prop)        | `false`            | Close the overlay after a finished single-control write. Outside press and Escape always close it.              |
| `filtersMode`               | `"popover" \| "drawer" \| "header"` | `"popover"`        | Ignored for the fields while `headerFilters()` is composed; header mode wins.                                   |
| `FilterDef.column`          | `string`                            | `key`              | Column whose header carries this definition's funnel.                                                           |
| `labels.headerFilters`      | `string`                            | `"Column filters"` | Accessible name of the exported compact filter row (`FilterHeaderRow`).                                         |

## Per-kit differences

Every kit draws the funnel with its own button and popover; the field inside
is that kit's auto-built filter form.

- **Ant Design** renders its own table header, so the funnel lives inside the
  column `title`. That keeps `fixed` columns on antd's own header. The
  overlay is portalled to `document.body` and positioned against the funnel,
  following scroll and resize. The funnel stops its click from reaching the
  header, so opening it never toggles antd's sort. Open state is held above
  the header (`HeaderFilterOpenProvider`), because antd rebuilds column
  titles on every filter write.
- **The other kits** render the funnel inside the header cell next to the
  caption and the sort control, so it moves with pinned columns, sticky
  headers and column windowing.

For custom header markup, each kit also exports `FilterHeaderControl` (one
column's compact control) and `FilterHeaderRow` (a filter row for a custom
header) over `FilterHeaderControlChrome` / `FilterHeaderChrome`. The overlay
logic is headless in `@adapttable/react`: `useHeaderFilterOverlay`,
`bindHeaderFilterDismiss`, `headerFilterFieldIsComplete` and
`usePointerDismiss`.

## Notes

- **Desktop only.** Mobile cards have no column headers, so no funnel
  renders below the mobile breakpoint. Active filters still show as removable
  chips, and the Filters button still opens the AND/OR tree. A table that
  must offer per-field filters on phones uses `filtersMode="popover"` or
  `"drawer"` without `headerFilters()`.
- **URL state and saved views.** Header filters write the same `f_<key>`
  params as the panel — `f_name` and `f_nameOp`, `f_budgetMin` /
  `f_budgetMax`, `f_dueAtFrom` / `f_dueAtTo`, `f_owner.name` above — so a
  shared link or a [saved view](./saved-views.md) reopens with the same
  funnels active. See [URL state](./url-state.md).
- **Keyboard and screen readers.** The funnel is a real button, reached with
  **Tab** and named by the definition's label (`filterLabel`: the `label`,
  or the humanized key). **Escape** closes the overlay.
- **The standard preset.** `standardFeatures()` includes `headerFilters()`,
  so a table composed from the preset opens its filters from the headers.
  The preset composes `filters(…)` only when its `filters` option is given —
  pass `standardFeatures({ filters: [] })` when every filter is declared on a
  column. Compose the members individually for popover or drawer filters — see
  [feature composition](./features.md#the-standard-preset--one-import-for-a-good-table).

---

# React table custom filter types — your own widgets, operators and predicates

The seven built-in filter types (`FILTER_TYPES`) are entries in a registry,
not a switch statement. A custom type is one more entry: a `FilterTypeSpec`
names the widget, the operators, the row predicate, the chips and the AND/OR
tree projection, and every filter definition whose `type` names it gets the
full treatment — the form field, the header funnel, the `f_<key>` URL params,
removable chips and the frontend predicate. Register specs with
`filterTypes([…])` from `@adapttable/<kit>/filters`, or from a feature's
`setup(host)`.

## Example

A `tags` type for rows that carry an array, with "has any" and "has all"
operators:

```tsx
import { filterLabel, filterOpKey, getPath } from "@adapttable/core";
import { DataTable, type FilterTypeSpec } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { filters, filterTypes } from "@adapttable/mantine/filters";

interface Article {
  id: string;
  title: string;
  tags: string[];
}

const articles: Article[] = [
  { id: "1", title: "Server-side sorting", tags: ["react", "server"] },
  { id: "2", title: "Mobile card layouts", tags: ["react", "mobile"] },
  { id: "3", title: "Streaming row patches", tags: ["server", "realtime"] },
  { id: "4", title: "Keyboard navigation", tags: ["a11y", "react"] },
];

// A list from the URL arrives as an array; a tree condition's value is
// the text typed into the builder, so split it on commas.
function asList(value: unknown): string[] {
  if (Array.isArray(value)) return value.map(String);
  if (typeof value !== "string") return [];
  return value
    .split(",")
    .map((entry) => entry.trim())
    .filter(Boolean);
}

const tagsFilter: FilterTypeSpec = {
  type: "tags",
  widget: "multiSelect",
  ops: ["hasAny", "hasAll"],
  defaultOp: "hasAny",
  urlArray: true,
  stateKeys: (def) => [def.key, filterOpKey(def.key)],
  match: (def, extra, row) => {
    const wanted = asList(extra[def.key]);
    if (wanted.length === 0) return true;
    const tags = asList(
      def.getValue ? def.getValue(row) : getPath(row, def.key)
    );
    return extra[filterOpKey(def.key)] === "hasAll"
      ? wanted.every((tag) => tags.includes(tag))
      : wanted.some((tag) => tags.includes(tag));
  },
  chips: (def) => ({
    [def.key]: (value) => `${filterLabel(def)}: ${value}`,
  }),
  conditionToExtra: (def, condition) => ({
    [def.key]: asList(condition.value),
    [filterOpKey(def.key)]: condition.op,
  }),
};

export function Articles() {
  return (
    <DataTable
      data={articles}
      rowKey={(row) => row.id}
      columns={[
        { key: "title", filter: "text" },
        {
          key: "tags",
          accessor: (row) => row.tags.join(", "),
          filter: {
            type: "tags",
            options: [
              { value: "react", label: "React" },
              { value: "server", label: "Server" },
              { value: "mobile", label: "Mobile" },
              { value: "realtime", label: "Realtime" },
              { value: "a11y", label: "Accessibility" },
            ],
          },
        },
      ]}
      features={[filterTypes([tagsFilter]), filters([])]}
    />
  );
}
```

The field draws as the kit's multi-select, the selection writes
`f_tags=react,server`, each selected tag becomes a chip, and the AND/OR
builder offers `hasAny` / `hasAll` for the Tags field.

## How it works

- **A registry of specs.** The table resolves its registry from the built-ins
  (`builtInFilterSpecs`, collected in `defaultFilterRegistry`) plus every
  registered spec (`resolveFilterRegistry`). A spec whose `type` matches an
  existing one replaces it — a built-in included. Registries are immutable:
  each registration builds the next one.
- **Definitions name a type.** A column `filter: { type: "tags", … }` or a
  standalone `filters([{ key, type: "tags" }])` entry uses the spec. Column
  declarations still need `filters(…)` composed; `filterTypes(…)` only
  teaches the table new types. A definition whose type is not registered
  warns in development, draws no field and matches every row.
- **Everything else is looked up.** `filterWidgetKind`, `filterTypeOps`,
  `filterTypeDefaultOp` and `filterTypeSpec` read a spec for a definition;
  `renderRegisteredFilter` returns a spec's `render` output, or `undefined`
  when the kit widget should draw. Each kit's auto-built form and header
  funnel call it first.
- **State is a flat bag.** A type owns the keys `stateKeys(def)` returns.
  Widgets write those keys with `source.setExtra` / `setExtras`, Clear all
  resets them, and the header funnel shows as active while any of them holds
  a value.

## The `FilterTypeSpec` contract

| Member             | Type                                               | Required | Description                                                                                                                                                                                   |
| ------------------ | -------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`             | `string`                                           | yes      | The name a `FilterDef.type` references.                                                                                                                                                       |
| `widget`           | `FilterWidgetKind`                                 | yes      | Built-in widget the kit draws: `text`, `select`, `multiSelect`, `checklist`, `boolean`, `dateRange` or `numberRange`. Ignored for the form when `render` is set.                              |
| `ops`              | `readonly string[]`                                | yes      | Operators the AND/OR builder offers for this type, in menu order.                                                                                                                             |
| `defaultOp`        | `string`                                           | yes      | Operator a new tree condition starts with.                                                                                                                                                    |
| `stateKeys(def)`   | `(def) => string[]`                                | yes      | The extra-bag keys this type owns for one definition. Each persists as `f_<stateKey>`.                                                                                                        |
| `match`            | `(def, extra, row) => boolean`                     | yes      | Frontend predicate. Return `true` when the filter is inactive.                                                                                                                                |
| `chips(def)`       | `(def) => Record<string, ChipLabelResolver>`       | yes      | Chip text per state key: `(value, extra?) => string`. An array value yields one chip per entry.                                                                                               |
| `conditionToExtra` | `(def, condition: QueryCondition) => ExtraFilters` | yes      | Projects one tree condition (`{ key, op, value }`) onto the flat bag `match` reads, so the tree reuses the predicate.                                                                         |
| `render`           | `(props: FilterWidgetRenderProps) => DisplayValue` | no       | Draw the field yourself. Receives `def`, `source` (`extra`, `setExtra`, `setExtras`, `allFilteredRows`, `facets`), resolved `labels` and `className`. Used by the form and the header funnel. |
| `urlArray`         | `boolean`                                          | no       | Read and write `f_<key>` as a comma-separated array, each entry percent-encoded.                                                                                                              |
| `urlNumberKeys`    | `boolean`                                          | no       | Parse `f_<key>Min` and `f_<key>Max` as numbers.                                                                                                                                               |

`widget` also decides the parts the type does not draw itself: the value
input a tree condition shows, whether `closeHeaderFilterOnSelect` treats a
write as finished, and — for `widget: "checklist"` — whether the frontend
tier computes facet counts for the key.

## Operators

`ops` and `defaultOp` belong to the [AND/OR filter tree](./filter-tree.md):
they are the operator menu of a condition row, and the stored
`condition.op`. The built-in field widgets keep their own operator menus —
`TEXT_OPS` for text, `NUMBER_OPS` for numbers, `DATE_OPS` for dates — and
store the choice in `f_<key>Op` (`filterOpKey(key)`). An operator token with a
built-in label (`contains`, `gte`, `before`, …) shows that label in the
builder; any other token shows as written, so name custom tokens readably.

The operator a type evaluates lives wherever `match` reads it. The example
reads `f_tagsOp` and falls back to "has any"; `conditionToExtra` writes the
tree condition's `op` into that same key, which is how one predicate serves
both the field and the tree. `isValuelessFilterOp`, `isListFilterOp` and
`isBetweenFilterOp` classify the built-in tokens when a custom predicate
reuses them.

## Registering from a feature

`filterTypes(specs)` is a feature whose `setup` calls
`host.registerFilterType` once per spec. A plugin can do the same next to its
other registrations, and patch an existing type with
`host.extendFilterType(type, patch)` — the patch merges onto the current
spec, so a feature changes one member without forking the rest:

```tsx
import { filterLabel, getPath, RANGE_SUFFIXES } from "@adapttable/core";
import { type FilterTypeSpec } from "@adapttable/mantine";
import type { TableFeature } from "@adapttable/mantine/features";
import { SegmentedControl } from "@mantine/core";

const minKey = (key: string) => key + RANGE_SUFFIXES.numberRange.start;

const minRating: FilterTypeSpec = {
  type: "minRating",
  widget: "numberRange",
  ops: ["gte"],
  defaultOp: "gte",
  urlNumberKeys: true, // f_<key>Min parses as a number
  stateKeys: (def) => [minKey(def.key)],
  match: (def, extra, row) => {
    const min = extra[minKey(def.key)];
    if (typeof min !== "number") return true;
    const value = Number(
      def.getValue ? def.getValue(row) : getPath(row, def.key)
    );
    return Number.isFinite(value) && value >= min;
  },
  chips: (def) => ({
    [minKey(def.key)]: (value) => `${filterLabel(def)} ≥ ${value}`,
  }),
  conditionToExtra: (def, condition) => {
    const min = Number(condition.value);
    const set = condition.value != null && condition.value !== "";
    return { [minKey(def.key)]: set && Number.isFinite(min) ? min : undefined };
  },
  render: ({ def, source }) => (
    <SegmentedControl
      aria-label={filterLabel(def)}
      data={["Any", "3", "4", "5"]}
      value={String(source.extra[minKey(def.key)] ?? "Any")}
      onChange={(next) =>
        source.setExtra(
          minKey(def.key),
          next === "Any" ? undefined : Number(next)
        )
      }
    />
  ),
};

export const ratingFilters: TableFeature = {
  id: "rating-filters",
  setup(host) {
    host.registerFilterType(minRating);
    // New text conditions in the AND/OR builder start at "starts with".
    host.extendFilterType("text", { defaultOp: "startsWith" });
  },
};
```

`features={[ratingFilters, filters([])]}` with a column declaring
`filter: { type: "minRating" }` draws the segmented control in the Filters
panel and in the header funnel, persists `f_ratingMin=4`, and chips it as
"Rating ≥ 4".

Registrations apply in order, then the patches, so a feature can register a
type and extend it in the same `setup`. `extendFilterType` on an unknown type
warns in development and changes nothing. `setup` may return a cleanup
function, or call `host.onDispose`, for when the table unmounts or `features`
changes.

`filterTypes` has one feature id (`filter-types`), and a later feature with
the same id replaces an earlier one. Pass every spec to one
`filterTypes([…])` call.

## URL state and server queries

- **URL.** Each state key persists as `f_<stateKey>` — `f_tags`, `f_tagsOp`,
  `f_ratingMin` — under the table's `urlKey` namespace. Values read back as
  strings, except `f_<key>` with `urlArray` (an array) and
  `f_<key>Min` / `f_<key>Max` with `urlNumberKeys` (numbers).
  `RANGE_SUFFIXES` names the pairs the built-ins use: `Min` / `Max` for
  `numberRange`, `From` / `To` for `dateRange`. Empty values delete their
  param. A tree condition travels inside `ft=1.{…}` with its custom `op`.
  See [URL state](./url-state.md).
- **Saved views** capture those params like any other filter — see
  [saved views](./saved-views.md).
- **Server tier.** `match` runs only on frontend data. A server source
  receives the same flat bag: `query.filters` in `useServerData`'s
  `onQueryChange`, `params.filters` in `useQuerySource`, keyed by state key
  without the `f_` prefix (`{ tags: ["react", "server"], tagsOp: "hasAll" }`).
  A source that declares `supports.filterTree` also receives
  `query.filterTree`, whose conditions carry the custom `op` tokens. The
  backend implements the same semantics as `match`.
- **Backend parsing.** `parseTableQuery` from `@adapttable/server` returns
  `filters` keyed by the name after `f_` and rejects names outside the
  schema's `columns` allowlist — list every state key (`"tags"`,
  `"tagsOp"`). An array arrives as one comma-separated string; split and
  decode it (`value.split(",").map(decodeURIComponent)`). See
  [server queries](./server-queries.md).

## Notes

- **Header filters.** A custom type gets a funnel like any built-in once
  [header filters](./header-filters.md) are composed; a `render` spec draws
  the same control there.
- **Mobile.** On the card layout the Filters popover or drawer draws the
  same field — kit widget or `render` — as on desktop.
- **Accessibility.** A spec without `render` inherits the kit widget's
  labelling. A `render` owns its own: name the control from
  `filterLabel(def)`, as above, and use `labels` for any built-in strings.
- **Headless pieces.** `createFilterRegistry(specs)` and
  `emptyFilterRegistry()` build a registry without the built-ins for tests
  or custom forms; `FilterTypeRegistry` exposes `get`, `has` and `types`.
  The built-in widgets are available to a custom form as hooks —
  `useTextFilterWidget` and `useRangeFilterWidget` in `@adapttable/react`
  ([filtering](./filtering.md#headless-filter-primitives)).

---

# React table pagination — paged, infinite scroll & auto by device

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — numbered pagination is on by default in the starter; edit it in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

Every table paginates out of the box. Choose between a classic paged footer,
infinite scroll, or `"auto"` (the default), which picks per device.

## Example

```tsx
import { DataTable } from "@adapttable/mantine"; // or @adapttable/mui, chakra, antd, radix, shadcn, unstyled

interface Person {
  id: string;
  name: string;
  city: string;
}

const data: Person[] = Array.from({ length: 120 }, (_, i) => ({
  id: String(i + 1),
  name: `Person ${i + 1}`,
  city: i % 2 === 0 ? "Dubai" : "Oslo",
}));

export function People() {
  return (
    <DataTable
      data={data}
      columns={[{ key: "name", sortable: true }, { key: "city" }]}
      rowKey={(r) => r.id}
      paginationMode="paged"
      defaults={{ limit: 10 }}
    />
  );
}
```

## How it works

- `paginationMode` accepts `"paged"`, `"infinite"`, or `"auto"` (the default).
  `"auto"` resolves by device: **infinite scroll on mobile, paged on desktop**,
  by the same rule as the card/table layout switch — the 768px media query, or
  `mobileBreakpoint` when you set it, and `forceMobile` over both.
- **Paged** renders a footer with a rows-per-page select, page buttons, and a
  "Showing X–Y of Z" summary.
- **Infinite** auto-loads the next page when a sentinel below the last row
  scrolls into view (`IntersectionObserver`, prefetching early), and also
  renders an explicit **Load more** button as a keyboard- and
  screen-reader-friendly fallback.
- Page and page size live in the URL (`?page=`, `?limit=`), so reloads and
  shared links restore the exact view. `defaults={{ limit }}` applies only
  while the URL is silent about a key. The rows-per-page list is 10 / 25 /
  50 / 100 (`PAGE_SIZE_OPTIONS`; `pageSizeOptions()` builds the list, both
  from `@adapttable/core`), plus that default when it isn't already in the
  list — so a table that starts at 500 still offers 500 after you pick 10.
- On the server tier, pagination state arrives in the consolidated
  `TableQuery` (`{ page, limit, … }`) passed to `onQueryChange` — forward both
  to your API and return `rows` + `total`; `total` drives the pager.

## Cursor pagination

Offset paging asks for "rows 100–125". If a row is inserted or deleted while
someone is reading, every later page shifts by one, and they see an entry twice
or never see it at all. Cursor pagination asks for "the 25 rows after _this_
one", which cannot drift.

Declare the capability and hand back the token your API returned:

```tsx
import { useState } from "react";
import { useServerData } from "@adapttable/react";
import { DataTable } from "@adapttable/mantine";

interface Row {
  id: string;
  name: string;
}

export function Rows() {
  const [data, setData] = useState<{
    rows: Row[];
    nextCursor: string | null;
  }>({ rows: [], nextCursor: null });

  const source = useServerData<Row>({
    rows: data.rows,
    total: 0, // cursor APIs usually have no count to give
    nextCursor: data.nextCursor,
    supports: { cursor: true },
    onQueryChange: async ({ cursor, limit, search }, { signal }) => {
      const params = new URLSearchParams({ limit: String(limit), search });
      if (cursor) params.set("cursor", cursor);
      const res = await fetch(`/api/rows?${params}`, { signal });
      setData(await res.json()); // { rows, nextCursor }
    },
  });

  return (
    <DataTable
      source={source}
      columns={[{ key: "name" }]}
      rowKey={(r) => r.id}
    />
  );
}
```

Return `nextCursor: null` when there are no more rows — that is what ends the
list, since there is no total to count against.

What the table guarantees:

- **It only ever sends a token your server issued.** The first page carries no
  `cursor` field at all, so the query is byte-for-byte the one an offset
  endpoint already receives.
- **Back works.** Tokens are kept as a trail, so paging back through what the
  user has already seen replays their own cursors.
- **A jump to an unvisited page does nothing.** Page 7 has no token, and
  sending none would silently re-serve page 1. This is the honest shape of
  cursor pagination rather than a limitation to route around — use offset
  paging (omit `supports.cursor`) where arbitrary jumps matter.
- **A trail that no longer means anything is thrown away.** Change the search,
  the sort, a filter or the page size and every held token points into a result
  that no longer exists, so the trail resets to page 1 rather than paging into
  the previous query's rows.

### With a query library

`useQuerySource` takes the same two options, so cursor mode is not tied to the
hand-rolled tier: declare the capability and say where the token lives on your
page.

```tsx
import { useInfiniteQuery } from "@tanstack/react-query";
import type { TableQueryParams } from "@adapttable/core";
import { useQuerySource } from "@adapttable/mantine";

interface Person {
  id: string;
  name: string;
}
type PeopleParams = TableQueryParams;
interface PeoplePage {
  items: Person[];
  next: string | null;
}

function usePeopleQuery(params: Partial<PeopleParams>) {
  return useInfiniteQuery({
    queryKey: ["people", params],
    queryFn: async (): Promise<PeoplePage> => {
      const search = new URLSearchParams();
      for (const [key, value] of Object.entries(params)) {
        if (value !== undefined) search.set(key, String(value));
      }
      return (await fetch(`/api/people?${search}`)).json();
    },
    initialPageParam: params.page ?? 1,
    getNextPageParam: () => undefined,
  });
}

export function usePeopleSource() {
  return useQuerySource<Person, PeopleParams, PeoplePage>({
    usePaginatedQuery: usePeopleQuery,
    selectPage: (page) => ({ rows: page.items, total: 0 }),
    supports: { cursor: true },
    nextCursor: (page) => page.next, // the token that opens the NEXT page
  });
}
```

The token reaches your query function as `params.cursor`, alongside the params
it already receives — nothing else about the hook changes.

- **A new sort, filter, search, or page size resets to the first page.** Those
  tokens describe a position in a result set that no longer exists.
- **The URL keeps everything except the cursor.** Sort, filters, search and
  page size stay shareable; an opaque token would be meaningless to whoever
  opened the link, and stale by the time they did.

## Options

| Prop               | Type                                   | Default                  | Description                                                                               |
| ------------------ | -------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `paginationMode`   | `"paged" \| "infinite" \| "auto"`      | `"auto"`                 | Pagination behaviour; `"auto"` = infinite on mobile, paged on desktop.                    |
| `defaults`         | `{ page?: number; limit?: number; … }` | `{ page: 1, limit: 25 }` | Initial page/page-size, used while the URL has no value.                                  |
| `labels`           | `TableLabels`                          | English                  | Override `rowsPerPage`, `loadMore`, and the `showing` range builder.                      |
| `skeletonRows`     | `number`                               | page size                | Number of skeleton rows shown while loading.                                              |
| `mobileBreakpoint` | `number`                               | `768`                    | Width at or below which the card layout takes over. `"auto"` pagination does not read it. |
| `forceMobile`      | `boolean`                              | —                        | Pins the card layout. `"auto"` pagination does not read it.                               |

## Notes

- A URL `limit` outside **1–500** falls back to the default page size, and
  the rows-per-page control clamps to 1–500. `defaults.limit` is used as
  given.
- `paginationMode` applies to every tier. On the `onQueryChange` tier
  (`useServerData`) infinite mode appends each new page to the rows already
  shown.
- `nextCursor` is read only when the source declares `supports: { cursor: true }`.
  Without that declaration the field is ignored and no `cursor` is ever sent,
  so an endpoint written before cursors existed keeps its exact query.
- In infinite mode the table slices `page × limit` rows, so "page" really
  means "how much is loaded" — `fetchNextPage` just bumps it.
- The infinite-scroll sentinel is exported from `@adapttable/react` as a
  headless hook, `useInfiniteScroll`, for custom markup (`rootMargin`
  defaults to `"200px"`); it no-ops safely where
  `IntersectionObserver` is unavailable (SSR, tests).

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

---

# React table row selection & bulk actions — checkbox, keyboard, URL-synced

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — a real AdaptTable you can edit in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

Import `bulkActions` from `@adapttable/<kit>/bulk-actions` and compose it in
`features` — checkboxes on every row, a tri-state header checkbox, and a
selection toolbar with your action buttons. The import and `features` entry
are the switch; there is no `bulkActions` table prop. See
[feature composition](./features.md).

## Example

```tsx
// or import from "@adapttable/mui", "@adapttable/chakra", "@adapttable/antd",
// "@adapttable/radix", "@adapttable/shadcn", "@adapttable/unstyled" — same props everywhere.
import {
  type BulkAction,
  DataTable,
  type RowAction,
} from "@adapttable/mantine";
import { bulkActions } from "@adapttable/mantine/bulk-actions";
import { rowActions } from "@adapttable/mantine/row-actions";

interface Person {
  id: string;
  name: string;
  role: string;
  status: string;
}

const PEOPLE: Person[] = [
  { id: "1", name: "Ada Lovelace", role: "Engineer", status: "active" },
  { id: "2", name: "Alan Turing", role: "Founder", status: "active" },
  { id: "3", name: "Grace Hopper", role: "Admiral", status: "retired" },
];

// Per-row: trailing buttons on each desktop row / mobile card.
const rowActionDefs: RowAction<Person>[] = [
  { key: "edit", label: "Edit", onClick: (row) => console.log("edit", row.id) },
];

// Bulk: buttons in the selection toolbar, fired with the selected ids.
const bulkActionDefs: BulkAction[] = [
  {
    key: "archive",
    label: "Archive",
    onClick: (ids, { allMatching, total }) => {
      if (allMatching) console.log(`archive all ${total} matching rows`);
      else console.log("archive", ids);
    },
  },
  {
    key: "delete",
    label: "Delete",
    color: "red",
    confirm: {
      title: "Delete people",
      message: (count) => `Delete ${count} people? This cannot be undone.`,
      confirmLabel: "Delete",
      danger: true,
    },
    onClick: (ids) => console.log("delete", ids),
  },
];

export function PeopleTable() {
  return (
    <DataTable
      data={PEOPLE}
      columns={[
        { key: "name", sortable: true },
        { key: "role" },
        { key: "status" },
      ]}
      rowKey={(r) => r.id}
      features={[rowActions(rowActionDefs), bulkActions(bulkActionDefs)]}
      onSelectionChange={(ids) => console.log("selected", ids)}
    />
  );
}
```

## How it works

- `bulkActions(actions)` is the switch: composing it enables the checkbox
  column, the header tri-state (all / some / none of the visible rows), and
  the bulk bar that appears once at least one row is selected.
  `selectionStats()` and `columnSelectionCheckbox()` share the same selection
  state, so either one also adds the checkbox column; without `bulkActions`
  there is no bulk bar.
- **`RowAction` vs `BulkAction`**: a row action runs on one row
  (`onClick(row)`, `confirm.message(row)`); a bulk action runs on the
  selection (`onClick(ids, context)`, `confirm.message(count)`).
- **Select all on the page vs all N matching**: the header checkbox selects
  the visible page. When the whole page is selected and more rows match, a
  Gmail-style banner offers "Select all N matching"; accepting widens the
  scope and your action receives `BulkActionContext` —
  `{ allMatching: true, total }` — so you act on the whole filtered set
  server-side, not just the page `ids`. Any explicit toggle narrows the scope
  back to concrete ids. The banner appears when the table can name the whole
  matching set — client data, or a server source that reports `total`.
- **Confirmation sized by scope**: a bulk action's `confirm.message(count)`
  receives `context.total` when all-matching is active, the page ids count
  otherwise. The dialog goes through the table's `confirm` handler
  (`window.confirm` by default); `danger: true` marks it destructive.
- **Controlled or uncontrolled**: omit `selectedIds` and the table owns the
  selection (`onSelectionChange` is then an observer). Pass `selectedIds` and
  it becomes controlled — apply `onSelectionChange` requests to your state to
  accept them, the same split as `columnLayout`.
- Selection is keyed by id (`selectionGetId`, defaulting to `rowKey`), so it
  survives page, sort, and page-size changes — and resets automatically when
  the result _set_ changes (a new search term, different filter values, or a
  grouping change).

## Options

| Factory / prop                   | Type                       | Default          | Description                                                                                                                                                                                                                      |
| -------------------------------- | -------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bulkActions(actions)`           | `BulkAction[]`             | —                | Factory from `@adapttable/<kit>/bulk-actions`; composing it turns on row selection and mounts the bulk bar with these buttons.                                                                                                   |
| `rowActions(actions, handlers?)` | `RowAction<TRow>[]`        | —                | Factory from `@adapttable/<kit>/row-actions`; trailing per-row actions, independent of selection. `handlers` add Add / Duplicate / Delete — see [row actions](./row-actions.md).                                                 |
| `rowActionsLayout`               | `RowActionsLayout`         | `"buttons"`      | Omit or `"buttons"` for the strip; `"menu"` for a 3-dot menu.                                                                                                                                                                    |
| `renderRowActions`               | `RowActionsRenderer<TRow>` | —                | Replace the trailing actions cell; wins over `rowActionsLayout`.                                                                                                                                                                 |
| `selectedIds`                    | `readonly string[]`        | — (uncontrolled) | Controlled selection ids.                                                                                                                                                                                                        |
| `onSelectionChange`              | `(ids: string[]) => void`  | —                | Uncontrolled: observer for every change — once on mount with the (empty) initial set, per toggle/select-all, and on the automatic reset when search or a filter changes. Controlled: the change-request handler (no mount fire). |
| `selectionGetId`                 | `(row: TRow) => string`    | `rowKey`         | Selection id extractor when it must differ from the React key.                                                                                                                                                                   |
| `confirm`                        | `ConfirmHandler`           | `window.confirm` | Confirmation handler for actions with a `confirm` block; pass your own for a styled dialog.                                                                                                                                      |

## Notes

- `BulkAction.onClick(ids, context)` may return a promise: the button shows a
  loading state, other bulk buttons disable while it runs, and the selection
  clears after a successful run.
- `BulkAction.disabledReason(ids)` returns a non-empty string to grey the
  button out _and_ explain why (shown as its tooltip). Row actions have
  `disabledReason(row)`, `isDisabled(row)`, and `isHidden(row)`.
- Both action types take `icon` and `color`. A `RowAction` with
  `editsRow: true` opens row edit mode and carries no `onClick` (see
  [cell editing](./cell-editing.md#opening-the-row-from-your-own-pencil)).
- The per-action `confirm` block is
  `{ title, message, confirmLabel, danger? }` — all strings pre-translated.
  Your `confirm` handler receives the full `ConfirmRequest` (including
  `cancelLabel` and `onConfirm`).
- With [`tableAgent`](./agent-capabilities.md#row-and-bulk-actions)
  composed, each row and bulk action is also an agent capability
  (`rowAction.<key>`, `bulkAction.<key>`) under the table's approval policy;
  `ai: false` on an action keeps it away from the agent, and `ai.approval`
  overrides the policy for that action.
- The selection toolbar's strings (`selectedCount`, `selectAllMatching`,
  `allMatchingSelected`, …) are overridable via the `labels` prop.
- Headless consumers can reuse the same machinery: `useSelection` (with a
  `resetKey`) and `useBulkActionRunner` are exported from `@adapttable/react`;
  `runRowAction` from `@adapttable/core`.

See it live in the [selection demo](https://adapttable.orwamahmoud.com/react/demo/mantine/selection/).

---

# React table row actions — add, duplicate and delete rows

▶ **See it working:** [row actions in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/rows/) — a trailing actions column, collapsed into a 3-dot menu. The same pages exist for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

Import `rowActions` from `@adapttable/<kit>/row-actions`. It takes two
optional arguments: your own per-row actions, and the handlers that add,
duplicate and delete rows. A table that does not compose it carries none of
this — see [feature composition](./features.md).

```tsx
import { DataTable } from "@adapttable/mantine";
import { rowActions } from "@adapttable/mantine/row-actions";

function Tasks({ rows, setRows }: TasksProps) {
  return (
    <DataTable
      data={rows}
      columns={columns}
      rowKey={(row) => row.id}
      features={[
        rowActions(
          [{ key: "open", label: "Open", onClick: (row) => openTask(row.id) }],
          {
            onAddRow: () => setRows((current) => [blankTask(), ...current]),
            onDuplicateRow: (row) =>
              setRows((current) => [{ ...row, id: nextId() }, ...current]),
            onDeleteRow: (row) =>
              setRows((current) => current.filter((r) => r.id !== row.id)),
          }
        ),
      ]}
    />
  );
}
```

## Your own actions

Each `RowAction` is `{ key, label, onClick }`, plus optional `icon` (renders
icon-only, with `label` as the tooltip and accessible name), `color`,
`isDisabled` / `disabledReason` (a non-empty reason disables the action and
explains why), `isHidden`, a `confirm` dialog (`title`, `message(row)`,
`confirmLabel`, `danger`) and `editsRow`, which opens the row's
[row-mode form](./cell-editing.md) instead of writing anything itself.

They render as trailing buttons on desktop and card buttons on mobile, in an
actions column that the Columns menu can hide or pin to the end.
`rowActionsLayout="menu"` collapses them into a 3-dot menu drawn with each
kit's own Menu (`labels.rowActionsMenu` names the trigger);
`renderRowActions` replaces the cell entirely and wins over the layout.

## Add, duplicate and delete

The second argument is `RowMutationHandlers`:

| Handler            | What appears                                                      |
| ------------------ | ----------------------------------------------------------------- |
| `onAddRow`         | An **Add row** button in the toolbar (part `add-row`).            |
| `onDuplicateRow`   | An icon-only **Duplicate row** action on every row.               |
| `onDeleteRow`      | An icon-only **Delete row** action on every row, confirmed first. |
| `confirmDeleteRow` | `false` deletes without the confirmation dialog.                  |

Duplicate and Delete come after your own actions, so a delete stays last, under
the keys `DUPLICATE_ROW_ACTION_KEY` and `DELETE_ROW_ACTION_KEY`. The delete
dialog uses `labels.deleteRow` as its title and `labels.deleteRowConfirm` as
its question. `labels.addRow`, `labels.duplicateRow`, `labels.deleteRow` and
`labels.deleteRowConfirm` are translated in every bundled locale, and the
controls mirror in a right-to-left table.

**The table asks; you do the rest.** It stores no row and holds no draft. A row
you add arrives through the source like every other row — editable, filterable,
sortable, counted, grouped and virtualized from the moment it lands. What a copy
means (which fields carry over, what id it gets) is yours. For an in-memory
table, `insertRow`, `removeRow` and `applyRowPatches` from `@adapttable/core`
do the list work. Pair the handlers with [`editing()`](./cell-editing.md) and a
reader adds a blank row and fills it in place.

## Keyboard and screen readers

Every action is a real button in the kit's own component: Tab reaches it, Enter
and Space run it, and its label is the accessible name. With
[`rowPinning`](./row-pinning.md) composed, its pin actions join the same column.

## Headless

`useRowMutations` (`UseRowMutationsOptions` in, `RowMutationsState` out) builds
the state a kit renders: `canAdd`, `addRow`, and the Duplicate and Delete
actions, which `chrome.rowActions` already includes. See
[headless](./headless.md) and [building an adapter](./building-an-adapter.md).

---

# React table expandable rows — detail panels with keyboard support

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — a real AdaptTable you can edit in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [nested tables in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/nested-tables/) — open a row onto another table, not a blank panel. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

Render a detail panel under any row by composing `rowDetail(render)` from
`@adapttable/<kit>/row-detail`. To put a whole table in the panel instead, the
same subpath exports `nestedTable(...)` — see
[nested tables](./nested-tables.md).

## Example

```tsx
import { DataTable } from "@adapttable/mantine"; // or @adapttable/mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { rowDetail } from "@adapttable/mantine/row-detail";

interface Order {
  id: string;
  customer: string;
  total: number;
  items: string[];
}

const data: Order[] = [
  { id: "1", customer: "Aisha", total: 240, items: ["Desk", "Lamp"] },
  { id: "2", customer: "Jonas", total: 90, items: ["Chair"] },
  { id: "3", customer: "Mei", total: 410, items: ["Monitor", "Dock", "Cable"] },
];

export function Orders() {
  return (
    <DataTable
      data={data}
      columns={[{ key: "customer", sortable: true }, { key: "total" }]}
      rowKey={(r) => r.id}
      features={[
        rowDetail((row: Order) => (
          <ul>
            {row.items.map((item) => (
              <li key={item}>{item}</li>
            ))}
          </ul>
        )),
      ]}
    />
  );
}
```

## How it works

- Composing `rowDetail(render)` adds a leading expand chevron on desktop
  rows and a detail section on mobile cards — no extra flag. The second
  argument, `defaultExpandedRowIds`, opens those rows on the first render; after
  that the reader's toggles own the set.
- **Multiple rows may be open at once.** Expansion is keyed by row id, so an
  open panel survives sorting and paging: a row that leaves the page simply
  re-opens when it returns.
- The chevron carries `aria-expanded` plus the `expandRow` / `collapseRow`
  labels (defaults "Expand row" / "Collapse row"; the i18n presets translate
  them).
- Ant Design maps the contract onto its **native** `expandable` API
  (`expandedRowKeys` / `expandedRowRender`), with a custom expand icon so the
  `labels.expandRow` / `labels.collapseRow` contract still applies instead of
  antd's ConfigProvider locale.
- The state lives in a headless hook, `useRowExpansion()` — use it for custom
  markup: `{ expandedIds, isExpanded(id), toggle(id) }`.

## Options

`rowDetail(renderRowDetail, defaultExpandedRowIds?)`:

| Argument                | Type                     | Default | Description                                                 |
| ----------------------- | ------------------------ | ------- | ----------------------------------------------------------- |
| `renderRowDetail`       | `(row: TRow) => unknown` | —       | Detail-panel renderer.                                      |
| `defaultExpandedRowIds` | `readonly string[]`      | —       | Row ids whose panel starts open. Later toggles own the set. |

Related `DataTable` props:

| Prop     | Type                    | Default | Description                                                              |
| -------- | ----------------------- | ------- | ------------------------------------------------------------------------ |
| `labels` | `TableLabels`           | English | Override `expandRow` / `collapseRow` for the chevron's accessible label. |
| `rowKey` | `(row: TRow) => string` | —       | Already required; expansion state is keyed by this id.                   |

## Notes

- Works with the `virtualize()` feature. A table cannot nest a detail panel inside the row it
  belongs to, so the two are separate elements — the window measures them
  **together**, and an open panel reports its real height instead of its row's.
  A panel that grows later (an image loading, a nested table opening) corrects
  the height as it happens.
- The detail cell spans the full row width, including selection, actions, and
  the expansion column itself.
- Kits with native expand affordances keep their own look; only the labels
  are unified through `labels`.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

---

# React nested tables — master/detail with nestedTable()

▶ **See it working:** [nested tables in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/nested-tables/) — open a person onto their recent orders; the inner table has its own columns and row keys. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

A nested table is a whole `DataTable` inside an expanded row: the kit's own
component, with its own columns, row type, sorting, paging and keyboard
support. It is opt-in — compose `nestedTable(nested)` from
`@adapttable/<kit>/nested-table`. Without it, rows carry no expand control
and nothing renders beneath them.

The factory ships for `@adapttable/mantine`, `mui`, `chakra`, `antd`,
`radix`, `base-ui`, `shadcn` and `unstyled`, and
`@adapttable/<kit>/row-detail` exports the same factory beside `rowDetail`.

## Example

```tsx
import { type ColumnDef, DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { nestedTable } from "@adapttable/mantine/nested-table";

interface Order {
  id: string;
  item: string;
  total: number;
}

interface Customer {
  id: string;
  name: string;
  city: string;
  orders: Order[];
}

const customers: Customer[] = [
  {
    id: "c1",
    name: "Aisha Rahman",
    city: "Cairo",
    orders: [
      { id: "o1", item: "Desk", total: 240 },
      { id: "o2", item: "Lamp", total: 45 },
    ],
  },
  {
    id: "c2",
    name: "Jonas Weber",
    city: "Berlin",
    orders: [{ id: "o3", item: "Chair", total: 90 }],
  },
];

const customerColumns: ColumnDef<Customer>[] = [
  { key: "name", sortable: true },
  { key: "city", sortable: true },
];

const orderColumns: ColumnDef<Order>[] = [
  { key: "item", sortable: true },
  { key: "total", sortable: true },
];

export function Customers() {
  return (
    <DataTable
      data={customers}
      columns={customerColumns}
      rowKey={(row) => row.id}
      features={[
        nestedTable(
          (row: Customer) => ({
            label: `Orders for ${row.name}`,
            table: (defaults) => (
              <DataTable
                {...defaults}
                data={row.orders}
                columns={orderColumns}
                rowKey={(order) => order.id}
              />
            ),
          }),
          ["c1"]
        ),
      ]}
    />
  );
}
```

The first customer opens on the first render; every other row starts
closed. Annotate the callback's row parameter (or call
`nestedTable<Customer>(…)`): the factory cannot infer the parent row type
from the surrounding `features` array.

## How it works

- **`NestedTableFor<TRow>`** is the callback: `(row) => NestedTable |
undefined`. It runs for an expanded row and returns that row's nested
  table, or `undefined` for none.
- **`NestedTable`** is `{ label?, table }`. `table(defaults)` mounts the
  kit's own `DataTable` and returns it. The child rows keep their own type
  — the closure holds it — so `orderColumns` is a `ColumnDef<Order>[]`, not
  something erased to fit the parent.
- **The defaults come first.** Spread `defaults` onto the inner table, then
  pass anything that should differ after it. See
  [the defaults](#the-defaults-nestedtabledefaults).
- **The inner table is independent.** It takes its own `features`,
  `columns`, `rowKey` and data tier. Nothing the parent composes — grouping,
  selection, editing — reaches it unless you pass it again.
- **Expansion is keyed by row id**, so an open row survives sorting and
  paging. Several rows may be open at once. The second argument,
  `defaultExpandedRowIds`, is uncontrolled initial state; after the first
  render the reader's toggles own the set.
- **Every row carries the expand chevron.** A row whose callback returns
  `undefined` opens an empty panel unless `rowDetail` is composed as its
  fallback (below).

## The defaults: `NestedTableDefaults`

`table` receives a `NestedTableDefaults` — the props a table inside a row
needs:

| Field        | Value                                  | Why                                                                                              |
| ------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `urlSync`    | `false`                                | Two tables writing `?page=` to one URL overwrite each other.                                     |
| `searchable` | `false`                                | A second search box inside a row reads as chrome. Pass `searchable` after the spread to keep it. |
| `density`    | the parent's `density` prop            | The child matches the parent.                                                                    |
| `labels`     | the parent's `labels` prop             | The child is localized like the parent.                                                          |
| `tableLabel` | `label`, or `"Row details"` if omitted | The inner table's accessible name — the same string names the region around it.                  |

`"Row details"` is a fixed English fallback, not a translated label. Give
every nested table a `label`, named after the row it belongs to ("Orders
for Aisha Rahman") rather than after the feature — it is what a
screen-reader user hears once focus is inside it.

`nestedTableDefaults(label, parent?)` on `@adapttable/react/adapter`
builds the same object, for a custom adapter or a host rendering its own
detail row. `nestedTableDetail({ nestedTable, renderRowDetail?, parent? })`
on the same entry turns a declaration into the detail renderer the
factories use.

## Rows without a nested table: `rowDetail` fallback

Compose `rowDetail(render)` beside `nestedTable` and each row resolves in
order: the nested table when the callback returns one, otherwise the
`rowDetail` panel, otherwise nothing. Master/detail panels and nested
tables can share one table:

```tsx
import { nestedTable } from "@adapttable/mantine/nested-table";
import { rowDetail } from "@adapttable/mantine/row-detail";

features={[
  nestedTable((row: Customer) =>
    row.orders.length === 0
      ? undefined
      : {
          label: `Orders for ${row.name}`,
          table: (defaults) => (
            <DataTable
              {...defaults}
              data={row.orders}
              columns={orderColumns}
              rowKey={(order) => order.id}
            />
          ),
        }
  ),
  rowDetail((row: Customer) => <p>{row.name} has no orders yet.</p>),
]}
```

Both factories share one expansion state. `defaultExpandedRowIds` may be
passed to either; when both pass one, the later feature in the array wins.
`rowDetail` on its own is covered in [row expansion](./row-expansion.md).

## Keyboard and screen readers

- The chevron is a real button with `aria-expanded` and the
  `expandRow` / `collapseRow` labels ("Expand row" / "Collapse row" by
  default, translated by the `@adapttable/i18n` locales). Enter and Space
  toggle it.
- The nested table renders inside
  `<section data-adapttable-part="nested-table" aria-label={label}>`, and
  the inner table carries the same name through `tableLabel`, so the region
  and the table both announce which row they belong to.
- The inner table keeps its own tab stops, and its own keyboard features —
  `cellNavigation()` included — only when you compose them on it.
- Ant Design maps expansion onto its native `expandable` API with a custom
  expand icon, so the same labels apply there.

## Virtualization

With `virtualize()` composed on the parent, an open row and its panel are
separate elements — a `<tr>` cannot contain the row beneath it — and the
window measures them together, reporting the open panel's real height. A
nested table that grows after it opens corrects the height as it happens.
See [virtualization](./virtualization.md).

## Mobile cards

On a phone the parent renders cards, and each card carries the same
chevron and opens its panel inside the card. The inner table is a
`DataTable` too, so it follows the same responsive switch and renders cards
on a phone. See [mobile cards](./mobile.md).

## URL state and saved views

The inner table never writes the URL (`urlSync: false`), and its sort,
page and filters are local to that mount. Which rows are expanded is not
URL state either: `defaultExpandedRowIds` sets the first render, and the
reader's toggles live in memory. The parent keeps its own URL state and
Saved Views as usual.

## Options

`nestedTable(nested, defaultExpandedRowIds?)`:

| Argument                | Type                   | Default | Description                                                   |
| ----------------------- | ---------------------- | ------- | ------------------------------------------------------------- |
| `nested`                | `NestedTableFor<TRow>` | —       | `(row) => NestedTable \| undefined` — the row's nested table. |
| `defaultExpandedRowIds` | `readonly string[]`    | —       | Row ids that start open. Later toggles own the set.           |

`NestedTable`:

| Field   | Type                                           | Default         | Description                                                    |
| ------- | ---------------------------------------------- | --------------- | -------------------------------------------------------------- |
| `label` | `string`                                       | `"Row details"` | Accessible name for the nested table and its region.           |
| `table` | `(defaults: NestedTableDefaults) => ReactNode` | —               | Mount the kit's `DataTable` with `{...defaults}` spread first. |

The types `NestedTable`, `NestedTableDefaults` and `NestedTableFor` are
exported from `@adapttable/react` and `@adapttable/react/features`.

Related: [tree data](./tree-data.md) for one row type in a hierarchy ·
[row expansion](./row-expansion.md) for a free-form panel ·
[feature composition](./features.md)

---

# React table inline cell editing — edit rows in place, validate & commit

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — this page's feature is already wired in `src/App.tsx` (`editable` columns + `editing()` + `editHistory()` for undo and redo); edit it in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [edit cells in the live demo](https://adapttable.orwamahmoud.com/react/demo/mantine/editing/) — a real table you can type into, not a recording.

Edit a cell in place by composing `editing` from `@adapttable/<kit>/editing`
and marking columns `editable`. Omit the factory and the table never opens an
editor — even if columns declare `editable`. The table never mutates rows; your
handler applies the change. See [feature composition](./features.md).

## Example

```tsx
import { useState } from "react";
import { DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { editing } from "@adapttable/mantine/editing";

interface Person {
  id: string;
  name: string;
  role: string;
  status: "Active" | "Planned" | "Blocked";
}

const SEED: Person[] = [
  { id: "1", name: "Aisha", role: "Engineer", status: "Active" },
  { id: "2", name: "Jonas", role: "Designer", status: "Planned" },
];

export function People() {
  const [rows, setRows] = useState(SEED);
  return (
    <DataTable
      data={rows}
      columns={[
        { key: "name", sortable: true, editable: true },
        {
          key: "status",
          editable: true,
          editor: {
            type: "select",
            options: ["Active", "Planned", "Blocked"],
          },
        },
        { key: "role", editable: (row) => row.status !== "Blocked" },
      ]}
      rowKey={(r) => r.id}
      features={[
        editing((row, key, nextValue) => {
          setRows((prev) =>
            prev.map((r) =>
              r.id === row.id ? { ...r, [key]: nextValue as never } : r
            )
          );
        }),
      ]}
    />
  );
}
```

## How it works

- **Opt-in.** `editing()` is the switch. Without it, cells stay plain display
  (package DNA: nothing is pushed on the developer).
- **Per-column.** `editable` is `true`, `false`, or `(row) => boolean`. The
  editor defaults to `"text"`; use `"number"` or
  `{ type: "select", options }` for the other kits.
- **Keyboard.** Double-click / Enter / F2 begins; Enter commits; Escape
  cancels and restores focus; Tab / Shift+Tab commits and advances to the
  next editable cell.
- **One-way data flow.** The commit payload is
  `(row, key, nextValue)` on the handler you pass to `editing()` — adapters
  render kit-native inputs; core owns the state machine so every kit behaves
  the same.
- **Beyond one cell.** Row-level edit mode (`rowEditing(onRowEdit)`) opens
  every field together and commits one patch; `validate` / `validateRow` reject
  a commit and mark the cells that failed; `onEditRollback` restores a row after
  a rejected save, and `dirtyIndicators()` marks what nobody has confirmed yet.
- **The table never writes to a row.** Persistence stays with the host: every
  commit reaches your handler, and the stored data changes only when you change
  it.

## Options

| Prop / field  | Type                                                    | Default  | Description                                                                                              |
| ------------- | ------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `editing(fn)` | `(row: TRow, key: string, nextValue: unknown) => void`  | —        | First argument to `editing()`; its presence enables editing.                                             |
| `editable`    | `boolean \| ((row: TRow) => boolean)`                   | —        | Whether this column can open an editor (still requires `editing()`).                                     |
| `editor`      | `CellEditor` — see [the editor set](#the-editor-set)    | `"text"` | Widget for the active cell: text, number, boolean, date, datetime, time, select, multi-select or custom. |
| `editValue`   | `(row: TRow) => string`                                 | —        | Draft seed when the displayed cell is formatted but editing needs the raw.                               |
| `parseValue`  | `(draft: string, row: TRow) => unknown`                 | —        | Turns the edited text into the value committed to your edit handler.                                     |
| `labels`      | `TableLabels`                                           | English  | Override `editCell` for the activate control's accessible name.                                          |
| `validate`    | `(value, row) => string \| undefined \| Promise<…>`     | —        | Column rule: return a message to reject the commit (see below).                                          |
| `validateRow` | `(row) => string \| Record<string,string> \| undefined` | —        | Table rule over the row the edit would produce (cross-field).                                            |
| `applyEdit`   | `(row, columnKey, value) => TRow`                       | spread   | How an edit lands on a row for `validateRow` to judge.                                                   |

### Lifecycle events

`onEditStart`, `onEditCancel`, `onEditCommit`, `onValidationFail` and
`onEditError` observe what the editor does. They cannot change it: a throw is
swallowed, a return value is ignored. The same events fire for a cell, a row
and a batch, and on a mobile card — the commit unit does not change with the
layout.

```tsx
<DataTable
  {...props}
  features={[
    editing(save, {
      onEditStart: (e) => analytics.track("edit_start", e.columnKey),
      onEditCommit: (e) => analytics.track("edit_commit", e.value),
      onEditCancel: (e) => analytics.track("edit_cancel", e.columnKey),
      onValidationFail: (e) => toast.error(e.error),
      onEditError: (e) => toast.error(e.error),
    }),
  ]}
/>
```

The payload is `EditEvent<TRow>`: `row`, `rowId`, `columnKey` (empty for a row
or batch), `value`, `previousValue`, `unit` (`"cell"` / `"row"` / `"batch"`)
and optional `error`. For `onEditError`, `value` is the attempted save and
`previousValue` is the cell's previous value. Omit every handler and nothing
is called.

### Live-update conflicts

A refetch, a websocket, another user — the row under an open editor can change.
(Live row updates that are not an open-editor fight are
[realtime](./realtime.md).)
The table does not merge. It can keep what you typed, take the incoming value,
or ask. Silently discarding a draft is the one outcome nobody forgives, so the
default is to ask.

```tsx
<DataTable
  {...props}
  features={[
    editing(save, {
      editConflictPolicy: "ask",
      rowVersion: (row) => row.updatedAt,
      onEditConflict: (conflict) => {
        analytics.track("edit_conflict", conflict.columnKey);
      },
    }),
  ]}
/>
```

`onEditConflict` may return `"keep"` or `"take"` to resolve it; returning
nothing uses the policy. `"ask"` puts Keep mine / Take theirs on the editor
(`data-conflict`, the same `aria-describedby` channel as a validation message)
and shows the incoming value (`labels.theirsValue`) so the reader can see
what they would take.
Without `rowVersion`, only the edited column's stored value counts as a change.

### The editor set

| `editor`                            | Control                | Commits                         |
| ----------------------------------- | ---------------------- | ------------------------------- |
| `"text"` (default)                  | text input             | the string                      |
| `"number"`                          | number input           | `number \| null` (empty → null) |
| `"boolean"`                         | checkbox               | `true` / `false`                |
| `"date"`                            | date input             | `"YYYY-MM-DD"`                  |
| `"datetime"`                        | datetime input         | `"YYYY-MM-DDTHH:mm"`            |
| `"time"`                            | time input             | `"HH:mm"`                       |
| `{ type: "select", options }`       | the kit's select       | the chosen value                |
| `{ type: "multi-select", options }` | the kit's multi-select | the chosen values, an array     |

The date, time and checkbox editors use the platform's own controls: they are
keyboard-complete and localized by the browser, which is a better answer than
nine hand-built pickers.

**Dates commit strings, not `Date` objects.** `"2026-08-13"` is a day; a `Date`
is an instant in a timezone the reader never chose, and converting to one moves
the day for most of the world. A column storing a `Date` still seeds its editor
correctly — the local parts are read off it — and `parseValue` turns the committed
string back into whatever you store.

**A boolean commits on the tick.** A checkbox has one gesture, so waiting for
Enter would leave a ticked box that changed nothing.

**A multi-select seeds itself from a stored array** and commits an array back, so
a host stores exactly what it gave — no separator to parse, no single-value
special case. An empty selection commits `[]`, not `""`.

Each kit picks several values the way that kit picks several values: Ant Design
and Mantine open their own multi-select, MUI and Chakra render a multiple list
box, and Radix Themes and Base UI — whose select holds one value by
construction — show a group of their own checkboxes. That group is
`MultiSelectEditorChrome`, core's structure with a `Checkbox` slot, so all three
kits share one accessible group and none of them ships hand-written markup.

### Bring your own editor

An autocomplete, a rich-text field, a colour picker — anything that is not one
of the eight. The table keeps everything it already owned; the component owns
only what the reader looks at:

```tsx
{
  key: "colour",
  editable: true,
  editor: {
    type: "custom",
    render: (ctrl) => (
      <SwatchPicker
        value={ctrl.draft}
        onKeyDown={ctrl.onKeyDown}
        firstSwatchRef={ctrl.focusRef}
        onPick={(swatch) => {
          ctrl.setDraft(swatch);
          ctrl.commit();
        }}
      />
    ),
  },
}
```

Double-click / Enter / F2 still activates the cell, focus still returns to it
afterwards, Enter still commits, Escape still cancels, Tab still moves on, and
validators still gate the commit — none of that is yours to write again. What
arrives is `draft` and the calls that change it: `setDraft`, `commit` (for a
picker, where choosing IS the gesture), `cancel`, `onKeyDown` (wire it to keep
the keyboard flow; an editor that owns Enter simply does not call it for Enter),
`onBlur`, and `focusRef` to point at what should take focus. `error`,
`validating` and `errorId` are there so a component can mark itself invalid —
the table renders the message either way. `label` is the accessible name for
the control, and `conflict` is set while a live-update conflict is open on the
cell.

The draft is a string, as it is for every editor; `parseValue` is still how a
column turns it into whatever gets stored.

### Display, draft, and committed value

Three moments in a cell's life, and a formatted column needs a different value
at each:

| Moment    | Field        | For a currency column |
| --------- | ------------ | --------------------- |
| Displayed | `accessor`   | `"$1,240.00"`         |
| Edited    | `editValue`  | `"1240"`              |
| Committed | `parseValue` | `1240`                |

```tsx
{
  key: "budget",
  editable: true,
  editor: "number",
  accessor: (row) => money.format(row.budget),
  editValue: (row) => String(row.budget),
  parseValue: (draft) => Number(draft.replace(/[^0-9.-]/g, "")),
}
```

`parseValue` receives the draft exactly as typed plus the row, and replaces the
editor's own parsing rather than running after it — so a column that says how
to read its drafts is in full control. Return anything your edit handler should
receive, including a value no built-in editor produces, such as a `Date`.

Without it nothing changes: a `number` editor commits `number | null` and every
other editor commits the raw string.

## Validation

A validator gates the commit and nothing else. It never rejects a keystroke,
never rewrites a value, and never decides what to save — the host still owns
persistence, and will usually validate again on the server.

Two levels, because they answer different questions. A **column** rule knows one
value:

```tsx
const columns: ColumnDef<Task>[] = [
  {
    key: "title",
    editable: true,
    validate: (value) =>
      String(value).trim() === "" ? "A title is required" : undefined,
  },
];
```

A **table** rule sees the row the edit would produce, and answers what no single
cell can:

```tsx
<DataTable
  {...props}
  features={[
    editing(apply, {
      validateRow: (task) =>
        task.end <= task.start
          ? "The end must come after the start"
          : undefined,
    }),
  ]}
/>
```

Return a string for a row-level problem, or a map of column key → message to
mark individual cells — which is how a cross-field rule points at the field the
reader should look at. Return nothing to allow the commit. When a column key is
not the field (a nested path), pass `applyEdit` so the rule sees the right row.

**A rejected value never reaches your edit handler.** The editor stays open holding
what the reader typed, and the message is announced rather than only painted.
Where it renders depends on the kit: Mantine and MUI put it in their own input's
error slot (their components own the field's `aria-describedby`), and every other
kit renders `data-adapttable-part="edit-cell-error"` with `role="alert"`, the
editor carrying `aria-invalid` and `aria-describedby` pointing at it. Either way
the message exists once in the DOM and is read with the field. Escape clears it
with the draft.

Both levels may be async — "is this SKU real" is a request. The editor stays open
and carries `aria-busy` while the check runs, and a newer draft supersedes an
older check, so a stale answer can never mark a value the reader has already
changed. A column with no validator commits synchronously, exactly as before.

## Saving, and what happens when it fails

Return a promise from your `editing()` handler and the table knows something the reader
cannot see: the value is on its way somewhere. The cell says so until the promise
settles — `data-save="saving"` and `aria-busy` on the cell — and says why if it
rejects, in a live region beside it (`data-adapttable-part="edit-cell-save-error"`,
`role="alert"`).

```tsx
<DataTable
  {...props}
  features={[
    editing(
      async (row, key, value) => {
        setRows(applyOptimistically(row, key, value));
        await api.save(row.id, { [key]: value });
      },
      {
        onEditRollback: (previous, columnKey) => {
          setRows((current) => restore(current, previous));
        },
        formatEditError: (error) => humanize(error),
      }
    ),
  ]}
/>
```

A table that shows the new value before the server has agreed has to put the old
one back when it disagrees — and only the host can write to its own rows, so
`onEditRollback` receives the row as it was and restores it. The failed cell then
offers an **Undo** (`labels.undoEdit`, localized in every bundled locale), and
pressing it calls that handler. Omit `onEditRollback` and the message shows
without an undo, which is right for a table that refetches instead.

A newer save supersedes an older one, so a slow rejection can never mark a value
the reader has already replaced. A host that saves synchronously pays nothing:
with nothing to wait for, there is no saving state to render.

Headless: `useCellSaveState` (`CellSaveState`, `CellSaveStatus`,
`FailedCellSave`, `UseCellSaveStateOptions`); the controller carries
`saveStatus`, `saveFailure`, `canRollback`, `rollback` and `dismissFailure`.

## Editing a whole row at once

Cell editing commits each field as the reader leaves it, which is right for a
spreadsheet and wrong for a form. A row whose fields constrain each other cannot
be edited one cell at a time without passing through states that are invalid on
the way — a start date after the end date it is about to replace. Row mode holds
every field's draft until the reader saves, then hands you one patch:

```tsx
import { rowEditing } from "@adapttable/mantine/editing";

<DataTable
  {...props}
  features={[
    rowEditing((row, patch) => {
      // patch === { title: "Ship it", points: 8 } — only what changed
      setRows((current) => applyPatch(current, row.id, patch));
    }),
  ]}
/>;
```

Each row grows an **Edit** control; opening one turns every editable column of
that row into its editor at once, seeded from the row. **Save** hands over one
patch of only the fields that actually changed — an untouched row reports
nothing at all — and **Cancel** throws the drafts away. Enter and Escape do the
same from any field, because in row mode the unit is the row.

Only one row is open at a time: opening another closes the first. The same
editors, the same `parseValue`, the same column-level `editable` predicate. The
mobile card behaves identically — the fields open in the card and the three
controls sit in its action area.

Both are one factory: `rowEditing(onRowEdit)` arms the mode and wires the patch
channel. `editing()` is not required — a table that only wants row-level commits
leaves it out, and its cells stay display-only until a row is opened.

### Opening the row from your own pencil

A table that already has a pencil in its actions column does not want a second
control beside it saying the same thing. Mark that action `editsRow` and it
becomes the way in — the built-in **Edit** control stands down, and save and
cancel still come from the open row:

```tsx
import { DataTable } from "@adapttable/mantine";
import { rowEditing } from "@adapttable/mantine/editing";
import { rowActions } from "@adapttable/mantine/row-actions";

const actions = [
  { key: "edit", label: "Edit", icon: <PencilIcon />, editsRow: true },
  { key: "delete", label: "Delete", onClick: remove },
];

<DataTable {...props} features={[rowActions(actions), rowEditing(save)]} />;
```

Such an action writes nothing itself, so it carries no `onClick`, and it renders
only where there is a form to open: a table without `rowEditing` drops it rather
than showing a control that cannot do what it says. While its own row is open it
steps aside, because that row is already showing save and cancel.

### An incoming row while a form is open

A row form is measured against the row it opened on, so a change arriving
underneath is the same question a cell already asks — asked of every field that
moved, and of no others. Each marks itself, shows the value that arrived, and
offers **Keep mine** / **Take theirs**, exactly as a cell does; answering on any
of them answers for the row, because the row moved as a whole. The form offers
nothing to save until it is answered.

Fields the reader never touched are not a problem to solve: a save sends a patch
of what the reader changed, so a value they left alone is never written back
over the one that arrived.

A batch asks the same way. Every cell is a field there, so an untouched one
already reads the row itself; a cell the reader changed marks itself and is
answered on its own, and **Save all** waits until nothing is outstanding.

`editConflictPolicy` and `onEditConflict` decide it without asking, exactly as
they do for a cell.

Parts: the cell's own `edit-cell-conflict`, `edit-cell-conflict-message`,
`edit-cell-incoming`, `edit-cell-keep-mine`, `edit-cell-take-theirs`, plus
`batch-edit-conflict` where the batch bar says why it is not saving yet.
Labels: `labels.editConflict`, `labels.keepMine`, `labels.takeTheirs`,
`labels.theirsValue`.

### The controls are glyphs

Each kit draws its own pencil, check and cross, with `labels.editRow`,
`labels.saveRow` and `labels.cancel` as both the accessible name and the hover
title — an actions column is a narrow place, and three words per control crowd
out the row. `rowEditIcons` changes that per control: a node is your own glyph,
`false` asks for the label as text.

```tsx
import { DataTable } from "@adapttable/mantine";
import { rowEditing } from "@adapttable/mantine/editing";

<DataTable
  {...props}
  features={[
    rowEditing(save, { rowEditIcons: { save: <TickIcon />, cancel: false } }),
  ]}
/>;
```

Parts: `row-edit-begin`, `row-edit-actions`, `row-edit-save`, `row-edit-cancel`.
Labels: `labels.editRow`, `labels.saveRow`, `labels.cancel`, all localized in
every locale.

Headless: `useRowEditing` (`RowEditingState`, `RowEditDrafts`,
`UseRowEditingOptions`), with `RowEditCell` (`RowEditCellProps`),
`rowEditControls` (`RowEditControlsOptions` in, `RowEditControls` out)
from `@adapttable/react/adapter`, `RowEditIcons` typing the glyph overrides,
and `rowEditConflict` (`RowEditConflict` out) telling one row's controls that
an answer is outstanding. `useEditConflict` returns `reconcileRow`
(`ReconcileLiveRowEdit` in) and `isRowConflict` for the row unit, and
`reconcileBatch` (`ReconcileLiveBatchEdit` in) for a batch;
`CellConflictAsk` is what one field's notice needs, and `EditConflictChange`
names each field that moved. Each adapter mounts `RowEditActions`
(`RowEditActionsProps`) over `RowEditActionsChrome`, and resolves one row's
actions against its edit state with `resolveRowEditTrigger` (`RowEditTrigger`
out) — which rewires an `editsRow` action to the form and reports whether the
built-in control still draws itself.

## Changing many rows, saving once

A review pass — walking a list correcting values — wants one write at the end,
not one per row. Compose `batchEditing()` and every editable cell becomes a field and holds
every change until the reader saves them all:

```tsx
import { batchEditing } from "@adapttable/mantine/editing";

<DataTable
  {...props}
  features={[
    batchEditing((edits) => {
      // edits === [{ row, rowId, patch }, …] — every pending row, once
      return api.saveAll(
        edits.map((edit) => ({ id: edit.rowId, ...edit.patch }))
      );
    }),
  ]}
/>;
```

The `batchEditing` handler is called **once** per save, which is what lets the
whole batch be one request — and makes it atomic if your endpoint treats it that way. A bar
appears as soon as something is pending, with the count, Save all and Cancel all;
it is a live region, so the count is heard as well as seen. Cancel restores
everything at once, because nothing was ever applied.

The count is **rows**, not cells: three changes across two rows read "2 unsaved
rows". A value typed back to what it was stops counting. Changed cells carry
`data-changed`, so the reader can find their way back to what they touched.

Labels: `pendingRows(count)`, `saveAll`, `cancelAll` — localized in every locale.
Parts: `batch-edit-cell`, `batch-edit-bar`, `batch-edit-count`,
`batch-edit-save`, `batch-edit-cancel`.

`batchEditing` is also its own entry, `@adapttable/<kit>/batch-editing`, for a
table that wants only the batch mode.

Headless: `useBatchEditing` (`BatchEditingState`, `BatchRowEdit`,
`UseBatchEditingOptions`), with `BatchEditCell` on
`@adapttable/react/adapter`. Each adapter mounts `BatchEditBar` over
`BatchEditBarChrome`.

## Adding, duplicating and deleting rows

Editing a value is one thing; changing which rows exist is another. Pass the
handlers as the second argument of `rowActions`, and each one puts its own
control on screen:

```tsx
import { rowActions } from "@adapttable/mantine/row-actions";

<DataTable
  {...props}
  features={[
    rowActions(undefined, {
      onAddRow: () => setRows((rows) => [blankTask(), ...rows]),
      onDuplicateRow: (row) =>
        setRows((rows) => [{ ...row, id: nextId() }, ...rows]),
      onDeleteRow: (row) =>
        setRows((rows) => rows.filter((r) => r.id !== row.id)),
    }),
  ]}
/>;
```

`onAddRow` puts an **Add row** button in the toolbar. `onDuplicateRow` and
`onDeleteRow` put icon-only **Duplicate row** and **Delete row** on every row
(the labels are the tooltip and accessible name), after your own row actions —
the first argument of `rowActions` — so a delete stays last, where a
destructive action belongs. They ride the actions column like any other row
action: hideable and end-pinnable from the Columns menu, buttons on desktop and
card buttons on mobile. The [row actions](./row-actions.md) page covers the
column itself.

**A delete asks first.** It goes through the same confirmation dialog a
`rowActions` entry with a `confirm` block uses — `labels.deleteRow` as the title,
`labels.deleteRowConfirm` as the question, both translated in every bundled
locale. Pass `confirmDeleteRow: false` when your own UI already asked, or when
your delete is reversible.

**The table asks; you do the rest.** It holds no draft and stores no row. A row
you add arrives through the source like every other row, which is what keeps it
ordinary — editable, filterable, sortable, counted, grouped and virtualized from
the moment it lands, with nothing about it special. It also means what a copy
_means_ is yours: which fields carry over, which reset, what id it gets.

For an in-memory table, [`insertRow`, `removeRow` and `applyRowPatches`](./api.md)
do the list work.

Nothing here needs `editing()`. Pair them and a reader adds a blank row and
fills it in place; leave editing off and Add is simply a button that runs your
handler.

Headless: `useRowMutations` (`RowMutationHandlers`, `RowMutationsState`) builds
the same state a kit renders, and `chrome.rowMutations` carries it — `canAdd`
plus `addRow`, with the duplicate and delete actions already folded into
`chrome.rowActions`.

## Reordering rows

Changing which row sits where is the same one-way write: compose `rowReorder`
and a grip appears. See [row reordering](./row-reordering.md).
Compose `rowPinning()` and pin actions appear. See
[row pinning](./row-pinning.md).

## Dirty marks

A table that looks identical before and after a save leaves the reader no way to
tell what is still at risk. Compose `dirtyIndicators()` and a changed cell carries
`data-dirty` until its value settles — and so does its row, so a long table can
be scanned without hunting for the cell inside it.

```tsx
import { dirtyIndicators, editing } from "@adapttable/mantine/editing";

<DataTable {...props} features={[editing(save), dirtyIndicators()]} />;
```

A mark clears when the save **resolves**, and stays when it fails: the value is
still at risk until the reader undoes it or tries again. A rollback clears it too,
since the value it belonged to is gone. Nothing clears on a timer — a mark that
fades on its own says the change is safe when nobody checked.

Off by default, because a mark is a claim about what the server has agreed to and
a table whose host never says would be guessing. For a table that confirms its
own state another way — a refetch that agrees, a websocket echoing the value back
— `editing(commit, { onDirtyChange })` tracks unsaved edits on its own and hands
them over on mount and whenever one moves: `{ count, confirm, confirmRow,
confirmAll }`, a `count` for an "unsaved changes" line and the functions that
settle them. It draws no marks; add `dirtyIndicators()` for those, and both read
the same set.

```tsx
const [dirty, setDirty] = useState<DirtyEdits>();

<DataTable
  {...props}
  features={[editing(save, { onDirtyChange: setDirty })]}
/>;
// dirty?.count — "3 unsaved changes"; dirty?.confirmAll() after a refetch
```

Headless: `useDirtyCells` (`DirtyCellState`, `UseDirtyCellsOptions`) and
`rowIsDirty(editing, rowId)` from `@adapttable/react/adapter`.

## Headless editing

The editing engine is exported for custom adapters and fully custom tables.
`useCellEditing` is the state machine (one active cell, a draft string, and
the Enter / Escape / Tab keyboard flow); `EditableCellGate` is the reusable
activation wrapper every built-in adapter renders (double-click / Enter / F2
to begin, with the cell value as the accessible name and the edit hint as
its `title`).

`useCellEditing`, `EditableCellGate` and the `MultiSelectEditor*` exports come
from `@adapttable/react`; `isCellEditable`, `hasEditableColumns`,
`parseCellEditValue`, `resolveCellEditor` and `resolveCommitValue` from
`@adapttable/core`; `editorValidationProps` from `@adapttable/react/adapter`.

| Export                                                                                                                   | Purpose                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `useCellEditing` / `CellEditingState`                                                                                    | The state machine hook and the state it returns.                                                          |
| `EditableCellGate` / `EditableCellGateProps`                                                                             | Activation wrapper: display content when idle, the kit's editor while active.                             |
| `EditableCellEditing`                                                                                                    | The editing bundle adapters receive from the chrome (`chrome.editing`).                                   |
| `CellEditCommit` / `CellEditTarget`                                                                                      | A commit payload (`row`, `key`, `value`) and the active-cell address.                                     |
| `CellEditor` / `CellEditorOption`                                                                                        | The column `editor` descriptor and one option of a select editor.                                         |
| `CellEditKeyAction` / `CellEditKeyOutcome` / `CellEditNavigation`                                                        | Keyboard-flow vocabulary: what a key press means and where focus goes next.                               |
| `EditableCellController` / `EditableCellEditorCtrl` / `EditableCellMode`                                                 | The controller handed to a custom editor: draft, commit/cancel, mode.                                     |
| `MultiSelectEditorChrome` / `MultiSelectEditorChromeProps` / `MultiSelectEditorSlots` / `MultiSelectEditorCheckboxProps` | Checkbox-group multi-select editor for kits whose select holds one value.                                 |
| `EditableColumnLike` / `isCellEditable` / `hasEditableColumns`                                                           | The minimal column shape editing reads, plus the two predicates the chrome uses.                          |
| `parseCellEditValue` / `resolveCellEditor` / `normalizeEditorOptions`                                                    | Draft parsing (number editors yield `number \| null`) and editor/option resolution.                       |
| `EditValidationState` / `ValidationCheckResult`                                                                          | Validation state: which cells carry a message, which are still checking, and what a check returned.       |
| `CellValidator` / `RowValidator` / `ValidationTarget`                                                                    | The two validator signatures and the cell address a check is about.                                       |
| `resolveCommitValue`                                                                                                     | The row, column and parsed value a commit resolves to — what a validator judges before the host sees it.  |
| `editorValidationProps`                                                                                                  | The `aria-invalid` / `aria-describedby` / `aria-busy` a kit's editor spreads while validation is in play. |

## Applying changes without a refetch

A commit hands you a change; what you do with your data is yours. Refetching
the page to reflect it costs a round trip and throws away the user's scroll
position, open rows, and sometimes their selection.

`applyRowPatches` applies changes to the rows you already hold. The same
helper is how a [realtime feed](./realtime.md) lands:

```tsx
import { applyRowPatches, updateRow, removeRow } from "@adapttable/core";
import { editing } from "@adapttable/mantine/editing";

const [rows, setRows] = useState(initial);
const byId = (row: Person) => row.id;

<DataTable
  data={rows}
  columns={columns}
  rowKey={byId}
  features={[
    editing((row, key, value) =>
      setRows((current) =>
        applyRowPatches(current, [updateRow(byId(row), { [key]: value })], byId)
      )
    ),
  ]}
/>;
```

Four builders — `insertRow`, `updateRow`, `upsertRow`, `removeRow` — and a
batch is just an array, applied in order, so a later patch acts on what an
earlier one did.

Two guarantees make it safe to call on every commit:

- **Untouched rows keep their object identity.** React reconciles them as
  unchanged, and per-row memos — a [computed column](./columns.md)'s cache, a
  `memo`'d cell — stay valid instead of recomputing for the whole page.
- **A patch that changes nothing returns the very same array.** An update whose
  values already match, an upsert of the row already in place, a removal of an
  id that is not there, or an empty batch hands back the original reference, so
  the `setState` does not re-render.

Selection and expansion survive for the same reason: both are keyed by row id,
and a patch never changes the id of a row it did not touch.

`applyRowPatches` is a pure function over an array — the table does not own
your data and this does not make it start.

The patch shapes are exported for code that builds them dynamically:
`RowPatch` is the union, with `InsertPatch`, `UpdatePatch`, `UpsertPatch` and
`RemovePatch` as its members.

## Notes

- Works on desktop rows and mobile cards, LTR and RTL.
- Custom `Cell` / `accessor` still render in display mode; the editor replaces
  them only while that cell is active.
- Prefer updating your row list immutably in your `editing()` handler so React
  sees a new `data` / source identity.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/) —
double-click an editable cell (Person, Email, or Team) in the editing
section.

## Undo and redo

Compose `editHistory` from `@adapttable/<kit>/editing` and edits can be taken back:

```tsx
import { DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { editHistory, editing } from "@adapttable/mantine/editing";

<DataTable
  data={rows}
  rowKey={(row) => row.id}
  features={[cellNavigation(), editHistory(), editing(commit)]}
  columns={[{ key: "budget", header: "Budget", editable: true }]}
/>;
```

**Ctrl/Cmd+Z** undoes, **Ctrl/Cmd+Shift+Z** and **Ctrl+Y** redo. Both announce
what moved — `labels.editUndone`, `labels.editRedone`, or
`labels.editNothingToUndo` when the history is empty.

An undo does not rewrite your data, because the table never owned it. It
**commits the previous value back through your `editing()` handler**, the same
call the original edit made — so validation, a mutation, an optimistic update, a
toast, whatever you wrapped around editing, all run on the way back exactly as
they ran on the way out.

**One gesture is one entry.** A paste of two hundred cells undoes in a single
press, as does a fill; an inline edit is a gesture of one. Fifty gestures are
kept by default — pass `{ depth: 200 }` to keep more.

The keys live on the grid, so they need `cellNavigation()`. For visible
controls, compose `undoRedoButtons()` beside `editHistory()`: Undo and Redo sit
in the toolbar and disable when there is nothing to take back. Without
`editHistory()` they do not render. See
[toolbar and view controls](./toolbar-and-view-controls.md).

```tsx
import { DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import {
  editHistory,
  editing,
  undoRedoButtons,
} from "@adapttable/mantine/editing";

<DataTable
  {...props}
  features={[
    cellNavigation(),
    editHistory(),
    undoRedoButtons(),
    editing(commit),
  ]}
/>;
```

For your own buttons, `editHistory({ onChange })` hands over the history on
mount and whenever `canUndo` or `canRedo` changes — `undo()`, `redo()`,
`canUndo`, `canRedo` and `clear()`:

```tsx
const [history, setHistory] = useState<EditHistoryHandle>();

<button disabled={!history?.canUndo} onClick={() => history?.undo()}>
  Undo
</button>
<DataTable
  {...props}
  features={[editHistory({ onChange: setHistory }), editing(commit)]}
/>;
```

The functions are stable and always act on the table's current history. Call
`clear()` when you replace the data underneath, since a history of rows that no
longer exist can only put back values nobody wants.

---

# React table row reordering — flat, grouped and tree rows

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — compose `rowReorder` and a grip appears. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [reorder flat, grouped and tree rows in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/row-reordering/) — Space lifts a row, arrows move it, Space drops it. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

Import `rowReorder` from `@adapttable/<kit>/row-reorder` and a drag handle
appears in a reserved leading column. The import is the switch: a table that
does not compose it never downloads the drag state machine, its keyboard
handling or its announcements — see [feature composition](./features.md).
The table never mutates your array; you apply the move.

```tsx
import { DataTable } from "@adapttable/mantine";
import { applyRowReorder } from "@adapttable/react";
import { rowReorder } from "@adapttable/mantine/row-reorder";
import { useState } from "react";

function Tasks({ seed }: { seed: Task[] }) {
  const [rows, setRows] = useState(seed);
  return (
    <DataTable
      data={rows}
      columns={columns}
      rowKey={(row) => row.id}
      features={[
        rowReorder((from, to) => {
          setRows((current) => applyRowReorder(current, from, to));
        }),
      ]}
    />
  );
}
```

`from` and `to` are **dataset-relative**: the row's index in the current source
plus the page offset, so a virtual window or a paged slice does not lie about
where the row sits. The third argument is the row that moved, so a host that
keys by identity never has to look it up.

`applyRowReorder(rows, from, to)` is the in-memory helper — a copy, never a
mutate. Out of range is a no-op copy.

## Keyboard first

A drag-only reorder is unusable with a keyboard and fails accessibility
review. The grip is a real button:

- **Space** lifts the row (announced: "Row 3 lifted")
- **Arrow Up / Down** (and Left / Right, following `dir`) move the drop target
- **Space** again drops it (announced: "Row moved from 3 to 5")
- **Escape** cancels

`RowReorderAnnouncer` is the live region. It mounts only when reorder is
armed, so a table that does not compose `rowReorder` adds no second status
region (export already owns one).

## Mobile

Cards get **up / down** buttons (`RowReorderButtons`), not a drag handle. The
ends disable rather than wrapping. Grouped and tree cards also get the same
**Move to group…** / **Move under…** menu as desktop, with 44px targets.

## Grouped rows: reorder versus move

The first handler still means **reorder among siblings**. Its `from` and `to`
are positions inside that group, not positions in the flattened list.
Crossing a group boundary is a different write:

```tsx
rowReorder((from, to, row) => reorderInsideGroup(row, from, to), {
  movePolicy: "confirm",
  onGroupMove: (row, fromGroup, toGroup, position) => {
    // toGroup.levels contains each grouping column and its raw value.
    moveRowIntoGroup(row, toGroup.levels, position);
  },
});
```

Dragging over another group's row or choosing **Move to group…** calls
`onGroupMove`. The menu lists loaded leaf groups. A nested `RowGroupRef`
contains a stable `id`, a breadcrumb `label`, and raw `{ key, value, label }`
levels, so the host can write the actual grouping fields.

## Tree rows: reorder versus re-parent

Before/after another sibling calls the ordinary reorder handler with sibling
positions. Dropping into the middle of another node, or choosing **Move
under…**, calls:

```tsx
rowReorder(reorderAmongSiblings, {
  movePolicy: "confirm",
  onTreeMove: (row, fromParent, toParent, position) => {
    updateParentAndOrder(row, toParent.id, position);
  },
});
```

`toParent.id` is `null` for the top level. A row cannot move under itself or
one of its descendants: the cycle guard rejects pointer, keyboard, and menu
paths before any host callback runs and announces the reason.

## Move policy

- `"never"` (default) keeps same-group/same-parent reorder available and
  rejects boundary changes with an announcement.
- `"confirm"` opens the kit-native confirmation in the move menu. Confirm and
  cancel return focus to the trigger. Supply `confirmMove(request)` to use a
  host-owned async confirmation surface instead.
- `"auto"` calls the matching move callback immediately.

Every pointer action has a keyboard/touch equivalent. Space + arrows can cross
the visible boundary; the destination menu reaches loaded groups and parents
directly.

When sorting is active, visual order belongs to the sort. Same-scope
order-only writes are rejected with “Clear sorting before changing row order.”
Cross-group moves and re-parenting remain available because they change row
membership; the active sort remains in force.

**URL / Saved Views.** Row order is the host's array. There is nothing to
serialize. Drag, keyboard, mobile and menu paths call the same host callbacks,
so host persistence receives one identical write contract.

## Column menu

The reorder column uses the reserved key `REORDER_COLUMN_KEY` (`"reorder"`),
the same trick as the actions column. Hide it or pin it to the start from the
Columns menu. CSV export drops it the way it drops actions
(`exportableColumns`).

## Headless

`RowReorderOptions`, `RowMovePolicy`, `RowMoveRequest`, `RowDropPosition`,
`RowGroupMoveHandler`, `RowTreeMoveHandler`, `RowTreeParentRef`,
`RowGroupRef`, `treeMoveCreatesCycle` and `rowDropPosition` are the nested
contracts. `RowReorderDecision` is the internal-seam result used to distinguish
an order write, a membership move, or a rejection. `useRowReorder(options)`
is the grab state: it returns `TableRowReorderState` from `@adapttable/react`,
the same shape adapters receive as `RowReorderState` from
`@adapttable/react/adapter`; `RowReorderHandler` is the ordinal write.
`datasetIndex(localIndex, windowStart)` turns a flat rendered slot into a
dataset index. `rowReorderSignature(reorder, rowId, localIndex)` is the memo
digest so a virtualized row repaints when lifted, targeted, or confirming.
`hostConfirmPending` is true while a host-owned `confirmMove` promise is
unresolved — adapters disable grips, buttons and menu items then, and a
second move is ignored until that promise settles.

Each adapter mounts `RowReorderHandle` (`RowReorderHandleProps`) and
`RowReorderButtons` (`RowReorderButtonsProps`) over
`RowReorderHandleChrome` / `RowReorderButtonsChrome`.
`RowReorderAnnouncer` stays on `@adapttable/react/adapter`.
`REORDER_COLUMN_WIDTH` is the pin-lead width every kit shares.
`ROW_DND_MIME` is the HTML5 drag type.

Styling and test hooks: `row-reorder-handle`, `row-reorder-buttons`,
`row-reorder-up`, `row-reorder-down`, `row-move-menu`,
`row-move-menu-trigger`, `row-move-menu-content`, `row-move-menu-item`, and
`row-move-confirmation`.

---

# React table row pinning — sticky top and bottom rows

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — compose `rowPinning()` and pin actions appear. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [pin and merge rows in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/rows/) — sticky pins, Team written once down consecutive teammates (pin keeps that one merge), and a 3-dot menu. Movement lives on the [row-reordering page](https://adapttable.orwamahmoud.com/react/demo/mantine/row-reordering/). The same pages exist for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

Import `rowPinning` from `@adapttable/<kit>/row-pinning` and compose it; every
row gains icon-only
Pin to top / Pin to bottom / Unpin (labels on hover and as the accessible name),
each hidden when it does not apply. A table that does not compose it carries
none of this — see [feature composition](./features.md). The value is
`{ top, bottom }` lists of row ids, not a flat array: which edge a row
sticks to is the feature.

```tsx
import { DataTable } from "@adapttable/mantine";
import type { RowPinState } from "@adapttable/mantine/features";
import { rowPinning } from "@adapttable/mantine/row-pinning";
import { useState } from "react";

function Tasks({ rows }: { rows: Task[] }) {
  const [pinnedRowIds, setPinnedRowIds] = useState<RowPinState>({
    top: [],
    bottom: [],
  });
  return (
    <DataTable
      data={rows}
      columns={columns}
      rowKey={(row) => row.id}
      features={[
        rowPinning({ pinnedRowIds, onPinnedRowIdsChange: setPinnedRowIds }),
      ]}
    />
  );
}
```

Uncontrolled: a bare `rowPinning()`, or `rowPinning({ onPinnedRowIdsChange })`
to observe the lists, and the table holds them. In that mode the
batteries-included shell writes them to the URL
(`rowPin=id1:top,id2:bottom`) so a shared link keeps the same rows stuck, and
Saved Views capture `rowPin` with the rest of the table. A controlled
`pinnedRowIds` keeps the URL out of it. `useRowPinningUrlState` is the same
pair for a host that wants to own the URL itself.

## Outside the virtual window

A pinned row is **removed** from the scroll list and rendered first or last
in the body (`data-adapttable-part="pinned-top"` /
`"pinned-bottom"` on the row). Leave it in the window and it draws twice. The
virtualizer windows only the unpinned rows; ARIA `rowCount` and
`windowStart` still describe the whole dataset.

Pinned-row cells keep column `pinOffset`, with a z-index between a scrolled
pinned column and the sticky header (`PIN_Z.rowPinned` /
`PIN_Z.rowPinnedColumn`), so a pinned row over a pinned column does not
overlap the header corner.

## Mobile

Cards get the same pin actions and no sticky chrome — a card list is not a
grid. The list order still puts top pins first and bottom pins last.

## What it will not do

**Grouping or a tree.** A nested list is not a flat pin stack. Composing
`rowPinning(…)` while either is armed logs a `devWarn` and the actions do not
render.
Host-owned totals that are not data rows are a different feature —
[`pinnedSummaryRows`](./pinned-summary-rows.md) sticks those objects above
or below the scroll body on every table shape, including grouped and tree
tables.

## Headless

`useRowPinning(options)` returns `RowPinningState`: `state`, `sideOf`,
`pin`, `unpin`, and the three synthesized actions
(`PIN_TOP_ACTION_KEY`, `PIN_BOTTOM_ACTION_KEY`, `UNPIN_ROW_ACTION_KEY`).
`applyRowPin(state, rowId, side)` is the in-memory helper — a copy, never
a mutate. `partitionPinnedRows(rows, state, getRowId)` splits a list into
top / scroll / bottom. `rowPinSignature(pinning, rowId)` is the memo
digest so a virtualized row repaints when it is pinned or unpinned.
`EMPTY_ROW_PIN_STATE` is `{ top: [], bottom: [] }`.

From `@adapttable/react/adapter`: `pinnedRowStickyStyle` / `pinnedRowCellStyle`
are the sticky CSS kits spread; `pinnedRowPart` names the row's
`data-adapttable-part`; `pinnedRowSticky` is the sticky style when the
kit asked for sticky pins; `orderedCardEntries` is the card-list order;
`useOffsetHeight` measures the header so top pins sit under it;
`PINNED_TOP_PART` / `PINNED_BOTTOM_PART` name the sections.
`rowSourceIndex(entry)` is the dataset index when pinning remapped the
window.

Labels: `pinToTop`, `pinToBottom`, `unpinRow` (`RowPinLabels`).

---

# React table pinned summary rows — totals that stay outside the row model

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — compose `pinnedSummaryRows`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [pinned summaries and group totals in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/aggregation/) — host-owned totals stick above and below the list, and they are not data rows. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

These are **not** lifted data rows. You pass separate objects
(`pinnedRows: { top, bottom }`) that never enter sort, filter, grouping,
pagination or selection. Cells still run through the ordinary column
pipeline — formatters, sparklines, spanning — and the rows stick above
or below the scroll window, including on grouped and tree tables where
[lift-a-data-row pinning](./row-pinning.md) stays refused.

```tsx
import { DataTable } from "@adapttable/mantine";
import { pinnedSummaryRows } from "@adapttable/mantine/pinned-summary-rows";

const totals = { id: "totals", name: "Team total", budget: 128_000 };

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    pinnedSummaryRows({
      top: [totals],
      bottom: [{ id: "grand", name: "Grand total", budget: 128_000 }],
    }),
  ]}
/>;
```

The objects are host data. Nothing is written to the URL or a Saved View
— a shared link does not have to invent totals the next load cannot
recompute. They are not exported, selected, edited, reordered, or given
pin / row-action menus.

Desktop rows use `data-adapttable-part="pinned-summary-top"` /
`"pinned-summary-bottom"` and `aria-label` from `pinnedSummaryRow`.
Keyboard cell navigation reaches them. Mobile cards keep the same order
and announcement; a card list has no sticky chrome.

Identities are namespaced (`adapttable:pinned-summary:top:0`) so they
never collide with a data-row id.

Totals computed from rows — `summaryRow` and group aggregates — are on the
[aggregation](./aggregation.md) page. Lift a real person with [`rowPinning`](./row-pinning.md). Stick a total
that is not in the dataset with this factory.

Labels: `pinnedSummaryRow`, `pinnedSummaryTop`, `pinnedSummaryBottom`.

Headless, from `@adapttable/core`: `PinnedRows` is the `{ top, bottom }`
shape and `PinnedSummaryEntry` one resolved row; `resolvePinnedRows`,
`pinnedSummaryEntries` and `allPinnedSummaryEntries` flatten them into keyed
entries. `pinnedSummaryRowId(side, index)` builds the namespaced id,
`isPinnedSummaryRowId(id)` and `pinnedSummarySideFromId(id)` read it back, and
`pinnedSummaryPart(side)` names the row's part (`PINNED_SUMMARY_TOP_PART` /
`PINNED_SUMMARY_BOTTOM_PART`). The id and part helpers are also on
`@adapttable/react/adapter`.

---

# React table row and column spanning

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — add `cellSpan(...)` from `@adapttable/mantine/cell-span` to `features`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [merge cells in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/rows/) — Team is written once down the people who share it. Person stays its own cell. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

A span is a rectangle. The origin cell carries `colSpan` / `rowSpan`; every
covered neighbour is omitted from that row's cell list, so every kit maps one
list instead of `columns.map`. Spanning is the `cellSpan` feature: without it
the list is one cell per column and nothing extra renders, even when a column
sets `colSpan` / `rowSpan`.

By default the origin is painted like a spreadsheet merge: **centered
content, one fill** across the whole span (`data-cell-span` is
`"colSpan x rowSpan"`, e.g. `"1x5"`). That is `cellSpan(getCellSpan, "merged")`,
the default. Pass `"plain"` as the second argument for geometry only — same chrome as a 1×1 cell — if you want
to draw a calendar-style bar yourself. Override the fill with
`--adapttable-cell-span-fill`, or the unstyled `cellSpan` class hook.

```tsx
import { DataTable } from "@adapttable/mantine";
import { cellSpan } from "@adapttable/mantine/cell-span";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    cellSpan(({ column, row, sectionRows, sectionRowIndex }) => {
      if (column.key !== "team") return undefined;
      if (sectionRows[sectionRowIndex - 1]?.team === row.team) return undefined;
      let rowSpan = 1;
      while (sectionRows[sectionRowIndex + rowSpan]?.team === row.team) {
        rowSpan += 1;
      }
      return rowSpan > 1 ? { rowSpan } : undefined;
    }),
  ]}
/>;
```

A column that always spans can say so on the definition:

```tsx
{ key: "team", header: "Team", accessor: (row) => row.team, rowSpan: 2 }
```

The table honours it once `cellSpan` is composed. With no per-cell rule,
pass one that defers to the columns: `features={[cellSpan(() => undefined)]}`.

The callback's value wins per side: a side it leaves unset, or an
`undefined` return, falls back to `column.colSpan` / `column.rowSpan`. Spans clamp to the remaining grid.
They clip at a **column pin** boundary (a pinned cell and a scrolling cell
cannot share one `<td>`) and at the **column window**: a span that starts
off-screen continues on the first visible column it covers.

Arrow keys skip a covered cell. CSV / XLSX write the origin value once and
leave covered cells empty.

## Mobile and the URL

Cards are a list of fields, not a grid — they ignore geometry and still
show every column. Spans are derived from data, so there is nothing to
put in the URL or a saved view.

Row spans stay inside one tbody. Consecutive teammates in visual order
(pinned top, then scroll, then pinned bottom) stay one merge — pinning a
Core person to the floor does not split Core into two cells. Kits render
those rows in the same tbody so HTML can express the span; a sticky pin
and a `rowSpan` taller than one row paint on top of each other, so the
sticky offset is skipped while any body cell spans more than one row.
The row still moves to the top or floor.

---

# React table full-width and separator rows

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — add `extraRows([...])` from `@adapttable/mantine/extra-rows` to `features`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [the all-options demo](https://adapttable.orwamahmoud.com/react/demo/all-options/) — turn **Extra attached to a person** on.

A separator is a thin rule. A full-width row is one cell that spans the
table. Both are host-injected slots in the same `kind`-tagged list grouping
already uses. Without the `extraRows` feature nothing is inserted.

```tsx
import { DataTable } from "@adapttable/mantine";
import { extraRows } from "@adapttable/mantine/extra-rows";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    extraRows([
      { key: "s", kind: "separator", beforeRowId: "2" },
      {
        key: "note",
        kind: "fullWidth",
        render: () => <em>Shipped Friday.</em>,
      },
    ]),
  ]}
/>;
```

`beforeRowId` is a data-row id. Omit it to append after the last data row.
Several extras that share a target keep the host's order. A named extra
stays in front of that person through drag-reorder and pin — it is its
own full-width row, with its own height, not folded into the person
below. When a Team (or any) row span would paint through that extra, the
extra sits on top of the spanned column so the note stays whole. The
extra uses the `backgroundColor` / `background` that
`rowAppearance({ rowStyle })` gives that person (light and dark are whatever
you passed) — AdaptTable does not pick a colour of its own.

```tsx
features={[
  extraRows([
    {
      key: "note",
      kind: "fullWidth",
      beforeRowId: ada.id,
      render: () =>
        `Attached to ${ada.name} — drag or pin them and this extra comes along.`,
    },
  ]),
]}
```

The slots join the grouping entry list when grouping is on, so they window
with the groups. On a flat or tree table they splice into the rendered
body. Mobile cards keep the same slots: a rule between cards, or a
full-width note.

Extras are content, not table state — nothing goes in the URL or a saved
view.

---

# React table row styling and heights

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — add `rowAppearance({ rowStyle, rowHeight })` from `@adapttable/mantine/row-appearance` to `features`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [the all-options demo](https://adapttable.orwamahmoud.com/react/demo/all-options/) — turn **Row style** on.

`rowAppearance` takes three options: `rowClassName` appends a class, and
`rowStyle` / `rowHeight` set inline style and height. Each is a function of
`(row, index)` (`rowHeight` also takes a number), applied to desktop rows and
mobile cards alike. Without the feature nothing is set.

```tsx
import { DataTable } from "@adapttable/mantine";
import { rowAppearance } from "@adapttable/mantine/row-appearance";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    rowAppearance({
      rowStyle: (row) =>
        row.overdue ? { backgroundColor: "var(--overdue)" } : undefined,
      rowHeight: (row) => (row.tall ? 72 : 48),
    }),
  ]}
/>;
```

A number `rowHeight` is every row. A function is per row. Height wins when
`rowStyle` also names `height` — `rowHeight` is the dedicated override.

Pass a light fill and a dark fill — AdaptTable does not pick those colours.
`light-dark()` follows the page `color-scheme` (and RTL uses logical
properties, so `text-align: start` is already the extra's alignment):

```tsx
rowAppearance({
  rowStyle: (row) =>
    row.overdue
      ? {
          backgroundColor:
            "light-dark(oklch(0.93 0.08 95), oklch(0.38 0.07 85))",
        }
      : undefined,
});
```

CSS variables that flip under the host's dark class work the same way.

The row virtualizer's `estimateSize` reads the same value, so a
variable-height table still windows. `measureElement` stays authoritative
for what the browser actually laid out.

Style and height are functions of the row, not table state — nothing goes
in the URL or a saved view.

---

# React data grid navigation — range selection, copy, paste and fill

Use arrow keys to navigate cells, select a range, copy and paste spreadsheet
values, or extend values with a fill handle. This guide also covers find-in-table,
selection statistics and accessible focus. For host-owned validation and saving,
see [cell editing](./cell-editing.md).

A table with a hundred cells should not be a hundred tab stops. Compose
`cellNavigation` from `@adapttable/<kit>/cell-navigation` and the table becomes
**one** tab stop whose interior is reachable by arrow keys, with correct ARIA
grid semantics and a screen reader that says where you are. See
[feature composition](./features.md).

**Related:** [Accessible React data table](./accessibility.md) ·
[Cell editing](./cell-editing.md) · [Virtualization](./virtualization.md) ·
[Columns](./columns.md)

## Copy and cut, the way a spreadsheet reads it

**Ctrl/Cmd+C** copies the selected rectangle as tab-separated text — the format
Excel, Google Sheets, Numbers and LibreOffice all read — so a paste lands in
columns rather than one cell. Cells carrying a tab, a newline or a quote are
quoted the way those applications quote them.

Values resolve exactly as an export's do, `exportValue` included, so a copy and
a downloaded file cannot disagree about what a cell contains.

**Ctrl/Cmd+X** copies the same text and then calls `onCellCut(range)`. The table
clears nothing itself: what "cut" removes is your decision, and a cut that
emptied cells before the clipboard accepted them would lose the data outright.
With [`contextMenu()`](./command-palette.md#built-in-entries) composed, the
cell menu offers the same Cut.

Either way the outcome is announced — `labels.gridRangeCopied` on success,
`labels.gridRangeCopyFailed` when the browser refuses (the Clipboard API needs a
secure context and can be denied). With nothing selected, both keys are left to
the browser.

Headless: `clipboardRangeText` builds the text and `writeClipboardText` writes
it, reporting whether it landed rather than throwing.

## Pasting a spreadsheet back in

**Ctrl/Cmd+V** parses what a spreadsheet put on the clipboard and commits it as
ordinary cell edits — through your `editing()` handler, the same channel inline
editing uses:

```tsx
import { DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { editing } from "@adapttable/mantine/editing";

<DataTable
  data={rows}
  rowKey={(row) => row.id}
  features={[
    cellNavigation(),
    editing((row, key, value) => save(row, key, value)),
  ]}
  columns={[{ key: "budget", header: "Budget", editable: true }]}
/>;
```

That is the whole wiring: a table that can be edited can be pasted into. Each
edit is the same thing an inline commit produces — same `parseValue`, same
shape, same handler — so paste is not a second editing route, and whatever you
wrap around a single-cell commit already covers a paste of two hundred.

To take the batch whole instead — one server round trip, one undo entry — set
`onCellPaste`, which takes precedence:

```tsx
<DataTable
  data={rows}
  rowKey={(row) => row.id}
  features={[cellNavigation(), editing(commit)]}
  onCellPaste={(edits) => saveAll(edits)}
  columns={[{ key: "budget", header: "Budget", editable: true }]}
/>
```

The **clipboard's shape wins** over the selection's: pasting a 3×2 block into one
focused cell writes 3×2, as every spreadsheet does. Cells landing outside the
loaded rows or the rendered columns are dropped rather than invented, and a
column that is not `editable` is skipped — a paste is an edit, and an edit into a
read-only column is not one.

The table writes nothing itself. Applying the edits stays yours, which is what
keeps a paste undoable, validatable and cancellable on your terms. The outcome
is announced through `labels.gridRangePasted`, or `labels.gridRangePasteFailed`
when the browser will not hand over the clipboard.

Headless: `readClipboardText` reads it, `parseClipboardTable` parses it, and
`pasteRangeEdits` maps it onto a range.

## The fill handle

Select a cell or a block and a small square appears on its bottom corner. Drag
it and the selection's values carry on — down, up, or sideways, whichever way
the drag mostly goes. The cells it would write are highlighted before anything
is committed, so the preview and the result cannot disagree.

**Two or more numbers a constant step apart continue the series** (1, 2 → 3, 4);
anything else repeats in order (Mon, Tue → Mon, Tue). A single number repeats
rather than counting — one value carries no step, and guessing `+1` there is the
behaviour spreadsheets are cursed for.

**Ctrl/Cmd+D** is the keyboard route: the selection's top row carries into the
rest of it. The handle itself is not a tab stop, because the grid is one tab
stop and a focusable square inside it would break that; the key press announces
what it wrote through `labels.gridRangeFilled`.

The edits arrive exactly as a paste's do — one call per cell through
`editing()`, or `onCellFill` for the batch — so the handle appears as soon as a
table can be edited, and never when it cannot:

```tsx
<DataTable
  data={rows}
  rowKey={(row) => row.id}
  features={[cellNavigation(), editing(commit)]}
  columns={[{ key: "budget", header: "Budget", editable: true }]}
/>
```

The square paints in the cell's own text colour; `--adapttable-fill-handle`
changes it. In RTL it sits on the row's inline end, which is the left, and a
sideways drag follows the same mirroring the arrow keys do.

Headless: `fillDirection`, `fillTargetRange` and `fillRangeEdits`;
`FillHandleChrome` passes the active corner to an adapter-owned handle.

## Find in table

Compose `findInTable` from `@adapttable/<kit>/find-in-table` and **Ctrl/Cmd+F**
opens a find bar over the table while focus is inside it or after a click in
it — a click elsewhere on the page hands the shortcut back to the browser;
`findInTable({ button: true })` also draws a **Find in table** control among
the toolbar's view controls, with the kit's own button (part `find-button`,
`aria-expanded` while the bar shows; `classNames.findButton` on unstyled and
shadcn):

```tsx
import { DataTable } from "@adapttable/mantine";
import { findInTable } from "@adapttable/mantine/find-in-table";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[findInTable({ button: true })]}
/>;
```

Find works on its own. With [`cellNavigation()`](#selecting-a-range) composed
too, walking the hits also moves the grid's focus and selection with them.

Find is not [search](./search.md). The search box asks "show me only the rows that match", and
on a server tier it asks the server; find asks "where does this appear in what I
am looking at", leaves every row where it is, and walks the hits. Both can be on
at once.

Every hit is marked — `data-cell-match`, and `data-cell-match-current` on the
one you are standing on — painted in the amber every browser paints its own
find hits, because a find highlight is a browser convention rather than a
design-system token. `--adapttable-find-match` and
`--adapttable-find-match-current` change it; in `@adapttable/unstyled` the
`cellMatch` / `cellMatchCurrent` class hooks do (the shadcn preset fills them
in).

**Enter** walks forward, **Shift+Enter** back, **Escape** closes and clears.
The current hit is scrolled into view — a find that highlighted without going
there would leave you hunting for the highlight — and the count is announced.
With cell navigation, walking also moves the grid's focus to the hit, which is
announced and left selected. The bar itself is one input, a count and
three buttons, all named through `labels.findInTable`, `findPlaceholder`,
`findMatchCount`, `findPrevious`, `findNext` and `findClose`.

Matching reads what a cell **shows**, so a column that renders a formatted date
is found by that date rather than by the ISO string underneath. Only the loaded
rows are searched: a hit the table cannot take you to would be a lie, so on a
paged table find covers the page you are on, and under virtualization it covers
what has been fetched. The **query** is part of the table's shareable URL state
(a `find` param beside `q`): opening a link that carries it reopens the bar,
runs the walk, and focuses the first hit. The current-match position stays
ephemeral — the receiving page's data may differ, so the query reproduces and
the cursor does not. Typing writes with replace-state after a short debounce so
browser history stays clean.

On mobile the cards are a list rather than a grid, so the bar opens and searches
but the hits are not marked; the desktop layout is where a cell can be pointed
at.

Headless: `findMatches`, `matchKeySet` and `stepMatch` in `@adapttable/core`,
`useFindInTable` in `@adapttable/react`. Each adapter mounts `FindBar` over
`FindBarChrome`.

## What the selection adds up to

Compose `selectionStats` from `@adapttable/<kit>/selection-stats` and a strip
under the table says what is selected:

```tsx
import { DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { selectionStats } from "@adapttable/mantine/selection-stats";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[cellNavigation(), selectionStats()]}
/>;
```

> Count 12 · Sum 1,240.5 · Avg 103.4 · Min 12 · Max 900

Composing `selectionStats()` also adds the row-selection checkbox column. The
figures need `cellNavigation()`, which is what produces a cell range.

The count covers every selected cell; the arithmetic covers the numeric ones,
so a rectangle spanning a name column and a budget column still has a sum.
Numbers are read the way an export reads them — `exportValue` included — so the
total here and the total a spreadsheet computes from a paste of the same cells
cannot disagree. Booleans are not counted as numbers: summing a column of ticks
to 3 answers a question nobody asked.

A single cell shows nothing — it has no total worth reading, and a strip that
flickers in on every arrow press is noise. The strip is a status region, so a
screen reader reads the figures after the range announcement rather than
interrupting it, and every word is localizable (`labels.selectionCount`,
`selectionSum`, `selectionAverage`, `selectionMin`, `selectionMax`). Number
formatting follows the table's `locale`.

Selecting a column covers the LOADED rows, so the figures describe the 500 rows
in hand rather than the 100,000 in the dataset — the table never totals rows it
has never seen.

Headless: `selectionStats(options)` returns the figures;
`SelectionStatsChrome` passes formatted parts to an adapter-owned status bar.

## Selecting with the pointer, and whole columns

Drag across cells to select a block: the press anchors it, crossing a cell
extends it, and releasing anywhere — including outside the table — ends it.

A **column header** selects its whole column. Where the header already sorts,
sorting keeps the plain click and **Ctrl/Cmd+click** selects instead; on a header
that does not sort, a plain click selects. Ctrl/Cmd+click also extends an
existing selection to a second column.

A column selection covers the **loaded** rows. With 500 of 100,000 rows in hand
that is 500 cells, not 100,000 — the table never claims rows the browser has
never seen, because a copy or an export would then invent them.

### The header checkbox

`columnSelectionCheckbox()` adds a checkbox to every column header that selects
that column. The gesture above is unchanged; this is the same state reached two
ways it cannot be. A touchscreen has no Ctrl key to hold, and a gesture nothing
announces is a gesture nobody finds — so the control is what a finger taps and
what a screen reader reads, named `labels.selectColumn` plus the column's own
name ("Select column: Team", translated in every bundled locale).

```tsx
import { DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { columnSelectionCheckbox } from "@adapttable/mantine/column-selection";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[cellNavigation(), columnSelectionCheckbox()]}
/>;
```

It needs `cellNavigation()`, because that is what makes a selection exist at all;
without it the header checkboxes do not render, and `columnSelectionCheckbox()`
alone adds only the row-selection column. Ticking selects the column, unticking clears
— nothing selected is the only state one checkbox can return to, since a
rectangle cannot lose a column out of its middle. A box reads as checked only
when the selection is exactly its column: inside a wider rectangle it stays
clear rather than saying the selection is one column when it is four.

Where the pointer can hover, the box holds its space and fades in on hover or
focus, so a wide header row is not a row of checkboxes and the layout never
moves; a selected column keeps its box on screen either way. Where there is no
hover — a touchscreen — it is always visible.

The control is `data-adapttable-part="column-select"` (`columnSelect` in
`@adapttable/unstyled`'s `classNames`), and it is each kit's own checkbox: core owns the layout, the
name, and keeping the click off the header underneath it, which would otherwise
sort the column the same click just selected.

Whenever the rectangle changes, the live region says what it now covers —
`"selected rows 1 to 2, columns 1 to 2, 4 cells"` — through
`labels.gridRangeSelection`, translated in every bundled locale. A single cell
stays silent: it announces itself already, and repeating "1 cell" on every arrow
press turns navigation into noise.

## The selection is visible, in each kit's own colour

Hold Shift while arrowing (or shift-click) and the extended range is filled with
the kit's own selected-cell token — Mantine's primary-light, MUI's
`action.selected`, Ant Design's active-item background, Radix's accent, and so
on. Nothing to configure.

Every selected cell also carries `data-cell-selected`, so CSS can target the
range directly. In `@adapttable/unstyled` there is no kit colour to borrow, so
the fill is yours through the `cellSelected` class hook (the shadcn preset sets
`bg-accent`).

## Example

```tsx
import { DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";

<DataTable
  data={people}
  columns={columns}
  rowKey={(row) => row.id}
  features={[cellNavigation()]}
/>;
```

That is the whole opt-in. Omit it and nothing changes — see
[Off means absent](#off-means-absent).

## The keys

| Key                          | Where focus goes                                |
| ---------------------------- | ----------------------------------------------- |
| `↑` `↓` `←` `→`              | One cell, stopping at the edges                 |
| `Home` / `End`               | Start / end of the current row                  |
| `Ctrl`+`Home` / `Ctrl`+`End` | First / last cell of the whole grid             |
| `PageUp` / `PageDown`        | A viewport's worth of rows                      |
| `Enter` / `F2`               | Opens the editor, when the column is `editable` |
| `Ctrl`/`Cmd`+`C` / `X` / `V` | Copy, cut, paste the selected rectangle         |
| `Ctrl`/`Cmd`+`D`             | Fill the selection down from its top row        |
| `Tab`                        | Leaves the table — it is one stop, not hundreds |

Edges **stop rather than wrap.** Wrapping off the last column would move the
user to a different record without saying so; a table is not a spreadsheet.

Under `dir="rtl"` the left and right arrows swap, because arrow keys describe
the screen rather than the data — in a mirrored table the visually-next column
is the previous one. `Home` and `End` do not swap: they mean the start and end
of the row either way.

## What a screen reader hears

Focus alone announces a cell's contents, which is not navigation — "1,240" says
nothing about which column it belongs to or where it sits in a dataset whose end
you cannot see. So a live region announces the column, the cell's text, and the
absolute position:

> Budget, 1,240, row 40,002 of 100,000

The cell's text comes from [`columnText`](./columns.md), so a column whose cell
renders a badge or an avatar needs a `formatValue` to have anything readable.
The position phrase is localizable through `labels.gridCellPosition`, and ships
translated in every bundled locale.

## Virtualization

This is where a naive implementation is wrong and looks right. With 24 rows of
100,000 rendered, `aria-rowindex` must number rows **within the dataset**, not
within the window — otherwise assistive technology reports "row 3 of 24" while
the user is at row 40,000. AdaptTable carries absolute `aria-rowindex` /
`aria-colindex` and dataset-wide `aria-rowcount` / `aria-colcount`.

`Ctrl`+`End` on a 100,000-row table also asks for a cell that is not in the DOM
at all. Focus scrolls it into existence and lands on it once it mounts.

## Selecting a range

Hold **Shift** with any movement key, or shift-click a cell, and the selection
extends from where it began:

| Gesture                       | Result                          |
| ----------------------------- | ------------------------------- |
| `Shift`+`↑` `↓` `←` `→`       | Extend the rectangle one cell   |
| `Shift`+`Home` / `End`        | Extend to the row's start / end |
| `Shift`+`PageUp` / `PageDown` | Extend by a viewport of rows    |
| `Shift`+click                 | Extend to the clicked cell      |
| Any plain move                | Collapse back to a single cell  |

A range is stored as two corners — the **anchor** where it started and the
**head** where it reaches — not as a list of cells. That is what makes
Shift+Down twice then Shift+Up _shrink_ the range instead of starting a new one
upward, and what makes a 50,000-cell selection cost two numbers.

Selected cells carry `data-cell-selected` for styling. `aria-selected` appears
only once a real rectangle exists: marking every focused cell as selected would
tell a screen reader the table is in selection mode when the user has merely
arrowed around.

`cellNavigation({ onRangeChange })` tells the host the rectangle on mount and
whenever it changes — `null` when nothing beyond the focused cell is selected —
which is what a "sum of selection" readout of your own reads:

```tsx
const [range, setRange] = useState<CellRange | null>(null);

<DataTable
  {...props}
  features={[cellNavigation({ onRangeChange: setRange })]}
/>;
```

Headless: `useGridFocus({ onRangeChange })` reports every change, and
`gridFocus.range` holds the current rectangle — which is what
`exportCsv({ scope: "range" })` reads.

Headless: `CellRange` and `CellRangeBounds` are the shapes, `cellRangeBounds`
sorts the corners of a range dragged up or left, `isInCellRange` tests
membership, `cellRangeSize` multiplies rather than enumerating,
`extendCellRange` moves the head while keeping the anchor, `singleCellRange`
and `isSingleCell` handle the one-cell case, and `cellRangeIndices` enumerates
the rows and columns for an exporter — the one place that does.

## Mobile

Cell navigation applies to the **desktop table layout**. Mobile cards are a
list, not a grid: they keep list semantics, and arrow keys are not hijacked
there. This is deliberate — a card is one record's worth of stacked
label/value pairs, and a two-dimensional focus model does not describe it.

## Off means absent

Without `cellNavigation()` composed there is no `role="grid"`, no `tabIndex`, no key
handler, no live region, and no extra attributes. Not "disabled" — absent. A
core test asserts the markup is byte-identical to a table built without the
feature, and each of the eight adapters asserts there is no grid role and no
focusable cell.

Focus position is also deliberately **not** saved to the URL or a Saved View.
Where the keyboard is sitting is ephemeral UI state, not part of a view someone
would share.

## Headless

| Export                                                    | Purpose                                                                                                                           |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `useGridFocus` / `UseGridFocusOptions` / `GridFocusState` | The hook, its options, and the state it returns (`getGridProps`, `getCellPropsAt`, `getRowPropsAt`, `focusCell`, `announcement`). |
| `GridFocusAnnouncer` / `GridFocusAnnouncerProps`          | The live region, from `@adapttable/react/adapter`. Renders nothing when navigation is off.                                        |
| `moveGridFocus` / `GridFocusMove` / `GridBounds`          | The pure move arithmetic and its vocabulary — no React, no DOM.                                                                   |
| `gridFocusMoveForKey` / `GridKeyPress`                    | Maps a key press to a move, applying the RTL swap.                                                                                |
| `GridCell` / `sameGridCell`                               | A cell address, and address equality.                                                                                             |
| `GRID_CELL_ATTR` / `gridCellAttr`                         | The `data-grid-cell` attribute focus uses to find a cell in the DOM.                                                              |
| `contextMenuCopyTarget` / `ContextMenuCopyTarget`         | Decides what a context-menu Copy takes: the clicked cell, or the selection it landed inside.                                      |

### Copying from the context menu

The context menu names what was clicked by row key and column key. Copying
needs a grid address, and a row key is not one: where a row sits on screen
follows the sort, the filter, the page, the pinned rows and the virtual
window. `gridFocus.cellAt(rowId, columnKey)` resolves it against the very rows
and columns that grid was handed, so no adapter counts positions itself.

`contextMenuCopyTarget(gridFocus, target)` then decides what Copy takes:

```tsx
onCopy: (target) => {
  const copy = contextMenuCopyTarget(gridFocus, target);
  if (!copy.available) return;
  gridFocus.copyCells(copy.cell);
};
```

A cell with nothing selected copies that cell. A click inside a selection
keeps the selection — the rectangle is what the reader built. A click outside
one copies the cell under the cursor. A target that names no cell reports
`available: false`, and the menu greys Copy out rather than copying data
nobody pointed at. `useGridFocus` needs `getRowId` for `cellAt` to answer.

`getCellPropsAt(windowIndex, col)` and `getRowPropsAt(windowIndex)` take the
index an adapter already has — its position in the rendered rows — and convert
to the absolute address internally. That conversion lives in core precisely
because getting it wrong is invisible on screen.

## Notes

- Works in all eight adapters, verified by the same parity test in each.
- Enter and F2 open the focused cell when its column is `editable`, and do
  nothing when it is not — so arrowing to a cell and pressing Enter edits it,
  which is the whole keyboard path.
- A click that focuses a cell moves the grid's focus too; in Safari, clicking
  the row-selection checkbox does not move focus into the grid.

---

# React table row grouping — interactive panel, nested groups & aggregates

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — the starter is grouped by role with salary subtotals (`groupingPanel("role", { groupAggregates })`); drag another header onto the panel, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [collapse groups and override aggregations in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/grouping/) — a real table you can click, not a recording. Independent pinned totals and the footer grand total live on the [aggregation page](https://adapttable.orwamahmoud.com/react/demo/mantine/aggregation/).

Each subtotal renders in its own column's cell, so it sits under the column it
totals — on a mobile card, where there are no columns to align to, the same
numbers appear captioned by their column instead. A custom renderer can place
them the same way with `groupRowLayout` and `groupAggregateEntries`.

Compose `groupingPanel` from `@adapttable/<kit>/grouping-panel`. It owns both
the grouped-row headers and the interactive panel, so use it instead of plain
`grouping()` when users should be able to configure grouping:

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

<DataTable features={[groupingPanel()]} … />;
<DataTable
  features={[
    groupingPanel(["team", "status"], {
      groupAggregates: (rows) => ({ budget: sum(rows) }),
    }),
  ]}
  …
/>;
```

The first argument is an initial column key or ordered list; omit it to start
with an empty strip. The second argument accepts the ordinary grouping extras,
including `groupAggregates`, whose mapper has the **same signature as
`summaryRow`**. Omit the factory and the table mounts neither grouping headers
nor panel chrome. Plain `grouping("team")` from `@adapttable/<kit>/grouping` is
the no-panel path for a host that deliberately fixes grouping in code, and the
only grouping entry `@adapttable/bootstrap` ships. See
[feature composition](./features.md).

## The grouping panel

On desktop, the feature adds a dedicated strip above the table. Drag any data
header into it to group — set `groupable: false` on a column and its header
offers no drag and the panel does not list it, the same opt-out shape as
`sortable` — drag the chips to change nesting order — onto another
chip to take its place, or onto the caret between two to land there — or drag a
chip to the remove target to ungroup it. A chip's focusable move control also
supports Arrow Up/Down and logical Arrow Left/Right; the latter reverse in RTL
so movement follows the visible order. Its remove button is the keyboard
dismiss route. Every add, move, removal, and aggregation change is announced
through a polite live region. The captions and announcement templates ship in
every bundled `@adapttable/i18n` locale.

A column decides what it buckets rows by. Without help a group is one distinct
sort value, which is right for a team or a status and wrong for anything
continuous — group by a timestamp and every row becomes its own group, headed
by the raw number. `groupValue` returns the bucket instead, and it is also the
group's caption:

```tsx
{
  key: "start",
  sortValue: (row) => row.start.getTime(),
  groupValue: (row) => monthOf(row.start),
}
```

Every layout also provides **Add grouping column**. Beside the grouping chips,
every active aggregate is its own item — column name, operation selector, and
remove — plus **Add aggregation column** and **Restore defaults** when the
developer sent defaults the reader has changed. Mobile uses these kit-native
controls rather than header drag-and-drop.

A column's `Aggregatable` declaration (`aggregatable`) decides what a reader
may add — `AggregatableConfig` with `default` and `operations` of
`AggregateOperation` values (a built-in name or a `CustomAggregateOperation`).
`resolveAggregatable` / `resolveAggregatableColumns` validate that offer;
`impliedOperations` is what `true` reads from the declared filter or editor
type. Developer defaults (`aggregatable.default`, a declared
`GroupAggregatesMapper` via `aggregate()`, or the original server
`aggregates` query) appear immediately. Removing a developer default records
an explicit suppression (`AGGREGATE_SUPPRESSED` / `"none"` in `groupAgg`);
`restoreAggregationDefaults` puts the original developer configuration back,
not the latest server response. The panel and column menu both read
`aggregationModel`. Display, local calculation and the server request share
`resolveEffectiveAggregation` (`EffectiveAggregationInput` /
`EffectiveAggregationKind`): a valid reader override or permitted
suppression, then a valid executable column default, then the original host
mapper or request. Defaults are not written into reader state — an untouched
table stays at defaults, and those defaults actually calculate and request.

```tsx
{
  key: "budget",
  aggregatable: {
    default: "sum",
    operations: ["sum", "avg", "min", "max", "count"],
  },
}
{
  key: "start",
  aggregatable: { operations: ["min", "max", "count"] },
}
{
  key: "score",
  aggregatable: {
    default: "median",
    operations: [
      "sum",
      "avg",
      { id: "median", label: "Median", calculate: median },
    ],
  },
}
```

`aggregatable: true` offers the operations that suit the column's **declared**
filter or editor type — never a sampled row, and never TypeScript's erased
value type. Numeric for `number` / `numberRange`; min/max/count for
`date` / `dateRange` / `datetime` / `time`; Count otherwise. A numeric column
without that metadata can still list explicit `operations`. `false` or omitted
refuses reader changes; a host mapper or server aggregate on that column still
shows — read-only when the reader cannot replace it, or as a Custom /
application-calculated item they may replace or suppress when they can.
Empty `operations` offers nothing. A custom `{ id, label, calculate }` is
addressed by `id`; omit `calculate` for an operation only the backend can
answer, and list that id on `supports.aggregateOperations`.

`min` and `max` compare numbers, `Date` values and strict ISO date / datetime /
time strings (`YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ssZ`,
`HH:mm`). Locale-dependent forms are skipped, not guessed. The winning
original value is what `formatAggregate` receives — a number, a `Date`, or
that ISO string — so a date column can format it without a numeric
`sortValue`. `count` still counts present values. An explicit `sortValue`
is respected first.

Grouping a column does not remove its aggregation offer. A grouped column
with Count (or any allowed operation) stays selectable; the group's row
count is not a substitute — missing values make those different.

`groupAgg` encodes both the column key and the operation id, so custom ids
with colons, commas, percents or Unicode round-trip. A built-in operation
encodes as `budget:sum`.

A computed aggregate is a number, and a number under a money column should
read as money. `formatAggregate` on the column says how one reads, and is
given the operation that produced it where the table knows it — the reader's
own choice, or the one a server was asked for — so a count reads as a count
under the same column:

```tsx
{
  key: "budget",
  accessor: (row) => money.format(row.budget),
  sortValue: (row) => row.budget,
  formatAggregate: (value, { aggregation }) =>
    typeof value !== "number" || aggregation === "count"
      ? value
      : money.format(value),
}
```

It runs where the cell is drawn — group header, group footer and mobile group
card alike — so the value the table holds, exports and compares stays the one
the aggregate returned.

**It composes with `aggregate({ format })`, and nothing stops it running
twice.** The two happen at different moments: `format` runs when the value is
computed, `formatAggregate` when the cell is drawn. Set both and the column's
formatter is handed whatever the mapper produced — a string, a node — and will
format that again unless it is written to pass non-numbers through, as the
example above does. The simplest arrangement is to leave group aggregates raw
and let the column own how they read; `format` still belongs on a mapper used
for `summaryRow`, which `formatAggregate` does not touch.

### Server tiers

On a server tier the operation is the one the request carried, and it is
published as of the response being drawn — so a column is told what the
numbers on screen were computed with, not what a request still in flight asks
for. Each request's operations are held against its own key, and only a
response that can be tied back to one of those requests moves what the table
publishes. A request that cannot be tied to one is reported as unknown:
`formatAggregate` is passed no operation, rather than one that may be wrong.

`useQuerySource` gets that association from the query itself: `dataUpdatedAt`
says whether the query showing these pages has an answer of its own, read
against the request it belongs to — two cached results can carry the same
stamp, so a stamp alone is not identity.

`useServerData` cannot see any of it. A controlled tier's rows simply change,
sometimes as the very array that was already there, and a cancelled request
looks exactly like an answered one from the outside. So `onQueryChange` hands
the handler an `info.key` naming the request, and `responseKey` is where the
answer's key comes back:

```tsx
const [rows, setRows] = useState<Person[]>([]);
const [answered, setAnswered] = useState<string>();

<DataTable
  mode="server"
  data={rows}
  total={total}
  loading={loading}
  responseKey={answered}
  onQueryChange={async (query, { signal, key }) => {
    const res = await fetch(`/api/people?${toParams(query)}`, { signal });
    const page = await res.json();
    setRows(page.items);
    setAnswered(key);
  }}
/>;
```

**A controlled tier needs `responseKey` to be accurate about this.** Without
it, rows retained through an in-flight or failed request keep the operations
they came with, but once a request simply stops the rows on screen are
described as unknown — a stopped request is what an abort looks like too, and
the table will not name an operation it cannot place. The same holds for a
hand-rolled `TableSource`: publish `groupAggregations` yourself, or leave it
unset and the table falls back to the reader's own choices. An aggregate
function only the server understands is reported as unknown rather than
guessed at.

Compose `columnMenu()` too and each column row gains **Group by…** or
**Ungroup…**. While grouping is active, an ungrouped column also offers the
same aggregation choice. Both routes write the same `groupBy` / `groupAgg`
state, so the panel, menu, URL, and Saved Views cannot disagree.

## Paging groups, and paging inside one

A table grouped by customer can have ten thousand groups. `groupPageSize` shows
a screenful and offers the rest; `groupRowPageSize` does the same for the rows
inside each group:

```tsx
import { DataTable } from "@adapttable/mantine";
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

<DataTable
  data={ORDERS}
  columns={columns}
  rowKey={rowKey}
  features={[
    groupingPanel("customer", {
      groupPageSize: 25,
      groupRowPageSize: 10,
    }),
  ]}
/>;
```

Each limit adds one row — "Show 42 more groups", "Show 8 more in this group" —
that reveals the next page when clicked. Only the **top level** pages: a nested
level is already inside a group the reader opened, and hiding part of what they
just opened would be a second "more" to hunt for.

On a **server tier** the rest of a group is not in the browser yet, so
`onGroupLoadMore(groupKey)` fires with the group that needs filling. Fetch it,
hand back a longer `rows` for that group, and the next render shows them; the
table reveals whatever it already holds either way. Both labels are localizable
(`labels.moreGroups`, `labels.moreRowsInGroup`) in every bundled locale, and the
rows carry `group-more-row` / `group-more-cell` / `group-more` parts (with
`groupMoreRow` / `groupMoreCell` class hooks in `@adapttable/unstyled`).

## Grouping on the server

A backend that can group is usually the only thing that can: it has the whole
dataset, and the browser has a page of it. Declare the capability and the table
sends the grouping keys with every query:

```tsx
import { DataTable, useQuerySource } from "@adapttable/mantine";
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

const source = useQuerySource<Person, Params, Page>({
  usePaginatedQuery: usePeopleQuery,
  selectPage: (page) => ({ rows: page.rows, total: page.total }),
  supports: { grouping: true, aggregates: true },
  aggregates: [{ key: "budget", fn: "sum" }],
});

<DataTable
  source={source}
  columns={columns}
  rowKey={rowKey}
  features={[groupingPanel("team")]}
/>;
```

`query.groupBy` arrives as an **array**, outermost key first — one entry for a
flat grouping, more for nested — and `query.aggregates` as
`[{ key, fn }]`. Neither is sent unless the source declared the matching
capability, so an endpoint that predates this never sees a field it does not
understand.

### The response shape

```ts
interface QueryGroupRow<TRow> {
  value: unknown; // the group's value, shown as its label
  count: number; // leaves beneath it, across the dataset
  aggregates?: Record<string, unknown>; // by column key
  groups?: QueryGroupRow<TRow>[]; // nested levels, when asked for
  rows?: TRow[]; // leaves, when the server includes them
}
```

They reach the table through the `groups` field of a `TableSource`
(`readonly groups?: readonly QueryGroupRow<TRow>[]`). `useQuerySource` and
`useServerData` send the grouping request and leave `groups` unset, so a
server-grouped tier is a `TableSource` that sets `groups` from the response.
The table renders them exactly as it renders local groups — same headers, same collapsing, same footers, same
selection. **The counts and aggregates are the server's**: a group of 4,000
whose response carried 20 rows says 4,000, because counting what arrived would
be a number the user can see is wrong.

A reference endpoint, grouping one level and returning the first page of each
group's rows:

```ts
app.get("/people", async (req, res) => {
  const groupBy = [req.query.groupBy ?? []].flat(); // e.g. ["team"]
  if (groupBy.length === 0) return res.json(await plainPage(req));

  const key = groupBy[0];
  const rows = await db
    .select(key, db.raw("count(*) as count"), db.raw("sum(budget) as budget"))
    .from("people")
    .groupBy(key)
    .orderBy("count", "desc");

  res.json({
    total: rows.reduce((sum, row) => sum + Number(row.count), 0),
    groups: await Promise.all(
      rows.map(async (row) => ({
        value: row[key],
        count: Number(row.count),
        aggregates: { budget: Number(row.budget) },
        rows: await db
          .select("*")
          .from("people")
          .where(key, row[key])
          .limit(20),
      }))
    ),
  });
});
```

Leave `rows` out to send counts only — the headers render with their counts and
nothing beneath them, which is the right answer for a table of a million rows
in a hundred groups. Fetch a group's rows when it opens by reacting to
`onCollapsedGroupIdsChange`: it tells you exactly which group the user just
expanded, and the next response fills it in.

**Without the capability**, a server tier that is asked to group says so in
the status bar and in development, and renders ungrouped rather than grouping
the page it happens to hold, which would be one page's worth of groups
presented as the whole set.

## Controlling what is open

Groups start expanded and collapse on their own. To hold that state yourself,
pass the pair:

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

const [closed, setClosed] = useState<string[]>([]);

<DataTable
  data={PEOPLE}
  columns={columns}
  rowKey={(r) => r.id}
  features={[
    groupingPanel(["team", "status"], {
      collapsedGroupIds: closed,
      onCollapsedGroupIdsChange: setClosed,
    }),
  ]}
/>;
```

The set names what is **closed**, because groups default to open — so an empty
set is a fully expanded table, and the state stays small no matter how many
groups there are. Each key carries the group's whole path, so nesting needs no
extra bookkeeping.

**In the URL**, with `useGroupCollapseUrlState`:

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";
import { useGroupCollapseUrlState } from "@adapttable/react";

const groups = useGroupCollapseUrlState({ urlKey: "people" });

<DataTable
  {...groups}
  features={[groupingPanel("team")]}
  columns={columns}
  rowKey={rowKey}
/>;
```

A link then carries which groups were folded — part of what someone means when
they send one. Keys are percent-encoded, so a label containing a comma cannot
split the list, and the parameter disappears when everything is open again.

**Whole-tree actions** live on the table's grouping bundle, for a host that
wants its own buttons: `expandAll()`, `collapseAll()`, and
`collapseToDepth(depth)` — depth `0` leaves only the outermost headers showing,
`1` opens the first level inside them.

## Ordering and filtering groups

`groupSort` orders the groups inside their parent, and `groupFilter` decides
which of them are worth showing:

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

<DataTable
  data={SALES}
  columns={columns}
  rowKey={(r) => r.id}
  features={[
    groupingPanel("region", {
      groupAggregates: (rows) => ({ amount: sum(rows) }),
      // Biggest region first — the same rows the aggregate is computed from.
      groupSort: (a, b) => sum(b.leafRows) - sum(a.leafRows),
      // And only the regions worth a line.
      groupFilter: (group) => sum(group.leafRows) >= 10_000,
    }),
  ]}
/>;
```

`groupSort` also takes `"label"`, `"label-desc"`, `"count"` and `"count-desc"`.
**To sort by an aggregate, compare the leaves** — an aggregate is a function of
its rows, and comparing the rendered aggregate cell would mean comparing
ReactNodes, which is not an ordering. Both props apply at every level of a
nested group.

### The order things happen in

1. **Row filters and search** run on the source, exactly as they do without
   grouping. Grouping never sees a row a filter removed.
2. **Grouping** partitions what survived, one level per `groupBy` key.
3. **`groupFilter`** drops whole groups — a dropped group takes its leaves with
   it, so the counts and totals that remain describe what is on screen.
4. **`groupSort`** orders the groups within each parent. Without it they keep
   the order the source's own sort produced.
5. **Leaf order inside a group is the source's**, always. Sorting a column sorts
   the rows within each group; it does not reorder the groups themselves —
   that is `groupSort`'s job, and keeping them separate is what lets you sort
   rows by name inside groups ordered by total.

Collapsed state is keyed by the group's path, so reordering or filtering groups
never opens or closes anything by accident.

## Footers and grand totals

`groupFooters` closes every group with a row carrying the same aggregates its
header carries:

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

<DataTable
  data={PEOPLE}
  columns={columns}
  rowKey={(r) => r.id}
  features={[
    groupingPanel("team", {
      groupAggregates: (rows) => ({ budget: sum(rows) }),
      groupFooters: true,
    }),
  ]}
  summaryRow={(rows) => ({ budget: sum(rows) })}
/>;
```

The totals then read at the bottom of a group as well as the top — which is
where the reader of a long group is by the time they want them. A footer shows
no chevron and no checkbox: the header already owns both. Nested groups each get
their own, innermost first, and a **collapsed** group shows none at all — its
header is already carrying the numbers, with nothing between them.

`summaryRow` is the table's grand total, and under grouping it totals the whole
filtered set rather than a page of it. The two compose: per-group footers, one
grand total.

On mobile the footer is a card of its own after the group's cards, captioned the
same way. Exports are unaffected — a footer is chrome, not a row, so a CSV
carries the data and nothing else.

Each footer is captioned through `labels.groupTotal`, translated in every
bundled locale, and carries `data-adapttable-part="group-footer-row"` /
`group-footer-cell` (plus the `groupFooterRow` / `groupFooterCell` class hooks
in `@adapttable/unstyled`).

## Nested groups

`groupingPanel` also takes an ordered list, and each key nests inside the one
before it:

```tsx
features={[groupingPanel(["team", "status"])]}
```

> Core (12)
> &nbsp;&nbsp;active (7)
> &nbsp;&nbsp;blocked (5)
> Platform (9)
> &nbsp;&nbsp;active (9)

Every header describes its **whole subtree**: the count beside "Core" is all
twelve of its people, and its `groupAggregates` cells total the same twelve.
Deeper levels indent by logical padding, so nesting mirrors in Arabic and
Hebrew without a second rule.

Each node collapses on its own — "Core > blocked" and "Platform > blocked" are
different groups with different keys, so closing one leaves the other open, and
closing a parent hides its whole subtree in one step. Collapsed keys serialize
exactly as they did with one level.

In the URL and in Saved Views the keys travel as one comma-separated value —
`?groupBy=team,status`. Session aggregation overrides travel beside them as
`groupAgg`, for example `groupAgg=budget:sum,headcount:count`. A single key
(`?groupBy=team`) and a list parse the same way, and `onGroupByChange` reports
the keys as a list.

## Example

```tsx
import { DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

interface Person {
  id: string;
  name: string;
  team: string;
  budget: number;
}

const PEOPLE: Person[] = [
  { id: "1", name: "Aisha", team: "Core", budget: 42_000 },
  { id: "2", name: "Jonas", team: "Platform", budget: 38_000 },
  { id: "3", name: "Mei", team: "Core", budget: 51_000 },
];

export function People() {
  return (
    <DataTable
      data={PEOPLE}
      columns={[
        { key: "name", sortable: true },
        { key: "team", sortable: true },
        {
          key: "budget",
          accessor: (r) => `$${r.budget.toLocaleString()}`,
          sortValue: (r) => r.budget,
        },
      ]}
      rowKey={(r) => r.id}
      features={[
        groupingPanel("team", {
          groupAggregates: (rows) => ({
            budget: (
              <b>
                ${rows.reduce((sum, r) => sum + r.budget, 0).toLocaleString()}
              </b>
            ),
          }),
        }),
      ]}
    />
  );
}
```

## How it works

- **Opt-in.** Compose `groupingPanel()` for user-configurable grouping. The
  source and URL state carry the resolved grouping value, but neither imports
  or mounts the feature.
- **One key or a list.** `groupingPanel("team")` starts with one level;
  `groupingPanel(["team", "status"])` starts nested, and users can add,
  remove, or reorder those keys from the panel.
- **Somewhere that can group.** Either the full filtered set is in memory
  (`allFilteredRows`) or the server returns group rows. A source that can do
  neither — `capabilities.grouping: false`, declared or inferred — renders
  ungrouped, says so in the status bar and warns in development. See
  [source capabilities](./data-tiers.md#what-a-source-can-do--capabilities).
- **Shared mapper.** `groupAggregates(rows)` uses the same `(rows) => cells`
  shape as `summaryRow` (`SummaryRowFn` on `@adapttable/react`); reuse
  one function for both if the math is identical — or build both with
  `aggregate()` (below).
- **Session aggregation overrides.** Each active column has its own operation.
  Reader choices overlay the developer's `aggregatable.default`, declared
  `groupAggregates`, or original `query.aggregates`. Removing a developer
  default writes `none`; **Restore defaults** clears the override map. The
  choices serialize as `groupAgg`, including host-defined ids.
- **Expand / collapse.** Groups start expanded. Collapse state can be paired
  with `useGroupCollapseUrlState`; `groupBy` and `groupAgg` use the table's
  ordinary URL state.
- **Selection.** When row checkboxes are enabled, each group header exposes a
  tri-state checkbox over its leaf rows.

## Aggregate without writing the maths

Every aggregation option — `aggregate()`, `aggregatable` columns, custom
operations and server aggregates — is on the [aggregation](./aggregation.md) page.

The mapper above is a function you write. When the sums are ordinary, declare
them instead and `aggregate()` returns that same mapper:

```tsx
import { aggregate } from "@adapttable/core";
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

<DataTable
  features={[
    groupingPanel("role", {
      groupAggregates: aggregate({ budget: "sum", team: "count" }, { columns }),
    }),
  ]}
  summaryRow={aggregate({ budget: "sum" }, { columns })}
  columns={columns}
  // …
/>;
```

Built in: `sum`, `avg`, `count`, `min`, `max`. Pass your own function for
anything else — it receives the values found for that column and returns the
cell:

```tsx
const distinct = (values) => new Set(values).size;
groupingPanel("team", { groupAggregates: aggregate({ team: distinct }) });
```

Passing `columns` lets values resolve through a column's `sortValue`, exactly
as sorting and grouping do, so a formatted cell still aggregates on its
underlying number. Add `format` to shape the result for display:

```tsx
aggregate(
  { budget: "sum" },
  { columns, format: (v) => (typeof v === "number" ? money.format(v) : v) }
);
```

Two behaviours worth knowing, because they are choices rather than accidents:
a missing value is skipped rather than counted as zero, so `count` reports the
values a column actually has; and while `sum` of nothing is `0`, `avg`, `min`
and `max` of nothing are `undefined` — an average of no numbers is
unanswerable, not zero.

## Reorder inside a group or move between groups

Compose `groupingPanel` and the kit's `rowReorder` feature together. A reorder
that stays inside one leaf group calls the ordinary handler with positions
scoped to that group. Crossing a boundary — by drag, arrows, mobile controls,
or **Move to group…** — calls
`onGroupMove(row, fromGroup, toGroup, position)`, passed in the second argument
of `rowReorder`:

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";
import { rowReorder } from "@adapttable/mantine/row-reorder";

features={[
  groupingPanel("team"),
  rowReorder(onRowReorder, { onGroupMove, movePolicy: "confirm" }),
]}
```

`RowGroupRef.levels` gives the host every grouping column and raw destination
value. `movePolicy` is `"never"` by default, `"confirm"` for a kit-native
confirmation, or `"auto"` for an immediate host write. See
[row reordering](./row-reordering.md) for the complete contract.

## Options

`groupingPanel(groupBy?, extras?)` — omit the first argument for an initially
empty user-configurable panel, or pass a column key / ordered list. Companion
options go in the second argument:

| Field / prop                | Type                                                            | Default | Description                                                                                       |
| --------------------------- | --------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `groupBy` (1st arg)         | `string \| readonly string[]`                                   | `[]`    | Initial ordered grouping keys. The panel, composed column menu, URL, and source can change them.  |
| `onGroupByChange`           | `(groupBy: readonly string[]) => void`                          | —       | Controlled change channel; falls back to `source.setGroupBy`.                                     |
| `groupAggregates`           | `(rows: readonly TRow[]) => Partial<Record<string, ReactNode>>` | —       | Per-group cells — **same signature as `summaryRow`**. Omit for headers without subtotals.         |
| `groupSort`                 | `GroupSort<TRow>`                                               | —       | `"label"`, `"label-desc"`, `"count"`, `"count-desc"`, or `(a, b) => number` over `GroupNode`s.    |
| `groupFilter`               | `(group: GroupNode<TRow>) => boolean`                           | —       | Keep only the groups this accepts — each group with its `value`, `label`, `level` and `leafRows`. |
| `groupFooters`              | `boolean`                                                       | `false` | Close every group with a footer row carrying its aggregates.                                      |
| `groupPageSize`             | `number`                                                        | —       | Top-level groups shown before a "Show more groups" row.                                           |
| `groupRowPageSize`          | `number`                                                        | —       | Rows shown per group before a "Show more in this group" row.                                      |
| `onGroupLoadMore`           | `(groupKey: string) => void`                                    | —       | Server tier: fetch the rest of a group.                                                           |
| `collapsedGroupIds`         | `readonly string[]`                                             | —       | Controlled collapsed group keys (ephemeral — not URL-synced).                                     |
| `onCollapsedGroupIdsChange` | `(ids: string[]) => void`                                       | —       | Controlled collapse channel; uncontrolled mode uses internal state.                               |

`labels` on `DataTable` overrides group headers, panel controls, menu actions,
aggregation names, and announcement templates.

## Grouped tables are a full-set view

With grouping active the table renders **every filtered row** (grouped),
and the chrome agrees with the screen: the footer count describes the
rendered set, header select-all covers all rendered rows, page-scope CSV
export contains exactly what you see, and the rows-per-page control hides
(page size has no effect). Ungroup to return to normal pagination.

## Headless grouping

The grouping model is exported so custom tables can render the same flat
structure the adapters do, at one level or nested:

| Export                                         | Purpose                                                                                        |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `buildGroupedFlatModel` / `GroupedFlatEntry`   | Partition leaf rows into a flat list — group header, then its leaves (omitted when collapsed). |
| `groupValueKey`                                | Stable, type-tagged string key for a group bucket (`5` and `"5"` never share one).             |
| `useGroupCollapse` / `GroupCollapseState`      | Ephemeral collapse state — groups default to expanded; not URL-synced.                         |
| `GroupAggregatesFn`                            | The `(rows) => Partial<Record<string, DisplayValue>>` mapper shared with `summaryRow`.         |
| `formatGroupLabel`                             | The header label for a bucket value (localized blank-value fallback included).                 |
| `groupSelectionState` / `HeaderSelectionState` | Tri-state for a group checkbox over its leaf ids — the same enum the header select-all uses.   |
| `windowGroupedEntries`                         | Slice a flat grouped model to a virtual window (see [Virtualization](./virtualization.md)).    |

The panel state is headless too. `GroupAggregateOverride` is an
`AggregateOperationId` (a built-in name or a custom operation id) or `"none"`,
and
`GroupAggregateOverrides` maps column keys to those choices.
`serializeGroupAggregateOverrides` / `parseGroupAggregateOverrides` implement
the `groupAgg` codec; `serializeAggregationDerivedKey` is the cache key for
the same effective operations. `withGroupAggregateOverrides` overlays choices on a
client mapper, and `withQueryAggregateOverrides` overlays them on server
aggregate requests. `GroupingPanel` on `@adapttable/<kit>/grouping-panel` is the
kit-wired panel for a host that places it itself; `useGroupPaging` (on
`@adapttable/react`) holds the "show more" state. Adapter authors build the
panel with `GroupingPanelChrome` and its required slots.

## Notes

- Bucketing uses the column's `groupValue`, then its `sortValue`, then a path
  lookup on the column's data path — its `i18n` entry for the active
  `locale`, else its key — never the JSX `accessor`.
- Works on desktop rows and mobile cards, LTR and RTL, with and without the
  `virtualize()` feature (virtual windows count collapsed groups as one row).
- The grouping panel configures row grouping and per-group aggregates.
  Pivoting remains a separate model — see [Pivot](./pivot.md).
- Ant Design maps group headers onto its high-level `Table` via custom row
  rendering; every other kit renders native group header rows/cards.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/) —
rows are grouped by team with a budget subtotal per group.

---

# React table aggregation — aggregate(), summaryRow & group totals

▶ **See it working:** [group totals, a footer grand total and pinned summaries in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/aggregation/) — filter the table and every total recomputes from the rows that remain. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

Aggregation turns rows into numbers the table shows beside them: a grand
total in the footer, a subtotal on every group, a reader's own choice of
Sum or Average under a column. All of it is opt-in. A table with no
`summaryRow`, no aggregating column and no grouping feature computes
nothing and renders no summary chrome.

There are three places a total can live, and each has one owner:

| Where                               | Declared with                                   | Computed from                       |
| ----------------------------------- | ----------------------------------------------- | ----------------------------------- |
| The table footer                    | `summaryRow` on `DataTable`                     | the rows the table is showing       |
| Every group's header and footer     | a column's `aggregatable`, or `groupAggregates` | each group's leaf rows              |
| Sticky rows above or below the list | `pinnedSummaryRows({ top, bottom })`            | nothing — the objects are host data |

## Example

```tsx
import { type ColumnDef, DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { groupingPanel } from "@adapttable/mantine/grouping-panel";
import { aggregate } from "@adapttable/react";

interface Deal {
  id: string;
  owner: string;
  region: string;
  amount: number;
  closedOn: string; // ISO date
}

const deals: Deal[] = [
  {
    id: "1",
    owner: "Aisha",
    region: "EMEA",
    amount: 42_000,
    closedOn: "2026-03-14",
  },
  {
    id: "2",
    owner: "Jonas",
    region: "EMEA",
    amount: 18_500,
    closedOn: "2026-05-02",
  },
  {
    id: "3",
    owner: "Mei",
    region: "APAC",
    amount: 61_000,
    closedOn: "2026-04-21",
  },
  {
    id: "4",
    owner: "Tom",
    region: "APAC",
    amount: 9_800,
    closedOn: "2026-06-30",
  },
];

const money = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 0,
});

const columns: ColumnDef<Deal>[] = [
  { key: "owner", sortable: true },
  { key: "region", sortable: true },
  {
    key: "amount",
    accessor: (row) => money.format(row.amount),
    sortValue: (row) => row.amount,
    filter: "numberRange",
    // Group cells start as Sum; readers may switch to any listed operation.
    aggregatable: {
      default: "sum",
      operations: ["sum", "avg", "min", "max", "count"],
    },
    // A count stays a count; every other number reads as money.
    formatAggregate: (value, { aggregation }) =>
      typeof value === "number" && aggregation !== "count"
        ? money.format(value)
        : String(value ?? ""),
  },
  // `true` reads the declared filter type: a date column offers Min, Max, Count.
  {
    key: "closedOn",
    header: "Closed",
    filter: "dateRange",
    aggregatable: true,
  },
];

export function Deals() {
  return (
    <DataTable
      data={deals}
      columns={columns}
      rowKey={(row) => row.id}
      summaryRow={aggregate(
        { amount: "sum" },
        {
          columns,
          format: (value) =>
            typeof value === "number" ? money.format(value) : value,
        }
      )}
      features={[groupingPanel("region", { groupFooters: true })]}
    />
  );
}
```

Each region opens with a Sum of `amount` in the amount column and closes
with a footer carrying the same number. The table footer holds the grand
total. From the grouping panel a reader can switch the amount to Average,
add Closed with Min or Max, or remove either.

## How it works

- **One mapper shape.** `summaryRow` and `groupAggregates` both take
  `(rows) => cells`: rows in, a record of cells keyed by column out. A key
  the record leaves out renders an empty cell. Write that function by hand,
  or let `aggregate()` build it.
- **`summaryRow` totals what the table shows.** On a paged table that is
  the current page. With grouping active the table renders every filtered
  row, and the footer totals all of them. It renders as a footer row
  aligned under its columns; `renderFooter` on a column replaces one of
  its cells and receives the mapper's value as `value`.
- **Group cells come from the columns.** A column's `aggregatable.default`
  calculates on every group with no mapper at all, on `grouping()` and
  `groupingPanel()` alike. `groupAggregates` in the grouping extras adds
  host-computed cells; reader choices overlay both.
- **Each subtotal sits under its column.** Group headers and footers place
  an aggregate in the cell of the column it totals. On a mobile card the
  same numbers are captioned by their column instead. The footer summary
  closes the card list as one card of its own.
- **Missing is not zero.** `undefined` and `null` are skipped before an
  aggregator runs, so `count` counts values a column actually has. `sum` of
  nothing is `0`; `avg`, `min` and `max` of nothing are `undefined`.

## Build a mapper with `aggregate()`

`aggregate(spec, options?)` returns the mapper from a declaration. The
spec maps a column key to a built-in name — `sum`, `avg`, `count`, `min`,
`max` — or to your own function, which receives the values found for that
column and returns the cell:

```tsx
const distinct = (values: readonly unknown[]) => new Set(values).size;

const amountSum = aggregate({ amount: "sum" }, { columns });
const summary = aggregate({ owner: distinct, amount: "avg" }, { columns });

<DataTable
  data={deals}
  columns={columns}
  rowKey={(row) => row.id}
  summaryRow={amountSum}
  features={[
    groupingPanel("region", { groupAggregates: amountSum, groupFooters: true }),
  ]}
/>;
```

Pass `columns` and values resolve through each column's `sortValue`, the
way sorting and grouping resolve them, so a money-formatted cell still
aggregates on its number. Without `columns`, values come from the key's
data path. `format(value, key)` shapes the result when it is computed.

`@adapttable/react` exports `aggregate` typed for React cells, so it drops
into `summaryRow` directly. `@adapttable/core` exports the same helper with
a framework-neutral cell type, for code that does not render React.

A mapper built by `aggregate()` also tells the table what it computes. The
grouping panel lists those columns under their operation names. A
hand-written mapper names no operation: its cells are listed as **Set by
the app**, or as a **Custom** item a reader may replace when the column is
`aggregatable`.

`min` and `max` compare numbers, `Date` values and strict ISO date,
datetime and time strings (`YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ssZ`, `HH:mm`).
Locale-formatted dates are skipped. The winning original value is what the
cell receives: a number, a `Date`, or that ISO string.

## Let readers choose: `aggregatable`

A column's `aggregatable` says whether a reader may aggregate it and with
which operations. It takes `false` (the default), `true`, or an
`AggregatableConfig`:

- `true` offers what suits the column's **declared** filter or editor
  type: all five for `number` / `numberRange`, Min / Max / Count for
  `date` / `dateRange` / `datetime` / `time`, and Count otherwise. It never
  samples row values.
- `{ operations, default? }` lists exactly what to offer. `default` must be
  one of `operations`; without it the column is on offer but inactive until
  a reader adds it. An empty `operations` list offers nothing.
- `false` or omitted refuses reader changes. A `groupAggregates` cell or a
  server aggregate on that column still shows, read-only.

`groupable: false` is a separate switch: it stops a column being grouped
by. Grouping a column does not remove its aggregation offer.

### Formatting with `formatAggregate`

`formatAggregate(value, context)` on a column decides how its aggregate
reads. `context.columnKey` names the column and `context.aggregation` the
operation that produced the value, when the table knows it — the reader's
choice, a column default, an `aggregate()` declaration, or the operation a
server was asked for. A hand-written mapper declares nothing, so
`aggregation` is absent for its cells.

It runs where a group cell is drawn — header, footer and mobile group card
— so the value the table holds, compares and exports stays the one the
aggregate returned. `summaryRow` cells do not pass through it; format those
with `aggregate({ … }, { format })`.

With both set on a group mapper, `format` runs first and `formatAggregate`
receives its result. Leave group aggregates raw and let the column own
presentation, or write `formatAggregate` to pass non-numbers through.

### Custom operations

An operation can be your own `CustomAggregateOperation` — an `id`, a
`label`, and optionally `calculate` and `description`:

```tsx
const median = (values: readonly unknown[]) => {
  const sorted = values
    .filter((value): value is number => typeof value === "number")
    .sort((a, b) => a - b);
  if (sorted.length === 0) return undefined;
  const mid = Math.floor(sorted.length / 2);
  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
};

{
  key: "amount",
  aggregatable: {
    default: "median",
    operations: [
      "sum",
      "avg",
      { id: "median", label: "Median", calculate: median },
      {
        id: "p90",
        label: "90th percentile",
        description: "The amount 90% of deals in the group stay under.",
      },
    ],
  },
}
```

- `id` is what state, the URL and a server request carry, so keep it
  stable. It cannot reuse a built-in name, `none` or `custom`; an invalid,
  duplicate or unknown entry is dropped with a development warning.
- `label` is what the reader sees. Built-in names are localized through
  `labels`; a custom label is yours to translate.
- `calculate` runs in the browser. Leave it out for an operation only the
  backend can answer — the table then offers it only when the source lists
  it in `supports.aggregateOperations`.
- `description` says what the operation means to anything reading the
  table rather than looking at it, such as an agent.

## Per-group aggregates and the grouping panel

`groupingPanel()` from `@adapttable/<kit>/grouping-panel` lists every
active aggregate as its own item — column name, operation selector, remove
— with **Add aggregation column**, and **Restore defaults** once the
reader has moved away from what the developer declared. Compose
`columnMenu()` as well and, while grouping is active, each column's menu
offers the same choice. Both surfaces read one `AggregationModel`, so a
column offers the same operations wherever a reader meets it. Every change
is announced through a polite live region.

Plain `grouping()` from `@adapttable/<kit>/grouping` has no panel, but it
still calculates column defaults, `groupAggregates` and choices restored
from the URL. Building, nesting and reordering group levels, group
footers, group sorting and paging are on the
[row grouping](./row-grouping.md) page.

### Reader choices: `GroupAggregateOverride`

A reader's choice for one column is a `GroupAggregateOverride`: an
operation id, or `"none"` (`AGGREGATE_SUPPRESSED`) when they removed an
aggregate the developer declared. `GroupAggregateOverrides` maps column
keys to those choices. They overlay the developer's setup and never
replace it — an untouched table has no overrides and stays at its
defaults, which still calculate.

`resolveEffectiveAggregation` from `@adapttable/core` decides what one
column shows, calculates and requests, in this order:

1. a valid reader override, or a permitted suppression (`override`,
   `suppressed`);
2. the column's `aggregatable.default`, when the source can execute it
   (`default`);
3. what the host's mapper or original server request already computes
   (`host`);
4. otherwise nothing (`inactive`).

A stale or disallowed id from any entry point — the panel, a URL, a saved
view — fails step 1 and falls through. `"none"` only removes a cell the
reader is allowed to control; a read-only host aggregate stays.

## Pinned totals

A total that is not computed from the visible rows — a target, a prior
period, a figure your backend returns — belongs in `pinnedSummaryRows`
from `@adapttable/<kit>/pinned-summary-rows`. Those rows stick above or
below the scroll window and never enter sort, filter, grouping, pagination
or selection. See [pinned summary rows](./pinned-summary-rows.md).

## Aggregates on the server

A server tier computes the aggregates itself. Declare the capability and
list the aggregates to request:

```tsx
import { DataTable, useQuerySource } from "@adapttable/mantine";
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

const source = useQuerySource<Deal, Params, Page>({
  usePaginatedQuery: useDealsQuery,
  selectPage: (page) => ({ rows: page.rows, total: page.total }),
  supports: {
    grouping: true,
    aggregates: true,
    aggregateOperations: ["sum", "avg", "min", "max", "count", "p90"],
  },
  aggregates: [{ key: "amount", fn: "sum" }],
  columns,
});

<DataTable
  source={source}
  columns={columns}
  rowKey={(row) => row.id}
  features={[groupingPanel("region")]}
/>;
```

- `query.aggregates` arrives as `[{ key, fn }]` and is sent only when the
  source declares `supports.aggregates`. With grouping active the server
  computes them per group and returns them on each `QueryGroupRow`'s
  `aggregates`; without grouping, over the whole result set.
- Reader choices and column defaults layer over the `aggregates` you
  declared before the request is sent. `columns` lets the source refuse an
  operation a column does not allow before it reaches the server.
- `supports.aggregateOperations` is the allowlist of ids the backend can
  compute. Without it, `aggregates: true` means the five built-ins; a local
  `calculate` is not proof the server knows an id.
- `formatAggregate` is told the operation the response on screen was
  computed with, not one still in flight. `useServerData` takes the same
  `supports`, `aggregates` and `columns`; a controlled `mode="server"` table
  echoes `responseKey` so the table can tie a response to its request. See
  [server tiers](./row-grouping.md#server-tiers).
- The table has no slot for a whole-set answer. Read it from your response
  and render it with `summaryRow` or `pinnedSummaryRows`.

## Options

`aggregate(spec, options?)` — `AggregateSpec` maps a column key to a
built-in name, a name registered with `registerAggregator`, or an
`Aggregator` function. `AggregateOptions<TRow>`:

| Option    | Type                                                                           | Default | Description                                                                           |
| --------- | ------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------- |
| `columns` | `readonly ColumnMetadata<TRow>[]`                                              | —       | Resolve values through each column's `sortValue`; without it, the key's data path.    |
| `format`  | `(value: DisplayValue \| undefined, key: string) => DisplayValue \| undefined` | —       | Shape the computed value. Runs when the value is computed.                            |
| `host`    | `FeatureHostState`                                                             | —       | The table the mapper runs in, for a call made outside one. The table binds it itself. |

Column fields:

| Field             | Type                                                    | Default | Description                                                                                    |
| ----------------- | ------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `aggregatable`    | `boolean \| AggregatableConfig`                         | `false` | What a reader may aggregate this column with. `true` reads the declared filter or editor type. |
| `formatAggregate` | `(value, context: AggregateFormatContext) => ReactNode` | —       | How a group aggregate of this column reads. Presentation only.                                 |
| `renderFooter`    | `(ctx: ColumnFooterContext<TRow>) => ReactNode`         | —       | Replace this column's `summaryRow` cell; `ctx.value` is the mapper's value.                    |

`AggregatableConfig`:

| Field        | Type                            | Default | Description                                                                        |
| ------------ | ------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `operations` | `readonly AggregateOperation[]` | —       | Built-in names and `{ id, label, calculate?, description? }` operations, in order. |
| `default`    | `string`                        | —       | The operation the column starts with; must be one of `operations`.                 |

Related props and options:

| Where                               | Field                          | Type                                                            | Description                                                  |
| ----------------------------------- | ------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------ |
| `DataTable`                         | `summaryRow`                   | `(rows: readonly TRow[]) => Partial<Record<string, ReactNode>>` | Footer cells for the rows the table shows.                   |
| `grouping` / `groupingPanel` extras | `groupAggregates`              | the same mapper shape                                           | Host-computed cells for each group.                          |
| `grouping` / `groupingPanel` extras | `groupFooters`                 | `boolean`                                                       | Close every group with a footer row carrying its aggregates. |
| `useQuerySource` / `useServerData`  | `aggregates`                   | `readonly QueryAggregate[]`                                     | Aggregates to request as `query.aggregates`.                 |
| `useQuerySource` / `useServerData`  | `supports.aggregates`          | `boolean`                                                       | The endpoint computes `query.aggregates`.                    |
| `useQuerySource` / `useServerData`  | `supports.aggregateOperations` | `readonly string[]`                                             | Operation ids the endpoint can compute.                      |

## URL state and saved views

Reader choices serialize as `groupAgg`, beside `groupBy`:
`?groupBy=region&groupAgg=amount:avg,closedOn:max`. `none` records a
removed developer default (`groupAgg=amount:none`); removing an aggregate
the reader added deletes its entry, and **Restore defaults** clears the
parameter. Column keys and operation ids are percent-encoded, so a custom
id containing a colon, comma or percent sign round-trips. With a `urlKey`
the parameter is prefixed like every other (`deals.groupAgg`). Saved Views
store the same state. `PARAM_GROUP_AGGREGATES` is the parameter name, and
`serializeGroupAggregateOverrides` / `parseGroupAggregateOverrides` are the
codec. See [URL state](./url-state.md) and [saved views](./saved-views.md).

`summaryRow`, `groupAggregates` and pinned summaries are code, not state:
nothing of them is written to the URL.

## Notes

- **RTL.** Aggregate cells follow their columns, so they mirror with the
  table. The grouping panel's operation labels and announcements ship in
  every bundled `@adapttable/i18n` locale. See [i18n and RTL](./i18n-rtl.md).
- **Keyboard and screen readers.** The panel's operation selector and
  remove button are kit-native controls, and every add, change, removal
  and restore is announced.
- **Agents.** `@adapttable/ai` changes the same reader choices through
  `view.setAggregations`, under the same rules. See
  [@adapttable/ai](./ai.md).
- **Pivot tables** aggregate across two axes with their own measures. See
  [pivot](./pivot.md).

Related: [row grouping](./row-grouping.md) ·
[pinned summary rows](./pinned-summary-rows.md) ·
[server queries](./server-queries.md) · [columns](./columns.md)

---

# React pivot table — rows, columns and measures

Grouping answers "what is the total per team". A pivot answers "what is the
total per team **per quarter**" — and that second dimension has to become
columns that were never in the data.

`@adapttable/core/pivot` is a separate entry, so a table that never pivots
never downloads the engine. It costs 2.1 KB gzipped to the tables that import
it and nothing to the rest, which the bundle budget checks on every build.

▶ **See it working:** [pivot in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/pivot/) — the same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

Three entries share the work: `@adapttable/core/pivot` holds the engine and the
codecs; `@adapttable/react/pivot` re-exports them and adds `pivotTableModel`,
`usePivotUrlState` and `PIVOT_ROW_COLUMN_KEY`; `@adapttable/<kit>/pivot` adds
the kit's `PivotPanel` to the core re-export.

## The shape

```tsx
import { pivot } from "@adapttable/core/pivot";

const result = pivot(sales, {
  rows: ["region", "team"], // down the side, outermost first
  columns: ["quarter"], // across the top
  measures: [{ key: "amount", agg: "sum" }],
});
```

`pivot` is the whole calculation and none of the rendering. It returns:

| Field          | What it is                                                            |
| -------------- | --------------------------------------------------------------------- |
| `columnLeaves` | The rendered columns, left to right — the order every row's cells use |
| `columnTree`   | The header tree, each node carrying the `span` its header cell needs  |
| `rows`         | Every line of the body, in render order                               |
| `rowDepth`     | How many dimensions are down the side                                 |

Each line has a `kind` — `"leaf"`, `"subtotal"` or `"grandTotal"` — a `depth`
for indentation, a `label`, a `count` of the source rows it covers, and one
cell per entry of `columnLeaves`.

## Rendering it with your kit

`pivot` returns data, and a pivot has three shapes an ordinary table does not:
header cells that span, a row-header area down the side, and lines that are
totals rather than data. `pivotTableModel` maps them onto mechanisms the table
already has, so the result goes straight into the `DataTable` you are already
using:

```tsx
import { DataTable } from "@adapttable/mantine";
import { pivot, pivotTableModel } from "@adapttable/react/pivot";

const result = pivot(sales, config, { collapsed });
const model = pivotTableModel(result, { fields, labels });

<DataTable
  data={model.rows}
  columns={model.columns}
  rowKey={model.rowKey}
  summaryRow={model.summaryRow}
/>;
```

The table is your kit's, with its own header groups, footer and sticky header —
nothing here draws a `<table>`:

| What the engine returns | What it becomes                                         |
| ----------------------- | ------------------------------------------------------- |
| `columnTree`            | `column.group`, one header row per level, spans and all |
| `columnLeaves`          | One column each, keyed `pivot-0`, `pivot-1`, …          |
| `rows`                  | The table's rows, keyed by the engine's own line key    |
| The grand-total line    | `summaryRow` — the column-aligned footer                |
| The grand-total column  | Its own header group, captioned from `labels`           |

The row-header column is keyed `PIVOT_ROW_COLUMN_KEY` (`"pivot-row"`) and each
measure column carries its `PivotColumnLeaf` in `column.meta.pivotLeaf`, so a
host can find the measure and the column path behind any cell.

Options are all optional: `fields` captions the measures (the same list the
panel takes), `labels` localizes the grand-total captions, `rowHeader` names the
corner cell — pass your row dimensions' captions, or take the localized "Rows" —
and `indent` is the pixels per nesting level down the side.

**The fold control is yours.** Core ships no user-facing controls, so
`renderRowHeader` hands you each body line and you render what it needs — a
subtotal line's `kind` says it is foldable and its `key` is the collapse key:

```tsx
pivotTableModel(result, {
  renderRowHeader: (row) =>
    row.kind === "subtotal" ? (
      <Button variant="subtle" onClick={() => toggle(row.key)}>
        {row.label}
      </Button>
    ) : (
      row.label
    ),
});
```

Rows that are totals are marked for styling: every row-header cell carries
`data-adapttable-part="pivot-row-header"` with a `data-pivot-kind` of `leaf`,
`subtotal` or `grandTotal`, and the row itself is yours through
`rowAppearance({ rowClassName })` from `@adapttable/<kit>/row-appearance`.

## Measures

A measure is a column key and an aggregation:

```tsx
measures: [
  { key: "amount", agg: "sum" },
  { key: "amount", agg: "count", label: "Deals" },
];
```

`sum`, `avg`, `count`, `min` and `max` are built in; anything else is a
function over the values found, the same `Aggregator` shape the summary row
and group aggregates take:

```tsx
measures: [{ key: "amount", agg: (values) => `${values.length} sales` }];
```

Every measure repeats under every column path, so two measures under three
quarters is six columns — the header tree's spans already account for it.

Values resolve through a column's `sortValue` when you pass `columns`, exactly
as sorting, grouping and the summary row do. A pivot that read raw fields
would disagree with the footer of the same table:

```tsx
pivot(sales, config, { columns });
```

The same options take `aggregators`, a `ReadonlyMap<string, Aggregator>` that
resolves a measure whose `agg` is a string naming a registered aggregator
rather than a built-in, and `format`,
`(value, measure) => DisplayValue | undefined`, which shapes each computed
cell.

## Subtotals, totals and collapsing

Subtotals are on by default: every level above the innermost gets a line, and
those lines come **before** their children rather than after. That is what
makes collapsing work — a collapsed group still shows its own line with its
own totals instead of vanishing.

```tsx
const result = pivot(sales, config, { collapsed: new Set(["EU"]) });
```

A subtotal line's `key` is its collapse key. Collapsing changes what is shown
and never what is computed: the grand total is the same number either way. Those
keys are what [the URL carries](#in-the-url), so a folded group travels with the
link.

Turn either off with `subtotals: false` / `grandTotals: false`. The grand-total
**column** only appears when something splits the columns — without column
dimensions it would repeat the only column there is.

## What it does not throw away

A row whose dimension value is missing gets its own bucket, labelled `—`
(`PIVOT_BLANK`), rather than being dropped. Rows falling into no bucket and
quietly disappearing is how a pivot table ends up lying about a total.

A value that is not summable is absent, not zero — a missing budget is not a
$0 budget, so a cell with nothing to add up reads as empty.

## Building the configuration

The panel a user drags fields around in is a separate concern from the pivot
itself, and the part of it that is not a widget lives here too:

```tsx
import {
  assignField,
  availableFields,
  moveField,
  removeField,
  setMeasureAgg,
  EMPTY_PIVOT_CONFIG,
} from "@adapttable/core/pivot";

const [config, setConfig] = useState(EMPTY_PIVOT_CONFIG);

setConfig(assignField(config, "team", "rows")); // put Team on the rows axis
setConfig(moveField(config, "rows", 1, -1)); // one step out — the keyboard path
setConfig(setMeasureAgg(config, 0, "avg"));
```

Every operation returns a new configuration and none of them can produce an
invalid one: placing a dimension on one axis takes it off the other rather than
pivoting the same field twice, an index past the end appends, and a step past
either end is a no-op rather than a wrap. Measures are the exception to "one
field, one axis" — summing and counting the same column in one pivot is an
ordinary thing to want, so `assignField` adds a measure rather than moving one.

`availableFields(fields, config)` is what the panel's unused list shows, and
`isPivotReady(config)` is false until something fills the cells — a pivot with
no measure is a half-built configuration, not an error.

## The configuration panel

`PivotPanelChrome` from `@adapttable/react/adapter` is the panel itself: three
zones, the fields in each, and the controls that move them. Structure, part
names, ordering and labels live in core; every visible control is a required
slot the adapter fills with its own kit's component, so a Mantine panel is
built from Mantine buttons and an antd panel from antd buttons.

Every adapter except `@adapttable/bootstrap` ships it pre-wired as
`PivotPanel`, from the kit root or `@adapttable/<kit>/pivot`, so a host imports
one component rather than assembling slots:

```tsx
import { PivotPanel } from "@adapttable/mantine";

<PivotPanel fields={fields} config={config} onChange={setConfig} />;
```

Underneath, `PivotPanel` is `PivotPanelChrome` with that kit's slots filled in:

```tsx
<PivotPanelChrome
  fields={fields}
  config={config}
  onChange={setConfig}
  slots={slots}
/>
```

Its `PivotPanelChromeProps` take the fields, the configuration and a change
handler — the panel never holds the configuration itself. `PivotPanelSlots`
names the five pieces a kit supplies, each with its own props type:
`PivotPanelSurfaceProps` for the body, `PivotZoneProps` for a titled zone,
`PivotFieldProps` for one field and its move/remove controls, `PivotAddProps`
for the control that adds a field, and `PivotAggProps` for a measure's
aggregation chooser.

Every pivot UI in every spreadsheet is drag-and-drop, and every one of them is
unusable without a mouse. This panel is keyboard-first instead: each field
carries buttons that move it one step, so the whole thing is drivable with Tab
and Enter. A kit that wants dragging can add it on top — nothing here forbids
it and nothing depends on it. The move controls are withheld at each end
rather than disabled, because a field at the top has nowhere up to go.

Drop it into a [side panel](./customization.md) as that panel's content, and
the pivot configuration lives beside the table rather than over it.

## Pivoting on the server

A pivot over ten million rows is not a browser's job. When the server can do
it, send the configuration and translate the answer:

```tsx
import { serverPivotResult } from "@adapttable/core/pivot";

const result = serverPivotResult(page, { config });
```

`serverPivotResult` is a translator, not a second engine. The server decides
the arithmetic and the ordering; core rebuilds the column tree, the spans and
the leaf ordering from the paths the server named, so the result is the _same_
`PivotResult` the local engine returns and every adapter renders one thing.

The wire format is small on purpose — a `QueryPivotPage`:

```ts
{
  // column-dimension paths, outermost value first, in display order.
  // One entry per PATH, not per rendered column: the measures multiply them.
  columns: [["EU", "Q1"], ["EU", "Q2"], ["US", "Q1"]],
  rows: [
    { path: ["EU"], cells: [30, 20, 0], totals: [50], subtotal: true },
    { path: ["EU", "Alpha"], cells: [30, 20, 0], totals: [50], count: 12 },
  ],
  total: { path: [], cells: [30, 20, 10], totals: [60] },
}
```

`count`, `subtotal`, `totals` and `total` are optional: a server that can pivot
but not count, or that has no subtotals, should not have to send empty fields to
say so. A cell the server omits is an empty cell, never a zero — the same rule
the local engine follows for a value that will not add up.

The grand-total **column** follows the local rule: it is there when
`grandTotals` is on, which is the default, and something splits the columns. Its
values are each line's `totals`, one per measure, because that column is
arithmetic rather than shape — summing sums is not how an average or a minimum
totals, so core does not guess it. Send `totals` and the column carries numbers;
omit it and the column is empty, like any other cell nobody sent; ask for
`grandTotals: false` and there is no column at all.

## In the URL

A pivot is the most expensive table state there is to rebuild by hand — two
axes, an order on each, and a measure list — which makes it the state most
worth putting in a link:

```tsx
import { PivotPanel } from "@adapttable/mantine";
import { pivot, usePivotUrlState } from "@adapttable/react/pivot";

const { config, onConfigChange, collapsed, onCollapsedChange } =
  usePivotUrlState();

const result = pivot(rows, config, { collapsed });

<PivotPanel fields={fields} config={config} onChange={onConfigChange} />;
```

The parameter is compact and readable rather than JSON in a query string:

```
?pivot=rows:region,team;cols:quarter;sum:amount;count:amount;sub:0;hide:EU/Alpha
```

Everything a reader can change travels: the two axes, the measures, the
subtotal and grand-total switches (`sub:0`, `grand:0`) and which groups are
folded (`hide:`). A link that carried the axes alone would reopen showing
numbers its sender had switched off, or lines they had folded away.

Only departures are written. Both switches default to on, so a parameter says
so by staying silent — which is also what makes the encoding backward
compatible: a link or a saved view from before those fields existed says
nothing about them and reads back exactly as it always did. A folded path is
percent-encoded per dimension value, so a team called `A/B` cannot split a path
in the wrong place, and `collapsed` hands straight to the engine.

`serializePivot` and `deserializePivot` are exported for saved views and
anywhere else a `PivotConfig` has to be stored; `serializePivotState` and
`deserializePivotState` are the same encoding including the folded set, as a
`PivotUrlState` (`config` and `collapsed`). The round trip is tested, not
assumed, and a hand-edited value degrades to a simpler pivot instead of
throwing — a URL is user input.

All four are also on [`@adapttable/core/query`](./server-queries.md#decoding-a-parameter-yourself),
the React-free entry, so a route handler can read the parameter a shared link
carries without importing the engine or React.

An empty pivot writes no parameter — folds included, since there is nothing to
fold — and `urlKey` namespaces it so two tables can share one URL.

A custom aggregator has no URL form, so a measure carrying one keeps working
in memory and is left out of the link. Writing `sum` instead would quietly
change what the link computes.

Related: [row grouping](./row-grouping.md) ·
[aggregation](./row-grouping.md#aggregate-without-writing-the-maths) · [API reference](./api.md)

---

# React table formulas — spreadsheet columns computed from your rows

▶ **See it working:** [type a formula and watch the column appear in the live demo](https://adapttable.orwamahmoud.com/react/demo/mantine/formulas/) — a real table you can click, not a recording.

A column whose value is `=[Unit Price] * Quantity`, typed by the user rather
than written by you.

`@adapttable/core/formula` is a separate entry, so a table with no computed
columns never downloads a parser. It costs 2.8 KB gzipped to the tables that
import it and nothing to the rest, which the bundle budget checks on every
build.

## The shape

```tsx
import { buildFormulaColumns } from "@adapttable/react/formula";

const {
  columns: computed,
  errors,
  cycles,
} = buildFormulaColumns<Row>([
  { key: "total", header: "Total", formula: "=[Unit Price] * Quantity" },
  { key: "withTax", header: "With tax", formula: "=total * 1.2" },
]);

<DataTable
  data={rows}
  columns={[...columns, ...computed]}
  rowKey={(r) => r.id}
/>;
```

`@adapttable/react/formula` returns kit-ready `ColumnDef`s. The same builder
on `@adapttable/core/formula` returns `ColumnMetadata` for React-free code.
Each spec may also carry `format: (value: FormulaValue) => string` to turn a
value into display text.

A formula may reference a data field or another formula column by name.
Bracket a name that contains spaces — `[Unit Price]` — which is why the
brackets exist rather than an escaping rule.

`errors` names the formulas that would not parse, with the parser's message;
`cycles` names the keys that reference each other in a loop. Both are reported
rather than thrown, because a formula bar has to show something useful while
someone is still typing, and half a formula is the normal state of one being
written.

## A formula is parsed, never evaluated

The rule the parser exists to keep: **a formula is text, and it is parsed.**
It never reaches `eval`, `new Function`, or anything else that would run it as
JavaScript.

A user-typed formula is untrusted input in exactly the way a URL is. A table
that evaluates one has handed the page to whoever typed it — and in a
[saved view](./saved-views.md) that can be shared, to whoever sent the link.

The grammar is deliberately small, because a formula language grows one "just
add" at a time until it is a programming language nobody can secure:

```
expression → comparison
comparison → concat ( ("=" | "<>" | "<" | "<=" | ">" | ">=") concat )?
concat     → sum ( "&" sum )*
sum        → product ( ("+" | "-") product )*
product    → unary ( ("*" | "/") unary )*
unary      → "-" unary | primary
primary    → number | string | reference | call | "(" expression ")"
```

`&` concatenates, as it does in a spreadsheet, and it binds **below** `+` and
`-`: `="a" & 2 + 3` is `"a5"`, because the arithmetic finishes before the join.
Comparisons bind loosest of all, so `="a" & "b" = "ab"` compares two whole
strings and is `TRUE`.

## Not supported, knowingly

`^` (exponent) and scientific notation (`1e5`) are outside the grammar. Both
are **reported**, never reinterpreted: `parseFormula` answers `ok: false` with
the character it stopped on, `buildFormulaColumns` names the column in
`errors`, and that column's cells read `#ERROR!`. Write `x * x` for a square.

The absence is deliberate — a formula language grows one "just add" at a time —
and an absence that says so beats one that quietly reads `1e5` as `1`.

## Values are tagged, and errors are values

A value is `{ kind: "number" | "text" | "boolean" | "blank" | "error" }`
rather than a bare union of primitives. That costs a `.kind` at every use and
buys two things.

An error stops being a string. With sentinel strings, data that genuinely
contains the text `#REF!` is indistinguishable from a cell that failed —
`isFormulaError` can tell them apart because one is tagged and the other is
not.

And a formula that cannot produce a number produces an error value rather than
throwing: `#DIV/0!`, `#VALUE!`, `#NAME?`, `#CYCLE!`, `#ERROR!`. They propagate
the way a spreadsheet's do — an error inside `SUM(a, b)` comes out of the
`SUM` instead of being counted as zero, so a wrong number never gets quietly
totalled. `COALESCE` is the one function that deliberately does not propagate,
because answering "what should I use when this is missing" is its whole job.

A field the engine has no kind for — an object, a function — is `#VALUE!`
rather than its stringification. `[object Object]` in a cell is not a
rendering of the data; it is a rendering of nobody having decided. A field that
is `NaN`, `Infinity` or an invalid date is `#VALUE!` too, and so is any result
too large to be a number — an overflowing product, sum or `ROUND` — so a
formula's answer is always a finite number or an error.

## Functions

| Function                                      | Result                                                                          |
| --------------------------------------------- | ------------------------------------------------------------------------------- |
| `SUM(values…)`                                | Sum after numeric coercion; non-numeric text is skipped.                        |
| `AVG(values…)`                                | Mean after numeric coercion; no numbers returns `#DIV/0!`.                      |
| `MIN(values…)` / `MAX(values…)`               | Smallest or largest value after numeric coercion; no numbers returns `0`.       |
| `ABS(value)`                                  | Absolute numeric value.                                                         |
| `ROUND(value, places)`                        | Number rounded to the requested decimal places.                                 |
| `POWER(base, exponent)`                       | `base` raised to `exponent`; a non-real or non-finite result returns `#VALUE!`. |
| `SQRT(value)`                                 | Square root; a negative value returns `#VALUE!`.                                |
| `IF(test, yes, no)`                           | One branch selected by spreadsheet truthiness.                                  |
| `AND(values…)` / `OR(values…)` / `NOT(value)` | Boolean logic.                                                                  |
| `CONCAT(values…)`                             | Values joined as text.                                                          |
| `LEN(value)`                                  | Length of the displayed text.                                                   |
| `UPPER(value)` / `LOWER(value)`               | Text converted to upper or lower case.                                          |
| `COALESCE(values…)`                           | First value that is neither blank nor an error.                                 |

For compound growth, write `=POWER(1 + rate, years)`. `POWER` and `SQRT` are
functions only: they do not expand the grammar or reinterpret the unsupported
`^` operator.

## Sorting and export

A formula column sorts by its **value**, never by the text in the cell. A
number orders numerically however it is formatted, so `$1,240.00` cannot land
before `$90.00`; `=UPPER(name)` orders alphabetically; a boolean puts `FALSE`
before `TRUE`.

A blank and an error have no place in an ordering, so both group at the **end**
of the column — in either direction, the way a spreadsheet leaves an error —
and rows tied there keep the order they already had. What matters is not the
order among broken cells but that they collect somewhere predictable instead of
being counted as zero and scattered among real values.

Export receives the same value a spreadsheet would. Formatting is never applied
to an error: showing `#DIV/0!` as `$#DIV/0!` would hide which cell went wrong.

## Share and save formulas

A typed formula is the one piece of table state nobody can rebuild from memory,
because the table never offered it — someone wrote it. So it travels in the URL
with sort, filters and the pivot:

```tsx
import {
  buildFormulaColumns,
  useFormulaUrlState,
} from "@adapttable/react/formula";

const { formulas, onFormulasChange } = useFormulaUrlState({
  urlKey: "people",
  defaultFormulas: [
    { key: "total", header: "Total", formula: "=[Unit Price] * Quantity" },
  ],
});
const {
  columns: computed,
  errors,
  cycles,
} = buildFormulaColumns<Row>(formulas);
```

The parameter is `formula=total:%3D%5BUnit%20Price%5D%20*%20Quantity:Total`
(`people.formula=` with the `urlKey` above) — one `key:formula[:header]` entry
per column, `;`-separated, every field percent-encoded so a formula may contain
the delimiters. One URL carries at most 24 formula columns, and a `format`
function stays in memory rather than in the link. Writes are debounced
(`FORMULA_URL_WRITE_DEBOUNCE_MS`, on `@adapttable/react/formula`), so a bar that writes while someone types
does not out-run Safari's `replaceState` limit; reads stay instant.

[Saved views](./saved-views.md) capture the parameter with the rest of the
table's state, so "Margin analysis" is a view like any other. A view saved
before formula columns existed carries none, and applying it clears them — the
same thing a pre-pivot view does to a live pivot.

`serializeFormulaColumns` and `deserializeFormulaColumns` are the encoding on
its own, exported from `@adapttable/core/formula` and from the React-free
`@adapttable/core/query` — the entry a route handler, loader or plain Node
service imports to read a shared link. **Reading never evaluates.** The codec
hands back the text; a hand-edited entry it cannot make sense of is dropped,
and a formula that will not parse arrives as the text it is, because half a
formula is the normal state of one being written.

## Building a formula bar

`FORMULA_FUNCTIONS` lists the function names the engine knows, for an
autocomplete. `parseFormula` returns a tree or the reason it could not, and
`formulaRefs` names the columns a formula depends on. `evaluateFormula`,
`toFormulaValue`, `formulaDisplay`, `formulaSortValue`, `isFormulaError`,
`FORMULA_ERRORS`, `FORMULA_BLANK` and the `formulaNumber` / `formulaText` /
`formulaBoolean` / `formulaError` constructors are the engine's pieces on their
own.

Related: [pivot tables](./pivot.md) · [row grouping](./row-grouping.md) ·
[API reference](./api.md)

---

# React table tree data — hierarchical rows with expand/collapse

Some data is a hierarchy before anyone asks a question of it: a folder holds
files, a task has subtasks, an account rolls up to a parent. Compose `tree()`
from `@adapttable/<kit>/tree` with `getChildren` (nested data) or `getParentId`
(a flat list with a parent column) and the table renders that hierarchy — one
chevron per parent, one indent step per level, in every adapter that ships the
subpath (all except `@adapttable/bootstrap`).

▶ **See it working:** [tree data in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/tree/) — the same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

```tsx
import { DataTable } from "@adapttable/mantine";
import { tree } from "@adapttable/mantine/tree";

<DataTable
  data={FILES}
  columns={columns}
  rowKey={(row) => row.id}
  features={[tree({ getChildren: (row) => row.children })]}
/>;
```

Without the `tree()` feature the table renders a flat list. The shape comes from
the data: `tree()` only says how to read it.

## A tree is not a grouping

They look alike and behave nothing alike, so AdaptTable ships them as two
models rather than one with a flag:

|                            | `grouping()` / `groupingPanel()` | `tree({ getChildren \| getParentId })` |
| -------------------------- | -------------------------------- | -------------------------------------- |
| Where the shape comes from | a value the reader picked        | the rows themselves                    |
| Re-sorting a column        | regroups                         | leaves the hierarchy alone             |
| Depth                      | the grouping keys                | whatever the data has                  |
| A parent row               | a synthetic header               | a real row with real cells             |

Sharing one implementation would mean either grouping that cannot express a
real hierarchy, or a tree that reshuffles when someone sorts a column. The body
draws one of them at a time: with grouping armed, a table that also declares a
tree shows the groups, and their rows carry no tree chevrons. Row pinning is
refused under either.

## Which column carries the chevron

The first visible column, unless `treeColumn` names another:

```tsx
<DataTable {...props} features={[tree({ getChildren, treeColumn: "name" })]} />
```

The chevron and the indent go in that column's cell, wrapping its content — so
the name steps in with its depth, not just the chevron. A leaf gets a spacer the
same width as a chevron, so a folder's children line up under its name rather
than under its disclosure control.

## Holding the open set

Uncontrolled by default — the table remembers which nodes are open. Pass
`expandedIds` to own it, and `onExpandedIdsChange` to hear about clicks:

```tsx
const [expandedIds, setExpandedIds] = useState<string[]>(["src"]);

<DataTable
  {...props}
  features={[
    tree({ getChildren, expandedIds, onExpandedIdsChange: setExpandedIds }),
  ]}
/>;
```

A tree starts folded, so the state is the set that is **open** — an empty array
is a closed tree, not an expanded one.

## A flat list with a parent column

The commonest shape out of a database is one table with a `parentId`. Read it
with `getParentId` and the table assembles the hierarchy itself:

```tsx
<DataTable
  data={rows} // [{ id: "1" }, { id: "2", parentId: "1" }]
  columns={columns}
  rowKey={(row) => row.id}
  features={[tree({ getParentId: (row) => row.parentId })]}
/>
```

Rows whose parent is not in the data are roots — so a filtered page still
renders rather than vanishing into a parent that never arrived.

## Children fetched when a branch is opened

A hierarchy of any size cannot arrive whole. Say which rows have children the
browser has not fetched, and what to do when one is opened:

```tsx
<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    tree({
      getChildren: (row) => row.children,
      hasChildren: (row) => row.childCount > 0,
      onLoadChildren: async (row) => {
        const children = await fetchChildren(row.id);
        setRows((current) => withChildren(current, row.id, children));
      },
    }),
  ]}
/>
```

`hasChildren` is what draws a chevron on a node with nothing under it yet.
`onLoadChildren` fires once per node — the second click while a request is out
does not ask again — and resolves when the children are in the data the table
reads; the table re-walks the hierarchy itself and needs nothing back.

The node **opens immediately** and shows it is working: its chevron carries
`data-loading` and `aria-busy` until the rows land, so nobody is left clicking a
control that appears to do nothing. A rejection clears the flag, records the node
in `failedIds` and closes it again, so the next click retries the fetch.

Headless: `useLazyChildren` holds the state (`LazyChildrenState`, options
`UseLazyChildrenOptions`, with `onLoadFailed` called on a rejection) and the table's tree bundle exposes `loadingIds` and
`failedIds`.

## The whole tree on the server

A browser holding one page cannot know what is under a branch it has never seen,
so a large hierarchy belongs to the side that has the data. Declare the
capability and hand the source the open set:

```tsx
import { DataTable, useQuerySource } from "@adapttable/mantine";
import { tree } from "@adapttable/mantine/tree";

const [expandedIds, setExpandedIds] = useState<string[]>([]);

const source = useQuerySource<Node, Params, Page>({
  usePaginatedQuery: useFilesQuery,
  supports: { tree: true },
  expandedIds,
});

<DataTable
  source={source}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    tree({
      getParentId: (row) => row.parentId,
      hasChildren: (row) => row.childCount > 0,
      expandedIds,
      onExpandedIdsChange: setExpandedIds,
    }),
  ]}
/>;
```

The query carries `expandedIds` — the ids the reader has open — and the response
returns the rows of the tree that are visible: the roots, plus the children of
every open node, each with its `parentId`. The table assembles the hierarchy from
what arrived, so no row model changes between tiers.

Without `supports: { tree: true }` the field is never sent, and development says
so once rather than letting a server quietly ignore it. The same is true of
`useServerData`, which takes `expandedIds` in the same place.

## Mobile

Cards keep the hierarchy. Each card steps in by its depth (logical margin, so
it steps from the right in Arabic and Hebrew) and carries the same chevron,
which folds the same nodes. A phone gets a tree, not a flattened list.

## A real table under a row

The full contract is on the [nested tables](./nested-tables.md) page.

▶ **See it working:** [nested tables in Mantine](https://adapttable.orwamahmoud.com/react/demo/mantine/nested-tables/) — open a person onto their orders; the inner table is the same component. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

`rowDetail()` gives a blank panel, and a table built by hand in one has none
of the sorting, filtering, selection, keyboard navigation or accessibility the
outer table has. `nestedTable()` from `@adapttable/<kit>/nested-table` puts the
same component in there instead:

```tsx
import { DataTable } from "@adapttable/mantine";
import { nestedTable } from "@adapttable/mantine/nested-table";

<DataTable
  data={people}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    nestedTable((row) => ({
      label: `Orders for ${row.name}`,
      table: (defaults) => (
        <DataTable
          {...defaults}
          data={row.orders}
          columns={orderColumns}
          rowKey={(order) => order.id}
        />
      ),
    })),
  ]}
/>;
```

The child rows keep their own type — the closure holds it, so nothing is erased
at a prop boundary — and the row gets the same expand chevron `rowDetail()`
gives it.

`defaults` carries what a table inside a row cannot do without: `urlSync: false`
(two tables writing `?page=` fight over one URL, and the loser silently resets
while the reader is using it), `searchable: false` (a second search box inside a
row reads as chrome, not as a feature — pass `searchable` after the spread to
keep it), the parent's `density` and `labels`, and `tableLabel` (the `label` you
gave, "Row details" when omitted). Spread them first and override anything
after.

Return `undefined` for a row with no nested table. With `rowDetail(render)`
composed beside it, those rows fall back to that panel, so master/detail and
nested tables can live in one table. The region carries
`data-adapttable-part="nested-table"` and is announced with the label you gave
it. The second argument, `nestedTable(nested, defaultExpandedRowIds)`, opens
those rows on the first render so the inner table is visible without a click.

## Reorder siblings or change parent

Compose the kit's `rowReorder` feature with `tree`. Before/after drops reorder
rows that already share a parent; the ordinary reorder handler receives
sibling positions. A middle drop, **Move under…**, or **Move to top level**
uses `onTreeMove(row, fromParent, toParent, position)`, passed in the second
argument of `rowReorder`:

```tsx
import { rowReorder } from "@adapttable/mantine/row-reorder";
import { tree } from "@adapttable/mantine/tree";

features={[
  tree({ getParentId: (row) => row.parentId }),
  rowReorder(onRowReorder, { onTreeMove, movePolicy: "confirm" }),
]}
```

Set `movePolicy` to `"auto"`, `"confirm"`, or `"never"` (the default).
Confirmation is kit-native and restores focus to its menu trigger; a host can
instead provide async `confirmMove`. The same controls appear on mobile cards
and follow logical direction in RTL.

The tree model carries each node's `parentId`, `siblingIndex`, and complete
`descendantIds`. Re-parenting is rejected before the host callback when the
target is the node itself or a descendant, so pointer and menu paths cannot
create a cycle. See [row reordering](./row-reordering.md) for the full write
contract and sorted-state rule.

## Headless pieces

Everything above is composed from exports you can use directly when you render
your own body:

- `buildTreeEntries(options: BuildTreeEntriesOptions<TRow>)` — flattens a
  hierarchy into `TreeEntry<TRow>[]` in reading order. A collapsed node
  contributes itself and nothing beneath it. Each entry carries `level`,
  `hasChildren`, `expanded`, `path`, `descendantIds` (the whole subtree, folded
  or not, so ticking a folder can tick what is in it) and `loading`.
- `TreeShape<TRow>` — the three ways a host declares the hierarchy:
  `getChildren`, `getParentId`, and `hasChildren` for children that have not
  been fetched yet.
- `useTreeExpansion(options)` → `TreeExpansionState` — the open set, controlled
  or not, with `toggle`, `expand`, `collapse`, `isExpanded`.
- `filterTreeRows(options)` — keeps matching rows **and every ancestor that
  leads to one**, so a filtered tree still has a path to what it found.
- `treeColumnKey(columns, declared?)` — which column carries the chevron.
- `treeIndentStyle(level)` — the cell's indent (`paddingInlineStart`).
- `treeCardStyle(level)` — the card's indent (`marginInlineStart`).
- `bodyRowEntries(rows, tree)` → `BodyRowEntry<TRow>[]` — the rows a body
  renders: the tree's visible entries when a tree is armed, the windowed rows
  otherwise. One `.map` either way.
- `TreeCell` (on the antd, Base UI, Chakra, Mantine, MUI, Radix and unstyled
  adapters, props `TreeCellProps<TRow>`) — wraps the
  tree column's cell in its chevron and its indent, and passes every
  other column through untouched. The indent goes on the wrapper around the
  content, so a name moves with its depth rather than sitting at the same margin
  as its parent's. Layout is `TreeCellChrome` on `@adapttable/react/adapter`.
- `TreeToggle` (on the same adapters, props `TreeToggleProps<TRow>`) — the
  chevron itself: `aria-expanded`, a localized accessible name, and an
  equal-width spacer on a leaf. Layout is `TreeToggleChrome`.

## Styling hooks

Every adapter stamps `data-adapttable-part` on each piece: `tree-cell` (the
indented wrapper), `tree-toggle` (the chevron), and `tree-spacer` (a leaf's
placeholder). A node whose children are loading carries `data-loading` and
`aria-busy` on its toggle.

---

# React table column management — rename, show, hide, reorder, pin & resize

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — this page's features are already wired in `src/App.tsx` (`columnMenu()` + `resizableColumns()`); edit it in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [rename, pin, resize and reorder columns in the live demo](https://adapttable.orwamahmoud.com/react/demo/mantine/columns/) — a real table you can edit and drag, not a recording.

Let users rename, show/hide, reorder, pin, and resize columns — compose one factory per
capability from `@adapttable/<kit>/<feature>`, with the resulting layout
persistable to the URL or localStorage. The import is the switch: `<DataTable>`
has no `enableColumnMenu` or `resizableColumns` prop. See
[feature composition](./features.md). Every adapter shares the same engine from
`@adapttable/core`.

## Example

```tsx
import { useColumnLayoutStorageState } from "@adapttable/react";
import { type ColumnDef, DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { columnMenu } from "@adapttable/mantine/column-menu";
import { resizableColumns } from "@adapttable/mantine/resizable-columns";
import { rowActions } from "@adapttable/mantine/row-actions";
import { useState } from "react";

interface Person {
  id: string;
  name: string;
  department: { name: string };
  city: string;
  salary: number;
  hiredAt: string;
}

const people: Person[] = [
  {
    id: "1",
    name: "Amira Hassan",
    department: { name: "Engineering" },
    city: "Dubai",
    salary: 96000,
    hiredAt: "2021-03-15",
  },
  {
    id: "2",
    name: "Tom Becker",
    department: { name: "Design" },
    city: "Berlin",
    salary: 78000,
    hiredAt: "2022-11-01",
  },
  {
    id: "3",
    name: "Lina Park",
    department: { name: "Engineering" },
    city: "Seoul",
    salary: 105000,
    hiredAt: "2019-07-20",
  },
];

const initialColumns: ColumnDef<Person>[] = [
  { key: "name", width: 200, renameable: true },
  { key: "department.name", header: "Department", width: 160 },
  { key: "city", width: 140 },
  { key: "salary", align: "end", width: 140 },
  { key: "hiredAt", width: 140 },
];

export function People() {
  const [columns, setColumns] = useState(initialColumns);
  // Persist the user's layout to localStorage; swap for useColumnLayoutUrlState
  // (from @adapttable/react) to make it part of shareable links instead.
  const { layout, onLayoutChange } = useColumnLayoutStorageState({
    storageKey: "people-table-columns",
    defaultColumnLayout: { pinned: { name: "start" } },
  });

  return (
    <DataTable
      data={people}
      columns={columns}
      rowKey={(r) => r.id}
      features={[
        columnMenu(), // Columns menu: rename, show/hide, reorder, pin
        resizableColumns(), // drag or arrow-key resize handles
        rowActions([
          { key: "edit", label: "Edit", onClick: (r) => console.log(r) },
        ]),
      ]}
      maxHeight={420} // scroll box so pinned columns visibly stick
      columnLayout={layout}
      onColumnLayoutChange={onLayoutChange}
      onColumnRename={(key, name) => {
        // The table updates its layout immediately. Persist the accepted
        // domain name in the host just like an edited cell value.
        setColumns((current) =>
          current.map((column) =>
            column.key === key ? { ...column, header: name } : column
          )
        );
      }}
    />
  );
}
```

## How it works

- `columnMenu()` renders the built-in Columns menu: a search box, bulk show/hide/unpin, a visibility toggle per column, drag- or arrow-key reorder on each row's grip, a pin control, a per-column submenu (sort, pin, hide, auto-size, filter, rename, reset one), auto-size-all, and reset-all. Hiding a column never reorders the rest. `lockPosition` / `lockVisibility` / `lockWidth` / `lockPin` on a `ColumnDef` gray out the matching controls.
- Set `renameable: true` on a column and provide `onColumnRename(key, name)` to offer **Rename column**. The kit-native inline form keeps a visible label, trims on save, rejects a blank name, commits with Enter, cancels with Escape, restores focus, and announces the completed rename to screen readers. The key never changes.
- Semantic-table adapters also put a small, named rename control beside the
  header caption for a direct path. Ant Design keeps the menu path because its
  native sorted title and sticky header clone own that hit target; keyboard
  users retain the same complete rename form through the Columns menu.
- The layout applies the accepted name immediately to desktop headers, mobile labels, the Columns menu, exports and accessible column names. The callback lets the host persist the domain name and update its `columns` definition; doing so also updates any column-derived filter label. An explicitly named standalone filter keeps its own label. Reset restores the declaration captured when that override began; a controlled echo of the custom name does not redefine the reset target. After the host writes the reset name back — or later changes the schema label — the next rename uses the current declared name, not a historical override.
- Pinning is logical (`"start"` / `"end"`), so a `"start"` pin sticks to the inline-start edge — the right edge under `dir="rtl"`. It needs a horizontal scroll context to visibly stick — set `maxHeight`, or let the table exceed its container width.
- `resizableColumns()` adds a handle to every header: drag it, or focus it and press ←/→ (16 px per step, 60 px minimum). Direction-aware, so it widens the right way in RTL.
- The row-actions column is first-class under the reserved key `"actions"` (`ACTIONS_COLUMN_KEY`): the menu lists it with a visibility toggle and an end-pin toggle — `hidden: ["actions"]` hides it, `pinned: { actions: "end" }` pins it to the end on its own, no data-column pin required. It never reorders or resizes; it always trails.
- The layout state is `{ hidden, order, pinned, widths, names?, collapsedGroups? }` (`ColumnLayoutState`), keyed by column key. Uncontrolled by default; seed it with `defaultColumnLayout`, or own it with `columnLayout` + `onColumnLayoutChange` — the same controlled/uncontrolled split as a form input. `names` and `collapsedGroups` are omitted when they carry no override.
- Two ready-made persistence hooks feed the controlled mode: `useColumnLayoutUrlState({ urlKey })` keeps the layout in the query string (`colHide` / `colPin` / `colOrder` / `colW` / `colName` / `colGroupCollapse` — shareable links and Saved Views), and `useColumnLayoutStorageState({ storageKey })` keeps it in localStorage (user preference).

## Options

| Factory / prop                                              | Type                                  | Default | Description                                                                                                                    |
| ----------------------------------------------------------- | ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `columnMenu()`                                              | —                                     | off     | Factory from `@adapttable/<kit>/column-menu`; composes the Columns menu (show/hide, pin, reorder).                             |
| `resizableColumns()`                                        | —                                     | off     | Factory from `@adapttable/<kit>/resizable-columns`; drag/keyboard column-resize handles.                                       |
| `fitColumns()`                                              | —                                     | off     | Factory from `@adapttable/<kit>/fit-columns`; columns share the container width.                                               |
| `collapsibleColumnGroups()`                                 | —                                     | off     | Factory from `@adapttable/<kit>/column-groups`; group headers gain a collapse toggle. See [column groups](./column-groups.md). |
| `columnSelectionCheckbox()`                                 | —                                     | off     | Factory from `@adapttable/<kit>/column-selection`; a checkbox in each header selects that column. Needs `cellNavigation()`.    |
| `lockPosition` / `lockVisibility` / `lockWidth` / `lockPin` | `boolean` (per `ColumnDef`)           | `false` | Gray out the reorder grip, show/hide toggle, resize and auto-size, or pin control for that column.                             |
| `defaultColumnLayout`                                       | `Partial<ColumnLayoutState>`          | —       | Initial layout for the uncontrolled mode.                                                                                      |
| `columnLayout`                                              | `ColumnLayoutState`                   | —       | Controlled layout (hidden/order/pinned/widths/names/collapsedGroups).                                                          |
| `onColumnLayoutChange`                                      | `(next: ColumnLayoutState) => void`   | —       | Change handler for the controlled layout.                                                                                      |
| `renameable`                                                | `boolean`                             | `false` | Per-column opt-in for the kit-native rename action.                                                                            |
| `onColumnRename`                                            | `(key: string, name: string) => void` | —       | Host persistence callback; required before rename controls are offered.                                                        |
| `maxHeight`                                                 | `number`                              | —       | Fixed-height scroll box (px); enables sideways scroll + visible pinning.                                                       |

Custom per-column menu actions register through `host.registerColumnMenuAction`
in a feature's `setup` — see [feature composition](./features.md).

## Notes

- Give pinned columns numeric pixel `width`s: sticky insets are summed from them, and a relative width (`"20%"`) falls back to a 150 px estimate, so adjacent pins may not stack exactly.
- A hidden pinned column reads back as unpinned until it is shown again — only visible columns have a cell to stick.
- `useColumnLayoutUrlState` debounces URL writes by 150 ms (a resize drag commits per animation frame; unthrottled `replaceState` trips Safari's rate limit). Reads stay instant.
- `useColumnLayoutStorageState` removes its stored entry when the layout returns to the exact default, so defaults can evolve in later releases; it is SSR-safe (memory-only without a browser).
- Layouts are keyed by column `key` — renaming a key orphans any persisted layout for it (the column reappears with default placement).
- `defaultColumnLayout` only applies in uncontrolled mode; once you pass `columnLayout`, the controlled value is the single source of truth (the persistence hooks take their own `defaultColumnLayout`).
- **SSR-safe persistence**: a stored layout hydrates in an effect AFTER the
  first client render, so server and client markup always match — expect one
  paint with the default layout before the stored one applies. Blocked
  storage (Safari private mode, sandboxed webviews) is tolerated silently.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

## Widths, bounds and shares

A column can say how wide it is three ways, and they compose:

```tsx
const columns = [
  { key: "id", header: "ID", width: 80 }, // exactly this
  { key: "name", header: "Name", minWidth: 160 }, // never narrower
  { key: "note", header: "Note", flex: 2 }, // twice the leftover space
];
```

`minWidth` and `maxWidth` are bounds the column keeps whatever else happens — a
resize will not cross them, and neither will the fitting mode. `flex` asks for a
share of whatever space is left over.

### Filling the container

By default a table takes the width its columns need and scrolls when that is
more than the container. Compose `fitColumns()` to reverse it: the columns
share the container instead.

```tsx
import { fitColumns } from "@adapttable/mantine/fit-columns";

<DataTable
  data={rows}
  columns={columns}
  rowKey={rowKey}
  features={[fitColumns()]}
/>;
```

Columns with a `width` keep it, columns with a `flex` take that share, and
everything else divides what remains equally. A width the **user** dragged wins
over all of it — they said what they wanted.

Underneath it is CSS the browser already knows: a fixed table layout with
percentage widths shares space proportionally, and the bounds clamp it. The Ant
Design adapter renders through antd's own `<Table>`, which sets its own layout
mode; the per-column widths, bounds and shares still apply there.

## Sizing a column to its content

Double-click a resize handle and that column takes the width of its widest
rendered cell. The Columns menu's **Size columns to content** does the same for
every column at once.

Measurement comes from the DOM, not the data: a cell renders a badge, an avatar
and a name, and the only honest answer to "how wide is this column" is what the
browser laid out. It measures the **rendered** rows — the page, or the window
under virtualization — which is the set the reader is looking at, and it reads
each cell's content width, so a column that is currently clipping its text is
sized to fit it rather than to its clipped width. Running it again does not
keep adding width: once a cell already fits, the box is not treated as new
content.

The result is an ordinary width in the column layout: it persists, serializes to
the URL and to saved views, and a later drag overrides it exactly as it
overrides any other width. A column with nothing measurable on screen is left
alone rather than collapsed.

Both actions are localizable — `labels.autoSizeColumns` and
`labels.autoSizeColumn` — in every bundled locale.

Headless: `measureColumnWidth(root, key)` and `autoSizeColumns(root, keys,
setWidth)`.

---

# React table saved views — shareable named layouts

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — a real AdaptTable you can edit in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

Let users capture the table's current state under a name and re-apply it
later. Compose `savedViews()` from `@adapttable/<kit>/saved-views` and a
ready-made menu mounts in the toolbar; a headless hook backs custom UIs. The
import and `features` entry are the switch; there is no `savedViews` table prop. See
[feature composition](./features.md).

A view captures **every parameter the table keeps in its URL**: search, the
find-in-table query, the multi-sort chain, page and page size, the simple
filters and the advanced filter tree, ordered grouping keys (`groupBy`),
session aggregation overrides (`groupAgg`), formula columns, and the
[pivot configuration](./pivot.md) — plus, when their URL hooks are wired, the
whole column layout (order, hidden, pinned, widths, user-renamed column names,
collapsed column groups), pinned rows, density and which groups are
collapsed. The parts that take longest to
rebuild by hand are exactly the parts worth capturing.

## Managing the list

`useSavedViews` returns the list plus the operations a management UI needs:

```tsx
import { useSavedViews } from "@adapttable/react";

const { views, save, apply, remove, rename, move, setDefault, defaultView } =
  useSavedViews({ storageKey: "people-views" });
```

`rename(from, to)` keeps the view's place in the list, and refuses a name that
is already taken — silently merging two views is how a rename loses one.
`move(name, -1 | 1)` steps a view through the list and stops at either end
rather than wrapping. `setDefault(name)` marks the view the table opens with;
naming the same view again clears it, and only one view can ever hold it.
Rename, move, set-default and delete all refuse a view this reader does not own,
so the panel's disabled controls and the hook agree.

Every operation is a no-op on a name that is not there, so a management UI
cannot get the list into a state the table will not accept.

## Views outliving the table that saved them

A saved view outlives the code that saved it — that is the point of saving one
— so each carries the schema version it was written at, and the table upgrades
what it reads.

```tsx
const views = useSavedViews({
  storageKey: "people-views",
  migrate: (view, from) => {
    if (from < 2) {
      // A column this table renamed since that view was saved.
      return {
        ...view,
        search: view.search.replace("colHide=email", "colHide=contact"),
      };
    }
    return view;
  },
});
```

`migrate` runs only for views behind `SAVED_VIEW_VERSION`, and is told which
version each came from. Views saved before versioning existed have no number
and are treated as version 1, which is what they are.

Returning `null` drops a view. That is a real answer: a view whose columns no
longer exist restores a table nobody asked for, and applying it silently is
worse than losing it. A migration that throws costs that view alone — one bad
entry in storage should not take the whole list with it.

Loading happens on mount and when `storageKey` changes. A `store` or a
`migrate` written inline changes identity on every render, so neither can be
allowed to trigger a reload; call `reload()` when you want the list read again.

## Keeping views on a server

`localStorage` is the zero-config default: a table that passes nothing keeps
working offline with no server at all. Pass a `store` and it takes over
completely — two sources of truth for one list is how a view comes back after
being deleted.

```tsx
const views = useSavedViews({
  storageKey: "people-views",
  visibility: "team", // what `save` marks a new view as
  store: {
    list: () => fetch("/api/views").then((r) => r.json()),
    save: (view) =>
      fetch("/api/views", { method: "POST", body: JSON.stringify(view) }),
    remove: (name) => fetch(`/api/views/${name}`, { method: "DELETE" }),
    reorder: (names) =>
      fetch("/api/views/order", {
        method: "PUT",
        body: JSON.stringify(names),
      }),
  },
});
```

The store is asked for **one view at a time**, never the whole list: sending
the list back would overwrite whatever other people changed between the load
and the save. A store that cannot be reached leaves the list empty rather than
throwing into a render — the table still works, the views simply are not there.

One gesture can be more than one write. Switching the default saves **two**
views — the one that gains the flag and the one that loses it — because a
cleared flag that never reached the store comes back set, and then two views
claim to be the default.

### Order

`reorder` is where the list's order lives. Order belongs to the list rather than
to any one view, so it has nowhere to go through `save`, and it travels as names
so that persisting an order carries no view contents with it and cannot overwrite
someone else's edit. It arrives after the same operation's own `save` and
`remove` writes have landed, so a renamed view's new name is already known by
the time its place in the list turns up.

`reorder` is **optional**, and a store without it keeps working: `list`, `save`
and `remove` carry saving, renaming, deleting and the default.
What such a store cannot do is remember an order — `move` reorders the list on
screen for that session, and the next `list()` decides the order again, as does
where a renamed view lands. Implement `reorder` when reordering has to survive a
reload.

### Views you may not change

A view carries `visibility` (`"private"` or `"team"`) and `readOnly`. A team
view someone else owns arrives read-only, and both halves honour it: the panel
shows a **Read-only** badge with its rename, reorder, set-default and delete
controls disabled, and the hook refuses those operations too. Applying it stays
enabled, since that is the point of a shared view.

Disabled rather than absent is deliberate. An absent control reads as "no such
feature"; a disabled one reads as "not yours". A control that silently does
nothing is a bug the user gets blamed for.

## The management panel

The saved-views _menu_ answers "switch to a view". Keeping the list in order is
a different job, and putting both in one dropdown makes the common one harder —
so management is a panel:

```tsx
import { SavedViewsPanelChrome } from "@adapttable/react/adapter";

<SavedViewsPanelChrome
  views={views}
  onApply={apply}
  onRename={rename}
  onMove={move}
  onSetDefault={setDefault}
  onRemove={remove}
  slots={slots}
/>;
```

`SavedViewsPanelSlots` names the four kit-supplied pieces —
`SavedViewsPanelSurfaceProps` (the titled card), `SavedViewsPanelRowProps` (one
view and its controls), `SavedViewsPanelInputProps` (the inline rename box) and
`SavedViewsPanelEmptyProps`. `SavedViewsPanelChromeProps` is what the panel
itself takes.

Every adapter ships it pre-wired as `SavedViewsPanel`:

```tsx
import { SavedViewsPanel } from "@adapttable/mantine";

<SavedViewsPanel
  views={views}
  onApply={apply}
  onRename={rename}
  onMove={move}
  onSetDefault={setDefault}
  onRemove={remove}
  footer={<span>Upgraded on load: Legacy view (v1)</span>}
/>;
```

`footer` puts anything of yours inside the card, under the list — a note about
where the views came from, a link to your own docs. Outside the card a line
like that reads as a caption belonging to whatever follows it on the page.

The panel is a card with a title, and each view is one row inside it. The row
has a single primary action: **applying a view is clicking its name**, which is
the widest target on the row and the thing a reader wants nine times out of
ten. Rename, move up, move down, set-default and delete are icons in a compact
cluster at the end of the line, each with its own localized accessible name.
`SavedViewRowControl` describes one of them and `SavedViewControlKey` names
which — an adapter maps over `controls` rather than hand-writing five buttons,
so no kit can render four of them or put them in a different order.

Reordering is buttons rather than drag, because a list you can only reorder by
dragging is a list some people cannot reorder. The move a row cannot make is
disabled rather than removed, so the row does not jump as the list is
reordered. Renaming is an inline input rather than a dialog: the name is
already on screen, and Escape abandons the edit without changing anything.

The card names four parts for styling and testing: `saved-views-panel` and
`saved-views-title` on the card, `saved-view-row` on each view, and
`saved-views-footer` on your note.

## Example

```tsx
// Needs your kit's provider once at the root (e.g. <MantineProvider>).
import { DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { columnMenu } from "@adapttable/mantine/column-menu";
import { savedViews } from "@adapttable/mantine/saved-views";

interface Person {
  id: string;
  name: string;
  department: { name: string };
  status: string;
  salary: number;
}

const data: Person[] = [
  {
    id: "1",
    name: "Amira Haddad",
    department: { name: "Engineering" },
    status: "active",
    salary: 98000,
  },
  {
    id: "2",
    name: "Jonas Weber",
    department: { name: "Design" },
    status: "onleave",
    salary: 76000,
  },
  {
    id: "3",
    name: "Priya Nair",
    department: { name: "Engineering" },
    status: "active",
    salary: 112000,
  },
  {
    id: "4",
    name: "Sam Ortiz",
    department: { name: "Sales" },
    status: "left",
    salary: 64000,
  },
];

export function PeopleTable() {
  return (
    <DataTable
      data={data}
      rowKey={(r) => r.id}
      columns={[
        { key: "name", sortable: true },
        {
          key: "department.name",
          header: "Department",
          filter: { type: "select", options: "auto" },
        },
        { key: "status", filter: { type: "multiSelect", options: "auto" } },
        { key: "salary", filter: "numberRange", sortable: true },
      ]}
      features={[columnMenu(), savedViews({ storageKey: "people-views" })]}
    />
  );
}
```

## How it works

- Composing `savedViews({ storageKey })` renders the kit's built-in Saved-views
  menu in the toolbar next to the Columns button: click a name to apply it, the
  trailing ✕ to delete it, or type a name and Save to capture the current state.
- A view stores the table-scoped query string — search, sort, page and
  page-size, every `f_*` filter param, and the URL-persisted column layout.
  Only this table's params are captured; saving under an existing name
  replaces it.
- Applying first drops this table's current params, then lays the view's
  over — other tables sharing the URL are untouched, and anything the view
  doesn't mention returns to its default.
- The list persists as JSON under `storageKey` (localStorage by default).
- `urlAdapter` and `urlKey` default to the table's own, so usually only
  `storageKey` is needed.

## Options

`savedViews(options)` takes `UseSavedViewsOptions` (the same options as the
headless hook):

| Prop         | Type                  | Default                                | Description                                                      |
| ------------ | --------------------- | -------------------------------------- | ---------------------------------------------------------------- |
| `storageKey` | `string`              | — (required)                           | Storage key for the view list, e.g. `"people-table-views"`.      |
| `storage`    | `LayoutStorage`       | `localStorage` (memory-only under SSR) | Storage backend — supply your own to persist elsewhere.          |
| `store`      | `SavedViewsStore`     | —                                      | Server-side list; replaces `storage` entirely.                   |
| `visibility` | `"private" \| "team"` | `"private"`                            | What `save` marks a new view as.                                 |
| `migrate`    | `SavedViewMigration`  | —                                      | Upgrade a view behind `SAVED_VIEW_VERSION`, or drop it (`null`). |
| `urlAdapter` | `UrlStateAdapter`     | the table's `urlAdapter`               | The table's URL-state backend.                                   |
| `urlKey`     | `string`              | the table's `urlKey`                   | The table's URL namespace — must match the table's `urlKey`.     |
| `urlSync`    | `boolean`             | `true`                                 | `false` captures and applies against in-memory state.            |

The hook returns `UseSavedViewsResult`: `views`, `save`, `apply`, `remove`,
`rename`, `move`, `setDefault`, `defaultView` and `reload`. Each entry is a
`SavedView` — `name`, `search` (the table-scoped query string), `isDefault`,
`visibility` (`SavedViewVisibility`), `version` and `readOnly`. A
`SavedViewsStore` implements `list`, `save`, `remove` and an optional
`reorder`; `SAVED_VIEW_VERSION` is the schema views are written at (`2`).

## Notes

- **SSR-safe**: stored views hydrate in an effect after mount (no
  hydration mismatch); blocked storage is tolerated.
- With `urlSync={false}` the menu captures and applies the table's
  IN-MEMORY state — the address bar never changes and foreign query
  params are never touched (`apply` writes only params the table owns).

- For custom UIs, use the headless hook and wire any menu into the `toolbar`
  slot (each adapter also exports its `SavedViewsMenu` component to pair with
  it):

  ```tsx
  import { useSavedViews } from "@adapttable/react";

  const views = useSavedViews({ storageKey: "people-views", urlKey: "people" });
  // views.views, views.save("Active EU"), views.apply("Active EU"),
  // views.remove("Active EU")
  ```

- Column layout, density, pinned rows and collapsed groups are part of a
  view only when they live in the URL (wire `useColumnLayoutUrlState`,
  `useDensityUrlState`, `useRowPinningUrlState`, `useGroupCollapseUrlState`);
  the localStorage-backed layout from `useColumnLayoutStorageState` is not
  captured.
- Views are local to the browser by default. Pass `storage` to persist them
  elsewhere; a full or denied storage degrades gracefully — the in-memory
  list keeps working for the session.
- Multiple tables on one page: give each table its own `urlKey` (so params
  are namespaced, `left.q`, `left.f_status`, …) and a distinct `storageKey`.
  Each menu captures and applies only its own namespace.
- A view stores state, not rows — applying one re-runs the usual
  search/filter/sort pipeline (or re-fires `onQueryChange` on the server
  tier).
- The menu's `savedViews` / `saveView` / `viewName` / `deleteView` labels are
  overridable via `labels` and localized by the `@adapttable/i18n` presets.

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

---

# React table virtualization — rows, columns and mobile cards

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — a real AdaptTable you can edit in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [scroll 50,000 rows in the live demo](https://adapttable.orwamahmoud.com/react/demo/mantine/scale/) — a real table you can scroll, not a recording.

Long lists opt into row/card windowing with one feature: `virtualize()` from
`@adapttable/<kit>/virtualize`. Fifty
thousand rows render as a handful of DOM nodes, on the page or inside a
fixed-height box.

## Example

```tsx
import { DataTable } from "@adapttable/mantine"; // or @adapttable/mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { virtualize } from "@adapttable/mantine/virtualize";

interface Reading {
  id: string;
  sensor: string;
  value: number;
}

const data: Reading[] = Array.from({ length: 50_000 }, (_, i) => ({
  id: String(i + 1),
  sensor: `Sensor ${(i % 40) + 1}`,
  value: Math.round(Math.sin(i) * 1000) / 10,
}));

export function Readings() {
  return (
    <DataTable
      data={data}
      columns={[{ key: "sensor", sortable: true }, { key: "value" }]}
      rowKey={(r) => r.id}
      paginationMode="infinite"
      features={[virtualize()]}
      maxHeight={380}
      estimateRowSize={56}
      estimateCardSize={140}
    />
  );
}
```

The estimates default to **56 px** rows and **132 px** cards — pass your
real measured sizes (like the `140` above) when your cells differ.

## How it works

- `virtualize()` is opt-in: a table that does not compose it never loads
  `@tanstack/react-virtual`. It applies in **infinite (non-paged) mode** — paged tables already cap the row count, so they never virtualize.
- **Window mode** (no `maxHeight`): the virtual window tracks the page scroll.
  The list's offset from the top of the document is measured automatically,
  so a table below page chrome does not open with a blank gap. Pass
  `virtualScrollMargin` only to override that measurement.
- **Element mode** (any `maxHeight` box): the same feature virtualizes inside the
  scroll box instead — the box is the scroller and the window tracks it.
  Mobile cards attach that box to the card list itself (desktop rows attach it
  to the table assembly), so `maxHeight` + `virtualize()` never mounts every card.
- `rowAppearance({ rowHeight })` overrides the estimate when set — a function is per row, so
  a variable-height table still windows. See [row styling and heights](./row-styling.md).
- Rows/cards are measured after render; `estimateRowSize` (desktop rows) and
  `estimateCardSize` (mobile cards) seed the math, and `virtualOverscan` rows
  are rendered beyond the visible window to keep scrolling smooth.
- Inside a `maxHeight` box the page-level **Load more** button and
  infinite-scroll sentinel are suppressed: the box never grows, so the virtual
  window extends itself at the box's scroll end instead.
- Ant Design maps `virtualize()` to antd's **native** virtual table mode on
  desktop; on mobile the cards window through the shared engine, just like
  every other adapter, and the page-level sentinel keeps loading more.
  `virtualize({ virtualizeColumns: true })` has no effect there: antd owns its scroller, so there is
  no measured box for the horizontal window, and every column stays in the DOM.

## Options

`virtualize(options?)` takes `true` (the default), `false`, or an options
object with `virtualizeColumns` and the size knobs below. The size knobs are
accepted on `DataTable` as props too.

| Option                | Type      | Default | Description                                                                                                     |
| --------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `virtualizeColumns`   | `boolean` | `false` | Window the rendered columns on very wide tables. Applies with `maxHeight` or pinned columns; not in Ant Design. |
| `maxHeight`           | `number`  | —       | `DataTable` prop. Fixed-height scroll box (px); switches to element-mode windowing.                             |
| `estimateRowSize`     | `number`  | `56`    | Desktop row-height estimate in px.                                                                              |
| `estimateCardSize`    | `number`  | `132`   | Mobile card-height estimate in px.                                                                              |
| `virtualOverscan`     | `number`  | `8`     | Extra rows/cards rendered before and after the visible window.                                                  |
| `virtualScrollMargin` | `number`  | —       | Override for the measured window-mode list offset.                                                              |

## Benchmark

Virtualization renders only the rows in view, so cost is bounded by the
viewport — not the dataset. A measured A/B on the scale demo (Mantine adapter,
the **same 10,000-row dataset fully loaded**, the showcase production build,
headless Chromium 151 at 1280×900 on an Apple M1 Max), recorded in
[`scripts/bench-runs/2026-09-23.json`](https://github.com/orwa-mahmoud/adapttable/blob/main/scripts/bench-runs/2026-09-23.json):

|                                  | Rows in the DOM | Retained JS heap |
| :------------------------------- | --------------: | ---------------: |
| **Virtualized** (`virtualize()`) |          **10** |        **11 MB** |
| Plain table — same 10,000 rows   |          10,000 |           202 MB |

Windowing mounts **1,000× fewer rows** (10 vs 10,000 — a viewport's worth
plus overscan) and holds **191 MB less memory, about 95% less** — while the
plain table blocks the main thread rendering ten thousand `<tr>`s.

The two arms differ in kind, not just degree: the plain table's memory sits in
10,000 mounted rows, which cannot be released while they are on screen. The
virtualized one mounts 10 and keeps the rest as a plain array, so what it costs
is your data, not your table.

And it stays flat: the rendered row count holds at **10 whether the dataset is
1,000 or 100,000 rows**. Only your own data array grows — never the table's DOM:

| Rows in the dataset |  1,000 | 10,000 | 50,000 | 100,000 |
| ------------------: | -----: | -----: | -----: | ------: |
|     Rows in the DOM | **10** | **10** | **10** |  **10** |

Reproduce both with
[`scripts/bench.mjs`](https://github.com/orwa-mahmoud/adapttable/blob/main/scripts/bench.mjs)
— it serves this demo itself, drives it through the whole scenario set (wide
tables, grouping, pinned columns, sorted data) and prints the DOM rows, cells,
heap and time-to-interactive for each:

```bash
node scripts/bench.mjs                   # every scenario
node scripts/bench.mjs --smoke           # the fast subset CI runs
node scripts/bench.mjs --record          # also saves the run to scripts/bench-runs/
```

`--record` writes the run — every scenario, the machine and the browser build it
ran on — to a dated JSON file in
[`scripts/bench-runs/`](https://github.com/orwa-mahmoud/adapttable/tree/main/scripts/bench-runs).

With nothing on the port it builds the showcase and serves the production
build — the code users download. A showcase already running on the port is
used as it is, so `pnpm --filter @adapttable/showcase dev` in another terminal
is the faster loop while iterating; `--record` refuses a dev server, because
React's development build runs slower and holds more memory, and a published
number comes from a production build only.

Heap here is **retained** memory — measured after forcing collection and taking
the floor across repeated runs, because the raw `usedJSHeapSize` figure counts
whatever the engine has not swept yet and swings by an order of magnitude with
how busy the machine is. Measured this way the numbers come out the same on a
loaded laptop as an idle one, which is what makes them worth publishing: run
`pnpm bench` and you should see them too.

## Notes

- Virtualization is optional — leave it off for small lists or paged tables.
- `virtualize()` and `rowDetail(...)` work together. A `<tr>` cannot contain the
  panel that belongs to it, so an open detail renders as a sibling row — and the
  pair is measured as a pair, with the combined height handed to the virtualizer.
  A panel that grows later (an image loading, a nested table expanding) corrects
  its item's size when it does, so scroll positions hold.
- The headless hook `useTableVirtualization` (from `@adapttable/react`) serves custom markup
  ([example](./headless.md#virtualization));
  when disabled it returns every row with no spacers, so one render path
  serves both cases.
- A windowed table still tells assistive technology how big the data really
  is: the table carries `aria-rowcount` with each row's absolute
  `aria-rowindex`, and the mobile card list carries `aria-setsize` with each
  card's `aria-posinset`. `virtualizeColumns` does the same for the horizontal
  axis — `aria-colcount` on the table and an absolute `aria-colindex` on every
  body and header cell — so a reader is never left counting the cells it can
  reach. Without
  that a screen reader would count only the few rows in the DOM. See
  [Accessibility](./accessibility.md).

See it live in the [demo](https://adapttable.orwamahmoud.com/react/demo/).

---

# Responsive React table — automatic mobile card layout

▶ **See it before you install:** [the live mobile demo](https://adapttable.orwamahmoud.com/react/demo/mantine/mobile-cards/) — the same table flipped between desktop rows and phone cards with one toggle.

<video src="https://adapttable.orwamahmoud.com/media/features/mobile.mp4" poster="https://adapttable.orwamahmoud.com/media/features/mobile-poster.png" aria-label="The same AdaptTable data table as phone cards — scrolling the card list, then switching to the desktop table" controls playsinline preload="none" width="1240" height="758" style="width:100%;height:auto;aspect-ratio:1240/758;border-radius:8px"></video>

Most React data tables answer the phone problem with a horizontal scrollbar.
AdaptTable answers it with a different layout: below the mobile breakpoint,
every row renders as a **card** — same columns, same filters, same search,
same selection, same URL state — and the switch happens by itself. There is
no second component to build, no `isMobile` plumbing, and nothing to
configure to get the default behavior.

```tsx
<DataTable data={rows} columns={columns} rowKey={(r) => r.id} />
```

That is already responsive. On a desktop viewport it renders the full table;
on a phone it renders the card list. Everything below is tuning.

## What changes on mobile — and what deliberately doesn't

| Surface                                                             | Desktop                             | Mobile                                              |
| ------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------- |
| Rows                                                                | `<table>` rows                      | Cards — one per row, labels from the column headers |
| Sorting                                                             | Clickable column headers            | A sort-by `<select>` (options via `sortByOptions`)  |
| Pagination                                                          | Pager (or infinite)                 | `paginationMode="auto"` resolves to infinite scroll |
| Row actions                                                         | Trailing icon buttons               | Card buttons                                        |
| Long lists                                                          | Row virtualization (`virtualize()`) | Card virtualization through the same feature        |
| Filters, chips, search, selection, bulk bar, saved views, URL state | identical                           | identical                                           |

The second half of that table is the point: behavior that took real work to
get right — declarative filters, select-across-pages, shareable URL state —
does not fork into a second code path on phones. One table, one state, two
layouts.

## Tuning the cards

- **`mobileLabel`** (per column) — the label a card shows for that field;
  falls back to the column's string `header`, then to its key. Set it to `""`
  for a field with no label at all — a bare avatar or title line — rather than
  an empty caption taking a line. `resolveMobileLabel` from
  `@adapttable/react/adapter` is the resolver every adapter uses, for a custom
  card layout that should match.
- **`hideOnMobile`** (per column) — drop a column from cards entirely.
- **`hideOnDesktop`** (per column) — show a field on cards only.
- **`mobileIdentityColumns`** — deprecated, accepted and ignored, removed in
  v4. `hideOnMobile` decides what a card shows: every column without it
  appears.
- **`sortByOptions`** — the options offered by the mobile sort-by select.
- **`forceMobile`** — pin either layout regardless of viewport: cards inside a
  desktop dashboard panel, or the full table in a tablet kiosk. The
  [mobile demo](https://adapttable.orwamahmoud.com/react/demo/mantine/mobile-cards/) uses
  exactly this prop for its toggle.
- **`rowAppearance({ rowClassName })`** applies to desktop rows and mobile
  cards alike, and the
  [class-hook / `data-adapttable-part` surface](./customization.md) names the
  card regions (`cardDetail`, `group-card`, `summaryCard`) for styling.
- **`rowAppearance({ rowStyle, rowHeight })`** applies the same way — see
  [row styling and heights](./row-styling.md).

## Your own card

The built-in card is a stack of labelled fields, which is right for most
tables and wrong for some: an order wants its total large and its reference
small; a person wants their avatar beside their name rather than under a
caption reading "Avatar".

`renderCard` replaces that stack — and only that stack:

```tsx
<DataTable
  data={people}
  columns={columns}
  rowKey={(r) => r.id}
  renderCard={(row, card) => (
    <article className="person-card">
      <img src={row.avatarUrl} alt="" />
      <h3>{row.name}</h3>
      <dl>
        {card.fields.map(({ column, label, value }) => (
          <div key={column.key}>
            {label && <dt>{label}</dt>}
            <dd>{value}</dd>
          </div>
        ))}
      </dl>
    </article>
  )}
/>
```

The card's shell stays around what you return: the list-item semantics, the
selection checkbox, the expand and tree toggles, the reorder controls, the row
actions and the detail panel. A custom card cannot drop the parts that make
the list usable, because it never owns them.

With `rowReorder(...)` from `@adapttable/mantine/row-reorder` composed, flat
cards expose up/down controls with a touch target of at least 44×44 px in
every kit (measured on the production build in
[`scripts/bench-runs/2026-09-23-2.json`](https://github.com/orwa-mahmoud/adapttable/blob/main/scripts/bench-runs/2026-09-23-2.json)). Grouped and tree cards also expose the
kit-native **Move to group…** / **Move under…** menu, including explicit
confirmation with `rowReorder(onRowReorder, { movePolicy: "confirm" })`;
touch never has to emulate a drag.

`card.fields` is what the built-in would have laid out — each field's
`column`, its resolved `label` (`undefined` when the column asked for none)
and its `value`, rendered exactly as the built-in renders it, cell renderers
and editors included. So this is a layout decision, not a re-implementation:
reuse the values and arrange them your way. `card.selected`, `card.expanded`
and `card.index` come along for cards that change with their state.

Omit it and the built-in card renders, byte for byte.

## Where the switch happens

`mobileBreakpoint` is the width, in pixels, at or below which the cards take
over. It defaults to 768 — a phone in portrait.

```tsx
<DataTable
  data={rows}
  columns={columns}
  rowKey={(r) => r.id}
  mobileBreakpoint={1024}
/>
```

Raise it when the table lives in a sidebar or a split pane: the viewport says
"desktop" while the table itself has a phone's width to work with, and the
default would keep a five-column table in a 300px column. Lower it when the
table is the whole page and its columns are narrow enough to survive.

## The width in between

Between "everything fits" and "narrow enough for cards" there is a long middle
where a table has too many columns. The usual outcomes are a horizontal
scrollbar nobody finds, or columns squeezed until nothing is legible — neither
is a decision.

`responsivePriority` is the decision, made by the person who knows the data:

```tsx
const columns = [
  { key: "name", header: "Name", width: 200 },
  { key: "team", header: "Team", width: 160, responsivePriority: 1 },
  { key: "note", header: "Note", width: 240, responsivePriority: 2 },
];
```

Priority 1 is kept longest, in the ordinary sense of the word. As the table
narrows, `note` goes first, then `team`. `name` never goes — a column that
omits `responsivePriority` is never dropped, which is how the columns carrying
the row's identity stay put by saying nothing. A table where no column sets it
behaves exactly as it did before.

The budget is arithmetic on each column's declared `width` (a resize wins over
it, and a column with no width is budgeted at 150px), so it settles in one pass
and gives the same answer every time. There is no measure-drop-remeasure loop,
which is what makes tables that do it flicker.

A dropped column is a fact about the viewport, not a choice the user made: it
never reaches the layout state, the URL or a saved view, and the column menu
still lists it.

## It composes with everything else

- **Grouping** renders group header blocks between cards, with the same
  collapse behavior as desktop — see [row grouping](./row-grouping.md).
- **Virtualization** windows the card list the same way it windows rows:
  one `virtualize()` feature, measured in a real browser across every adapter —
  see [virtualization](./virtualization.md).
- **RTL** flips the cards along with everything else — see
  [i18n & RTL](./i18n-rtl.md).
- **Every adapter ships it**: Mantine, MUI, Chakra, Ant Design, Radix,
  Base UI, shadcn/ui and unstyled all render the card layout natively —
  the [comparison table](./comparison.md) tracks it as a built-in across
  the board.

## When you still want the table on phones

Set `forceMobile={false}` and the desktop layout renders everywhere —
sticky header, pinned columns and horizontal scrolling included. The cards
are the default because thumb-reach beats pinch-zoom for row-by-row work,
but the choice stays yours per table.

Related: [Getting started](./getting-started.md) ·
[API reference](./api.md) ·
[Live mobile demo](https://adapttable.orwamahmoud.com/react/demo/mantine/mobile-cards/)

---

# React table URL state — shareable filters, sort, and page

▶ **See it working:** [the live demo](https://adapttable.orwamahmoud.com/react/demo/) — filter, sort and page it, then copy the URL: every bit of that state is in the address bar (the kit switcher too).

AdaptTable keeps the table's state in the URL query string: search (`q`),
pagination (`page`, `limit`), sorting (`sortBy`/`sortDir`, or `sort` for a
multi-sort chain), row grouping (`groupBy`) and session aggregation choices
(`groupAgg`), and every filter value (`f_<key>`). Column layout
(`colHide`, `colPin`, `colOrder`, `colW`, `colName`) joins in when you wire
`useColumnLayoutUrlState`, and saved views capture all of it under a name.
Reloading, sharing the link, or pressing back lands on the exact same slice.

Two conventions keep URLs clean: default values are omitted, and changing
search, sort, or a filter resets the page to 1.

## Format stability and recovery

Every table namespace AdaptTable has written carries an `atv=1` marker
(`people.atv=1` when `urlKey="people"`). A link without the marker is also
version 1, so links created before the marker existed keep their exact meaning.
The marker remains when the other values are cleared, so an explicitly empty
state is versioned too. It changes only when a future release needs a real
migration; adding an optional parameter does not reinterpret existing ones.

URL state is untrusted input and recovers by policy:

- Unknown parameters are ignored by the table and preserved on writes.
- Malformed values fall back or are dropped independently, so one bad field
  cannot erase valid state.
- When a parameter is duplicated, the first value wins.
- An unsupported or malformed `atv` ignores AdaptTable's recognized parameters
  for that table only. Other table namespaces and application parameters remain
  intact.
- One table may carry at most 8,192 encoded characters of recognized state.
  Oversized incoming state is ignored for that table; a write that would cross
  the limit keeps the previous valid state instead.

Every recovery path produces the normal default table rather than throwing or
rendering a blank result.

## Multiple tables on one URL: `urlKey`

Two tables on one page would clobber each other's params. Give each a
namespace and every param is prefixed (`people.q`, `orders.f_totalMin`, …):

```tsx
import { DataTable } from "@adapttable/mantine";
import { filters } from "@adapttable/mantine/filters";

type Person = { id: string; name: string; status: string };
type Order = { id: string; ref: string; total: number };

export function Dashboard({
  people,
  orders,
}: {
  people: Person[];
  orders: Order[];
}) {
  return (
    <>
      <DataTable
        data={people}
        columns={[
          { key: "name", sortable: true },
          { key: "status", filter: { type: "select", options: "auto" } },
        ]}
        rowKey={(r) => r.id}
        urlKey="people"
        features={[filters([])]}
      />
      <DataTable
        data={orders}
        columns={[{ key: "ref" }, { key: "total", filter: "numberRange" }]}
        rowKey={(o) => o.id}
        urlKey="orders"
        features={[filters([])]}
      />
    </>
  );
}
// → ?people.q=avery&people.page=2&people.atv=1&orders.f_totalMin=100&orders.atv=1
```

The same `urlKey` option exists on `useFrontendData`, `useServerData`,
`useQuerySource`, `useTableUrlState`, `useColumnLayoutUrlState`,
`useDensityUrlState`, `useGroupCollapseUrlState`, `useRowPinningUrlState`, and
`useSavedViews` for headless consumers. Omitting distinct `urlKey`s on
shared-URL tables logs a development warning.

## URL adapters

The URL layer is decoupled from any router via a tiny `UrlStateAdapter`:

```ts
interface UrlStateAdapter {
  getSearch(): string; // current query string (no "?")
  setSearch(search: string, opts?: { push?: boolean }): void;
  subscribe(onChange: () => void): () => void;
}
```

- **`createHistoryAdapter()`** — browser History API; the default (one
  shared instance per window via `getHistoryAdapter()`).
- **`createMemoryAdapter(initial?)`** — in-memory; used for SSR, tests, and
  when URL sync is disabled (the table still gets fully working local state).

Pass a custom adapter as `urlAdapter` on any `<DataTable>` or headless hook.

## Your router

Every router recipe is the same shape: read the current query string, and
navigate to a new one. `routerUrlAdapter` is that shape — its
`RouterUrlAdapterOptions` are the router's current `search` and a `navigate` —
so each router takes two lines instead of twelve — and it depends on no router, which is why it can
ship at all.

Memoize it on the search: the adapter is a value, and rebuilding it is how the
table learns the route changed.

### react-router

```tsx
import { useMemo } from "react";
import { useNavigate, useSearchParams } from "react-router-dom";
import { routerUrlAdapter } from "@adapttable/core";

export function useReactRouterAdapter() {
  const [params] = useSearchParams();
  const navigate = useNavigate();
  return useMemo(
    () =>
      routerUrlAdapter({
        search: params.toString(),
        navigate: (search, { push }) =>
          navigate({ search }, { replace: !push }),
      }),
    [params, navigate]
  );
}
```

### TanStack Router

```tsx
import { useMemo } from "react";
import { useNavigate, useRouterState } from "@tanstack/react-router";
import { routerUrlAdapter } from "@adapttable/core";

export function useTanStackAdapter() {
  const search = useRouterState({ select: (s) => s.location.searchStr });
  const navigate = useNavigate();
  return useMemo(
    () =>
      routerUrlAdapter({
        search,
        navigate: (next, { push }) =>
          navigate({ to: ".", search: next, replace: !push }),
      }),
    [search, navigate]
  );
}
```

### Next.js (App Router)

```tsx
"use client";
import { useMemo } from "react";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
import { routerUrlAdapter } from "@adapttable/core";

export function useNextAdapter() {
  const searchParams = useSearchParams();
  const pathname = usePathname();
  const router = useRouter();
  return useMemo(
    () =>
      routerUrlAdapter({
        search: searchParams.toString(),
        navigate: (search, { push }) => {
          const url = search ? `${pathname}?${search}` : pathname;
          if (push) router.push(url, { scroll: false });
          else router.replace(url, { scroll: false });
        },
      }),
    [searchParams, pathname, router]
  );
}
```

```tsx
<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  urlAdapter={useNextAdapter()}
/>
```

`push` is opt-in throughout: the default is a replace, because a table's every
keystroke is not a page anyone wants to walk back through.

The adapter reports no external changes on purpose. A router re-renders its
tree on navigation, so the hook holding the adapter runs again and reads the
new search itself — subscribing would deliver the same change twice. The one
way to hold it wrong is to pass a `search` that does not update, which is why
it takes a value rather than a getter.

## Turning URL sync off

One prop: `urlSync={false}`. Search, sort, filters and pagination keep
working identically — state just lives in memory, the address bar never
changes, and any `urlAdapter` is ignored.

```tsx
<DataTable data={data} columns={columns} rowKey={(r) => r.id} urlSync={false} />
```

Headless equivalent: `useTableUrlState({ urlSync: false })` — handy inside
modals or drawers where the address bar shouldn't change.

## Param reference

| Param                       | Example                        | Meaning                                                                                                                                                                                                                                |
| --------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `atv`                       | `atv=1`                        | AdaptTable URL-state format. Missing also means version 1; unsupported versions recover to defaults for this table only.                                                                                                               |
| `q`                         | `q=avery`                      | Committed [search](./search.md) term.                                                                                                                                                                                                  |
| `find`                      | `find=Ada`                     | Find-bar query (in-table walk). Empty or closed deletes the param; the current-match index is never stored.                                                                                                                            |
| `page`                      | `page=3`                       | 1-based page; omitted at 1.                                                                                                                                                                                                            |
| `limit`                     | `limit=50`                     | Page size; a value outside 1–500 falls back to the default. Omitted at the default (25).                                                                                                                                               |
| `sortBy` + `sortDir`        | `sortBy=name&sortDir=desc`     | Single-column sort (`sortDir` falls back to `asc`).                                                                                                                                                                                    |
| `sort`                      | `sort=name:asc,age:desc`       | Multi-sort chain; supersedes `sortBy`/`sortDir` while present.                                                                                                                                                                         |
| `groupBy`                   | `groupBy=team,status`          | Ordered row-grouping column keys, outermost first. Written by `groupingPanel()` and omitted when no grouping is active.                                                                                                                |
| `groupAgg`                  | `groupAgg=budget:sum,age:none` | Per-column session aggregation overrides: a built-in name, a host operation id, or `none` (explicit suppression). A missing column preserves the developer's `groupAggregates` / `aggregatable.default` / original `query.aggregates`. |
| `f_<key>`                   | `f_status=active`              | One filter value; `multiSelect` arrays are comma-separated with each entry percent-encoded.                                                                                                                                            |
| `f_<key>From` / `f_<key>To` | `f_hiredAtFrom=2026-01-01`     | `dateRange` bounds (inclusive; the end bound keeps that whole day). A `relative` operator stores the token here (`today`, `last:7`) instead of a resolved day.                                                                         |
| `f_<key>Min` / `f_<key>Max` | `f_salaryMin=50000`            | `numberRange` bounds (inclusive; parsed as numbers).                                                                                                                                                                                   |
| `ft`                        | `ft=1.{"combinator":"and"}`    | Versioned AND/OR filter tree. Unknown versions are dropped, never reinterpreted.                                                                                                                                                       |
| `colHide`                   | `colHide=email,phone`          | Hidden columns (keys percent-encoded).                                                                                                                                                                                                 |
| `colPin`                    | `colPin=name:left`             | Pinned columns and their side.                                                                                                                                                                                                         |
| `colOrder`                  | `colOrder=name,role,salary`    | Explicit column order.                                                                                                                                                                                                                 |
| `colW`                      | `colW=name:220`                | Per-column pixel widths.                                                                                                                                                                                                               |
| `colName`                   | `colName=name:Account%20owner` | User display names by stable column key.                                                                                                                                                                                               |
| `colGroupCollapse`          | `colGroupCollapse=contact`     | Collapsed column groups (ids percent-encoded).                                                                                                                                                                                         |
| `groupClosed`               | `groupClosed=Engineering`      | Collapsed row groups, by group key.                                                                                                                                                                                                    |
| `rowPin`                    | `rowPin=id1:top,id2:bottom`    | Pinned rows and their edge.                                                                                                                                                                                                            |
| `density`                   | `density=compact`              | Row density; omitted at the default.                                                                                                                                                                                                   |
| `pivot`                     | `pivot=rows:…`                 | Pivot configuration and folded groups (see [pivot tables](./pivot.md)).                                                                                                                                                                |
| `formula`                   | `formula=margin:…`             | User-typed formula columns, as text (see [formulas](./formulas.md)).                                                                                                                                                                   |

With a `urlKey` every param is prefixed: `people.q`, `people.f_status`,
`people.groupBy`, `people.groupAgg`, `people.colHide`, ….

`groupAgg` is intentionally an override map, not a replacement aggregate
configuration. Adding or changing an operation writes that column's id;
removing a developer-declared aggregate writes `none` so the default does not
come back; removing a reader-added aggregate deletes the entry. **Restore
defaults** clears the whole map. Keys are percent-encoded, host-defined ids
survive the round trip, and equivalent maps serialize in stable column-key
order. [Row grouping](./row-grouping.md) documents the panel, column-menu,
mobile, and keyboard routes that write this state.

### Defaults vs. explicit clears

`defaults` (search, sort, `extra` filter values) apply only while the URL is
silent about a key. When the user explicitly clears a defaulted value, the
hook records it as an empty-valued param (`q=`, `f_status=`) so the default
does not instantly resurrect — a missing param means "default applies", an
empty one means "explicitly cleared".

## Reading and writing the params yourself

The codecs the table uses are published, so a route handler, a saved-view
store, or a test can read and write the same URL without mounting a table.

`parseTableUrlState(search, namespace)` returns one table's recognized
params as `URLSearchParams`. `updateTableUrlState(search, namespace, mutate)`
returns the next query string, preserving every unrelated param.
`captureTableUrlState(search, namespace)` and
`applyTableUrlState(search, savedSearch, namespace)` copy one table's state
out of and into a query string. `namespace` is the param prefix: `"people."` for
`urlKey="people"`, `""` for a table without one.

The core params have named constants and, where the value is not a plain
string, a reader and a writer:

| Constant                                        | Reader / writer                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------- |
| `PARAM_PAGE`, `PARAM_LIMIT`, `MAX_LIMIT`        | `readPage`, `readLimit`                                                |
| `PARAM_SEARCH`, `PARAM_FIND`                    | plain strings                                                          |
| `PARAM_SORT_BY`, `PARAM_SORT_DIR`               | `readSortDir`; the chain is `readSortLevels` / `writeSortLevels`       |
| `PARAM_GROUP_BY`, `PARAM_GROUP_AGGREGATES`      | ordered keys and the per-column overrides                              |
| `PARAM_COL_HIDDEN`                              | `readColumnLayout` / `writeColumnLayout` cover the whole column layout |
| `PARAM_DENSITY`, `PARAM_FORMULA`, `PARAM_PIVOT` | the density, formula-column and pivot codecs                           |
| `FILTER_PREFIX` (`f_`)                          | `readExtra` / `writeExtra`; `isEmptyFilterValue`                       |
| `PARAM_GROUP_CLOSED`                            | `readCollapsedGroups` / `writeCollapsedGroups`                         |
| `ft`                                            | `readFilterTreeParam` / `writeFilterTreeParam`                         |
| row pins                                        | `readRowPins` / `writeRowPins`                                         |

Writing a value that equals the default deletes the param instead of spelling
it out, which is what keeps a shared link short.

## SSR

The default History-API adapter hydrates from an empty query string (the
server has no `window`; the real URL applies right after hydration). To
server-render the exact requested slice, pass an explicit router adapter —
it knows the request URL, and the hooks trust an explicit adapter to be
hydration-consistent. `getHistoryAdapter()` itself returns a memory adapter
when there is no `window`, so nothing crashes under SSR either way.

---

# React table exports — browser files and server-built jobs

AdaptTable uses one `exportCsv()` feature for CSV, XLSX, PDF, and custom
writers. Small and medium exports can be built in the browser. Large
server-backed exports can stay beside the data while the table shows progress,
offers cancellation, and returns the finished download to the reader.

## Browser-built export

For frontend data, `scope: "all"` reads the source's complete filtered and
sorted set and builds the file directly:

```tsx
import { exportCsv } from "@adapttable/mantine/export";

<DataTable
  features={[exportCsv({ scope: "all", filename: "people.csv" })]}
  {...props}
/>;
```

A server source normally holds one page. `fetchAll` is the explicit
browser-built alternative: it pages the current query, then runs the normal
writer. The walk defaults to `EXPORT_FETCH_ALL_MAX_ROWS` (50,000). Reaching
that cap calls `onCapped` and never pretends a partial file is complete.

```tsx
features={[
  exportCsv({
    scope: "all",
    fetchAll: {
      fetchPage: (query) => api.people.list(query),
      onCapped: ({ rows }) => notify(`${rows} rows is the browser limit`),
    },
  }),
]}
```

`maxRows` (default `EXPORT_FETCH_ALL_MAX_ROWS`) and `pageSize` tune the walk;
`onCapped` receives `{ rows, maxRows }`.

Use this route only when downloading every page and holding the resulting file
in the tab is appropriate. The file goes through the normal writer, and
`onBeforeExport`/`onAfterExport` run as they do for any browser-built export.

## Server-built export with progress

`onExportAll(query, controls)` is the path beyond the browser cap. The table
does not fetch rows. It sends the page-free view only:

- committed search, flat filters, and the nested filter tree;
- the primary sort and complete multi-sort chain;
- grouping keys, outermost first;
- visible column keys and requested export column keys, both in display order;
- filename and writer format.

```tsx
import { exportCsv } from "@adapttable/mantine/export";

<DataTable
  features={[
    exportCsv({
      scope: "all",
      filename: "people.csv",
      onExportAll: async (query, controls) => {
        const job = await api.exports.start(query, {
          signal: controls.signal,
        });

        for await (const update of api.exports.watch(job.id, {
          signal: controls.signal,
        })) {
          controls.setProgress?.(update.percent);
          controls.setMessage?.(update.message);
          if (update.url) return { url: update.url };
        }
      },
    }),
  ]}
  {...props}
/>;
```

Each run gets a fresh `AbortSignal`. The surface's Cancel button aborts it;
the host should pass that signal through every request and stop its polling or
stream. `setProgress` is clamped to 0–100. If it is never called, the kit shows
an indeterminate indicator. `setMessage` supplies short job-specific detail
below the localized heading.

The host settles in one of three ways:

- resolve `{ url }`: the completed surface offers a **Download export** link;
- resolve nothing: the host chose another delivery method, and the surface
  still shows **Export complete**;
- reject: the error surface shows the reason and a localized **Retry** button.

Every terminal state — complete with or without a URL, failed, or cancelled —
also offers a localized **Dismiss** control. Dismiss returns the surface to
idle, clears the stale message, error, and download URL, and restores focus to
the Export button. It does not abort or restart a job. Busy work keeps
**Cancel** only; Dismiss never replaces it.

Cancellation is not a failure. It shows and announces **Export cancelled**,
ignores a late rejection from the aborted run, and never offers Retry for that
run. Retry starts a new job with a new signal and the table's current view.

`onExportAll` takes precedence over the generic `request` callback for
`scope: "all"`. `request` remains available for hosts that take over page,
selected, or range exports without the progress protocol. Neither host-owned
route runs `onBeforeExport` or `onAfterExport`, because the table never builds
their file.

## Accessibility and adapter behavior

Every published adapter renders the same lifecycle through its own components:
a progress card and determinate bar or indeterminate spinner, plus native-kit
Cancel, Retry, Download, and Dismiss controls. The card is viewport-safe on
mobile and uses logical positioning, so it remains at the inline end in LTR
and RTL. Dismiss sits at the inline end of the heading so RTL placement stays
correct.

A polite live region announces start, each reported progress value, completion,
failure, and cancellation. The Export button remains present with
`aria-busy="true"` while a job runs, and the single-flight guard refuses a
second start until that run settles or is cancelled.

For column scopes, writers, lifecycle hooks, and headless helpers, see
[Customization — Export](./customization.md#export). For PDF and print-specific
options, see [PDF export and print layout](./export-pdf.md).

---

# React table Excel export — xlsxWriter

▶ **See it working:** [export a grouped table to XLSX](https://adapttable.orwamahmoud.com/react/demo/mantine/grouping/) — the Export button writes the grouped sheet with outline levels and bold totals.

`xlsxWriter()` turns the export button into a real `.xlsx` download. It
ships as `@adapttable/core/xlsx`, a separate entry point with no
dependency: the workbook and its ZIP container are written by hand, and a
table that never imports the writer never carries the code.

```tsx
import { xlsxWriter } from "@adapttable/core/xlsx";
import { type ColumnDef, DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, radix, base-ui, shadcn, unstyled
import { exportCsv } from "@adapttable/mantine/export";

interface Person {
  id: string;
  name: string;
  zip: string;
  salary: number;
  active: boolean;
  hiredAt: Date;
}

const columns: ColumnDef<Person>[] = [
  { key: "name", header: "Name", width: 200 },
  { key: "zip", header: "ZIP" },
  {
    key: "salary",
    header: "Salary",
    accessor: (row) => `$${row.salary.toLocaleString()}`,
    exportValue: (row) => row.salary,
  },
  {
    key: "active",
    header: "Active",
    accessor: (row) => (row.active ? "Yes" : "No"),
    exportValue: (row) => row.active,
  },
  {
    key: "hiredAt",
    header: "Hired",
    accessor: (row) => row.hiredAt.toLocaleDateString(),
    exportValue: (row) => row.hiredAt,
  },
];

export function People({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      columns={columns}
      rowKey={(row) => row.id}
      features={[
        exportCsv<Person>({
          writer: xlsxWriter({ sheetName: "People" }),
          scope: "all",
          filename: "people.xlsx",
        }),
      ]}
    />
  );
}
```

The writer plugs into the same `exportCsv()` feature as CSV and PDF. Which
rows and columns leave the table, the lifecycle hooks, and the server-built
route are shared by every format; they are covered in
[Browser and server exports](./exporting.md) and
[Customization — Export](./customization.md#export). This page covers what
is specific to the spreadsheet.

## How it works

1. The export button resolves the scope and the column set, then resolves
   every cell once into an `ExportTable` — headers, keys, one array of values
   per row, plus row structure and suggested widths.
2. `xlsxWriter().build` turns that table into a workbook and returns an
   `ExportPayload`: the bytes in `parts`, the MIME type
   `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, and an
   empty `text`, because the file is binary.
3. `downloadExportFile` saves it. Without a `filename`, the file is
   `export.xlsx`; a `filename` you pass is used as given, so include the
   extension.

The button relabels itself **Export XLSX**, from `labels.exportFile("xlsx")`.
`onAfterExport` receives an empty `csv` for this format and the workbook in
`file.parts`.

The workbook holds one worksheet:

- a header row in bold on a shaded fill, frozen so it stays visible while the
  sheet scrolls;
- one row per exported row, with each value typed by what it is;
- column widths from the table's columns;
- outline levels for grouped and tree rows, with group headers and totals in
  the header's bold, shaded style.

## Cell values and types

Cells resolve exactly as they do for CSV: a column's `exportValue` first,
then its `accessor`, then its `sortValue`. The resolved value decides the
cell type, never its text:

| Resolved value              | Cell in the sheet                                                |
| --------------------------- | ---------------------------------------------------------------- |
| finite `number`             | number — sums, averages and number formats work                  |
| `boolean`                   | boolean (`TRUE` / `FALSE`)                                       |
| `Date` at midnight          | date serial with the `yyyy-mm-dd` format                         |
| any other valid `Date`      | date-and-time serial with the `yyyy-mm-dd hh:mm` format          |
| `string`                    | text, including text that looks numeric: `"01730"` stays `01730` |
| empty string, `null`, other | empty cell                                                       |

Two consequences follow from typing by value:

- **Give a formatted column an `exportValue`.** An accessor that returns
  `"$1,240.00"` exports text. `exportValue: (row) => row.salary` exports the
  number while the table keeps showing the formatted string — see
  [Exporting a different value than the screen shows](./customization.md#exporting-a-different-value-than-the-screen-shows).
- **A column with no `accessor` exports its field as display text.** The
  table derives an accessor for a bare-key column that renders the field as
  a string, so `{ key: "salary" }` writes `"1200.5"` as text. Add
  `accessor: (row) => row.salary` or an `exportValue` to keep the number. A
  bare-key column whose field is a `Date` still exports the date.

A `Date` counts as midnight when its UTC or its local clock reads
00:00:00.000. Other date-and-time values are written from their UTC instant.

Formula escaping does not apply. XLSX stores formulas in their own element
and the writer never emits one, so a cell reading `=CMD()` is text that is
displayed, never evaluated; `escapeFormulas` is ignored for this format.
Control characters that XML 1.0 cannot carry (everything below U+0020
except tab, newline and carriage return) are removed, and markup characters
are escaped.

## Column widths

Widths are in the spreadsheet's character units:

- a column with a pixel `width` gets `width / 8` characters, clamped to 8–40
  (`200` becomes `25`); a string width is read by its leading number, so
  `"200px"` behaves like `200`;
- a column without one gets its header length plus two, clamped to 8–40.

## Sheet name

`sheetName` defaults to `"Sheet1"`. Excel refuses a workbook whose sheet name
breaks its rules, so the name is corrected rather than passed through: each
of `: \ / ? * [ ]` becomes a space, the result is trimmed and cut to 31
characters, and an empty result becomes `"Sheet1"`.
`"Q1: payroll/draft"` is written as `"Q1  payroll draft"`.

## Grouped and tree exports

A grouped or tree-shaped table exports its structure, not a flat list of
leaves. Each row carries its role and its depth:

- group header rows sit at their grouping level, bold and shaded, with the
  group label and any group totals the table shows;
- leaves sit one level below their group, as outline levels Excel can
  collapse and expand;
- group footers and a `summaryRow` grand total are bold, shaded rows;
- a tree writes each node at its depth.

Group headers are written above their rows, and the sheet declares that
order, so the outline control for each group sits on its header.

Which leaves appear follows the scope. `scope: "page"` writes the view as
shown: a collapsed group keeps its header and leaves out its hidden rows.
`scope: "all"` and `scope: "selected"` include leaves inside collapsed
groups and folded tree nodes; `"selected"` then keeps only the groups that
still hold a selected leaf. `scope: "range"` stays a flat rectangle, because
the selection already named its shape. Cells covered by a
[row or column span](./row-spanning.md) are written empty in a flat export.

## Scope and columns

Every scope works unchanged, because the scope is resolved before the writer
sees anything:

| Scope              | Rows in the workbook                                                         |
| ------------------ | ---------------------------------------------------------------------------- |
| `"page"` (default) | The current page or loaded slice.                                            |
| `"all"`            | Every row matching the search and filters, in sort order.                    |
| `"selected"`       | The ticked rows, in table order, from every page the source holds.           |
| `"range"`          | The highlighted cell rectangle from [cell navigation](./cell-navigation.md). |

`columns: "visible"` (the default), `"all"`, or an array of keys chooses the
columns; a range names its own. `hideOnMobile` never removes a column from
the file, so a phone and a desktop download the same workbook. On a server
source, `scope: "all"` needs `onExportAll`, `request` or `fetchAll`; see
[Browser and server exports](./exporting.md).

## Building the workbook in Node

`buildTableXlsx` is the same workbook without a table. The
`@adapttable/core/xlsx` entry needs no React and no DOM, so it runs in
Node, an edge function or a worker:

```ts
import { writeFile } from "node:fs/promises";

import { buildTableXlsx, type ColumnMetadata } from "@adapttable/core/xlsx";

interface Person {
  id: string;
  name: string;
  team: string;
  salary: number;
  hiredAt: Date;
}

const columns: ColumnMetadata<Person>[] = [
  { key: "name", header: "Name", accessor: (row) => row.name, width: 200 },
  { key: "team", header: "Team", accessor: (row) => row.team },
  { key: "salary", header: "Salary", accessor: (row) => row.salary },
  { key: "hiredAt", header: "Hired", accessor: (row) => row.hiredAt },
];

const people: Person[] = [
  {
    id: "1",
    name: "Ada Lovelace",
    team: "Platform",
    salary: 1200.5,
    hiredAt: new Date(Date.UTC(2026, 0, 15)),
  },
];

const bytes = buildTableXlsx({ rows: people, columns, sheetName: "People" });
await writeFile("people.xlsx", bytes);
```

It returns a `Uint8Array`, which a web `Response` accepts as a body:

```ts
return new Response(bytes, {
  headers: {
    "content-type":
      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "content-disposition": 'attachment; filename="people.xlsx"',
  },
});
```

Direct calls resolve columns exactly as written. Give each column an
`accessor` or `exportValue` that returns the raw value; a column with
neither writes empty cells, except for a field holding a `Date`. A column
without a string `header` is headed by its `key`.

This is the natural pair for `onExportAll`: the browser sends the page-free
`ExportAllQuery` — search, filters, sort, grouping, the requested column keys
in order, `format: "xlsx"` and the filename — and the server builds the file
next to the data. The client half, with progress and cancellation, is in
[Server-built export with progress](./exporting.md#server-built-export-with-progress).

Pass `view` to write groups and `summary` to append a grand total. A `view`
lists every row in display order as `ExportViewEntry` values:

```ts
import { buildTableXlsx, type ColumnMetadata } from "@adapttable/core/xlsx";

interface Sale {
  id: string;
  region: string;
  amount: number;
}

const columns: ColumnMetadata<Sale>[] = [
  { key: "region", header: "Region", accessor: (row) => row.region },
  { key: "amount", header: "Amount", accessor: (row) => row.amount },
];

const north: Sale[] = [
  { id: "1", region: "North", amount: 120 },
  { id: "2", region: "North", amount: 80 },
];

const bytes = buildTableXlsx({
  rows: north,
  columns,
  view: [
    { role: "group", label: "North", level: 0, labelKey: "region" },
    ...north.map((row) => ({ role: "data" as const, row, level: 1 })),
    {
      role: "aggregate",
      label: "North total",
      level: 0,
      labelKey: "region",
      values: { amount: 200 },
    },
  ],
  summary: { region: "Grand total", amount: 200 },
});
```

A `group` or `aggregate` entry writes its `values` by column key and puts
`label` in the `labelKey` column when that cell has no value. With `view`
present, the workbook follows it and `rows` is not read on its own.

## Bundle isolation

`@adapttable/core/xlsx` is the entry to import from. The `@adapttable/core`
root still serves `xlsxWriter` and `buildTableXlsx`, marked `@deprecated`.
`@adapttable/core` declares `sideEffects: false`, so a bundler drops the
spreadsheet code from any build that does not call them. A bundle that
exports CSV only contains no XLSX code.

## Options

`xlsxWriter(options?)` returns an `ExportWriter` with `extension: "xlsx"`.

| Option      | Type     | Default    | Description                                              |
| ----------- | -------- | ---------- | -------------------------------------------------------- |
| `sheetName` | `string` | `"Sheet1"` | The worksheet's name, corrected to Excel's naming rules. |

`buildTableXlsx(options)` returns `Uint8Array` workbook bytes.

| Option      | Type                                         | Default    | Description                                                                |
| ----------- | -------------------------------------------- | ---------- | -------------------------------------------------------------------------- |
| `rows`      | `readonly TRow[]`                            | required   | The rows to write, in order.                                               |
| `columns`   | `readonly ColumnMetadata<TRow>[]`            | required   | The columns to write, in order; `header`, `width` and value resolution.    |
| `sheetName` | `string`                                     | `"Sheet1"` | The worksheet's name.                                                      |
| `view`      | `readonly ExportViewEntry<TRow>[]`           | —          | Grouped or tree rows in display order; the workbook follows it when given. |
| `summary`   | `Readonly<Partial<Record<string, unknown>>>` | —          | A grand-total row appended in the bold total style, keyed by column key.   |

Both come from `@adapttable/core/xlsx`, which also exports the types they
use: `ExportWriter`, `ExportViewEntry`, `ExportPayload`, `ExportWriteContext`,
`ExportTable`, `ExportRowMeta`, `ExportRowRole`, `ColumnMetadata` and
`ColumnModel`.

## Notes

- One worksheet per file. The writer does not emit formulas, merged cells,
  cell colours beyond the header, group and total styling, or a
  right-to-left sheet view; text in any script is stored as UTF-8 and reads correctly, and a
  reader can switch the sheet's direction in the spreadsheet application.
- ZIP entries are stored uncompressed, which keeps the writer free of a
  compression library. The file is larger than one a spreadsheet application
  saves; past the browser's comfortable size, build it on the server with
  `onExportAll`.
- The archive timestamp is fixed, so the same table produces the same bytes
  every time — convenient for tests and caching.
- For CSV and the full export flow, see [Browser and server exports](./exporting.md);
  for PDF and print, see [PDF export and print layout](./export-pdf.md).

---

# React table PDF export and print layout

▶ **See it working:** [download a grouped PDF and print the same view](https://adapttable.orwamahmoud.com/react/demo/mantine/export/) — a real table, not a recording.

▶ **Try it live:** [open a Mantine starter in StackBlitz](https://stackblitz.com/github/orwa-mahmoud/adapttable/tree/main/starters/mantine?file=src%2FApp.tsx) — import `@adapttable/core/pdf`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

A downloaded PDF and a printed page are the same view — the columns, group
structure and page breaks the reader can actually see — shipped as
`@adapttable/core/pdf` so a table that never imports it never pays for it.
No PDF library.

```tsx
import { pdfWriter, printTable } from "@adapttable/core/pdf";
import { DataTable } from "@adapttable/mantine";
import { exportCsv } from "@adapttable/mantine/export";

<DataTable
  data={people}
  columns={columns}
  rowKey={(row) => row.id}
  features={[exportCsv({ writer: pdfWriter(), scope: "all" })]}
/>;
```

`pdfWriter()` plugs into the export button through the same
`exportCsv()` seam as [CSV](./exporting.md) and [XLSX](./export-xlsx.md), with the same
scopes (`page`, `all`, `selected`, `range`) and the same column subset.
The button relabels itself **Export PDF** from `labels.exportFile("pdf")`.
`buildTablePdf` is the same file, for a host assembling rows by hand.

Print is a different verb. `downloadExportFile` cannot open a dialog, so
`openPrintLayout` (an `ExportTable`) and `printTable` (rows and columns)
load `buildPrintDocument` into a hidden iframe and call `window.print()`.
`buildPrintTableHtml` is the `<table>` alone; `printStyles` is the
stylesheet — repeating `thead`, `break-inside: avoid` on rows and groups,
column widths from the table, `padding-inline-start` so a tree or a
group indents under RTL. `PrintLayoutOptions` / `PdfWriterOptions` /
`PrintPageSize` / `PrintPageBreak` configure title, direction, paper and whether a
top-level group starts a new page (`pageBreak: "group"`). Paper defaults
to A4 landscape; direction inherits `document.documentElement.dir` when
omitted, so print matches what the reader is looking at. `PrintLayoutOptions` also takes `caption` (a
visible caption when it should differ from `title`) and `lang` (the printed
document's language). `printTable` and `buildTablePdf` also take
`view` (grouped or tree `ExportViewEntry` rows) and `summary` (a grand-total
row).

What to print stays the host's call — the table never picks the rows for a
dialog it cannot open. Compose `print(onPrint)` and Print becomes a palette command; pass
`true` as the second argument and the toolbar draws a Print button beside the view controls,
captioned from `labels.print`. Both are opt-in, and the button needs the
handler as well as the second argument, so neither can appear on its own.

The PDF is written by hand (one page tree, no dependency). By default it
draws in Helvetica and embeds nothing, so the file stays a few kilobytes
and the alphabet stops at WinAnsi — glyphs outside it paint as `?` and
still travel in `/ActualText`. Give it a font and that limit lifts; see
[Fonts and non-Latin text](#fonts-and-non-latin-text) below.

## Fonts and non-Latin text

`font` takes a TrueType file as bytes — `Uint8Array` or `ArrayBuffer` —
and the writer embeds a **subset** of it: only the glyphs this table
drew. A 421 KB Arabic face embeds as about 15 KB (the whole exported file is
about 71 KB, recorded in [`scripts/bench-runs/2026-09-23.json`](https://github.com/orwa-mahmoud/adapttable/blob/main/scripts/bench-runs/2026-09-23.json)), which is what
makes the option usable on a CJK font at all.

```tsx
import { pdfWriter } from "@adapttable/core/pdf";
import { exportCsv } from "@adapttable/mantine/export";

const font = await fetch("/fonts/NotoSansArabic-Regular.ttf").then((res) =>
  res.arrayBuffer()
);

<DataTable
  features={[
    exportCsv({
      scope: "all",
      writer: pdfWriter({ font, direction: "rtl", title: "تقرير المبيعات" }),
      filename: "report.pdf",
    }),
  ]}
  …
/>;
```

Arabic needs more than glyphs, and it gets it. Letters take their
contextual shapes — initial, medial, final, isolated — lam and alef
become the single glyph they are written as, and right-to-left runs are
reordered for drawing with the Unicode bidirectional algorithm's
reordering rule, so a Latin product name, a date or a price inside an
Arabic sentence still reads forwards and brackets face the right way.
The logical string travels untouched in `/ActualText` and in the font's
`/ToUnicode` map, so copy-paste, search and a screen reader read the
sentence as written whatever order it was drawn in. Hebrew, Persian and
Urdu reorder the same way; Persian and Urdu letters shape too.

CJK needs neither shaping nor reordering — embed the font and the
subsetter does the rest.

What the option does not do:

- **OpenType shaping (GSUB).** Contextual alternates and a font's own
  ligature tables need a shaping engine, which is a dependency. Shapes
  come from the Unicode presentation forms instead: correct, readable,
  connected Arabic, drawn plainly where a face's own design would go
  further.
- **Bold.** A PDF font resource is one face, so a header row is stroked
  as well as filled rather than switching to a bold file.
- **Characters the font does not cover** — colour emoji, or Latin in an
  Arabic-only face — draw as `?`, the same fallback the built-in face
  uses. Pick a font that covers the scripts the table holds.
- **CFF-flavoured OpenType.** Those store outlines as PostScript
  charstrings; the writer throws with a message saying so rather than
  embedding megabytes whole. Use the `.ttf` build of the same family.

`openPrintLayout` and `printTable` take `font` too, and embed it whole as
an `@font-face` — the browser shapes text itself and needs every glyph.
Print does not require it: the browser already has fonts. Pass it when
the printed page must match the downloaded one, or when the machine doing
the printing cannot be assumed to have a face for the script.

Mobile cards use the same button and the same file. `hideOnMobile` never
shrinks an export; print and PDF are the column view, not a card list.
A grouped or tree-shaped table exports that structure, not a
denormalised leaf list — the same `ExportViewEntry` rows XLSX writes as
outline levels. Omit the import and nothing is drawn and nothing is
downloaded.

---

# React table with SSR, server components & streaming — Next.js App Router

AdaptTable renders on the server, hydrates without mismatches, and sits inside
Suspense and streaming boundaries — provided the client boundary goes in the
right place. This page says where that is and why.

**Related:** [Data tiers](./data-tiers.md) · [URL state](./url-state.md) ·
[Getting started](./getting-started.md)

## The short version

```tsx
// app/people/page.tsx — a server component
import { PeopleTable } from "./PeopleTable";

export default async function PeoplePage() {
  const people = await db.people.findMany(); // runs on the server
  return <PeopleTable data={people} />; // client component, see below
}
```

```tsx
// app/people/PeopleTable.tsx
"use client";

import { DataTable } from "@adapttable/mantine";

export interface Person {
  id: string;
  name: string;
  role: string;
}

const columns = [{ key: "name", sortable: true }, { key: "role" }];

export function PeopleTable({ data }: { data: Person[] }) {
  return <DataTable data={data} columns={columns} rowKey={(row) => row.id} />;
}
```

Fetch on the server, pass the rows down, render the table in a client
component. That is the whole pattern.

## Why the table is a client component

A table is interactive: it holds state for sorting, filters, the open editor,
the selection. React Server Components cannot hold state, so the table has to
sit on the client side of the boundary. That is a property of what a table is,
not a limitation of this one.

Every package that ships hooks carries the `"use client"` directive in its
build, so importing `DataTable` from a server component works without you
writing a wrapper. A test in the release gate asserts the directive is on every
built entry — if it were ever dropped, an App Router build would fail on the
first `useState` with an error pointing at your application rather than at us.

**The packages without hooks carry no directive** — every entry of
`@adapttable/core`, plus `@adapttable/i18n`, `@adapttable/server`,
`@adapttable/ai` and `@adapttable/cli`. They are plain data and pure
functions, so locale labels, URL codecs and query parsers can be imported and
run in a server component and their results passed down as props.

## Server rendering without a DOM

During SSR there is no `window`, `document`, `matchMedia` or `localStorage`.
The engine renders through `renderToString` with none of them present — the
frontend tier, the server tier, and the table shell are each covered by a test
that runs in a DOM-free environment.

Two seams matter when you render on a server:

- **`forceMobile`** decides the card/table layout explicitly. The automatic
  choice comes from a media query, which a server cannot answer; passing the
  value you want makes the server and the first client render agree on the
  layout, and `paginationMode="auto"` follows it.
- **`urlAdapter`** defaults to the browser History API, whose hydration
  snapshot is an empty query string. To render the requested slice on the
  server, pass the same explicit adapter in both renders — a router adapter
  that reads the request's search params on the server and the address bar on
  the client. With an explicit adapter the hydration snapshot is that
  adapter's own search, so both renders start from the same state.

```tsx
"use client";

import { DataTable } from "@adapttable/mantine";

import { useNextAdapter } from "./useNextAdapter"; // the recipe in URL state

export interface Person {
  id: string;
  name: string;
  role: string;
}

const columns = [{ key: "name", sortable: true }, { key: "role" }];

export function PeopleTable({ data }: { data: Person[] }) {
  return (
    <DataTable
      data={data}
      columns={columns}
      rowKey={(row) => row.id}
      urlAdapter={useNextAdapter()}
      forceMobile={false} // decided per request, e.g. from the user agent
    />
  );
}
```

[`useNextAdapter`](./url-state.md#nextjs-app-router) wraps `useSearchParams()`,
which Next.js answers from the request during SSR. A server-only
`createMemoryAdapter(query)` (from `@adapttable/react` or the kit) with no
adapter on the client does not match: the client hydrates from `""`.

## Hydration

The rule is the ordinary React one: the server's markup and the first client
render must match. Two things in a table can break it, and both have an answer
above:

- **Layout** — if the server guesses desktop and the client is a phone, the
  first render disagrees. Pass `forceMobile` when you render on a server; the
  layout and `paginationMode="auto"` both follow it.
- **URL-restored state** — sort, filters and page come from the query string.
  Pass one explicit router adapter to both renders and they start from the
  same state.

Anything read from `localStorage` — saved views, a stored column layout —
is applied after mount by design, so the first client render matches the
server and the stored state arrives immediately afterwards.

## Suspense and streaming

The table does not suspend. It renders whatever rows it is given, including
none, so it never blocks a streaming response by itself.

What suspends is your data. Put the boundary around the component that fetches:

```tsx
<Suspense fallback={<TableSkeleton />}>
  <PeopleTable /> {/* awaits its own data */}
</Suspense>
```

For a table that fetches on the client instead, `loading` drives the built-in
skeleton, and `skeletonRows` sets how many rows it shows — a Suspense boundary
is not needed for that case and adds nothing.

The table's first paint needs no measurement — column widths, sticky offsets
and virtualization all resolve after mount — so a table inside a late-arriving
chunk renders from its props alone, exactly as it does on a normal client
render.

## Notes

- Works the same in **Next.js (App and Pages Router), Remix, and Vite SSR**.
- Server components can fetch, sort and filter before the table ever sees the
  data — pass the finished rows and let the table page them, or use the
  [server tier](./data-tiers.md) and let it drive your endpoint.
- The `"use client"` directive is in the published build; you never add it to
  your own imports of AdaptTable.

---

# Server queries — parse and validate the table's query

The table puts its whole state in the URL. That is what makes a view
shareable and a page reloadable — and the moment that URL reaches a backend
it stops being state and becomes **user input**.

`limit=999999`. `sortBy=password`. A filter on a column that is not in the
table at all. Each is one fetch away from a slow query, a leaked field, or a
stack trace in a log.

```bash
npm install @adapttable/server
```

That is the whole install. The package runs in a route handler by definition,
so it holds no React: nothing in it renders, and nothing it imports does
either. An Express or Fastify service with no React in the project can install
it and parse.

## One call

```ts
import { parseTableQuery } from "@adapttable/server";

export async function GET(request: Request) {
  const query = parseTableQuery(request, {
    columns: ["name", "team", "budget"],
    maxLimit: 100,
  });

  return Response.json(await people(query));
}
```

`parseTableQuery` takes a `Request`, a `URL`, a query string or
`URLSearchParams` — so Next.js route handlers, Remix loaders and Server
Actions all work without an adapter — and returns a `ServerTableQuery`:

| Field            | What it is                                                                               |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `page`           | 1-based, always at least 1                                                               |
| `limit`          | clamped to the schema's ceiling                                                          |
| `offset`         | `(page - 1) * limit`, computed once so every caller does not                             |
| `search`         | the free-text [search](./search.md) query, absent when there was none                    |
| `sort`           | the multi-sort chain, outermost first                                                    |
| `groupBy`        | a single grouping column, when the schema allows it                                      |
| `groupByKeys`    | every grouping key, outermost first — at every level, with `groupByKeys: true`           |
| `filters`        | column filters, keyed by the name after `f_`                                             |
| `shapedFilters`  | at level 0: each filter's operator beside it, a range's bounds joined, values as strings |
| `typedFilters`   | at levels 2 and 3: each declared filter typed, its operator and value checked            |
| `filterTree`     | the advanced AND/OR tree                                                                 |
| `pivot`          | the [pivot configuration](./pivot.md)                                                    |
| `pivotCollapsed` | the folded pivot groups, by collapse key                                                 |
| `cursor`         | the opaque cursor, in cursor mode                                                        |
| `rejected`       | everything it refused, and why                                                           |

## The schema is an allowlist

`columns` is the reason this package exists. A `sortBy` that reaches your
database because nobody checked it is a column name chosen by whoever sent
the request.

```ts
{
  columns: ["name", "team", "budget"],  // what a client may name
  maxLimit: 100,                        // the largest page it may ask for
  defaultLimit: 25,                     // when it asks for none
  urlKey: "left",                       // when two tables share one URL
}
```

A schema cannot raise `maxLimit` past the table's own ceiling of 500.

The parser reads `q`, `page`, `limit`, `sort` (or `sortBy` + `sortDir`),
every `f_*` param, `groupBy`, `ft`, `pivot` and `cursor`, each under the
`<urlKey>.` prefix when `urlKey` is set. Session-only params — `groupAgg`,
`groupClosed`, `rowPin`, `formula`, `density`, the `col*` layout — are not
read.

## Four levels of checking

How much the parser checks is the schema's choice:

| Level | Schema                   | Filters come back as                                                                                                            | Refused                                                                                             |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 0     | `columns: "any"`         | `shapedFilters` — each filter's `op` beside it, a range's bounds joined into `{ min, max }` / `{ from, to }`, values as strings | Nothing for its name                                                                                |
| 1     | `columns: [...]`         | `filters` — one raw string per `f_*` param                                                                                      | A sort, filter, group, tree or pivot field outside `columns`                                        |
| 2     | `filters: { key: type }` | `typedFilters` — typed values, operators checked against the type                                                               | Level 1, plus an undeclared filter, an operator the type does not allow, a malformed number or date |
| 3     | `filters: FilterDef[]`   | `typedFilters`, as level 2                                                                                                      | Level 2, plus a value outside a static `select` / `multiSelect` / `checklist` option list           |

Level 0 still parses page, limit, sort, search, filters and the tree — it only
stops checking names. The names are then the client's own words: map them to
your fields, and never interpolate them into SQL.

A column-list schema without `filters` returns the fields in the table above
and no typed view. At levels 2 and 3 the typed filters are:

```ts
const query = parseTableQuery(request, {
  columns: ["name", "team", "budget", "hiredAt"],
  filters: {
    name: "text",
    team: "multiSelect",
    budget: "numberRange",
    hiredAt: "dateRange",
  },
});

query.typedFilters;
// {
//   name:    { type: "text", op: "contains", value: "ada" },
//   team:    { type: "multiSelect", op: "in", values: ["Core", "R&D"] },
//   budget:  { type: "numberRange", op: "between", min: 1000, max: 5000 },
//   hiredAt: { type: "dateRange", op: "gte", from: "2024-01-01" },
// }
```

When the link names no operator, a filter reads the way the table matches
it: text as `contains`, and a number or date range by the bounds it carries —
`between` for both (inclusive), `gte` for a lower bound alone, `lte` for an
upper bound alone. A date filter's `eq`, the table's other spelling of `on`,
arrives as `on`, in `typedFilters` and in the filter tree alike. A
relative date arrives as `{ op: "relative", relative: "last:7" }`, and a
`numberRange` `in` / `notIn` as `values`. Filter types the host registered go
in `filterTypes` (a `FilterTypeSpec` fits) and come back as
`{ type: "custom", filterType, op, value }`. At levels 2 and 3 the AND/OR
tree gets the same checks per condition: a declared key, an allowed operator,
a value of the type's shape — and, as always, one bad condition drops the
whole tree.

Level 3 takes the same `FilterDef` objects the browser passes to `filters(…)`
— import them on the server from wherever the table's definitions live. A
static `options` list is enforced; `options: "auto"` and a loader are accepted
as they are.

### Scoping filters by user or role

The schema is built per request, so permission is passing the subset a caller
may use:

```ts
import { parseTableQuery, pickFilters } from "@adapttable/server";

const query = parseTableQuery(request, {
  columns: COLUMNS,
  filters: pickFilters(FILTER_DEFS, allowedFilterKeys(user)),
});
```

A filter outside the subset is refused like any undeclared one.

### Multi-value filters and nested grouping

The table writes a multi-value filter (`multiSelect`, checklist) as ONE
parameter: entries joined with commas, each percent-encoded, so a value may
itself contain a comma. `typedFilters` splits it; at level 1 the raw string
is in `filters`, and `splitFilterValues(raw)` is the exact inverse.

`groupByKeys` lists every grouping key, outermost first
(`groupBy=team,status` → `["team", "status"]`), each checked against
`columns`. It is reported at every level when the schema sets
`groupByKeys: true`. `groupBy` keeps its single-key meaning.

### What replaces a hand-written workaround

| Hand-written                                                     | Declared instead                                                                                  |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `budgetMin` / `budgetMax` listed in `columns` to let a range in  | `filters: { budget: "numberRange" }` — one `typedFilters.budget` with `op`, `min` and `max`       |
| Splitting `"Core,Data"` on commas by hand                        | `splitFilterValues(raw)` at level 1, or a declared `multiSelect` / `checklist` for `values`       |
| `f_<key>Op` refused on a column list, so the operator is guessed | Declared `filters` — the operator is read, checked against the type and returned beside the value |
| Splitting `groupBy` on commas by hand                            | `groupByKeys` — every key, outermost first, each one checked                                      |

### Without a parser

A host that owns both ends can skip the URL entirely: send the
`TableQueryParams` object `onQueryChange` hands you as JSON, and read it on the
server as the typed object it already is. `parseTableQuery` is for the case the
URL is the request — a shared link, a server render, a route handler.

## Forgiving by default, strict on request

It never throws. Anything invalid is dropped and reported:

```ts
const query = parseTableQuery(request, schema);

query.rejected;
// [{ param: "sortBy", value: "password", reason: "not a sortable column" }]
```

A stale bookmark should give a sensible table, not a 500 — so the default is
to degrade. A route that would rather reject has the list to do it with:

```ts
if (query.rejected.length > 0) {
  return Response.json({ error: query.rejected }, { status: 400 });
}
```

## Filter trees are all or nothing

An unknown field discards the **whole** tree rather than one condition.
Dropping a single condition out of an AND quietly _widens_ the result set,
which is the one failure mode a filter must not have — a request that should
have returned three rows returning three thousand is worse than one that
returned none.

Sorting and pivoting are different: an unusable sort level or pivot field is
dropped on its own, because losing one level of an ordering is a smaller lie
than losing the ordering, and neither can widen anything.

A pivot parameter carries more than column names — whether subtotals and grand
totals are shown, and which groups are folded. Those are the client's view of
its own table, so they arrive as sent: the schema filters the axes and the
measures, and `pivot.subtotals`, `pivot.grandTotals` and `pivotCollapsed` pass
through. The folded keys are dimension **values** rather than columns — a team,
a region — so nothing can vouch for them and nothing pretends to: parameterise
them like a search term.

## The types

`parseTableQuery(input, schema)` takes a `QueryInput` — a `Request`, a `URL`,
a query string or `URLSearchParams` — plus a `QuerySchema`, and returns a
`ServerTableQuery`.

`QuerySchema` is the allowlist: `columns`, `filters`, `filterTypes`,
`groupByKeys`, `maxLimit`, `defaultLimit`, `urlKey`. Declared `filters` are
`ServerFilterDef`s — the `key`, `type` and optional `options` of a `FilterDef`,
which fits as it is — and `filterTypes` are `ServerFilterType`s (`type`, `ops`,
`defaultOp`), which a `FilterTypeSpec` fits. `ServerTableQuery` is the
table above, where `filters` values are `ServerFilterValue` (one string, or an
array for a repeated param), `shapedFilters` is `ShapedFilter` per key,
`typedFilters` is `TypedFilter` per key (`TextFilter`, `SelectFilter`,
`ListFilter`, `BooleanFilter`, `NumberRangeFilter`, `DateRangeFilter`,
`CustomTypedFilter`), `groupByKeys` lists every grouping key, `pivotCollapsed`
is absent rather than empty when nothing is folded, and `rejected` is a list of
`QueryRejection` — each carrying the `param` it came from, the `value` that
arrived, and the `reason` it was refused.

## Decoding a parameter yourself

`@adapttable/core/query` is the model without React — the encodings on their
own, which is what this package is built on:

```ts
import { deserializePivot, parseFilterTree } from "@adapttable/core/query";

const tree = parseFilterTree(params.get("ft"));
const config = deserializePivot(params.get("pivot"));
```

It exports the `ft=1.{…}` codec (`parseFilterTree`, `serializeFilterTree`,
`isActiveFilterTree`, `FILTER_TREE_PARAM`, `FILTER_TREE_VERSION`), the
`pivot=rows:…` codec (`serializePivot`, `deserializePivot`, and
`serializePivotState` / `deserializePivotState` for the folded groups as well),
the `formula=` codec (`serializeFormulaColumns`, `deserializeFormulaColumns`
— it yields formula text and never evaluates it), `isFilterGroup` for walking
a tree, and the types those speak in — `QueryCondition`, `QueryFilterGroup`,
`SortLevel`, `SortDirection`, `SortableValue`, `DisplayValue`, `PivotConfig`,
`PivotMeasure`, `PivotUrlState`, `FormulaColumnSpec`, `FormulaValue`,
`AggregateName`, `AggregateOrderedValue` and `Aggregator`. The filter model is
there too: `FILTER_TYPES`, `RANGE_SUFFIXES`, `FILTER_OP_SUFFIX`, `TEXT_OPS`,
`NUMBER_OPS`, `DATE_OPS`, `parseRelativeToken`, and the `FilterDef`,
`FilterType`, `FilterOption`, `FilterOptionsSource` and `FilterTypeSpec`
types.

Every one of those names is also on `@adapttable/core`,
`@adapttable/core/pivot` or `@adapttable/core/formula`, from the same source
module. The narrow entry leaves out the engine, sources and models, so a
backend loads only the codecs. Like every `@adapttable/core` entry it imports
no React and carries no `"use client"` boundary, and the encoding it reads is
the same one the table wrote.

Reach for it when you want the pieces; reach for `parseTableQuery` when you
want the allowlist, which is almost always.

Related: [data tiers](./data-tiers.md) · [URL state](./url-state.md) ·
[filtering](./filtering.md) · [pivot tables](./pivot.md)

---

# React table AI assistant — native widgets and active capabilities

A table can tell an agent what it can do **right now**, without sending every
row or every feature guide up front.

Use the [optional native assistant](#the-optional-widget) or the headless
`useTableAssistant` controller to build a conversation around that contract.
Your application supplies the transport; table operations still pass through
the same permissions, validation and approval path.

That contract lives in `@adapttable/ai`. It is optional. `@adapttable/core`,
every adapter root, and `@adapttable/server` import none of it. Compose
`tableAgent` from `@adapttable/ai-react` when a table should publish a
manifest; omit the import and the bytes stay out.

## What is wired, not what is installed

Capabilities come from the live table:

- A table with search and pagination advertises `view.setSearch` and
  `view.setPage`.
- Grouping, filters, export, editing and reorder appear only when that
  feature is composed **and** the host callback (where a write needs one)
  is present. `view.setGroupBy` needs the grouping panel (`grouping-panel`),
  because a static `grouping(key)` reimposes its key; `view.setAggregations`
  appears with either grouping feature when a column is eligible.
- `view.setSelection` appears when selection is wired (`apply.setSelection`).
- `view.pinColumn` appears when column pinning is wired and at least one
  column is pinnable. `view.hideColumn` and `view.setColumnOrder` appear
  when a layout-owning feature (the Columns menu) is composed. `view.pinRow`
  appears when row pinning is wired. These are view operations, so none
  takes the write-approval path.
- `views.apply` appears when `featureIds` includes `saved-views` and
  `apply.applyView` exists.
- `rows.read` / `rows.resolve` appear when the table has columns.
  `rows.read` redacts `readable: false` cells and is bounded by
  `limits.readMax`. `scope: "full"` requires `source.fullDataset === true`.
- `rows.add` / `rows.delete` appear when the host apply methods exist and
  `writePolicy` is `"allow"`. `rows.delete` is destructive, and takes the same
  row references `edit.cells` does — a stable `rowKey`, or a 1-based
  `position` in a named `scope` — resolved before any row is removed.
  `rows.add`, `rows.delete` and `rows.reorder` have no staging path: under the
  default `commit: "stage"` they return `commit-incompatible`, so a table that
  offers them sets `commit: "immediate"`.
- `rowAction.<key>` and `bulkAction.<key>` appear for every row and bulk
  action the host composed — see [row and bulk actions](#row-and-bulk-actions).
- Data-layer truth comes from the source's
  [`TableSourceCapabilities`](./data-tiers.md) — the manifest copies those
  fields and never re-infers them from shape.

Package availability never participates. Installing `@adapttable/ai` does
not enable grouping on a table that never imported it.

## Filters

`view.setFilters` is the extra bag the table already applies — the same
keys the filter form writes (`team`, `salaryMin`, `salaryOp`). `describe`
lists each visible filter's type, operators and, when the static list is
short enough, its options. A `{ key, op, value }` array is accepted and
converted to that bag.

`FilterDef.ai` controls what the assistant sees. Omit it and the filter is
visible, with options sent only when there are 50 or fewer static choices.
`ai: false` hides the filter. `{ options: false }` keeps the filter and
omits the values — the usual 10k-customer case. `{ options: 10 }` raises or
lowers that cutoff. A list over the cutoff is omitted, not truncated, so a
sample cannot look like the full set. `"auto"` and async loaders are never
fetched into the prompt.

`view.describe` reports the current extras and the same catalog
(`AgentFilter` / `AgentFilterOption`).

Pagination, sort and search already publish current state and a typed
schema (`page` / `pageMax`, `sortBy` / sortable columns, the search
string). Filters were the gap this catalog closes.

## Pinning

Pinning is addressing, not styling, so both capabilities take identity rather
than a position on screen.

`view.pinColumn` takes a column `key` and a **logical** `side`: `"start"` is
the inline-start edge, which is the right edge under `dir="rtl"`. The same
call is therefore correct in both writing directions. Pass `side: null` to
unpin. A column the host marked `pinnable: false` refuses a pin but still
accepts an unpin, so a column the host pinned itself is never stranded. The
end edge belongs to the table's trailing actions column, which is chrome an
agent never addresses.

`view.pinRow` takes a `side` of `"top"` or `"bottom"` — physical, because a
pinned row sits above or below the scrolled body in every direction — plus a
row reference. Address the row by stable `rowKey`, or by 1-based `position`
with the `scope` and the `expectedRevision` that position was read at; a
position read against a view the table has since left is refused rather than
applied to whatever row now sits there. Summary rows are chrome, not data,
and cannot be pinned this way.

`view.describe` reports the live `pinnedColumns` map and `pinnedRows` lists,
so unpinning is an inverse of what is actually pinned rather than a reset of
the layout.

## Assistant contracts

A conversational assistant is a wrapper around this same executor — there is
no chat-specific dispatcher. `@adapttable/ai` exports the shapes a controller
and a widget are written against: `AssistantRequest`, `AssistantAction`,
`AssistantProposal`, `AssistantOutcome`, `AssistantTurn`,
`AssistantConversation` and the `AssistantPlanner` seam that turns a sentence
into actions.

An `AssistantAction` is exactly the `(capabilityKey, args, expectedRevision,
idempotencyKey)` tuple `execute` already takes, so a planned turn is governed
identically to a scripted call, and an action planned against a stale view
fails instead of applying to a different one.

`AssistantSuggestion` is an authored prompt with a stable `id`, a localizable
`title`, the `prompt` it sends, and the capability keys it `requires`. Suggestions are never derived
from capability keys — a key is not a sentence.
`eligibleSuggestions(suggestions, available)` hides the ones this table
cannot run, and `assertUniqueSuggestions` catches a repeated id. A capability
definition may contribute its own through `presentation`.

Nothing in these contracts imports React or calls a model.

## The headless assistant

`@adapttable/ai-react` turns those contracts into a conversation, and
still renders nothing. `useTableAssistant({ session, transport, suggestions })`
returns `status`, `busy`, `messages`, `draft`/`setDraft`, `send`, `stop`,
`clear`, the live `suggestions`, `runSuggestion`, `open`/`setOpen`, `error` and
`errorCode`, plus the pending `approval`, `alwaysAllowed` /
`revokeAlwaysAllow`, `undo` / `undoTurn` / `undoAction`, `interrupted`,
`resumable` / `resume`, `progress` and `answer` for a structured question. A host renders its own panel from those; the widget each kit
ships is written against the same values, so it is a convenience and never a
requirement. `examples/ai-assistant-custom-ui.tsx` is a complete panel with no
widget in it.

The rules it keeps:

- **One send at a time**, reserved before any await, so two clicks in one tick
  cannot interleave two turns' actions against one table.
- **A draft survives a failed turn.** It is cleared optimistically and put
  back if the turn fails — unless the reader typed something else meanwhile.
- **Stopping is not failing, and nothing is retried.** An action whose outcome
  is unknown stays unknown; the assistant never sends it twice.
- **A late reply is dropped.** A turn belonging to a previous table, or to a
  panel that has unmounted, never writes into the transcript.
- **Closing the panel discards nothing** — not the draft, not the transcript,
  not a submitted action.
- **A new session is a new conversation.** Switching tables aborts the turn in
  flight and starts empty, so history never crosses between tables.

`transport` may be a fresh object every render; the controller reads the
latest one rather than reconnecting on its identity. A host that genuinely
swaps transports — a backend for a scripted one — says so with `transportKey`,
because a backend must never quietly become a simulated one.

Receipts come from results, never from an outer flag. `receiptFromResult` and
`receiptsFromResults` report `executed`, `staged`, `partial`, `rejected`,
`awaiting-approval`, `cancelled`, `stale` or `failed`; `turnStatus` summarizes
a turn as `applied`, `partial`, `none`, `cancelled` or `failed`. An approved
write that has not reached the host is `staged`, not executed — Save is still
the reader's, on the table's own dirty path.

A transport is the only thing that knows about HTTP or a model.
`assistantHttpTransport` on `@adapttable/ai/http` adapts the existing backend
bridge; a host writing its own implements `AssistantTransport` from
`@adapttable/ai` and pulls in neither.

## The optional widget

Every kit ships a panel on `@adapttable/<kit>/assistant`, and it is a separate
entry point on purpose: a table that never imports it carries none of it.

```tsx
import { TableAssistant } from "@adapttable/mantine/assistant";
import { useTableAssistant } from "@adapttable/ai-react";

const assistant = useTableAssistant({ session, transport, suggestions });

<TableAssistant
  assistant={assistant}
  open={assistant.open}
  onOpenChange={assistant.setOpen}
/>;
```

`TableAssistant` takes `TableAssistantProps`: the `assistant` view, `open` and
`onOpenChange`, an optional `presentation` (`TableAssistantPresentation` —
`"panel"` beside the table, `"sheet"` for a modal on a narrow viewport, or
`"floating"`), `labels`, `className`, `launcher` (set `false` when the host
supplies its own trigger — the toolbar button and the floating launcher drive
ONE panel), `onSettings`, `approval`, `receipts`, [`speech`](./ai-voice.md), `greeting`, `note`,
`accent`, `avatars`, `boundary`, `dir` and `messageAction`. `tableAssistant()` binds the same component to the
`TABLE_ASSISTANT` slot for hosts that compose it as a feature.

The panel is a sibling of the table, never a cell inside it, so it can sit
beside the grid without covering the rows a reader is asking about.

### What the panel does, in every kit

Structure, keyboard and announcements live in `TableAssistantChrome`
(`TableAssistantChromeProps`); each kit fills `TableAssistantSlots` with its
own `Panel`, `Sheet`, `Window`, `Button`, `Composer` and `Badge`, and
optionally `Menu` and `LanguageChip` (`TableAssistantPanelProps`, `TableAssistantSheetProps`,
`TableAssistantButtonProps`, `TableAssistantComposerProps`,
`TableAssistantBadgeProps`). Core draws no control, so a Mantine table's
assistant is Mantine and an antd table's is antd —
`createAdapterTableAssistantFeature` is what an adapter calls to bind its own.

- **Empty state** asks what to do, then offers only the suggestions this table
  can actually run.
- **Enter sends, Shift+Enter starts a line**, and Enter mid-IME-composition
  belongs to the IME — sending there would post a half-written word.
- **Send becomes Stop** while a turn runs. A disabled composer always says
  why rather than becoming a dead end.
- **Roles are named, not coloured.** Each message shows its speaker, and each
  receipt says in words what became of the action. A staged write says it
  still needs saving in the table.
- **New messages follow only when the reader is already at the bottom**;
  otherwise the panel offers to take them there, so an earlier result stays
  readable.
- **Escape closes the panel**, unless something inside it already answered —
  one key never dismisses two things. Closing returns focus to the launcher.
- Backend text is rendered as text, never as markup.

The view it reads is `TableAssistantView`, built from
`TableAssistantMessageView`, `TableAssistantReceiptView` and
`TableAssistantSuggestionView`. `useTableAssistant`'s return satisfies it, and
so does a host driving the panel from its own state. `assistantIsBusy` and
`assistantIsUsable` answer the two questions a host's own chrome usually asks
of a status token.

## Six ways to wire it

Every one of these runs through the SAME governed executor. What changes is
how much of the UI you keep.

**1 — The ready widget.** The short path: a panel in your kit's own
components, beside the table.

```tsx
import { useTableAssistant } from "@adapttable/ai-react";
import { assistantHttpTransport } from "@adapttable/ai/http";
import { TableAssistant } from "@adapttable/mantine/assistant";
import { tableAgent } from "@adapttable/ai-react";

const transport = useMemo(
  () => assistantHttpTransport({ endpoint: "/api/table-agent" }),
  []
);
const assistant = useTableAssistant({ session, transport, suggestions });

<DataTable {...props} features={[tableAgent({ tableId: "orders" })]} />
<TableAssistant
  assistant={assistant}
  open={assistant.open}
  onOpenChange={assistant.setOpen}
/>;
```

`session` comes from the table. Either read it inside the table's tree with
`useFeatureState(TABLE_AGENT_STATE)`, or lift it out with
`tableAgent({ tableId, bridge: { attach: setSession } })` when the panel is a
sibling.

**2 — Your own launcher.** The floating launcher and a toolbar button drive
one panel, so turn the built-in one off and open it yourself.

```tsx
<button type="button" onClick={() => { assistant.setOpen(true); }}>
  Ask AI
</button>
<TableAssistant
  assistant={assistant}
  open={assistant.open}
  onOpenChange={assistant.setOpen}
  launcher={false}
/>;
```

**3 — A controlled panel.** Own the open state and the surface. Pass
`presentation="sheet"` on a viewport too narrow for a table and a panel side
by side, and the kit's own modal is used.

```tsx
const [open, setOpen] = useState(false);
const narrow = useMediaQuery("(max-width: 900px)");
const assistant = useTableAssistant({
  session,
  transport,
  open,
  onOpenChange: setOpen,
});

<TableAssistant
  assistant={assistant}
  open={open}
  onOpenChange={setOpen}
  presentation={narrow ? "sheet" : "panel"}
  launcher={narrow}
/>;
```

**4 — Your own UI, our controller.** Keep the lifecycle, render nothing of
ours. `examples/ai-assistant-custom-ui.tsx` is a complete panel built this
way; the widget above uses these same public values, which is what makes it
optional rather than required.

```tsx
const a = useTableAssistant({ session, transport, suggestions });

<ol>
  {a.messages.map((m) => (
    <li key={m.id}>
      <strong>{m.role}</strong> {m.text}
      {m.receipts?.map((r) => (
        <span key={r.idempotencyKey}>
          {r.capabilityKey}: {r.status}
        </span>
      ))}
    </li>
  ))}
</ol>;
```

**5 — Your own transport.** The seam names nothing about HTTP or any model,
so this pulls in neither. Anything that turns a sentence into actions is
valid — a backend, an in-process planner, or a fixed script.

```ts
import type { AssistantTransport } from "@adapttable/ai";

const transport: AssistantTransport = {
  async send({ session, text }) {
    const result = await session.execute(
      "view.setFilters",
      { filters: planFilters(text) },
      session.manifest().viewRevision,
      crypto.randomUUID()
    );
    return { text: "Filtered.", results: [result], keys: ["view.setFilters"] };
  },
};
```

Pass the live revision, not a remembered one: an action planned against a view
the table has left must fail rather than apply to a different one.

**What a transport owes the panel.** `signal` is a request, and a transport is
your code: honour it if you can, by passing it to `fetch` or to whatever does
the waiting. The panel does not depend on that. If a stopped turn answers
anyway, its reply is dropped rather than appended, and Stop frees the composer
immediately rather than waiting for a transport that may never settle.

What a transport must NOT do is retry. Stopping cancels the panel's interest
in an answer; it does not undo a write that already reached the host, and it
cannot cancel work a backend has already started. An action whose outcome is
unknown stays unknown — sending it again is how one stopped edit becomes two.

**6 — The HTTP backend you already run.** `assistantHttpTransport` adapts the
existing bridge; `examples/ai-http-backend.ts` is the runnable server.

```ts
const transport = assistantHttpTransport({
  endpoint: "/api/table-agent",
  headers: { authorization: `Bearer ${yourEndpointToken}` },
});
```

That token is your endpoint's, never a model provider's. Provider credentials
belong on the backend; the browser never holds one, and this library contains
no model client to hold it with.

## What a reader is actually told

- **Eligibility is live.** Suggestions and capabilities are re-checked against
  the current manifest, so a feature the host turns off stops being offered
  rather than failing when pressed.
- **Descriptions are progressive.** `catalog()` is small and stays small;
  `describe(key)` fetches a schema only when something needs it.
- **Approval is not persistence.** Approving a write lets it reach the host.
  Under `commit: "stage"` the host callback is the staging one, so the change
  sits on the table's own dirty path and the panel says it still needs saving.
  Approving and saving are two separate acts by design.
- **Continuation is optional.** A local action receipt needs no second model
  call; nothing forces one turn to become two.
- **Sessions are isolated.** One session per table, one conversation per
  session. Switching tables aborts the turn in flight and starts empty, so a
  reply about one table can never land under another.

## Three portable calls

Any agent runtime can speak this:

1. `catalog()` — keys and one-line summaries, in a stable order.
2. `describe(key)` — the guide plus strict input/output JSON Schemas.
3. `execute(key, arguments, expectedRevision, idempotencyKey)` — validate,
   refuse a stale revision, replay an idempotent key, then dispatch.

Runtimes that support typed tools can wrap each described capability as its
own tool. The three calls stay the fallback.

Protocol identity is the schema version (`adapttable.agent.v1`) and the
capability keys. Labels may be translated for people; execution is
locale-independent.

## The manifest does not send rows

Initialization publishes:

- table id and view revision
- the enabled capability keys
- readable/writable column metadata
- how rows are addressed (`visible` / `page` / `full`)
- limits (`pageMax`, `readMax`) and policy (`write`, `approval`, `commit`)
- the source capability record

It never dumps the dataset or every feature instruction. Bounded
`rows.read` and write approval (`approval` / `commit` / kit chrome) live
in [`@adapttable/ai`](./ai.md). The kit strip uses `agent-approval`,
`agent-approval-list`, `agent-approval-approve`, `agent-approval-reject`,
and `agent-approval-row`. Escape rejects. Enter is not a silent confirm.

## Row and bulk actions

`tableAgent` offers every action the host composed with `rowActions(…)` and
`bulkActions(…)` as its own governed capability. Nothing else needs wiring:

| Capability         | Input         | Runs                                                   |
| ------------------ | ------------- | ------------------------------------------------------ |
| `rowAction.<key>`  | `{ rowKey }`  | The action's `onClick(row)`, as a click would.         |
| `bulkAction.<key>` | `{ rowKeys }` | The action's `onClick(ids, context)` on the selection. |

Each is a write, and `destructive` when its `confirm` is marked `danger`, so
the table's write policy, commit mode and approval apply before the host's
handler runs. An action's `ai.approval` overrides the table's policy for that
capability, field by field, exactly as `capabilityApproval` does; an action
with a `confirm` block asks a person unless its `ai.approval.policy` says
otherwise. `ai: false` keeps an action away from the agent. A host handler
cannot be staged, so the actions run on a `commit: "immediate"` table; a
staged table refuses them with `commit-incompatible`.

A row action refuses a row it is hidden or disabled for (`isHidden`,
`disabledReason`, `isDisabled`) before anything runs. A bulk action runs on
the current selection: the agent selects with `view.setSelection`, then passes
the same keys as `rowKeys`, and a selection that changed in between is
refused. The table's own add, duplicate, delete and pin controls are not
offered this way — they are `rows.add`, `rows.delete` and `view.pinRow`.

The table still never changes the data: the capability calls the host's own
handler, and the host decides what the action does.

Without React, `tableActionCapabilities(declared, source)` from
`@adapttable/ai` builds the same definitions for `createAgentSession`.
`declared` is a `DeclaredTableActions` — the table's `row` and `bulk` actions —
and `source` is a `TableActionSource`: `actions()`, `rowFor(rowKey)` and
`selectedIds()`, read each time a capability plans or runs, so it acts on the
live table. `tableActionSignature(declared)` says when the set changed; rebuild
the definitions then, because a session's capabilities are fixed when it is
built.

## Registering a capability of your own

`createAgentSession({ capabilities })` takes `AgentCapabilityDefinition`s. A
definition carries a namespaced `key`, a one-line `summary` for the catalog, a
`guide` with JSON Schema for its input and output, an `isEnabled(observation)`
that decides whether it is wired right now, and `execute`.

```ts
const archive: AgentCapabilityDefinition = {
  key: "orders.archive",
  summary: "Archive an order.",
  kind: "write",
  guide: { guide: "…", input: archiveInput, output: archiveOutput },
  isEnabled: (observation) => observation.writePolicy === "allow",
  execute: (context, args) => host.archive((args as ArchiveArgs).rowKey),
};
```

`kind` is what makes it governed. A `"write"` or `"destructive"` capability
goes through the same path as a built-in mutation, and the session — not your
handler — enforces it:

1. the table's write policy, then the commit mode;
2. `plan`, if you wrote one, to resolve a side-effect-free `CapabilityPlan`
   the approver can read;
3. approval, when the table's `approval` policy asks for it;
4. the revision and the permissions again, after every await;
5. only then `execute`.

A handler that never calls `onApprove` therefore cannot write unapproved, and a
denied or still-pending approval calls it zero times.

Staging is declared, not assumed. A governed capability defaults to
`staging: "unsupported"`, so a table running `commit: "stage"` rejects the call
with `commit-incompatible` before your handler runs rather than committing
something the host wanted staged. Set `staging: "supported"` when the
capability really can stage. Among the built-ins only `edit.cells` stages.

`AgentCapabilityContext` is what `execute` receives: the `observation` it was
authorized against, the host's `apply` callbacks, a live `observe()`, the bound
`onApprove`, the request's `signal` and `throwIfCancelled()`, an optional
`reportProgress`, and — for a governed write — the approved `plan`, the
resolved `commit` mode and, after a per-row decision, `approvedIndexes`.

### Wiring the review

The ready-made path is two props. The assistant hands you the write; the
panel draws it:

```tsx
import { useTableAssistant } from "@adapttable/ai-react";
import { TableAssistant } from "@adapttable/mantine/assistant";

const assistant = useTableAssistant({ session, transport });

<TableAssistant
  assistant={assistant}
  open={assistant.open}
  onOpenChange={assistant.setOpen}
  approval={assistant.approval}
/>;
```

`approval` is safe to pass always: the panel draws it only when the resolved
presentation names the widget.

A panel mounted outside the table cannot read its feature state, so the bridge
hands the same value over:

```tsx
const [approval, setApproval] = useState<AgentApprovalPending | null>(null);

tableAgent({ tableId: "orders", bridge: { approvals: setApproval } });
```

To draw the review yourself, read the model and render whatever you like. The
counting, the labels and the preview are all in it, so a custom surface says
the same things the built-in ones do:

```tsx
import { approvalReview } from "@adapttable/react/adapter";

function MyApproval({ pending }: { pending: AgentApprovalPending }) {
  const review = approvalReview(pending, labels);
  if (!review) return null;
  return (
    <aside>
      <p>{review.summary}</p>
      {review.items.map((item) => (
        <button
          key={item.id}
          onClick={() => pending.decideAt?.(item.index, true)}
        >
          {item.proposal.rowLabel ?? item.proposal.rowKey}
        </button>
      ))}
      <button onClick={() => pending.approve()}>{review.approveLabel}</button>
      <button onClick={() => pending.reject()}>{review.rejectLabel}</button>
    </aside>
  );
}
```

`decideAt` is absent when the write cannot be split — hide per-row controls
rather than drawing dead ones.

### One write at a time

An approval is one transaction, and a second write while one is open is
refused rather than queued behind it. Every decision control belongs to the
transaction it was made for: a control left over from an approval that has
settled does nothing, so a stale click cannot answer the next write. The
write settles exactly once, whichever comes first — the reader deciding, the
turn being aborted, or the last row being answered.

Approving is not saving. `commit: "stage"` puts an approved change on the
table's own dirty path, where the reader still presses Save; `commit:
"immediate"` calls the host save path and reports what it returned. Rejecting
stops a write that has not run. It does not undo one that already has —
cancellation after the host callback is the host's own concern.

### Where a waiting write is reviewed

Three surfaces can review an approval, and exactly one of them draws the
controls: whichever the resolved `presentation` names.

| `presentation`     | Where                                   |
| ------------------ | --------------------------------------- |
| `widget` (default) | In the conversation, under the messages |
| `table`            | A strip above the rows it changes       |
| `modal`            | The kit's own dialog, over the page     |

The others do not repeat the buttons. The assistant says a change is waiting
when the decision is being made elsewhere; that is all.

Every surface draws the same review, because they all read one model:

```ts
import { approvalReview } from "@adapttable/react/adapter";

const review = approvalReview(pending, labels);
review.changes; // 12
review.rows; //  8 — three edits to one row are three changes and one row
review.preview; // the first three
review.approveLabel; // "Approve all" — "Approve" for one, "Approve remaining"
//                      once any change has been decided
```

A long write opens with a summary — _12 proposed changes across 8 rows_ — and
the first three changes. **Review all 12 changes** opens the rest inside the
same surface: in widget mode the conversation gives way and **Back to
conversation** returns, rather than a second overlay opening over the first.

`Approve all` becomes `Approve remaining` the moment any single change is
decided, because a row already refused stays refused and the first label
would be a promise the control cannot keep. A running tally sits beside it.
A write with one change says `Approve` and offers no per-row pair: "all" of
one names a set that does not exist, and two controls answering the same
question is a decision the reader has to make before they can act.

A write that enumerates no rows — an opaque server operation — is shown by
name and its arguments as pairs, not as the JSON the capability will receive.
It gets no invented row count and no per-row checkboxes, and it is answered
whole.

Closing the assistant does not answer anything. The write stays parked and
the launcher still says so; reopening brings the review back.

### The reader and the model are told different things

A proposal has two before-values, and they are not the same value.

`WriteProposal.before` is what the MODEL is told. It is read at the agent's
own addressing scope, through the same readable-column allowlist as
`rows.read`, because it travels: the session returns it, and an HTTP or MCP
continuation sends it back to the backend. A row outside that scope therefore
has no before-value here, and a column marked `readable: false` never appears
in one.

What the person approving sees is resolved separately, in the React binding,
from the table already on their screen. That value never enters a proposal, a
result, or any transport — so a row the current filter hides still reads
correctly for them without widening what the model was given.

Being able to see the table is not entitlement to every cell in it. A column
the host marked unreadable resolves to nothing on that side too, and nothing
is reported as **Unavailable** rather than drawn as an empty cell:

```
Ada · ssn: Unavailable → redacted     // nobody could look it up
Ada · notes: — → "call back"          // the cell is genuinely empty
```

`beforeUnavailable` on the approval proposal is that distinction. A value is
never invented to fill the gap.

### Whether a human is asked, and where

Two questions, answered separately.

**Policy** is whether an agent has to wait for a person. **Presentation** is
where that person is asked. Turning approval off does not move a surface, and
choosing a surface authorizes nothing.

The table sets both once:

```ts
tableAgent({
  tableId: "orders",
  approval: { policy: "writes", presentation: "widget" },
});
```

`approval: "writes"` still works and means the policy alone. The defaults are
`writes` and `widget`.

A capability overrides either field on its own, through `capabilityApproval`
for a built-in key or `ai` on a custom definition:

```ts
tableAgent({
  tableId: "staff",
  commit: "immediate",
  approval: { policy: "writes", presentation: "widget" },
  capabilityApproval: {
    // Always ask for this one, wherever the table reviews approvals.
    "rows.delete": { approval: { policy: "required" } },
  },
});
```

Inheritance is per FIELD. Overriding the policy leaves the presentation as the
shared one, and vice versa — so a table can say "review in the widget" once and
then mark two sensitive capabilities as always-ask without repeating itself. An
absent entry changes nothing: there is no key whose absence means authorized.

`policy: "automatic"` skips the human confirmation and nothing else.
Permissions, schema validation, and the staging and save rules all still run,
and a column the table marked unwritable is still refused.

An entry carries overrides only. It never enables a capability the table does
not wire or one in `excludeCapabilities`, and `required` drops
`alwaysAllow` for that capability.

### Deciding a bulk write row by row

A reader can approve some of a bulk write and refuse the rest, and the session
then narrows `context.plan`: `proposals` and `payload` both describe exactly
the approved rows, in plan order.

`args` is not narrowed. It is what the model asked for, and rewriting it would
misreport the request. So a handler that works from `args` rather than from
`plan.payload` would apply rows the reader refused — and the session cannot
read your handler to find out which kind it is.

So you say. `partial: "supported"` is a promise that `execute` applies
`plan.payload`:

```ts
{
  key: "staff.raise",
  kind: "write",
  partial: "supported",
  plan: (context, args) => ({
    proposals: rows.map((row) => ({ rowKey: row.id, column: "salary", after: row.next })),
    payload: rows,
    perItem: true,
  }),
  execute: (context) => save(context.plan?.payload as Row[]),
}
```

The default is `"unsupported"`. An undeclared capability is offered to the
reader whole, and a row-by-row answer for it is refused with
`approval-not-decomposable` rather than quietly widened to "approve all" — so
`args` and `plan` always agree for handlers that never opted in.

Three things must all hold before a write is offered per item: the plan sets
`perItem: true`, the capability declares `partial: "supported"`, and `payload`
is an array lined up with `proposals` index for index. `rows.reorder` is the
counter-example among the built-ins — two proposals describe one indivisible
move, so it is always offered whole.

A malformed decision fails the call without writing anything: a position
outside the plan, a repeated position, or a non-integer returns
`approval-invalid`. Nothing is filtered and run anyway.

A `read` or `view` capability skips all of it. Nothing about a view operation
asks for write approval.

## Cancelling

Pass an `AbortSignal` to `execute` and the session stops at every seam it
owns: before your handler runs, after planning, after approval, and before
each row of a bulk write. Cancellation is not an approval question — a table
with `approval: "never"` and no `onApprove` cancels exactly the same way.

A multi-step handler cooperates by calling `context.throwIfCancelled()`
immediately BEFORE each side effect, and by passing `context.signal` to
anything that accepts one:

```ts
execute: async (context, args) => {
  const rows = await fetchArchivable(args, { signal: context.signal });
  context.throwIfCancelled();
  await context.apply.deleteRows?.(rows.map((row) => row.id));
  return { archived: rows.length };
};
```

Nothing here claims to undo a callback the host has already been given. That
is what decides the retry rule:

- **Cancelled before any write.** Nothing ran, so the idempotency key is left
  free and the same key may be sent again.
- **Cancelled part way through a bulk write.** The rows already written stay
  written and are reported in `results`; the rows after them are never
  attempted. The key now belongs to that partial outcome, and sending it again
  replays the outcome rather than writing the first rows twice.

---

# AI table API — sessions, approval and governed execution

`@adapttable/ai` exposes a table's available operations to an agent without
choosing a model provider. Discover capabilities, inspect their schemas and
execute validated actions against the current table. Applications retain
control of permissions, approval and persistence.

For connection examples, read [OpenAI, MCP and JSON integrations](./ai-integrations.md)
or [the HTTP backend guide](./ai-http.md).

## Start here

Three levels, in the order most teams want them. Each is complete on its own;
none is a prerequisite for the next.

**1. The ready experience.** A widget, a transport, and the table you already
have. The capabilities come from the table's configuration — you do not copy a
schema into a backend, and there is nothing to keep in step.

```tsx
import { useState } from "react";
import type { AgentSession } from "@adapttable/ai";
import { tableAgent, useTableAssistant } from "@adapttable/ai-react";
import { assistantHttpTransport } from "@adapttable/ai/http";
import { DataTable } from "@adapttable/mantine";
import { TableAssistant } from "@adapttable/mantine/assistant";

const transport = assistantHttpTransport({ endpoint: "/api/agent" });

function Orders({ rows }: { rows: Order[] }) {
  const [session, setSession] = useState<AgentSession | null>(null);
  const assistant = useTableAssistant({
    session: session ?? undefined,
    transport,
    // Only a genuine transport swap re-establishes the conversation.
    transportKey: "orders",
  });

  return (
    <>
      <DataTable
        data={rows}
        columns={columns}
        features={[
          tableAgent({
            tableId: "orders",
            writePolicy: "allow",
            approval: { policy: "writes", presentation: "widget" },
            bridge: { attach: setSession },
          }),
        ]}
      />
      <TableAssistant
        assistant={assistant}
        open={assistant.open}
        onOpenChange={assistant.setOpen}
      />
    </>
  );
}
```

`assistant.error` carries the last failure and each receipt says what
actually happened — `executed`, `staged`, `partial`, `awaiting-approval`,
`rejected`, `stale`, `failed` or `cancelled`. A staged write is not a saved one, and the
panel says so rather than reporting success.

**2. Your own agent, our executor.** You already have a model call and a reply
to parse. Map whatever it produced onto a capability key and arguments, and
call the session — the permission predicate, the revision check and the
approval policy all apply, whichever route reaches them.

```ts
const result = await session.execute(
  "view.setFilters",
  { filters: { team: ["Core"] } },
  session.manifest().viewRevision,
  // Your own replay identity. The same key twice never runs twice.
  `turn-${turnId}-1`
);
if (!result.ok) report(result.error); // never a silent retry
```

See [`examples/ai-custom-bridge.ts`](https://github.com/orwa-mahmoud/adapttable/blob/main/examples/ai-custom-bridge.ts).

**3. The conversation, without React.** `@adapttable/ai/assistant` is the whole
lifecycle — one send at a time, a draft that survives a failure, a late reply
dropped rather than appended — with no DOM and no HTTP. A binding for another
framework subscribes to it rather than re-deriving those rules.

```ts
import { createTableAssistant } from "@adapttable/ai/assistant";

const store = createTableAssistant({ session, transport });
const stop = store.subscribe(() => render(store.getState()));
store.connect();
// Always, on unmount or teardown: a disposed store drops its connection and
// cannot write into a surface that has gone.
onTeardown(() => {
  stop();
  store.dispose();
});
```

See [`examples/ai-assistant-store.ts`](https://github.com/orwa-mahmoud/adapttable/blob/main/examples/ai-assistant-store.ts)
and, for a custom panel in React,
[`examples/ai-assistant-custom-ui.tsx`](https://github.com/orwa-mahmoud/adapttable/blob/main/examples/ai-assistant-custom-ui.tsx).

The optional helpers add convenience, not permission. None of them is required
to use an agent you already have, and none of them can reach past what the
table wired.

```bash
npm install @adapttable/ai
```

The root entry is React-free and SDK-free. Use it from any agent runtime.
The React feature is a separate import.

```ts
import { createAgentSession } from "@adapttable/ai";
import { tableAgent } from "@adapttable/ai-react";
```

## `tableAgent(options)`

Compose it next to the other features:

```tsx
import { tableAgent } from "@adapttable/ai-react";
import { DataTable } from "@adapttable/mui";
import { agentApproval } from "@adapttable/mui";
import { filters } from "@adapttable/mui/filters";

<DataTable
  columns={columns}
  data={rows}
  rowKey="id"
  features={[
    filters([]), // column `filter` declarations need the feature
    agentApproval(),
    tableAgent({
      tableId: "orders",
      writePolicy: "allow",
      approval: "writes",
      commit: "stage",
      bridge: {
        publish: (manifest) => sendToRuntime(manifest),
        attach: (session) => (runtime.session = session),
      },
    }),
  ]}
/>;
```

`writePolicy` is `"allow"` (default) or `"deny"`. Deny strips every write key.
Allow still goes through the host's existing edit/reorder/add/delete
callbacks — the table never owns the data.

`approval` is `"writes"` (default — every mutating key), `"destructive"`
(every capability of kind `destructive` — `rows.delete` among the built-ins),
or `"never"` (skip chrome and `onApprove`; still validate and honour commit).
Host `onApprove?: (subject: ApprovalSubject, signal?: AbortSignal) =>
Promise<ApprovalResult>` replaces the kit strip when it is set; it resolves
`true` / `false`, or `{ approved: [indexes] }` for a per-row answer.

`commit` is `"stage"` (default — `edit.cells` goes to `apply.stageCells`, the
table's dirty path; Save still belongs to the reader) or `"immediate"` (the
host callback runs now). `rows.add`, `rows.delete` and `rows.reorder` have no
staging path and return `commit-incompatible` under `"stage"`, so a table that
offers them sets `commit: "immediate"`.

`readMax` bounds `rows.read` (default 50). `scope: "full"` requires
`source.fullDataset === true`. Readable-false columns are redacted.

`columns` overlays readable/writable/type on the published column metadata.

`capabilities` adds custom governed definitions (see
[registering a capability](./agent-capabilities.md#registering-a-capability-of-your-own)).
`excludeCapabilities` denies keys to the agent. `capabilityApproval` maps a
capability key to `{ approval: { policy?: "required" | "automatic",
presentation? } }` and replaces the table's `approval` for that one
capability. `webmcp: true | { exposedTo?, onRegister? }` registers the
capabilities as browser tools (see
[WebMCP](./ai-integrations.md#webmcp--an-agent-in-the-page)).

`bridge.publish` receives every new manifest (feature, column, permission or
policy change). `bridge.attach` receives the live
`catalog` / `describe` / `execute` session. Two tables each get their own
session; they do not share revision or idempotency state.

## Manifest shape

```ts
{
  schemaVersion: "adapttable.agent.v1",
  tableId: string,
  viewRevision: number,
  capabilities: string[], // built-in CapabilityKeys plus custom keys
  columns: {
    id, label, type, readable, writable, sortable,
    hideable?, pinnable?, visible?, ai?,
  }[],
  rowAddressing: { scope: "visible" | "page" | "full", key: "rowKey" },
  limits: { pageMax: number, readMax: number },
  pagination?: AgentPagination,
  aggregateOperations?: { id: string, operations: string[] }[],
  policy: {
    write: "deny" | "allow",
    approval: "writes" | "destructive" | "never",
    commit: "stage" | "immediate",
  },
  source: TableSourceCapabilities,
}
```

## Capability keys

Stable catalog order:

`columns.describe`, `view.describe`, `view.setPage`, `view.setSort`,
`view.setSearch`, `view.setFilters`, `view.setGroupBy`,
`view.setAggregations`, `view.pinColumn`,
`view.hideColumn`, `view.setColumnOrder`,
`view.pinRow`, `view.setSelection`, `views.apply`, `rows.read`,
`rows.resolve`, `export.run`, `edit.cells`, `rows.add`, `rows.delete`,
`rows.reorder`, then the table's own actions — `rowAction.<key>` for each row
action and `bulkAction.<key>` for each bulk action the host composed (see
[row and bulk actions](./agent-capabilities.md#row-and-bulk-actions)).

`view.setFilters` takes `{ filters }` — the extra bag the table already
uses (`{ team: ["Core"] }`, `{ salaryMin: 10000, salaryOp: "gt" }`) or an
array of `{ key, op, value }` conditions. `describe` lists the live
filters, operators and (when the static list is short enough) options.
`ai: false` on a `FilterDef` hides that filter; `{ options: false }` or a
number cap omits a large list rather than truncating it. Without
declarative defs the argument stays the host's own object.

`view.setAggregations` takes `{ set?, remove?, restoreDefaults? }` — add or
change specific column operations without replacing the others, remove
specific aggregations with the same suppression semantics as the panel, or
restore developer defaults. The whole request is validated before anything
is applied. It is advertised only when grouping can actually execute
aggregates. `describe` lists eligible columns and operation ids (never a
`calculate` function). A server-side apply reports `pending: true` until the
response that answers the new query arrives.

`view.pinColumn` takes `{ key, side }` where `side` is the logical `"start"`
or `null` to unpin. `view.hideColumn` takes `{ key, hidden? }` — omit
`hidden` or send `true` to hide, `false` to show. `view.setColumnOrder`
takes `{ key, index }` (0-based, hidden columns included) or `{ order }`
with every column id exactly once. `view.pinRow` takes `{ side }` — `"top"`,
`"bottom"` or `null` — with a `rowKey`, or a `position` plus the `scope` and
`expectedRevision` it was read at. These are view operations, so none takes
the write-approval path. See
[adaptive capabilities](./agent-capabilities.md#pinning).

`edit.cells` takes `{ edits: Array<{ column, value, rowKey?, position?, scope? }> }`
— each edit needs `rowKey` or a 1-based `position`. Positions resolve
before write. `rows.delete` addresses rows the same way:
`{ rows: Array<{ rowKey?, position?, scope? }> }`, resolved before anything
is removed, so a reference that names no row is refused while the deletion is
still a proposal. The execute result is

`{ ok, revision, idempotencyKey, error?, result: { proposals, applied, approval, approvalReason?, results? } }`.

`createAgentSession({ observe, apply })` is the same contract without React —
hand it the current observation and the apply hooks. See
[adaptive capabilities](./agent-capabilities.md).

## What the agent is told

`buildAgentContext(session, options?, inputs?)` on `@adapttable/ai/context`
produces the whole of it: the **contract** (what this table permits, which
changes rarely) and the **view** (where it is right now, which changes
constantly). Nothing else reaches a model, and the builder performs no I/O —
it reads no rows and makes no request.

```ts
import { buildAgentContext } from "@adapttable/ai/context";

const { contract, view, selection } = buildAgentContext(
  session,
  { profile: "compact" }, // omit for the unbudgeted default
  { filters: liveFilters, view: { page, limit, search } }
);
```

**Profiles.** `full` is the default: every guide and every column description
travels, bounded only by the hard byte limit. What a model's context window
costs is the backend's business, and trimming on its behalf means guessing —
a guess that drops the sentence saying a column counts thousands is paid for
by the reader who gets the wrong number back.

`compact` is there for a host that has measured its own backend and wants the
smaller payload: it names every capability but attaches the full guide only for
the ones a turn is likely to need, and strips column detail to make room. The
rest are fetched on demand, in one batched discovery round rather than one
request per key. `selection.selected` and `selection.deferred` say which went
which way, and `selection.notes` says why. Pass `tokenBudget` with either
profile to name your own ceiling.

**Budgets and sizes.** `selection.contractBytes` and `selection.viewBytes` are
UTF-8 bytes on the wire. `selection.estimatedTokens` is an estimate of prompt
size and says so: `selection.estimated` is `true` when nobody counted, and you
can pass your own `estimateTokens` to make it a measurement. Neither is a count
of model invocations — a turn is one invocation whatever the context weighs.

**Exclusions.** `createAgentSession({ excludeCapabilities })` and
`tableAgent({ ... })`'s equivalent remove a capability from the contract, the
suggestions and the executor at once. The table's own control is untouched: a
person can still filter a table whose agent may not.

**Versions.** `contract.version` names everything the contract says. Two
requests carrying the same version describe the same table; a backend that
pinned one and sees another knows to ask for the whole thing again.

**Column examples.** `ai.examples` on a column is what the author wrote.
`ai.sample: true` opts that column into live sampling, which is a separate,
deliberate call — `sampleColumnValues(session, key)` reads through `rows.read`
under the session's own permission predicate, caps at five distinct values,
revalidates each against the column's declared type, and never touches an
unreadable column. The contract marks those columns `sampled: true`, so nobody
confuses an author's example with somebody's data.

`tableAgent` does the reading for you: it collects the columns whose author
asked, samples them once when the contract changes rather than once per turn,
and hands the values in. A host building its own context calls
`sampleColumns(session, wanted)` and passes the result as `inputs.samples` —
the context builder performs no I/O of its own, which is why the read happens
outside it.

Sampling is for a column with no declared list of its own. A filter-backed
column already publishes its options in the filter catalog — the declared set,
complete, so no row can introduce a value the model has not been told about.
What sampling answers is the other case: free text, references, dates and
amounts, where the only way to learn how a value looks is to see one.

The values are read when the contract changes, so they illustrate the column
rather than tracking it. Five values were never the set anyway, which is why
the contract marks them `sampled: true` — a model needing the real list reads
rows or the filter catalog.

## Saying how far a long call has got

A capability that works through a thousand rows one call at a time has nothing
to say between "started" and its receipt, and a reader watching a spinner
cannot tell a slow write from a stuck one. Its execution context carries a
channel for that:

```ts
capabilities: [
  {
    key: "orders.settle",
    // …
    execute: async (context, args) => {
      const rows = rowsFor(args);
      for (const [index, row] of rows.entries()) {
        context.throwIfCancelled();
        await settle(row);
        context.reportProgress?.({
          done: index + 1,
          total: rows.length,
          label: "orders",
        });
      }
      return { settled: rows.length };
    },
  },
];
```

The conversation shows it where it is waiting, and it goes when the turn
settles. `label` is shown as given — this package has no translation for your
nouns, and inventing one would be worse than leaving it out.

**Progress is not a result.** The receipt still comes from what the handler
returned, a call that reported progress and then failed has failed, and none of
this involves the model: nothing is sent, and no second call is made to say the
work is done.

Wire `bridge.progress` to read it outside the table; a panel inside the table
reads it from the table's own state and needs nothing.

## Who owns the conversation

The panel keeps the transcript itself and sends every earlier message with each
turn, which is what a backend that remembers nothing needs. Both halves are
yours to change, and they are independent of each other.

**Where the messages live.** Pass `messages` and the panel renders the list you
hand it instead of the one it kept; `onMessagesChange` reports every change,
with the whole list. A different array replaces the transcript, which is how a
message that arrived somewhere else gets in:

```tsx
const [messages, setMessages] = useState(() => loadThread(threadId));

// Another device, a colleague, an agent working the same table.
useEffect(
  () => socket.on("message", (m) => setMessages((all) => [...all, m])),
  []
);

useTableAssistant({
  session,
  transport,
  messages,
  onMessagesChange: setMessages,
});
```

Handing the same array back is you holding what you were given; only a
different one replaces the transcript.

**How much of it travels.** `conversation` decides how much history goes out
with each turn. It never changes what the reader sees.

|                    | On the wire            | For                                                   |
| ------------------ | ---------------------- | ----------------------------------------------------- |
| `"full"` (default) | every earlier message  | a backend that keeps no session                       |
| `20`               | the last 20            | a long thread where resending all of it earns nothing |
| `0`                | this turn's text alone | a backend that holds the thread itself                |

```tsx
// The server owns the thread; it needs the question, not the history.
useTableAssistant({ session, transport, conversation: 0 });
```

## Stopping, losing the connection, and coming back

Three different things happen to a turn that does not end in a reply, and the
conversation reports which one:

- **Stop** — the reader ended it. The signal is raised, the remaining actions
  never run, and nothing is left running anywhere. `interrupted` is
  `"stopped"`.
- **Disconnect** — the connection was released, by an unmount, a table change
  or `disconnect()`. The backend was never asked to stop, so it may still be
  working. `interrupted` is `"detached"`, and the conversation stops waiting
  for a reply that can no longer reach it.
- **Resume** — rejoin work that is still running. The turn comes back on a
  fresh baseline: the table is read again before anything is applied, because
  it is not the table the turn started against.

A turn can only be detached if the transport named something to come back to.
It does that while the turn runs, through `onResumable`, and implements
`resume` to rejoin:

```ts
const transport: AssistantTransport = {
  send: async ({ text, onResumable, signal }) => {
    const job = await backend.start(text, { signal });
    // Named now, because a connection released later is too late to ask.
    onResumable?.(job.id);
    return toReply(await backend.wait(job.id, { signal }));
  },
  resume: async ({ handle, signal }) => {
    // Same replay identities as the first attempt, so a completed action is
    // answered from the session's record rather than run again.
    return toReply(await backend.wait(handle.token as string, { signal }));
  },
};
```

Without `resume`, releasing the connection ends the turn — which is the honest
outcome for a transport that cannot get back to it.

**What this package guarantees:** within the life of one session, an action
that already ran is not run again when a turn is resumed. The session keeps a
replay record per identity, and a resumed attempt that reuses its identities
gets the recorded result rather than a second execution.

**What the host owns:** everything that has to survive the page. A reload
builds a new session with an empty replay record, a new transcript and no
memory of what ran, so durable recovery is a host decision. Keep the handle
and hand it back:

```ts
useTableAssistant({
  session,
  transport,
  onDetach: (handle) => sessionStorage.setItem("turn", JSON.stringify(handle)),
  resumeHandle: restoredHandle,
});
```

A backend whose work outlives a page must also be idempotent across it — the
replay record that answers a repeated action is in the session that went away.

## Approval, undo and what a reader agreed to

`approval` answers two questions separately: **which** capabilities need a
human (`policy`), and **where** they are asked (`presentation`). A capability can
override either for itself, through `capabilityApproval`.

`alwaysAllow` is a third, and it is off unless you name the keys:

```ts
tableAgent({
  tableId: "orders",
  // A write that runs as one operation: kind "write", no row proposals.
  capabilities: [settleOrders], // key: "orders.settle"
  commit: "immediate",
  approval: { policy: "writes", alwaysAllow: ["orders.settle"] },
});
```

The control appears only for a capability on that list. It never appears for a
destructive one, never for a write that enumerates rows — `edit.cells`,
`rows.add` and `rows.delete` always ask — and never for a capability whose own
configuration demands a human every time; a host `onApprove` bypasses the
chrome entirely, so nothing there can reach past it.

A panel mounted beside the table rather than inside it cannot read the table's
feature state, so the standing decision travels through the bridge:
`bridge.alwaysAllowed` is called with an `AlwaysAllowedState` — the capability
keys currently waved through and a `revoke(key)` — and `useTableAssistant`
takes it as `alwaysAllow`. Without it a reader can allow a capability and have
no way to take it back.

```ts
const [allowed, setAllowed] = useState<AlwaysAllowedState | null>(null);

tableAgent({ tableId: "orders", bridge: { alwaysAllowed: setAllowed } });
useTableAssistant({ session, transport, alwaysAllow: allowed ?? undefined });
```

What a reader waved through is readable from the store as `alwaysAllowed` and
revocable with `revokeAlwaysAllow(key)`; it resets whenever the contract moves,
because "allow this" was said about a table that no longer exists in that
shape. A key that this table does not offer is an error at build time
(`ApprovalAlwaysAllowError`), not a control that silently never appears.

**Undo covers the view, per turn and per action.** The sanitized view is
captured before a turn's calls run and restored through the same capabilities
the agent used. A turn that did more than one thing also offers each action its
own control on its receipt card, because restoring the field that action wrote
is exactly that action and nothing else; a turn that did one thing offers only
the turn's, which is already the same control. The offer stands while the
fields it would put back still hold what the turn left in them — a reader
changing the page, a second agent, a source refresh or a later turn all end it,
and the panel says which. Writes are not part of it: staging, Save and the edit
history own those.

Receipt cards are on by default and `receipts={false}` on the assistant turns
them off for a host that keeps its own account of a turn. The record is
unchanged either way: the receipts stay in the conversation state.

## Protocol adapters

Each is an optional subpath, and each routes every call back through
`session.execute`. `http`, `json`, `openai`, `mcp`, `mcp-apps`, `ag-ui` and
`ai-sdk` stay out of the root graph; `assistant`, `context`, `voice` and
`webmcp` are also re-exported from the root entry.

| Subpath                    | For                                                             |
| -------------------------- | --------------------------------------------------------------- |
| `@adapttable/ai/http`      | The wire, the client and the assistant transport                |
| `@adapttable/ai/assistant` | The framework-free conversation store                           |
| `@adapttable/ai/context`   | The permitted context, and column sampling                      |
| `@adapttable/ai/voice`     | [Dictation](./ai-voice.md), in the browser or through a backend |
| `@adapttable/ai/json`      | Plain JSON tools and `AgentEnvelope`                            |
| `@adapttable/ai/openai`    | Strict function tools with OpenAI-safe names                    |
| `@adapttable/ai/mcp`       | MCP tools, resources and annotations                            |
| `@adapttable/ai/mcp-apps`  | The table as a view an MCP host embeds                          |
| `@adapttable/ai/webmcp`    | The table as browser tools for a page agent                     |
| `@adapttable/ai/ag-ui`     | The table as an AG-UI run's frontend tools                      |
| `@adapttable/ai/ai-sdk`    | The table as AI SDK client tools                                |

`@adapttable/ai-react` is the React binding: `tableAgent`,
`TABLE_AGENT_STATE`, `useTableAssistant` and `useSpeechInput`. It is the only one of these that imports React.

---

# React table AI integrations — OpenAI, MCP and JSON tools

`@adapttable/ai` does not host a model, a chat UI, or an AdaptTable service.
A live table publishes a compact catalog. Your runtime maps that contract
onto the tools it already speaks, then calls `session.execute`.

[Try the interactive demo](https://adapttable.orwamahmoud.com/react/demo/mantine/ai/)
— a real Mantine table you talk to. The demo answers a fixed set of example
requests with no model behind them; connect your own backend from the
assistant's settings for free-form conversation.

Nothing on this page is required to put a conversation in front of a reader.
If that is what you want, start with
[the optional widget](./agent-capabilities.md#the-optional-widget) — one panel
per kit — or
[the headless controller](./agent-capabilities.md#the-headless-assistant) if
you would rather draw it yourself.
[Six ways to wire it](./agent-capabilities.md#six-ways-to-wire-it) lays them
side by side, from the ready widget to a transport of your own.

This page is the layer underneath: how any agent runtime reaches the same
governed executor. See [adaptive capabilities](./agent-capabilities.md) and
[`@adapttable/ai`](./ai.md) for the session itself.

```ts
import { createAgentSession } from "@adapttable/ai";
import { executeEnvelope, toJsonTools } from "@adapttable/ai/json";
import { toOpenAITools } from "@adapttable/ai/openai";
import { mcpListChanged, toMcpResources, toMcpTools } from "@adapttable/ai/mcp";
```

The root entry stays React-free. `@adapttable/ai-react` holds the React
binding (`tableAgent`, `useTableAssistant`, [`useSpeechInput`](./ai-voice.md)). The JSON,
OpenAI and MCP subpaths never import a model SDK.

## Three integration levels

### 1. Custom frontend bridge

Transform any agent's action format, then call `session.execute`.

```ts
import {
  runCustomBridge,
  createBridgeSession,
} from "../examples/ai-custom-bridge";

const session = createBridgeSession({
  setFilters: (filters) => applyHostFilters(filters),
});

await runCustomBridge(
  session,
  { tool: "view.setFilters", input: { filters: { team: ["Core"] } } },
  "bridge-filter-core"
);
```

Compiling source: [ai-custom-bridge.ts](../examples/ai-custom-bridge.ts).

### 2. `AgentEnvelope` on your transport

Carry a versioned envelope over HTTP, a websocket, or postMessage. Parse
it in the browser or worker, then execute. There is no second argument
validator — `session.execute` owns that.

```ts
import { executeEnvelope, parseEnvelope } from "@adapttable/ai/json";

const envelope = parseEnvelope(body);
const result = await executeEnvelope(session, envelope);
```

```ts
interface AgentEnvelope {
  schemaVersion: "adapttable.agent.v1";
  tableId: string;
  key: string;
  args: unknown;
  expectedRevision: number;
  idempotencyKey: string;
}
```

Compiling source: [ai-server-agent.ts](../examples/ai-server-agent.ts).

### 3. Optional JSON / OpenAI / MCP helpers

Use these from **your** agent runtime. LangChain or any other framework
may consume the JSON tools. None of them become an AdaptTable dependency.

```ts
const tools = toJsonTools(session);
const openai = toOpenAITools(session, { deferred: true });
const mcp = toMcpTools(session);
```

Compiling source: [ai-mcp-host.ts](../examples/ai-mcp-host.ts).

## One-call response — result stays in the app

A model may return text and structured actions in one response. Execute
the actions, then show success or error in application or table UI.
Sending `ExecuteResult` back to the model is optional.

```ts
import { applyTurnWithoutRoundTrip } from "../examples/ai-one-call";

const { text, results } = await applyTurnWithoutRoundTrip(session, turn);
showInApp(text, results);
```

Compiling source: [ai-one-call.ts](../examples/ai-one-call.ts).

## Optional result-return loop

```ts
import { applyTurnAndReply } from "../examples/ai-result-return";

await applyTurnAndReply(session, turn, (text, results) => {
  sendBackToYourRuntime(text, results);
});
```

Compiling source: [ai-result-return.ts](../examples/ai-result-return.ts).

Do not add a chat-response wrapper to AdaptTable. The turn envelope is
application-owned.

## Catalog is live-table-derived

`catalog()` lists only capabilities enabled by mounted features, column
permissions, source support and host callbacks. A table with filtering
and pagination must not advertise editing, grouping or pivoting.

Two equally valid ways to learn schemas:

1. Compact `catalog → describe → execute` — describe one key when needed.
2. Eager helpers (`toJsonTools`, `toOpenAITools`) that call `describe`
   for every enabled key.

```ts
for (const entry of session.catalog()) {
  const guide = session.describe(entry.key);
  await session.execute(entry.key, args, revision, idempotencyKey);
}
```

Host write-safety chrome (not on the envelope):

- `approval`: `"writes"` | `"destructive"` | `"never"` (default `"writes"`)
- `commit`: `"stage"` | `"immediate"` (default `"stage"`)

Stage hands `edit.cells` to the host's `stageCells` callback, the table's
dirty path. Immediate calls `editCells` and the add, delete and reorder
callbacks directly. `rows.add`, `rows.delete` and `rows.reorder` have no
staging path and return `commit-incompatible` under `"stage"`. Approve, then
Save, then Undo — the table never owns the data.

## JSON, OpenAI, MCP

`toJsonTools` returns `JsonFunctionTool[]`. `executeJsonTool` takes a
`JsonToolCall`. `executeEnvelope` and `parseEnvelope` are re-exported
from `@adapttable/ai/json`.

`toOpenAITools(session, { deferred: true })` returns only `catalog`,
`describe` and `execute`. `strict: true` is the default. Eager tools
replace each `.` in a catalog key with `_` (`view.setPage` →
`view_setPage`) because OpenAI function names cannot contain dots.
`executeOpenAITool` maps those names back, and still accepts the dotted
catalog key. Deferred `execute` requires both `key` and `args`, a JSON-encoded string of
the capability arguments. Strict mode lists every property in
`required`, forbids open maps, and treats originally-optional fields as
nullable.

`toMcpTools` / `toMcpResources` list enabled keys. Each capability is
also a resource at
`adapttable://table/{tableId}/capability/{key}`. `mcpListChanged`
decides when to emit `notifications/tools/list_changed`.

`@adapttable/ai/http` is the optional ready-made transport: post the permitted
context to your endpoint and execute the calls that come back through the same
session. Setup, protocol and the runnable example live on
[connect a backend](./ai-http.md).

## Protocol adapters

Each of these speaks a protocol somebody else defined, and each ends in the
same `session.execute` — the same exclusion predicate, the same revision check,
the same approval policy and the same receipts. None adds an SDK dependency:
the event and part types are this package's own, and the one seam a host fills
is "send this, stream that back."

An integration is described as supported here only once its recorded-event
conformance fixture runs against the real adapter code.

### MCP tools, and the table as an MCP App

`toMcpTools` carries annotations derived from what each capability declares:
`readOnlyHint` for view and read keys, `destructiveHint` true only for a
destructive one and explicitly false elsewhere, `idempotentHint` where running
it twice lands where running it once did, and `openWorldHint` always false —
a capability acts on this table and nothing behind it. `toMcpToolList` and
`toMcpResourceList` return the same lists as cacheable responses, stamped with
the contract they describe. `mcpToolResult` maps one `execute` outcome into a
`tools/call` result and keeps the provenance envelope on a row window.

`@adapttable/ai/mcp-apps` publishes the table as a view an MCP host embeds:
`mcpAppResource` for the `ui://adapttable/table/{tableId}` descriptor,
`mcpAppCsp` for a policy built only from the domains you declared, and
`createMcpAppBridge` for the view's side — `ui/initialize`, the tool-input and
tool-result notifications, and `tools/call` for a reader's actions. The bridge
requires the host's exact origin: a handshake posted to `"*"` would announce
the table's contract to whatever else is listening. `approveThroughHost` and
`askThroughHost` use the host's elicitation when it advertises one and return
nothing when it does not, leaving the table's own approval in charge.

```ts
import type { ApprovalSubject } from "@adapttable/ai";
import { toMcpTools } from "@adapttable/ai/mcp";
import {
  approveThroughHost,
  createMcpAppBridge,
  mcpAppResource,
  withMcpAppMeta,
} from "@adapttable/ai/mcp-apps";

// Server: list the view, and point each tool at it.
const resource = mcpAppResource(session, {
  src: "https://view.example/table/",
  security: { connectDomains: ["https://api.example"] },
});
const tools = withMcpAppMeta(toMcpTools(session), session);

// View: talk to the embedding host, and only to it.
const bridge = createMcpAppBridge({ hostOrigin: "https://host.example" });
await bridge.initialize();
// Resolves undefined when the host advertises no elicitation.
const askHost = (subject: ApprovalSubject) =>
  approveThroughHost(bridge, subject);
```

### WebMCP — an agent in the page

```ts
import { registerWebMcpTools } from "@adapttable/ai/webmcp";

const registration = registerWebMcpTools(session, {
  exposedTo: ["view.setPage", "view.setSort", "rows.read"],
  onWarning: (warning) => console.warn(warning.message),
});
// A contract change is a different set of tools: dispose and register again.
onTeardown(() => registration.dispose());
```

Nothing happens at import: `document.modelContext` is read when you call it, so
the module loads on a server and in a browser without the API and registers
nothing in either. In React, `tableAgent({ webmcp: true })` does the same and
re-registers on a contract change for you.

An agent in the page reads the table through one call and changes it through
another, and the reader can move the table in between. Every tool therefore
takes an optional `expectedRevision` — the revision the call was planned
against, from the `revision` an earlier result carried:

```ts
// The agent read the table at revision 5 and acts on what it read.
await tool.execute({ page: 3, expectedRevision: 5 });
// Refused if the reader has since moved it, and the refusal says where it is:
// { error: { code: "revision-mismatch", ... }, revision: 7 }
```

Omit it and the call acts on the table as it is, which is what an agent that
never names a revision has always done. This is the one transport where the
revision travels on the call: HTTP and the AI SDK send the view with each
request, and AG-UI publishes it as state, so those bind it for you.

### AG-UI — the table as a run's frontend tools

```ts
import { aguiTransport } from "@adapttable/ai/ag-ui";

const transport = aguiTransport({
  connection: { run: (input, signal) => yourEndpoint(input, signal) },
  onApprove, // the same seam `session.execute` uses
});
```

The enabled contract becomes the run's tool definitions, the sanitized view
its `STATE_SNAPSHOT` and then RFC 6902 `STATE_DELTA`s, and the conversation its
`MESSAGES_SNAPSHOT`. A `RUN_FINISHED` interrupt with `reason: "confirmation"`
becomes an `ApprovalSubject` and resumes with `resume[{ interruptId, status,
payload }]`; `input_required` becomes a question for the reader. A tool call
this table does not own is left to whoever registered it. `AgUiOptions` also
takes `askUser`, `threadId`, `maxRuns`, `presentation`, `context`,
`contextInputs` and `onEvent`; `aguiTools` returns the tool definitions alone.

### AI SDK — client tools on your own route

```ts
// Your route, your provider, unchanged apart from the spread.
import { aiSdkTools } from "@adapttable/ai/ai-sdk";

streamText({
  model,
  system,
  tools: { ...yourTools, ...aiSdkTools(session) },
});
```

Every entry omits `execute`, which is how the AI SDK decides the client runs
it. In the browser, `aiSdkTransport` answers those calls and returns each
result as the tool output on the next request — the shape `addToolOutput`
sends. `tool-approval-request` becomes an `ApprovalSubject` and answers as an
approval response; `output-denied` carries the reject reason. A stream that
declares a version this adapter does not speak is refused with
`unknown-stream-version` rather than parsed as though it were one it does.

```ts
import { aiSdkTransport } from "@adapttable/ai/ai-sdk";

const transport = aiSdkTransport({
  // POST the request to your route and yield its UI message stream parts.
  connection: { run: (request, signal) => yourRoute(request, signal) },
});
```

`AiSdkOptions` also takes `onApprove`, `presentation`, `context`,
`contextInputs`, `maxRequests` and `onPart`.

## Examples

- [ai-custom-bridge.ts](../examples/ai-custom-bridge.ts) — any agent format → `execute`
- [ai-one-call.ts](../examples/ai-one-call.ts) — text + actions, no model round trip
- [ai-result-return.ts](../examples/ai-result-return.ts) — optional result return
- [ai-server-agent.ts](../examples/ai-server-agent.ts) — Node worker + HTTP envelope
- [ai-mcp-host.ts](../examples/ai-mcp-host.ts) — tools, resources, list-changed
- [ai-browser-agent.tsx](../examples/ai-browser-agent.tsx) — `tableAgent` + JSON tools
- [ai-http-backend.ts](../examples/ai-http-backend.ts) — runnable OpenAI/Anthropic/Gemini/DeepSeek server
- [ai-assistant-custom-ui.tsx](../examples/ai-assistant-custom-ui.tsx) — a complete conversation panel with none of the shipped widget in it
- [ai-assistant-store.ts](../examples/ai-assistant-store.ts) — the conversation with no React, no DOM and no HTTP
- [ai-agui-host.ts](../examples/ai-agui-host.ts) — an AG-UI run driven from recorded events, including a confirmation interrupt
- [ai-sdk-route.ts](../examples/ai-sdk-route.ts) — the route half: client tools declared beside a route tool
- [ai-http-backend.py](../examples/ai-http-backend.py) — the same wire in Python, standard library only, run through `uv`

Intention fixtures (no live model) live in
`packages/shared/ai/src/__fixtures__/intentions.json`.

---

# React table AI backend — HTTP protocol and local example

This is the setup page for a real model behind a live table. The [interactive
playground](https://adapttable.orwamahmoud.com/react/demo/mantine/ai/)
defaults to **Simulated demo**: local scripted buttons, no credentials, no
network model call. Switch to **Try it for real**, paste an endpoint, and the same
`tableAgent` session sends the permitted context and executes the calls that come back.

`@adapttable/ai` stays provider-neutral. It does not ship a model SDK, an API
key field, or a hosted AdaptTable service. Provider selection lives in your
backend, or in the example server below.

## What the table does automatically

On each request the HTTP bridge sends:

- the [permitted context](./ai.md#what-the-agent-is-told) — the contract
  (capabilities, column permissions, filters, limits, write/approval/commit
  policy) and the view (page, size, search, sort, grouping, filter state);
  never the dataset
- the user message, and the conversation so far

How much of each capability's guide travels is the **profile**. `compact`
names every capability and explains the ones a turn is likely to need;
anything else is asked for on demand, in one batched round rather than a
request per key, and cached per connection and contract version. `full` sends
every guide up front. Neither changes what the table permits — only how much
explaining arrives before it is asked for. `full` is the default; a client sets
`compact` with `context: { profile: "compact" }` on `createAgentHttpClient` or
`assistantHttpTransport`.

A backend that asks for a guide or a row window puts that in `toolCalls`
alongside anything it wants run; the bridge answers through `session.describe`
and `rows.read`, so an unreadable column stays redacted and `readMax` still
applies, then continues the same turn.

Returned calls run through `session.execute`. Revision checks, permissions,
approval chrome, commit policy and idempotency stay on the session, and the
replay identity is the bridge's own — a backend cannot mint a second write by
repeating one. The bridge never retries a mutation.

Text plus calls is a complete turn. A second model call is not required to say
“done.” Sending execute receipts back is optional (`continueWithResults` on the
response, `returnResults` on the client).

## Path 1 — run our example

Prerequisites: Node 22.12 or newer (the example runs TypeScript directly with
`--experimental-strip-types`) and `pnpm install` at the repository root.

From this repository:

```bash
cp -n examples/ai-http-backend.env.example examples/.env.ai-http
```

`-n` keeps an env file you already filled in — the copy is skipped rather
than overwritten.

Edit `examples/.env.ai-http`. Set `AGENT_PROVIDER` to `openai`,
`anthropic`, `gemini` or `deepseek`, and the matching API key. Never commit
the filled file.

```bash
pnpm --filter @adapttable/ai build
pnpm --filter @adapttable/examples ai-http
```

The server refuses to start on a configuration it cannot use: an
`AGENT_PORT` that is not a whole number between 1 and 65535, an
`AGENT_MAX_BODY` that is not a positive whole number of bytes, an empty
`AGENT_HOST` or `AGENT_MODEL`, an
unknown `AGENT_PROVIDER`, or a provider whose API key is missing. Each of
those exits with the name of the variable to fix.

The process binds `127.0.0.1` on port `8787` by default. A non-loopback
`AGENT_HOST` requires `AGENT_HTTP_TOKEN`.

**Local showcase (reliable).** The hosted site cannot be assumed to reach
`localhost` — browsers treat that as a cross-origin public-site request, and
many block it. Run the showcase on the same machine:

```bash
pnpm --filter @adapttable/showcase dev
```

Open `/mantine/ai/` (or any adapter AI page). Choose **Try it for real**. The
URL defaults to `http://127.0.0.1:8787`. If the example set
`AGENT_HTTP_TOKEN`, paste that same value into **Endpoint token** (Bearer
for the HTTP endpoint — not a provider API key). Click **Connect**. A valid
hello body is required; a random 200 is a failure. Then type a message and
**Send**. Writes still go through that kit’s approval and staged-save chrome.

**Hosted showcase.** Deploy the example with HTTPS, set
`AGENT_ALLOWED_ORIGINS` to `https://adapttable.orwamahmoud.com`, set
`AGENT_HTTP_TOKEN` and a non-loopback `AGENT_HOST`, then paste the public
URL and the same endpoint token into the connect dialog. Do not point the
hosted page at `localhost`.

### Environment

See [ai-http-backend.env.example](../examples/ai-http-backend.env.example).

Values are read in this order, and the first one that sets a key wins:

1. the real process environment — no file overrides what the shell, the
   container or the CI runner already set;
2. the file named by `AGENT_ENV_FILE`;
3. `.env.ai-http` beside the example;
4. `.env` in the working directory.

Files are parsed by Node itself (`process.loadEnvFile`), not a bespoke
reader.

| Variable                                                                       | Role                                                               |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `AGENT_PROVIDER`                                                               | `openai` (default), `anthropic`, `gemini`, or `deepseek`           |
| `AGENT_MODEL`                                                                  | Optional override. Each provider has a default.                    |
| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `DEEPSEEK_API_KEY` | Server-side only                                                   |
| `AGENT_HTTP_TOKEN`                                                             | Required when `AGENT_HOST` is not loopback. Bearer on the endpoint |
| `AGENT_HOST`                                                                   | Bind address. Default `127.0.0.1`                                  |
| `AGENT_ENV_FILE`                                                               | Optional extra env file. Existing process.env keys win             |
| `AGENT_ALLOWED_ORIGINS`                                                        | Comma-separated origins. Defaults to local showcase ports          |
| `AGENT_PORT`                                                                   | Default `8787`                                                     |
| `AGENT_MAX_BODY`                                                               | Default `65536` bytes                                              |

`AGENT_ALLOWED_ORIGINS` is a CORS list. CORS is a browser convenience, not
authentication: it tells a browser which pages may read the response, and
nothing at all to curl, a script, or any non-browser client. `AGENT_HTTP_TOKEN`
is what actually authenticates a caller — set it on every bind you do not
fully control.

The example does not log credentials or table contents. It is not an open
proxy: it only calls the configured provider.

### Add another provider

Implement an `ExampleComplete` —
`({ system, user, history, signal }, onDelta?) => Promise<string>`, resolving
with the JSON reply and calling `onDelta` with each fragment when streaming —
then register it in `completeForProvider`. Arbitrary provider names do not
work without that adapter.

## Path 2 — connect an existing backend

Implement the protocol below, or adapt your agent runtime so it emits the
same JSON. The showcase and `createAgentHttpClient` need no custom glue
when the body matches.

Junior backends import `agentSystemPrompt` and send that string as the
model system prompt. Senior backends skip it and keep their own prompt
or tools. The example calls the export; it does not keep a private copy
of the skill text.

```ts
import { agentSystemPrompt, createAgentHttpClient } from "@adapttable/ai/http";

const client = createAgentHttpClient({
  endpoint: "https://your.example/agent",
  headers: () => ({ authorization: `Bearer ${token}` }),
  timeoutMs: 20_000,
});

await client.connect(session);
const { text, results } = await client.send(session, "Filter the Core team");
```

You can still use your own transport, tool definitions and response
transform — this client is optional. See [agent integrations](./ai-integrations.md).

## Protocol

`POST` JSON. Schema family: `adapttable.agent.v1`. Import
`parseAgentHttpRequest` / `parseAgentHttpResponse` from `@adapttable/ai/http`
rather than duplicating the shape; both refuse an unknown `schemaVersion`.

### Request

| Field              | When                                              | What                                                                                       |
| ------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `schemaVersion`    | always                                            | `"adapttable.agent.v1"`                                                                    |
| `kind`             | always                                            | `"hello"`, `"schema"` or `"turn"`                                                          |
| `tableId`          | always                                            | The table's identity                                                                       |
| `context`          | hello, schema, and every turn when pinning is off | `{ contract, selection }` — what this table permits, and what was selected from it         |
| `contractVersion`  | with `context`                                    | Names everything the contract says                                                         |
| `selectionVersion` | with `context`                                    | Names what was selected from it                                                            |
| `sessionId`        | after a hello                                     | The pin the backend handed back                                                            |
| `viewRevision`     | a pinned turn                                     | The revision the contract was read at                                                      |
| `view`             | every turn                                        | Where the table is **now** — page, size, search, sort, grouping and permitted filter state |
| `message`          | a turn                                            | What the reader said                                                                       |
| `conversation`     | a turn                                            | Earlier exchanges, oldest first                                                            |
| `toolResults`      | a continuation                                    | Results for calls the client just ran                                                      |
| `audio`            | a voice turn                                      | One clip, travelling once                                                                  |
| `manifest`         | hello, schema, and every unpinned turn            | Compact capability snapshot; required on hello and schema                                  |
| `catalog`          | hello, schema, and every unpinned turn            | Enabled keys and one-line summaries; required on hello and schema                          |
| `turnId`           | a turn                                            | Stable identity of this send across its phases                                             |
| `phaseId`          | a turn                                            | Monotonic position of this phase within the turn                                           |
| `pendingCalls`     | a continuation                                    | The calls this phase has proposed so far                                                   |

The contract and the view move on different clocks, which is why they are
separate fields: pinning the contract does not pin the view, and a backend
answering a turn is always answering against the view in that request.

### Response

```ts
{
  schemaVersion: "adapttable.agent.v1",
  ok?: boolean,               // hello / health only
  sessionId?: string,
  text?: string,
  toolCalls?: { id, name, args?, expectedRevision? }[],
  askUser?: { id, question, options?, allowFreeText },
  transcript?: string,        // what the backend heard, on a voice turn
  pin?: { status, contractVersion?, ttlMs? },
  continueWithResults?: boolean
}
```

**`toolCalls`** is one list, whether a call runs a capability or asks for
something: `name` is a capability key, or `describe` / `read`. A call's `id`
is a correlation handle unique within the reply — it is **not** the replay
identity. The client issues that itself, from the table, the turn, the phase
and the call's position, so a backend cannot mint a second write by repeating
a string.

**`expectedRevision`** is optional. Omitted means the view this request
described, which is the ordinary case; a backend that names one is answering
for a revision it observed itself, and a stale call is refused with
`revision-mismatch` rather than rebased onto the live table.

**`askUser`** puts a structured question to the reader instead of asking in
prose. The turn stops at that call and resumes when they answer; the answer
returns as that call's `toolResults` entry. A client with nowhere to draw one
reports `unresolved` with code `no-reader-channel` and still says what already
ran, and a reader who declines reports code `question-unanswered` — different
facts.

**`pin`** is the backend's answer about the contract it was sent:
`acknowledged` (and only that) pins something; `expired` and `unknown` say a
pin it once held is gone, which is recoverable by resending the contract;
`unsupported` says this backend does not pin at all. A backend that echoes a
different `contractVersion`, or none, is not pinned and keeps being sent the
contract. None of these is ever the answer to a call whose outcome is unknown:
a write is never retried.

### Discovery

A turn that needs a guide asks for it in the same `toolCalls` list, and the
client answers in one batched round rather than one request per key. Guides
are cached per connection and contract version, so a second turn that needs
the same guide does not ask again. Set `context: { profile: "compact" }` on the
client and let discovery do this; keep the default `full` when you would rather
pay the bytes up front.

### Streaming

Set `stream: true` on the client and it asks for `text/event-stream`;
`onStreamText(text)` receives the text so far. A backend that answers JSON is
used as-is. The same reply arrives as events:

- `text-delta` — a piece of the answer, as it is produced
- `transcript` — what the backend heard, on a voice turn
- `ask-user` — the structured question
- `tool-calls` — the calls, whole, exactly once
- `done` — the calls are final
- `error` — the turn failed; `{ code, message }`

The calls travel whole and only before `done`: a client that loses the
connection first has run nothing. A stream that ends without `done` is
reported as `stream-incomplete` rather than treated as a short answer.

### Voice

`@adapttable/ai/voice` has two modes. In **browser** mode the browser's speech
recognizer turns speech into the composer's draft — never a send, so a
misheard word is a typo the reader corrects. In **backend** mode one clip is
recorded and released from the microphone on stop, and `onClip` hands it to
the host. The wire contract carries it: a turn may send one `audio` clip
(`mimeType`, `base64`, `durationMs`) instead of `message`, and the reply may
name what the backend heard in `transcript`. The built-in client sends a clip
on the turn's first round only: `assistantHttpTransport` takes it from the
assistant's `sendClip`, and `createAgentHttpClient().send(session, "", { audio,
onTranscript })` takes it directly. Once a reply names the `transcript`, every
later round of the turn sends those words as `message`; a turn that needs
another round and never got a transcript stops with an error. The assistant
shows the transcript as the reader's own message. See
[voice input](./ai-voice.md#backend-mode).

### Any language

The wire is a wire. [`examples/ai-http-backend.py`](https://github.com/orwa-mahmoud/adapttable/blob/main/examples/ai-http-backend.py)
is the same contract in Python with no model and no framework — standard
library only, run through `uv`:

```bash
uv run --python 3.12 examples/ai-http-backend.py
```

It listens on `http://127.0.0.1:8788`, reads the contract out of the request,
decides one call, and answers in the shape above. Swap its `decide` for a real model call and nothing else changes.

The machine-readable schema and the general rules text are generated from
`AGENT_HTTP_LIMITS` and `agentInstructions` into `schemas/agent-http.v1.json`
and `docs/agent-rules.txt` — build the package and run
`node scripts/build-agent-schema.mjs`.

## Live provider test

Automated checks use mocked providers and never spend money. To try a real
model: fill `examples/.env.ai-http`, start the example with
`pnpm --filter @adapttable/examples ai-http`, run the local
showcase, connect, and send a message.

---

# React table voice input — speak to the table assistant

`@adapttable/ai/voice` lets a reader dictate to the table assistant instead of
typing. `createSpeechInput` is a framework-free dictation controller,
`useSpeechInput` from `@adapttable/ai-react` binds it to a React composer, and
every kit's `TableAssistant` draws a mic from the handle the hook returns.

Dictation produces a draft, never a turn. Heard text lands in the composer,
the reader reads it, corrects a misheard word, and presses Send. A browser
that cannot listen gets no mic button, and typing works the same way.

This page covers voice only. The conversation, transports and approval are in
[adaptive capabilities](./agent-capabilities.md) and
[`@adapttable/ai`](./ai.md); the wire a backend speaks is in
[the HTTP backend guide](./ai-http.md).

## Add a mic to the assistant panel

Pass `voice` to `useSpeechInput`, route heard text into the assistant's draft
with `setDraft`, and hand the result to `TableAssistant` as `speech`:

```tsx
import { useState } from "react";
import type { AgentSession } from "@adapttable/ai";
import {
  tableAgent,
  useSpeechInput,
  useTableAssistant,
} from "@adapttable/ai-react";
import { assistantHttpTransport } from "@adapttable/ai/http";
import { DataTable } from "@adapttable/mantine";
import { TableAssistant } from "@adapttable/mantine/assistant";

interface Order {
  id: string;
  customer: string;
  status: string;
  total: number;
}

const transport = assistantHttpTransport({ endpoint: "/api/agent" });

export function Orders({ rows }: { rows: Order[] }) {
  const [session, setSession] = useState<AgentSession | null>(null);
  const assistant = useTableAssistant({
    session: session ?? undefined,
    transport,
    transportKey: "orders",
  });
  const speech = useSpeechInput({
    voice: { languages: ["en-US", "ar-SA"] },
    setDraft: assistant.setDraft,
  });

  return (
    <>
      <DataTable
        data={rows}
        columns={[{ key: "customer" }, { key: "status" }, { key: "total" }]}
        rowKey={(row) => row.id}
        features={[
          tableAgent({ tableId: "orders", bridge: { attach: setSession } }),
        ]}
      />
      <TableAssistant
        assistant={assistant}
        speech={speech}
        open={assistant.open}
        onOpenChange={assistant.setOpen}
      />
    </>
  );
}
```

The same `speech` prop exists on the panel from `@adapttable/mui/assistant`,
`@adapttable/chakra/assistant`, `@adapttable/antd/assistant`,
`@adapttable/radix/assistant`, `@adapttable/base-ui/assistant`,
`@adapttable/shadcn/assistant` and `@adapttable/unstyled/assistant`. It takes a
`SpeechInputHandle`, a structural type declared in `@adapttable/react/adapter`,
so the panel draws a mic without importing `@adapttable/ai`. A host driving
its own recognizer can pass any object of that shape.

## How it works

1. `useSpeechInput` builds one controller with `createSpeechInput` the first
   time it renders with `voice` set, and disposes it on unmount.
2. The panel draws the mic only when the handle's `available` is `true` —
   `voice` is set and this browser supports the chosen mode.
3. Pressing the mic calls `start()`; pressing it again calls `stop()`.
4. **Browser mode** runs the Web Speech API recognizer with `continuous` and
   `interimResults` on, in the language chosen for this utterance. Each result
   calls `onDraft` with the text heard so far, and the hook writes it through
   `setDraft`, replacing the composer's draft.
5. **Backend mode** records one clip with `MediaRecorder`. On `stop()` the
   microphone tracks are stopped, the status moves to `processing`, and
   `onClip` receives the recording once, base64-encoded.
6. Sending is the reader's action. The controller never calls `send`; the
   draft becomes a turn only through the composer's Enter or Send.

### How a transcript becomes a turn

In browser mode the transcript is the draft. The reader edits it in the
composer like typed text, and Send runs `assistant.send()`, which sends the
draft as an ordinary text turn — the same turn, the same approval and the same
receipts as a typed request. A misheard sentence is therefore a typo to fix,
never an action the table already ran.

In backend mode the clip goes wherever `onClip` sends it. Pass
`assistant.sendClip` and the clip is the turn: the backend transcribes it, and
its transcript replaces a "Voice message" placeholder as the reader's message.
Or transcribe it yourself and write the text into the draft, which keeps the
same review step as browser mode (see [Backend mode](#backend-mode)).

## `useSpeechInput(options)`

From `@adapttable/ai-react`. Returns a `SpeechInputHandle`.

| Option     | Type                         | Default                      | What                                                            |
| ---------- | ---------------------------- | ---------------------------- | --------------------------------------------------------------- |
| `setDraft` | `(text: string) => void`     | required                     | Where heard text goes. Pass the assistant's `setDraft`.         |
| `voice`    | `VoiceOptions`               | none — no controller, no mic | `{ mode?, languages? }`. Setting it turns dictation on.         |
| `locale`   | `string`                     | `"en-US"` when absent        | The language offered when `voice.languages` is empty or absent. |
| `onClip`   | `(clip: SpeechClip) => void` | none                         | Receives the recording in backend mode.                         |

`VoiceOptions`, from `@adapttable/ai/voice`:

| Field       | Type                     | Default               | What                                                                    |
| ----------- | ------------------------ | --------------------- | ----------------------------------------------------------------------- |
| `mode`      | `"browser" \| "backend"` | `"browser"`           | Recognize in the browser, or record a clip for a backend                |
| `languages` | `readonly string[]`      | `[locale ?? "en-US"]` | BCP-47 tags offered. One shows the mic alone; more adds a language chip |

The handle the hook returns:

| Field         | Type                         | What                                                                         |
| ------------- | ---------------------------- | ---------------------------------------------------------------------------- |
| `available`   | `boolean`                    | `false` when `voice` is absent or the browser cannot do the mode             |
| `state`       | `SpeechInputState`           | `status`, `language`, `interim`, and `error` when dictation failed           |
| `languages`   | `readonly string[]`          | The languages offered                                                        |
| `start`       | `() => void`                 | Begin listening                                                              |
| `stop`        | `() => void`                 | Stop and deliver what was captured                                           |
| `setLanguage` | `(language: string) => void` | Choose the language for the next utterance and remember it in `localStorage` |

The controller is built once per mount. Changing `voice` after it exists does
not rebuild it; remount the component to apply a different mode or language
list. `setDraft` and `onClip` are read live, so fresh callbacks on every
render are fine.

## `createSpeechInput(options)`

The controller without React, from `@adapttable/ai/voice`. The `@adapttable/ai`
root entry re-exports it together with `readRememberedLanguage`,
`rememberLanguage` and the voice types.

| Option            | Type                         | Default                                        | What                                                          |
| ----------------- | ---------------------------- | ---------------------------------------------- | ------------------------------------------------------------- |
| `mode`            | `"browser" \| "backend"`     | `"browser"`                                    | Which way the voice reaches the table                         |
| `languages`       | `readonly string[]`          | `[navigator.language]`, or `["en-US"]` without | Languages offered; the first is the default                   |
| `initialLanguage` | `string`                     | `languages[0]`                                 | The language to start in, such as one remembered from a visit |
| `onDraft`         | `(text: string) => void`     | none                                           | Called with the text heard so far, in browser mode            |
| `onClip`          | `(clip: SpeechClip) => void` | none                                           | Called once with the recording, in backend mode               |

It returns a `SpeechInput`:

| Member        | What                                                                                                |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `getState()`  | The current `SpeechState`. The same object is returned until something changes                      |
| `subscribe()` | Listen for changes; returns the unsubscribe                                                         |
| `start()`     | Begin listening. A no-op while already listening or after `dispose()`; clears `interim`             |
| `stop()`      | Stop, and deliver whatever was captured                                                             |
| `setLanguage` | Choose the language for the next utterance. An utterance in progress keeps the language it began in |
| `supported()` | Whether this browser can do this mode at all                                                        |
| `dispose()`   | Idempotent. Aborts the recognizer, releases the microphone, and notifies no listener afterwards     |

`SpeechState.status` is one of:

| Status        | Meaning                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------- |
| `idle`        | Not listening                                                                             |
| `listening`   | The recognizer or the recorder is running                                                 |
| `processing`  | Backend mode: recording stopped, the clip is being read                                   |
| `denied`      | Microphone access was refused; `error` is `"microphone access was refused"`               |
| `unsupported` | `start()` was called in a browser that cannot do this mode                                |
| `error`       | The recognizer reported an error (`error` holds its code) or the recording was unreadable |

The module touches no browser API at import time. `SpeechRecognition` and
`MediaRecorder` are looked up when `start()` or `supported()` runs, so it loads
on a server, in a test runner, and in a browser that has neither.

```ts
import {
  createSpeechInput,
  readRememberedLanguage,
  rememberLanguage,
} from "@adapttable/ai/voice";

const box = document.querySelector<HTMLTextAreaElement>("#ask");
const mic = document.querySelector<HTMLButtonElement>("#mic");

if (box && mic) {
  const remembered = readRememberedLanguage();
  const dictation = createSpeechInput({
    languages: ["en-US", "fr-FR"],
    ...(remembered ? { initialLanguage: remembered } : {}),
    onDraft: (text) => {
      box.value = text;
    },
  });

  // No mic in a browser that cannot listen.
  mic.hidden = !dictation.supported();

  dictation.subscribe(() => {
    const { status } = dictation.getState();
    mic.setAttribute("aria-pressed", String(status === "listening"));
  });

  mic.addEventListener("click", () => {
    if (dictation.getState().status === "listening") dictation.stop();
    else dictation.start();
  });

  document
    .querySelector<HTMLSelectElement>("#language")
    ?.addEventListener("change", (event) => {
      const language = (event.currentTarget as HTMLSelectElement).value;
      dictation.setLanguage(language);
      rememberLanguage(language);
    });
}
```

## Language memory

`rememberLanguage(language, key?)` stores a language choice in `localStorage`;
`readRememberedLanguage(key?)` reads it back, or returns `undefined`. Both
default to the key `"adapttable.voice.language"`. A browser that refuses
storage does not break dictation: the read returns `undefined` and the write
keeps nothing.

`useSpeechInput` uses both: it starts in the remembered language when one is
stored, and its `setLanguage` remembers every choice. The controller's own
`setLanguage` does not write storage; a host calling it directly calls
`rememberLanguage` itself, as in the example above.

## Backend mode

Backend mode records the reader and hands the clip to the host. It covers
languages the browser's recognizer does not, and hosts that transcribe with
their own provider.

### The clip as the turn

With the HTTP transport, the backend that answers the turn also hears it:

```tsx
const speech = useSpeechInput({
  voice: { mode: "backend", languages: ["ar-SA"] },
  setDraft: assistant.setDraft,
  onClip: assistant.sendClip,
});
```

`sendClip` sends the recording as the turn's first round. The reader's message
shows `labels.assistantVoiceMessage` ("Voice message") until the reply names
the `transcript`, then shows the transcript. A host writing its own
`AssistantTransport` receives the clip as `audio` on `send` — an
`AssistantAudio`, the same `{ mimeType, base64, durationMs }` as a
`SpeechClip` — reports the words
through `onTranscript`, and may return them as `transcript` on the reply.

### Transcribing it yourself

```tsx
import type { SpeechClip } from "@adapttable/ai/voice";
import { type TableAssistantState, useSpeechInput } from "@adapttable/ai-react";

async function transcribe(clip: SpeechClip): Promise<string> {
  const response = await fetch("/api/transcribe", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(clip),
  });
  if (!response.ok) {
    throw new Error(`transcription failed with ${String(response.status)}`);
  }
  const { text } = (await response.json()) as { text: string };
  return text;
}

function useBackendDictation(assistant: TableAssistantState) {
  return useSpeechInput({
    voice: { mode: "backend", languages: ["ar-SA"] },
    setDraft: assistant.setDraft,
    // The transcript lands in the draft, so the reader still reviews it.
    onClip: (clip) => {
      transcribe(clip).then(assistant.setDraft, (error: unknown) => {
        console.error(error);
      });
    },
  });
}
```

A `SpeechClip` is `{ mimeType, base64, durationMs }`. `mimeType` is the
recorder's media type without codec parameters — `audio/webm`, not
`audio/webm;codecs=opus`. The clip does not carry the language; send
`speech.state.language` alongside it when the transcriber needs one. The
status returns to `idle` as soon as `onClip` has been called, so a host that
wants to show transcription progress tracks it itself.

The [HTTP protocol](./ai-http.md#voice) also defines a voice turn: an `audio`
field on the request, the same shape as `SpeechClip`, and a `transcript` on the
reply. `parseAgentHttpRequest` from `@adapttable/ai/http` refuses a clip that
is not `audio/webm`, `audio/ogg`, `audio/mp4`, `audio/mpeg` or `audio/wav`,
that decodes to more than 4,000,000 bytes, or that runs longer than 120,000 ms;
`AGENT_HTTP_LIMITS` publishes the same ceilings as `maxAudioBytes`,
`maxAudioMs` and `audioTypes` for a backend to enforce.
[`examples/ai-http-backend.ts`](https://github.com/orwa-mahmoud/adapttable/blob/main/examples/ai-http-backend.ts)
takes a `transcribe(audio, signal)` function as the last argument of
`handleExampleAgentTurn`, answers the words it returns and sends them back as
`transcript`.

## Notes

### Browser support and the fallback

Browser mode needs `SpeechRecognition` or the prefixed
`webkitSpeechRecognition`. Backend mode needs `MediaRecorder` and
`navigator.mediaDevices.getUserMedia`. `supported()` checks exactly those, per
mode.

When the check fails, `useSpeechInput` returns `available: false` and the panel
draws no mic and no language chip — an absent control rather than a disabled
one. The composer, Enter and Send are unchanged. On the server the hook's
snapshot is `unsupported`, so server-rendered markup has no mic either.

A refused microphone permission sets the status to `denied`. The panel keeps
the mic and does not print the error; a host that wants to explain the refusal
reads `speech.state.status` and `speech.state.error`.

### Privacy

The voice module makes no network request of its own.

- **Browser mode:** audio goes to the browser's speech recognizer, and only the
  recognized text comes back into the draft. Whether that recognizer runs on
  the device or on the browser vendor's service is decided by the browser, not
  by AdaptTable; check your target browsers if that matters to you. Nothing
  reaches your backend until the reader presses Send, and then only the text.
- **Backend mode:** the clip is held in memory and handed to `onClip`. Where it
  goes next is the host's code. The microphone is released when recording
  stops and when the controller is disposed.
- **Language memory:** the chosen tag is stored in the browser's
  `localStorage` under `adapttable.voice.language` and is not sent anywhere.

### Languages and RTL

Languages are BCP-47 tags such as `"en-US"`, `"ar-SA"` or `"fa-IR"`. With more
than one, the panel shows a language chip beside the mic, labelled with the
tags as given. The chip is disabled while listening, and a change applies to
the next utterance: switching a recognizer's language mid-sentence would lose
what it has heard.

A right-to-left table passes `dir="rtl"` to `TableAssistant` so the portalled
narrow-viewport sheet lays out in the table's direction; see
[i18n and RTL](./i18n-rtl.md).

### Accessibility and labels

The mic is an icon button named **Dictate**, and **Stop dictation** while
listening. The chip is named **Dictation language**. A live region announces
**Listening** once when listening starts and does not read each interim
result aloud. The mic is disabled whenever the assistant cannot take a message.

These strings are the `TableLabels` keys `assistantVoiceStart`,
`assistantVoiceStop`, `assistantVoiceListening` and `assistantVoiceLanguage`,
translated by the `@adapttable/i18n` locales and overridable through the
panel's `labels` prop.

## Related

- [Adaptive capabilities](./agent-capabilities.md) — the headless assistant and
  the optional widget
- [`@adapttable/ai`](./ai.md) — sessions, approval, and
  [undo per turn and per action](./ai.md#approval-undo-and-what-a-reader-agreed-to)
- [Connect a backend](./ai-http.md) — the HTTP protocol, including voice turns
- [Agent integrations](./ai-integrations.md) — OpenAI, MCP and JSON tools over
  the same session

---

# Customize AdaptTable — slots, classNames, headless prop-getters

▶ **See it working:** [the unstyled adapter in the live demo](https://adapttable.orwamahmoud.com/react/demo/?kit=tailwind) — same engine, your own classes.

A spectrum, all opt-in: restyle parts with `classNames`, replace parts with
`slots`, tune the chrome with props, or theme through your kit's provider.
Per-row class, colour and height come from
`rowAppearance({ rowClassName, rowStyle, rowHeight })` in
`@adapttable/<kit>/row-appearance` — see
[row styling and heights](./row-styling.md).

## `classNames` — per-part styling

Restyle without replacing. Every themed kit (Mantine, MUI, Chakra, Ant
Design, Radix Themes, Base UI) exposes five wrapper hooks (`root`,
`toolbar`, `table`, `card`, `footer`); the **unstyled** adapter exposes a
hook for every rendered node:

```tsx
import { DataTable } from "@adapttable/unstyled";

<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  classNames={{
    table: "w-full text-sm",
    row: "border-b hover:bg-zinc-50 data-[selected]:bg-blue-50",
    cell: "px-3 py-2",
    filtersPopover: "rounded-lg border bg-white shadow-xl",
    filtersDone: "rounded-md bg-zinc-900 text-white px-3 py-2",
  }}
/>;
```

Every unstyled node also carries a stable `data-adapttable-part` attribute —
the kebab-case of the `classNames` key (`searchField` →
`data-adapttable-part="search-field"`) — plus `data-*` state attributes, so
plain CSS, Tailwind, and shadcn tokens all work. The main parts are below;
`DataTableClassNames` on the unstyled adapter names every key (see
[adapter extras](./api.md#adapter-extras)).

> **Using shadcn/ui?** `@adapttable/shadcn` is this same unstyled adapter with
> the shadcn class preset already applied — import `DataTable` from
> `@adapttable/shadcn` and pass `classNames` to override only the parts you
> name.

### Toolbar & search

| Part          | Element                                                                 |
| ------------- | ----------------------------------------------------------------------- |
| `root`        | The outer wrapper around the whole table.                               |
| `toolbar`     | The toolbar row (search, filters, columns, views, your `toolbar`).      |
| `searchField` | The search field wrapper (input + leading icon).                        |
| `search`      | The search `<input>`.                                                   |
| `searchIcon`  | The leading magnifying-glass icon.                                      |
| `sortSelect`  | The mobile sort-by `<select>`.                                          |
| `rowsPerPage` | Rows-per-page `<select>` (toolbar in infinite mode, footer when paged). |

### Filters

| Part                                                                                                                    | Element                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `filtersButton`                                                                                                         | The Filters trigger button.                                                                                               |
| `filtersIcon`                                                                                                           | The funnel icon inside the trigger.                                                                                       |
| `filtersCount`                                                                                                          | The active-filter count badge.                                                                                            |
| `exportCsvButton`                                                                                                       | The Export CSV toolbar button (`exportCsv()` feature).                                                                    |
| `exportSpinner`                                                                                                         | The spinner inside that button while a host-handled export runs.                                                          |
| `cellSelected`                                                                                                          | A cell inside the selected range (`cellNavigation`). Styled kits use their own token.                                     |
| `cellSpan`                                                                                                              | A spanned cell (`cellSpan()` feature). `data-cell-span` is on the element (`"2x1"`). Default look is centered + one fill. |
| `filtersAnchor`                                                                                                         | The popover anchor wrapper around the trigger.                                                                            |
| `filtersPopover`                                                                                                        | The anchored popover card (`filtersMode="popover"`).                                                                      |
| `filtersBackdrop`                                                                                                       | The drawer backdrop (`filtersMode="drawer"`).                                                                             |
| `filtersPanel`                                                                                                          | The drawer panel.                                                                                                         |
| `filtersHeader` / `filtersTitle` / `filtersClose`                                                                       | Panel header, its title, and the close button.                                                                            |
| `filtersBody` / `filtersFooter`                                                                                         | The panel content area and its action row.                                                                                |
| `filtersClear` / `filtersDone`                                                                                          | The clear-all and done/apply buttons.                                                                                     |
| `filterField` / `filterLabel`                                                                                           | One auto-built field's wrapper and its caption.                                                                           |
| `filterInput` / `filterSelect` / `filterOperator`                                                                       | Text/date/number inputs, the `select` widget, and a range field's operator `<select>`.                                    |
| `filterCheckboxGroup` / `filterCheckbox`                                                                                | A `multiSelect` checkbox list and one option.                                                                             |
| `filterChecklist` / `filterChecklistSearch` / `filterChecklistActions` / `filterChecklistList` / `filterChecklistCount` | Excel-style checklist and its search, actions, list, and counts.                                                          |
| `filterHeaderRow` / `filterHeaderTrigger` / `filterHeaderCell` / `filterHeaderInput` / `filterHeaderMenu`               | Compact header filter row, funnel overlay trigger, one cell, its input, and the multi-select menu.                        |
| `filterOptionsLoading`                                                                                                  | The placeholder shown while async options load.                                                                           |

### Chips

| Part         | Element                       |
| ------------ | ----------------------------- |
| `chips`      | The active-filter chip strip. |
| `chip`       | One removable chip.           |
| `chipRemove` | A chip's remove button.       |

### Column menu & resize

| Part                                                    | Element                                                     |
| ------------------------------------------------------- | ----------------------------------------------------------- |
| `columnMenu` / `columnMenuButton` / `columnMenuPanel`   | The menu wrapper, trigger, and dropdown panel.              |
| `columnMenuHeader` / `columnMenuTitle`                  | The panel header and its title.                             |
| `columnMenuItem` / `columnMenuGrip` / `columnMenuLabel` | One column row, its drag grip, and its label.               |
| `columnMenuVisibility` / `columnMenuPin`                | The show/hide toggle and the pin control.                   |
| `columnMenuSeparator` / `columnMenuReset`               | The separator above the actions entry and the reset button. |
| `columnMenuAutoSize`                                    | The menu's "size columns to content" action.                |
| `resizeHandle`                                          | A header's drag/keyboard resize handle.                     |

### Saved views

| Part                         | Element                                        |
| ---------------------------- | ---------------------------------------------- |
| `viewsButton` / `viewsPanel` | The menu trigger and dropdown panel.           |
| `viewsItem` / `viewsDelete`  | One view's apply button and its delete button. |
| `viewsInput` / `viewsSave`   | The view-name input and the save button.       |

### Selection & bulk actions

| Part                                                    | Element                                                 |
| ------------------------------------------------------- | ------------------------------------------------------- |
| `bulkBar` / `bulkButton`                                | The selection toolbar and one bulk-action button.       |
| `selectAllBanner` / `selectAllText` / `selectAllButton` | The cross-page banner, its status text, and its action. |
| `selectionCell` / `checkbox`                            | A row's selection cell and the checkbox itself.         |

### Table

| Part                                   | Element                                                                                      |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| `table` / `thead` / `tbody`            | The `<table>` and its sections.                                                              |
| `headerRow` / `headerCell`             | The header `<tr>` and one `<th>`.                                                            |
| `groupRow` / `groupCell`               | The grouped-header row and one spanning cell.                                                |
| `sortButton` / `sortIndex`             | A sortable header's button and its multi-sort badge.                                         |
| `row` / `cell`                         | One body `<tr>` and one `<td>`.                                                              |
| `actionsCell` / `actionButton`         | The trailing actions cell and one action button.                                             |
| `rowActionsTrigger` / `rowActionsMenu` | The 3-dot control and its menu (`rowActionsLayout="menu"`). Menu items reuse `actionButton`. |

### Row expansion

| Part                          | Element                                               |
| ----------------------------- | ----------------------------------------------------- |
| `expandHeader` / `expandCell` | The leading chevron header cell and body cell.        |
| `expandButton`                | The expand/collapse chevron (rows and cards).         |
| `detailRow` / `detailCell`    | The full-width detail `<tr>` and its spanning `<td>`. |
| `cardDetail`                  | The detail section inside an expanded mobile card.    |

### Inline cell editing

Opt-in via `editing()` — see [Inline cell editing](./cell-editing.md). When
editing is dormant these parts are never mounted.

| Part                 | Element                                                             |
| -------------------- | ------------------------------------------------------------------- |
| `edit-cell-activate` | Invisible activate control (double-click / Enter / F2 begins edit). |
| `edit-cell-editor`   | Kit-native input / select while the cell is active.                 |

### Row grouping

Opt in with `groupingPanel()` from the kit's `/grouping-panel` subpath — see
[Row grouping](./row-grouping.md). The panel owns the grouped headers as well
as the configuration strip; when it is dormant these parts are never mounted.

| Part                             | Element                                                                         |
| -------------------------------- | ------------------------------------------------------------------------------- |
| `grouping-panel`                 | The dedicated grouping strip above the table.                                   |
| `grouping-drop-zone`             | A desktop insertion target for header/chip drag-and-drop.                       |
| `grouping-item`                  | One active grouping level: chip plus its following insertion target.            |
| `grouping-chip`                  | An active grouping field, with logical arrow-key movement and a remove control. |
| `grouping-add`                   | The Add grouping column select, present on desktop and mobile.                  |
| `grouping-aggregations`          | Active aggregation chips plus Add aggregation column and Restore defaults.      |
| `grouping-aggregation-item`      | One active aggregation: column name, operation select, remove.                  |
| `grouping-aggregation-operation` | That item's operation select.                                                   |
| `grouping-aggregation-remove`    | That item's remove control.                                                     |
| `grouping-aggregation-add`       | The Add aggregation column control.                                             |
| `grouping-aggregation-option`    | One checklist row.                                                              |
| `grouping-aggregations-restore`  | Restore defaults.                                                               |
| `grouping-remove-zone`           | Desktop drop target shown while dragging a grouping chip to remove it.          |
| `grouping-announcer`             | Polite live region for add, move, remove, and aggregation-change feedback.      |

| Part                | Element                                                               |
| ------------------- | --------------------------------------------------------------------- |
| `group-row`         | Desktop group header `<tr>` (or antd's grouped row wrapper).          |
| `group-cell`        | The spanning `<td>` / `<th>` inside a group header (most kits).       |
| `group-footer-row`  | The row closing a group when `groupFooters` is set.                   |
| `group-footer-cell` | The spanning cell inside a group footer.                              |
| `group-footer-card` | Group footer block in the mobile card list.                           |
| `group-card`        | Group header block in the mobile card list.                           |
| `group-toggle`      | Expand / collapse chevron (`aria-expanded`, `expandGroup` labels).    |
| `group-label`       | The group's display label (bucket value).                             |
| `group-count`       | Leaf count beside the label (`labels.groupCount`).                    |
| `group-select`      | Tri-state checkbox over the group's leaf rows (when selection is on). |
| `group-aggregate`   | One per-group aggregate cell (`data-column` = column key).            |

### Mobile cards & summary

| Part                                     | Element                                            |
| ---------------------------------------- | -------------------------------------------------- |
| `cards` / `card`                         | The card list and one card.                        |
| `cardRow` / `cardLabel` / `cardValue`    | One label/value line inside a card.                |
| `summary` / `summaryRow` / `summaryCell` | The `<tfoot>`, its `<tr>`, and one summary `<td>`. |
| `summaryCard`                            | The trailing summary card in the mobile list.      |

### Footer, pagination & states

| Part                           | Element                                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| `footer` / `pager`             | The footer bar and the trailing pager group (page-of label + numbered pages).               |
| `pagePrev` / `pageNext`        | The previous and next page buttons.                                                         |
| `pageNumber` / `pageEllipsis`  | Each numbered page (the current one carries `aria-current="page"`) and the "…" elision gap. |
| `loadMore` / `loadMoreButton`  | The infinite-mode sentinel area and its button.                                             |
| `empty` / `emptyClear`         | The empty state and its clear-filters button.                                               |
| `loading` / `refreshIndicator` | The first-load skeleton and the background-refresh bar.                                     |
| `error` / `retryButton`        | The error state and its retry button.                                                       |

### View controls

| Part                                 | Element                                                    |
| ------------------------------------ | ---------------------------------------------------------- |
| `densityToggle` / `fullscreenToggle` | The `densityChooser()` and `fullscreen()` toolbar buttons. |
| `printButton`                        | The Print button drawn by `print(onPrint, true)`.          |
| `commandPaletteButton`               | The control drawn by `commandPalette({ button: true })`.   |
| `undoButton` / `redoButton`          | The Undo and Redo buttons from `undoRedoButtons()`.        |
| `addRow`                             | The Add-row toolbar button.                                |

### Export progress

| Part                                               | Element                                                     |
| -------------------------------------------------- | ----------------------------------------------------------- |
| `exportProgressSurface`                            | The server-export progress card.                            |
| `exportProgressBar` / `exportProgressMessage`      | The determinate or indeterminate bar and the host's detail. |
| `exportProgressActions`                            | The card's action row.                                      |
| `exportProgressCancel` / `exportProgressRetry`     | Cancel while running; Retry after a failure.                |
| `exportProgressDownload` / `exportProgressDismiss` | The finished download link and the Dismiss control.         |

### Command palette, context menu, side panel & status bar

| Part                                                       | Element                                                  |
| ---------------------------------------------------------- | -------------------------------------------------------- |
| `commandPalette` / `commandInput`                          | The `commandPalette()` surface and its search box.       |
| `commandItem` / `commandEmpty`                             | One command row and the "nothing matched" line.          |
| `contextMenu` / `contextMenuItem` / `contextMenuSeparator` | The `contextMenu()` menu, one entry, and a divider.      |
| `sidePanel` / `sidePanelTab` / `sidePanelClose`            | The `sidePanel()` dock, one tab in its strip, and close. |
| `statusBar` / `statusItem`                                 | The `statusBar()` strip and one figure inside it.        |

A few purely structural nodes (`scroll-box`, `virtual-spacer`, the skeleton
internals) expose only the `data-adapttable-part` attribute.

### The structural parts every adapter names

Seven part names are guaranteed in **every** kit, on the same element in each —
so one selector works whichever adapter an app mounts:

| Part                        | Element                          |
| --------------------------- | -------------------------------- |
| `table` / `thead` / `tbody` | The `<table>` and its sections.  |
| `row` / `cell`              | One body `<tr>` and one `<td>`.  |
| `header-cell`               | One header `<th>`.               |
| `toolbar`                   | The toolbar row above the table. |

Two kit-specific shapes to know: antd owns its `<td>` for the selection column,
so `selection-cell` sits on a wrapper one element inside it; and a bounded
height makes antd split the grid into a header table and a body table, both
named `table`. Everything else in the map above is per-adapter — a themed kit
names what it renders.

## Slots

Replace whole sub-components on any adapter:

```tsx
<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  slots={{ empty: <MyEmptyState />, skeleton: <MySkeleton /> }}
/>
```

`skeleton` replaces the first-load skeleton; `empty` replaces the
empty-state.

### The error state

`error` replaces the load-failure state. It takes a node like the others, and
it also takes a function — because an error state is _about_ something:

```tsx
<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  slots={{
    error: ({ error, retry, retrying }) => (
      <MyAlert message={error.message} onRetry={retry} busy={retrying} />
    ),
  }}
/>
```

`retry` is `undefined` when the source has nothing to ask again — a static
`data` array, for instance — so hide your retry control when it is missing
rather than rendering one that does nothing. `retrying` is true while a retry
is already in flight.

Leave the slot off and the built-in state renders, retry button included;
translate it via the `errorTitle` / `errorMessage` / `retry` labels.

### Two empty states, one optional slot

A table is empty for two different reasons, and they deserve different words:
there is no data at all, or a search and filters matched nothing. The built-in
filtered state says so and offers a **clear all filters** action.

`empty` covers both. Add `noResults` when the filtered case needs its own
message — including its own way back:

```tsx
<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  slots={{
    empty: <NoInvoicesYet />,
    noResults: <NothingMatched onClear={clearFilters} />,
  }}
/>
```

Set only `empty` and it covers both states — but the
built-in clear-filters action goes with it, so give your replacement a way to
reset the query.

## Toolbar and status bar

Every view control, the toolbar order and feature notices are on
[toolbar and view controls](./toolbar-and-view-controls.md).

`toolbar` fills the middle of the toolbar — between the search input and
the built-in buttons. `toolbarSlots` fills the two ends:

```tsx
<DataTable
  toolbarSlots={{ start: <BackButton />, end: <HelpLink /> }}
  toolbar={<ViewSwitcher />}
  …
/>
```

The order is: `start` · Search · (mobile sort select) · `toolbar` ·
Filters · Saved views · Columns · Density · Export · Fullscreen · Print ·
Undo/Redo · Add · `end` · Rows per page, in every kit.

`undoRedoButtons()` adds Undo and Redo to that row. They render only when
`editHistory()` is composed, and they disable rather than disappear when there is
nothing to put back — a toolbar that reflows while someone is working is
worse than a button that is briefly unavailable. The keyboard shortcuts
stay the always-on path; the buttons are the visible one, for users who will
not find Ctrl+Z.

```tsx
import {
  editing,
  editHistory,
  undoRedoButtons,
} from "@adapttable/mantine/editing";
import { statusBar } from "@adapttable/mantine/status-bar";

<DataTable
  features={[
    editing(saveCell),
    editHistory(),
    undoRedoButtons(),
    statusBar(),
  ]}
  …
/>;
```

`statusBar()` puts a strip under the table: the row range, how many rows are
selected, and — with `selectionStats()` composed — what the selected cells add up
to. The range is the one the pagination footer shows, from the same
arithmetic, so the two never disagree. The strip hosts the selection figures
rather than repeating them, so turning it on does not print them twice.

Opted-in features that cannot run (virtualize on a paged table, pin under
grouping/tree rows, grouping the source cannot perform, `exportCsv()` with
`scope: "all"` and no full-export route, edits with no writer) show as
`FeatureNotice` items (`FeatureNoticeKind` is the union). They live on
`StatusBarChromeProps.notices` and `TableChrome.featureNotices`, and they
render in the status strip whenever `statusBar()` or `selectionStats()` is
composed — row and selected counts need `statusBar()`. The table's root
element always carries the active kinds in `data-adapttable-notices`.

`print(onPrint, true)` adds a Print button beside the view controls. It needs two
things, not one: the handler, and `true` as the second argument to draw the
button. Either alone draws nothing — a button that opens no dialog would be worse than
no button, and a handler on its own is the palette's Print command. The caption is `labels.print`, the same string the command
uses.

```tsx
import { printTable } from "@adapttable/core/pdf";
import { print } from "@adapttable/mantine/print";

<DataTable
  features={[print(() => printTable({ rows, columns }), true)]}
  …
/>;
```

All of them are off unless asked for: omit them from `features` and nothing renders and
nothing is bundled.

## Highlighting a row

After a save or an import, the row that changed is somewhere in a list of a
thousand. `useHighlight` marks it for a moment:

```tsx
import { useHighlight } from "@adapttable/react";
import { rowAppearance } from "@adapttable/mantine/row-appearance";

const highlight = useHighlight(true);

<DataTable
  features={[
    rowAppearance({
      rowClassName: (row) =>
        highlight.isRowHighlighted(row.id) ? "flash" : undefined,
    }),
  ]}
  …
/>;

// after a save
highlight.flashRow(saved.id);
```

The highlight is a class you compute through
`rowAppearance({ rowClassName })`, which every adapter honours — which means it works
in every kit and looks like the rest of your design system rather than
like ours.

Marks are keyed by row id, so one survives the sort, filter or page change
that moves the row. Flashing the same row again restarts its clock rather
than stacking.

`animated` is false when the user has asked for reduced motion. The mark
still appears and still clears — it holds steady, and holds longer, because a
steady mark is easier to miss than one that moves. Reduced motion means less
movement, not less feedback, so branch on `animated` to pick a class rather
than to skip the highlight:

```tsx
rowAppearance({
  rowClassName: (row) =>
    highlight.isRowHighlighted(row.id)
      ? highlight.animated
        ? "flash flash--animated"
        : "flash"
      : undefined,
});
```

`flashCell({ rowId, columnKey })` and `isCellHighlighted` do the same for one
cell, for a column's `Cell` renderer to read.

## Density and fullscreen

```tsx
import { DataTable } from "@adapttable/mantine";
import { standardFeatures } from "@adapttable/mantine/preset";

<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  features={standardFeatures()}
  …
/>;
```

`standardFeatures()` includes `densityChooser()` — the toggle works with no
`density` or `onDensityChange` from the host. The feature owns uncontrolled
state and starts at `"comfortable"`. To control density yourself, pass `density`
as the source of truth and `onDensityChange` to observe requests:

```tsx
import { densityChooser } from "@adapttable/mantine/density";
import { fullscreen } from "@adapttable/mantine/fullscreen";
import type { Density } from "@adapttable/mantine/density";

const [density, setDensity] = useState<Density>("comfortable");

<DataTable
  density={density}
  onDensityChange={setDensity}
  features={[densityChooser(), fullscreen()]}
  …
/>;
```

Pairing controlled density with `useDensityUrlState` keeps the choice in the
URL beside sort and filters, so a reload and a shared link both reproduce it:

```tsx
import { densityChooser } from "@adapttable/mantine/density";
import { fullscreen } from "@adapttable/mantine/fullscreen";
import { useDensityUrlState } from "@adapttable/react";

const { density, onDensityChange } = useDensityUrlState();

<DataTable
  density={density}
  onDensityChange={onDensityChange}
  features={[densityChooser(), fullscreen()]}
  …
/>;
```

`fullscreen()` adds a toggle. Fullscreen hides everything outside the table,
which is what makes it useful and also what breaks overlays: a menu
portalled to `document.body` sits inside the part being hidden, still
mounted and still focused. The table's own overlays are re-pointed at the
fullscreen element automatically. Adapter code that portals its own reads
`DataTableShellResult.fullscreen.container` from `@adapttable/react/adapter`
and uses it while it is set; host overlays portalled outside the table are
hidden while fullscreen is on.

The toggle hides itself where the browser will not allow fullscreen — an
embedded webview, a sandboxed frame — because a control that cannot work is
worse than no control.

## Command palette

The full reference is [command palette and context menu](./command-palette.md).

```tsx
import { commandPalette } from "@adapttable/mantine/command-palette";
import { print } from "@adapttable/mantine/print";
import { printTable } from "@adapttable/core/pdf";

<DataTable
  features={[
    commandPalette(),
    print(() => printTable({ rows, columns })),
  ]}
  …
/>;
```

Cmd/Ctrl+K opens a palette listing the built-in commands the composed
features provide (Print, Export, Clear filters), followed by any `commands`
you register. Type
to filter, arrows to move, Enter to run, Escape to close.

Its entries are the same objects the context menus take. That is the point:
an action written once appears in both, and cannot gain a condition in one
and not the other.

```tsx
import { commandPalette } from "@adapttable/mantine/command-palette";

<DataTable
  features={[
    commandPalette({
      commands: [{ key: "audit", label: "Open audit log", onSelect: open }],
      shortcuts: [{ chord: "ctrl+shift+p", command: "command-palette" }],
    }),
  ]}
  …
/>;
```

Shortcuts are data, not a key handler, because remapping is not a
preference — your app may already own Cmd/Ctrl+K. `mod` means Cmd on a Mac
and Ctrl elsewhere, so one chord is right on both. `shortcuts: []` binds no
key, and the palette then stays closed. See
[command palette and context menu](./command-palette.md).

`printTable` opens a browser dialog, so printing is the host's call to make.
Compose `print(onPrint)` and it becomes a command; pass `true` as the second
argument to also draw the toolbar button; leave it out and it is not offered.

## Context menus

The full reference is
[command palette and context menu](./command-palette.md#context-menu).

```tsx
import { contextMenu } from "@adapttable/mantine/context-menu";

<DataTable features={[contextMenu()]} … />;
```

Right-click a header and it offers that column's actions — sort, filter,
hide. Right-click a cell and it offers copy. Each entry appears only
when the handler behind it is wired and the column allows it: a menu that
lists "Hide column" over a column locked against hiding reads as broken
rather than as forbidden.

Every route in works, because a right-click-only menu is one half the people
who need it cannot reach:

| Route    | Opens with                           |
| -------- | ------------------------------------ |
| Pointer  | Right-click                          |
| Keyboard | Shift+F10, or the dedicated menu key |
| Touch    | Press and hold                       |

Escape closes it and puts focus back where it came from. A press that travels
more than a few pixels is a scroll, not a menu.

Add your own entries with `{ items }`. They land behind a divider, so a
custom action is never mistaken for a built-in one:

```tsx
import { contextMenu } from "@adapttable/mantine/context-menu";

<DataTable
  features={[
    contextMenu({
      items: (target) =>
        target.kind !== "header"
          ? [{ key: "audit", label: "Open audit log", onSelect: () => open(target.rowId) }]
          : [],
    }),
  ]}
  …
/>;
```

## Side panel

A popover is right for a control you touch once and dismiss. It is wrong for
setting a table up — choosing columns, building a filter, arranging a pivot —
because that is iterative: change one thing, look at the rows, change
another. A popover closes when you look away, and the rows are behind it
while it is open.

`sidePanel()` docks that work beside the table instead. It is controlled,
because the control that opens it is yours — `toolbarSlots` is where it
usually goes:

```tsx
import { sidePanel } from "@adapttable/mantine/side-panel";

const [panel, setPanel] = useState<string | null>(null);

<DataTable
  toolbarSlots={{
    end: <button onClick={() => setPanel("filters")}>Settings</button>,
  }}
  features={[
    sidePanel({
      panels: [
        { key: "filters", label: "Filters", content: <MyFilters /> },
        { key: "columns", label: "Columns", content: <MyColumnList /> },
      ],
      open: panel,
      onOpenChange: setPanel,
      side: "end",
    }),
  ]}
  …
/>;
```

`SidePanelOptions` types it and `SidePanelEntry` is one panel — a `key`, a
`label` and the `content` to show. With more than one panel the labels
become a real tab strip: one tab stop for the whole strip, arrow keys that
wrap and carry the selection, Home and End. Escape closes from anywhere
inside. Putting focus back afterwards is the opener's job, since only it
knows where focus was.

`side` picks the edge — `"end"` (the default) is the right in a
left-to-right table and the left in a right-to-left one. Omit `sidePanel()`
from `features` and nothing renders, nothing is bundled, and the table's markup is
unchanged.

Adapters build their panel over `SidePanelChrome` / `SidePanelSlots` /
`SidePanelFrameProps` / `SidePanelTabProps` / `SidePanelCloseProps` and dock
it with `SidePanelLayout` / `SidePanelLayoutProps`, all from
`@adapttable/react/adapter`.

## Density

```tsx
<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  density="compact"
/>
```

`"comfortable"` (default) is the roomy layout; `"compact"` tightens row
height and padding. With `densityChooser()` composed and no controlled
`density` prop, the feature owns the choice and defaults to `"comfortable"`.
Each adapter maps density to its kit's table size — MUI `"comfortable"` →
`medium` / `"compact"` → `small`, antd → `middle` / `small`, Radix `"2"` /
`"1"`, Base UI `"2"` / `"1"` — and Chakra, antd, Radix and Base UI take an
explicit `size` prop that overrides the mapping (e.g. antd `size="large"`).
MUI always follows density.

## Export

CSV by default, spreadsheets when you ask for them — one factory, one set of
scopes, [one button](#spreadsheet-xlsx-export).

Opt in with `exportCsv()` from `@adapttable/<kit>/export` to render a kit-native **Export CSV** button next to
Filters / Columns. The file mirrors the current view's data — the active search, filters,
and sort — with **the full exportable column set in display order,
regardless of viewport**: the same button produces the same file on phone
and desktop (`hideOnMobile` never shrinks an export).

Cells that a spreadsheet would execute as formulas (`=`, `+`, `-`, `@`,
tab or carriage-return prefixes) are neutralised with a leading `'` by
default; pass `escapeFormulas: false` in the options object if you need
raw output for a non-spreadsheet pipeline.

```tsx
import { DataTable } from "@adapttable/mantine";
import { exportCsv } from "@adapttable/mantine/export";

<DataTable
  data={people}
  columns={columns}
  rowKey={(r) => r.id}
  features={[exportCsv()]} // defaults: export.csv, current page
/>;

<DataTable
  data={people}
  columns={columns}
  rowKey={(r) => r.id}
  features={[exportCsv({ filename: "people.csv", scope: "all" })]}
/>;
```

- `scope: "page"` (default) — the current page / loaded slice.
- `scope: "all"` — the full filtered+sorted set when the source can reach it
  (frontend can). A source-owned route requires both actual
  `allFilteredRows` and a capability contract that permits `"all"`; the
  declaration alone does not retrieve rows. Otherwise `request` or `fetchAll`
  must fetch the rest — see
  [source capabilities](./data-tiers.md#what-a-source-can-do--capabilities).

  **"All" means every row that matched the filters, not every row on screen.**
  Display state never shrinks an export: a collapsed tree folder still writes
  the rows inside it, and pagination does not decide what leaves the table.
  A grouped export keeps its headers and totals around those rows.

  A server-backed table holds one page, so `"all"` has to be answered by
  fetching. There are two ways, and no third:

  - `request` — hand the whole thing to your backend. The `ExportRequest` it
    receives carries an `ExportQuery` with `page` and `limit` **undefined** for
    this scope, precisely so a handler cannot answer with one page.
  - `fetchAll` — let the table page the query itself and build the file in the
    browser. It is opt-in because it is a loop of requests, and capped because
    an unbounded one can hang a tab: `maxRows` defaults to
    `EXPORT_FETCH_ALL_MAX_ROWS` (50,000), and `onCapped` fires if the cap
    stopped the export short. `fetchAllExportRows` is the same walk, exported
    for hand-built downloads.

  With no executable route, the Export button stays rendered but disabled,
  with the localized reason on the control, and in the status bar when one is
  composed. Writing the
  current page as if it were everything is the one answer that is always wrong.

- `scope: "selected"` — the ticked rows, in table order. Selection is a set of
  ids, so a row checked on page 1 is still in the file while page 3 is on
  screen. Nothing ticked writes a header-only file.
- `scope: "range"` — the highlighted cell rectangle from
  [cell navigation](./cell-navigation.md). A rectangle names its own columns,
  so it decides them and `columns` is not consulted. With nothing selected the
  current page is exported instead.

`columns` chooses the file's shape independently of the rows:

- `columns: "visible"` (default) — what the user can see, so the file matches
  the screen.
- `columns: "all"` — every defined column, including ones hidden through the
  column menu, for a complete extract.
- `columns: ["name", "email"]` — exactly these, in this order. A key matching
  no column is ignored, so a stale saved config cannot break the button.

The synthetic actions column is never exported under any of them.

### Exporting a different value than the screen shows

A cell formatted for reading is worse than useless in a spreadsheet: `"$1,240.00"`
cannot be summed and `"3 days ago"` cannot be sorted. Give the column an
`exportValue` and the file carries the value underneath while the table keeps
rendering the friendly version:

```tsx
{
  key: "budget",
  accessor: (row) => money.format(row.budget),  // what the user reads
  exportValue: (row) => row.budget,             // what the spreadsheet gets
}
```

Columns without one export what the table shows, so this is only needed where
the two genuinely differ. Formula escaping still applies to whatever is
returned.

### Spreadsheet (XLSX) export

The full reference — cell typing, widths, sheet names and Node builds — is
[Excel (XLSX) export](./export-xlsx.md).

The same button writes a real `.xlsx` when you hand it the spreadsheet writer:

```tsx
import { xlsxWriter } from "@adapttable/core/xlsx";
import { exportCsv } from "@adapttable/mantine/export";

<DataTable
  data={people}
  columns={columns}
  rowKey={(r) => r.id}
  features={[
    exportCsv({ writer: xlsxWriter({ sheetName: "People" }), scope: "all" }),
  ]}
/>;
```

Every scope and column option above works unchanged — which rows and columns
leave the table is decided before the format is asked for anything.

The button relabels itself: it reads **Export XLSX** here, not "Export CSV",
from `labels.exportFile(format)` — translated in every bundled locale, and
given a caption for a format nobody planned for (a custom writer calling itself
`tsv` gets "Export TSV"). CSV keeps `labels.exportCsv`, so its existing
translations and any wording you overrode are untouched.

Three differences from CSV, all in your favour. Numbers, booleans and `Date`
values stay **typed**, so a spreadsheet can sum a column, filter a date, and
sort a checkbox instead of reading text that looks like one; text that looks
numeric stays text, so a postal code of `01730` arrives as `01730` rather than
`1730`; and the sheet is styled for reading — a frozen bold header, column
widths from the table, group and tree rows outlined at their depth, group
footers and a `summaryRow` grand total in bold. Formula escaping is not needed
and is ignored: XLSX keeps formulas in their own element, so a cell reading
`=CMD()` is displayed, never executed.

A grouped or tree-shaped table exports that structure, not a denormalised
leaf list: group headers and footers travel with the leaves, collapsed groups
stay collapsed on `scope: "page"`, and `scope: "all"` / `"selected"` include
leaves that were folded or paged away — then `"selected"` keeps only the
groups that still have a selected leaf. A `scope: "range"` export stays a
rectangle — the selection already named its shape. Mobile cards use the same
button and the same file; `hideOnMobile` never shrinks an export.

`@adapttable/core/xlsx` is its documented entry, because a table that
exports CSV should not ship a ZIP encoder: nothing XLSX-related reaches a
bundle that does not import `xlsxWriter`. There is no new dependency either way — `buildTableXlsx` writes
the workbook by hand.

Any format is reachable the same way. An `ExportWriter` is an extension and a
`build` function over the resolved values (`ExportWriteContext` in,
`ExportPayload` out); `csvWriter` is the built-in one, and `downloadExportFile`
hands a built payload to the browser. A writer receives an `ExportTable` —
headers, keys, and one array of values per row, resolved once by
`buildExportTable` — rather than rows and columns, so two formats of the same
table cannot disagree about what a cell contains, and a writer needs no type
argument.

### Before and after the file is written

```tsx
import { exportCsv } from "@adapttable/mantine/export";

<DataTable
  features={[
    exportCsv({
      onBeforeExport: ({ rows, columns, filename }) => {
        if (rows.length > 50_000) return false; // cancel
        return { filename: `people-${rows.length}.csv` }; // or rename
      },
      onAfterExport: ({ csv, file, filename }) =>
        track("export", { filename }),
    }),
  ]}
  …
/>;
```

`onBeforeExport` runs once the rows and columns are resolved and before
anything is written — the only moment where the file's contents are known and
nothing has happened yet. Return `false` to cancel, `{ filename }` to rename,
or nothing to continue — a cancelled export builds no file at all.
`onAfterExport` receives the text that was written as `csv`, and the built file
as `file`; a binary format leaves `csv` empty and carries its bytes in
`file.parts`.

Headless helpers remain available: `rowsToCsv`, `downloadCsv`, and
`downloadTableCsv` from `@adapttable/core`.

### Exporting from your backend

Past a certain size the browser is the wrong place to build the file: the rows
are not all loaded, holding them would cost more memory than the tab has, and
the work blocks the main thread. `onExportAll` hands the page-free current view
to the server and keeps the job visible:

```tsx
import { exportCsv } from "@adapttable/mantine/export";

<DataTable
  features={[
    exportCsv({
      scope: "all",
      onExportAll: async (query, controls) => {
        const res = await fetch("/api/people/export", {
          method: "POST",
          body: JSON.stringify(query),
          signal: controls.signal,
        });
        const job = await res.json();
        controls.setProgress?.(job.progress);
        controls.setMessage?.(job.message);
        return job.url ? { url: job.url } : undefined;
      },
    }),
  ]}
  …
/>;
```

`query` carries search, flat and nested filters, single and multi-sort,
grouping, visible and requested column keys, format, and filename — but no page
window and no rows. `controls.signal` powers Cancel; `setProgress(0–100)` and
`setMessage(text)` update every kit's progress surface. No progress means an
indeterminate indicator. Resolve `{ url }` and the table offers the download;
resolve nothing when the host delivered it another way; reject for a localized
error with Retry.

The existing `fetchAll` route still pages in the browser and keeps its 50,000
row default cap. `onExportAll` is the documented route past it. The generic
`request` callback also remains for backend takeover of page, selected, or
range exports without progress. Host-owned routes do not run
`onBeforeExport`/`onAfterExport`, because the table never builds their file.

The full settle, cancellation, and accessibility contract is in
[Browser and server-built exports](./exporting.md).

### The export pipeline (headless)

The export path is exported end to end: `exportableColumns` filters the
visible layout to columns with exportable values, `resolveExportColumns`
applies a column scope to them, `buildTableCsv` turns rows + columns into CSV
text (`RowsToCsvOptions` controls `delimiter`, `escapeFormulas` and
`getValue`; `downloadCsv` adds the UTF-8 BOM Excel needs),
`resolveExportCsv` normalizes the export options (`ExportCsvOptions`), and
`makeExportCsvHandler` wires all of it to a download handler the toolbar button
calls. Custom toolbars can reuse any stage.

Formats plug in at the last stage only. `csvWriter` and `xlsxWriter` are both
`ExportWriter`s — given an `ExportWriteContext` (an `ExportTable` of resolved
values, plus the filename) they return an `ExportPayload`, which
`downloadExportFile` writes. Nothing earlier in the pipeline knows which format
is in play, and `matrixToCsv` is the CSV half of it for anyone assembling values
themselves.

Custom adapters bind the button with `useExportHandler` from
`@adapttable/react/adapter`: it takes the handler above and returns an
`ExportHandlerState` — `onExportCsv`, `exportBusy`, `exportLabel`,
`exportDisabled`, `exportDisabledReason`, `exportStatus`,
`exportProgressState` and `exportAnnouncement` — which is how every
built-in adapter gets identical single-flight behaviour.

Four supporting types: `ExportRowScope` and `ExportColumnScope` name the two
scope unions, `ExportInfo` is what the lifecycle hooks receive, and
`ExportContext` carries the selection, full column set and highlighted range
that `scope: "selected"`, `columns: "all"` and `scope: "range"` need — the
adapters pass all of it automatically, and only a hand-built
`downloadTableCsv` call has to supply it.

## Sticky header, offset & scroll box

```tsx
<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  stickyHeader // keep the desktop header pinned while the page scrolls
  stickyTop={56} // offset under your app header (also offsets the toolbar)
  maxHeight={420} // fixed-height scroll box instead of page scroll
/>
```

`maxHeight` turns the table into a scroll box that also scrolls sideways —
the header and pinned columns stick within it, which is what makes column
pinning visibly stick. `scrollToTopOnChange` (default `true`) scrolls back
to the table when search/filter/page changes, with `scrollTopGap` (default
`8`) of breathing room below sticky chrome.

### The surface behind sticky and pinned cells (Mantine)

A sticky header and pinned columns need an opaque background, or scrolled rows
show through them. That colour and the hairline under the header come from two
CSS variables, so a panel whose surface is not the page background can say so:

```css
.my-dark-panel {
  --adapttable-surface: #101418;
  --adapttable-header-border: #2b3238;
}
```

They default to `--mantine-color-body` and `--mantine-color-default-border`,
so tables look the same until you set them. Declare them on any ancestor of
the table.

## Desktop table assembly

The six HTML kits (Mantine, MUI, Chakra, Radix, Base UI, Unstyled; shadcn
follows Unstyled) paint from one shared plan on
`@adapttable/react/adapter`. Ant Design stays on its native `<Table>`.

```ts
import {
  createDesktopRow,
  DESKTOP_ACTIONS_WIDTH,
  DESKTOP_EXPANSION_WIDTH,
  DESKTOP_SELECTION_WIDTH,
  useDesktopTableAssembly,
} from "@adapttable/react/adapter";
```

`useDesktopTableAssembly(props, options?)` takes
`DesktopAssemblyProps` plus optional `DesktopAssemblyOptions` (mostly
`DesktopChromeWidths` for the reserved selection / expansion / actions
columns — defaults `DESKTOP_SELECTION_WIDTH`, `DESKTOP_EXPANSION_WIDTH`,
`DESKTOP_ACTIONS_WIDTH`) and returns a `DesktopTableAssembly`: header
leaves (`DesktopHeaderLeaf`), pin state (`DesktopTablePin`), and body
slots (`DesktopBodySlot` — rows as `DesktopRowSlot`, groups as
`DesktopGroupSlot` / `DesktopGroupEntry`, extras as `DesktopExtraSlot`,
virtual pads as `DesktopVirtualPadSlot`). `createDesktopRow` is the
memoized row the kits mount; `DesktopRowWiring` is the per-row bundle it
receives. Layout changes land once in the plan; each kit still owns
pixels.

`tableRenderModel` and `getRowProps` stay first-class — this helper is
add-only.

## Theming per kit

The core is style-free: wrap your app in the kit's provider and AdaptTable
renders with that kit's real components, following its theme and dark mode
(`prefers-color-scheme`) automatically.

## Animations

`animate` works on **every adapter** — a dependency-free row/card entrance
stagger that honours reduced motion. Rolling your own? Every animatable
row/card carries a `data-stagger` attribute, so leave `animate` off and target
those elements with GSAP/Framer Motion.

Kit-specific knobs:

- **MUI** — `className` lands on the root `<Paper>`; table size follows
  density.
- **Chakra** — `accentColor` colors primary accents (buttons, badges);
  `size` (`"sm" | "md" | "lg"`, default `"md"`).
- **Radix / Base UI** — `accentColor` colors primary accents; `size`
  (`"1" | "2" | "3"`).
- **Ant Design** — `size` (`"small" | "middle" | "large"`), `bordered` for
  cell borders, `className` on the wrapper. The virtualized scroll area is
  bounded by the shared `maxHeight` prop.
- **Unstyled** — no provider needed; theme entirely through `classNames`,
  the `data-adapttable-part` hooks above, and your own CSS variables /
  `data-theme`.

## Custom cells

Pass a `Cell` component (receives `{ row, rowIndex }`; define it at module
level so its identity is stable) or a lighter `accessor`:

```tsx
import type { CellProps } from "@adapttable/core";

function StatusCell({ row }: CellProps<Person>) {
  return (
    <Badge color={row.status === "active" ? "green" : "gray"}>
      {row.status}
    </Badge>
  );
}

const columns = [
  { key: "name", sortable: true },
  { key: "status", Cell: StatusCell },
  {
    key: "salary",
    accessor: (r: Person) => formatMoney(r.salary),
    align: "end",
  },
];
```

See the [Columns guide](./columns.md) and the
[ColumnDef table](./api.md#columndef) for the full column surface
(`sortValue`, `i18n`, `group`, `hideOnMobile`, …).

---

# React table toolbar and view controls — density, fullscreen, print, status bar

▶ **See it working:** [the Feature Lab](https://adapttable.orwamahmoud.com/react/demo/all-options/) — turn **Density & fullscreen**, **Print button**, **Status bar**, **Undo / Redo buttons** and **Side panel** on, on any kit.

The toolbar above the table carries search and the controls of the features
you compose. Every view control is opt-in: `densityChooser()`, `fullscreen()`,
`print(onPrint, true)`, `statusBar()`, `selectionStats()`, `sidePanel({...})`,
`undoRedoButtons()` and `exportCsv()` are factories in `features={[...]}`, each
imported from its own `@adapttable/<kit>/<subpath>`. Omit one and its control
is not drawn and its code is not bundled. Each control is drawn with the kit's
own components. See [feature composition](./features.md).

This page covers what each control does and where it sits. For per-part
class names and slot replacement, see
[customization](./customization.md#view-controls).

## Example

```tsx
import { printTable } from "@adapttable/core/pdf";
import { type ColumnDef, DataTable } from "@adapttable/mantine";
import { densityChooser } from "@adapttable/mantine/density";
import { exportCsv } from "@adapttable/mantine/export";
import { fullscreen } from "@adapttable/mantine/fullscreen";
import { print } from "@adapttable/mantine/print";
import { statusBar } from "@adapttable/mantine/status-bar";

interface Person {
  id: string;
  name: string;
  team: string;
  budget: number;
}

const people: Person[] = [
  { id: "1", name: "Amira Hassan", team: "Platform", budget: 12000 },
  { id: "2", name: "Tom Becker", team: "Design", budget: 8400 },
  { id: "3", name: "Lina Park", team: "Platform", budget: 15100 },
];

const columns: ColumnDef<Person>[] = [
  { key: "name", header: "Name", sortable: true },
  { key: "team", header: "Team", sortable: true },
  { key: "budget", header: "Budget", sortable: true },
];

export function People() {
  return (
    <DataTable
      data={people}
      columns={columns}
      rowKey={(row) => row.id}
      features={[
        densityChooser(),
        exportCsv(),
        fullscreen(),
        print(() => printTable({ rows: people, columns }), true),
        statusBar(),
      ]}
    />
  );
}
```

After the search input the toolbar shows the density toggle (captioned
**Comfortable**), **Export CSV**, the fullscreen toggle and **Print**, and a
strip under the table reads "Showing 1–3 of 3". The snippets below reuse
`people` and `columns` from this example.

## How it works

- Each factory contributes its control to one toolbar position. The controls
  in that position are ordered by feature, not by the order of the
  `features` array, so `[print(...), densityChooser()]` and
  `[densityChooser(), print(...)]` draw the same toolbar.
- A control renders only when the feature that makes it work is composed.
  The button and its behaviour arrive in the same import.
- `standardFeatures()` from `@adapttable/<kit>/preset` includes
  `densityChooser()`, `exportCsv()`, `fullscreen()` and `statusBar()`, and
  find-in-table without its toolbar control; `standardFeatures({ findButton: true })`
  draws the Find control too. It does not include `print`, `selectionStats`,
  `sidePanel` or `undoRedoButtons`, which need a handler, a sibling feature or
  content from you.

## Toolbar order

Left to right in a left-to-right table:

| Kit       | Order                                                                                                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Every kit | `start` · Search · mobile sort select · `toolbar` · Filters · Saved views · Columns · Density · Export · Find · Fullscreen · Print · Undo/Redo · Add row · `end` · Rows per page |

Undo and Redo sit after Print in every kit. To draw them yourself — outside
the table, or in your own toolbar — take the history from
`editHistory({ onChange })`; see
[cell editing](./cell-editing.md#undo-and-redo).

Each entry appears only when its source is present:

| Entry              | Appears when                                                                                                                 |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Search             | Always, unless `searchable={false}`.                                                                                         |
| Mobile sort select | `sortByOptions` is set, or the table is in the mobile card layout and has sortable columns.                                  |
| Filters            | [Filters](./filtering.md) are composed.                                                                                      |
| Saved views        | [`savedViews(...)`](./saved-views.md) is composed.                                                                           |
| Columns            | [`columnMenu()`](./column-management.md) is composed.                                                                        |
| Density            | `densityChooser()` is composed.                                                                                              |
| Export             | `exportCsv()` is composed. See [exporting](./exporting.md).                                                                  |
| Find               | `findInTable({ button: true })` is composed. See [find in table](./cell-navigation.md#find-in-table).                        |
| Fullscreen         | `fullscreen()` is composed and the browser allows fullscreen.                                                                |
| Print              | `print(onPrint, true)` is composed.                                                                                          |
| Undo/Redo          | `undoRedoButtons()` and `editHistory()` are both composed.                                                                   |
| Add row            | `rowActions(actions, { onAddRow })` is composed. See [cell editing](./cell-editing.md#adding-duplicating-and-deleting-rows). |
| Rows per page      | The table loads more rows on scroll (infinite mode) and is not grouped. Paged tables show it in the footer.                  |

## Toolbar slots

`toolbar` fills the middle of the toolbar, before the Filters button.
`toolbarSlots` fills the two ends. Both are plain React nodes and neither
needs a feature:

```tsx
import { Anchor, Button, SegmentedControl } from "@mantine/core";

<DataTable
  data={people}
  columns={columns}
  rowKey={(row) => row.id}
  toolbarSlots={{
    start: <Button variant="subtle">Back</Button>,
    end: <Anchor href="/help">Help</Anchor>,
  }}
  toolbar={<SegmentedControl data={["Table", "Board"]} />}
/>;
```

| Prop                 | Type        | Position                                                       |
| -------------------- | ----------- | -------------------------------------------------------------- |
| `toolbarSlots.start` | `ReactNode` | Ahead of the search input.                                     |
| `toolbar`            | `ReactNode` | After search and the mobile sort select, before Filters.       |
| `toolbarSlots.end`   | `ReactNode` | After every built-in control, before the rows-per-page select. |

`ToolbarSlots` types the object. `@adapttable/bootstrap` ships none of the
view-control subpaths on this page, and its toolbar does not draw
`toolbarSlots`.

## Density

`densityChooser()` from `@adapttable/<kit>/density` adds a toolbar button that
switches between `"comfortable"` and `"compact"`. Its caption is the current
density (`labels.densityComfortable` / `labels.densityCompact`) and its
accessible name is `labels.density`.

Without a `density` prop, the feature owns the value and starts at
`"comfortable"`. Pass `density` to control it; `onDensityChange` receives
every request in both modes, and a controlled table changes only when its
prop does.

```tsx
import { useState } from "react";
import { DataTable } from "@adapttable/mantine";
import { type Density, densityChooser } from "@adapttable/mantine/density";

export function People() {
  const [density, setDensity] = useState<Density>("compact");
  return (
    <DataTable
      data={people}
      columns={columns}
      rowKey={(row) => row.id}
      density={density}
      onDensityChange={setDensity}
      features={[densityChooser()]}
    />
  );
}
```

The `density` prop works without the feature too: `density="compact"` alone
renders a compact table with no toolbar button.

### Density and kit sizes

Each adapter maps density to its kit's own table size:

| Kit                 | `"comfortable"`                                  | `"compact"`                                     | Explicit `size` prop overrides  |
| ------------------- | ------------------------------------------------ | ----------------------------------------------- | ------------------------------- |
| Mantine             | `verticalSpacing="sm"`, `horizontalSpacing="md"` | `verticalSpacing={4}`, `horizontalSpacing="sm"` | —                               |
| MUI                 | `size="medium"`                                  | `size="small"`                                  | No — MUI always follows density |
| Chakra UI           | `size="md"`                                      | `size="sm"`                                     | Yes                             |
| Ant Design          | `size="middle"`                                  | `size="small"`                                  | Yes (e.g. `size="large"`)       |
| Radix               | `size="2"`                                       | `size="1"`                                      | Yes                             |
| Base UI             | `size="2"`                                       | `size="1"`                                      | Yes                             |
| unstyled, shadcn/ui | `data-density="comfortable"` on the root         | `data-density="compact"` on the root            | —                               |

Mantine exports the mapping as `DENSITY_SPACING` (typed
`Record<Density, DensitySpacing>`) from `@adapttable/mantine/density`.

### Density in the URL

`useDensityUrlState()` from `@adapttable/react` keeps the choice in the URL
beside sort and filters, so a reload and a shared link reproduce it. Pair it
with the controlled prop:

```tsx
import { DataTable } from "@adapttable/mantine";
import { densityChooser } from "@adapttable/mantine/density";
import { useDensityUrlState } from "@adapttable/react";

export function People() {
  const { density, onDensityChange } = useDensityUrlState();
  return (
    <DataTable
      data={people}
      columns={columns}
      rowKey={(row) => row.id}
      density={density}
      onDensityChange={onDensityChange}
      features={[densityChooser()]}
    />
  );
}
```

| Option           | Type              | Default         | Description                                                                      |
| ---------------- | ----------------- | --------------- | -------------------------------------------------------------------------------- |
| `urlKey`         | `string`          | —               | Namespace: the parameter becomes `<urlKey>.density`. Match the table's `urlKey`. |
| `urlSync`        | `boolean`         | `true`          | Mirror the value into the URL.                                                   |
| `urlAdapter`     | `UrlStateAdapter` | the browser URL | Router adapter. See [URL state](./url-state.md).                                 |
| `defaultDensity` | `Density`         | `"comfortable"` | The value before anyone chooses one.                                             |

The parameter is `density=compact`. Choosing the default removes it rather
than restating it, and writes are debounced by 150 ms. A density kept in the
URL is part of a [saved view](./saved-views.md); the feature's own
uncontrolled value is not.

## Fullscreen

`fullscreen()` from `@adapttable/<kit>/fullscreen` adds a toggle that promotes
the table's root element with the browser Fullscreen API. Its accessible name
is `labels.enterFullscreen` or `labels.exitFullscreen`.

- The state is read from the document, so leaving by Escape or the browser's
  own control updates the toggle.
- The toggle is not drawn where `document.fullscreenEnabled` is false, such as
  a sandboxed frame.
- The table's own overlays (menus, popovers, the context menu) portal into the
  fullscreen element while it is active. Host overlays portalled to
  `document.body` are hidden while fullscreen is on. Adapter authors read
  `DataTableShellResult.fullscreen.container` from `@adapttable/react/adapter`.

## Print

`print(onPrint, printButton?)` from `@adapttable/<kit>/print` registers a print
action. What is printed is yours to decide; `printTable` from
`@adapttable/core/pdf` lays rows and columns out for paper and opens the
browser's print dialog. See [PDF export and print](./export-pdf.md).

| Argument      | Type         | Default | Description                                                                |
| ------------- | ------------ | ------- | -------------------------------------------------------------------------- |
| `onPrint`     | `() => void` | —       | Runs when Print is chosen. Required.                                       |
| `printButton` | `boolean`    | `false` | `true` also draws a Print button in the toolbar, captioned `labels.print`. |

With `printButton` left at `false`, the handler is only a
[command palette](./command-palette.md) entry. The palette lists Print
whenever `print(...)` is composed.

## Undo and redo buttons

`undoRedoButtons()` from `@adapttable/<kit>/editing` draws Undo and Redo
(`labels.undoEdit` / `labels.redoEdit`) over the stack `editHistory()` keeps.
Both factories are needed: without `editHistory()` the buttons do not render.
They are disabled, not removed, when there is nothing to undo or redo, so the
toolbar does not reflow.

```tsx
import { useState } from "react";
import { DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import {
  editHistory,
  editing,
  undoRedoButtons,
} from "@adapttable/mantine/editing";

export function Budgets() {
  const [rows, setRows] = useState(people);
  return (
    <DataTable
      data={rows}
      columns={[
        { key: "name", header: "Name" },
        { key: "budget", header: "Budget", editable: true },
      ]}
      rowKey={(row) => row.id}
      features={[
        cellNavigation(),
        editing((row, key, nextValue) => {
          setRows((prev) =>
            prev.map((r) =>
              r.id === row.id ? { ...r, [key]: nextValue as never } : r
            )
          );
        }),
        editHistory(),
        undoRedoButtons(),
      ]}
    />
  );
}
```

The Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z keys need `cellNavigation()`; the buttons
do not. History depth, gestures and what an undo commits are covered in
[cell editing](./cell-editing.md#undo-and-redo).

## Status bar

`statusBar()` from `@adapttable/<kit>/status-bar` draws a strip under the
table:

- the row range, from the same arithmetic as the pagination footer
  ("Showing 1–10 of 240", `labels.showing`);
- how many rows are selected, when row selection is on and the count is above
  zero (`labels.selectedCount`);
- the selection figures, when `selectionStats()` is composed.

`selectionStats()` is exported from both `@adapttable/<kit>/status-bar` and
`@adapttable/<kit>/selection-stats`. It adds Count, Sum, Avg, Min and Max for a
multi-cell range, which needs [`cellNavigation()`](./cell-navigation.md#what-the-selection-adds-up-to).
Composing it also mounts row selection. The two features share one strip, so
composing both draws the figures once.

```tsx
import { DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { selectionStats, statusBar } from "@adapttable/mantine/status-bar";

<DataTable
  data={people}
  columns={columns}
  rowKey={(row) => row.id}
  features={[cellNavigation(), statusBar(), selectionStats()]}
/>;
```

Every figure is a `status-item` part carrying `data-status` (`rows`,
`selected`, or a notice kind) in every kit.

## Feature notices

A feature you composed that cannot run in the current configuration produces
a `FeatureNotice` (`kind`, `appearance`, `message`) instead of failing
silently. The matching control already looks off, disabled or limited to one
page; the notice says why.

| `kind`                 | `appearance` | Raised when                                                                                | Label                       |
| ---------------------- | ------------ | ------------------------------------------------------------------------------------------ | --------------------------- |
| `virtualize-paged`     | `one-page`   | Row virtualization is requested on a paged table.                                          | `noticeVirtualizePaged`     |
| `grouping-unavailable` | `off`        | Grouping is armed and the source cannot group.                                             | `noticeGroupingUnavailable` |
| `pin-nested`           | `off`        | Row pinning is requested while grouping or a tree is on.                                   | `noticePinNested`           |
| `export-all-page`      | `disabled`   | `exportCsv({ scope: "all" })` has no route to the full dataset and falls back to the page. | `noticeExportAllPage`       |
| `edit-without-writer`  | `off`        | A column is `editable`, or row or batch editing is on, with no write handler.              | `noticeEditWithoutWriter`   |

`FeatureNoticeKind` is the union of kinds and `FeatureNoticeAppearance` the
union of appearances, both from `@adapttable/core`.

Notices reach the page in two ways:

- **In the status strip**, only when `statusBar()` or `selectionStats()` is
  composed. They render first, as `status-item` parts with
  `data-status="<kind>"` and `data-appearance="<appearance>"`. They show
  without `statusBar()`; the row and selected counts need it.
- **On the root element** always, as `data-adapttable-notices` — the active
  kinds separated by spaces, e.g.
  `data-adapttable-notices="virtualize-paged export-all-page"`. The attribute
  is absent when there are none, so CSS and tests can select on it.

Adapter authors receive the list as `TableChrome.featureNotices` and pass it
to `StatusBarChromeProps.notices`.

## Side panel

`sidePanel(options)` from `@adapttable/<kit>/side-panel` docks a panel beside
the table for work that is iterative — choosing columns, building a filter —
where a popover would close and hide the rows. It is controlled and draws no
opener of its own; `toolbarSlots` is where the opener usually goes.

```tsx
import { useState } from "react";
import { Button } from "@mantine/core";
import { DataTable } from "@adapttable/mantine";
import { sidePanel } from "@adapttable/mantine/side-panel";

export function People() {
  const [panel, setPanel] = useState<string | null>(null);
  return (
    <DataTable
      data={people}
      columns={columns}
      rowKey={(row) => row.id}
      toolbarSlots={{
        end: (
          <Button variant="default" onClick={() => setPanel("summary")}>
            Settings
          </Button>
        ),
      }}
      features={[
        sidePanel({
          panels: [
            { key: "summary", label: "Summary", content: <p>3 people</p> },
            { key: "help", label: "Help", content: <p>Sort any column.</p> },
          ],
          open: panel,
          onOpenChange: setPanel,
        }),
      ]}
    />
  );
}
```

`SidePanelOptions`:

| Option         | Type                            | Default | Description                                                         |
| -------------- | ------------------------------- | ------- | ------------------------------------------------------------------- |
| `panels`       | `readonly SidePanelEntry[]`     | —       | Each entry is `{ key, label, content }`.                            |
| `open`         | `string \| null`                | —       | The open panel's `key`, or `null` for closed.                       |
| `onOpenChange` | `(key: string \| null) => void` | —       | Called with a tab's key, or `null` on close.                        |
| `side`         | `"start" \| "end"`              | `"end"` | The docking edge — logical, so `"end"` is the left in an RTL table. |

With more than one panel the labels form a tab strip (`role="tablist"`): one
tab stop, arrow keys that wrap and move the selection, Home and End. Escape
closes from anywhere inside the panel. Returning focus afterwards is the
opener's job. A plugin can add panels with `host.registerPanel` — see
[host plugins](./features.md#host-plugins--setuphost).

## Export placement

`exportCsv()` from `@adapttable/<kit>/export` draws its button in the view-control
position, after Density and before Fullscreen. The button shows the kit's busy
state while a file is written and is disabled, with the reason as its title,
when the export cannot run. Scopes, writers and server-built exports are
covered in [exporting](./exporting.md).

## Notes

- **Mobile.** The toolbar is the same on phones: the view controls stay in
  place and the card layout adds the sort select. See
  [mobile cards](./mobile.md).
- **RTL.** The toolbar follows the table's `dir`, so the order above reads
  right to left. `sidePanel`'s `side` is logical.
- **Keyboard and screen readers.** Every control is a native kit button in
  the tab order. Density is announced by `labels.density`, fullscreen by
  `labels.enterFullscreen` / `labels.exitFullscreen`. Selection figures render
  in a status region, read after the range announcement. All captions are
  [labels](./i18n-rtl.md#custom-labels).
- **Headless.** Adapters render the toolbar through `ToolbarChromeProps`, the
  strip through `StatusBarChrome`, and the panel through `SidePanelChrome`, all
  from `@adapttable/react/adapter`. See [customization](./customization.md#toolbar-and-status-bar).

---

# React table command palette and context menu — commandPalette, contextMenu

▶ **See it working:** [the Feature Lab](https://adapttable.orwamahmoud.com/react/demo/all-options/) — turn **Command palette (⌘K)** and **Right-click menus** on, then press Cmd/Ctrl+K or right-click a header.

Two opt-in features put the table's actions where people look for them.
`commandPalette()` from `@adapttable/<kit>/command-palette` opens a searchable
list of table actions on Cmd/Ctrl+K. `contextMenu()` from
`@adapttable/<kit>/context-menu` opens a menu for the header, row or cell
under the pointer. Both draw with the kit's own dialog and menu components.
Omit them from `features` and nothing is bound, drawn or bundled. See
[feature composition](./features.md).

An entry in either is the same object: a `Command` is a `ContextMenuItem`. An
action written once can be offered in both.

## Example

```tsx
import { printTable } from "@adapttable/core/pdf";
import { type ColumnDef, DataTable } from "@adapttable/mantine";
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { commandPalette } from "@adapttable/mantine/command-palette";
import { contextMenu } from "@adapttable/mantine/context-menu";
import { exportCsv } from "@adapttable/mantine/export";
import { print } from "@adapttable/mantine/print";

interface Person {
  id: string;
  name: string;
  team: string;
  budget: number;
}

const people: Person[] = [
  { id: "1", name: "Amira Hassan", team: "Platform", budget: 12000 },
  { id: "2", name: "Tom Becker", team: "Design", budget: 8400 },
  { id: "3", name: "Lina Park", team: "Platform", budget: 15100 },
];

const columns: ColumnDef<Person>[] = [
  { key: "name", header: "Name", sortable: true },
  { key: "team", header: "Team", sortable: true, lockVisibility: true },
  { key: "budget", header: "Budget", sortable: true },
];

export function People() {
  return (
    <DataTable
      data={people}
      columns={columns}
      rowKey={(row) => row.id}
      features={[
        cellNavigation(),
        exportCsv(),
        print(() => printTable({ rows: people, columns })),
        commandPalette(),
        contextMenu(),
      ]}
    />
  );
}
```

Cmd/Ctrl+K lists **Print**, **Export CSV** and **Clear all**. Right-clicking
the Name header offers Sort ascending, Sort descending and Hide column; the
Team header offers only the two sorts, because it is locked against hiding.
Right-clicking a cell offers Copy. The snippets below reuse `people` and
`columns` from this example.

## Command palette

### How it works

- Cmd+K or Ctrl+K opens the palette; either modifier satisfies `mod` on every
  platform. The shortcut listens on the document, so it works wherever focus
  is on the page, text inputs included.
- The list is the built-in commands followed by yours, in registration order.
  Order does not change as you type.
- Typing filters by a case- and accent-insensitive substring of the label, so
  "resume" finds "Résumé".
- Choosing an entry closes the palette first, then runs `onSelect`.
- A disabled entry stays in the list, announced as disabled, and does not run.
- When nothing matches, the palette shows `labels.commandEmpty`
  ("No matching command").

### Built-in commands

Only the commands whose handler exists appear:

| Command   | Key             | Label (`labels.*`)         | Appears when                                                                                      |
| --------- | --------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| Print     | `print`         | `print` — "Print"          | [`print(onPrint)`](./toolbar-and-view-controls.md#print) is composed, with or without its button. |
| Export    | `export`        | `exportCsv` — "Export CSV" | [`exportCsv()`](./exporting.md) is composed. It runs the toolbar button's export.                 |
| Clear all | `clear-filters` | `clearAll` — "Clear all"   | Always; disabled while no filter is active.                                                       |

The Export entry is captioned `labels.exportCsv` whichever writer the export
uses.

### Registering commands

Pass `commands` to add entries after the built-ins:

```tsx
import { commandPalette } from "@adapttable/mantine/command-palette";

const archiveTeam = () => fetch("/api/team/archive", { method: "POST" });

<DataTable
  data={people}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    commandPalette({
      commands: [
        {
          key: "audit",
          label: "Open audit log",
          onSelect: () => window.open("/audit"),
        },
        {
          key: "archive",
          label: "Archive team",
          danger: true,
          onSelect: archiveTeam,
        },
      ],
    }),
  ]}
/>;
```

A plugin registers the same object with `host.registerCommand(command)` in its
`setup`; see [host plugins](./features.md#host-plugins--setuphost). Commands
from options and plugins are merged by `key`, so one key lists once.
A registered command lists only in a table that composes `commandPalette()`.

### The `Command` model

`Command` is `ContextMenuItem` from `@adapttable/core`:

| Field             | Type         | Description                                                             |
| ----------------- | ------------ | ----------------------------------------------------------------------- |
| `key`             | `string`     | Stable identity and React key.                                          |
| `label`           | `string`     | The caption, already localized. Search matches against it.              |
| `onSelect`        | `() => void` | Runs after the palette or menu closes.                                  |
| `disabled`        | `boolean`    | Listed and announced, but not selectable.                               |
| `danger`          | `boolean`    | Destructive; a kit may colour it (Mantine's context menu draws it red). |
| `separatorBefore` | `boolean`    | Draws a divider above the entry in a context menu.                      |

### Shortcuts

`shortcuts` replaces the key bindings. The default is `DEFAULT_SHORTCUTS`
(exported from `@adapttable/react`),
`[{ chord: "mod+k", command: "command-palette" }]`.

```tsx
commandPalette({
  shortcuts: [{ chord: "ctrl+shift+p", command: "command-palette" }],
});
```

A `Shortcut` is `{ chord, command }`. A chord is modifiers and a key joined by
`+`: `mod` matches Cmd or Ctrl, so one chord is right on macOS and elsewhere;
`ctrl`, `meta`, `alt` and `shift` are also accepted, and `alt` and `shift`
must match exactly. The key is compared case-insensitively against the
character the keyboard layout produces. A chord without `mod`, `ctrl` or
`meta` does not fire while focus is in a text input, textarea, select or
editable element.

`command-palette` is the only command key a shortcut runs. `shortcuts: []`
binds nothing; the palette still opens from a toolbar control
(`button: true`) or from your own control through `open` and
`onOpenChange`.

### Opening it from a control

`commandPalette({ button: true })` puts a **Command palette** button among the
toolbar's view controls, drawn with the kit's own button (part
`command-palette-button`, `aria-haspopup="dialog"`, `aria-expanded` while the
palette shows; unstyled and shadcn style it through
`classNames.commandPaletteButton`). The label is `labels.commandPalette`.

To open it from a control of your own, hold the state:

```tsx
import { commandPalette } from "@adapttable/mantine/command-palette";

const [paletteOpen, setPaletteOpen] = useState(false);

<Button onClick={() => setPaletteOpen(true)}>Commands</Button>
<DataTable
  {...props}
  features={[
    commandPalette({ open: paletteOpen, onOpenChange: setPaletteOpen }),
  ]}
/>;
```

`onOpenChange` is told whenever the palette asks to open or close — the
shortcut, the toolbar control, Escape, or a command having run — with or
without `open`.

### `commandPalette` options

`commandPalette(options?: boolean | CommandPaletteOptions)`:

| Option         | Type                      | Default             | Description                                    |
| -------------- | ------------------------- | ------------------- | ---------------------------------------------- |
| `commands`     | `readonly Command[]`      | `[]`                | Entries appended after the built-ins.          |
| `shortcuts`    | `readonly Shortcut[]`     | `DEFAULT_SHORTCUTS` | The chords that open the palette.              |
| `button`       | `boolean`                 | `false`             | Draw a toolbar control that opens the palette. |
| `open`         | `boolean`                 | —                   | Controlled open state.                         |
| `onOpenChange` | `(open: boolean) => void` | —                   | Told when the palette asks to open or close.   |

## Context menu

### Targets

The menu reads what was clicked from the table's `data-adapttable-part`
attributes. `ContextMenuTarget<TRow>` is one of:

| `kind`   | Shape                             | Occurs when                                                                                           |
| -------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `header` | `{ kind, columnKey }`             | The event starts inside a column header cell.                                                         |
| `cell`   | `{ kind, row, rowId, columnKey }` | The event starts inside a body cell of a rendered row.                                                |
| `row`    | `{ kind, row, rowId }`            | The event starts inside a rendered row but outside any cell — the gap between cells, a pinned spacer. |

Anywhere else — the toolbar, the footer, a mobile card — has no target, and
no menu opens.

### Built-in entries

Every kit with a `/context-menu` subpath (Mantine, MUI, Chakra UI, Ant Design,
Radix, Base UI, shadcn/ui, unstyled) wires the same handlers:

| Target        | Entry                            | Shown when                                                                         | Does                                                                        |
| ------------- | -------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `header`      | Sort ascending, Sort descending  | The column is `sortable`.                                                          | Sorts by the column; the current direction is disabled.                     |
| `header`      | Filter column                    | The column has a `filter`.                                                         | Opens the table's filter panel.                                             |
| `header`      | Hide column                      | The column is not `lockVisibility`.                                                | Hides the column.                                                           |
| `cell`, `row` | Copy                             | Always; disabled on a `row` target.                                                | Copies the cell, or the selection it sits inside.                           |
| `cell`, `row` | Cut                              | `cellNavigation()` is composed and `onCellCut` is set; disabled on a `row` target. | Copies like Copy, then calls `onCellCut(range)` once the clipboard took it. |
| `cell`, `row` | Pin to top, Pin to bottom, Unpin | `rowPinning()` is composed; each shows only where it applies.                      | Pins or unpins the row, as its row actions do.                              |

Labels are `labels.sortAscending`, `sortDescending`, `filterColumn`,
`hideColumn`, `copyCells`, `cutCells`, `pinToTop`, `pinToBottom` and
`unpinRow`. Filter column is separated from the sorts by a
divider.

With [`cellNavigation()`](./cell-navigation.md#copying-from-the-context-menu)
composed, Copy goes through the grid focus: a click inside a selected range
copies the range; anywhere else copies the clicked cell. Without it, Copy
writes the clicked cell's value. The row pin entries follow the divider after
Copy and Cut.

The model in `@adapttable/core` also defines a column Pin to start / Unpin
entry for headers (`onTogglePin`); the kits leave it unwired, and the Columns
menu owns column pinning.

When a target has no entries — every built-in unwired or locked and no custom
items — no menu renders.

### Custom items

`items(target)` returns extra entries for each target. They are appended after
the built-ins behind a divider:

```tsx
import { contextMenu } from "@adapttable/mantine/context-menu";

<DataTable
  data={people}
  columns={columns}
  rowKey={(row) => row.id}
  features={[
    contextMenu<Person>({
      items: (target) =>
        target.kind === "header"
          ? []
          : [
              {
                key: "open",
                label: `Open ${target.row.name}`,
                onSelect: () => window.open(`/people/${target.rowId}`),
              },
            ],
    }),
  ]}
/>;
```

`contextMenu<Person>` types `target.row`, so `target.row.name` checks against
`Person`.
Return `[]` for a target that needs nothing. A plugin adds a factory of the
same shape with `host.registerContextMenuItems(items)`.

`contextMenu(options?: boolean | ContextMenuOptions<TRow>)`:

| Option  | Type                                                              | Default | Description                           |
| ------- | ----------------------------------------------------------------- | ------- | ------------------------------------- |
| `items` | `(target: ContextMenuTarget<TRow>) => readonly ContextMenuItem[]` | —       | Entries appended after the built-ins. |

### Opening the menu

| Route    | Opens with                        | Positioned at                             |
| -------- | --------------------------------- | ----------------------------------------- |
| Pointer  | Right-click                       | The pointer.                              |
| Keyboard | Shift+F10, or the ContextMenu key | The bottom centre of the focused element. |
| Touch    | Press and hold for 500 ms         | The touch point.                          |

A touch that moves more than 10 px before the 500 ms elapse is a scroll, and
the press is cancelled. Mouse and pen presses never open the menu by holding.

## Notes

- **Keyboard.** In the palette, focus moves to the search input on open. The
  arrow keys move the highlighted entry (wrapping), Home and End jump to the
  ends, Enter runs it and Escape closes. Tab stays inside the dialog. Clicking
  outside closes it. Focus returns to the element that had it before the
  palette opened. The context menu is the kit's own menu primitive, which
  handles arrow keys, typeahead and Escape; closing returns focus to the
  header, row or cell it opened from.
- **Screen readers.** The palette is a dialog named `labels.commandPalette`
  ("Command palette"). Its input is a `combobox` labelled
  `labels.commandSearch` ("Search commands") that controls a `listbox` of
  `option`s, with the highlighted entry as `aria-activedescendant`, so focus
  stays in the input while the arrows move. The context menu is named
  `labels.contextMenu` ("Table actions"); disabled entries are announced
  rather than removed.
- **Mobile.** On a touch screen, press and hold opens the context menu over
  the desktop table's headers, rows and cells. The mobile card layout carries
  none of those parts, so holding a card opens nothing. The palette opens only
  from a keyboard chord.
- **RTL.** Menus position with the kit's own placement logic; shortcuts are
  unaffected by direction.
- **Fullscreen.** While [`fullscreen()`](./toolbar-and-view-controls.md#fullscreen)
  is active, the context menu portals into the fullscreen element.
- **Styling.** Class names and parts (`commandPalette`, `commandInput`,
  `commandItem`, `commandEmpty`, `contextMenu`, `contextMenuItem`,
  `contextMenuSeparator`) are listed in
  [customization](./customization.md#view-controls). Adapter authors build on
  `CommandPaletteChrome` and `ContextMenuChrome` from
  `@adapttable/react/adapter`; the pure pieces — `tableCommands`,
  `filterCommands`, `contextMenuItems`, `resolveContextTarget` — are in
  `@adapttable/core`.

---

# React table i18n & RTL — Arabic, Hebrew, 18 locales

▶ **See it working:** [flip the whole table to Arabic RTL in the live demo](https://adapttable.orwamahmoud.com/react/demo/mantine/rtl/) — a real table you can interact with, not a recording.

AdaptTable is **i18n-agnostic at its core** — it never imports an i18n
library. Strings come in through a `labels` prop, so you can use your own
stack (i18next, react-intl, …) or the ready presets in `@adapttable/i18n`.

## Complete example

`labels` translates the chrome, `dir` flips the layout, and `locale` makes
per-column `i18n` data paths resolve — three independent props, one line each:

```tsx
import { DataTable } from "@adapttable/mantine";
import { filters } from "@adapttable/mantine/filters";
import { getDirection, getLabels } from "@adapttable/i18n";

type Person = {
  id: string;
  name: string;
  nameAr: string;
  department: { name: string };
  hiredAt: string;
};

const locale = "ar";

export function People({ data }: { data: Person[] }) {
  return (
    <DataTable
      data={data}
      columns={[
        {
          key: "name",
          header: "الاسم",
          i18n: { ar: "nameAr" },
          sortable: true,
        },
        { key: "department.name", header: "القسم" },
        { key: "hiredAt", header: "تاريخ التعيين", filter: "dateRange" },
      ]}
      rowKey={(r) => r.id}
      features={[filters([])]} // runs the column `filter` declarations
      locale={locale}
      labels={getLabels(locale)} // Arabic chrome strings
      dir={getDirection(locale)} // "ar" → "rtl"
    />
  );
}
```

## Bundled presets

The label sets below ship in `@adapttable/i18n`. `getLabels` prefers an
exact tag (`"zh-TW"` → Traditional Chinese), then the primary subtag
(`"ar-EG"` → Arabic, `"de-AT"` → German), and falls back to English for
unknown locales; `hasLocale(locale)` tells you whether a preset exists.

| Preset  | Language              | Direction |
| ------- | --------------------- | --------- |
| `en`    | English               | ltr       |
| `ar`    | Arabic                | rtl       |
| `de`    | German                | ltr       |
| `es`    | Spanish               | ltr       |
| `fa`    | Persian               | rtl       |
| `fr`    | French                | ltr       |
| `he`    | Hebrew                | rtl       |
| `hi`    | Hindi                 | ltr       |
| `it`    | Italian               | ltr       |
| `ja`    | Japanese              | ltr       |
| `ko`    | Korean                | ltr       |
| `pl`    | Polish                | ltr       |
| `pt`    | Portuguese            | ltr       |
| `ru`    | Russian               | ltr       |
| `tr`    | Turkish               | ltr       |
| `ur`    | Urdu                  | rtl       |
| `zh`    | Chinese (Simplified)  | ltr       |
| `zh-TW` | Chinese (Traditional) | ltr       |

## Per-column `i18n` data paths

`ColumnDef.i18n` maps locales to alternate data paths for the column's
**value**. The table `locale` picks the path — exact tag first, then its
primary subtag, then `key`:

```tsx
// Flat fields:
{ key: "nameEn", i18n: { ar: "nameAr" } }
// Nested objects:
{ key: "name.en", i18n: { ar: "name.ar" } }
```

The cell, the client-side sort, row grouping, and the column's declarative
filter all follow the resolved path, so searching, filtering and group
headers match what the user sees. Header **text** stays whatever you pass in `header` — translate it
through your label pipeline, not `i18n`.

## RTL

RTL is first-class. Pass `dir="rtl"` (or `dir={getDirection(locale)}`) and
the adapter applies it through its direction provider and logical CSS:

- Layout, alignment, and the filter drawer side flip automatically.
- Column pinning is logical: pins use `insetInlineStart`/`insetInlineEnd`,
  so a "left" pin sticks to the correct edge in RTL too.
- With `resizableColumns()` composed, column resizing is direction-aware:
  the handle sits on the column's inline-end edge, and dragging outward (or
  pressing the leading arrow key) widens the column in both LTR and RTL.

Helpers from `@adapttable/i18n`:

- `getDirection(locale)` → `"ltr" | "rtl"`
- `isRtlLocale(locale)` — covers ar, he, fa, ur, ps, and more
- `RTL_LANGUAGES` — the raw list of RTL primary subtags
- `primarySubtag(locale)` — `"ar-EG"` → `"ar"`
- `locales` — every preset keyed by tag (`LocaleKey`); each preset is also a
  named export (`ar`, `de`, …, `zhTW` for `zh-TW`)

## Custom labels

`labels` accepts a partial `TableLabels`; missing keys fall back to the
English defaults. Count-and-range strings are functions, so any word order
works:

```tsx
<DataTable
  data={data}
  columns={columns}
  rowKey={(r) => r.id}
  labels={{
    searchPlaceholder: "Search people…",
    noResults: "Nothing matches your filters",
    showing: ({ from, to, total }) => `${from}–${to} of ${total}`,
    pageOf: ({ page, total }) => `Page ${page} of ${total}`,
    selectedCount: (count) => `${count} selected`,
  }}
/>
```

Need a language without a preset? Spread one and override:

```ts
import { en } from "@adapttable/i18n";

const sw = { ...en, search: "Tafuta", noData: "Hakuna data" };
```

---

# Accessible React data table — keyboard, screen readers, labelled controls

▶ **See it working:** [arrow through a Mantine table and read the live-region transcript](https://adapttable.orwamahmoud.com/react/demo/mantine/accessibility/) — Tab in, arrow between cells, and every announcement appears as text. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind. Keyboard walk is documented in [cell navigation](./cell-navigation.md).

An accessible data table is one a person can use without a mouse, and one a
screen reader can describe. AdaptTable ships that way. There is no
`accessible` prop to turn on.

**Related:** [Keyboard & cell navigation](./cell-navigation.md) ·
[i18n & RTL](./i18n-rtl.md) · [Browser and server-built exports](./exporting.md) ·
[FAQ](./faq.md)

## What is on by default

Every table you render already:

- uses a real `<table>` with header and body cells
- names every control it draws (Filters, checkboxes, close, Done — not icon-only)
- marks sortable headers with `aria-sort`
- states the real dataset size when only part of it is in the DOM — a virtualized or paged
  table carries `aria-rowcount` with each row's absolute `aria-rowindex`, a table whose columns
  are windowed carries `aria-colcount` with an absolute `aria-colindex` on every body and header
  cell, and the mobile
  card list carries `aria-setsize` with each card's `aria-posinset`, so a screen reader says "row
  40,001 of 50,000" instead of counting the handful of rows it can reach
- says what changed when the rows change — sorting, filtering, paging and page size
  announce politely through one live region, naming the new order or the new count in the
  same words the footer shows ("Sorted by Name, ascending", "Page 2 of 4. Showing 26–50 of
  87"), because a control that rewrites the table silently gives a screen-reader user no
  way to tell it worked
- honours `prefers-reduced-motion` when rows animate in
- honours `forced-colors: active` (Windows High Contrast) and
  `prefers-contrast: more`: focus, selection, dirty cells, validation errors
  and find-match highlights each keep an outline, not a fill or a box-shadow,
  so nothing is signaled by colour alone. Borders, pinned-column edges and
  overlays use system colors (`Canvas`, `CanvasText`, `Highlight`)

Every adapter is audited with `axe` in CI, on desktop and mobile card layouts.

## Try it yourself

On the [accessibility demo](https://adapttable.orwamahmoud.com/react/demo/mantine/accessibility/):

1. Press **Tab** until a cell shows a focus ring.
2. Press the **arrow keys**. The ring moves cell to cell.
3. Open a cell with Enter or a double-click; Escape cancels.

If Tab never enters the table or arrows do nothing, that page is failing.

Optional row reordering is keyboard-complete: Space lifts, arrows choose a
visible target, Space drops, and Escape cancels. Group and tree moves also
have a **Move to group…** / **Move under…** menu, so re-parenting never
depends on drag precision. Confirm/cancel restores focus to that menu trigger,
and a live region announces successful moves, policy rejections, sort
conflicts, and cycle guards.

Server-built exports are keyboard-complete too. Their kit-native progress
surface exposes Cancel while busy, Retry after failure, and a real download
link after `{ url }` settles. A polite region announces start, each reported
progress value, completion, failure, and cancellation; no progress report
stays indeterminate without repeatedly announcing a fake percentage.

## What this page is not

The optional spreadsheet grid — one Tab stop, arrow keys through every cell,
`role="grid"` — is a separate feature. See
[keyboard & cell navigation](./cell-navigation.md). Without the
`cellNavigation()` feature the grid extras are absent; the default table
above still stands.

## High contrast and forced colors

Windows High Contrast (and other `forced-colors: active` modes) strips the
fills and box-shadows a kit painted. AdaptTable does not ask each kit to
re-theme that itself. One stylesheet — `ForcedColorsStyle`, mounted from
every adapter — switches those marks to system colors:

| Mark        | Affordances that survive                                                               |
| ----------- | -------------------------------------------------------------------------------------- |
| Focus       | `outline` in `Highlight`, never a box-shadow                                           |
| Selection   | solid outline (also in the cell style, so it is not CSS-only)                          |
| Find match  | dashed outline; the current hit is solid                                               |
| Dirty cell  | dotted outline — `data-dirty` is never colour-only                                     |
| Validation  | double outline on `aria-invalid`                                                       |
| Pinned edge | `CanvasText` border on the pin side                                                    |
| Overlays    | find bar, command palette, saved views, side panel use `Canvas` / `CanvasText` borders |

`prefers-contrast: more` thickens the focus outline to 3px. Kits that expose
no contrast hook of their own still pick this up: the query is global.

The antd adapter keeps its sticky header. The `role="grid"` lives on the
wrapper around both of antd's tables so a screen reader walking a cell still
finds that cell's `columnheader` in the same grid.

## Notes

- Works in all eight adapters. The demo is the same walk on each kit.
- Labels you pass through `labels` are the accessible names, including in
  Arabic and the other [bundled locales](./i18n-rtl.md).

---

# Realtime React data table — live row updates, websockets

▶ **See it working:** [watch rows patch in on the Mantine demo](https://adapttable.orwamahmoud.com/react/demo/mantine/realtime/) — budgets change while you read them; sort and selection hold. The same page exists for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

A realtime table is one whose rows update as data arrives — a websocket, a
poll, another tab. AdaptTable does not open the socket. You do. When a change
lands, you patch the rows you already hold. There is no `realtime` prop.

**Related:** [Inline cell editing](./cell-editing.md) · [API](./api.md) ·
[Data tiers](./data-tiers.md)

## Apply a patch

`applyRowPatches` updates the array you pass as `data`. Untouched rows keep
their object identity, so React does not redraw the whole page, and scroll,
sort, filters and selection survive.

```tsx
import { DataTable } from "@adapttable/mantine";
import { applyRowPatches, updateRow } from "@adapttable/core";

export function People({ rows, columns, setRows }) {
  const byId = (row) => row.id;

  // Your socket / poll calls this when a row changes.
  const onMessage = (id, budget) =>
    setRows(applyRowPatches(rows, [updateRow(id, { budget })], byId));

  return <DataTable data={rows} columns={columns} rowKey={byId} />;
}
```

`insertRow`, `updateRow`, `upsertRow` and `removeRow` build the batch. A later
patch sees what an earlier one did.

## Incremental re-evaluation

Hand the array `applyRowPatches` returns back as `data` — do not spread it.
The result carries a `rowPatchLog`; `useFrontendData` continues the live
view and re-runs search, filters, sort, grouping and aggregates for the
rows the patch touched, not the whole set. A copy (`[...patched]`) drops
the log and rebuilds everything, which is how the scale bench's full-rebuild
arm is built.

```tsx
setRows(applyRowPatches(rows, [updateRow(id, { budget })], byId));
```

`createIncrementalView` / `applyRowPatchesToView` /
`applyRowPatchLogToView` are the same engine if you hold the snapshot
yourself. All eight adapters share it, including the mobile card layout.

The scale demo measures both pipelines: `?patch=200` spreads (full rebuild)
and `?patch=200&incremental=1` keeps the log. `node scripts/bench.mjs
--only patch` prints the burst times. Measured on the showcase production
build (Apple M1 Max, Chromium 151), 200 updates on 20,000 rows through the
live Mantine table take **4.9 s** as full rebuilds and **0.97 s**
incrementally (**5.0×**) — recorded in
[`scripts/bench-runs/2026-09-23.json`](https://github.com/orwa-mahmoud/adapttable/blob/main/scripts/bench-runs/2026-09-23.json).

## Live patches over WebSocket or SSE

`@adapttable/react/stream` is a separate entry, so a table that never opens
a socket never downloads one. `useRowPatchStream` binds a WebSocket or an
SSE endpoint to the rows you already own. Frames become ordinary row
patches and go back through your setter — filters, sort, grouping and
aggregates happen the way they do for any other change.

```tsx
import { useRowPatchStream } from "@adapttable/react/stream";
import { DataTable } from "@adapttable/mantine";

function LiveTable({ initial, columns }) {
  const [rows, setRows] = useState(initial);
  const stream = useRowPatchStream({
    websocket: "wss://api.example.com/rows",
    getRowId: (row) => row.id,
    onPatch: setRows,
  });

  return (
    <>
      {stream.status === "reconnecting" && <span>Reconnecting…</span>}
      <DataTable data={rows} columns={columns} rowKey={(row) => row.id} />
    </>
  );
}
```

### The wire format is the patch shape

A frame is one patch, or an array of them, as JSON — the same four shapes
`applyRowPatches` already takes:

```json
[
  { "type": "insert", "row": { "id": "9", "name": "Ada" }, "at": 0 },
  { "type": "update", "id": "3", "changes": { "status": "active" } },
  { "type": "upsert", "row": { "id": "4", "name": "Bo" } },
  { "type": "remove", "id": "7" }
]
```

A server that already speaks this needs no translation. One that speaks
something else supplies `parse`. **Nothing from the wire is trusted.** A
frame that is not JSON, an entry that is not an object, an update with no
`changes`, a remove with no id — each is dropped rather than applied. One
malformed frame cannot empty a table, and it does not take the connection
down either.

### Connection state

`status` is one of `idle`, `connecting`, `open`, `reconnecting`, `error` or
`closed`. The hook also returns `error` (the reason, or `null`) and
`close()`. `isStreamLive` and
`isStreamSettled` are the two questions worth asking:

|                |                                                            |
| -------------- | ---------------------------------------------------------- |
| `idle`         | No url, or `enabled: false`. Nothing is open.              |
| `connecting`   | Opening for the first time.                                |
| `open`         | Receiving.                                                 |
| `reconnecting` | Dropped; a retry is scheduled.                             |
| `error`        | Gave up — retries spent, or no socket in this environment. |
| `closed`       | You closed it. Final.                                      |

A dropped **WebSocket** is reopened here, after `reconnect.delayMs`
(1000 ms by default) and at most `reconnect.maxAttempts` times (unlimited
by default). An
**EventSource** reconnects on its own, so it is left to do that and simply
reported as `reconnecting` — retrying alongside it would give the server
two subscriptions for one table.

```tsx
useRowPatchStream({
  eventSource: "https://api.example.com/rows/stream",
  event: "patch", // defaults to "message"
  getRowId: (row) => row.id,
  onPatch: setRows,
});
```

An authenticated connection, a wrapper, or a test double is
`createWebSocket` / `createEventSource`; `protocols` passes WebSocket
subprotocols. `onPatches` receives each frame's parsed patches before they
are applied. `parseRowPatchFrame` is the default parser, exported for reuse
in a custom `parse`. `openRowPatchStream` from `@adapttable/core/stream` is
the same connector without React — frames in, status out.

`enabled: false` keeps everything idle — nothing is opened, nothing retries.
The table never owns your rows. `onPatch` hands you an updater, so it drops
straight into a `useState` setter and never races a concurrent update.

## Flash the cells that moved

A number that quietly becomes a different number is a number nobody
notices. `useChangedCellFlash` from the same `/stream` entry tracks the
cells a patch changed and answers `isCellFlashing(rowId, columnKey)`. Pass
that into the table; kits set `data-flash` on the cell and on the matching
card value, and your stylesheet decides what the pulse looks like — the
same seam `data-dirty` already uses.

It is off by default. `prefers-reduced-motion` is a hard opt-out of the
pulse (unlike `useHighlight`, which still marks the row and holds it
steady). An update is diffed, so a field sent back unchanged stays dark.
An insert marks the whole row; a remove has no cells left to mark.
`durationMs` sets how long a cell stays marked (1200 ms by default). The
result also offers `isRowFlashing(rowId)`, `flashProps(rowId, columnKey)`
for custom cells, and `clear()`.

```tsx
import {
  useChangedCellFlash,
  useRowPatchStream,
} from "@adapttable/react/stream";
import { rowPatchLog } from "@adapttable/core";
import { DataTable } from "@adapttable/mantine";

function LiveTable({ initial, columns }) {
  const [rows, setRows] = useState(initial);
  const flash = useChangedCellFlash({ enabled: true });
  useRowPatchStream({
    websocket: "wss://api.example.com/rows",
    getRowId: (row) => row.id,
    onPatch: (update) => {
      setRows((prev) => {
        const next = update(prev);
        const log = rowPatchLog(next);
        if (log) flash.mark(log.events);
        return next;
      });
    },
  });

  return (
    <DataTable
      data={rows}
      columns={columns}
      rowKey={(row) => row.id}
      isCellFlashing={flash.isFlashing}
    />
  );
}
```

## What this page is not

A websocket that changes the row **under an open editor** is a conflict, not
this page. That lives under [cell editing](./cell-editing.md#live-update-conflicts).

## Notes

- Works in all eight adapters. The demo is the same feed on each kit.
- The table never owns your data. A patch is a new array you hand back.
- [API reference](./api.md) lists `applyRowPatches`, `applyRowPatchesWithLog`
  and the patch shapes.

---

# AdaptTable API reference — DataTable, columns, hooks

The complete public surface. Every symbol ships full TypeScript types and
JSDoc, so editor autocomplete mirrors everything below.

## `<DataTable>` props

Every adapter (`@adapttable/mantine`, `mui`, `chakra`, `antd`, `radix`, `base-ui`, `shadcn`, `unstyled`)
exports `DataTable<TRow>`. The props below are the shared core surface
(`BaseDataTableProps`); kit-specific extras follow in
[Adapter extras](#adapter-extras).

### Data

| Prop             | Type                                                   | Default  | Description                                                                                                                                                                 |
| ---------------- | ------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`         | `TableSource<TRow>`                                    | —        | Data + state contract from `useFrontendData` / `useQuerySource`; adapters make it optional when you pass `data` instead.                                                    |
| `rowKey`         | `(row: TRow) => string`                                | —        | Stable React key extractor for a row (required).                                                                                                                            |
| `features`       | `readonly TableFeature<TRow>[]`                        | —        | Compose opt-in features from `@adapttable/<kit>/<feature>` subpaths. The import is the switch, and the only way to arm a feature. See [feature composition](./features.md). |
| `defaults`       | `Partial<TableQueryParams> & { extra?: ExtraFilters }` | —        | Initial state applied while the URL is silent about a key (e.g. `{ limit: 10, sortBy: "name" }`); the user's changes and explicit URL params win.                           |
| `paginationMode` | `PaginationMode`                                       | `"auto"` | `"paged"`, `"infinite"`, or `"auto"` (mobile resolves to infinite, desktop to paged). `virtualize()` applies in infinite mode.                                              |

Feature factory options are not `DataTable` props. For example, compose
`columnMenu()`, `filters(defs)`, `editing(save)` or `virtualize()` in
`features`; each feature page documents its options.

### Interactive row grouping

Each kit exports `groupingPanel` from
`@adapttable/<kit>/grouping-panel`:

```tsx
import { groupingPanel } from "@adapttable/mantine/grouping-panel";

groupingPanel();
groupingPanel(["team", "status"], extras);
```

`groupingPanel(groupBy?, extras?)` owns the ordinary grouping row model,
group-header renderers, and the kit-native panel. The optional first argument
is a column key or ordered list; the second is `GroupingExtras<TRow>`. Use
plain `grouping(groupBy)` only for code-fixed grouping with no interactive panel.
When `columnMenu()` is also composed, its menu model adds Group by/Ungroup and
per-column aggregation choices.

### Columns & layout

| Prop                    | Type                                  | Default | Description                                                                                                                    |
| ----------------------- | ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `columns`               | `ColumnInput<TRow>[]`                 | —       | Leaf `ColumnDef`s and optional `ColumnGroupDef` parents — see [ColumnDef](#columndef) and [column groups](./column-groups.md). |
| `columnLayout`          | `ColumnLayoutState`                   | —       | Controlled column layout (hidden/order/pinned/widths).                                                                         |
| `onColumnLayoutChange`  | `(next: ColumnLayoutState) => void`   | —       | Change handler for the controlled column layout.                                                                               |
| `defaultColumnLayout`   | `Partial<ColumnLayoutState>`          | —       | Initial column layout for the uncontrolled mode.                                                                               |
| `onColumnRename`        | `(key: string, name: string) => void` | —       | Host persistence channel for a `renameable` column's accepted display name; stable keys never change.                          |
| `maxHeight`             | `number`                              | —       | Fixed-height scroll box (px) enabling sideways scrolling + column pinning; omit for page scroll.                               |
| `sortByOptions`         | `SortByOption[]`                      | —       | Options for a mobile sort-by select.                                                                                           |
| `mobileIdentityColumns` | `number`                              | —       | Deprecated and ignored; removed in v4. `hideOnMobile` decides which fields a card shows.                                       |

### Filters & search

| Prop                        | Type                                | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------- | ----------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filtersMode`               | `"popover" \| "drawer" \| "header"` | `"popover"` | Container for a composed `filters()` feature. Popover: anchored card, no backdrop. Drawer: panel + backdrop. Header: per-column icons; hides the Filters button unless the AND/OR tree is on (`toolbarShowsFilters`).                                                                                                                                                                                                                                                                                      |
| `closeHeaderFilterOnSelect` | `boolean`                           | `false`     | Close a header-filter overlay after a finished single-control write (a select/boolean value, or a valueless operator such as "Is empty"). Off by default — picking an operator on a field that still has a value input does not dismiss. Outside click and Escape always close. `useHeaderFilterOverlay` / `bindHeaderFilterDismiss` / `headerFilterFieldIsComplete` / `usePointerDismiss` / `HeaderFilterSessionProps` / `HeaderFilterOpenProvider` / `HeaderFilterOpenContext` / `HeaderFilterOpenHost`. |
| `filterLabels`              | `Record<string, ChipLabelResolver>` | —           | Per-filter-key chip label resolvers. Declarative `filters()` definitions derive them automatically; needed only for hand-drawn JSX filters (or to override a derived label).                                                                                                                                                                                                                                                                                                                               |
| `extraChips`                | `ActiveFilterChip[]`                | —           | Extra chips driven by non-URL state, merged with the derived chips.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `activeFilterCount`         | `number`                            | chip count  | Override the active-filter count badge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `onClearFilters`            | `() => void`                        | —           | Clear-filters handler used by the panel + chip strip (built-in `clearExtras` fallback otherwise).                                                                                                                                                                                                                                                                                                                                                                                                          |
| `searchable`                | `boolean`                           | `true`      | Render the built-in search box; pass `false` to hide it.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `searchPlaceholder`         | `string`                            | —           | Placeholder for the search input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `searchDebounceMs`          | `number`                            | `300`       | Debounce in ms for committing the search input to the source.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `filterDefs`                | `readonly FilterDef<TRow>[]`        | —           | Resolved filter definitions used to label AND/OR tree chips. The shell sets this from `filters()`; hosts calling `useTableChrome` directly pass the same defs.                                                                                                                                                                                                                                                                                                                                             |
| `filterRegistry`            | `FilterTypeRegistry`                | —           | Type registry those defs were built against.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `filterFields`              | `boolean`                           | `true`      | Mount the per-field Filters form; `false` keeps only the AND/OR tree in that chrome.                                                                                                                                                                                                                                                                                                                                                                                                                       |

### Selection & actions

| Prop                | Type                              | Default          | Description                                                                                                                                                                                                               |
| ------------------- | --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rowActionsLayout`  | `RowActionsLayout`                | `"buttons"`      | How the trailing actions column renders. Omit or `"buttons"` keeps today's horizontal strip. `"menu"` collapses visible actions into a 3-dot menu using each kit's own Menu. Ignored when `renderRowActions` is set.      |
| `renderRowActions`  | `RowActionsRenderer<TRow>`        | —                | Replace the trailing actions cell (desktop and mobile cards). Receives the resolved action list (host + built-in duplicate / delete / pin). The column still only appears when there are row actions or row-mode editing. |
| `selectionGetId`    | `(row: TRow) => string`           | `rowKey`         | Selection id extractor when it must differ from `rowKey`.                                                                                                                                                                 |
| `selectedIds`       | `readonly string[]`               | —                | Controlled selection; apply `onSelectionChange` requests to your own state.                                                                                                                                               |
| `onSelectionChange` | `(selectedIds: string[]) => void` | —                | Selection observer (uncontrolled) or change-request handler (controlled).                                                                                                                                                 |
| `confirm`           | `ConfirmHandler`                  | `window.confirm` | Confirmation handler for actions that declare a `confirm` block. Where no dialog exists (SSR, some webviews), the default DENIES the action and dev-warns — pass your own handler for dialogless environments.            |

### Appearance & chrome

| Prop                        | Type                                                            | Default         | Description                                                                                                                                                                                                                       |
| --------------------------- | --------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tableLabel`                | `string`                                                        | —               | Accessible label for the table.                                                                                                                                                                                                   |
| `labels`                    | `TableLabels`                                                   | English         | Pre-translated label overrides; missing keys fall back to English defaults.                                                                                                                                                       |
| `dir`                       | `"ltr" \| "rtl"`                                                | `"ltr"`         | Text direction.                                                                                                                                                                                                                   |
| `locale`                    | `string`                                                        | —               | Active locale tag (e.g. `"ar"`, `"ar-EG"`) driving per-column `i18n` data-path resolution.                                                                                                                                        |
| `density`                   | `"comfortable" \| "compact"`                                    | `"comfortable"` | Row density; each adapter maps it to its kit's table size. With `densityChooser()` composed, omit this to let the feature own uncontrolled state; pass it to control density and pair with `onDensityChange` to observe requests. |
| `onDensityChange`           | `(next: "comfortable" \| "compact") => void`                    | —               | Called when the user picks a density.                                                                                                                                                                                             |
| `renderCard`                | `(row, card) => ReactNode`                                      | —               | Replace a mobile card's body; the shell keeps selection, actions and expansion. See [mobile](./mobile.md).                                                                                                                        |
| `mobileBreakpoint`          | `number`                                                        | `768`           | Width (px) at or below which the card layout takes over and `paginationMode="auto"` scrolls. See [mobile](./mobile.md).                                                                                                           |
| `forceMobile`               | `boolean`                                                       | viewport        | Force the mobile layout instead of resolving from the viewport.                                                                                                                                                                   |
| `toolbar`                   | `ReactNode`                                                     | —               | Inline toolbar slot for custom controls (view toggles, etc.).                                                                                                                                                                     |
| `toolbarSlots`              | `ToolbarSlots`                                                  | —               | Toolbar end regions: `start` (ahead of everything) and `end` (after everything). `toolbar` stays the middle region.                                                                                                               |
| `skeletonRows`              | `number`                                                        | page size       | Number of skeleton rows while loading.                                                                                                                                                                                            |
| `stickyHeader`              | `boolean`                                                       | `false`         | Keep the desktop table header sticky while scrolling.                                                                                                                                                                             |
| `stickyToolbar`             | `boolean`                                                       | `stickyHeader`  | Keep search and page-size pinned with the header on page-scroll tables. Pass `false` to let the toolbar scroll away.                                                                                                              |
| `stickyTop`                 | `number`                                                        | `0`             | Inset in px for the sticky header (and the sticky toolbar) so they clear an app bar.                                                                                                                                              |
| `scrollToTopOnChange`       | `boolean`                                                       | `true`          | Scroll back to the table when search/filter/page changes.                                                                                                                                                                         |
| `scrollTopGap`              | `number`                                                        | `8`             | Extra gap below sticky chrome when scrolling back.                                                                                                                                                                                |
| `isCellFlashing`            | `(rowId: string, columnKey: string) => boolean`                 | —               | Mark cells a patch just changed (`data-flash` on the cell and on the matching card value). Pair with `useChangedCellFlash` from `@adapttable/react/stream`. Omit and nothing is marked. See [realtime](./realtime.md).            |
| `onEditStart`               | `EditEventHandler<TRow>`                                        | —               | Observe an editor opening (cell, row or batch). Cannot change the outcome.                                                                                                                                                        |
| `onEditCancel`              | `EditEventHandler<TRow>`                                        | —               | Observe a cancel. Not fired when a successful commit merely closes the editor.                                                                                                                                                    |
| `onEditCommit`              | `EditEventHandler<TRow>`                                        | —               | Observe a value reaching the host, after parse and validation.                                                                                                                                                                    |
| `onValidationFail`          | `EditEventHandler<TRow>`                                        | —               | Observe a validator refusing a value; the editor stays open.                                                                                                                                                                      |
| `onEditError`               | `EditEventHandler<TRow>`                                        | —               | Observe a save promise rejecting.                                                                                                                                                                                                 |
| `onEditConflict`            | `EditConflictHandler<TRow>`                                     | —               | A row changed under an open editor. Return `"keep"` or `"take"`; omit and `editConflictPolicy` decides.                                                                                                                           |
| `editConflictPolicy`        | `"keep" \| "take" \| "ask"`                                     | `"ask"`         | What to do when the host does not choose. `"ask"` surfaces Keep mine / Take theirs.                                                                                                                                               |
| `rowVersion`                | `(row: TRow) => string \| number`                               | —               | Host version of a row. Any change under an open editor is a conflict, not only the edited column.                                                                                                                                 |
| `validateRow`               | `RowValidator<TRow>`                                            | —               | Gate a commit on a row-level rule. Receives the row the edit would produce; return a message, a column key → message map, or nothing. May be async.                                                                               |
| `applyEdit`                 | `(row: TRow, columnKey: string, value: unknown) => TRow`        | shallow spread  | How an edit is applied to a row for `validateRow` to judge; pass it when a column reads a nested path.                                                                                                                            |
| `onEditRollback`            | `(previous: TRow, columnKey: string) => void`                   | —               | Put a row back after a rejected save. Without it the cell is marked failed and the value stays.                                                                                                                                   |
| `formatEditError`           | `(error: unknown) => string`                                    | —               | Turn a rejected save into the sentence its cell shows.                                                                                                                                                                            |
| `onCellPaste`               | `(edits: CellEdit<TRow>[]) => void`                             | —               | Ctrl/Cmd+V with the clipboard parsed into cell edits. Requires `cellNavigation()`. Omit it and each edit goes through the composed `editing()` handler.                                                                           |
| `onCellFill`                | `(edits: CellEdit<TRow>[]) => void`                             | —               | Fill handle drag or Ctrl/Cmd+D. Requires `cellNavigation()`. Same contract as `onCellPaste`.                                                                                                                                      |
| `onCellCut`                 | `(range: CellRange) => void`                                    | —               | Ctrl/Cmd+X, after the clipboard accepted the copy. Requires `cellNavigation()`. The table clears nothing itself.                                                                                                                  |
| `summaryRow`                | `(rows: readonly TRow[]) => Partial<Record<string, ReactNode>>` | —               | Map the current page's rows to per-column footer summary cells.                                                                                                                                                                   |
| `tableFooter`               | `ReactNode`                                                     | —               | Free slot under the table, above the pager. Not the column-aligned summary row.                                                                                                                                                   |
| `onGroupByChange`           | `(groupBy: readonly string[]) => void`                          | —               | Notified after a grouping change, with the keys as a list. The chrome always applies the change itself; take full control via `source.setGroupBy`.                                                                                |
| `groupAggregates`           | `(rows: readonly TRow[]) => Partial<Record<string, ReactNode>>` | —               | Per-group aggregate cells — **same signature as `summaryRow`**. Called with each group's leaf rows.                                                                                                                               |
| `collapsedGroupIds`         | `readonly string[]`                                             | —               | Controlled collapsed group keys (ephemeral — not URL-synced).                                                                                                                                                                     |
| `onCollapsedGroupIdsChange` | `(ids: string[]) => void`                                       | —               | Controlled collapse channel; uncontrolled mode uses internal state.                                                                                                                                                               |
| `groupSort`                 | `GroupSort<TRow>`                                               | source order    | Order groups within their parent: `"label"`, `"label-desc"`, `"count"`, `"count-desc"`, or a comparator.                                                                                                                          |
| `groupFilter`               | `(group: GroupNode<TRow>) => boolean`                           | —               | Keep only the groups this answers true for, at every level. Row filters run first.                                                                                                                                                |
| `groupFooters`              | `boolean`                                                       | —               | Close every group with a footer row carrying its aggregates. Needs `groupAggregates`.                                                                                                                                             |
| `groupPageSize`             | `number`                                                        | —               | Show at most this many top-level groups at a time, with a row offering the rest.                                                                                                                                                  |
| `groupRowPageSize`          | `number`                                                        | —               | Show at most this many rows inside each group, with a "load more in this group" row.                                                                                                                                              |
| `onGroupLoadMore`           | `(groupKey: string) => void`                                    | —               | Called when a reader asks for more rows inside a group. The table reveals what it already holds either way.                                                                                                                       |
| `hasChildren`               | `(row: TRow) => boolean`                                        | —               | Whether a row has children not fetched yet (server trees).                                                                                                                                                                        |
| `expandedIds`               | `readonly string[]`                                             | —               | Controlled tree expansion: the ids currently open.                                                                                                                                                                                |
| `onExpandedIdsChange`       | `(ids: string[]) => void`                                       | —               | Fired after the table opens or closes a node.                                                                                                                                                                                     |

### Virtualization

| Prop                  | Type     | Default | Description                                                    |
| --------------------- | -------- | ------- | -------------------------------------------------------------- |
| `estimateRowSize`     | `number` | `56`    | Desktop row-size estimate in px.                               |
| `estimateCardSize`    | `number` | `132`   | Mobile card-size estimate in px.                               |
| `virtualOverscan`     | `number` | `8`     | Extra rows/cards rendered before and after the virtual window. |
| `virtualScrollMargin` | `number` | —       | Override for the measured window-mode list offset.             |

### URL & persistence

URL props (`urlSync`, `urlKey`, `urlAdapter`) and the `data` /
`onQueryChange` tiers live on the adapter components, not the core prop
surface — see [Adapter extras](#adapter-extras) and
[URL-synced state](./url-state.md). The two tiers are typed as `DataModeProps`,
and the server one's callback is `TableQueryHandler`: the consolidated query
plus the `AbortSignal` for the request it starts.

### Callbacks

| Prop           | Type                              | Default | Description                                                                                        |
| -------------- | --------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `onRowClick`   | `(row: TRow) => void`             | —       | Row activation on click/Enter; interactive children (actions, checkboxes, links) never trigger it. |
| `onRowsChange` | `(rows: readonly TRow[]) => void` | —       | Called whenever the materialized source rows change.                                               |
| `prefetch`     | `(row: TRow) => void`             | —       | Hover-prefetch callback fired on desktop row mouse-enter.                                          |

## Feature composition

`features={[rowReorder(fn, options)]}` from `@adapttable/<kit>/row-reorder` (or
the `@adapttable/<kit>/features` barrel, or `@adapttable/react/features`). The
import is the switch, and it is the only way in — see
[feature composition](./features.md) and, for a v2 table,
[upgrading from v2](./migrate-from-v2.md).

Types: `TableFeature` · `TableFeatureHost` · `FeaturePatch` ·
`FeatureApplyInput`. The merge is `applyTableFeatures`. Live registration is
`setup(host)` on the same `TableFeature`: `registerFilterType`,
`extendFilterType`, `registerEditor`, `registerAggregator`, `registerWriter`,
`registerColumnMenuAction`, `registerPanel`, `registerCommand`,
`registerContextMenuItems`, `onDispose`. Adapters run this through
`useTableFeatures`. The host belongs to that table: `featureHostOf` /
`rememberFeatureHost` thread it into chrome, `FeatureHostProvider` /
`useFeatureHost` hand it to hooks in the tree, and `bindFeatureHostFn`
scopes a mapper (summary, group aggregates) to the table that invoked it.
`RowOf<P>` derives the row type from a wrapper's `rowKey` prop so adapter
feature hosts retain the consumer's row contract.

A feature whose behaviour is a hook carries a `provider` instead —
`FeatureProviderContribution`, whose component receives
`FeatureProviderProps` and wraps the table. `FeatureProviders` nests them in
feature-id order. It publishes through `FeatureStateScope` under a
`FeatureStateKey` from `featureStateKey`, and anything below reads it with
`useFeatureState`. A provider sits above the chrome, so it reads the live rows
and labels through `useTableRuntime` (`TableRuntime`, `TableRuntimeView`) rather than being handed
them (`featureIds()`, optional `query` for page/search/sort); chrome offers them with `usePublishTableRuntime`. A feature also fills
named positions: `renders` is a list of `FeatureRender` entries, each pairing a
`FeatureSlotKey` from `featureSlotKey` with what to draw — built with
`slotRender`, which keeps the props typed — chrome asks through `FeatureSlot`,
and the positions themselves are named constants: `STATUS_BAR` (the footer
strip, filled by `statusBar` or `selectionStats` from
`@adapttable/<kit>/status-bar` — a single slot, so the pair share one element
and it draws once), `FIND_BAR` (`findInTable` from
`@adapttable/<kit>/find-in-table`), `BATCH_EDIT_BAR` (`batchEditing` from
`@adapttable/<kit>/batch-editing`), `COMMAND_PALETTE` (`commandPalette` from
`@adapttable/<kit>/command-palette`), `CONTEXT_MENU` (`contextMenu` from
`@adapttable/<kit>/context-menu`), `SIDE_PANEL` (`sidePanel` from
`@adapttable/<kit>/side-panel`), `COLUMN_MENU` (`columnMenu` from
`@adapttable/<kit>/column-menu`), `BULK_BAR` (`bulkActions` from
`@adapttable/<kit>/bulk-actions`), and `ACTIVE_FILTER_CHIPS` plus
`FILTERS_FORM` (`filters` from `@adapttable/<kit>/filters` — one feature
fills both the chip strip and the panel body). And
`useFeatureSlotFilled` says whether anyone answered. All from
`@adapttable/react/adapter`; see [feature composition](./features.md).

Column-name controls stay kit-owned through `ColumnMenuSlotProps.onRenameColumn`
and the optional `COLUMN_HEADER_RENAME` render slot
(`ColumnHeaderRenameSlotProps`).
`useColumnRenameEditor` (`UseColumnRenameEditorOptions` in,
`ColumnRenameEditorState` out) centralizes trim/validation, Escape cancellation,
focus restoration and the commit announcement without drawing an input in core.
`SharedTableRenderProps.onRenameColumn` carries the same commit channel to
semantic-table header controls; Ant Design intentionally uses the menu path.

Adapter authors bind those slots without copying feature lifecycle through
`createAdapterEditingFeatures`, `createAdapterFiltersFeature`,
`createAdapterGroupingFeature`, `createAdapterRowDetailFeatures`,
`createAdapterRowReorderFeature`, `createAdapterContextMenuFeature`,
`createAdapterCommandPaletteFeature` and
`createAdapterAgentApprovalFeature`. Each accepts kit-owned
`AdapterFeatureComponent`s and returns ordinary feature factories. Their
contracts are `AdapterEditingComponents` — whose `EditableCell` is handed
`EditableCellRenderProps`, the slot's props with the display already worked
out from the row, the column's `Cell` or its accessor, so no kit repeats that
rule — `AdapterEditingFeatures`,
`AdapterFiltersComponents`, `AdapterFiltersFeature`,
`AdapterGroupingComponents`, `AdapterGroupingFeature`,
`AdapterRowDetailComponents`, `AdapterRowDetailFeatures`,
`AdapterRowReorderComponents`, `AdapterRowReorderFeature`,
`AdapterContextMenuFeature` and `AdapterCommandPaletteFeature`, with
`AdapterCommandPaletteTriggerProps` for the palette's optional toolbar trigger
(`createAdapterCommandPaletteFeature(CommandPalette, Trigger)`, drawn for
`commandPalette({ button: true })`); normalized
`AdapterContextMenuProps` / `AdapterCommandPaletteProps` types keep the seam
typed. `createAdapterStandardFeatures` takes
`AdapterStandardFeatureFactories` and returns a `StandardFeaturesFactory`
using `StandardFeatureOptions`; individual feature imports remain independent.
`ContextMenuLiveGate` and `OptionalSidePanel` are the two invariant root-layout
helpers. None imports a kit or belongs on the app-facing core entry.

Chrome asks for the rest of a kit's parts the same way, one slot per part.
Around a cell: `EDITABLE_CELL` (`EditableCellSlotProps`, the editor and the
dirty mark), `FILL_HANDLE` (`FillHandleCellSlotProps`), `EXPAND_TOGGLE`
(`ExpandToggleSlotProps`), `TREE_CELL` and `TREE_TOGGLE`, `COLUMN_SELECT`,
`COLUMN_GROUP_TOGGLE` and `FILTER_HEADER`. Around a row: `ROW_EDIT_ACTIONS`,
`ROW_REORDER_HANDLE`, `ROW_REORDER_BUTTONS` and `ROW_REORDER_ANNOUNCER`,
`GROUP_HEADER_ROW` (`GroupHeaderRowSlotProps`) and its mobile card
`GROUP_HEADER_CARD` (`GroupHeaderCardSlotProps`). Around the table:
`TOOLBAR_EXTRAS` (`ToolbarExtrasSlotProps` — undo/redo, export, print,
density, fullscreen), `SAVED_VIEWS` (`SavedViewsSlotProps`),
`GRID_FOCUS_ANNOUNCER`, the filter surfaces `FILTER_POPOVER` / `FILTER_DRAWER`
(`FilterOverlaySlotProps`) with `FiltersFormSlotProps` and
`ActiveFilterChipsSlotProps`, and `CHROME_BODY` (`ChromeBodySlotProps`), which
`virtualize` fills with the windowed body a plain table never downloads —
`ChromeBodyGate` is what asks for it, falling back to the plain body. A kit
that assembles its own table body — antd renders through its own `<Table>` —
asks `KEYED_WINDOW` (`KeyedWindowSlotProps`) for a window over a keyed list
instead, so the virtualizer stays behind the same import there too. The window
it gets back is a `KeyedWindow`, whose `scrollToIndex` brings one entry into
view. Find reaches a match outside the window through `RowScrollContext`: the
`virtualize` body provides it, and a kit that renders its own body provides it
above its find stage with a scroll for its own window.
A kit dresses a core feature with its own parts through `extendFeature`.
The heavy pieces of body assembly a feature can replace — cell spanning, extra
rows, the resize handle — are typed as `AssemblyFns`, and `virtualize` takes
`VirtualizeOptions`.

A feature whose behaviour is a hook rather than a component fills a **live**
slot instead: the hook mounts inside the table and hands its state back down,
so a table that never imported the feature never carries it. Chrome-shaped
state arrives through `ChromeExtrasGate` (`ChromeExtraSlotProps`) —
`COLUMN_LAYOUT_LIVE`, `FILTER_CHIPS_LIVE`, `GROUPING_LIVE`, `TREE_LIVE`,
`SELECTION_LIVE`, `ROW_ACTIONS_LIVE`, `PINNING_LIVE`, `EXPANSION_LIVE` and
`EDITING_LIVE` — and interaction state through `HistoryLiveGate`
(`EDIT_HISTORY_LIVE`, `EditHistoryLiveSlotProps`) and `ShellLiveGate`:
`FIND_LIVE` (`FindLiveSlotProps`), `CELL_NAV_LIVE` (`CellNavLiveSlotProps`),
`EXPORT_LIVE` (`ExportLiveSlotProps`), `FULLSCREEN_LIVE`
(`FullscreenLiveSlotProps`), `SELECTION_STATS_LIVE`
(`SelectionStatsLiveSlotProps`), `COMMAND_PALETTE_LIVE` and
`CONTEXT_MENU_LIVE` (`ContextMenuLiveSlotProps`). An unfilled live slot passes
an inert stand-in through, so the same chrome renders either way.

Factories: `feature` (ad-hoc) · `rowReorder` · `rowPinning` · `cellSpan` ·
`extraRows` · `rowAppearance` · `rowDetail` · `nestedTable` · `editing` ·
`rowEditing` · `batchEditing` · `editHistory` · `dirtyIndicators` ·
`grouping` · `tree` · `virtualize` · `columnMenu` · `resizableColumns` ·
`collapsibleColumnGroups` · `exportCsv` · `cellNavigation` · `findInTable` ·
`fullscreen` · `commandPalette` · `contextMenu` · `sidePanel` · `bulkActions` ·
`filters` · `filterTypes` · `headerFilters` · `savedViews` · `selectionStats` ·
`densityChooser` · `print` · `statusBar` · `undoRedoButtons` · `multiSort` ·
`fitColumns` · `columnSelectionCheckbox` · `rowActions` · `pinnedSummaryRows` ·
`groupingPanel`.

Kit `/pivot` re-exports `PivotPanel` plus the `@adapttable/core/pivot` engine.

## ColumnDef

| Prop                 | Type                                                                                 | Default       | Description                                                                                                                                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `key`                | `string`                                                                             | —             | Unique id (required); also the backend `sortBy` value and — absent `accessor`/`Cell` — the row's dot-path for the cell value.                                                                                                                                            |
| `header`             | `ReactNode`                                                                          | humanized key | Header content; omit it and the header derives from `key` (`"hiredAt"` → "Hired At").                                                                                                                                                                                    |
| `renderHeader`       | `(ctx: ColumnHeaderContext<TRow>) => ReactNode`                                      | —             | Replace the header caption. The cell still owns sort, resize and the menu; `ctx.controller` exposes them.                                                                                                                                                                |
| `renderFooter`       | `(ctx: ColumnFooterContext<TRow>) => ReactNode`                                      | —             | Replace one summary-row cell. `value` is the `summaryRow` result for this key.                                                                                                                                                                                           |
| `headerTooltip`      | `string`                                                                             | —             | Native tooltip on the header caption.                                                                                                                                                                                                                                    |
| `renameable`         | `boolean`                                                                            | `false`       | Offer the kit-native Rename column action when the table also has `onColumnRename`.                                                                                                                                                                                      |
| `headerActions`      | `ReactNode`                                                                          | —             | Host controls after the caption, before the resize handle.                                                                                                                                                                                                               |
| `group`              | `string \| readonly string[]`                                                        | —             | Presentational header group shortcut. A string is one level; a path stacks rows. Contiguous same-path columns merge; a reorder splits the group. Prefer a `ColumnGroupDef` with `children` when the group has collapse options. See [column groups](./column-groups.md). |
| `groupShow`          | `ColumnGroupShow` (`"open" \| "closed" \| "always"`)                                 | `"open"`      | When this leaf sits under a collapsible group: expanded only, collapsed only, or both.                                                                                                                                                                                   |
| `i18n`               | `Record<string, string>`                                                             | —             | Per-locale data paths for the column's value (`{ key: "nameEn", i18n: { ar: "nameAr" } }`); cell, client-side sort and filter follow the resolved path.                                                                                                                  |
| `filter`             | `ColumnFilter<TRow>`                                                                 | —             | Declarative filter for this column: a bare type (`"dateRange"`) or a definition without `key`/`label`.                                                                                                                                                                   |
| `Cell`               | `ComponentType<CellProps<TRow>>`                                                     | —             | Component rendered per row (receives `{ row, rowIndex }`); define at module level so its identity is stable.                                                                                                                                                             |
| `accessor`           | `(row: TRow) => ReactNode`                                                           | —             | Lightweight alternative to `Cell`; returns cell content.                                                                                                                                                                                                                 |
| `sortValue`          | `(row: TRow) => SortableValue`                                                       | —             | Primitive extractor used by the client-side sort comparator; unused for server-sorted data.                                                                                                                                                                              |
| `exportValue`        | `(row: TRow) => unknown`                                                             | —             | Value written to a CSV export when the file should carry something other than the formatted cell (a number rather than `"$1,240.00"`).                                                                                                                                   |
| `formatValue`        | `(row: TRow) => string`                                                              | derived       | The cell as plain text, for contexts that cannot render JSX — screen-reader announcements, `aria-label`, tooltips, the clipboard.                                                                                                                                        |
| `parseValue`         | `(draft: string, row: TRow) => unknown`                                              | —             | Turns an edited draft into the value committed by `editing()`. See [cell editing](./cell-editing.md).                                                                                                                                                                    |
| `sortable`           | `boolean`                                                                            | `false`       | Enable sorting for this column.                                                                                                                                                                                                                                          |
| `colSpan`            | `number \| ((row: TRow) => number)`                                                  | `1`           | Columns this cell covers. Covered neighbours are omitted. See [row and column spanning](./row-spanning.md).                                                                                                                                                              |
| `rowSpan`            | `number \| ((row: TRow) => number)`                                                  | `1`           | Rows this cell covers. Stays inside one tbody.                                                                                                                                                                                                                           |
| `width`              | `number \| string`                                                                   | —             | Column width passed through to the rendered header/cell.                                                                                                                                                                                                                 |
| `minWidth`           | `number`                                                                             | —             | Floor for this column's width, in pixels.                                                                                                                                                                                                                                |
| `maxWidth`           | `number`                                                                             | —             | Ceiling for this column's width, in pixels.                                                                                                                                                                                                                              |
| `flex`               | `number`                                                                             | —             | This column's share of leftover width when the table fits its container (`fitColumns()`).                                                                                                                                                                                |
| `responsivePriority` | `number`                                                                             | —             | How readily this column is given up when the table is too narrow. Priority 1 is kept longest; omitting it means never dropped. See [mobile](./mobile.md).                                                                                                                |
| `align`              | `"start" \| "center" \| "end"`                                                       | `"start"`     | Text alignment within the cell.                                                                                                                                                                                                                                          |
| `mobileLabel`        | `string`                                                                             | `header`      | Label used on mobile card layouts; falls back to a string `header`.                                                                                                                                                                                                      |
| `hideOnMobile`       | `boolean`                                                                            | `false`       | Hide this column entirely on mobile layouts.                                                                                                                                                                                                                             |
| `hideOnDesktop`      | `boolean`                                                                            | `false`       | Hide this column entirely on desktop layouts.                                                                                                                                                                                                                            |
| `lockPosition`       | `boolean`                                                                            | `false`       | Gray out the column menu's reorder grip.                                                                                                                                                                                                                                 |
| `lockVisibility`     | `boolean`                                                                            | `false`       | Gray out the column menu's show/hide control.                                                                                                                                                                                                                            |
| `lockWidth`          | `boolean`                                                                            | `false`       | Gray out resize and per-column auto-size.                                                                                                                                                                                                                                |
| `lockPin`            | `boolean`                                                                            | `false`       | Gray out the column menu's pin control.                                                                                                                                                                                                                                  |
| `editable`           | `boolean \| ((row: TRow) => boolean)`                                                | —             | Opt-in cell editing for this column (requires the `editing()` feature; omit either and nothing changes).                                                                                                                                                                 |
| `editor`             | `CellEditor`                                                                         | `"text"`      | Widget for the active cell when `editable` is set: `"text"`, `"number"`, `"boolean"`, `"date"`, `"datetime"`, `"time"`, `{ type: "select" }`, `{ type: "multi-select" }` or `{ type: "custom" }`.                                                                        |
| `editValue`          | `(row: TRow) => string`                                                              | —             | Draft seed when display formatting differs from the value you want to edit.                                                                                                                                                                                              |
| `validate`           | `(value: unknown, row: TRow) => string \| undefined \| Promise<string \| undefined>` | —             | Gate a commit on this column's own rule.                                                                                                                                                                                                                                 |
| `groupable`          | `boolean`                                                                            | `true`        | Whether a reader may group by this column; `false` keeps it out of the grouping panel.                                                                                                                                                                                   |
| `groupValue`         | `(row: TRow) => unknown`                                                             | sort value    | What this column buckets a row by when the table groups on it, and the caption the group carries.                                                                                                                                                                        |
| `aggregatable`       | `Aggregatable`                                                                       | `false`       | Whether and how a reader may aggregate this column: `true` offers operations suited to its value type; an object lists `operations` and a `default`.                                                                                                                     |
| `formatAggregate`    | `(value: DisplayValue \| undefined, context: AggregateFormatContext) => ReactNode`   | —             | How an aggregate of this column reads. Presentation only.                                                                                                                                                                                                                |
| `ai`                 | `ColumnAiOptions`                                                                    | —             | What an agent is told about this column. Ignored on a table with no agent. See [the pieces in core and react](#the-pieces-in-core-and-react).                                                                                                                            |
| `meta`               | `Record<string, unknown>`                                                            | —             | Arbitrary metadata adapters (or your own code) may read back.                                                                                                                                                                                                            |

## ColumnGroupDef

A parent header with `children`. Collapse options live here, not on the table.

| Prop              | Type                                       | Default    | Description                                                                                             |
| ----------------- | ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------- |
| `header`          | `string`                                   | —          | Caption on the spanning header cell, and the group's id.                                                |
| `children`        | `ColumnInput<TRow>[]`                      | —          | Nested groups or leaf columns.                                                                          |
| `collapsedKey`    | `string`                                   | —          | Leaf `key` to keep when this group is collapsed. Omit with `collapsedRender` omitted for an arrow stub. |
| `collapsedRender` | `(row: TRow) => DisplayValue \| undefined` | —          | Cell shown for every row while collapsed. Takes precedence over `collapsedKey`.                         |
| `marryChildren`   | `boolean`                                  | `true`     | Keep these children adjacent through reorder. The flat `group` shortcut still splits on drag.           |
| `align`           | `"start" \| "center" \| "end"`             | `"center"` | Spanning header alignment. Omit and it stays `"center"` — the previous hardcoded look.                  |
| `headerTooltip`   | `string`                                   | —          | Optional native tooltip. The collapse chevron does not show one.                                        |

`ColumnInput<TRow>` is `ColumnDef<TRow> \| ColumnGroupDef<TRow>`. See
[column groups](./column-groups.md).

## FilterDef

| Prop          | Type                       | Default         | Description                                                                                                                                                            |
| ------------- | -------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | `string`                   | —               | State key in the filter bag and the `f_<key>` URL param (required); doubles as the row's dot-path for the client-side predicate.                                       |
| `column`      | `string`                   | `key`           | Column whose header filter shows this widget, when the bag key and the column key differ.                                                                              |
| `type`        | `string`                   | —               | Built-in `FilterType` or a custom type registered by `filterTypes()`.                                                                                                  |
| `label`       | `string`                   | humanized `key` | Widget + chip label.                                                                                                                                                   |
| `options`     | `FilterOptionsSource`      | —               | Choices for `select`/`multiSelect`/`checklist` labels: a static `FilterOption[]`, `"auto"`, or an async loader.                                                        |
| `getValue`    | `(row: TRow) => unknown`   | `key` as path   | Row-value extractor for the client-side predicate.                                                                                                                     |
| `placeholder` | `string`                   | —               | Placeholder for text-like inputs.                                                                                                                                      |
| `ai`          | `false \| FilterAiOptions` | visible         | What the assistant may see: `false` hides this filter; `{ options: false }` omits the value list; `{ options: n }` sends values only for static lists of `n` or fewer. |

Range types persist two inclusive state keys: `dateRange` →
`${key}From`/`${key}To`, `numberRange` → `${key}Min`/`${key}Max`. Every
operator-first widget also writes `f_<key>Op` (`TEXT_OPS` / `NUMBER_OPS` /
`DATE_OPS`) so the comparison survives the URL and Saved Views. Headless:
`readRangeWidget`, `writeRangeWidget`, `writeRangeFilter`,
`useTextFilterWidget`, `useRangeFilterWidget`, `useBooleanFilterWidget`.
A `boolean` filter is any / true / false (`f_<key>=true|false`); omitting
the param is any. A `dateRange` `relative` operator stores a token
(`today`, `last:7`, …) in `${key}From` — never a resolved calendar day —
and `resolveRelativeRange` is the only place that token becomes a window.
An AND/OR tree lives in `ft=1.{…}` (`parseFilterTree` /
`serializeFilterTree`); the frontend ANDs it with the flat bag, and a
server that sets `supports.filterTree` receives `query.filterTree`.
Each adapter mounts `FilterTreeBuilder` (`FilterTreeBuilderProps`) as
the panel UI over that tree — kit controls, same part names. The
shared layout (no form controls) is `FilterTreeChrome` /
`FilterTreeChromeProps` / `FilterTreeClassNames` / `FilterTreeSlots` /
`FilterTreeSelectProps` / `FilterTreeInputProps` /
`FilterTreeButtonProps` / `FilterTreeDisclosureProps` / `FilterTreeOption` on
`@adapttable/react/adapter`.
`filterDefs` lets the chrome label tree chips. A `checklist` filter is
the Excel-style distinct-values widget (`ChecklistFilter` /
`ChecklistFilterProps` / `useChecklistFilter` / `collectChecklistValues`);
adapters draw it. The shared layout is `ChecklistChrome` /
`ChecklistChromeProps` / `ChecklistClassNames` / `ChecklistSlots` /
`ChecklistSearchProps` / `ChecklistButtonProps` /
`ChecklistCheckboxProps`. It prefers `source.facets` (own-filter
excluded via `computeFilterFacets` / `rowsExcludingFilter` /
`FacetMap` / `FacetCounts`) and falls back to `allFilteredRows`. A
server that sets `supports.facets` receives `query.facets` and returns
the same map on the page (`PaginatedResponse.facets`,
`PageSelector.facets`). Without either surface the widget stays hidden.
`headerFilters()` selects `filtersMode="header"` (`resolveFilterMode` /
`FilterChromeMode` / `toolbarShowsFilters`): each adapter mounts a
per-column filter icon (the `FILTER_HEADER` slot) on the same extra bag and
hides the toolbar Filters button unless `source.setFilterTree` is set, so
the AND/OR tree still has a chrome. The shared layout is `FilterHeaderChrome`
/ `FilterHeaderControlChrome` / `FilterHeaderChromeProps` /
`FilterHeaderControlChromeProps` / `FilterHeaderClassNames` /
`FilterHeaderSlots` / `FilterHeaderSearchProps` / `FilterHeaderSelectProps`
/ `FilterHeaderRangeProps` / `FilterHeaderMultiProps` / `FilterHeaderOption`
on `@adapttable/react/adapter`. Helpers `filterDefForColumn` /
`headerFilterStickTop` stay on core. Nested kit dropdowns (Select, DatePicker)
are not "outside" — the overlay stays open until a true outside click, Escape,
or (when `closeHeaderFilterOnSelect` is on) a finished single-control write
(`useHeaderFilterOverlay` / `bindHeaderFilterDismiss` /
`headerFilterFieldIsComplete` / `usePointerDismiss` /
`HeaderFilterSessionProps` / `HeaderFilterOpenProvider` /
`HeaderFilterOpenContext` / `HeaderFilterOpenHost`). Desktop only. Never stacked with the
popover or drawer.
`filterTypes()` merges `FilterTypeSpec`s onto `defaultFilterRegistry`
(`builtInFilterSpecs` / `resolveFilterRegistry` / `createFilterRegistry` /
`emptyFilterRegistry`). A spec supplies widget (`FilterWidgetKind`),
operators, predicate, chips, tree projection, and optional `render`
(`FilterWidgetRenderProps`). `FilterTypeRegistry.register` / `extend` and the
`filterTypes` prop are not v3 APIs — register with
`TableFeatureHost.registerFilterType` / `extendFilterType` in
`feature.setup(host)`, or `features={[filterTypes(specs)]}`. Lookups:
`filterTypeSpec` / `filterWidgetKind` / `filterTypeOps` /
`filterTypeDefaultOp` / `renderRegisteredFilter`.

## Adapter extras

Props beyond the core surface, with per-kit availability.

| Prop            | Type                                        | Default        | Available on                 | Description                                                                                                                                                                                               |
| --------------- | ------------------------------------------- | -------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`          | `readonly TRow[]`                           | —              | all                          | Frontend tier: raw rows the table filters/sorts/pages; with `onQueryChange` it is the current server page.                                                                                                |
| `total`         | `number`                                    | —              | all                          | Server tier: total row count across all pages (drives the pager).                                                                                                                                         |
| `loading`       | `boolean`                                   | —              | all                          | Server tier: a request is in flight.                                                                                                                                                                      |
| `error`         | `Error \| null`                             | `null`         | all                          | Forwarded error to display in the table's error state (retry via the source's `refetch`).                                                                                                                 |
| `mode`          | `"frontend" \| "server"`                    | `"frontend"`   | all                          | Data mode from `DataModeProps`. `"server"` requires `onQueryChange`.                                                                                                                                      |
| `onQueryChange` | `TableQueryHandler`                         | —              | all                          | Server tier: fired with the consolidated query whenever it changes (mount included); fetch and hand back `data` + `total`. `info.key` identifies the request.                                             |
| `responseKey`   | `string`                                    | —              | all                          | Server tier: the `onQueryChange` `info.key` the current `data` answers, so aggregate metadata belongs to the rows on screen.                                                                              |
| `aggregates`    | `readonly QueryAggregate[]`                 | —              | all                          | Server tier: aggregates to send as `query.aggregates`; requires `supports.aggregates`. Reader overrides layer over these.                                                                                 |
| `supports`      | `QuerySupport`                              | —              | all                          | Server tier: capabilities this endpoint answers. `supports.facets` unlocks `query.facets`.                                                                                                                |
| `facetKeys`     | `readonly string[]`                         | checklist keys | all                          | Server tier: keys sent as `query.facets`. Defaults to every `checklist` definition.                                                                                                                       |
| `facets`        | `FacetMap`                                  | —              | all                          | Server tier: distinct-value counts from the last fetch, surfaced on the source for the checklist.                                                                                                         |
| `urlKey`        | `string`                                    | —              | all                          | Namespace for this table's URL params (`urlKey="left"` → `left.q`, `left.page`, …).                                                                                                                       |
| `urlAdapter`    | `UrlStateAdapter`                           | History API    | all                          | URL-state backend for the `data`/`onQueryChange` tiers (router adapter, `createMemoryAdapter()` in tests).                                                                                                |
| `urlSync`       | `boolean`                                   | `true`         | all                          | `false` keeps all state in memory — the address bar never changes, any `urlAdapter` is ignored.                                                                                                           |
| `slots`         | `{ skeleton?, empty?, noResults?, error? }` | —              | all                          | Replace sub-components. `empty` covers both empty states; `noResults` overrides just the filtered one; `error` takes a node or a `(state) => node` receiving the error and its retry (see customization). |
| `classNames`    | `DataTableClassNames`                       | —              | all                          | Per-part class overrides — five parts on Mantine/MUI/Chakra/antd/Radix/Base UI (`root`/`toolbar`/`table`/`card`/`footer`), every part on unstyled and shadcn.                                             |
| `className`     | `string`                                    | —              | mui, antd                    | Class name applied to the root wrapper.                                                                                                                                                                   |
| `animate`       | `boolean`                                   | `false`        | all                          | Animate rows/cards on mount (dependency-free; honors reduced motion).                                                                                                                                     |
| `size`          | kit-specific union                          | —              | chakra, antd, radix, base-ui | Explicit kit table size, overriding the density mapping. MUI uses `density`; the listed kits retain native values density cannot express.                                                                 |
| `accentColor`   | kit accent union (chakra: `string`)         | —              | chakra, radix, base-ui       | Accent color for primary controls (buttons, badges, active page).                                                                                                                                         |
| `bordered`      | `boolean`                                   | `false`        | antd                         | Render the table with cell borders.                                                                                                                                                                       |

Mantine also publishes the spacing its density mapping uses, as
`DENSITY_SPACING` (`DensitySpacing`) from `@adapttable/mantine/density`, so a
host can match its own chrome to the table's rows.

Each adapter also re-exports the core source builders and types, so one
import path covers everything.

## Headless hooks

All from `@adapttable/react` unless marked `@adapttable/react/adapter`.

### Data sources

- `useFrontendData<TRow>(options): TableSource<TRow>` — in-memory source:
  filters, sorts, and slices a raw array from URL state. Pass
  `filterTreeFn` (usually `evaluateFilterTree`) to apply an AND/OR tree.
  `getRowId` (default `defaultFrontendRowId`) matches `applyRowPatches`
  so a `rowPatchLog` can continue the live incremental view.
- `useQuerySource<TRow, TParams, TPage>(options): TableSource<TRow>` — wraps
  your `useInfiniteQuery`-style hook into the same contract.
- `useServerData<TRow>(options): TableSource<TRow>` — hand-rolled-fetch
  server tier: emits one consolidated `TableQuery` per change, aborting
  superseded requests via `AbortSignal`.
- `useTableData<TRow>(options): { source, runtime }` — tier resolution
  (source ▸ server ▸ frontend) plus the declarative filter runtime; what
  every adapter calls internally.

### URL state & persistence

- **The codecs themselves**, for reading and writing the query string without
  a table — see [URL state](./url-state.md#reading-and-writing-the-params-yourself).
  `parseTableUrlState(search, namespace)` reads one table's params from a query string;
  `updateTableUrlState(search, namespace, mutate)` returns the next one;
  `applyTableUrlState` / `captureTableUrlState` move that state on and off a
  live table. Per param: `PARAM_PAGE`, `PARAM_LIMIT`, `PARAM_SEARCH`,
  `PARAM_FIND`, `PARAM_SORT_BY`, `PARAM_SORT_DIR`, `PARAM_GROUP_BY`,
  `PARAM_GROUP_AGGREGATES`, `PARAM_COL_HIDDEN`, `PARAM_DENSITY`,
  `PARAM_FORMULA`, `PARAM_PIVOT`, with `readPage`, `readLimit`, `readSortDir`,
  `readSortLevels` / `writeSortLevels`, `readColumnLayout` /
  `writeColumnLayout`, `readExtra` / `writeExtra`, `readFilterTreeParam` /
  `writeFilterTreeParam`, and `readRowPins` / `writeRowPins`.
- `useTableUrlState(options?): UseTableUrlStateResult` — page / limit /
  search / sort / grouping / group-aggregation overrides / extra-filter bag in
  the query string, with setters
  (`setPage`, `setLimit`, `setSearch`, `setSort`, `toggleSortLevel`, `setExtra`,
  `setExtras`, `setFilterTree`, `setGroupBy`,
  `setGroupAggregateOverrides`, `initializeGroupBy`, `clearExtras`, `clearAll`). Group keys use
  `groupBy`; overrides use `groupAgg`.
- `useColumnLayoutUrlState(options?): { layout, onLayoutChange }` —
  URL-persisted column layout (hidden / order / pinned / widths / names).
- `useColumnLayoutStorageState(options): { layout, onLayoutChange }` — the
  localStorage counterpart (user preference rather than shareable link).
- `useSavedViews(options: UseSavedViewsOptions): UseSavedViewsResult` —
  `views`, `defaultView`, `save`, `apply`, `remove`, `rename`, `move`,
  `setDefault`, `reload`
  — named snapshots of this table's URL params, persisted to storage.
- `createHistoryAdapter()` / `createMemoryAdapter(initial?)` /
  `getHistoryAdapter()` → `UrlStateAdapter`.

### Rendering & orchestration

- `useDataTable<TRow>(options): UseDataTableResult<TRow>` — derived state +
  prop-getters: `getTableProps`, `getHeaderRowProps`, `getHeaderCellProps`,
  `getSortButtonProps`, `getRowProps`, `getCellProps`,
  `getSearchInputProps`.
- `useTableChrome<TRow>(props): TableChrome<TRow>` — shared adapter
  orchestration: layout, confirm, chips, body region (`emptyVariant`,
  `isRefreshing`), `clearFilters`, footer.
- `useVirtualChromeBodyData(chrome, props): ChromeBodyData<TRow>` — body
  data-flow wiring: window virtualization + the infinite-scroll sentinel.
  `usePlainChromeBodyData` is the same shape without the virtualizer, for a
  table that never composed `virtualize`; `VirtualItemMeta` is one windowed
  entry and `virtualColumnSpan` is the span a windowed row's spacer cells
  cover.
- `useDataTableShell(props, renderAutoForm): DataTableShellResult<TRow>`
  (`@adapttable/react/adapter`) —
  the whole adapter shell in one call: resolved tier, chrome, and the
  `DataTableShellTableProps` / `DataTableShellToolbarProps` bundles a kit
  spreads, plus `DataTableShellChromeProps` and
  `DataTableShellGroupingPanelProps`. `DataTableShellView` mounts the gates
  below it and hands back the finished view; `finishDataTableShell` folds a
  body into a shell for an adapter that assembles its own.
- `useColumnLayout(options): ReactUseColumnLayoutResult<TRow>` — headless
  visibility / order / pinning / width / name / collapsed-group state
  (`visibleColumns`, `toggleVisible`, `move`, `setPinned`, `setWidth`,
  `setName`, `resetName`, `pinOffset`, `reset`, `toggleColumnGroup`). It is
  core's `UseColumnLayoutResult` with `visibleColumns` typed as React
  `ColumnDef`s.
- `useSearchInput(...)` — debounced search-input state behind
  `getSearchInputProps`.
- `useSelection(options): SelectionState` — page-scoped selection with
  select-all and cross-page "all matching".
- `useRowExpansion(): RowExpansionState` — multi-open row expansion keyed by
  row id.
- `useActiveFilterChips(options)` / `useExtraChips(options)` — removable
  chips from URL filter state / from non-URL state.
- `useFilterOptions(def): { options, loading }` — resolves static, `"auto"`,
  and async filter-option sources for custom forms.
- `useBulkActionRunner(options): BulkActionRunner` — runs bulk actions
  through the confirm handler.
- `useColumnDragState()` — drag-reorder state for custom column menus.
- `useHorizontalOverflow()` — scroll-overflow detection for pinned-column
  affordances.
- `useFilterTriggerToggle()` / `useChromeScrollReset()` — filter-trigger
  open state / scroll reset on query change.

### The neutral engine

Framework-free — see [concepts](./concepts.md#the-engine-and-why-it-has-no-react-in-it).

- `createTableEngine(options: CreateTableEngineOptions): TableEngine` — build
  an engine over in-memory rows. Filter, sort, page and group run here, with no
  React in the import graph.
- `TableEngine` — the handle: `snapshot()`, `rows(scope)`, `dispatch(op)`,
  `configure(patch)`, `invalidate(axes, next)`, `subscribe(axes, listener)`,
  `cellValue`, `rowByKey`, `rowKey`, `getColumn`, `dispose()`.
- `TableEngineReader` — the read half: `snapshot()`, `rows(scope)`,
  `rowByKey`, `cellValue`, `getColumn`. The engine is one, and so is the
  candidate below.
- `stageCandidate(patch, next?)` / `candidate` / `commitCandidate()` /
  `discardCandidate()` — a private candidate a binding builds while it renders.
  `snapshot()`, `rows()`, the revision tokens and every subscriber stay on the
  committed state until `commitCandidate()` publishes it, so a render that
  suspends or is abandoned changes nothing anyone else can read. Tokens move
  only where the columns, the rows or the view values actually differ: adopting
  a fresh `data` array or a new `rowKey` closure is not news. Any other write —
  a `dispatch`, an `invalidate` — takes the candidate with it. React hosts get
  this through `useTableEngine` and `useFrontendData` and never call it.
- `TableSnapshot` — query state plus `page` (the page actually shown),
  `requestedPage`, `lastPage`, `total` and `revisions`.
- `TableOperation` — a person's action: `setSort`, `setSearch`, `setPage`,
  `setLimit`, `setFilters`, `setGroupBy`, `setSelection`.
- `TableRowScope` — `"page"`, `"visible"` or `"full"`.
- `TableRevisions` / `TableRevisionAxis` — the four counters (`data`, `view`,
  `schema`, `policy`) and the axis names you subscribe to.
- `cellValue(row, column, locale?)` — resolve one cell's value, following a
  column's `i18n` path.
- `createNeutralTable(engine, tableId, binding?): NeutralTable` — wrap an
  engine as the shape `@adapttable/ai` reads: rows, revisions, and an
  `operations` map of what is wired right now. `NeutralTableBinding` is how a
  host supplies the visible rows and that map.
- `devWarn(message)` — development-only warning, printed once per message.

### Table options and runtime contracts

- `TableOptions` — the non-rendering half of `DataTableProps`: data, columns,
  query, selection, editing, URL and feature options, with no render types.
  `TableToolbarSlots` names the toolbar slots a binding fills.
- `TableQueryInput` / `buildTableQuery` / `TableQueryListener` /
  `QueryEmitter` / `createQueryEmitter` — the one consolidated query a table
  hands `onQueryChange`, and the emitter that fires it once per change.

### The view-state store

- `createTableViewStore(source, config?)` — the store over a
  `ViewStateSource`'s URL adapter for everything the table writes to the URL,
  configured by `TableViewStateConfig`: `getSnapshot()`, `subscribe()` and the
  mutators. `TableViewStore` is the store, `TableViewState` its snapshot, and
  `ViewStateSubscription` how a binding listens.
- `createUrlSliceStore(source, spec, config)` — one debounced URL slice
  (`URL_SLICE_WRITE_DEBOUNCE_MS`) described by a `UrlSliceSpec`, as a
  `UrlSliceStore`. The slices the table ships: `columnLayoutSlice`,
  `densitySlice` (`TableDensity`), `groupCollapseSlice`, `rowPinningSlice`,
  `pivotSlice` and `formulaSlice`.
- `resolveUrlAdapter(adapter, enabled, local)` — the adapter a table uses: the
  host's, the browser history, or the caller's own memory store when URL sync
  is off or there is no browser. `resetHistoryAdapter()` drops the shared
  history adapter, for tests.

### The data-tier controller

- `DataTier` / `resolveDataTier(options)` — which tier serves the rows:
  frontend, server, query or infinite. `warnDataTierMisuse` reports a
  contradictory combination in development.
- `queryAggregationSource`, `effectiveQueryAggregates`, `queryGroupBy` — what a
  server query asks the backend to aggregate and group.
- `FirstLoadLatch` / `createFirstLoadLatch` — holds the loading state until the
  first answer. `clampedPage(page, limit, total)` — the last real page when
  `page` is past it, `undefined` otherwise.
- `CursorTrail` / `EMPTY_CURSOR_TRAIL` / `recordCursor` / `cursorHasMore` /
  `canRequestCursorPage` — cursor paging's trail of seen cursors.
- `AppendStash` / `appendBaseKey` / `appendedRows` / `staleAppendStash` —
  infinite paging's accumulated rows and when they reset.
- `LoadedFilterOption` / `FilterOptionsLoader` / `createFilterOptionsLoader` —
  async filter options, loaded once per key and aborted when superseded.
- `createFrontendSource()` — the frontend tier as a `FrontendSource`: call
  `update(config, view)` with the host's rows and callbacks
  (`FrontendSourceConfig`) and the view-state store's snapshot
  (`FrontendSourceViewState`) to read a `FrontendSourceFrame` — the page's
  rows, the filtered and searched rows, `total`, the clamped `page` and
  `hasNextPage` — from the engine's candidate, then `commit()` once the frame
  is on screen. It caches each row's search text, restages only when a value
  moved, and keeps one page slice per engine revision. `useFrontendData` runs
  on it. `resolvePaginationMode(mode, isMobile)` turns `"auto"` into
  `"infinite"` on mobile and `"paged"` elsewhere; `defaultSearchText` and
  `defaultFrontendRowId` are the defaults a source uses.
- `createServerSource()` — the server tier as a `ServerSource`: call
  `update(config, view)` with the host's last answer and request settings
  (`ServerSourceConfig`) and the view-state store's snapshot and `setPage`
  (`ServerSourceViewState`) to read a `ServerSourceFrame` — the query and its
  key, the rows to show (appended pages included), `isLoading`,
  `isFetchingNextPage`, `hasNextPage` and the aggregate operations on screen.
  `commit()` once the frame is on screen sends a changed query (aborting the
  one it supersedes), latches the first load, clamps a page past the end and
  records the cursor the host returned; `setPage`, `fetchNextPage` and
  `refetch` are the source's own actions, `subscribe` / `revision` report when
  its state moved, and `dispose()` aborts the request in flight.
  `useServerData` runs on it.
- `createQuerySource()` — the query-library tier as a `QuerySource`: call
  `params(config, view)` with the host's `QuerySourceConfig` and the
  view-state store's snapshot for the params to hand the library (the same
  inputs give the same object), then `update(answer)` with the library's
  result (`QuerySourceAnswer`) to read a `QuerySourceFrame` — the rows (the
  last page when paged, every page so far when infinite), `total`, `facets`,
  the append flags and the aggregate operations on screen. `commit()` once the
  frame is on screen records the cursor, restarts a stale trail from page 1,
  and clamps a page past the end; `fetchNextPage` and `refetch` drive the
  library. `useQuerySource` runs on it.
- `cursorTrailKey(query)` — what a cursor token's position depends on: limit,
  search, sort, grouping, aggregate overrides, filters and the filter tree. A
  change to any of it restarts the trail in both server tiers.
- `createTableData()` — the table data controller as a `TableData`: `plan`
  a `TableDataConfig` (the data props plus the filter engine, when composed)
  into a `TableDataPlan` — the tier, the merged filter runtime, the combined
  predicate, the tree predicate and the facet keys a server query asks for;
  `finish({ resolved, frontend })` adds facet counts computed from the
  searched rows when nothing answered them; `commit()` tells a
  `mode="frontend"` table's `onQueryChange` about each change (never the
  mount), `loadOptions()` loads each filter's own option list once, and
  `dispose()` aborts a notification in flight. `useTableData` runs on it.
- `ResponseAggregateOps` / `ResponseAggregateOpsInput` /
  `createResponseAggregateOps` — which aggregate
  operations the rows on screen were computed with: `remember` each request's
  operations, `settle` from the response's provenance, read `current()`.

### Controllable stores

- `createControllableStore(initial, options?)` — a value that is the host's
  when controlled and the store's own otherwise, reporting every change.
  `ControllableStore` is the store, `ControllableStoreOptions` its observer
  mode and change detection, and `ControllableControl` the controlled half.
- Selection: `toggleId`, `toggleIds`, `idSetReader`, `headerSelectionOf`.
  Expansion: `groupsCollapsedToDepth`. Row pinning: `sameRowPins`,
  `rowPinSideOf`.
- Column layout: `withColumnHidden`, `withColumnPinned`, `withColumnWidth`,
  `withColumnMoved`, `withColumnOrder`, `initialColumnLayout`,
  `readStoredColumnLayout`, `sanitizeStoredLayout`.

### Editing

- `createCellEditSession(options: CellEditSessionOptions): CellEditSession` —
  the active cell and its draft, Enter/Escape/Tab, and the start and cancel
  observers. `CellEditSnapshot`, `isCellEditActive`, `observeEdit`.
- `createCellSaveStore(options: CellSaveStoreOptions): CellSaveStore` — saving
  and failed cells, superseded saves and rollback. `CellSaveSnapshot`,
  `cellSaveKey`, `cellSaveStatus`, `cellSaveFailure`, `cellSaveSignature`,
  `defaultSaveErrorMessage`.
- `createEditValidationStore(options: EditValidationStoreOptions):
EditValidationStore` — cell then row validation, with superseded checks
  dropped. `EditValidationSnapshot`, `validationKey`, `validationErrorFor`,
  `rowHasValidationError`, `validationSignature`.
- `createEditHistoryStack(): EditHistoryStack` — undo and redo over edit
  gestures; `DEFAULT_EDIT_HISTORY_DEPTH` is the depth a host that sets none
  keeps. `EditHistorySnapshot`,
  `editHistoryEntry`, `cellsOfBatch`.
- `createEditHistory(options: EditHistoryControllerOptions):
EditHistoryController` — the history a table runs: records a gesture with
  each cell's value before it changed and replays undo and redo through the
  host's `CellEditHandler`. `editHistoryView` (`EditHistoryState`),
  `resolveEditHistory` reads the `editHistory` prop, and `recordingCellEdit`
  wraps the channel so each inline commit is one gesture.
- `createEditConflictStore(): EditConflictStore` — the live-update
  reconciler for the open cell, an open row form and a batch
  (`ReconcileLiveEdit`, `ReconcileLiveRowEdit`, `ReconcileLiveBatchEdit`): a
  field the reader never typed in takes what arrived, the rest follow
  `onEditConflict` or the policy, and "ask" holds the question.
  `EditConflictSnapshot`, `ContestedEditCell`, `contestedCellKey`,
  `isCellInConflict`, `isRowContested`, `contestedRowSignature`,
  `editConflictView` (`EditConflictState`), `liveRowChanged`,
  `resolveConflictChoice`.
- `createRowEditStore(options: RowEditStoreOptions): RowEditStore` — a row
  edited as one form: seeds, drafts, one patch on save, and the seeds a live
  update moves. `RowEditSnapshot`, `RowEditDrafts`, `rowEditSignature`,
  `rowEditingView` (`RowEditingState`), `parseColumnDraft`.
- `createBatchEditStore(options: BatchEditStoreOptions): BatchEditStore` —
  many rows held and saved in one list. `BatchEditSnapshot`,
  `BatchPendingDrafts`, `BatchEditEntry`, `batchEditingView`
  (`BatchEditingState`).
- `createDirtyCellStore(options: DirtyCellStoreOptions): DirtyCellStore` —
  cells changed and not yet confirmed. `DirtyCellSnapshot`, `dirtyCellKey`,
  `dirtyCellView` (`DirtyCellState`), and `dirtyMarkerView`, which keeps the
  count but draws no marks when the host did not ask for them.
- `cellEditingView` (`CellEditingState`), `editValidationView`
  (`EditValidationState`) and `cellSaveView` (`CellSaveState`) — the state a
  binding hands its cells, read off the session, validation and save
  snapshots.
- `editableCellController(options)` — one cell's commit pipeline over an
  `EditingBundle` (with `EditConflictLabels`): the validation gate, the hold
  while an async check decides, the send to the host, the save it watches,
  dirty marks and the step to the next cell. `EditableCellController`,
  `EditableCellMode`, `beginCellEdit`, `stopCellEditKeyboard`,
  `focusEditorOnMount`.
- The rules every binding draws the same: `resolveEditingArming`
  (`EditingArmingProps`, `EditingArming`) — which units the props arm;
  `editableCellPresentation` (`EditableCellPresentation`) — batch, then an
  open row form, then the cell; `isEditActivateKey`, `editorKeyRestoresFocus`,
  `stopEditKeys`, `handleRowEditorKey` and `rowEditSaveBlocked` — the keys;
  `isFirstEditableColumn` — the field a row form focuses;
  `editableCellErrorId`, `rowEditErrorId`, `batchEditErrorId`,
  `editorValidationProps` and `editorBusyProps` (`EditorAriaState`) — ids and
  ARIA; `editorSelectOptions`, `resolveEditableCellDisplay`;
  `cellConflictAsk`, `controllerConflictAsk`, `customEditorConflict`
  (`CellConflictAsk`) and `rowEditConflict` (`RowEditConflict`) — the
  conflict questions; `resolveRowEditTrigger` (`RowEditTrigger`),
  `rowEditControls` (`RowEditControls`, `RowEditControlsOptions`) and
  `rowEditActionsLayout` (`RowEditActionsLayout`) — the row's controls;
  `batchEditBarModel` (`BatchEditBarModel`) and `defaultPendingRows` — the
  batch bar.
- `approvalReview(pending, labels)` — the model every approval surface
  reads: tallies, the first `APPROVAL_PREVIEW_LIMIT` changes and the summary
  labels. `ApprovalReview`, `ApprovalReviewItem`.

### Grid focus

- `createGridFocusController(options: GridFocusControllerOptions):
GridFocusController` — the active cell, the selected range, a fill drag, the
  key dispatch (movement, Enter/F2, undo/redo, find, copy, cut, fill down,
  paste) and the announcement, against an attached container element.
  `GridFocusSnapshot`, `GridKeyEvent`, `PointerReleaseTarget`.
- `gridContainerAttributes` (`GridContainerAttributes`), `gridCellAttributes`
  (`GridCellAttributesInput`, `GridCellAttributes`), `gridRowAttributes`,
  `gridColumnHeaderAttributes` — the roles, absolute ARIA indices and selection
  and find marks every binding puts on the grid.
- `isGridColumnSelected`, `gridFillHandleCell` — whether a column is selected
  over every loaded row, and which cell carries the fill handle.

### Row reordering

- `createRowReorderController(options: RowReorderControllerOptions):
RowReorderController` — the keyboard grab, drag and drop, the mobile swap and
  the move policy. `RowReorderSnapshot`, `RowReorderSlot`, `RowDragEvent`,
  `RowKeyEvent`.
- `resolveRowMove(view, drop, options, labels)` — a drop inside grouped or tree
  rows as a reorder, a move or a rejection. `rowMoveMenu` — the keyboard and
  touch destinations. `RowMoveView`, `RowMoveDrop`.
- `rowReorderAnnouncements(read)` / `defaultRowReorderAnnouncements` /
  `RowReorderAnnouncements` — the announcements, each label read when spoken.
- `rowReorderRowAttributes`, `isRowMovePending` — a row's drag marks, and
  whether it owns the pending confirmation.

### Interaction models

- `createFindController(options: FindControllerOptions): FindController` — the
  find bar's open state, query and walk, and the debounced `find` URL param.
  `FindSnapshot`, `readFindQuery`, `clampMatchIndex`.
- `createHeaderFilterOverlay(options: HeaderFilterOverlayOptions):
HeaderFilterOverlayController` — one header filter's open state and reset
  key. `HeaderFilterOverlaySnapshot`, `isHeaderFilterOpen`,
  `HEADER_FILTER_SESSION_ATTR`, `headerFilterInsideSelector`,
  `watchOverlayDismiss`, `HeaderFilterWrites`.
- `createSavedViewsController(options: SavedViewsControllerOptions):
SavedViewsController` — the saved views list, its storage and every
  operation on it. `SavedViewsSnapshot`.
- `createExportController(options: ExportControllerOptions): ExportController`
  — an export run's progress, cancel and retry. `ExportSnapshot`,
  `ExportRunHandler`, `resolveExportAnnouncement`,
  `resolveExportDisabledReason`, `resolveExportProgressState`.
- `resolveTableStatus(options)` — the status line a table announces after
  loading, filtering or paging. `TableStatusSignature`.
- `createContextMenuOpenController(options: ContextMenuOpenControllerOptions):
ContextMenuOpenController` — the menu's open state and position, from a
  right-click, a long press or the context-menu key. `ContextMenuOpenSnapshot`,
  `ContextMenuState`, `ContextMenuTriggerHandlers`,
  `ContextMenuRegionHandlers`, `ContextMenuPointerEvent`,
  `ContextMenuPressEvent`, `ContextMenuMoveEvent`, `ContextMenuKeyEvent`,
  `isContextMenuArmed`, `isContextMenuKey`, `composeContextMenuExtra`.
- `createCommandPaletteController(options: CommandPaletteControllerOptions):
CommandPaletteController` — the palette's open state, controlled or its own.
  `CommandPaletteSnapshot`, `isCommandPaletteArmed`, `commandPaletteCommands`
  (`CommandPaletteCommandsOptions`), `OPEN_PALETTE_COMMAND`.
- `createCommandList(): CommandListController` — the palette's query and
  highlighted row. `CommandListSnapshot`, `commandListView`
  (`CommandListView`), `commandListKeyAction` (`CommandListKeyAction`),
  `nextCommandIndex`, `runCommand`, `tabTrapTarget`.

### Column and filter controllers

The rules behind the column menu and the filter panel, for a binding to wire
its own controls to.

- `createColumnLayoutController(defaultColumnLayout?): ColumnLayoutController`
  — the column layout store (`COLUMN_LAYOUT_STORE_OPTIONS`) plus the rename
  baselines a reset restores while the host echoes an accepted name. Call
  `configure(options: ColumnLayoutControllerOptions)` each render.
  `columnLayoutVisibleColumns(columns, state, options?)` derives the columns
  that render; `columnPinInsets(visibleColumns, state)` each pinned column's
  sticky inset.
- `writeStoredColumnLayout(storage, storageKey, next, fallback)` — save a
  layout, removing the entry when it equals the default; a failed write is
  swallowed.
- `COLUMN_DND_MIME`, `columnDragAllowed(target: ColumnDragTarget | null)`,
  `columnReorderKeyStep(key, rtl)` and
  `columnDragRowAttrs(drag: ColumnDragSource | null, overIndex, key, index):
ColumnDragRowAttrs` — the column-menu reorder: which drags start, which arrow
  moves a column in either writing direction, and the drop edge.
- `createColumnDragController(): ColumnDragController` — the column menu's
  drag in progress (`ColumnDragSnapshot`: the dragged column and the hovered
  index), fed the drag events a binding receives. `startColumnDrag`,
  `acceptColumnDrag`, `dropColumn` and `columnReorderKeyDown` are its steps
  on their own: they read any DOM-shaped event (`ColumnDragEvent` with its
  `ColumnDataTransfer`, `ColumnReorderKeyEvent`), a browser's or a
  framework's wrapper.
- `createColumnRenameEditor(options: ColumnRenameEditorOptions):
ColumnRenameEditor` — the inline rename form. `ColumnRenameEditorSnapshot`;
  `submit()` returns a `ColumnRenameSubmit`.
- `rangeFilterWidget(def, source, op)` with `initialRangeFilterOp(def, extra)`,
  `textFilterWidget(def, source, localOp, setLocalOp)` with
  `initialTextFilterOp(def, extra)`, and `booleanFilterWidget(def, source)` —
  the auto-built form's fields: `RangeFieldWidget` (`RangeOpArity`,
  `RangeOpLabelKeys`), `TextFieldWidget`, `BooleanFieldWidget`
  (`BooleanChoice`, `parseBooleanChoice`). `scalarFilterText`,
  `filterOpLabel`.
- `filterTreeConditionModel(condition, defs, registry, labels):
FilterTreeConditionModel` — one AND/OR builder row: its field and operator
  choices (`FilterTreeOption`) and its value editor
  (`filterTreeValueEditor`, `FilterTreeValueEditor`).
  `filterTreeEditorActions(tree, commit, first, registry):
FilterTreeEditorActions`, `filterTreeCombinatorOptions`,
  `filterTreeOpLabel`, `newFilterTreeCondition`, and
  `filterTreeChipLabel(condition, defs, labels, registry?)`, which reads
  operators through the same registry widget the builder does.
- `activeFilterChips(options: ActiveFilterChipsOptions)`,
  `chipValuesOf(extra, labels)`, `mergeFilterChips` and
  `resolveActiveFilterCount` — the chip strip and the filters count.
- `checklistItems(def, source: ChecklistSource): ChecklistItems`,
  `searchChecklistItems(items, query)` and
  `checklistActions(def, source, visible): ChecklistActions` — the checklist
  filter. `checklistWindow(count, scrollTop, width): ChecklistWindow` and
  `checklistColumnsAcross(width)` window a long list;
  `CHECKLIST_VIRTUALIZE_AT`, `CHECKLIST_ITEM_HEIGHT`, `CHECKLIST_ITEM_WIDTH`,
  `CHECKLIST_OPTION_GAP`, `CHECKLIST_LIST_HEIGHT`.
- `headerFilterCellKind(def, registry): HeaderFilterCellKind` — the compact
  control a header filter cell draws, with `headerFilterSelectModel`
  (`HeaderFilterSelectModel`), `headerFilterMultiModel`
  (`HeaderFilterMultiModel`), `headerFilterBooleanOptions`,
  `headerFilterRangeModel` (`HeaderFilterRangeModel`) and
  `HeaderFilterOption`. `hasActiveHeaderFilter` says when a column's funnel
  lights.

### Row feature runtimes

Grouping, trees, row actions and cell navigation, for a binding to drive.

- `createGroupingPanelController(options: GroupingPanelControllerOptions):
GroupingPanelController` — the grouping panel's drag and keyboard state
  machine, its aggregate gates and announcements. `GroupingPanelSnapshot`,
  `GroupingDragEventLike`, `GroupingKeyEventLike`. The panel's layout reads
  `groupingDropPlan` (`GroupingDropPlan`), `GroupingDropHandlers`,
  `INERT_GROUPING_DROP_HANDLERS`, `deferGroupingDropToInner`,
  `groupingAvailableColumns`, `groupingColumnName`, `groupingOperationLabel`,
  `groupingAggregationOptions`, `focusAfterAggregationRemoval` and
  `aggregationRemovalFocusSelectors`.
- `groupingAggregationSource`, `groupingIgnoredWarning`,
  `groupingAggregates(options: GroupingAggregatesOptions):
GroupingAggregates`, `groupedRowModel(options: GroupedRowModelOptions):
GroupedRowModel`, `groupShowMoreRequest` (`GroupShowMoreRequest`),
  `groupedViewSource` and `groupingPanelAggregations` — the grouping runtime
  over a `GroupingRuntimeSource`. `advanceGroupPaging` and
  `createGroupPagingController(): GroupPagingController` page a group's
  rows; `groupCollapseActions(): GroupCollapseActions` expands and collapses.
- `createLazyChildrenController(options: LazyChildrenOptions):
LazyChildrenController` — a tree's children loaded on expand, with the node
  closed again when the load fails. `LazyChildrenSnapshot`.
  `treeExpansionActions` (`TreeExpansionActions`), `toggleTreeNode`,
  `closeFailedTreeNode` and
  `treeExportExpandedIds`.
- `rowPinActions`, `withRowPinActions`, `commitRowPin`,
  `rowPinningRequested`, `rowPinningBlockedWarning`, `rowPinningControl`,
  `rowPinningUrlSync` and `ROW_PIN_STORE_OPTIONS` — row pinning;
  `EMPTY_ROW_PIN_STATE`. `rowMutationActions` and `withRowMutationActions`
  add duplicate and delete (`MergedRowActions`).
  `dispatchRowMove`, `rowMoveView` and `rowReorderRuntimeOptions` dispatch a
  row reorder.
- `cellNavigationChannels(options: CellNavigationChannelsOptions)` — cell
  navigation's covered cells, and paste and fill recorded as one undo
  gesture. `reportedCellRange` and `cellRangeKey` report the selected range.
- `copyContextMenuSelection`, `copyContextMenuTargetCell` and
  `withContextMenuCellCopy` — the context menu's copy rules, with and
  without cell navigation (`ContextMenuCopyFocus`).
- `TableRuntime` and `TableRuntimeView` are named on the main entry too, since
  these runtimes take them.

### Panel, bar and effect models

- `handleFindBarKey` (`FindBarKeyEvent`, `FindBarKeyTarget`),
  `findMatchCountText`, `defaultFindMatchCount`, `isFindShortcut`,
  `createFindShortcutScope(options: FindShortcutScopeOptions):
FindShortcutScope`, `scrollCurrentMatchIntoView`,
  `FIND_CURRENT_MATCH_SELECTOR` and `findMatchRow` — the find bar's keys,
  count text, Ctrl/Cmd+F scope and scrolling to the current match.
- `parseChord` (`ParsedChord`), `chordMatches` (`ChordKeyEvent`),
  `chordHasCommandModifier`, `isTextEntryTarget` and
  `createShortcutHandler` (`ShortcutKeyEvent`) — keyboard shortcuts,
  `mod+k` included.
- `createBulkActionRunner(options: BulkActionRunnerOptions):
BulkActionRunnerController` (`BulkActionRunnerSnapshot`) and
  `bulkBarModel(selection: BulkBarSelection): BulkBarModel` — the bulk
  action runner and the "all matching" banner.
- `savedViewRowControls(input: SavedViewRowControlsInput)`
  (`SavedViewRowControlModel`, `SavedViewGlyph`, `SAVED_VIEW_GLYPH_PATHS`)
  and `createSavedViewRenameController(): SavedViewRenameController`
  (`SavedViewRenameSnapshot`) — a saved view's row controls.
- `exportProgressView` (`ExportProgressView`), `exportProgressHeading` and
  `focusExportTrigger` — the export progress panel.
- `statusBarItems(input: StatusBarItemsInput)` and `selectionStatParts` —
  the status bar and selection stats.
- `sidePanelModel` (`SidePanelModel`, `SidePanelModelPanel`,
  `SidePanelTabModel`), `sidePanelTabIndex`, `sidePanelTabId`,
  `handleSidePanelTabKey`, `handleSidePanelBodyKey` (`SidePanelKeyEvent`) and
  `DEFAULT_SIDE_PANEL_ID_PREFIX` — the side panel's tablist.
- `stickyToolbarStyle` (`StickyToolbarStyle`), `stickyHeaderOffset` and
  `measuredToolbarHeight` — the sticky toolbar rule. `shouldEscapeClose`
  and `isElementShowing` — the Escape-close rule. `restoreFocusSoon` and
  `focusWasDropped` — restore-focus timing. `resolveDensity`,
  `requestDensityChange` and `DEFAULT_DENSITY` — density.
- `createAllMatchingScope(): AllMatchingScope` — selection's "all matching"
  scope. `createHighlightStore(options: HighlightStoreOptions):
HighlightStore` (`HighlightSnapshot`, `highlightDuration`,
  `highlightCellKey`, `HIGHLIGHT_FADE_MS`, `HIGHLIGHT_STEADY_MS`) and
  `createChangedCellFlashStore(options: ChangedCellFlashOptions):
ChangedCellFlashStore` (`changedRowFields`, `patchTouchedKeys`,
  `CHANGED_CELL_FLASH_MS`) — row highlights and the changed-cell flash.
- `sparklineBars` (`SparklineBar`), `sparklinePoints` (`SparklinePoint`),
  `sparklineLinePath`, `sparklineAreaPath`, `sparklineSortValue`,
  `SPARKLINE_DEFAULT_WIDTH` and `SPARKLINE_DEFAULT_HEIGHT` — sparkline
  geometry. `NESTED_TABLE_DEFAULT_LABEL` and `nestedTableLabel` — nested
  table defaults.
- On `@adapttable/core` and `@adapttable/core/pivot`:
  `pivotTableLayout` (`PivotTableLayout`, `PivotLeafColumnLayout`),
  `pivotLeafColumnKey`, `pivotLeafGroup`, `pivotRowCaption`,
  `pivotRowIndentStyle` and `PIVOT_ROW_INDENT` lay out a pivot table;
  `pivotPanelZones` (`PivotZoneModel`, `PivotZoneEntry`), `pivotZoneLabel`,
  `pivotMeasureAggName` and `PIVOT_AGGREGATIONS` model its panel.

### `@adapttable/core/binding` — the Chrome model

A binding also finds here what its hooks share with every other binding: the
state shapes they return (`SelectionState`, `GridFocusState`,
`ChecklistWindowState`, `TreeExpansionState`, `RowPinningState`, the URL-state
results and the rest), the feature-state keys `DENSITY_STATE`
(`DensityFeatureState`) and `ROW_REORDER`, `resolveColumnDefaults`
(`ResolvableColumn`) and `resolveColumnHeaders` for a column's declarative
defaults, `columnPathText` for a data-path value as cell text, and
`sameRows` — whether a new `data` array holds the same rows, so a table
engine does not rebuild for an inline array.

- `chromeColumnPlan` (`ChromeColumnPlan`) — the columns a desktop table draws,
  with selection, expansion and action lanes.
- `ChromeBodySlot`, `ChromeRowSlot`, `ChromeGroupSlot`, `ChromeGroupEntry`,
  `ChromeExtraSlot`, `ChromeVirtualPadSlot` — the body as slots a binding
  renders in order.
- `tableAttributes`, `headerRowAttributes`, `headerCellAttributes`,
  `sortButtonAttributes`, `rowAttributes`, `cellAttributes`,
  `searchInputAttributes` — the prop getters, with `data-adapttable-part` names.
  `ChromeSortState`, `ChromeCellSizing`, `columnAriaSort`, `columnTextAlign`,
  `sortLevelOf`, `sortIndexOf`.
- `desktopChromeMetrics`, `desktopHasPinned`, `desktopScrollBoxStyle`
  (`DesktopScrollBoxStyle`), `desktopBodyPinStyle` (`DesktopBodyPinStyle`),
  `desktopHeadCellGeometry` (`DesktopHeadCellGeometry`), `desktopEdgeHeadPin`,
  `desktopPinSignature`, `DESKTOP_RESIZE_HANDLE_STYLE` — desktop layout and
  pinning geometry.
- `desktopRowMeasureRef`, `desktopDetailMeasureRef`, `measureRowDetailAsPair`,
  `measureWindowScrollMargin`, `documentOffsetTop`, `virtualListElement`,
  `sourceWindowStart` — measuring rows and the scroll window for
  virtualization.
- `entryKeys`, `extraRowCoveredSlots` — row keys and the slots an extra row
  covers.
- `LiveFeatureHost` / `createFeatureHost` / `disposeFeatureHost` /
  `EMPTY_FEATURE_HOST` / `FeatureSetup` — the host that runs composed
  features. `SlotFill`, `slotFillsOf`, `drawnSlotFills`, `OrderedContribution`,
  `orderedContributions` — how features fill slots, in order.
- The slot contract: every position a kit fills, with the id and `single`
  flag each binding shares — `STATUS_BAR`, `FIND_BAR`, `BULK_BAR`
  (`BulkBarSlotProps`), `EDITABLE_CELL`, `GRID_FOCUS_ANNOUNCER`
  (`GridFocusAnnouncerSlotProps`), `TOOLBAR_EXTRAS`, the `*_LIVE` keys and the
  rest — and the props each kit control receives. Props that carry rendered
  content take the binding's node as `TNode`, and key, drag and style types
  are parameters too. A binding re-types a neutral key with its own props;
  the id stays core's. The feature-state keys that go with them
  include `FILTER_ENGINE` and `GROUPING_PANEL_STATE`.
- Glyphs as data: `IconDescriptor` is an `<svg>`'s attributes and its
  `IconShape` list, which each binding draws with its own renderer.
  `FILTERS_ICON`, `SEARCH_ICON`, `expandChevronIcon` (turned for open and
  RTL), `GRIP_ICON`, `eyeIcon`, `PIN_ICON`; the assistant's
  `ASSISTANT_AVATAR_ICON`, `PERSON_AVATAR_ICON`, `ASSISTANT_SETTINGS_ICON`,
  `ASSISTANT_CLOSE_ICON`, `ASSISTANT_SEND_ICON`, `ASSISTANT_STOP_ICON`,
  `ASSISTANT_EXAMPLES_ICON`, `ASSISTANT_UNDO_ICON`, `ASSISTANT_ACTIONS_ICON`,
  `assistantMicIcon`, `assistantKindIcon` and `assistantReceiptIcon`, over
  the per-kind `ASSISTANT_KIND_PATHS` and `ASSISTANT_KIND_HUES`.
- Motion and paint rules: `OVERLAY_MOTION`, `MOUNT_STAGGER` (the entrance
  stagger's selector, step, duration, easing and keyframes),
  `FORCED_COLORS_CSS`, and the cell rules — `cellHighlightKind` (current
  match over match over selection) and `cellHighlightStyle`, which merges it
  into a kit's cell style, with `CURRENT_MATCH_CELL_STYLE`,
  `MATCHED_CELL_STYLE` and `SELECTED_CELL_OUTLINE`, and `mergedCellStyle`
  (`MergedCellStyle`).

#### Chrome orchestration

Every binding assembles a table the same way; these are the decisions it
shares, so a new binding calls them rather than re-deriving them.

- **Feature patch layer.** `applyTableFeatures` merges each feature's `apply`
  patch into the table's props: later features win, `assembly` is merged one
  level deep, host props win, and a second call is a no-op.
  `mergeFeaturePatches`, `getAppliedFeatures` and `rememberAppliedFeatures`
  are its parts. `FeaturePatch`, `PatchFeature`, `CoreFeature`,
  `CoreFeatureRegistrar`, `CoreRowFeatureRegistrar` and `VirtualizeInput` are
  the types. Each built-in factory's id and option normalization is its own export, named `core` plus the factory: `coreFeature`, `coreCellSpan`, `coreExtraRows`, `corePinnedSummaryRows`, `coreRowAppearance`, `coreColumnMenu`, `coreResizableColumns`, `coreCollapsibleColumnGroups`, `coreCommandPalette`, `coreContextMenu`, `coreSidePanel`, `coreBulkActions`, `coreFilterTypes`, `coreHeaderFilters`, `coreSavedViews`, `corePrint`, `coreStatusBar`, `coreUndoRedoButtons`, `coreMultiSort`, `coreFitColumns`, `coreColumnSelectionCheckbox`, `coreCellNavigation`, `coreDensityChooser`, `coreEditHistory`, `coreEditing`, `coreRowEditing`, `coreBatchEditing`, `coreDirtyIndicators`, `coreExportCsv`, `coreFilters`, `coreFindInTable`, `coreFullscreen`, `coreGrouping`, `coreGroupingPanel`, `coreRowActions`, `coreRowDetail`, `coreNestedTable`, `coreRowPinning`, `coreSelectionStats`, `coreTree`, `coreVirtualize`. They are separate functions so a table bundles only the features it uses; a binding spreads one and adds what it draws.
- **Standard preset.** `standardFeatureList` (`CoreStandardFeatureFactories`,
  `CoreStandardFeatureOptions`) builds the preset's members in order from the
  binding's own factories.
- **Shell pipeline.** `CHROME_EXTRA_SLOT_ORDER` and `SHELL_LIVE_STAGE_ORDER`
  (`ShellLiveStageId`) fix the order of the extra slots and live stages.
  `TableRuntimePublisher` projects the chrome into the runtime view through
  `tableRuntimeView`, `renderedRowsOf`, `readableRowLabel`,
  `liveColumnLayout` and `livePinning` (`RuntimeChromeInput`,
  `RuntimeColumn`). `cellNavigationInput`, `exportPageOnly`,
  `viewControlsToolbarProps`, `undoRedoToolbarProps` and `printToolbarProps`
  build the live stages' inputs. `finishShellLive`, `overlayChromeExtras` and
  `finishShellBody` (`PipelineShell`, `OverlayChrome`, `ShellBodyInput`)
  finish the shell.
- **Table chrome state.** `chromeBodyRegion` (`ChromeBodyRegion`),
  `chromeEmptyVariant`, `chromeIsRefreshing`, `chromeShowFooter`,
  `clearChromeFilters`, `selectionObserverIds`, `rowReorderEnablement`,
  `groupingPanelState`, `chromeFeatureNotices` (`ChromeFeatureNoticesInput`),
  `featureNoticesAttribute`, `applyFeatureNoticesAttribute`,
  `FilterTriggerToggleState`, `scrollResetKeys`, `cardSetSize` and
  `sortedColumnName` — what the frame shows before a kit draws it.
- **Desktop assembly.** `desktopRowWiring` (`DesktopRowWiringContext`,
  `DesktopRowWiringArgs`, `DesktopRowWiringModel`, `WiringReorder`,
  `DesktopRowPinPart`) and `desktopRowDomProps` wire one row;
  `desktopRowWiringEqual` over `DESKTOP_ROW_WIRING_KEYS` is its memo policy.
  `desktopBodySlots` (`DesktopBodySlotsInput`) orders the body: summaries top,
  pinned top, the top spacer, the rows with their extras, the bottom spacer,
  pinned bottom, summaries bottom. `desktopStickyPlan` (`DesktopStickyPlan`),
  `desktopPinEdges`, `desktopHeadCellStyle`, `desktopEdgeHeadStyle`,
  `desktopEdgeBodyStyle` and `desktopTableStyle` are the sticky, pin and
  min-width rules. `desktopHeaderLeaf` (`DesktopHeaderLeafContext`,
  `LeafColumn`, `LeafSortProps`), `columnHeaderControllerFor`,
  `headerSortDir` and `absoluteColumnIndex` assemble a header cell.
- **Body windows.** `chromeRenderModel` (`ChromeRenderModel`,
  `ChromeRenderModelInput`) and `SummaryCellsCache` build what the body
  renders. `isBodyEligible`, `virtualizeIgnoredOnPage`,
  `estimateBodyItemSize`, `bodySentinelCount`, `bodyCanLoadMore`,
  `fetchNextBodyPage`, `pinnedScrollRows`, `hasLoadedChildren`,
  `bodyWindowKind` (`BodyWindowKind`, `BodyChrome`),
  `resolveBodyVirtualization`, `withSourceIndices` and `rowScrollTarget` plan
  which window is armed. `WindowVirtualizer`, `asSizeEstimator`,
  `pendingListSize`, `materializeWindowRows`, `rowWindow`, `keyedWindow` and
  `EndReachedLatch` are the window math over any virtualizer.
  `readColumnViewport` and `columnWindowPlan` (`ColumnViewport`,
  `ColumnWindowPlan`) window the columns; `RowPairMeasureController`
  measures a row with its open detail panel.

### The builder tier

`@adapttable/react/adapter` publishes what the eight kits are made of, for
anyone wiring a ninth ([build an adapter](./building-an-adapter.md)). App code rarely reaches for these; each is here because
an adapter or a plugin genuinely needs it.

| Name                                                                                                                                     | What it is                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useTableEngine(options)`                                                                                                                | Subscribe a React tree to one `TableEngine`. Two calls are two isolated tables.                                                                                                    |
| `revisionToken(revisions)`                                                                                                               | Collapse the four revision counters into one comparable string.                                                                                                                    |
| `engineSearchText(row)` / `cellSortValue` / `resolveColumnPath`                                                                          | The engine's default searchable text, its sort-value resolution, and a column's `i18n` path.                                                                                       |
| `FeatureRegistration` / `NeutralFeatureHost` / `currentFeatureHost()` / `runWithFeatureHost`                                             | How a feature registers with the host, and the ambient host a registration runs against.                                                                                           |
| `collectFeatureNotices(input)` / `CollectFeatureNoticesInput`                                                                            | The dev-time notices a table raises when a feature is asked for something it cannot do.                                                                                            |
| `groupedEntriesForStrategy(options)` / `GroupedEntriesForStrategyOptions` / `groupingComputationKind` / `GroupingComputationKind`        | Which grouping computation a view needs, and the entries it produces.                                                                                                              |
| `groupingDragKey` / `moveGroupingKey` / `moveGroupingKeyBy` / `removeGroupingKey` / `hasGroupingColumnDrag` / `GROUPING_COLUMN_DND_MIME` | Reordering the grouping panel's keys by pointer or keyboard.                                                                                                                       |
| `EMPTY_COLUMN_LAYOUT` / `applyColumnOrder` / `applyColumnNames` / `declaredColumnLayout` / `declaredColumnName`                          | The column-layout value and the pure functions that move it.                                                                                                                       |
| `MIN_COLUMN_WIDTH` / `MAX_COLUMN_WIDTH` / `FALLBACK_PIN_WIDTH`                                                                           | Resize clamps, and the width a pin assumes when a column declares none.                                                                                                            |
| `responsiveColumns(...)` / `ResponsiveColumns` / `ResponsiveFit`                                                                         | Which columns survive at a given width, and what had to be dropped.                                                                                                                |
| `flattenReactColumnTree` / `resolveNeutralColumnHeaders` / `columnLetter`                                                                | Flatten a grouped column tree, resolve neutral headers, and the spreadsheet letter for an index.                                                                                   |
| `resolveAssembly(...)`                                                                                                                   | The desktop table assembly a kit renders from.                                                                                                                                     |
| `readEditableCellValue` / `stepEditableCell`                                                                                             | Read the value under an editable cell, and step the editor to the next one.                                                                                                        |
| `contextMenuItems(...)` / `ContextMenuModelOptions`                                                                                      | The context-menu model, before a kit draws it.                                                                                                                                     |
| `RowPinLookup` / `RowReorderDigest`                                                                                                      | Pin membership by row id, and the memo digest a reorder compares.                                                                                                                  |
| `FilterEngine` / `FILTER_ENGINE_IMPL` / `FILTER_PREFIX` / `withFilterType` / `isEmptyFilterValue` / `applyFilterExtends`                 | The filter engine behind the declarative filters, its param prefix, and the helpers that extend it.                                                                                |
| `applyQuerySupport` / `applyGroupLeafSelection` / `appendByKey`                                                                          | Narrow a query to what an endpoint supports, apply a leaf selection, append keyed entries.                                                                                         |
| `DEFAULT_ROW_SIZE_PX` / `MOBILE_BREAKPOINT_PX` / `VIRTUAL_OVERSCAN` / `MAX_LIMIT`                                                        | The row-height estimate, the mobile breakpoint, the virtualizer overscan, and the page-size ceiling.                                                                               |
| `CssProperties` / `ElementRef` / `isRtlElement` / `isBrowser` / `safeLocalStorage` / `safeSheetName` / `resetDevWarnings`                | Style and environment helpers: a style object, a ref that may be a callback, direction, environment probes, a spreadsheet-safe sheet name, and the dev-warning reset a test calls. |
| `AgentHttpError` / `openAiToolNameMap` / `FakeSocket`                                                                                    | The HTTP bridge's structured failure, the reversible OpenAI tool-name map, and the in-memory socket the realtime tests drive.                                                      |

### Utilities

- `useTableVirtualization(options): TableVirtualization` — headless row/card
  windowing: page scroll by default, element scroll inside a `maxHeight` box.
- `useInfiniteScroll(options)` — IntersectionObserver sentinel ref that
  auto-loads the next page in infinite mode.
- `useScrollToTableTop(options)` — sticky-chrome-aware scroll restoration.
- `useDebounce(value, ms)`, `useMediaQuery(query)`, `useIsMobile()`,
  `usePrefersReducedMotion()`, `useColorScheme(preference)`.

- `useExportHandler(handler)` — binds the Export button: makes a host-handled
  export single-flight and reports `exportBusy`. From `@adapttable/react/adapter`.

Building blocks for columns, rows and queries:

- `computed({ key, deps, value, format })` — a derived column, cached per row,
  consistent across display, sorting, filtering and export. See
  [columns](./columns.md).
- `aggregate(spec, options)` — builds the `summaryRow` / `groupAggregates`
  mapper. See [row grouping](./row-grouping.md).
- `applyRowPatches(rows, patches, getRowId)` with `insertRow` / `updateRow` /
  `upsertRow` / `removeRow` — apply changes without a refetch, preserving row
  identity. `applyRowPatchesWithLog` returns the `RowPatchLog` /
  `RowPatchEvent`s; `rowPatchLog` reads the log `applyRowPatches` attaches
  (spreading the array drops it). See [cell editing](./cell-editing.md).
- `tableQueryKey(query, options)` / `tableQueryBaseKey(query, options)` —
  stable cache keys for TanStack Query or SWR. See
  [data tiers](./data-tiers.md).

**Headless cell editing.** `useCellEditing` is the state machine (one active
cell, a draft string, the Enter/Escape/Tab flow) and returns
`CellEditingState`; `EditableCellGate` / `EditableCellGateProps` is the
activation wrapper every adapter renders, with `EditableCellControls` /
`EditableCellActivateControlProps` / `EditableCellConflictButtonProps` on
the main entry for the kit activate control and conflict / undo buttons. The
adapter entry names those three contracts `EditableCellSlots`,
`EditableCellActivateProps` and `EditableCellButtonProps`. A commit arrives as
`CellEditCommit` and the active address as `CellEditTarget`. The keyboard
vocabulary is `CellEditKeyAction` / `CellEditKeyOutcome` /
`CellEditNavigation`. A custom editor receives `EditableCellController` /
`EditableCellEditorCtrl` and an `EditableCellMode`; `EditableCellEditing` is
the bundle adapters get from the chrome. `MultiSelectEditorChrome` /
`MultiSelectEditorChromeProps` is the multi-select editor for kits whose select
holds one value — a named group of the kit's own checkboxes, filled through
`MultiSelectEditorSlots` / `MultiSelectEditorCheckboxProps`. `CellEditor` / `CellEditorOption`
describe the column's `editor` descriptor, resolved by `resolveCellEditor` and
`normalizeEditorOptions`, with drafts parsed by `parseCellEditValue`. Beyond
text, number and select it names `boolean`, `date`, `datetime`, `time` and
`multi-select`: `editorInputType` maps one to its input's `type`,
`isBooleanEditor` / `isSelectEditor` / `isMultiSelectEditor` tell them apart,
`booleanDraft` / `isDraftChecked` and `formatMultiDraft` / `readMultiDraft`
(joined by `MULTI_SEPARATOR`) are the draft shapes those two hold, and
`commitBooleanDraft` / `multiDraftFromSelect` from `@adapttable/react/adapter`
are the draft helpers the kits use for those two. Each adapter draws the
checkbox and multi-select with its own controls. A ninth kind,
`{ type: "custom", render }`, is a host's own component:
`CustomCellEditorRender` is the callback and `CustomCellEditorCtrl` what it
receives (`draft`, `setDraft`, `commit`, `cancel`, `onKeyDown`, `onBlur`,
`focusRef`, plus the validation trio), with `isCustomEditor` telling it apart.
A cell whose value moved under the draft also carries
`CustomCellEditorConflict` — the incoming value and the two ways out of it —
so an editor can put the choice inside its own surface; the table draws its
notice either way, in cell, row and batch editing alike.
`EditableColumnLike` is the minimal column shape editing reads, and
`isCellEditable` / `hasEditableColumns` are the two predicates the chrome uses.

**A save the reader can see.** `onCellEdit` may return a promise;
`useCellSaveState(options)` (`UseCellSaveStateOptions` in, `CellSaveState` out)
tracks it, exposing a `CellSaveStatus` per cell and a `FailedCellSave<TRow>` —
the previous row, the attempted value and the message — for one that rejected.
`onEditRollback` puts the row back and `formatEditError` words the failure;
`labels.undoEdit` names the control the failed cell offers.

**Editing a row as one unit.** `rowEditing` + `onRowEdit` change the commit unit
from a cell to a row: `useRowEditing(options)` (`UseRowEditingOptions` in,
`RowEditingState` out, holding `RowEditDrafts`) opens every editable field
together and hands the host one patch of what changed. `RowEditCell` (`RowEditCellProps`) and `rowEditControls`
(`RowEditControlsOptions` in, `RowEditControls` out) stay on
`@adapttable/react/adapter`. Each adapter mounts `RowEditActions`
(`RowEditActionsProps`) over `RowEditActionsChrome` /
`RowEditActionsChromeProps` / `RowEditActionsSlots` / `RowEditButtonProps`;
`labels.editRow` and `labels.saveRow` name them, as accessible names over each
kit's own pencil, check and cross; `rowEditIcons` (`RowEditIcons`) replaces a
glyph with your own node, or `false` to show the label as text. A row action
marked `editsRow`
becomes that trigger instead: `resolveRowEditTrigger(actions, rowEditing, row, rowId)`
(`RowEditTrigger` out) wires it to the row's form and reports whether the
built-in control still draws itself. An incoming row under an open form asks the
same question a cell does, of every field that moved: `useEditConflict` finds
them through `reconcileRow` (`ReconcileLiveRowEdit` in) and `isRowConflict` —
and across a batch through `reconcileBatch` (`ReconcileLiveBatchEdit` in),
`CellConflictAsk` is what one field's notice needs and `EditConflictChange`
names each field that moved,
and `rowEditConflict` (`RowEditConflict` out) tells the row's controls an
answer is outstanding.

**Changing many rows at once.** `batchEditing` + `onBatchEdit` hold every change
until one save: `useBatchEditing(options)` (`UseBatchEditingOptions` in,
`BatchEditingState` out) counts pending ROWS, marks changed cells, and produces
the `BatchRowEdit<TRow>[]` — `{ row, rowId, patch }` — the host receives in a
single call. `BatchEditCell` (`BatchEditCellProps`) renders a field per editable
cell. Each adapter mounts `BatchEditBar` (`BatchEditBarProps`) over
`BatchEditBarChrome` / `BatchEditBarChromeProps` / `BatchEditBarSlots` /
`BatchEditButtonProps`; `labels.pendingRows`, `labels.saveAll` and
`labels.cancelAll` name them.

**Lifecycle events.** `onEditStart`, `onEditCancel`, `onEditCommit`,
`onValidationFail` and `onEditError` observe a commit; they never own it. The
shared payload is `EditEvent<TRow>` (`row`, `rowId`, `columnKey`, `value`,
`previousValue`, `unit` of `EditUnit` `"cell" \| "row" \| "batch"`, optional
`error`). `EditEventHandler<TRow>` is the callback shape and `EditLifecycle<TRow>`
the five together. `useCellEditing` accepts `UseCellEditingOptions` for start
and cancel; a throw from any handler is swallowed so analytics cannot rewind a
commit. The same events fire on a mobile card — the commit unit does not change
with the layout.

**Live-update conflicts.** A refetch or a websocket that changes the row under
an open editor is a conflict, not a discard. `onEditConflict` (`EditConflictHandler<TRow>`)
receives an `EditConflict<TRow>` (`row`, `previous`, `rowId`, `columnKey`,
`draft`, `incomingValue`, `previousValue`) and may return `"keep"` or `"take"`
(`EditConflictChoice`); returning nothing defers to `editConflictPolicy`
(`EditConflictPolicy`, default `"ask"`). `"ask"` surfaces Keep mine / Take
theirs on the same channel validation already owns (`aria-describedby`,
`data-conflict`). `rowVersion` makes any version change a conflict, not only the
edited column. `useEditConflict` (`EditConflictState` in, `ReconcileLiveEdit` the
inspect input) is the headless state; `liveRowChanged` is the comparison.
`labels.editConflict`, `labels.keepMine`, `labels.takeTheirs` and
`labels.theirsValue` name the notice — `theirsValue` is the incoming cell
so Take theirs is a choice, not a blind swap.
The same notice appears on a mobile card.

**Adding, duplicating and deleting rows.** `rowActions(actions?, handlers?)`
takes the host's row actions and `RowMutationHandlers`. `onAddRow` puts an Add
control in the toolbar; `onDuplicateRow` and `onDeleteRow` put icon-only
Duplicate row and Delete row on every row, after the host's own actions, under
the keys `DUPLICATE_ROW_ACTION_KEY` and `DELETE_ROW_ACTION_KEY`. The labels are
the tooltip and accessible name. A delete confirms first unless
`confirmDeleteRow: false`. `useRowMutations(options)` (`UseRowMutationsOptions`
in, `RowMutationsState` out, taking the `RowMutationHandlers`) is the state
behind them; `labels.addRow`, `labels.duplicateRow`, `labels.deleteRow` and
`labels.deleteRowConfirm` name them, and `labels.rowActionsMenu` names the
3-dot trigger when `rowActionsLayout="menu"`. The table stores nothing — a new
row arrives through the source like any other. See [row actions](./row-actions.md).

**Dirty marks.** `dirtyIndicators` turns them on;
`useDirtyCells(options)` (`UseDirtyCellsOptions` in, `DirtyCellState` out) holds
which cells hold an unconfirmed change, with `isDirty` / `isRowDirty`, a `count`,
and `confirm` / `confirmRow` / `confirmAll` for a host that settles its own state.
`rowIsDirty(editing, rowId)` from `@adapttable/react/adapter` is what a row reads.
`cellFlashAttr` / `rowFlashSignature` are the same door for `data-flash`.

**Validation gates the commit.** A column's `validate` (`CellValidator`) judges
one value; the table's `validateRow` (`RowValidator`) judges the row an edit
would produce, with `applyEdit` saying how the edit lands on it.
`EditValidationState` carries what the table knows — which cells hold a
message, which are still checking — and reaches a kit through the editing
controller; `ValidationTarget` names the cell a check is about and
`ValidationCheckResult` is what one returned.
`resolveCommitValue(options)` is the row, column and parsed value a validator
sees before the host does. `editorValidationProps(ctrl)` from
`@adapttable/react/adapter` is the `aria-invalid` / `aria-describedby` /
`aria-busy` a kit's editor spreads, and `editorBusyProps(ctrl)` is just the busy
flag for a kit whose own input owns the other two. `stopEditKeys(event)` keeps
Enter, Escape and Tab inside the open editor: all three mean something to the
grid as well, and the editor is where the user is typing.
See [cell editing](./cell-editing.md).

**The grouped row model.** `buildGroupedFlatModel` turns rows into the flat
`GroupedFlatEntry` list adapters render (a group header or a leaf row);
`GroupAggregatesFn` is the per-group mapper, `groupValueKey` buckets a value,
`formatGroupLabel(value, blankLabel)` renders its header text,
`groupSelectionState` gives a group checkbox its tri-state over the group's
leaf ids, `groupRowLayout` places a group header's cells so each subtotal sits
under the column it totals (`GroupRowLayout` in, `GroupRowCell`s out) while
`groupAggregateEntries` lists just the numbers for a mobile card,
`windowGroupedEntries` slices the model to virtual window indices,
and `useGroupCollapse` / `GroupCollapseState` hold which groups are collapsed.
See [row grouping](./row-grouping.md).

**The export pipeline, stage by stage.** `resolveExportCsv` normalizes the
`exportCsv()` feature configuration, `exportableColumns` drops the synthetic actions column,
`resolveExportColumns` applies a column scope (`ExportColumnScope`),
`buildTableCsv` renders the text (`RowsToCsvOptions` controls delimiter, BOM
and formula escaping), and `makeExportCsvHandler` wires the lot to the toolbar
button. `ExportRowScope` names the row scopes — including `"range"`, the
highlighted cell rectangle — `ExportContext` carries the selection, full column
set and range those scopes need, `ExportInfo` is what the lifecycle hooks
receive. Handing an export to a backend sends an `ExportRequest`, whose
`ExportQuery` carries the view's search, filters, sort and grouping — with
`page` and `limit` undefined for `scope: "all"`, so "everything" cannot be
answered with one page. `onExportAll` instead receives an `ExportAllQuery`:
the page-free search, flat and nested filters, primary and multi-sort,
grouping, visible/requested column keys, format, and filename. Its
`ExportAllControls` carries an `AbortSignal` plus optional progress and message
setters; `ExportAllResult` is `{ url }` or empty.

`FetchAllExport` is the opt-in that lets the table page a server source itself,
capped at `EXPORT_FETCH_ALL_MAX_ROWS` (50,000) unless `maxRows` says otherwise;
`fetchAllExportRows` performs that unchanged browser walk. `ExportHandlerState`
is what `useExportHandler` returns — the click handler, `exportBusy`, an
`ExportStatus`, `ExportProgressState`, and the text `ExportAnnouncer` reads
out. `ExportProgressChrome` (configured by `ExportProgressChromeProps`) maps
that shared state into an adapter's required `ExportProgressSlots`;
`ExportProgressSurfaceSlotProps`,
`ExportProgressAction`, and `ExportProgressDownload` type the kit-owned
surface. Terminal states expose `onDismiss` / a Dismiss action; busy work
keeps Cancel only. `LiveRegion` (with `LiveRegionProps`) is the polite region underneath
it and `GridFocusAnnouncer`'s, and `ExportAnnouncerProps` types the announcer
itself. See [browser and server-built exports](./exporting.md).

**Lean live stubs.** A ninth adapter that mounts chrome by hand still has to
hand the table a find/grid/export/history object when those features are
off. `DISABLED_FIND`, `DISABLED_EXPORT`, `disabledHistory` and
`windowedTableAria` are the inert shapes the shell already uses — so the
adapter root never imports the hooks.

**High contrast.** `ForcedColorsStyle` (and `ensureForcedColorsStyles`, which
it calls) inject `FORCED_COLORS_CSS` once per page so Windows High Contrast
and `prefers-contrast: more` keep focus, selection, dirty cells, validation
and find hits visible as outlines. Adapters mount it; app code rarely needs
to. See [accessibility](./accessibility.md).

**Status announcements.** Sorting, filtering and paging rewrite the body with
nothing a screen reader can perceive, so the table says what changed through one
polite region. `useDataTableShell` returns the message as `statusAnnouncement`
and adapters render it with `TableStatusAnnouncer` (`TableStatusAnnouncerProps`)
beside their table, so the region is in the DOM before it has anything to say.
Custom markup composes the message itself with `useTableStatusAnnouncement`
(`TableStatusAnnouncementOptions` in — the row set, the page window and the
sorted column). The sort sentence comes from the `sortedBy` and `sortingCleared`
labels; the counts reuse `showing`, `pageOf` and `noResults`, so what a user
hears matches what the footer shows. See
[accessibility](./accessibility.md).

**File formats.** An `ExportWriter` turns an `ExportWriteContext` — an
`ExportTable` of values resolved once by `buildExportTable`, plus the filename —
into an `ExportPayload`, which `downloadExportFile` hands to the browser.
`csvWriter` is the built-in one, and `matrixToCsv` writes CSV from values a
caller assembled itself. `exportButtonLabel` gives the button a caption naming
the format it produces — `labels.exportCsv` for CSV, `labels.exportFile(format)`
for anything else. `@adapttable/core/xlsx`
adds `xlsxWriter` for real spreadsheets — typed numbers, booleans and dates,
basic styling, group/tree outline and aggregate rows, no new dependency, and
a separate entry so a CSV export never ships it — with `buildTableXlsx`
underneath for building a workbook by hand. An `ExportTable` may carry
`rowMeta` (`ExportRowMeta`, `ExportRowRole`) and `widths` when the view is
grouped or a tree; a flat table omits them. `buildTableXlsx` accepts that
view as `ExportViewEntry` rows — group headers, leaves and aggregates —
so a host building a workbook by hand can pass the same shape the table
does. `viewFromGroupedEntries` and `viewFromTreeEntries` build that view
from the grouping or tree model, `filterExportView` drops groups a scope
emptied, `exportViewFromChrome` picks which model is showing, and
`summaryExportValues` turns a `summaryRow` into file values. See
[customization](./customization.md#spreadsheet-xlsx-export).

**PDF export and print layout.** `@adapttable/core/pdf` adds `pdfWriter` for
the export button and `buildTablePdf` for a host assembling rows by hand.
Print is a different verb: `openPrintLayout` (an `ExportTable`) and
`printTable` (rows and columns) load `buildPrintDocument` into a hidden
iframe. `buildPrintTableHtml` is the `<table>` alone; `printStyles` is the
stylesheet. `PrintLayoutOptions` / `PdfWriterOptions` / `PrintPageSize` /
`PrintPageBreak` configure title, direction, paper and how groups meet a
page boundary. Both option types take `font` — a
TrueType file as bytes — which the PDF writer subsets and embeds so the
download draws Arabic, CJK or any script the built-in face cannot; Arabic
is shaped into its contextual forms and reordered right to left. See
[PDF export and print layout](./export-pdf.md).

**Sparkline columns.** `@adapttable/react/sparkline` adds `Sparkline` /
`sparklineColumn` so a cell can draw a bar, line or area chart without a
chart library and without pulling the mark into the base bundle.
`SparklineProps` / `SparklineKind` / `SparklineColumnSpec` type the
surface. `finiteSparklineValues` drops non-finite points, `sparklineSummary`
is the default accessible label, and `sparklineExportValue` writes the
series as text so CSV and xlsx never get an SVG. See
[sparkline columns](./sparkline.md).

**Row patches.** `RowPatch` is the union applied by `applyRowPatches`, with
`InsertPatch`, `UpdatePatch`, `UpsertPatch` and `RemovePatch` as its members.
`applyRowPatchesWithLog` returns a `RowPatchLog` of `RowPatchEvent`s;
`rowPatchLog` reads the log attached to the result array (a spread copy
drops it). **Incremental re-evaluation.** `createIncrementalView` builds
an `IncrementalView` from an `IncrementalViewConfig`; `applyRowPatchesToView`
and `applyRowPatchLogToView` re-run search, filters, sort, grouping and
aggregates for touched rows only. `configureIncrementalView` merges
grouping / summary extras without walking the set when only those
changed. `incrementalViewOf` / `attachIncrementalView` link a derived
array to the snapshot (`incrementalViewConfig` reads it back);
`incrementalSearchText` is the default projector.

**Live row patches.** `useRowPatchStream` from `@adapttable/react/stream`
(`UseRowPatchStreamOptions` in, `RowPatchStreamState` out) binds a
WebSocket or SSE endpoint to the rows a host owns: frames become ordinary
row patches and go back through the host's own setter.
`openRowPatchStream` (`OpenRowPatchStreamOptions`, `RowPatchStreamHandle`,
`RowPatchStreamReconnect`) is the connector without React, over a
`StreamSocket` / `StreamSocketEvent` a host can supply itself.
`parseRowPatchFrame` reads the table's patch shape as JSON and drops
anything malformed. `RowPatchStreamStatus` is what the connection is
doing, with `isStreamLive` and `isStreamSettled` as the two questions
worth asking. `useChangedCellFlash` (`UseChangedCellFlashOptions` in,
`ChangedCellFlashState` out) tracks the cells a patch just changed so
the host can pass `isCellFlashing` — a pulse, not a locate-the-row
highlight, and never against `prefers-reduced-motion`. See
[realtime](./realtime.md).

**Row reordering.** `rowReorder(handler, options)` from
`@adapttable/<kit>/row-reorder` arms flat, grouped, and tree reorder.
`RowReorderHandler` is an ordinal write: dataset positions for a flat source,
sibling positions for grouped/tree rows. `RowReorderOptions` adds
`movePolicy` (`RowMovePolicy`: `"auto" | "confirm" | "never"`),
`onGroupMove` (`RowGroupMoveHandler`), `onTreeMove`
(`RowTreeMoveHandler`), and async `confirmMove` (`RowMoveConfirmHandler`).
Requests are `RowMoveRequest`; group destinations use `RowGroupRef` /
`RowGroupLevel`, and tree destinations use `RowTreeParentRef`.
`treeMoveCreatesCycle` guards re-parenting and `rowDropPosition` resolves the
`RowDropPosition` before/inside/after pointer zone. `RowReorderDecision` is the
headless seam's reorder/move/reject result.

`ROW_REORDER` is the `FeatureStateKey` its provider publishes under, so custom
chrome reads `RowReorderState` (`TableRowReorderState` from the main entry)
with `useFeatureState(ROW_REORDER)`. `hostConfirmPending` is the inert-controls
flag while a host-owned `confirmMove` is outstanding.
`applyRowReorder`, `datasetIndex`, `useRowReorder`,
`rowReorderSignature`, `rowReorderDropStyle`, `REORDER_COLUMN_KEY`,
`REORDER_COLUMN_WIDTH`, and `ROW_DND_MIME` are the headless primitives.
Nested move menus use `RowMoveMenuModel` / `RowMoveTarget`; the adapter seam is
`RowMoveMenuSlotProps`, `RowMoveMenuItemProps`, and
`RowMoveConfirmationProps`. Each adapter mounts
`RowReorderHandle` / `RowReorderHandleProps` and
`RowReorderButtons` / `RowReorderButtonsProps` over
`RowReorderHandleChrome` / `RowReorderHandleChromeProps` /
`RowReorderHandleSlots` / `RowReorderHandleSlotProps` and
`RowReorderButtonsChrome` / `RowReorderButtonsChromeProps` /
`RowReorderButtonsSlots` / `RowReorderMoveButtonProps`.
`RowReorderAnnouncer` stays on `@adapttable/react/adapter`. Move-menu,
confirmation, success, policy, sort, and cycle labels extend
`RowReorderLabels` / `TableLabels`. See
[row reordering](./row-reordering.md).

**Row and column spanning.** `getCellSpan` / `ColumnDef.colSpan` / `ColumnDef.rowSpan` produce a per-row `TableBodyCell` list (`BodyCell` on the adapter entry) through `buildBodyCells`, `cellsForRow`, `coveredAddressSet`, `rowSpanSignature`, `spanningArmed`, `bodyCellsHaveRowSpan` and `cellSpanMark`. `cellSpanAppearance` (`"merged"` / `"plain"`) is how the origin cell is painted. Arrow keys skip a covered cell; CSV writes the origin once. Types: `GetCellSpan`, `GetCellSpanArgs`, `CellSpanRequest`, `CellSpanAppearance`, `TableBodyCell`. See [row and column spanning](./row-spanning.md).

**Full-width and separator rows.** `extraRows` is a list of `ExtraRow` (`kind: "separator" | "fullWidth"`, `beforeRowId`, `render`); the spliced main-entry shape is `TableExtraEntry` (`ExtraEntry` on the adapter entry). A named extra (`beforeRowId`) stays a full-width row in front of that person through reorder and pin; when a Team span would paint through it, `EXTRA_OVER_SPAN_STYLE` sits the extra on top of that column. `insertExtraRows` / `insertExtrasBeforeRows` / `extraRowsForSection` / `isExtraEntry` / `extraRowsArmed` / `EXTRA_ROW_PARTS` are the kit helpers. Label: `rowSeparator`. See [full-width and separator rows](./full-width-rows.md).

**Row styling and heights.** `rowStyle` / `rowHeight` resolve through `resolveRowStyle` / `resolveRowHeight`. Height wins over `style.height`. `rowStyleSignature` is the memo digest; `rowStyleArmed` is whether either hook was passed; `estimateFromRowHeight` is the virtualizer estimator. Types: `RowStyle`, `RowHeight`. See [row styling and heights](./row-styling.md).

**Row pinning.** `pinnedRowIds` / `onPinnedRowIdsChange` take a `RowPinState` (`{ top, bottom }` of `RowPinSide`). `applyRowPin(state, rowId, side)` is the in-memory helper; `partitionPinnedRows` splits a list into top / scroll / bottom; `EMPTY_ROW_PIN_STATE` is the empty lists. `useRowPinning` returns `RowPinningState`; `rowPinSignature` is the memo digest. Action keys: `PIN_TOP_ACTION_KEY`, `PIN_BOTTOM_ACTION_KEY`, `UNPIN_ROW_ACTION_KEY`. URL: `useRowPinningUrlState` (`UseRowPinningUrlStateOptions` / `UseRowPinningUrlStateResult`) writes `rowPin=id:top,id:bottom`. Labels: `pinToTop`, `pinToBottom`, `unpinRow` (`RowPinLabels`). `rowSourceIndex(entry)` is the dataset index when pinning remapped the window. From `@adapttable/react/adapter`: `pinnedRowStickyStyle` / `pinnedRowCellStyle`, `pinnedRowPart` / `pinnedRowSticky`, `orderedCardEntries`, `useOffsetHeight`, `PINNED_TOP_PART` / `PINNED_BOTTOM_PART`. See [row pinning](./row-pinning.md).

**Pinned summary rows.** `pinnedSummaryRows({ top, bottom })` (`PinnedRows`) sticks host-owned objects outside the row model — sort, filter, grouping, pagination and selection never see them, so they coexist with grouped and tree tables. Identities are `pinnedSummaryRowId(side, index)` (`PINNED_SUMMARY_KEY_PREFIX` + `:side:index`); `PinnedSummaryEntry` / `isPinnedSummaryRowId` / `pinnedSummarySideFromId` / `pinnedSummaryEntries` / `allPinnedSummaryEntries` / `resolvePinnedRows` / `EMPTY_PINNED_ROWS` are the helpers. Parts: `PINNED_SUMMARY_TOP_PART` / `PINNED_SUMMARY_BOTTOM_PART` via `pinnedSummaryPart`. Labels: `pinnedSummaryRow`, `pinnedSummaryTop`, `pinnedSummaryBottom`. Not URL or Saved Views — the objects are host data. See [pinned summary rows](./pinned-summary-rows.md).

**Filter internals.** `FILTER_TYPES` lists the built-in types, `filterLabel`
resolves a filter's caption, `filterStateKeys` names the URL keys one filter
owns, `hasActiveHeaderFilter` says whether any of them holds a value worth
marking the column with — a cleared text field leaves `""` and a cleared
multi-select leaves `[]`, and neither is a filter — `FilterRuntime` is what
`buildFilterRuntime` returns, and
`ResolvedFilterOptions` is what `useFilterOptions` resolves.
`isDeclarativeFilters` tells the array form from JSX. A form reads its values
through `FilterFormSource` with `listFilterValues` and `scalarFilterText`.
Count filters: `COUNT_OPERATORS` / `COUNT_OPERATOR_SYMBOL` / `CountOperator`,
state via `countFilterExtra` / `countFilterStateFromExtra` / `CountFilterState`
/ `isCountFilterComplete` / `clearCountFilterExtra` /
`sanitizeCountFilterParams`, and a chip label from `countFilterChipLabel`.
Range widgets: `useRangeFilterWidget` / `RangeWidgetState` /
`RangeFieldWidget` / `RangeOp` / `RangeOpArity` / `RANGE_SUFFIXES` /
`RANGE_OPS` / `RANGE_OP_LABEL_KEYS` / `RangeOpLabelKeys` /
`writeRangeFilter`. Operator registry: `TEXT_OPS` /
`NUMBER_OPS` / `DATE_OPS` / `TEXT_OP_LABEL_KEYS` / `NUMBER_OP_LABEL_KEYS` /
`DATE_OP_LABEL_KEYS` / `FilterOp` / `TextOp` / `NumberOp` / `DateOp` /
`FILTER_OP_SUFFIX` / `filterOpKey` / `isFilterOpKey` /
`isValuelessFilterOp` / `isListFilterOp` / `isBetweenFilterOp` /
`parseTextOp` / `parseNumberOp` / `parseDateOp` /
`readFilterOp` / `parseListOperand` / `parseNumberList` / `isEmptyRowValue` /
`formatFilterChip` / `filterOpLabel` / `useTextFilterWidget` /
`TextFieldWidget` / `useBooleanFilterWidget` / `BooleanFieldWidget` /
`BooleanChoice` / `parseBooleanChoice` / `coerceBooleanValue`.
Relative dates: `RELATIVE_NAMED` / `RELATIVE_PRESETS` /
`RELATIVE_PRESET_LABEL_KEYS` / `RelativeDateToken` / `RelativeDateRange` /
`RelativePreset` / `parseRelativeToken` / `isRelativeDateToken` /
`countedRelativeToken` / `splitRelativeToken` / `joinRelativeToken` /
`relativeTokenLabel` / `resolveRelativeRange`.
AND/OR trees: `FILTER_TREE_PARAM` / `FILTER_TREE_VERSION` /
`parseFilterTree` / `serializeFilterTree` / `isActiveFilterTree` /
`evaluateFilterTree` / `conditionToExtra`. Mutations:
`emptyFilterTree` / `addFilterTreeCondition` / `addFilterTreeGroup` /
`removeFilterTreeNode` / `replaceFilterTreeNode` /
`setFilterTreeCombinator` / `walkFilterTreeConditions` /
`FilterTreeNode`. Builder (on each adapter): `FilterTreeBuilder` /
`FilterTreeBuilderProps`. Layout (on `@adapttable/react/adapter`):
`FilterTreeChrome` / `FilterTreeChromeProps` / `FilterTreeClassNames` /
`FilterTreeSlots` / `FilterTreeSelectProps` / `FilterTreeInputProps` /
`FilterTreeButtonProps` / `FilterTreeDisclosureProps` / `FilterTreeOption`.
Chips:
`useFilterTreeChips` / `UseFilterTreeChipsOptions` /
`filterTreeChipLabel`. Checklist (on each adapter): `ChecklistFilter` /
`ChecklistFilterProps`. Layout (on `@adapttable/react/adapter`):
`ChecklistChrome` / `ChecklistChromeProps` / `ChecklistClassNames` /
`ChecklistSlots` / `ChecklistSearchProps` / `ChecklistButtonProps` /
`ChecklistCheckboxProps`. Headless: `useChecklistFilter` /
`ChecklistFilterState` / `collectChecklistValues` / `ChecklistValue` /
`CHECKLIST_VIRTUALIZE_AT` / `CHECKLIST_ITEM_HEIGHT` /
`CHECKLIST_LIST_HEIGHT`. Header row (on each adapter): `FilterHeaderRow` /
`FilterHeaderControl` / `FilterHeaderRowProps` / `FilterHeaderControlProps`
(`closeOnSelect`).
Layout (on `@adapttable/react/adapter`): `FilterHeaderChrome` /
`FilterHeaderControlChrome` / `FilterHeaderChromeProps` /
`FilterHeaderControlChromeProps` / `FilterHeaderClassNames` /
`FilterHeaderSlots` / `FilterHeaderSearchProps` / `FilterHeaderSelectProps`
/ `FilterHeaderRangeProps` / `FilterHeaderMultiProps` / `FilterHeaderOption`.
Helpers: `filterDefForColumn` / `headerFilterStickTop` /
`resolveFilterMode` / `toolbarShowsFilters` / `FilterChromeMode`. Facets: `computeFilterFacets` /
`rowsExcludingFilter` / `FacetMap` / `FacetCounts`. The tree is a `QueryFilterGroup` of
`QueryCondition`s (`isFilterGroup` narrows a child). See
[filtering](./filtering.md).

**Keyboard cell navigation.** `useGridFocus(options)` is the focus grid —
`UseGridFocusOptions` in, `GridFocusState` out (`getGridProps`,
`getCellPropsAt`, `getRowPropsAt`, `getColumnHeaderProps`, `selectColumn`,
`focusCell`, `announcement`, `enabled`), and
composing `cellNavigation()` wires it for you. The move arithmetic is separate
and pure: `moveGridFocus(from, move, bounds)` over a `GridCell` and
`GridBounds`, with `GridFocusMove` naming the intents and
`gridFocusMoveForKey(press, dir)` maps a `GridKeyPress` to one (applying the
RTL swap). `sameGridCell` compares addresses. `GRID_CELL_ATTR` /
`gridCellAttr(cell)` are the `data-grid-cell` attribute focus uses to find a
cell in the DOM. `GridFocusAnnouncer` / `GridFocusAnnouncerProps` render the
live region and come from `@adapttable/react/adapter`.
`contextMenuCopyTarget(gridFocus, target)` returns a `ContextMenuCopyTarget`
saying what a context-menu Copy should take — the clicked cell, or the
selection it landed inside — resolving the address through
`gridFocus.cellAt(rowId, columnKey)` so the sort, filter, page and virtual
window are all followed. See [cell navigation](./cell-navigation.md).

**The column-selection checkbox.** `columnSelectionCheckbox` adds a checkbox to
every column header that selects that column — the touch and screen-reader path
into the same state Ctrl/Cmd+click reaches. `GridFocusState` resolves it:
`columnCheckbox` is true when the option and `cellNavigation` both are,
`isColumnSelected(col)` answers whether the selection is exactly that column,
and `toggleColumn(col)` selects it or clears. The control is core chrome with a
kit checkbox in it — `ColumnSelectCheckboxChrome` /
`ColumnSelectCheckboxChromeProps` / `ColumnSelectCheckboxProps` /
`ColumnSelectSlots` from `@adapttable/react/adapter`, with
`columnSelectLabel(label, column)` composing `labels.selectColumn` and the
column's name. See [cell navigation](./cell-navigation.md).

**Cell range selection.** Shift with a movement key or a shift-click extends a
rectangle from its anchor. `CellRange` is the pair of corners and
`CellRangeBounds` the sorted edges; `cellRangeBounds` sorts a range dragged up
or left, `isInCellRange` tests membership, `cellRangeSize` multiplies rather
than enumerating, `extendCellRange` moves the head while keeping the anchor,
`singleCellRange` / `isSingleCell` cover the one-cell case, and
`cellRangeIndices` lists the rows and columns for an exporter. See
[cell navigation](./cell-navigation.md).

**Clipboard.** `clipboardRangeText(options)` turns the selected rectangle into
the tab-separated text a spreadsheet reads (`ClipboardRangeOptions` in), and
`writeClipboardText` puts it on the clipboard, answering whether it landed
rather than throwing. Coming back the other way, `readClipboardText` returns the
clipboard's text or `null` when the browser refuses it, `parseClipboardTable`
parses tab-separated text into a grid of raw strings (quoted tabs and newlines
intact), and `pasteRangeEdits(options)` maps that grid onto a range
(`PasteRangeOptions` in) as `CellEdit` values — one per cell, already through
the column's `parseValue`, ready for the same handler an inline edit uses. `cellPasteHandler(options)`
resolves who receives them — `onCellPaste` when given, otherwise `onCellEdit`
one cell at a time, `undefined` when the table takes no edits at all
(`CellPasteHandlerOptions` in). On `<DataTable>` the props are `onCellPaste` and
`onCellCut`. See [cell navigation](./cell-navigation.md).

**Fill handle.** `fillDirection(source, to)` says which way a drag from the
selection's corner is filling (`FillDirection`, or `null` inside the selection),
`fillTargetRange(source, to)` is the rectangle it would cover — what the preview
highlights — and `fillRangeEdits(options)` turns the gesture into `CellEdit`
values (`FillRangeOptions` in), continuing an arithmetic series when the source
is one and repeating otherwise. `cellFillHandler(options)` resolves the
recipient (`CellFillHandlerOptions`), and `batchEditHandler(batch, onCellEdit)`
is the rule both it and `cellPasteHandler` follow. Adapters export their
kit-owned `FillHandle` and render it over `FillHandleChrome` /
`FillHandleChromeProps` / `FillHandleSlots` / `FillHandleSlotProps` from
`@adapttable/react/adapter`; on `<DataTable>` the prop is `onCellFill`. See
[cell navigation](./cell-navigation.md).

**Undo and redo.** `useEditHistory(options)` remembers gestures and replays
them through `onCellEdit` (`UseEditHistoryOptions` in, `EditHistoryState` out —
`undo`, `redo`, `canUndo`, `canRedo`, `clear`, `record`), with
`EditHistoryEntry` the recorded pair. `useTableEditHistory(props)` is the
table-level wiring — it takes the `editHistory` prop
(`TableEditHistoryProps`) and returns the history plus the commit channel that
records each inline edit as a one-cell gesture. `asGesture(apply, record)` wraps
a cell-edit handler as one undo entry. `asBatchGesture(apply, record)` does the
same for `onBatchEdit`, so one save is one undo. `readCellValue(row, column)` reads a
cell's current value unstringified — what an undo puts back. Compose `editHistory()` to
arm it; `editHistory({ depth, onChange })` (`EditHistoryOptions`) hands a host
an `EditHistoryHandle` — `undo`, `redo`, `canUndo`, `canRedo`, `clear`.
`editing(commit, { onDirtyChange })` reports `DirtyEdits` (`count`, `confirm`,
`confirmRow`, `confirmAll`), and `cellNavigation({ onRangeChange })`
(`CellNavigationOptions`) the selected `CellRange`, each on mount and on
change. See [cell editing](./cell-editing.md).

**Server-side grouping.** A source that declares `supports.grouping` receives
`query.groupBy` (the keys, outermost first) and, with `supports.aggregates`,
`query.aggregates` from `useQuerySource`'s `aggregates` option. It answers with
`QueryGroupRow` values — `value`, `count`, optional `aggregates`, `groups` and
`rows` — on the source's `groups` field (`QueryGroupsPage` types a whole page),
and `serverGroupEntries(options)` (`ServerGroupEntriesOptions`) lays them out as
the same entries local grouping produces. `groupLeafCount(entry)` is the count a
header shows: the server's when it grouped, the rows in hand otherwise. See
[row grouping](./row-grouping.md).

**Column sizing.** A `ColumnDef` takes `width`, `minWidth`, `maxWidth` and
`flex`; composing `fitColumns()` makes the columns share the container.
`columnFlexShares(options)` computes each flexible column's percentage
(`ColumnSizingOptions`), `columnSizeStyle(column, shares, userWidth)` is the
style a cell carries — dragged width first, then the column's own, then its
share — and `fittedTableStyle(fitColumns)` is what the `<table>` needs for
percentages to mean anything. See
[column management](./column-management.md).

**Column auto-sizing.** `measureColumnWidth(root, key)` returns the width a
column needs for its widest rendered cell — measured from the DOM by the
`data-column-key` every cell carries — and `autoSizeColumns(root, keys,
setWidth)` sizes a whole set, returning how many it could measure. A cell that
already fits is not grown again on a later click. A resize handle sizes its
own column on double-click, and the column menu's action calls
`shell.autoSizeColumns`. See [column management](./column-management.md).

**Column virtualization.** `useColumnWindow(options)` windows the horizontal
axis (`UseColumnWindowOptions` in, `ColumnWindow` out — the columns to render
and the `paddingStart` / `paddingEnd` that hold the rest open), and
`ColumnSpacer` / `ColumnSpacerProps` from `@adapttable/react/adapter` render one
of those spacers.
The render model swaps the windowed columns in, so an adapter maps over
`model.columns` the same way and renders `model.columnSpacers` either side. Compose
`virtualize({ virtualizeColumns: true })` to arm it. See
[virtualization](./virtualization.md).

**Virtualized row detail.** `useRowPairMeasurer(virtualizer, enabled)` returns
`RowPairMeasurer` — `row(index)` and `detail(index)` ref callbacks — which
report a row and its open panel as one height through the virtualizer's
`resizeItem` (`ResizableVirtualizer`). It is what lets `renderRowDetail` and
`virtualize` be used together; adapters take it as `measureRowPair` in place of
`measureElement` when the table can expand rows. See
[virtualization](./virtualization.md).

**Row grouping.** `groupBy` takes a key or an ordered list; `parseGroupBy(value)`
turns any of its forms (`GroupByInput`) into the key list and `formatGroupBy`
back into the single comma-separated value state is stored as.
`groupingPanel(groupBy?, extras?)` from each kit's `/grouping-panel` subpath
adds the interactive strip and still accepts every `GroupingExtras` option.
It publishes `GroupingPanelState`: ordered `groupBy`, the `aggregations`
model every surface reads, drag/drop and keyboard bindings, `add` / `remove`
/ `moveBy`, and `setAggregateOperation` / `addAggregate` / `removeAggregate`
/ `restoreAggregateDefaults`. A column's `aggregatable` (`false` / `true` /
`{ default?, operations }`) is the one offer the panel, the column menu, a
URL and a request all resolve. `GroupAggregateOverride` is a built-in name, a
host operation id, or `"none"`; `GroupAggregateOverrides` maps those session
choices by column. `serializeGroupAggregateOverrides` /
`parseGroupAggregateOverrides` encode both the column key and the operation
id (`encodeURIComponent`, split on the first `:`), so custom ids with
colons, commas, percents or Unicode round-trip. `serializeAggregationDerivedKey`
is the cache key for the effective set. Built-in `budget:sum` URLs
stay compatible. `withGroupAggregateOverrides` layers them over a developer
`groupAggregates` mapper and refuses a disallowed id at execution, while
`withQueryAggregateOverrides` does the same for server `query.aggregates`.
`queryAggregateOps` reads those requested functions back as the operations a
column is told about — `TableSource.groupAggregations`, which
`useQuerySource` and `useServerData` publish as of the response being drawn —
`useQuerySource` from the query's `dataUpdatedAt` read against its request,
`useServerData` from the `responseKey` a host echoes back, without which a
request it cannot place is reported as unknown. The developer's original
`aggregates` option is published separately as `queryAggregates`, so Restore
defaults never treats the current response as the initial query. An absent
key preserves the host request; `"none"` removes it only while
`readerControlAllowed` is true. `TableSource.honorsAggregates` is false when
a server groups but drops `query.aggregates`, which hides the aggregation
controls rather than letting them mutate unused local state. A column's
`formatAggregate` says how the result reads, taking the value and an
`AggregateFormatContext` — the column key, and the operation where the table
knows it. It is applied where the cell is drawn: `groupRowLayout` and
`groupAggregateEntries` take the group's `GroupAggregateOps` and hand each
cell through it, and `groupAggregateNode` does one cell for a kit that lays
out its own group rows.

Adapter authors bind the `GROUPING_PANEL` slot with
`createAdapterGroupingPanelFeature(AdapterGroupingPanelComponents)`.
`GroupingPanelChrome` takes `GroupingPanelChromeProps` /
`GroupingPanelSlotProps` and a `GroupingPanelSlots` object whose required
pieces receive `GroupingPanelSurfaceProps`, `GroupingPanelDropZoneProps`,
`GroupingPanelChipProps`, `GroupingPanelSelectProps`,
`GroupingPanelRemoveZoneProps`, `GroupingPanelAggregationItemProps`,
`GroupingPanelAggregationRemoveProps`, `GroupingPanelChecklistProps`,
`GroupingPanelChecklistOption`, and
`GroupingPanelRestoreProps`; select entries are `GroupingPanelOption`s and
native event wiring uses `GroupingDragProps` / `GroupingDropProps`.
`GroupingPanelInteractions` carries those callbacks,
`GroupingChipKeyboardProps` defines the equal keyboard path, and
`GroupingDragState` describes the active drag while `GroupingDragSource` names
its header-or-chip origin. Every kit exports its kit-owned `GroupingPanel`;
Radix additionally names `RadixGroupingPanelProps`.
Column-menu plugins return a `ColumnMenuItem`: either an ordinary action or a
`ColumnMenuChoice` made of `ColumnMenuChoiceOption`s.

`buildGroupedFlatModel(options)` walks the tree into the flat `GroupedFlatEntry`
list adapters render — each group entry carrying its `level`, its `groupBy` key,
its `path` and the leaves of its whole subtree — and `groupIndentStyle(level)`
from `@adapttable/react/adapter` is the indent every kit applies. `GroupSort`
names the orderings `groupSort` accepts (`"label"`, `"label-desc"`, `"count"`,
`"count-desc"`, or a comparator) and `GroupNode` is what it and `groupFilter`
receive: `value`, `label`, `level`, `groupBy` and the group's `leafRows`.
Paging is `groupPageSize` / `groupRowPageSize`: `useGroupPaging()` holds how
much has been revealed (`GroupPagingState`, whose `paging` is a `GroupPaging`),
the model emits a `groupMore` entry for the rest, and each adapter mounts
`GroupMoreButton` / `GroupMoreButtonProps` over `GroupMoreButtonChrome` /
`GroupMoreButtonChromeProps` / `GroupMoreButtonSlots` /
`GroupMoreButtonSlotProps`.
`groupRowParts(kind)` names the `data-adapttable-part` values for each of the
three rows a grouped body renders (`GroupRowKind`), and `GroupToggleSpacer`
holds the chevron's width on the two rows that have no chevron, so a footer
lines up with the header it closes.
Expansion is the `collapsedGroupIds` / `onCollapsedGroupIdsChange` pair —
`useGroupCollapseUrlState(options)` keeps it in the URL
(`UseGroupCollapseUrlStateOptions` in, `UseGroupCollapseUrlStateResult` out,
serialized by `readCollapsedGroups` / `writeCollapsedGroups` under
`PARAM_GROUP_CLOSED`), and the table's grouping bundle carries `expandAll`,
`collapseAll` and `collapseToDepth`. See
[row grouping](./row-grouping.md).

**Tree data.** A hierarchy the data declares, not one derived from values, so
it is a separate model from grouping. `TreeShape<TRow>` is how a host declares
it — `getChildren` for nested rows, `getParentId` for a flat list with a parent
column, `hasChildren` for children not fetched yet. `buildTreeEntries(options)`
(`BuildTreeEntriesOptions` in) flattens it into the `TreeEntry<TRow>` list
adapters render, each entry carrying its `level`, `path`, `descendantIds` and
`loading`; `useTreeExpansion(options)` holds the open set
(`TreeExpansionState`), `treeColumnKey(columns, declared?)` picks the column
that carries the chevron, and `filterTreeRows(options)` keeps a match together
with every ancestor that leads to it. `treeIndentStyle(level)` indents a cell
and `treeCardStyle(level)` a mobile card; `bodyRowEntries(rows, tree)` returns
the `BodyRowEntry<TRow>` list a body maps over, tree or flat. Each adapter
mounts `TreeCell` / `TreeCellProps` and `TreeToggle` / `TreeToggleProps`
over `TreeCellChrome` / `TreeCellChromeProps` / `TreeToggleChrome` /
`TreeToggleChromeProps` / `TreeToggleSlots` / `TreeToggleButtonProps`.
Lazy branches are
`hasChildren` + `onLoadChildren`: `useLazyChildren(options)` holds which nodes
are fetching (`LazyChildrenState`, `UseLazyChildrenOptions` in) and the tree
bundle carries `loadingIds` / `failedIds`. A server-side tree is
`supports: { tree: true }` plus `expandedIds` on `useServerData` /
`useQuerySource`, which sends the open ids as `query.expandedIds`.

**A real table under a row.** `nestedTable` takes a `NestedTableFor<TRow>` and
returns a `NestedTable` — a `label` and a `table(defaults)` that mounts the kit's
own component. `NestedTableDefaults` is what it receives: `urlSync: false`,
`searchable: false`, the parent's `density`, `labels` and the `tableLabel`.
`nestedTableDefaults(label, parent)` builds them and `nestedTableDetail(options)`
turns the declaration into the `renderRowDetail` the table places under a row
(both from `@adapttable/react/adapter`, with `NestedTableParent` for what the
parent contributes). See [tree data](./tree-data.md).

**Find in table.** `findMatches(options)` returns every cell whose text
contains the query, in absolute addresses (`FindMatchesOptions` in);
`matchKey(cell)` / `matchKeySet(matches)` make membership a constant-time
question and `stepMatch(index, total, step)` wraps the walk.
`useFindInTable(options)` is the bar's state — `open`, `query`, `matches`,
`index`, `current`, `next`, `previous` (`UseFindInTableOptions` in,
`FindInTableState` out). The query is shareable table state: pass the same
`urlAdapter` / `urlSync` / `urlKey` the table already uses and a `find` param
rides beside `q`. `FIND_URL_WRITE_DEBOUNCE_MS` is the trailing debounce on
that write (replace-state only). Each adapter mounts `FindBar` / `FindBarProps`
over `FindBarChrome` / `FindBarChromeProps` / `FindBarSlots` /
`FindSearchProps` / `FindButtonProps` / `FindButtonKind`.
`useFindFocus(current, focusCell,
selectRange)` is what takes the table's focus to the match the walk is on. Cells carry `data-cell-match` /
`data-cell-match-current`, which `isMatchedCell` / `isCurrentMatchCell` read and
`cellHighlightStyle(props, base, selected)` resolves into one background. Compose
`findInTable()` to arm it. From `@adapttable/react/adapter`,
`findButtonRender(Button)` draws a kit's toolbar Find control
(`AdapterFindButtonProps`: the toolbar props plus `onOpenFind` and `findOpen`),
`useFindState()` reads the live find state, `null` outside a table that
composed find, and `withFindMarks(base, find, firstRowIndex)` lays the match
marks over cell props built without cell navigation. See
[cell navigation](./cell-navigation.md).

**Selection statistics.** `selectionStats(options)` returns `SelectionStats` —
`cells`, `numeric`, and `sum` / `average` / `min` / `max`, each `null` when the
selection holds no numbers (`SelectionStatsOptions` in). Adapters export their
kit-owned `SelectionStatsBar` and render it over `SelectionStatsChrome` /
`SelectionStatsChromeProps` / `SelectionStatsSlots` /
`SelectionStatsSlotProps` / `SelectionStatPart` from
`@adapttable/react/adapter`; it is empty below two cells. Compose
`selectionStats()` from `@adapttable/<kit>/status-bar` to arm it. See
[cell navigation](./cell-navigation.md).

**Highlighting a row.** `useHighlight(enabled)` returns a `HighlightState`:
`flashRow(rowId)`, `flashCell({ rowId, columnKey })` (a `HighlightedCell`),
`clear()`, `isRowHighlighted` / `isCellHighlighted`, and `animated`. Marks
are keyed by row id rather than position, so one survives the sort, filter
or page change that moves the row. Flashing the same row again restarts its
clock instead of stacking. Under `prefers-reduced-motion` the mark still
appears — `animated` goes false and it holds steady, and longer, because a
steady mark is easier to miss than one that moves. Reduced motion means less
movement, not less feedback.

**`PivotPanel`** is each adapter's pre-wired configuration panel — import it
from your kit and pass `fields`, `config` and `onChange`. It is
`PivotPanelChrome` with that kit's slots already filled.

**`SavedViewsPanel`** is each adapter's pre-wired management panel — import it
from your kit and pass the views plus the five handlers. shadcn's names its own
`SavedViewsPanelProps`: the views, the five handlers, `labels`, `footer`,
`className`, and a `classNames` map merged per key over the shadcn preset. It
is the panel's whole contract, with no slot type to fill in — the kit has
already filled them.

**Saved-view storage and versioning.** `useSavedViews` takes a
`SavedViewsStore` (`list` / `save` / `remove`, all async) that replaces
localStorage, a `SavedViewVisibility` (`"private"` | `"team"`) for new views,
and a `SavedViewMigration` for views behind `SAVED_VIEW_VERSION`. Its result
adds `rename`, `move`, `setDefault`, `defaultView` and `reload`. A store's
fourth member, `reorder(names)`, is optional and persists the list's order —
without it a store keeps every other operation and `move` reorders for the
session only. See [saved views](./saved-views.md).

**The saved-views management panel.** `SavedViewsPanelChrome` from
`@adapttable/react/adapter` is a titled card listing every saved view;
`SavedViewsPanelChromeProps` takes the views, the five handlers, and an
optional `footer` rendered inside the card under the list. Applying a view is
clicking its name; rename, move, set-default and delete are an icon cluster
described by `SavedViewRowControl`, keyed by `SavedViewControlKey`.
`SavedViewsPanelSlots` names the four kit-supplied pieces —
`SavedViewsPanelSurfaceProps`, `SavedViewsPanelRowProps`,
`SavedViewsPanelInputProps` and `SavedViewsPanelEmptyProps`. Reordering is
buttons, and renaming is an inline input that Escape abandons. See
[saved views](./saved-views.md).

**Your router's URL adapter.** `routerUrlAdapter(options)` builds a
`UrlStateAdapter` from a router's current search string and its navigate;
`RouterUrlAdapterOptions` is that pair. It depends on no router, so React
Router, TanStack Router and Next.js all take two lines. See
[URL state](./url-state.md).

**Adaptive capabilities.** `@adapttable/ai` is the optional, provider-neutral
agent contract. The root exports `AGENT_SCHEMA_VERSION`, `CAPABILITY_KEYS`,
`CapabilityKey`, `WritePolicy`, `ApprovalPolicy`, `CommitPolicy`,
`RowAddressScope`, `createAgentSession`, `CreateAgentSessionOptions`,
`buildManifest`, `enabledKeys`, `guideOf`, `summaryOf`, `validateSchema`,
`eligibleSuggestions`, `assertUniqueSuggestions`, and
the types `AgentApply`, `AgentAggregateOperation`, `AgentAggregationColumn`,
`AgentAggregations`, `AgentAggregationsPatch`, `AgentCapabilityContext`,
`AgentCapabilityDefinition`,
`AgentCellEdit`, `AgentColumn`, `AgentFilter`, `AgentFilterOption`, `AgentLimits`,
`AgentManifest`, `AgentManifestAggregation`, `AgentObservation`, `AgentPolicy`, `AgentRowAddressing`,
`AgentSession`, `ApprovalOutcome`, `ApprovalResult`, `ApprovalSubject`,
`CapabilityGuide`, `CatalogEntry`,
`ExecuteError`, `ExecuteResult`, `JsonSchema`, `ResolvedRow`, `RowKeyRef`,
`RowPositionRef`, `RowReadQuery`, `RowRef`, `RowWindow`, `RowWindowRow`,
`WriteExecuteResult`, `WriteProposal`, `WriteRowResult`,
`sharedApproval`, `SharedApproval`, `ResolvedApproval`,
`agentFiltersFromDefs`, `FilterCatalogColumnPatch`,
`agentColumnsFromNeutral`, `TableAgentColumnPatch`,
`LiveObservationOptions`, `NeutralQueryOverlay`, `monotonicRevision`,
`observationFromNeutral`, `readRowsFromNeutral`, `resolveRowFromNeutral`
and `revisionToken`,
and the assistant contracts `AssistantAction`, `AssistantConversation`,
`AssistantOutcome`, `AssistantOutcomeStatus`, `AssistantPlanner`,
`AssistantProposal`, `AssistantRequest`, `AssistantSuggestion`,
`AssistantTurn`, `AssistantExchange`, `AssistantTransport`,
`AssistantTransportReply`, `AssistantTurnInput`, `AssistantSendInput`,
`AssistantResumeInput`, `AssistantResumeHandle`, `CapabilityProgress` and
`CapabilityPresentation`, plus the receipt
readers `receiptFromResult`, `receiptsFromResults`, `turnStatus` and the types
`AssistantReceipt`, `AssistantReceiptStatus`, `AssistantTurnStatus`.
`@adapttable/ai-react` exports `useTableAssistant`,
`TableAssistantOptions`, `TableAssistantState`, `AssistantMessage`,
`AssistantStatus`, `AssistantInterruption`, `AssistantResumeHandle`,
`AgentProgress`,
`AssistantSuggestion`, `tableAgent`, `TableAgentOptions`,
`TableAgentColumnPatch`, `TABLE_AGENT_STATE`, `TableAgentBridge` and
`SharedApproval`. `@adapttable/ai/http` adds `assistantHttpTransport`. Receipts come from
`receiptFromResult` and `receiptsFromResults` as `AssistantReceipt`, whose
optional `AssistantReceiptSubject` names what changed so the panel can say
"Filter applied — Team is Core" rather than a capability key. `subjectFor`
builds that subject for a built-in capability from what the session returned,
carrying the columns and values as `AssistantReceiptTerm` pairs — label and
formatted value, never a key — so the panel joins them in the reader's
language through `assistantReceiptTerms`. The turn's transports fill
`AssistantTransportReply.subjects` with it; a host capability has no entry,
because only its own runner knows what it did.
Each kit ships the panel on its own `@adapttable/<kit>/assistant` entry,
exporting `TableAssistant` and `tableAssistant`. Core chrome exports
`TableAssistantChrome` (`TableAssistantChromeProps`, `TableAssistantProps`),
`TABLE_ASSISTANT`, `createAdapterTableAssistantFeature`,
`TableAssistantPresentation` — `"floating"` for a nonmodal window over the
page, `"panel"` for a surface the host places, `"sheet"` for the kit's modal —
with `TableAssistantBoundary` scoping a floating window to the viewport or to
a container of your own. `TableAssistantSlots` collects
`TableAssistantPanelProps`, `TableAssistantSheetProps`,
`TableAssistantWindowProps`,
`TableAssistantButtonProps`, `TableAssistantComposerProps` and
`TableAssistantBadgeProps`, plus `TableAssistantMenuProps` and
`TableAssistantMenuItem` — the examples menu in the composer, which each kit
draws with its own menu primitive. `TableAssistantAvatars` sets the mark
beside each speaker, each one a `TableAssistantFace`: a string is read as a
name and drawn as its initials, anything else renders as given — an image, a
kit's own Avatar. Either side left out keeps the built-in face. `greeting`
sets the assistant's opening line, and an empty one opens the panel silent. The view types are `TableAssistantView`,
`TableAssistantMessageView`, `TableAssistantReceiptView` with
`TableAssistantReceiptSubject` — what an action changed, supplied by whoever
ran it — and `TableAssistantSuggestionView`, plus `assistantIsBusy` and
`assistantIsUsable`.
The panel's presentation rules are `@adapttable/core/binding`'s, so every
binding draws the same conversation: `assistantBadgeTone`
(`TableAssistantBadgeTone`), `assistantLauncherName`, `assistantQuestion`,
`assistantRejoinable`, `assistantComposerState`
(`TableAssistantComposerState`), `assistantWithGreeting`,
`assistantVoicePlaceholder`, `assistantInitials`, and for receipts
`assistantShownReceipts`, `assistantReceiptHeadline`, `assistantReceiptDetail`,
`assistantReceiptWhere`, `assistantReceiptNeedsSave`, `assistantUndoReason`,
`assistantUndoTurnLabel` and `assistantActionsName`. Progress reads through
`assistantProgressText` and `assistantWorkingText`. The floating window's
placement is `assistantFloatingStyle` and `assistantLauncherStyle`, each a
`TableAssistantPlacement`, with `assistantFloatingFits` and
`ASSISTANT_FLOATING_MIN_WIDTH` deciding when it becomes the kit's sheet.
Each published kit exports
`agentApproval` and `AgentApproval` (`AgentApprovalProps`). Core chrome
exports `AgentApprovalChrome` (`AgentApprovalChromeProps`),
`AGENT_APPROVAL`, `AGENT_APPROVAL_STATE`, `AgentApprovalPending`,
`approvalReview`, `ApprovalReview`, `ApprovalReviewItem`,
`APPROVAL_PREVIEW_LIMIT`, `ApprovalReviewChrome`,
`ApprovalReviewChromeProps`, `ApprovalReviewSlots`,
`AgentApprovalDecision`, `AgentApprovalOperation`,
`AgentApprovalProposal`, `AgentApprovalButtonProps`,
`AgentApprovalListProps` and `AgentApprovalSlots`. Portable adapters live
on subpaths: `@adapttable/ai/json` (`toJsonTools`, `JsonFunctionTool`,
`executeJsonTool`, `JsonToolCall`, `parseEnvelope`, `executeEnvelope`,
`AgentEnvelope`), `@adapttable/ai/openai` (`toOpenAITools`,
`toOpenAIToolName`, `fromOpenAIToolName`,
`OpenAIFunctionTool`, `OpenAIFunctionDefinition`, `OpenAIToolsOptions`,
`executeOpenAITool`, `OpenAIToolCall`, `OpenAIToolCallFunction`),
`@adapttable/ai/mcp` (`toMcpTools`, `McpTool`,
`toMcpResources`, `McpResource`, `mcpListChanged`, `executeMcpTool`),
`@adapttable/ai/http` (`createAgentHttpClient`, `connectAgentHttp`,
`runAgentHttpTurn`, `parseAgentHttpRequest`, `parseAgentHttpResponse`,
`agentSystemPrompt`, `AgentSystemPromptInput`,
`AGENT_HTTP_SCHEMA`, `AgentHttpKind` (`hello` / `schema` / `turn`),
`AgentHttpMessage`, `AgentHttpUnresolved`, `sessionId`, `viewRevision`,
`pinCatalog`, `AgentHttpPinAck`, `AgentHttpAudio`,
`AgentHttpRequest`, `AgentHttpResponse`, `AgentHttpError`,
`AgentHttpClientOptions`, `AgentHttpTurnResult`). See
[adaptive capabilities](./agent-capabilities.md),
[`@adapttable/ai`](./ai.md), [agent integrations](./ai-integrations.md)
and [connect a backend](./ai-http.md).

**Server queries.** `parseTableQuery(input, schema)` from
`@adapttable/server` validates a request against a `QuerySchema` and returns a
`ServerTableQuery` — page, limit, offset, search, sort chain, grouping,
filters, filter tree, pivot, the folded pivot groups in `pivotCollapsed`, and
cursor, plus a `QueryRejection[]` naming everything it refused. The schema
picks the level of checking: `columns: "any"` shapes every filter
(`shapedFilters`, one `ShapedFilter` per key), a column list checks names,
and `filters` — a shorthand record or the table's own `FilterDef[]`, read as
`ServerFilterDef`s — types and checks each filter (`typedFilters`, one
`TypedFilter` per key: `TextFilter`, `SelectFilter`, `ListFilter`,
`BooleanFilter`, `NumberRangeFilter`, `DateRangeFilter` or
`CustomTypedFilter`), with `filterTypes` (`ServerFilterType`s) for registered
types. `groupByKeys: true`
lists every grouping key. `pickFilters(defs, keys)` scopes the declared
filters per caller, and `splitFilterValues(raw)` inverts the table's
multi-value encoding. `QueryInput` is a `Request`, `URL`, query string or
`URLSearchParams`; `ServerFilterValue` is one filter's value. See
[server queries](./server-queries.md).

**The query model without React.** `@adapttable/core/query` is the half of the
model a backend needs and no more: the `ft=1.{…}` codec (`parseFilterTree`,
`serializeFilterTree`, `isActiveFilterTree`, `FILTER_TREE_PARAM`,
`FILTER_TREE_VERSION`), the `pivot=rows:…` codec (`serializePivot`,
`deserializePivot`, plus `serializePivotState` / `deserializePivotState` for the
whole `PivotUrlState` — the `config` and the folded `collapsed` keys), the
`formula=key:text` codec (`serializeFormulaColumns`,
`deserializeFormulaColumns`, `FormulaColumnSpec`), `isFilterGroup` for walking a
tree, and the types they speak in — `QueryCondition`, `QueryFilterGroup`,
`SortLevel`, `SortDirection`,
and the pivot pair `PivotConfig` (`rows`, `columns`, `measures`, `subtotals`,
`grandTotals`) and `PivotMeasure` (a column `key`, an `agg`, an optional
`label`). Every name is the same one `@adapttable/core` exports, from the same
module; this entry only omits the hooks, so it carries no `"use client"`
boundary and no React import and loads where React is not installed. See
[server queries](./server-queries.md#decoding-a-parameter-yourself).

**Formulas.** `buildFormulaColumns(specs)` from `@adapttable/core/formula`
turns `FormulaColumnSpec`s into columns, returning a `FormulaColumnsResult`:
the columns, the `errors` that would not parse, and any `cycles`. A value is a
tagged `FormulaValue` (`FormulaErrorCode`, `FORMULA_ERRORS`, `FORMULA_BLANK`),
built with `formulaNumber` / `formulaText` / `formulaBoolean` / `formulaError`
or read off a row with `toFormulaValue`, rendered with `formulaDisplay`,
compared with `formulaSortValue`, and tested with `isFormulaError`.
`parseFormula` returns a `ParseResult` holding a `FormulaNode` tree
(`BinaryOp`), `formulaRefs` names what a formula reads, `evaluateFormula` runs
one against a `FormulaScope`, and `FORMULA_FUNCTIONS` lists the built-ins,
including `POWER` and `SQRT`. See [formulas](./formulas.md).

**Formulas in the URL.** `useFormulaUrlState({ urlAdapter, urlSync, urlKey,
defaultFormulas })` from `@adapttable/react/formula` returns a
`UseFormulaUrlStateResult` — the `formulas` to hand `buildFormulaColumns`, and
an `onFormulasChange` that persists them; `UseFormulaUrlStateOptions` names the
options and `FORMULA_URL_WRITE_DEBOUNCE_MS` is the trailing debounce on the URL
write. `serializeFormulaColumns` and `deserializeFormulaColumns` are the
encoding on its own, exported from `@adapttable/core/formula` and from the
React-free `@adapttable/core/query`; reading produces `FormulaColumnSpec`s and
never evaluates anything. Saved views capture the parameter with the rest.

**The pivot engine.** `pivot(rows, options)` from `@adapttable/core/pivot`
returns a `PivotResult`: `columnTree`, a tree of `PivotColumnNode`s carrying
each dimension value's `label`, `path`, header `span` and `children`;
`columnLeaves`, the rendered columns left to right as `PivotColumnLeaf`es (a
stable `key`, the column `path`, the `measure` shown in it, and `total` for the
grand-total column); `rows`, the body as `PivotRow`s (`key`, `path`, `depth`,
a `PivotRowKind` of `"leaf"` / `"subtotal"` / `"grandTotal"`, `label`, `cells`
in `columnLeaves` order, and the `count` of source rows behind the line); and
`rowDepth`, how many dimensions sit down the side. `PivotOptions` carries the
`columns` — so dimension and measure values resolve through `sortValue` exactly
as sorting and grouping do — a `format` for a computed cell, and the
`collapsed` subtotal keys. A row with no value for a dimension buckets under
`PIVOT_BLANK` instead of vanishing, and the grand-total line's key is
`PIVOT_GRAND_TOTAL_KEY`. See [pivot tables](./pivot.md).

**Editing a pivot configuration.** The panel's non-widget half, so every kit's
buttons agree on what a move means. A `PivotField` is a column `key` plus the
`label` to show it under, and `PIVOT_ZONES` lists the `PivotZone`s a field can
sit in — `"rows"`, `"columns"`, `"measures"` — in panel order.
`availableFields(fields, config)` is what no axis has claimed yet;
`assignField(config, key, zone, index)` places a field (past the end appends,
and a dimension leaves the other axis rather than pivoting twice);
`removeField(config, zone, index)` takes one off; `moveField(config, zone,
index, delta)` is the keyboard step within a zone; and `setMeasureAgg(config,
index, agg)` changes what a measure computes. Each returns a new `PivotConfig`,
starting from `EMPTY_PIVOT_CONFIG`. `isPivotReady(config)` is false while no
measure has been chosen — a half-built configuration the panel shows and the
table waits on, not an error. `measureLabel(measure, fields)` is the caption
the panel and the column header share. See [pivot tables](./pivot.md).

**Pivot state in the URL.** `usePivotUrlState({ urlAdapter, urlSync, urlKey,
defaultConfig })` from `@adapttable/react/pivot` returns a
`UsePivotUrlStateResult` — the `config` to hand both the panel and `pivot`, an
`onConfigChange` that persists it, the folded `collapsed` set to pass as
`pivot`'s `collapsed` option, and `onCollapsedChange`;
`UsePivotUrlStateOptions` names the options. An empty pivot writes no
parameter. See [URL state](./url-state.md).

**Pivoting on the server.** `serverPivotResult(page, options)` from
`@adapttable/core/pivot` turns a server's answer into the same `PivotResult`
the local engine returns, so one rendering path serves both tiers. A
`QueryPivotPage` is the column-dimension `columns` paths in display order, the
body `rows`, and the `total` line when the server computed one; each
`QueryPivotRow` is a row `path` (empty for the grand total), its `cells` in
column-then-measure order, optional `totals` for the grand-total column, a
`count`, and `subtotal` when the line totals the ones beneath it. Absent cells
render empty rather than zero. `ServerPivotOptions` is the `config` that was
sent — for the measures and their order — plus the same `format`. See
[server queries](./server-queries.md).

**The pivot configuration panel.** `PivotPanelChrome` from
`@adapttable/react/adapter` renders the three zones and the controls that move
fields between them; `PivotPanelChromeProps` takes the fields, the config and
an `onChange`. `PivotPanelSlots` names the five kit-supplied pieces —
`PivotPanelSurfaceProps` (the body), `PivotZoneProps` (a titled zone),
`PivotFieldProps` (one field with its move and remove controls),
`PivotAddProps` (the add control) and `PivotAggProps` (a measure's aggregation
chooser). Keyboard-first by construction: the move controls are buttons, so
the panel needs no pointer. See [pivot tables](./pivot.md).

**A pivot, as table props.** `pivotTableModel(result, options)` from
`@adapttable/react/pivot` turns a `PivotResult` into a `PivotTableModel` — the
`columns`, `rows`, `rowKey` and `summaryRow` a `DataTable` takes — so the pivot
is rendered by your kit rather than by markup of your own. The column tree
becomes `column.group`, the grand total becomes the footer, and the row-header
column is keyed `PIVOT_ROW_COLUMN_KEY`. `PivotTableModelOptions` are the
`fields` that caption the measures, the `labels` behind the grand-total
captions, the corner cell's `rowHeader`, the per-level `indent`, and
`renderRowHeader` — where a fold control goes, since core ships no controls.
See [pivot tables](./pivot.md#rendering-it-with-your-kit).

**Replacing a mobile card's body.** `renderCard(row, card)` returns the card's
content; the shell renders around it. `renderCard` has the type `ReactMobileCardRenderer` from `@adapttable/react`, and `card` is a
`MobileCardModel`: `index`,
`selected`, `expanded`, and `fields` — a `MobileCardField` per column carrying
its `column`, resolved `label` (`undefined` when the column asked for none) and
`value`, the same node the built-in would have shown. See
[mobile](./mobile.md).

**Replacing the error state.** `slots.error` is a `Slot<TableErrorState>`:
a node, or a function receiving the `TableErrorState` the built-in was
showing — `error`, `retry` (absent when the source cannot re-fetch, so a
static `data` array offers no dead button) and `retrying`. Adapters derive it
with `tableErrorState(source)` and resolve the slot with `fillSlot(slot,
state)`, both from `@adapttable/react/adapter`, where the slot and the node
it resolves to are React content. `@adapttable/core` exports the neutral pair
for a non-React host. See
[customization](./customization.md).

**Density chooser and fullscreen toggle.** `densityChooser()` puts a density
control in the toolbar. Without a controlled `density` prop, the feature owns
the choice and starts at `"comfortable"`; pass `density` to control it and
`onDensityChange` to observe requests. `fullscreen()` puts a fullscreen toggle
beside it, and that button hides itself where the browser will not allow
fullscreen at all. Adapters build both from `viewControlsToolbar(props,
fullscreen)` / `ViewControlsToolbar` in `@adapttable/react/adapter`. Density
is an always-resolved read/write contract passed to the toolbar slots; whether
the density button draws is decided by feature composition. Fullscreen stays
present-or-absent from the feature and browser support.
Adapters with a custom chrome path call `useResolvedDensity(props)` directly;
its `ResolvedDensity` result carries the same resolved value and request
callback.

**Fullscreen.** `useFullscreen(element)` promotes the table and returns a
`FullscreenState`: `active`, `supported`, `toggle`, `exit`, and — the part
that matters — `container`. The Fullscreen API hides everything outside the
promoted element, so an overlay portalled to `document.body` stays mounted,
focused and announced while being completely invisible. Hand `container` to
each kit's portal target and menus keep working; ignore it and they vanish.
State is read from the document rather than remembered, because Escape and
the browser's own control both leave fullscreen without asking.

**Density in the URL.** `useDensityUrlState(options)` returns a `Density`
(`"comfortable"` | `"compact"`) and `onDensityChange` to spread onto the
table when you want the choice in the URL beside sort and filters — a reload
or a shared link reproduces it. Pair with a controlled `density` prop; the
chooser works without it. `UseDensityUrlStateOptions` /
`UseDensityUrlStateResult` type it. Choosing the default removes the
parameter rather than restating it.

**Command palette.** `commandPalette` opens a palette on Cmd/Ctrl+K listing
every table action — `true` for the built-ins, or `CommandPaletteOptions`
(`{ commands, shortcuts }`) to add your own and remap the chord. A `Command`
IS a `ContextMenuItem`, so an action is written once and offered in both
places rather than drifting between them; `tableCommands(options)` builds the
target-free ones (print, export, clear filters) and `filterCommands(commands,
query)` is the case- and accent-folded substring match the input runs.
Composing `print(onPrint)` is what makes Print appear. Shortcuts are data:
`Shortcut` is a chord and a command key, `DEFAULT_SHORTCUTS` is Cmd/Ctrl+K,
and `useShortcuts(options)` binds them — `mod` means Cmd on a Mac and Ctrl
elsewhere. Adapters build theirs over `CommandPaletteChrome` /
`CommandPaletteChromeProps` / `CommandPaletteSlots` /
`CommandPaletteSurfaceProps` / `CommandPaletteInputProps` /
`CommandPaletteItemProps` and arm it with `useCommandPalette` (returning a
`TableCommandPalette`; `UseCommandPaletteOptions` is the hook's input), from
`@adapttable/react/adapter`. See
[customization](./customization.md#command-palette).

**Context menus.** `contextMenu` arms right-click menus for headers, rows and
cells — `true` for the built-ins, or `ContextMenuOptions` (`{ items }`) to
append your own behind a divider. `ContextMenuItem` is one entry (`key`,
`label`, `onSelect`, and optional `disabled` / `danger` / `separatorBefore`);
`ContextMenuTarget` is what was clicked; `ContextMenuActions` are the handlers
the built-in entries call. Every route in works: right-click, Shift+F10, the
menu key, and a long press. Adapters build theirs over `ContextMenuChrome` /
`ContextMenuChromeProps` / `ContextMenuSlots` / `ContextMenuSurfaceProps` /
`ContextMenuItemProps` and arm it with `useTableContextMenu`
(`TableContextMenuOptions` is the hook's input; it returns a
`TableContextMenu`: `regionProps` to bind once, plus `items`, `at` and
`close`). `ContextMenuPoint` is the click coordinates the chrome hands the
surface. All from `@adapttable/react/adapter`. The surface slot receives an
`anchorRef` — a zero-size element at the click point — because every kit's
menu positions against an element rather than coordinates. See
[customization](./customization.md#context-menus).

**Context-menu targets.** `resolveContextTarget(from, rowFor)` works out
which header, row or cell an event happened in, returning a
`ResolvedContextTarget` — the target and the element to put focus back on —
or `null` when there is no menu there. It reads the `data-adapttable-part`
names and `ROW_ID_ATTRIBUTE` (`data-row-id`), which every kit's rows and
header cells carry, so an adapter binds one set of handlers to the element
containing all three rather than to each of them. Precedence: a cell inside a
row wins, a header cell is neither, and a click on the row outside any data
cell is a row target.

**Side panel.** `sidePanel` docks table settings beside the table instead of
in a popover over them. `SidePanelOptions` types it — `panels`, `open`,
`onOpenChange`, `side` — and `SidePanelEntry` is one panel (`key`, `label`,
`content`). It is controlled, because the control that opens it is the
host's. Adapters build theirs over `SidePanelChrome` / `SidePanelChromeProps`
/ `SidePanelSlots` / `SidePanelFrameProps` / `SidePanelTabProps` /
`SidePanelCloseProps` and dock it with `SidePanelLayout` /
`SidePanelLayoutProps` from `@adapttable/react/adapter`; the tab strip's
keyboard contract lives in core, not in each kit. See
[customization](./customization.md#side-panel).

**Status bar.** `statusBar` puts a strip under the table reading the row
range, how many rows are selected, and what a multi-cell selection adds up
to. Adapters render their kit-owned status bar over `StatusBarChrome` /
`StatusBarChromeProps` / `StatusBarSlots` / `StatusBarSlotProps` /
`StatusBarItem` from `@adapttable/react/adapter`. It hosts the selection
figures rather than repeating them: with `enabled` false the chrome renders
those alone, which is why an adapter has one element here and no branch. The
row range comes from the same arithmetic the pagination footer uses.
`StatusBarChromeProps.notices` / `TableChrome.featureNotices` carry
`FeatureNotice` values (`FeatureNoticeKind` names the inert opt-in). They draw
in the status strip when `statusBar()` or `selectionStats()` is composed, and
the table root carries the active kinds in `data-adapttable-notices`. See
[customization](./customization.md#toolbar-and-status-bar).

**Toolbar regions and undo/redo.** `toolbar` fills the middle of the toolbar;
`toolbarSlots` (`ToolbarSlots` — `start`, `end`) fills either end.
`undoRedoButtons` adds Undo and Redo, which render only when `editHistory` is
armed and disable rather than disappear; `undoRedoToolbar(wanted, history,
labels)` from `@adapttable/react/adapter` is the one rule both wiring paths
resolve that with. Labels are `undoEdit` and `redoEdit`. `print(onPrint, printButton)` adds a
Print button when `printButton` is set;
`printToolbar(wanted, onPrint, labels)` resolves that pair the same way
(`PrintToolbar` is the resolved `{ onPrint, label }`), and
the caption is `labels.print`. See
[customization](./customization.md#toolbar-and-status-bar).

**Reading a cell as text.** `columnText(column, row)` returns a column's cell
as a string for anything that cannot render JSX. It resolves
`formatValue` → `exportValue` → `sortValue` → `accessor` when that yields a
primitive → the key's data path, and never returns `undefined`. The data path
is used only for a column that renders no cell of its own: a column with
`accessor: () => null` shows an empty cell, so reading its path would announce
a value the user cannot see. See [columns](./columns.md).

**Odds and ends.** `ComputedColumnSpec` is the declaration
[`computed`](./columns.md) takes. `TableQueryKeyOptions` options the cache-key
builders. `HeaderSelectionState` is the header checkbox's tri-state.
`defaultSearchText` is the default searchable-text projector (a row's own
values, flattened). `columnMenuLabel` gives a column its readable name in the
menu (header string → `mobileLabel` → key). `runRowAction` runs a row action
through the confirmation handler. `visibleRowActions` drops `isHidden` entries
from a resolved list. `LayoutStorage` is the slice of the `Storage`
API the column-layout hook needs, injectable for tests. `SavedViewsMenu` /
`SavedViewsLabels` are the adapters' saved-views control and its strings, and
`ToolbarChromeProps` is the toolbar's kit-agnostic prop surface. The CLI
exports `Kit`, the union of UI kits `@adapttable/cli init` can detect.

**Locale exports.** `@adapttable/i18n` exports one label set per locale, named
by its tag: `ar`, `de`, `en`, `es`, `fa`, `fr`, `he`, `hi`, `it`, `ja`, `ko`,
`pl`, `pt`, `ru`, `tr`, `ur`, `zh`, `zhTW`. See
[i18n & RTL](./i18n-rtl.md).

Adapter-machinery names (`headerGroupRows`, `insertExtraRows`, `useFullscreen`,
`columnMenuActions`, `BodyCell`, …) resolve only from
`@adapttable/react/adapter`. Body data comes from
`usePlainChromeBodyData` or `useVirtualChromeBodyData`.

Notable non-hook helpers: `rowsToCsv` / `downloadCsv` / `downloadTableCsv`
(CSV export — or compose `exportCsv()` for a built-in button),
`sortRows` / `sortRowsMulti` / `compareValues` / `nextSort`,
`computePagination`, `headerGroupRow` / `headerGroupRows` /
`htmlGroupedHeaderPlan` / `groupedHeaderChildRule` /
`groupedHeaderCellStyle` / `groupedHeaderLabelStyle` / `groupedHeaderAlign` / `columnGroupStubStyle` / `COLUMN_GROUP_STUB_WIDTH`,
`columnGroupPath` / `columnGroupId` / `COLUMN_GROUP_ID_SEP` /
`COLUMN_GROUP_STUB_PREFIX` / `COLUMN_GROUP_RENDER_PREFIX` /
`isColumnGroupStubKey` / `isColumnGroupRenderKey` /
`isColumnGroupSummaryKey` /
`columnGroupHeaderCaption`,
`flattenColumnTree` / `isColumnGroup` / `marriedOrderHolds` /
`applyCollapsedColumnGroups` / `toggleCollapsedColumnGroup`,
`columnHeaderLabel` / `columnHeaderController` /
`resolveColumnHeader` / `resolveColumnFooter` / `columnsHaveFooter`,
`ColumnHeaderController` / `ColumnHeaderContext` / `ColumnFooterContext`,
`columnMenuRows` / `filterColumnMenuRows` / `columnMenuActions` /
`showAllColumns` / `hideAllColumns` / `unpinAllColumns` /
`resetColumnLayout`, `ColumnMenuAction` / `ColumnMenuActionContext`,
`columnRowDragProps` / `columnDropProps` / `columnReorderKeyProps` /
`columnResizeHandleProps` (RTL-aware), `pinnedCellStyle` / `edgePinStyle` /
`PIN_Z`, `tableMinWidth` / `resolveColumnWidth` / `parsePxWidth`,
`rowClickProps`, `resolveFilterDefs` / `buildFilterRuntime` /
`filterPredicate` / `showSimpleFilterFields` / `materializeAutoOptions` / `clearedFilterExtras`,
`builtInFilterSpecs` / `defaultFilterRegistry` / `resolveFilterRegistry` /
`createFilterRegistry` / `emptyFilterRegistry` / `filterTypeSpec` /
`filterWidgetKind` / `filterTypeOps` / `filterTypeDefaultOp` /
`renderRegisteredFilter`,
`mergeProps`, `stableKey`, `getPath`, `humanizeKey`, `resolveLabels` /
`defaultLabels`, `pageSizeOptions`, and the constants `DEFAULT_LIMIT` (25),
`PAGE_SIZE_OPTIONS`, `SEARCH_DEBOUNCE_MS` (300), `AUTO_OPTIONS_LIMIT` (50),
`FILTER_AI_OPTIONS_LIMIT` (same 50, the assistant option cutoff),
`ACTIONS_COLUMN_KEY` (`"actions"`).

## Feature composition types

| Export                         | What it is                                                                                                                                                                                     |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TableFeature<TRow>`           | A composed feature: `id`, optional `apply`, `setup`, `provider` and `renders`. Row-aware factories return this and infer `TRow` from their callback.                                           |
| `StaticTableFeature`           | A feature whose configuration says nothing about rows — `grouping("team")`, `virtualize()`, `columnMenu()`. Composes into any table with no type argument.                                     |
| `TableFeatureHost<TRow>`       | What `setup(host)` registers against: filter types, editors, aggregators, writers, column-menu actions, panels, commands, context-menu items.                                                  |
| `StaticFeatureHost`            | The same host minus the two row-shaped registrations, which is what a static feature sees.                                                                                                     |
| `standardFeatures(options?)`   | On each kit's `/preset` entry: the zero-configuration members plus the ones whose options you supply; `findButton: true` draws the toolbar Find control. Returns a plain array you can extend. |
| `StandardFeatureOptions<TRow>` | `grouping`, `bulkActions`, `filters`, `savedViews` — each the argument its own factory already takes.                                                                                          |
| `AdapterGroupingPanelFeature`  | The overloaded kit `groupingPanel()` factory after an adapter supplies its group headers and panel chrome.                                                                                     |
| `GroupingExtras<TRow>`         | Everything `grouping` takes beyond the key, including the row-shaped `groupAggregates` and `groupSort`.                                                                                        |
| `StaticGroupingExtras`         | The subset that says nothing about the row — paging, collapse state, footers — so `grouping(key, thoseOnly)` stays row-independent.                                                            |
| `FeatureProps<TRow>`           | What a feature's `apply()` writes — the props v3 removed from `<DataTable>`. A host composes the feature instead; see [upgrading from v2](./migrate-from-v2.md).                               |
| `ComposedTableProps<TRow>`     | `BaseDataTableProps` plus `FeatureProps`: the shape the table works with once features have applied, which is what an adapter's internals read.                                                |

See [feature composition](./features.md).

## Source capabilities

What the data layer behind the table can actually do. A control that needs
more than the source has is turned OFF and says why, instead of quietly doing
something narrower — `scope: "all"` writing one page, `groupBy` doing nothing,
"select all N matching" over rows nobody can name.

| Export                                                                  | What it is                                                                                                                                                     |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TableSourceCapabilities`                                               | The declaration on `TableSource.capabilities`: `fullDataset`, `grouping`, `selectAcrossPages`, `exportScope`, `totalCount`, `aggregateOperations`.             |
| `GroupingCapability` / `ExportScopeCapability` / `TotalCountCapability` | `"client" \| "server" \| false`, `"all" \| "page"`, and `"exact" \| "loaded"`.                                                                                 |
| `sourceCapabilities(source, support?)`                                  | The one place the answer is decided: the source's own declaration when it has one, otherwise inferred from its shape (and `QuerySupport.grouping` when given). |
| `CapabilitySource`                                                      | The handful of fields that read consults — enough to ask without holding a whole source.                                                                       |
| `capabilityReason(capability)`                                          | The sentence a kit puts on the control it disabled. Localized copy overrides it through `TableLabels`.                                                         |
| `offersAllMatching(selection, total)`                                   | Whether the "select all N matching" banner applies: the source can reach past the page, the page is fully selected, and more rows match.                       |

| Capability          | Runtime consequence                                                                                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fullDataset`       | When false, only the page on screen is reachable.                                                                                                                                                                                          |
| `grouping`          | When false, `groupBy` is ignored, the status bar carries `noticeGroupingUnavailable`, and dev mode warns.                                                                                                                                  |
| `selectAcrossPages` | When false, selection stays on the rows on screen; the banner never appears and `selectAllMatching()` no-ops.                                                                                                                              |
| `exportScope`       | `"all"` permits a source-owned full export only when `allFilteredRows` actually supplies the rows. A declaration alone is not transport. `request` or `fetchAll` is an independent executable route; with none, Export all stays disabled. |
| `totalCount`        | `"loaded"` means `total` is what has loaded rather than the match count.                                                                                                                                                                   |

Omitting `capabilities` changes nothing: the same answers are inferred from
the source's shape. See [data tiers](./data-tiers.md#what-a-source-can-do--capabilities).

## Types

| Type                                                                                                                                                                                                                                                                                                                     | What it is                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TableSource<TRow>`                                                                                                                                                                                                                                                                                                      | The uniform data + state contract a table consumes (rows, total, `defaultLimit`, `allFilteredRows`, `allSearchedRows`, `facets`, loading flags, state read/write). Server grouping that cannot honour `query.aggregates` sets `honorsAggregates: false`.                                                                                                                                                                                                                                             |
| `TableQuery`                                                                                                                                                                                                                                                                                                             | The consolidated server-tier query: `page`, `limit`, `search`, `sortBy`, `sortDir`, `sortLevels`, `filters`.                                                                                                                                                                                                                                                                                                                                                                                         |
| `TableQueryParams`                                                                                                                                                                                                                                                                                                       | Baseline query params a backend list endpoint receives.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `QuerySupport`                                                                                                                                                                                                                                                                                                           | What a server endpoint can answer: `grouping`, `aggregates`, `filterTree`, `facets`, `cursor`.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `QueryExtensions`                                                                                                                                                                                                                                                                                                        | The optional query fields those capabilities unlock, carried on `TableQuery`.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `QueryAggregate`                                                                                                                                                                                                                                                                                                         | One aggregate to compute: `{ key, fn }` where `fn` is a `AggregateFn` or your backend's own name.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `aggregate`                                                                                                                                                                                                                                                                                                              | Builds a `summaryRow` / `groupAggregates` mapper from a declaration — see [row grouping](./row-grouping.md).                                                                                                                                                                                                                                                                                                                                                                                         |
| `AggregateName` / `AGGREGATE_NAMES`                                                                                                                                                                                                                                                                                      | The built-in aggregate names: `sum`, `avg`, `count`, `min`, `max`.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `Aggregator` / `AggregateSpec` / `AggregateOptions`                                                                                                                                                                                                                                                                      | A custom aggregate function, the per-column declaration, and `aggregate()`'s options (`columns`, `format`).                                                                                                                                                                                                                                                                                                                                                                                          |
| `Aggregatable` / `AggregatableConfig` / `AggregateOperation` / `CustomAggregateOperation`                                                                                                                                                                                                                                | A column's reader-controlled offer: `false` / `true` / `{ default?, operations }`. `operations` is built-in names or `{ id, label, calculate? }`.                                                                                                                                                                                                                                                                                                                                                    |
| `AggregateOperationId`                                                                                                                                                                                                                                                                                                   | A built-in name or a host's own stable id. Sent to a server; never a function.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `ResolvedAggregatable` / `ResolvedAggregateOperation` / `resolveAggregatable` / `resolveAggregatableColumns` / `impliedOperations`                                                                                                                                                                                       | The validated offer for one column or every column. `aggregatable: true` reads `impliedOperations` from the declared filter/editor type.                                                                                                                                                                                                                                                                                                                                                             |
| `allowsOperation` / `allowsReaderOperation` / `offerableOperations` / `AggregationSourceSupport`                                                                                                                                                                                                                         | The one execution gate: a column must offer the id, and the source must be able to compute it.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `AggregationModel` / `AggregationModelInput` / `AggregationItem` / `AggregationCandidate` / `AggregationOrigin` / `aggregationModel`                                                                                                                                                                                     | The list the panel and column menu both draw: active items, addable candidates, whether the reader is still at the developer's defaults, and `hasDefaults` when restore would put a developer baseline back.                                                                                                                                                                                                                                                                                         |
| `resolveEffectiveAggregation` / `EffectiveAggregation` / `EffectiveAggregationInput` / `EffectiveAggregationKind` / `effectiveAggregateOps` / `readerControlAllowed` / `columnAggregationSignature`                                                                                                                      | Shared precedence for display and execution: a valid reader override or permitted suppression, then a valid executable column default, then the original host mapper or request. `EffectiveAggregationKind` is that one owner. `effectiveAggregateOps` is the map the calculator and the first server request both use.                                                                                                                                                                              |
| `toAggregateInstant` / `toAggregateOrdered` / `AggregateOrderedValue`                                                                                                                                                                                                                                                    | How `min` / `max` compare a value: a `Date`, a finite number, or a strict ISO date / datetime / time string (`AggregateOrderedValue`). Locale forms are skipped, not guessed.                                                                                                                                                                                                                                                                                                                        |
| `addAggregation` / `removeAggregation` / `restoreAggregationDefaults` / `reconcileAggregations` / `initialOperation` / `declaredByDeveloper` / `AGGREGATE_SUPPRESSED`                                                                                                                                                    | Reader transitions and URL/saved-view cleanup. Removing a developer default writes `AGGREGATE_SUPPRESSED` (`"none"`) only while the reader may still choose that column.                                                                                                                                                                                                                                                                                                                             |
| `computedAggregateKeys`                                                                                                                                                                                                                                                                                                  | Column keys that already have an aggregate cell in the current group rows — enough to show a read-only opaque mapper, not enough to name its operation.                                                                                                                                                                                                                                                                                                                                              |
| `CUSTOM_AGGREGATE` / `DeclaredAggregates` / `declaredAggregates` / `withDeclaredAggregates` / `GroupAggregatesMapper`                                                                                                                                                                                                    | Metadata on `aggregate()`: a declared mapper's operation ids, or `CUSTOM_AGGREGATE` when the host supplied a function. `withDeclaredAggregates` tags a mapper so Restore defaults can name those ids.                                                                                                                                                                                                                                                                                                |
| `AggregateFn`                                                                                                                                                                                                                                                                                                            | The standard aggregate names: `sum`, `avg`, `count`, `min`, `max`.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `QueryCondition` / `QueryFilterGroup`                                                                                                                                                                                                                                                                                    | A leaf condition (`key`, `op`, `value`) and a nestable AND/OR group of them.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `isFilterGroup`                                                                                                                                                                                                                                                                                                          | Narrows a filter-tree child to a nested group while walking the tree.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `PaginatedResponse<TRow>`                                                                                                                                                                                                                                                                                                | Standard envelope: `items`, `total`, `page`, `limit`, `hasNext`.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ColumnLayoutState`                                                                                                                                                                                                                                                                                                      | `{ hidden, order, pinned, widths, names?, collapsedGroups? }` — the column-layout shape.                                                                                                                                                                                                                                                                                                                                                                                                             |
| `ColumnGroupDef<TRow>` / `ColumnInput<TRow>`                                                                                                                                                                                                                                                                             | A parent header with `children`, or a leaf-or-parent union. See [column groups](./column-groups.md).                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ColumnGroupShow`                                                                                                                                                                                                                                                                                                        | `"open" \| "closed" \| "always"` — when a leaf under a collapsible group is visible.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ColumnGroupRecord` / `FlattenedColumns`                                                                                                                                                                                                                                                                                 | Collapse policy for one parent, and the `{ leaves, groups }` result of `flattenColumnTree`.                                                                                                                                                                                                                                                                                                                                                                                                          |
| `TableLabels`                                                                                                                                                                                                                                                                                                            | Every string the table renders; all keys optional, English defaults fill gaps.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `RowAction<TRow>` / `BulkAction`                                                                                                                                                                                                                                                                                         | Action definitions with `disabledReason`, `isHidden`, optional `confirm` wiring.                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `RowActionsLayout`                                                                                                                                                                                                                                                                                                       | `"buttons" \| "menu"` — omit / `"buttons"` is the strip; `"menu"` is the 3-dot control.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `RowActionsRenderContext<TRow>` / `RowActionsRenderer<TRow>`                                                                                                                                                                                                                                                             | What `renderRowActions` receives (`row`, `actions`, `confirm`, `labels`) / the renderer type.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `visibleRowActions`                                                                                                                                                                                                                                                                                                      | Filters `isHidden` actions out of a resolved list. Default layouts use this; a custom cell can keep hidden ones.                                                                                                                                                                                                                                                                                                                                                                                     |
| `BulkActionContext`                                                                                                                                                                                                                                                                                                      | `{ allMatching, total }` — scope handed to a bulk action handler.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `ActionConfirm<TArg>`                                                                                                                                                                                                                                                                                                    | Confirmation dialog wiring (`title`, `message`, `confirmLabel`, `danger`).                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `ActionAiOptions` / `ActionApprovalPolicy` / `ApprovalPresentation`                                                                                                                                                                                                                                                      | What a row or bulk action says about being invoked by an agent — approval overrides that inherit field by field from the shared assistant configuration / `"required"` or `"automatic"`, whether a human is asked / `"widget"`, `"table"` or `"modal"`, where they are asked. Distinct from `confirm`, which is a person confirming their own click. See [agent capabilities](./agent-capabilities.md).                                                                                              |
| `ConfirmHandler` / `ConfirmRequest`                                                                                                                                                                                                                                                                                      | The injectable confirmation seam (`(request) => void`).                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `defaultConfirm`                                                                                                                                                                                                                                                                                                         | The built-in `ConfirmHandler` (`window.confirm`; DENIES when no dialog exists).                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `ActiveFilterChip` / `ChipLabelResolver`                                                                                                                                                                                                                                                                                 | One removable chip (`key`, `label`, `onRemove`) / value → chip-label function.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `UrlStateAdapter`                                                                                                                                                                                                                                                                                                        | The router seam: `getSearch()`, `setSearch(search, { push? })`, `subscribe(onChange)`.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `SavedView`                                                                                                                                                                                                                                                                                                              | `{ name, search }` — one captured view.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `FilterDef` / `FilterType` / `FilterOption` / `FilterOptionsSource` / `FilterAiOptions`                                                                                                                                                                                                                                  | The declarative filter surface (see [FilterDef](#filterdef)), including what the assistant may see.                                                                                                                                                                                                                                                                                                                                                                                                  |
| `FilterTypeSpec` / `FilterTypeRegistry` / `FilterWidgetKind`                                                                                                                                                                                                                                                             | One registered type / the immutable registry / which built-in widget to draw. Register types with `TableFeatureHost.registerFilterType` / `extendFilterType`.                                                                                                                                                                                                                                                                                                                                        |
| `FilterWidgetRenderProps`                                                                                                                                                                                                                                                                                                | Props a custom `FilterTypeSpec.render` receives.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `CellProps<TRow>`                                                                                                                                                                                                                                                                                                        | `{ row, rowIndex }` — what a `Cell` component receives.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `SortDirection` / `SortLevel`                                                                                                                                                                                                                                                                                            | `"asc" \| "desc"` / one entry in the multi-sort chain.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `Direction`                                                                                                                                                                                                                                                                                                              | `"ltr" \| "rtl"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `ColorScheme`                                                                                                                                                                                                                                                                                                            | `"light" \| "dark" \| "auto"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `PaginationMode`                                                                                                                                                                                                                                                                                                         | `"infinite" \| "paged" \| "auto"` (`"auto"` resolves by viewport: mobile → infinite).                                                                                                                                                                                                                                                                                                                                                                                                                |
| `FilterValue` / `ExtraFilters`                                                                                                                                                                                                                                                                                           | One URL-round-tripped filter value / the keyed bag of them.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `ColumnMetadata<TRow>` / `ColumnModel<TRow>`                                                                                                                                                                                                                                                                             | The neutral column the engine reads, and its alias on the main entry. `ColumnDef` is the React column that extends it.                                                                                                                                                                                                                                                                                                                                                                               |
| `ColumnModelFilter<TRow>` / `ColumnModelEditor`                                                                                                                                                                                                                                                                          | A neutral column's declarative filter and editor, before a binding narrows them — `ColumnDef` narrows both to `ColumnFilter` and `CellEditor`.                                                                                                                                                                                                                                                                                                                                                       |
| `DisplayValue`                                                                                                                                                                                                                                                                                                           | What a binding stores for a cell it will render — a primitive, or an object only that binding understands. The engine hands it back untouched and stringifies it only when it is already a primitive. React's faces of these say `ReactNode` instead.                                                                                                                                                                                                                                                |
| `MobileCardRenderer<TRow>`                                                                                                                                                                                                                                                                                               | The neutral mobile-card renderer. A React table wants `ReactMobileCardRenderer`, whose field values are `ReactNode`.                                                                                                                                                                                                                                                                                                                                                                                 |
| `SummaryRowFn<TRow>`                                                                                                                                                                                                                                                                                                     | Map a set of rows to per-column summary cells — one shape for `summaryRow` and `groupAggregates`. The React face of core's neutral `GroupAggregatesFn`, so its values are `ReactNode`.                                                                                                                                                                                                                                                                                                               |
| `ReactComputedColumnSpec<TRow, TValue>`                                                                                                                                                                                                                                                                                  | Input to `computed` from `@adapttable/react`: the neutral spec with a React `column`.                                                                                                                                                                                                                                                                                                                                                                                                                |
| `ReactFormulaColumnsResult<TRow>`                                                                                                                                                                                                                                                                                        | What `buildFormulaColumns` from `@adapttable/react/formula` returns — the neutral result with `ColumnDef` columns.                                                                                                                                                                                                                                                                                                                                                                                   |
| `ReactColumnGroupDef<TRow>`                                                                                                                                                                                                                                                                                              | A parent header whose children are React `ColumnDef`s.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `ReactUseColumnLayoutResult<TRow>`                                                                                                                                                                                                                                                                                       | `useColumnLayout`'s result over React columns.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `ReactMobileCardField<TRow>` / `ReactMobileCardModel<TRow>` / `ReactMobileCardRenderer<TRow>`                                                                                                                                                                                                                            | One card field / a card's model / a custom card body, with `ReactNode` values rather than the neutral model's `DisplayValue`. See [mobile cards](./mobile.md).                                                                                                                                                                                                                                                                                                                                       |
| `ReactColumnResizeHandleProps` / `toReactColumnResizeHandleProps`                                                                                                                                                                                                                                                        | Resize-handle props typed for a React element / convert the neutral props to them. For adapter authors, from `@adapttable/react/adapter`.                                                                                                                                                                                                                                                                                                                                                            |
| `TableEngineConfigPatch<TRow>`                                                                                                                                                                                                                                                                                           | Live configuration a binding replays onto a committed engine: the incremental query options plus `locale`, `paginationMode`, `page` and `limit`.                                                                                                                                                                                                                                                                                                                                                     |
| `CapabilityPlan` / `CapabilityStaging`                                                                                                                                                                                                                                                                                   | A governed write's side-effect-free proposal / whether a capability honours `commit: "stage"`. See [AI integrations](./ai-integrations.md).                                                                                                                                                                                                                                                                                                                                                          |
| `CapabilityPartial`                                                                                                                                                                                                                                                                                                      | Whether a capability's `execute` applies `plan.payload` rather than its own arguments, and may therefore be offered for row-by-row approval. Defaults to `"unsupported"`. See [agent capabilities](./agent-capabilities.md).                                                                                                                                                                                                                                                                         |
| `ApprovalSubject` / `ApprovalResult`                                                                                                                                                                                                                                                                                     | What a reader is asked to confirm — the rows a write touches, or the operation behind a write that enumerates none / what they decided: a boolean for the whole write, or the positions they approved. See [agent capabilities](./agent-capabilities.md).                                                                                                                                                                                                                                            |
| `SharedApproval`                                                                                                                                                                                                                                                                                                         | The assistant's own approval defaults — the policy string it already took, or `{ policy, presentation }`. An action overrides either field on its own through `ai`. See [agent capabilities](./agent-capabilities.md).                                                                                                                                                                                                                                                                               |
| `SortableValue`                                                                                                                                                                                                                                                                                                          | Comparable primitive returned by a sort-value extractor.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `SortByOption`                                                                                                                                                                                                                                                                                                           | `{ value, label }` for the mobile sort-by select.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `GetCellSpan` / `GetCellSpanArgs` / `TableBodyCell` / `BodyCell` / `CellSpanRequest` / `CellSpanAppearance`                                                                                                                                                                                                              | Span callback / `{ row, column, rowIndex, columnIndex, sectionRows, sectionRowIndex }` / one rendered body cell on the main / adapter entry / `{ colSpan?, rowSpan? }` / `"merged" \| "plain"`. See [row and column spanning](./row-spanning.md).                                                                                                                                                                                                                                                    |
| `ExtraRow` / `TableExtraEntry` / `ExtraEntry` / `ExtraRowKind`                                                                                                                                                                                                                                                           | Host-injected slot / the spliced main-entry / adapter-entry shape / `"separator" \| "fullWidth"`. See [full-width and separator rows](./full-width-rows.md).                                                                                                                                                                                                                                                                                                                                         |
| `insertExtraRows` / `insertExtrasBeforeRows` / `extraRowsForSection` / `isExtraEntry` / `extraRowsArmed` / `EXTRA_ROW_PARTS` / `EXTRA_OVER_SPAN_ROW_STYLE` / `EXTRA_OVER_SPAN_STYLE` / `extraHostFillStyle` / `extraCountBeforeRowIds` / `inflateBodyCellRowSpans` / `extraCoveredTableSlots` / `extraUncoveredColSpans` | Splice extras into a `kind`-tagged list / splice named extras in front of a pin section / extras whose target sits in this section / narrow one / whether any were asked for / the part names kits stamp / lift an extra above a continuing span / extra cell padding and RTL align / the host `rowStyle` fill for that extra's person / count extras in front of ids / grow a row span so extras do not drop the last person / slots an extra would leave open / uncovered colSpans for that extra. |
| `RowStyle` / `RowHeight`                                                                                                                                                                                                                                                                                                 | Per-row style callback / a number or `(row, index) => number`. See [row styling and heights](./row-styling.md).                                                                                                                                                                                                                                                                                                                                                                                      |
| `resolveRowStyle` / `resolveRowHeight` / `rowStyleSignature`                                                                                                                                                                                                                                                             | Merge style + height / read one height / memo digest of the resolved style.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `rowStyleArmed` / `estimateFromRowHeight`                                                                                                                                                                                                                                                                                | Whether either hook was passed / virtualizer `estimateSize` from `rowHeight`.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `RowPinState` / `RowPinSide`                                                                                                                                                                                                                                                                                             | `{ top, bottom }` id lists / `"top" \| "bottom"`. See [row pinning](./row-pinning.md).                                                                                                                                                                                                                                                                                                                                                                                                               |
| `RowPinningState` / `RowPinLabels`                                                                                                                                                                                                                                                                                       | Headless pin state and the three action strings.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ExportCsvProp`                                                                                                                                                                                                                                                                                                          | The configuration accepted by `exportCsv()`: `true`, an `ExportCsvOptions`, or absent. See [export](./customization.md#export).                                                                                                                                                                                                                                                                                                                                                                      |
| `WidthColumn`                                                                                                                                                                                                                                                                                                            | A column reduced to what width resolution reads — its `key` and declared `width`.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `GroupedHeaderAlign`                                                                                                                                                                                                                                                                                                     | Alignment of a spanning group header: `"start"`, `"center"` or `"end"`. See [column groups](./column-groups.md).                                                                                                                                                                                                                                                                                                                                                                                     |
| `BuildGroupedFlatModelOptions`                                                                                                                                                                                                                                                                                           | What `buildGroupedFlatModel` flattens — `rows`, `groupBy`, `columns`, `getRowId` and the collapse/aggregate options. See [row grouping](./row-grouping.md).                                                                                                                                                                                                                                                                                                                                          |
| `HorizontalOverflow`                                                                                                                                                                                                                                                                                                     | `useHorizontalOverflow`'s result — a callback `ref` and `overflowing`, true only while the content is wider than its wrapper.                                                                                                                                                                                                                                                                                                                                                                        |
| `FeatureNoticeAppearance`                                                                                                                                                                                                                                                                                                | How an inert feature already looks to the person at the table: `"off"`, `"disabled"` or `"one-page"`.                                                                                                                                                                                                                                                                                                                                                                                                |
| `SESSION_ATTR`                                                                                                                                                                                                                                                                                                           | `data-adapttable-header-filter` — the attribute tying a header filter's trigger to its overlay, so one editing session is identifiable across both. See [filtering](./filtering.md).                                                                                                                                                                                                                                                                                                                 |
| `TableCommandOptions`                                                                                                                                                                                                                                                                                                    | What `tableCommands` needs for the table-wide entries: labels, plus `onPrint` / `onExport` / `onClearFilters` and `hasFilters`.                                                                                                                                                                                                                                                                                                                                                                      |
| `UseShortcutsOptions`                                                                                                                                                                                                                                                                                                    | What `useShortcuts` needs: `enabled`, the `shortcuts` list, `onCommand`, and where to listen.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `ValidationCheckResult`                                                                                                                                                                                                                                                                                                  | The outcome of `EditValidationState.check` — `allowed`, and `error` when it is not. See [cell editing](./cell-editing.md).                                                                                                                                                                                                                                                                                                                                                                           |
| `editableCellController`                                                                                                                                                                                                                                                                                                 | Derives one cell's editing controller. Returns `mode: "display"` whenever the host passed no `onCellEdit`, so a table that never opted in renders exactly as before.                                                                                                                                                                                                                                                                                                                                 |
| `FeatureHostState`                                                                                                                                                                                                                                                                                                       | The registrations a feature's `setup` collected — filter types, queued patches, menu factories, side-panel entries — as the table reads them. See [feature composition](./features.md).                                                                                                                                                                                                                                                                                                              |
| `FilterTypeExtend`                                                                                                                                                                                                                                                                                                       | One queued `extendFilterType` patch: the `type` being extended and the `patch` merged onto its spec.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ColumnMenuActionFactory`                                                                                                                                                                                                                                                                                                | A plugin's extra column-menu actions, appended after the built-ins.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ContextMenuItemsFactory`                                                                                                                                                                                                                                                                                                | A plugin's extra context-menu entries, appended after the built-ins.                                                                                                                                                                                                                                                                                                                                                                                                                                 |

## Development warnings

Misconfiguration warns once per message in development (silent in
production):

- no data tier, or both `source` and `data`/`onQueryChange` provided;
- duplicate column keys (sorting, selection, and column layout all target keys);
- unresolvable sorts (no matching column, or a non-primitive accessor without `sortValue`);
- a column `filter` whose key is also defined in the `filters` array (the array wins);
- `options: "auto"` on a tier with no full dataset, and async options that fail to load;
- two tables sharing a URL namespace without distinct `urlKey`s;

## Companion types

Every documented hook and component exports its option/result/prop types
under predictable names — `useFoo` ships `UseFooOptions` (and
`UseFooResult` where the return type is named), a component `Foo` ships
`FooProps` — and each companion follows its owner's stability tier. The
full set: `UseDataTableOptions`, `UseFrontendDataOptions`,
`UseServerDataOptions`, `UseTableDataOptions` / `UseTableDataResult`,
`UseTableUrlStateOptions`, `UseSavedViewsResult`, `UseSelectionOptions`,
`UseColumnLayoutOptions`, `UseColumnLayoutStorageStateOptions` /
`UseColumnLayoutStorageStateResult`, `UseColumnLayoutUrlStateOptions` /
`UseColumnLayoutUrlStateResult`, `UseRowPinningUrlStateOptions` /
`UseRowPinningUrlStateResult`, `UseQuerySourceOptions` (`selectPage` plus
optional `selectorKey` to re-project unchanged pages),
`UseActiveFilterChipsOptions`,
`UseExtraChipsOptions`, `UseBulkActionRunnerOptions`,
`UseBulkBarStateOptions`, `UseInfiniteScrollOptions`,
`UseScrollToTableTopOptions`, `UseTableVirtualizationOptions`,
`MountStaggerOptions`.

## The adapter contract

Everything the eight built-in adapters are made of ships from its own
entry point, **`@adapttable/react/adapter`** — the same public surface a
ninth adapter would use; there are no private channels. Same package,
same semver promise as the main entry. This tier is aimed at adapter
authors; app code rarely (if ever) imports from it:

```ts
import { useDataTableShell, paginationSlots } from "@adapttable/react/adapter";
```

A handful of names stay on the main entry even though adapters also use
them, because app-facing signatures reach them (`PinSide` in the column
layout state, `PaginationInfo` from `computePagination`, the
`useDataTable` prop-getter payload types, `ResolvedPaginationMode`,
`TableLayout`).

**Orchestration.** `useDataTableShell(props, renderAutoForm)` is the whole
shared engine behind a batteries-included `<DataTable>` — it resolves the
data tier, builds the declarative-filter runtime, wires the chrome, and
returns the `tableProps` / `toolbarProps` bundles
(`DataTableShellTableProps`, `DataTableShellToolbarProps`,
`DataTableShellChromeProps`, `DataTableShellGroupingPanelProps`).
`useStickyToolbarLayout`
and `resolveStickyToolbar` park search and page-size with a sticky header.
`DataTableShellProps`
is its kit-agnostic prop surface and `DataModeProps` the discriminated
`mode` union inside it (`mode="server"` requires `onQueryChange` at
compile time). `tableRenderModel(props)` / `TableRenderModel` derive the
shared render prelude from `SharedTableRenderProps`; `TableBodyRegion`
names which body region renders (desktop rows, mobile cards);
`VirtualTableRow` is one materialized virtual row/card entry.
HTML kits assemble the desktop table through `useDesktopTableAssembly`
(`DesktopAssemblyOptions` / `DesktopAssemblyProps` in,
`DesktopTableAssembly` out) and `createDesktopRow` — wiring, not pixels.
The reserved chrome widths are `DESKTOP_SELECTION_WIDTH`,
`DESKTOP_EXPANSION_WIDTH`, `DESKTOP_ACTIONS_WIDTH` (override via
`DesktopChromeWidths`). The plan names `DesktopHeaderLeaf`,
`DesktopTablePin`, `DesktopRowWiring`, `DesktopRowSlot`, `DesktopBodySlot`,
`DesktopGroupSlot`, `DesktopGroupEntry`, `DesktopExtraSlot`, and
`DesktopVirtualPadSlot`. Ant Design stays on its native `<Table>`. See
[customization](./customization.md#desktop-table-assembly).
`useResolvedAdapter` resolves the URL backend the way the shell does;
`PageSelector` projects a fetched page to rows, an optional total, and
optional `facets`, and
`InfiniteQueryLike` is the minimal `useInfiniteQuery` shape
`useQuerySource` reads (structural — TanStack Query stays a type-only
peer).

**Render plumbing.** The prop-getter payload types (`TableElementProps`,
`RowElementProps`, `CellElementProps`, `SearchInputElementProps`,
`SortButtonElementProps`, `RowClickProps`) name what `useDataTable`'s
getters and `rowClickProps` return. Pinning: `PinSide` / `PinnedSide` /
`PinOffset` / `PinLeads` describe the layout, `nextPinSide` cycles a
column's pin, `pinActionLabel` labels the action, and
`pinnedDataCellStyle` / `pinnedEdgeCellStyle` / `pinnedColumnWidth` /
`PinnedCellStyle` compute direction-aware sticky styles. Pager math:
`paginationSlots` / `paginationItems` build the windowed pager model
(`PaginationSlot`, `PaginationItem`, `PaginationInfo`). Column chrome:
`ColumnMenuChromeProps`, `ColumnMenuSlotProps`, `ColumnMenuRow`, `ColumnMenuLabels`,
`ColumnDragState`, `ColumnDragRowAttrs`, `ColumnDropProps`,
`ColumnRowDragProps`, `ColumnReorderKeyProps`,
`ColumnResizeHandleProps` and `COLUMN_DND_MIME` power the column menu's
reorder/resize/pin rows. Toolbar glue: `SearchInputState` (debounced
search binding), `FilterTriggerToggle` (popover/drawer trigger
handlers). Editing/grouping glue: `focusEditorOnMount`,
`rowEditingSignature`, `HeaderGroupCell`, `HtmlGroupedHeaderCell`, `headerGroupRow` /
`headerGroupRows` / `htmlGroupedHeaderPlan` / `groupedHeaderChildRule` /
`groupedHeaderCellStyle` / `groupedHeaderLabelStyle` / `groupedHeaderAlign` / `columnGroupStubStyle` / `COLUMN_GROUP_STUB_WIDTH`, `columnGroupHeaderCaption`. Each adapter mounts `ColumnGroupToggle` /
`ColumnGroupToggleProps` over `ColumnGroupToggleChrome` /
`ColumnGroupToggleChromeProps` / `ColumnGroupToggleSlots` /
`ColumnGroupToggleButtonProps`. Shared
utilities: `logicalAlign` (logical → physical alignment),
`mergedCellStyle` (spreadsheet merge paint for a spanned cell),
`cellSpanMark` (`"2x1"` on the origin),
`cellFlashAttr` / `rowFlashSignature` (`data-flash` on a patched cell),
`resolveMobileLabel` (a card field's caption), `isSelectedCell` (whether a
cell's props put it inside the selected range, for a kit applying its own fill),
`shallowEqualByKeys`, `resolveVirtualRows`, `SHARED_DESKTOP_ROW_KEYS`,
`DEFAULT_CARD_SIZE_PX`, `useKeyedVirtualization` / `KeyedVirtualization`
(virtualize an opaque keyed list, e.g. grouped entries),
`useMountStagger` (the `animate` stagger),
`useOverlayTransition` / `OverlayTransition` (turns an `open` boolean into
`{ rendered, state }` — `rendered` outlives `open` by one exit so an overlay
has something to animate on the way out, and reduced motion skips both edges),
`OVERLAY_MOTION` (the durations and curves the unstyled, shadcn, Base UI and
Radix drawers share),
`useEscapeClose` / `EscapeCloseOptions` (close an overlay on Escape wherever
focus is, since kits disagree about when they do it themselves — pass
`ignoreWithin` a selector for controls inside that answer the key first, so
one Escape closes one layer),
`restoreFocusSoon` (hand focus back to the control an overlay was opened
from, reclaiming it once if the kit's own focus handling drops it, and
leaving focus a reader moved elsewhere alone), and the inline icon set
(`FiltersIcon`, `SearchIcon`, `EyeIcon`, `GripIcon`, `PinIcon`,
`ExpandChevron`, `sortArrow`). Row reorder chrome (on each adapter):
`RowReorderHandle`, `RowReorderHandleProps`, `RowReorderButtons`,
`RowReorderButtonsProps`. Layout: `RowReorderHandleChrome`,
`RowReorderButtonsChrome`. Also `RowReorderAnnouncer`,
`rowReorderSignature`, `REORDER_COLUMN_WIDTH`,
`ROW_DND_MIME`. Row pin chrome: `rowPinSignature`, `rowSourceIndex`,
`pinnedRowStickyStyle`, `pinnedRowCellStyle`, `pinnedRowPart`,
`pinnedRowSticky`, `orderedCardEntries`,
`bindMobileCardList`, `mobileCardListStyle`,
`useOffsetHeight`, `PINNED_TOP_PART`, `PINNED_BOTTOM_PART`.

**Bulk actions.** `useBulkBarState` / `BulkBarState` /
`BulkBarChromeProps` derive everything a bulk-action toolbar renders
(selected ids, in-flight action, the "select all matching" banner);
`BulkActionOutcome` is a run's result and `bulkActionErrorMessage` its
failure text.

**Misc helpers.** `deriveSortByOptions` builds mobile "Sort by" options
from sortable columns; `resolveColumns` fills declarative column
defaults (humanized headers, locale-resolved accessors);
`resolveDisabledReason` normalizes a row action's `disabled`;
`useSummaryCells` maps a `summaryRow` builder over the visible columns;
`ResolvedPaginationMode` is `paginationMode` after `"auto"` resolves;
`TableLayout` names which layout is rendering (desktop table or mobile
cards); `TableStateMutators` is the setter half shared by `TableSource`
and `useTableUrlState` — the same mutations exist whether state lives in
the URL, in memory, or behind a server query;
`localizedColumnPath`, `normalizeLocaleTag` and `resolveLocaleTag` are
the shared locale-resolution algorithm (see [i18n & RTL](./i18n-rtl.md)).

**Conformance.** `@adapttable/core/conformance` is the suite every built-in
adapter passes, with no test runner and no framework in it.
`tableConformanceTests(driver, harness)` returns the tests
(`ConformanceTest`) for a runner to register. A `ConformanceDriver` mounts
the table for a `ConformanceScenario` and returns a `ConformanceMount`; a
`ConformanceHarness` carries the runner's `expect` (`ConformanceExpectation`)
and DOM Testing Library's `fireEvent` (`click` and `keyDown`) and `waitFor`.
A scenario's `labels` (`ConformanceLabels`) are the host's words the table must
use. `CONFORMANCE_ROWS`
(`ConformanceRow`) and `CONFORMANCE_COLUMNS` (`ConformanceColumn`) are the
scenario data. [Testing an adapter](./building-an-adapter.md#testing) shows a
React driver.

## The AI packages

`@adapttable/ai` is React-free and model-neutral: it turns a live table into a
capability catalog an agent can read and call, and every protocol adapter below
is a view over that one catalog. `@adapttable/ai-react` is the binding that
mounts it on a React table. See [AI & agents](./ai.md), the
[HTTP contract](./ai-http.md) and
[protocol integrations](./ai-integrations.md).

### `@adapttable/ai` — the session and its catalog

`createAgentSession(options)` builds the session from a `CreateAgentSessionOptions`
description of the table: `AgentApply` is the write seam the host fills,
`AgentObservation` is what the table reports each time it is read, `AgentColumn`
/ `AgentFilter` / `AgentFilterOption` describe its shape, `AgentLimits` and
`AgentPolicy` its bounds, and `AgentRowAddressing` / `RowAddressScope` say how a
row may be named. The result is an `AgentSession`: `buildManifest` renders its
`AgentManifest` (and per-column `AgentManifestAggregation` ids), `enabledKeys` lists what the table actually offers, and
`CAPABILITY_KEYS` / `CapabilityKey` are the built-in names.

A capability is a `CatalogEntry` backed by an `AgentCapabilityDefinition`.
`AgentCapabilityKind` is its effect class (`read`, `view`, `write`,
`destructive`), which is what decides how much ceremony a call needs;
`CapabilityFamily` and `familyOf` group related keys for one-round discovery,
capped at `MAX_FAMILY_GUIDES`. `CapabilityGuide` is the per-capability
instruction, read with `guideOf` and `summaryOf`;
`AgentCapabilityContext` is what a custom capability's handler receives, and
`CapabilityPartial` / `CapabilityPlan` / `CapabilityStaging` describe work a
capability can stage rather than apply at once. `JsonSchema` and
`validateSchema` are the argument contract. Calls return an `ExecuteResult`
(`WriteExecuteResult` for writes, with `WriteRowResult` per row) or an
`ExecuteError`. `AgentColumnAuthoring` is the column-level authoring a table
author supplies.

**Discovery.** `discover(request, source, limit?)` answers a `DiscoveryRequest` with a
`DiscoveryResult` drawn from a `DiscoverySource`, so a model asks once instead
of being handed everything. `createDiscoveryCache` memoizes it as a
`DiscoveryCache`, holding `DEFAULT_CACHE_GUIDES` guides across
`DEFAULT_CACHE_VERSIONS` contract versions.

**Context.** `buildAgentContext(session, options, inputs)` (also on the
narrower `@adapttable/ai/context` entry) renders an
`AgentContext` from `AgentContextOptions` and `AgentContextInputs`;
`AgentContextProfile` picks how much to send — `full` by default, bounded only
by `MAX_CONTEXT_BYTES`, with `DEFAULT_COMPACT_TOKENS` the budget `compact` opts
into, a guide left out carries
a `DeferralReason` saying which of the two cut it, and `ContextIncludeError`
names an `include` entry the table does not publish. `ContextCapability` and
`ContextColumn` are the rendered pieces, `AgentContextContract`,
`AgentContextView` and `AgentContextSelection` the halves a request carries.
`renderAgentContext(context)` turns it into the prompt text and
`agentInstructions(input)` writes the general rules beside it from an
`AgentInstructionsInput`; `agentSystemPrompt` composes the two.
`sampleColumnValues` and `sampleColumns` give a model real values to match on,
bounded by `SAMPLE_CAP`, with `matchesType` deciding what is worth sampling.
Row values reach a model only inside `rowProvenance`'s
`RowProvenanceEnvelope`, which marks them untrusted; `RowWindow`,
`RowWindowRow`, `RowReadQuery`, `RowRef`, `RowKeyRef`, `RowPositionRef` and
`ResolvedRow` are the read surface behind it.

**Approval.** `sharedApproval` and `resolveApproval` turn a `SharedApproval`
into a `ResolvedApproval`. A turn opens with `openTransaction`, collects
`PendingApproval`s, records answers with `recordDecision`, settles them with
`settleDecisions` and ends at `closeTransaction`; `ApprovalTransaction`,
`ApprovalSubject`, `ApprovalOutcome` and `ApprovalResult` are its types.
"Always allow" is deliberate rather than sticky: `createApprovalMemory` holds an
`ApprovalMemory` scoped to a contract version, `mayAlwaysAllow` says whether a
capability is eligible, and `assertAlwaysAllow` validates an `AlwaysAllowInput`
against the live catalog at build time, raising `ApprovalAlwaysAllowError` on a
key no table offers — a typo opts nothing in silently.

**Assistant.** `createTableAssistant(inputs)` (also on the narrower
`@adapttable/ai/assistant` entry) is the headless conversation
store: `TableAssistantInputs` configures it, `TableAssistantStore` is the
handle and `TableAssistantSnapshot` the value a view renders, holding
`AssistantMessage`s and an `AssistantStatus`. A turn is an `AssistantTurn` in an
`AssistantConversation` of `AssistantExchange`s, produced by an
`AssistantPlanner` or carried by an `AssistantTransport` (`AssistantRequest` in,
`AssistantTransportReply` out). `AssistantAction`, `AssistantProposal` and
`WriteProposal` are what it asks to do, `AssistantOutcome` /
`AssistantOutcomeStatus` how it ended, and `AssistantUnresolved` why it could
not. `AssistantQuestion`, `AssistantQuestionOption` and `AssistantAnswer` are
the question channel. `AssistantSuggestion`s are filtered by
`eligibleSuggestions` and checked by `assertUniqueSuggestions`;
`CapabilityPresentation` says how a capability is shown. Every turn is given an
`AssistantTurnInput` — an `AssistantSendInput` when the reader asked (its
`audio` an `AssistantAudio` clip when `sendClip` sent a recording) and an
`AssistantResumeInput` when it is rejoining — and a transport that names work
outliving its connection through `onResumable` hands back an
`AssistantResumeHandle` that `resume` takes. `AssistantInterruption` says which
of the three ended a turn no reply ended. A capability says how far it has got
through `CapabilityProgress` on its execution context; the session names the
call and passes it on as `AgentProgress`. Receipts come from
`receiptFromResult` / `receiptsFromResults` as `AssistantReceipt`s with an
`AssistantReceiptStatus` and `AssistantReceiptSubject` — `subjectFor` builds
one for a built-in capability, as `AssistantReceiptTerm` pairs of column label
and formatted value — and `turnStatus` reads the `AssistantTurnStatus`.

**Undo.** `planUndo` turns a finished turn into an `AssistantUndo` of
`UndoCall`s, or an `UndoBlock` saying why not (`isUndoBlock` narrows it,
`undoBlocked` explains it); `runUndo` applies one, and `AssistantUndoOffer` is
what the panel shows.

**The table binding.** `TableAgentBridge` is how a host receives live updates —
a session to attach, a manifest to publish, a pending approval, a reader for the
live view, and an `AlwaysAllowedState` naming what the reader has agreed to stop
being asked about, with the `revoke` that takes one back. The panel reads those
back as `AssistantAllowance` entries — one per capability, each carrying the
name the table knows it by. A binding states what its own runtime offers through
`ObservationInputs` and `agentObservation` turns that into the observation a
session reads the table through, so every binding answers "what can this table
do" the same way. `contractFingerprint` and `contractVersion` identify the
contract a backend was sent, `displayProposals` and `ProposalResolver` render
proposed writes.
`observationFromNeutral`, `agentColumnsFromNeutral`, `readRowsFromNeutral`,
`resolveRowFromNeutral`, `monotonicRevision`, `revisionToken`,
`LiveObservationOptions`, `NeutralQueryOverlay` and `TableAgentColumnPatch`
build that observation from the neutral engine, and `agentFiltersFromDefs` with
`FilterCatalogColumnPatch` build the filter half. Aggregations are described by
`AgentAggregations`, `AgentAggregationsPatch`, `AgentAggregationColumn` and
`AgentAggregateOperation`, and applied with `aggregationsFor` /
`applyAggregations` over `AggregationInputs` and `AggregationState`. Cell writes
are `AgentCellEdit`s.

**A live table runtime.** `bindLiveSession(inputs)` binds the `TableRuntime` a
binding publishes to one `AgentSession`: it reads the runtime view as the
observation, serves row reads and row resolution from it, and applies view
changes and cell writes through the view's own setters, with the host's `apply`
callbacks laid over them. `LiveSessionInputs` carries the binding's
`TableAgentRuntimeOptions`, the runtime, a `RevisionCounter` from
`createRevisionCounter`, and the binding's flush, approval and progress hooks;
`viewRevisionStamp` is the stamp that counter moves on.
`viewInputsFromRuntime` reads the same view in the shape the context builder
takes, and `sampledColumns` names the columns whose author asked for live
values. For approvals, `readerResolver` is the `ProposalResolver` over the
runtime view, `capabilityKind` and `alwaysAllowFor` are what `mayAlwaysAllow`
is asked with, `perItemRefusal` refuses every undecided row with the reader's
stated reason, and `exclusionKey` makes an exclusion list comparable.
`@adapttable/ai-react`'s `tableAgent` is this binding for React.

**A table agent controller.** `createTableAgentController(inputs)` is everything
a binding's table agent does on top of that session, with no framework in it:
it parks a write on the table's own approval surface, remembers what the reader
waved through, republishes a changed manifest, announces approvals to the
bridge, samples the columns that asked, and offers the table to a browser agent.
`TableAgentControllerInputs` carries the binding's live
`TableAgentControllerOptions` (the runtime options plus `bridge` and `webmcp`,
narrowed by `TableAgentWebMcpOptions`), its runtime and its commit hooks. The
`TableAgentController` it returns has `subscribe` and `getState` — a
`TableAgentState` holding the session, the open approval, the always-allow
list, progress and a `TableAgentViewReader` — plus `sync`, called after each
commit, and `disconnect`, called when the table goes away. `tableAgent` in
`@adapttable/ai-react` is a thin subscriber to it.

**Row and bulk actions.** `tableActionCapabilities(declared, source)` turns a
table's `DeclaredTableActions` into one `AgentCapabilityDefinition` per action,
keyed `rowAction.<key>` or `bulkAction.<key>`, for
`createAgentSession({ capabilities })`; the `TableActionSource` supplies the
live actions, rows and selection each time one plans or runs.
`tableActionSignature(declared)` changes when the offered set does — keys,
labels, confirmation and approval. See
[agent capabilities](./agent-capabilities.md#row-and-bulk-actions).

**Streaming.** `createStreamReply` emits `AgentStreamEvent`s of
`AgentStreamEventKind`, capped at `MAX_STREAM_EVENTS`; `splitRecords` and
`parseStreamRecord` read them back, and `AgentStreamError` is the failure.

**What a table's pages are.** `agentPagination` turns what a binding can say
about its own source — `PaginationInput`: the current page and size, the sizes
the host offers, the counted total for the _current query_ where there is one,
whether a page number may be named — into an `AgentPagination`. It divides the
page count from the total and works out whether a further page exists; anything
unknowable is left absent rather than guessed, so "there is no next page" stays
distinct from "nobody counted". `pageRefusal` and `pageSizeRefusal` answer
whether a requested page or size can be served, in a sentence naming both
sides. The session checks both before the host is called, so a page past the
end is refused rather than reported as a move that happened.

**What a table can do.** `agentObservation` decides that once, for every
binding: a capability is available when the host wired a callback for it or the
runtime already offers it. A binding states its own half — `ObservationInputs`,
carrying `RuntimeOperations` for what the runtime does by itself, the host's
`AgentApply`, an `ObservedPolicy` and an `ObservedView` — and reads the answer
back. The page and size it publishes come from the `AgentPagination` it
carries, so the bound a session enforces and the pages a model is told about
are the same number by construction.

**When the context will not fit.** A `compact` build, or any build given a
`tokenBudget`, budgets the whole payload.
Column descriptions that do not fit are named in `selection.deferredColumns`
and fetched with `columns.describe`; a deferral says which kind of thing it was
through `DeferralKind`. A `tokenBudget` the caller chose that nothing can
satisfy raises `ContextBudgetError`, which names the floor the table costs with
everything deferrable already deferred.

### `@adapttable/ai/json` and `/openai`

Two shapes of the same catalog: JSON Schema tool definitions, and OpenAI
function tools whose names are mapped by `openAiToolNameMap` because the
provider's naming rules are narrower than a capability key.

### `@adapttable/ai/http` — the wire contract

`agentHttpJsonSchema` is the published request schema as a
`JsonSchemaDocument`, and `AGENT_HTTP_LIMITS` / `AgentWireLimits` are its
bounds. A reply carries `AgentHttpToolCall`s and answers them with
`AgentHttpToolResult` / `AgentHttpToolFailure`, whose payload is an
`AgentHttpToolValue` (`isToolValue` narrows it); `AgentHttpAnswer` is the text,
`AgentHttpQuestion` with `AgentHttpQuestionOption` the question channel,
`AgentHttpAudio` a spoken turn, and `AgentHttpUnresolved` a turn that stopped.
`AgentTurnError` is the typed failure. `PhaseState` is the phase-bound
execution record that makes a replayed call identical rather than repeated.
Contract pinning is a `PinRecord` with a `PinStatus`, held for
`DEFAULT_PIN_TTL_MS` across at most `DEFAULT_PIN_CONNECTIONS` connections, and
acknowledged with an `AgentHttpPinAck`.

### `@adapttable/ai/webmcp` — in-page tools

`registerWebMcpTools(session, options)` publishes the catalog on
`document.modelContext` — `ModelContextLike` is the shape it needs, so a test
or a polyfill can stand in. `WebMcpOptions` configures it, `WebMcpRegistration`
is the handle, and each `WebMcpTool` carries `WebMcpAnnotations` derived from
the capability's own `kind` rather than authored twice. Results are a
`WebMcpResult` of `WebMcpContent`.

### `@adapttable/ai/mcp` and `/mcp-apps` — MCP servers and embedded views

`toMcpToolList(session)` and `toMcpResourceList(session)` render an
`McpToolList` and `McpResourceList` with `McpListMeta`, each tool carrying
`McpToolAnnotations`; `mcpToolResult` returns an `McpToolResult` of
`McpContent`.

MCP Apps puts a real table inside the conversation. `mcpAppResource(session, options)`
declares an `McpAppResource` at a `mcpAppUri` with the `MCP_APP_MIME` type and
an `McpAppSecurity` policy `mcpAppCsp` renders; `McpAppResourceOptions`
configures it and `withMcpAppMeta` / `mcpAppToolMeta` attach the metadata that
binds a tool to its view. Inside the frame, `createMcpAppBridge(options)` speaks
JSON-RPC over an `McpAppChannel` to the host: `McpAppBridge` is the handle,
`McpAppBridgeOptions` configures it, `McpAppHostCapabilities` is what the host
admits to, and `McpAppToolInput` / `McpAppToolOutcome` report the host's own
tool traffic. `approveThroughHost` and `askThroughHost` route approval and
questions to the host's UI as an `McpAppElicitRequest` of
`McpAppElicitOption`s, answered with an `McpAppElicitResult`.

### `@adapttable/ai/ag-ui` — the AG-UI protocol

`aguiTransport(options)` is an `AssistantTransport` over an `AgUiConnection`;
`AgUiOptions` configures it. `aguiTools(session)` renders the catalog as
`AgUiTool`s named by `aguiToolName`. A run takes an `AgUiRunInput` of
`AgUiMessage`s and streams `AgUiEvent`s to an `AgUiRunOutcome`; an
`AgUiInterrupt` pauses for approval or a question and is answered with an
`AgUiResume` carrying an `AgUiResumeStatus`. `statePatch` emits RFC 6902
`JsonPatchOperation`s for shared state, and `AgUiProtocolError` is a malformed
or failed run.

### `@adapttable/ai/ai-sdk` — the AI SDK UI message stream

`aiSdkTransport(options)` is an `AssistantTransport` over an `AiSdkConnection`
configured by `AiSdkOptions`; `aiSdkTools(session)` renders `AiSdkTool`s named
by `aiSdkToolName`, and `aiSdkCapability` maps a tool name back to its
capability. The route sends `AiSdkRequest`s and streams `AiSdkPart`s —
`AI_SDK_STREAM_VERSION` is the version this adapter speaks and
`assertAiSdkVersion` refuses a stream it does not understand. Tool results go
back as `AiSdkToolOutput`s and approvals as `AiSdkApprovalResponse`s;
`AiSdkProtocolError` is a malformed or failed stream.

### `@adapttable/ai/voice` — dictation and clips

`createSpeechInput(options)` returns a `SpeechInput` whose `SpeechState` holds a
`SpeechStatus`. `SpeechMode` picks between the browser's own recognizer and
recording an audio `SpeechClip` for a backend to transcribe;
`SpeechInputOptions` and `VoiceOptions` configure it, and `rememberLanguage` /
`readRememberedLanguage` keep the reader's dictation language between visits.

### `@adapttable/ai-react` — the React binding

`tableAgent` mounts a session on a live table and `useTableAssistant` drives the
conversation, exposing the same `TableAssistantStore` and
`TableAssistantSnapshot` as the headless store, including its `AssistantQuestion`
and `AssistantAnswer` channel. `useSpeechInput(options)` is the hook form of the
speech input, taking `UseSpeechInputOptions`.

### The pieces in core and react

`@adapttable/core` exports `ColumnAiOptions` — the per-column `ai` block a
table author writes to describe a column to a model — and
`BUILTIN_AGGREGATE_LABELS`, the localized names of the built-in aggregate
functions, so a surface naming an aggregate reads the same word the table
shows.

`@adapttable/react/adapter` exports what an adapter needs to render the
assistant: `AGENT_VIEW_STATE` / `AgentViewState`,
`AGENT_ALWAYS_ALLOW_STATE` / `AgentAlwaysAllowState` and
`AGENT_PROGRESS_STATE` / `AgentProgress` — how far a running capability has
got — are the shared state keys,
`TableAssistantLanguageChipProps` is the dictation-language slot, and
`SpeechInputHandle` / `SpeechInputState` / `SpeechInputStatus` are the
structural view of a speech input — structural so that `@adapttable/react`
describes dictation without depending on `@adapttable/ai`.

The rendered assistant carries two blocks an adapter draws itself:
`TableAssistantQuestionView` with its `TableAssistantQuestionOption`s is a
question waiting on the reader, and `TableAssistantUndoView` is the offer to
put back what the last turn changed. `TableAssistantResumableView` says there
is work a released connection left running, which the panel offers to rejoin,
`TableAssistantProgressView` is how far a running capability has got, and
`TableAssistantAllowanceView` is one capability the reader stopped being asked
about.

`deriveRuntimeOperations` reads which view operations a live runtime offers by
itself, for a binding projecting them into `@adapttable/ai`'s
`agentObservation`. It reports what the runtime does; what that means for a
capability is decided there, once, rather than per binding.

## The Angular binding

`@adapttable/angular` is the headless binding for Angular 20 and newer. It
adapts the same core stores as `@adapttable/react`, as signals, and draws no
controls: the host writes its own markup.

- `injectFrontendData(options)` is the in-memory tier: it takes
  `FrontendDataOptions` (the rows, as a value or a signal, plus the URL-state
  options) and returns a signal of the core `TableSource`.
- `injectTableUrlState(options)` is the URL-synced view state: a
  `TableUrlState` with a `state` signal and the store's setters, configured by
  `TableUrlStateOptions`. `ADAPTTABLE_URL_ADAPTER` is the injection token that
  sets the URL adapter every table under an injector uses, such as one over the
  Angular Router.
- `injectDataTable(options)` is the headless table, configured by
  `DataTableOptions` and returning `DataTable`: rows, visible columns,
  pagination, sort, search, labels and direction as signals, plus the core
  prop getters (`tableAttrs`, `headerCellAttrs`, `sortButtonAttrs`,
  `rowAttrs`, `cellAttrs`, `searchInputAttrs`, `cardAttrs`), each an `Attrs`
  record. It also says what the table's frame shows: `bodyRegion` (skeleton,
  empty, cards or table), `emptyVariant`, `showFooter`, `pagerSlots`,
  `pageSizeOptions`, `canLoadMore` with `loadMore` and the load-more
  attributes for an infinite list, and `statusAnnouncement`, the sentence a
  sort or a page speaks. `injectIsMobile` (with `IsMobileOptions`) is the viewport breakpoint
  as a signal.
- `injectRowSelection(options)` is row selection as signals, configured by
  `RowSelectionOptions` and returning `RowSelection`: the selected ids, the
  select-all tri-state, the toggles, and the attributes of the row and
  select-all checkboxes. Pass it to `injectDataTable` as `selection`, and each
  row states whether it is selected. It is uncontrolled unless `selectedIds`
  is given.
- `injectGridFocus(options)` is keyboard cell navigation, configured by
  `GridFocusOptions` and returning `GridFocus`: the active cell and range as
  signals, the announcement, and attribute getters that wrap the table's own
  with the grid's roles, indices, roving tab stop and handlers. Off, they are
  the table's attributes unchanged.
- `AdaptLiveRegion` makes an element a polite, visually hidden live region
  that speaks its text — the table's status and the grid's announcer.
- `ColumnDef` is the Angular column. Its `cell`, `headerCell` and `footer`
  are a `Renderer`: an `ng-template` or a standalone component, which receives
  a `CellContext` or a `HeaderContext`. `resolveColumns` fills the defaults a
  column leaves out, and `ResolvedRenderer` is a renderer split into its
  template or component.
- `AdaptCell` and `AdaptHeader` render a column's content into the host's own
  `<td>` and `<th>`, `AdaptCellTemplate` declares a cell template beside the
  table (`<ng-template adaptCellTemplate="status" let-row>`), and
  `AdaptAttrs` applies an `Attrs` record to an element.
- `provideAdaptTableFeatures(...features)` composes features through
  dependency injection into the `ADAPTTABLE_FEATURES` multi-provider; an
  `AdaptTableFeature` has any of `apply` (configuration it merges into the
  table), `setup` (registrations against the live table) and `renders` (the
  slots it fills, each drawn by a `SlotComponent`). `extendFeature` adds
  renders to a core feature, which is how a kit puts its own controls in;
  `featureOptionsOf` is the merged configuration of a feature list.
- Slots: `AdaptSlot` draws what the table's features put in one named slot,
  handing each component the slot's props; `SlotFills` is the table's map of
  fills, `SlotTable` what a slot component can ask of its table, and
  `ADAPTTABLE_SLOT_TABLE` the token that provides it. `AdaptControl` draws one
  kit control inside a Chrome, and `AdaptIcon` draws a core glyph as SVG.
- Column layout: `DataTableOptions` takes `ColumnLayoutOptions` (controlled
  or default layout, the change callback and the rename handler), and the
  table's `layout` is a `ColumnLayout` signal — hidden, order, pins, widths
  and names with their setters. `injectColumnDrag` returns a `ColumnDrag`
  (row and grip attributes that reorder a Columns menu by drag or keyboard),
  and `injectColumnRenameEditor` the inline column-name editor.
- Filters: `filterRuntimeFor` (`FilterRuntimeOptions`) derives a
  `TableFilters` runtime from the definitions — the predicates and the URL
  keys; `filterChipsFor` the active chips and their count;
  `filterOptionsFor` a definition's choices as a `FilterOptionsState`; and
  `textFilterFor`, `rangeFilterFor` and `booleanFilterFor` the per-field
  widgets a kit's form draws. `AdaptFilterTreeChrome` (with
  `AngularFilterTreeDisclosureProps`) and `AdaptChecklistChrome` are the
  nested AND/OR builder and the checklist filter, structure only; the kit
  hands its controls in `slots`. `AdaptGroupingPanelChrome` is the grouping
  strip — chips, insertion carets, aggregations and the ungroup target —
  with `GroupingPanelSlots`, `AngularGroupingPanelSurfaceProps` and
  `AngularGroupingPanelAggregationItemProps`. `groupingPanel` (with
  `GroupingPanelExtras`) is the feature that owns the group-by state;
  `injectGroupingPanelState` (`GroupingPanelStateOptions`) publishes the
  strip's props for the `GROUPING_PANEL` slot. `virtualize`
  (`VirtualizeOptions`) windows the body through `@tanstack/angular-virtual`;
  `injectTableVirtualization` / `injectKeyedVirtualization` (with
  `TableVirtualizationOptions` / `KeyedVirtualizationOptions`) and the
  `injectTableVirtualizer` / `injectKeyedVirtualizer` scroll helpers are the
  headless hooks kits call. `cellNavigation` (`CellNavigationOptions`) turns
  on the keyboard grid; `injectGridFocus` is the underlying hook.
  `rowReorder` / `injectRowReorder` (`RowReorderStateOptions`) publish the
  drag and keyboard grab model. `editing` / `injectCellEditing`
  (`CellEditHandler`, `CellEditingOptions`) arm in-place cell edits;
  `rowEditing` / `injectRowEditing` (`RowEditHandler`,
  `RowEditingInjectOptions`) and `batchEditing` / `injectBatchEditing`
  (`BatchEditHandler`, `BatchEditingInjectOptions`) arm whole-row and
  batch commits.
- Actions: `injectBulkActionRunner` runs bulk actions and returns a
  `BulkActionRunnerState`; `rowActionsFor` (`RowActionsOptions`) is the
  actions column's list, with Duplicate and Delete appended for the host's
  handlers.
- Toolbar: `injectDensity` (`DensityOptions`, returning `DensityState`) is
  row density kept in the URL, `injectFullscreen` the fullscreen toggle,
  `injectExportCsv` (`ExportCsvHandlerOptions`) the Export button's state,
  and `injectSavedViews` (`SavedViewsOptions`, returning `SavedViewsState`)
  the saved views over the table's URL. `urlAdapterFor` resolves the one URL
  adapter a table and its features share.
- `fromStore(store, options)` turns any core store, an `ExternalStore`, into a
  read-only signal that ends with its injector (`FromStoreOptions`).
  `MaybeSignal` and `MaybeSignalOptional` are the option types that take a
  value or a signal of one.

`@adapttable/angular-unstyled` is the Angular table drawn with native HTML,
unpublished while it reaches parity with the React kits. `AdaptDataTable`
(`<adapt-data-table>`) takes the rows, columns and row key as inputs and
renders search, sorting, paging, the phone card layout, row selection and
keyboard cell navigation with the `data-adapttable-part` names every kit
shares. Its `features` input composes `columnMenu`, `filters`,
`headerFilters`, `bulkActions`, `rowActions` (`RowActionsFeatureOptions`),
`densityChooser`, `fullscreen`, `exportCsv`, `savedViews`,
`groupingPanel`, `virtualize`, `cellNavigation`, `rowReorder`, `editing`,
`rowEditing` and `batchEditing`; `filtersMode`
(`FiltersMode`) picks the anchored popover or the drawer. Each feature draws
the kit's own native controls. `AdaptGroupingPanel` draws the grouping
strip with those same native controls. `paginationMode` and `maxHeight` arm
infinite lists and a scroll-box window. `TableView` is what the table renders from
once its inputs have arrived, and `FiltersView` is the filters on that view:
the button, the open panel, and the form, overlay, chips and header funnels.

## Other packages

- `@adapttable/i18n` — `getLabels(locale)`, `getDirection(locale)`,
  `isRtlLocale(locale)`, `hasLocale(locale)`, `primarySubtag(locale)`,
  `RTL_LANGUAGES`, `locales` (keyed by `LocaleKey`) and the bundled
  presets (`en`, `ar`, `de`, `es`, `fr`, `he`, `it`, `ja`, `pt`, `zh`,
  … including `zhTW`) — see [i18n & RTL](./i18n-rtl.md).
- `@adapttable/cli` — binary `adapttable init [--force]`; programmatic
  `detectKit`, `choosePackageManager`, `installCommand`, `scaffoldFiles`,
  `runInit` plus the pieces they compose: `KITS` / `KitInfo` / `SHADCN`
  describe the detectable kits, `packagesFor` and `mergeDependencies`
  compute what to install, `starterComponent` / `ScaffoldFile` /
  `STARTER_PATH` describe the scaffold, `PackageManager` names the
  supported managers, `InitError` is the typed failure, and
  `InitOptions` / `InitResult` / `InitIO` parameterize `runInit` for
  testing.
- **Adapter packages** — each exports its `DataTable` with `DataTableProps`,
  `DataTablePropsBase`, `DataTableSlots` and `SavedViewsMenuProps` (plus the
  shared core re-exports). `DataTableProps` is `DataTablePropsBase &
DataModeProps`: the base carries every prop except the data mode, which is
  the half to name when you wrap or extend a table's props without committing
  to a tier. `@adapttable/unstyled` also exports `IconProps`, the props its
  exported icons take, so a caller supplying one has a name for the argument; Radix and Base UI export their accent unions
  (`RadixAccentColor`, `BaseUiAccentColor`); Mantine also exports its
  chrome as reusable components (`ActiveFilterChips`, `AutoFilterForm`,
  `EmptyState`, `ErrorState`, `FilterDrawer`, `PaginationFooter`,
  `TableSkeleton`, each with a `…Props` companion:
  `ActiveFilterChipsProps`, `AutoFilterFormProps`, `EmptyStateProps`,
  `ErrorStateProps`, `FilterDrawerProps`, `PaginationFooterProps`,
  `TableSkeletonProps`); unstyled and shadcn export their building blocks
  (`FilterPanel` / `FilterPanelProps`,
  `FilterPopover` / `FilterPopoverProps`, `AutoFilterForm`, the `cx`
  class joiner) and shadcn additionally ships `shadcnClassNames`, the
  preset map behind its default look.

---

# AdaptTable FAQ — free MUI X / ag-Grid alternative, RTL, SSR

Short, direct answers to the things people ask when choosing a React table.
(Looking for a quick comparison table instead? See
[comparison.md](./comparison.md). Looking for what the product does not
do? See [limitations.md](./limitations.md).)

**Jump to a feature:** [URL state](./url-state.md) ·
[Filtering](./filtering.md) · [Virtualization](./virtualization.md) ·
[i18n & RTL](./i18n-rtl.md) · [Accessibility](./accessibility.md) · [Realtime](./realtime.md) ·
[Column management](./column-management.md) ·
[Data tiers](./data-tiers.md) ·
[Live demo](https://adapttable.orwamahmoud.com/react/demo/)

**Migrating from another table:**
[MUI X DataGrid](./migrate-from-mui-x-datagrid.md) ·
[TanStack Table](./migrate-from-tanstack-table.md) ·
[mantine-datatable](./migrate-from-mantine-datatable.md) ·
[ag-Grid](./migrate-from-ag-grid.md) ·
[mui-datatables](./migrate-from-mui-datatables.md) ·
[material-table](./migrate-from-material-table.md)

## What is AdaptTable?

AdaptTable is a **headless, UI-agnostic React data table**. A single headless
engine (`@adapttable/core`) powers ready, batteries-included adapters for
**Mantine, MUI, Chakra, Ant Design, Radix, Base UI, shadcn/ui, and unstyled Tailwind**. You get
TanStack-Table-style headless freedom _and_ a styled table for the UI kit you
already use — from the same core.

## What is the best headless React table that works with my design system?

If you use **Mantine, MUI, Chakra, Ant Design, Radix, Base UI, or shadcn/ui**, AdaptTable
gives you a fully-featured table (sorting, filtering, selection, pagination,
infinite scroll, optional virtualization, URL state, i18n/RTL, dark mode) that
matches your kit without building the UI yourself. If you're on a different
kit or plain Tailwind, the unstyled adapter exposes semantic HTML with `data-*`
and `className` hooks, and the headless `useDataTable` core works with any
markup.

## Which UI libraries does AdaptTable support?

Eight adapters from one API: **Mantine, MUI, Chakra UI, Ant Design, Radix
Themes, Base UI, shadcn/ui, and unstyled** (for Tailwind or your own CSS) —
each kit adapter rendered with that kit's real components, plus a headless
core (`useDataTable`) that works with any markup. Install only the adapter
you use.

## Is there a free alternative to MUI X DataGrid or ag-Grid?

Yes — AdaptTable is **MIT-licensed and fully free**, including server-side
data, infinite scroll, filtering and selection. MUI X DataGrid and ag-Grid are
**open-core**: their advanced server-side data and infinite-loading
capabilities sit behind paid Pro/Premium or Enterprise tiers.

Six more sit in those same paid tiers and are MIT here:
[pivoting](./pivot.md), [tree data](./tree-data.md),
[cell-range selection, range clipboard copy/paste and the fill
handle](./cell-navigation.md), and
[Excel (.xlsx) export](./customization.md#export). What the paid tiers still
have is integration — one spreadsheet surface with its tool panels assembled —
where AdaptTable gives you the parts. [Comparison](./comparison.md) has the
table, with each vendor's tier named.

The MUI adapter gives a DataGrid-style experience at no cost.

## Is AdaptTable free?

Yes — every package is **MIT-licensed and completely free**, including
server-side data, infinite scroll, filtering, selection, and virtualization.
There is no paid tier and no feature gated behind a license (unlike the
open-core AG Grid Enterprise or MUI X DataGrid Pro / Premium).

## How does it handle responsive tables on mobile?

It does not try to squeeze desktop columns into a tiny viewport. The adapters
automatically switch to mobile cards, with labels per value; `hideOnMobile`
drops the low-value columns so the ones that matter lead each card.
This avoids the horizontal-scroll table pattern that breaks many responsive
apps.

## How do I use the same table for client-side and server-side data?

Use one `TableSource` contract for both:

```tsx
// in-memory
const source = useFrontendData({ data: rows, columns });
// server-paginated (wraps your useInfiniteQuery hook) — the table is identical
const source = useQuerySource({ usePaginatedQuery });
```

`<DataTable source={source} … />` doesn't change between them.

## Does AdaptTable support RTL and Arabic?

Yes, RTL is first-class. Column alignment uses **logical CSS** (`start`/`end`),
so it flips automatically under `dir="rtl"`. The optional `@adapttable/i18n`
package ships **18 locales** — English, Arabic, German, Spanish, Persian,
French, Hebrew, Hindi, Italian, Japanese, Korean, Polish, Portuguese, Russian,
Turkish, Urdu, Simplified Chinese, and Traditional Chinese — plus `getDirection` /
`isRtlLocale` helpers. Arabic, Hebrew, Persian, and Urdu are right-to-left.

## Does it have dark mode?

Dark mode is **seamless** — it's inherited from your UI kit's theme, with
logical color choices and no hardcoded surfaces that fight the host theme.

## Can I animate rows? Do I need GSAP?

Animation is **opt-in and dependency-free** — the built-in entrance stagger
uses the Web Animations API and honours `prefers-reduced-motion`. Prefer GSAP
or Framer Motion? Every row/card is tagged with `data-stagger`, so you can
drive the animation yourself (see
[customization.md](./customization.md#animations)). Or run with no animation at
all — your call.

## Does it support virtualization?

Yes. Compose `virtualize()` for row and card virtualization, and tune
`estimateRowSize`, `estimateCardSize`, and `virtualOverscan`. Ant Design uses its native virtual table mode through the
same feature.

## How do I add URL-synced (shareable, deep-linkable) table state?

It's built in. Search, sort, filters, and page sync to the URL through an
injectable adapter (browser History by default; pass a router adapter for
Next.js / react-router). Reloads, shared links, and back/forward restore the
exact view. See [url-state.md](./url-state.md).

## Which React table has a filter drawer with URL-synced state?

AdaptTable ships both out of the box: declarative filters render in an
anchored popover or a slide-in drawer (`filtersMode="drawer"`) with removable
chips, and every filter, search, sort, and page value syncs to the URL — so a
refresh or a shared link restores the exact view. It works the same for
client-side data and server-side fetching, rendered natively by Mantine, MUI,
Chakra, Ant Design, Radix, Base UI, or shadcn/ui. See
[filtering.md](./filtering.md) and [url-state.md](./url-state.md).

## Which React versions and bundlers are supported?

React **18+**. Every package ships dual ESM/CJS builds with `.d.ts` types
(verified with `publint --strict`), so it works with
Vite, Next.js, Remix, webpack, and friends. It's written in strict TypeScript.

## Does AdaptTable work with Next.js and server components?

Yes. It works with **Next.js (App or Pages Router), Remix, and Vite**. The
table is interactive, so render it inside a client component (`"use client"`
in the App Router) — you can still fetch in a server component and pass the
data in. URL-synced state takes a router adapter for Next.js or react-router,
and falls back to the browser History API.

## Does it support realtime or websocket updates?

Yes — you own the socket. When a row changes, patch the array you already
pass as `data` with `applyRowPatches`. Sort, filters and selection survive.
See [realtime React data table](./realtime.md). A websocket that hits a row
someone is editing is a [conflict](./cell-editing.md#live-update-conflicts),
not that page.

## Is it accessible?

Yes — semantic table markup, `aria-sort` on sortable headers, labelled
selection checkboxes and icon buttons, and a keyboard-friendly UX. Every
adapter is audited with `axe` in CI, on both desktop and mobile layouts. See
[accessible React data table](./accessibility.md).

## How big is it / is it tree-shakeable?

Every package declares its side effects — none, or only its stylesheet in
`@adapttable/base-ui` — and ships ESM, so unused code is tree-shaken. You only install the one adapter you use; the headless core has
zero UI-kit dependencies.

Measured 2026-09-28 from packed fixtures (`pnpm budget`: rolldown, min+gzip,
React and the UI kit external because your app already ships those):

| What you import                            | min+gzip  |
| ------------------------------------------ | --------- |
| `useFrontendData` + `useDataTable` (react) | ~25 kB    |
| every core export                          | ~97 kB    |
| `DataTable` from an adapter                | ~72–80 kB |

The first row is the one to read: a headless table costs about a quarter of the
full core, because the parts you never import never arrive. All eight adapters
land within ~12 kB of each other, so switching kits does not change what you
pay.

The third row is what composition buys. Every optional feature lives on its own
entry point, so a plain `DataTable` carries none of them: no drag machine, no
virtualizer, no export writer, no filter engine. Each one arrives with the
import that names it — `features={[grouping("team")]}` — and costs what it
weighs. [Feature composition](./features.md) has the detail.

These are not estimates. `pnpm budget` bundles each of those imports for real
and fails the build if one crosses its ceiling, and it checks this table against
what it just measured — so a figure here cannot drift from the build.

## How do I get started quickly?

```bash
npx @adapttable/cli init   # detects your UI kit and scaffolds a table
```

Or install an adapter directly, e.g. `pnpm add @adapttable/mantine`. See
[the Getting started guide](./getting-started.md).

## Is AdaptTable production-ready?

Yes — AdaptTable is **stable at 3.0** and follows semantic versioning, so
breaking changes ship only in a major release. It is strict-TypeScript, dual
ESM/CJS with `.d.ts` types, axe-audited for accessibility in CI, and enforces
per-package coverage floors (adapter line floors 96–100%, branch floors
88–100%).

## What does AdaptTable not do?

Present-tense ceilings — data ownership, formula grammar, reorder policy,
virtualization, export caps, adapter size, SSR, kit coverage — live on
[limitations and boundaries](./limitations.md). Each claim there traces to
a test, a measurement, or a documented decision.

## When might another library fit better?

- You want a mature, deeply integrated spreadsheet-analytics product and are
  happy to licence it → **AG Grid Enterprise** or **MUI X Premium**. Their pivot
  UI, tool panels and range tooling arrive as one assembled surface you switch
  on. AdaptTable ships the same capabilities under MIT —
  [pivoting](./pivot.md), [cell-range selection, range clipboard and the fill
  handle](./cell-navigation.md), [tree data](./tree-data.md),
  [inline editing](./cell-editing.md) and
  [Excel (.xlsx) export](./customization.md#export) — but as parts you compose,
  with their prerequisites stated, rather than one spreadsheet product.
- You're not on React → **TanStack Table** (multi-framework). AdaptTable is
  React-only.
- You want the table to draw its own look rather than your design system's.
  Every AdaptTable adapter renders your UI kit's real components, which is the
  whole point of it — and the wrong trade if you would rather not own the
  theming at all.

---

# Limitations and boundaries

What AdaptTable does not do, and the ceilings that are true of the
shipped tree. Every statement below is present-tense fact with a source.
This page is not a roadmap.

## The table never owns the data

AdaptTable does not mutate your array. Edits, adds, deletes and reorders
call host callbacks (`editing()`, `batchEditing()`, `rowEditing()`,
the `rowActions` add / duplicate / delete handlers, reorder/move handlers). Undo, dirty state and
persistence are whatever those callbacks already do.
[Cell editing](./cell-editing.md) · [row reordering](./row-reordering.md).

## Formula grammar

The optional `@adapttable/core/formula` grammar is the comparison /
concat / sum / product / unary / primary tree in
[formulas](./formulas.md). `^` and scientific notation (`1e5`) are
outside it: `parseFormula` returns `ok: false` and the column reads
`#ERROR!`. Write `x * x` or `POWER`. The function set is the table on
that page — no `eval`, no user-defined functions, no expansion of the
grammar through `POWER` / `SQRT`.

## Row reorder and move

`rowReorder` is an import. Without it the drag machine is not in the
graph. The default move policy is `"never"`: same-group / same-parent
reorder works; crossing a group or parent boundary is rejected with an
announcement. `"confirm"` and `"auto"` are opt-in.

A row cannot move under itself or a descendant — the cycle guard rejects
pointer, keyboard and menu paths before any host callback.

While a sort is active, same-scope order-only writes are rejected
(“Clear sorting before changing row order”). Cross-group moves and
re-parenting still run because they change membership. Row order is the
host array; it is not a URL or Saved Views parameter.
[Row reordering](./row-reordering.md).

## Source capabilities

A `TableSource` declares what it can retrieve. The table does not invent
the rest:

| Capability            | When it is not granted                                                                                                                                                             |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fullDataset: false`  | The browser holds the current page. `rows.read` with `scope: "full"` is denied. Export-all needs a source-owned `allFilteredRows` route or `onExportAll`, `request` or `fetchAll`. |
| `grouping: false`     | `grouping()` is not applied, and a `grouping-unavailable` notice says why in the status strip.                                                                                     |
| `exportScope: "page"` | `scope: "all"` with no host route renders the Export control disabled, with the reason on it.                                                                                      |

Declared in [data tiers](./data-tiers.md). Copied, never re-inferred, into
the agent manifest ([adaptive capabilities](./agent-capabilities.md)).

`rows.read` redacts `readable: false` cells and is bounded by
`limits.readMax` (default 50). Installing `@adapttable/ai` does not add
grouping, editing or a dataset the table cannot see.

## Client-side size and export

Without `virtualize`, the body renders every row in the current view. At
10,000 rows that is 10,000 `<tr>`s; the virtualized measurement on the
same set is 10 DOM rows and stays at 10 from 1k to 100k
([virtualization](./virtualization.md)). That is a measurement, not a
supported-row SLA. A server page plus virtualize is the path for large
sets.

Browser `fetchAll` export walks the current query up to
`EXPORT_FETCH_ALL_MAX_ROWS` (50,000). Hitting the cap calls `onCapped`
and does not write a file that pretends to be complete. Beyond that,
`onExportAll` is a host job. [Exporting](./exporting.md).

## URL state and page size

One table's URL state — and therefore one saved view — holds at most 8,192
encoded characters (`MAX_TABLE_URL_STATE_LENGTH`); see
[URL state](./url-state.md). `limit` is clamped to 1–500 (`MAX_LIMIT`);
see [pagination](./pagination.md).

## Bundle entrypoints

Sizes are minified + gzipped AdaptTable bytes. React and the UI kit are
external — an application already ships them. The method is packed
consumer fixtures in `scripts/bundle-budget.mjs`.

- A published adapter's base `DataTable` is held to **≤ 80 KB**
  (`PLAIN_ADAPTER_CEILING_KB`) and at least 35% under that kit's recorded
  pre-v3 size (`scripts/consumer-fixtures.mjs`). Omitted feature markers must be absent from the base graph.
- Optional features arrive with their import. Called with no argument,
  `standardFeatures()` composes only zero-argument factories; its options
  add grouping, bulk actions, filters and saved views.
- `@adapttable/ai` is a separate package. Eleven base graphs contain none
  of `createAgentSession`, `tableAgent`, `adapttable.agent.v1` or
  `@adapttable/ai` (`scripts/ai-isolation.mjs`).

Published FAQ figures are the measurements the budget script checks, not
a second estimate. [FAQ](./faq.md#how-big-is-it--is-it-tree-shakeable) ·
[feature composition](./features.md).

Interaction timings on the Tailwind showcase (first render, sort, page,
search, column-menu open, CLS) are locked in
`scripts/v3-perf-baseline.json`. The nightly workflow (`e2e-nightly.yml`)
measures the production showcase on its Linux runner and fails when one of
them regresses by more than 25% (or 80 ms) against that runner's own
baseline; `pnpm perf:v3` runs the same check locally. They are a regression
gate, not a promise to an application.

## Browser, SSR, and the e2e gate

Supported runtimes: React 18 or 19, Node `>=22.12.0`, and the kit
versions in [getting started](./getting-started.md). The table UI is
React. Vue and Angular bindings are not in this tree.

The per-PR Playwright project is **Chromium** against the built showcase
(`playwright.config.ts`). Firefox, WebKit and a Pixel 5 mobile project
run on the nightly/pre-release workflow
(`.github/workflows/e2e-nightly.yml`), not on every PR. Chromium visual
baselines live in `e2e/visual/` and are compared on that same nightly
job. An axe audit walks five feature pages per published kit — filtering,
accessibility, mobile cards, saved views and pivot; antd's accessibility
page is covered by `e2e/aria-parity.spec.ts` — and fails on serious or
critical findings (`e2e/axe-audit.spec.ts`).

The table is a client component. During SSR there is no `window` or
`matchMedia`: pass `forceMobile` so server and first paint agree, and
pass `createMemoryAdapter(search)` so URL state does not touch History.
`@adapttable/react`, `@adapttable/ai-react` and every adapter carry
`"use client"`; `@adapttable/core`, `@adapttable/i18n`, `@adapttable/ai`,
`@adapttable/server` and `@adapttable/cli` do not.
[SSR & RSC](./ssr-rsc.md).

`@adapttable/bootstrap` is private and unpublished. “All eight adapters”
means Mantine, MUI, Chakra, Ant Design, Radix Themes, Base UI, shadcn/ui
and unstyled.

## Accessibility

Keyboard, names, RTL and forced-colors are on by default across the eight
published kits ([accessibility](./accessibility.md)).

antd keeps a sticky header. `role="grid"` sits on the wrapper around
both of antd's tables so a cell and its `columnheader` share one grid.
The e2e `every body gridcell shares its columnheader with the same grid`
walks every kit with antd sticky **on**, forbids `headers=` pointing at
another table (W3C ACT a25f45), and requires `columnheader` in the same
grid snapshot (`e2e/aria-parity.spec.ts`). That is the outcome of the
sticky-header association work — it is not an open caveat.

A remaining kit-specific accessibility defect is listed here only after
a fix was attempted and failed. None is listed.

## What this product is not

- A spreadsheet host. Formula, pivot, fill and range paste are parts you
  compose; they are not one locked workbook surface.
- A hosted agent service. `@adapttable/ai` ships no model SDK and holds
  no API key; the opt-in `@adapttable/<kit>/assistant` panel talks to a
  model the host provides. Core, every adapter root and
  `@adapttable/server` import none of it.
- A data store. There is no built-in backend, auth or sync.
- A config-object API. Features are imports and callbacks, not a second
  options bag with synonyms.

## Sources

| Claim                                    | Source                                                                                                   |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Host callbacks own writes                | [cell-editing](./cell-editing.md), [row-reordering](./row-reordering.md)                                 |
| Formula grammar and refused tokens       | [formulas](./formulas.md), `parseFormula`                                                                |
| Move policy, cycle guard, sort block     | [row-reordering](./row-reordering.md)                                                                    |
| `fullDataset` / export-all / `rows.read` | [data-tiers](./data-tiers.md), [agent-capabilities](./agent-capabilities.md), `session.governed.test.ts` |
| `readMax` default 50                     | `packages/shared/ai/src/session.ts` `readMaxOf`                                                          |
| Virtualize DOM count                     | [virtualization](./virtualization.md)                                                                    |
| Export 50,000 cap                        | [exporting](./exporting.md) `EXPORT_FETCH_ALL_MAX_ROWS`                                                  |
| URL-state 8,192 cap, `limit` 1–500       | `MAX_TABLE_URL_STATE_LENGTH` in `packages/shared/core/src/url/urlStateCodec.ts`, `MAX_LIMIT`             |
| Adapter ≤ 80 KB, omitted-feature markers | `scripts/bundle-budget.mjs`, `scripts/consumer-fixtures.mjs`                                             |
| AI absent from base graphs               | `scripts/ai-isolation.mjs`                                                                               |
| Perf baseline                            | `scripts/v3-perf-baseline.json`                                                                          |
| Chromium e2e                             | `playwright.config.ts`                                                                                   |
| Nightly Firefox / WebKit / Pixel 5       | `.github/workflows/e2e-nightly.yml`, `name: "firefox"` in `playwright.config.ts`                         |
| Showcase axe audit                       | `e2e/axe-audit.spec.ts`                                                                                  |
| Visual baselines                         | `e2e/visual/v3-ui.spec.ts`, `e2e/visual/README.md`                                                       |
| SSR seams                                | [ssr-rsc](./ssr-rsc.md)                                                                                  |
| antd sticky header association           | `e2e/aria-parity.spec.ts`, [accessibility](./accessibility.md)                                           |
| React / Node / kit floors                | [getting-started](./getting-started.md)                                                                  |

---

# React data table comparison 2026 — AdaptTable vs AG Grid, TanStack Table & MUI X

How AdaptTable compares to popular React table libraries — scoped to what
each ships **built-in**. Every one of these projects is excellent at what it
targets; the table below is about scope fit, not quality. A "✗" means "not a
built-in feature" — most gaps can be closed with custom code or third-party
libraries.

| Feature                                        |  AG Grid  |    TanStack Table    | mantine-datatable | MUI X DataGrid |      **AdaptTable**       |
| ---------------------------------------------- | :-------: | :------------------: | :---------------: | :------------: | :-----------------------: |
| Headless core                                  |     ✗     |          ✓           |         ✗         |       ✗        |           **✓**           |
| Works across UI kits                           |     ✗     | ✓ (you build the UI) |   Mantine only    |    MUI only    | **✓ via ready adapters**  |
| Responsive mobile card layout                  |  partial  |  build it yourself   |      partial      |    partial     | **✓ automatic + tunable** |
| Client **and** server data, same API           |  partial  |   wire it yourself   |         ✗         |    partial     |   **✓ (`TableSource`)**   |
| URL-synced state (shareable links)             |     ✗     |          ✗           |         ✗         |       ✗        |           **✓**           |
| Filter drawer + removable chips                |     ✗     |          ✗           |         ✗         |    partial     |      **✓ built-in**       |
| Infinite scroll **and** paged (auto by device) |     ✓     |      ✓ (manual)      |      partial      |    ✓ (paid)    |   **✓ auto by device**    |
| Optional row/card virtualization               |     ✓     |      ✓ (manual)      |         ✗         |    ✓ (paid)    |   **✓ built-in opt-in**   |
| i18n + **RTL / Arabic** first-class            |  partial  |          ✗           |         ✗         |    partial     |           **✓**           |
| Dark mode                                      |     ✓     |         n/a          |         ✓         |       ✓        |      **✓ seamless**       |
| MIT / free                                     | open-core |          ✓           |         ✓         |   open-core    |           **✓**           |
| Pivoting                                       | ✓ (paid)  |          ✗           |         ✗         |    ✓ (paid)    | **✓ engine + panel, MIT** |
| Cell-range selection                           | ✓ (paid)  |          ✗           |         ✗         |    ✓ (paid)    |  **✓ MIT (cell nav on)**  |
| Fill handle (drag to fill)                     | ✓ (paid)  |          ✗           |         ✗         |    ✓ (paid)    | **✓ MIT (cell nav+edit)** |
| Clipboard copy / paste of a range              | ✓ (paid)  |          ✗           |         ✗         |    ✓ (paid)    | **✓ MIT (paste writes)**  |
| Excel (.xlsx) export                           | ✓ (paid)  |          ✗           |         ✗         |    ✓ (paid)    |         **✓ MIT**         |
| Tree data (self-referencing rows)              | ✓ (paid)  |  build it yourself   |         ✗         |    ✓ (paid)    |         **✓ MIT**         |

<sub>Comparison as of August 2026, based on each project's public documentation; capabilities evolve, so verify against the latest docs. "Open-core" means a free, MIT/community edition plus paid Enterprise/Pro tiers (AG Grid Enterprise; MUI X DataGrid Pro/Premium); the advanced server-side data and infinite-loading features sit in those paid tiers. Verified against their own docs in August 2026: AG Grid puts pivoting, cell-range selection, the fill handle, tree data, clipboard operations and Excel export in Enterprise; MUI X puts pivoting, cell selection, the fill handle, clipboard paste and Excel export in Premium. AdaptTable ships all of them under MIT, with the prerequisites stated: cell-range selection, the fill handle and range copy all need `cellNavigation()`, and paste and fill write through editable columns and the composed `editing()` handler — the channel inline editing uses — unless `onCellPaste` / `onCellFill` take the batch whole; cut reports its range to `onCellCut`. Pivoting is a separate engine plus its own panel rather than a one-line toggle. AG Grid and MUI X remain the more integrated spreadsheet-style products. Spotted something outdated or wrong? Please open an issue — we will correct it promptly.</sub>

A plain AdaptTable adapter `DataTable` is 72–80 kB min+gzip (measured
2026-09-28 from packed fixtures; React and the kit stay external). Competitor
bundle sizes are not listed here — they depend on which paid modules you
licence and are not produced by this repo's fixtures. Method and the rest of
the grid: [FAQ](./faq.md#how-big-is-it--is-it-tree-shakeable).

## Head-to-head

### AdaptTable vs TanStack Table

TanStack Table is a headless engine — framework-agnostic and the closest in
philosophy. The difference is what you ship: with TanStack you build every
cell, header, filter, and pagination control yourself. AdaptTable gives you
native, batteries-included UI for Mantine, MUI, Chakra, Ant Design, Radix, Base UI, and
shadcn/ui out of the box — and still exposes a headless core with prop-getters
when you want to drop down. Pick TanStack for non-React or total-control
builds; pick AdaptTable when you want the UI done for your kit without losing
the escape hatch.

→ [Migrate from TanStack Table](./migrate-from-tanstack-table.md).

### AdaptTable vs AG Grid

AG Grid is the enterprise heavyweight, and its spreadsheet stack is the more
integrated one. It puts pivoting, range selection, the fill handle, tree data,
clipboard operations and Excel export in the paid Enterprise tier, and it
renders its own look rather than your design system's. AdaptTable ships those
same capabilities under MIT — assembled from parts rather than one spreadsheet
surface — plus an interactive grouping strip with header drag-and-drop,
keyboard/mobile controls, aggregation choices, URL state, and Saved Views.
AdaptTable is free end to end, server data and infinite scroll included,
rendering as your UI kit's real components. Reach for AG Grid when you want its
more mature integrated spreadsheet product and are happy to licence it; reach
for AdaptTable for application data tables that match your app and stay free.

→ [Migrate from ag-Grid](./migrate-from-ag-grid.md) (CRUD tables only — the
guide starts with when to stay).

### AdaptTable vs MUI X DataGrid

MUI X DataGrid is a strong choice if you're all-in on MUI — but it's
MUI-only, and its server-side data, tree data, and infinite loading sit behind
the paid Pro / Premium tiers (open-core). AdaptTable's MUI adapter gives a
DataGrid-style experience for free, and the same API also renders in Mantine,
Chakra, Ant Design, Radix, Base UI, and shadcn/ui, with server data and shareable URL
state built in at no cost.

→ [Migrate from MUI X DataGrid](./migrate-from-mui-x-datagrid.md). Coming from
the older MUI table generation instead? →
[mui-datatables](./migrate-from-mui-datatables.md) ·
[material-table](./migrate-from-material-table.md).

### AdaptTable vs mantine-datatable

mantine-datatable is a polished, popular table — but it's Mantine-only.
AdaptTable renders natively in Mantine and six other kits from one API, and
adds client/server data behind a single contract, shareable URL state, saved
views, and first-class RTL. If you're on Mantine and staying there, either
works; if you want the same table across kits (or those extra batteries),
AdaptTable covers more ground.

→ [Migrate from mantine-datatable](./migrate-from-mantine-datatable.md).

## Every adapter, every feature

The point of AdaptTable is that the feature set never changes when you switch
kits — only the look does. Every adapter ships the same batteries:

| Feature                               | Mantine | MUI | Chakra | Ant Design | Radix | Base UI | shadcn/ui | Unstyled |
| ------------------------------------- | :-----: | :-: | :----: | :--------: | :---: | :-----: | :-------: | :------: |
| Filter popover                        |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Filter drawer                         |   ✅    | ✅  |   ✅   |     ✅     |  ✅¹  |   ✅    |    ✅     |    ✅    |
| Active-filter chips                   |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Column menu (show/hide, reorder, pin) |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Column resize                         |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Saved views                           |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Bulk action bar                       |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Summary / footer row                  |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Row expansion                         |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Inline cell editing (opt-in)          |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Row grouping + per-group aggregates   |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Interactive grouping panel            |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Pinned summary rows                   |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Row virtualization                    |   ✅    | ✅  |   ✅   |    ✅²     |  ✅   |   ✅    |    ✅     |    ✅    |
| Card virtualization (mobile)          |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| RTL / Arabic                          |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Skeleton / empty / error states       |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |
| Mount entrance animation              |   ✅    | ✅  |   ✅   |     ✅     |  ✅   |   ✅    |    ✅     |    ✅    |

<sub>¹ Radix Themes ships no Drawer primitive, so `filtersMode="drawer"` renders
as a Radix Dialog restyled into a side panel — same dimming backdrop and focus
trap. ² Ant Design maps `virtualize` to its own native virtual table for desktop
rows; mobile cards window through the shared engine like every other adapter.</sub>

shadcn/ui is the unstyled adapter pre-wired with the shadcn class preset, so it
matches unstyled feature-for-feature.

## When to choose AdaptTable

- You use **Mantine, MUI, Chakra, Ant Design, Radix, Base UI, or shadcn/ui** and want a table
  that matches your kit without building it yourself.
- You need **the same table for both in-memory and server-paginated data**.
- You want **shareable, deep-linkable table state** for free.
- You want tables that stay usable on phones without horizontal-scroll hacks.
- You need **RTL / Arabic** done properly.
- You want a **headless escape hatch** when the defaults aren't enough — the
  same core powers both the batteries-included components and your own
  custom markup.

## When another library may fit better

- You want a mature, deeply integrated spreadsheet-analytics product and are
  happy to licence it → **AG Grid Enterprise** / **MUI X Premium**. AdaptTable
  has an interactive grouping panel, pivoting, range selection, the fill
  handle, clipboard and Excel export under MIT, but they are assembled from
  composable features rather than one spreadsheet surface.
- You're on a framework other than React → **TanStack Table** (multi-
  framework). AdaptTable is React-only.
- You need a spreadsheet-like editing surface today, not a responsive data
  table for application lists.

## Migration guides

- [MUI X DataGrid alternative](./migrate-from-mui-x-datagrid.md)
- [TanStack Table alternative](./migrate-from-tanstack-table.md)
- [mantine-datatable alternative](./migrate-from-mantine-datatable.md)
- [ag-Grid alternative for CRUD](./migrate-from-ag-grid.md)
- [mui-datatables alternative](./migrate-from-mui-datatables.md)
- [material-table alternative](./migrate-from-material-table.md)

Also: [Mobile cards](./mobile.md) · [URL state](./url-state.md) ·
[Virtualization](./virtualization.md) · [i18n & RTL](./i18n-rtl.md) ·
[Accessibility](./accessibility.md) · [Realtime](./realtime.md) ·
[Limitations and boundaries](./limitations.md) ·
[Live demo](https://adapttable.orwamahmoud.com/react/demo/)

---

# Migrate from mantine-datatable to AdaptTable — more features, same Mantine look

▶ **See it before you install:** [the live demo running on real Mantine](https://adapttable.orwamahmoud.com/react/demo/?kit=mantine) — same components you already use, nothing to set up.

[mantine-datatable](https://icflorescu.github.io/mantine-datatable/) is a
polished, Mantine-only table. `@adapttable/mantine` renders the **same Mantine
primitives**, so the look barely changes — what changes is how much you wire by
hand. Sorting, pagination, filtering, and data fetching move from imperative
state you manage into declarative props the table owns.

Both are Mantine-native and both do RTL first-class, so those stay the same.
This page maps the API across and shows a before/after.

## What you gain

Things mantine-datatable leaves to you that AdaptTable does for you:

- **One data contract for client and server.** Pass `data` for in-memory rows,
  or `data` + `total` + `loading` + `onQueryChange` for a paginated API — no
  manual `useEffect`/`fetching`/`totalRecords` juggling. See
  [data tiers](./data-tiers.md).
- **A real filter UI.** Declare `filter` on a column and get a kit-native
  widget, a removable chip, and URL parsing for free. mantine-datatable's
  `column.filter` is an empty slot you render yourself. See
  [filtering](./filtering.md).
- **Search, sort, and paging applied for you.** On the frontend tier AdaptTable
  filters, sorts, and pages the array itself — you no longer sort and slice
  `records` in response to `sortStatus`/`page`.
- **URL-synced, shareable, reload-safe state** — mantine-datatable keeps state
  in React only. See [URL state](./url-state.md).
- **A ready Columns menu** (show/hide, reorder, pin) via `columnMenu()`, and
  drag/keyboard resize via `resizableColumns()`. mantine-datatable gives you the
  column mechanics but no menu UI. See
  [column management](./column-management.md).
- **Saved views, an automatic mobile card layout, and opt-in
  virtualization** — none of which mantine-datatable ships. See
  [saved views](./saved-views.md) and [virtualization](./virtualization.md).

## Install

```bash
pnpm add @adapttable/core @adapttable/mantine @mantine/core @mantine/hooks
```

Keep your existing `<MantineProvider>` at the app root — the adapter renders
through it exactly as mantine-datatable did.

## Prop mapping

`<DataTable>` props:

| mantine-datatable                             | `@adapttable/mantine`                                      | Notes                                                                                                                                 |
| --------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `records`                                     | `data`                                                     | Frontend tier. Server tier: `data` (current page) + `total` + `onQueryChange`.                                                        |
| `columns`                                     | `columns`                                                  | Field-by-field mapping below.                                                                                                         |
| `idAccessor`                                  | `rowKey`                                                   | **Required** — `(row) => string`. There is no `"id"` default.                                                                         |
| `sortStatus` / `onSortStatusChange`           | `sortable` per column (+ `multiSort()`)                    | AdaptTable owns sort state and applies it; you don't sort `records` yourself.                                                         |
| `page` / `onPageChange` / `totalRecords`      | automatic (frontend) or `total` + `onQueryChange` (server) | Pagination is `"auto"`: paged on desktop, infinite on mobile.                                                                         |
| `recordsPerPage` / `recordsPerPageOptions`    | built-in page-size control                                 | Defaults to `PAGE_SIZE_OPTIONS`; `DEFAULT_LIMIT` is 25.                                                                               |
| `selectedRecords` / `onSelectedRecordsChange` | `bulkActions([…])`, or `selectedIds` / `onSelectionChange` | Composing `bulkActions()` turns selection on and mounts the bulk bar.                                                                 |
| `isRecordSelectable`                          | — (gate in your bulk actions)                              | No per-row checkbox disable; use a bulk action's `disabledReason` to refuse ineligible ids (`selectionGetId` only customises the id). |
| `rowExpansion={{ content }}`                  | `rowDetail(fn)`                                            | `(row) => ReactNode`; multiple rows may be open at once.                                                                              |
| `fetching`                                    | `loading`                                                  | Server tier: skeleton when empty, subtle refresh indicator otherwise.                                                                 |
| `noRecordsText` / `emptyState`                | `slots.empty`                                              | Replace the empty state; `slots.skeleton` replaces the loader.                                                                        |
| `column.filter` (your JSX popover)            | column `filter` shorthand                                  | Declarative — see below. JSX is still allowed via the `filters(<Form />)` feature.                                                    |

Column fields (`DataTableColumn` → `ColumnDef`):

| mantine-datatable           | `@adapttable/mantine`                           | Notes                                                                     |
| --------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
| `accessor`                  | `key`                                           | Both support dot paths (`"department.name"`).                             |
| `title`                     | `header`                                        | Auto-derived from `key` when omitted (`hiredAt` → "Hired At").            |
| `render: (rec, i) => …`     | `Cell` (component) or `accessor: (row) => …`    | `Cell` receives `{ row, rowIndex }`; define it at module level.           |
| `sortable`                  | `sortable`                                      | Add `sortValue` when the cell renders formatted/JSX content.              |
| `textAlign: 'left'/'right'` | `align: 'start'/'end'`                          | Logical alignment — correct under RTL automatically.                      |
| `width`                     | `width`                                         | —                                                                         |
| `hidden` / `toggleable`     | `hideOnMobile`/`hideOnDesktop` + `columnMenu()` | Per-layout hiding is a column flag; user toggling lives in the menu.      |
| `draggable` / `resizable`   | `columnMenu()` / `resizableColumns()`           | Enabled once at the table level, not per column.                          |
| `pinned: 'left'/'right'`    | `columnLayout` / `defaultColumnLayout`          | Pinning is part of the column-layout state (menu-driven or controlled).   |
| `footer`                    | `summaryRow`                                    | One table-level function maps the page's rows to per-column footer cells. |

## Before / after

**Before** — mantine-datatable, wiring sort + paging yourself:

```tsx
import { DataTable } from "mantine-datatable";
import { useMemo, useState } from "react";

function PeopleTable({ people }: { people: Person[] }) {
  const [page, setPage] = useState(1);
  const PER_PAGE = 25;
  const [sortStatus, setSortStatus] = useState<DataTableSortStatus<Person>>({
    columnAccessor: "name",
    direction: "asc",
  });

  const sorted = useMemo(() => {
    const data = [...people].sort((a, b) =>
      String(a[sortStatus.columnAccessor]).localeCompare(
        String(b[sortStatus.columnAccessor])
      )
    );
    return sortStatus.direction === "desc" ? data.reverse() : data;
  }, [people, sortStatus]);

  const records = sorted.slice((page - 1) * PER_PAGE, page * PER_PAGE);

  return (
    <DataTable
      records={records}
      idAccessor="id"
      totalRecords={people.length}
      recordsPerPage={PER_PAGE}
      page={page}
      onPageChange={setPage}
      sortStatus={sortStatus}
      onSortStatusChange={setSortStatus}
      columns={[
        { accessor: "name", sortable: true },
        { accessor: "role" },
        { accessor: "status" },
      ]}
    />
  );
}
```

**After** — AdaptTable applies search, sort, filters, and paging itself:

```tsx
import { DataTable } from "@adapttable/mantine";

function PeopleTable({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      rowKey={(r) => r.id}
      columns={[
        { key: "name", sortable: true },
        { key: "role" },
        { key: "status", filter: { type: "select", options: "auto" } },
      ]}
    />
  );
}
```

The `status` filter alone — a kit-native select, a removable chip, a URL param,
and the row predicate — is code you would have written by hand before.

## Gotchas

- **`rowKey` is required.** mantine-datatable defaults `idAccessor` to `"id"`;
  AdaptTable has no default, so always pass `rowKey={(r) => r.id}`.
- **Stop sorting and slicing `records`.** On the frontend tier, hand the full
  array to `data` and delete your `sortStatus`/`page` sort-and-slice logic — the
  table does it. For a server API, use the [server tier](./data-tiers.md)
  instead of manual `fetching`.
- **`render(record, index)` → `Cell`.** Use a module-level component receiving
  `{ row, rowIndex }`, or the lighter `accessor: (row) => …`. A cell that
  returns formatted/JSX content needs `sortValue` to stay sortable.
- **Filters are declarative.** Replace a hand-built `column.filter` popover with
  a `filter` shorthand (`"text"`, `"select"`, `"dateRange"`, …). A genuinely
  bespoke control can still be passed as JSX to the `filters(<Form />)` feature.
- **`textAlign` values change.** `'left'`/`'right'` become the logical
  `'start'`/`'end'`, which flip correctly in RTL.
- **Features compose in `features`.** Import each factory from its kit subpath
  (`@adapttable/mantine/column-menu`, …). See [feature composition](./features.md).

## Where next

- [Getting started](./getting-started.md) — install, providers, first table.
- [Filtering](./filtering.md) · [Data tiers](./data-tiers.md) ·
  [Column management](./column-management.md) · [Saved views](./saved-views.md).
- [Comparison](./comparison.md) — where each library fits.

---

# Migrate from MUI X DataGrid to AdaptTable — v8 breaking changes mapped, Pro features free (MIT)

▶ **See it before you install:** [the live demo running on real Material UI](https://adapttable.orwamahmoud.com/react/demo/?kit=mui) — same components you already use, nothing to set up.

[MUI X DataGrid](https://mui.com/x/react-data-grid/) is an excellent grid if
you are all-in on Material UI. The catch is its licensing: many everyday table
features live in the paid **Pro** and **Premium** tiers. `@adapttable/mui`
renders real MUI components — so it looks like Material UI — while giving you a
lot of that paid surface **free under MIT**, plus shareable URL state and an
automatic mobile layout the DataGrid doesn't ship at any tier.

This page maps `<DataGrid>` to `<DataTable>` and shows a before/after.

## What you gain (free, MIT)

Features that are **paid** in MUI X but built into `@adapttable/mui`:

- **Column pinning** (Pro) → `columnMenu()` + column layout / Columns menu.
- **Row virtualization** (Pro in v8) → `virtualize()`. Community `<DataGrid>` also
  caps pages at 100 rows; AdaptTable has no such cap.
- **Multi-column sort** (Pro) → `multiSort()`.
- **Multiple simultaneous filters** (Pro) → declarative `filters([…])`, always
  multi-condition.
- **Column resizing** (Pro) → `resizableColumns()`.
- **Master-detail / detail panel** (Pro) → `rowDetail(fn)`.
- **Multiple row selection** (Pro) → `bulkActions([…])` (+ `selectedIds` /
  `onSelectionChange` when controlled).
- **Footer summary rows** → `summaryRow` (MUI's statistical aggregation is
  Premium; AdaptTable gives you the footer row, you supply the values).

Plus things DataGrid has no built-in answer for at any tier:

- **URL-synced, shareable state** — see [URL state](./url-state.md).
- **An automatic responsive card layout** on mobile (DataGrid's List view is
  Pro and manual).
- **One API for seven UI kits** — the same code renders in Mantine, Chakra, Ant
  Design, Radix, Base UI, and shadcn/ui too.

> Tiers above reflect MUI X **v8** (2025), verified against MUI's licensing
> docs. MUI may move features between tiers — check their
> [licensing page](https://mui.com/x/introduction/licensing/) before relying on
> a specific boundary.

## Install

```bash
pnpm add @adapttable/core @adapttable/mui @mui/material
```

Works with the default theme; wrap in `<ThemeProvider>` to customize, exactly as
DataGrid does.

## Prop mapping

`<DataGrid>` → `<DataTable>`:

| MUI X DataGrid                                       | `@adapttable/mui`                                          | Notes                                                                  |
| ---------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `rows`                                               | `data`                                                     | Frontend tier. Server tier: `data` (page) + `total` + `onQueryChange`. |
| `columns`                                            | `columns`                                                  | `GridColDef` → `ColumnDef`, mapped below.                              |
| `getRowId`                                           | `rowKey`                                                   | **Required** — `(row) => string`.                                      |
| `sortModel` / `onSortModelChange`                    | `sortable` per column (+ `multiSort()`)                    | AdaptTable owns and applies sort state.                                |
| `sortingMode: "server"`                              | `onQueryChange` (or `source`)                              | The consolidated query carries `sortBy`/`sortDir`.                     |
| `filterModel` / `onFilterModelChange`                | column `filter` shorthand + `filters([…])`                 | Widgets, chips, and URL params are derived for you.                    |
| `paginationModel` / `onPaginationModelChange`        | automatic (frontend) or `total` + `onQueryChange`          | No 100-row community cap.                                              |
| `checkboxSelection` + `rowSelectionModel`            | `bulkActions([…])`, or `selectedIds` / `onSelectionChange` | Multi-row selection is free; no `{ type, ids }` model to manage.       |
| `getDetailPanelContent` (Pro)                        | `rowDetail(fn)`                                            | `(row) => ReactNode`.                                                  |
| `loading`                                            | `loading`                                                  | —                                                                      |
| `slots.noRowsOverlay` / `loadingOverlay`             | `slots.empty` / `slots.skeleton`                           | —                                                                      |
| `initialState` / `apiRef.exportState()` (state only) | `urlSync` + `urlKey` (+ `savedViews({ storageKey })`)      | State lives in the URL, shareable and reload-safe.                     |
| `pinnedColumns` (Pro) / `columnVisibilityModel`      | `columnMenu()` / `columnLayout`                            | Show/hide, reorder, pin in one menu.                                   |

`GridColDef` → `ColumnDef`:

| MUI X DataGrid                         | `@adapttable/mui`                     | Notes                                                         |
| -------------------------------------- | ------------------------------------- | ------------------------------------------------------------- |
| `field`                                | `key`                                 | Also the value path (dot paths supported).                    |
| `headerName`                           | `header`                              | Auto-derived from `key` when omitted.                         |
| `width` / `flex`                       | `width` / `flex`                      | Same names.                                                   |
| `valueGetter: (value, row) => …`       | `accessor: (row) => …`                | AdaptTable reads the row directly — no v7/v8 signature churn. |
| `valueFormatter` / `renderCell`        | `accessor` / `Cell`                   | `Cell` is a component receiving `{ row, rowIndex }`.          |
| `type: "singleSelect"`, `valueOptions` | `filter: { type: "select", options }` | Turns the column into a native select filter.                 |
| `sortable`                             | `sortable`                            | Add `sortValue` for formatted/JSX cells.                      |
| `align` / `headerAlign`                | `align`                               | Use logical `"start"`/`"center"`/`"end"`.                     |

## Before / after

**Before** — MUI X, reaching for `<DataGridPro>` to pin and resize columns:

```tsx
import { DataGridPro } from "@mui/x-data-grid-pro"; // paid tier

function PeopleGrid({ rows }: { rows: Person[] }) {
  return (
    <DataGridPro
      rows={rows}
      getRowId={(r) => r.id}
      checkboxSelection
      columns={[
        { field: "name", headerName: "Name", sortable: true },
        { field: "role", headerName: "Role" },
        {
          field: "status",
          headerName: "Status",
          type: "singleSelect",
          valueOptions: ["active", "retired"],
        },
      ]}
      initialState={{ pinnedColumns: { left: ["name"] } }}
    />
  );
}
```

**After** — `@adapttable/mui`, all MIT, with a status filter + chip and URL state
for free:

```tsx
import { DataTable } from "@adapttable/mui";
import { bulkActions } from "@adapttable/mui/bulk-actions";
import { columnMenu } from "@adapttable/mui/column-menu";
import { resizableColumns } from "@adapttable/mui/resizable-columns";

function PeopleTable({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      rowKey={(r) => r.id}
      features={[
        columnMenu(), // show/hide, reorder, pin — no Pro licence
        resizableColumns(),
        bulkActions([]), // turns on multi-row selection; add your actions
      ]}
      columns={[
        { key: "name", sortable: true },
        { key: "role" },
        { key: "status", filter: { type: "select", options: "auto" } },
      ]}
    />
  );
}
```

## Escaping the version churn (v6 → v7 → v8 breaking changes)

A big reason teams migrate is that each DataGrid major rewrites your code.
If one of these breaking changes brought you here, the right column is what
the same thing looks like in AdaptTable:

| DataGrid breaking change                                                                                                            | In AdaptTable                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **`valueGetter` signature** rewritten in v7: `(params) => …` became `(value, row, column, apiRef) => …` (same for `valueFormatter`) | `accessor: (row) => …` — one argument, the row, stable API                     |
| **`disableSelectionOnClick` renamed** to `disableRowSelectionOnClick` (v6)                                                          | selection never binds to row clicks; `onRowClick` is a separate, explicit prop |
| **`rowSelectionModel` reshaped** in v8: a plain id array became `{ type: "include" \| "exclude", ids: Set }`                        | `onSelectionChange` hands you a plain `string[]` — no model object             |
| **Row virtualization moved to Pro** in v8 (Community pages cap at 100 rows)                                                         | `virtualize()` — free, MIT, no page cap                                        |
| **Multi-column sorting / multi-filters** gated behind Pro                                                                           | `multiSort()` and multi-condition `filters([…])` — free                        |
| **Column resizing** gated behind Pro                                                                                                | `resizableColumns()` — free                                                    |

One declarative API, semver-stable, and the features that keep moving behind
the paywall are simply included.

## Gotchas

- **`rowKey` is required** — the equivalent of `getRowId`, but with no `id`
  default.
- **No `sortModel`/`filterModel`/`paginationModel` objects.** Sorting is a
  per-column `sortable` flag; filtering is declarative `filter` shorthands;
  pagination is automatic. For a server API, emit one query via
  [`onQueryChange`](./data-tiers.md) instead of three `*Mode="server"` props.
- **`valueGetter` becomes `accessor`.** AdaptTable passes the row, so the v7/v8
  `(value, row, column, apiRef)` signature change doesn't apply — and a JSX cell
  uses `Cell` (a `{ row, rowIndex }` component).
- **Selection is a plain id list.** No v8 `{ type: "include" | "exclude", ids:
Set }` model — `onSelectionChange` hands you `string[]`.
- **Row expansion replaces master-detail.** `rowDetail(fn)` is the free
  equivalent of the Pro `getDetailPanelContent`.
- **`summaryRow` is a footer, not aggregation.** You compute the totals from the
  page's rows; there is no Premium aggregation engine (and none needed for a
  sum/count footer).
- **Features compose in `features`.** Import each factory from its kit subpath
  (`@adapttable/mui/column-menu`, …); enabling props no longer arm chrome. See
  [feature composition](./features.md).

## Where next

- [Getting started](./getting-started.md) · [Data tiers](./data-tiers.md) ·
  [Filtering](./filtering.md) · [Column management](./column-management.md).
- [Virtualization](./virtualization.md) — window large lists, free.
- [Comparison](./comparison.md) — where each library fits.

---

# Migrate from TanStack Table to AdaptTable — built-in UI, same headless control

▶ **See it before you install:** [the live demo](https://adapttable.orwamahmoud.com/react/demo/?kit=tailwind) — the unstyled adapter with your own classes, plus seven kit-native ones in the switcher.

[TanStack Table](https://tanstack.com/table/latest) is a superb headless engine
— you keep total control because it renders nothing: no markup, no toolbar, no
filter inputs, no pagination controls, no URL sync. AdaptTable shares that
philosophy. `@adapttable/react` is also headless (prop-getters, no forced
markup), but it comes with the parts you rebuild on every TanStack project
already wired: a filter UI, a toolbar, pagination, URL-synced state, and saved
views. And when you _don't_ need bespoke markup, an adapter renders native kit
components so you can delete the table UI entirely.

TanStack is multi-framework (React, Vue, Svelte, Solid, …); AdaptTable is
React-only. If you're not on React, stay on TanStack. This page is for React
teams tired of rebuilding the same chrome.

## What you gain

Everything TanStack leaves to you (verified from its docs), done for you:

- **A filter UI.** TanStack gives you `columnFilters` state and
  `getFacetedUniqueValues`, but you render every input. AdaptTable derives
  kit-native widgets, removable chips, and URL params from a `filter`
  declaration. See [filtering](./filtering.md).
- **A toolbar, pagination, and search** — none of which exist in TanStack; you
  wire the buttons around `nextPage()`/`setPageIndex()` yourself.
- **URL-synced state.** TanStack has no URL API; you serialize
  `sorting`/`columnFilters`/`pagination` by hand. AdaptTable does it. See
  [URL state](./url-state.md).
- **Saved views** — no concept in TanStack. See [saved views](./saved-views.md).
- **No opt-in row models.** You don't import `getSortedRowModel` /
  `getFilteredRowModel` / `getPaginationRowModel` — search, filter, sort, and
  paging run by default on the frontend tier.
- **Native kit UI, optional.** Keep headless control with `useDataTable`
  prop-getters, or adopt an adapter (`@adapttable/mantine`, `mui`, …) and drop
  your hand-written markup.

## Install

The headless React binding only, or an adapter for ready UI:

```bash
# Headless (keep rendering your own markup, TanStack-style)
pnpm add @adapttable/core @adapttable/react

# Batteries — native components for your kit (delete the markup)
pnpm add @adapttable/core @adapttable/mantine @mantine/core @mantine/hooks
```

## Concept mapping

| TanStack Table                                                        | AdaptTable                                                              | Notes                                                             |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `useReactTable({ data, columns, getCoreRowModel })`                   | `useDataTable({ source, columns, rowKey })` or an adapter `<DataTable>` | `source` from `useFrontendData`; adapters accept `data` directly. |
| `getSortedRowModel` / `getFilteredRowModel` / `getPaginationRowModel` | (none needed)                                                           | Applied automatically on the frontend tier.                       |
| `flexRender(cell.column.columnDef.cell, …)`                           | adapter renders, or prop-getters (`getCellProps`, …)                    | Headless route mirrors TanStack's model.                          |
| `columnHelper.accessor("name", …)`                                    | `{ key: "name" }`                                                       | Dot paths work in both.                                           |
| `columnHelper.accessor(row => …)` (`accessorFn`)                      | `{ key, accessor: (row) => … }`                                         | —                                                                 |
| `columnHelper.display({ cell })`                                      | `{ key, Cell }`                                                         | `Cell` receives `{ row, rowIndex }`.                              |
| `header` / `cell` / `footer`                                          | `header` / `Cell` (or `accessor`) / `summaryRow`                        | Footer is one table-level function.                               |
| `enableSorting` / `state.sorting` / `onSortingChange`                 | `sortable` per column (+ `multiSort()`)                                 | AdaptTable owns sort state.                                       |
| `columnFilters` + `getFilteredRowModel` + your inputs                 | column `filter` shorthand + `filters([…])`                              | Widgets + chips built for you.                                    |
| `state.pagination` + `getPaginationRowModel` + your controls          | automatic pagination                                                    | Paged on desktop, infinite on mobile.                             |
| `enableRowSelection` + `state.rowSelection` + your checkboxes         | `bulkActions([…])` / `selectedIds` / `onSelectionChange`                | —                                                                 |
| `getExpandedRowModel` + `row.getToggleExpandedHandler()`              | `rowDetail(fn)`                                                         | Toggle UI is provided, not hand-added.                            |
| `columnVisibility` / `columnOrder` / `columnPinning` state            | `columnMenu()` / `columnLayout`                                         | One built-in menu instead of hand-wired state + DnD.              |
| `manualSorting` / `manualFiltering` / `manualPagination`              | `onQueryChange` (or `source` via `useQuerySource`)                      | One consolidated server query. See [data tiers](./data-tiers.md). |
| (serialize state to the URL yourself)                                 | `urlSync` / `urlKey` / `savedViews({ storageKey })`                     | URL sync is on by default; `savedViews()` is opt-in.              |

## Before / after

**Before** — TanStack: opt-in row models, `flexRender`, and hand-built
pagination:

```tsx
import {
  createColumnHelper,
  flexRender,
  getCoreRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
} from "@tanstack/react-table";

const col = createColumnHelper<Person>();
const columns = [
  col.accessor("name", { header: "Name" }),
  col.accessor("role", { header: "Role" }),
];

function PeopleTable({ people }: { people: Person[] }) {
  const table = useReactTable({
    data: people,
    columns,
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
  });

  return (
    <>
      <table>
        <thead>
          {table.getHeaderGroups().map((hg) => (
            <tr key={hg.id}>
              {hg.headers.map((h) => (
                <th key={h.id} onClick={h.column.getToggleSortingHandler()}>
                  {flexRender(h.column.columnDef.header, h.getContext())}
                </th>
              ))}
            </tr>
          ))}
        </thead>
        <tbody>
          {table.getRowModel().rows.map((row) => (
            <tr key={row.id}>
              {row.getVisibleCells().map((cell) => (
                <td key={cell.id}>
                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
                </td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>
      {/* …and you still hand-write the pagination buttons, search box,
          filter inputs, and URL syncing. */}
    </>
  );
}
```

**After** — an adapter renders native UI; search, sort, filters, pagination, and
URL state come built in:

```tsx
import { DataTable } from "@adapttable/mantine"; // or mui, chakra, antd, …

function PeopleTable({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      rowKey={(r) => r.id}
      columns={[
        { key: "name", sortable: true },
        { key: "role", filter: { type: "select", options: "auto" } },
      ]}
    />
  );
}
```

Prefer to keep your own markup? Stay headless with `@adapttable/react`
([walkthrough](./headless.md)):
`useFrontendData` for the source and `useDataTable` for the prop-getters
(`getTableProps`, `getHeaderCellProps`, `getSortButtonProps`, `getRowProps`,
`getCellProps`, `getSearchInputProps`) — the same headless shape as TanStack,
but with filters, pagination, and URL state already handled.

## Gotchas

- **React only.** On Vue/Svelte/Solid/Angular, keep TanStack — AdaptTable has no
  adapter for those.
- **`rowKey` is required** (AdaptTable's `getRowId`).
- **Delete the opt-in row models.** No `getSortedRowModel` /
  `getFilteredRowModel` / `getPaginationRowModel` imports — those run for you.
- **Filters are declarative, not hand-rendered.** Swap your custom filter inputs
  for a `filter` shorthand; a bespoke control can still be JSX in `filters(<Form />)`.
- **You keep the headless escape hatch.** `useDataTable` returns prop-getters, so
  moving to AdaptTable doesn't mean giving up control — it means not rebuilding
  the chrome first.
- **Features compose in `features`.** Import each factory from its kit subpath
  (`@adapttable/mantine/row-detail`, …). See [feature composition](./features.md).

## Still on react-table v7?

If your project uses the legacy `react-table` package (v7 — `useTable` +
`useSortBy` / `useFilters` / `usePagination` / `useRowSelect` plugin hooks),
you're on a frozen library: v7 stopped receiving releases when the project
became TanStack Table v8. You have two upgrade paths, and both are rewrites of
your table UI — the v7 plugin-hook API doesn't carry over:

- **react-table v7 → TanStack v8**: new package, new column defs, new row
  models — and you still hand-build every piece of UI afterwards.
- **react-table v7 → AdaptTable**: the same rewrite cost, but you come out the
  other side with the toolbar, filters, pagination, URL sync, and native kit
  rendering already done.

The v7 concepts map cleanly: `useTable({ columns, data })` → `<DataTable
data={…} columns={…}>`; a v7 column's `Header`/`accessor`/`Cell` →
AdaptTable's `header`/`key` (or `accessor`)/`Cell`; `useSortBy` → per-column
`sortable`; `usePagination` → automatic; `useRowSelect` → `bulkActions([…])` /
`onSelectionChange`; `useExpanded` → `rowDetail(fn)`. Since you must rewrite
anyway, migrating "up" to batteries beats migrating sideways to another
build-it-yourself engine.

## Where next

- [Concepts](./concepts.md) — the headless engine and `TableSource`.
- [Getting started](./getting-started.md) · [Filtering](./filtering.md) ·
  [Data tiers](./data-tiers.md) · [API reference](./api.md).
- [Comparison](./comparison.md) — where each library fits.

---

# Migrate from mui-datatables to AdaptTable — maintained, MUI v6+, React 19 ready

▶ **See it before you install:** [the live demo running on real Material UI](https://adapttable.orwamahmoud.com/react/demo/?kit=mui) — nothing to set up.

[mui-datatables](https://github.com/gregnb/mui-datatables) served a generation
of Material UI apps well — but it has had **no releases or commits since
January 2023** (last version 4.3.0). Its peer range stops at
`@mui/material ^5`, so **MUI v6 and v7 apps can't install it cleanly**, React
19 is unsupported, and ~624 open issues sit unaddressed. If your app is stuck
on MUI v5 because of your table, this page is the way out.

`@adapttable/mui` renders real Material UI components — supported across
**MUI v6 through v9** — so migrating unfreezes your MUI upgrade path while
keeping the Material look. This page maps the API across and shows a
before/after.

## Why move

All verifiable as of mid-2026:

- **Unmaintained**: no releases or commits since January 2023; hundreds of
  open issues and PRs without a response.
- **Version lock**: peer dependencies require `@mui/material ^5.11` — npm
  refuses clean installs on MUI v6/v7, and React 19 is outside the peer range.
  Your table shouldn't decide your framework versions.
- **Weight**: 18 runtime dependencies, and drag-and-drop, print and CSV
  machinery ship whether you use them or not — there is no opting out of a
  feature you never turned on.
- **No bundled types**: TypeScript definitions live in community
  `@types/mui-datatables` and can drift. AdaptTable is TypeScript-first.

## What you gain

Beyond the unfreeze: URL-synced shareable state (filters, search, sort, page
in the query string — reload-safe), one data contract for client **and**
server data instead of the `onTableChange` action switch, chips for active
filters, an automatic mobile card layout (no `responsive` mode quirks), saved
views, and opt-in virtualization. See the [feature
overview](./getting-started.md).

## Install

```bash
pnpm add @adapttable/core @adapttable/mui @mui/material
```

Works with your existing MUI theme — and lets you upgrade `@mui/material`
whenever you want.

## Prop mapping

`<MUIDataTable>` → `<DataTable>`:

| mui-datatables                                        | `@adapttable/mui`                                          | Notes                                                                                                                                    |
| ----------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `data` (objects)                                      | `data`                                                     | Array-of-objects only; no array-of-arrays mode.                                                                                          |
| `data` (arrays)                                       | convert to objects                                         | One `map()` at the boundary — see Gotchas.                                                                                               |
| `columns` (`name`, `label`, `options`)                | `columns` (`key`, `header`, …)                             | Field-by-field below.                                                                                                                    |
| `options.serverSide` + `count` + `onTableChange`      | `data` + `total` + `onQueryChange`                         | One consolidated query object replaces the action-string switch.                                                                         |
| `options.page` / `rowsPerPage` / `rowsPerPageOptions` | automatic                                                  | Built-in pager; page size control included.                                                                                              |
| `options.sortOrder` / `onColumnSortChange`            | per-column `sortable` (+ `multiSort()`)                    | AdaptTable owns and applies sort state.                                                                                                  |
| `options.filterType` / `onFilterChange`               | column `filter` shorthand + `filters([…])`                 | Kit-native widgets + removable chips, derived for you.                                                                                   |
| `options.search` / `searchText` / `onSearchChange`    | built-in search (`searchPlaceholder`, `searchable`)        | Debounced and URL-synced.                                                                                                                |
| `options.selectableRows` + `onRowSelectionChange`     | `bulkActions([…])`, or `selectedIds` / `onSelectionChange` | Compose `bulkActions()` to enable selection + the bulk bar.                                                                              |
| `options.expandableRows` + `renderExpandableRow`      | `rowDetail(fn)`                                            | `(row) => ReactNode` — no separate flag, no colSpan markup.                                                                              |
| `options.viewColumns` / `draggableColumns`            | `columnMenu()`                                             | Show/hide, reorder, and pin in one menu.                                                                                                 |
| `options.resizableColumns`                            | `resizableColumns()`                                       | Drag + keyboard resize.                                                                                                                  |
| `options.responsive` (`'vertical'`, …)                | automatic mobile cards                                     | Cards render below the breakpoint — no mode to configure.                                                                                |
| `options.download` / `print`                          | `exportCsv()` / `rowsToCsv` + `downloadCsv`                | Compose `exportCsv()` for a toolbar button, or headless helpers on a custom `toolbar` button; `print(onPrint, true)` for a print button. |
| `options.textLabels`                                  | `labels`                                                   | Same idea; English defaults fill missing keys.                                                                                           |
| `options.storageKey`                                  | `savedViews({ storageKey })` / URL state                   | Views are named, shareable snapshots instead of one implicit save.                                                                       |

Column options → `ColumnDef`:

| mui-datatables                                    | `@adapttable/mui`                       | Notes                                                                                                 |
| ------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `name`                                            | `key`                                   | Dot paths reach nested values without `enableNestedDataAccess`.                                       |
| `label`                                           | `header`                                | Auto-derived from `key` when omitted.                                                                 |
| `options.customBodyRender(value, tableMeta)`      | `Cell` (component) or `accessor: (row)` | You get the **row object**, not index bookkeeping.                                                    |
| `options.customBodyRenderLite(dataIndex)`         | `Cell`                                  | Row memoization is built in — no "lite" variant needed.                                               |
| `options.display` / `viewColumns`                 | `columnMenu()` (+ `columnLayout`)       | User-facing visibility lives in the Columns menu.                                                     |
| `options.filter` / `filterType` / `filterOptions` | `filter` shorthand                      | `"text"`, `"select"`, `"multiSelect"`, `"numberRange"`, `"dateRange"`.                                |
| `options.sort` / `sortCompare`                    | `sortable` / `sortValue`                | `sortValue` extracts the comparable primitive.                                                        |
| `options.setCellProps` / `setCellHeaderProps`     | `align`, `width`, `classNames`          | Common cases are first-class column props; per-part classes come from the adapter's `classNames` map. |

## Server-side data: retire the action switch

mui-datatables server mode means `serverSide: true`, a `count`, and an
`onTableChange(action, tableState)` callback where you `switch` over action
strings — `'changePage'`, `'sort'`, `'search'`, `'filterChange'`,
`'changeRowsPerPage'` — re-fetching in each case (the library throws if
`onTableChange` is missing). AdaptTable replaces the whole dispatch with one
callback receiving one consolidated query:

```tsx
<DataTable
  data={rows}
  total={total}
  loading={loading}
  onQueryChange={async (query, { signal }) => {
    // query: { page, limit, search, sortBy, sortDir, sortLevels, filters } — one shape,
    // fired once per real change (mount included), previous fetch aborted.
    const res = await fetch(`/api/people?${toParams(query)}`, { signal });
    const body = await res.json();
    setRows(body.items);
    setTotal(body.total);
  }}
  columns={columns}
  rowKey={(r) => r.id}
/>
```

## Before / after

**Before** — mui-datatables:

```tsx
import MUIDataTable from "mui-datatables";

function PeopleTable({ people }) {
  return (
    <MUIDataTable
      title="People"
      data={people}
      columns={[
        { name: "name", label: "Name" },
        { name: "role", label: "Role" },
        {
          name: "status",
          label: "Status",
          options: {
            filter: true,
            customBodyRender: (value) => <StatusChip value={value} />,
          },
        },
      ]}
      options={{
        filterType: "dropdown",
        selectableRows: "multiple",
        responsive: "vertical",
      }}
    />
  );
}
```

**After** — `@adapttable/mui` (typed, URL-synced, MUI v6–v9):

```tsx
import { type CellProps, DataTable } from "@adapttable/mui";
import { bulkActions } from "@adapttable/mui/bulk-actions";

function StatusCell({ row }: CellProps<Person>) {
  return <StatusChip value={row.status} />;
}

function PeopleTable({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      rowKey={(r) => r.id}
      features={[bulkActions([])]}
      columns={[
        { key: "name", sortable: true },
        { key: "role" },
        {
          key: "status",
          Cell: StatusCell,
          filter: { type: "select", options: "auto" },
        },
      ]}
    />
  );
}
```

## Gotchas

- **Array-of-arrays data isn't supported.** If your `data` is
  `[["Ada", "Engineer"], …]`, map it to objects once at the boundary:
  `rows.map(([name, role], i) => ({ id: String(i), name, role }))` — and use a
  real id when you have one.
- **`rowKey` is required.** mui-datatables keys rows by index internally;
  AdaptTable wants a stable id.
- **`customBodyRender` receives a value; `Cell` receives the row.** Rewrites
  usually get simpler — no `tableMeta.rowData[…]` index lookups.
- **Filters become declarative.** A `filterType: "dropdown"` column becomes
  `filter: { type: "select", options: "auto" }`; ranges become
  `"numberRange"` / `"dateRange"` with operator widgets and chips included.
- **CSV export composes with `exportCsv()`.** Compose it (options: `filename`,
  `scope`, `writer`) for a toolbar button, or wire `rowsToCsv` / `downloadCsv`
  yourself via the `toolbar` slot; `print(onPrint, true)` adds a print button.
- **`textLabels` → `labels`**, and locale presets (incl. RTL languages) come
  from [`@adapttable/i18n`](./i18n-rtl.md).
- **Features compose in `features`.** Import each factory from its kit subpath;
  enabling props no longer arm chrome. See [feature composition](./features.md).

## Where next

- [Getting started](./getting-started.md) · [Data tiers](./data-tiers.md) ·
  [Filtering](./filtering.md) · [Column management](./column-management.md).
- Also migrating the grid elsewhere in your app? See
  [Migrate from MUI X DataGrid](./migrate-from-mui-x-datagrid.md).
- [Comparison](./comparison.md) — where each library fits.

---

# Migrate from material-table to AdaptTable — maintained drop-in for MUI

▶ **See it before you install:** [the live demo running on real Material UI](https://adapttable.orwamahmoud.com/react/demo/?kit=mui) — same components material-table wraps, nothing to set up.

[material-table](https://github.com/mbrn/material-table) was once the default
Material UI table. Today it's effectively dormant: the last release with
release notes shipped in **August 2020**, maintenance since has been sporadic
single-maintainer dependency bumps, and the issue tracker is cleared by a
stale-bot rather than by fixes. Roughly **78% of its ~47k weekly downloads
still run the 1.x line — which supports only Material-UI v4 and React
16/17** — and the official docs still show the v4 install. (Material React
Table's own docs describe the project as having "become abandoned.")

If your table is one of those stranded 1.x installs, `@adapttable/mui`
renders real Material UI components across **MUI v6 through v9** — migrating
unblocks your MUI and React upgrades at the same time.

## First, the honest part: what does NOT map

material-table is a table-plus-CRUD-suite. AdaptTable deliberately isn't.
If you depend on these, AdaptTable is the wrong target (Material React Table
is the closer fit):

- **Full row-edit CRUD suites** (`editable` as a material-table-style
  object with `onRowAdd` / `onRowUpdate`) — AdaptTable ships **opt-in
  inline cell editing** via `editing(save)` + `ColumnDef.editable` (see
  [Inline cell editing](./cell-editing.md)), not material-table's row
  dialog engine. Multi-field forms still go through `rowActions([…])` + your
  own UI, with the built-in `confirm` seam for destructive actions.
- **Drag-to-group aggregation** (`options.grouping`) — AdaptTable ships
  [row grouping](./row-grouping.md) at any depth (`grouping("team")` or an
  ordered list, plus optional `groupAggregates`); `groupingPanel()` adds the
  drag-a-column-to-group strip with chip reorder/removal and aggregation
  choices.
- **Tree data** (`parentChildData`) — [`tree({ getParentId })`](./tree-data.md) is the
  same idea: a flat list with a parent column, rendered as a hierarchy.
- **PDF export button** — compose `exportCsv({ writer: pdfWriter() })` with
  `pdfWriter` from `@adapttable/core/pdf`. See
  [PDF export](./export-pdf.md).

What's left — sorted, filtered, searched, paginated, selectable CRUD list
tables with remote data — is the majority use case, and it maps cleanly.

## Why move (all verifiable)

- **The version trap**: 1.x peers on `@material-ui/core ^4` (a package
  discontinued years ago); the 2.x escape hatch exact-pins specific MUI
  versions and rides the deprecated `@mui/styles`. Weekly downloads have
  roughly halved since 2020–21.
- **It mutates your rows**: material-table injects a `tableData` property
  into your data objects — breaking frozen/Redux state (issues #666, #1979).
  AdaptTable never writes to your rows.
- **No virtualization**: nothing in its public API windows large datasets,
  and slow-large-table issues are long-standing. AdaptTable has opt-in
  row/card virtualization via `virtualize()`.
- **Fragile foundations**: header-drag grouping depends on the archived
  `react-beautiful-dnd`.
- Plus the AdaptTable batteries the old stack never had: URL-synced shareable
  state, filter chips, an automatic mobile card layout, saved views, i18n/RTL.

## Install

```bash
pnpm add @adapttable/core @adapttable/mui @mui/material
```

Same Material look, on a current MUI — and your rows stay untouched.

## Prop mapping

`<MaterialTable>` → `<DataTable>`:

| material-table                                       | `@adapttable/mui`                                          | Notes                                                                            |
| ---------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `data` (array)                                       | `data`                                                     | No `tableData` injection — your objects are never mutated.                       |
| `data` (query function)                              | `onQueryChange` (or `source`)                              | Mapping below.                                                                   |
| `columns`                                            | `columns`                                                  | Field-by-field below.                                                            |
| `title`                                              | `tableLabel` / your own heading                            | The toolbar is yours to compose (`toolbar` slot).                                |
| `actions` (row actions)                              | `rowActions([…])`                                          | Icon buttons on desktop, card buttons on mobile; `confirm` built in.             |
| `actions` (`isFreeAction: true`)                     | `toolbar` slot                                             | Free actions are just toolbar content.                                           |
| `options.selection` + `onSelectionChange`            | `bulkActions([…])`, or `selectedIds` / `onSelectionChange` | Compose `bulkActions()` to turn on selection.                                    |
| `detailPanel`                                        | `rowDetail(fn)`                                            | `(row) => ReactNode`.                                                            |
| `options.paging` / `pageSize` / `pageSizeOptions`    | automatic                                                  | Paged on desktop, infinite on mobile (`"auto"`).                                 |
| `options.search` / `searchText` / `debounceInterval` | built-in search                                            | Debounced + URL-synced by default.                                               |
| `options.filtering`                                  | column `filter` shorthands + `filters([…])`                | Real widgets + removable chips, not per-column text rows.                        |
| `options.columnsButton`                              | `columnMenu()`                                             | Show/hide, reorder, pin.                                                         |
| `options.columnResizable`                            | `resizableColumns()`                                       | —                                                                                |
| `options.fixedColumns: { left, right }`              | column pinning via `columnMenu()` + `columnLayout`         | Logical sides — RTL-correct.                                                     |
| `options.padding: "dense"`                           | `density="compact"`                                        | —                                                                                |
| `options.exportButton`                               | `exportCsv()` / `rowsToCsv` + `downloadCsv`                | Compose `exportCsv()` for a built-in button; the writer picks CSV, Excel or PDF. |
| `options.maxBodyHeight`                              | `maxHeight`                                                | Enables the scroll box + sticky pinning.                                         |
| `localization`                                       | `labels` (+ [`@adapttable/i18n`](./i18n-rtl.md))           | Flat label object; presets for every bundled locale, RTL included.               |
| `isLoading`                                          | `loading`                                                  | —                                                                                |

Column def → `ColumnDef`:

| material-table                     | `@adapttable/mui`                             | Notes                                                                           |
| ---------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
| `field`                            | `key`                                         | Dot paths supported.                                                            |
| `title`                            | `header`                                      | Auto-derived from `key` when omitted.                                           |
| `render(rowData)`                  | `Cell` / `accessor: (row) => …`               | Same idea, typed row.                                                           |
| `type: "numeric"`                  | `align: "end"` + `filter: "numberRange"`      | Type is behavior you declare, not an enum.                                      |
| `type: "date"` / `"datetime"`      | `accessor` formatting + `filter: "dateRange"` | Operator-first range widgets included.                                          |
| `lookup: { 1: "Active", … }`       | `filter: { type: "select", options }`         | Options are explicit `{ value, label }[]` (or `"auto"`).                        |
| `sorting` / `defaultSort`          | `sortable` + `defaults`                       | Default sort is `defaults={{ sortBy, sortDir }}` (URL state wins when present). |
| `customSort(a, b)`                 | `sortValue: (row) => primitive`               | Extract a comparable value instead of writing a comparator.                     |
| `customFilterAndSearch`            | `filter` + `getValue`                         | Predicate derives from the declaration.                                         |
| `hidden` / `hiddenByColumnsButton` | `columnMenu()` + `columnLayout`               | User-facing visibility lives in the menu.                                       |
| `cellStyle` / `headerStyle`        | `align`, `width`, `Cell`, table `classNames`  | Style through your own components/classes.                                      |

## Remote data: the query function maps almost 1:1

material-table's remote mode —
`data={query => fetch(...).then(r => ({ data, page, totalCount }))}` — is the
same idea as AdaptTable's server tier, minus two quirks:

```tsx
<DataTable
  data={rows}
  total={total}
  loading={loading}
  onQueryChange={async (query, { signal }) => {
    // material-table: query.page, query.pageSize, query.search,
    //                query.orderBy (a whole Column OBJECT), query.orderDirection
    // AdaptTable:    query.page, query.limit, query.search,
    //                query.sortBy (the column KEY, a string), query.sortDir,
    //                query.filters
    const res = await fetch(`/api/people?${toParams(query)}`, { signal });
    const body = await res.json();
    setRows(body.items); // no { data, page, totalCount } envelope required
    setTotal(body.total);
  }}
  columns={columns}
  rowKey={(r) => r.id}
/>
```

The classic material-table stumbling block — `query.orderBy` being a full
column object you have to unwrap — goes away: `sortBy` is the column key,
which you chose to be API-stable.

## Before / after

**Before** — material-table (MUI v4 era):

```tsx
import MaterialTable from "material-table";

function PeopleTable({ people }) {
  return (
    <MaterialTable
      title="People"
      data={people}
      columns={[
        { title: "Name", field: "name" },
        { title: "Role", field: "role" },
        { title: "Status", field: "status", lookup: STATUS_LOOKUP },
        { title: "Salary", field: "salary", type: "currency" },
      ]}
      options={{ selection: true, filtering: true, columnsButton: true }}
      actions={[
        { icon: "edit", tooltip: "Edit", onClick: (e, row) => openEdit(row) },
      ]}
    />
  );
}
```

**After** — `@adapttable/mui` (typed, URL-synced, current MUI):

```tsx
import { DataTable } from "@adapttable/mui";
import { bulkActions } from "@adapttable/mui/bulk-actions";
import { columnMenu } from "@adapttable/mui/column-menu";
import { rowActions } from "@adapttable/mui/row-actions";

function PeopleTable({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      rowKey={(r) => r.id}
      features={[
        columnMenu(),
        bulkActions([]),
        rowActions([
          { key: "edit", label: "Edit", onClick: (row) => openEdit(row) },
        ]),
      ]}
      columns={[
        { key: "name", sortable: true },
        { key: "role" },
        { key: "status", filter: { type: "select", options: STATUS_OPTIONS } },
        {
          key: "salary",
          align: "end",
          accessor: (r) => formatCurrency(r.salary),
          sortValue: (r) => r.salary,
          filter: "numberRange",
        },
      ]}
    />
  );
}
```

## Gotchas

- **Strip `tableData` if you persist rows.** Rows that passed through
  material-table carry its injected `tableData` property — harmless to
  AdaptTable, but don't let it leak into your API payloads.
- **`rowKey` is required.** material-table keyed rows via its injected ids;
  AdaptTable wants your stable id.
- **Editing is a workflow now, not a table mode.** Recreate `onRowUpdate` /
  `onRowDelete` as `rowActions([…])` with your own form/dialog; destructive
  actions get the built-in `confirm` dialog seam.
- **`lookup` becomes explicit options.** `{ 1: "Active" }` →
  `[{ value: "1", label: "Active" }]` (values round-trip through the URL as
  strings).
- **`type` enums become declarations.** `"numeric"` → `align: "end"` (+
  `numberRange` filter); dates → an `accessor` that formats + `dateRange`
  filter; `"currency"` → your formatter, with `sortValue` keeping sort
  numeric.
- **Features compose in `features`.** Import each factory from its kit subpath;
  enabling props no longer arm chrome. See [feature composition](./features.md).

## Where next

- [Getting started](./getting-started.md) · [Data tiers](./data-tiers.md) ·
  [Filtering](./filtering.md) · [Selection & bulk actions](./selection.md).
- Same app also uses DataGrid or mui-datatables? See
  [Migrate from MUI X DataGrid](./migrate-from-mui-x-datagrid.md) and
  [Migrate from mui-datatables](./migrate-from-mui-datatables.md).
- [Comparison](./comparison.md) — where each library fits.

---

# Migrate from AG Grid to AdaptTable — CRUD tables in your UI kit, MIT

▶ **See it before you install:** [the live demo](https://adapttable.orwamahmoud.com/react/demo/) — flip between Mantine, MUI, Chakra, Ant Design, Radix, Base UI, shadcn and Tailwind on the same data.

[AG Grid](https://www.ag-grid.com/) is the best spreadsheet-grade grid in the
React ecosystem — and this page starts by telling you when **not** to migrate.

The honest line is not a feature list. Pivoting, tree data, cell-range
selection, the fill handle, clipboard range operations and Excel export all
ship in AdaptTable, under MIT, where AG Grid puts them in its paid Enterprise
tier — $999/developer when we checked in August 2026. What AG Grid has that
AdaptTable does not is **integration**: one spreadsheet surface, tool panels
already assembled, and a decade of behaviour at the edges of it. In AdaptTable
those are parts you compose — a pivot engine and its panel, a range model, a
side-panel frame you fill, and a grouping panel you opt into.

So stay on AG Grid when the grid IS the product: an analytics surface where
users pivot, drill and drag fields around all day, or a workflow that leans on
Excel-style editing at scale. That week is not worth spending, and the licence
buys something real.

This page is for the other — much larger — group: teams running **ordinary
CRUD tables** on AG Grid Community, paying for spreadsheet power they don't use
in two currencies: **churn** (a new AG Grid major about every 6 months — v32.2
rewrote the selection API, v33 made module registration and the Theming API
mandatory, v36 overhauled the DOM and CSS class names), and **look** (AG Grid
renders its own theme; AdaptTable renders _your_ UI kit's real components).

## When to stay on AG Grid

- The grid is the product — an analytics surface users pivot and drill all day
- Excel-style cell editing at scale
- Assembled tool panels: AdaptTable's `sidePanel({ panels, open, onOpenChange })`
  is a frame with tabs that you fill (the pivot, saved-views and filter-tree
  panels ship; arranging them is yours)

If you rely on those and the Enterprise licence is worth it to you, that is the
right tool. Migrate the CRUD tables, keep the analytics grid — they can run side
by side.

## What you gain (for CRUD tables)

- **Native look per kit** — MUI tables look like MUI, Mantine like Mantine.
  No Quartz theme to restyle, no CSS class renames on major upgrades.
- **Declarative instead of imperative** — no `gridRef.current.api.*` calls;
  selection, filters, sort, and page are props and URL state.
- **URL-synced shareable state** built in — AG Grid exposes grid state through
  its API and leaves persistence to you.
- **Interactive grouping in every kit** — `groupingPanel()` adds a dedicated
  strip above the table, desktop header drag-and-drop, chip reorder/removal,
  mobile selects, aggregation choices, RTL keyboard movement, and polite
  announcements. `groupBy` and `groupAgg` are URL state and Saved Views capture
  both.
- **Free master/detail** — `rowDetail(fn)` does what AG Grid gates behind
  Enterprise master/detail (for detail panels, not nested grids).
- **A real filter UI for free** — AG Grid's set filter, multi filter, and
  filter tool panel are Enterprise; AdaptTable's select/multi-select/range
  filters with chips are MIT.
- **Everything is MIT** — no watermark risk when a developer touches the
  wrong feature flag.

## Install

```bash
# pick the adapter for your UI kit
pnpm add @adapttable/core @adapttable/mui @mui/material
```

No module registration, no theme objects, no CSS imports — the adapter
renders through the kit provider your app already has.

## Prop mapping

Grid-level (`<AgGridReact>` → `<DataTable>`):

| AG Grid                                            | AdaptTable                                                 | Notes                                                             |
| -------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- |
| `rowData`                                          | `data`                                                     | —                                                                 |
| `columnDefs`                                       | `columns`                                                  | `ColDef` mapping below.                                           |
| `defaultColDef`                                    | (not needed)                                               | Column defaults are explicit per column.                          |
| `pagination` + `paginationPageSize`                | automatic                                                  | Paged on desktop, infinite on mobile; page-size control built in. |
| `rowSelection={{ mode: "multiRow" }}`              | `bulkActions([…])`, or `selectedIds` / `onSelectionChange` | Compose `bulkActions()` to turn on checkboxes.                    |
| `api.getSelectedRows()`                            | `onSelectionChange` state                                  | Selection is React state, not an API call.                        |
| `rowModelType: "infinite"`                         | `onQueryChange` (+ infinite mode)                          | One consolidated query; superseded fetches abort via `signal`.    |
| `api.exportDataAsCsv()`                            | `exportCsv()` / `rowsToCsv` + `downloadCsv`                | Compose `exportCsv()` for a toolbar button or headless helpers.   |
| `theme={themeQuartz}`                              | your kit's provider/theme                                  | The table inherits the design system, incl. dark mode.            |
| `<AgGridProvider modules={[AllCommunityModule]}>`  | (nothing)                                                  | No module registry.                                               |
| `onGridReady` / `gridRef.current.api`              | (nothing)                                                  | Declarative props replace the imperative API.                     |
| column tool panel (Enterprise side bar)            | `columnMenu()`                                             | Show/hide, reorder, pin — free.                                   |
| `rowGroupPanelShow` / tool-panel grouping          | `groupingPanel()`                                          | Dedicated strip; drag headers on desktop, use selects on mobile.  |
| `getDetailPanelContent`-style master/detail (Ent.) | `rowDetail(fn)`                                            | `(row) => ReactNode`, free.                                       |

`ColDef` → `ColumnDef`:

| AG Grid                             | AdaptTable                                                      | Notes                                              |
| ----------------------------------- | --------------------------------------------------------------- | -------------------------------------------------- |
| `field`                             | `key`                                                           | Dot paths supported.                               |
| `headerName`                        | `header`                                                        | Auto-derived from `key` when omitted.              |
| `valueGetter` / `valueFormatter`    | `accessor: (row) => …`                                          | One function, receives the row.                    |
| `cellRenderer`                      | `Cell`                                                          | Component receiving `{ row, rowIndex }`.           |
| `sortable` (default true)           | `sortable` (default false)                                      | Opt-in instead of opt-out.                         |
| `comparator`                        | `sortValue`                                                     | Extract a comparable primitive.                    |
| `filter: "agTextColumnFilter"` etc. | `filter: "text"` / `"select"` / `"numberRange"` / `"dateRange"` | Widgets + chips derived from the declaration.      |
| `flex` / `width` / `minWidth`       | `flex` / `width` / `minWidth` (+ `maxWidth`)                    | Same names.                                        |
| `pinned: "left" \| "right"`         | pinning via `columnMenu()` + `columnLayout`                     | Logical sides — RTL-correct.                       |
| `hide`                              | `columnMenu()` + `columnLayout`                                 | User-facing visibility lives in the menu.          |
| `resizable` (default true)          | `resizableColumns()` (table-level)                              | —                                                  |
| `editable`                          | `editable` + `editor` + `editing(save)`                         | Opt-in; no editor until `editing()` is composed.   |
| `rowGroup: true`                    | Initial key in `groupingPanel(["team"])`                        | Users can add, reorder, or remove keys afterwards. |
| `aggFunc`                           | `groupAggregates` default + panel aggregation override          | Session choices are sum/avg/min/max/count/none.    |

## Before / after

**Before** — AG Grid Community (v36 setup):

```tsx
import { AgGridReact } from "ag-grid-react";
import {
  AgGridProvider,
  AllCommunityModule,
  themeQuartz,
} from "ag-grid-community";
import { useRef } from "react";

function PeopleGrid({ rows }: { rows: Person[] }) {
  const gridRef = useRef<AgGridReact>(null);
  return (
    <AgGridProvider modules={[AllCommunityModule]}>
      <AgGridReact
        ref={gridRef}
        theme={themeQuartz}
        rowData={rows}
        pagination
        rowSelection={{ mode: "multiRow" }}
        columnDefs={[
          { field: "name", sortable: true },
          { field: "role" },
          { field: "status", filter: "agTextColumnFilter" },
          { field: "salary", valueFormatter: (p) => fmt(p.value) },
        ]}
      />
    </AgGridProvider>
  );
}
```

**After** — AdaptTable (here with the MUI adapter; swap the import for your kit):

```tsx
import { DataTable } from "@adapttable/mui";
import { bulkActions } from "@adapttable/mui/bulk-actions";
import { columnMenu } from "@adapttable/mui/column-menu";
import { groupingPanel } from "@adapttable/mui/grouping-panel";

function PeopleTable({ people }: { people: Person[] }) {
  return (
    <DataTable
      data={people}
      rowKey={(r) => r.id}
      features={[bulkActions([]), columnMenu(), groupingPanel()]}
      columns={[
        { key: "name", sortable: true },
        { key: "role" },
        { key: "status", filter: { type: "select", options: "auto" } },
        {
          key: "salary",
          align: "end",
          accessor: (r) => fmt(r.salary),
          sortValue: (r) => r.salary,
          filter: "numberRange",
        },
      ]}
    />
  );
}
```

No provider wrapper, no modules, no theme object, no ref — and the rendered
table is your design system's, not a themed grid.

## Gotchas

- **The analytics features are parts, not a mode.** [Pivoting](./pivot.md) is
  an engine plus its own panel; [nested grouping](./row-grouping.md) is
  `groupingPanel(["team", "status"], extras)` with header drag-and-drop,
  selects, and optional aggregate defaults; [tree data](./tree-data.md) is
  `tree({ getChildren })` or `tree({ getParentId })`; range selection, the fill
  handle and clipboard operations all need `cellNavigation()` composed (see
  [Cell navigation](./cell-navigation.md)). Each works — none is the single
  spreadsheet surface AG Grid hands you, so budget assembly time rather than a
  prop rename.
- **Cell editing is opt-in.** Map AG Grid `editable` columns to
  `ColumnDef.editable` + `editing(save)` (see
  [Inline cell editing](./cell-editing.md)). For a multi-field edit dialog,
  `rowActions([…])` + your own form is still the answer — that part AdaptTable
  deliberately leaves to you.
- **The imperative API disappears.** Anywhere you called
  `api.getSelectedRows()`, `api.setFilterModel()`, or `api.sizeColumnsToFit()`,
  you now read props/state (`onSelectionChange`, URL-synced filters, column
  `width`s). This is usually the bulk of the rewrite — and the part that
  stops breaking on majors.
- **Sorting is opt-in.** AG Grid columns sort by default; AdaptTable columns
  need `sortable: true`.
- **Export is a writer, not three features.** Compose `exportCsv()` for the
  toolbar button; the format is whatever writer you hand it — `csvWriter`,
  `xlsxWriter` from `@adapttable/core/xlsx` for a real spreadsheet, or
  `pdfWriter` from `@adapttable/core/pdf`. Excel export is AG Grid Enterprise;
  here it is one import. (Its context menu is Enterprise anyway.)
- **Row virtualization is opt-in** (`virtualize()`) rather than always-on —
  enable it for genuinely large lists; a benchmark lives in the
  [virtualization docs](./virtualization.md).
- **Features compose in `features`.** Import each factory from its kit subpath;
  enabling props no longer arm chrome. See [feature composition](./features.md).

## Where next

- [Getting started](./getting-started.md) · [Data tiers](./data-tiers.md) ·
  [Filtering](./filtering.md) · [Column management](./column-management.md).
- [Comparison](./comparison.md) — the honest feature table, including where
  AG Grid wins.

---

# Upgrading from v2

v3 removes the enabling props. A feature is an import and an entry in
`features`, and that is the only way in — which is what lets a table download
what it named and nothing else. Measured adapter sizes live in the
[FAQ](./faq.md#how-big-is-it--is-it-tree-shakeable); the acceptance ceiling
is 80 KB min+gzip.

Nothing else about the table changed: the same columns, the same data tiers,
the same URL state, the same labels.

## The shortest upgrade

If your table used most of the chrome, one import replaces the lot:

```tsx
import { DataTable } from "@adapttable/mantine";
import { standardFeatures } from "@adapttable/mantine/preset";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(r) => r.id}
  features={standardFeatures({ grouping: "team", filters: filterDefs })}
/>;
```

`standardFeatures()` brings the Columns menu, the density chooser, CSV export,
find-in-table, fit-columns, the fullscreen toggle, header filters, multi-sort,
resizable columns and the status bar. Grouping, bulk actions, filters and saved
views join when you pass their options. See [feature composition](./features.md)
for what the preset costs against individual imports.

## The smallest upgrade

Import only what you used. Each row below is a prop you were passing and the
factory that replaces it:

```tsx
// v2
<DataTable groupBy="team" enableColumnMenu exportCsv onCellEdit={save} />;

// v3
import { columnMenu } from "@adapttable/mantine/column-menu";
import { editing } from "@adapttable/mantine/editing";
import { exportCsv } from "@adapttable/mantine/export";
import { grouping } from "@adapttable/mantine/grouping";

<DataTable
  features={[grouping("team"), columnMenu(), exportCsv(), editing(save)]}
/>;
```

No type arguments are needed. A factory whose configuration says nothing about
rows composes into any table; one that takes a row-typed callback infers the
row from that callback.

## Every removed prop, and what replaces it

| Removed prop                                                                  | Replacement                     | Import                                |
| ----------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- |
| `batchEditing`, `onBatchEdit`                                                 | `batchEditing(…)`               | `@adapttable/<kit>/editing`           |
| `bulkActions`                                                                 | `bulkActions(…)`                | `@adapttable/<kit>/bulk-actions`      |
| `cellNavigation`                                                              | `cellNavigation(…)`             | `@adapttable/<kit>/cell-navigation`   |
| `getCellSpan`, `cellSpanAppearance`                                           | `cellSpan(…)`                   | `@adapttable/<kit>/cell-span`         |
| `collapsibleColumnGroups`                                                     | `collapsibleColumnGroups(…)`    | `@adapttable/<kit>/column-groups`     |
| `enableColumnMenu`                                                            | `columnMenu(…)`                 | `@adapttable/<kit>/column-menu`       |
| `columnSelectionCheckbox`                                                     | `columnSelectionCheckbox(…)`    | `@adapttable/<kit>/column-selection`  |
| `commandPalette`                                                              | `commandPalette(…)`             | `@adapttable/<kit>/command-palette`   |
| `contextMenu`                                                                 | `contextMenu(…)`                | `@adapttable/<kit>/context-menu`      |
| `densityChooser`                                                              | `densityChooser(…)`             | `@adapttable/<kit>/density`           |
| `dirtyIndicators`                                                             | `dirtyIndicators(…)`            | `@adapttable/<kit>/editing`           |
| `editHistory`                                                                 | `editHistory(…)`                | `@adapttable/<kit>/editing`           |
| `onCellEdit`                                                                  | `editing(…)`                    | `@adapttable/<kit>/editing`           |
| `exportCsv`                                                                   | `exportCsv(…)`                  | `@adapttable/<kit>/export`            |
| `extraRows`                                                                   | `extraRows(…)`                  | `@adapttable/<kit>/extra-rows`        |
| `filters`                                                                     | `filters(…)`                    | `@adapttable/<kit>/filters`           |
| `filterTypes`                                                                 | `filterTypes(…)`                | `@adapttable/<kit>/filters`           |
| `findInTable`                                                                 | `findInTable(…)`                | `@adapttable/<kit>/find-in-table`     |
| `fitColumns`                                                                  | `fitColumns(…)`                 | `@adapttable/<kit>/fit-columns`       |
| `fullscreen`                                                                  | `fullscreen(…)`                 | `@adapttable/<kit>/fullscreen`        |
| `groupBy`                                                                     | `grouping(…)`                   | `@adapttable/<kit>/grouping`          |
| `headerFilters`                                                               | `headerFilters(…)`              | `@adapttable/<kit>/header-filters`    |
| `multiSort`                                                                   | `multiSort(…)`                  | `@adapttable/<kit>/multi-sort`        |
| `nestedTable`                                                                 | `nestedTable(…)`                | `@adapttable/<kit>/nested-table`      |
| `onPrint`, `printButton`                                                      | `print(…)`                      | `@adapttable/<kit>/print`             |
| `resizableColumns`                                                            | `resizableColumns(…)`           | `@adapttable/<kit>/resizable-columns` |
| `onAddRow`, `onDuplicateRow`, `onDeleteRow`, `confirmDeleteRow`, `rowActions` | `rowActions(actions, handlers)` | `@adapttable/<kit>/row-actions`       |
| `rowStyle`, `rowHeight`, `rowClassName`                                       | `rowAppearance(…)`              | `@adapttable/<kit>/row-appearance`    |
| `renderRowDetail`, `defaultExpandedRowIds`                                    | `rowDetail(…)`                  | `@adapttable/<kit>/row-detail`        |
| `rowEditing`, `onRowEdit`                                                     | `rowEditing(…)`                 | `@adapttable/<kit>/editing`           |
| `pinnedRowIds`, `onPinnedRowIdsChange`                                        | `rowPinning(…)`                 | `@adapttable/<kit>/row-pinning`       |
| `onRowReorder`                                                                | `rowReorder(…)`                 | `@adapttable/<kit>/row-reorder`       |
| `savedViews`                                                                  | `savedViews(…)`                 | `@adapttable/<kit>/saved-views`       |
| `selectionStats`                                                              | `selectionStats(…)`             | `@adapttable/<kit>/selection-stats`   |
| `sidePanel`                                                                   | `sidePanel(…)`                  | `@adapttable/<kit>/side-panel`        |
| `statusBar`                                                                   | `statusBar(…)`                  | `@adapttable/<kit>/status-bar`        |
| `getChildren`, `getParentId`, `treeColumn`, `onLoadChildren`                  | `tree(…)`                       | `@adapttable/<kit>/tree`              |
| `undoRedoButtons`                                                             | `undoRedoButtons(…)`            | `@adapttable/<kit>/editing`           |
| `virtualize`, `virtualizeColumns`                                             | `virtualize(…)`                 | `@adapttable/<kit>/virtualize`        |

Companion props travel with their feature: `cellSpanAppearance` is the second
argument to `cellSpan`, `defaultExpandedRowIds` the second to `rowDetail` and
`nestedTable`, `printButton` the second to `print`. Grouping's extras
(`groupAggregates`, `groupSort`, `groupFooters`, paging, collapse state) are one
options object:

```tsx
grouping("team", {
  groupAggregates: (rows: readonly Person[]) => ({ spend: total(rows) }),
  groupFooters: true,
});
```

## The other four removals

**Main-entry adapter machinery.** The 72 adapter-machinery names v2
re-exported from `@adapttable/core` are all exported from
`@adapttable/react/adapter`, which is where to import them. The React-bound
ones are exported only there; the framework-neutral helpers (column-group,
extra-row, pinned-row and row-span math) are also still on `@adapttable/core`,
deprecated there:

```ts
// v2
import { useFullscreen } from "@adapttable/core";
// v3
import { useFullscreen } from "@adapttable/react/adapter";
```

Every name keeps the same spelling:

| Name                         | v3 import                   |
| ---------------------------- | --------------------------- |
| `COLUMN_GROUP_ID_SEP`        | `@adapttable/react/adapter` |
| `COLUMN_GROUP_RENDER_PREFIX` | `@adapttable/react/adapter` |
| `COLUMN_GROUP_STUB_PREFIX`   | `@adapttable/react/adapter` |
| `COLUMN_GROUP_STUB_WIDTH`    | `@adapttable/react/adapter` |
| `columnGroupHeaderCaption`   | `@adapttable/react/adapter` |
| `columnGroupId`              | `@adapttable/react/adapter` |
| `columnGroupPath`            | `@adapttable/react/adapter` |
| `columnGroupStubStyle`       | `@adapttable/react/adapter` |
| `groupedHeaderAlign`         | `@adapttable/react/adapter` |
| `groupedHeaderCellStyle`     | `@adapttable/react/adapter` |
| `groupedHeaderChildRule`     | `@adapttable/react/adapter` |
| `groupedHeaderLabelStyle`    | `@adapttable/react/adapter` |
| `HeaderGroupCell`            | `@adapttable/react/adapter` |
| `headerGroupRow`             | `@adapttable/react/adapter` |
| `headerGroupRows`            | `@adapttable/react/adapter` |
| `HtmlGroupedHeaderCell`      | `@adapttable/react/adapter` |
| `htmlGroupedHeaderPlan`      | `@adapttable/react/adapter` |
| `isColumnGroupRenderKey`     | `@adapttable/react/adapter` |
| `isColumnGroupStubKey`       | `@adapttable/react/adapter` |
| `isColumnGroupSummaryKey`    | `@adapttable/react/adapter` |
| `toggleCollapsedColumnGroup` | `@adapttable/react/adapter` |
| `EXTRA_OVER_SPAN_ROW_STYLE`  | `@adapttable/react/adapter` |
| `EXTRA_OVER_SPAN_STYLE`      | `@adapttable/react/adapter` |
| `EXTRA_ROW_PARTS`            | `@adapttable/react/adapter` |
| `extraCountBeforeRowIds`     | `@adapttable/react/adapter` |
| `extraCoveredTableSlots`     | `@adapttable/react/adapter` |
| `ExtraEntry`                 | `@adapttable/react/adapter` |
| `extraHostFillStyle`         | `@adapttable/react/adapter` |
| `extraRowsForSection`        | `@adapttable/react/adapter` |
| `extraUncoveredColSpans`     | `@adapttable/react/adapter` |
| `inflateBodyCellRowSpans`    | `@adapttable/react/adapter` |
| `insertExtraRows`            | `@adapttable/react/adapter` |
| `insertExtrasBeforeRows`     | `@adapttable/react/adapter` |
| `isExtraEntry`               | `@adapttable/react/adapter` |
| `orderedCardEntries`         | `@adapttable/react/adapter` |
| `PINNED_BOTTOM_PART`         | `@adapttable/react/adapter` |
| `PINNED_TOP_PART`            | `@adapttable/react/adapter` |
| `pinnedRowCellStyle`         | `@adapttable/react/adapter` |
| `pinnedRowPart`              | `@adapttable/react/adapter` |
| `pinnedRowSticky`            | `@adapttable/react/adapter` |
| `pinnedRowStickyStyle`       | `@adapttable/react/adapter` |
| `useOffsetHeight`            | `@adapttable/react/adapter` |
| `columnMenuActions`          | `@adapttable/react/adapter` |
| `filterColumnMenuRows`       | `@adapttable/react/adapter` |
| `hideAllColumns`             | `@adapttable/react/adapter` |
| `resetColumnLayout`          | `@adapttable/react/adapter` |
| `showAllColumns`             | `@adapttable/react/adapter` |
| `unpinAllColumns`            | `@adapttable/react/adapter` |
| `BodyCell`                   | `@adapttable/react/adapter` |
| `bodyCellsHaveRowSpan`       | `@adapttable/react/adapter` |
| `cellsForRow`                | `@adapttable/react/adapter` |
| `cellSpanMark`               | `@adapttable/react/adapter` |
| `rowSpanSignature`           | `@adapttable/react/adapter` |
| `REORDER_COLUMN_WIDTH`       | `@adapttable/react/adapter` |
| `ROW_DND_MIME`               | `@adapttable/react/adapter` |
| `rowReorderDropStyle`        | `@adapttable/react/adapter` |
| `rowReorderSignature`        | `@adapttable/react/adapter` |
| `RowReorderState`            | `@adapttable/react/adapter` |
| `resolveRowHeight`           | `@adapttable/react/adapter` |
| `resolveRowStyle`            | `@adapttable/react/adapter` |
| `rowStyleSignature`          | `@adapttable/react/adapter` |
| `EditableCellActivateProps`  | `@adapttable/react/adapter` |
| `EditableCellButtonProps`    | `@adapttable/react/adapter` |
| `EditableCellSlots`          | `@adapttable/react/adapter` |
| `FilterHeaderClassNames`     | `@adapttable/react/adapter` |
| `FilterHeaderRowProps`       | `@adapttable/react/adapter` |
| `applyCollapsedColumnGroups` | `@adapttable/react/adapter` |
| `flattenColumnTree`          | `@adapttable/react/adapter` |
| `FullscreenState`            | `@adapttable/react/adapter` |
| `useFullscreen`              | `@adapttable/react/adapter` |
| `rowPinSignature`            | `@adapttable/react/adapter` |
| `rowSourceIndex`             | `@adapttable/react/adapter` |

**`useChromeBodyData`.** Choose the implementation the host actually renders:
`usePlainChromeBodyData` for a normal table, or `useVirtualChromeBodyData` for
the virtualized feature path. Both are exported from `@adapttable/react`.

**`FilterTypeRegistry.register` / `FilterTypeRegistry.extend`.** A custom
filter type registers through a feature, on the same object every other
extension uses:

```tsx
// v2
const registry = FilterTypeRegistry.register(mySpec);
// v3
features={[{ id: "my-filter", setup: (host) => host.registerFilterType(mySpec) }]}
```

`filterTypes([mySpec])` from `@adapttable/<kit>/filters` does the same thing
without writing the object by hand.

**MUI's `size` prop.** Use `density`: `density="compact"` is what `size="small"`
meant, and `density="comfortable"` is `size="medium"`.

The hooks, the React column and the prop-getters a host imports directly are
exported from `@adapttable/react`. The framework-neutral models and helpers in
the same list stay on `@adapttable/core`:

| Name                               | v3 import                                 |
| ---------------------------------- | ----------------------------------------- |
| `aggregate`                        | `@adapttable/core` or `@adapttable/react` |
| `AggregateOptions`                 | `@adapttable/core`                        |
| `Aggregator`                       | `@adapttable/core`                        |
| `BaseDataTableProps`               | `@adapttable/react`                       |
| `BulkAction`                       | `@adapttable/core`                        |
| `CellElementProps`                 | `@adapttable/react`                       |
| `ChromeBodyData`                   | `@adapttable/react`                       |
| `ColumnFooterContext`              | `@adapttable/core` or `@adapttable/react` |
| `ColumnGroupDef`                   | `@adapttable/core`                        |
| `ColumnGroupRecord`                | `@adapttable/core`                        |
| `ColumnHeaderController`           | `@adapttable/core` or `@adapttable/react` |
| `columnHeaderLabel`                | `@adapttable/core`                        |
| `ColumnReorderKeyProps`            | `@adapttable/react`                       |
| `ColumnResizeHandleProps`          | `@adapttable/core`                        |
| `ComputedColumnSpec`               | `@adapttable/core`                        |
| `CustomCellEditorRender`           | `@adapttable/core`                        |
| `EditableCellActivateControlProps` | `@adapttable/react`                       |
| `EditableCellControls`             | `@adapttable/react`                       |
| `EditableCellGate`                 | `@adapttable/react`                       |
| `EditableCellGateProps`            | `@adapttable/react`                       |
| `ExportContext`                    | `@adapttable/core`                        |
| `exportViewFromChrome`             | `@adapttable/core`                        |
| `ExtraRow`                         | `@adapttable/core`                        |
| `FeatureProps`                     | `@adapttable/react`                       |
| `FeatureProviderContribution`      | `@adapttable/react`                       |
| `FeatureProviderProps`             | `@adapttable/react`                       |
| `FeatureRender`                    | `@adapttable/react`                       |
| `FilterChromeMode`                 | `@adapttable/core`                        |
| `FilterTypeSpec`                   | `@adapttable/core`                        |
| `groupAggregateEntries`            | `@adapttable/core`                        |
| `GroupAggregatesFn`                | `@adapttable/core`                        |
| `GroupedFlatEntry`                 | `@adapttable/core`                        |
| `GroupingChipKeyboardProps`        | `@adapttable/core`                        |
| `GroupingDragProps`                | `@adapttable/core`                        |
| `GroupingDropProps`                | `@adapttable/core`                        |
| `GroupRowCell`                     | `@adapttable/core`                        |
| `groupRowLayout`                   | `@adapttable/core`                        |
| `HeaderFilterOpenProvider`         | `@adapttable/react`                       |
| `headerFilterStickTop`             | `@adapttable/react`                       |
| `IncrementalView`                  | `@adapttable/core`                        |
| `IncrementalViewConfig`            | `@adapttable/core`                        |
| `isDeclarativeFilters`             | `@adapttable/core` or `@adapttable/react` |
| `MobileCardField`                  | `@adapttable/core`                        |
| `MobileCardRenderer`               | `@adapttable/core`                        |
| `MultiSelectEditorCheckboxProps`   | `@adapttable/react`                       |
| `MultiSelectEditorChrome`          | `@adapttable/react`                       |
| `MultiSelectEditorChromeProps`     | `@adapttable/react`                       |
| `MultiSelectEditorSlots`           | `@adapttable/react`                       |
| `NestedTable`                      | `@adapttable/react`                       |
| `renderRegisteredFilter`           | `@adapttable/core`                        |
| `resolveColumnFooter`              | `@adapttable/react`                       |
| `resolveColumnHeader`              | `@adapttable/react`                       |
| `RowAction`                        | `@adapttable/core`                        |
| `RowActionsRenderer`               | `@adapttable/core`                        |
| `RowStyle`                         | `@adapttable/core`                        |
| `SidePanelEntry`                   | `@adapttable/core` or `@adapttable/react` |
| `Slot`                             | `@adapttable/core` or `@adapttable/react` |
| `TableChrome`                      | `@adapttable/react`                       |
| `TableExtraEntry`                  | `@adapttable/core`                        |
| `TableRowReorderState`             | `@adapttable/react`                       |
| `ToolbarSlots`                     | `@adapttable/react`                       |
| `useActiveFilterChips`             | `@adapttable/react`                       |
| `useBatchEditing`                  | `@adapttable/react`                       |
| `useBooleanFilterWidget`           | `@adapttable/react`                       |
| `useBulkActionRunner`              | `@adapttable/react`                       |
| `useCellEditing`                   | `@adapttable/react`                       |
| `useCellSaveState`                 | `@adapttable/react`                       |
| `useChecklistFilter`               | `@adapttable/react`                       |
| `useChromeScrollReset`             | `@adapttable/react`                       |
| `useColorScheme`                   | `@adapttable/react`                       |
| `useColumnDragState`               | `@adapttable/react`                       |
| `useColumnLayout`                  | `@adapttable/react`                       |
| `useColumnLayoutStorageState`      | `@adapttable/react`                       |
| `useColumnLayoutUrlState`          | `@adapttable/react`                       |
| `UseDataTableResult`               | `@adapttable/react`                       |
| `useDebounce`                      | `@adapttable/react`                       |
| `useDensityUrlState`               | `@adapttable/react`                       |
| `useDirtyCells`                    | `@adapttable/react`                       |
| `useEditConflict`                  | `@adapttable/react`                       |
| `useEditHistory`                   | `@adapttable/react`                       |
| `useExtraChips`                    | `@adapttable/react`                       |
| `useFilterOptions`                 | `@adapttable/react`                       |
| `useFilterTreeChips`               | `@adapttable/react`                       |
| `useFilterTriggerToggle`           | `@adapttable/react`                       |
| `useFindFocus`                     | `@adapttable/react`                       |
| `useFindInTable`                   | `@adapttable/react`                       |
| `useFrontendData`                  | `@adapttable/react`                       |
| `useGridFocus`                     | `@adapttable/react`                       |
| `useGroupCollapse`                 | `@adapttable/react`                       |
| `useGroupCollapseUrlState`         | `@adapttable/react`                       |
| `useGroupPaging`                   | `@adapttable/react`                       |
| `useHeaderFilterOverlay`           | `@adapttable/react`                       |
| `useHighlight`                     | `@adapttable/react`                       |
| `useHorizontalOverflow`            | `@adapttable/react`                       |
| `useInfiniteScroll`                | `@adapttable/react`                       |
| `useIsMobile`                      | `@adapttable/react`                       |
| `useLazyChildren`                  | `@adapttable/react`                       |
| `useMediaQuery`                    | `@adapttable/react`                       |
| `usePointerDismiss`                | `@adapttable/react`                       |
| `usePrefersReducedMotion`          | `@adapttable/react`                       |
| `useRangeFilterWidget`             | `@adapttable/react`                       |
| `useRowEditing`                    | `@adapttable/react`                       |
| `useRowExpansion`                  | `@adapttable/react`                       |
| `useRowMutations`                  | `@adapttable/react`                       |
| `useRowPinning`                    | `@adapttable/react`                       |
| `useRowPinningUrlState`            | `@adapttable/react`                       |
| `useRowReorder`                    | `@adapttable/react`                       |
| `useSavedViews`                    | `@adapttable/react`                       |
| `useScrollToTableTop`              | `@adapttable/react`                       |
| `UseScrollToTableTopOptions`       | `@adapttable/react`                       |
| `useSearchInput`                   | `@adapttable/react`                       |
| `useSelection`                     | `@adapttable/react`                       |
| `useServerData`                    | `@adapttable/react`                       |
| `useShortcuts`                     | `@adapttable/react`                       |
| `useTableData`                     | `@adapttable/react`                       |
| `UseTableDataOptions`              | `@adapttable/react`                       |
| `useTableEditHistory`              | `@adapttable/react`                       |
| `useTableUrlState`                 | `@adapttable/react`                       |
| `useTableVirtualization`           | `@adapttable/react`                       |
| `useTextFilterWidget`              | `@adapttable/react`                       |
| `useTreeExpansion`                 | `@adapttable/react`                       |

## Checking the upgrade

The compiler finds every call site: a removed prop is not in
`DataTableProps` any more, so `tsc` names each one. There is no deprecation
warning to grep for, because there is nothing left to deprecate.

This repository rehearses that upgrade against packed tarballs for every
published kit — preset-equivalent first, then the four-import minimal path —
with `pnpm migrate:rehearse`. Headless consumers keep `useDataTable`.

Run the v3 codemod over the source directories:

```bash
npx @adapttable/cli migrate-v3 src
npx @adapttable/cli migrate-v3 src --check
```

The codemod performs one provably mechanical rewrite: named imports of moved
exports go from `@adapttable/core` to their v3 home — `@adapttable/react` or
`@adapttable/react/adapter` — splitting a mixed import when necessary. It is idempotent; the second run reports zero
updates. Enabling props, `FilterTypeRegistry.register` / `extend`,
`useChromeBodyData`, and MUI `size` need behavior choices, so the command
reports each location and exits non-zero without rewriting it. Use those
locations with the inventory above; no feature order or option mapping is
guessed.

## v3 package split

In v3 `@adapttable/core` is framework-neutral and the React binding is
`@adapttable/react`. Kit `DataTable` imports do not change.
Capabilities do not disappear. Relocation is not deletion.

The complete symbol map — every current public export, its kind, class, and
destination — is [`scripts/v3-package-split-map.json`](../scripts/v3-package-split-map.json).
`node scripts/check-package-split-map.mjs` fails if a published typed entry
is missing from the map or a mapped symbol has no current home. Read
[ARCHITECTURE.md](../ARCHITECTURE.md) for the package graph and the engine /
column / AI contracts.

### How to read a move

| Symbol                  | v3 import                                                    | Kind                                                |
| ----------------------- | ------------------------------------------------------------ | --------------------------------------------------- |
| `useDataTable`          | `@adapttable/react`                                          | Headless React hook                                 |
| `ColumnDef`             | `@adapttable/react`                                          | React column (extends neutral `ColumnModel`)        |
| `TableSource`           | `@adapttable/core`                                           | Unchanged                                           |
| `useQuerySource`        | `@adapttable/react`                                          | React source hook; query types stay on core         |
| `useTableChrome`        | `@adapttable/react`                                          | Chrome binding                                      |
| `HeaderGroupCell`       | `@adapttable/react/adapter`                                  | Neutral header-group model                          |
| `sourceCapabilities`    | `@adapttable/core`                                           | Neutral helper                                      |
| `grouping`              | `@adapttable/<kit>/grouping` or `@adapttable/react/features` | Feature factory that returns a React `TableFeature` |
| `pivot`                 | `@adapttable/core/pivot`                                     | Pure engine                                         |
| `usePivotUrlState`      | `@adapttable/react/pivot`                                    | React hook                                          |
| `DataTable`             | `@adapttable/mui`                                            | Unchanged                                           |
| `createAgentSession`    | `@adapttable/ai`                                             | Unchanged                                           |
| `tableAgent`            | `@adapttable/ai-react`                                       | React binding                                       |
| `createAgentHttpClient` | `@adapttable/ai/http`                                        | Unchanged                                           |

The split retires no public symbol. A row in the map whose
`proposedImport` equals `currentImport` is a keep. Every other row is a
specifier change only, unless `behavior` is non-empty.

### Representative consumers

Plain engine (no React installed):

```ts
import {
  sourceCapabilities,
  type TableSourceCapabilities,
} from "@adapttable/core";
import { pivot } from "@adapttable/core/pivot";

const capabilities: TableSourceCapabilities = sourceCapabilities({
  allFilteredRows: rows,
  total: rows.length,
});
const result = pivot(rows, { rows: ["team"], columns: [], measures: [] });
```

Headless React — `useDataTable` from `@adapttable/react`:

```tsx
import {
  type ColumnDef,
  useDataTable,
  useFrontendData,
} from "@adapttable/react";

const columns: ColumnDef<Person>[] = [{ key: "name", header: "Name" }];
const source = useFrontendData({ data: people, columns });
const table = useDataTable({ source, columns, rowKey: (r) => r.id });
```

Kit — no import change:

```tsx
import { DataTable } from "@adapttable/mui";
import { grouping } from "@adapttable/mui/grouping";

<DataTable
  data={people}
  columns={columns}
  rowKey={(r) => r.id}
  features={[grouping("team")]}
/>;
```

AI — root stays React-free; the React feature binds to the live engine:

```ts
import { createAgentSession } from "@adapttable/ai";
import { tableAgent } from "@adapttable/ai-react";

const session = createAgentSession({ observe, apply });
const feature = tableAgent({ tableId: "orders" });
```

[ARCHITECTURE.md](../ARCHITECTURE.md) holds the contracts these four snippets
follow.

---

# Migrating from v1 to v2

This guide ends at v2. Continue with [Upgrading from v2](./migrate-from-v2.md)
to reach v3: several v2 names below — `virtualize` as a prop, MUI's `size`,
`@adapttable/core/adapter` — are removed in v3.

v2 is a truth-and-consistency release: every documented behavior now works
as written, the same word always means the same thing across all eight
adapters, and a batch of silent traps became loud. Nothing deprecated
ships — v1 names were removed, not aliased, so the compiler walks you
through the rename table below.

## The rename table

| v1                                                            | v2                                                | Where                                                         |
| ------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- |
| `enabled`                                                     | `urlSync`                                         | source hooks + `useTableUrlState`                             |
| `adapter`                                                     | `urlAdapter`                                      | source hooks + `UseSavedViewsOptions`                         |
| `useBackendData` / `UseBackendDataOptions`                    | `useQuerySource` / `UseQuerySourceOptions`        | the query-library source builder                              |
| `defaultLayout`                                               | `defaultColumnLayout`                             | column-layout hooks                                           |
| `selected` / `onChange`                                       | `selectedIds` / `onSelectionChange`               | `useSelection` options                                        |
| `collapsedIds` / `onCollapsedIdsChange`                       | `collapsedGroupIds` / `onCollapsedGroupIdsChange` | row grouping                                                  |
| `customToolbar`                                               | `toolbar`                                         | `ToolbarChromeProps`                                          |
| `PaginatedResponse.items` / `.hasNext`                        | `.rows` / `.hasNextPage`                          | response envelope                                             |
| `SortState`                                                   | `SortLevel` (one merged type)                     | sorting types                                                 |
| `colorScheme` (Chakra accent)                                 | `accentColor`                                     | Chakra adapter (frees the light/dark type name)               |
| `hideSearch`                                                  | `searchable` (positive polarity, default `true`)  | all adapters                                                  |
| `isMobile` prop                                               | `forceMobile`                                     | all adapters                                                  |
| `labels.applyFilters`                                         | `labels.filtersDone`                              | labels (the button closes; filters apply live)                |
| `SavedViewsMenuLabels` (and per-kit variants)                 | `SavedViewsLabels`                                | every adapter, one exported name                              |
| `PageSelector` returning `{ items }`                          | `{ rows }`                                        | `useQuerySource` custom `selectPage`                          |
| `GroupCollapseState.collapsedIds` (and the model option)      | `collapsedGroupIds`                               | headless grouping                                             |
| `useDataTable` option `isMobile`                              | `forceMobile` (result field stays `isMobile`)     | headless tier                                                 |
| `emptyState` / `loadingState` props                           | `slots.empty` / `slots.skeleton`                  | unstyled / shadcn (one override surface)                      |
| `classNames.rowsPerPageSelect`                                | `classNames.rowsPerPage`                          | unstyled / shadcn                                             |
| `classNames.pageButton`                                       | `pagePrev` / `pageNext` / `pageNumber`            | unstyled / shadcn (one key per rendered part)                 |
| `data-adapttable-part="group-row/group-cell"` (header groups) | `header-group-row` / `header-group-cell`          | header groups; `group-row`/`group-cell` now mean ROW grouping |
| `data-adapttable-part="retry"`                                | `retry-button`                                    | error state                                                   |
| antd `virtualHeight` / `virtualWidth`                         | removed — bound the scroller with `maxHeight`     | antd adapter                                                  |

## Behavior changes (and why)

- **The adapter-builder tier moved to `@adapttable/core/adapter`** (in v3:
  `@adapttable/react/adapter`). The
  ~65 exports only adapter implementations consume — `useDataTableShell`,
  the render prelude, chrome prop bundles, pinning and pager math, the
  inline icons — import from the new entry; `@adapttable/core` keeps the
  app-facing API. _Why: autocomplete and docs at the main entry now show
  only what app code is meant to use._

- **React 18 works again.** v1.2 accidentally required React 19.2
  (`useEffectEvent`); v2 runs the declared `^18 || ^19` range and CI
  proves it on 18.3 / 19.0 / 19.2.
- **Explicit `mode` prop.** `mode="server"` requires `onQueryChange` at
  compile time; `mode="frontend"` turns `onQueryChange` into a pure
  notification (the table keeps processing your `data`). Omitting `mode`
  keeps v1 inference exactly. _Why: the frontend tier had no way to
  observe query changes without surrendering the data path._
- **`onGroupByChange` and `onClearFilters` are observers.** The table
  always performs the change itself, then notifies. _Why: providing a
  logging handler used to silently replace the built-in mutation._ Take
  full control via `source.setGroupBy` / `source.clearExtras`.
- **One source-flag contract.** `isLoading` = first
  load only; `isFetching` = any in-flight; `hasNextPage`/`fetchNextPage` =
  infinite-append only (false / no-op when paged); `refetch` really
  re-runs. The `onQueryChange` tier now APPENDS on `fetchNextPage`
  (accumulating across round-trips) instead of replacing the page, and it
  resolves `paginationMode: "auto"` like the other tiers — mobile becomes
  infinite cards; pass `paginationMode="paged"` for the v1 behavior.
- **`baseParams` never beat live state, and filters are namespaced.**
  Query hooks receive filter values under `params.filters` instead of
  spread at the top level. _Why: a static param could silently override an
  active filter, and a filter named `sortBy` clobbered the sort._
- **The headless tier renders real tables.** `useDataTable` resolves
  bare-key columns (headers + accessors) like `<DataTable>` does, and
  `getRowProps` no longer smuggles `key` inside its spreadable result —
  read `getRowKey(row)`; `getCellContent(column, row, index)` renders
  Cell-or-accessor without casts.
- **`defaults`, `searchDebounceMs` and `paginationMode` are real
  component props** (they were documented but didn't exist), and
  `virtualize` on a paged table dev-warns instead of silently doing
  nothing.
- **An explicit `hideOnMobile: true` always wins** — the mobile identity
  anchor no longer forces hidden columns onto cards. A column marked
  `editable` without a composed `editing()` feature dev-warns instead of doing
  nothing.
- **The selection contract is settled**: uncontrolled =` onSelectionChange`
  observes (mount fire with the empty set, auto-reset on search/filter
  change included); controlled = change-request handler, no mount fire.
- **`clearAll` clears the multi-sort chain too** (it used to leave rows
  visibly sorted).
- **Grouped tables are a full-set view**: footer count, select-all scope
  and page-scope CSV all describe the rendered (full filtered) set.
- **CSV export**: formula-prefixed cells are neutralised by default
  (`escapeFormulas: false` opts out), and the export always contains the
  full exportable column set regardless of viewport.
- **`defaultConfirm` fails safe**: no dialog available (SSR, webviews)
  now DENIES a destructive action instead of auto-approving it.
- **Persisted state hydrates after mount** (column layout, saved views) —
  no SSR hydration mismatch; blocked storage is tolerated.
- **Styling surface is 1:1** — every `classNames` key maps to a rendered
  `data-adapttable-part` and vice versa (127 keys, enforced by tests);
  the shadcn preset styles every part; MUI and antd gained structural
  `classNames`; Chakra/Radix/Base UI export their `DataTableClassNames`.
- **`density` has a visual effect in every adapter** and kit `size`
  overrides it; `stickyTop` means the sticky-header inset everywhere
  (`stickyToolbar` follows `stickyHeader` on page-scroll tables; pass
  `false` to let the toolbar scroll away);
  Mantine's `SavedViewsMenu` takes the same `options` shape as the other
  kits.
- **Accessibility**: editable cells expose the VALUE as their accessible
  name (edit hint as title); Enter-commit restores focus; clickable rows
  use a roving tab stop and activate on Space; menus restore focus on
  Escape; antd multi-sort chains from the keyboard (Shift+Enter); bulk
  selection announces via a live region; the pager announces the current
  page.
- **i18n**: one locale-resolution algorithm for labels AND per-column
  `i18n` paths (`ar_EG` ≡ `AR-eg`); count-aware plural forms; a new
  `labels.removeFilter` names chip removal; the RTL list is script-based
  (Hausa out, Assyrian Neo-Aramaic / Western Punjabi / South Azerbaijani
  in).
- **Packaging**: truthful peer floors (Chakra `^3.13`, MUI `^6`,
  Mantine `^7.2`); `"use client"` in every hook-bearing build (Next App
  Router imports work without wrappers); LICENSE in every tarball; the
  CLI gained a CJS entry and stopped scaffolding on a bare invocation.

## Suggested path

1. Update the packages; let the compiler surface the renames (table above).
2. If you consume the `onQueryChange` tier: move filter reads to
   `query.filters` / `params.filters`, and re-test infinite flows (append
   semantics).
3. If you relied on replacing behavior through `onGroupByChange` /
   `onClearFilters`, switch to `source.setGroupBy` / `source.clearExtras`.
4. Re-run your visual checks on mobile if you used the server tier
   (auto → infinite cards) or relied on identity-anchored hidden columns.

---

# AdaptTable versioning & stability policy

AdaptTable follows [Semantic Versioning](https://semver.org/). This page states
what that means in practice, what the committed-stable API surface is, and how
deprecations are handled — so you can upgrade with confidence.

## Versioning policy

Given `MAJOR.MINOR.PATCH`:

- **PATCH** — bug fixes and internal improvements that don't change the
  public API. Always safe to adopt.
- **MINOR** — new features and backwards-compatible changes. Code written
  against the current minor keeps working on the next.
- **MAJOR** — breaking changes to the public API. We avoid these; when one is
  unavoidable, it ships in a major with a migration note in the CHANGELOG.

The published packages (`@adapttable/core`, `@adapttable/react`, the adapters,
`@adapttable/i18n`, `@adapttable/server`, `@adapttable/ai`,
`@adapttable/ai-react`, and `@adapttable/cli`) each follow
[changesets](https://github.com/changesets/changesets) **independently**: a
package only bumps when a changeset names it. Internal dependencies are exact
pins at publish time: adapters pin `@adapttable/core` and `@adapttable/react`,
`@adapttable/shadcn` pins `@adapttable/unstyled`, and `@adapttable/i18n`,
`@adapttable/server`, `@adapttable/ai` and `@adapttable/ai-react` pin
`@adapttable/core` (`@adapttable/ai-react` also pins `@adapttable/ai` and
`@adapttable/react`), so you do not need matching version numbers across
kits — install the adapter you use and let npm pull the core it was published
against. `@adapttable/cli` versions on its own cadence; its programmatic API
is still part of the public surface below.

## Stability

Each package carries its own version, and what its stability depends on is
its major line. The exact current version is on npm and at the top of the
package's `CHANGELOG.md`.

| Package                                                                 | Major line |
| ----------------------------------------------------------------------- | ---------- |
| `@adapttable/core`, the adapters, `@adapttable/cli`, `@adapttable/i18n` | `3.x`      |
| `@adapttable/react`                                                     | `1.x`      |
| `@adapttable/server`, `@adapttable/ai`, `@adapttable/ai-react`          | `0.x`      |

The packages at `1.0` and above are **stable**. The full SemVer contract above
applies to them: breaking changes to the public API surface (below) ship only
in a major release, with a migration note in the relevant package's
`CHANGELOG.md`. `@adapttable/server`, `@adapttable/ai` and
`@adapttable/ai-react` are `0.x`: under SemVer a `0.x` minor may carry a
breaking change, and its changelog names it. In
practice such changes are rare — most releases are additive minors and safe
patches.

## Supported UI-kit versions

Each adapter declares a wide peer range for its kit, and a weekly, non-blocking
peer-matrix workflow typechecks each adapter against the **oldest and newest**
supported major — so a claimed-but-broken version is caught before you hit it:

| Adapter                                       | Kit peer range                                   |
| --------------------------------------------- | ------------------------------------------------ |
| `@adapttable/mantine`                         | `@mantine/core` + `@mantine/hooks` 7.2+ – 9      |
| `@adapttable/mui`                             | `@mui/material` 6.1.2+ – 9                       |
| `@adapttable/chakra`                          | `@chakra-ui/react` 3.13+ and `@emotion/react` 11 |
| `@adapttable/antd`                            | `antd` 6                                         |
| `@adapttable/radix`                           | `@radix-ui/themes` 3                             |
| `@adapttable/base-ui`                         | `@base-ui/react` ^1.6                            |
| `@adapttable/unstyled` / `@adapttable/shadcn` | no UI-kit dependency                             |

`react` / `react-dom` 18 and 19 are supported across every package.

## Public API surface

**What is exported and documented is supported.** Removal or narrowing of
that surface happens in a major, with a migration note. A symbol tagged
`@internal` is not the contract even when it appears in the published
`.d.ts`. The complete name list lives on the [API reference](./api.md);
this page names every **supported entrypoint** so a derived allowlist
cannot omit one.

### `@adapttable/core`

The framework-neutral engine: `createTableEngine` and the view it publishes;
`TableSource`; the neutral column and filter models (`ColumnInput`,
`ColumnFilter`, `ColumnLayoutState`, …); the data operations — filtering,
sorting, paging, grouping, aggregation; URL-state codecs
(`parseTableUrlState` / `applyTableUrlState` / `UrlStateAdapter` /
`routerUrlAdapter`); the labels contract. No React in its import graph. The
[API reference](./api.md) lists every export on this entry.

### `@adapttable/react`

The React binding: the `useFrontendData` / `useQuerySource` / `useServerData`
source builders; `useDataTable` and its prop-getters; `BaseDataTableProps`;
`ColumnDef` and the other React column types, whose render callbacks return
elements; the URL-state hooks (`useColumnLayoutUrlState`,
`useDensityUrlState`, …); column-layout, selection, sorting, pagination and
virtualization hooks.

### `@adapttable/react/features`

Canonical home of the feature factories (`rowReorder`, `savedViews`,
`grouping`, `editing`, `virtualize`, `columnMenu`, `cellNavigation`,
`applyTableFeatures`, …). Kit subpaths re-export this entry; values stay
off the core main barrel.

### `@adapttable/react/adapter`

The supported **adapter-author** boundary. A ninth adapter is built from this
entry — `useDataTableShell`, chrome components, slot contracts, pager and pin
math, announcers — with the same SemVer promise as the main entry. App code
rarely imports it; reaching for it is choosing that contract, not an
undocumented escape. There is no private channel behind it.

### Focused core subpaths

Each is a published, supported entry — not an implementation detail:

| Entry                      | What it is                                                                                            |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `@adapttable/core/binding` | The framework-neutral adapter machinery `@adapttable/react/adapter` re-exports — import it from there |
| `@adapttable/core/formula` | Formula columns (`buildFormulaColumns`, `FormulaValue`, …)                                            |
| `@adapttable/core/pdf`     | Print / PDF writers and page layout (`PrintPageSize`, `PrintPageBreak`, …)                            |
| `@adapttable/core/pivot`   | Pivot engine (`pivot`, `serverPivotResult`, field helpers, pivot URL codecs)                          |
| `@adapttable/core/query`   | The query model without React — codecs a backend can load                                             |
| `@adapttable/core/stream`  | Live row patches (`RowPatch`, `RowPatchEvent`, …)                                                     |
| `@adapttable/core/xlsx`    | Spreadsheet export writer                                                                             |

`@adapttable/react` publishes the React-facing counterparts of the ones that
need elements — `/formula`, `/pivot`, `/stream` — plus `/sparkline`, the
sparkline column helper. `pivotTableModel` lives on `@adapttable/react/pivot`.

### Adapter main entries

Published kits: `@adapttable/mantine`, `@adapttable/mui`,
`@adapttable/chakra`, `@adapttable/antd`, `@adapttable/radix`,
`@adapttable/base-ui`, `@adapttable/unstyled`, `@adapttable/shadcn`.

Each main entry exports `<DataTable>` with `DataTableProps` /
`DataTablePropsBase` / `DataTableSlots` / `SavedViewsMenuProps`, plus the
documented kit extras (Mantine chrome components, unstyled/shadcn building
blocks, Radix and Base UI accent unions, unstyled `IconProps`, shadcn's
`shadcnClassNames`). `@adapttable/base-ui` also publishes `./styles.css`, its
minimal chrome stylesheet. Styled kits do **not** expose every internal node —
their `classNames` are the documented wrapper hooks; per-node classes and
`data-adapttable-part` are the unstyled/shadcn contract.

### Kit feature subpaths

Forty paths, the same on every published adapter, re-exporting
`@adapttable/react/features` (and the pivot panel on `/pivot`):

`/features`, `/preset`, `/assistant`, `/batch-editing`, `/bulk-actions`,
`/cell-navigation`, `/cell-span`, `/column-groups`, `/column-menu`,
`/column-selection`, `/command-palette`, `/context-menu`, `/density`,
`/editing`, `/export`, `/extra-rows`, `/filters`, `/find-in-table`,
`/fit-columns`, `/fullscreen`, `/grouping`, `/grouping-panel`,
`/header-filters`, `/multi-sort`, `/nested-table`, `/pinned-summary-rows`,
`/pivot`, `/print`, `/resizable-columns`, `/row-actions`, `/row-appearance`,
`/row-detail`, `/row-pinning`, `/row-reorder`, `/saved-views`,
`/selection-stats`, `/side-panel`, `/status-bar`, `/tree`, `/virtualize`.

`/preset` carries `standardFeatures` — the composed starting point. Import
from the kit you mount (`@adapttable/mantine/row-reorder`, …) so the factory
and the table share one package.

### `@adapttable/i18n`

Locale presets (`en`, `ar`, …, `zhTW`), `getLabels` / `hasLocale` /
`locales` / `LocaleKey`, and direction helpers (`getDirection`,
`isRtlLocale`, `primarySubtag`, `RTL_LANGUAGES`).

### `@adapttable/ai`

`createAgentSession`, the `adapttable.agent.v1` manifest and the
`CAPABILITY_KEYS` catalog. Optional — core and adapter roots do not
re-export it. Its subpaths are supported entries too:

| Entry                      | What it is                                                                 |
| -------------------------- | -------------------------------------------------------------------------- |
| `@adapttable/ai/json`      | Provider-neutral JSON tool envelope (`executeEnvelope`, `executeJsonTool`) |
| `@adapttable/ai/openai`    | OpenAI tool definitions and execution (`executeOpenAITool`)                |
| `@adapttable/ai/mcp`       | MCP tool execution (`executeMcpTool`, `mcpListChanged`)                    |
| `@adapttable/ai/http`      | The agent HTTP wire (`AGENT_HTTP_LIMITS`, `AgentHttpError`)                |
| `@adapttable/ai/assistant` | The assistant loop (`createTableAssistant`, `planUndo`)                    |
| `@adapttable/ai/context`   | Context and prompt builders (`buildAgentContext`, `agentInstructions`)     |
| `@adapttable/ai/voice`     | Dictation (`createSpeechInput`)                                            |
| `@adapttable/ai/webmcp`    | WebMCP registration (`registerWebMcpTools`)                                |
| `@adapttable/ai/ag-ui`     | AG-UI protocol tools (`aguiTools`)                                         |
| `@adapttable/ai/ai-sdk`    | AI SDK stream adapter (`aiSdkCapability`)                                  |
| `@adapttable/ai/mcp-apps`  | MCP Apps host bridge (`createMcpAppBridge`)                                |

### `@adapttable/ai-react`

`tableAgent`, `useTableAssistant`, `useSpeechInput` and `TABLE_AGENT_STATE`. Depends on `@adapttable/ai` and
`@adapttable/react`. The AI root stays React-free.

### `@adapttable/server`

`parseTableQuery` against a `QuerySchema`, returning `ServerTableQuery` and
`QueryRejection[]`. `QueryInput` is a `Request`, `URL`, query string or
`URLSearchParams`.

### `@adapttable/cli`

The `adapttable` binary — `init [--force]` and `migrate-v3 [paths...] [--check]`
— and the programmatic surface:
`detectKit`, `runInit`, `choosePackageManager`, `installCommand`,
`scaffoldFiles`, plus `KITS` / `Kit` / `KitInfo` / `SHADCN`,
`packagesFor` / `mergeDependencies`, `starterComponent` / `ScaffoldFile` /
`STARTER_PATH`, `PackageManager`, `InitError`, `InitOptions` /
`InitResult` / `InitIO`. `./package.json` and the binary path are not typed
entrypoints.

## Customization ladder

Four rungs, each more surface than the last. A styled adapter does not
pretend to be the last two:

1. **Kit theming and adapter defaults** — the table looks like the rest of
   the app because it is built from that kit. Theme through the kit
   provider; no AdaptTable class map required.
2. **Structural slots, `classNames`, and render callbacks** — replace a
   region (`slots.empty`, `toolbar`, `confirm`) or restyle the hooks the
   kit documents. Styled adapters expose wrapper hooks (`root`, `toolbar`,
   `table`, `card`, `footer`), not every cell and icon.
3. **Unstyled / shadcn per-node classes** — `@adapttable/unstyled` (and
   `@adapttable/shadcn` on top of it) expose a `classNames` key and a
   stable `data-adapttable-part` on every rendered node. That part map is
   the contract; see [customization](./customization.md).
4. **Headless markup** — `useDataTable` and the prop-getters, or a custom
   adapter over `@adapttable/react/adapter`. You own every pixel.

Reach for the lowest rung that does the job. Jumping to `/adapter` or
headless getters to restyle a button is using the wrong contract.

## Deprecation policy

When an API is retired, it is **not** removed immediately:

1. The deprecated API is marked `@deprecated` with a JSDoc note pointing to the
   replacement.
2. It keeps working for **at least one minor** release (longer when practical).
3. Removal happens in a **major** release.

We never silently remove a documented public API.

v3 is the one release that did not follow step 2 for its enabling props: the
last v2 release (`@adapttable/core@2.9.0`) carried no `@deprecated` note on the
`<DataTable>` props v3 replaced with features, and v3 removed them in the
major. Its main-entry adapter aliases were deprecated in v2 as step 1
describes. [Upgrading from v2](./migrate-from-v2.md) maps every removed prop
to its feature, and `npx @adapttable/cli migrate-v3` reports each one in a
codebase.

## Releasing

Releases are produced by changesets: open a changeset describing which packages
changed, merge it, and the release workflow versions **only those packages** and
publishes them to npm with a generated per-package `CHANGELOG.md`. See
[CONTRIBUTING.md](../CONTRIBUTING.md) for the contributor flow.