apex-grid 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to the `apex-grid` (community) package are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 and the format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [3.3.0] - 2026-07-02
+
+A large, additive, backward-compatible release. The public `.` / `./define` API
+stays compatible and existing grids keep working. A couple of default behaviors
+changed: numeric and currency columns now left-align (previously their values
+right-aligned), and a column menu / filter button now appear on sortable /
+filterable columns.
+
+### Added
+- **State snapshots: `getState()` / `setState()`.** Serialize and restore the
+  grid's state (such as sort, filter, columns, pagination, selection, and
+  expansion) as a plain, JSON-safe object. `setState()` is defensive: it
+  validates the incoming shape and returns a result report instead of throwing
+  on unexpected input.
+- **`getSchema()`.** A capability descriptor for the grid's columns and features,
+  intended for tooling and AI integrations.
+- **`stateChanged` event.** Fires when a state-bearing operation changes, so a
+  host can persist or react to grid state.
+- **Internationalization.** A `localeText` override map plus a bundled Spanish
+  (`es`) locale; every built-in string (core, and the enterprise features) is
+  localizable.
+- **Declarative cell validation.** Per-column validators reject invalid edits,
+  reflect `data-invalid` on the cell, surface an inline error message, and block
+  the commit.
+- **Undo / redo** for cell-data edits, backed by a history controller.
+- **Row pinning.** Pin rows to sticky top and / or bottom bands that stay in view
+  while the body scrolls.
+- **Row drag-reorder.** Reorder rows by dragging, applied as a manual-order
+  pipeline step. A six-dot grip handle shows by default (`rowReordering.handle`,
+  default `true`) and dragging lifts a full-row floating ghost. Two modes are
+  supported: handle mode (only the grip starts a drag, so the rest of the row
+  stays free for selection and editing) and whole-row mode (`handle: false`,
+  drag from anywhere on the row).
+- **Column groups.** Spanning header groups above the column header row.
+- **Spreadsheet coordinate hints.** Set `coordinateHints` (reflected as the
+  `coordinate-hints` attribute) to reveal a leading row-number gutter
+  (1, 2, 3, and so on) and A / B / C column-letter header chips, so cell
+  references are discoverable.
+- **Header column menu and per-column filter button.** A kebab (three-dot)
+  button opens a column menu; the built-in items are Sort Ascending / Descending
+  and Autosize Column, and a feature module can supply the menu through the new
+  `ColumnMenuProvider` seam (so `apex-grid-enterprise` fills it with pin / hide /
+  group / chart actions). The kebab shows on sortable or resizable columns, or
+  whenever a module provides a menu, and is always visible (not hover-only); set
+  the new `columnMenu` property to `false` to hide it. Filterable columns also
+  show a filter button that opens the filter panel.
+- **Column separators.** A persistent vertical divider now shows on every
+  column header's trailing edge, not just the frozen-column pin edges. On
+  columns that opt into resizing the divider doubles as the resize handle (it
+  takes the `col-resize` cursor and can be dragged). On by default; set
+  `columnSeparator` to `false` (reflected as the `column-separator` attribute)
+  to hide them. The line's color and vertical inset are themeable via
+  `--ag-header-separator` / `--header-separator-color` and
+  `--apex-header-separator-inset`.
+- **`allowFormula` column flag.** Inert in the community grid; the seam the
+  `apex-grid-enterprise` formula editor builds on.
+
+### Changed
+- **Numeric and currency columns left-align by default**, matching the common
+  data-grid default. Previously their values right-aligned; now the header label
+  and the column values both sit at the leading edge, like every other column.
+  Digits still use tabular figures so they stay vertically consistent.
+- **Filtering opens in a floating panel** from the header filter button, instead
+  of an always-present inline filter row.
+- Theming refinements: design-token tweaks and a crisp 1px frozen-column
+  pin-edge line.
+
+### Fixed
+- Range-selection drag now tracks through `pointermove`, so a drag that leaves
+  and re-enters the grid stays accurate.
+
+### Internal
+- Cell writes funnel through a single `applyCellEdit` choke point, so undo / redo,
+  validation, and (in enterprise) formula recalculation share one write path.
+  `apex-grid/internal` also gained the seams the enterprise coordinate, formula,
+  and column-menu (`ColumnMenuProvider`) features build on.
+
 ## [3.2.0] — 2026-06-23
 
 Additive, backward-compatible release. The default look of `<apex-grid>` is
@@ -107,6 +184,7 @@ Documentation-only patch (no runtime or API changes).
 - Repository converted to an npm-workspaces monorepo; this package publishes
   from `packages/core`.
 
