apex-grid 3.5.0 → 4.0.0-beta.1

package/LICENSE.md

@@ -0,0 +1,125 @@
+## 📄 License Options for ApexGrid
+
+ApexGrid is offered under a **dual-license model** to support individuals, startups, and commercial products of all sizes.
+
+One license key works across every Apex product, so a customer of one does not buy a second for another.
+
+---
+
+### 🔓 Community License (Free)
+
+For individuals, non-profits, educators, and small businesses whose **annual revenue, operating budget, funding, or equivalent financial resources are less than $2 million USD**.
+
+✅ What's allowed:
+
+- Personal, educational, or non-profit use
+- Commercial use by small orgs (under $2M in annual revenue, budget or funding)
+- Modifications, and redistribution of the library itself (with attribution)
+
+🚫 Not allowed:
+
+- Use by companies or entities at or above $2M in annual revenue, budget or funding
+- Use in competing data grid or charting products
+- Sublicensing under different terms
+- Embedding in a product or platform used by other people, which needs the OEM License below whatever your size
+
+➡ By using ApexGrid under this license, you confirm that **you qualify as a Small Organization**.
+
+---
+
+### 💼 Commercial License (Paid)
+
+The Commercial License applies to all paid SKUs (Pro, Premium and OEM).
+
+The **Community License** is available at no cost **only** to organizations whose **annual revenue, operating budget, funding, or equivalent financial resources are under $2M USD**.
+If you, your parent company, affiliates, or any entity under common control reach $2M USD or more on any of those measures, you must purchase one of our paid licenses.
+
+Pro and Premium are priced per developer, and priced on the features you use rather than on your size.
+
+✅ What's included:
+
+- Use in internal tools and commercial applications
+- Modifications and app-level distribution
+- 12-month subscription with updates & support
+
+🚫 Not allowed:
+
+- Redistribution in toolkits, SDKs, or platforms
+- Use by unlicensed developers
+- Competing data grid or charting products
+
+---
+
+### 🎚 What each plan includes for ApexGrid
+
+- **Free, at Community and above:** ApexGrid itself.
+- **Premium and above:** the ApexGrid Enterprise add-on, a separate package (`apex-grid-enterprise`) covering Row Grouping, Aggregations, Pivoting, the Server-Side Row Model, Advanced Filter Builder, Range Selection, Integrated Charts, Formula Engine, AI Toolkit and Companion Elements.
+
+For the full comparison see [https://apexcharts.com/pricing](https://apexcharts.com/pricing).
+
+---
+
+### 🏛 Non-Profit Tiers
+
+Non-Profits are treated like commercial entities:
+
+- Annual operating budget **less than $2 million USD**
+- _Eligible for Community licenses_
+
+or
+
+- Annual operating budget **greater than $2 million USD**
+- _Commercial license with possible discounts for Community, Pro, Premium and OEM products_
+
+---
+
+### 🔄 OEM / Redistribution License (Paid)
+
+Required if you are **embedding ApexGrid into a product or platform used by other people**, such as:
+
+- No-code dashboards
+- Developer platforms
+- Embedded BI tools
+- SDKs
+
+✅ What's included:
+
+- Redistribution rights for **one application or product**
+- **Unlimited developer seats** on that application, with no separate per-developer license to buy
+- **Every licensed feature**, at the highest tier
+- 12-month subscription with updates & support
+
+Your end users need no license of their own. A second application needs a second OEM license. White-label, resale, and affiliate arrangements are quoted separately.
+
+✅ OEM **not required** if your app simply renders static grids and users **cannot** configure or interact with them.
+
+---
+
+### ⏳ When a subscription ends
+
+Your license key expires, and **licensed features render with a trial watermark**. You no longer receive updates, new features, or technical support. Work built only from free features is unaffected, and your existing deployment keeps running.
+
+For OEM licenses, continued redistribution requires an active subscription.
+
+---
+
+### ⚠️ License Acceptance
+
+By installing ApexGrid (e.g., via `npm install apex-grid`), you are agreeing to the applicable license based on your usage:
+
+- Community License (if under $2M in annual revenue, budget or funding)
+- Commercial License (if at or above $2M in annual revenue, budget or funding)
+- OEM License (if redistributing to third-party users)
+
+---
+
+### 🛠 Need a License or Have Questions?
+
+📧 Contact us at [sales@apexcharts.com](mailto:sales@apexcharts.com)
+📚 Read full license agreements here: [https://apexcharts.com/license](https://apexcharts.com/license)
+
+---
+
+Copyright © 2026 ApexCharts. All rights reserved.
+
+Thank you for supporting ApexGrid! Your licensing keeps the Community License available to individuals and small teams.

package/README.md

@@ -45,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`), also inside any shadow root a grid connects in. The grid is styled out-of-the-box; no theme CSS import is required.
 
 ### Render the grid
 
@@ -111,7 +111,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 on any ancestor: `:root`, a dashboard panel, or the shadow host of a web component the grid renders in (custom properties inherit through shadow boundaries, however deep). A one-line brand override cascades to every tint:
 
 ```css
 apex-grid {
@@ -122,16 +122,40 @@ 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).
+See [`src/styles/_token-values.scss`](src/styles/_token-values.scss) for the full token list and defaults (surfaces, text, semantic state colors, typography, spacing, motion).
+
+**Where the defaults live.** The first grid to connect adopts the token defaults into its document, on `:where(:root)`, through `adoptedStyleSheets` (no `<style>` element, so no CSP nonce). Zero specificity means any value you set wins, and `var(--ag-*)` reads in your own CSS resolve to the defaults. If you manage your own CSS, opt out with `setup({ tokenStyles: false })` and import the same defaults as a file (also the way to get them into server-rendered HTML):
+
+```ts
+import 'apex-grid/tokens.css';
+```
+
+The grid renders the same without the sheet; it carries the defaults as fallbacks. Three groups have no root default, so page CSS reading them needs its own fallback:
+
+- `--ag-brand` and `--ag-brand-strong`, so an Ignite UI palette set on any ancestor keeps tinting the grid (see below).
+- The derived washes `--ag-brand-soft`, `--ag-brand-softer`, `--ag-brand-line`, `--ag-row-hover` and `--ag-surface-alt`. The grid mixes them from the brand and surface in effect, so they follow a brand set on an ancestor. Set them only to override the mix.
+
+**Dark mode.** `theme="dark"` reads its own colour inputs, `--ag-dark-*` (`--ag-dark-surface`, `--ag-dark-text`, `--ag-dark-hairline`, `--ag-dark-shadow-card`, and so on), so a light palette set on a shared ancestor never puts a white surface under the dark theme's light text. Sizing, typography, motion, the brand and the base state colours are shared by both modes. To theme both from one place, set both palettes:
+
+```css
+.dashboard {
+  --ag-brand: #7c3aed;
+  --ag-surface: #fdfcff;
+  --ag-dark-surface: #140f24;
+}
+```
+
+`theme="tinted"` mixes a little brand into the surface, gridline and muted-text values in effect, including any you set. Its row separators are the brand alone, so a tinted grid ignores `--ag-border` and `--ag-dark-border`.
 
 **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 */
+apex-grid { --ag-grid-shadow: var(--ag-shadow-card); }                     /* elevated floating-card look */
+apex-grid[theme~='dark'] { --ag-grid-shadow: var(--ag-dark-shadow-card); } /* the same, for dark grids */
+apex-grid { --ag-grid-shadow: none; }                                      /* remove the edge entirely */
 ```
 
-If you embed the grid in an Ignite UI app, the brand tokens automatically re-tint from its palette: they read `--ig-primary-500` with the grid's own default as the fallback. That is a plain CSS variable lookup, so the grid neither depends on nor bundles Ignite UI.
+If you embed the grid in an Ignite UI app, the brand tokens automatically re-tint from its palette, wherever it is declared: they read `--ig-primary-500` with the grid's own default as the fallback. That is a plain CSS variable lookup, so the grid neither depends on nor bundles Ignite UI.
 
 ### 4. Size the host
 
@@ -168,6 +192,9 @@ With the element registered and the host sized, you should see:
 | `<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) |
 
+> [!NOTE]
+> Rows whose text wraps change height while the grid resizes or scrolls, and the browser can defer the resulting row layout by one frame. It reports each deferral as a window `error` event with the message "ResizeObserver loop completed with undelivered notifications" (older browsers say "ResizeObserver loop limit exceeded"). The event is benign, so the first grid to connect adds one window `error` listener that cancels any message containing "ResizeObserver loop" (Safari then stops logging it) and stops the listeners added after it from seeing it. Every other error passes through untouched. Listeners added before the first grid connects, such as error monitoring set up at page start, still receive it, and the same message raised by your own code is quieted as well, since the browser does not say which observer raised it.
+
 ---
 
 ## Features in depth
@@ -231,7 +258,20 @@ await grid.setPageSize(50);
 grid.nextPage(); grid.previousPage(); grid.firstPage(); grid.lastPage();
 ```
 
-Remote mode:
+The paginator never clips its controls: on a narrow grid it drops the page size select first, then the first and last buttons, so previous and next stay reachable. `paginator: 'compact'` always uses that narrow layout ("start-end of total", previous, "page / count", next), for example in a small dashboard tile:
+
+```ts
+grid.pagination = { enabled: true, pageSize: 5, paginator: 'compact' };
+```
+
+Style it through the grid with `apex-grid::part(...)`: `paginator-host` (the element), `paginator`, `paginator-size`, `paginator-info`, `paginator-controls`, `paginator-page`, and `paginator-button` on each button, which also carries `paginator-first`, `paginator-prev`, `paginator-next` or `paginator-last`:
+
+```css
+apex-grid::part(paginator-first),
+apex-grid::part(paginator-last) { display: none; }
+```
+
+Remote mode: the grid does not slice `data`, it renders whatever `data` holds as the current page. Fetch the page on `pageChanged`, and keep `pagination.totalItems` at the number of rows the server holds for the current filter (update it when a server side filter changes that number), so the paginator can count the pages:
 
 ```ts
 grid.pagination = { enabled: true, mode: 'remote', pageSize: 25, totalItems: 1280 };
@@ -240,7 +280,7 @@ grid.addEventListener('pageChanged', async (e) => {
 });
 ```
 
-Properties: `page`, `pageSize`, `pageCount`, `totalItems`, `pageItems`. Events: `pageChanging` (cancellable), `pageChanged`.
+Properties: `page`, `pageSize`, `pageCount`, `totalItems`, `pageItems`. `totalItems` is the post-filter, post-sort row count; with pagination enabled it counts the rows paged through, without pinned rows, which show on every page (in remote mode, the `pagination.totalItems` you supplied), and `pageChanged` carries the same number in `detail.totalItems`. Events: `pageChanging` (cancellable), `pageChanged`.
 
 ### Column pinning
 
@@ -281,6 +321,16 @@ grid.columnSeparator = false;                     // hide the dividers
 
 Theme the line with `--ag-header-separator` (or the `--header-separator-color` override hook) 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`.
 
+### Hiding the header
+
+For a compact table, such as a short dashboard tile, leave out the header rows and give their room to the data rows:
+
+```ts
+grid.showHeader = false;                          // or <apex-grid show-header="false">
+```
+
+The column header row, the column group row and the filter panel take no space, paint nothing and take no pointer, and the built-in header controls leave the tab order, so resizing, the column menu and drag reorder are unavailable while the header is hidden (an open column menu closes). A focusable control you render in a `headerTemplate` stays in the tab order: give it `tabindex="-1"` while the header is hidden. The column header row stays in the accessibility tree, so screen readers still announce the column names, and `aria-rowcount` and `aria-rowindex` do not change. Sort, filter, column widths and the current page are kept and come back unchanged with `grid.showHeader = true`. Attribute: `show-header`.
+
 ### Column groups (spanning headers)
 
 ```ts
@@ -334,6 +384,14 @@ re-renders. The returned tally splits `applied` from `unchanged`, `invalid`,
 one. Edits naming a row out of range or a column the user could not edit either
 are skipped rather than throwing.
 
+`rowIndex` is view-relative, so it reaches the current page only. To edit rows
+anywhere (other pages, pinned rows, rows under a collapsed tree parent), name
+the record itself with `row`:
+
+```ts
+grid.applyEdits(grid.selectedRows.map((row) => ({ row, column: 'discount', value: 0 })));
+```
+
 ### Keyboard navigation and accessibility
 
 The grid body is a single tab stop: Tab enters the grid, and the active cell
@@ -356,9 +414,21 @@ A keyboard-driven commit or cancel returns focus to the cell, so navigation
 continues from where you were. Sorting, filtering, selection, paging, row
 pinning, reorder, expansion, and undo / redo are announced through a polite
 live region, and every announcement and control label is localizable (the
-`announce.*` and `header.*` locale keys). The host gets a localized
-`aria-label` ("Data grid") unless you provide `aria-label` /
-`aria-labelledby` yourself.
+`announce.*` and `header.*` locale keys).
+
+The `grid` role (`treegrid` for tree data, master-detail and other expandable
+rows), `aria-rowcount`, `aria-colcount` and `aria-multiselectable` sit on the
+element exposed as `part="table"` inside the shadow root, not on the
+`<apex-grid>` host. It holds only the header rows and the body, so the toolbar,
+paginator and live region around it are not read as table content. It gets a
+localized `aria-label` ("Data grid") unless you put `aria-label` or
+`aria-labelledby` on the host, which then names it. An `aria-describedby` on
+the host becomes its description. The references are resolved when the grid
+renders, so if you add the referenced element later (a heading shown
+conditionally), set the attribute again afterwards to pick it up.
+
+> Changed in 4.0.0: the role and the row and column counts used to be on the
+> host. Query `grid.shadowRoot.querySelector('[part~="table"]')` instead.
 
 > Changed in 3.4.0: Home / End used to jump to the first / last row; they now
 > stay within the row. Use Ctrl/Cmd+Home / Ctrl/Cmd+End for the grid corners.
@@ -403,6 +473,8 @@ grid.selectedRows;                  // snapshot
 grid.selectedRows = [data[2]];      // replace selection (goes through `rowSelecting`)
 ```
 
+Every row is selectable by default, pinned rows included. `selection.isRowSelectable: (row) => boolean` keeps rows out of the selection (a pinned total row, for example): such a row renders no checkbox and no `aria-selected`, every selection path skips it (clicks, Space, Select all, `selectRow`, `selectedRows = ...`, `setState`), and the header checkbox counts only selectable rows. Reassigning `selection` or `data` drops selected rows the predicate now rejects; a selected row it comes to reject otherwise (pinned or edited in place) keeps its checkbox until deselected.
+
 Events: `rowSelecting` (cancellable), `rowSelected`.
 
 ### Row pinning (top / bottom)
@@ -416,7 +488,7 @@ 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`.
+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. Replacing `grid.data` carries the pins onto the new rows (by `rowId` when set, else a pin whose row left the data is dropped). While `rowPinning.enabled` is false the pinned rows return to the body and `pinnedRows` reports none, but the pins are kept (`getState` still saves them) and re-enabling brings them back. Events: `rowPinning` (cancellable), `rowPinned`.
 
 ### Row drag-reorder
 
@@ -426,7 +498,7 @@ grid.rowReordering = { enabled: true };   // add applyToData: true to splice gri
 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 }`.
+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, and a move clears the sort). Rows hidden by a filter keep their place when a visible row moves, and the order follows `grid.data` when it is replaced (by `rowId` when set). 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, position, toIndex, data }`, where `toIndex` is the view index the row lands at.
 
 ### Row expansion (master-detail)
 
@@ -471,7 +543,7 @@ await grid.toggleTreeRow(data[0]);
 await grid.expandAllTreeRows();
 ```
 
