# 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://orwa-mahmoud.github.io/adapttable/llms.txt.


---

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

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

<video src="https://orwa-mahmoud.github.io/adapttable/media/core/tour.mp4" poster="https://orwa-mahmoud.github.io/adapttable/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, filterable, paginated
table with URL-synced state, selection + bulk actions, RTL, and dark mode.

## 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 69–79 kB min+gzip (measured 2026-09-15 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
```

## 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 \|\| ^7 \|\| ^8 \|\| ^9`                                          |
| Chakra UI         | `^3.13.0`                                                             |
| Ant Design        | `^6`                                                                  |
| Radix Themes      | `^3`                                                                  |
| Base UI           | `^1`                                                                  |
| 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. 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
- [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
  keyboard, dataset-relative indices.
- [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://orwa-mahmoud.github.io/adapttable/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://orwa-mahmoud.github.io/adapttable/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. Both built-in source hooks fulfil it, and the table renders without
knowing which produced it.

```ts
interface TableSource<TRow> {
  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
  refetch?: () => void; // re-runs the underlying fetch
  error: Error | null;
  paginationMode: "infinite" | "paged";
  // state
  page: number;
  limit: number;
  search: string;
  sortBy: string | undefined;
  sortDir: "asc" | "desc" | undefined;
  extra: Record<string, string | string[] | number | undefined>;
  // setters
  setPage;
  setLimit;
  setSort;
  setSearch;
  setExtra;
  setExtras;
  clearAll;
}
```

Because the table is agnostic to the source's origin, you can switch between
in-memory and server data — or build a custom source — 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
  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**, using the same breakpoint the table uses, so the two
never drift. 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/core` — attach
the returned ref to a sentinel element after your last row to get the same
behaviour in custom markup:

```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 `virtualize`. The
core exports `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 prop 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
<DataTable
  source={source}
  columns={columns}
  rowKey={(row) => row.id}
  paginationMode="infinite"
  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 the shared
mobile breakpoint. `hideOnMobile` can hide low-value columns, while
`mobileIdentityColumns` preserves a configurable number of leading
desktop-visible columns so every card keeps enough identity to be useful.

```tsx
<DataTable mobileIdentityColumns={2} />
```

## 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, 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.                                                               |

`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.

## 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.

---

# React table features — optional imports, presets and plugins

▶ **See it working:** [the Feature Lab](https://orwa-mahmoud.github.io/adapttable/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 { 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.

The props that used to arm features are inert: `enableColumnMenu`,
`bulkActions`, `contextMenu`, `commandPalette`, `statusBar`, `sidePanel`,
`findInTable` and the rest configure a feature you compose, and draw nothing on
their own.

## Kit subpaths

Every public adapter exports the same factories:

| Import                              | Factory                                                           |
| ----------------------------------- | ----------------------------------------------------------------- |
| `@adapttable/<kit>/row-reorder`     | `rowReorder`                                                      |
| `@adapttable/<kit>/saved-views`     | `savedViews`                                                      |
| `@adapttable/<kit>/grouping-panel`  | `groupingPanel` — grouping headers + interactive panel            |
| `@adapttable/<kit>/grouping`        | `grouping` — code-fixed grouping without the interactive panel    |
| `@adapttable/<kit>/editing`         | `editing`                                                         |
| `@adapttable/<kit>/virtualize`      | `virtualize`                                                      |
| `@adapttable/<kit>/column-menu`     | `columnMenu`                                                      |
| `@adapttable/<kit>/cell-navigation` | `cellNavigation`                                                  |
| `@adapttable/<kit>/preset`          | `standardFeatures`, `StandardFeatureOptions`                      |
| `@adapttable/<kit>/features`        | every factory, plus `applyTableFeatures`                          |
| `@adapttable/<kit>/pivot`           | `PivotPanel` and the pivot engine (`pivot`, `pivotTableModel`, …) |

`<kit>` is `mantine`, `mui`, `chakra`, `antd`, `radix`, `base-ui`, `shadcn`,
or `unstyled`. The factories themselves live in `@adapttable/react/features`;
the kit subpaths re-export them so the import path matches the table.

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,
fit-columns, the fullscreen toggle, header filters, multi-sort, resizable
columns and the status bar.

Configurable preset members join only when you give them input. 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: { storage: "local" },
  }),
  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 69 kB gzipped and the same table with
`standardFeatures()` composed is 122 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: "number",
      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)]} … />;
```

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,
} from "@adapttable/react/adapter";

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` · `feature` (ad-hoc patch) · `applyTableFeatures`
(the merge used by every adapter) · `useTableFeatures` (apply + `setup(host)`,
the hook every adapter runs) · `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
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                                                                                                                                                                                       |

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.

```tsx
import { keepPreviousData, useInfiniteQuery } from "@tanstack/react-query";
// or import from "@adapttable/mui", "@adapttable/chakra", "@adapttable/antd",
// "@adapttable/radix", "@adapttable/shadcn", "@adapttable/unstyled" — same props everywhere.
import {
  DataTable,
  type PaginatedResponse,
  type TableQueryParams,
  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.hasNext ? 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 and
  StrictMode double-mounts 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                            |

**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 { tableQueryKey, tableQueryBaseKey } from "@adapttable/core";

const infinite = useInfiniteQuery({
  queryKey: tableQueryKey(query, { scope: "people" }),
  queryFn: ({ signal }) => fetchPeople(query, signal),
  getNextPageParam: (last) => last.nextCursor,
});

// 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, each
covered by a test:

- **One request per query.** Queries are compared by value, so setting the same
  search term three times in a tick, an identical re-render, or a StrictMode
  double-mount all collapse into a single call.
- **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`; requires `supports.aggregates`. 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.                                                                                        |

## 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://orwa-mahmoud.github.io/adapttable/demo/).

---

# 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`, `toggleSort`) 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 the column's accessor. 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, 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`                    | the generated accessor value | Primitive extractor for the client-side sort. See [sorting](./sorting.md).                                    |
| `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.                                                             |
| `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. `accessor`, when it happens to return a primitive
5. the key's data path

with one deliberate restriction on that last step: **a column that renders its
own cell never falls back to the data path.** A column with
`accessor: () => null` renders an empty cell, and reading its path would
announce a value the user cannot see — worse than announcing nothing. Such a
column resolves to `""`, and giving it a `formatValue` is the fix.

## 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/core";

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`, `sortValue` and `exportValue`
  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. The spec type is exported as `ComputedColumnSpec` for callers that build columns dynamically.

## 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.

Pass `collapsibleColumnGroups` 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 needs `sortValue` to be sortable — without it the sort silently no-ops and 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://orwa-mahmoud.github.io/adapttable/demo/).

---

# React table column groups — spanning headers, collapsible

▶ **See it working:** [collapse column groups in Mantine](https://orwa-mahmoud.github.io/adapttable/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. Omit
`collapsibleColumnGroups` and the headers stay static.

This is not [row grouping](./row-grouping.md). Rows fold under a `groupBy`;
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";

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}
  collapsibleColumnGroups
/>;
```

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