+[3.3.0]: https://github.com/apexcharts/apex-grid/releases
 [3.2.0]: https://github.com/apexcharts/apex-grid/releases
 [3.1.0]: https://github.com/apexcharts/apex-grid/releases
 [3.0.1]: https://github.com/apexcharts/apex-grid/releases

package/README.md

@@ -8,22 +8,29 @@ A Lit-based, framework-agnostic web component data grid. Ships as a single custo
 
 ## Features
 
-- **Row virtualization** via `@lit-labs/virtualizer` — only ~20 rows in the DOM at any time, regardless of dataset size.
-- **Sorting** — single or multi-column, tri-state (asc / desc / none), per-column comparers.
-- **Filtering** — per-column filter chips with string / number / boolean / date operands, plus a quick-filter (global search) input.
-- **Pagination** — local slicing or remote mode with a `pageChanging` / `pageChanged` event pair; built-in `<apex-grid-paginator>`.
-- **Column pinning** — pin to start or end; visual reordering only, source `columns` array is preserved.
-- **Column reordering** — drag-and-drop with per-column opt-out, constrained to the column's pinning group.
-- **Column resizing** — pointer-driven, with a min-width safeguard.
-- **Inline editing** — cell or row mode, click or double-click trigger, per-column opt-in.
-- **Row selection** — single or multiple, optional checkbox column, full programmatic API.
-- **Row expansion (master-detail)** — opt-in chevron column with a `detailTemplate`.
-- **Tree data (nested rows)** — AG Grid–style `getDataPath` pattern over a flat array.
-- **CSV export** — programmatic method plus an optional toolbar dropdown. (Excel/XLSX export is in `apex-grid-enterprise`.)
-- **Toolbar** — opt-in `<apex-grid-toolbar>` with debounced quick filter and export menu.
-- **Templating** — slot-based templates for cells, headers, editors, and detail panels.
-- **Theming** — styled out-of-the-box; fully customizable through `--ag-*` CSS custom properties (no theme import or build step). Auto-matches an `igniteui-webcomponents` host app when one is present.
-- **Accessibility** — WCAG 2.2 AA semantics (`role="grid"` / `role="treegrid"`, `aria-rowcount`, `aria-colcount`, focus + keyboard navigation).
+- **Row virtualization** via `@lit-labs/virtualizer`: only ~20 rows in the DOM at any time, regardless of dataset size.
+- **Sorting**: single or multi-column, tri-state (asc / desc / none), per-column comparers.
+- **Filtering**: per-column filter chips with string / number / boolean / date operands, plus a quick-filter (global search) input.
+- **Pagination**: local slicing or remote mode with a `pageChanging` / `pageChanged` event pair; built-in `<apex-grid-paginator>`.
+- **Column pinning**: pin to start or end; visual reordering only, source `columns` array is preserved.
+- **Column reordering**: drag-and-drop with per-column opt-out, constrained to the column's pinning group.
+- **Column resizing**: pointer-driven, with a min-width safeguard.
+- **Column groups**: spanning multi-level headers over a flat `columns` array, respecting pin regions.
+- **Inline editing**: cell or row mode, click or double-click trigger, per-column opt-in.
+- **Cell validation**: declarative per-column `validators` (built-ins plus custom), surfaced with `aria-invalid` and an event.
+- **Undo / redo**: opt-in history for cell edits, with keyboard shortcuts (Ctrl/Cmd+Z, etc.).
+- **Row selection**: single or multiple, optional checkbox column, full programmatic API.
+- **Row pinning**: sticky top / bottom bands rendered outside the virtualizer.
+- **Row drag-reorder**: pointer and keyboard reordering with a manual order, mutually exclusive with sorting.
+- **Row expansion (master-detail)**: opt-in chevron column with a `detailTemplate`.
+- **Tree data (nested rows)**: `getDataPath` pattern over a flat array.
+- **State & persistence**: `getState()` / `setState()` snapshot round-trip, a `stateChanged` event, and a `getSchema()` capability descriptor.
+- **Localization (i18n)**: override any built-in string via `localeText`; bundled dictionaries (e.g. `esLocale`).
+- **CSV export**: programmatic method plus an optional toolbar dropdown. (Excel/XLSX export is in `apex-grid-enterprise`.)
+- **Toolbar**: opt-in `<apex-grid-toolbar>` with debounced quick filter and export menu.
+- **Templating**: slot-based templates for cells, headers, editors, and detail panels.
+- **Theming**: styled out-of-the-box; fully customizable through `--ag-*` CSS custom properties (no theme import or build step). Auto-matches an `igniteui-webcomponents` host app when one is present.
+- **Accessibility**: WCAG 2.2 AA semantics (`role="grid"` / `role="treegrid"`, `aria-rowcount`, `aria-colcount`, focus + keyboard navigation).
 - **Provenance-signed npm releases** with OIDC trusted publishing.
 
 ---