-Methods: `toggleTreeRow`, `expandTreeRow`, `collapseTreeRow`, `expandAllTreeRows`, `collapseAllTreeRows`, `isTreeRowExpanded`. Events: `treeRowExpanding` (cancellable), `treeRowExpanded`. When tree mode is active, the host element advertises `role="treegrid"`.
+Methods: `toggleTreeRow`, `expandTreeRow`, `collapseTreeRow`, `expandAllTreeRows`, `collapseAllTreeRows`, `isTreeRowExpanded`. Events: `treeRowExpanding` (cancellable), `treeRowExpanded`. When tree mode is active, the grid's `part="table"` element advertises `role="treegrid"`.
 
 ### CSV export
 
@@ -497,16 +569,19 @@ Renders a download icon in the toolbar's trailing actions area; the menu has an
 
 ### Toolbar
 
-Rendered automatically above the header row when at least one of `show-quick-filter` or `show-export` is on. CSS parts:
+Rendered automatically above the header row when at least one of `show-quick-filter` or `show-export` is on. The grid re-exports its CSS parts, so `apex-grid::part(name)` reaches them:
 
 | Part | What |
 |---|---|
+| `toolbar-host` | The `<apex-grid-toolbar>` element |
 | `toolbar` | Root container |
 | `toolbar-search` | Quick-filter input wrapper |
 | `search-field` | The bordered input field |
 | `search-icon`, `search-input` | Leading icon, input element |
 | `toolbar-actions` | Trailing actions area |