Pass `collapsibleColumnGroups` 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 (when armed) 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://orwa-mahmoud.github.io/adapttable/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://orwa-mahmoud.github.io/adapttable/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`).

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); 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 extra prop.

## Example

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

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}
      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 the column's accessor. Numbers 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` under `multiSort`. `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). 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`     | `boolean`                                  | `false`                      | Opt into multi-column sorting via shift-click / shift-Enter.                       |
| `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 needs `sortValue`; otherwise the sort cannot resolve a value and a development warning fires (`sortBy` matching 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://orwa-mahmoud.github.io/adapttable/demo/).

---

# 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) — this page's feature is already wired in `src/App.tsx` (declarative `filter` widgets on four columns); 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 / 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`
  replaces the built-in handler.

## 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.                                                                                                                                                                                                                               |
| `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: compact per-column row; hides the Filters button.   |
| `onClearFilters`            | `() => void`                        | built-in clear | Clear handler used by the drawer and the chip strip.                                                                                      |
| `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.            |
| `filterTypes([…])`          | `FilterTypeSpec[]`                  | built-ins      | Extra or replacement filter types merged onto `defaultFilterRegistry`. Same `type` replaces. Compose via `features`.                      |
| `headerFilters()`           | factory                             | —              | Compose when `filtersMode="header"` (or pass `headerFilters` on a test harness). 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` on the table 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; `extend("text", { ops })` adds operators without forking.
  `emptyFilterRegistry` seeds a registry from scratch.
  `FilterTypeRegistry` / `FilterWidgetKind` / `FilterWidgetRenderProps`
  are the types.
- **Header filter row**: compose `headerFilters()` and set
  `filtersMode="header"` (see [feature composition](./features.md))
  mounts each adapter's `FilterHeaderRow` / `FilterHeaderControl` over
  `FilterHeaderChrome` / `FilterHeaderControlChrome`. Helpers
  `filterDefForColumn` / `headerFilterStickTop` stay on core. The row
  sits under the leaf header and hides the toolbar Filters button
  (`resolveFilterMode` / `FilterChromeMode`).
  Pads and column spacers match the header so sticky, pin offsets, and
  column windowing stay aligned. A def whose bag key differs from the
  column key sets `column` (`key: "name"` under `column: "person"`). Ant Design keeps the control inside the
  header cell so `fixed` columns stay on antd's own header. Compact
  range inputs default the operator to `gte` (no picker in the header);
  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 `Min` / `Max` key pair,
  `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 the `filters` prop 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**: `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://orwa-mahmoud.github.io/adapttable/demo/).

---

# React table advanced filters — AND/OR filter tree

▶ **Try it live:** [Filtering in Mantine](https://orwa-mahmoud.github.io/adapttable/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

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" },
      ]}
      filtersMode="popover"
      urlKey="f"
    />
  );
}
```

Pass `filterTreeFn` on `useFrontendData` (or `supports.filterTree` on a
server source) so the engine evaluates the tree. Each adapter's
`FilterTreeBuilder` mounts itself at the top of the Filters form when
`source.setFilterTree` is set; omit the setter and the builder is gone.

## 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.
- **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 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**,
  using the same breakpoint as the card/table layout switch, so the two never
  drift.
- **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, 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
const [data, setData] = useState({ rows: [], nextCursor: null });

const source = useServerData({
  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 res = await fetch(
      `/api/rows?limit=${limit}&search=${search}` +
        (cursor ? `&cursor=${cursor}` : ""),
      { signal }
    );
    setData(await res.json()); // { rows, nextCursor }
  },
});
```

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 infinite
  scroll (`paginationMode="infinite"`) 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
const source = 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.

Using a query library instead? `useQuerySource` already supports cursors
through your own `getNextPageParam` — the table reads `hasNextPage` and calls
`fetchNextPage`, and never needs to see the token.

## 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.                           |

## Notes

- `limit` is clamped to **1–500**, whether it comes from
  `defaults` or a hand-edited URL.
- Sources built with `useServerData` (the `onQueryChange` tier) are always
  paged; `paginationMode` applies to the frontend tier and `useQuerySource`.
- `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 as a headless hook,
  `useInfiniteScroll`, for custom markup; it no-ops safely where
  `IntersectionObserver` is unavailable (SSR, tests).

See it live in the [demo](https://orwa-mahmoud.github.io/adapttable/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.
- **`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.
- **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 or different filter values).

## 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)`  | `RowAction<TRow>[]`        | —                | Factory from `@adapttable/<kit>/row-actions`; trailing per-row actions, independent of selection.                                                                                                                                |
| `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)`.
- 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`).
- 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`), `useBulkActionRunner`, and `runRowAction` are exported from
  `@adapttable/core`.

See it live in the [demo](https://orwa-mahmoud.github.io/adapttable/demo/).

---

# 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://orwa-mahmoud.github.io/adapttable/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 passing `renderRowDetail` — its
presence is the whole API.

## Example

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

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}
      renderRowDetail={(row) => (
        <ul>
          {row.items.map((item) => (
            <li key={item}>{item}</li>
          ))}
        </ul>
      )}
    />
  );
}
```

## How it works

- Passing `renderRowDetail(row)` enables a leading expand chevron on desktop
  rows and a detail section on mobile cards — no extra flag.
  `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

| Prop                    | Type                       | Default | Description                                                              |
| ----------------------- | -------------------------- | ------- | ------------------------------------------------------------------------ |
| `renderRowDetail`       | `(row: TRow) => ReactNode` | —       | Detail-panel renderer; its presence enables expansion.                   |
| `defaultExpandedRowIds` | `readonly string[]`        | —       | Row ids whose panel starts open. Later toggles own the set.              |
| `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 `virtualize`. 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://orwa-mahmoud.github.io/adapttable/demo/).

---

# 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()`); 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://orwa-mahmoud.github.io/adapttable/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`      | `"text" \| "number" \| { type: "select"; options }`     | `"text"` | Widget for the active cell.                                                |
| `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.

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
const actions = [
  { key: "edit", label: "Edit", icon: <PencilIcon />, editsRow: true },
  { key: "delete", label: "Delete", onClick: remove },
];
```

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
<DataTable {...props} 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` grew `reconcileRow`
(`ReconcileLiveRowEdit` in) and `isRowConflict` for the row unit, plus
`reconcileBatch` (`ReconcileLiveBatchEdit` in) for a batch, and
`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 }))
      );
    }),
  ]}
/>;
```

`onBatchEdit` is called **once** per save through `batchEditing(handler)`, 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`.

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. Three
handlers cover it, and each one puts its own control on screen:

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

<DataTable
  {...props}
  features={[rowActions()]}
  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 `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.

Pass `rowActionsLayout="menu"` to collapse those buttons into a 3-dot menu
(omit or `"buttons"` keeps today's strip). `renderRowActions` replaces the
cell entirely when you want your own chrome — it wins over the layout.

**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.

## 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).

**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.

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`.