@@ -38,7 +45,7 @@ import { setup } from 'apex-grid';
 setup();
 ```
 
-That single call registers `<apex-grid>` and adopts a default host stylesheet (`height: 100%; min-height: 240px`). The grid is styled out-of-the-box — no theme CSS import is required.
+That single call registers `<apex-grid>` and adopts a default host stylesheet (`height: 100%; min-height: 240px`). The grid is styled out-of-the-box; no theme CSS import is required.
 
 ### Render the grid
 
@@ -87,7 +94,7 @@ If you'd rather not use `setup()`, this is what it does under the hood. Skipping
 npm install apex-grid lit
 ```
 
-`igniteui-webcomponents` ships as a transitive dependency — no separate install.
+`igniteui-webcomponents` ships as a transitive dependency; no separate install.
 
 ### 2. Register the custom element
 
@@ -106,7 +113,7 @@ Without this, `<apex-grid>` is an inert unknown element.
 
 ### 3. (Optional) Customize the look
 
-The grid is styled out-of-the-box — there is no theme to import. Customize it by overriding the `--ag-*` CSS custom properties on `apex-grid` (or any ancestor); a one-line brand override cascades to every tint:
+The grid is styled out-of-the-box; there is no theme to import. Customize it by overriding the `--ag-*` CSS custom properties on `apex-grid` (or any ancestor); a one-line brand override cascades to every tint:
 
 ```css
 apex-grid {
@@ -119,14 +126,14 @@ apex-grid {
 
 See [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full token list (brand, surfaces, text, semantic state colors, typography, spacing, motion).
 
-**Grid edge / shadow.** By default the grid shows a flat 1px hairline edge (no drop shadow). Control it with the `--ag-grid-shadow` hook — this is an opt-in override, not one of the `_tokens.scss` defaults:
+**Grid edge / shadow.** By default the grid shows a flat 1px hairline edge (no drop shadow). Control it with the `--ag-grid-shadow` hook, an opt-in override that is not one of the `_tokens.scss` defaults:
 
 ```css
 apex-grid { --ag-grid-shadow: var(--ag-shadow-card); } /* elevated floating-card look */
 apex-grid { --ag-grid-shadow: none; }                  /* remove the edge entirely */
 ```
 
-If you embed the grid alongside `igniteui-webcomponents`, the brand tokens automatically re-tint from the igniteui palette (`--ig-primary-500`) — no configuration needed.
+If you embed the grid alongside `igniteui-webcomponents`, the brand tokens automatically re-tint from the igniteui palette (`--ig-primary-500`); no configuration needed.
 
 ### 4. Size the host
 
@@ -152,22 +159,22 @@ With the element registered and the host sized, you should see:
 - **Sort arrows** (↕) next to each header when `sort: true`.
 - A **filter row** below the headers with a "Filter" chip per column when `filter: true`.
 - **Hover state** on rows.
-- **Smooth scrolling** — DevTools shows only ~20 `<apex-grid-row>` elements at any time.
+- **Smooth scrolling**: DevTools shows only ~20 `<apex-grid-row>` elements at any time.
 
 ### Troubleshooting
 
 | What you see | Likely cause |
 |---|---|
-| Want a different look / brand color | Step 3 — override the `--ag-*` CSS variables |
-| Only ~3 rows visible regardless of data size | Step 4 — no bounded height, **or** consumer CSS sets `display` on `<apex-grid>` (check console for the warning) |
-| `<apex-grid>` blank tag in DOM | Step 2 — element not registered |
-| Columns shown as literal `[object Object]` | `columns=` used as an attribute — must be a **property** (`.columns=${...}` in Lit, `[columns]=` in Angular, `:columns.prop=` in Vue, `el.columns = ...` in vanilla JS) |
+| Want a different look / brand color | Step 3: override the `--ag-*` CSS variables |
+| Only ~3 rows visible regardless of data size | Step 4: no bounded height, **or** consumer CSS sets `display` on `<apex-grid>` (check console for the warning) |
+| `<apex-grid>` blank tag in DOM | Step 2: element not registered |
+| Columns shown as literal `[object Object]` | `columns=` used as an attribute; must be a **property** (`.columns=${...}` in Lit, `[columns]=` in Angular, `:columns.prop=` in Vue, `el.columns = ...` in vanilla JS) |
 
 ---
 
 ## Features in depth
 
-Each feature below is fully opt-in — you only pay for what you turn on. Snippets assume `const grid = document.querySelector('apex-grid')!`.
+Each feature below is fully opt-in: you only pay for what you turn on. Snippets assume `const grid = document.querySelector('apex-grid')!`.
 
 ### Sorting
 
@@ -184,6 +191,8 @@ grid.clearSort();                                          // or grid.clearSort(
 
 When `multiple` is enabled, a plain header click sorts by that column alone; hold Ctrl/Cmd and click to append additional columns as lower-priority sort keys. Events: `sorting` (cancellable), `sorted`.
 
+Columns show a column menu (the three-dot / kebab button) in the header. Out of the box it offers **Sort Ascending**, **Sort Descending**, and **Autosize Column** (on sortable or resizable columns). A feature module can supply the menu instead through the `ColumnMenuProvider` seam: `apex-grid-enterprise` fills it with pin, hide, group, and chart actions on every column, shared with the right-click context menu. The button is always visible; set `columnMenu` to `false` to hide it entirely (a module's menu stays reachable by right-click).
+
 ### Filtering
 
 ```ts