-| `export-trigger` | Export menu button |
+| `toolbar-action` | A host-contributed action button |
+| `export` | Export menu wrapper |
+| `export-trigger`, `export-icon`, `export-caret` | Export menu button and its icons |
 | `export-menu` | Dropdown panel |
 | `export-menu-item` | Menu item |
 
@@ -514,13 +589,35 @@ 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. Where an Ignite UI palette is present, the brand tokens auto-tint from `--ig-primary-500`.
+The grid styles itself through `--ag-*` CSS custom properties; override them on `apex-grid` or any ancestor (shadow hosts included) to rebrand, and use `--ag-dark-*` for dark grids. See [Customize the look](#3-optional-customize-the-look) and [`src/styles/_token-values.scss`](src/styles/_token-values.scss) for the full list. Where an Ignite UI palette is present, the brand tokens auto-tint from `--ig-primary-500`.
 
 Style with CSS parts on the grid, paginator, and toolbar:
 
 ```css
 apex-grid::part(paginator) { background: var(--surface-2); }
-apex-grid-toolbar::part(search-input) { font-family: var(--font-mono); }
+apex-grid::part(search-input) { font-family: var(--font-mono); }
+```
+
+Body rows re-export these parts, so `apex-grid::part(name)` reaches them:
+
+| Part | What |
+|---|---|
+| `cell` | A data cell |
+| `selection-cell`, `selection-checkbox` | Selection column cell and its checkbox |
+| `expansion-cell`, `expansion-toggle`, `expansion-chevron` | Expansion column cell, its button and the chevron icon |
+| `detail-panel` | Expanded detail panel container |
+| `row-number-cell`, `row-number` | Row-number gutter cell and its label (`coordinateHints`) |
+| `reorder-handle-cell`, `reorder-handle`, `reorder-grip` | Row-reorder grip cell, handle and icon (handle mode) |
+| `group-row` | Default container of a row a feature module renders full width |
+
+Parts used inside your own `detailTemplate` content are re-exported when you list them in `expansion.exportParts`:
+
+```js
+grid.expansion = {
+  enabled: true,
+  exportParts: ['order-summary'],
+  detailTemplate: ({ data }) => html`<div part="order-summary">${data.total}</div>`,
+};
 ```
 
 ### Right-to-left
@@ -557,6 +654,27 @@ grid.coordinateHints = true;
 
 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`).
 
+### Row recycling
+
+```ts
+grid.rowRecycling = false; // opt out
+```
+
+```html
+<apex-grid row-recycling="false"></apex-grid>
+```
+
+On by default. A scroll, sort or filter re-binds the rendered body rows to the records now in view instead of building new rows, which makes long jumps and sorts cheaper on large grids. A row element, and its cells, then shows another record later, so cell and editor templates follow these rules:
+
+- Derive everything a template renders from its context on each render, and keep no state in the elements it creates.
+- Read `ctx.data` for the record, also after an `await`. `ctx.row` and `ctx.parent` are row and cell elements that may show another record by then, so do not hold them across an `await`.
+- Wrap a template that has to keep element state in `keyed(ctx.data, ...)` from `lit/directives/keyed.js`. The state then never shows on the wrong record, but it is rebuilt every time the row shows another record, including after a sort or `moveRow`.
+- Code that holds `grid.rows` elements across a scroll or a sort should read each element's `data` again rather than assume it still shows the same record.
+
+Set `rowRecycling` to `false` (or the `row-recycling="false"` attribute) to restore record-keyed rows, where each row element stays with its record. Do that for templates that must keep element state across a sort or a move, such as some third-party widgets.
+
+Detail templates are different: their content follows its record into whichever row shows it, and keeps its DOM state (typed text, a nested grid's sort) across a scroll within the rendered rows, a sort or a `moveRow`, so it needs neither `keyed()` nor the opt-out. It is rebuilt when the record leaves the rendered rows or is collapsed, as before. `ctx.parent` in a detail context is the grid itself. A grid created inside a `detailTemplate` has its own `rowRecycling` setting, so set it there too when you opt out.
+
 ### 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).
@@ -593,7 +711,7 @@ See [`demo/state-persistence.html`](../../demo/state-persistence.html) for a sav
 | `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 |
+| `dataPipelineConfiguration` | `DataPipelineConfiguration<T>` |  | Custom sort, filter and quick filter hooks |
 | `pagination` | `PaginationConfiguration` |  | |
 | `quickFilter` | `string` | `''` | Attr `quick-filter` |
 | `showQuickFilter` | `boolean` | `false` | Attr `show-quick-filter` |
@@ -608,6 +726,8 @@ See [`demo/state-persistence.html`](../../demo/state-persistence.html) for a sav
 | `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 |
+| `showHeader` | `boolean` | `true` | `false` hides the header rows (kept for screen readers). Attr `show-header="false"` |
+| `rowRecycling` | `boolean` | `true` | Re-binds body row elements across records on scroll, sort and filter; `false` restores record-keyed rows. See [Row recycling](#row-recycling). Attr `row-recycling="false"` |
 | `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) |
@@ -688,7 +808,7 @@ All events bubble and are composed across shadow boundaries. Names ending in `-i
 | `historyChanged` | no | `{ canUndo, canRedo }` |
 | `rowSelecting` / `rowSelected` | yes / no | `{ added, removed }` |
 | `rowPinning` / `rowPinned` | yes / no | `{ row, position }` |
-| `rowMoving` / `rowMoved` | yes / no | `{ from, to, data }` |
+| `rowMoving` / `rowMoved` | yes / no | `{ from, to, position, toIndex, data }` |
 | `rowExpanding` / `rowExpanded` | yes / no | row context |
 | `treeRowExpanding` / `treeRowExpanded` | yes / no | row context |
 | `stateChanged` | no | `{ state }` (debounced; only while listened) |
@@ -697,14 +817,14 @@ Programmatic `sort()` / `filter()` calls are silent; only UI-initiated changes e
 
 ### Attributes
 
-`auto-generate`, `quick-filter`, `show-quick-filter`, `show-export`, `column-reordering`, `coordinate-hints`.
+`auto-generate`, `quick-filter`, `show-quick-filter`, `show-export`, `column-reordering`, `coordinate-hints`, `show-header`, `row-recycling`.
 
 ### CSS parts
 
 | Component | Parts |
 |---|---|
-| `<apex-grid-toolbar>` | `toolbar`, `toolbar-search`, `search-field`, `search-icon`, `search-input`, `toolbar-actions`, `export-trigger`, `export-menu`, `export-menu-item` |
-| `<apex-grid-paginator>` | `paginator`, `paginator-size`, `paginator-info`, `paginator-controls`, `paginator-page` |
+| `<apex-grid-toolbar>` | `toolbar`, `toolbar-search`, `search-field`, `search-icon`, `search-input`, `toolbar-actions`, `toolbar-action`, `export`, `export-trigger`, `export-icon`, `export-caret`, `export-menu`, `export-menu-item` (re-exported by the grid, which names the element `toolbar-host`) |
+| `<apex-grid-paginator>` | `paginator`, `paginator-size`, `paginator-info`, `paginator-controls`, `paginator-page`, `paginator-button`, `paginator-first`, `paginator-prev`, `paginator-next`, `paginator-last` (re-exported by the grid, which names the element `paginator-host`) |
 | `<apex-grid-cell>` | `cell`, `editor` |
 
 ---

package/components/cell.d.ts

@@ -17,6 +17,16 @@ export default class ApexGridCell<T extends object> extends LitElement {
      * The value which will be rendered by the component.
      */
     value: PropertyType<T>;
+    /**
+     * The record (row data object) the cell shows, set by the row next to
+     * {@link value}. A row element can be re-bound to another record without
+     * being rebuilt (a pinned band does when a row above it is unpinned), and
+     * `value` alone cannot tell: two records may hold the same value. A change
+     * here is a full update that drops every per-record state of the cell.
+     *
+     * @internal
+     */
+    record: T;
     /**
      * A reference to the column configuration object.
      */
@@ -46,13 +56,30 @@ export default class ApexGridCell<T extends object> extends LitElement {
      * auto-rendered selection + expansion columns ahead of the data columns.
      */
     colindex: number;
+    /**
+     * The parent row's view index, set by the row. Changing it re-decorates the
+     * cell (decoration such as a range selection is positional), so a row that
+     * moves with the same data (sort, filter, an expand above it) never keeps a
+     * stale highlight.
+     *
+     * @internal
+     */
+    rowIndex: number;
     /**
      * Reactive token forwarded from {@link StateController.decorationVersion}.
-     * Changing it re-runs {@link willUpdate} so module-driven cell decoration is
-     * re-evaluated when it changes (e.g. while dragging a selection range). Stays
-     * `0` for the community grid, so cells are never re-decorated there.
+     * Changing it re-applies module-driven cell decoration (e.g. while dragging a
+     * selection range) without re-rendering the cell content. Stays `0` for the
+     * community grid, so cells are never re-decorated there.
      */
     decorationVersion: number;
+    /**
+     * Reactive token forwarded from {@link StateController.dataVersion}, bumped
+     * once per pipeline run. Re-renders only a cell that reads its row beyond
+     * its own value (see {@link shouldUpdate}).
+     *
+     * @internal
+     */
+    dataVersion: number;
     /**
      * Reactive token forwarded from {@link EditingController.validationVersion}.
      * Changing it re-runs {@link willUpdate} so the cell re-reads its validation
@@ -62,11 +89,22 @@ export default class ApexGridCell<T extends object> extends LitElement {
     validationVersion: number;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    protected willUpdate(): void;
+    /**
+     * Skips the render when only positional or decoration tokens changed: the
+     * decoration is host attributes, so it is reconciled here and the cell
+     * template (type renderers, user templates) is not re-run. A cell that reads
+     * its row beyond {@link value} (a `cellTemplate`, which may read other fields
+     * or the row index, or the tree group cell, whose chevron shows the row's
+     * expansion) still renders when the row index or the data token moves.
+     * A {@link record} change is never a token: the cell renders in full.
+     */
+    protected shouldUpdate(changed: PropertyValues<this>): boolean;
+    protected willUpdate(changed: PropertyValues<this>): 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.
+     * an `aria-errormessage` IDREF on the host can't reach this node, so the
+     * host sets none (it would dangle).
      */
     protected renderError(): import("lit-html").TemplateResult<1> | null;
     protected updated(changed: PropertyValues<this>): void;