## 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
— `table.editing?.dirty` exposes `confirm`, `confirmRow` and `confirmAll`, plus a
`count` for an "unsaved changes" line.

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`).

| 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` / `ValidationTarget` / `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://orwa-mahmoud.github.io/adapttable/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 { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { editHistory, editing } from "@adapttable/mantine/editing";

<DataTable
  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 your own buttons,
`table.editHistory` carries `undo()`, `redo()`, `canUndo`, `canRedo` and
`clear()` — 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://orwa-mahmoud.github.io/adapttable/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 { applyRowReorder, DataTable } from "@adapttable/mantine";
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)`
(`RowReorderState`, also exported as `TableRowReorderState`, is what it
returns; `RowReorderHandler` is the ordinal write) is the grab state.
`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) — pass `onPinnedRowIdsChange` and pin actions appear. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [pin and merge rows in Mantine](https://orwa-mahmoud.github.io/adapttable/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://orwa-mahmoud.github.io/adapttable/demo/mantine/row-reordering/). The same pages exist for MUI, Chakra, antd, Radix, Base UI, shadcn and Tailwind.

Pass `pinnedRowIds` and/or `onPinnedRowIdsChange` and every row gains icon-only
Pin to top / Pin to bottom / Unpin (labels on hover and as the accessible name).
Omit both and nothing renders, nothing ships in
the hot path — the same opt-in rule as `onCellEdit`. 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, type RowPinState } from "@adapttable/mantine";
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}
      pinnedRowIds={pinnedRowIds}
      onPinnedRowIdsChange={setPinnedRowIds}
    />
  );
}
```

Uncontrolled: pass only `onPinnedRowIdsChange` (an observer) and the table
holds the lists. The batteries-included shell also writes them to the URL
(`rowPin=id1:top,id2:bottom`) so a shared link keeps the same rows stuck.
`useRowPinningUrlState` is the same pair for a host that wants to own the
URL itself. Saved views capture `rowPin` with the rest of the table.

## 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. Passing the
props 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://orwa-mahmoud.github.io/adapttable/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.

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`.

---

# 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) — pass `getCellSpan` or `column.colSpan`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [merge cells in Mantine](https://orwa-mahmoud.github.io/adapttable/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`. Omit `getCellSpan` and every `column.colSpan` /
`column.rowSpan` and the list is one cell per column — nothing extra renders.

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 `cellSpanAppearance="merged"`.
Pass `"plain"` 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";

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  getCellSpan={({ 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 }
```

`getCellSpan` wins when both are set. 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) — pass `extraRows`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [the live demo](https://orwa-mahmoud.github.io/adapttable/demo/) — turn **Extras** 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 — omit `extraRows` and nothing is inserted.

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

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  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 that person's `rowStyle` fill (light and dark are whatever
you passed) — AdaptTable does not pick a colour of its own.

```tsx
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) — pass `rowStyle` or `rowHeight`. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [the live demo](https://orwa-mahmoud.github.io/adapttable/demo/) — turn **Style** on.

`rowClassName` already appends a class. `rowStyle` and `rowHeight` are the
inline half of the same hook: a function of `(row, index)`, applied on
desktop rows and mobile cards alike. Omit both and nothing is set.

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

<DataTable
  data={rows}
  columns={columns}
  rowKey={(row) => row.id}
  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
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.

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
  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
  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
  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:

```tsx
import { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { findInTable } from "@adapttable/mantine/find-in-table";

<DataTable features={[cellNavigation(), findInTable()]} />;
```

Find is not search. 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.
Walking moves the table's focus with it, so the cell is scrolled into view,
announced, and left selected — a find that highlighted without going there would
leave you hunting for the highlight. 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 { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { selectionStats } from "@adapttable/mantine/selection-stats";

<DataTable features={[cellNavigation(), selectionStats()]} />;
```

> Count 12 · Sum 1,240.5 · Avg 103.4 · Min 12 · Max 900

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 { cellNavigation } from "@adapttable/mantine/cell-navigation";
import { columnSelectionCheckbox } from "@adapttable/mantine/column-selection";

<DataTable features={[cellNavigation(), columnSelectionCheckbox()]} … />;
```

It needs `cellNavigation()`, because that is what makes a selection exist at all;
either factory alone renders nothing. 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
`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.

`onRangeChange` fires whenever it changes and `table.gridFocus.range` holds the
current rectangle — which is what `exportCsv` with `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
test asserts the rendered markup is byte-identical to a table built without the
feature at all, in every one of the eight adapters.

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 moves focus too: state follows the DOM rather than fighting it.

---

# 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) — edit the table in the browser, no install. [Other UI kits →](./getting-started.md#try-it-in-stackblitz)

▶ **See it working:** [collapse groups and override aggregations in Mantine](https://orwa-mahmoud.github.io/adapttable/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://orwa-mahmoud.github.io/adapttable/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()` remains the no-panel path for a host that
deliberately fixes grouping in code. 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 as before, and also `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. Built-in
`budget:sum` URLs stay compatible.

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
const source = useQuerySource<Person, Params, Page>({
  queryKey: ["people"],
  queryFn: fetchPeople,
  select: (page) => ({
    rows: page.rows,
    total: page.total,
    groups: page.groups,
  }),
  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
}
```

Return them as `groups` on the source and 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";

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 link built
before the panel existed still works, 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) => Partial<Record<string, ReactNode>>` shape as `summaryRow`; 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

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;
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)`.

`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.            |
| `collapsedGroupIds`         | `readonly string[]`                                             | —       | Controlled collapsed group keys (ephemeral — not URL-synced).                                        |
| `onCollapsedGroupIdsChange` | `(ids: string[]) => void`                                       | —       | Controlled collapse channel; uncontrolled mode uses internal state.                                  |
| `labels`                    | `TableLabels`                                                   | English | Override 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, ReactNode>>` 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
`"sum" | "avg" | "min" | "max" | "count" | "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. Adapter authors build the panel with
`GroupingPanelChrome` and its required slots.

## Notes

- Bucketing uses the column's `sortValue` when present, otherwise a path lookup
  on the column key — never the JSX `accessor`.
- Works on desktop rows and mobile cards, LTR and RTL, with and without
  `virtualize` (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://orwa-mahmoud.github.io/adapttable/demo/) —
rows are grouped by team with a budget subtotal per group.

---

# 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.

## 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 { pivot, pivotTableModel } from "@adapttable/core/pivot";
import { DataTable } from "@adapttable/mantine";

const result = pivot(sales, config, { collapsed });
const model = pivotTableModel(result, { fields, labels });

<DataTable {...model} />;
```

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 the table's
`rowClassName`.

## 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 });
```

## 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 ships it pre-wired as `PivotPanel`, 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 { pivot, usePivotUrlState } from "@adapttable/core/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#aggregates) · [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://orwa-mahmoud.github.io/adapttable/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/core/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}
/>;
```

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.

## 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.                               |
| `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/core/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` —
one `key:formula[:header]` entry per column, `;`-separated, every field
percent-encoded so a formula may contain the delimiters. Writes are debounced
(`FORMULA_URL_WRITE_DEBOUNCE_MS`), 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.

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. Pass `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.

```tsx
<DataTable
  data={FILES}
  columns={columns}
  rowKey={(row) => row.id}
  getChildren={(row) => row.children}
/>
```

Without either prop the table is the flat list it always was. Nothing is a mode
to switch on: a tree is declared by the data.

## 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:

|                            | `groupBy`                 | `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. A table
may use both — group a tree by a column and the groups hold trees.

## Which column carries the chevron

The first column, unless `treeColumn` names another:

```tsx
<DataTable {...props} getChildren={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}
  getChildren={getChildren}
  expandedIds={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}
  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}
  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 and leaves the
node closed and clickable, so the retry is the same gesture as the first attempt.

Headless: `useLazyChildren` holds the state (`LazyChildrenState`, options
`UseLazyChildrenOptions`) 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
const [expandedIds, setExpandedIds] = useState<string[]>([]);

const source = useQuerySource<Node, Params, Page>({
  queryKey: ["files", expandedIds],
  queryFn: fetchFiles,
  supports: { tree: true },
  expandedIds,
});

<DataTable
  source={source}
  columns={columns}
  rowKey={(row) => row.id}
  getParentId={(row) => row.parentId}
  hasChildren={(row) => row.childCount > 0}
  expandedIds={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

▶ **See it working:** [nested tables in Mantine](https://orwa-mahmoud.github.io/adapttable/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.

`renderRowDetail` 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` puts the same component in there instead:

```tsx
<DataTable
  data={people}
  columns={columns}
  rowKey={(row) => row.id}
  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 `renderRowDetail`
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), and the parent's `density` and `labels`. Spread them first and override
anything after.

Return `undefined` for a row with no nested table. With `renderRowDetail` also
set, those rows fall back to it, 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. `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)`.

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 each adapter, 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 each adapter, 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

`@adapttable/unstyled` and `@adapttable/shadcn` stamp `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` 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://orwa-mahmoud.github.io/adapttable/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; enabling props
such as `enableColumnMenu` or `resizableColumns` draw nothing on their own. See
[feature composition](./features.md). Every adapter shares the same engine from
`@adapttable/core`.

## Example

```tsx
import { useColumnLayoutStorageState } from "@adapttable/core";
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/core) 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 (inline start/end), so a "left" pin sticks to the correct 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: "right" }` 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). |
| `defaultColumnLayout`       | `Partial<ColumnLayoutState>`          | —       | Initial layout for the uncontrolled mode.                                                                                      |
| `columnLayout`              | `ColumnLayoutState`                   | —       | Controlled layout (hidden/order/pinned/widths/names).                                                                          |
| `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.                                                       |