@@ -199,6 +208,8 @@ grid.clearFilter();
 
 Operand classes: `StringOperands`, `NumberOperands`, `BooleanOperands`. Events: `filtering` (cancellable), `filtered`.
 
+Filterable columns show a per-column filter button in the header that opens the filter panel; an active filter is highlighted (with a count badge when more than one condition is set).
+
 ### Quick filter (global search)
 
 ```ts
@@ -246,7 +257,7 @@ await grid.pinColumn('name', 'start');
 await grid.unpinColumn('name');                 // or pinColumn('name', null)
 ```
 
-The source `columns` array is **not** reordered — only the visual render order changes. Read `grid.displayColumns` for the render order. Events: `columnPinning` (cancellable), `columnPinned`.
+The source `columns` array is **not** reordered; only the visual render order changes. Read `grid.displayColumns` for the render order. Events: `columnPinning` (cancellable), `columnPinned`.
 
 ### Column reordering
 
@@ -262,6 +273,33 @@ await grid.moveColumn('email', 'name', 'after');
 
 Per-column opt-out: `{ key: 'id', reorderable: false }`. Reordering is constrained to the column's own pinning group (start / unpinned / end). Events: `columnMoving` (cancellable), `columnMoved`. Attribute: `column-reordering`.
 
+### Column separators
+
+A persistent vertical divider on each column header's trailing edge, on by default. On columns that opt into resizing (`{ key, resizable: true }`) the divider doubles as the resize handle: it takes the `col-resize` cursor and can be dragged.
+
+```ts
+grid.columnSeparator = false;                     // hide the dividers
+```
+
+Theme the line with `--ag-header-separator` (or the `--header-separator-color` / `--igx-header-separator-color` override hooks) and set its vertical inset with `--apex-header-separator-inset`. Because the default is `true`, disable it through the property rather than markup (a default-on boolean attribute cannot be turned off by attribute alone). Attribute: `column-separator`.
+
+### Column groups (spanning headers)
+
+```ts
+const columns = [
+  { key: 'first', group: 'name' },
+  { key: 'last',  group: 'name' },
+  { key: 'city',  group: 'address' },
+  { key: 'zip',   group: 'address' },
+];
+grid.columnGroups = [
+  { id: 'name',    headerText: 'Name' },
+  { id: 'address', headerText: 'Address' },
+];
+```
+
+A spanning header row renders above the column headers. `columns` stays flat, so width / pinning / resize / reorder are unaffected; membership is by reference (`column.group` points at a `columnGroups` entry). A group's members must be contiguous within one pin region (non-contiguous groups warn and skip the spanning cell); ungrouped columns get a blank spacer. Member reordering is confined to its group.
+
 ### Inline editing
 
 ```ts
@@ -279,6 +317,33 @@ grid.cancelEdit();
 
 `mode: 'row'` puts all editable cells in the row into edit together. Properties: `editingCell`, `editingRow`. Events: `cellValueChanging` (cancellable), `cellValueChanged`, plus `rowEditStarted` / `rowEditEnded` in row mode.
 
+### Cell validation
+
+```ts
+import { required, min, max, pattern, custom } from 'apex-grid';
+
+const columns = [
+  { key: 'name',  editable: true, validators: [required('Name is required')] },
+  { key: 'age',   editable: true, type: 'number', validators: [min(18), max(99)] },
+  { key: 'email', editable: true, validators: [pattern(/^[^@\s]+@[^@\s]+$/, 'Invalid email')] },
+];
+```
+
+Validators run inside the commit path, before the cancellable `cellValueChanging` gate. A failure keeps the editor open, marks the cell (`aria-invalid` + an error message node), and fires `cellValidationFailed { key, rowIndex, data, value, errors }`. Built-ins: `required`, `min`, `max`, `pattern`, `custom`, or any `(value, ctx) => string | null`. In row mode all pending cells are validated atomically (no partial write); enterprise paste / fill validate per cell.
+
+### Undo / redo
+
+```ts
+grid.editing = { enabled: true, mode: 'cell', history: { enabled: true } };
+
+grid.undo();          // or Ctrl/Cmd+Z
+grid.redo();          // or Ctrl/Cmd+Shift+Z / Ctrl+Y
+grid.clearHistory();
+grid.canUndo; grid.canRedo;
+```
+
+Opt in via `editing.history`. Every committed cell edit is recorded (single, row-mode, and enterprise paste / fill collapse to one step). Keyboard shortcuts work while the grid body has focus, so an open editor's native undo is untouched. The stack holds 100 commands by default (`history: { enabled: true, stackSize: 200 }`). Event: `historyChanged { canUndo, canRedo }`.
+
 ### Row selection
 
 ```ts
