# KanuniLabs documentation, full text

> Every guide page of the KanuniLabs PivotGrid and DataGrid documentation, as Markdown, in the order of the documentation sidebar. The API reference is not included; https://kanunilabs.com/llms.txt links to it.

---

Source: https://kanunilabs.com/docs/pivotgrid

# PivotGrid: Introduction

A fast, framework-agnostic PivotGrid for the web.

Read it at https://kanunilabs.com/docs/pivotgrid

---

Source: https://kanunilabs.com/docs/pivotgrid/installation

# Installation

Install the React bindings (the framework-agnostic core is pulled in automatically):

```bash
npm i @kanunilabs/pivotgrid-react
```

(Any package manager works — `yarn add` / `pnpm add` too.)

The React package declares its UI libraries as peer dependencies. npm 7+ installs
these automatically; if your setup doesn't, add the ones your app doesn't already have:

```bash
npm i @dnd-kit/core lucide-react zustand
```

**Not using React?** `@kanunilabs/pivotgrid` is the same grid over the same
engine, driven by a plain `createPivotGrid()` call — no framework peer at all
(`@dnd-kit`, `lucide-react` and `zustand` are not needed). The
[JavaScript guide](https://kanunilabs.com/docs/pivotgrid/javascript) covers it end to end, including
the Enterprise edition via `createEnterprisePivotGrid()`.

```bash
npm i @kanunilabs/pivotgrid
```

## Styles

Import the stylesheet once, near your app root:

```ts
import '@kanunilabs/pivotgrid-react/styles.css';
```

The JavaScript package ships the same stylesheet as `@kanunilabs/pivotgrid/styles.css`.

## The Web Worker: nothing to configure

The engine runs its aggregation in a Web Worker, and the worker is compiled into
the package and started from a Blob URL. There is no file to copy, no bundler
recipe and nothing to import — Vite, webpack, Next.js and Parcel all work as
they are. The same is true of the import and export workers.

### If you have a strict Content-Security-Policy

A Blob worker needs `worker-src` to allow `blob:`:

```
Content-Security-Policy: worker-src 'self' blob:
```

If you cannot change the policy, the grid falls back to loading the worker file
from `node_modules` on its own — and where that fails too, point `workerUrl` at
a copy you serve. The file ships in the package either way.

**Vite** — import the worker as an asset URL:

```jsx
import workerUrl from '@kanunilabs/pivotgrid-core/dist/pivot.worker.js?url';

<BasePivotGrid workerUrl={workerUrl} /* ... */ />
```

**Next.js and other bundlers** — copy `pivot.worker.js` from
`node_modules/@kanunilabs/pivotgrid-core/dist/` into a served path (e.g.
`public/`) and point at it:

```jsx
<BasePivotGrid workerUrl="/pivot.worker.js" /* ... */ />
```

The same route is worth taking if you would rather serve the worker from a CDN,
so it caches separately from your app bundle.

## TypeScript

Types ship with the packages — no `@types/*` needed. The public API is fully typed,
including `PivotField`, `PivotLocale`, and the component props.

Next: [render your first grid](https://kanunilabs.com/docs/pivotgrid/react).

---

Source: https://kanunilabs.com/docs/pivotgrid/nextjs

# Next.js setup

The grid renders on the client and uses a Web Worker. Since the worker is
compiled into the package, there is now exactly **one** step.

## Render client-side

The grid touches browser APIs, so load it without SSR:

```tsx
'use client';
import dynamic from 'next/dynamic';

const Grid = dynamic(() => import('./MyGrid'), { ssr: false });
```

That is the whole setup:

```tsx
<BasePivotGrid gridId="demo" data={data} initialFields={fields} />
```

## What happened to the copy-worker step?

It is gone. Next's bundler cannot statically resolve a worker URL inside
`node_modules`, so this page used to ask you to copy `pivot.worker.js` into
`public/` and pass `workerUrl`. The worker is now embedded in the package and
started from a Blob URL, which no bundler has to resolve — so the script, the
`predev`/`prebuild` hook and the prop all disappear.

Existing `workerUrl` code keeps working and still wins when it is set: it is the
right answer for a Content-Security-Policy without `worker-src blob:`, or when
you would rather serve the worker from a CDN. See
[Installation](https://kanunilabs.com/docs/pivotgrid/installation#if-you-have-a-strict-content-security-policy).

See it working in the [playground](https://kanunilabs.com/playground).

---

Source: https://kanunilabs.com/docs/pivotgrid/browser-support

# Supported browsers

The PivotGrid targets the current versions of the evergreen browsers:
**Chrome, Edge, Firefox and Safari**. Internet Explorer and the original,
pre-Chromium Edge are not supported: the packages are compiled to modern
JavaScript (ES2022 and later) and ship no polyfills.

This applies to every PivotGrid package: React and plain JavaScript, Community
and Enterprise, the npm builds and the `<script>` tag builds.

## Oldest browser versions

| Browser | Oldest version | Set by |
| --- | --- | --- |
| Chrome, Edge | 112 | CSS nesting in the stylesheet |
| Firefox | 117 | CSS nesting in the stylesheet |
| Safari (macOS and iOS) | 16.5 | CSS nesting in the stylesheet |

Part of the stylesheet is compiled with Tailwind CSS, whose output nests some
hover and focus styles inside their rules. Without nesting those styles are
dropped; the next limits down are the engine's module worker (Firefox 114) and
`color-mix()` (Chrome and Edge 111, Firefox 113, Safari 16.2).

**Import from Clipboard** reads the clipboard with
`navigator.clipboard.readText()`, which Firefox has from version 125.

These numbers come from the code, not from a test run on those versions. Each
one is the first release of that browser that supports every feature the
shipped packages use, according to MDN's browser compatibility data. An older
release is missing at least one of them.

## What the grid needs from the browser

Required:

| Feature | What it is for |
| --- | --- |
| Modern JavaScript (ES2022 and later) | Everything. Without it the script does not load. |
| Web Worker (module type) | The pivot engine. Aggregation always runs in a worker; there is no main-thread fallback, so without a worker the grid cannot compute. Import and export use workers too. |
| `color-mix()` in CSS | Tints: selected and focused cells, total and subtotal rows, field chips and drop zones. Without it those tints are not drawn. |
| CSS nesting | Some hover and focus styles. Without it those styles are dropped. |
| `ResizeObserver` | Measuring the grid, and keeping the row and column headers aligned with the body as it resizes. |
| `Intl` | Number and date formatting, and locale-aware sorting. |

Used when available:

| Feature | What it is for | When it is missing |
| --- | --- | --- |
| Blob URLs | Starting the workers from code embedded in the package, so there is no file to copy. | The grid loads the worker file that ships next to the package instead; see [Content-Security-Policy](#content-security-policy). |
| Clipboard API (`navigator.clipboard`) | Copying selected cells (Ctrl+C or Cmd+C), **Copy to Clipboard** in the export menu, and **Import from Clipboard**. | Browsers offer it only on secure pages (HTTPS or `localhost`). On a plain-HTTP page, copying a selection does nothing and the import reports that the clipboard could not be read. The export falls back to the browser's older copy command. |
| `localStorage` / `sessionStorage` | Remembering the user's layout between visits. | Where storage is unavailable, such as some private browsing modes, the layout is not remembered. |
| `crypto.subtle` (Enterprise) | Verifying the licence key. | Browsers offer it only on secure pages. Elsewhere a bundled JavaScript verifier checks the same signature; see [Enterprise & licensing](https://kanunilabs.com/docs/pivotgrid/enterprise#license-key). |

## Content-Security-Policy

- The shipped JavaScript has no `eval` and no `new Function` — calculated
  fields included — so a `script-src` without `'unsafe-eval'` works.
- The workers start from a `blob:` URL. Allow it with `worker-src 'self' blob:`.
  If the policy refuses it, the grid tries the worker file next to the package;
  where that fails too, pass `workerUrl`.
  [Installation](https://kanunilabs.com/docs/pivotgrid/installation#if-you-have-a-strict-content-security-policy)
  shows how.
- The licence check is the shared `@kanunilabs/licensing` package. Its
  real-browser test, described below, runs under this policy:

```
default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
img-src 'self' data:; connect-src 'self'; worker-src 'self' blob:
```

That policy allows inline styles. A policy without `'unsafe-inline'` in
`style-src` has not been tested.

## What is tested

**Unit tests** run in Node in continuous integration, on every push and pull
request to the main branch. Tests that need a DOM use jsdom, a simulated DOM.
jsdom does no layout and no painting, so these tests prove behaviour, not how a
particular browser draws the grid.

**In a real browser:** licence verification. A script drives an installed
Google Chrome against the built packages, on a plain-HTTP page (no
`crypto.subtle`, so the bundled JavaScript verifier runs) and on a secure page
(WebCrypto), through the npm (ESM) build and the `<script>` tag (UMD) build,
under the policy above. It loads the licence check through the DataGrid
Enterprise packages; PivotGrid Enterprise uses the same `@kanunilabs/licensing`
package. This test runs outside continuous integration.

Firefox and Safari are not part of an automated run. If the grid misbehaves in
a browser at or above the versions listed here, [tell us](https://kanunilabs.com/contact) the browser,
its version and what you saw.

---

Source: https://kanunilabs.com/docs/pivotgrid/upgrading

# Upgrading

## How versions are numbered

- **Patch** (1.7.1 → 1.7.2): fixes.
- **Minor** (1.7.2 → 1.8.0): new features, plus fixes. A fix can change what
  your app sees — a custom summary that now runs, column subtotals that are now
  on by default. Every such change is listed below, under the version that made
  it.
- **Major**: none so far.

The packages of one product do not always share a number: in a release, each
package moves by what changed in it. The [changelog](https://kanunilabs.com/changelog) lists the
exact number of every package in each release.

## Upgrade the packages together

The Enterprise packages depend on an **exact** version of the Community ones.
Upgrade every `@kanunilabs/pivotgrid*` package your app lists in the same
command, to the set one release shipped:

```bash
npm i @kanunilabs/pivotgrid-react@latest @kanunilabs/pivotgrid-react-enterprise@latest
```

Upgrading only one of them can install a second copy of the engine next to the
first. Two copies do not share state: a licence key set through one is not seen
by the other. Check that one version is installed:

```bash
npm ls @kanunilabs/pivotgrid-core
```

One version in the tree is right; two mean a package was left behind.

## What changes for you

The changes below can make an existing app behave or type-check differently
after an upgrade. Versions not listed asked nothing of you. Going from an older
version to the newest, read every entry in between.

(This part is generated when the page renders. See it at https://kanunilabs.com/docs/pivotgrid/upgrading)

---

Source: https://kanunilabs.com/docs/pivotgrid/ai-assistants

# AI coding assistants

An assistant writing PivotGrid code from memory guesses prop names, and a prop
that does not exist does nothing: no error, no effect. Two things let it look
the names up instead:

- **The MCP server** `@kanunilabs/mcp`: the documentation and the full API
  reference, searchable by the assistant while it works.
- **The skill**: one instruction file the assistant reads when a task involves
  the grid — which package to install, the licence key, the worker, Next.js,
  upgrading.

Neither runs an AI model or calls one. The server runs on your machine and
makes no network requests: the docs are inside the package.

## The MCP server

It covers PivotGrid and [DataGrid](https://kanunilabs.com/docs/datagrid/ai-assistants) both, and
carries the docs of the release it was published with.

| Tool | What the assistant gets |
|---|---|
| `search_docs` | Guide sections and API members matching a question in words |
| `get_doc` | One page, or one section of it, as Markdown |
| `get_api` | One exported symbol, or one member: `PivotLayoutState.showColumnTotals` |
| `list_docs` | The packages with their versions, the guides, the exported symbols |
| `get_changes` | What changed between two versions, upgrade notes first |

### Claude Code

```bash
claude mcp add kanunilabs -- npx -y @kanunilabs/mcp
```

On Windows outside WSL, `npx` needs a `cmd /c` in front:

```bash
claude mcp add kanunilabs -- cmd /c npx -y @kanunilabs/mcp
```

### Cursor

Add to `.cursor/mcp.json` in the project, or to `~/.cursor/mcp.json` for every
project:

```json
{
  "mcpServers": {
    "kanunilabs": { "command": "npx", "args": ["-y", "@kanunilabs/mcp"] }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "kanunilabs": { "type": "stdio", "command": "npx", "args": ["-y", "@kanunilabs/mcp"] }
  }
}
```

### Other assistants

Any MCP client that starts a local (stdio) server works: the command is `npx`
and the arguments are `-y @kanunilabs/mcp`.

To check it is connected, ask the assistant something only the reference
knows, such as which members `PivotLayoutState` has.

## The skill

```bash
npx -y @kanunilabs/mcp install-skill
```

This writes `.claude/skills/kanunilabs-grids/SKILL.md`, where Claude Code finds
skills. For an assistant that reads skills from another folder, name it:

```bash
npx -y @kanunilabs/mcp install-skill path/to/skills/kanunilabs-grids
```

A changed copy is not overwritten; run it with `--force` to replace your copy
with the one in the package. The skill tells the assistant to use the MCP
server when it is connected, and the files below when it is not.

## Without either

The same documentation is published for assistants that read the web:

- [/llms.txt](https://kanunilabs.com/llms.txt): every page with one line on what it covers
- [/llms-full.txt](https://kanunilabs.com/llms-full.txt): every guide in one Markdown file

---

Source: https://kanunilabs.com/docs/pivotgrid/react

# Quick start (React)

Define your data, describe the fields, and render `BasePivotGrid`.

```tsx
import { BasePivotGrid, type PivotField } from '@kanunilabs/pivotgrid-react';
import '@kanunilabs/pivotgrid-react/styles.css';

const data = [
  { region: 'EMEA', quarter: 'Q1', revenue: 1200 },
  { region: 'EMEA', quarter: 'Q2', revenue: 980 },
  { region: 'APAC', quarter: 'Q1', revenue: 1500 },
];

const fields: PivotField<(typeof data)[number]>[] = [
  { id: 'region', dataField: 'region', caption: 'Region', dataType: 'string', area: 'row' },
  { id: 'quarter', dataField: 'quarter', caption: 'Quarter', dataType: 'string', area: 'column' },
  { id: 'revenue', dataField: 'revenue', caption: 'Revenue', dataType: 'number', area: 'data', summaryType: 'sum' },
];

export function MyGrid() {
  return <BasePivotGrid gridId="demo" data={data} initialFields={fields} />;
}
```

The grid fills the element you put it in. Give that element a height (say
`500px`, or a flex slot) to get a fixed-size grid that scrolls inside; without
one, the grid is as tall as its content. It never draws outside its container.

## Fields

Each field declares where it lives (`area`: `'row' | 'column' | 'data' | 'filter'`),
its `dataType`, and — for measures — a `summaryType` (`sum`, `count`, `avg`, `min`,
`max`). Numbers accept an Intl `format`:

```tsx
{
  id: 'revenue',
  dataField: 'revenue',
  caption: 'Revenue',
  dataType: 'number',
  area: 'data',
  summaryType: 'sum',
  format: { style: 'currency', currency: 'USD', maximumFractionDigits: 0 },
}
```

## Localization

Pass a `locale` (one of 12) and the grid translates its chrome; `ar` switches to RTL.

```tsx
<BasePivotGrid gridId="demo" data={data} initialFields={fields} locale="tr" />
```

> Using Next.js? See [Next.js setup](https://kanunilabs.com/docs/pivotgrid/nextjs) for the one extra step the bundler needs.

For the complete prop and type list, see the [API Reference](https://kanunilabs.com/docs/pivotgrid/api).

---

Source: https://kanunilabs.com/docs/pivotgrid/javascript

# JavaScript

The PivotGrid does not need React. `@kanunilabs/pivotgrid` is a second renderer
over the **same engine** (`@kanunilabs/pivotgrid-core`) and the **same
stylesheet** — aggregation in the Web Worker, drag-and-drop between areas,
filters, sorting, expand/collapse, saved layouts and theming behave
identically, and a parity ledger checked in CI records, surface by surface,
where the two renderers agree and where they deliberately do not.

```bash
npm i @kanunilabs/pivotgrid
```

## A pivot in one call

```ts
import { createPivotGrid, type PivotField } from '@kanunilabs/pivotgrid';
import '@kanunilabs/pivotgrid/styles.css';
import '@kanunilabs/pivotgrid/themes/graphite.css'; // optional: one of 36 colour schemes

const data = [
  { region: 'EMEA', quarter: 'Q1', revenue: 1200 },
  { region: 'EMEA', quarter: 'Q2', revenue: 980 },
  { region: 'APAC', quarter: 'Q1', revenue: 1500 },
];

const fields: PivotField<(typeof data)[number]>[] = [
  { id: 'region', dataField: 'region', caption: 'Region', dataType: 'string', area: 'row' },
  { id: 'quarter', dataField: 'quarter', caption: 'Quarter', dataType: 'string', area: 'column' },
  { id: 'revenue', dataField: 'revenue', caption: 'Revenue', dataType: 'number', area: 'data', summaryType: 'sum' },
];

const grid = createPivotGrid(document.getElementById('host'), {
  gridId: 'sales',
  data,
  initialFields: fields,
  locale: 'tr',            // one of 12; 'ar' switches to RTL
  theme: { id: 'graphite' }, // the scheme imported above
  density: 'compact',      // 24px rows; 'normal' (28) is the default
});

grid.setData(nextRows);          // replace every row
grid.applyTransaction({ add: [row] }); // or change a few (Features guide → Live updates)
grid.applyTransactionAsync({ update: [tick] }); // a fast feed: queued, applied together
grid.setLocale('de');            // relabels chrome, chart axes and dialogs
grid.setDensity('comfortable');  // 36px rows, repainted in place
grid.controller.expandAll();     // the engine, directly
grid.destroy();                  // when the host goes away
```

The same `data` and `fields` as the [React quick start](https://kanunilabs.com/docs/pivotgrid/react)
— the field vocabulary (`area`, `dataType`, `summaryType`, `format`,
`groupInterval`) is core's, not the renderer's, so it is identical in both.

The **config mirrors the React props**. Everything `BasePivotGrid` takes as a
prop, `createPivotGrid` takes as a key: `layout`, `stateStoring`, `toolbar`,
`theme`, `striped`, `density`, `defaultColumnWidths`, `dictionary`, `rtl`, `workerUrl`,
`keyboardNavigation`, `disabled`,
and the event callbacks (`onCellClick`, `onFieldsChange`, `onLayoutChange`,
`onExporting`, `onError`, …). One difference in the shape of one payload:
`onCellClick` receives the **native** `MouseEvent`, where React hands you a
synthetic one.

The overlap is not total, and the renderer tells you where it ends rather than
letting you guess: **pass a React-only option and it says so in the console**,
naming what to write instead. The React-only keys are the three render slots
(`renderCalculatedFieldModal`, `renderPrefilterBuilder`,
`renderNodeContextMenu`), `onOpenFullScreenChart` (deprecated in React too),
`children` and `ref`. Each has a plain-callback or Enterprise-package
counterpart, and the warning names it.

`grid.controller` is the engine itself — the same `PivotController` the React
binding exposes. Everything imperative (fields, layout, filters, expansion,
export, the cell-click resolver) lives there; see the
[API reference](https://kanunilabs.com/docs/pivotgrid/api). The JavaScript surface itself —
[createPivotGrid](https://kanunilabs.com/docs/pivotgrid/api/javascript/functions/createPivotGrid)
and [PivotGridVanillaConfig](https://kanunilabs.com/docs/pivotgrid/api/javascript/interfaces/PivotGridVanillaConfig)
— has its own generated pages.

### Three differences worth knowing

- **Row headers are sticky, not a second table.** One scroll container; the
  row-header cells pin themselves with computed insets, and their widths are
  budgeted against the viewport so the data never disappears behind them. A
  dragged row-header width is stored as the *configured* width, so a saved
  layout means the same thing at any window size.
- **Sockets, not render props.** Where React takes `renderCalculatedFieldModal`,
  vanilla exposes `onAddCalculatedField` / `onEditCalculatedField`,
  `onOpenPrefilter` and `onToggleChart`. When a callback is present the footer
  draws the matching button; absent, nothing is drawn. The Enterprise package
  fills all four — an app may fill any.
- **Charts are a subscription.** `createChartSync(controller, getLocale,
  options, onSync)` is the React hook `usePivotChartSync` as a plain
  subscription: 150 ms after the result, the expansion set or the locale
  changes, your transformer runs. The Community bridge ships no transformer;
  the Enterprise package does.

## Script tag (UMD)

No bundler? The package ships a self-contained build:

```html
<link rel="stylesheet" href="https://unpkg.com/@kanunilabs/pivotgrid/dist/styles.css" />
<script src="https://unpkg.com/@kanunilabs/pivotgrid/dist/pivotgrid.umd.js"></script>
<script>
  const { createPivotGrid } = KanuniLabsPivotGrid;
  createPivotGrid(document.getElementById('host'), { /* the same config */ });
</script>
```

The engine and its Web Worker are bundled in — the worker starts from a Blob
URL, so there is no file to serve. If a strict Content-Security-Policy blocks
`blob:` workers, pass `workerUrl` as described under
[Installation](https://kanunilabs.com/docs/pivotgrid/installation#if-you-have-a-strict-content-security-policy).

## Enterprise edition

`@kanunilabs/pivotgrid-enterprise` wraps the Community renderer — it does not
fork it — and fills the sockets it opens: the no-code calculated-field
designer, the visual prefilter builder, the drill-down modal, an eight-type
chart panel and styled Excel & PDF export. It is installed from the
[private registry](https://kanunilabs.com/docs/pivotgrid/registry) with your licence.

```ts
import { createEnterprisePivotGrid } from '@kanunilabs/pivotgrid-enterprise';
import '@kanunilabs/pivotgrid/styles.css';   // no separate Enterprise stylesheet

const grid = createEnterprisePivotGrid(host, {
  licenseKey: 'KLAB1.…',
  // everything createPivotGrid takes, plus — all default ON:
  calculatedFields: true,   // footer calculator → the designer
  prefilter: true,          // footer filter → the AND/OR builder
  drillDown: true,          // click a value cell → the source rows
  charts: true,             // footer chart button → the panel, hidden until pressed
  chartType: 'column',
  chartStacking: 'grouped', // or 'stacked' | 'normalized' (100%)
  chartFormat: { title: 'Revenue', legend: 'bottom', dataLabels: true },
  onChartFormatChange: (format) => save(format),
  chartFloating: false,     // true (or { x, y, width, height }) opens it as a window
  drillDownPageSize: 50,
  data,
  initialFields: fields,
});

grid.openCalculatedFieldDesigner();          // or (fieldId) to edit one
grid.openPrefilterBuilder();
grid.openDrillDown({ records, rowPath: ['EMEA'] });
grid.toggleChart();
grid.setChartType('pie');
grid.setChartStacking('stacked');
grid.setChartFormat({ title: 'Q3', valueAxisTitle: 'Revenue' });
grid.isEnterpriseLicensed();
```

Without a valid key the grid **still works**, watermarked — your app never
breaks on a licensing problem. One licence key opens both Enterprise packages,
React and plain JavaScript alike; see
[Enterprise & licensing](https://kanunilabs.com/docs/pivotgrid/enterprise).

`drillDown` **chains** your own `onCellClick` rather than replacing it: your
handler runs first and sees every click, whether or not a modal follows. Pass
`drillDown: false` to keep the click for yourself and call `openDrillDown` when
you want the dialog.

### Charts without a charting library

The chart panel draws its types — column, bar, line, area, pie, donut,
dot plot, scatter, bubble, radar, combination, waterfall, funnel, treemap,
heatmap, range, sunburst and histogram — as SVG the package writes itself, and
downloads the chart as PNG or SVG with its title. The histogram counts the
categories in each band of the first visible measure; a picker beside it asks
for about 5, 10, 20 or 50 bands of one round width, and the choice is kept in
the chart's state (`bins`, absent at the default 10).
Scatter and bubble put one point per category at (first measure, second
measure); the bubble's size is the third measure. There is no charting
dependency, for a reason that decided itself: a library marked *external*
survives into the script-tag bundle as a bare `import('…')` that a classic
script cannot resolve, and a second `<script>` tag defines a global that a
dynamic import never looks at. Bundling a library would have added it to every
customer's page; leaving it out would have made charts unreachable from the one
delivery path this package exists for.

With two or more series, column, bar, line and area charts offer a grouped,
stacked or 100% stacked layout in the panel's toolbar. A 100% chart reads its
axis in percent, and its tooltip shows the real value with the share beside it.
The **Format** button sets a title, axis titles, the legend position, data
labels and a linear or logarithmic value scale. Values print with the measure's own `format`.

The panel also carries what the React chart never had: axis captions in the
grid's locale (so the axis agrees with the cells above it), a note whenever
`maxPoints` or `maxSeries` dropped data, and a visually-hidden data table so a
screen reader gets the numbers, not just "graphic".

The chart is plain data too. `grid.getChartState()` returns whether the panel
is open, the type, the stacking, the format and the series hidden in the legend
(by series key — the layout decides the series, so a position would name a
different one next time); `grid.setChartState(state)` restores it. A **saved
report keeps the chart** (`parts.chart`), so loading the report brings it back,
the default report included. The controller reports the panel:

```js
grid.controller.on('chartOpened', ({ state }) => {});
grid.controller.on('chartChanged', ({ state, changes }) => {}); // 'type' | 'stacking' | 'format' | 'hiddenSeries' | 'placement'
grid.controller.on('chartClosed', ({ state }) => {});
```

**Pop out** in the panel's toolbar lifts the chart off its dock and lays it over
the pivot as a window: drag its toolbar to move it, its bottom-right corner to
resize it, or use the arrow keys on its two grips (10px a press, 50px with
Shift). It stays inside the grid, and **Dock** puts it back. The window's
rectangle is part of the chart state (`floating: { x, y, width, height }`, no
`floating` key while docked), so a saved report brings it back where it was.

**Swap category and series** turns the drawn chart around — each series (a
column path and measure of the pivot) becomes a category and each row a series —
with the same numbers; press it again to swap back. At most 20 rows become
series. The swap is part of the chart state (`switched: true`) and of saved
reports. While swapped a click filters nothing, since the categories are no
longer rows. (`chartIntegrationOptions.inverted` is a different, code-only
choice: it builds the chart from the pivot's column fields instead of its row
fields.)

**Unlink** freezes the chart: new pivot results (a filter, an expanded row,
new data) are kept aside and the chart keeps what it shows; **Link** draws the
latest. The state has `unlinked: true` while it is; a report restored unlinked
takes the pivot's first result and keeps it.

**New window** draws the same pivot in another window of its own — a copy of
the chart that you can switch to another type, stacking or format while the
first stays as it was. The windows are numbered ("Chart 2"…), their events
carry that number as `chartId`, and a saved report keeps them
(`parts.chart.windows`). From code:

```js
const win = grid.openChartWindow({ type: 'pie' });  // a copy of the panel's chart, as a pie
grid.getChartWindows();                              // the windows open now
win.update({ stacking: 'stacked' });
win.close();
grid.controller.on('chartOpened', ({ chartId }) => {}); // 'chart-2'…, none for the panel
```

The series colours follow the grid's theme: the first series is the theme's
accent (`--pivot-primary`) and the rest are derived from it, the way the
DataGrid chart colours itself, dark themes included. `chartColors` takes a
list of your own, or `'fixed'` for the packaged eight; with your own
`chartIntegrationOptions.transformer`, its colours are kept unless you set
`chartColors`.

With `chartCrossFilter: true`, a click on a category (a bar, a slice, a cell)
filters the pivot to it — every row field of the category, so "EMEA - Q1"
keeps EMEA and Q1. A note under the chart says so and has a Clear button; the
same click again clears it too, and the fields get back the filters they had
before. Off by default: a chart that changes the grid when clicked is a
surprise unless you asked for it.

From the keyboard the chart is then one tab stop: the arrow keys (and
<kbd>Home</kbd> / <kbd>End</kbd>) move a focused category, named in a chip at
the top of the chart (a live region, so a screen reader says it too) and
outlined on the chart; <kbd>Enter</kbd> or <kbd>Space</kbd> does what the
click does. The focus stays on the category when the filter narrows the chart
to it, and the chip then adds that it is filtering the pivot.

`grid.downloadChart({ format: 'jpeg', width: 1200 })` saves the chart in the
format and size you choose (`'png'`, `'jpeg'` or `'svg'`), and
`grid.getChartImageDataUrl(options)` hands it back as a `data:` URL instead —
to keep with a report or send to a server. One side keeps the chart's
proportions; both centre it in the box you give.

### Excel and PDF from a script tag

The export peers are optional and never bundled. A bundler resolves them the
usual way; a script-tag page provides them as **globals**, which is what their
own UMD builds define:

```html
<script src="https://cdn.jsdelivr.net/npm/exceljs@4.4.0/dist/exceljs.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/jspdf@4.2.1/dist/jspdf.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/jspdf-autotable@5.0.8/dist/jspdf.plugin.autotable.js"></script>
<script src="https://unpkg.com/@kanunilabs/pivotgrid-enterprise/dist/pivotgrid-enterprise.umd.js"></script>
```

The package looks for `globalThis.ExcelJS` and `globalThis.jspdf` first and
falls back to `import()` — a page that loads the tags in any order works, and a
click that lands before a tag has loaded is not remembered as a failure. If a
peer is nowhere, the export does nothing and the console says which tag to add.
A missing peer never throws into your click handler.

The Enterprise UMD bundles the Community renderer and the licensing core
(global `KanuniLabsPivotGridEnterprise`), so one stylesheet and one script tag
are enough.

### Where it stops

The [Enterprise parity ledger](https://kanunilabs.com/docs/pivotgrid/api/javascript-enterprise/variables/ENTERPRISE_PARITY_LEDGER)
grades every paid surface against the React edition and is exported from the
package, so the limits below are checked, not remembered:

- **PDF has no embedded Unicode font** (shared with React). Labels the built-in
  font cannot draw fall back to English rather than rendering as glyph soup;
  cell text outside Latin-1 is a known limit.
- **Very large pivots export as SpreadsheetML (`.xls`)**, above 150,000 engine
  cells, and that path carries no conditional formatting, freeze pane or
  outline levels (shared with React). Unlike React, the console says so when
  the switch happens.
- **Chart series colours follow the theme by default here**, React's
  `ChartFactory` only with `palette="theme"`; the chrome — axes, gridlines,
  labels — follows it in both.
- **A prefilter on a date field with a `groupInterval`** compares the group key,
  not the date, in both editions. The builder therefore offers such a field a
  text box and no ordering operators, so what you type is what is compared.

## What is the same, what is different

| | React | JavaScript |
| --- | --- | --- |
| Engine, stylesheet, themes, worker | shared | shared |
| Config / props | `<BasePivotGrid {...props} />` | `createPivotGrid(host, props)` |
| Enterprise surfaces | render props | plain callbacks (sockets) |
| Cell click payload | synthetic event | native `MouseEvent` |
| Imperative API | `ref` → controller | `grid.controller` |
| Charts | `usePivotChartSync` + recharts | `createChartSync` + built-in SVG panel |
| Server-side rendering | renders markup | constructs on mount (needs a `document`) |
| Enterprise | `<EnterprisePivotGrid>` | `createEnterprisePivotGrid()` |

SSR is the one honest difference: the JavaScript renderer produces DOM, so it is
created when the host element exists. Everything else is held to parity by the
ledgers and conformance suites that run on every commit.

---

Source: https://kanunilabs.com/docs/pivotgrid/features

# Features guide

Everything below is available in the **free** `@kanunilabs/pivotgrid-react`
and `@kanunilabs/pivotgrid` packages unless a section is explicitly marked
**Enterprise**. Each feature is
driven by props or per-field configuration — no imperative setup required.

Most features are configured on the `PivotField` objects you pass to
`initialFields` (or the controlled `fields` prop), or on the `layout`,
`stateStoring`, `theme` and `toolbar` props of `BasePivotGrid`.

## Aggregation

Every measure (a field in the `data` area) declares a `summaryType`:

```tsx
{ id: 'revenue', dataField: 'revenue', caption: 'Revenue', dataType: 'number',
  area: 'data', summaryType: 'sum' }
```

Supported: `sum`, `count`, `avg`, `min`, `max`, `distinct` (distinct count) and
`custom`. The built-in summaries run in the Web Worker, off the main thread.

### Custom summaries

For bespoke rollups, provide `calculateCustomSummary` (start → calculate →
finalize), the same three-phase model used by classic pivot engines. It runs
once per cell, subtotals and grand totals included, over that cell's own rows:

```tsx
{ id: 'priceRange', dataField: 'price', caption: 'Price Range', dataType: 'number',
  area: 'data', summaryType: 'custom',
  calculateCustomSummary: (o) => {
    if (o.summaryProcess === 'start') { o.lo = Infinity; o.hi = -Infinity; }
    if (o.summaryProcess === 'calculate') {
      o.lo = Math.min(o.lo, o.value);
      o.hi = Math.max(o.hi, o.value);
    }
    if (o.summaryProcess === 'finalize') o.totalValue = o.hi - o.lo;
  } }
```

Rows arrive in source order, and anything you store on the options object
stays there between phases. The worker groups the rows; your function runs on
the main thread, because a function cannot be sent to a worker.

To reuse one summary across fields, register it and refer to it by name. The
function receives the cell's values:

```tsx
import { PivotEngineRegistry } from '@kanunilabs/pivotgrid-core';

const registry = new PivotEngineRegistry();
registry.registerAggregator('median', (values) => {
  const s = [...values].sort((a, b) => a - b);
  const m = s.length >> 1;
  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
});

// pass `registry` to the grid, then:
{ id: 'medianPrice', dataField: 'price', caption: 'Median Price', dataType: 'number',
  area: 'data', summaryType: 'custom', calculateCustomSummary: 'median' }
```

A name that is not registered stops the grid with an error that names it,
instead of quietly showing a sum.

## Summary display modes

Transform an aggregated value **after** it is computed with `summaryDisplayMode`:

```tsx
{ id: 'revenue', dataField: 'revenue', caption: '% of Total', dataType: 'number',
  area: 'data', summaryType: 'sum', summaryDisplayMode: 'percentOfTotal' }
```

| Mode | Shows each cell as… |
|---|---|
| `absolute` | the raw aggregated value (default) |
| `percentOfTotal` | % of the grand total |
| `percentOfRowTotal` | % of its row total |
| `percentOfColumnTotal` | % of its column total |
| `percentOfParentRowTotal` | % of its parent row group, in the same column |
| `percentOfParentColumnTotal` | % of its parent column group, in the same row |
| `runningTotal` | a cumulative running total |
| `difference` | the difference from the previous value |
| `percentDifference` | the % difference from the previous value |

The percent modes are computed on a 0–100 scale. A field without a `format`
of its own shows them as the locale's percent with at most two decimals —
`37.51%` in English, `%37,51` in Turkish — on screen, in CSV and PDF, and in
Excel (number format `0.00"%"`). A `format` on the field replaces this; the
value it receives is still on the 0–100 scale.

### % of the parent total

With nested row fields, `percentOfParentRowTotal` answers "what share of its
group is this?" rather than "what share of everything?":

```tsx
// Rows: Region > Country. Each country shows its share of its region,
// each region its share of the grand total.
{ id: 'share', dataField: 'revenue', caption: 'Share of parent', dataType: 'number',
  area: 'data', summaryType: 'sum', summaryDisplayMode: 'percentOfParentRowTotal' }
```

| Row | Revenue | Share of parent |
|---|---|---|
| EMEA | 100 | 50% (of the 200 grand total) |
| EMEA › Germany | 60 | 60% (of EMEA) |
| EMEA › France | 40 | 40% (of EMEA) |
| APAC | 100 | 50% |
| Grand total | 200 | 100% |

- The parent is the **immediate** parent group on that axis. A top-level group's
  parent is the grand total, and the grand total itself shows 100%.
- Each column is divided separately: Germany in 2025 is a share of EMEA in 2025.
- A collapsed group shows its own share of its parent; its children are not
  computed until it is opened.
- Hiding subtotal rows (`showRowTotals: false`) changes nothing: the parent's
  total is still what the share is taken of.
- `percentOfParentColumnTotal` is the same rule across nested column fields,
  within each row.
- A parent that totals 0 shows 0.

## Grouping

Group `date` and `number` fields with `groupInterval`:

```tsx
{ id: 'orderDate', dataField: 'orderDate', caption: 'Month', dataType: 'date',
  area: 'column', groupInterval: 'month' }
```

Date intervals: `year`, `quarter`, `month`, `week`, `day`. `quarter`, `month`
and `day` gather the same period of every year into one member (every January
together); nest them under a `year` field to keep years apart.

`week` is the ISO 8601 week: weeks start on Monday, and week 1 is the week
holding the year's first Thursday. Each member is labelled with its ISO
week-year and number, so years never mix and the members sort in calendar
order:

```tsx
{ id: 'orderWeek', dataField: 'orderDate', caption: 'Week', dataType: 'date',
  area: 'row', groupInterval: 'week' }
// 2026-12-28 → "2026-W53", 2027-01-01 → "2026-W53", 2027-01-04 → "2027-W01"
```

Like the other intervals, a date is read as the local calendar date it falls on.

Numbers take a bucket width as a number: `groupInterval: 100` groups into
0–99, 100–199, and so on. The strings `numeric` and `custom` have no effect, and
the grid reports them when the fields are set.

## Sorting

Sort a field's own values, or sort a row/column dimension by a measure:

```tsx
// Sort Regions by descending Revenue rather than alphabetically.
{ id: 'region', dataField: 'region', caption: 'Region', dataType: 'string',
  area: 'row', sortOrder: 'desc', sortBySummaryField: 'revenue' }
```

`sortBySummaryField` targets a data field by `id`. For an order the built-ins
cannot express, supply `calculateCustomSort` — a comparator that also receives
the two cells being compared.

## Top-N

Keep only the leading values of a row or column dimension. `topN` is applied
**after** the sort, so it means "top by whatever you just sorted by":

```tsx
// The ten highest-revenue regions, and nothing else.
{ id: 'region', dataField: 'region', caption: 'Region', dataType: 'string',
  area: 'row', sortOrder: 'desc', sortBySummaryField: 'revenue', topN: 10 }
```

It applies per level: a `topN` on Region and a different one on Category keeps
the top regions, and within each, the top categories.

**Grand totals still cover the whole dataset.** A "top 10 regions" view totals
all regions, not the ten on screen, so the visible rows will not add up to the
total — unless you ask for the remainder:

```tsx
{ ...region, topN: 10, topNShowOthers: true, topNOthersCaption: 'Other regions' }
```

`topNShowOthers` folds everything below the cut into one extra row (or column)
carrying its own figures.

> **One honest limit: `avg` and `distinct` measures are left EMPTY in that
> row.** The remainder is combined from cells that are already aggregated,
> which is exact for `sum`, `count`, `min` and `max` — but an average needs the
> row counts behind each value and a distinct count needs the values
> themselves, and neither survives aggregation. Rather than print a plausible
> wrong number in a total row, those cells stay blank and the grid reports
> which measures they were through your `onError` handler.
>
> All three of these were declared and read by nothing until 2026-08-27, and
> this page carried a worked example of the "Others" row before it existed.

## Value and label filters

Two more ways to choose which members of a row or column field stay — the
ones a spreadsheet pivot calls value and label filters. By the member's
**total**:

```tsx
// Regions that sold over a million, and nothing else.
{ id: 'region', dataField: 'region', caption: 'Region', dataType: 'string', area: 'row',
  valueFilter: { dataField: 'revenue', operator: '>', value: 1_000_000 } }
```

`operator` is `>`, `>=`, `<`, `<=`, `=`, `!=`, `between` or `notBetween`; the
two range operators take a second bound in `value2` (inclusive, either order).
`dataField` is the **id** of a field in the data area, and the test reads its
summary — before any `summaryDisplayMode`, so a percent-of-total view still
filters on the amount.

By the member's **caption**:

```tsx
// Cities whose name starts with "an" — Ankara and Antalya.
{ ...city, labelFilter: { operator: 'startsWith', value: 'an' } }
```

`operator` is `equals`, `notEquals`, `contains`, `notContains`, `startsWith` or
`endsWith`. The match ignores case unless you set `caseSensitive: true`, and it
lowercases in the grid's `locale`, so in Turkish "iz" matches "İzmir". A blank
member reads as empty text.

They run per level, after the sort and **before** `topN`, so the two combine
the way the sentence reads: `valueFilter` over a million plus `topN: 3` is "the
top three of those over a million". As with Top-N, **the totals keep counting
every member** — the subtotals and the grand total do not shrink to the rows
on screen. A parent whose members are all filtered out stays as one row with
its own total. To leave rows out of the figures themselves, filter the source
data instead, with `layout.prefilter`.

Both filters are kept in the saved state, so a reader's choice survives a
reload, and a change through `controller.updateField` recomputes straight away.

A filter that cannot be honoured — a `dataField` not in the data area, an
unknown operator, a missing `value2` — leaves the level unfiltered and is
reported through your `onError` handler, rather than quietly showing nothing.

Readers set them on screen too. The menu of a row or column field (right-click
the field, or Shift+F10 on it) has **Filter by condition…**, and so does the
button at the bottom of its member list. The dialog has one line for the
caption and one for a total, with the data field to test. **None** removes that
line. A field with a condition shows the same filled filter icon as one with
members unticked. The dialog keeps a `caseSensitive: true` your code set; it
does not offer the switch itself.

## Filtering

Header filters are built in — click a row/column field header to include or
exclude values. You can also seed filters declaratively:

```tsx
{ id: 'country', dataField: 'country', caption: 'Country', dataType: 'string',
  area: 'filter', filterType: 'include', filterValues: new Set(['USA', 'Germany']) }
```

**Fully keyboard-driven:** the filter popup never needs the mouse — start
typing to search, use <kbd>↑</kbd>/<kbd>↓</kbd> to move through the values,
<kbd>Space</kbd> to toggle a checkbox, <kbd>Backspace</kbd> to jump straight
back to the search box (deleting as you go), and <kbd>Enter</kbd> to apply.

The visual **Prefilter builder** (pre-aggregation, multi-condition) is an
**Enterprise** feature — see [Enterprise & licensing](https://kanunilabs.com/docs/pivotgrid/enterprise).

## Conditional formatting

Style cells by value with `expression` rules. Each rule provides a `formula`
`(value, cell) => boolean` and a `style` applied when it returns `true`:

```tsx
{ id: 'revenue', dataField: 'revenue', caption: 'Revenue', dataType: 'number',
  area: 'data', summaryType: 'sum',
  conditionalFormatting: [
    { type: 'expression', formula: (v) => v < 0,      style: { color: '#dc2626', fontWeight: 600 } },
    { type: 'expression', formula: (v) => v > 100000, style: { backgroundColor: '#dcfce7' } },
  ] }
```

Rules are evaluated top-to-bottom and merged, so later rules win on conflicting
properties. `style` is a standard React `CSSProperties` object.

### The other three rule types

`PivotConditionRule.type` offers four kinds, and since `@kanunilabs/pivotgrid-core`
1.3.0 all four render. The three scale-based ones take their configuration in the same
`style` object:

```tsx
conditionalFormatting: [
  // A colour scale across the measure's range.
  { type: 'colorScale', style: { colors: ['#f8fafc', '#2563eb'] } },
  // An in-cell bar, painted UNDER the value so the number stays readable.
  { type: 'dataBar', style: { color: '#3b82f6', negativeColor: '#ef4444' } },
  // A glyph before the value. Cut points are in the measure's own units;
  // without them the range is split evenly between the icons.
  { type: 'iconSet', style: { icons: ['arrow-down', 'minus', 'arrow-up'], thresholds: [0, 100] } },
]
```

Two things are worth knowing:

**Totals are excluded from the range.** A grand total sits an order of
magnitude above the cells beside it; letting it set the top of a colour scale
would push every real value into the first stop — correct, and useless.

**Only `colorScale` survives an export.** A spreadsheet cell in our writers
carries a fill colour, so a colour scale exports as that colour. A bar and an
icon have no cell-level equivalent, so an exported file keeps the value without
them — and setting one of those rules says so through your `onError` handler
when the fields are set, once per message.

Note also that the export applies the **first** matching rule where the screen
merges all of them, so a cell with two matching rules can look different in a
downloaded file.

## Totals & layout

Grand totals, subtotals and the row-header shape are controlled by the `layout`
prop (`PivotLayoutState`):

```tsx
<BasePivotGrid
  gridId="sales"
  data={data}
  initialFields={fields}
  layout={{
    showRowGrandTotals: true,     // the grand total row
    showColumnGrandTotals: true,  // the grand total column
    showRowTotals: true,          // per-level subtotals on the row axis
    showColumnTotals: true,       // …and on the column axis
    totalsPosition: 'bottom',     // 'top' | 'bottom', both axes
    rowHeaderLayout: 'tree',      // 'tabular' (a column per field) | 'tree' (nested)
    hideEmptySummaryCells: true,  // drop empty rows/columns
    dataFieldPosition: 'columns', // where measure captions live
  }}
/>
```

### The coarse form

There is a second, coarser spelling of the same switches — one option
per axis pair instead of one per axis:

```tsx
layout={{
  showGrandTotals: 'both',   // → showRowGrandTotals + showColumnGrandTotals
  showSubTotals: 'both',     // → showRowTotals + showColumnTotals
  totalsDisplayMode: 'top',  // → totalsPosition
}}
```

These are translated at the controller boundary, so either spelling works. If
you pass both, the **granular** one wins — it is the more specific request.

### Column subtotals

Expanding a column group adds a **subtotal column** carrying that group's own
figure, beside its children — the column-axis twin of the subtotal rows. It
follows `totalsPosition`, so `'top'` puts it before the children.

```tsx
layout={{ showColumnTotals: true, totalsPosition: 'bottom' }}
```

It is **on by default**, like `showRowTotals`. Set `showColumnTotals: false`
for the column set you had before this landed.

> **New in 1.3.0.** Before it the option was accepted and reported as
> unimplemented through `onError`. Two things are worth knowing about how it
> works: the figure is not a second aggregation pass — the engine already
> totals every visible node, so the subtotal column addresses the group's own
> value — and it appears in **exports** too, because the exporters derive their
> columns from the same list the screen does.
>
> All four coarse options were declared and read by nothing until 2026-08-27,
> and this page used two of them in the example above.

### Column widths

Row-header columns start at 150px and data columns at 95px. Long member names
or large totals need more, and `defaultColumnWidths` sets the starting width
for every column of a kind, however many there turn out to be:

```tsx
<BasePivotGrid
  gridId="sales"
  data={data}
  initialFields={fields}
  defaultColumnWidths={{ rowHeader: 280, data: 120 }}
/>
```

`rowHeader` applies to each row-header column — one per row field in the
tabular layout, the single column in the tree layout — and `data` to each data
column. Either can be left out. The frozen row-header block is still kept
narrow enough to leave room for the data, so in a small container a wide
`rowHeader` is painted narrower than asked.

A width the user drags beats the default, and is saved with the layout when
`stateStoring` is on. To set one column from code, use the `ref`:

```tsx
const grid = useRef<PivotGridRef>(null);

// Keys: `row-<i>` for row-header column i (0 is the outermost row field),
// `leaf-<i>` for data column i, counted left to right with totals included.
grid.current?.setColumnWidths({
  ...grid.current.getState().columnWidths,
  'row-0': 320,
});
```

`setColumnWidths` replaces the whole map, so spread the current one to change a
single column; a column left out goes back to `defaultColumnWidths`. In the
JavaScript edition the option is the same key on `createPivotGrid`, and the
method is `grid.controller.setColumnWidths`.

## Import

The footer's **Import** menu ingests external data without code. It reads
**CSV / TSV / TXT**, **Excel** (`.xlsx`, `.xls`, `.xlsm`, `.xlsb`), **XML** and
**JSON**, plus **clipboard paste** (delimited text) and **drag-and-drop** onto
the grid. Column types are inferred with locale-aware parsing (EU/US decimals,
dates, booleans, leading-zero IDs stay strings). Large files stream with a
progress bar and can be cancelled.

Receive imported rows via `onImportData`, and optionally show a preview +
column-mapping step first:

```tsx
<BasePivotGrid
  gridId="sales"
  data={data}
  initialFields={fields}
  previewImport                    // show a preview/mapping step before applying
  onImportData={(rows) => setData(rows)}
/>
```

## Export

The footer's **Export** menu produces **CSV**, **JSON** (list / tree / full session
snapshot), **XML**, **Print** and **Copy to clipboard** (tab-separated) in the Community
build. Styled **Excel** (WYSIWYG *Pivot View* or flat *List View*) and **PDF** export are
**Enterprise** features — in Community they appear in the menu with an "Enterprise" badge,
and become active when you render `EnterprisePivotGrid`. Large exports switch to a
streaming writer, and CSV output is sanitized against formula injection.

Cancellation and progress are plumbed through `exportData`'s `signal` and
`onProgress`, but the built-in download menu passes neither — you reach them only
through your own `PivotGridRef`. Row assembly yields between chunks; the three
heaviest calls do not. See [Styled Excel & PDF export](https://kanunilabs.com/docs/pivotgrid/export) for
what changes at 100,000 rows and what the file will not match on screen.

Hook `onExporting` to observe or cancel an export:

```tsx
<BasePivotGrid
  gridId="sales" data={data} initialFields={fields}
  onExporting={(e) => { if (!userAllowed) e.cancel = true; }}
/>
```

## Saved views & state persistence

The footer's report menu lets users save, load and set a default **named view**
(fields + layout). Persist the whole grid state across reloads with
`stateStoring`:

```tsx
<BasePivotGrid
  gridId="sales" data={data} initialFields={fields}
  stateStoring={{ enabled: true, type: 'localStorage', storageKey: 'sales-pivot' }}
/>
```

Use `type: 'custom'` with `onSave`/`onLoad` to persist to your own backend.

## Theming & striping

The grid is themed entirely with CSS variables. Pass a `theme` object, or toggle
zebra striping with `striped`:

```tsx
<BasePivotGrid
  gridId="sales" data={data} initialFields={fields}
  striped
  theme={{ primary: '#0284c7', surfaceHeader: '#e0f2fe', border: '#bae6fd' }}
/>
```

`surfaceHeader` and `textHeader` colour the panels — the filter area, the field
areas, the footer, dialog headers — and, unless you say otherwise, the column
headers too. For a dark header band over light panels, give the band its own
pair:

```tsx
theme={{ surfaceHeader: '#f1f5f9', headerBackground: '#1e293b', headerText: '#f8fafc' }}
```

Try the presets live in the [Theming playground](https://kanunilabs.com/playground/pivotgrid/theming).

### Colour schemes

Both packages ship 36 ready-made colour schemes, light and dark, each one a
small stylesheet next to the grid's own. Browse them, or make your own from any
of them, in the [Theme Builder](https://kanunilabs.com/theme-builder) — it previews the pivot table
and exports the stylesheet. Import the one you want and name it by its id:

```tsx
import '@kanunilabs/pivotgrid-react/styles.css';
import '@kanunilabs/pivotgrid-react/themes/graphite.css';

<BasePivotGrid gridId="sales" data={data} initialFields={fields} theme={{ id: 'graphite' }} />
```

The id is all the grid needs: it marks the grid root with `data-theme`, and
every popup it opens (field menus, the filter list, dialogs, the field chooser,
the drill-down) carries the same mark, so the scheme reaches all of them.
`themes/all.css` holds every scheme at once, for an app that lets its users
choose. The plain JavaScript package has the same files:

```ts
import '@kanunilabs/pivotgrid/styles.css';
import '@kanunilabs/pivotgrid/themes/graphite.css';

createPivotGrid(host, { data, initialFields: fields, theme: { id: 'graphite' } });
```

A scheme and your own colours combine: anything you set in the `theme` object
wins over the scheme, so a scheme can be the starting point for a brand colour:

```tsx
<BasePivotGrid … theme={{ id: 'graphite', primary: '#f59e0b' }} />
```

Without an id, or with an id no imported stylesheet knows, the grid keeps its
default look. A chart drawn with `ChartFactory` beside the grid follows the
scheme when you wrap it in `<PivotThemeProvider theme={{ id: 'graphite' }}>` and
pass `palette="theme"`, which derives the series colours from the scheme's
accent.

## Density

`density` sets the row rhythm. It changes no colours, so it combines with any
theme or scheme:

```tsx
<BasePivotGrid gridId="sales" data={data} initialFields={fields} density="compact" />
```

| `density` | Rows | Also |
|---|---|---|
| `'compact'` | 24px | Type one size smaller; for screens that need the most rows. |
| `'normal'` (default) | 28px | The grid as it has always looked. |
| `'comfortable'` | 36px | Larger targets on the toolbar buttons. |

Header rows follow the same height. Menus, the filter list and dialogs keep
their size in every density. Changing the prop repaints in place, without
re-running the pivot engine. In the plain JavaScript package, pass `density` in
the config and switch it later with `grid.setDensity('comfortable')`.

## Localization & RTL

Twelve locales ship in the box; `ar` flips the layout to RTL automatically. See
the [Quick start](https://kanunilabs.com/docs/pivotgrid/react#localization) and the
[Localization playground](https://kanunilabs.com/playground/pivotgrid/localization).

## Performance

Built-in aggregation runs in a Web Worker over columnar storage with a
trie-based grouper, so the UI stays responsive on **a million rows** — try the
[Big Data Performance playground](https://kanunilabs.com/playground/pivotgrid/performance) (100 →
1,000,000 rows). The worker is compiled into the package and started from a Blob URL, so
there is nothing to configure in any bundler:

```tsx
<BasePivotGrid data={data} initialFields={fields} />
```

A strict Content-Security-Policy is the one case that still needs attention —
see [Installation](https://kanunilabs.com/docs/pivotgrid/installation#if-you-have-a-strict-content-security-policy).

## Live updates

A dashboard that receives rows as they change does not have to hand the grid a
new `data` array every time. `applyTransaction` adds, updates and removes rows
without a rebuild: only the rows in the transaction are encoded and sent to the
worker, which regroups them and recomputes the groups they touched.

```tsx
const grid = useRef<PivotGridRef>(null);

<BasePivotGrid ref={grid} gridId="desk" data={trades} rowKey="id" initialFields={fields} />

// on every message from the feed
grid.current?.applyTransaction({
  update: [{ id: 'T-1042', desk: 'Rates', pnl: 18250 }],
  add: [{ id: 'T-1043', desk: 'FX', pnl: -400 }],
  remove: ['T-0999'],
});
```

In JavaScript the call is on the grid itself, `grid.applyTransaction({ … })`,
with `rowKey` in the `createPivotGrid` options.

- **Rows are matched by `rowKey`** — a field name, or a function returning a
  string or number. Without it rows are matched by object identity: update with
  the very object that is in your data, changed in place, and remove by passing
  rows rather than keys.
- An update for a key the grid does not have is ignored, a remove wins over an
  update of the same row, and added rows go to the end — the same rules as the
  DataGrid's transactions.
- It returns what it applied, `{ added, updated, removed }`, and
  `getRawData()` returns the new rows at once; the recomputed pivot follows a
  moment later (the `engineCompleted` event, or the next render).
- The result is the pivot a rebuild from the new rows would show: the same
  groups, totals, filters, sorting and custom summaries. The totals a change
  touches are summed again from their rows, not adjusted by the difference, so
  decimal totals do not drift over thousands of updates.
- Re-rendering with the **same** `data` array keeps the changes. A **new**
  array replaces every row, as before.
- A transaction that arrives while the grid is still building, or while a
  field is being moved, is applied as soon as that finishes — in order, without
  starting the build again.

Measured on 2026-10-03 over a million rows (three grouping fields, two
measures; a transaction of 10 updates, 5 removes and 10 adds, in Node 24): about
17 ms of worker time per transaction against 230–290 ms to rebuild there, and
about 35 ms on the main thread against 160 ms to encode every row again. Most
of that main-thread time is finding the changed rows by key, which is one pass
over all rows.

Two things to know. The first transaction on a grid prepares the engine for
the ones after it with one regrouping of the stored data (about 0.3 s at a
million rows), without encoding anything again. And a value that no longer
occurs in any row stays in the engine's dictionary until the next full build —
a new `data` array, `setData` or **Refresh**.

### Feeds that tick many times a second

Every `applyTransaction` finds its rows by key in one pass over all rows and
sends the worker its own message. A feed that calls it a hundred times a second
pays that a hundred times for one picture. Queue the ticks instead:

```tsx
<BasePivotGrid ref={grid} rowKey="id" asyncTransactionWait={50} /* … */ />

// on every message from the feed
grid.current?.applyTransactionAsync({ update: [tick] });
```

Queued transactions are merged and applied together once `asyncTransactionWait`
milliseconds (default 50) have passed since the first of them. The optional
second argument is a callback that runs when its batch has been applied.
`flushAsyncTransactions()` applies the queue at once, and
`controller.getPendingAsyncTransactionCount()` says how many transactions wait.

- **The merged batch leaves the rows that applying each transaction in order
  would.** An add followed by an update is one add of the latest row; an add
  followed by a remove leaves nothing; the last update of a row wins; a remove
  drops an earlier update. Inside one transaction, "remove `7`, add `7`" is a
  replacement.
- **The order of your calls is kept.** A synchronous `applyTransaction`,
  `setData` or a new `data` array applies the queue first.
- **Destroying the grid drops the queue** without applying it.

In JavaScript the calls are on the grid, `grid.applyTransactionAsync(…)` and
`grid.flushAsyncTransactions()`, with `asyncTransactionWait` in the
`createPivotGrid` options. Measured on 2026-10-08 over a million rows in Node 24:
finding the rows for 100 single-row ticks took about 1.7 s one by one and about
24 ms merged, and the worker received one message instead of a hundred.

## Toolbar customization

Show or hide individual footer controls with the `toolbar` prop:

```tsx
<BasePivotGrid
  gridId="sales" data={data} initialFields={fields}
  toolbar={{ showExportButton: true, showImportFile: false, showCalculatedFields: false }}
/>
```

---

Looking for calculated fields, charts or drill-down? Those are in the
[Enterprise](https://kanunilabs.com/docs/pivotgrid/enterprise) package. For every prop and type, see
the [API Reference](https://kanunilabs.com/docs/pivotgrid/api).

## Missing a feature? Tell us

The grid grows out of real-world requests — if something you need is missing,
awkward, or plain broken, we genuinely want to hear it. Write to
[hello@kanunilabs.com](mailto:hello@kanunilabs.com) or use the
[contact form](https://kanunilabs.com/contact); license holders can also open a
[support ticket](https://kanunilabs.com/dashboard/support). Every message is read and answered.

---

Source: https://kanunilabs.com/docs/pivotgrid/faq

# Frequently asked questions

## Is the free tier open source?

No. The free packages (`@kanunilabs/pivotgrid-core`, `@kanunilabs/pivotgrid-react`,
`@kanunilabs/pivotgrid`) are
**free to use** but proprietary — you may install and ship them in your apps, but the
source is not published and may not be redistributed on its own. See the LICENSE in each
package.

## What's the difference between free and Enterprise?

**Community** (the free `@kanunilabs/pivotgrid-react` and `@kanunilabs/pivotgrid` packages) is a fully usable pivot
table: pivoting, grouping, sorting, filtering, conditional formatting, theming,
localization, saved views, broad import, and CSV/JSON/clipboard/print export.
**Enterprise** adds advanced analytics and BI-grade output — calculated fields, the
prefilter builder, drill-down to source records, live chart integration, and styled
Excel/PDF export — delivered via a private registry with a signed license key.

## How does licensing work?

Each license is a signed key (`KLAB1….`) verified **offline** in the browser (no network
needed) using an embedded public key. Keys are bound to your domains and tier. Manage
domains in your [dashboard](https://kanunilabs.com/dashboard/licenses) — changing them re-issues the key.

## Which frameworks are supported?

React (18 & 19), and plain JavaScript with no framework at all.

`@kanunilabs/pivotgrid-react` is the React binding.
[`@kanunilabs/pivotgrid`](https://kanunilabs.com/docs/pivotgrid/javascript) is the same grid built straight into
the DOM: one `createPivotGrid(element, config)` call, no component tree, and a UMD build so
a `<script>` tag is a complete install. Both are real renderers over one engine
(`@kanunilabs/pivotgrid-core`), and the JavaScript config mirrors the React props by name.

Angular and Vue are not supported, and no adapter is planned for now: development
stays on React and plain JavaScript. The engine itself is framework-agnostic — no
DOM, no framework imports — which is what makes the plain JavaScript renderer
possible.

## Which browsers are supported?

The current versions of Chrome, Edge, Firefox and Safari. Internet Explorer is
not supported. [Supported browsers](https://kanunilabs.com/docs/pivotgrid/browser-support) lists the
oldest version of each browser that has every feature the grid uses, and what is
tested in a real browser.

## Can I use it in a commercial / closed-source app?

Yes. Both the free and Enterprise tiers may be used in commercial applications, including
closed-source products.

## How is this different from a full component suite?

A focused, modern alternative: a single high-performance PivotGrid with a Web Worker
engine, a smaller install, per-developer pricing, and a private-registry delivery model —
without buying a whole suite.

## How do I get support?

Free tier: community support on GitHub. Paid tiers: open a ticket from your
[dashboard](https://kanunilabs.com/dashboard/support) — Team and Enterprise get prioritized replies.

## How do I request a feature or report a bug?

Send it to [hello@kanunilabs.com](mailto:hello@kanunilabs.com) or the
[contact form](https://kanunilabs.com/contact) — a short description and, for bugs, the steps to
reproduce are enough. License holders can also open a
[support ticket](https://kanunilabs.com/dashboard/support). Feature requests directly shape the
roadmap, so don't hold back.

## What happens when my subscription ends?

Nothing you have shipped changes. A paid license key covers every version released up to
the end of the period you paid for, with no time limit, so an application built with those
versions keeps running without a watermark. What ends is access to new versions through
the private registry, and support.

A version released after that date is not covered: upgrade to it without renewing and it
shows the watermark. While a subscription is active each renewal moves the date forward,
so copy the current key from your [dashboard](https://kanunilabs.com/dashboard/licenses) before you upgrade.

## Do you offer refunds?

Billing is handled by Paddle (our Merchant of Record), and refund requests go through
Paddle. The [refund policy](https://kanunilabs.com/refunds) explains what a refund means for your license.

---

Source: https://kanunilabs.com/docs/pivotgrid/enterprise

# Enterprise & licensing

Advanced analytics ship in `@kanunilabs/pivotgrid-react-enterprise`: the no-code
calculated-field editor, live chart integration, drill-down to source records, the visual
prefilter builder, and styled Excel & PDF
export. `EnterprisePivotGrid` is a drop-in replacement for `BasePivotGrid` — it accepts the
same props and adds these.

Not using React? The same paid surface ships as `@kanunilabs/pivotgrid-enterprise`:
one `createEnterprisePivotGrid()` call, same licence key, same licence terms. The
[JavaScript guide](https://kanunilabs.com/docs/pivotgrid/javascript#enterprise-edition) shows it in use.

## Private registry

The enterprise package is delivered from our private registry with per-customer
credentials. After purchase you receive a ready-to-paste `.npmrc` by email (also
manageable from your [dashboard](https://kanunilabs.com/dashboard/licenses)):

```ini
@kanunilabs:registry=https://registry.kanunilabs.com/
//registry.kanunilabs.com/:_auth=<value from your email or dashboard>
//registry.kanunilabs.com/:always-auth=true
```

Then install:

```bash
npm i @kanunilabs/pivotgrid-react-enterprise
```

or, without React:

```bash
npm i @kanunilabs/pivotgrid-enterprise
```

Setup details, CI usage and credential rotation are covered in the
[Private registry access guide](https://kanunilabs.com/docs/pivotgrid/registry).

## License key

Set your key once at startup, then use `EnterprisePivotGrid` in place of `BasePivotGrid`:

```tsx
import { EnterprisePivotGrid, LicenseManager } from '@kanunilabs/pivotgrid-react-enterprise';

LicenseManager.setLicenseKey('KLAB1....');

export function MyProGrid(props) {
  return <EnterprisePivotGrid {...props} />;
}
```

Without a valid license the grid still renders and shows a watermark that says
what is wrong, in the grid's language — "Unlicensed", "License expired",
"Browser cannot verify the license (HTTPS required)" and so on. Nothing is
logged to the console when no key is supplied at all — the notice, in
PivotGrid's name, only appears when a key IS given and fails to verify.
Licenses are verified offline: the signature is checked against a public key
compiled into the package, with no licence server to reach.

- **Plain HTTP intranets are supported.** Where the browser offers no
  `crypto.subtle` (any `http://` page that is not `localhost`), the key is
  verified by a JavaScript implementation of the same algorithm, bundled with
  the grid — same verdict, signature always checked.
- **`reasonCode`** on the licence state names the reason in a stable form
  (`expired`, `domain-mismatch`, `engine-unavailable`...). The DataGrid guide
  has [the full table](https://kanunilabs.com/docs/datagrid/enterprise#reading-the-reason) — the
  licence is shared, so the codes are too.

## What the license key actually controls

One thing: the watermark. An unlicensed Enterprise build is not a crippled
build, it is a watermarked one — a feature you cannot run is a feature you
cannot evaluate before buying.

That is separate from the **edition** boundary, which is real and has two
different shapes:

- **A runtime gate**, on the three styled export formats. `PivotController`
  refuses `excel-list`, `excel-pivot` and `pdf` on a Community grid — see
  [Styled Excel & PDF export](https://kanunilabs.com/docs/pivotgrid/export#community-refuses-and-says-so).
  It is an *edition* check, not a licence check: an unlicensed Enterprise grid
  still exports.
- **A packaging boundary**, for everything else on this page. The calculated-field
  designer, the prefilter builder, the drill-down modal
  and the chart renderer are components that exist only in the Enterprise
  packages — React and JavaScript alike. (The node context menu moved to Community on 2026-08-30 —
  bulk expand/collapse is free.) `BasePivotGrid` does not disable them, it never renders them — the
  footer's calculator and filter buttons are absent rather than greyed out.

## What Enterprise unlocks

Seven entries, and that is the whole paid surface. Everything **not** in this
list is in Community and needs no licence — the [full side-by-side
table](https://kanunilabs.com/pricing#every-feature) is on the pricing
page.

(This part is generated when the page renders. See it at https://kanunilabs.com/docs/pivotgrid/enterprise)

## Where each feature is documented

Rendering `EnterprisePivotGrid` makes the paid surfaces available: the footer's
calculator and filter buttons open their editors, and the Excel/PDF entries in
the Export menu become
active. Two of them — drill-down and charts — are headless: the grid hands you
data and you decide where to render it.

Each has its own guide, with the configuration, the API and an honest account of
where it stops:

| Guide | Covers |
|---|---|
| [Calculated fields](https://kanunilabs.com/docs/pivotgrid/calculated-fields) | row-level vs summary-level, the formula language, the designer modal, and what a saved report does to them |
| [Prefilter & node menu](https://kanunilabs.com/docs/pivotgrid/prefilter) | the pre-aggregation predicate, its AST, the builder, and the right-click expand/collapse items |
| [Drill-down & charts](https://kanunilabs.com/docs/pivotgrid/drill-down-and-charts) | the rows behind a cell, the chart transformer/sync/factory trio, and the wiring the grid does not do for you |
| [Styled Excel & PDF export](https://kanunilabs.com/docs/pivotgrid/export) | the three paid formats, the options that reach the exporter, and what the file will not match on screen |

## `EnterprisePivotGrid` vs `BasePivotGrid`

The wrapper hard-wires four props — `advancedExport` and the three render slots
— and draws the watermark. It re-assigns them **after** spreading your props, so
passing your own `renderCalculatedFieldModal`, `renderPrefilterBuilder`,
`renderNodeContextMenu` or `advancedExport` has no effect. Use `BasePivotGrid`
directly if you need to supply your own.

It is also not a type-level drop-in: `forwardRef` erases the generic, so the
shipped type is `EnterprisePivotGridProps<unknown>` and a `PivotField<Sale>[]`
will not assign to `initialFields` without a cast.

---

Source: https://kanunilabs.com/docs/pivotgrid/registry

# Private registry access

The Enterprise packages are not published on public npm. They install from our private
registry at `registry.kanunilabs.com`, and every license comes with its own registry
credentials: a username like `cust_ab12cd34` and a password.

| Package | For |
|---|---|
| `@kanunilabs/pivotgrid-react-enterprise` | React |
| `@kanunilabs/pivotgrid-enterprise` | plain JavaScript, no framework |

> **The same credentials serve every package.** One license, one registry
> account — use it for `pivotgrid-react-enterprise`, `pivotgrid-enterprise`,
> `datagrid-react-enterprise` and `datagrid-enterprise` alike. There is nothing
> separate to set up if you already installed one of them.

## Where your credentials come from

You can get them in two places:

1. **Purchase email** — the *"Your license is ready"* email contains a ready-to-paste
   `.npmrc` block under **Private npm registry**.
2. **Dashboard** — [Dashboard → Licenses](https://kanunilabs.com/dashboard/licenses), open your license, and use
   the **Private npm registry** section.

For security we store only a **hash** of your password — it can never be displayed again
after it is first shown. Losing it is not a problem: regenerating takes one click
([see below](#lost-or-leaked-password-regenerate-it)).

## Set up your project

Put the three lines from your email (or the dashboard) into a `.npmrc` file **next to your
`package.json`**:

```ini
@kanunilabs:registry=https://registry.kanunilabs.com/
//registry.kanunilabs.com/:_auth=<value from your email or dashboard>
//registry.kanunilabs.com/:always-auth=true
```

Then install as usual:

```bash
npm install @kanunilabs/pivotgrid-react-enterprise
```

or, for plain JavaScript with no framework:

```bash
npm install @kanunilabs/pivotgrid-enterprise
```

For the React package, all peer dependencies (React, charting, export libraries) are
installed automatically by npm 7+ — a single install command is enough. The JavaScript
package has no required peers; the Excel and PDF libraries are optional ones you add when
you use those export formats.

The first line routes **only the `@kanunilabs` scope** to our registry — which also
transparently serves the public `@kanunilabs/pivotgrid-core`, `-react` and `@kanunilabs/pivotgrid`
packages, so
everything else about your setup stays unchanged.

> ⚠️ **Scaffold first, `.npmrc` after.** Project generators can wipe the directory
> they scaffold into — `create-vite`'s `--overwrite` flag, for example, deletes an
> existing `.npmrc`. Create your project first, then add the `.npmrc`.

### Keeping the token out of git (teams & CI)

`.npmrc` contains a secret, so either add it to `.gitignore`, or commit a variable
version and inject the value from the environment — npm expands `${VAR}` inside `.npmrc`:

```ini
@kanunilabs:registry=https://registry.kanunilabs.com/
//registry.kanunilabs.com/:_auth=${KANUNILABS_REGISTRY_AUTH}
//registry.kanunilabs.com/:always-auth=true
```

Set `KANUNILABS_REGISTRY_AUTH` (the `_auth` value from your email or dashboard) as a CI
secret or in your local shell.

## Lost or leaked password? Regenerate it

1. Sign in at [kanunilabs.com/dashboard](https://kanunilabs.com/dashboard).
2. Open **Licenses** and click your license.
3. In the **Private npm registry** section, click **Regenerate credentials**
   (or **Generate credentials** if you never had any).
4. Copy the new `.npmrc` block right away — it is shown **only once**.

> ⚠️ Regenerating invalidates the previous password **immediately**. Update every place
> that uses it (developer machines, CI secrets) at the same time, or their
> `npm install` will start failing with `401`.

Your registry **username never changes** when you regenerate — only the password does.

## Troubleshooting

| Symptom | Cause & fix |
| --- | --- |
| `404 Not Found` for the enterprise package | npm asked the public registry — the `@kanunilabs:registry=` line is missing or `.npmrc` is not in the project root. |
| `401 Unauthorized` / `403 Forbidden` | Wrong or rotated password. Regenerate from the dashboard and update `.npmrc` / CI secrets. |
| Works locally, fails in CI | CI can't see your `.npmrc` or its env var. Use the `${VAR}` form above and set the secret in your CI provider. |
| Access stopped after cancellation or refund | Registry access ends with the subscription — that's by design. Reactivating the subscription restores it. |

Still stuck? [Open a support ticket](https://kanunilabs.com/dashboard/support) — we're happy to help.

---

Source: https://kanunilabs.com/docs/pivotgrid/calculated-fields

# Calculated fields

A field whose value is computed rather than read from the row. There is no
separate type and no registry — it is an ordinary `PivotField` carrying five
extra members, pushed into the same `fields` array as everything else.

The **compiler is free**; the **designer modal** is Enterprise. If you are
defining fields in code, everything on this page works in the Community
package.

## Row-level or summary-level — decide first

This is the one decision that matters, and getting it wrong gives you a column
of plausible-looking wrong numbers.

| | Row-level | Summary-level |
|---|---|---|
| Member | `calculateExpression` | `calculateSummaryExpression` |
| Runs | once per row, during encoding | once per cell, after aggregation |
| Sees | the row object | the other data fields' aggregated values |
| Then | is aggregated like any measure | overwrites the cell outright |
| Needs `summaryType` | **yes** | no |

**A ratio or a percentage must be summary-level.** A row-level margin computes
per-row percentages and then *adds them together*, because the engine's default
`summaryType` is `sum`. EMEA's 60% and APAC's 37.5% become 97.5%.

## In code

```tsx
import { compileSafeFormula } from '@kanunilabs/pivotgrid-core';
import type { PivotField } from '@kanunilabs/pivotgrid-react';

const revenue: PivotField<Sale> = {
  id: 'revenue', dataField: 'revenue', caption: 'Revenue',
  dataType: 'number', area: 'data', areaIndex: 0, summaryType: 'sum',
};

// Row-level: a plain function, aggregated afterwards like any measure.
const profit: PivotField<Sale> = {
  id: 'profit', caption: 'Profit', dataType: 'number',
  area: 'data', areaIndex: 1,
  summaryType: 'sum',          // state it — the default is 'sum' either way
  isCalculated: true,
  calculateExpression: (row) => row.revenue - row.cost,
  format: { style: 'currency', currency: 'USD' },
};

// Summary-level: the correct shape for a ratio.
const MARGIN = '([Revenue] - [Cost]) / [Revenue] * 100';
const fieldMap = new Map([['Revenue', 'revenue'], ['Cost', 'cost']]);

const margin: PivotField<Sale> = {
  id: 'margin', caption: 'Margin %', dataType: 'number',
  area: 'data', areaIndex: 2,
  isCalculated: true,
  formulaType: 'summary',
  formulaString: MARGIN,
  calculateSummaryExpression: compileSafeFormula(MARGIN, fieldMap)!,
  format: { style: 'decimal', maximumFractionDigits: 2 },
};
```

**Give every field an `id` equal to its `dataField`.** Row formulas bind on
`dataField || id`, summary formulas bind on `id`. Keeping them identical means
one `fieldMap` serves both, and moving a formula between the two levels stops
being a rewrite.

`formulaString` and `formulaType` are what gets *recompiled* on reload — a bare
`calculateExpression` function does not survive a page refresh. Supply both if
the field should persist.

## The formula language

The whole grammar:

```
numbers        1  2.5  100
field refs     [Revenue]        — by CAPTION, in square brackets
operators      +  -  *  /  %
grouping       (  )
```

That is all of it. There are **no functions** — no `SUM`, `IF`, `ABS`, `ROUND`,
`MIN`, `MAX` — no comparisons, no ternaries, no strings, no dates, and no way
to reference another cell. It is a hand-written recursive-descent parser
compiled to a closure tree, so nothing goes near `eval` or `new Function`.

Validate before you commit a formula:

```tsx
import { testSafeFormula } from '@kanunilabs/pivotgrid-core';

try {
  testSafeFormula(input, fieldMap);   // throws with a message
} catch (err) {
  setError((err as Error).message);
}
```

`compileSafeFormula` returns `null` instead of throwing — use it when you have
already validated, and `testSafeFormula` when a human is typing.

## The designer modal (Enterprise)

Passing `renderCalculatedFieldModal` is what makes the footer's calculator
button appear. `EnterprisePivotGrid` does this for you.

```tsx
import { EnterprisePivotGrid } from '@kanunilabs/pivotgrid-react-enterprise';

<EnterprisePivotGrid
  licenseKey={key}
  data={data}
  initialFields={fields}
  onFieldsChange={(next) => {
    // The only signal that a user added, edited or deleted a calculated field.
    persist(next.filter((f) => f.isCalculated));
  }}
/>
```

`onSave` hands you a finished `PivotField` with `isCalculated`, `formulaString`
and the compiled function already in the right slot.

## What this does not do

- **A saved report destroys every calculated field.** Reports are persisted by
  `JSON.stringify`, which drops the compiled functions, and loading one never
  recompiles from `formulaString`. The column comes back as zeros, with no
  error. And it is not opt-in: a *default* report is loaded after the state
  store has correctly rehydrated, so a user who set one loses their calculated
  fields on every page load. **Persist `formulaString` + `formulaType` yourself
  from `onFieldsChange` if these must outlive the browser.**
- **Formulas bind by CAPTION.** Renaming a field silently invalidates every
  formula that references it, and the field settings dialog lets a user rename
  anything with no cross-check.
- **A typo reports the wrong error.** An unknown caption comes back as "Formula
  contains unsafe characters", not "unknown field".
- **Everything non-numeric becomes zero.** Every field read is `Number(x) || 0`,
  so `null`, missing and text all collapse to `0` rather than to a blank cell.
  Division and modulo by zero also yield `0`.
- **The modal never sets `summaryType`.** A ratio created through the designer
  is therefore summed. Create ratios in code, or edit the field afterwards.
- **A summary expression cannot read another summary expression.** The context
  is a snapshot taken before any expression writes to it.
- **Row-level expressions run on the main thread.** They are evaluated during
  column encoding, before the data is handed to the worker — functions cannot
  be serialised across that boundary. A heavy row expression is felt directly.
- **Only data-area fields are visible to a summary expression.** Row and column
  fields are not in the context.

Without a licence key the modal still works, watermarked.

---

Source: https://kanunilabs.com/docs/pivotgrid/prefilter

# Prefilter and the node context menu

Two surfaces that both attach to what is already on screen: a predicate
applied to rows **before** anything is aggregated (its visual builder is
Enterprise; the `layout.prefilter` API is free), and a right-click menu on a
header node — **Community** since 2026-08-30, in every renderer.

## The prefilter

It runs earlier than everything else — before each field's own `filterValues`,
before grouping, before aggregation. So it changes the totals, not just what
you can see.

```tsx
import { EnterprisePivotGrid } from '@kanunilabs/pivotgrid-react-enterprise';

<EnterprisePivotGrid
  licenseKey={key}
  data={data}
  initialFields={fields}
  layout={layout}
  onLayoutChange={setLayout}
/>
```

`EnterprisePivotGrid` supplies the builder; the footer's filter button opens
it. The applied predicate lives at `layout.prefilter`.

### The AST

```ts
type PivotPrefilter = FilterGroup;

interface FilterGroup {
  logicalOperator: 'and' | 'or';
  conditions: (FilterCondition | FilterGroup)[];
}

interface FilterCondition {
  fieldId: string;      // PivotField.id — not dataField
  operator: FilterOperator;
  value: PivotValue;
}
```

Set one from code without the dialog:

```tsx
setLayout((l) => ({
  ...l,
  prefilter: {
    logicalOperator: 'and',
    conditions: [
      { fieldId: 'region', operator: '=', value: 'EMEA' },
      { fieldId: 'year', operator: '>=', value: 2024 },
    ],
  },
}));
```

**Do not pass an inline `layout={{ … }}` literal.** A fresh object every render
overwrites whatever the dialog just applied. Hold it in state, as above.

Note this is *not* the DataGrid filter AST. PivotGrid uses
`logicalOperator` / `conditions` / `fieldId`; DataGrid uses `logic` / `nodes` /
`columnId`. They are not interchangeable.

## The node context menu

Community, in both the React and the JavaScript renderer. Right-click a row or
column header that has children:

| Item | What it does |
|---|---|
| Expand / Collapse | toggles that node |
| Expand All | expands one more level, across the whole tree |
| Collapse All | collapses one level, across the whole tree |

## What this does not do

### The prefilter is evaluated twice, by two different implementations

This is the one worth knowing before you rely on it. The predicate is
interpreted by **two separate switch statements**:

- `engine/FlatPivotEngine.ts` — drives everything the grid displays. On a
  string (dictionary-encoded) column it compares with **string** semantics:
  `strVal > targetStr`.
- `engine/filter.ts` — drives drill-down and export. It coerces first:
  `Number(val) > targetNum`.

So `>` on a column of numeric-looking strings can order values differently in
the grid than in the file you export from it. The two were written
independently and nothing keeps them in step.

Two more consequences of the same split:

- **`isnull` on a measure treats zero as blank.** The numeric branch returns
  `isNaN(numVal) || numVal === 0`, so a genuine `0` is reported as missing.
- **Text operators on a measure match everything.** The numeric branch has no
  case for `contains` / `startswith` / `endswith` and falls through to
  `default: return true`.

### The rest

- **A condition on a field that is in neither the Row nor the Column area is
  silently ignored** — while the dialog's dropdown offers every field, with
  nothing to distinguish them.
- **The dialog offers 12 of the 14 operators.** `in` and `notin` are
  implemented in both evaluators and absent from the UI. Worse: loading an
  existing prefilter that uses one **corrupts it**, because the `select` has no
  matching option and the next Apply writes whatever the browser selected
  instead.
- **Every value is a string.** One text input for all types — no date picker,
  no numeric input, no `between`.
- **An empty condition blanks the grid.** Apply only checks whether the root
  group is empty; a freshly added condition defaults to `{ operator: '=',
  value: '' }` and matches nothing.
- **"Expand All" expands exactly one level**, and it **ignores the node you
  right-clicked**. It walks the already-materialised tree, which only contains
  children of already-expanded nodes, and it is seeded from the root — so
  right-clicking EMEA also expands APAC and every other branch at that depth.
- **No keyboard path to the menu at all.** The grid's key handler covers
  arrows, Home/End, PageUp/PageDown, Escape, Space and Enter — there is no
  ContextMenu-key binding. The dialog has no Escape handler, no focus trap and
  no `role="dialog"`.
- **Parts are hardcoded English** despite the dictionary being one hook away:
  all 12 operator labels, "Add Group", and the condition editor generally — that
  component never calls `usePivotConfig`, so it has no translator at all. The
  dialog's own title reads "Filter Area", which is the caption of a different
  feature.
- **You cannot add your own menu items.** There is no `items` prop, and the
  only escape hatch replaces the whole component.
- **Neither feature is licence-gated.** Without a key they run watermarked.

If any of these is load-bearing for you, say so — several are small, and
knowing which one blocks real work is how they get prioritised.

---

Source: https://kanunilabs.com/docs/pivotgrid/drill-down-and-charts

# Drill-down and charts

Both of these are **headless**. The grid gives you data; you render the
surface. `EnterprisePivotGrid` ships the components but wires neither — so a
first integration that "does nothing" is usually this, not a bug.

## Drill-down: the rows behind a cell

Clicking a cell resolves the source records that produced it and hands them to
`onCellClick`.

```tsx
import { useState } from 'react';
import { EnterprisePivotGrid, PivotDrillDownModal } from '@kanunilabs/pivotgrid-react-enterprise';

const [drill, setDrill] = useState<{ records: unknown[]; rowPath: string[]; colPath: string[] } | null>(null);

<EnterprisePivotGrid
  licenseKey={key}
  data={data}
  initialFields={fields}
  locale="de"
  onCellClick={(e) => {
    // Guard the cell type — headers and totals resolve too.
    if (e.cellType !== 'data' || !e.records?.length) return;
    setDrill({ records: e.records, rowPath: e.rowPath, colPath: e.colPath });
  }}
/>

{drill && (
  <PivotDrillDownModal
    records={drill.records}
    rowPath={drill.rowPath}
    colPath={drill.colPath}
    locale="de"        // the window sits outside the grid, so give it the grid's language
    fields={fields}    // columns titled by your captions instead of the record keys
    onClose={() => setDrill(null)}
  />
)}
```

`e.records` is found when you first read it, by scanning the dataset — the grid
does not keep the rows behind each cell. A handler that never reads it costs
nothing. See the limits.

The window is yours to place, usually outside the grid, so it cannot see the
grid's language: pass the same `locale` (and `dictionary`, if you reword any
caption). Its title, record count, search box and buttons then follow it in
all twelve languages, numbers and dates are written for that locale, and
Arabic turns it right-to-left. Rendered inside a `PivotConfigProvider`, it
follows the provider when `locale` is left out.

## Charts

Three pieces: a **transformer** turns the engine result into chart-shaped data,
a **hook** keeps it in sync, and a **factory** renders it.

```tsx
import { useMemo } from 'react';
import { EnterprisePivotGrid, ChartDataTransformer, ChartFactory } from '@kanunilabs/pivotgrid-react-enterprise';

// MEMOISE THIS. An inline literal recomputes the transform on every render.
const chartOptions = useMemo(
  () => ({
    transformer: ChartDataTransformer.transform,   // required — there is no default
    maxPoints: 100,
    hideTotals: true,
    inverted: false,
  }),
  [],
);

const [chart, setChart] = useState({ chartData: [], chartSeries: [] });

<EnterprisePivotGrid
  licenseKey={key}
  data={data}
  initialFields={fields}
  chartIntegrationOptions={chartOptions}
  onChartSync={setChart}
/>

<div style={{ height: 320 }}>
  <ChartFactory type="column" data={chart.chartData} series={chart.chartSeries} />
</div>
```

| Option | Type | Default |
|---|---|---|
| `transformer` | `(engineResult, …) => ChartNormalizedData` | none — **required in practice** |
| `maxPoints` | `number` | `100` |
| `hideTotals` | `boolean` | `true` |
| `inverted` | `boolean` | `false` |

Chart types: `column`, `bar`, `line`, `area`, `pie`, `donut`, `scatter`, `xy`,
`bubble`, `polar`, `combination`, `waterfall`, `funnel`, `treemap`, `heatmap`,
`rangeBar`, `sunburst`, `histogram`. The last seven are drawn as plain SVG rather
than through recharts.

A histogram counts how many categories fall in each band of the first visible
measure: with products on the rows and revenue as the value, "how many products
sold between 1,000 and 2,000". The bands share one round width — 1, 2 or 5 times
a power of ten — so the edges read as 0, 500, 1,000; `bins` asks for about that
many (default 10), and the last band includes its upper edge. `countLabel` names
the value axis (default `'Count'`; pass the grid's word). Blank values are left
out. A bar stands for many categories, so it reports no `onCategoryClick` and the
keyboard does not stop on it. A sunburst draws the row fields as rings: the outermost field in the
middle, each arc its share of the whole, each inner ring the sum of the rings
outside it. Expand a row group to add its ring. It sizes the arcs by the first
visible measure, and a parent's arc is the sum of its children, which is right
for a sum or a count but not for an average. Zero and negative values take no
arc.
A range bar floats between the first two measures in each category, from the
smaller to the larger (say "Min of price" and "Max of price"), each end in its
measure's colour. A pivot's
heatmap is its own matrix: row categories across, column paths and measures
down. Pass `totalLabel` to caption the waterfall's closing bar in your
language. `scatter` is a dot plot: dots over the category axis.
`xy` is the true scatter chart. It puts one point per category at
(first measure, second measure) for each column path. `bubble` sizes each
point by a third measure, so put the measures in the data area in that order.
With too few measures the chart says what is missing (`xyNeedsMeasuresText`
sets that sentence in your language; `rangeNeedsTwoText` does the same for a
`rangeBar`, which needs a low and a high measure). The renderer is `recharts`, a **peer dependency** — install it
yourself. `ResponsiveContainer` fills 100% of its parent, so the parent needs a
height.

`ChartFactory` also takes:

| Prop | Type | Default |
|---|---|---|
| `stacking` | `'grouped' \| 'stacked' \| 'normalized'` | `'grouped'` |
| `width`, `height` | `number` (px) | fill the parent |
| `animate` | `boolean` | `true` |
| `format` | `ChartFormat`: `title`, `categoryAxisTitle`, `valueAxisTitle`, `legend`, `dataLabels`, `valueScale`, `font`, `labelAngle`, `gridLines`, `gridDashed`, `lineWidth`, `lineDashed`, `fillOpacity`, `palette`, `colors` | none |
| `fields` | the grid's `PivotField[]` | none |
| `palette` | `string[]`; `'theme'` for a ramp from `--pivot-primary`; or a named set — `'classic'`, `'colorblind'`, `'vivid'`, `'monochrome'` — kept at 3:1 contrast with `--pivot-surface`. `format.palette` and `format.colors` win over it. | the transformer's colours |
| `hiddenSeries`, `onHiddenSeriesChange` | `string[]` of series `dataKey`s, and the legend clicks | kept inside |
| `defaultHiddenSeries` | `string[]` | none |

`stacking` lays the series of a column, bar, line or area chart on top of one
another, or as shares of 100% with a percent axis. It needs two or more series
and leaves combination charts alone. Negative values stack below zero, a
missing value leaves a gap, and the tooltip shows the real value with the share
beside it.

A filling chart is sized by a `ResizeObserver`, which never fires while the
chart is hidden (an inactive tab, a collapsed panel), so it draws nothing until
shown. Pass both `width` and `height` to draw at a fixed size straight away.
`animate={false}` turns off the entry animation, for dashboards that redraw
often and for images taken right after mount.

`format` takes the same shape the chart panels edit: a title above the chart,
axis titles, the legend at the top, bottom, left or right (or `'none'`), and
data labels, and `valueScale: 'log'` for a logarithmic value axis (zero and
negatives are left out; stacked charts stay linear). It also takes the text
(`font: { family, size, color, bold, italic }`), the category-label angle
(`labelAngle: 'auto' | 0 | 45 | 90`), the grid (`gridLines: 'value' | 'both' |
'none'`, `gridDashed`) and the series lines (`lineWidth`, `lineDashed`,
`fillOpacity`), and the series colours: `palette` names a set — `'theme'`,
`'classic'`, `'colorblind'` (the Okabe–Ito hues), `'vivid'` or `'monochrome'` —
whose colours are kept at 3:1 contrast with the chart background, and `colors`
gives your own list, used exactly as given. A field left out keeps the chart's
own look. The JavaScript grid's chart panel edits all of them (its Format
dialog has a Colours picker) except the font family, bold or italic text and
`colors`. Pass `fields` (the grid's current fields) and tooltips and labels
print each series the way its measure prints in the grid, using the field's
`format`. Without `fields` they use the locale's number format.

A click on a category — a bar, a slice, a dot-plot point or a shape cell —
calls `onCategoryClick` with the category and the row values behind it, ready
to filter the pivot by:

```tsx
<ChartFactory
  type="column"
  data={chart.chartData}
  series={chart.chartSeries}
  onCategoryClick={({ path }) =>
    path.forEach((p) => controller.applyFilter(p.fieldId, new Set([p.value]), 'include'))
  }
/>
```

`path` has one entry per row field, so a click on "EMEA - Q1" names both the
region and the quarter. It is empty for the grand total.

With `onCategoryClick` set, the chart is also **one tab stop**: the arrow keys
(and <kbd>Home</kbd> / <kbd>End</kbd>) move a focused category, a chip at its
top names it with its values and position ("APAC: Revenue 30 — 2 of 3"), its
bars or slice are outlined, and <kbd>Enter</kbd> or <kbd>Space</kbd> calls
`onCategoryClick` exactly as a click would. The chip is a live region, so a
screen reader says the same; it speaks the `locale` you pass, in the twelve
languages. Without `onCategoryClick` the chart is not wrapped and takes no
keys.

Everything about the chart is already your state — the type, stacking and
format are props — except which series the reader switched off in the legend.
Pass `hiddenSeries` with `onHiddenSeriesChange` to own that too and save it with
the rest; the keys are the series' `dataKey`s, the ones the JavaScript panel's
`getChartState()` uses.

### A chart in a window

`ChartWindow` puts a chart in a window over the pivot: moved by its title bar,
resized from its corner, both from the keyboard too (arrow keys on its two
grips), and always kept inside its parent. Several windows are several charts —
the last one touched comes to the front.

```tsx
import { ChartWindow, ChartFactory } from '@kanunilabs/pivotgrid-react-enterprise';

<div style={{ position: 'relative', height: 600 }}>
  <EnterprisePivotGrid /* … */ onChartSync={setChart} />
  {windows.map((w) => (
    <ChartWindow
      key={w.id}
      title={w.title}
      defaultRect={w.rect}                  // { x, y, width, height }; centred without it
      onRectChange={(rect) => save(w.id, rect)}
      onClose={() => remove(w.id)}
      toolbar={
        <select value={w.type} onChange={(e) => setType(w.id, e.target.value as ChartType)}>
          <option value="column">Column</option>
          <option value="pie">Pie</option>
        </select>
      }
    >
      <ChartFactory type={w.type} data={chart.chartData} series={chart.chartSeries} />
    </ChartWindow>
  ))}
</div>
```

The window is positioned inside its **parent**, and makes the parent a
positioning box while it is mounted if it is not one already. `defaultRect` is
read once; after that the window is the user's to move, and `onRectChange`
reports each finished move or resize so you can open it there next time.
`labels` names the grips and the close button in your language
(`{ move, resize, close }`; English by default).

In the JavaScript package there is no charting peer: `@kanunilabs/pivotgrid-enterprise`
draws the fifteen types as its own SVG and exports them as PNG or SVG — see
[Charts without a charting library](https://kanunilabs.com/docs/pivotgrid/javascript#charts-without-a-charting-library).

## Row sparkline

A pivot row already holds a series: one value per column, month after month.
`rowSparkline` draws it small in the row's grand-total cell, in front of the
total, so you can see at a glance which rows rise and which fall:

```tsx
<EnterprisePivotGrid licenseKey={key} data={rows} initialFields={fields} rowSparkline />

// or pick the measure, bars instead of a line, and the size
<EnterprisePivotGrid rowSparkline={{ field: 'units', type: 'bar', width: 72, height: 18 }} … />
```

`createEnterprisePivotGrid(host, { rowSparkline: true, … })` takes the same
option. The trend runs over the columns on screen, in their on-screen order: a
collapsed column group is one step, an expanded one is its children, and totals
are left out. Each row has its own scale, because the line shows the shape and
the total beside it shows the size. A month with no data leaves a gap in the
line. A negative bar takes the theme's danger colour.

It needs the grand-total column (`showColumnGrandTotals`, on by default) and at
least two columns. The grand-total column keeps its width, so give it more
room (`setColumnWidths`) if the totals are long. It is drawn through the
`cellRender` plugin socket: pass your own `registry` and the sparkline
registers into it. A measure with its own `cellTemplate` keeps that template.

## What these do not do

### Both

- **There is no server-side data source.** `data: TRow[]` in memory is the only
  input — to the grid, to drill-down and to charts. PivotGrid has no remote row
  model at all. Size your dataset accordingly.
- **Object identity is load-bearing.** `chartIntegrationOptions` is in the
  memo's dependency list, so an inline literal recomputes the transform every
  render and re-fires `onChartSync` — which typically sets state, which
  re-renders. Memoise it.
- **No keyboard or screen-reader path into either.** The drill-down modal has
  no `role="dialog"`, no focus trap and no focus restore; the chart emits no
  `role`, no `aria-label` and no tabular fallback, so its numbers exist only as
  SVG geometry.
- **Neither inherits the grid's theme**, and in fullscreen the drill-down modal
  portals to `document.body` — outside the fullscreen element, so it is not
  visible. Wrap them in your own `PivotThemeProvider`.
- **Everything is hardcoded English** — the whole drill-down modal and the
  chart type selector. Neither goes through the dictionary.

### Drill-down

- **Clicking a grand-total cell hands you the entire filtered dataset.** The
  row path is empty, so both match loops run zero times and nothing narrows.
  The modal then renders it unpaginated — one `<tr>` per source row, with no
  cap and no warning. Guard on `cellType` and on `records.length`.
- **Reading `records` scans the whole dataset once, on the main thread.** The
  rows are found rather than remembered: the cell's path is matched first and
  the filters run only on what matched. About 30–60 ms per read on a million
  rows on a recent laptop; the same event's second read is free.
- **Columns are inferred from the first record only** — `Object.keys(records[0])`
  — so heterogeneous records lose the keys the first one lacks. Headers are
  produced by capitalising the key.
- **An empty record set renders nothing and says nothing.** The modal returns
  `null`, so your state says a dialog is open and the screen shows none.

### Charts

- **No transformer means an empty chart.** `usePivotChartSync` needs
  `chartIntegrationOptions.transformer`; without one it returns no data and
  warns once in the console.
- **Series are capped.** `maxPoints` caps the categories (default 100) and
  `maxSeries` the series (default 20). The hook's result reports both
  (`isSampled` of `totalArgs`, `isSeriesSampled` of `totalSeries`), so say
  so when the chart shows part of the pivot.
- **Colours follow the theme only when asked.** Without `palette` the
  transformer's eight colours are used, wrapping, so series nine repeats series
  one's. `palette="theme"` derives them from the theme instead.
- **Cross-filter is yours to apply.** `onCategoryClick` reports the category
  and the row values behind it; the factory filters nothing itself (the
  JavaScript panel does, with `chartCrossFilter`). Lines and areas have no mark
  to click.
- **`ChartFactory` is headless.** It draws a chart; maximising, a type picker
  and export buttons are the app's (`ChartWindow` is the window to put it in). The exporters are exported
  (`exportChartPng`, `exportChartJpeg`, `exportChartSvg`, `chartImageDataUrl`
  for the image as a `data:` URL at a size you choose, and `findChartSvg` for
  the container).

Without a licence key both run watermarked.

---

Source: https://kanunilabs.com/docs/pivotgrid/export

# Styled Excel and PDF export

Three of the ten export formats need the Enterprise package: `excel-list`,
`excel-pivot` and `pdf`. The other seven — CSV, JSON in three shapes, XML,
print and clipboard — are free.

Everything *structural* is in the free core: flattening rows, building merged
headers, resolving values, evaluating conditional-format rules. What Enterprise
adds is the **writing** — ExcelJS and jsPDF, plus a streaming fallback for
large sheets.

## Turning it on

Importing anything from the Enterprise package registers the exporter. There is
no configuration:

```tsx
import { EnterprisePivotGrid } from '@kanunilabs/pivotgrid-react-enterprise';
```

The footer's download menu then enables the three paid entries. From code:

```tsx
const ref = useRef<PivotGridRef<Sale>>(null);

ref.current?.exportData('excel-pivot', {
  fileName: 'Q4-revenue',
  applyFilters: true,
  expandAll: false,
  locale: 'tr-TR',
});
```

`exportData` returns a promise, so you can await it and catch a refusal:

```tsx
try {
  await ref.current?.exportData('excel-pivot', { fileName: 'Q4' });
} catch (err) {
  // A Community grid refuses the three paid formats. See below.
}
```

| Option | Default | Read by the exporter |
|---|---|---|
| `fileName` | `'PivotExport'` | yes — the extension is appended |
| `locale` | `'tr-TR'` | pivot only; the flat list ignores it |
| `applyFilters` | — | yes |
| `expandAll` | — | yes |
| `signal` | — | only at chunk boundaries |
| `onProgress` | — | plumbed, never wired to any UI |

`ExportFormat` and `ExportOptions` come from `@kanunilabs/pivotgrid-core`, not
from the React package.

## What this does not do

### Size silently changes the file

`excel-list` past **100,000 rows** stops producing a real `.xlsx` and starts
producing SpreadsheetML with an `.xls` extension. Same menu item, same name,
different file — and in that format every formatted number is written as a
string, which Excel will not sum.

The pivot equivalent switches at **150,000 materialised cells** and
additionally drops conditional formatting, outline levels, frozen panes and
column widths.

There is no warning at either threshold.

### The file will not match the screen

Absent from every export path:

- `cellTemplate` output — the exporter writes the underlying value
- theme colours
- vertical header merges
- `dataFieldPosition: 'rows'`, which the grid honours and the exporters ignore
- localized total labels — the screen says "Genel Toplam", the file says
  "Grand Total". **Nothing in the export is translated**, although the
  translations exist.
- conditional rules other than `expression`
- when several conditional rules match a cell, the screen merges them all; the
  export applies the first

### Progress and cancellation are not reachable from the UI

The footer menu passes neither `signal` nor `onProgress` — both are fully
plumbed and wired to nothing. You can only use them through your own ref.

Even then, cancellation is coarse: the signal is polled at chunk boundaries and
not during the three most expensive calls, and aborting discards all work.

### PDF

A wide pivot gets one accommodation: landscape orientation. No page breaking by
column, no scaling, no per-column widths.

**No font is registered**, so non-ASCII text is at risk — worth checking with
Turkish characters before you rely on it, given the default export locale is
`tr-TR`.

### Community refuses, and says so

A Community grid asked for one of the three paid formats gets a rejected
promise naming the format and the package that provides it. The refusal happens
**before** the `exporting` event, so nothing is left waiting on it, and the
rejection is routed to your `onError` handler — or to `console.error` if you
have none.

Until this shipped it was a `console.warn` and a resolved promise, fired *after*
`onExporting` — so a spinner started on that event span forever with a clean
console.

If your application registers its **own** exporter under one of those format
ids, yours wins: the gate looks for a custom exporter first and steps aside.

### It is an edition gate, not a licence gate

An unlicensed Enterprise build still exports — watermarked, not crippled. That
is deliberate and matches DataGrid: a dead feature cannot be evaluated before
purchase.

What the gate closes is the accidental path. The exporter registers itself into
a module-level slot when the Enterprise package is imported, and that slot
cannot tell which grid is asking — so one Enterprise import anywhere used to
enable styled export for every grid in the bundle, Community ones included. The
controller can tell, so the check lives there.

It is not DRM. `exportPivotData`, `PivotExportService` and `getAdvancedExporter`
are public exports of the free package, so deliberate code can still reach the
exporter. Narrowing that is a breaking change and belongs in a major version.

---

Source: https://kanunilabs.com/docs/pivotgrid/ai

# Pivot layout for AI models

"Revenue by region and year, only the top five regions, as a share of the
total." That sentence describes a pivot layout: two fields, one measure with an
aggregate and a display mode, and a sort by value with a cut-off. A language
model can write that layout if it knows exactly what **this** pivot can do.
Three functions give it that:

| Function | What it does |
|---|---|
| `getPivotAiSchema(controller, options?)` | A JSON Schema of the layout, limited to what the fields allow |
| `getPivotAiState(controller, options?)` | The current layout in that shape, for the model to start from |
| `applyPivotAiState(controller, answer, options?)` | Checks the model's answer and applies the valid part |

There is no model inside the grid, and the grid sends nothing anywhere. You use
your own model (any model that supports structured output, or any that can
return JSON) and call it from your own code. Import the functions from
`@kanunilabs/pivotgrid-react-enterprise` or `@kanunilabs/pivotgrid-enterprise`.
They work only on an Enterprise grid's controller. A Community grid's
controller makes them throw an error that names the feature.

## Getting the controller

```tsx
// React
const ref = useRef<PivotGridRef>(null);
<EnterprisePivotGrid ref={ref} licenseKey={key} data={rows} initialFields={fields} />;
const controller = ref.current!.getController();

// JavaScript
const grid = createEnterprisePivotGrid(host, { licenseKey: key, data: rows, initialFields: fields });
const controller = grid.controller;
```

## A round trip

```ts
import { getPivotAiSchema, getPivotAiState, applyPivotAiState } from '@kanunilabs/pivotgrid-react-enterprise';

const schema = getPivotAiSchema(controller);
const current = getPivotAiState(controller);

// On your server: ask your own model, with the schema as its output format.
const answer = await askModel({
  instructions: 'You change the layout of a pivot table. Start from the current layout.',
  input: `Current layout: ${JSON.stringify(current)}\nRequest: ${userText}`,
  outputSchema: schema,
});

const { applied, dropped } = applyPivotAiState(controller, answer);
```

`askModel` stands for your own call to your model's API. `answer` can be the
parsed object or the JSON text the API returns.

## What the schema covers

| Part | Properties | Notes |
|---|---|---|
| `fields` | `rows`, `columns`, `values` | Which fields go where. Each value has an aggregate (`sum`, `avg`, …) and a display mode (`absolute`, `percentOfTotal`, `runningTotal`, …) |
| `filter` | `filters`, `conditions` | `filters` keep (`include`) or drop (`exclude`) listed values of a field. `conditions` keep the members whose total or caption passes a test — the field's [`valueFilter` and `labelFilter`](https://kanunilabs.com/docs/pivotgrid/features#value-and-label-filters). `[]` removes every one |
| `sort` | `sort` | Per row or column field: by the field itself, or by a measure (`byValueField`), with an optional `top` cut-off |
| `totals` | `totals` | Grand total row and column, subtotals, and `tabular` or `tree` row headers |

The schema only offers what the pivot accepts. A text field gets `count` and
`distinct` but never `sum`. A summary-level calculated field can be a measure
but not a row. A field you hid from the field chooser (`visible: false`) is not
offered at all. Every object lists all of its properties as required and allows
no others. That is the subset the strictest structured-output modes accept. The
schema is draft 2020-12.

"Top five regions by revenue" is a sort with `byValueField: 'revenue'` and
`top: 5`. The measure's grand total sets the order, which is what "biggest"
usually means.

"Only the regions that sold over a million" is a condition:

```json
{ "fieldId": "region", "kind": "value", "dataField": "revenue", "operator": ">", "value": 1000000, "value2": null }
```

and "cities starting with A" is
`{ "fieldId": "city", "kind": "label", "operator": "startsWith", "text": "A" }`.
A condition runs before `top`, so the two together read as "the top five of
those over a million". `dataField` must be one of the values on the grid, and a
field can hold one condition of each kind.

## Telling the model more

```ts
const options = {
  exclude: ['totals'],                         // parts the model may not change
  fields: {
    revenue: { description: 'Net revenue in EUR' },
    city: { includeValues: true },             // list its values in the schema
    customer: { exclude: true },               // never mention it; it stays where it is
  },
  maxValues: 50,                               // per field, default 100
};
getPivotAiSchema(controller, options);
applyPivotAiState(controller, answer, options); // same options on the way back
```

**Values are listed only when you ask.** `includeValues` sends a field's
distinct values to whatever model you use, so turn it on only where you are
allowed to share them. Without the list a model has to guess the spelling.
Either way, `applyPivotAiState` checks every filter value against the data, in
the browser. A value that does not exist, such as "Izmit" instead of "Izmir",
is reported in `dropped` and not applied. Without that check, the pivot would
quietly filter down to nothing.

## What `applyPivotAiState` does with an answer

- **Keeps the valid part** and lists everything it left out in `dropped`, in
  words: `values city: sum does not suit a string field`,
  `sort by region: top needs byValueField, kept every value`.
- **Never throws on a bad answer.** Text that is not JSON, or JSON that is not
  an object, returns `applied: []` with the reason.
- **Places fields in one commit.** A field the answer no longer uses goes back
  to the field chooser. A field in the filter area stays there, and so does a
  field you excluded.
- **Changes only the parts the answer mentions.** If an answer has `rows` but no
  `columns`, the column fields stay where they are.

## What it does not do

- **No model, prompt or chat box.** Those belong to your application.
- **No row data.** The model sees fields, and a field's values only when you
  allow it. It never sees rows, so it cannot answer questions about the
  numbers themselves.
- **Not the prefilter or calculated fields.** It does not touch the row-level
  [prefilter](https://kanunilabs.com/docs/pivotgrid/prefilter), and it does not create
  [calculated fields](https://kanunilabs.com/docs/pivotgrid/calculated-fields). It can place existing
  ones.

This page is about AI features inside your app. To help an AI assistant write
code that uses the grid, see [AI coding assistants](https://kanunilabs.com/docs/pivotgrid/ai-assistants).

---

Source: https://kanunilabs.com/docs/pivotgrid/server-side

# Server-side pivot

The PivotGrid normally holds every row in the browser and aggregates them in a
Web Worker. That works well up to several million rows. Past that, or when the
rows must not leave your database, let the **server** do the aggregating. The
grid sends the layout, the server answers with the totals, and the grid lays
them out.

Only the totals ever reach the browser. The first answer is one level deep:
when a group is closed, the grid does not ask for its children. Opening a group
sends one more request.

```tsx
import { EnterprisePivotGrid, pivotServerSource } from '@kanunilabs/pivotgrid-react-enterprise';

const source = pivotServerSource({
  load: (request) => fetch('/api/pivot', { method: 'POST', body: JSON.stringify(request) }).then((r) => r.json()),
  loadFieldValues: (field) => fetch(`/api/pivot/values?field=${field.fieldId}`).then((r) => r.json()),
});

<EnterprisePivotGrid licenseKey={key} serverSource={source} initialFields={fields} />;
```

`data` is not needed. In JavaScript, pass the same `serverSource` to
`createEnterprisePivotGrid`.

Rendering, sorting (by a field or by a measure, with top-N), percent-of-total
and the other display modes, calculated summary fields, charts, the row
sparkline, saved layouts and the pivot exports all work as usual. They run in
the browser on the totals the server sent.

## What the grid asks

Each change sends one `PivotServerRequest`, such as a field moved, a filter
ticked or a group opened:

```ts
{
  rows:    [{ fieldId: 'region', dataField: 'region', dataType: 'string' }, { fieldId: 'city', … }],
  columns: [{ fieldId: 'year', dataField: 'year', dataType: 'number' }],
  values:  [{ fieldId: 'revenue', dataField: 'revenue', dataType: 'number', summaryType: 'sum' }],
  filters: [{ fieldId: 'region', dataField: 'region', type: 'exclude', values: ['APAC'] }],
  prefilter: null,              // the prefilter builder's AND/OR tree, when set
  expandedRows: [['EMEA']],     // open row groups by path, or 'all'
  expandedColumns: [],
}
```

## What the server answers

Your server answers with **cells**. A cell is a row path, a column path and the
measures at that point. You need one cell for every combination the open groups
make visible, including each level's subtotal and the grand totals (the empty
path `[]`):

```ts
{
  cells: [
    { row: [],                 col: [],       values: { revenue: 100 } },  // grand total
    { row: ['EMEA'],           col: [],       values: { revenue: 35 } },   // a row total
    { row: ['EMEA'],           col: [2026],   values: { revenue: 25 } },
    { row: ['EMEA', 'Berlin'], col: [2026],   values: { revenue: 20 } },   // EMEA is open
    { row: [],                 col: [2026],   values: { revenue: 50 } },   // a column total
    // …
  ],
}
```

In SQL this is one `GROUP BY` with grouping sets or `ROLLUP`, one set per
visible level. Apply the filters and the prefilter first. Cells for levels
below a closed group are ignored, so a server that always returns a little more
than was asked is fine.

`rollupInMemory(rows, request)` is the reference implementation. It answers a
request from an array, and its source is the specification. A test in this
repository puts random data through it and through the local engine, and
checks that every visible cell matches for all six aggregates, fully expanded
and filtered. Use it to check your own server: for the same rows, both should
send back the same cells.

## Caching and refresh

`pivotServerSource` keeps the last 16 answers by request (`cacheSize`). Closing
a group and opening it again, or changing totals and sort order, does not ask
the server again. Call `refreshEngine()` (the toolbar's refresh button) when
the data on the server has changed. It clears the cache and asks again. A
failed request is not cached. It shows as an engine error, and the next change
tries again.

## What does not apply

Everything that needs the individual rows in the browser:

- **Custom summaries** (`summaryType: 'custom'`) and **row-level calculated
  fields** (`calculateExpression`). The server computes what it is asked for;
  compute such values there and send them as an ordinary measure.
  Summary-level calculated fields (`calculateSummaryExpression`) work, because
  they combine totals.
- **Drill-down to source rows.** The JavaScript Enterprise grid turns its
  drill-down modal off in server mode, and `cellClick` reports no records.
- **Import, live updates (`applyTransaction`) and raw-row exports.** The pivot
  exports (the layout as you see it) work.
- **The header filter's checklist** shows what `loadFieldValues` returns. Leave
  it out and the list is empty.

---

Source: https://kanunilabs.com/docs/datagrid

# KanuniLabs DataGrid

**KanuniLabs DataGrid** is a high-performance data grid for React and plain
JavaScript. Columns are
encoded into typed arrays and the filter/sort pipeline moves to a Web Worker
once the dataset gets large, so scrolling, sorting and filtering a million rows
stays responsive.

## Why this grid

- **Fast on large data, measurably.** Sort, filter and search over 1,000,000
  rows are timed against the published package. The
  [performance guide](https://kanunilabs.com/docs/datagrid/performance) lists every number, including
  the one-time cost of the first text sort and search, and the command to
  reproduce them.
- **Small DOM.** Rows *and* columns are virtualized. A 100,000-row grid keeps
  roughly 25 rows mounted.
- **Pinned columns that cannot drift.** Pinned columns are sticky cells inside a
  single scroll container — there is no second table to keep in sync.
- **Keyboard and screen-reader ready.** A complete WAI-ARIA grid model, virtual
  focus, and one tab stop for the header instead of one per column.
- **Free core.** Everything on this page is in the free Community package.

## Packages

| Package | Description | License |
|---|---|---|
| `@kanunilabs/datagrid-react` | React components and hooks | Free (proprietary) |
| `@kanunilabs/datagrid` | The same grid without React — [`createGrid()`](https://kanunilabs.com/docs/datagrid/javascript) | Free (proprietary) |
| `@kanunilabs/datagrid-core` | Framework-agnostic engine (comes with either) | Free (proprietary) |
| `@kanunilabs/datagrid-react-enterprise` | Editing, master-detail, charts — React | Commercial |
| `@kanunilabs/datagrid-enterprise` | The same Enterprise features, no React | Commercial |

Installing a renderer pulls in the core automatically:

```bash
npm i @kanunilabs/datagrid-react
```

```bash
npm i @kanunilabs/datagrid
```

## A first grid

```tsx
import { DataGrid, type ReactGridColumnDef } from '@kanunilabs/datagrid-react';
import '@kanunilabs/datagrid-react/styles.css';

const columns: ReactGridColumnDef<Sale>[] = [
  { field: 'id', headerName: 'ID', dataType: 'number', width: 80, pin: 'left' },
  { field: 'product', headerName: 'Product', width: 220 },
  { field: 'revenue', headerName: 'Revenue', dataType: 'number', width: 140 },
];

<DataGrid gridId="sales" dataSource={rows} rowKey="id" columns={columns} style={{ height: 600 }} />;
```

`rowKey` is required — selection and focus are keyed by row identity, which is
what lets them survive sorting and filtering.

## Where to next

- [Installation](https://kanunilabs.com/docs/datagrid/installation) — packages, styles, bundler notes
- [Features](https://kanunilabs.com/docs/datagrid/features) — sorting, filtering, grouping, export
- [Performance](https://kanunilabs.com/docs/datagrid/performance) — the numbers and the techniques
- [FAQ](https://kanunilabs.com/docs/datagrid/faq)
- [Playground](https://kanunilabs.com/playground/datagrid) — try it on 100,000 rows

## Status

The Community edition is feature-complete for its v1 scope. Cell/row/batch
**editing**, master-detail, multi-level grouping, charts and grouping on the
server ship in the [Enterprise edition](https://kanunilabs.com/docs/datagrid/enterprise) — in both
renderers. Loading rows from a server as the user scrolls is Community.

Missing something? [Tell us what you need](https://kanunilabs.com/contact) — feature requests are read
by the people who write the code.

---

Source: https://kanunilabs.com/docs/datagrid/installation

# Installation

Install the React bindings (the framework-agnostic core comes with them):

```bash
npm i @kanunilabs/datagrid-react
```

(Any package manager works — `yarn add` / `pnpm add` too.)

React is the only required peer dependency. There are no other runtime
dependencies to install.

**Not using React?** `@kanunilabs/datagrid` is the same grid over the same
engine, driven by a plain `createGrid()` call — no framework peer at all. The
[JavaScript guide](https://kanunilabs.com/docs/datagrid/javascript) covers it end to end,
including the Enterprise edition via `createEnterpriseGrid()`.

```bash
npm i @kanunilabs/datagrid
```

## Styles

Import the stylesheet once, near your app root:

```ts
import '@kanunilabs/datagrid-react/styles.css';
```

The stylesheet is plain CSS scoped under `.kanuni-datagrid-root`, so it cannot
leak into your app and your app's CSS cannot leak into the grid. Theming is done
with CSS custom properties — see [Features → Theming](https://kanunilabs.com/docs/datagrid/features#theming).

## The Web Worker: nothing to configure

Above roughly 20,000 rows the grid moves filtering and sorting into a Web
Worker. The worker is compiled into the package and started from a Blob URL, so
there is no file to copy, no bundler recipe and nothing to import — Vite,
webpack, Next.js and Parcel all work as they are.

You can still control the offload:

```tsx
<DataGrid worker={{ enabled: false }} />          {/* always main thread */}
<DataGrid worker={{ threshold: 50_000 }} />        {/* offload later */}
```

### If you have a strict Content-Security-Policy

A Blob worker needs `worker-src` to allow `blob:`:

```
Content-Security-Policy: worker-src 'self' blob:
```

If you cannot change the policy, serve the worker as a file instead. It ships
in the package either way, and pointing at it opts out of the Blob entirely.

**Vite** — import the worker as an asset URL:

```tsx
import workerUrl from '@kanunilabs/datagrid-core/dist/datagrid.worker.js?url';

<DataGrid worker={{ url: workerUrl }} /* ... */ />
```

**Next.js and other bundlers** — copy `datagrid.worker.js` from
`node_modules/@kanunilabs/datagrid-core/dist/` into a served path (e.g. `public/`)
and point at it:

```tsx
<DataGrid worker={{ url: '/datagrid.worker.js' }} /* ... */ />
```

Copy the file again every time you upgrade the package. A copied worker from an
older version keeps answering, but it does not know options added since — for
example, it sorts an `absoluteSort` column by signed value — and nothing reports
the mismatch. A script that copies it on install (`postinstall`) removes the
risk. The Vite import above always follows the installed version.

The same route is worth taking if you would rather serve the worker from a CDN,
so it caches separately from your app bundle.

## Excel export (optional)

CSV export needs nothing extra. For `.xlsx`, install the optional peer:

```bash
npm i exceljs
```

It is loaded lazily, so apps that never export to Excel don't pay for it. If it
isn't installed, the Excel path reports an actionable error and CSV keeps working.

## TypeScript

Types ship with the packages — no `@types/*` needed. The public API is fully
typed, including `GridColumnDef`, `ReactGridColumnDef`, the filter AST and every
event payload.

## Server-side rendering

The grid renders on the server without a worker or DOM measurement and
hydrates normally. Popups are created on mount, so nothing is portaled during SSR.
See [SSR & bundlers](https://kanunilabs.com/docs/datagrid/ssr) for the Next.js and Vite specifics.

Next: [explore the features](https://kanunilabs.com/docs/datagrid/features).

---

Source: https://kanunilabs.com/docs/datagrid/browser-support

# Supported browsers

The DataGrid targets the current versions of the evergreen browsers:
**Chrome, Edge, Firefox and Safari**. Internet Explorer and the original,
pre-Chromium Edge are not supported: the packages are compiled to modern
JavaScript (ES2022 and later) and ship no polyfills.

This applies to every DataGrid package: React and plain JavaScript, Community
and Enterprise, the npm builds and the `<script>` tag builds.

## Oldest browser versions

| Browser | Oldest version | Set by |
| --- | --- | --- |
| Chrome, Edge | 111 | `color-mix()` in the stylesheet |
| Firefox | 113 | `color-mix()` in the stylesheet |
| Safari (macOS and iOS) | 16.2 | `color-mix()` in the stylesheet |

Two Enterprise features need a newer Firefox:

- **Paste** reads the clipboard with `navigator.clipboard.readText()`, which
  Firefox has from version 125.
- **The validation message of a cell being edited** relies on `:has()` (Firefox
  121) to lift the edited row above the next one, so the message is not
  covered.

These numbers come from the code, not from a test run on those versions. Each
one is the first release of that browser that supports every feature the
shipped packages use, according to MDN's browser compatibility data. An older
release is missing at least one of them.

## What the grid needs from the browser

Required:

| Feature | What it is for |
| --- | --- |
| Modern JavaScript (ES2022 and later) | Everything. Without it the script does not load. |
| `color-mix()` in CSS | Tints: the focused row, group rows, the loading overlay. In Enterprise also the selected range, the fill preview and chart ranges. Without it those tints are not drawn. |
| `ResizeObserver` | Measuring the viewport, so the right rows are rendered when the grid changes size. |
| `Intl` | Number and date formatting, and locale-aware sorting. |

Used when available:

| Feature | What it is for | When it is missing |
| --- | --- | --- |
| Web Worker started from a Blob URL | Filtering and sorting above 20,000 rows ([configurable](https://kanunilabs.com/docs/datagrid/installation#the-web-worker-nothing-to-configure)). | The same work runs on the main thread: same results, slower on large data. |
| Clipboard API (`navigator.clipboard`) | Copy, cut and paste. | Browsers offer it only on secure pages (HTTPS or `localhost`). On a plain-HTTP page, copy and paste do nothing. |
| `localStorage` / `sessionStorage` | Remembering the user's layout, when state saving is turned on. | The grid opens with its default layout. Storage errors are never fatal. |
| `crypto.subtle` (Enterprise) | Verifying the licence key. | Browsers offer it only on secure pages. Elsewhere a bundled JavaScript verifier checks the same signature; see [Plain HTTP and intranets](https://kanunilabs.com/docs/datagrid/enterprise#plain-http-and-intranets). |

## Content-Security-Policy

- The shipped JavaScript has no `eval` and no `new Function`, so a `script-src`
  without `'unsafe-eval'` works.
- The worker starts from a `blob:` URL. Allow it with `worker-src 'self' blob:`,
  or serve the worker as a file:
  [Installation](https://kanunilabs.com/docs/datagrid/installation#if-you-have-a-strict-content-security-policy)
  shows how. If no worker can start, the grid falls back to the main thread.
- The real-browser licence test below runs under this policy:

```
default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
img-src 'self' data:; connect-src 'self'; worker-src 'self' blob:
```

That policy allows inline styles. A policy without `'unsafe-inline'` in
`style-src` has not been tested.

## What is tested

**Unit tests** run in Node in continuous integration, on every push and pull
request to the main branch. Tests that need a DOM use jsdom, a simulated DOM.
jsdom does no layout and no painting, so these tests prove behaviour, not how a
particular browser draws the grid.

**In a real browser:** licence verification. A script drives an installed
Google Chrome against the built packages:

- on a plain-HTTP page, where there is no `crypto.subtle` and the bundled
  JavaScript verifier has to load as its own chunk;
- on a secure page, where WebCrypto is used and that chunk must never load;
- through the npm (ESM) build and through the `<script>` tag (UMD) build;
- under the Content-Security-Policy above, so an `eval` in the verifier would
  fail the run.

This test runs outside continuous integration.

Firefox and Safari are not part of an automated run. If the grid misbehaves in
a browser at or above the versions listed here, [tell us](https://kanunilabs.com/contact) the browser,
its version and what you saw.

---

Source: https://kanunilabs.com/docs/datagrid/upgrading

# Upgrading

## How versions are numbered

- **Patch** (1.4.1 → 1.4.2): fixes.
- **Minor** (1.6.0 → 1.7.0): new features, plus fixes. A fix can change what
  your app sees — an export that now writes real dates, a search that now finds
  more rows. Every such change is listed below, under the version that made it.
- **Major**: none so far.

The packages of one product do not always share a number: in a release, each
package moves by what changed in it. The [changelog](https://kanunilabs.com/changelog) lists the
exact number of every package in each release.

## Upgrade the packages together

The Enterprise packages depend on an **exact** version of the Community ones.
Upgrade every `@kanunilabs/datagrid*` package your app lists in the same
command, to the set one release shipped:

```bash
npm i @kanunilabs/datagrid-react@latest @kanunilabs/datagrid-react-enterprise@latest
```

Upgrading only one of them can install a second copy of the engine next to the
first. Two copies do not share state: a licence key set through one is not seen
by the other. Check that one version is installed:

```bash
npm ls @kanunilabs/datagrid-core
```

One version in the tree is right; two mean a package was left behind.

## What changes for you

The changes below can make an existing app behave or type-check differently
after an upgrade. Versions not listed asked nothing of you. Going from an older
version to the newest, read every entry in between.

(This part is generated when the page renders. See it at https://kanunilabs.com/docs/datagrid/upgrading)

---

Source: https://kanunilabs.com/docs/datagrid/ai-assistants

# AI coding assistants

An assistant writing DataGrid code from memory guesses prop names, and a prop
that does not exist does nothing: no error, no effect. Two things let it look
the names up instead:

- **The MCP server** `@kanunilabs/mcp`: the documentation and the full API
  reference, searchable by the assistant while it works.
- **The skill**: one instruction file the assistant reads when a task involves
  the grid — which package to install, the licence key, the worker, Next.js,
  upgrading.

Neither runs an AI model or calls one. The server runs on your machine and
makes no network requests: the docs are inside the package.

## The MCP server

It covers DataGrid and [PivotGrid](https://kanunilabs.com/docs/pivotgrid/ai-assistants) both, and
carries the docs of the release it was published with.

| Tool | What the assistant gets |
|---|---|
| `search_docs` | Guide sections and API members matching a question in words |
| `get_doc` | One page, or one section of it, as Markdown |
| `get_api` | One exported symbol, or one member: `DataGridProps.columns` |
| `list_docs` | The packages with their versions, the guides, the exported symbols |
| `get_changes` | What changed between two versions, upgrade notes first |

### Claude Code

```bash
claude mcp add kanunilabs -- npx -y @kanunilabs/mcp
```

On Windows outside WSL, `npx` needs a `cmd /c` in front:

```bash
claude mcp add kanunilabs -- cmd /c npx -y @kanunilabs/mcp
```

### Cursor

Add to `.cursor/mcp.json` in the project, or to `~/.cursor/mcp.json` for every
project:

```json
{
  "mcpServers": {
    "kanunilabs": { "command": "npx", "args": ["-y", "@kanunilabs/mcp"] }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "kanunilabs": { "type": "stdio", "command": "npx", "args": ["-y", "@kanunilabs/mcp"] }
  }
}
```

### Other assistants

Any MCP client that starts a local (stdio) server works: the command is `npx`
and the arguments are `-y @kanunilabs/mcp`.

To check it is connected, ask the assistant something only the reference
knows, such as which members `DataGridProps` has.

## The skill

```bash
npx -y @kanunilabs/mcp install-skill
```

This writes `.claude/skills/kanunilabs-grids/SKILL.md`, where Claude Code finds
skills. For an assistant that reads skills from another folder, name it:

```bash
npx -y @kanunilabs/mcp install-skill path/to/skills/kanunilabs-grids
```

A changed copy is not overwritten; run it with `--force` to replace your copy
with the one in the package. The skill tells the assistant to use the MCP
server when it is connected, and the files below when it is not.

## Without either

The same documentation is published for assistants that read the web:

- [/llms.txt](https://kanunilabs.com/llms.txt): every page with one line on what it covers
- [/llms-full.txt](https://kanunilabs.com/llms-full.txt): every guide in one Markdown file

---

Source: https://kanunilabs.com/docs/datagrid/features

# Features

Most of this page is in the free Community package. The sections marked
**Enterprise** need `EnterpriseDataGrid` (React) or `createEnterpriseGrid`
(JavaScript): merged cells, cell notes, Excel and PDF export, multi-level
grouping with group summaries, and the chart panel. In the Community grid
those options are ignored (`debugMode` says so), and `exportToExcel` /
`exportToPdf` throw an error that names the Enterprise package. CSV export is
Community.

## Data

An array is the simple case:

```tsx
<DataGrid dataSource={rows} rowKey="id" />
```

For data that lives on a server, pass a `DataSource` — an object with a
`load(options)` method. The grid hands it `skip`, `take`, `sort`, `filter`,
`searchText` and (when grouping remotely) `group`/`groupKeys`, and expects
`{ rows, totalCount }` back. `createRestDataSource` is that object for an HTTP
endpoint:

```tsx
import { createRestDataSource } from '@kanunilabs/datagrid-react';

const source = createRestDataSource<Order>({ url: '/api/orders' });

<DataGrid dataSource={source} rowKey="id" remote={{ enabled: true }} />
```

It handles three things that are easy to get wrong by hand. Every load
**aborts the one before it**, so typing in the search box cannot leave the grid
showing the results of an earlier query. `sort` and `filter` are **JSON-encoded**
rather than stringified, which is what `URLSearchParams` would otherwise turn
into `[object Object]`. And a non-2xx response **throws**, because `fetch`
resolves on a 500 and the grid would otherwise try to render an error page as
rows.

Adapt it to an existing API without giving up any of that:

```tsx
createRestDataSource<Order>({
  url: '/odata/Orders',
  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
  buildQuery: (o) => ({ $skip: String(o.skip ?? 0), $top: String(o.take ?? 50) }),
  mapResponse: (body) => ({ rows: body.value, totalCount: body['@odata.count'] }),
  byKeyUrl: (key) => `/odata/Orders(${key})`,
});
```

`headers` is re-read per request, so a token refreshed mid-session reaches the
next call. `byKeyUrl` is optional — without it the grid does not offer `byKey`
at all rather than guessing a REST convention that may not be yours.

## Columns

```tsx
const columns: ReactGridColumnDef<Sale>[] = [
  { field: 'id', headerName: 'ID', dataType: 'number', width: 80, pin: 'left' },
  { field: 'product', headerName: 'Product', width: 220 },
  { field: 'revenue', headerName: 'Revenue', dataType: 'number', width: 140,
    valueFormatter: (v) => `$${Number(v).toLocaleString()}` },
  { field: 'status', headerName: 'Status', width: 120, pin: 'right',
    renderCell: ({ value }) => <strong>{String(value)}</strong> },
];
```

`dataType` (`string` · `number` · `bigint` · `date` · `boolean` · `lookup`) drives sorting,
filtering and alignment. `valueFormatter` is the cheap path — it returns a
string and is what export and clipboard copy use. `renderCell` is the expensive
path: arbitrary React per cell.

**Pinned columns** (`pin: 'left' | 'right'`) are sticky cells inside the single
scroll container. Because there is no second table, the header and body cannot
fall out of alignment.

Other per-column switches: `sortable`, `filterable`, `groupable`, `visible`,
`minWidth`/`maxWidth`, `align`, and `calculateSortValue` to sort by a derived key.

### Column widths

A column is `width` pixels wide (150 when not set), and the user can drag its
edge. For a grid that should always fill its container, give some columns a
`flex` instead:

```tsx
const columns: ReactGridColumnDef<Order>[] = [
  { field: 'id', headerName: 'ID', width: 80 },
  { field: 'customer', headerName: 'Customer', flex: 1, minWidth: 160 },
  { field: 'notes', headerName: 'Notes', flex: 2 },
];
```

The columns without `flex` keep their width; the rest of the grid's width is
shared by the `flex` columns in proportion — here Notes gets twice what
Customer gets. It is shared again whenever the grid is resized or a column is
shown, hidden or resized. `minWidth` and `maxWidth` still hold, and when every
flex column is at its `minWidth` the grid scrolls sideways.

When the user drags a flex column's edge, or best-fits that one column, it
keeps the width they gave it and stops flexing; a saved layout remembers that,
and resetting the layout brings the flex back. "Best fit (all columns)" sizes
the fixed columns and leaves the flex ones flexing.

To size every column at once, `autoSizeStrategy` has two modes. `'fitGrid'`
scales the widths you set so they fill the grid, again on every resize.
`'fitCells'` measures the rendered cells once and sizes each column to its
content. A `flex` column is never changed by either.

Both renderers take the same column definitions.

### Large integers

A JavaScript number is exact only up to 2^53 (9,007,199,254,740,991). Past
that it rounds: 9007199254740993 becomes 9007199254740992. A 64-bit id from a
database is often that large, so a column of them needs `dataType: 'bigint'`:

```tsx
{ field: 'trackingId', headerName: 'Tracking ID', dataType: 'bigint' }
```

The values can be `bigint`s or the digits as strings — the form a JSON API
sends them in, since JSON has no bigint. The column sorts by exact value,
filters exactly in the filter row, the header popup and the filter builder,
and right-aligns. Filter values are stored as digits, so a saved view stays
valid JSON. Excel export writes the digits as text, since an Excel number would
round them too.

Footer sum, average, minimum and maximum stay blank on a `bigint` column:
they are JavaScript numbers and would show a rounded result. Count and
distinct count work. Editing keeps a `bigint` cell a `bigint`, and a cell
that held digits as text keeps them as text.

A string column of long numeric ids filters exactly too: two ids that differ
only past the 16th digit never match each other's filter.

### Renaming columns in the grid

**Enterprise.** Let the people using the grid call a column what they call it:

```tsx
<EnterpriseDataGrid columnRenaming />
```

"Rename column" in the header's right-click menu — or <kbd>F2</kbd> on a
focused header — turns the header into a name box. <kbd>Enter</kbd> or clicking
away keeps the name, <kbd>Escape</kbd> keeps the old one, and an empty box goes
back to the name in your column definition. The grid's own columns (selection,
row numbers, commands) and the group column are never offered; pass a function
to choose the rest, `columnRenaming={(columnId) => columnId !== 'id'}`.

The new name is what the grid shows everywhere a column is named — the header,
the column chooser, the group panel, menus, filter descriptions and the headers
of an export. It is part of the column state, so a [saved view](#saved-views)
or a remembered layout brings it back and resetting the columns drops it.
Formulas keep using the names in your definitions, so renaming "Unit price"
does not break `[Unit price] * [qty]`.

Each rename fires `columnRenamed` with the old and new name; from code,
`setColumnHeaderName(columnId, name)` does the same (`null` goes back).

### Multi-level headers (bands)

`band` puts a caption row above a group of columns. One string is one level; an
array is several:

```tsx
{ field: 'units',     headerName: 'Units',      band: ['Sales', 'Volume'] },
{ field: 'unitPrice', headerName: 'Unit price', band: ['Sales', 'Money'] },
{ field: 'revenue',   headerName: 'Revenue',    band: ['Sales', 'Money'] },
```

A band is a **path on the column**, not a nested column tree. The list stays
flat, so widths, order, pinning, visibility, saved views, the column chooser
and virtualization all keep working exactly as they do without bands.

Adjacent columns whose paths agree merge into one band cell. Two consequences
worth knowing:

- A band **splits** when a column that is not in it sits between its members —
  a cell spanning a column that does not belong to it would be a lie. Reorder
  the columns together and the cells merge.
- Same-named bands under **different parents** stay separate: `Q1 › Total` and
  `Q2 › Total` are two Totals, never one spanning both quarters.

Bands never cross the seam into a pinned block, and a column with no band at a
given level simply has its own header reach up through it.

### Columns from the data

With an array data source and no `columns`, one column per field is derived
from the rows:

```tsx
<DataGrid dataSource={rows} rowKey="id" />
```

Field names are humanised (`unitPrice` → "Unit price", `SKU` stays "SKU",
`customerId` → "Customer ID") and data types are inferred by sampling — so
sorting a number column is numeric, not lexical. The sample is capped (50 rows
by default) rather than scanning the whole set, a column whose first values are
all `null` keeps looking, and a column that is null all the way down stays
untyped rather than being guessed at.

Tune it with `autoColumns`:

```tsx
<DataGrid
  dataSource={rows}
  rowKey="id"
  autoColumns={{
    sampleSize: 200,
    exclude: ['internalRef', 'rawPayload'],
    defaults: { width: 140 },
  }}
/>
```

A declared `columns` list always wins — this only fills in what you did not
write. A remote `DataSource` must declare its columns: there is nothing to
sample before the first fetch, and inventing them after it would reshape the
grid under the user.

### Row drag & drop

`rowDrag` puts a grip at the start of each row on hover. Drag it to reorder:

```tsx
<DataGrid dataSource={rows} rowKey="id" rowDrag={{ enabled: true }} />
```

**Who owns the order** is the decision to make. With no `onReorder`, the grid
moves its own array — fine when you hand it the data once. With a handler, you
own it and the grid changes nothing:

```tsx
rowDrag={{
  enabled: true,
  onReorder: ({ dragKey, targetKey, position }) =>
    api.move(dragKey, targetKey, position),   // and re-render from your state
}}
```

If you keep the rows in component state, use the handler. Otherwise the next
time you set that state you hand the grid a fresh array in the original order
and every reorder silently disappears.

Reordering the grid's own array **only works on an unsorted view**: with a sort
active the sort decides the order, so the drop would be invisible. Rather than
move a row that visibly snaps back, the grid refuses and says why under
`debugMode`. To reorder a sorted grid, sort by an order field and rewrite that
field from `onReorder` — then the move is what the sort sees.

Dropping in the empty space below the last row sends it to the end.

**Between two grids** — give both the same `group`:

```tsx
<DataGrid gridId="backlog" rowDrag={{ enabled: true, group: 'tasks',
  onAdd: ({ row }) => setBacklog((l) => [...l, row]) }} />

<DataGrid gridId="sprint" rowDrag={{ enabled: true, group: 'tasks',
  onAdd: ({ row, rowKey }) => { setSprint((l) => [...l, row]); removeFromBacklog(rowKey); } }} />
```

`onAdd` fires on the grid that receives the row, with the row itself — no
round trip needed. Removing it from the source is the app's call, because only
the app knows whether a cross-grid drag is a move, a copy, or an assignment.

Two grids without a shared `group` ignore each other, which is what you want
when a page has several unrelated grids.

### Merged cells

**Enterprise.** `spanRows` draws one box over consecutive rows that hold the same value:

```tsx
const columns = [
  { field: 'region', spanRows: true },
  { field: 'product' },
];
```

It is computed over the **current view**, which is the point — sorting a column
into `A A A B B` is what makes the merge meaningful, and the same rows unsorted
merge nothing. Sort, filter or edit and the blocks recompute.

Three rules that a plain "merge equal values" gets wrong:

- **Blanks never merge.** Twelve empty cells are twelve rows that happen to have
  nothing, not one twelve-row empty cell.
- **A group banner interrupts a run.** Rows either side of one are not adjacent
  to a reader, and the block would be drawn straight through it.
- **A run of one is an ordinary cell**, not a one-row block.

Pass a function instead of `true` for values that need their own equality — a
column of objects, or a case-insensitive code:

```tsx
{ field: 'code', spanRows: (a, b) => String(a.value).toLowerCase() === String(b.value).toLowerCase() }
```

**Only the drawing is merged.** Selection, editing, the clipboard and export all
still see the rows your data has — a block over five rows is five cells, which
is what makes it safe to turn on over data you edit.

A block longer than the screen is **clipped to what is rendered**, so the value
stays visible while you scroll through it rather than sitting at a top you
scrolled past. Sorting a million rows by a five-value column is a legitimate
thing to do; drawn at full height that block would be a 38-million-pixel
element.

### Spanning columns

`colSpan` draws a cell across the columns after it. It is asked per row, so a
section heading can run across the grid while the rows under it stay cell by
cell:

```tsx
{
  field: 'title',
  colSpan: ({ row }) => (row.kind === 'section' ? 4 : 1),
}
```

The answer counts the cell itself; anything below 2 is an ordinary cell. The
cell is drawn at the width of the columns it covers, and the covered cells are
not drawn — on screen, and for a screen reader, which hears one cell with
`aria-colspan`. The arrow keys step over the whole span.

A span stays inside its block: it never runs from a pinned column into the
scrolling ones, and it stops at a `sticky` column. A longer answer is cut
there. A span that starts left of the columns on screen is still drawn when
you scroll sideways.

As with merged cells, **only the drawing spans**. Sorting, filtering, copying
and export see every column of the row, the covered ones included.

### Tooltips

With nothing configured, a cell whose text does not fit shows it in full in a
tooltip. A column can say something else:

| Column option | Shows |
|---|---|
| `tooltip: 'text'` or `tooltip: (ctx) => text` | Your text; `null` from the function shows none |
| `tooltipField: 'statusDetail'` | Another field of the row |
| `renderTooltip: (ctx) => …` | Rich content — an image, a small table, a link. A React element in React, a DOM node (or text) in plain JavaScript |
| `headerTooltip: 'text'` | The header's tooltip |

The grid-wide `tooltip` option decides how they open:

```tsx
<DataGrid tooltip={{ trigger: 'both', interactive: true, delay: 300 }} />
```

- **`trigger`** — `'hover'` (default), `'focus'` or `'both'`. With focus, the
  tooltip follows the focused cell: arrowing onto a cell opens it, and so does
  tapping a cell on a touch screen, where there is no hover. It is tied to its
  cell with `aria-describedby`, so a screen reader reads it with the cell, and
  <kbd>Escape</kbd> closes it. A cell focused from code while the user is
  elsewhere on the page opens nothing.
- **`interactive`** — the pointer may move onto the tooltip and rest there, to
  select its text or click a link in it; it closes when the pointer leaves it.
  Off by default, so a tooltip never stands between the pointer and the next
  cell.
- **`delay`** (ms, default 400), **`showOnTruncation`** (default true) and
  **`enabled`**.

A [cell note](#cell-notes) outranks all of these: a person wrote it about that
cell.

### Cell notes

**Enterprise.** Prose a **person** attached to a cell — Excel's comments. Not a tooltip: a
tooltip describes what the cell already says, a note is something someone added
that is not in the data, so it carries a corner marker you can see without
hovering.

```tsx
const [notes, setNotes] = useState(new Map<string, string>());
const key = (rowKey, columnId) => `${rowKey}:${columnId}`;

<DataGrid
  dataSource={rows}
  rowKey="id"
  notes={{
    get: ({ rowKey, columnId }) => notes.get(key(rowKey, columnId)) ?? null,
    onChange: ({ rowKey, columnId, text }) =>
      setNotes((prev) => {
        const next = new Map(prev);
        if (text === null) next.delete(key(rowKey, columnId));
        else next.set(key(rowKey, columnId), text);
        return next;
      }),
  }}
/>
```

**Storage is yours.** The grid renders notes, reveals them on hover and collects
edits; it does not decide where they live, because a note that survives a reload
has to go somewhere only your app knows about.

`get` runs for every rendered cell, so make it a lookup — a `Map` keyed by
`rowKey:columnId` is the shape that fits. Anything that scans turns a viewport
into quadratic work.

Giving `onChange` is what makes notes **editable**: the grid then adds Add /
Edit / Delete to the row context menu for the cell under the pointer.
Ctrl+Enter saves, Escape cancels, and saving an empty note deletes it — a marker
on a cell whose note says nothing lies about there being something to read. Pass
`menu: false` to place those actions yourself.

A note **outranks** the column's `tooltip`, its `tooltipField` and the clipped
text. Those describe the column or repeat what is on screen; neither should hide
something a person wrote.

### Aligned grids

Two grids that have to read as one table — a scrolling body with a fixed totals
strip under it, a master and a detail over the same columns. Give them the same
name:

```tsx
<DataGrid gridId="body"   dataSource={rows}   columns={cols} alignedGrids="sales" columnResize />
<DataGrid gridId="totals" dataSource={totals} columns={cols} alignedGrids="sales" />
```

Resize, move, hide or pin a column in one and the others follow; scroll one
sideways and the others keep pace.

**Sort, filter, selection and vertical scroll deliberately do not travel.**
Aligned grids share a shape, not a result — a totals strip that re-sorted itself
because the grid above it did would be answering a different question. Columns a
peer does not have are ignored, so a three-column strip aligns under a
twelve-column grid.

### Row numbers

`rowNumbers` adds a leading column numbering the rows:

```tsx
<DataGrid dataSource={rows} rowKey="id" rowNumbers />
```

The number is the row's position in **what is shown**. It renumbers after a
sort or a filter, because that is what people mean by "the third row" — they
mean the third one on screen. If you need a number that follows a record
around, that is a column of your data, not this.

Three things follow from that:

- **Pagination continues the count.** Page 2 of 50 starts at 51. A second page
  starting at 1 again tells you nothing about where you are.
- **Group headers get no number.** A banner is not a record, and numbering it
  would push every row below it one past the count in the footer.
- **Pinned rows get no number.** They sit outside the result rather than at a
  position in it — otherwise a pinned row and the first data row would both
  claim to be row 1.

## Sorting

Click a header to cycle ascending → descending → unsorted. With
`sorting={{ multi: true }}`, <kbd>Shift</kbd>+click adds a second key and the
header shows its position.

Sorting is `Intl.Collator`-based for text, chronological for dates, and blanks
always sort last regardless of direction.

### Sorting by magnitude

A variance or profit-and-loss column usually wants its biggest movements
together, whatever their sign. `absoluteSort` orders a number column by its
absolute value — −50 and +50 sit side by side, and descending puts the largest
deviation first:

```tsx
const columns = [
  { field: 'account', headerName: 'Account' },
  { field: 'variance', headerName: 'Variance', dataType: 'number', absoluteSort: true },
];
```

The cells still show their sign; only the order changes. Blanks stay last, and
two values of the same size keep their data order. It applies to
`calculateSortValue` when the column has one, and gives the same order whether
the grid sorts on the main thread or in its Web Worker. It is ignored on a
column with a `comparator` (the comparator decides) and on a column you group
by, where −50 and +50 are two different groups. A server-side `DataSource`
sorts the way your server does.

### The click cycle

By default a header click steps ascending → descending → unsorted. Change it for
every column with `sorting.cycle`, or for one column with `sortCycle`; the
column wins:

```tsx
<DataGrid
  sorting={{ cycle: ['asc', 'desc'] }} // never back to unsorted once sorted
  columns={[
    { field: 'name', headerName: 'Name' },
    // A figures column whose first click should show the largest.
    { field: 'revenue', headerName: 'Revenue', dataType: 'number', sortCycle: ['desc', 'asc', null] },
  ]}
/>
```

`null` is "unsorted". Each click moves to the next entry, wrapping round; a
column whose state is not in its cycle starts at the first entry. The cycle only
governs the header click — `setSort()` can still set any direction.

### Reordering after the sort

`sorting.postSort` gets the final say on the order. It receives the filtered rows
in sorted order and may rearrange them in place or return them in a new order —
the classic case is a "Total" row that stays at the bottom whichever way a column
is sorted:

```tsx
const totalLast = (rows) => [
  ...rows.filter((row) => !row.isTotal),
  ...rows.filter((row) => row.isTotal),
];

<DataGrid sorting={{ postSort: totalLast }} />;
```

- It must return the **same rows**. An answer that adds or drops a row is
  ignored — the grid keeps its own order and says so once in the console.
- It runs on every pass, also when nothing is sorted, so a pinned-last row stays
  last in every view. The second argument says which sort is active:
  `postSort(rows, { sort, group })`.
- With grouping on, it is called once per group with that group's rows, and
  `group` names the group. A row can never be moved out of its group.
- Large grids sort in a Web Worker, and a function cannot be sent there. The
  hook therefore runs on the main thread **after** the worker's answer: the
  worker still does the sorting, and reordering a sorted list is cheap. Keep it
  fast and free of side effects.
- In React the grid always calls the function from the latest render, without
  re-sorting just because a new function arrived. When the rule itself changes
  (a "keep totals last" toggle), call `controller.refresh()`. In JavaScript,
  `grid.controller.setPostSort(fn)` replaces it and re-sorts.
- Client data only: a server-side `DataSource` returns rows in its server's
  order, and the grid warns if both are configured.

### Row animation

```tsx
<DataGrid animateRows />
```

When a sort, a filter, a grouping or a data change puts the rows in a new
order, each row on screen glides from its old place to its new one instead of
jumping, and rows that come into view fade in. It is how a reader follows a
row they were looking at through the reorder.

Off by default, and off whenever the operating system asks for reduced motion.
Only the rows on screen move — the rest of a million-row result is not
animated, so the cost does not grow with the data. Scrolling never animates.

It also matters for **Core Web Vitals** on a page with live data. When rows
arrive or reorder with no click or key press from the visitor — a feed, a
timer, a server push — the browser counts every row pushed down as layout shift
(CLS). The React grid moves its row elements, so each inserted row costs about
0.01 on a desktop screen and 0.017 on a phone (measured in Chrome). With
`animateRows` the rows travel by transform, which the browser does not count:
the same page measured 0. A visitor who asks for reduced motion gets no
animation, and the shifts count again.

## Filtering

Three independent mechanisms, combined with AND:

**Filter row** (`filterRow`) — one input per column. Numeric and date columns
accept operator prefixes:

```
>=100      <50      <>0      2024-01-01
```

A date column's box also takes a **relative period** by name, in the grid's
language or in English: `this month`, `last week`, `the last 30 days` (`bu ay`,
`geçen hafta` and `son 30 gün` in a Turkish grid). The box suggests the names
as you type. The filter keeps its meaning: "this month" set today still means
this month next month. It is stored as a `period` condition (see the
[filter builder](https://kanunilabs.com/docs/datagrid/filter-builder)). In the React grid, a period
restored from a saved view shows its name in the box again.

**Header filter popup** (`headerFilter`) — an Excel-style checklist of the
column's distinct values, with a search box. The list is complete — every
distinct value, even when every row is unique: it's windowed (~20 DOM nodes at
any length), and on large columns it's prepared in background slices behind a
loader so the page never freezes. Fully keyboard-driven: arrows to move,
<kbd>Space</kbd> to toggle, <kbd>Backspace</kbd> to jump back into the search
box, <kbd>Enter</kbd> to apply. Open it from the keyboard with
<kbd>Alt</kbd>+<kbd>↓</kbd> on a focused header.

**Programmatic filters** — a serializable AST:

```tsx
controller.setFilter({
  logic: 'and',
  nodes: [
    { columnId: 'region', operator: '=', value: 'Marmara' },
    { columnId: 'revenue', operator: 'between', value: [1000, 5000] },
  ],
});
```

Operators: `=` `<>` `>` `>=` `<` `<=` `contains` `notcontains` `startswith`
`endswith` `isnull` `isnotnull` `in` `between`.

**Free-text search** scans every visible column:

```tsx
controller.setSearchText('istanbul');
```

It matches **what the cell shows** as well as the stored value: a lookup
column's label, a `valueFormatter`'s output and a date column's `dateFormat`
rendering. A date stored as `2026-09-22` and shown as `22.09.2026` is found by
`22.09`; an object column formatted with `JSON.stringify` is found by the text
inside it. The stored value still matches too.

Matching ignores case, and treats **İ, I, ı and i as one letter**:
`istanbul` finds `İSTANBUL`, and `yilmaz` finds `Yılmaz`. Plain lower-casing
cannot do this — `"İ".toLowerCase()` is an `i` followed by a combining dot — so
without it a Turkish search found nothing. The same rule applies to the
`contains` / `startswith` / `endswith` filters and to the search box in the
header filter popup; `=` and `in` stay exact.

Formatted text is searched at a cost. Below the worker threshold the formatter
runs per row per keystroke; above it, each formatted column gets a text lane
the first time a search runs — measured at about a second per column at a
million rows (an `Intl` currency formatter), paid once and kept up to date
through edits.

### Reading a filter back

`describeFilter` turns the AST into a sentence, resolving column ids to their
header names and lookup codes to their labels — so a user who arrives at a grid
showing 12 of 100.000 rows can see *why*:

```tsx
describeFilter(controller.getFilter(), controller.getColumnModel());
// "Revenue > 50000 and (Region is Marmara or Region is Aegean)"
```

`EnterpriseDataGrid` already shows this above the grid when `filterBuilder` is
on. Pass `labels` to translate the operator words, and `maxListValues` to
change when a long `in` list collapses to "5 values".

### Find without filtering

**Enterprise.** Quick search narrows the rows; find leaves every row where it
is and steps through the cells that contain the text, the way Ctrl+F does in a
spreadsheet:

```tsx
<EnterpriseDataGrid find />
```

Ctrl+F (⌘F) inside the grid opens a find bar above it. Every matching cell is
tinted, the current one stronger, and the bar counts them ("3 of 17"). Enter and
Shift+Enter — or F3 and Shift+F3 — move to the next and previous match and
scroll to it; Escape closes the bar and leaves keyboard focus on the current
match. The browser's own find cannot do this on a grid: it only sees the rows
that are drawn.

It matches what a cell **shows** — a lookup's label, a formatted number, a
formatted date — with the same case folding as quick search, so "istanbul"
finds "İSTANBUL". It searches the rows the grid displays: the current page, and
not the rows inside a collapsed group. A new sort, filter or data change
updates the matches, and the current one stays current while it still matches.

From code, without the bar: `setFindText(text)`, `findNext()`,
`findPrevious()`, `clearFind()`, `getFindState()` and the `findChanged` event.

## Grouping and summaries

```tsx
<DataGrid grouping={{ groupBy: 'region', panel: true }}
          summaries={[{ columnId: 'revenue', type: 'sum' }]} />
```

Single-level grouping produces collapsible group headers with member counts.
The group panel lets users drop a column to group by it (with a `<select>`
fallback so it works from the keyboard).

Footer summaries support `sum` `avg` `min` `max` `count` `countDistinct`, plus
`type: 'custom'` with a `calculate` function that receives the visible cells in
view order. Blanks are skipped rather than counted as zero, so `[10, null, 20]`
averages to 15 — spreadsheet semantics.

Above ~100k rows the summary pass streams in slices so the rows never wait for
the footer: `contentReady` fires first, the totals land moments later with a
`summariesChanged` event. Sorting re-runs a custom summary by default because
its cells arrive in view order; if your `calculate` doesn't care about order
(sums, ratios, averages), declare `dependsOnOrder: false` and re-sorting skips
it entirely.

Multi-level grouping and per-group aggregates are Enterprise features — pass a
`groupBy` array and `groupSummaries: true` to `EnterpriseDataGrid`. The
Community grid clamps `groupBy` to its first level and ignores `groupSummaries`
rather than half-honoring them.

## Cell context menu

Right-click a cell (or press <kbd>Shift</kbd>+<kbd>F10</kbd>) and the grid
offers its own clipboard and export entries, below whatever `rowMenu` supplies:

| Entry | Tier | Notes |
|---|---|---|
| Copy | Community | The selected cells, or the selected rows when there is no range. Same code path as <kbd>Ctrl</kbd>+<kbd>C</kbd>. |
| Copy with headers | Community | One header line above the values. |
| Copy with group headers | Community | Band captions above the header line. Hidden on a grid with no bands, where it would be identical to the entry above. |
| Export ▸ | Community | CSV, Excel, Excel (selected rows), PDF — the same four the toolbar offers. "Selected rows" is disabled with an empty selection. |
| Cut · Paste | Enterprise | Write through the editing engine — one undo step, and validation applies, so a required field refuses to be emptied. Shown only on a cell the permissions allow writing. |
| Chart selected cells ▸ | Enterprise | Opens the chart panel over the selected cells — their columns, and their rows when the range spans several — in the type you pick. |

```tsx
// Every entry is on by default; this REMOVES rather than opts in.
<DataGrid cellMenu={{ copyWithGroupHeaders: false, export: ['csv', 'excel'] }} />
<DataGrid cellMenu={false} />   // no built-ins; `rowMenu` still shown
```

**Excel and PDF need their optional peers.** `exceljs` and `jspdf` +
`jspdf-autotable` are optional `peerDependencies`, so on a project that never
installed them those two entries throw when pressed. The grid does not hide
them for that: it shows the writer's message — which names the package and the
install command — in an alert at the menu's corner, and logs it. Narrow the
list with `export: ['csv']` if you know the peers will never be there.

**"Chart selected cells" charts the range's rows.** A range over several rows
charts exactly those rows (`source: 'range'`), and the grid paints the cells the
chart reads; a single row, or a column picked from the header menu, charts the
current view. See
[Charting a cell range](https://kanunilabs.com/docs/datagrid/charts#charting-a-cell-range).

**Chrome columns never reach the clipboard.** The command column and the
row-number column are real columns in the model (that is what makes width,
order and pinning work for them), but they hold buttons, not data — copying a
row emits the data columns only.

## Selection and keyboard

```tsx
<DataGrid selection={{ mode: 'multiple', checkboxColumn: true }} />
```

<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+click toggles a row and <kbd>Shift</kbd>+click
extends a range. A **plain** click depends on `rowClick`:

| `rowClick` | A plain click… | Default when |
|---|---|---|
| `'replace'` | makes that row the whole selection | no checkbox column |
| `'toggle'` | adds or removes that one row | `checkboxColumn: true` |

The checkbox column defaults to toggling because it exists to build a
multi-selection — a click a few pixels outside a box should not wipe three
ticked rows. A screen whose actions want exactly one row (an "Edit" button that
shows only for a single selection) sets it back:

```tsx
<DataGrid selection={{ mode: 'multiple', checkboxColumn: true, rowClick: 'replace' }} />
```

**The header checkbox** follows one rule: if anything is selected, a click
**clears** the selection; if nothing is, it selects every row the current
filter matches. So from the mixed (partially selected) state the first click
clears and the second selects all — the opposite of what some users expect
from a mixed box, so say so in your UI if it matters.

`selection.mode` can change at runtime; switching to `'none'` clears the
selection. Selection is keyed by **row identity**, so it survives sorting,
filtering and data updates.

### Rows that cannot be selected

`isRowSelectable` decides which rows may be selected — a closed order, a locked
record, a row the user has no rights to:

```tsx
<DataGrid
  selection={{
    mode: 'multiple',
    checkboxColumn: true,
    isRowSelectable: (order) => order.status !== 'closed',
  }}
/>
```

Every way of selecting respects it. The row's checkbox is drawn disabled; a
click, <kbd>Space</kbd> and <kbd>Shift</kbd>+click range pass over the row;
select-all and a group's checkbox skip it; `selectRow`, `toggleRow` and
`setSelectedKeys` ignore it. The selected count and the header checkbox count
the selectable rows only, so after select-all the header box reads "all", and
it is disabled when nothing in the result can be selected.
`controller.isRowSelectable(key)` and `getSelectableCount()` give your own UI
the same answers.

The rule is asked again whenever the data changes — `setData`, a transaction, a
saved edit — and a selected row it now refuses is deselected. When the rule
depends on something else (the user's role changed), pass a new function in
React, or call `controller.setRowSelectable(rule)` in JavaScript; the grid
re-asks every row and repaints. Answers are remembered per row until the data
changes, so keep the function cheap and free of side effects, and give React a
stable one (`useCallback`) so it is not re-asked on every render.

With `selection.deferred`, "everything matching" excludes the refused rows, and
`getSelectionDescriptor()` lists them among the exclusions — a server applying
the descriptor will not touch rows the user could not tick. On a server-side
`DataSource` only loaded rows can be asked, so the server should apply the same
rule.

The full keyboard model:

| Key | Action |
|---|---|
| <kbd>↑</kbd> <kbd>↓</kbd> <kbd>←</kbd> <kbd>→</kbd> | Move focus |
| <kbd>Page↑</kbd> <kbd>Page↓</kbd> | Move a page |
| <kbd>Home</kbd> / <kbd>End</kbd> | Row start / end |
| <kbd>Ctrl</kbd>+<kbd>Home</kbd> / <kbd>End</kbd> | Grid start / end |
| <kbd>Space</kbd> | Toggle selection (or expand a group) |
| <kbd>→</kbd> / <kbd>←</kbd> on a group or tree node | Open / close it; <kbd>←</kbd> on a closed tree row goes to its parent. On a tree row only in the first column, where the toggle is |
| <kbd>Shift</kbd>+<kbd>↑</kbd>/<kbd>↓</kbd> | Extend selection (with Enterprise range selection on: grow the cell range, <kbd>←</kbd>/<kbd>→</kbd> too) |
| <kbd>Ctrl</kbd>+<kbd>A</kbd> | Select all |
| <kbd>Ctrl</kbd>+<kbd>C</kbd> | Copy as TSV |
| <kbd>Esc</kbd> | Clear selection |
| <kbd>Alt</kbd>+<kbd>↓</kbd> | Open the header filter (on a header) |

## Accessibility

`role="grid"` with `aria-rowindex` / `aria-colindex` / `aria-rowcount`,
`aria-selected` on rows, and a polite live region announcing row counts, sort
changes and selection size — in the grid's `locale`, from the same dictionary
as the rest of its text (`announceRows`, `announceSortedBy`, `announceSelected`,
`announceAscending`, `announceDescending`; override them through `messages`).

Focus inside the grid is **virtual** (`aria-activedescendant`) because moving
real DOM focus would fight row virtualization. The header uses a roving
tabindex, so the whole header is one tab stop rather than one per column.

Give each grid a name with `ariaLabel` — it is what a screen reader says when
focus enters the grid. Without it the grid is named by its `gridId`, which is
an identifier rather than words:

```tsx
<DataGrid gridId="orders" ariaLabel="Open orders" /* ... */ />
```

`aria-selected` is written only where rows can be selected: a grid without
selection, and a pinned row, say nothing about it rather than "not selected"
on every row.

From the keyboard, in both the React and the plain JavaScript grid:

| Where | Key | Does |
| --- | --- | --- |
| Header | ← → Home End | Move between column headers |
| Header | Enter, Space (Shift adds a level) | Sort by the column |
| Header | Alt+↓ | Open the column's filter |
| Header, cell | Shift+F10, the Menu key | Open the column's or the cell's menu |
| Menu | ↑ ↓ Home End, → ← | Move through the items, into and out of a submenu |
| Filter, menu | Escape | Close it; focus returns to where it was opened |

## Export and import

```tsx
const { blob, fileName } = await controller.exportToCsv();
downloadBlob(blob, fileName);
```

CSV follows RFC 4180 and is written with a UTF-8 BOM so Excel opens it with the
right encoding. Excel export (`exportToExcel`) needs the optional `exceljs`
peer and writes numbers and dates as real numbers and dates so they stay
computable.

**The CSV delimiter follows the grid's `locale`.** Excel splits a
double-clicked CSV on the *list separator* of the machine's region, and where
the comma is the decimal mark that separator is `;` — a comma-separated file
opens there as a single column. So the default is `;` for `tr`, `de`, `fr`,
`es`, `it`, `pt`, `ru` and `ar`, and `,` for `en`, `ja`, `ko` and `zh-CN` (each
taken from Windows' own regional data). Pass `delimiter` to choose.

**Defaults for the toolbar's buttons.** The export buttons call the export
methods without arguments, so options they should use are set once, per
format:

```tsx
<DataGrid
  onReady={(controller) => {
    controller.setExportDefaults('csv', { delimiter: ';' });
    controller.setExportDefaults('pdf', { font: { family: 'Noto Sans', normal: notoTtf } });
  }}
/>
```

Explicit arguments still win over these. The one-argument form,
`setExportDefaults({ … })`, is the original Excel-only signature and keeps
meaning Excel.

Exports reflect **what you see**: formatted values, visible columns, current
sort/filter/grouping, group subtotals — and the whole result, not just the
current page. Both formats are produced from one model, so they cannot drift
apart.

**Past a million rows, Excel gets more sheets.** An Excel sheet holds 1,048,576
rows, header included; one more and Excel will not open the file. Rows past the
limit continue on `Data (2)`, `Data (3)`… (named after `sheetName`), each with the
header repeated, its own filter and a frozen top row, so every row arrives in a
file Excel opens. `maxRowsPerSheet` sets a lower limit; it is never raised. CSV
has no limit of its own and is not split — Excel cuts a CSV off at the same row
when it opens one.

**Dates are dates in Excel.** In a `dataType: 'date'` column, a `Date`, an ISO
string (`"2011-11-01"`, `"2011-11-01T10:30:00"` — what a JSON API sends) and an
epoch number are written as real Excel dates, so Excel's date filter, sort and
grouping work on them. They land on the same local calendar day and clock time
the grid shows: a bare `yyyy-mm-dd` is that day, not UTC midnight. Text that is
not an ISO date stays text. In CSV and PDF a date column with a `dateFormat`
reads exactly as its cells do.

### Excel: from a dump to a report

**Enterprise**, like every Excel export. Four options turn the sheet into something you can hand to someone.

**Per-cell rules.** `customizeCell` runs for every cell and returns a style to
merge over whatever the writer chose — or nothing, to leave it alone:

```tsx
await controller.exportToExcel({
  styled: true,
  customizeCell: ({ kind, columnId, value }) => {
    if (kind !== 'data' || columnId !== 'revenue') return;
    if (Number(value) < 0) return { fill: 'FFFEE2E2', font: { color: 'FFB91C1C' } };
  },
});
```

`kind` is `header` · `data` · `group` · `totals` · `band`, so a rule can target
the totals row without touching the data. The hook is on the hot path — one
call per cell — so it is skipped entirely when you do not pass one.

**Rows above and below the table**, for a title, a date, a note:

```tsx
headerBlock: [
  { cells: ['Quarterly revenue'], merge: true, style: { font: { bold: true, size: 15 } } },
  { cells: [`Generated ${today}`] },
  { cells: [] },                       // a blank spacer row
],
footerBlock: [{ cells: ['Figures are unaudited.'] }],
```

`merge` spans the row across the table's width. The freeze line and the
auto-filter follow the real header row, so a title above the table does not
push either onto the wrong row.

**A logo**, anchored in sheet coordinates:

```tsx
images: [{ data: base64Png, extension: 'png',
           position: { col: 5, row: 0, width: 90, height: 30 } }],
```

**More than one grid.** A block with a `sheetName` gets its own sheet; without
one it is stacked below the previous block on the same sheet:

```tsx
additionalGrids: [
  { model: summaryModel, title: 'By region', gap: 2 },
  { model: detailModel, sheetName: 'Detail' },
],
```

The auto-filter stays on the first grid's header — Excel allows one per sheet,
and pointing it at a stacked block would filter rows the reader is not looking
at.

A `fileName` that already ends in `.xlsx` is left alone rather than becoming
`report.xlsx.xlsx`.

#### Formulas and links

Calculated columns and cell formulas are written as **Excel formulas** over the
sheet's own cells — `=B2*C2`, `=SUM(C2:C9)` — with the grid's result cached
beside them, so the sheet shows the values at once and keeps calculating when
someone edits it. A formula whose cells are not all in the file (a hidden column,
a filtered-out row) is written as its value, and so is one in a cycle; a range
over a sorted grid is written as the cells it means, and a reference into a
continuation sheet is sheet-qualified. `formulas: false` writes values only. See
[Formulas](https://kanunilabs.com/docs/datagrid/formulas).

A column's `exportLink` makes its cells hyperlinks in Excel and PDF:

```tsx
{ field: 'orderNo', headerName: 'Order', exportLink: (row) => `https://shop.example/orders/${row.id}` }
```

Only `http:`, `https:`, `mailto:` and `tel:` links are written; anything else —
a `javascript:` URL above all — is dropped and the cell stays text. CSV writes
the text.

### Printing

Ctrl+P on a virtualized grid prints the twenty rows that happened to be on
screen, inside a box the browser has clipped to one viewport. `printLayout`
fixes that:

```tsx
<DataGrid dataSource={rows} rowKey="id" printLayout />
```

On `beforeprint` the grid renders **every** row and stops clipping itself, so
the browser paginates real content; `afterprint` puts it back. Scroll position,
selection and filters all survive — only the rendering changed. Controls that
mean nothing on paper (toolbar, pager, resize handles, funnels) are hidden, rows
are kept from splitting across a page break, and background colours are asked
for explicitly so the header and striping survive Chrome's default.

**It refuses above 5.000 rows.** Print layout puts every row in the DOM; at a
hundred thousand that is a frozen tab with a print dialog open, which the user
cannot cancel out of. Past the cap the grid prints what it always did and says
so under `debugMode`. For a result that size use [PDF export](#pdf) — it
streams. Move the line with `printLayout={{ maxRows: 20000 }}` if your rows are
narrow and you have measured it.

**Your own layout has to let go too.** A grid is usually mounted as a flex child
filling a viewport-height shell, and the grid can only unclip itself and its own
wrappers. While printing it marks the root element, so one rule releases yours:

```css
@media print {
  .kanuni-datagrid-printing .my-app-shell {
    height: auto !important;
    overflow: visible !important;
    flex: none !important;
  }
}
```

`printLayout={{ always: true }}` stays in that mode permanently, for rendering a
grid into a report page where there is no print dialog to react to.

### PDF

**Enterprise.** `exportToPdf` needs the optional `jspdf` and `jspdf-autotable` peers — a grid
that never exports PDF should not pay for them, so they are loaded on first use
and a missing install is reported as an install hint rather than a
module-not-found stack.

```tsx
const { blob, fileName } = await controller.exportToPdf();
downloadBlob(blob, fileName);
```

The API is **deliberately the same** as the Excel report's — `customizeCell`,
`headerBlock` / `footerBlock`, `additionalGrids`, `images` — so a report you
have already styled for Excel does not need a second vocabulary:

```tsx
await controller.exportToPdf({
  orientation: 'landscape',          // default; 'portrait' also accepted
  pageSize: 'a4',                    // 'a3' · 'letter' · 'legal'
  pageNumbers: (page, total) => `Page ${page} of ${total}`,
  headerBlock: [
    { text: 'Quarterly revenue', fontSize: 15, fontStyle: 'bold' },
    { text: `Generated ${today}`, fontSize: 9, color: [100, 116, 139] },
  ],
  footerBlock: [{ text: 'Figures are unaudited.', fontStyle: 'italic' }],
  customizeCell: ({ kind, columnId, value }) => {
    if (kind !== 'data' || columnId !== 'revenue') return;
    if (Number(value) < 0) return { fillColor: [254, 226, 226], textColor: [185, 28, 28] };
  },
  additionalGrids: [{ model: detailModel, title: 'Detail', pageBreak: true }],
});
```

Colours are RGB triples (0–255) rather than the ARGB strings Excel uses,
because that is what a PDF actually stores.

**Text outside Western European Latin needs a font.** Without one, jsPDF draws
with its built-in Helvetica, which covers Latin-1 plus a few typographic marks
and nothing else: Turkish `ş ğ ı İ`, Central European, Cyrillic, Greek, Arabic
and CJK letters come out as the wrong characters (`Kişi` became `Ki_i`,
`İSTANBUL` became `0STANBUL`). Give the export a TrueType font that covers your
language — it is embedded, subset to the glyphs used:

```tsx
const normal = await fetch('/fonts/NotoSans-Regular.ttf').then((r) => r.arrayBuffer());
const bold = await fetch('/fonts/NotoSans-Bold.ttf').then((r) => r.arrayBuffer());

await controller.exportToPdf({ font: { family: 'Noto Sans', normal, bold } });
// or once, for the toolbar button too:
controller.setExportDefaults('pdf', { font: { family: 'Noto Sans', normal, bold } });
```

Only `normal` is required; a missing `bold` falls back to it, so headers and
totals stay in the right script (merely not emboldened). The file must be a
`.ttf` — jsPDF does not read `.otf` or WOFF, and the export says so if it is
handed one. When a PDF export meets text the built-in font cannot draw and no
`font` was given, it warns in the console, naming the first such character.

**Large tables are laid out in slices.** `autoTable` lays a table out in one
synchronous call, so past ~400 rows the writer feeds it a slice at a time and
yields between them — `onProgress` ticks, `signal` can cancel, and the tab
stays alive instead of freezing until the file is done. Measured on the bench
at 4.000 rows × 15 columns:

| `sliceRows` | Total | Longest freeze |
|---|---|---|
| `0` (one call) | 14,9 s | ~15 s |
| 1000 (default) | 12,8 s | 3,3 s |
| 500 | 13,0 s | 1,9 s |

Slicing costs nothing in total time — but the slices must not get *too* small:
every call redoes its own setup, and an early attempt that sliced one PAGE at a
time (≈45 rows) took minutes. Set `sliceRows` lower for shorter freezes,
or `0` to force the single call and the tightest possible document.

**PDF is not a format for a million rows.** The measurements above scale
linearly: that 4.000-row file is already 18 MB, so a million rows is gigabytes
and hours whatever the slicing. Use CSV or Excel at that size, or filter first.

Three behaviours worth knowing:

**Column headers repeat on every page** (`repeatHeaders`, default on). A table
that spills onto page three with no headings is unreadable on paper, where you
cannot scroll back up to check which column is which.

**PDF carries the formatted text**, where Excel writes raw numbers and dates.
A PDF is a picture of the data, not a spreadsheet you go on computing with, so
there is nothing to gain from a raw value that then has to be formatted for
drawing anyway.

**A footer that would not fit gets its own page.** Text drawn past the page
edge is simply invisible, so the note would silently vanish exactly when the
report is long enough to need one.

If `images` data is not a real file of the declared `format`, the export fails
with a message naming which image and why. jsPDF decodes an image to read its
dimensions, so a malformed one cannot be embedded — unlike Excel, which stores
the bytes without looking at them and would produce a quietly broken file.

CSV import sniffs the delimiter (`,` `;` tab `|`), infers column types, and
reports malformed rows instead of hiding them:

```tsx
const { columns, rows, malformedRows } = importCsv(text);
```

## Pagination and toolbar

```tsx
<DataGrid pagination={{ enabled: true, pageSize: 100 }} toolbar />
```

Pagination and virtualization coexist — the pager slices the view and the
window still virtualizes the page. Changing a filter resets to page 1.

### Numbered pages

With `pageButtons` the pager shows page numbers between the previous and next
buttons, so a user can jump straight to a page:

```tsx
<DataGrid pagination={{ pageSize: 50, pageButtons: true, maxPageButtons: 7 }} />
```

With more pages than fit, the run is shortened with an ellipsis — `1 2 3 4 5 …
40` at the start, `1 … 19 20 21 … 40` in the middle — and the first page, the
last page and the current one always stay. `maxPageButtons` caps the slots,
ellipses included (default 7, at least 5). The current page's button carries
`aria-current="page"`, every number is a real button named in the grid's
language ("Page 3", "Sayfa 3"), and keyboard focus stays on the button you
pressed while the pages move round it. The same options work in
`createGrid`.

The toolbar provides debounced search, a column chooser and export buttons.
Your own controls go beside them rather than in a second bar above:

```tsx
<DataGrid
  toolbar
  toolbarItemsBefore={<button onClick={refresh}>Refresh</button>}
  toolbarItemsAfter={<button onClick={openReport}>Report…</button>}
/>
```

## Saved views

```tsx
const view = controller.getViewState();   // JSON-safe
controller.applyViewState(view);
```

Captures column widths, order, pinning and visibility, plus sort, filters,
search, grouping, which groups are collapsed and pagination. It also keeps
what the user changed from the menus: the footer's aggregation for each column
(a `custom` one comes from your configuration and is not saved, since its
reducer is a function), group footers on or off, folded column bands, and under
server-side grouping which groups were open.

### Selection, focus and scroll

These describe a moment rather than a layout, so a view leaves them out unless
you ask for them:

```tsx
const view = controller.getViewState({ include: ['selection', 'focus', 'scroll'] });
```

`'ranges'` adds the Enterprise cell ranges (columns by id, so a range saved
over a column comes back over it after a restored column order). A restored
focus and scroll wait until the rows are there. A restored selection drops keys
the data no longer has; "everything matching" comes back as it was, exclusions
included. Restoring never clears what a view does not carry — a view without a
selection leaves the current one alone.

### Remembering the layout automatically

`stateStoring` does the same thing without you writing the wiring: it restores
once on mount and saves on every layout change, debounced.

```tsx
<DataGrid stateStoring={{ enabled: true }} />
```

It saves after every change the view carries — `stateUpdated` fires for each,
including a collapsed group, a turned page and a changed footer aggregation.
Session state is kept only when you name it:

```tsx
<DataGrid stateStoring={{ enabled: true, include: ['selection', 'scroll'] }} />
```

Off by default, because a reload that brings yesterday's selection back over
today's rows selects rows nobody chose today.

The key defaults to `kanuni-datagrid-<gridId>`, so two grids on a page never
share a layout. `type` chooses `'localStorage'` (default), `'sessionStorage'`
or `'custom'`; `custom` hands you `customLoad`/`customSave`, either of which
may be async, for a layout kept on your server per user.

```tsx
<DataGrid
  stateStoring={{
    enabled: true,
    type: 'custom',
    customLoad: () => fetch(`/api/grid-layout/${userId}`).then((r) => r.json()),
    customSave: (state) =>
      fetch(`/api/grid-layout/${userId}`, { method: 'PUT', body: JSON.stringify(state) }),
  }}
/>
```

Three behaviours are deliberate. The layout is restored **once**, at mount — a
later restore would undo the sort the user just asked for. Writes are
**debounced** (`saveDelay`, default 500 ms) because dragging a column edge
fires a change per pixel, and a pending write is still flushed when the grid
unmounts. And a failed restore is **never fatal**: storage that is full,
disabled by privacy settings, or holding a snapshot from an older build leaves
the grid opening with its default layout instead of refusing to open.

## Row template

`renderRow` replaces a data row's content — a card, a chart line, a summary
sentence — while the header, virtualization, selection and keyboard all keep
working:

```tsx
<DataGrid
  renderRow={({ row, selected }) => (
    <div className={selected ? 'row card selected' : 'row card'}>
      <strong>{row.product}</strong> — {row.units} × {row.unitPrice}
    </div>
  )}
/>
```

Group headers and detail panels keep their own rendering: a template that had
to handle those as well would be a template of the whole grid.

What the template replaces are the **cells** — so while it is on, in-cell
editing, range selection and the fill handle have nothing to attach to. For
per-cell customization that keeps the column layout, use a column's
`renderCell` instead.

## Density

Three presets set the row height, header height, type scale and cell padding
together:

```tsx
<DataGrid density="compact" /* | "normal" | "comfortable" */ />
```

| | Row height | Header | Font |
| --- | --- | --- | --- |
| `compact` | 24 px | 28 px | 12 px |
| `normal` (default) | 28 px | 32 px | 13 px |
| `comfortable` | 36 px | 40 px | 14 px |

The row height is a virtualization value, not only a CSS variable, so switching
density re-measures the scroll extent — a 100.000-row grid goes from a
2.800.000 px canvas to 2.400.000 px on `compact`. An explicit `rowHeight` still
wins: density is a shorthand, not an override.

## Pinned rows

Rows that stay in view while the data scrolls between them, above the body or
below it.

**Rows the app pins** — a target line, last year's figures — are passed in
`pinnedTopRows` and `pinnedBottomRows`. They are not data: never sorted,
filtered, paged, selected or counted, and not exported. They share the
columns, widths and cell rendering of a real row, so the two stay aligned.

```tsx
<DataGrid
  pinnedTopRows={[{ id: -1, product: 'Target', revenue: 60_000 }]}
  pinnedBottomRows={[{ id: -2, product: 'Last quarter', revenue: 48_616 }]}
/>
```

**Rows the user pins**: with `rowPinning`, the row menu offers "Pin row to
top" and "Pin row to bottom". The pinned row shows in that band, after the
app's rows, and right-clicking it there moves it to the other band or unpins
it.

```tsx
<DataGrid rowPinning={{ isRowPinnable: (row) => row.status !== 'Draft' }} />
```

A pinned row is a copy in the band; the row itself stays where it was. It is
still counted, sorted, filtered, paged, selected and exported like any other.
The copy shows the row's current values, and it stays in the band while a
filter hides the row from the body — keeping it in view is what pinning is
for. A row deleted from the data is unpinned with it.

From code: `pinRow(key, 'top' | 'bottom' | null)`, `getPinnedRowKeys()`,
`clearPinnedRows()`, and the `rowPinningChanged` event. The pins are part of a
saved view; a key the data no longer has is dropped when the view is restored.
The API works with `rowPinning` off too — the option is what the menu offers.

## Row context menu

```tsx
<DataGrid
  rowMenu={[
    { id: 'copy', label: 'Copy SKU', shortcut: 'Ctrl+C', onSelect: (ctx) => copy(ctx.row.sku) },
    { separator: true },
    { id: 'more', label: 'More', items: [{ id: 'log', label: 'Log row', onSelect: log }] },
  ]}
/>
```

Pass a function instead of an array to build the items from the row that was
clicked — returning an empty list suppresses the menu for that row:

```tsx
rowMenu={(ctx) => (ctx.row.locked ? [] : itemsFor(ctx.row))}
```

The context carries `row`, `node`, `rowIndex`, the `columnId` under the pointer
and the `selectedKeys` at the moment the menu opened. Right-clicking a row that
is not selected selects it first, so an action driven by the selection operates
on what the user pointed at.

The menu is keyboard-operable: **Shift+F10** or the **ContextMenu key** opens it
on the focused row, arrow keys move (skipping disabled items), **→** and **←**
enter and leave a submenu, **Enter** activates and **Esc** closes. It is clamped
to the viewport, so opening it on the last row does not push it off-screen.

## Theming

Styles are plain CSS driven by custom properties, scoped under
`.kanuni-datagrid-root`:

```css
.kanuni-datagrid-root {
  --dg-primary: #7c3aed;
  --dg-row-height: 32px;
  --dg-border: #e5e7eb;
}
```

That restyles the grid body only. For a theme that also reaches the popups and
the Enterprise chrome, give it a name and pass it as `theme` — see
[Theming](https://kanunilabs.com/docs/datagrid/theming#writing-your-own). Pass `dark` for the
packaged dark palette.

## Charts

The chart MODEL is here in Community: `useGridChartData()` turns the grid's
current result into categories and aggregated series, ready for any chart
library. The panel and its renderers are Enterprise — see
[Charts](https://kanunilabs.com/docs/datagrid/charts).

```tsx
import { useGridChartData } from '@kanunilabs/datagrid-react';

const model = useGridChartData(controller, {
  categoryColumnId: 'region',
  series: [{ columnId: 'revenue', aggregate: 'sum' }],
});
```

## Missing a feature? Tell us

This grid is shaped by the people using it. If something is missing, awkward or
broken, we want to hear about it — [send us your feedback](https://kanunilabs.com/contact).

---

Source: https://kanunilabs.com/docs/datagrid/editing

# Editing

Editing is an Enterprise feature. Import `EnterpriseDataGrid` instead of
`DataGrid` and pass an `editing` object:

```tsx
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';

<EnterpriseDataGrid
  licenseKey={key}
  dataSource={rows}
  rowKey="id"
  columns={columns}
  editing={{ mode: 'batch', allowAdding: true, allowDeleting: true }}
/>
```

**Editing is ON by default in `EnterpriseDataGrid`**, whether or not you pass
`editing`: with no prop at all, cells open an editor on double-click or typing,
and the cell menu offers Cut and Paste. The object configures editing; it does
not switch it on. For an Enterprise grid used for its other features — export,
charts, the status bar — and meant to be **read-only**, switch it off:

```tsx
<EnterpriseDataGrid editing={{ enabled: false }} … />
```

That also turns off range selection, the fill handle and paste, which ride on
editing (see [range selection](https://kanunilabs.com/docs/datagrid/range-selection)); copying stays.

## Modes

`mode` decides two things: what the user opens, and when the change is
persisted.

| Mode | The user edits | Saved when |
| --- | --- | --- |
| `cell` | one cell | immediately on commit |
| `batch` (default) | any cells, freely | an explicit **Save** |
| `row` | the whole row, in place | that row's **Save** |
| `form` | the row as a form panel | that row's **Save** |
| `popup` | the row as a modal dialog | that row's **Save** |

`row`, `form` and `popup` differ only in **presentation** — they share one row
session underneath, so Save, Cancel and validation behave identically in all
three. Switching between them mid-edit keeps what the user has typed.

### Row, form and popup

Double-click a row to open it, or use **Edit row…** in the row context menu.
`row` turns every editable cell of that row into an editor and puts Save /
Cancel in the strip above the grid; `form` and `popup` lay the fields out with
labels and carry their own buttons.

```tsx
editing={{
  mode: 'popup',
  allowAdding: true,
  rules: {
    product: [{ type: 'required' }, { type: 'stringLength', min: 3 }],
    units: [{ type: 'required' }, { type: 'range', min: 1, max: 1000 }],
  },
  crud: {
    update: (key, values, row) =>
      fetch(`/api/orders/${key}`, { method: 'PATCH', body: JSON.stringify(values) })
        .then((r) => r.json()),
  },
}}
```

Four behaviours are deliberate:

**Only that row is saved.** A half-filled row elsewhere stays pending. That is
the whole difference from `batch`.

**Nothing is written through until Save.** The values live in the change store,
so a Cancel genuinely restores the row and a cancelled edit never reached
sorting, filtering or an export. Totals still follow the draft — the footer
updates as you type, before you save.

**A rejected save keeps the row open**, holding what the user typed, with the
server's message above the fields. Nothing is lost because row 3 of 10 hit a
constraint.

**Every field is validated on Save**, not just the ones that were touched. A
required field the user never opened is the common failure on a new row, and
per-keystroke validation cannot see it. The first invalid field takes focus.

`+ New row` in `row`/`form`/`popup` **opens** the new record instead of posting
a blank one; `onInitNewRow` seeds it, and Cancel removes it entirely.

Keyboard: <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>Enter</kbd> saves, <kbd>Esc</kbd>
cancels. In `row` mode a bare <kbd>Enter</kbd> also saves. In a form a bare
<kbd>Enter</kbd> is inert on purpose — in a grid it is one keystroke away at
all times, and "I pressed Enter and it saved a half-filled row" is the
complaint that follows.

Wording is translatable:

```tsx
editing={{
  mode: 'popup',
  formLabels: { save: 'Kaydet', cancel: 'Vazgeç', editTitle: 'Satırı düzenle' },
}}
```

## Persistence

Two shapes, and the per-row one wins when both are present.

**Per row** — one call per insert / update / delete, which is what a REST or
SQL back end wants:

```tsx
crud: {
  insert: (values) => api.create(values),          // return the stored row
  update: (key, values, row) => api.patch(key, values),
  remove: (key, row) => api.delete(key),
}
```

`values` on an update holds the **changed columns only**. Returning the stored
row makes the grid adopt the server's version of it — its real primary key,
defaults, computed columns. Return nothing and the grid leaves your data alone:
it never mutates your array behind your back.

**As a batch** — one call with everything:

```tsx
onSave: (changes) => api.saveAll(changes)
```

Either way a rejection fails the whole save and leaves the changes pending, so
nothing the user typed is lost. The grid shows the reason in every mode —
including cell mode, where each commit saves on its own and nobody else is
waiting for the answer.

Supply a handler for every kind of change the grid allows. With `crud`
present and, say, `allowAdding` on but no `insert`, a save containing a new
row is refused before anything is sent, and the console names the missing
handler — rather than reporting the row as saved while it never reached you.

## Validation

Rules are per column id, checked as the user types and again on save:

```tsx
rules: {
  email: [{ type: 'required' }, { type: 'pattern', pattern: /@/ }],
  qty: [{ type: 'range', min: 1, max: 999 }],
  code: [{ type: 'custom', validate: async (v) => (await isFree(v)) || 'Already taken' }],
}
```

Async rules run on save, not per keystroke.

## Permissions

```tsx
editing={{
  allowAdding: true,
  allowDeleting: (row) => row.status === 'draft',
  allowUpdating: (row, columnId) => columnId !== 'id',
}}
```

A column the predicate refuses is read-only in every mode — it is skipped by
Tab, shown but disabled in a form, and rejected by paste and fill.

---

Source: https://kanunilabs.com/docs/datagrid/formulas

# Formulas and calculated columns

A **calculated column** is a column whose value is a formula over the row's other
columns — the way a spreadsheet user would write it:

```tsx
import { DataGrid } from '@kanunilabs/datagrid-react';

<DataGrid
  dataSource={orders}
  rowKey="id"
  columns={[
    { field: 'product', headerName: 'Product' },
    { field: 'price', headerName: 'Unit price', dataType: 'number' },
    { field: 'qty', headerName: 'Qty', dataType: 'number' },
    { id: 'total', headerName: 'Total', formula: '[Unit price] * [Qty]' },
    { id: 'level', headerName: 'Stock', formula: 'IF([Qty] < 10; "Low"; "OK")' },
  ]}
/>
```

The column behaves like data: it sorts, filters, searches, groups, takes a
footer total, exports and is part of the saved view. It is not editable — there
is nothing to write the value back to. A formula is **Community**.

The formula runs without `eval` or `new Function`, so it works on pages with a
strict Content-Security-Policy.

## Writing a formula

- **Columns** are written in brackets: `[qty]` (the column id) or `[Unit price]`
  (the header text), case-insensitively. A `]` inside a name is written `]]`.
- **Operators**, in Excel's order: comparison `= <> < <= > >=`, then `&` (join
  text), `+ -`, `* /`, `^`, unary `-`, and a trailing `%`. `-2^2` is `4`, as in
  Excel.
- **Arguments** are separated by `;` or `,` — `ROUND([Price]; 2)` and
  `ROUND([Price], 2)` are the same.
- **Text** is in double quotes; `""` is a quote inside it. `TRUE` and `FALSE`
  are booleans.
- **Blank** counts as `0` in arithmetic and `""` in text.
- **Dates** count in days: a date plus `7` is a week later, and a date minus a
  date is the days between them. An ISO day string such as `"2026-03-15"` — what
  a JSON API sends — counts as a date.

| Group | Functions |
|---|---|
| Logic | `IF`, `IFERROR`, `AND`, `OR`, `NOT`, `ISBLANK` |
| Numbers | `ROUND`, `ROUNDUP`, `ROUNDDOWN`, `ABS`, `MOD`, `POWER`, `SQRT` |
| Aggregates | `SUM`, `AVERAGE`, `MIN`, `MAX`, `COUNT` |
| Text | `LEN`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `MID`, `CONCAT` |
| Dates | `YEAR`, `MONTH`, `DAY`, `TODAY`, `DATE` |

`ROUND` rounds half away from zero (`ROUND(1.005; 2)` is `1.01`), and `UPPER` /
`LOWER` follow the grid's `locale` — in Turkish, `i` becomes `İ`.

A calculated column can read another. Its `dataType` defaults to what the
formula produces (arithmetic is a number, `&` is text, a comparison is a
boolean), so it sorts and aligns correctly without one.

## When a formula goes wrong

Errors are values, as in a spreadsheet, and a cell shows the code:

| Code | Meaning |
|---|---|
| `#DIV/0!` | Division by zero |
| `#VALUE!` | A value of the wrong kind — text in arithmetic |
| `#NUM!` | No number answers it — `SQRT(-1)` |
| `#NAME?` | The formula does not compile (an unknown column or function) |
| `#CYCLE!` | The column reads itself, directly or through another column |

Errors propagate through operators, `IFERROR(x; fallback)` catches them, and they
sort with the blanks. For a `#NAME?` column, `controller.getFormulaError(id)`
says why and where: `{ message, position, kind, params }`.

## Letting users add columns

*Enterprise.* With `calculatedColumns`, the column menu offers **Add calculated
column…**; on a column the user added, also **Edit** and **Remove**.

```tsx
<EnterpriseDataGrid calculatedColumns dataSource={orders} columns={columns} />
```

The dialog takes a name and a formula, inserts columns and functions at the
caret, previews the first rows as you type, and explains an error in the grid's
language with the character it is at — Save stays disabled until the formula
compiles. The new column is placed after the one whose menu it came from.

It is off by default, so an upgrade does not put a new entry in front of every
user of every grid. The same from code:

```ts
const id = controller.addCalculatedColumn({ headerName: 'Margin', formula: '[Revenue] - [Cost]', after: 'cost' });
controller.updateCalculatedColumn(id, { formula: 'ROUND([Revenue] - [Cost]; 0)' });
controller.removeCalculatedColumn(id); // also drops its sort, filter or grouping
controller.previewFormula('[Revenue] / [Units]'); // { ok, values, dataType } or { ok: false, error }
```

Columns added this way are kept in the saved view (`calculatedColumns`), and they
stay when the app passes its `columns` again. A Community grid does not restore
them.

## Cell formulas

*Enterprise, with editing.* On a column with `allowFormulas`, a cell can hold a
formula: the user types `=` and the rest, as in a spreadsheet.

```tsx
<EnterpriseDataGrid
  editing={{ mode: 'cell' }}
  columns={[
    { field: 'qty', headerName: 'Qty', dataType: 'number' },
    { field: 'price', headerName: 'Price', dataType: 'number' },
    { field: 'total', headerName: 'Total', dataType: 'number', allowFormulas: true },
  ]}
/>
```

The data keeps the formula text; the grid shows, sorts, filters, totals and
exports the **result**. The editor of such a column is a text box whatever its
`dataType` — a number box would not take `=` — and a plain number typed into a
number column is still stored as a number.

- **`[Qty]`** is this row's Qty, as in a calculated column. Copy the formula down
  and every row reads its own.
- **`A1`, `B2:B9`** are the cells **on screen**: the letter is the column's
  visible position, the number the row's position among the data rows. Typed
  references are stored by **column id and row key** — `={qty@17}*2` — and shown
  back as A1 at wherever that cell is now, so sorting or filtering afterwards
  never repoints a formula. A range is kept a range while those cells are
  adjacent in the data; one framed over a sorted screen is stored as the cells the
  user framed.
- **`$`** fixes a part, as in Excel: `$A$1` stays put when the fill handle copies
  the formula; relative references move with it, along the screen.
- A formula that reads **another row** updates when that row is edited. One that
  reads itself shows `#CYCLE!`; a reference to a row that no longer exists shows
  `#REF!`.

A formula that arrives **with the data** — written by your backend — may use the
stored `{column@key}` form, or plain A1, which then counts in **data order**: the
order of the rows you passed and of the column definitions.

Cell formulas are for data in the browser (an array). `controller.getCellFormula(rowKey,
columnId)` returns a cell's formula text, or null for a plain value.

## In Excel

*Enterprise.* The Excel export writes calculated columns and cell formulas as
Excel formulas over the sheet's cells, with the grid's result cached — details in
[Excel: formulas and links](https://kanunilabs.com/docs/datagrid/features#formulas-and-links). Excel
then recalculates with its own rules, which differ at the edges: text that merely
looks like a number or a date is not coerced the same way everywhere.

## What it does not do yet

- **Function names are English** (`IF`, not `EĞER`).
- **A pasted formula is stored as typed**: its A1 references then count in data
  order rather than on the screen it was pasted onto.

---

Source: https://kanunilabs.com/docs/datagrid/remote

# Server-side data

Everything on this site so far hands the grid an **array** and it does the work
in the browser: a Web Worker sorts and filters, and a million rows stay
interactive. That is the right answer for most applications, and it is what the
Community edition does.

It stops being the right answer when the data is bigger than a browser tab, or
when it lives behind permissions that must not be evaluated on the client. For
that, implement a `DataSource` instead of passing an array. **Filtering,
sorting, paging, distinct values and footer totals then run on your server**,
and the component you render does not change.

> Loading from a server is **Community** (since October 2026): blocks fetched
> as the user scrolls, sort, filter, search, distinct values, footer totals,
> [Retry](#when-a-load-fails) and [refresh](#refreshing-when-the-servers-data-changes).
> **Enterprise** adds what makes the server do more:
> [grouping on the server](#grouping-on-the-server), a
> [server tree](#a-tree-on-the-server), and an export of the whole result. On a
> Community grid fed by a server those are not offered — the grouping entries
> leave the column menu and CSV export leaves the toolbar, because a file of
> only the rows already loaded would look complete and not be.

## The contract

```ts
interface DataSource<TRow> {
  load(options: LoadOptions): Promise<LoadResult<TRow>>;
  byKey?(key: RowKey): Promise<TRow | undefined>;
  loadDistinctValues?(options: DistinctValuesOptions): Promise<DistinctValue[]>;
}
```

Only `load` is required. The grid calls it whenever the query changes or it
needs a block of rows it does not hold.

```tsx
import { DataGrid } from '@kanunilabs/datagrid-react';

const orders = {
  async load({ skip = 0, take = 100, sort, filter, searchText, summaries }) {
    const res = await fetch('/api/orders', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ skip, take, sort, filter, searchText, summaries }),
    });
    const data = await res.json();
    return {
      rows: data.rows,
      totalCount: data.total,     // the whole filtered result, not this page
      summaries: data.totals,     // optional; see "Totals" below
    };
  },
};

<DataGrid
  dataSource={orders}
  rowKey="id"
  columns={columns}
  filterRow
/>;
```

`totalCount` is the size of the **entire filtered result**, not of the block you
just returned. It is what sizes the scrollbar, so a wrong number here shows up
as a grid that scrolls into empty space.

## What arrives in `load`

| Field | What it is |
| --- | --- |
| `skip` / `take` | The block being asked for. |
| `sort` | Column ids and directions, in priority order. |
| `filter` | A serializable filter **AST** — the same tree the worker gets. |
| `searchText` | The quick-search box, if the grid has one. |
| `group` / `groupKeys` | Remote grouping; see below. |
| `summaries` | Footer totals to compute over the whole result. |

The filter is an AST rather than a string on purpose: it survives
`JSON.stringify`, so the same value can travel to a Web Worker or to your
server, and you translate it into SQL (or whatever you speak) once.

## Distinct values — the header filter checklist

The header filter popup is a checklist of every distinct value in a column. A
client-side grid derives that from the data it holds. A server-side grid cannot:
it holds a few blocks, and a checklist built from "whatever happens to be
cached" is worse than no checklist — a user would tick four values believing
they were all of them.

So the popup is offered **only when you implement `loadDistinctValues`**:

```ts
async loadDistinctValues({ columnId, limit }) {
  const rows = await db
    .selectDistinct(columnId)
    .orderBy(columnId)
    .limit(limit);              // apply the limit in SQL, not after
  return rows.map((r) => ({ value: r[columnId] }));
}
```

Without it the popup is simply not offered. The filter row, if you turned it on,
still works — it sends a condition, not a list of values.

## Totals

Ask for footer totals by reading `options.summaries` and returning
`result.summaries`, keyed `"columnId:type"`:

```ts
// options.summaries → [{ columnId: 'revenue', type: 'sum' }]
return {
  rows,
  totalCount,
  summaries: { 'revenue:sum': 1_284_500, 'id:count': 8_412 },
};
```

Two things worth knowing:

- **A custom aggregation never reaches you.** `type: 'custom'` is a JavaScript
  function on the client, and your server has no way to run it. A grid whose
  only aggregation is custom therefore sends nothing and shows an empty footer
  on a remote source — the honest answer rather than a wrong number.
- **Totals belong to the query, not to a block.** Returning them on every
  response is fine (the last wins), and so is returning them only when
  `skip === 0`. What must not happen is answering a *new* filter with the *old*
  filter's totals; the grid discards what it holds the moment the query changes
  precisely so a stale number cannot sit under fresh rows.

## Grouping on the server

*Enterprise.* `EnterpriseDataGrid` / `createEnterpriseGrid`.

With `group` set, `groupKeys` says which level is being asked for: its **length**
is the depth. Given `group: [region, category]`:

- `groupKeys: []` → return the regions, as `groups`
- `groupKeys: ['Berlin']` → return Berlin's categories, as `groups`
- `groupKeys: ['Berlin', 'Toys']` → return the data rows, as `rows`

A group row carries its own count and, optionally, its aggregates:

```ts
return {
  rows: [],                     // required by the type; a group level answers with `groups`
  totalCount: 12,               // children at THIS level
  groups: [
    { value: 'Berlin', count: 1_204, aggregates: { 'revenue:sum': 91_400 } },
  ],
};
```

`count` is the data rows underneath at any depth — what the header shows.
`totalCount` is the number of children at this level, which is what the grid
pages through. They are different numbers and mixing them up produces a group
that reports thousands of rows and scrolls twelve.

**Expand all** (the group panel's button, or `controller.expandAllGroups()`)
does not download the table. Groups open as they arrive, and a group asks for
its children only when it reaches the screen: roughly one request per group on
or just below it, however many groups the server has.

## A tree on the server

With `tree.hasChildren`, `load` gets `parentKey`. It is `null` for the top
level, and otherwise the key of the row being opened. Return that level's rows
in `rows` and their number in `totalCount`; sort, filter and `skip` / `take`
apply within the level. See
[Master-detail & tree data](https://kanunilabs.com/docs/datagrid/hierarchy#from-the-server).

## Typing while the server thinks

The filter row **debounces** on a remote source (200 ms by default), so a word
typed in one go is one request rather than one per letter. The grid also shows
its loading overlay for anything slower than a moment. It cannot cancel a
request already in flight — `load` is not handed an abort signal — but it drops
any answer that arrives for a query that has since changed, so a slow early
response never overwrites a newer one.

## When a load fails

If `load` rejects — the network dropped, the server answered with an error —
the rows of that block do not keep pulsing as loading rows. Each of them says
**Couldn't load these rows** and carries a **Retry** button, so the message is
in view wherever the reader scrolled to. The rows the grid already had stay
where they are, and the `dataError` event reports the error.

A failed block is **not asked for again on its own**, so a server that is down
is not hit again on every scroll. Retry asks for exactly the blocks that failed
— the button does it, and so does the controller:

```ts
// After the connection comes back
window.addEventListener('online', () => controller.retryFailedLoads());
```

`controller.isRowLoadFailed(index)` tells whether a row in the view has nothing
to show because its load failed, if you draw your own message. When the very first request fails there are no rows
yet, so the grid shows one failed row to hold the message and the button. A
changed sort, filter or search starts over, failures included. The same applies
to a group's rows under server-side grouping and to a level of a server tree.

## Refreshing when the server's data changes

The grid caches what it has fetched. When the data changes on the server —
another user saved, a job finished — tell it to ask again:

```ts
controller.invalidate();

// A dashboard that polls: refresh every 10 seconds without the loading overlay
setInterval(() => controller.invalidate({ background: true }), 10_000);
```

The rows on screen stay until the new ones arrive. Only the blocks on screen
are asked for again, plus the first one, which carries the row count; under
server-side grouping, the top level and the open groups on screen. That is why
there is no call to refresh a single group: a full refresh already costs only
what is on screen. If the refresh fails, the rows keep their last data rather
than turning into Retry rows, `dataError` reports the error, and the part that
failed is asked for again by the next refresh or `retryFailedLoads()` — not on
every scroll.

`background: true` drops the overlay only; the `busyChanged` event still fires,
with `background: true`, if you want a quieter sign of your own.

## Rows pushed by the server — the viewport model

**Enterprise.** Everything above *asks*: the grid requests blocks and waits
for them. For data that changes on its own — prices, an order book, a
monitoring screen — the server should instead *push* the rows on screen and
every change to them. That is `viewportDatasource`:

```tsx
const feed: ViewportDatasource<Quote> = {
  init({ setRowCount, setRowData }) {
    socket.on('count', setRowCount);
    // { 120: {...}, 121: {...} } — row index → row, any time
    socket.on('rows', setRowData);
  },
  setViewportRange(first, last) {
    socket.send({ subscribe: [first, last] }); // and drop the old range
  },
  setQuery({ sort, filter, searchText }) {
    socket.send({ query: { sort, filter, searchText } });
  },
  destroy() {
    socket.close();
  },
};

<EnterpriseDataGrid dataSource={[]} viewportDatasource={feed} rowKey="symbol" columns={columns} />
```

The grid calls `init` once with three functions: `setRowCount(n)` sizes the
scrollbar, `setRowData(rows)` puts rows at their indexes (an object or a `Map`,
the first answer for a range or a change later), `getRow(i)` reads what it
holds. It then tells the source which rows are on screen with
`setViewportRange(first, last)` — a screen either side included, so a scroll
lands on rows that are already there, and only the latest range once the
scrolling stops moving. Rows that leave the range are dropped: the source stops
keeping them current, so the grid does not keep them either.

The source owns the order. The grid's sort, filter and search arrive in
`setQuery` (once before the first range, then on every change); the rows held
are dropped, and the source answers with the new count and the rows of the
range. Without `setQuery` the grid's sort and filter do nothing.

What it does not do: rows cannot be grouped (the source sends flat rows), and
an export holds the rows on screen rather than paging through the result. A
Community grid refuses the option with an error rather than showing an empty
grid.

## What stays client-side

Some things never become part of a query:

- **`comparator`** and **`externalFilter`** are JavaScript functions, and a
  function cannot be sent to your server. On a remote source the grid does not
  apply them at all — the order and the rows are whatever `load` returns. Put
  that logic in the endpoint.
- **Selection, focus, editing state and column layout** are view state; they
  never round-trip.

**Export** does reach the server: it covers the whole filtered result, so the
grid pages through the source to build the file, and a large export is as slow
as your endpoint is. It is capped at 100,000 rows by default
(`remote.exportMaxRows`); above that the export fails with a message naming the
limit instead of writing a truncated file.

## Local or remote, same component

Nothing else in your code changes. Grouping, filtering, totals, selection,
theming and the event surface are the same props and the same events either way
— the differences above are the exceptions — so a grid can
start on an array and move to a `DataSource` when the data outgrows the tab —
without a rewrite.

---

Source: https://kanunilabs.com/docs/datagrid/events

# Events

The grid publishes what happens on a typed event bus. Props like `onRowClick`
reach whoever renders the grid; events reach **anything else** — a detail pane,
a router, an audit trail, a layout you persist.

## Subscribing

`onReady` hands you the controller. Everything hangs off `controller.events`:

```tsx
<DataGrid
  dataSource={rows}
  rowKey="id"
  columns={columns}
  onReady={(controller) => {
    const off = controller.events.on('cellValueChanged', (e) => {
      console.log(e.columnId, e.previousValue, '→', e.value, `(${e.source})`);
    });
    // `on` returns its own unsubscribe.
    return off;
  }}
/>
```

Payloads are typed from the event name — `GridEventMap` is the single source,
so `e` above is a `CellValueChangedEvent` with no cast. Every payload type is
exported from `@kanunilabs/datagrid-core` if you need to name it:

```ts
import type { CellValueChangedEvent, PaginationChangedEvent } from '@kanunilabs/datagrid-core';
```

## Three patterns worth knowing first

**Coarse and granular events coexist.** `columnStateChanged` fires for every
column change and carries the whole state; `columnResized` / `columnMoved` /
`columnPinned` / `columnVisible` each name one gesture. Subscribe to the coarse
one to persist a layout, to a granular one to react to a specific action. The
granular events are additive — nothing stopped firing when they arrived.

**Gestures come in brackets.** Undo, redo, cut, copy, paste and fill each
publish a `…Start` and a `…End` around the per-cell events they produce, so a
listener syncing a backing store can batch 500 changes instead of issuing 500
writes. **The close always arrives** — including when the gesture did nothing,
and including when it threw.

**Events describe the grid's view of the data, not the DOM.** No payload
carries a DOM or React event: the core runs and is tested without a browser,
and a React synthetic event is pooled — invalid by the time an async listener
reads it. If you need `preventDefault`, use the prop; props run first.

---

## Data & lifecycle

| Event | Payload | Fires when |
|---|---|---|
| `contentReady` | `rows`, `totalCount`, `visibleCount` | The pipeline produced a result — after any sort, filter, search, grouping or data change. |
| `firstDataRendered` | `rowCount` | **Once**, on the first non-empty view. Not the same as `onReady`, which fires before any data has been through the pipeline. |
| `dataUpdated` | `totalCount` | The source rows were replaced. |
| `rowsChanged` | `added`, `updated`, `removed` | An `applyTransaction` landed. |
| `asyncTransactionsFlushed` | `count` | A batch of `applyTransactionAsync` calls was applied as one. `count` is how many CALLS the batch absorbed, not how many rows moved — it fires even when the batch cancelled itself out, because the caller asked to be told when its transactions were dealt with. |
| `dataError` | `error` | A remote block failed to load. The grid keeps the rows it has; the failed rows show a Retry button (`controller.retryFailedLoads()`). |
| `busyChanged` | `busy`, `progress`, `phase`, `cancellable` | Long work started or finished. `progress` is a real percentage only where one exists — otherwise `null`, meaning "indeterminate". |
| `summariesChanged` | `values` | The footer totals landed. Above ~100k rows the summary pass streams in slices **after** `contentReady` (the rows paint first, the totals follow moments later); this event is how the footer — or your own listener — learns the final numbers. Below that size summaries are computed inside the pipeline and this event does not fire. |
| `stateUpdated` | `scope`, `state` | Anything a saved view carries moved — sort, filter, a collapsed group, a page, a footer aggregation, a folded band, an Enterprise cell range. One subscription instead of six; `scope` is `'data'`, `'view'` or `'page'`, and `state` is `getViewState()` without session parts. |
| `gridPreDestroyed` | `state` | `dispose()` was called. Emitted **before** teardown, so `getRows()` still answers inside your handler — this is where you save a layout. |

## Sorting, filtering, grouping

| Event | Payload |
|---|---|
| `sortChanged` | `sort` |
| `filterChanged` | `filter`, `searchText` |
| `groupChanged` | `groupBy`, `levels` |

## Selection & focus

| Event | Payload |
|---|---|
| `selectionChanged` | `selectedKeys`, `selectedCount` |
| `focusChanged` | `focus` |
| `focusedRowChanged` | `rowKey`, `previousRowKey`, `row?` |

`focusedRowChanged` fires only when the **row** changes, so moving left and
right along one row does not wake row-level listeners.

## Interaction

| Event | Payload |
|---|---|
| `cellClicked` · `cellDoubleClicked` · `cellContextMenu` | `rowKey`, `rowIndex`, `columnId`, `value`, `row?`, `node` |
| `rowClicked` · `rowDoubleClicked` | `rowKey`, `rowIndex`, `row?`, `node` |

`value` is resolved the same way the renderer resolves it, so a `valueGetter`
column reports what the user is actually looking at. On a group header `row`
and `value` are `undefined` rather than invented.

`rowIndex` is the position in the **current view** — after filter, sort,
grouping and paging.

## Editing

| Event | Payload |
|---|---|
| `cellValueChanged` | `rowKey`, `columnId`, `value`, `previousValue`, `row?`, `source` |
| `cellEditingStarted` | `rowKey`, `columnId`, `value` |
| `cellEditingStopped` | `rowKey`, `columnId`, `value`, `cancelled` |
| `rowEditingStarted` | `rowKey`, `isNew`, `row?` |
| `rowEditingStopped` | `rowKey`, `isNew`, `cancelled`, `row?` |

`cellValueChanged` fires the moment the grid's own view of a value changes —
**not** when it is persisted. Those are different instants in every mode but
`cell`, and a chart or a dirty-form indicator wants the first one. `onSave` and
`onRowUpdated` remain the persistence hooks.

`source` says which gesture produced it: `'edit'`, `'cut'`, `'fill'`,
`'paste'`, `'undo'` or `'redo'`. Without it you cannot tell your own history
navigation from user input, or batch a paste.

Two things that are easy to assume and wrong:

- **Committing an untouched editor** emits `cellEditingStopped` with no
  `cellValueChanged`. The two events are not derivable from one another.
- **A refused save** — validation or the server said no — emits **nothing**.
  The editor is still on screen with the error in it; the user has not moved on.

## Undo / redo

| Event | Payload |
|---|---|
| `undoStarted` · `redoStarted` | `label` |
| `undoEnded` · `redoEnded` | `performed`, `label` |

The bracket wraps the replayed values, so the order you see is
`undoStarted` → each `cellValueChanged` with `source: 'undo'` → `undoEnded`.
Asking to undo an empty history still opens and closes the bracket, with
`performed: false`.

## Clipboard & fill

| Event | Payload |
|---|---|
| `cutStart` · `copyStart` · `pasteStart` · `fillStart` | `cellCount` |
| `cutEnd` · `copyEnd` · `pasteEnd` · `fillEnd` | `cellCount`, `performed` |

> `cut` is defined but nothing triggers it yet — the grid has no cut command
> today. The contract is in place for when one lands.

## Columns

| Event | Payload |
|---|---|
| `columnStateChanged` | `columns` |
| `columnResized` | `columnId`, `width`, `previousWidth`, `finished` |
| `columnMoved` | `columnId`, `fromIndex`, `toIndex` |
| `columnPinned` | `columnId`, `pinned`, `previous` |
| `columnVisible` | `columnId`, `visible` |
| `columnGroupOpened` | `band`, `open` |

`columnResized.finished` is what makes a drag usable: every pointer move
reports `false`, the release reports `true` **once**. Persist on the close, or
you write a layout per pixel.

Bulk operations — `applyColumnStates`, `resetColumnState`, `sizeColumnsToFit`, a
`columns` prop swap — publish only `columnStateChanged`. Replaying a restored
layout as dozens of synthetic gestures would tell you the user did things they
never did.

`columnGroupOpened` reports a header band folding or unfolding, with `band` as
the caption path (outermost first). Folding is **not** hiding: a column tucked
away with its band keeps `visible: true`, because that flag belongs to the
column chooser and the user did not touch it. Which columns survive a fold is
decided per column by `bandShow`.

## Pagination, viewport, rendering

| Event | Payload |
|---|---|
| `paginationChanged` | `page`, `pageSize`, `pageCount`, `fromResultChange` |
| `viewportChanged` | `window` |
| `bodyScroll` | `scrollTop`, `scrollLeft`, `firstRow`, `lastRow` |
| `bodyScrollEnd` | same payload, once the scrolling stops |
| `gridSizeChanged` | `width`, `height`, `previousWidth`, `previousHeight` |
| `scrollRequested` | `scrollTop?`, `scrollLeft?` |
| `cellsFlashed` | `rowKeys`, `columnIds`, `duration` |
| `cellsRefreshed` | `revision` |

`pageCount` is in the pagination payload because it moves without anyone
touching the pager — a filter that narrows the result re-paginates it.
`fromResultChange` separates "the user paged" from "the ground moved".

`viewportChanged` fires only when the quantized window actually moves, not per
scrolled pixel. `bodyScroll` is the other half of that pair: it fires whenever
the **offsets** change, including a scroll of a few pixels that moves no rows —
which is what a panel synchronized beside the grid needs. `bodyScrollEnd`
follows once the offsets have been still for a moment, so work you only want to
do when the user has settled (fetching previews, recording a reading position)
does not run sixty times on the way there.

`gridSizeChanged` reports the drawing area, not the window: a grid that got
wider shows the same rows, and a layout listening for the size still needs to
hear about it.

## Row drag

| Event | Payload |
|---|---|
| `rowDragEnter` · `rowDragMove` · `rowDragLeave` | `rowKey`, `row?`, `overKey`, `position`, `fromGridId` |
| `rowDragEnd` | the same, plus `dropped` |

`rowDragEnd` fires for **every** drag that ends, including one abandoned with
Escape or dropped outside a target — `dropped` is what separates "the user
moved a row" from "the user thought about it". `overKey` is null when the
pointer is past the last row, which is where "move to the end" lands.

`rowDragMove` is emitted only when the drop target actually changes, not on
every `dragover` tick — the browser fires those continuously while the pointer
sits still.

`fromGridId` differs from this grid's id when the row came from another grid
sharing a `rowDrag.group`.

## Trees and detail panels

| Event | Payload |
|---|---|
| `treeRowToggled` | `rowKey`, `expanded` |
| `detailToggled` | `rowKey`, `expanded` |

A tree row, or a master row's detail panel, opened or closed — by a click, a
key or the API. `rowKey` is `null` when every row changed at once
(`expandAllTreeRows`, `collapseAllTreeRows`, `expandAllDetails`,
`collapseAllDetails`). Tree expansion is also part of the saved view, so
`stateStoring` remembers it; open detail panels deliberately are not.

## Overlays

| Event | Payload |
|---|---|
| `overlayChanged` | `overlay`, `manual` |

The grid decides on its own: busy shows the loading overlay, an empty result
shows the no-rows message. The API is for what the grid cannot know —
`controller.showLoadingOverlay()` while **you** fetch the data you are about to
hand over, `showNoRowsOverlay()` to say "nothing matches" for a reason of your
own, and `hideOverlay()` to hand the decision back.

`hideOverlay()` is not "show nothing": it releases the override, so an empty
grid goes back to saying it is empty. `controller.getOverlay()` answers with
what should be on screen right now, override resolved.

`cellsFlashed` and `cellsRefreshed` are intents the adapter paints — the core
has no DOM. You will normally call `controller.flashCells(...)` and
`controller.refreshCells()` rather than listen to them.

## Charts (Enterprise)

| Event | Payload |
|---|---|
| `chartOpened` | `state` |
| `chartChanged` | `state`, `changes` |
| `chartClosed` | `state` |

The Enterprise chart panel, opened, changed or closed — by the reader or from
code. `state` is the whole `GridChartState`, the same object `getState()`
returns. `changes` names what moved (`type`, `data`, `stacking`, `format`,
`hiddenSeries`, `window`). A Community grid never fires these. See
[Chart API, events and saved charts](https://kanunilabs.com/docs/datagrid/charts#chart-api-events-and-saved-charts).

---

## Deliberately absent

Two things you might look for and not find, with the reason:

**`columnHeaderClicked`** — a header click is a sort gesture today, and
`sortChanged` already reports the outcome. A separate event would need its own
answer for what happens when the click was on the menu, the resize handle or
the filter funnel.

**A "filtered but unsorted" iteration hook** (a pattern some grids expose
as a separate callback) — this engine's filter and sort are one indivisible
pass, which is why `BusyPhase` calls it `computing`. There is no moment when
that array exists; producing it would mean running the filter a second time and
selling the cost as an API. `forEachNode`, `forEachNodeAfterFilterAndSort` and
`forEachDisplayedNode` cover the three stages that are real.

## A worked example

Persisting a layout, without saving on every pixel of a resize drag:

```tsx
onReady={(controller) => {
  const offs = [
    // The coarse event covers resize, move, pin, visibility and bulk restores.
    controller.events.on('columnStateChanged', ({ columns }) => {
      localStorage.setItem('grid-columns', JSON.stringify(columns));
    }),
    // …but during a drag, wait for the close.
    controller.events.on('columnResized', ({ finished }) => {
      if (!finished) return; // mid-drag: the coarse event already fired, ignore it
      // persist here if you want resize handled separately
    }),
    controller.events.on('gridPreDestroyed', ({ state }) => {
      localStorage.setItem('grid-view', JSON.stringify(state));
    }),
  ];
  return () => offs.forEach((off) => off());
}}
```

---

Source: https://kanunilabs.com/docs/datagrid/theming

# Theming

[Try it live](https://kanunilabs.com/playground/datagrid) — the theme and density pickers above the
grid switch every combination on this page. To design a colour theme of your
own instead, start in the [Theme Builder](https://kanunilabs.com/theme-builder).

Two props:

```tsx
<DataGrid
  dataSource={rows}
  rowKey="id"
  columns={columns}
  theme="minimal"
  density="compact"
  dark={isDark}
/>
```

Both are optional. **Omit `theme` and the grid renders exactly as it always
has** — the packaged look is not one of the six, it is the default, and it is
not going to move under you.

Switching is a class swap on the grid root, so it repaints without rebuilding
anything: no re-render of a cell, no reload, and nothing to configure. Bind it
to a user preference and it changes as fast as the user clicks.

## The six

| `theme` | Character |
|---|---|
| `minimal` | Minimal chrome — no column rules, hairline row rules, roomy radii. For product UIs where the grid sits among cards. |
| `ledger` | Dense and fully ruled — small type, tight padding, near-square corners. For the case where the grid *is* the application. |
| `elevated` | Tall rhythm, rows-only rules, a medium-weight tracked header, pill controls and real elevation. |
| `framed` | Airy but fully framed, with a doubled rule anchoring the header band. |
| `kanuni` | The KanuniLabs house theme: an ink header carrying the brand gold, over a warm near-white body. |
| `kanuni-midnight` | The house theme in dark. Already dark — it ignores the `dark` flag. |

Every theme ships a **light and a dark palette**. `dark` picks between them, so
one flag drives all six:

```tsx
<DataGrid theme="elevated" dark={prefersDark} … />
```

Nothing here is a third-party stylesheet: the palettes, metrics and line work
are ours, and each name says what the theme does.

## Palettes

A **second, independent axis**. The theme decides the structure — where the
rules are drawn, how tall a row is, how round a control is. A palette decides
only the colours:

```tsx
<DataGrid theme="ledger" palette="nord" dark={isDark} … />
```

| `palette` | Character |
|---|---|
| `nord` | Arctic, desaturated blue-grey. The calmest — a dense grid of numbers does not vibrate. |
| `dracula` | Near-black violet with high-chroma purple and pink. |
| `solarized` | The fixed-lightness classic, designed as a matched light/dark pair. |
| `gruvbox` | Warm retro, high contrast — the only genuinely warm light mode here. |
| `catppuccin` | Pastel, with very close surface tones. Easy over a long reading session. |
| `tokyo-night` | Deep navy with violet and cyan; the most saturated dark. |

The two multiply: `theme="ledger" palette="nord"` is Ledger's dense ruled grid
in Nord's arctic blues, and `theme="elevated" palette="nord"` is Elevated's tall
airy one in the same blues. Six themes and six palettes is thirty-six looks out
of twelve class names. A palette on its own recolours the packaged default.

Each ships a light and a dark set, so `dark` keeps working across all of them.

These are the colour schemes people already know from their editors. The hues
are theirs; the mapping onto the grid's tokens — which colour becomes the
header, the stripe, the accent, the thing that has to stay readable *on* the
accent — and the contrast work that mapping needs are ours. No third-party
stylesheet is involved. Where a scheme publishes only a dark set, the light
counterpart is our own reading of the same hue family, and the stylesheet says
so at that block.

## Colour schemes

Thirty-six more colour sets on the same `palette` prop, built differently from
the six above: each is a handful of seed colours — page, cell, ink, accent and
optionally a header band — from which every token is **derived and then
measured**. Text is pushed until it reaches 4.5:1 on the surface it sits on, an
accent and a focus ring until they reach 3:1, so a scheme cannot ship a muted
label or an invisible focus ring.

Each scheme is one mode, light or dark, and carries it with it: `dark` does not
flip a scheme, the scheme decides. Pick a dark one for a dark app.

They come as separate stylesheets so you load only what you use. Load them
**after** `styles.css`:

```tsx
import '@kanunilabs/datagrid-react/styles.css';
import '@kanunilabs/datagrid-react/themes/graphite.css';
// or every scheme at once (~57 KB):
// import '@kanunilabs/datagrid-react/themes/all.css';

<DataGrid theme="minimal" palette="graphite" density="compact" … />
```

The vanilla package ships the same files under `@kanunilabs/datagrid/themes/`
and takes the same option:

```js
import '@kanunilabs/datagrid/styles.css';
import '@kanunilabs/datagrid/themes/linen.css';

createGrid(host, { …, theme: 'ledger', palette: 'linen' });
```

A scheme recolours every surface the grid draws — the header band, rows,
stripes, selection and range, totals and group rows, the filter and column
menus, the editor and its validation message, the chart panel (its series are
derived from the scheme's accent, as below), the status bar and dialogs.
Structure stays with `theme`: `theme="ledger" palette="corporate"` keeps
Ledger's ruled, dense layout under Corporate's ink header.

| `palette` | Mode | Family | Character |
|---|---|---|---|
| `porcelain` | Light | neutral | Crisp white, cool ink and a clear blue — the everyday default. |
| `ivory` | Light | neutral | Warm off-white with a bronze accent; quiet and premium. |
| `stone` | Light | neutral | Warm greys and a graphite accent — low noise, high polish. |
| `mist` | Light | cool | Cool grey surfaces and a steel-blue accent for analytical work. |
| `glacier` | Light | cool | Blue-grey header band over white cells, a deep sky accent. |
| `slate` | Light | cool | Light slate surfaces with an indigo-slate accent; technical and calm. |
| `linen` | Light | warm | Cream cells and a sage accent; natural and soft for long sessions. |
| `sandstone` | Light | warm | Sand and beige with a terracotta accent. |
| `taupe` | Light | warm | Soft grey-brown neutrals and a cocoa accent; understated. |
| `azure` | Light | colorful | A blue-tinted header band and a confident blue accent. |
| `indigo` | Light | colorful | White cells under a lavender band, an indigo accent. |
| `teal` | Light | colorful | Fresh mint band and a deep teal accent. |
| `lagoon` | Light | colorful | Cyan-washed surfaces and an ocean accent. |
| `emerald` | Light | colorful | Green-tinted band and an emerald accent; good for finance. |
| `orchid` | Light | colorful | Soft violet band and a vivid violet accent. |
| `rose` | Light | colorful | A blush band and a muted crimson accent. |
| `amber` | Light | colorful | Honey band and an amber accent; warm and bright. |
| `coral` | Light | colorful | Peach band and a coral-orange accent. |
| `corporate` | Light | specialty | An ink header band over white cells; boardroom-formal. |
| `editorial` | Light | specialty | Paper white and deep red, like a printed report. |
| `monochrome` | Light | specialty | Pure greyscale: no hue anywhere, the accent is ink. |
| `contrast-light` | Light | specialty | Black on white with strong rules, for low vision and bright rooms. |
| `charcoal` | Dark | neutral | Neutral charcoal with a soft blue accent; the everyday dark. |
| `graphite` | Dark | neutral | Mid-grey graphite and a silver-blue accent; gentle contrast. |
| `onyx` | Dark | neutral | Soft black for OLED screens, with a lilac accent. |
| `slate-night` | Dark | cool | Deep slate and a sky accent — technical and cool. |
| `steel` | Dark | cool | Blue-grey steel surfaces and a cornflower accent. |
| `midnight` | Dark | colorful | Navy depth with a bright blue accent. |
| `indigo-night` | Dark | colorful | Indigo-tinted dark and a periwinkle accent. |
| `forest` | Dark | colorful | Deep green-black with an emerald accent. |
| `deep-sea` | Dark | colorful | Dark teal water and an aqua accent. |
| `aubergine` | Dark | colorful | Plum-dark surfaces with a soft violet accent. |
| `burgundy` | Dark | colorful | Wine-dark and a rose accent; warm for a dark. |
| `ember` | Dark | colorful | Brown-black with a glowing amber accent. |
| `contrast-dark` | Dark | specialty | White on black with bright rules and a yellow accent. |
| `terminal` | Dark | specialty | Green-on-black for dense, data-heavy monitoring screens. |

The list is exported, so a picker never drifts from what is installed:

```ts
import { COLOR_SCHEMES } from '@kanunilabs/datagrid-core';
// [{ id: 'porcelain', name: 'Porcelain', mode: 'light', family: 'neutral', description: '…', seed: {…} }, …]
```

### Your own scheme

The derivation is public. Give it seeds and it returns the tokens; turn those
into `--dg-*` properties and set them on the grid's container — no class, no
CSS file:

```tsx
import { deriveSchemeTokens, dataGridSchemeVars } from '@kanunilabs/datagrid-core';

const tokens = deriveSchemeTokens(
  { background: '#f4f1ea', surface: '#fffdf8', text: '#1d1a14', accent: '#0f6b5c' },
  'light',
);

<div style={dataGridSchemeVars(tokens)}>
  <DataGrid … />
</div>
```

Inline properties on a wrapper reach the grid itself; popups are portalled to
`<body>` and do not inherit them. For a scheme that also covers menus and
dialogs, write the stylesheet instead — `dataGridSchemeCss('acme', tokens)`
returns it, for `palette="acme"` — or build one in the
[Theme Builder](https://kanunilabs.com/theme-builder), which exports that CSS, a JSON file to import
again later, and the PivotGrid equivalent.

`schemeContrastChecks(tokens)` returns the nineteen contrast pairs the packaged
schemes are tested against, each with its measured ratio, so your own can be
held to the same floor.

## Density

`density` is `'compact' | 'normal' | 'comfortable'`, and it is not a font-size
switch. Row height, header height, cell padding, control heights, toolbar and
pager padding and the filter field all move together, so the proportions hold:

| | `compact` | `normal` | `comfortable` |
|---|---|---|---|
| `ledger` | 20px rows, 11px type | 25px, 12px | 32px, 13px |
| `minimal` | 26px, 12px | 36px, 13px | 44px, 14px |
| `elevated` | 32px, 13px | 40px, 14px | 52px, 15px |

Each theme scales from **its own** normal rather than a shared table — Elevated
starts at 40px and Ledger at 25px, and one common compact value would have
flattened the presets into each other at that density.

An explicit `rowHeight` still wins over both props. Density is a shorthand, not
an override.

## Charts follow the theme

When a theme is set, the chart panel derives its series colours from that
theme's accent instead of a fixed palette — so an Elevated grid does not draw its
first bar in someone else's blue. The first series *is* the accent; the rest are
hue rotations of it that keep its saturation and lightness, which is what makes
a dark theme's series come out light enough for a dark canvas.

The colours are resolved to literals rather than left as `var()`, for two
reasons that both bite: recharts writes the colour as an SVG presentation
attribute, which does not support `var()`, and PNG/SVG export serializes the
chart into a standalone file with no stylesheet behind it.

Without a `theme`, the packaged eight are used, unchanged.

## Writing your own

A theme here is a set of **CSS custom property overrides and nothing else**.
Everything the stylesheet draws with — every colour, metric, shadow and border —
is read through a `--dg-*` property, so a theme never restyles a component and
can never fall behind one.

Yours is a **name**, passed to the same `theme` prop the packaged ones use:

```tsx
<DataGrid theme="acme" rowHeight={30} … />
```

The grid turns it into the class `kanuni-datagrid-theme-acme` and puts that
class on every surface it draws — the grid itself, the Enterprise wrapper (chart
panel, status bar, filter and edit strips) and every popup and dialog, which are
portalled to `<body>` and could not inherit a class through the cascade. Write
the tokens on the three roots those surfaces carry, exactly as the packaged
themes do:

```css
.kanuni-datagrid-root.kanuni-datagrid-theme-acme,
.kanuni-datagrid-enterprise.kanuni-datagrid-theme-acme,
.kanuni-datagrid-detached.kanuni-datagrid-theme-acme {
  --dg-surface: #fffdf8;
  --dg-surface-header: #f4efe4;
  --dg-border: #e4dccb;
  --dg-text: #1b1811;
  --dg-primary: #8a6d2f;
  /* What sits ON the accent. Set it: white on a light accent is unreadable,
     and this is the token that decides a chip label and a primary button. */
  --dg-on-primary: #ffffff;

  --dg-row-height: 30px;
  --dg-header-height: 34px;
  /* A whole shorthand, so a theme can drop a rule entirely rather than fade it. */
  --dg-cell-border: none;
}
```

The two-class selectors matter: each root declares the default tokens itself,
so a single-class rule wins or loses by stylesheet order alone.

One caveat with `--dg-row-height`: the virtualizer computes every row offset and
the scroll extent from the row height, so it has to reach the engine as a
number. A custom theme has no preset row height — set `rowHeight` alongside your
CSS, or use `density`, and the two stay in agreement.

**`className` is not the channel for a theme.** It lands on the grid root only:
not on the Enterprise wrapper, not on any popup. Keep it for layout — size,
margin, a border around the grid. (Earlier versions of this page said to theme
through `className`; that styled the grid and left its popups, and on
`EnterpriseDataGrid` its chart panel and status bar, in the default palette.)

### The tokens

**Surfaces** — `--dg-bg`, `--dg-surface`, `--dg-surface-hover`,
`--dg-surface-stripe`, `--dg-surface-header`, `--dg-group-bg`, `--dg-footer-bg`,
`--dg-selected-bg`, `--dg-overlay`

**Header band** — `--dg-header-bg`, `--dg-header-text`,
`--dg-header-text-muted`, `--dg-header-hover`, `--dg-header-weight`,
`--dg-header-transform`, `--dg-header-tracking`, `--dg-header-font-size`

The header is deliberately separate from `--dg-surface-header`: they default to
the same value, but an ink header still wants a light group panel, filter row
and footer.

**Text and accent** — `--dg-text`, `--dg-text-muted`, `--dg-primary`,
`--dg-primary-soft`, `--dg-on-primary`, `--dg-focus-ring`, `--dg-danger`,
`--dg-danger-text`, `--dg-on-danger`, `--dg-warning`

**Line work** — `--dg-border`, `--dg-border-strong`, `--dg-cell-border`,
`--dg-row-border`, `--dg-header-cell-border`, `--dg-header-border`

**Metrics** — `--dg-row-height`, `--dg-header-height`, `--dg-cell-padding-x`,
`--dg-font-size`, `--dg-radius`, `--dg-radius-control`, `--dg-control-height`,
`--dg-control-font-size`, `--dg-filter-input-height`, `--dg-chrome-font-size`,
`--dg-chrome-padding-y`

**Elevation** — `--dg-shadow-popup`, `--dg-shadow-popup-sm`,
`--dg-shadow-menu`, `--dg-shadow-card`, `--dg-shadow-panel`,
`--dg-shadow-dialog`, `--dg-shadow-pinned`, `--dg-shadow-pinned-right`

**Scrollbar** — `--dg-scrollbar-thumb`, `--dg-scrollbar-track`. Only applied
when a theme is set; an unthemed grid keeps the platform scrollbar.

## Theme Builder

The [Theme Builder](https://kanunilabs.com/theme-builder) designs a colour theme on the real grids.
Start from one of the 36 packaged colour schemes, change any of its seed
colours — background, cells, text, accent, header band, borders, status
colours — and the DataGrid and PivotGrid beside it follow, menus and filter
popups included. Contrast is measured on every change, and colours the theme
had to deepen to stay readable are listed.

It exports three files under the id you give the theme:

- **CSS** — the DataGrid palette block and the PivotGrid `data-theme` block.
  Load it after the grid stylesheets and pass the id:

  ```tsx
  <DataGrid palette="acme" … />
  <BasePivotGrid theme={{ id: 'acme' }} … />
  ```

- **JSON** — the theme definition (seed, mode and any pinned tokens). Import it
  back into the builder to keep editing.
- **PivotGrid `theme` object** — the same colours for an app that sets them
  from code.

The preview on that page is drawn with the same generated stylesheet the CSS
export contains. Structure (`theme`) and `density` stay separate props and are
not part of the export.

## Contrast

Every packaged theme and palette clears WCAG AA (4.5:1) on the surfaces that
carry text, measured rather than assumed, and the floor is pinned by a test so a
colour cannot be nudged for looks and quietly drop below it.

The thirty-six colour schemes are held to nineteen pairs each — text on the page and on cells,
stripes, hovered and selected rows and totals; muted text on cells and panels;
header text, plain and muted; the accent on cells and on the header band; the
focus ring; the label on the accent and on the danger fill; error, success and
warning text; search highlights. A test also fails if two schemes of the same
mode come out too close to tell apart.

Three palettes needed a correction to get there, which is the point of measuring
rather than trusting the source scheme: Nord's muted red left its own label at
4.31:1, Gruvbox's light yellow sits at 3.33:1 on its cream ground, and Tokyo
Night Day's keyword blue is a keyword colour rather than a body ink and measured
4.03:1 on the header. Each was moved within its own hue family.

`--dg-on-primary` is the one to be careful with in a theme of your own. It is
what sits *on* the accent — a group chip's label, a primary button's text — and
the house theme is the case that proves it: the KanuniLabs gold is `#c5a55a`,
and white on it measures 1.9:1. Set the token, do not inherit it.

## Cost

None on the render path. The browser resolves custom properties during style
computation, so a themed grid does no more work per cell than an unthemed one,
and there is no per-cell React work of any kind — the theme is one class on the
root, composed once per grid.

---

Source: https://kanunilabs.com/theme-builder

# DataGrid: Theme Builder

Build a colour theme for a React or JavaScript data grid and pivot table: start from 36 light and dark schemes, check WCAG contrast live, and export the CSS. Free.

Read it at https://kanunilabs.com/theme-builder

---

Source: https://kanunilabs.com/docs/datagrid/charts

# Charts

[Try it live](https://kanunilabs.com/playground/datagrid/charts) — 50,000 rows, the panel and every
option on this page.

Charting is split the same way the rest of the grid is: the **model** is
Community, the **renderers and the panel** are Enterprise.

| | Package | What you get |
|---|---|---|
| Model | `@kanunilabs/datagrid-react` | `useGridChartData()` — categories and aggregated series, ready for any chart library |
| Panel | `@kanunilabs/datagrid-react-enterprise` | The dock panel, six renderers, pickers, fullscreen, cross-filtering |

## The panel (Enterprise)

One prop:

```tsx
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';

<EnterpriseDataGrid
  licenseKey={key}
  dataSource={rows}
  rowKey="id"
  columns={columns}
  charting
/>
```

That adds a **Chart** button to the toolbar and a **Chart by this column** entry
to every column header's right-click menu. The panel docks above the grid — not
over it, because watching the chart follow a filter you just applied is the
point, and a modal would hide the grid doing the filtering. When the grid needs
the room, **Pop out** turns the panel into a window over it
([A floating window](#a-floating-window)).

The pickers are built from the grid's own column model, so there is no list to
keep in sync: hide a column and it leaves the pickers with it.

### Options

```tsx
<EnterpriseDataGrid
  charting={{
    crossFilter: true,   // clicking a category filters the grid. Default false.
    defaultOpen: true,   // dock the panel open instead of waiting for the button.
    height: 280,         // docked canvas height in px. Default 280.
    floating: true,      // open as a window over the grid (or { x, y, width, height }).
    container: box,      // or put the chart in an element of yours instead (below).
    defaultSpec: { categoryColumnId: 'region' },
    defaultStacking: 'stacked', // 'grouped' (default) | 'stacked' | 'normalized'
    defaultFormat: { title: 'Sales by region', legend: 'right', dataLabels: true },
    onFormatChange: (format) => save(format), // the reader's Format edits, to keep
    labels: { title: 'Grafik' },
  }}
/>
```

`recharts` is an **optional** peer dependency, loaded only when the panel is
first opened. A grid that never charts does not pull it into the bundle:

```bash
npm i recharts
```

Without it the grid builds and runs as usual; opening the chart panel says the
package is needed. (Up to `@kanunilabs/datagrid-react-enterprise` 1.2.0 the
published build imported recharts at load time despite this — an app without
it failed to start, and one with it carried it in the main bundle. A build
check now keeps optional peers behind a dynamic `import()`.)

## Chart types

`column` · `bar` · `line` · `area` · `pie` · `donut` · `radar` · `scatter` ·
`bubble` · `waterfall` · `funnel` · `treemap` · `heatmap` · `rangeBar` · `box`

A **radar** puts one spoke per category round a circle and draws each series
as a polygon over them, on rings at round values — for comparing a few series
across the same handful of categories. Each vertex has a tooltip; in the
JavaScript panel a click on one cross-filters like a bar.

The list is a registry, not a `switch`. Register your own renderer — D3,
ECharts, hand-written SVG — and it appears in the type picker beside the
built-ins:

```tsx
import { chartRegistry } from '@kanunilabs/datagrid-react-enterprise';

chartRegistry.register({
  def: { id: 'radar', label: 'Radar', requiresCategory: true },
  render: (model, ctx) => <MyRadar model={model} colors={ctx.colors} />,
});
```

`model` is the same `ChartModel` described below; `ctx` carries the locale,
colours, hidden-series set, the measured canvas size, the series layout
(`ctx.stacking`) and the cross-filter callback.

### Waterfall, funnel, treemap and heatmap

- **Waterfall**: each category moves a running total. Rises and falls are
  coloured apart, a dashed connector carries the total to the next bar, and a
  closing **Total** bar stands on zero.
- **Funnel**: the categories as stages, in the order they come (the order is
  the process, so it is never re-sorted). Each stage is labelled with its value
  and its share of the first stage.
- **Treemap**: a rectangle per category with its area proportional to the
  value, laid out to stay close to square. Zero and negative values take no
  area.
- **Heatmap**: categories across, series down, each cell coloured by its value
  on one scale over the whole matrix. Values print in the cells that have room.

The first three show one series; the heatmap shows every visible series. Each
cell or bar has a tooltip and takes part in cross-filtering like a column.

### Range

A floating bar per category, from one series to the other: the lowest and
highest price of each month, a planned against an actual figure. Pick two
series, for example the same column with `min` and with `max`:

```tsx
charting={{
  defaultType: 'rangeBar',
  defaultSpec: {
    categoryColumnId: 'month',
    series: [
      { columnId: 'price', aggregate: 'min' },
      { columnId: 'price', aggregate: 'max' },
    ],
  },
}}
```

Either series can be the low one: each category runs from its own smaller value
to its larger one. Both ends are labelled, and each end is drawn in its own
series' colour so the legend matches the chart. A category missing either value
draws no bar, and with only one series visible there is no range to draw. The
tooltip shows both ends; a click cross-filters like a bar.

### Box plot

A box per category shows the **spread** of one number column, where every
other type reduces the category to a single number: the box spans the first to
the third quartile with a line at the median, the whiskers reach the furthest
values within 1.5 × the box's height, and anything beyond them is a dot. The
series has no aggregate — the box is the values themselves — and a text column
picked for it moves to the first number column. Dates and numbers on the
category axis group by the same intervals as the other charts; past 30
categories the most populous ones are kept and the panel says so. The tooltip
lists the five numbers and the count; a click on a box cross-filters like a
bar. The values are held to find the medians, so it is computed on the main
thread, as scatter is.

### Scatter and bubble

Every other type is a group-by: a category and an aggregate per series.
**Scatter** and **bubble** are not. They plot one point per row:

- the category picker becomes the **x axis**, offering number and date columns
  (a date axis reads as dates);
- each series is a **y column**, with no aggregate to choose;
- a bubble adds a **size** column, and the bubble's *area* follows the value,
  which is how a reader compares circles.

A million points is not a chart anyone can read, and an SVG with a million
circles is not a page that responds. So each series shows at most 2,000
points. Past that, rows are taken evenly through the current order, every
k-th row, and the panel says how many of how many it shows. The tooltip prints
x, y and size the way their own columns print them.

Without the panel, `controller.computeChartXYData(spec)` returns the same
points, and `useGridChartXYData(controller, spec)` (React) and
`watchChartXYData` (JavaScript) keep them current.

### Grouped, stacked and 100% stacked

With two or more series, column, bar, line and area charts offer three layouts
in the panel's toolbar:

- **Grouped**: the series stand side by side. The default.
- **Stacked**: each category is one bar (or band) cut into the series, so its
  height is the total and each segment is one series' part of it.
- **100% stacked**: every category is the same height and each segment is a
  share of it. The value axis reads in percent.

The rules are the ones spreadsheet charts use. Negative values stack downward
from zero, apart from the positives. A series with nothing to total in a
category leaves a gap, and the rest stack past it. A 100% share is taken of
the **absolute** total, so a negative value takes its share below the axis.
A stack has one baseline, so the automatic second axis (below) does not apply.
The tooltip always shows the real value, with the share beside it in 100%.

Open on a layout with `defaultStacking`. In JavaScript the same option exists
on `charting`, and `grid.chartPanel.open({ stacking: 'normalized' })` opens
straight into it. Pie and donut show a single series and have no layout to
choose.

### Swapping categories and series

**Swap category and series** turns the chart around: each series becomes a
category and each category a series. "Revenue and cost, per region" becomes
"each region's revenue and cost" — the same numbers, read the other way, with
nothing aggregated again. Press it again to swap back. It is offered for every
type except the X-Y ones (scatter, bubble) and the box plot, where a point or a
box has no category to swap.

While swapped, the categories are column names, so a click on a mark filters
nothing (cross-filtering waits until you swap back), and the bucket bounds of a
date or number axis no longer apply. At most 24 categories become series; past
that the chart says it is cut. Series values print in their column's format
when every series read the same column, and as plain numbers otherwise. The
legend switches and the zoom start over, since the positions they named
changed meaning.

The swap is part of the chart state (`switched: true`, no key when not), so the
saved view keeps it; `open({ switched: true })` opens swapped.

### Unlinking a chart from the grid

**Unlink** freezes the chart as it is: it keeps the data it had and no longer
follows the grid — filter, sort, edit or add rows and the chart stays put, which
is what you want when comparing "before" with "after". The type (among types
that read the same kind of data), the format, the stacking and the swap still
change; what would need fresh data — the columns, the rows it reads, the
grouping, or a scatter or box plot from a bar chart — is switched off until you
press **Link**, which draws the grid as it is now. A note under the chart says
it is unlinked.

The state has `unlinked: true` while it is. A saved view keeps that, but not the
data: a restored unlinked chart takes the grid's data once, as it is when it
opens, and keeps that. While unlinked, `open()` changes to the columns or rows
are recorded and take effect when linked again.

### A column's part in charts

A column definition can say what it is to a chart, with `chartRole`:

```tsx
const columns = [
  { field: 'region', chartRole: 'category' },  // the panel's first choice for the axis
  { field: 'margin', chartRole: 'series' },    // its first choice for the series
  { field: 'period', chartRole: 'time' },      // a date axis, grouped by calendar
  { field: 'internalId', chartRole: 'excluded' }, // never in a chart
];
```

`'excluded'` keeps a column out of the panel's pickers, out of the header menu's
**Chart by this column**, and out of a charted selection. `'time'` treats a
column the grid types as text (say `'2026-06'`) as dates. Without a role the
panel decides by data type, as before.

### Format: titles, legend, labels, text, grid and lines

The panel's **Format** button opens an editor for what a reader usually wants to
change before sending a chart on:

- a **title** above the chart,
- a **title for each axis**,
- the **legend** at the top, bottom, left or right, or hidden,
- **data labels**: each value printed on its mark (on a 100% stack, its share).
- the **value scale**: linear, or logarithmic for values that span several
  orders of magnitude. A log axis cannot show zero or a negative value, so
  those marks are left out. A stacked chart keeps the linear scale.
- the **text size and colour** of everything written in the chart: tick
  labels, axis titles, data labels. Titles draw one step larger, data labels
  one step smaller.
- the **category labels**: slanted (the default), flat, 45 or 90 degrees.
- the **grid lines**: along the value axis (the default), along both axes, or
  none; dashed or solid.
- the **series lines**: width and dashes for lines, area outlines and radar
  shapes, and the fill opacity of areas, radar shapes and bubbles.
- the **colours** of the series: *Theme* (the default, derived from the grid's
  accent), *Classic*, *Colour-blind safe* (the Okabe–Ito hues), *Vivid* or
  *One colour* (shades of the accent). Every colour of a named palette is
  moved, where it must be, to at least 3:1 contrast with the chart's
  background, so the same palette stays visible on a light and a dark colour
  scheme — measured for all 36 schemes in the test suite.

Every one of these starts at "Default", which leaves the field out of the
format, and a chart drawn without them looks exactly as it did before. From code
the same fields are on `ChartFormat`, plus a font family and bold or italic text
that the editor does not offer:

```tsx
defaultFormat: {
  font: { family: 'Inter, sans-serif', size: 13, color: '#334155', bold: false, italic: false },
  labelAngle: 0,            // 'auto' | 0 | 45 | 90
  gridLines: 'both',        // 'value' | 'both' | 'none'
  gridDashed: false,
  lineWidth: 3,             // 1–6 px
  lineDashed: false,
  fillOpacity: 0.4,         // 0.05–1
  palette: 'colorblind',    // 'theme' | 'classic' | 'colorblind' | 'vivid' | 'monochrome'
}
```

For a brand palette, give the colours themselves. `colors` is used in order and
repeated, exactly as given, and wins over `palette` — the Colours picker is then
disabled, since the app has already chosen:

```tsx
defaultFormat: { colors: ['#0f6b5c', '#e07a1f', '#4b5bd6', '#b83280'] }   // #rgb or #rrggbb
```

A saved format is read back defensively: a size, width or opacity out of range
and a font or colour that could break out of a style attribute are dropped,
not drawn. Text written on a coloured cell (a treemap tile, a heatmap cell)
keeps the colour chosen for contrast with that cell.

Open with `charting.defaultFormat`, and keep the reader's edits with
`onFormatChange`. The format is plain data, so it fits in a saved view. In
JavaScript the same two options sit on `charting`, and
`grid.chartPanel.open({ format })` opens with a given one.

Axis titles and data labels are drawn inside the chart, and an exported PNG or
SVG gets the title as well. A label wider than its bar is left out instead of
being printed over the next one; the tooltip still shows that value.

**Values print the way their column prints them.** Tooltips and data labels run
a `sum`, `avg`, `min` or `max` through the column's own `valueFormatter`, the
same rule as the footer. A currency column reads as currency in its chart too.
`count` and distinct count are row counts and keep a plain number.

### Axis labels of your own

The axes print compact numbers (`12.5k`), the categories, and date groups in the
chosen date format. To write the tick labels yourself, give the grid one
function, `charting.axisLabelFormatter`. It is asked for every tick label on both
axes, with the raw value and the text the chart would print — return `text` to
keep the default:

```tsx
const axisLabelFormatter = useCallback((p: ChartAxisLabelParams) => {
  if (p.axis === 'value') return p.percent ? p.text : `€${p.text}`;
  // A date group's raw value is its first day, in ms since the epoch.
  if (p.columnId === 'orderedAt' && typeof p.value === 'number') {
    const d = new Date(p.value);
    return `Q${Math.floor(d.getUTCMonth() / 3) + 1} '${String(d.getUTCFullYear()).slice(2)}`;
  }
  return p.text;
}, []);

<EnterpriseDataGrid charting={{ axisLabelFormatter }} />
```

| Field | |
|---|---|
| `axis` | `'value'` or `'category'`. A scatter's or bubble's x axis is the category axis. |
| `value` | The raw value. Value axis: the tick's number. Category axis: the category (`''` for a blank) — on an axis grouped by date or number, the group's lower bound as a number (ms for dates); on a scatter's x axis, the x value. |
| `text` | What the chart prints without you: after the number and date format settings, `(blank)` for a blank. |
| `columnId` | Category axis: the column it reads. |
| `percent` | A 100% stack's value axis: `value` is a share from 0 to 100. |
| `secondary` | The right-hand axis that much smaller series move to. |
| `chartType` | `'column'`, `'line'`, `'waterfall'`, a type of your own… |

It covers the cartesian types, radar, scatter and bubble, and the axes of the
waterfall, heatmap, range and box charts. Pie, donut, funnel and treemap have
no axes. Tooltips and data labels keep their own text — except, in the React
panel, the built-in tooltip of a waterfall, heatmap, range or box mark, which
those layouts draw from the same category text as the axis. A range bar's two
end values are printed the way its axis prints numbers, so they follow the
formatter as value labels too.

A function cannot be saved, so it lives on the grid's options and never in the
chart's state: `getState()` and a saved view stay plain data, and the formatter
applies to every chart window of the grid. It runs while the chart draws, so
keep it quick, and stable — in React a new function draws the chart again. A
formatter that throws, or returns something other than a string, leaves that one
label at its default. In JavaScript the same option sits on `charting`, and a
renderer of your own gets it as `ctx.formatAxisLabel`.

## What the chart aggregates

A chart is a **group-by**: one category column, one or more value series.

```tsx
const spec = {
  categoryColumnId: 'region',
  series: [
    { columnId: 'revenue', aggregate: 'sum' },
    { columnId: 'units', aggregate: 'avg' },
  ],
  source: 'view',
};
```

Aggregations are the grid's own: `sum` `avg` `min` `max` `count` `countDistinct` —
plus two that only a chart has: `first` and `last`, the first and the last number
of each category **in the grid's order**. With the grid sorted by date, `last` is
each month's closing value. A sort therefore changes these two (and only these:
the others do not care about order, and a sort leaves their charts alone). A
selection is read in the grid's order too, not the order it was picked in; `all`
reads the rows in their source order.
They are computed by the **same reducers as the footer totals**, so a bar and the
footer total of that column can never disagree — blanks are skipped rather than
counted as zero, `count` is COUNTA, and date columns are parsed before reducing.

A non-numeric column only offers `count` and `countDistinct`: summing a warehouse
code runs `Number('WH-04')`, which is NaN for every row and a silently blank
series.

### Which rows

`source` decides, and the answer is explicit rather than implied:

| `source` | Rows charted |
|---|---|
| `'view'` (default) | Filtered and searched rows, **before** paging |
| `'selection'` | The selected rows — falling back to `'view'` when nothing is selected, so the chart is never silently empty |
| `'all'` | Every source row, ignoring the filter |
| `'range'` | The rows of a cell range, by position (below) |

### Charting a cell range

Select cells over several rows, right-click and pick **Chart selected cells ▸**
and a type: the chart reads exactly those rows, its category the range's first
text column and its series the number columns in it. (A single row, or a column
from the header menu, charts the whole view as before.) The source picker says
which rows — "Selected range (rows 2–5)" — and choosing another source forgets
the range.

The grid paints the cells the chart reads: the category column **green**, the
series columns **blue**, the colours spreadsheet charts use. The range's
bottom-right cell has a small handle; drag it up or down and the chart follows
as soon as you let go. (A selection made inside the painted range shows over
it.)

A range is **positions**, the way a cell range is: sort or filter the grid and
the chart reads whatever rows now sit at those positions, so what it shows and
what is painted always agree. In the state it is `source: 'range'` with
`rowRange: { start, end }` — view positions, 0-based, inclusive — and from code:

```ts
chart.open({
  categoryColumnId: 'region',
  series: [{ columnId: 'revenue', aggregate: 'sum' }],
  source: 'range',
  rowRange: { start: 0, end: 9 },   // the first ten rows of the view
});
```

Group header rows take a position too (as they do in a cell range) and are not
data, so a range across a group header charts the data rows on either side.
Extra chart windows can read ranges of their own; each is painted and has its
own handle.

### Continuous columns: dates and numbers

A date column has one distinct value per order date. Charted raw, 900 dates
become 900 categories, of which the cap below keeps 30 and folds 870 into
"Other" — an axis with no chronology left in it. So a date axis is **grouped by
an interval** instead:

```tsx
const spec = {
  categoryColumnId: 'orderedAt',
  series: [{ columnId: 'revenue', aggregate: 'sum' }],
  categoryBucket: { kind: 'date', unit: 'month' },   // or 'auto'
};
```

`unit` is `'auto'` (the default) or `day` · `week` · `month` · `quarter` ·
`year`. `'auto'` measures the data's own span and picks the finest unit that
still fits a readable axis. In the panel this is the **By** picker, which
appears whenever the category column is a date or a number.

A date axis prints its groups as `2026-03`, `2026-Q1` and so on. The Format
editor's **Date format** (shown only on a calendar axis) prints them in a preset
instead, written by the browser in the chart's language — `monthYearLong` is
"March 2026" in English and "Mart 2026" in Turkish. In code it is
`format.dateFormat`. The samples below are as Node 24 writes them; a browser's
own date library may differ in small details:

| Preset | en-US | tr-TR |
|---|---|---|
| `iso` | 2026-03-05 | 2026-03-05 |
| `numeric` | 03/05/2026 | 05.03.2026 |
| `dayMonth` | Mar 5 | 5 Mar |
| `dayMonthYear` | Mar 5, 2026 | 5 Mar 2026 |
| `long` | March 5, 2026 | 5 Mart 2026 |
| `weekday` | Thu, Mar 5 | 5 Mar Per |
| `month` | Mar | Mar |
| `monthYear` | Mar 2026 | Mar 2026 |
| `monthYearLong` | March 2026 | Mart 2026 |
| `monthNumeric` | 03/2026 | 03.2026 |
| `year` | 2026 | 2026 |

Each group prints its **first** day: a quarter shown as `monthYear` reads "Jan
2026" for Q1. The groups are calendar intervals in UTC, so the label is the
same in every time zone. Tooltips use the same text; a cross-filter still reads
the group's bounds, not its label.

A numeric column bins the same way:

```tsx
categoryBucket: { kind: 'number', bins: 20 }   // or an exact { size: 50 }
```

`bins` is a target: the width is rounded to a 1/2/5×10ⁿ step, so asking for 20
bins over a 0–500.000 range gives ten bins of 50.000 rather than twenty of
23.817.

A bucketed axis behaves differently on purpose:

- **Ordered by the interval**, never by value. `categoryOrder` is ignored.
- **Empty intervals are kept.** A month with no orders is information, and a
  chart that closes the gap draws a line straight through it as though the
  months were adjacent. Those bars are `NaN`, not `0`.
- **No "Other" and no top-N.** An "Other" in the middle of a time axis is not a
  category, it is a hole. When there would be too many intervals the unit is
  **coarsened** instead — every row stays in the chart, the axis just gets less
  granular, and `model.bucket.adjusted` says it happened.
- **Rows whose value will not parse** go to the blank category rather than
  being dropped without trace.

Everything is UTC. Local bucketing would put the same row in a different day
depending on where the browser is, and `Date.parse('2023-01-15')` is UTC
midnight anyway.

Weeks start on Monday and are labelled by that Monday's date rather than
`2023-W03`: the ISO week number disagrees with the calendar year at both ends of
December, and a chart axis is a bad place to explain that.

### Categories are capped

`maxCategories` (default 30) keeps the top categories by value and collapses the
rest into a single **Other** bucket. This is not cosmetic: a grid's category axis
is a raw column, so pointing it at an id column would otherwise ask for a million
categories.

"Other" is folded from the accumulators, not from the finished numbers — so its
average is the average of its **rows**, not the average of the averages it
swallowed, and the grand total stays exact.

### Two axes when the scales differ

Revenue summed over a million rows is ~10⁸; units over the same rows ~10⁶. On one
axis the second series is a hundredth of the chart and draws as a flat line —
present in the legend, invisible in the plot. When one series is more than 25×
smaller than the largest, it moves to its own right-hand axis automatically.
Stacked layouts keep every series on one axis: a stack has a single baseline.

## Cross-filtering

Off by default, because a chart click that suddenly re-filters the grid is
surprising. With `crossFilter: true`, clicking a bar or slice applies that
category as a grid filter. The chart keeps every category on screen — the
picked one at full strength, the rest faint — so the next one is there to
click.

On a **bucketed** axis the click applies a half-open range —
`>= 2023-01-01 AND < 2023-04-01` — not an equality. `= '2023-Q1'` would match no
row, because "2023-Q1" is a label the engine invented; and an inclusive
`between` would put the first of April in the first quarter as well as the
second.

Clicking the **same** mark again clears the filter, and while one is applied the
panel says so with a Clear link beside it. Both exist because the condition does
not come from an input: the filter row stays empty, so without them the user is
looking at 8.000 of 50.000 rows with nothing on screen to press.

The filter **replaces** whatever was active rather than narrowing it — one
click, one condition, and a second click gets you back. (It is the grid's own
filter, the one `setFilter` holds; the filter row and the header menus filter
separately and keep applying.)

### Several categories at once

Hold **Ctrl** (**Cmd** on a Mac) and click: that category joins the selection,
and the grid shows the rows of **any** picked category. Ctrl-click a picked one
to take it out again; the last one out clears the filter. On the grid it is one
condition per category under an OR:

```ts
controller.getFilter();
// { logic: 'or', nodes: [
//   { columnId: 'region', operator: '=', value: 'North' },
//   { columnId: 'region', operator: '=', value: 'East' },
// ] }
```

As with one category, the chart keeps every category on screen, the picked
ones at full strength and the rest faint; the note reads "The grid is filtered
to North or East." To do that it reads the view **without its own filter** —
the column filters, the quick search and an external filter still apply. A
plain click goes back to one category.

A click on the chart's **background** clears what the chart put on the grid,
however it was picked. A filter that is not the chart's (typed in the filter
row, set by your code) is left alone.

**From the keyboard**, the chart is one tab stop: <kbd>Tab</kbd> to it, and
the arrow keys (or <kbd>Home</kbd> / <kbd>End</kbd>) move a focused
category. A chip at the top of the chart names it with its values and
position ("North: Revenue 20 — 2 of 4"), its bars are outlined, and the chip
is a live region, so a screen reader says the same. <kbd>Enter</kbd> or
<kbd>Space</kbd> does what a click does, <kbd>Ctrl</kbd> (<kbd>Cmd</kbd> on a
Mac) adds like a Ctrl-click, and pressing it again on a picked category takes
it out. On a zoomed chart the view follows the focus; <kbd>+</kbd>,
<kbd>−</kbd> and <kbd>0</kbd> still zoom. A click moves the keyboard's focus
to the bar it hit. In React the outline is drawn on bars and slices; on a line
or area the chip alone shows the focus.

### Charts filtering each other

Every chart that reads the view (`source: 'view'`, the default) follows the
grid, so a cross-filter set from one chart narrows all the others. Open a
second chart window by month and click a region in the first: the second
redraws for that region's rows; Ctrl-pick three regions and it shows those
three. A click in the second chart **replaces** the first chart's pick rather
than narrowing it further, since there is one grid filter — the first chart
then follows the grid like any other.

## Zoom and pan

Once an axis is bucketed it can legitimately hold hundreds of points, so the
panel lets you look closer:

| | |
|---|---|
| **Scroll** over the chart | zoom in and out, around the pointer |
| **Drag** | pan (only while zoomed) |
| **← →** | pan by a quarter of the window |
| **+ −** | zoom from the centre |
| **0** or **Home** | show everything |

While a window is active the panel says *"Showing 295 of 900"* with a **Show
all** beside it.

This is a **slice of the model**, not a transform of the picture and not a
library feature. The chart engine hands the renderer a smaller `ChartModel`;
nothing is recomputed, and the series are `subarray` views over the same
buffers, so panning allocates nothing. That also means a renderer you register
yourself gets zooming without writing any:

```tsx
chartRegistry.register({
  def: { id: 'radar', label: 'Radar', requiresCategory: true, windowable: true },
  render: (model, ctx) => <MyRadar model={model} colors={ctx.colors} />,
});
```

`windowable` is off by default, and deliberately false for **pie** and
**donut**: a pie states "these are the parts of a whole", and a pie of 30 slices
out of 900 categories states something untrue. Zooming is offered only where it
does not lie.

A drag that ends on a bar does **not** cross-filter — the two gestures are kept
apart, so panning cannot filter the grid by accident.

## Performance

Aggregation runs **off the main thread** whenever the grid's worker is in play
(20.000 rows by default), reusing the columns the worker already encoded for
filtering and sorting. Measured on a million rows, two series:

| | Main thread | Worker |
|---|---|---|
| Aggregate | 111,7 ms | **33,0 ms** |

What crosses the worker boundary is `categories × series` numbers — 90 floats for
a 30-category, 3-series chart — not the rows.

Two rules keep it cheap while you use the grid:

- **A sort does not recompute the chart.** Aggregation is order-independent, so
  reordering a million rows costs the chart nothing.
- **Changing chart type does not recompute either** — the model is reused and
  only the renderer changes.

A filter, a search, or a data change does recompute; those are the things that
change the numbers.

> `aggregate: 'custom'` takes a reducer function, and a function cannot be sent
> to a worker. A spec using one is computed on the main thread.

## Messages in the plot

The canvas says what it is doing instead of showing an empty frame:

| Message | When |
|---|---|
| **Nothing to chart yet.** | The chart's rows hold nothing to chart. |
| **No visible series.** | Every series is switched off in the legend. The legend stays, to switch one back on. |
| **Loading…** | The chart is still being computed — the first open on a large grid, a new column or grouping, the first click of a Ctrl selection. |

"Loading…" waits **300 ms** before it shows, so the answers that land at once —
nearly all of them — never flash a message. It lies over the plot rather than
replacing it: a slow recompute keeps the previous chart readable under it until
the new one arrives. Before the first answer the canvas is blank, never "Nothing
to chart yet." — a chart that announces there is no data and then fills with
bars reads as broken. A recompute the grid starts on its own (a filter, an edit)
keeps the previous chart up without a message, as it always did.

All three are status regions (`role="status"`), so a screen reader hears what
the eye sees. They come translated in all twelve languages; rename them with
`charting.labels` — `empty`, `noVisibleSeries` and `loading` in React,
`chartEmpty`, `chartNoVisibleSeries` and `chartLoading` in JavaScript.

## The model without the panel (Community)

If you would rather draw the chart yourself, take the data and stop there:

```tsx
import { useGridChartData } from '@kanunilabs/datagrid-react';

const spec = useMemo(
  () => ({ categoryColumnId: 'region', series: [{ columnId: 'revenue', aggregate: 'sum' }] }),
  [],
);
const model = useGridChartData(controller, spec);
```

Memoize the spec — a new object reference recomputes. The hook subscribes to the
grid and returns:

```ts
interface ChartModel {
  categories: string[];        // '' for blanks, matching the checkbox filter
  series: Array<{
    label: string;
    columnId: string;
    aggregate: SummaryType;
    values: Float64Array;      // one per category; NaN = nothing to total
  }>;
  truncated: boolean;          // categories were collapsed or dropped
  otherIndex: number | null;   // where "Other" sits, if present
  rowCount: number;
  categoryCount: number;
  rankingExact: boolean;       // false past the distinct-category ceiling
  // Only on a bucketed axis:
  bucket?: { kind: 'date' | 'number'; unit?: ChartDateUnit; size?: number; adjusted: boolean };
  bucketStarts?: Float64Array; // inclusive lower bound per category
  bucketEnds?: Float64Array;   // exclusive upper bound; dates are ms
}
```

`NaN` rather than `0` is deliberate: "no numeric values here" and "totals to
zero" are different answers, and a zero-height bar claims the second.

`excludeFilter: true` on the spec charts the view **without** the grid's own
filter (the one `setFilter` holds) while keeping the column filters, the
search and an external filter — what the panel does while several categories
are picked, so a chart of your own can cross-filter the same way.

## A floating window

**Pop out** in the panel's toolbar lifts the panel off its dock and lays it over
the grid as a window. It is the same panel, so the chart keeps its type, its
series, the legend switches and the zoom. **Dock** puts it back.

- Drag the title bar to move it; drag the bottom-right corner to resize it. The
  controls in the bar keep their own clicks.
- From the keyboard: the grip at the start of the bar moves the window with the
  arrow keys, the corner grip resizes it (10px a press, 50px with Shift).
- The window always stays inside the grid. Dragged past an edge it stops at the
  edge, and a grid that shrinks pulls the window back in.
- Fullscreen from a window and back returns to the window where it was.

To open as a window, set `floating: true` for a centred one, or give the
rectangle: `floating: { x: 40, y: 24, width: 640, height: 360 }` — px, relative
to the grid, top-left corner first. The plain-JavaScript grid takes the same
option.

Where the window is belongs to the chart state: `getState()` has
`floating: { x, y, width, height }` while it floats and no `floating` key while
it is docked, so a docked panel's state reads exactly as it did before. The saved
view keeps it, and `setState` with a state that has no rectangle docks the
panel. A move or a resize is reported once, when it ends, as a `chartChanged`
with `changes: ['placement']`.

### In a container of your own

`container` puts the chart somewhere else on the page — a dashboard tile, a
side panel — instead of docking it above the grid:

```tsx
const [box, setBox] = useState<HTMLDivElement | null>(null);

<div ref={setBox} className="chart-tile" style={{ height: 420 }} />
<EnterpriseDataGrid charting={{ container: box }} /* … */ />
```

Everything that opens the chart opens it there: the toolbar button, the menus
and the API. **Pop out** and extra windows float inside the container. The
panel sits in a box that carries the grid's theme classes, so a dark grid's
chart is dark in the tile as well. In React a container that is still `null` (a
ref not attached yet) docks the chart as usual until it exists; in JavaScript
pass the element itself, `charting: { container: tile }`, and destroying the
grid removes the box from it.

### Several charts at once

**New window** opens a copy of the chart in a window of its own, floating over
the grid. From then on the two are independent: change the type, the columns or
the format of one and the other stays as it was. A copy of the docked panel
opens centred over the grid; a copy made from a window opens a step down and to
the right of it, so a row of copies fans out instead of piling up. Windows
cannot dock — the dock is the panel's — and **Close** on a window removes it.

The windows are numbered in their title ("Chart 2", "Chart 3"…) after their
`id`, the same id their events carry (below). From code:

```ts
const win = chart.openWindow({ type: 'pie' });   // a copy of the panel's chart, as a pie
chart.openWindow({ floating: { x: 20, y: 20, width: 420, height: 300 } }); // exactly there
chart.getWindows();          // the windows open now, oldest first
win.update({ format: { title: 'Share' } });
win.getState();              // a GridChartState, like the panel's
win.close();
```

## Fullscreen and a fixed height

`height` sets the **docked** height; fullscreen ignores it and fills the screen.

The height is a number rather than "fill" for a reason worth knowing: recharts
sizes itself from a `ResizeObserver`, which never fires while an element is
`display: none`. A chart inside a collapsed accordion or an inactive tab would
stay blank until it is shown. A fixed height sidesteps the observer entirely.

## Image export

The panel has **PNG** and **SVG** buttons. The file is named after what the
chart shows — `region-revenue.png`, not `chart.png`.

Both go through the same step, which is the part worth knowing about: the SVG in
the page is **not** self-contained. Every colour in it reads a CSS custom
property that resolves against the document, and the text inherits a font from
an ancestor. Serialised naively it would open as the fallback palette in the
browser's default serif. So the export flattens the clone first — the values the
browser actually computed are written onto each element — and adds an opaque
background, because a transparent PNG dropped on a dark slide loses every dark
label on it.

PNG is rasterised at **2×** by default; a chart exported at CSS pixels looks soft
the moment it lands in a document.

Call them directly if you would rather not use the buttons:

```tsx
import { exportChartPng, exportChartSvg } from '@kanunilabs/datagrid-react-enterprise';

const svg = container.querySelector('svg');
await exportChartPng(svg, { fileName: 'sales-by-region', pixelRatio: 3 });
exportChartSvg(svg, { background: null }); // keep transparency deliberately
```

### JPEG, a size of your choosing, or the image as data

The chart API (below) takes a format and a size, and can hand the image back
instead of downloading it — to keep beside a saved report, send to a server or
put in an `<img>`:

```tsx
await chart.current?.download({ format: 'jpeg', width: 1200 });          // .jpg, 1200 px wide
const url = await chart.current?.getImageDataUrl({ width: 800, height: 600 }); // data:image/png;base64,…
```

`format` is `'png'` (default), `'jpeg'` or `'svg'`. One side keeps the chart's
proportions; both fix the box and centre the chart in it on its background —
stretched to fit, every label would be distorted. The chart is vector, so any
size is sharp. JPEG has no transparency, so `background: null` is drawn white
there. Both calls answer `null` / `false` while the panel is closed. The same
options work on the bare exporters: `chartImageDataUrl(svg, options)`,
`exportChartJpeg`, `exportChartImage(svg, { type })`.

## Chart API, events and saved charts

The chart is plain data, a `GridChartState`: whether the panel is open, the
type, the category and series columns, the grouping, which rows it reads, the
bubble's size column, the stacking, the Format choices, the series switched off
in the legend and the zoom window. Both grids hand out the same shape and take
it back, so a chart saved by the React grid restores in the JavaScript one.

In React, pass a ref:

```tsx
import type { GridChartApi } from '@kanunilabs/datagrid-core';

const chart = useRef<GridChartApi | null>(null);

<EnterpriseDataGrid charting={{ apiRef: chart }} /* … */ />

chart.current?.open({
  categoryColumnId: 'region',
  series: [{ columnId: 'revenue', aggregate: 'sum' }],
  type: 'line',
});
chart.current?.open({ format: { title: 'Q3' } }); // open already: the title changes, the rest stays
const saved = chart.current?.getState();          // JSON-safe
chart.current?.setState(saved);                   // later, or in another grid
chart.current?.close();
```

In JavaScript the same object is `grid.chartPanel`:

```ts
grid.chartPanel.open({ type: 'bar', stacking: 'stacked' });
const saved = grid.chartPanel.getState();
grid.chartPanel.setState(saved);
```

`open(seed)` takes any part of the state, and what it leaves out keeps its
value. Reopening a closed panel shows the chart the reader left, with every
series shown and the axis unzoomed. `setState` drops what the grid no longer
has instead of refusing the whole chart: a series over a removed column goes,
and an unknown category falls back to the panel's default.

### Events

The controller's event bus reports the panel:

```ts
controller.events.on('chartOpened', ({ state }) => {});
controller.events.on('chartChanged', ({ state, changes }) => {});
controller.events.on('chartClosed', ({ state }) => {});
```

`changes` names what moved: `type`, `data`, `stacking`, `format`,
`hiddenSeries`, `window` or `placement` (docked or floating, or the window
moved). An extra chart window reports the same three events with its `chartId`
(`'chart-2'`…); the panel's own events have no `chartId`. `data` is a change of columns, reducers, grouping
or row source — the parts that run the aggregation again. A pan is reported
once, when the pointer is released, not on every move. Changes made through the
API while the panel is closed send no event; they arrive with the next
`chartOpened`.

### In the saved view

The chart is part of `controller.getViewState()`, under `parts.chart`.
`applyViewState` restores it, and **`stateStoring` keeps it with no code of
yours**: change the chart, reload the page, and it comes back. Extra windows
travel with it, under `parts.chart.windows` — each a chart state with its `id`
and its rectangle — and a view without them closes the ones that are open.

## Sparklines

A chart small enough to live in a cell. Not part of the chart panel — it is a
property on the column, and it draws whatever array the cell holds:

```tsx
const columns = [
  { field: 'name', headerName: 'Product' },
  {
    field: 'weekly',              // e.g. [12, 18, 9, 22, 31, 28]
    headerName: 'Last 6 weeks',
    width: 140,
    sparkline: { type: 'line' },
  },
];
```

| Option | Type | Default |
|---|---|---|
| `type` | `'line' \| 'area' \| 'bar' \| 'horizontalBar'` | `'line'` |
| `xKey` / `yKey` | `string` | `'x'` / `'y'` |
| `min` / `max` | `number` | the series' own range |
| `showLast` | `boolean` | on, except for the bar types |
| `showBaseline` | `boolean` | on for the bar types, off otherwise |
| `highlight` | `{ first?, min?, max? }` | none |
| `color` / `negativeColor` | CSS colour | the theme's primary / danger |
| `tooltip` | `boolean` | off |
| `lineWidth` / `lineDashed` | `number` (1–6 px) / `boolean` | the stylesheet's |
| `fillOpacity` | `number` (0.05–1) | the stylesheet's |
| `markers` | `boolean` — a dot on every reading | off |
| `labels` | `boolean` — each bar's value beside it | off |
| `valueFormat` | `Intl.NumberFormatOptions` | the locale's numbers |
| `pointColor` | `(point) => colour \| undefined` | none |
| `tooltipText` | `(point) => string` | the value |

`horizontalBar` draws one row per reading, top to bottom, each bar growing to
the right from a vertical zero line — the shape for "how big is each part"
rather than "where is it heading".

### What the cell can hold

Three shapes, and a column may use whichever its data already has:

```ts
[12, 18, 9, 22]                                   // plain numbers
[['Q1', 12], ['Q2', 18], ['Q3', 9]]               // [x, y] pairs
[{ day: '2026-06-01', sales: 12 }, /* … */]       // objects: set xKey: 'day', yKey: 'sales'
```

Objects are read through `xKey` and `yKey`, which default to `x` and `y`.

When **every** reading has a number or a date as its x — a `Date`, or an ISO
date such as `'2026-06-01'` — the readings are sorted by it, and a line or area
places them by it: readings on the 1st, 2nd and 30th of a month sit close
together at the left and far apart at the right, as they did in time. Bars keep
one even slot per reading, in that sorted order. If any reading has no x, or a
text x such as `'Q1'`, the readings stay evenly spaced in the order given.

With `tooltip` on, a reading with an x shows it before the value
(`6/30/2026: 31`, `Q3: 9`); a bare ISO date is read as a calendar day, so it
never shows the day before in a time zone behind UTC. A reading without a y, or
with a y that is not a number, is a hole like any other.

### Highlights and scale

`highlight` marks the first, lowest and highest readings: dots on a line or
area (highest green, lowest red, first muted), recoloured bars on a bar
sparkline. `tooltip` shows each reading's value on hover with the browser's own
tooltip, so it needs no script.

By default every cell scales to **its own** series, so a row peaking at 30 and a
row peaking at 3,000 look identical. Set `min` and `max` when the point is to
compare rows against each other.

`showBaseline` draws the zero line only when the series actually crosses zero —
a baseline at the floor of an all-positive series is just a second border. Bars
follow the same rule and grow from zero when zero is on the scale, from the
floor when it is not: a bar chart of values between 90 and 100 growing from zero
would be ten identical full-height bars.

Colours come from CSS classes (`.kanuni-datagrid-sparkline-line`,
`-area`, `-bar`, `-bar--negative`, `-baseline`, `-last`, `-hi--first`,
`-hi--min`, `-hi--max`, `-lone`, `-marker`, `-ring`, `-label`,
`-label--inside`), so themes and dark mode work with no JavaScript and nothing
recomputes when the theme changes. `color` and `negativeColor` set one column's
colours without a stylesheet.

Every dot on a line (`-last`, `-hi--*`, `-lone`, `-marker`) is coloured by its
`stroke`, not its `fill`: it is drawn as a round stroke so it stays round in a
drawing stretched to the cell, and `stroke-width` is its diameter. The last and
highlighted dots sit on a ring of the surface colour (`-ring`). Bars keep
`fill`, so a highlight class recolours a bar by `fill` and a dot by `stroke`:

```css
.kanuni-datagrid-sparkline-last { stroke: #7c3aed; stroke-width: 6px; }
rect.kanuni-datagrid-sparkline-hi--max { fill: #15803d; }
path.kanuni-datagrid-sparkline-hi--max { stroke: #15803d; }
```

### Lines, markers, labels and colours of your own

`lineWidth`, `lineDashed` and `fillOpacity` restyle one column's line and area;
a value out of range is ignored, not clamped, and the stylesheet keeps what you
leave out. `markers` puts a dot on every reading of a line or area, and each
dot carries the tooltip.

`labels` writes each bar's value beside it: past the end of a horizontal bar,
above a vertical one, or inside near the end when the bar reaches the far edge
and there is no room outside. The labels are page text laid over the drawing —
the drawing stretches to the cell, and text inside it would stretch with it.
`valueFormat` sets how the values print, in the labels, the tooltip and the
screen-reader summary alike.

`pointColor` colours each reading your own way. It is told the reading's value,
its position, its `x` when it has one, whether it is the first, last, lowest or
highest, and the row — and returns a colour, or nothing for the default. It
wins over `highlight`, `color` and `negativeColor`, and applies to bars and
dots (a line has one colour). `tooltipText` writes the tooltip from the same
facts, so it can show another column of the row beside the value; setting it
turns tooltips on.

A **progress bar** is a horizontal bar with one reading:

```tsx
{
  field: 'done',                                   // 0.62
  headerName: 'Progress',
  valueGetter: (row) => [row.done],                // the sparkline reads an array
  sparkline: {
    type: 'horizontalBar',
    min: 0,
    max: 1,
    labels: true,
    valueFormat: { style: 'percent' },             // "62%"
    pointColor: ({ value }) => (value < 0.3 ? '#dc2626' : value < 0.7 ? '#d97706' : '#16a34a'),
    tooltipText: ({ value, row }) => `${row?.task}: ${Math.round(value * 100)}% done`, // no row outside a grid
  },
}
```

The maths is Community and has no DOM in it — useful if you want the paths
without the grid:

```ts
import { sparklineGeometry, SPARK_WIDTH, SPARK_HEIGHT } from '@kanunilabs/datagrid-core';

const { line, area, bars, baselineY, last, count, points, min: low, max: high } =
  sparklineGeometry(values, { min, max });
```

Only the drawing is Enterprise: `<Sparkline>` in
`@kanunilabs/datagrid-react-enterprise`, `renderSparkline()` in
`@kanunilabs/datagrid-enterprise`. With `labels` on a bar type,
`renderSparkline()` returns a `<span class="kanuni-datagrid-sparkline-box">`
holding the drawing and its labels; otherwise the `<svg>` itself.

### What sparklines do not do

- **A non-numeric entry is a gap, not a zero.** A `null` from a join or a
  missing period keeps its place in the series: the line breaks there and the
  bar's slot stays empty, instead of a dip that never happened. A reading with
  a gap on both sides gets a dot, because no line reaches it. Only numbers and
  non-empty numeric strings are plotted.
- **Nothing numeric means nothing drawn.** The cell falls through to the grid's
  ordinary text rendering.
- **A flat series draws through the middle** — one value, or every value equal,
  has no range to scale against. A single point sits at the **left** edge, so a
  series that grows to two points keeps its first point in place.
- **No click target.** `tooltip` gives a hover readout; there is no click
  event. The SVG is `role="img"`, labelled in the grid's language with the
  count, the range and the last value (`ariaLabel` replaces it).
- **Sorting and filtering are not meaningful on the column.** With no
  `dataType` the engine collates `String(value)`, so `[1,2,3]` sorts as the text
  `"1,2,3"`. Give the column a `comparator` (sort by the last reading, say) or
  turn sorting off.
- **Enterprise only for the drawing.** Community can compute the geometry and
  render it itself; the components ship in the paid packages.

## Not yet

- The chart aggregates **data rows**; grid grouping is not carried into it. The
  chart's category axis is its own group-by, and stacking the grid's grouping on
  top would leave two competing answers to "what is grouped here".

---

Source: https://kanunilabs.com/docs/datagrid/performance

# Performance

Every number here comes from a script you can run against the npm package.
Nothing is extrapolated.

```bash
npm install @kanunilabs/datagrid-core
curl -O https://kanunilabs.com/benchmarks/datagrid-pipeline.bench.mjs
node datagrid-pipeline.bench.mjs 1000000
```

(This part is generated when the page renders. See it at https://kanunilabs.com/docs/datagrid/performance)

## 1,000,000 rows

(This part is generated when the page renders. See it at https://kanunilabs.com/docs/datagrid/performance)

## 100,000 rows

(This part is generated when the page renders. See it at https://kanunilabs.com/docs/datagrid/performance)

## Where the speed comes from

**Columnar encoding.** Columns become typed arrays — `Float64Array` for
numbers, dates and booleans; a string dictionary plus `Int32Array` codes for
text. Row objects are never copied to the worker; only the buffers are
transferred, which is a zero-copy handover.

**Dictionary evaluation.** A `contains` or equality filter on a text column is
evaluated against the column's *distinct values*, then reduced to an integer
scan. Work scales with cardinality, not row count.

**Collator ranks.** Text sorting compares precomputed integer ranks instead of
calling `Intl.Collator` inside the comparator. Most of the gap on the text sort
comes from this. The ranks are built by sorting the column's distinct values
once, and kept until the data changes, so the first sort on a column with many
distinct values is much slower than the ones after it.

**Radix sort.** Numeric sorting uses an LSD radix sort over an order-preserving
64-bit key — eight linear passes with no comparator callbacks at all. A
comparator sort of a million rows costs roughly 20 million JS callback
invocations; this costs none. Multi-key sorting runs one stable pass per key.

**Search elimination.** If the search term appears in no dictionary entry of a
column, that column is skipped entirely. And since `String(someNumber)` can only
contain a fixed set of characters, a term with letters never scans numeric
columns. In the benchmark, a search for "Marmara" scans one column of nine. The
lower-cased dictionaries this needs are built by the first search and reused
after that.

**Quantized scrolling.** The virtual window only changes when a row or column
boundary is crossed, so most scroll events never reach React at all.

## The worker

Above ~20,000 rows the pipeline moves off the main thread. Below that the main
thread is genuinely faster — latency beats parallelism for small data.

The worker runs the *same* pipeline function the main thread would, so results
are identical by construction rather than by convention. A suite of golden tests
asserts that both paths produce byte-identical row orderings across every
operator and data type.

If no `Worker` global exists (SSR, tests, restrictive environments) or the
worker fails to start, the grid degrades to the synchronous path instead of
breaking.

## Rendering

Rows and columns are both virtualized. A 100,000-row grid keeps ~25 rows in the
DOM; columns scrolled out of view are replaced by a single spacer element rather
than being rendered.

Measured in a real browser at 100,000 rows: the scroll container reports a
2,800,032 px scroll height while the DOM holds 21–30 row elements, and the
rendered block's transform lands exactly on the row grid.

## The first-query encode

Before the first sort at large row counts, the grid encodes the columns into
typed arrays and transfers them to the worker. That encode has to run on the
main thread: it calls your `valueGetter` and `calculateSortValue`, and functions
cannot be sent to a worker.

The figures in this section come from an earlier measurement on a wider
15-column dataset, not from the 9-column script above. At 100,000 rows the whole pass is 169 ms
and unnoticeable. At 1,000,000 rows × 15 columns it is about 3.1 seconds of
work — but it is **not one 3.1-second freeze**. The encode yields to the browser between columns, so the longest
single task is one column:

| | 1,000,000 rows × 15 columns |
| --- | --- |
| Total encode work | ~3.1 s |
| Longest blocking task | **~0.55 s** (the widest text column) |
| Tasks | 15, with a paint opportunity between each |

The total work is unchanged — the same rows still have to be read — but the page
keeps painting and responding while it happens instead of going white.

Yielding is skipped below 100,000 rows, where the whole encode is a few
milliseconds and the scheduling round trip would cost more than it saves.

---

Source: https://kanunilabs.com/docs/datagrid/ssr

# SSR & bundlers

The grid renders on the server and hydrates normally. Nothing touches `window`,
`document` or `ResizeObserver` outside an effect, so a page containing a grid
does not need `ssr: false` or a `typeof window` guard.

This is covered by tests that render the component to a string in a DOM-free
environment — including with the toolbar, filter row, group panel, pager,
summary bar and a remote data source all switched on.

## What the server renders

| | On the server | After hydration |
| --- | --- | --- |
| Root, header, ARIA roles | rendered | unchanged |
| Column captions | rendered | unchanged |
| Row window | empty | measured and filled |
| Web Worker | never constructed | constructed above the threshold |
| Remote `DataSource` | `load()` called once, not awaited | loaded by the client |

The row window is empty because the viewport has no size until the browser
measures it. Guessing a row count server-side would render rows the client
immediately replaces.

On a remote source the server render calls `load()` once and does not wait for
it — the markup goes out without rows and the client loads its own after
hydration. With an absolute URL that is one extra request per page render whose
answer is discarded; a relative `fetch('/api/...')` simply fails on the server,
and the grid absorbs the failure without breaking the render.

The markup still contains the grid skeleton and the column headers, so the
pre-hydration page is not a blank box.

## Next.js (App Router)

The grid is a client component — it holds state and subscribes to events. Mark
the file that renders it:

```tsx
'use client';

import { DataGrid } from '@kanunilabs/datagrid-react';
import '@kanunilabs/datagrid-react/styles.css';

export function SalesGrid({ rows }) {
  return <DataGrid gridId="sales" dataSource={rows} rowKey="id" columns={columns} />;
}
```

A server component can fetch the rows and pass them down as a prop; only the
grid itself needs the client boundary.

Import the stylesheet once — in the root layout or in the client component.

### The worker in Next.js

Nothing to do. The worker is compiled into the package and starts from a Blob
URL, so Next never has to resolve a worker file out of a dependency — which it
does not do.

Two cases still need the file, and it ships in the package for them:

- **a Content-Security-Policy without `worker-src … blob:`** — the browser
  refuses the Blob, and only a real URL will start the worker;
- **wanting the worker as its own cacheable file** rather than inlined in your
  bundle.

Either way, serve the file from **your own origin**: a browser will not start a
worker script from another domain, so a CDN on a different host does not work.

```bash
cp node_modules/@kanunilabs/datagrid-core/dist/datagrid.worker.js public/
```

```tsx
<DataGrid worker={{ url: '/datagrid.worker.js' }} /* ... */ />
```

If the worker cannot start for any reason the grid still works: it runs the same
pipeline on the main thread and warns once in development. The only difference
is that a large sort blocks the UI instead of running off-thread.

## Vite

Also nothing to do. If you need the file route (CSP or CDN, as above):

```ts
import workerUrl from '@kanunilabs/datagrid-core/dist/datagrid.worker.js?url';

<DataGrid worker={{ url: workerUrl }} /* ... */ />
```

## Other bundlers

Any setup that can serve a static `.js` file works: copy
`node_modules/@kanunilabs/datagrid-core/dist/datagrid.worker.js` somewhere
public and pass its URL. The file is self-contained — it has no imports of its
own, so no additional chunk resolution is involved.

## Turning the worker off

```tsx
<DataGrid worker={{ enabled: false }} />     {/* always main thread */}
<DataGrid worker={{ threshold: 50_000 }} />  {/* offload later than the default 20.000 */}
```

Below the threshold the main thread is genuinely faster — the round trip costs
more than the sort saves — so small grids never use the worker regardless.

## Content Security Policy

The default worker starts from a Blob URL, so a policy that restricts workers
needs `worker-src 'self' blob:`. If you serve the file yourself instead (see
above), it is loaded from your own origin and `worker-src 'self'` is enough.
The grid does not use `eval`, inline scripts or remote resources.

Next: [performance](https://kanunilabs.com/docs/datagrid/performance).

---

Source: https://kanunilabs.com/docs/datagrid/javascript

# JavaScript

The DataGrid does not need React. `@kanunilabs/datagrid` is a second renderer
over the **same engine** (`@kanunilabs/datagrid-core`) and the **same
stylesheet** — virtualization, sorting, filtering, grouping, pinning, the
worker offload and theming behave identically, and a conformance suite in CI
keeps the two renderers from drifting.

```bash
npm i @kanunilabs/datagrid
```

[Try it live](https://kanunilabs.com/playground/datagrid/virtual-scrolling?renderer=js) — every demo in the
playground has a React — JavaScript switch, and this link arrives with JavaScript
already selected. The grid you see is built by `createGrid()`; React owns only
the empty host element around it. Row count is yours to pick, up to a million.

## A grid in one call

```ts
import { createGrid } from '@kanunilabs/datagrid';
import '@kanunilabs/datagrid/styles.css';

const grid = createGrid(document.getElementById('host'), {
  gridId: 'orders',
  dataSource: rows,            // your array
  rowKey: 'id',
  columns: [
    { field: 'id', headerName: 'ID', dataType: 'number', width: 80 },
    { field: 'product', headerName: 'Product', width: 220 },
    { field: 'units', headerName: 'Units', dataType: 'number', width: 100 },
    { field: 'unitPrice', headerName: 'Unit price', dataType: 'number',
      valueFormatter: (v) => `$${Number(v).toFixed(2)}` },
  ],
  theme: 'minimal',
  toolbar: true,
  filterRow: true,
  headerFilter: true,
  selection: { mode: 'multiple' },
});

grid.controller.setSort([{ columnId: 'units', direction: 'desc' }]);
grid.setData(nextRows);   // live data
grid.destroy();           // when the host goes away
```

The **config mirrors the React props**, DOM-flavoured. Where React takes a
React node, vanilla takes a string or a DOM `Node` — `renderCell` returns
either, and the string form is set as `textContent`, so there is no HTML
string API and no injection surface.

The overlap is not total, and the renderer tells you where it ends rather than
letting you guess: **pass a React-only option and it says so in the console**,
naming what to write instead. Two column switches are spelled differently —
React's `columnResize` / `columnReorder` are `resizable` / `reorderable` here.
Every option in the React prop table now has an answer here — the last one,
`renderRow`, landed in #142. What remains in the console warning are spellings,
not gaps.

`renderRow` draws the same line React does: the template replaces the row's
CELLS — including the row number, the detail expander and the selection
checkbox — while the row element itself stays, carrying the height, the aria
indices and the classes the virtualizer and selection depend on. So in-cell
editing and range selection have nothing to attach to while it is on. Return
the SAME node you returned last time and the DOM is left alone, which is what
lets a focused input inside a template keep its caret across a sort.

Two differences are worth knowing rather than discovering. `focusedRowKey` is
the STARTING focus here, applied once — React re-applies it whenever the prop
changes, and a vanilla config is read once; later moves go through
`grid.controller.focusRow(key)`. And `showRowCount`, retired in both renderers
on 2026-08-15, prints a one-line notice here when you set it — a React user
reads the `@deprecated` tag in their editor, and someone writing plain JS
against the UMD bundle has no such surface. The row count lives in the status
bar (Enterprise) or the pager.

Everything the engine does — virtualization, sorting, filtering, grouping,
pinning, the worker, export — is identical in both, because both call the same
controller.

`grid.controller` is the engine itself — the same object the React binding
hands to `onReady`. Everything imperative (search, filters, selection, export,
scrolling, state) lives there; see the
[API reference](https://kanunilabs.com/docs/datagrid/api). The JavaScript surface itself —
[createGrid](https://kanunilabs.com/docs/datagrid/api/javascript/functions/createGrid),
[CreateGridConfig](https://kanunilabs.com/docs/datagrid/api/javascript/interfaces/CreateGridConfig)
and the column type — has its own generated pages too.

### Menus and extension points

- **Row context menu** — `rowMenu` (an array, or a function of the clicked row)
  appends your items above the grid's own Copy/Export block.
- **Header context menu** — right-click a header for sort, group, pin, hide,
  best-fit and move; `headerMenu(context, defaults)` reshapes the list,
  `headerMenu: false` turns it off.
- **Toolbar** — `toolbar: true` adds quick search, the column chooser and an
  export menu; `toolbarItemsAfter: [button, …]` appends your own controls.

## Script tag (UMD)

No bundler? The package ships a self-contained build:

```html
<link rel="stylesheet" href="https://unpkg.com/@kanunilabs/datagrid/dist/styles.css" />
<script src="https://unpkg.com/@kanunilabs/datagrid/dist/datagrid.umd.js"></script>
<script>
  const { createGrid } = KanuniLabsDataGrid;
  createGrid(document.getElementById('host'), { /* the same config */ });
</script>
```

The engine is bundled in; the optional export peers (exceljs, jsPDF) are not,
and degrade with an actionable error if an export needs them.

## Enterprise edition

`@kanunilabs/datagrid-enterprise` wraps the Community grid — it does not fork
it — and adds the paid surface: cell / batch / row / form / popup editing
with validation and undo, range selection, fill handle and clipboard,
master-detail, tree data, cell spans and notes, charts and sparklines, the
filter builder, the import wizard, styled Excel/PDF export, status and side
bars. It is installed from the
[private registry](https://kanunilabs.com/docs/datagrid/registry) with your license.

```ts
import { createEnterpriseGrid } from '@kanunilabs/datagrid-enterprise';
import '@kanunilabs/datagrid/styles.css';
import '@kanunilabs/datagrid-enterprise/styles.css';

const grid = createEnterpriseGrid(host, {
  licenseKey: 'KLAB1.…',
  // everything createGrid takes, plus:
  editing: {
    mode: 'batch',                 // 'cell' | 'batch' | 'row' | 'form' | 'popup'
    commandColumn: true,
    allowAdding: true,
    allowDeleting: true,
    rules: { product: [{ type: 'required' }] },
    onSave: (changes) => api.save(changes),
  },
  statusBar: true,
  sideBar: true,
  charting: { crossFilter: true },
  filterBuilder: true,
  onImport: (rows) => append(rows),
  toolbarExcel: true,
  toolbarPdf: true,
  // styledExport defaults to true — Excel carries the grid's formatting.
});

grid.chartPanel?.open({ categoryColumnId: 'category' });
grid.openFilterBuilder();
grid.isEnterpriseLicensed();
```

Without a valid key the grid **still works**, watermarked — your app never
breaks on a licensing problem. One license key opens both Enterprise
packages, React and plain JavaScript alike; see
[Enterprise & licensing](https://kanunilabs.com/docs/datagrid/enterprise).

The Enterprise UMD build is `dist/datagrid-enterprise.umd.js`
(global `KanuniLabsDataGridEnterprise`); it bundles the Community renderer and
the licensing core, so one script tag is enough.

## What is the same, what is different

| | React | JavaScript |
| --- | --- | --- |
| Engine, stylesheet, themes, worker | shared | shared |
| Config / props | `<DataGrid {...props} />` | `createGrid(host, props)` |
| Custom cell content | React node | string or DOM `Node` |
| Imperative API | `onReady(controller)` | `grid.controller` |
| Server-side rendering | renders markup | constructs on mount (needs a `document`) |
| Enterprise | `<EnterpriseDataGrid>` | `createEnterpriseGrid()` |

SSR is the one honest difference: the JavaScript renderer produces DOM, so it is
created when the host element exists. Everything else is held to parity by the
conformance suites that run on every commit.

---

Source: https://kanunilabs.com/docs/datagrid/faq

# FAQ

## Is the Community edition really free?

Yes. `@kanunilabs/datagrid-react` and `@kanunilabs/datagrid-core` are free to
use, including commercially, under the KanuniLabs Community License. They are
proprietary — the compiled packages are distributed, the source is not.

## Why is `rowKey` required?

Selection, focus and future live updates are keyed by row identity. Using array
position instead would break the moment rows sort or filter — a selected row
would appear to jump to a different record. Requiring `rowKey` makes that class
of bug impossible.

## Do I need the Web Worker?

No. Below ~20,000 rows the grid stays on the main thread because that is
genuinely faster. Above it, the offload happens automatically when a `Worker`
global is available; if not, the grid falls back to the synchronous path.

## My grid renders but feels slow on a big dataset

Most likely the worker did not start, so filtering and sorting are running on
the main thread. The worker ships inside the package and starts from a Blob URL,
so the usual cause is a Content-Security-Policy that forbids `blob:` workers —
see [Installation → The Web Worker](https://kanunilabs.com/docs/datagrid/installation#the-web-worker-nothing-to-configure).
In development the grid warns once in the console with the exact cause.

## Does it work with Next.js / SSR?

Yes, with no extra setup. The grid renders on the server without a worker or DOM
measurement and hydrates normally; popups are created on mount, so nothing is
portaled during SSR. The worker is embedded in the package, so Next.js needs no
file copied into `public/` — see [SSR](https://kanunilabs.com/docs/datagrid/ssr).

## Why does my CSV open with broken characters in Excel?

It shouldn't — exports are written with a UTF-8 BOM precisely because Excel
otherwise reads the file as ANSI. If you disabled it with `bom: false`, that's
the cause.

## Can I export to Excel?

Yes, in Enterprise (`EnterpriseDataGrid`, or `createEnterpriseGrid` in plain
JavaScript), with the optional `exceljs` peer installed (`npm i exceljs`). It
is loaded lazily, so apps that only use CSV don't pay for it. CSV export is in
the free Community grid.

## Does export include everything or just the visible page?

Everything in the current result — all filtered and sorted rows, not just the
page on screen. What it *does* respect is what you see per row: formatted
values and visible columns only.

## Can I edit cells?

Not in the Community edition. Editing is the anchor feature of Enterprise:
cell, batch, row, form and popup modes, validation, per-row CRUD handlers,
undo/redo, range selection, the fill handle and paste. See
[Editing](https://kanunilabs.com/docs/datagrid/editing).

## Does it support multi-level grouping?

Community ships single-level grouping. Multi-level grouping and per-group
aggregates are Enterprise.

## Is it accessible?

Yes — a full WAI-ARIA grid implementation: `role="grid"` with row/column
indices, virtual focus via `aria-activedescendant`, live-region announcements,
and a roving tabindex so the header is one tab stop instead of one per column.

## Which frameworks are supported?

React, and plain JavaScript with no framework at all.

`@kanunilabs/datagrid-react` is the React binding.
[`@kanunilabs/datagrid`](https://kanunilabs.com/docs/datagrid/javascript) is the same grid built
straight into the DOM: one `createGrid(element, config)` call, no component
tree, and a UMD build so a `<script>` tag is a complete install. Both are real
renderers over one engine (`@kanunilabs/datagrid-core`) — the pipeline, the
events and the controller API are identical, and the JavaScript config mirrors
the React props by name.

The engine is deliberately framework-agnostic — no DOM, no framework imports —
so further adapters can be built on the same controller contract.

## Which browsers are supported?

The current versions of Chrome, Edge, Firefox and Safari. Internet Explorer is
not supported. [Supported browsers](https://kanunilabs.com/docs/datagrid/browser-support) lists the
oldest version of each browser that has every feature the grid uses, and what is
tested in a real browser.

## How do I request a feature or report a bug?

[Contact us](https://kanunilabs.com/contact). Feature requests and bug reports go to the same place
and are read by the people who write the code.

---

Source: https://kanunilabs.com/docs/datagrid/enterprise

# Enterprise & licensing

The Community package is a complete, fast grid: a million rows, sorting,
filtering, selection, pagination, loading from your server as the user scrolls,
themes, twelve languages and CSV export.

`@kanunilabs/datagrid-react-enterprise` starts where you **change** the data and
where you **take it out**: the four editing modes, range selection and the fill
handle, grouping and trees on the server, Excel and PDF export, the chart panel, the nested
filter builder, and the docked side and status bars.

`EnterpriseDataGrid` is a drop-in replacement for `DataGrid` — same props, plus
these.

> **One key opens both products.** A KanuniLabs license unlocks the Enterprise
> edition of DataGrid *and* PivotGrid. If you already bought for one, you do not
> buy again for the other.

## 1. Install from the private registry

The Enterprise package is not on public npm. It comes from our private registry
with credentials issued per license — you receive a ready-to-paste `.npmrc` by
email, and can always fetch it again from your
[dashboard](https://kanunilabs.com/dashboard/licenses).

```ini
@kanunilabs:registry=https://registry.kanunilabs.com/
//registry.kanunilabs.com/:_auth=<value from your email or dashboard>
//registry.kanunilabs.com/:always-auth=true
```

```bash
npm i @kanunilabs/datagrid-react-enterprise
```

Without React, the same features ship as `@kanunilabs/datagrid-enterprise` —
one `createEnterpriseGrid()` call, same licence key, same licence terms. The
[JavaScript guide](https://kanunilabs.com/docs/datagrid/javascript) shows it in use.

```bash
npm i @kanunilabs/datagrid-enterprise
```

CI usage, keeping the token out of git and rotating a leaked password are all
covered in the [Private registry access guide](https://kanunilabs.com/docs/datagrid/registry).

## 2. Set the license key

Set it once, at startup, before the first grid renders:

```tsx
import {
  EnterpriseDataGrid,
  LicenseManager,
} from '@kanunilabs/datagrid-react-enterprise';

LicenseManager.setLicenseKey('KLAB1....');

export function OrdersGrid({ rows }) {
  return (
    <EnterpriseDataGrid
      dataSource={rows}
      rowKey="id"
      columns={[
        { field: 'id', headerName: 'ID', dataType: 'number' },
        { field: 'customer', headerName: 'Customer' },
        { field: 'total', headerName: 'Total', dataType: 'number' },
      ]}
      editing={{ mode: 'cell' }}
    />
  );
}
```

Both stylesheets are needed — the Enterprise one only adds what it introduces:

```ts
import '@kanunilabs/datagrid-react/styles.css';
import '@kanunilabs/datagrid-react-enterprise/styles.css';
```

### Without a valid key

The grid **keeps working**. It is watermarked, not crippled: a badge appears
and says what is wrong, in the grid's language — "Unlicensed", "License
expired", "License not valid for this domain", "Browser cannot verify the
license (HTTPS required)" and so on. A key that was given but did not pass also
logs one console notice, in DataGrid's name; with no key at all, the badge is
the only notice. This is deliberate — an evaluation, a staging box with a stale
key or an expired card should never take your application down.

To act on the reason in your own code, read `reasonCode` from the licence
state (see [Reading the reason](#reading-the-reason) below).

### When a subscription ends

A paid key covers every version released up to the end of the period you paid
for, with no time limit. The grid compares its own release date with the key,
never today's date, so an application you shipped keeps running without a
watermark after the subscription ends. A version released later is not
covered; while you are subscribed, each renewal moves the date forward, so take
the current key from your dashboard when you upgrade.

Keys are verified offline. The signature is checked inside the grid, against a
public key compiled into the package — there is no licence server to reach, so
the check works when our site is down and on a network with no internet at all.

**On `localhost` the key is still required** — what local development skips is
the *domain* check, so one key works from `localhost`, `127.0.0.1` and `*.local`
without listing them as domains. The signature is verified everywhere; a grid
with no key is watermarked on your machine exactly as it would be in
production, which is deliberate: you should see what your users would.

### Plain HTTP and intranets

A page served over plain `http://` from an intranet host (`http://erp.corp/`,
`http://10.0.0.5:8080/`) is supported. Browsers only offer their built-in
cryptography (`crypto.subtle`) on HTTPS and `localhost`; everywhere else the
grid verifies the key with a JavaScript implementation of the same algorithm,
bundled with the grid and loaded only on such pages. The verdict is the same
either way, and the check is just as strict — a key is valid only after its
signature is verified, on HTTP too. Only the cost differs: an HTTP page loads
that verifier (about 15 KB gzipped) once, on first use — the script-tag builds
carry it inside — and the badge does not appear while the check runs.

### Reading the reason

The licence state carries a `reasonCode` next to `status`, so your code does not
have to parse the English `reason` text:

```tsx
import { useLicenseGuard } from '@kanunilabs/datagrid-react-enterprise';

function LicenceBanner() {
  const license = useLicenseGuard();
  if (license.reasonCode === 'engine-unavailable') {
    return <p>This browser cannot check the licence. Open the app over HTTPS.</p>;
  }
  return null;
}
```

| `reasonCode` | `status` | Meaning |
|---|---|---|
| `valid` | `valid` | Verified, in date, this domain |
| `grace` | `valid` | Past its date, inside the grace period — still licensed |
| `checking` | `checking` | Verification has not finished yet |
| `missing` | `missing` | No key, or a key that does not cover this product |
| `invalid-format` | `invalid-format` | Not a KanuniLabs key — truncated, mistyped or not `KLAB1.` |
| `invalid-signature` | `invalid-signature` | The key was altered, or not issued by KanuniLabs |
| `engine-unavailable` | `invalid-signature` | This browser could not run any verifier (no `crypto.subtle`, and the bundled one could not load) |
| `expired` | `expired` | A subscription key past its date and grace period |
| `release-not-covered` | `expired` | A paid key, but this version was released after its cover ended |
| `domain-mismatch` | `domain-mismatch` | Issued for other domains |
| `revoked` | `revoked` | The key was reported revoked |

`useLicenseGuard` and `getLicenseState` describe the **key**, shared by every
grid on the page. Two verdicts are made per product, inside the grid, and show
on its badge rather than in that shared state: `release-not-covered` (this
build is newer than the key's cover) and `missing` for a key that does not
include DataGrid. For those the shared state still reads `valid`.

`reasonCode` is optional in the type, so code written against the older
`status` values keeps compiling; `status` itself has not changed.

## What Enterprise unlocks

Each entry links to the guide that shows it working. Everything **not** in this
list is in Community and needs no license.

(This part is generated when the page renders. See it at https://kanunilabs.com/docs/datagrid/enterprise)

## What happens if you use one without the license

The boundary is enforced in two places, and both explain themselves rather than
failing silently:

- **Configuration** (grouping depth, group summaries, master-detail, tree data,
  cell span, notes) is dropped, and the reason is logged when you
  render with `debugMode`.
- **Calls** (`exportToExcel`, `exportToPdf`) throw an error naming the feature.
- **A server-side `DataSource`** works in Community. Grouping it is dropped from
  the configuration (logged under `debugMode`), and grouping or a CSV export of
  it is not offered at runtime — `controller.canGroup()` and
  `controller.canExportAll()` say so.

Community keeps single-level grouping, footer column totals and CSV export, so a Community grid is
never a demo — it is a grid.

## What it costs

One key covers **both** components — DataGrid and
[PivotGrid](https://kanunilabs.com/docs/pivotgrid/enterprise) — so the list above and PivotGrid's own
Enterprise surface come together, not as two purchases.

See [Pricing](https://kanunilabs.com/pricing) for the tiers, or
[Private registry access](https://kanunilabs.com/docs/datagrid/registry) for how the packages are
delivered once you have a licence.

---

Source: https://kanunilabs.com/docs/datagrid/registry

# Private registry access

The Enterprise packages are not published on public npm. They install from our
private registry at `registry.kanunilabs.com`, and every license comes with its
own registry credentials: a username like `cust_ab12cd34` and a password.

| Package | For |
|---|---|
| `@kanunilabs/datagrid-react-enterprise` | React |
| `@kanunilabs/datagrid-enterprise` | plain JavaScript, no framework |

> **The same credentials serve every package.** One license, one registry
> account — use it for `datagrid-react-enterprise`, `datagrid-enterprise`,
> `pivotgrid-react-enterprise` and `pivotgrid-enterprise` alike. There is nothing separate to set up if you
> already installed one of them.

## Where your credentials come from

Two places:

1. **Purchase email** — the *"Your license is ready"* email contains a
   ready-to-paste `.npmrc` block under **Private npm registry**.
2. **Dashboard** — [Dashboard → Licenses](https://kanunilabs.com/dashboard/licenses), open your
   license, and use the **Private npm registry** section.

We store only a **hash** of the password, so it can never be shown again after
the first time. Losing it costs nothing: regenerating takes one click
([see below](#lost-or-leaked-password-regenerate-it)).

## Set up your project

Put the three lines from your email (or the dashboard) into a `.npmrc` file
**next to your `package.json`**:

```ini
@kanunilabs:registry=https://registry.kanunilabs.com/
//registry.kanunilabs.com/:_auth=<value from your email or dashboard>
//registry.kanunilabs.com/:always-auth=true
```

Then install as usual:

```bash
# React
npm install @kanunilabs/datagrid-react-enterprise

# or plain JavaScript, no framework
npm install @kanunilabs/datagrid-enterprise
```

Peer dependencies are resolved automatically by npm 7+ — one command is enough.

The first line routes **only the `@kanunilabs` scope** to our registry, which
also transparently serves the public `@kanunilabs/datagrid-core`,
`@kanunilabs/datagrid-react` and `@kanunilabs/datagrid` packages. Everything
else about your setup is unchanged.

> ⚠️ **Scaffold first, `.npmrc` after.** Project generators can wipe the
> directory they scaffold into — `create-vite`'s `--overwrite` flag, for
> example, deletes an existing `.npmrc`. Create the project first, then add the
> file.

### Keeping the token out of git (teams & CI)

`.npmrc` holds a secret, so either add it to `.gitignore`, or commit a variable
version and inject the value from the environment — npm expands `${VAR}` inside
`.npmrc`:

```ini
@kanunilabs:registry=https://registry.kanunilabs.com/
//registry.kanunilabs.com/:_auth=${KANUNILABS_REGISTRY_AUTH}
//registry.kanunilabs.com/:always-auth=true
```

Set `KANUNILABS_REGISTRY_AUTH` (the `_auth` value from your email or dashboard)
as a CI secret or in your local shell.

## Lost or leaked password? Regenerate it

1. Sign in at [kanunilabs.com/dashboard](https://kanunilabs.com/dashboard).
2. Open **Licenses** and click your license.
3. In the **Private npm registry** section, click **Regenerate credentials**
   (or **Generate credentials** if you never had any).
4. Copy the new `.npmrc` block right away — it is shown **only once**.

> ⚠️ Regenerating invalidates the previous password **immediately**. Update
> every place that uses it (developer machines, CI secrets) at the same time, or
> their `npm install` will start failing with `401`.

Your registry **username never changes** when you regenerate — only the
password does.

## Troubleshooting

| Symptom | Cause & fix |
| --- | --- |
| `404 Not Found` for the enterprise package | npm asked the public registry — the `@kanunilabs:registry=` line is missing, or `.npmrc` is not in the project root. |
| `401 Unauthorized` / `403 Forbidden` | Wrong or rotated password. Regenerate from the dashboard and update `.npmrc` / CI secrets. |
| Works locally, fails in CI | CI cannot see your `.npmrc` or its env var. Use the `${VAR}` form above and set the secret in your CI provider. |
| Installed fine, but the grid shows "Unlicensed" | The package is installed; the **license key** is a separate step. See [Enterprise & licensing](https://kanunilabs.com/docs/datagrid/enterprise#2-set-the-license-key). |
| Access stopped after cancellation or refund | Registry access ends with the subscription — by design. Reactivating restores it. |

Still stuck? [Open a support ticket](https://kanunilabs.com/dashboard/support) — we're happy to help.

---

Source: https://kanunilabs.com/docs/datagrid/range-selection

# Range selection, fill handle and clipboard

Three behaviours, **one switch**. There is no `rangeSelection`, `fillHandle` or
`clipboard` prop — all of it is `editing.range`, and it rides on the editing
layer:

```tsx
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';

<EnterpriseDataGrid
  licenseKey={key}
  dataSource={rows}
  rowKey="id"
  columns={columns}
  editing={{ mode: 'cell', range: true }}
/>
```

`range` defaults to **true**, so enabling editing already gives you the
rectangle. Turning editing off turns range off with it: internally it resolves
to `editingEnabled && (editing.range ?? true)`.

[See it working →](https://kanunilabs.com/playground/datagrid/range-selection)

## What the user can do

| Gesture | Result |
|---|---|
| Drag from a cell | Draws the rectangle |
| Shift-click | Extends it to the clicked cell |
| <kbd>Ctrl</kbd>-click or <kbd>Ctrl</kbd>-drag (<kbd>Cmd</kbd> on a Mac) | Adds another rectangle; the ones already selected stay |
| <kbd>Shift</kbd>+arrow | Grows it one cell from its anchor (from the focused cell when there is none) |
| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+arrow | Grows it to the first or last row or column |
| Drag the small square on the anchor cell | Fill handle — extends the values |
| <kbd>Ctrl</kbd>+<kbd>D</kbd> | Fills down: copies the rectangle's first row into the rows below it — with one cell, copies the cell above |
| <kbd>Ctrl</kbd>+<kbd>R</kbd> | Fills right: copies the first column into the columns to its right — with one cell, copies the cell to the left |
| <kbd>Ctrl</kbd>+<kbd>C</kbd> | Copies the rectangle as TSV |
| <kbd>Ctrl</kbd>+<kbd>X</kbd> | Copies, then clears the cells the user may write |
| <kbd>Ctrl</kbd>+<kbd>V</kbd> | Pastes from the rectangle's top-left cell — or from the focused cell when there is no rectangle. A rectangle bigger than the clipboard gets the clipboard repeated to fill it |
| Arrow / Home / End / PageUp / PageDown / Tab | **Collapses** the selection — every rectangle |

For the arrow keys, Home and PageUp/PageDown that last row is Excel's rule, and
it surprises people who expect "select, then nudge with the arrows". (Tab
differs from Excel, which walks the active cell through the selection without
collapsing it.)

## Several rectangles

Hold <kbd>Ctrl</kbd> (<kbd>Cmd</kbd> on a Mac, where <kbd>Ctrl</kbd>-click is
the right-click) and click or drag to add a rectangle; a plain click starts
over with one. What each gesture does with several:

| Gesture | With several rectangles |
|---|---|
| Statistics | Count and total **every** rectangle; a cell two of them share counts once |
| <kbd>Ctrl</kbd>+<kbd>C</kbd> | Rectangles over the **same columns** copy as one block, top to bottom; over the **same rows**, side by side. Rectangles that do not line up have no single block to paste back, so only the newest is copied |
| <kbd>Ctrl</kbd>+<kbd>X</kbd> | Clears every rectangle (the cells the user may write) |
| <kbd>Ctrl</kbd>+<kbd>V</kbd>, <kbd>Shift</kbd>+arrow, <kbd>Ctrl</kbd>+<kbd>D</kbd> / <kbd>R</kbd>, "Chart selected cells" | Act on the **newest** rectangle |
| Fill handle | Hidden — a fill copies one block, and a handle on one of several would hide which |

## Whole columns from the header

Turn on `columnSelection` and a click on a column header selects that column
— every row, top to bottom — as one rectangle, the way clicking a column letter
does in a spreadsheet:

```tsx
<EnterpriseDataGrid columnSelection />
```

The header is tinted while its column is selected, and everything above works
on it: the statistics total the column, <kbd>Ctrl</kbd>+<kbd>C</kbd> copies it,
<kbd>Ctrl</kbd>+<kbd>X</kbd> clears it, "Chart selected cells" charts it.

| Gesture | Does |
|---|---|
| Click a header | Selects that column; the other rectangles go |
| <kbd>Shift</kbd>+click | Widens the newest rectangle to every column between it and this one, all rows |
| <kbd>Ctrl</kbd>+click (<kbd>Cmd</kbd> on a Mac) | Adds the column and keeps the rest |
| <kbd>Ctrl</kbd>+<kbd>Space</kbd> | Selects the column of the focused cell, or of the focused header |

**The header click stops sorting while this is on** — one click cannot mean
both. Sort from the column menu (right-click the header), or focus the header
and press <kbd>Enter</kbd>. The grid's own columns (selection checkbox, row
numbers, commands) and the group column still sort or do nothing, as before.

A column means the rows the grid shows now. Clear a filter afterwards and the
rectangle still covers the rows it had; the header stops showing as selected,
because the column now holds more than that.

## Which cells may change

`allowUpdating` is the single gate for editing, fill, paste and cut:

```tsx
editing={{
  mode: 'cell',
  allowUpdating: (row, columnId) => columnId !== 'id' && !row?.locked,
}}
```

A cell the predicate refuses — or a column with `editable: false` — is still
**copied**; it is just not cleared, pasted over or filled. The rest of the
gesture goes ahead: one read-only column inside a paste does not cancel it.

Validation rules run when the change is **saved**, not during the gesture. Cut
writes `null`, so a required-field rule refuses the save, the grid shows why,
and the change stays pending until it is corrected or undone with
<kbd>Ctrl</kbd>+<kbd>Z</kbd>.

## Watching it happen

Gestures are published as a bracket — a `Start` and an `End`. Once a `Start` has
fired, its `End` always follows, even when the gesture wrote nothing or threw:

```tsx
onReady={(controller) => {
  controller.events.on('fillStart', (e) => console.log('filling', e.cellCount));
  controller.events.on('fillEnd', (e) => console.log('done', e.performed));

  controller.events.on('cellValueChanged', (e) => {
    // 'edit' | 'cut' | 'fill' | 'paste' | 'undo' | 'redo'
    if (e.source === 'paste') audit(e.rowKey, e.columnId, e.value);
  });
}}
```

The pairs are `cutStart`/`cutEnd`, `copyStart`/`copyEnd`,
`pasteStart`/`pasteEnd` and `fillStart`/`fillEnd`. A whole paste is **one undo
step**, not one per cell.

## Selection statistics

Set `statusBar` and the rectangle reports itself — cells, sum, average, min,
max:

```tsx
statusBar={{ items: ['totalRows', 'selectedRows', 'rangeStats'] }}
```

Without a status bar the stats appear in their own strip instead, so the numbers
show up exactly once either way. Non-numeric cells are **skipped**, not counted
as zero.

## Clipboard callbacks

By default a copy writes what the cells **show** — the lookup label and the
`valueFormatter` text; a `renderCell` drawing can be anything, so it is not
copied — and a paste reads the text as the column's type. The `clipboard` option lets your code change both — for
every copy in the grid: a cell range, a cut, the selected rows, "Copy with
headers".

```tsx
<EnterpriseDataGrid
  clipboard={{
    // A price shown through a valueFormatter: copy the number, not "$1,234.50".
    processCellForClipboard: ({ columnId, value, text }) =>
      columnId === 'price' ? String(value) : text,
    processHeaderForClipboard: ({ text }) => text.toUpperCase(),
    // Drop empty lines and trim before anything is written.
    processDataFromClipboard: ({ data }) =>
      data.filter((row) => row.some((cell) => cell.trim() !== '')).map((row) => row.map((c) => c.trim())),
    // Read "12,5" as 12.5 in a Turkish spreadsheet's paste.
    processCellFromClipboard: ({ columnId, text, value }) =>
      columnId === 'price' ? Number(text.replace(/\./g, '').replace(',', '.')) : value,
  }}
/>
```

| Callback | Gets | Returns |
|---|---|---|
| `processCellForClipboard` | `row`, `rowKey`, `columnId`, `value`, `text` (shown) | The text to copy |
| `processHeaderForClipboard` | `columnId`, `text` | The header text to copy |
| `processDataFromClipboard` | `data` — rows of cell texts | The table to paste, or `null` to paste nothing |
| `processCellFromClipboard` | `row`, `rowKey`, `columnId`, `text` (pasted), `value` (what the grid would write) | The value to write |
| `sendToClipboard` | `text`, `kind` (`'copy'` or `'cut'`) | Nothing — the grid leaves the system clipboard alone |

Tabs and line breaks in a copied cell become spaces, whatever the callback
returns: they would split the cell in a spreadsheet. A pasted cell still goes
through the permission check first (`editable`, `allowUpdating`) and validation
after; the callback chooses the value, not whether the cell may change. With
`sendToClipboard` the text stays in your app — keep it for an in-app paste, or
write HTML beside it. The `copyStart` / `copyEnd` events fire either way.

## What this does not do

Written down because finding out mid-integration costs more than reading it
here.

- **The fill handle itself is mouse-only.** It is `aria-hidden`; from the
  keyboard, <kbd>Ctrl</kbd>+<kbd>D</kbd> and <kbd>Ctrl</kbd>+<kbd>R</kbd>
  (<kbd>Cmd</kbd> on a Mac) fill the way a spreadsheet does — they COPY the
  first row or column, they do not extend a numeric series the way a drag
  does. They write through the same path as the handle: the same
  `allowUpdating` check, one undo step. With nothing to copy from (one cell in
  the first row or column) the key is left to the browser. The rectangle is
  built with <kbd>Shift</kbd>+arrow, and the statistics strip is a polite live
  region, so a screen reader hears the cell count and sum as it grows. With range selection on, <kbd>Shift</kbd>+Up/Down
  extends the rectangle, not the row selection, and <kbd>Ctrl</kbd>+<kbd>A</kbd>
  still selects rows.
- **Several rectangles are a selection, not a shape.** Paste, fill and the
  chart take the newest one; copy joins them only when they line up (see
  [Several rectangles](#several-rectangles)). There is no "add mode" key
  (Excel's <kbd>Shift</kbd>+<kbd>F8</kbd>), so adding a rectangle needs the
  mouse.
- **Paste needs the async clipboard.** It reads `navigator.clipboard.readText()`
  with no `clipboardData` fallback, so it needs a secure context and whatever
  permission or confirmation the browser asks for. Where the browser refuses,
  paste does nothing.
- **Paste crops, it never grows the grid.** Copy 100 rows onto the last row and
  only the rows that fit are written.
- **Type coercion covers numbers and booleans.** A pasted **date** is written as
  text; so is a number the parser cannot read.
- **Fill extrapolates evenly spaced numbers only.** Two or more numbers with a
  constant step become an arithmetic sequence. Unevenly spaced numbers, text,
  dates, booleans and blanks repeat the pattern. No date series, no month
  names, no `Item 1 → Item 2`. Fill writes **values**, never formats.
- **Fill is single-axis**, as in Excel. A diagonal drag resolves to whichever
  direction moved further.
- **Copied text is what the user sees** — the lookup label, then the
  `valueFormatter`. That is one-way: pasting `Antalya` back does not turn it
  into the stored code.
- **Sorting or filtering does not clear the rectangle.** Range coordinates are
  view indices and only `columnStateChanged` clears them, so after a sort the
  rectangle sits on the same positions over different rows. Clear it yourself if
  that matters.
- **No event for the rectangle.** `selectionChanged` is *row* selection; there
  is no `rangeSelectionChanged`. You can observe the gestures, not the shape.
- **Statistics stop at 100,000 cells** and report `truncated` instead.
- **Community has none of it** — no rectangle, no fill, no cut, no paste.
  Community copies whole **rows** with <kbd>Ctrl</kbd>+<kbd>C</kbd>.

Without a licence key the features still run, watermarked. The boundary is
distribution and the watermark, not a code path that refuses you.

---

Source: https://kanunilabs.com/docs/datagrid/grouping

# Multi-level grouping and group summaries

Grouping itself is **Community**, and so is the group panel, and so are footer
column totals. Enterprise adds exactly two things:

1. a **second and further** grouping level,
2. those same totals **repeated on every group header**.

Worth knowing before you reach for a licence key: if one level is enough, you
already have everything.

## One level — Community

```tsx
import { DataGrid } from '@kanunilabs/datagrid-react';

<DataGrid
  dataSource={orders}
  rowKey="id"
  columns={columns}
  grouping={{ groupBy: 'region', panel: true }}
  summaries={[
    { columnId: 'units', type: 'sum' },
    { columnId: 'revenue', type: 'sum' },
  ]}
/>
```

`panel: true` puts the drop strip above the grid; dragging a header into it
groups by that column. `summaries` draws the totals in the footer.

## More levels — Enterprise

```tsx
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';

<EnterpriseDataGrid
  licenseKey={key}
  dataSource={orders}
  rowKey="id"
  columns={columns}
  grouping={{
    groupBy: ['region', 'category', 'rep'],   // outermost first
    panel: true,
    groupSummaries: true,
    collapsedByDefault: true,
  }}
  summaries={[
    { columnId: 'units', type: 'sum' },
    { columnId: 'revenue', type: 'sum' },
  ]}
/>
```

| Option | Type | Default |
|---|---|---|
| `grouping.groupBy` | `string \| string[] \| null` | `null` |
| `grouping.panel` | `boolean` | `false` |
| `grouping.groupSummaries` | `boolean` | `false` |
| `grouping.collapsedByDefault` | `boolean` | `false` |
| `grouping.showGroupedColumns` | `boolean` | `false` |
| `grouping.display` | `'fullWidth' \| 'aligned' \| 'column'` | `'fullWidth'` |
| `grouping.groupColumn` | `{ headerName?, width?, minWidth? }` | — |
| `grouping.stickyHeaders` | `boolean` | `false` |

**`groupSummaries: true` on its own shows nothing.** The group header reuses the
`summaries` array, so an empty one produces empty headers. There is no separate
per-level or per-group definition list.

Totals land *inside* the header strip — `▸ Category: Toys (12) · Revenue:
1,240` — not in a footer row beneath the members, even though the header menu
item is worded "Show group footers".

Summary types are `sum`, `avg`, `min`, `max`, `count` and `custom`. `avg`,
`min` and `max` skip blanks; `count` counts non-empty cells.

```tsx
summaries={[
  {
    columnId: 'margin',
    type: 'custom',
    calculate: (cells) => cells.reduce((a, c) => a + Number(c.value ?? 0), 0) / cells.length,
  },
]}
```

Inside a group header, `calculate` receives only that group's cells.

## Group rows aligned to the columns

By default a group row is one banner across the grid, with its summaries
written out after the label ("Sum Revenue: 11,733"). For a report you read
down the columns, put each summary under its own column instead:

```tsx
grouping={{ groupBy: 'region', groupSummaries: true, display: 'aligned' }}
```

The group row then becomes a row of cells. The group's caption, value, count
and toggle sit in the first visible column, indented by level. Each column
that has a group summary shows it in its own cell, formatted like the footer.
If a column has two summaries (`sum` and `avg`), the cell shows the first one
declared. A click still opens and closes the group, the row is still not
selectable, and its box in the checkbox column ticks every row under it.
Both the React and the JavaScript grid support it. `'fullWidth'` is the
default.

## Editing a group total

**Enterprise.** In a plan or a budget the number people change is often the
subtotal: "North gets 80 units, not 40". Give the column `groupEdit` and the
subtotal under it becomes editable:

```tsx
<EnterpriseDataGrid
  editing={{ mode: 'cell' }}
  grouping={{ groupBy: 'region', groupSummaries: true, display: 'aligned' }}
  summaries={[{ columnId: 'units', type: 'sum' }]}
  columns={[
    { field: 'region' },
    { field: 'units', dataType: 'number', groupEdit: 'proportional' },
  ]}
/>
```

Double-click the subtotal in a group row, type the new total, press
<kbd>Enter</kbd>; <kbd>Escape</kbd> keeps the old one. The new total is shared
out over every row in the group — nested groups included, open or closed:

| `groupEdit` | What the rows get |
|---|---|
| `'proportional'` | Each row keeps its share: 10 and 30 of 40 become 20 and 60 of 80. A group adding up to zero is split evenly. |
| `'even'` | Every row the same: 80 over 4 rows is 20 each. |
| a function | Whatever it returns. It gets `groupKey`, `columnId`, `aggregate`, `target` and the group's `rows` (with their value and whether they may change) and returns `{ rowKey, value }[]`. |

It works where the column's subtotal is a `sum` or an `avg` (for an average,
the rows move so their average is what you typed), and only in group rows that
show subtotals under their columns — `display: 'aligned'` or `'column'` with
`groupSummaries` on. Whole numbers stay whole: when every row and the new total
are whole, the remainder goes to the rows with the largest fractions, so the
rows add up to exactly the total typed.

The change goes through editing like any other: one step on the undo stack
(<kbd>Ctrl</kbd>+<kbd>Z</kbd> takes back the whole share-out), rows the user may
not change (`editable: false`, `allowUpdating`) keep their value and the others
take the difference, and in batch mode the rows wait for Save. A typed total is
read the way a paste is, so "1.234,5" and "1,234.5" both work.

## Group column

With `display: 'column'` the group rows get a column of their own at the start
of the grid:

```tsx
grouping={{ groupBy: ['region', 'city'], display: 'column', groupSummaries: true }}
```

The column holds each group row's toggle, value and count, indented by level.
The rest of the group row is laid out as in `'aligned'`: each group summary sits
under its own column. A record's cell in the group column is empty, since the
group header above it already gives the value.

- **Header.** The grouped columns' names, "Region › City". Set
  `groupColumn: { headerName: 'Group' }` to name it yourself.
- **Width.** 200 px by default, at least 80 (`groupColumn.width`, `minWidth`).
  It resizes and auto-fits like any column, and the width is kept in
  `getViewState()`.
- **Sorting.** A click on the header turns every grouping level around at
  once, A→Z to Z→A. In single-sort mode a click on another header replaces that
  sort, as any header click does, and the groups go back to A→Z.
- **Pinning.** It is pinned left, before any column you pinned there, so it
  stays in view while the grid scrolls sideways.
- **What it does not have.** No filter, no header menu, no total in the footer
  row. You cannot hide or move it. It exists only while rows are grouped.
- **Where it is left out.** Copy, editing, the chart and the AI state leave it
  out like the grid's other own columns.
- **Export.** It becomes the first column of an export: the group label on
  group rows, blank on records.
- **Where it works.** In Community, in the React and the JavaScript grid.
  Grouping by two or more levels is still Enterprise.

## Sticky group headers

Scroll into a long group and its header leaves the screen with the first rows.
Keep it in view:

```tsx
grouping={{ groupBy: ['region', 'city'], stickyHeaders: true }}
```

While you scroll, the headers of the groups the top row belongs to stay under
the column header, outermost first: a region, then the city inside it. When the
next group arrives, its header pushes the old one up and out. A sticky header is
the same row as the real one, with the same summaries, the same checkbox and the
same aligned cells. Clicking it opens or closes the group. Closing a group from
its sticky header also scrolls the group's real header into view, so you do not
land on whatever rows moved up into its place.

Keyboard navigation accounts for it: moving the focus up to a row stops short of
the headers that will cover it. The sticky copies are hidden from screen readers
and out of the tab order; the real headers stay in the row list. Both the React
and the JavaScript grid support it, in Community. It is off by default. It works
with client data only, because a remote grid does not hold the rows between a
header and the top of the screen.

## Dates by day, week, month, quarter or year

A date column groups by its exact value unless it says otherwise — a year of
orders makes hundreds of groups. `groupInterval` groups it by calendar unit:

```tsx
{ field: 'placed', dataType: 'date', groupInterval: 'month' } // 'day' | 'week' | 'month' | 'quarter' | 'year'
```

The banners read in the grid's language ("October 2026", "Q4 2026"; a week
shows its ISO number and the Monday it starts on), in date order, blanks last.
The group's key is the language-free bucket — `placed::2026-10` — so which
groups are collapsed survives a language switch and a saved view. Dates are
local calendar dates; a bare `"2026-10-03"` string is that calendar day, not
UTC midnight. It applies to client-side data: a server-side source groups the
way its server does.

## Reacting to it

```tsx
controller.events.on('groupChanged', ({ groupBy, levels }) => {
  // groupBy = outermost level, levels = every level
});
```

`columnStateChanged` fires too, because the grouped column leaves the data area
and comes back when grouping is removed.

From code: `controller.groupBy(id)`, `controller.setGroupSummaries(true)`,
`controller.expandAllGroups()`, `controller.collapseAllGroups()`.

[See it working →](https://kanunilabs.com/playground/datagrid/grouping-multi)

## What this does not do

- **Community trims silently.** Pass three levels to `DataGrid` and you get the
  first one; `groupSummaries` is forced to `false`. The warning is printed
  **only** under `debugMode: true`. Adding a second level in the Community UI
  *replaces* the first rather than nesting — a deliberate swap, not a no-op.
- **Group keys are `String(value)`.** Apart from date buckets
  (`groupInterval`, above) there is no `groupValueGetter`. Two values with the
  same text (`1` and `'1'`) merge into one group; `null` and `undefined` collect
  under a localised "(Blanks)".
- **`valueFormatter` is not applied to the header caption.** A formatter takes a
  row, and a group strip has no single row. `lookup` columns are the exception —
  those resolve to the label rather than the code.
- **A banner subtotal is not editable.** With the default
  `display: 'fullWidth'` the subtotals are text in one strip, so there is no
  cell to type in — use `'aligned'` or `'column'` for [editing a group
  total](#editing-a-group-total).
- **The runtime "group footers" toggle is React-only.** The vanilla header menu
  has no such item; call `controller.setGroupSummaries(...)` yourself.
- **Grouping outranks the user's sort.** Group columns are pushed to the front
  of the sort, so a user's own sort becomes the secondary key. They can still
  flip a group column's direction, and that is kept.
- **One group column, not one per level.** `display: 'column'` puts every level
  in a single column, indented. A column per level is not available, and a
  record does not repeat its group values in the group column. With
  `display: 'aligned'` the name sits in the first visible column and scrolls
  sideways with it; the group column is pinned and does not.
- **A group header is not a selectable row.** <kbd>Space</kbd> on a focused
  header opens or closes it. With `selection: { mode: 'multiple',
  checkboxColumn: true }` the banner carries a checkbox that ticks every row
  under the group — open or collapsed, nested or not — and shows all / some /
  none; from code, `controller.toggleGroupSelection(key)`,
  `setGroupSelected(key, on)` and `getGroupSelectionState(key)`.
- **`groupable: false` only closes the UI.** The header menu item is disabled
  and the column drops out of the panel list, but `controller.groupBy('thatOne')`
  still works.
- **Export lays a group row out like the aligned display.** The first column
  holds `"<label> (<count>)"`; with `groupSummaries`, each subtotal sits under
  its own column (the first summary declared for it), formatted as on screen
  and, in Excel, written as a number you can still sum. A summary on the FIRST
  column has no cell of its own there and is not exported. Styled Excel export
  turns nesting into real outline levels; PDF only indents.
- **Group totals lag unsaved edits.** Footer totals read pending edits; the
  cached group tree does not, so a group header can show the old number until
  the edit is committed.
- **Tree wins over grouping.** Configure both and `groupBy` is ignored, warned
  once under `debugMode`.
- **Server-side grouping is the server's job.** With a `DataSource` object the
  client computes nothing: return `groups: RemoteGroupRow[]` keyed on
  `groupKeys` length, with aggregates under `${columnId}:${type}`. `type:
  'custom'` is never sent (a JS reducer cannot run there).
  `expandAllGroups()` opens every level without fetching the table: groups open
  as they arrive, and only the groups the viewport reaches ask for their
  children. Closing one afterwards keeps it closed; `collapseAllGroups()`
  closes them all again.

---

Source: https://kanunilabs.com/docs/datagrid/hierarchy

# Master-detail and tree data

Two ways to show something *inside* a row. **Master-detail** opens a panel you
draw yourself; **tree data** turns a flat list into a hierarchy using a parent
reference. Both are Enterprise, and both are silently stripped in Community —
turn on `debugMode` and the console says which.

## Master-detail

Two things together: the config, and the renderer.

```tsx
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';

<EnterpriseDataGrid
  licenseKey={key}
  dataSource={orders}
  rowKey="id"
  columns={columns}
  masterDetail={{ height: 220 }}
  renderDetail={(order) => <OrderLines orderId={order.id} />}
/>
```

`masterDetail` adds the expander column and reserves the row; `renderDetail`
fills it. **Give both** — the config on its own produces an expander that opens
an empty panel.

| Option | Type | Default |
|---|---|---|
| `masterDetail.height` | `number` | the row height |
| `masterDetail.expandedByDefault` | `boolean` | `false` |
| `masterDetail.export` | `{ get, rows? }` | none — see [Details in Excel and PDF](#details-in-excel-and-pdf) |

Driving it from code:

```tsx
controller.toggleDetail(rowKey);
controller.isDetailExpanded(rowKey);
controller.collapseAllDetails();
```

### Details in Excel and PDF

A panel is whatever you render — a chart, a form, another grid — so the grid
cannot read it back into a file. Give the export the same content as a table
and it goes under each master row:

```tsx
<EnterpriseDataGrid
  masterDetail={{
    height: 220,
    export: {
      get: async (order) => ({
        title: 'Order lines',
        columns: ['Product', { header: 'Qty' }, { header: 'Price', numFmt: '#,##0.00' }],
        rows: (await fetchLines(order.id)).map((l) => [l.product, l.qty, l.price]),
      }),
      rows: 'open', // the default: rows whose panel is open; 'all' for every row
    },
  }}
  renderDetail={(order) => <OrderLines orderId={order.id} />}
/>
```

- **Excel:** the table starts one column in, under its master row, numbers and
  dates stay typed, and with the styled export (on in Enterprise) it is one
  outline level below the row, so Excel's **−** folds it away like the panel.
- **PDF:** shaded rows of the same table, from the second column on. A detail
  with more columns than the grid joins the extra values into its last cell —
  a PDF table has one set of columns.
- **CSV** is one table and leaves details out.

`get` may be async; the grid asks eight rows at a time. If it rejects, the
export fails rather than writing a file with some details missing. The toolbar
and menu exports use `masterDetail.export`; a call's own `details` option wins
(`controller.exportToExcel({ details: { get, rows: 'all' } })`).

[See it working →](https://kanunilabs.com/playground/datagrid/master-detail)

## Tree data

The rows stay flat; the grid builds the hierarchy from a parent reference.

```tsx
<EnterpriseDataGrid
  licenseKey={key}
  dataSource={employees}      // flat array
  rowKey="id"
  columns={columns}
  tree={{ parentField: 'managerId', defaultExpanded: true }}
/>
```

A row whose parent is `null` (or missing) is a root. When the parent key is not
a plain field, resolve it yourself:

```tsx
tree={{ getParentKey: (row) => row.managerRef?.id ?? null }}
```

The indent and the twisty land on the first visible column; a leaf keeps the
slot so the text stays aligned.

### From a path

When each row knows where it sits as a list of names — a file system, a
category trail, an org chart written as `Sales / EMEA / Berlin` — hand the
grid the path instead of a parent key:

```tsx
const files = [
  { id: 1, path: ['Docs', '2026', 'q3-report.pdf'], size: 120 },
  { id: 2, path: ['Docs', 'notes.txt'], size: 4 },
  { id: 3, path: ['Pics', 'logo.png'], size: 38 },
];

<EnterpriseDataGrid
  dataSource={files}
  rowKey="id"
  columns={columns}
  tree={{ getDataPath: (row) => row.path }}
/>
```

A step that has a row of its own uses that row. A step that does not —
`Docs`, `2026` and `Pics` above — becomes a **folder row**: the grid makes it
up, shows its name in the tree column and leaves the other cells empty. A
folder row is not a record. It cannot be selected or edited, select-all and
the row numbers skip it, and it is never passed to your formatters, cell
renderers or class callbacks. It does sort with its siblings (by where its
first row sorts) and stays visible when a filter matches something inside it.

Its key is `treePathKey(path)` from `@kanunilabs/datagrid-core`, so you can
open one from code (the controller from `onReady`):

```ts
import { treePathKey } from '@kanunilabs/datagrid-core';
controller.toggleTreeRow(treePathKey(['Docs', '2026']));
```

### From nested children

When the data already arrives as a tree — each row holding its children —
name the field and pass it as it is:

```tsx
const org = [
  { id: 1, name: 'CEO', reports: [
    { id: 2, name: 'CTO', reports: [{ id: 4, name: 'Developer' }] },
    { id: 3, name: 'CFO' },
  ] },
];

<EnterpriseDataGrid dataSource={org} rowKey="id" columns={columns} tree={{ childrenField: 'reports' }} />
```

The grid reads the nesting once on the way in and keeps your objects, so an
edit still writes to the row you passed. `setData` and an added row in
`applyTransaction` bring their children with them. `getDataPath` wins over
`childrenField`, which wins over `parentField` / `getParentKey`, if more than
one is set.

### From the server

A tree too big to send whole can load one level at a time. Give a server-side
`DataSource` and say which rows have children:

```tsx
<EnterpriseDataGrid
  dataSource={{
    // parentKey: null for the top level, otherwise the row being opened
    load: ({ parentKey, skip, take, sort, filter }) =>
      api.children(parentKey, { skip, take, sort, filter }),
  }}
  rowKey="id"
  columns={columns}
  tree={{ hasChildren: (row) => row.childCount > 0 }}
/>
```

The grid asks for the top level first. When a row is opened, it asks for that
row's children, and only for the rows the screen needs. Each level is paged in
blocks, the same way [grouping on the server](https://kanunilabs.com/docs/datagrid/remote#grouping-on-the-server)
pages through groups. A closed row costs no request. A row opened, closed and
opened again reuses what it already loaded.

Sort, filter and paging (`skip` / `take`) apply within each level, and
`totalCount` is the number of children that level has. When a filter matches a
row deep in the tree, the server decides whether that row's ancestors are sent
too. Sending them is what keeps the match reachable.

Which rows are open is part of the saved view, as for a tree in memory. "Expand
all" also loads lazily: it opens every row, but only the levels the viewport
reaches are fetched. Export refuses, as it does for grouping on the server,
because the whole tree is never in the browser.

[See it working →](https://kanunilabs.com/playground/datagrid/tree-data)

## What these do not do

- **A server tree needs `hasChildren`.** Pass a server-side `DataSource` with
  only `parentField` / `getParentKey` and the tree is ignored: the grid shows a
  flat list and logs a console warning when it is created, because finding
  parents needs every row in memory. With `hasChildren` the tree loads
  [level by level from the server](#from-the-server); the path and nested
  forms are for data in memory.
- **Tree and grouping are exclusive.** With both configured the tree wins and
  `groupBy` is ignored; `debugMode` says so once.
- **One panel height for the whole grid.** `masterDetail.height` is not
  per-row, and `getRowHeight` cannot override a detail row.
- **Saved views do not remember open detail panels.** A restored view resets
  them deliberately — they would reopen against rows that may be gone. Tree
  expansion IS stored (`getViewState().tree`), as are collapsed groups.
  `expandAllDetails()` / `collapseAllDetails()` open and close every visible
  panel, and `treeRowToggled` / `detailToggled` report each change.
- **Detail rows are skipped by cell navigation.** Tree nodes open from the
  keyboard: <kbd>→</kbd> opens a closed node and <kbd>←</kbd> closes an open
  one or goes to the parent, in the first column (where the toggle is); the
  toggle button itself still takes <kbd>Enter</kbd> and <kbd>Space</kbd>.
- **Tree export is flat.** Tree rows export as ordinary rows at level 0 — no
  indentation. Detail panels are written only through
  [`masterDetail.export`](#details-in-excel-and-pdf). A folder row of a path tree is
  written as its name in the first column, the way a group banner is, and is
  left out of a selected-only export or one with `includeGroups: false`.
- **A nested tree is read once.** Changing a row's `children` array after it
  is loaded does not move anything; pass the data again with `setData`, or add
  and remove rows with `applyTransaction`.
- **Tree selection does not cascade.** Ticking a parent does not tick its
  children; there is no descendant concept in the selection engine.

If any of those is load-bearing for you, say so — several are small, and knowing
which one blocks a real project is how they get prioritised.

---

Source: https://kanunilabs.com/docs/datagrid/filter-builder

# Filter builder

A dialog where the user assembles conditions into AND/OR groups, nested as deep
as they like. One boolean turns it on:

```tsx
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';

<EnterpriseDataGrid
  licenseKey={key}
  dataSource={rows}
  rowKey="id"
  columns={columns}
  filterBuilder
  filterPanel
/>
```

That adds a **Filter builder…** button above the grid plus a chip showing the
active filter with a Clear button. `filterPanel` is the companion: a bar under
the footer that spells the *effective* filter out as a sentence — pass
`'always'` to keep it visible when nothing is filtered.

Vanilla is the same field on `createEnterpriseGrid`, and there you can also open
it from code:

```js
const grid = createEnterpriseGrid(el, { /* … */ filterBuilder: true });
grid.openFilterBuilder();
```

[See it working →](https://kanunilabs.com/playground/datagrid/filter-builder)

## The tree it produces

The dialog writes a serialisable AST — store it, restore it, send it to a
server:

```ts
type FilterNode = FilterCondition | FilterGroupNode;

interface FilterCondition {
  columnId: string;
  operator: FilterOperator;   // 'contains' | '=' | '>' | 'between' | 'blank' | …
  value?: unknown;            // array for 'in', [min, max] for 'between'
}

interface FilterGroupNode {
  logic: 'and' | 'or';
  nodes: FilterNode[];        // every "+ Group" nests one of these
}
```

```tsx
controller.setFilter({
  logic: 'and',
  nodes: [
    { columnId: 'status', operator: '=', value: 'open' },
    {
      logic: 'or',
      nodes: [
        { columnId: 'amount', operator: '>', value: 10_000 },
        { columnId: 'priority', operator: '=', value: 'high' },
      ],
    },
  ],
});
```

`controller.getFilter()` reads it back; `controller.setFilter(null)` clears it.

## Relative dates

A date column offers **is in** a period next to the fixed comparisons: today,
yesterday, tomorrow, this / last / next week, month, quarter and year, year to
date, and the last or next *N* days (today included). The condition stores the
period, not the dates:

```ts
controller.setColumnFilter('placed', {
  columnId: 'placed',
  operator: 'period',
  value: { period: 'lastDays', days: 7 },   // or { period: 'thisMonth' }
});
```

So a saved view filtered to "this month" still means this month next month.
The grid turns the period into an ordinary `between` over two instants each
time it filters, so the worker and a server-side data source receive a plain
range and need no calendar of their own. Periods are local calendar days,
weeks start on Monday, and a filter set yesterday is re-evaluated on the next
filter, sort or data change — the grid does not wake itself at midnight. The
operator works in every edition from code; the dialog is Enterprise, and the
Community filter row takes a period by name ("this month", "the last 30 days")
in a date column's box.

## Two filters, not one

This is the part that catches people. The grid holds **two** filter sources:

| source | where it lives | read with |
|---|---|---|
| the builder | the programmatic slot | `controller.getFilter()` |
| header funnel + filter row | per-column state | column state |
| both, combined | — | `controller.getEffectiveFilter()` |

The builder writes only to the first. A condition the user set through the
header funnel does **not** appear in the dialog and is **not** removed by its
Clear button. The `filterPanel` sentence describes the combined result, which is
why it is worth turning on alongside the builder.

The `filterChanged` event follows the panel, not the builder:

```tsx
controller.events.on('filterChanged', ({ filter }) => {
  // `filter` is the EFFECTIVE filter — builder plus every column filter.
  // It is NOT the same value as controller.getFilter().
});
```

## What this does not do

- **The `in` operator is missing from the dialog.** The AST has 14 operators and
  the builder offers 13; multi-value membership is produced only by the header
  funnel's checkbox list.
- **The column dropdown lists visible, ungrouped columns.** Hidden columns, and
  grouped ones while `showGroupedColumns` is off, are not offered — write those
  conditions with `controller.setFilter` instead.
- **The dropdown ignores `filterable: false`.** The editing command column is
  declared unfilterable and still shows up in the list.
- **Empty nodes survive.** Apply sends `null` only when the *root* group is
  empty; a nested empty group stays in the AST (harmless — the engine reads it
  as true — but visible in a saved view), and a condition left blank is applied
  as written.
- **No validation.** Nothing caps condition count or nesting depth, and
  `between` with From greater than To raises no warning — it simply matches
  nothing.
- **`=` is unreliable on dates.** The date input produces a `yyyy-mm-dd`
  **string** and equality compares it against the stored cell, so a `Date`
  object or a differently formatted ISO string never matches. The ordering
  operators (`>`, `>=`, `<`, `<=`, `between`) are date-aware and correct.
- **Lookup columns compare the stored code.** The value field is plain text and
  the engine matches the code, not the label the user sees on screen. Reading is
  fine — the panel sentence resolves codes to labels — but typing the label does
  not match.
- **Some chrome is untranslated.** `+ Condition`, `+ Group`, `Apply`, `Clear
  all`, the AND/OR options and the `Column`/`Operator`/`Value`/`From`/`To`
  aria-labels are hardcoded English. Title, operator labels, Cancel, the
  empty-group text and the value placeholder come from the dictionary.
- **Community has the hook, not the dialog.** `onOpenFilterBuilder` exists on
  the Community `DataGrid` and draws a chevron on the filter panel, but it opens
  nothing on its own — the application supplies the UI.
- **React and vanilla only.** The `prefilter-builder` in the Angular packages
  belongs to PivotGrid and speaks a different AST; the two are not
  interchangeable.
- **Test hooks are asymmetric.** `data-testid` attributes exist on the vanilla
  dialog only (`dg-filter-builder`, `dg-filter-builder-apply`, …). Reach the
  React dialog through aria-labels and the `.kanuni-datagrid-filter-condition`
  class.

---

Source: https://kanunilabs.com/docs/datagrid/import

# Import wizard

A dialog that takes a CSV — or pasted text — sniffs the delimiter, infers types,
maps the file's columns onto the grid's, and hands the rows to you.

**The parser is Community. Only the dialog is Enterprise.** If you are building
your own import UI, everything underneath is already in the free package:

```ts
import {
  parseCsv, sniffDelimiter, importCsv,
  autoMapColumns, buildImportPlan, applyImportMapping,
} from '@kanunilabs/datagrid-core';
```

## The dialog

```tsx
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';

<EnterpriseDataGrid
  licenseKey={key}
  dataSource={rows}
  rowKey="id"
  columns={columns}
  onImport={(imported) => setRows((prev) => [...prev, ...imported])}
/>
```

Defining `onImport` is what puts the **Import…** button on the toolbar. Vanilla
takes the same field and adds a programmatic opener:

```js
const grid = createEnterpriseGrid(el, { /* … */ onImport: (rows) => append(rows) });
grid.openImportWizard();
```

The two steps are **1. Source** (file or paste, delimiter, header row) and
**2. Map columns** (each file column against a grid column, with the inferred
type and a sample). There is no third step.

Using the component directly:

```tsx
import { GridImportWizard } from '@kanunilabs/datagrid-react-enterprise';

<GridImportWizard
  open={open}
  onClose={() => setOpen(false)}
  columnModel={controller.columnModel}
  onImport={(rows) => append(rows)}
  previewRows={20}
/>
```

[See it working →](https://kanunilabs.com/playground/datagrid/import-wizard)

## The grid does not touch your data

`onImport` gives you rows. That is where the grid's involvement ends — inserting,
updating, deduplicating and writing to a server are yours. Nothing is published
on the event bus, and the import does not enter the editing undo stack.

Auto-mapping is deliberately **not fuzzy**. It tries the exact column id, the
exact `headerName`, and a normalised comparison (lowercased, spaces/`_`/`-`
removed). `Amount Paid` does not match `Amount` — a wrong guess in an import is
worse than no guess.

## What this does not do

- **CSV-family text only.** The picker accepts `.csv,.tsv,.txt,text/csv`. No
  XLSX, JSON, XML, clipboard HTML or archives — convert the Excel file first.
- **No validation step.** No per-row error report, no upsert or dedupe, no
  partial commit, no rollback.
- **Type mismatches are shown, not enforced.** Values are carried across as
  parsed. Types are inferred from the **file**, not from the target column's
  `dataType`, so mapping a text column onto a number column puts text in the
  cell.
- **Dates stay strings.** The date branch returns the trimmed string, not a
  `Date`.
- **The "(N unparsed)" badge is number-only.** A malformed date or an
  unrecognised boolean never produces one.
- **Type inference samples the first 200 non-empty values.** A column that is
  numeric for 200 rows and text after that is inferred as a number, and the rest
  become `NaN`.
- **The boolean vocabulary is fixed:** `true/false/yes/no/evet/hayır` are
  accepted, `true/yes/evet` are truthy. No hook to extend or localise it.
- **Delimiter sniffing tries four candidates** — comma, semicolon, tab, pipe —
  over the first five non-empty rows. No fixed-width, no multi-character
  delimiters.
- **Short rows are padded, long rows are cropped.** Missing fields become `null`
  and are counted in a warning; extra fields beyond the header count are dropped
  **silently**.
- **Two file columns may be mapped to one target.** Auto-mapping refuses it, but
  a user can do it by hand with no warning, and the last mapping wins.
- **Going Back re-parses and resets the mapping.** Manual corrections made in
  step 2 are lost when the user returns to step 1.
- **Everything is read into memory at once.** `file.text()` then a synchronous
  parse — no streaming, no worker. `previewRows` trims the preview table only.
  A very large file blocks the main thread.
- **No programmatic open in React.** Toggle the `open` prop yourself or use the
  toolbar button; only vanilla has `openImportWizard()`. Vanilla also allows one
  dialog at a time — opening the filter builder closes the wizard.
- **Translation is partial.** Field labels come from the dictionary; `1. Source`,
  `2. Map columns`, `First row is a header`, `Delimiter`, `Next →`, `← Back`,
  `Import N rows` and the summary line are hardcoded English. The "Not filled by
  this file:" list prints raw column **ids**, not header names.
- **Nothing is imported if nothing maps.** The commit button stays disabled —
  there is no silent half-import.

The licence key must carry the `datagrid-editing` feature. Without a key the
wizard still runs, watermarked.

---

Source: https://kanunilabs.com/docs/datagrid/panels

# Side bar and status bar

Two strips of chrome around the grid. The **side bar** docks a column chooser
and a filter panel to the right edge; the **status bar** puts row counts and
selection statistics along the bottom. Both are Enterprise.

```tsx
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';

<EnterpriseDataGrid
  licenseKey={key}
  dataSource={rows}
  rowKey="id"
  columns={columns}
  sideBar={{ panels: ['columns', 'filters'], defaultOpen: 'columns' }}
  statusBar={{ items: ['totalRows', 'filteredRows', 'selectedRows', 'rangeStats'] }}
/>
```

`sideBar` and `statusBar` both accept `true` as a shorthand for every panel and
every built-in item, in that order.

| Option | Type | Notes |
|---|---|---|
| `sideBar.panels` | `('columns' \| 'filters' \| { id, label, render })[]` | order is the tab order; objects are [your own panels](#your-own-panels) |
| `sideBar.defaultOpen` | panel id or `null` | read at mount only |
| `sideBar.open` / `onOpenChange` | panel id or `null` | React: the open tab from your state; vanilla: `openSideBarPanel(id)` on the returned API |
| `statusBar.items` | `('totalRows' \| 'filteredRows' \| 'selectedRows' \| 'rangeStats')[]` | order is the render order |
| `statusBar.itemsAfter` | `ReactNode` / `Node \| string` | appended **after** the built-ins |

[See it working →](https://kanunilabs.com/playground/datagrid/status-bar)

## Selection statistics

`rangeStats` reports the **cell rectangle** — count, sum, average, min, max:

```tsx
statusBar={{ items: ['totalRows', 'rangeStats'] }}
editing={{ mode: 'cell', range: true }}
```

The second line is not optional. `rangeStats` reads the editing layer's range
source, so `editing: { enabled: false }` or `range: false` leaves it
permanently null. See [range selection](https://kanunilabs.com/docs/datagrid/range-selection) for the
rectangle itself.

## Your own panels

A panel of your own sits in the same strip as Columns and Filters — a summary
of what the grid shows, a legend, the details of the selected row. Put an
object in `panels`:

```tsx
<EnterpriseDataGrid
  sideBar={{
    panels: [
      'columns',
      { id: 'summary', label: 'Summary', render: (controller) => <Summary controller={controller} /> },
      'filters',
    ],
    defaultOpen: 'summary',
  }}
/>
```

`render` gets the grid's controller, to read rows (`getRows()`,
`getSelectedRows()`) or act on them. The panel is drawn only while its tab is
open, like the built-ins, so state that must outlive a close belongs to your
app. In React the panel redraws with the bar; a component that should follow
selection or edits subscribes to `controller.events` itself.

In plain JavaScript `render(host, controller)` draws into `host` and may
return a cleanup, called when the tab closes or the grid is destroyed — the
place to remove the event listeners it added. The bar never redraws your
panel:

```js
const grid = createEnterpriseGrid(el, {
  sideBar: {
    panels: ['columns', {
      id: 'summary',
      label: 'Summary',
      render(host, controller) {
        const paint = () => { host.textContent = `${controller.getRows().length} rows`; };
        paint();
        const off = controller.events.on('contentReady', paint);
        return off;
      },
    }],
  },
});
grid.openSideBarPanel('summary');
```

To open a tab from your own button, pass `open` and `onOpenChange` (React) or
call `openSideBarPanel(id)` (vanilla; `null` closes the bar). `onOpenChange`
reports the user's clicks — not the tab you opened from code.

[See it working →](https://kanunilabs.com/playground/datagrid/side-bar-panels)

## Two side effects worth knowing

1. A side bar containing the `columns` panel **silently turns off** the toolbar
   column-chooser button. Pass `toolbarColumnChooser` explicitly to get it back.
2. With a status bar present, the standalone `GridSelectionStats` strip is no
   longer rendered — the numbers move into the bar, so they appear exactly once
   either way.

## What these do not do

- **Panels go in the side bar's strip, not anywhere else.** A panel of your
  own is a tab beside the built-ins ([above](#your-own-panels)); the status
  bar's `itemsAfter` is its only slot, and it only appends.
- **Chips are conditional.** `filteredRows` draws only when a filter actually
  narrows the set, `selectedRows` only when the selection is non-empty. You
  cannot force "Selected 0" or "Filtered = Total".
- **Totals stop at 100,000 cells.** Past that the bar reads "Selection too large
  to total" and returns `truncated: true` with `numeric: null`. The limit is a
  constant, not a prop.
- **Only real numbers are summed.** Numeric strings are coerced first, but
  `Date` objects are skipped — the accumulator ignores anything that is not
  `typeof value === 'number'`. With no numbers in the rectangle only the Cells
  chip remains.
- **`cells` and `numeric.count` differ on purpose.** The first counts the whole
  rectangle, the second only the numeric cells.
- **Row selection is not cell selection.** Ticking checkboxes moves
  `selectedRows` and nothing else; statistics come from the cell rectangle.
- **Open state is not persisted.** `defaultOpen` is read once at mount —
  changing the prop later does not reopen a closed panel, and the open tab is
  not written to grid state or `localStorage`.
- **Neither strip publishes events.** There is no `sideBarOpened` in
  `GridEventMap`; they are passive observers of the controller. In React the
  open state is not lifted, so you cannot drive the tab from outside either.
- **A filter set before the panel mounts is invisible in React** until a
  `filterChanged` event arrives — the inputs start empty and reconcile on the
  event. Vanilla refreshes on open, so it fills correctly.
- **The Filters panel edits only filter-row conditions.** Set filters chosen in
  the funnel popup, and filters set from code, show as a ● dot and a description
  line but cannot be edited in the box. "Clear all filters" does clear
  everything.
- **Hidden and unfilterable columns are skipped,** and neither panel ever lists
  the grid's own chrome columns (the `__dg_` prefixed ones).
- **The last visible column cannot be unticked** — the panel will not let you
  hide every column.
- **Layout is fixed:** a 28px tab rail and a 232px panel, right edge only. Not
  resizable, not draggable, no left dock.
- **Accessibility is half-done.** The tabs carry `role="tab"` and
  `aria-selected`, but the panels have no `role="tabpanel"` and no
  `aria-controls` link. The status bar is `role="status"` — a live region, so
  every counter change is announced.
- **Vanilla statistics ignore `config.locale`.** The stat formatter uses the
  browser locale while the row counters beside it use yours. React's
  `GridSelectionStats` takes the `locale` prop correctly.
- **Chip labels have no per-instance prop.** Override the dictionary keys
  `statusRows` / `statusFiltered` / `statusSelected` through `messages`; a
  `labels` prop exists only on the standalone `GridSelectionStats`.
- **Community cannot use either.** Both props exist only on
  `EnterpriseDataGrid` and `createEnterpriseGrid`. Without a licence key they
  still work, watermarked.

---

Source: https://kanunilabs.com/docs/datagrid/ai

# Grid state for AI models

"Show me the pending orders in the Aegean, biggest first, and hide the SKU." That
is a filter, a sort and a hidden column, and the grid already supports all three.
A language model can produce that state if it knows exactly what the state
looks like for **this** grid. The grid gives you three calls for that:

| Call | What it does |
|---|---|
| `getAiSchema(options?)` | A JSON Schema of the grid's state, limited to what its columns allow |
| `getAiState(options?)` | The current state in that shape, for the model to start from |
| `applyAiState(answer, options?)` | Checks the model's answer and applies the valid part in one step |

There is no model inside the grid, and the grid sends nothing anywhere. You use
your own model (any model that supports structured output, or any that can
return JSON) and call it from your own code, usually your server. The calls are
on the controller, so they work the same in React (`onReady`) and in plain
JavaScript (`grid.controller`). Enterprise only: in Community they throw an
error that names the feature.

The PivotGrid has the same for its layout of fields, measures and totals: see
[Pivot layout for AI models](https://kanunilabs.com/docs/pivotgrid/ai).

## A round trip

```ts
// In the browser: describe the grid and its current state.
const schema = controller.getAiSchema();
const current = controller.getAiState();

// On your server: ask your own model, with the schema as its output format.
const answer = await askModel({
  instructions:
    'You change the state of a data grid. Start from the current state and ' +
    'change only what the user asks for.',
  input: `Current state: ${JSON.stringify(current)}\nRequest: ${userText}`,
  outputSchema: schema,
});

// Back in the browser: apply what came back.
const { applied, dropped } = controller.applyAiState(answer);
if (dropped.length > 0) showNotice(`Could not apply: ${dropped.join('; ')}`);
```

`askModel` stands for your own call to your model's API. Most APIs that support
structured output accept the schema as it is. `answer` can be the parsed object
or the JSON text the API returns.

## What the schema covers

| Part | Property | Notes |
|---|---|---|
| `filter` | `filter` | One condition or a tree of `and` / `or` groups. `null` clears it |
| `sort` | `sort` | Outermost first; `[]` for unsorted |
| `grouping` | `groupBy` | Outermost first; `[]` for none. Not offered on a tree grid |
| `columnVisibility` | `columns[].visible` | Only the columns listed change |
| `columnSizing` | `columns[].width` | Pixels, or `null` to leave as is |
| `columnPinning` | `columns[].pinned` | `'left'`, `'right'` or `null` |
| `search` | `searchText` | The toolbar's free-text search |

The schema only offers what the grid would accept. A column with
`sortable: false` is not in the sort list, a column with `groupable: false` is
not in the grouping list, and each data type gets the operators the
[filter builder](https://kanunilabs.com/docs/datagrid/filter-builder) offers for it. Text columns get
contains / starts with / ends with. Numbers and dates get comparisons and
`between`. Dates also get `period`, which keeps "this month" meaning this month
tomorrow. Yes/no columns get `=`, and every column gets is blank / is not blank.

The schema's description lists every column with its id, header, type and
meaning, so a model can map "biggest" to the right number column.

### Strict structured output

Every object in the schema lists all of its properties as required and allows
no others. "Leave this alone" is written as an explicit `null` or `[]`. That is
the subset the strictest structured-output modes accept, and any other JSON
Schema consumer accepts it too. The schema is draft 2020-12. The filter is
recursive through `$defs`.

## Telling the model more

```ts
const options = {
  // Parts the model may not change. They are also left out of the schema.
  exclude: ['columnSizing', 'columnPinning'],
  columns: {
    revenue: { description: 'Order total in USD, VAT included' },
    // List this column's values, so "orders from Izmir" matches what is stored.
    city: { includeValues: true },
    // Never mention this column to the model.
    customerEmail: { exclude: true },
  },
  maxValues: 50, // most values listed per column (default 100)
};

controller.getAiSchema(options);
controller.applyAiState(answer, options); // same options on the way back
```

**Data values are listed only when you ask.** `includeValues` sends the
column's distinct values to whatever model you use, so turn it on only for
columns whose values you are allowed to share. A column with a static `lookup`
list is the exception: that list is your own code → label table (say `izm`
shown as "Izmir"), and a model cannot match a coded value without it. It is
listed by default. Set `includeValues: false` to keep it out.

## What `applyAiState` does with an answer

- **Keeps the valid part.** A condition on a column that does not exist, an
  operator that does not suit the column's type, a sort on a column that cannot
  be sorted: each one is dropped, and the rest is applied.
- **Says what it dropped.** `dropped` lists each problem in words, such as
  `filter on country (=): no such column`. Show it to the user, log it, or send
  it back to the model for a second try. With `debugMode` the console prints it
  as well.
- **Never throws on a bad answer.** Text that is not JSON, or JSON that is not
  an object, returns `applied: []` with the reason.
- **Applies everything in one step.** The filter, sort, grouping and columns
  change in one view change, so the grid recomputes once.
- **Puts single-column conditions in that column's own filter.** There the
  filter row and the header popup show them, and the user can clear them the
  usual way. Only conditions that span columns (an `or` across two of them) go
  to the [filter builder](https://kanunilabs.com/docs/datagrid/filter-builder)'s tree.
- **Will not hide every column.** An answer that would leave no visible column
  keeps the visibility as it was.
- **Ignores parts it was told to leave alone.** If `exclude` names a part, that
  part is ignored even when the model sends it.

## What it does not do

- **No model, prompt or chat box.** The schema and the checks are the grid's
  part. The conversation, the model and the API key belong to your application.
- **Not saved views.** A saved view (`getViewState`) holds more than the model
  should touch: pages, open groups, chart state. Use saved views to remember a
  layout and this API to change one from words.
- **No row data in the schema.** The model sees columns and, only when you
  allow it, the distinct values of a column. It never sees rows. Questions about
  the data ("which region sold most?") need the data, which is a different
  feature.

This page is about AI features inside your app. To help an AI assistant write
code that uses the grid, see [AI coding assistants](https://kanunilabs.com/docs/datagrid/ai-assistants).