## 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://orwa-mahmoud.github.io/adapttable/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 **everything the table can put in a URL**: search, the
multi-sort chain, page and page size, the simple filters and the advanced
filter tree, ordered grouping keys (`groupBy`), session aggregation overrides
(`groupAgg`), and which groups are collapsed, the whole column layout (order,
hidden, pinned, widths, user-renamed column names, collapsed column groups),
pinned rows, density,
and the [pivot configuration](./pivot.md). 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
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 exactly as before.
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, 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).
- `adapter` and `urlKey` default to the table's own `urlAdapter` / `urlKey`,
  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.      |
| `adapter`    | `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`. |

## 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/core";

  const views = useSavedViews({ storageKey: "people-views", urlKey: "people" });
  // views.views, views.save("Active EU"), views.apply("Active EU"),
  // views.remove("Active EU")
  ```

- Column layout is part of a view only when it lives in the URL (wire
  `useColumnLayoutUrlState`); 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://orwa-mahmoud.github.io/adapttable/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://orwa-mahmoud.github.io/adapttable/demo/mantine/scale/) — a real table you can scroll, not a recording.

Long lists can opt into row/card windowing with one prop: `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, shadcn, unstyled

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"
      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 (default `false`) and 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 prop 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.
- `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.
  `virtualizeColumns` 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

| Prop                  | Type      | Default | Description                                                       |
| --------------------- | --------- | ------- | ----------------------------------------------------------------- |
| `virtualize`          | `boolean` | `false` | Window the rendered rows/cards on long infinite lists.            |
| `virtualizeColumns`   | `boolean` | `false` | Window the rendered columns on very wide tables.                  |
| `maxHeight`           | `number`  | —       | Fixed-height scroll box (px); switches to element-mode windowing. |
| `estimateRowSize`     | `number`  | `56`    | Desktop row-height estimate in px.                                |
| `estimateCardSize`    | `number`  | —       | 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**, headless Chromium, 1280×900):

|                                | Rows in the DOM | Retained JS heap |
| :----------------------------- | --------------: | ---------------: |
| **Virtualized** (`virtualize`) |          **24** |        **17 MB** |
| Plain table — same 10,000 rows |          10,000 |           368 MB |

Windowing mounts **417× fewer DOM nodes** (24 vs 10,000 — a viewport's worth
plus overscan) and holds **351 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 24 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 **~24 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 | **24** | **24** | **24** |  **24** |

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
```

A showcase already running on the port is used as-is, so
`pnpm --filter @adapttable/showcase dev` in another terminal still works and is
the faster loop while iterating.

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 `renderRowDetail` 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 is exported as `useTableVirtualization` for custom markup;
  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://orwa-mahmoud.github.io/adapttable/demo/).

---

# Responsive React table — automatic mobile card layout

▶ **See it before you install:** [the live mobile demo](https://orwa-mahmoud.github.io/adapttable/demo/mantine/mobile-cards/) — the same table flipped between desktop rows and phone cards with one toggle.

<a href="https://orwa-mahmoud.github.io/adapttable/demo/mantine/mobile-cards/"><img src="https://orwa-mahmoud.github.io/adapttable/media/features/mobile.gif" alt="The same AdaptTable data table as phone cards — scrolling the card list, then switching to the desktop table" width="640" height="392" style="width:100%;height:auto;aspect-ratio:640/392;border-radius:8px" /></a>

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 prop           |
| 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.
- **`mobileIdentityColumns`** (default `3`) — how many leading desktop-visible
  columns the cards always keep.
- **`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://orwa-mahmoud.github.io/adapttable/demo/mantine/mobile-cards/) uses
  exactly this prop for its toggle.
- **`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.
- **`rowStyle` / `rowHeight`** apply 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.

Flat cards expose 44px up/down controls. Grouped and tree cards also expose
the kit-native **Move to group…** / **Move under…** menu, including explicit
confirmation when `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://orwa-mahmoud.github.io/adapttable/demo/mantine/mobile-cards/)

---

# React table URL state — shareable filters, sort, and page

▶ **See it working:** [the live demo](https://orwa-mahmoud.github.io/adapttable/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";

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"
      />
      <DataTable
        data={orders}
        columns={[{ key: "ref" }, { key: "total", filter: "numberRange" }]}
        rowKey={(o) => o.id}
        urlKey="orders"
      />
    </>
  );
}
// → ?people.q=avery&people.page=2&people.atv=1&orders.f_totalMin=100&orders.atv=1
```

The same `urlKey` option exists on `useFrontendData`, `useQuerySource`,
`useTableUrlState`, `useColumnLayoutUrlState`, 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>` (the headless
hooks call the option `adapter`).

## 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 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, clamped to 1–500; 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.                                                                                                                                                                                               |

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)` reads a whole query string into table state;
`updateTableUrlState(search, patch)` returns the next query string;
`applyTableUrlState` and `captureTableUrlState` move that state on and off a
live table.

Each param has a named constant and, where the value is not a plain string, a
reader and a writer:

| Constant                                        | Reader / writer                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------- |
| `PARAM_PAGE`, `PARAM_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                           |
| `f_<key>`                                       | `readExtra` / `writeExtra`                                             |
| `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`),
    },
  }),
]}
```

Use this route only when downloading every page and holding the resulting file
in the tab is appropriate. The cap, paging behavior, and
`onBeforeExport`/`onAfterExport` hooks are unchanged.

## 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 PDF export and print layout

▶ **See it working:** [download a grouped PDF and print the same view](https://orwa-mahmoud.github.io/adapttable/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` is the production default for the export button: the same
`exportCsv()` seam as [CSV and XLSX](./customization.md#export), 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.

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 becomes about 20 KB in the file, 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 { DataTable } from "@adapttable/mantine";

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 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.

**`@adapttable/i18n` is deliberately the exception.** It is plain data and pure
functions — no hooks, no directive — so locale labels can be imported and
resolved in a server component and 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.
- **`urlAdapter`** defaults to the browser History API. On the server, pass
  `createMemoryAdapter(searchParamsString)` so the table restores state from
  the request's query string instead of reaching for a `window` that is not
  there.

```tsx
import { createMemoryAdapter } from "@adapttable/core";

const urlAdapter =
  typeof window === "undefined"
    ? createMemoryAdapter(searchParams.toString())
    : undefined; // the browser default
```

## 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.
- **URL-restored state** — sort, filters and page come from the query string.
  Give the server the same query string the browser has, through
  `createMemoryAdapter`, and both renders 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 query, absent when there was none              |
| `sort`           | the multi-sort chain, outermost first                        |
| `groupBy`        | the grouping column, when the schema allows it               |
| `filters`        | column filters, keyed by column                              |
| `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.

## 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`, `maxLimit`, `defaultLimit`,
`urlKey`. `ServerTableQuery` is the table above, where `filters` values are
`ServerFilterValue` (one string, or several for a checklist), `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),
`isFilterGroup` for walking a tree, and the types those speak in —
`QueryCondition`, `QueryFilterGroup`, `SortLevel`, `SortDirection`,
`PivotConfig`, `PivotMeasure` and `PivotUrlState`.

Every one of those names is also on `@adapttable/core`, from the same source
module. The narrow entry leaves out the hooks, which is what lets it carry no
`"use client"` boundary and no React import at all — so it loads in a process
that has never installed React, 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.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.
- 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`, 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`, `messages`, `draft`/`setDraft`, `send`, `stop`, `clear`,
the live `suggestions`, `runSuggestion`, `open`/`setOpen`
and `error`. 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`, `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, or `"sheet"` for a modal on a narrow viewport),
`labels`, `className`, `launcher` (set `false` when the host supplies its own
trigger — the toolbar button and the floating launcher drive ONE panel), and
`onSettings`. `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`, `Button`, `Composer` and `Badge`
(`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.

## 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.

`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()`, and — for a
governed write — the approved `plan` and the resolved `commit` mode.

### 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({ 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
useTableAssistant({
  approval: { policy: "writes", presentation: "widget" },
});
```

`approval: "writes"` still works and means the policy alone. The defaults are
`writes` and `widget`.

An action overrides either field on its own:

```ts
const actions: RowAction<Person>[] = [
  { key: "email", label: "Email", onClick: email },
  {
    key: "delete",
    label: "Delete",
    onClick: remove,
    // Always ask for this one, wherever the table reviews approvals.
    ai: { 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 actions as always-ask without repeating itself. An
absent `ai` object 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.

**`ai.approval` is not `confirm`.** `confirm` describes a person clicking the
action themselves and being asked whether they meant it. `ai.approval`
describes an agent asking to run it on their behalf. One agent execution
raises one prompt — the approval — not both.

The `ai` object carries overrides only. The action's key, label, handler and
disabled rules stay where they are; it is plain data, so a table with no
assistant carries no agent code because one of its actions mentions it.

### 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 { tableAgent, useTableAssistant } from "@adapttable/ai-react";
import { assistantHttpTransport } from "@adapttable/ai/http";
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 turn's receipts say what
actually happened — `applied`, `staged`, `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({ tableId, bridge, writePolicy, approval, commit, columns, readMax })`

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(),
    agentApproval(),
    tableAgent({
      tableId: "orders",
      writePolicy: "allow",
      approval: "writes",
      commit: "stage",
      bridge: {
        publish: (manifest) => sendToRuntime(manifest),
        attach: (session) => (runtime.session = session),
      },
    }),
  ]}
/>;
```

`writePolicy` is `"allow"` 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"`
(only `rows.delete`), or `"never"` (skip chrome and `onApprove`; still
validate and honour commit). Host `onApprove?: (proposal) => Promise<boolean>`
replaces the kit strip when it is set.

`commit` is `"stage"` (default — dirty/batch path; Save still belongs to
the reader) or `"immediate"` (invoke the host callback now).

`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.

`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: CapabilityKey[],
  columns: { id, label, type, readable, writable, sortable }[],
  rowAddressing: { scope: "visible" | "page" | "full", key: "rowKey" },
  limits: { pageMax: number, readMax: number },
  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`.

`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, result: { proposals, applied, approval, 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`). An action can
override either for itself.

`alwaysAllow` is a third, and it is off unless you name the keys:

```ts
tableAgent({
  tableId: "orders",
  approval: { policy: "writes", alwaysAllow: ["edit.cells"] },
});
```

The control appears only for a capability on that list. It never appears for a
destructive one, never for a write that enumerates rows, and never for an
action whose own configuration demands a human every time — and 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({ 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. None is in the root graph, and each routes every
call back through `session.execute`.

| 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, 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` and
`useTableAssistant`. 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://orwa-mahmoud.github.io/adapttable/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` is only for
`tableAgent`. The three integration 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 records a proposal in the host edit callback. Immediate persists
through that same callback. 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` (`args` is
a JSON string under `strict`). 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.

### 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.

### 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.

## 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/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://orwa-mahmoud.github.io/adapttable/demo/mantine/ai/)
defaults to **Simulated**: local scripted buttons, no credentials, no network
model call. Switch to **Connect backend**, paste an endpoint, and the same
`tableAgent` session sends the permitted context and executes the calls that come back.

A recorded walkthrough of this page will land here when it exists. Absence of
that video is not a missing feature.

`@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.

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.6 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 port, 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).** Hosted GitHub Pages 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 **Connect backend**. 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://orwa-mahmoud.github.io`, set
`AGENT_HTTP_TOKEN` and a non-loopback `AGENT_HOST`, then paste the public
URL and the same endpoint token into Connect backend. 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 a `complete({ system, user, signal })` that returns a JSON string,
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                                                                  |

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: "no-reader-channel"` and still says what already ran, and
a reader who declines reports `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. Send `profile: "compact"` and let discovery
do this; send `profile: "full"` when you would rather pay the bytes up front.

### Streaming

Ask for `text/event-stream` and 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 recognizer runs
locally and heard text becomes the composer's draft — never a send, so a
misheard word is a typo the reader corrects. In **backend** mode one clip is
recorded, released from the microphone on stop, and sent as `audio`; the
backend answers with a `transcript`, which the panel shows in place of the
reader's own bubble and sends as text on every later round of the turn.

### 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 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 (owner)

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. That live test is yours.

---

# Customize AdaptTable — slots, classNames, headless prop-getters

▶ **See it working:** [the unstyled adapter in the live demo](https://orwa-mahmoud.github.io/adapttable/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 colour and height are `rowStyle` / `rowHeight` — see
[row styling and heights](./row-styling.md).

## `classNames` — per-part styling

Restyle without replacing. Mantine and Chakra expose 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 full part map:

> **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 (`getCellSpan`). `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).                                           |
| `pageButton` / `pageEllipsis`  | Every pager button (prev/next + each numbered page; the current 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.                                                                                   |

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 still covers both states, exactly as before — but the
built-in clear-filters action goes with it, so give your replacement a way to
reset the query.

## Toolbar and status bar

`toolbar` has always filled 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 the same in every kit: `start` · Search · `toolbar` · Filters ·
Saved views · Columns · Undo/Redo · Export · Add · Print · Density ·
Fullscreen · `end` · Rows per page.

`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 and
`table.editHistory` are unchanged and stay the always-on path; this is 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, `exportCsv()` with `scope: "all"` on a page-scoped source,
edits with no writer) still show as `FeatureNotice` items
(`FeatureNoticeKind` is the union). They live on
`StatusBarChromeProps.notices` and `TableChrome.featureNotices`, and they
render even when `statusBar()` is off — row and selected counts still need
the bar.

`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 stays what it always was, 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
const highlight = useHighlight(true);

<DataTable
  rowClassName={(row) =>
    highlight.isRowHighlighted(row.id) ? "flash" : undefined
  }
  …
/>;

// after a save
highlight.flashRow(saved.id);
```

There is no new prop for this on purpose. `rowClassName` already reaches
every adapter, so the highlight is a class you compute — 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
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/core";

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/core";

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. If you portal your own, take
`shell.fullscreen.container` and use it while it is set.

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

```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 every action the table can perform. 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. Pass `shortcuts: []` to
bind nothing and open the palette from your own control instead.

Print lives here rather than in the toolbar: `printTable` opens a browser
dialog, so it is the host's call to make. Compose `print(onPrint)` and it becomes a
command; leave it out and it is not offered.

## Context menus

```tsx
import { contextMenu } from "@adapttable/mantine/context-menu";

<DataTable features={[contextMenu()]} … />;
```

Right-click a header and it offers that column's actions — sort, filter, pin,
hide. Right-click a cell and it offers copy and cut. 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 === "row"
          ? [{ 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"` — and MUI, Chakra, antd, and Radix offer an explicit `size` prop that
overrides the mapping (e.g. antd `size="large"`).

## 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. 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 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.

It is a **separate entry point** because a table that exports CSV should not
ship a ZIP encoder. Import it and you pay for it; do not and none of it reaches
your bundle. 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, BOM and `escapeFormulas`),
`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
`{ onExportCsv, exportBusy }` (typed `ExportHandlerState`), 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** — `size` (`"small" | "medium"`) overrides the density mapping;
  `className` lands on the root `<Paper>`.
- **Chakra** — `accentColor` colors primary accents (buttons, badges);
  `size` (`"sm" | "md" | "lg"`, default `"md"`).
- **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 i18n & RTL — Arabic, Hebrew, 18 locales

▶ **See it working:** [flip the whole table to Arabic RTL in the live demo](https://orwa-mahmoud.github.io/adapttable/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 { 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}
      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, and the column's declarative filter all
follow the resolved path, so searching and filtering 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.
- 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"`

## 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://orwa-mahmoud.github.io/adapttable/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://orwa-mahmoud.github.io/adapttable/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). Omit that prop and 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://orwa-mahmoud.github.io/adapttable/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. A 2026-08-26 run on this machine was
**13.5 s** full rebuild → **9.9 s** incremental (**1.4×**) for 200 updates
on 20,000 rows through the live Mantine table.

## Live patches over WebSocket or SSE

`@adapttable/core/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/core/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`, with `error` carrying the reason. `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. 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`. `openRowPatchStream` 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.

```tsx
import {
  useChangedCellFlash,
  useRowPatchStream,
} from "@adapttable/core/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). |

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()` 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.                                                                                                                      |
| `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). |
| `mobileIdentityColumns` | `number`                              | `3`     | Leading desktop-visible columns kept on mobile even if `hideOnMobile`.                                                                                    |

### 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### 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. |
| `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. 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.).                                                                                                                                                                     |
| `error`                     | `Error \| null`                                                 | `null`          | Forwarded error to display in the table's error state (retry via the source's `refetch`).                                                                                                                                         |
| `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/core/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.                                                                                                                                 |
| `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.                                                                                                                                                               |

### 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`; 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.
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`.

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.                                                                                                                                                                                                                 |
| `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`         | `"text" \| "number" \| { type: "select"; options }`  | `"text"`      | Widget for the active cell when `editable` is set.                                                                                                                                                                                                                       |
| `editValue`      | `(row: TRow) => string`                              | —             | Draft seed when display formatting differs from the value you want to edit.                                                                                                                                                                                              |
| `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) => ReactNode`     | —          | 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 the header filter row places this widget under, 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.                                                                                                |

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 (`FilterHeaderTrigger`) 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.                                                                                                                                                                      |
| `onQueryChange`             | `(query: TableQuery, info: { signal, key }) => void` | —              | 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.                                                                                                         |
| `closeHeaderFilterOnSelect` | `boolean`                                            | `false`        | all                                       | Close a header-filter overlay after a finished single-control write. Off by default so an operator pick on a multi-input field stays open.                                                                |
| `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`                                | —              | mantine, chakra, radix, base-ui, unstyled | Per-part class overrides — five parts on Mantine/Chakra/Radix/Base UI (`root`/`toolbar`/`table`/`card`/`footer`), every part on unstyled.                                                                 |
| `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, bootstrap   | 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/core`.

### 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)` reads a whole query string;
  `updateTableUrlState(search, patch)` 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`, `setSearch`, `setSort`, `toggleSortLevel`, `setExtra`,
  `setExtras`, `setFilterTree`, `setGroupBy`,
  `setGroupAggregateOverrides`, `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): { views, save, apply, remove }`
  — 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>` —
  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): UseColumnLayoutResult<TRow>` — headless
  visibility / order / pinning / width / name / collapsed-group state
  (`visibleColumns`, `toggleVisible`, `move`, `setPinned`, `setWidth`,
  `setName`, `resetName`, `pinOffset`, `reset`, `toggleColumnGroup`).
- `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.

### The builder tier

`@adapttable/react/adapter` publishes what the eight kits are made of, for
anyone wiring a ninth. 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.** `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 `rowActions`, 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.

**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/core/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
`<DataTable 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. On `<DataTable>` the prop is
`editHistory`. 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`; `<DataTable 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` as before and renders `model.columnSpacers` either side. On
`<DataTable>` the prop is `virtualizeColumns`. 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).
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. On
`<DataTable>` the prop is `findInTable`. 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. On `<DataTable>` the
prop is `selectionStats`. 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`.
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. `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/core/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/core/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/core/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.
`onPrint` on `<DataTable>` 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 export their kit-owned `StatusBar` 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) so a
silent no-op stays visible even when `statusBar` is off. 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`. `printButton` adds a
Print button, which renders only when `onPrint` is also wired;
`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`. The aggregate `useChromeBodyData` hook is gone;
choose `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. 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`.                                    |
| `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` / `extend` are deprecated — use `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;
- `virtualize` combined with `renderRowDetail` (detail panels are unmeasured sibling rows).

## 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)).

## 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)` 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)` 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)` 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 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.

**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(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.

## 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://orwa-mahmoud.github.io/adapttable/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 and a tunable
`mobileIdentityColumns` option so the most important columns remain visible.
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. Long infinite lists can opt into row/card virtualization with
Compose `virtualize()` 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` and `are-the-types-wrong`), 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 sets `sideEffects: false` 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-15 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) | ~24 kB    |
| every core export                          | ~56 kB    |
| `DataTable` from an adapter                | ~69–79 kB |

The first row is the one to read: a headless table costs about a fifth 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 holds
near-100% test coverage across every adapter.

## 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()`,
add/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 false                                                                                                                                          |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fullDataset` | The browser holds the current page. `rows.read` with `scope: "full"` is denied. Export-all needs a source-owned `allFilteredRows` route or `onExportAll`. |
| `grouping`    | `groupBy` is ignored and the status bar says why.                                                                                                         |
| `exportScope` | The Export control is 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 ~24 DOM rows and stays ~24 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).

## 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 item-1
  baseline. Omitted feature markers must be absent from the base graph.
- Optional features arrive with their import. `standardFeatures()`
  includes only factories that run with no required argument.
- `@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`. 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 every kit landing plus key feature pages
(`e2e/axe-audit.spec.ts`) and fails on serious or critical findings.

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/i18n` is the one package without `"use client"`.
[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, API key
  or chat UI. Core, every adapter root and `@adapttable/server` import
  none of those.
- 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/ai/src/session.ts` `readMaxOf`                                                                 |
| Virtualize DOM count                     | [virtualization](./virtualization.md)                                                                    |
| Export 50,000 cap                        | [exporting](./exporting.md) `EXPORT_FETCH_ALL_MAX_ROWS`                                                  |
| 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 anything that writes — paste, cut, fill — goes through editable columns and `onCellEdit`, the channel inline editing already uses. 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 69–79 kB min+gzip (measured
2026-09-15 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://orwa-mahmoud.github.io/adapttable/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://orwa-mahmoud.github.io/adapttable/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 `enableColumnMenu`, 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`      | Providing `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 }}`                  | `renderRowDetail`                                          | `(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 table-level `filters` prop.                                                     |

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` + `enableColumnMenu` | Per-layout hiding is a column flag; user toggling lives in the menu.      |
| `draggable` / `resizable`   | `enableColumnMenu` / `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 table-level `filters` prop.
- **`textAlign` values change.** `'left'`/`'right'` become the logical
  `'start'`/`'end'`, which flip correctly in RTL.

## 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://orwa-mahmoud.github.io/adapttable/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 + table `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`                               | —                                                             |
| `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 — where it hasn't changed since 1.0:

| 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://orwa-mahmoud.github.io/adapttable/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/core` 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

Headless core only, or core plus an adapter for ready UI:

```bash
# Headless (keep rendering your own markup, TanStack-style)
pnpm add @adapttable/core

# 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 })` 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` array                     | 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()`              | `renderRowDetail`                                               | Toggle UI is provided, not hand-added.                                   |
| `columnVisibility` / `columnOrder` / `columnPinning` state            | `enableColumnMenu` / `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`                             | URL sync is on by default; `savedViews` is opt-in (pass a `storageKey`). |

## 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/core`:
`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`.
- **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.

## 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` → `renderRowDetail`. 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://orwa-mahmoud.github.io/adapttable/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 v5 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 + table `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 via CSS. |
| `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 v5–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()`.** Pass actions to the factory for
  a toolbar button, or wire `rowsToCsv` / `downloadCsv` yourself via the
  `toolbar` slot; print is your app's concern.
- **`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://orwa-mahmoud.github.io/adapttable/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 v5 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`); there is no
  drag-a-column-to-group UI, so wire your own control to `groupBy` if you need
  that gesture.
- **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`, `className`, `Cell`         | 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://orwa-mahmoud.github.io/adapttable/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`       | `width`                                                         | —                                                  |
| `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(…)`              | `@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`       |
| `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.** 72 names that were re-exported from
`@adapttable/core` now live only on `@adapttable/react/adapter`. The builder
tier moved with the React binding, because everything in it renders:

```ts
// v2
import { headerGroupRows } from "@adapttable/core";
// v3
import { headerGroupRows } from "@adapttable/react/adapter";
```

Every moved name keeps the same spelling:

| Removed from `@adapttable/core` | 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 remain available from `@adapttable/core`.

**`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 React binding took the rest of the main entry with it — the hooks, the
React column and the prop-getters a host imports directly:

| Removed from `@adapttable/core`    | v3 import           |
| ---------------------------------- | ------------------- |
| `aggregate`                        | `@adapttable/react` |
| `AggregateOptions`                 | `@adapttable/react` |
| `Aggregator`                       | `@adapttable/react` |
| `BaseDataTableProps`               | `@adapttable/react` |
| `BulkAction`                       | `@adapttable/react` |
| `CellElementProps`                 | `@adapttable/react` |
| `ChromeBodyData`                   | `@adapttable/react` |
| `ColumnFooterContext`              | `@adapttable/react` |
| `ColumnGroupDef`                   | `@adapttable/react` |
| `ColumnGroupRecord`                | `@adapttable/react` |
| `ColumnHeaderController`           | `@adapttable/react` |
| `columnHeaderLabel`                | `@adapttable/react` |
| `ColumnReorderKeyProps`            | `@adapttable/react` |
| `ColumnResizeHandleProps`          | `@adapttable/react` |
| `ComputedColumnSpec`               | `@adapttable/react` |
| `CustomCellEditorRender`           | `@adapttable/react` |
| `EditableCellActivateControlProps` | `@adapttable/react` |
| `EditableCellControls`             | `@adapttable/react` |
| `EditableCellGate`                 | `@adapttable/react` |
| `EditableCellGateProps`            | `@adapttable/react` |
| `ExportContext`                    | `@adapttable/react` |
| `exportViewFromChrome`             | `@adapttable/react` |
| `ExtraRow`                         | `@adapttable/react` |
| `FeatureProps`                     | `@adapttable/react` |
| `FeatureProviderContribution`      | `@adapttable/react` |
| `FeatureProviderProps`             | `@adapttable/react` |
| `FeatureRender`                    | `@adapttable/react` |
| `FilterChromeMode`                 | `@adapttable/react` |
| `FilterTypeSpec`                   | `@adapttable/react` |
| `groupAggregateEntries`            | `@adapttable/react` |
| `GroupAggregatesFn`                | `@adapttable/react` |
| `GroupedFlatEntry`                 | `@adapttable/react` |
| `GroupingChipKeyboardProps`        | `@adapttable/react` |
| `GroupingDragProps`                | `@adapttable/react` |
| `GroupingDropProps`                | `@adapttable/react` |
| `GroupRowCell`                     | `@adapttable/react` |
| `groupRowLayout`                   | `@adapttable/react` |
| `HeaderFilterOpenProvider`         | `@adapttable/react` |
| `headerFilterStickTop`             | `@adapttable/react` |
| `IncrementalView`                  | `@adapttable/react` |
| `IncrementalViewConfig`            | `@adapttable/react` |
| `isDeclarativeFilters`             | `@adapttable/react` |
| `MobileCardField`                  | `@adapttable/react` |
| `MobileCardRenderer`               | `@adapttable/react` |
| `MultiSelectEditorCheckboxProps`   | `@adapttable/react` |
| `MultiSelectEditorChrome`          | `@adapttable/react` |
| `MultiSelectEditorChromeProps`     | `@adapttable/react` |
| `MultiSelectEditorSlots`           | `@adapttable/react` |
| `NestedTable`                      | `@adapttable/react` |
| `renderRegisteredFilter`           | `@adapttable/react` |
| `resolveColumnFooter`              | `@adapttable/react` |
| `resolveColumnHeader`              | `@adapttable/react` |
| `RowAction`                        | `@adapttable/react` |
| `RowActionsRenderer`               | `@adapttable/react` |
| `RowStyle`                         | `@adapttable/react` |
| `SidePanelEntry`                   | `@adapttable/react` |
| `Slot`                             | `@adapttable/react` |
| `TableChrome`                      | `@adapttable/react` |
| `TableExtraEntry`                  | `@adapttable/react` |
| `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`. The
release receipt is `scripts/v3-receipt.md`.

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 adapter-contract
imports move from `@adapttable/core` to `@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.

Item 16 extends the same command for the package split below: React hooks,
Chrome, and renderer types move from `@adapttable/core` to
`@adapttable/react`. Until that ships, the map is the contract — not a
runtime.

## v3 package split

v3's remaining foundation change: `@adapttable/core` becomes framework-neutral
and React moves to `@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

| Today's import                                     | After the split                                   | What moved                                          |
| -------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------- |
| `@adapttable/core` → `useDataTable`                | `@adapttable/react`                               | Headless React hook                                 |
| `@adapttable/core` → `ColumnDef`                   | `@adapttable/react`                               | React column (extends neutral `ColumnModel`)        |
| `@adapttable/core` → `TableSource`                 | `@adapttable/core`                                | Unchanged                                           |
| `@adapttable/core` → `useQuerySource`              | `@adapttable/react`                               | React source hook; query types stay on core         |
| `@adapttable/core` → `useTableChrome`              | `@adapttable/react`                               | Chrome binding                                      |
| `@adapttable/react/adapter` → `HeaderGroupCell`    | `@adapttable/react/adapter`                       | React adapter chrome                                |
| `@adapttable/react/adapter` → `sourceCapabilities` | `@adapttable/core` or `@adapttable/react/adapter` | Neutral helper stays in core                        |
| `@adapttable/react/features` → `grouping`          | `@adapttable/react/features`                      | Feature factory that returns a React `TableFeature` |
| `@adapttable/core/pivot` → `pivot`                 | `@adapttable/core/pivot`                          | Pure engine                                         |
| `@adapttable/core/pivot` → `usePivotUrlState`      | `@adapttable/react/pivot`                         | React hook                                          |
| `@adapttable/mui` → `DataTable`                    | `@adapttable/mui`                                 | Unchanged                                           |
| `@adapttable/ai` → `createAgentSession`            | `@adapttable/ai`                                  | Unchanged                                           |
| `@adapttable/ai/react` → `tableAgent`              | `@adapttable/ai-react`                            | React binding moved off `@adapttable/ai`            |
| `@adapttable/ai/http` → `createAgentHttpClient`    | `@adapttable/ai/http`                             | Unchanged                                           |

No public symbol is retired by this split. 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) — item 10 must make this typecheck and run:

```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 — today's `useDataTable` with the new specifier:

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

const columns: ColumnDef<Person>[] = [{ key: "name", header: "Name" }];
const table = useDataTable({ data: people, 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" });
```

These four snippets must keep agreeing with the frozen contracts in
ARCHITECTURE.md as items 10–15 land. They are examples, not published stubs.

---

# Migrating from v1 to v2

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`.** 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. Adapters, `@adapttable/i18n`
and `@adapttable/server` depend on a concrete `@adapttable/core` version at
publish time (exact pin), 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

AdaptTable is **stable at `3.0`**. The full SemVer contract above applies:
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`. 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–9 |
| `@adapttable/mui`                             | `@mui/material` 6.1.2+ – 9             |
| `@adapttable/chakra`                          | `@chakra-ui/react` 3                   |
| `@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/formula` | Formula columns (`buildFormulaColumns`, `FormulaValue`, …)                 |
| `@adapttable/core/pdf`     | Print / PDF writers and page layout (`PrintPageSize`, `PrintPageBreak`, …) |
| `@adapttable/core/pivot`   | Pivot engine (`pivot`, `pivotTableModel`, aggregators)                     |
| `@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.

### 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`). 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.

### `@adapttable/ai-react`

`tableAgent` and `useTableAssistant`. 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 init` binary, 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.

## 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.