@@ -294,6 +359,29 @@ grid.selectedRows = [data[2]];      // replace selection (goes through `rowSelec
 
 Events: `rowSelecting` (cancellable), `rowSelected`.
 
+### Row pinning (top / bottom)
+
+```ts
+grid.rowPinning = { enabled: true };
+
+grid.pinRow(data[0], 'top');
+grid.pinRow(data[5], 'bottom');
+grid.unpinRow(data[0]);
+grid.pinnedRows;                    // { top: T[], bottom: T[] }
+```
+
+Pinned rows render in sticky top / bottom bands outside the virtualizer and are lifted out of the scrollable set (no duplication). Selection and styling work by row reference. Events: `rowPinning` (cancellable), `rowPinned`.
+
+### Row drag-reorder
+
+```ts
+grid.rowReordering = { enabled: true };   // add applyToData: true to splice grid.data in place
+
+grid.moveRow(0, 4, 'after');
+```
+
+By default (`rowReordering.handle`, boolean, default `true`) a six-dot grip handle shows at the start of every reorderable row, and dragging lifts a full-row floating ghost that follows the cursor. Both interaction modes are supported: **handle mode** (only the grip starts a drag, so the rest of the row stays free for selection and editing) and **whole-row mode** (set `handle: false` to drag from anywhere on the row, excluding interactive sub-parts like inputs and buttons). Or use the keyboard: focus a row, **Space** to grab, **Arrow** keys to move, **Space / Enter** to drop, **Esc** to cancel. The grid holds a manual order that is mutually exclusive with sorting (applying a sort clears it). By default the app persists the order via the `rowMoved` event; set `applyToData: true` to splice `grid.data` directly. Events: `rowMoving` (cancellable), `rowMoved { from, to, data }`.
+
 ### Row expansion (master-detail)
 
 ```ts
@@ -314,7 +402,7 @@ Events: `rowExpanding` (cancellable), `rowExpanded`.
 
 ### Tree data (nested rows)
 
-The data array stays **flat**. The grid derives the hierarchy from a `getDataPath(row)` callback that returns the path from root to that row — AG Grid's "tree data" pattern.
+The data array stays **flat**. The grid derives the hierarchy from a `getDataPath(row)` callback that returns the path from root to that row, the flat-array "tree data" pattern.
 
 ```ts
 type Person = { id: number; name: string; title: string; path: string[] };
