apex-grid 3.6.0 → 4.0.0-beta.2

package/CHANGELOG.md

@@ -4,6 +4,307 @@ 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/).
 
+## [Unreleased]
+
+## [4.0.0-beta.2] - 2026-11-08
+
+A second pre-release of 4.0.0, under the `next` npm tag. It adds opt-in
+Ignite UI theming (`apex-grid/ignite-ui`) and the family `--apx-*` tokens.
+Breaking against 4.0.0-beta.1 and 3.x: an Ignite UI stylesheet no longer
+re-tints the brand or replaces the font until you import the add-on, and
+`--ag-font` has no root default any more (see Changed and Fixed).
+
+### Added
+- **`apex-grid/ignite-ui`, the Ignite UI add-on.** `import 'apex-grid/ignite-ui'`
+  once and every grid on the page follows the Ignite UI theme the page loads:
+  brand, text and muted text, gridlines and the pinned-column edge, the header
+  (`--ig-surface-raised`, Ignite UI 7.5 and later), state colours, font and the
+  enterprise popups (`--ig-surface-overlay` on 7.5 and later). A grid without
+  `theme="dark"` or `theme="light"` follows the Ignite UI variant, live, with
+  a JS fallback where the browser has no container style queries;
+  `theme="light"` keeps a grid light. Ranking: an `--ag-*` token you set, then
+  the family `--apx-*` tokens, then Ignite UI, then the built-in values. Per
+  grid, `design-system="off"` turns the Ignite UI colours and font off (the
+  variant still picks the mode) and `tokens="off"` turns off the family tokens
+  and Ignite UI, variant included (both also as the reflected `designSystem`
+  and `tokens` properties). It registers on a shared `globalThis` slot, so it
+  reaches the grids of a separately built bundle too. While the add-on is
+  loaded, the tokens that follow Ignite UI (text, lines, surfaces, header,
+  state colours, pinned edge) leave the root defaults, so page CSS that reads
+  one needs its own fallback. It adds about 2.5 KB gzip to an app, and only
+  where it is imported.
+- **The family `--apx-*` tokens** shared by every Apex product: `--apx-accent`
+  (brand), `--apx-fore` (text), `--apx-grid` (gridlines, row borders, header
+  separator), `--apx-surface` (card and row background), `--apx-font-family`
+  and `--apx-radius-factor`, each ranked below the matching `--ag-*` token.
+  The text, line and surface root defaults are now written as their family
+  chain (`--ag-text: var(--apx-fore, #111827)` in `:where(:root)` and
+  `apex-grid/tokens.css`), so they follow a family token set on `:root`.
+- `--apx-radius-factor` scales `--ag-radius`, `--ag-radius-sm` and
+  `--ag-radius-xs` while it is set. Unset or 1, every radius is unchanged
+  (a multi-value radius too, without a factor); the pill stays round.
+- `tokens="off"` (or `grid.tokens = false`) keeps one grid, and the content it
+  renders, off the family tokens, with or without the add-on. Without the
+  add-on, an `--apx-fore`, `--apx-grid` or `--apx-surface` set on `:root` still
+  reaches that grid through the root defaults, which resolve there.
+- `--ag-overlay` and `--ag-overlay-text` (dark grids: `--ag-dark-overlay`,
+  `--ag-dark-overlay-text`) colour the `apex-grid-enterprise` popups. They have
+  no default: unset, each popup keeps its built-in colours.
+
+### Changed
+- **Breaking: the grid no longer reads Ignite UI tokens by itself.** Before,
+  an Ignite UI theme on the page re-tinted the brand (`--ig-primary-500`,
+  `--ig-primary-700`) and replaced the font (`--ig-font-family`) with no
+  import. Now an Ignite UI stylesheet changes nothing until you import
+  `apex-grid/ignite-ui`, which brings the brand and font back along with the
+  rest of the theme.
+- The grid now follows the family `--apx-*` tokens (above). A page that sets
+  them for its charts, on `:root` for example, sees the grid follow them too.
+  Set the matching `--ag-*` tokens to keep the grid as it was, or set the
+  family tokens on the elements they are meant for.
+
+### Fixed
+- An explicit `--ag-font` now wins over the family and Ignite UI fonts, the
+  same order the brand tokens use. Before, an Ignite UI theme on the page
+  replaced the grid font even when `--ag-font` was set on the grid itself. The
+  default Inter stack is unchanged. To keep the family and Ignite UI fonts
+  reachable, `--ag-font` no longer has a root default (it is gone from
+  `:where(:root)` and `apex-grid/tokens.css`), so page CSS that reads
+  `var(--ag-font)` needs its own fallback, as with `--ag-brand`.
+
+## [4.0.0-beta.1] - 2026-10-29
+
+A pre-release of 4.0.0, published under the `next` npm tag for trying out
+before it becomes `latest`. It is a major version because these changes can
+break existing code:
+
+- **Body rows are recycled by default** (`rowRecycling`). A row element and
+  its cells can show another record after a scroll, sort or filter, so a
+  template that keeps state in the elements it creates, or code that holds
+  `grid.rows` elements or `ctx.row` across an `await`, can see another
+  record. Set `rowRecycling = false` (or `row-recycling="false"`) to keep
+  record-keyed rows.
+- **The grid role moved off the host.** `role`, `aria-rowcount`,
+  `aria-colcount`, `aria-multiselectable` and the accessible name are on the
+  inner `[part~="table"]` element.
+- **Types removed:** `DataPipelineConfiguration.pagination` and the
+  `'pagination'` value of `DataPipelineParams.type`.
+- **Pagination:** pinned rows no longer count toward `totalItems` and the
+  pages, and a local page change no longer calls custom sort and filter hooks.
+- **Smaller type and DOM changes:** `ctx.data` is a required field of the cell
+  context, `ApexGridPaginator.pageSizeOptions` is `readonly number[]`, the
+  paginator's previous button id is `prev`, and the protected
+  `ApexGrid.headerRowCount` and `ApexGridHeaderRow.renderDragGhost` are gone.
+
+See Changed and Removed for the details and for other changes apps may notice.
+
+### Added
+- The `ai.cancelled` locale key (English and Spanish), used by the enterprise
+  Ask AI panel.
+- The `chart.rangeResized` locale key (English and Spanish), announced when an
+  enterprise charted range is resized from the keyboard.
+- **`showHeader`** (attribute `show-header="false"`) leaves out the column
+  header row, the column group row and the filter panel, so a short grid such as
+  a dashboard tile gives that room to the data rows. Screen readers still
+  announce the column names, and sort, filter, column widths and the page come
+  back unchanged when the header returns. While it is hidden, resizing, the
+  column menu, drag reorder and the header filter button are unavailable.
+  ([#35](https://github.com/apexcharts/apex-grid/issues/35))
+- **`selection.isRowSelectable(row)`** keeps chosen rows out of selection,
+  such as a pinned total row. Such a row shows no checkbox, and clicks, Shift
+  and Ctrl clicks, Space, Select all, `selectRow` and `setState` all skip it;
+  the header checkbox counts only selectable rows. Rows stay selectable by
+  default, pinned rows included.
+  ([#38](https://github.com/apexcharts/apex-grid/issues/38))
+- `pagination.paginator: 'compact'` draws the small paginator: summary,
+  previous, page / count, next.
+  ([#36](https://github.com/apexcharts/apex-grid/issues/36))
+- `apex-grid::part()` reaches every paginator and toolbar part
+  (`paginator-host`, `paginator`, `paginator-size`, `paginator-info`,
+  `paginator-controls`, `paginator-page`, `paginator-button`, `toolbar-host`,
+  `toolbar`, `toolbar-search`, `search-input`, `toolbar-actions`, `export`,
+  `export-menu` and the rest), and each paginator button also carries its own
+  part: `paginator-first`, `paginator-prev`, `paginator-next` or
+  `paginator-last`. ([#37](https://github.com/apexcharts/apex-grid/issues/37))
+- **`ctx.data` in cell and editor templates.** The context handed to a
+  `cellTemplate` or an `editorTemplate` carries `data`, the record the cell
+  was rendered for. It stays that record after an `await`, while `ctx.row`
+  and `ctx.parent` are elements that a pinned row band can later re-bind to
+  another record. A `cellTemplate`'s `ctx.commit` writes to `ctx.data`. An
+  editor's `ctx.commit` still commits the cell in edit when it is called.
+
+### Changed
+- **Body rows are now recycled by default** (new `rowRecycling` property,
+  default `true`). A scroll, sort or filter re-binds the rendered row elements
+  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, can
+  therefore show another record later. Cell and editor templates should
+  derive what they render from their context on each render, read
+  `ctx.data` for the record, and not hold `ctx.row` or `ctx.parent` across an
+  `await`; a template that keeps element state can wrap itself in
+  `keyed(ctx.data, ...)`. What you might notice: a template that keeps state
+  in the elements it creates (an input's typed value, a third-party widget)
+  can show it on another record after a scroll or a sort, and code that holds
+  `grid.rows` elements across a scroll or a sort finds them showing other
+  records. To keep record-keyed rows, set `grid.rowRecycling = false` (or the
+  `row-recycling="false"` attribute). Detail panel content follows its record
+  and keeps its DOM state across a scroll, a sort or a `moveRow`, so detail
+  templates need no change; a grid created inside a `detailTemplate` keeps its
+  own setting.
+- **The grid role and its row counts moved from the `<apex-grid>` host to an
+  inner element** exposed as part `table`: `role` (`grid` or `treegrid`),
+  `aria-rowcount`, `aria-colcount`, `aria-multiselectable` and the accessible
+  name. It holds only the header rows and the body, so the toolbar, paginator,
+  filter panel and live region are no longer read as table content, and every
+  default grid passes the axe `aria-required-children` rule. Code or tests
+  that read these from the host should query
+  `grid.shadowRoot.querySelector('[part~="table"]')`. The layout is unchanged.
+- An `aria-label` or `aria-labelledby` on the host still names the grid, and
+  `aria-describedby` becomes its description. References are resolved when the
+  grid renders: if the referenced element is added later, set the attribute
+  again.
+- The grid uses the `treegrid` role whenever rows carry levels or expand: tree
+  data, master-detail with a detail template, and the enterprise row grouping,
+  expandable pivot and server-side grouping.
+- `pageItems` keeps the same array between updates while nothing that shapes
+  it changes. Apps that compared it by identity now see a new array only when
+  the body rows change.
+- The column header row is no longer a Tab stop.
+- **The built-in column menu opens in the top layer** where the browser supports
+  the Popover API: pinned rows, the paginator and the grid's edge no longer
+  cover or clip it, it stays on its header cell through any scroll or layout
+  change, and it closes when its column scrolls out of the grid. It can now
+  extend outside the grid's box.
+- The column drag ghost renders at the grid root, so it stays above the column
+  group header and pinned top rows, and `apex-grid::part(drag-ghost)` now
+  reaches it.
+- `--filtering-header-background` applies to every filtered header, pinned and
+  dragged ones included, as a layer over the header's own background, and
+  filtered headers get the same hover highlight as other headers.
+- The paginator follows `--header-background` and group header labels follow
+  `--header-text-color`, like the rest of the header area. The paginator text
+  size follows `--ag-fs-cell-secondary`, and the filter count badge uses
+  `--ag-text-on-brand` and `--ag-fw-semibold`. Default rendering is unchanged.
+- Forced colors (Windows High Contrast): checkboxes are drawn by the browser in
+  system colours, so apps that styled them through parts see the native
+  checkbox in that mode only.
+- With pagination, pinned rows no longer count toward the pages: `totalItems`,
+  `pageCount`, the paginator summary and the `pageChanged` detail count the
+  rows the pager pages through, and pinning a row on the last page moves to the
+  new last page. Without pagination `totalItems` still counts every row.
+- A local page or page size change no longer reruns sorting, filtering and the
+  rest of the pipeline, so custom sort and filter hooks are no longer called on
+  a local page change. Remote mode still reruns it.
+- `pageChanged` reports the change that was applied, so two quick
+  `nextPage()` calls report page 2 and then page 3.
+- A page change is announced once ("Page X of N"); the paginator summary and
+  page label are no longer live regions.
+- The first grid on a page adds one window `error` listener that cancels
+  "ResizeObserver loop" messages and hides them from listeners added after it.
+  Listeners registered before the first grid still receive them. Every other
+  error is untouched. ([#32](https://github.com/apexcharts/apex-grid/issues/32))
+- `totalItems` is described one way everywhere: the post-filter, post-sort
+  row count, and in remote mode the `pagination.totalItems` you supply, the
+  number of rows the server holds for the current filter.
+  ([#34](https://github.com/apexcharts/apex-grid/issues/34))
+- Type and DOM details for code that builds on the grid's internals:
+  `BaseApexCellContext.data` is required, so code that builds a cell context
+  by hand must supply it; `ApexGridPaginator.pageSizeOptions` is typed
+  `readonly number[]`; the paginator's previous button has the id `prev`
+  (it was `previous`) inside its shadow root; and the protected
+  `ApexGrid.headerRowCount` and `ApexGridHeaderRow.renderDragGhost` were
+  removed, which affects subclasses only.
+- The `@lit-labs/virtualizer` dependency is pinned to exactly `2.1.1` (it was
+  `~2.1.0`). The grid body builds on parts of that package that are not public
+  API, so a newer version arrives only with a grid release that has been
+  checked against it.
+
+### Removed
+- **Breaking (types):** `DataPipelineConfiguration.pagination` and the
+  `'pagination'` value of `DataPipelineParams.type`. The hook was documented
+  but never called, so no runtime behaviour changes; TypeScript code that sets
+  it stops compiling. For server paging use `pagination.mode: 'remote'`, fetch
+  the page on `pageChanged` and keep `pagination.totalItems` current.
+  ([#33](https://github.com/apexcharts/apex-grid/issues/33))
+
+### Fixed
+- `aria-rowcount` no longer counts the floating filter panel as a row, and a
+  pinned top row no longer shares its `aria-rowindex` with the first body row.
+- The master-detail panel sits in a full-width gridcell, and `aria-expanded` is
+  set only on rows and toggle buttons that can expand. Turning expansion off or
+  removing the detail template no longer leaves it on rows.
+- Announcing the same message twice in a row (two identical `grid.announce()`
+  calls, for example) is read out again by screen readers.
+- Invalid cells no longer set an `aria-errormessage` that pointed at an
+  unreachable id. The inline alert message is unchanged.
+- Range and formula reference highlights on a pinned column no longer let
+  scrolled cells show through it.
+- Alternating row stripes follow the row index, so they no longer flip or
+  flicker while you scroll.
+- In the dark theme the default, muted and gold badges are readable and the
+  progress bar track is visible. The light theme is unchanged.
+- The selected row accent bar sits on the leading edge in right to left
+  layouts, including a left to right grid nested in a right to left one.
+- Forced colors: checked and indeterminate checkboxes no longer look unchecked;
+  in a selected row the cell text, row number, reorder grip and chevrons take
+  the selection text colour; an editor opened in a selected row uses the
+  system field colours; a keyboard-grabbed row shows an outline.
+- The paginator no longer clips its controls in a narrow grid: it drops the
+  rows per page selector, then the first and last buttons, so previous and next
+  stay reachable. ([#36](https://github.com/apexcharts/apex-grid/issues/36))
+- Grids whose cell text wraps no longer raise "ResizeObserver loop completed
+  with undelivered notifications" while they resize or scroll.
+  ([#32](https://github.com/apexcharts/apex-grid/issues/32))
+- With row pinning and pagination, no trailing page is left empty.
+- A `pageSize` missing from `pageSizeOptions` now appears in the rows per
+  page selector and is selected.
+- A page size change or quick filter cancelled through `pageChanging` or
+  `quickFilterChanging` no longer leaves the selector or search box showing
+  the refused value.
+- **Pinned rows no longer show the previous row's state.** When a pinned row
+  element switches to another record (a row above it is unpinned, say), it no
+  longer keeps the previous record's staged row edit value, validation error,
+  expanded state, detail panel content or selection checkbox state, even when
+  both records hold the same cell value.
+- A `cellTemplate` that calls `ctx.commit` after an `await` writes to the
+  record it was rendered for, even if the rows changed in the meantime.
+- Moving a keyboard grabbed row with the arrow keys keeps focus on that row
+  instead of dropping it to the page, and Escape puts the active cell and
+  focus back on the row at its original position.
+- The floating ghost of a row drag shows the row's cell text. It showed empty
+  cells before.
+- An editor rendered again for an edit already in progress (its row scrolled
+  back into view, for example) no longer scrolls the grid or selects the typed
+  draft when it takes focus.
+- With an async `dataPipelineConfiguration` hook, moving a row with
+  `moveRow`, a keyboard grab or a drag animates the rows into their new places.
+  They jumped there without the animation before.
+- A jump to a row far outside the view that is still waiting for the body to
+  finish scrolling no longer runs after a newer jump, so two quick jumps end on
+  the second row instead of snapping back to the first.
+- A pinned row that switches to another record no longer animates from the
+  previous record's look: its selected wash, expand chevron, checkbox and
+  progress bars show the new record's state at once.
+- An image cell whose URL changes (a pinned row switching records, an edit of
+  the URL) renders a new `<img>`, so the previous picture no longer stays on
+  screen while the new one loads.
+- Arrow and Page keys in a grid whose rows grew after they were first shown
+  (detail panels expanded, wrapped text) keep the active cell in view and
+  focused. A quick run of key presses could leave it unrendered, with focus on
+  the body or on a cell of another record, until the next click.
+- When a sort, a filter or a data change moves the record of an open cell
+  edit to another row that is still in view, the active cell moves with it, so
+  the keyboard carries on from the edited cell once the edit closes. It used to
+  stay on the old row, which then showed another record.
+
+### Performance
+- Scrolling no longer re-renders the rows that stay in view; only the rows that
+  scroll in render.
+- A grid with a pinned row or a page slice no longer rescans the whole view on
+  every key press or click.
+- Grids without feature modules skip the per-cell decoration step, and grids
+  with modules no longer check every module on each row and cell render.
+
 ## [3.6.0] - 2026-10-21
 
 A quality release built from a full code-quality audit, plus `--ag-*` tokens

package/LICENSE.md

@@ -85,10 +85,11 @@ Required if you are **embedding ApexGrid into a product or platform used by othe
 ✅ 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
 
+⚠️ **Developer licenses are purchased separately.** The OEM License grants redistribution rights and carries no developer seats. Each developer who works with ApexGrid in that application also needs a **Community + Commercial** license of their own. That is the tier whatever features your product uses, because the license key comes from the OEM License and already renders every licensed feature.
+
 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.

package/README.md

@@ -29,7 +29,7 @@ A Lit-based, framework-agnostic web component data grid. Ships as a single custo
 - **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-tints to an Ignite UI host app's palette when one is present, with no dependency on it.
+- **Theming**: styled out-of-the-box; fully customizable through `--ag-*` CSS custom properties (no theme import or build step), and follows the `--apx-*` tokens shared by every Apex product. One import (`apex-grid/ignite-ui`) makes it follow an Ignite UI theme, light or dark.
 - **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.
 
@@ -130,11 +130,15 @@ See [`src/styles/_token-values.scss`](src/styles/_token-values.scss) for the ful
 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:
+The grid renders the same without the sheet; it carries the defaults as fallbacks. Four 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).
+- `--ag-brand` and `--ag-brand-strong`, so a family `--apx-accent` (or, with the Ignite UI add-on, an Ignite UI palette) set on any ancestor still reaches the grid (see below).
+- `--ag-font`, for the same reason (`--apx-font-family`, an Ignite UI font).
+- `--ag-overlay` and `--ag-overlay-text` (and `--ag-dark-overlay`, `--ag-dark-overlay-text`): unset, the enterprise popups keep their own colours (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.
 
+The root defaults of the text, line and surface tokens are written as their family chain (`--ag-text: var(--apx-fore, #111827)`), so they follow a family token set on `:root` (see below).
+
 **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
@@ -155,7 +159,34 @@ apex-grid[theme~='dark'] { --ag-grid-shadow: var(--ag-dark-shadow-card); } /* th
 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, 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.
+**Enterprise popups.** `--ag-overlay` and `--ag-overlay-text` colour the popups of `apex-grid-enterprise` (filter builder, set filter, AI panel, tool panel, status bar); dark grids read `--ag-dark-overlay` and `--ag-dark-overlay-text`. Set both: the popup lines, muted text and hover wash are mixed from the two. Unset, each popup keeps its built-in colours.
+
+**Family tokens (`--apx-*`).** The grid also reads the tokens every Apex product shares, ranked below its own: `--apx-accent` (brand), `--apx-fore` (text), `--apx-grid` (gridlines, row borders, header separator), `--apx-surface` (card and row background), `--apx-font-family` and `--apx-radius-factor`. An `--ag-*` or `--ag-dark-*` token you set wins over them, and they apply to light and dark grids alike. The brand, font and radius factor reach the grid from any ancestor. Text, lines and surface have root defaults, which resolve on `:root`: they follow a family token set on `:root` (or, with the Ignite UI add-on, which lifts those defaults, on any ancestor). `--apx-radius-factor` scales `--ag-radius`, `--ag-radius-sm` and `--ag-radius-xs` while it is set; at 1 nothing changes, the pill shape stays round, and a multi-value radius (`--ag-radius: 12px 12px 0 0`) works only without a factor.
+
+`tokens="off"` on a grid (or `grid.tokens = false`) keeps it off the family tokens and the content it renders too. One limit without the Ignite UI add-on: an `--apx-fore`, `--apx-grid` or `--apx-surface` set on `:root` has already resolved into the text, line and surface root defaults there, which every grid reads, so that grid still shows it; set the matching `--ag-*` tokens on it, or set the family tokens on the elements they are meant for.
+
+```css
+:root {
+  --apx-accent: #7c3aed;
+  --apx-font-family: 'Source Sans 3', sans-serif;
+  --apx-radius-factor: 0.5;
+}
+```
+
+**Ignite UI.** To follow an Ignite UI theme, import the add-on once:
+
+```ts
+import 'apex-grid/ignite-ui';
+```
+
+Every grid on the page, in the document or in any shadow root, then follows the Ignite UI theme the page loads, including grids that connected before the import: the brand (`--ig-primary-*`), text and muted text, gridlines and the pinned-column edge (the gray ramp), the header (`--ig-surface-raised`, Ignite UI 7.5 and later), the state colours, the font, and the enterprise popups (`--ig-surface-overlay` on 7.5 and later, else the grid's own popup colours). The card and row surfaces keep the grid's own light or dark background. Without the add-on the grid reads no `--ig-*` token, and an Ignite UI stylesheet changes nothing.
+
+- **Ranking:** an `--ag-*` token you set, then the family `--apx-*` tokens, then Ignite UI, then the built-in values.
+- **Mode:** a grid without `theme="dark"` or `theme="light"` follows the Ignite UI variant (`--ig-theme-variant`) declared on `:root` or any ancestor (as Ignite UI themes do), and a theme swap live. `theme="light"` keeps a grid light (text and lines then keep the built-in values, since a dark theme's grays are light) and `theme="dark"` keeps it dark. Where the browser has no container style queries, grids follow the document's variant.
+- **Per grid:** `design-system="off"` (the `designSystem` property set to `false`) turns the Ignite UI colours and font off (the variant still picks the mode); `tokens="off"` (`tokens = false`) turns off the family tokens and Ignite UI, the variant included, for the grid and the content it renders.
+- **Root defaults:** while the add-on is loaded, the tokens that follow Ignite UI (text, lines, surfaces, header, state colours, pinned edge) leave the root defaults, as `--ag-brand` and `--ag-font` always have, so page CSS that reads one gives its own fallback: `var(--ag-text, #111827)`.
+- **Other products:** each takes its own add-on. For the `apex-grid-enterprise` chart panel to read the theme itself, also import `apexcharts/features/ignite-ui` (ApexCharts releases that ship it); the grid never loads it, since it themes every chart on the page. Without it the panel chart takes the grid's colours, which follow the theme.
+- **Bundles:** the add-on registers on a shared `globalThis` slot, so it reaches every grid even when the grid and the add-on come from separately built bundles.
 
 ### 4. Size the host
 
@@ -192,6 +223,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
@@ -255,7 +289,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 };
@@ -264,7 +311,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
 
@@ -305,6 +352,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
@@ -388,9 +445,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.
@@ -435,6 +504,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)
@@ -503,7 +574,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
 
@@ -529,16 +600,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 |
 
@@ -546,13 +620,13 @@ 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 (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`.
+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. The grid also follows the family `--apx-*` tokens, and an Ignite UI theme with the opt-in `apex-grid/ignite-ui` add-on (both under Customize the look).
 
 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:
@@ -611,6 +685,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).
@@ -647,7 +742,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` |
@@ -662,6 +757,10 @@ 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"` |
+| `designSystem` | `boolean` | `true` | With the `apex-grid/ignite-ui` add-on, `false` turns the Ignite UI colours and font off for this grid (the variant still picks the mode). Reflected as `design-system="off"` |
+| `tokens` | `boolean` | `true` | `false` turns the family `--apx-*` tokens (and, with the add-on, Ignite UI) off for this grid and its content. Reflected as `tokens="off"` |
+| `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) |
@@ -751,14 +850,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`. Theming: `theme` (`dark`, `light`, `tinted`), `tokens="off"` and, with the `apex-grid/ignite-ui` add-on, `design-system="off"` (see [Customize the look](#3-optional-customize-the-look)).
 
 ### 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.
      */
@@ -86,13 +96,15 @@ export default class ApexGridCell<T extends object> extends LitElement {
      * 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;