apex-grid 3.6.0 → 4.0.0-beta.1

package/CHANGELOG.md

@@ -4,6 +4,241 @@ 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.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/README.md

@@ -192,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
@@ -255,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 };
@@ -264,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
 
@@ -305,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
@@ -388,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.
@@ -435,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)
@@ -503,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
 
@@ -529,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 |
 
@@ -552,7 +595,7 @@ 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 +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).
@@ -647,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` |
@@ -662,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) |
@@ -751,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.
      */
@@ -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;

package/components/cell.js

@@ -4,7 +4,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-var _a;
 import { consume } from '@lit/context';
 import { html, LitElement } from 'lit';
 import { property, query } from 'lit/decorators.js';
@@ -62,7 +61,7 @@ function scrollRowIntoRange(scroller, body, index) {
     const rowCentre = top + (index - first.index + 0.5) * height;
     scroller.scrollTop += rowCentre - (view.top + scroller.clientHeight / 2);
 }
-class ApexGridCell extends LitElement {
+export default class ApexGridCell extends LitElement {
     constructor() {
         super(...arguments);
         this.active = false;
@@ -77,6 +76,7 @@ class ApexGridCell extends LitElement {
         this.#staged = false;
         this.#resumed = null;
         this.#reconnected = false;
+        this.#rebound = false;
         this.#handleClick = (event) => {
             if (this.isEditing) {
                 event.stopPropagation();
@@ -170,17 +170,20 @@ class ApexGridCell extends LitElement {
     }
     static { this.styles = styles; }
     static register() {
-        registerComponent(_a);
+        registerComponent(ApexGridCell);
     }
     get context() {
+        const data = this.row.data;
+        const key = this.column.key;
         const ctx = {
             parent: this,
             row: this.row,
             column: this.column,
             value: this.value,
+            data,
         };
         if (this.isEditable) {
-            ctx.commit = (next) => this.editingController.commitImmediate(this.row.data, this.column.key, next);
+            ctx.commit = (next) => this.editingController.commitImmediate(data, key, next);
         }
         return ctx;
     }
@@ -199,12 +202,15 @@ class ApexGridCell extends LitElement {
         const pin = this.state.rowPin;
         return pin.hasPinnedRows && pin.enabled && pin.isPinned(this.row.data);
     }
+    get #recycledBody() {
+        return Boolean(this.state.host.rowRecycling) && !this.#inPinnedBand;
+    }
     #decoratedKeys;
-    static #ERROR_ID = 'apex-cell-error';
     #errors;
     #staged;
     #resumed;
     #reconnected;
+    #rebound;
     connectedCallback() {
         this.#reconnected = this.hasUpdated && !this.isUpdatePending;
         super.connectedCallback();
@@ -238,8 +244,9 @@ class ApexGridCell extends LitElement {
         return false;
     }
     willUpdate(changed) {
+        this.#rebound = this.hasUpdated && changed.has('record');
         this.#applyStaged();
-        if (changed.has('editing')) {
+        if (changed.has('editing') || this.#rebound) {
             this.#resumed = this.editing
                 ? this.editingController.heldDraft(this.row.data, this.column.key)
                 : null;
@@ -289,13 +296,11 @@ class ApexGridCell extends LitElement {
         this.#errors = errors && errors.length > 0 ? errors : null;
         if (this.#errors) {
             this.setAttribute('aria-invalid', 'true');
-            this.setAttribute('aria-errormessage', _a.#ERROR_ID);
             this.setAttribute('data-invalid', '');
             this.setAttribute('title', this.#errors.join('; '));
         }
         else {
             this.removeAttribute('aria-invalid');
-            this.removeAttribute('aria-errormessage');
             this.removeAttribute('data-invalid');
             this.removeAttribute('title');
         }
@@ -305,12 +310,13 @@ class ApexGridCell extends LitElement {
             return null;
         return html `<span
       part="cell-error"
-      id=${_a.#ERROR_ID}
       role="alert"
       >${this.#errors.join('; ')}</span
     >`;
     }
     #applyDecoration() {
+        if (!this.state?.hasCellDecorators && !this.#decoratedKeys.length)
+            return;
         const decoration = this.state && this.row
             ? this.state.decorateCell({
                 row: this.row.data,
@@ -341,8 +347,13 @@ class ApexGridCell extends LitElement {
             if (!changed.has('editing'))
                 return;
             const editor = this.editorElement;
-            editor?.focus();
-            if (editor instanceof HTMLInputElement) {
+            const resumed = this.#resumed !== null || this.#rebound;
+            if (resumed && this.#recycledBody && !this.state.navigation.ownsFocus)
+                return;
+            if (resumed)
+                editor?.getBoundingClientRect();
+            editor?.focus(resumed ? { preventScroll: true } : undefined);
+            if (!resumed && editor instanceof HTMLInputElement) {
                 if (editor.type === 'text' || editor.type === 'number') {
                     editor.select();
                 }
@@ -351,6 +362,8 @@ class ApexGridCell extends LitElement {
         }
         if (changed.get('editing') === true && this.#refocusAfterEdit) {
             this.#refocusAfterEdit = false;
+            if (this.#rebound && this.editingController.activeCell)
+                return;
             this.focus();
         }
     }
@@ -482,6 +495,7 @@ class ApexGridCell extends LitElement {
             row: this.row,
             column: this.column,
             value: this.#editorValue,
+            data: this.row.data,
             commit: (next) => this.editingController.commitCell(next),
             cancel: () => this.editingController.cancelCell(),
             setDraft: (next) => this.editingController.setDraft(next),
@@ -586,11 +600,12 @@ class ApexGridCell extends LitElement {
         return html `${this.renderCellBody()}${error}`;
     }
 }
-_a = ApexGridCell;
-export default ApexGridCell;
 __decorate([
     property({ attribute: false })
 ], ApexGridCell.prototype, "value", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGridCell.prototype, "record", void 0);
 __decorate([
     property({ attribute: false })
 ], ApexGridCell.prototype, "column", void 0);