@@ -328,7 +416,7 @@ const data: Person[] = [
 grid.tree = {
   enabled: true,
   getDataPath: (row) => row.path,
-  defaultExpanded: 1,              // boolean | number — depth to expand
+  defaultExpanded: 1,              // boolean | number, depth to expand
   groupColumnKey: 'name',          // which column shows the chevron + indent
   childIndent: 20,                 // px per depth level
 };
@@ -349,7 +437,7 @@ grid.exportToCSV({ filename: 'users', source: 'selected' });
 const text = grid.exportToCSV({ filename: '' });               // no download, returns the string
 ```
 
-`source` can be `'view'` (default — post-filter/post-sort), `'page'`, `'selected'`, or `'all'`. Per-column opt-out: `{ key: 'secret', exportable: false }`.
+`source` can be `'view'` (default, post-filter/post-sort), `'page'`, `'selected'`, or `'all'`. Per-column opt-out: `{ key: 'secret', exportable: false }`.
 
 > **XLSX (Excel) export** moved to [`apex-grid-enterprise`](https://www.npmjs.com/package/apex-grid-enterprise) in v3. `<apex-grid-enterprise>` adds `grid.exportToXLSX(...)` and an "Export XLSX" entry to this same toolbar menu. CSV stays free.
 
@@ -380,7 +468,7 @@ Search input has a `debounce` attribute (default `200`ms).
 
 ### Theming
 
-The grid styles itself through `--ag-*` CSS custom properties — override them on `apex-grid` (or any ancestor) to rebrand; see [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full list. When `igniteui-webcomponents` is present, the brand tokens auto-tint from its palette.
+The grid styles itself through `--ag-*` CSS custom properties; override them on `apex-grid` (or any ancestor) to rebrand; see [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full list. When `igniteui-webcomponents` is present, the brand tokens auto-tint from its palette.
 
 Style with CSS parts on the grid, paginator, and toolbar:
 
@@ -389,6 +477,42 @@ apex-grid::part(paginator) { background: var(--surface-2); }
 apex-grid-toolbar::part(search-input) { font-family: var(--font-mono); }
 ```
 
+### Spreadsheet coordinates
+
+```ts
+grid.coordinateHints = true;
+```
+
+```html
+<apex-grid coordinate-hints></apex-grid>
+```
+
+When `coordinateHints` is on, the grid shows a leading row-number gutter (1, 2, 3, and so on) and A / B / C column-letter chips in the headers, so cell references are discoverable (a spreadsheet-style look). Set it directly for a persistent spreadsheet look. `apex-grid-enterprise` turns it on by default for any grid that has an `allowFormula` column, so the gutter is reserved up front and entering a formula never shifts the layout. Reflected to the `coordinate-hints` attribute (default `false`).
+
+### State & persistence
+
+`getState()` returns a JSON-safe snapshot of the grid's restorable view and `setState()` applies one back. The snapshot covers column layout (order, width, pinning, visibility), sort, filter, quick filter, pagination, selection, expansion, tree expansion, pinned rows, the manual drag-reorder order, and any feature-module state (enterprise grouping / pivot / aggregation / ranges). Functions and templates are never serialized: sort comparers, filter condition functions, and cell/header/editor templates re-bind from the live `columns` config on restore (filter conditions are captured by operand name).
+
+```js
+// Save and restore a view.
+localStorage.setItem('view', JSON.stringify(grid.getState()));
+grid.setState(JSON.parse(localStorage.getItem('view')));
+
+// Persist automatically: stateChanged fires (debounced) after every settled
+// change, and only while something is listening.
+grid.addEventListener('stateChanged', (e) =>
+  localStorage.setItem('view', JSON.stringify(e.detail.state))
+);
+```
+
+**Row identity.** Selection, expansion, pinned rows, and the manual order are captured as row references. Set `grid.rowId = (row) => row.id` for durable references that survive a data reload; without it, rows are referenced by position (index), which round-trips within a session but not across a reload.
+
+**`setState` is defensive.** It is meant to accept persisted-and-possibly-stale blobs and AI output, so it never throws on bad input (unless you pass `{ strict: true }`): unknown columns / operands are dropped, out-of-range pages clamped, unresolvable rows skipped, and a wrong snapshot `version` applied best-effort. It returns a `SetStateResult` (`{ applied, skipped, warnings }`) so you can see exactly what happened. `setState` is partial: pass only the slices you want to change.
+
+**`getSchema()`** returns a machine-readable description of the grid (columns + data types, available sort directions and filter operands per column, grid-level capabilities) with the current state embedded. It is the contract an AI layer feeds an LLM and validates a patch against, but it equally drives a view-editor UI or documentation.
+
+See [`demo/state-persistence.html`](../../demo/state-persistence.html) for a save / restore / live-snapshot example.
+
 ---
 
 ## API Reference
@@ -401,26 +525,34 @@ apex-grid-toolbar::part(search-input) { font-family: var(--font-mono); }
 | `columns` | `ColumnConfiguration<T>[]` | `[]` | Column configuration (property only) |
 | `autoGenerate` | `boolean` | `false` | Infer columns from `data[0]` keys. Attr `auto-generate` |
 | `sortConfiguration` | `GridSortConfiguration` | `{ multiple, triState }` | |
-| `dataPipelineConfiguration` | `DataPipelineConfiguration<T>` | — | Custom sort/filter/pagination hooks |
-| `pagination` | `PaginationConfiguration` | — | |
+| `dataPipelineConfiguration` | `DataPipelineConfiguration<T>` |  | Custom sort/filter/pagination hooks |
+| `pagination` | `PaginationConfiguration` |  | |
 | `quickFilter` | `string` | `''` | Attr `quick-filter` |
 | `showQuickFilter` | `boolean` | `false` | Attr `show-quick-filter` |
 | `showExport` | `boolean` | `false` | Attr `show-export` |
 | `columnReordering` | `boolean` | `false` | Attr `column-reordering` |
-| `editing` | `GridEditingConfiguration` | — | |
-| `selection` | `GridSelectionConfiguration` | — | |
-| `expansion` | `GridExpansionConfiguration<T>` | — | |
-| `tree` | `GridTreeConfiguration<T>` | — | |
-| `sortExpressions` | `SortExpression<T>[]` | — | Get/set |
-| `filterExpressions` | `FilterExpression<T>[]` | — | Get/set |
-| `selectedRows` | `T[]` | — | Get/set |
-| `expandedRows` | `T[]` | — | Get/set |
-| `page`, `pageSize`, `pageCount`, `totalItems` | `number` | — | |
-| `pageItems` | `readonly T[]` | — | Currently rendered slice |
-| `dataView` | `readonly T[]` | — | Post-filter, post-sort |
-| `displayColumns` | `readonly ColumnConfiguration<T>[]` | — | Render order (pinned start → unpinned → pinned end) |
-| `editingCell` | `{ rowIndex, columnKey } \| null` | — | |
-| `editingRow` | `number \| null` | — | Row-mode only |
+| `columnGroups` | `ColumnGroupConfiguration[]` |  | Spanning header groups (`column.group` references an `id`) |
+| `editing` | `GridEditingConfiguration` |  | Includes `history` for undo/redo; per-column `validators` |
+| `selection` | `GridSelectionConfiguration` |  | |
+| `expansion` | `GridExpansionConfiguration<T>` |  | |
+| `tree` | `GridTreeConfiguration<T>` |  | |
+| `rowPinning` | `GridRowPinningConfiguration` |  | `{ enabled }` |
+| `rowReordering` | `GridRowReorderingConfiguration` |  | `{ enabled, applyToData?, handle? }` (`handle` default `true`: grip-only drag) |
+| `coordinateHints` | `boolean` | `false` | Show a row-number gutter + A / B / C header chips (spreadsheet look). Attr `coordinate-hints` |
+| `columnMenu` | `boolean` | `true` | Show the always-visible column-menu (kebab) button on headers; `false` hides it |
+| `rowId` | `(row: T) => string \| number` |  | Durable row identity for `getState` / `setState` |
+| `localeText` | `GridLocaleText` |  | Override map for built-in strings (e.g. `esLocale`) |
+| `canUndo`, `canRedo` | `boolean` |  | Get (history) |
+| `sortExpressions` | `SortExpression<T>[]` |  | Get/set |
+| `filterExpressions` | `FilterExpression<T>[]` |  | Get/set |
+| `selectedRows` | `T[]` |  | Get/set |
+| `expandedRows` | `T[]` |  | Get/set |
+| `page`, `pageSize`, `pageCount`, `totalItems` | `number` |  | |
+| `pageItems` | `readonly T[]` |  | Currently rendered slice |
+| `dataView` | `readonly T[]` |  | Post-filter, post-sort |
+| `displayColumns` | `readonly ColumnConfiguration<T>[]` |  | Render order (pinned start → unpinned → pinned end) |
+| `editingCell` | `{ rowIndex, columnKey } \| null` |  | |
+| `editingRow` | `number \| null` |  | Row-mode only |
 
 ### Methods
 
@@ -455,8 +587,19 @@ expandAllRows(); collapseAllRows(); isRowExpanded(row)
 toggleTreeRow(row); expandTreeRow(row); collapseTreeRow(row)
 expandAllTreeRows(); collapseAllTreeRows(); isTreeRowExpanded(row)
 
+pinRow(row, 'top' | 'bottom'); unpinRow(row)   // pinnedRows getter
+moveRow(from, to, 'before' | 'after')
+
+undo(); redo(); clearHistory()                 // canUndo / canRedo getters
+
+localize(key, params?, fallback?): string      // resolve a locale string
+
 exportToCSV(options?): string
 exportAs(formatId, options?): void   // toolbar dispatch; 'csv' (community), 'xlsx' (enterprise)
+
+getState(options?): GridState
+setState(state, options?): SetStateResult   // partial + defensive; never throws unless { strict: true }
+getSchema(): GridSchema                      // machine-readable capability descriptor
 ```
 
 ### Events
@@ -472,16 +615,21 @@ All events bubble and are composed across shadow boundaries. Names ending in `-i
 | `columnPinning` / `columnPinned` | yes / no | `{ key, previous, next }` / `{ key, pinned }` |
 | `columnMoving` / `columnMoved` | yes / no | `{ key, fromIndex, toKey, position }` / `{ key, fromIndex, toIndex }` |
 | `cellValueChanging` / `cellValueChanged` | yes / no | `{ row, column, value, newValue }` |
+| `cellValidationFailed` | no | `{ key, rowIndex, data, value, errors }` |
 | `rowEditStarted` / `rowEditEnded` | no / no | row context |
+| `historyChanged` | no | `{ canUndo, canRedo }` |
 | `rowSelecting` / `rowSelected` | yes / no | `{ added, removed }` |
+| `rowPinning` / `rowPinned` | yes / no | `{ row, position }` |
+| `rowMoving` / `rowMoved` | yes / no | `{ from, to, data }` |
 | `rowExpanding` / `rowExpanded` | yes / no | row context |
 | `treeRowExpanding` / `treeRowExpanded` | yes / no | row context |
+| `stateChanged` | no | `{ state }` (debounced; only while listened) |
 
-Programmatic `sort()` / `filter()` calls are silent — only UI-initiated changes emit `sorting` / `filtering`.
+Programmatic `sort()` / `filter()` calls are silent; only UI-initiated changes emit `sorting` / `filtering`.
 
 ### Attributes
 
-`auto-generate`, `quick-filter`, `show-quick-filter`, `show-export`, `column-reordering`.
+`auto-generate`, `quick-filter`, `show-quick-filter`, `show-export`, `column-reordering`, `coordinate-hints`.
 
 ### CSS parts
 
@@ -523,11 +671,11 @@ npm run build         # builds dist/ + custom-elements.json + typedoc
 
 Releases are automated by [.github/workflows/publish.yml](.github/workflows/publish.yml):
 
-1. Bump `"version"` in [package.json](package.json) — the single source of truth. The build injects it into `dist/package.json`.
+1. Bump `"version"` in [package.json](package.json), the single source of truth. The build injects it into `dist/package.json`.
 2. Commit with a message starting with `release:` and the same version, e.g. `release: 2.0.0` or `release: 2.0.0-rc.1`.
 3. Push to `main`.
 
-The workflow then verifies the version triple-match, runs lint + tests + build, publishes `dist/` to npm with `--provenance` (OIDC trusted publishing — no token in secrets), and creates a `vX.Y.Z` git tag and GitHub Release with auto-generated notes. Pre-release versions (containing `-`) publish under the `next` dist-tag; stable versions under `latest`.
+The workflow then verifies the version triple-match, runs lint + tests + build, publishes `dist/` to npm with `--provenance` (OIDC trusted publishing, no token in secrets), and creates a `vX.Y.Z` git tag and GitHub Release with auto-generated notes. Pre-release versions (containing `-`) publish under the `next` dist-tag; stable versions under `latest`.
 
 Any push whose head commit does not start with `release:` is a no-op for the workflow.
 

package/components/cell.d.ts

@@ -53,9 +53,22 @@ export default class ApexGridCell<T extends object> extends LitElement {
      * `0` for the community grid, so cells are never re-decorated there.
      */
     decorationVersion: number;
+    /**
+     * Reactive token forwarded from {@link EditingController.validationVersion}.
+     * Changing it re-runs {@link willUpdate} so the cell re-reads its validation
+     * errors and toggles `aria-invalid` / the inline error node. Stays `0` until
+     * the first validation failure.
+     */
+    validationVersion: number;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(): void;
+    /**
+     * The inline error node surfaced when the cell is invalid. `role="alert"`
+     * announces the message when it appears, covering the cross-shadow gap where
+     * an `aria-errormessage` IDREF on the host can't reach this node.
+     */
+    protected renderError(): import("lit-html").TemplateResult<1> | null;
     protected updated(): void;
     protected renderDefaultEditor(): import("lit-html").TemplateResult<1>;
     protected renderEditor(): unknown;
@@ -72,7 +85,7 @@ export default class ApexGridCell<T extends object> extends LitElement {
      */
     protected resolveDisplayValue(): unknown;
     protected renderCellBody(): unknown;
-    protected render(): unknown;
+    protected render(): import("lit-html").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {