apexgrid-skill 2.3.1 → 2.4.0

package/.cursorrules

@@ -4,7 +4,7 @@ You are working with `apex-grid`, a Lit-based web-component data grid by ApexCha
 Documentation: https://github.com/apexcharts/apexgrid
 NPM: apex-grid (with a hyphen — no `apexgrid` package exists)
 GitHub: https://github.com/apexcharts/apexgrid
-Confirmed versions: apex-grid@3.0.1, lit@^3.0.0
+Confirmed versions: apex-grid@3.6.0, lit@^3.0.0
 
 ## Quickstart — register + size the host
 
@@ -16,7 +16,8 @@ height or it collapses and renders nothing. `setup()` handles both.
 ```bash
 npm install apex-grid lit
 ```
-`igniteui-webcomponents` installs transitively — you do NOT import theme CSS from it.
+That is the whole install: `apex-grid` brings `lit`, `@lit/context` and `@lit-labs/virtualizer`.
+There is no theme CSS to import from anywhere (3.5.0 dropped the old Ignite UI dependencies).
 
 ### 2. Register + size — `setup()` does both
 ```ts
@@ -28,10 +29,16 @@ Manual alternative: `import 'apex-grid/define'` (or `ApexGrid.register()`) plus
 
 ### 3. Style via `--ag-*` CSS variables (no theme import)
 The grid is styled out of the box; retheme by overriding `--ag-*` custom properties on
-`apex-grid`. The deprecated `theme` option / `configureTheme()` does NOT affect appearance.
+`apex-grid` or on any ancestor, shadow hosts included (3.6). The deprecated `setup({ theme })`
+option / `configureTheme()` does NOT affect appearance.
 ```css
-apex-grid { height: 480px; /* + any --ag-* overrides */ }
+apex-grid { height: 480px; --ag-brand: #7c3aed; /* + any --ag-* overrides */ }
 ```
+Dark mode: the `theme="dark"` attribute (`tinted` adds brand chrome; `theme="dark tinted"`).
+Since 3.6 a dark grid reads `--ag-dark-*` colour tokens (`--ag-dark-surface`, `--ag-dark-text`, ...)
+and IGNORES the light ones (`--ag-surface`, ...), even when set on the dark grid itself.
+Brand, sizing and typography tokens are shared. In your own CSS, `var(--ag-brand)` has no
+root default: write `var(--ag-brand, #0d6fd3)`.
 
 ### Minimal example
 
@@ -88,7 +95,7 @@ render(
 1. **Apex Grid is a Lit web component, not a JS class.** Don't `new ApexGrid(...)`. Render `<apex-grid>` and set `.data` / `.columns` as properties.
 2. **Two setup steps:** register the element and give the host a bounded height — `setup()` does both. **No theme CSS import is needed** (the grid self-styles via `--ag-*`).
 3. **`columns` and `data` are properties, not attributes.** Use property binding.
-4. **`column.key` must be a real `keyof T`.** No aliases. Compute derived values in `cellTemplate`.
+4. **`column.key` must be a real `keyof T`.** No aliases. Compute derived values in `cellTemplate` (its `row` is the row element; the record is `row.data`).
 5. **Set `type` per column.** Primitive `'string'`/`'number'`/`'boolean'` drive sort/filter/editing (default `'string'`). Presentation types also exist: `'select'`, `'rating'`, `'date'`, `'image'`, `'currency'`, `'avatar'`, `'badge'`, `'progress'`, `'sparkline'`, `'status'`.
 6. **`cellTemplate` and `headerTemplate` must return Lit `TemplateResult`s** (`html\`...\``). Strings render as escaped text.
 7. **Sort/filter events fire only for UI-initiated operations.** Programmatic `grid.sort(...)` / `grid.filter(...)` are silent.
@@ -145,8 +152,8 @@ render(html`<apex-grid auto-generate .data=${data}></apex-grid>`, root);
 
 | Type | Operands |
 |---|---|
-| `'string'` | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
-| `'number'` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
+| `'string'` and other non-numeric types | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
+| `'number'`, `'currency'`, `'rating'`, `'progress'` (3.6) | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
 | `'boolean'` | `all`, `true`, `false`, `empty`, `notEmpty` (all unary — no `searchTerm`) |
 
 ```ts
@@ -172,7 +179,7 @@ grid.filter([
 | `dataPipelineConfiguration` | `{ sort?, filter?, pagination?, quickFilter? }` | Server-side hooks |
 | `selection` / `editing` / `pagination` / `tree` / `expansion` | config objects | Opt-in: `{ enabled, ... }` (see SKILL.md §5) |
 | `quickFilter` / `columnReordering` | `string` / `boolean` | Global search / drag-reorder headers |
-| `sortExpressions` / `filterExpressions` | array (get/set) | To clear, use `clearSort()` / `clearFilter()` |
+| `sortExpressions` / `filterExpressions` | array (get/set) | Assigning REPLACES (3.6); `[]` clears. `sort()` / `filter()` add |
 | `selectedRows` / `expandedRows` | `T[]` (get/set) | Snapshots; set to replace |
 | `rows` (getter) | `ApexGridRow<T>[]` | Currently rendered only (virtualized) |
 | `dataView` / `pageItems` (getters) | `readonly T[]` | Full post-filter/sort / current page |
@@ -235,7 +242,7 @@ Built-in pipeline is skipped for whichever operations have a hook. Omit one to k
 
 ### 5. `column.key` not a `keyof T`
 ❌ `{ key: 'fullName' }` when not in `T`
-✅ `cellTemplate: ({ row }) => html\`${row.firstName} ${row.lastName}\``
+✅ `cellTemplate: ({ row }) => html\`${row.data.firstName} ${row.data.lastName}\`` (`row` is the element)
 
 ### 6. String from `cellTemplate`
 ❌ `cellTemplate: ({ value }) => \`<b>\${value}</b>\``
@@ -278,6 +285,25 @@ Built-in pipeline is skipped for whichever operations have a hook. Omit one to k
 
 ---
 
+## Changed in 3.6
+
+- `sortExpressions` / `filterExpressions` assignment REPLACES the sort / filter (`[]` or `null` clears).
+  Assigning one expression at a time keeps only the last: assign the full list, or `grid.sort(expr)` to add.
+- `sorted`, `filtered`, `pageChanged`, `quickFilterChanged` fire after the pipeline run, so `dataView` is fresh
+  in the listener, async hooks included.
+- `currency`, `rating`, `progress` columns filter with the number operands; a `contains` on them is dropped.
+- A sort `comparer` receives raw values (original casing, `null` included); empty cells sort last otherwise.
+- `applyEdits([{ row, column, value }])` names a row by record (any page, pinned); `rowIndex` stays page-relative.
+- `grid.ownsEvent(e)`: events bubble, so filter out a nested master-detail grid's events with it.
+- `expansion.exportParts` re-exports parts used in `detailTemplate`; every row part now works with `apex-grid::part()`.
+- `rowMoving` / `rowMoved` add `position` and `toIndex`; a row move on a sorted grid clears the sort.
+- Row edit mode: validators get the staged row as `ctx.data`; checkbox and `ctx.commit` join the row edit.
+- Replacing `grid.data` with new records clears undo history; `grid.data = null` shows an empty grid.
+- CSV export prefixes formula-like text with `'` (`exportToCSV({ escapeFormulas: false })` to opt out);
+  booleans export `true` only for `true`; currency / progress export as numbers.
+
+---
+
 ## Dev-server reminder
 
 ES module imports require an HTTP server — opening with `file://` fails CORS. Use Vite (`npm create vite@latest`) or any static server.

package/SKILL.md

@@ -7,14 +7,15 @@ description: >
   table with `<apex-grid>`. Covers the register-and-size setup (no theme import —
   the grid styles itself via `--ag-*` CSS variables), the generic
   `ColumnConfiguration<T>` shape with its 13 column types, Lit `cellTemplate`
-  requirements, sorting / filtering / quick-filter, pagination, inline editing,
-  row selection, master-detail and tree rows, CSV export, batch writes via
-  `applyEdits`, right-to-left layout, the UI-only event model, and the
+  requirements, theming and dark mode (`--ag-*` / `--ag-dark-*` tokens,
+  `theme="dark"`), sorting / filtering / quick-filter, pagination, inline
+  editing, row selection, master-detail and tree rows, CSV export, batch writes
+  via `applyEdits`, right-to-left layout, the UI-only event model, and the
   `dataPipelineConfiguration` hooks for server-side data.
 metadata:
   author: ApexCharts
-  version: "2.3.1"
-  library_version: "3.5.0"
+  version: "2.4.0"
+  library_version: "3.6.0"
   category: data-visualization
   tags: [grid, data-grid, table, web-component, lit, apex-grid]
   docs: https://github.com/apexcharts/apexgrid
@@ -38,7 +39,7 @@ That is the whole install. `apex-grid` brings its own runtime dependencies (`lit
 
 > **Changed in 3.5.0:** earlier versions also pulled in `igniteui-webcomponents` and `igniteui-theming` transitively. Both are gone. The grid never registered an Ignite UI element, so nothing you wrote against the grid is affected, but code that relied on `igc-*` elements being installed as a side effect must now depend on that package directly.
 
-> Confirmed working versions: `apex-grid@3.5.0`, `lit@^3.0.0`.
+> Confirmed working versions: `apex-grid@3.6.0`, `lit@^3.0.0`.
 
 ### 1.2 Register the element + size the host — `setup()` does both
 
@@ -62,20 +63,44 @@ apex-grid { height: 480px; }   /* any explicit height; % works if the parent is
 
 `setup({ hostStyles: false })` registers the element but skips the injected host CSS, leaving sizing entirely to you. Without a bounded height (from `setup()` or your own CSS) the grid collapses and shows no rows.
 
+Since 3.6.0 the `setup()` sizing is adopted into whichever root each grid connects in, so a grid rendered inside another web component's shadow root gets it too. On 3.5 and earlier it reached the page only, and a grid inside a shadow root needed its own height rule there.
+
 > **Do not set `display` on `apex-grid`** — the component declares `:host { display: grid }` for its internal track layout; an outer `display` rule overrides it and collapses the virtualizer.
 
 ### 1.3 Styling — `--ag-*` CSS custom properties (no theme import)
 
-The grid is styled out of the box and customized entirely through `--ag-*` CSS custom properties — there is **no theme file to import and no `configureTheme()` call**. Set the variables on `apex-grid` (or an ancestor):
+The grid is styled out of the box and customized entirely through `--ag-*` CSS custom properties. There is **no theme file to import and no `configureTheme()` call**. Set the variables on `apex-grid` or on any ancestor: `:root`, a dashboard panel, or the shadow host of a web component the grid renders in.
 
 ```css
 apex-grid {
   height: 480px;
-  /* override any --ag-* variables to retheme; see the package README for the full list */
+  --ag-brand: #7c3aed;   /* selection, focus, accents; the brand washes follow it */
+  --ag-radius: 12px;     /* outer card radius */
+  --ag-row-h: 40px;      /* row height; see the package README for the full token list */
+}
+```
+
+> **Changed in 3.6.0:** the token defaults moved off the grid host onto `:where(:root)`, adopted into the document (through `adoptedStyleSheets`, so no CSP nonce) when the first grid connects. On 3.5 and earlier a value set on an ancestor never reached the grid, because the host's own default beat it; only values set on the `apex-grid` element took effect. Now both do, through shadow roots however deep.
+
+**Dark mode.** Add the `theme="dark"` attribute (an attribute, not a property). `theme="tinted"` mixes the brand into the chrome, and the two combine as `theme="dark tinted"`. A dark grid reads its own colour inputs, the `--ag-dark-*` tokens (`--ag-dark-surface`, `--ag-dark-surface-elevated`, `--ag-dark-grid-bg`, `--ag-dark-text`, `--ag-dark-text-muted`, `--ag-dark-hairline`, `--ag-dark-border`, `--ag-dark-row-hover`, `--ag-dark-shadow-card`, ...). Sizing, typography, motion, the brand and the base state colours are shared by both modes, so one place can theme light and dark grids:
+
+```css
+.dashboard {
+  --ag-brand: #7c3aed;
+  --ag-surface: #fdfcff;        /* light grids */
+  --ag-dark-surface: #140f24;   /* grids with theme="dark" */
 }
+apex-grid { --ag-grid-shadow: var(--ag-shadow-card); }                     /* elevated card edge */
+apex-grid[theme~='dark'] { --ag-grid-shadow: var(--ag-dark-shadow-card); } /* the same, on dark grids */
 ```
 
-> The deprecated `setup({ theme })` option does **not** change the grid's appearance. It only ever forwarded to Ignite UI's `configureTheme()`, and since 3.5.0 it is inert and warns once. Omit it; use `--ag-*` variables instead.
+> **Changed in 3.6.0:** a light colour token (`--ag-surface`, `--ag-text`, `--ag-border`, ...) no longer applies to a dark grid, whether it is set on an ancestor or **on the dark grid element itself**. A rule such as `apex-grid[theme='dark'] { --ag-surface: #111; }` is now ignored: write `--ag-dark-surface`. A `theme="tinted"` grid ignores `--ag-border` and `--ag-dark-border` (its row separators are the brand alone).
+
+**Reading tokens in your own CSS** (page styles, markup in a `cellTemplate`): `var(--ag-surface)`, `var(--ag-text-muted)` and the other inputs resolve to their defaults anywhere on the page. `--ag-brand`, `--ag-brand-strong` and the derived washes (`--ag-brand-soft`, `--ag-brand-softer`, `--ag-brand-line`, `--ag-row-hover`, `--ag-surface-alt`) have no root default, so give them a fallback: `var(--ag-brand, #0d6fd3)`. To manage the defaults yourself, `setup({ tokenStyles: false })` skips the adopted sheet and `import 'apex-grid/tokens.css'` ships the same defaults as a file (also the way to get them into server-rendered HTML). The grid renders the same either way.
+
+**CSS parts.** Since 3.6.0 every part a body row renders is reachable with `apex-grid::part(...)`: `cell`, `selection-cell`, `selection-checkbox`, `expansion-cell`, `expansion-toggle`, `expansion-chevron`, `detail-panel`, `row-number-cell`, `row-number`, `reorder-handle-cell`, `reorder-handle`, `reorder-grip`. Before, only `cell` was. Parts inside your own `detailTemplate` content are reached by listing them in `expansion.exportParts` (`references/state-and-features.md`).
+
+> The deprecated `setup({ theme })` option does **not** change the grid's appearance. It only ever forwarded to Ignite UI's `configureTheme()`, and since 3.5.0 it is inert and warns once. Omit it; use `--ag-*` variables (and the `theme="dark"` attribute) instead.
 
 ### 1.4 Minimal example — a styled, sortable, filterable table
 
@@ -143,7 +168,7 @@ AI models trained before the package was published may suggest `apexgrid` (no hy
 
 3. **`columns` and `data` are properties, not attributes.** Use property binding (`.columns=${...}` in Lit, `[columns]=` in Angular, `:columns.prop=` in Vue, `el.columns = ...` in vanilla JS). A stringified `columns="[...]"` HTML attribute becomes the literal string and the grid renders nothing.
 
-4. **`column.key` must be a real `keyof T`.** No `field` / `dataIndex` / `accessor` aliases. To display a derived value, compute it in `cellTemplate` (which has `row` access).
+4. **`column.key` must be a real `keyof T`.** No `field` / `dataIndex` / `accessor` aliases. To display a derived value, compute it in `cellTemplate`, whose `row` is the `<apex-grid-row>` element: the record is `row.data`.
 
 5. **Set `type` per column.** The primitive types `'string'`, `'number'`, `'boolean'` drive the default sort comparer, filter operands, and editor. The default is `'string'` — leaving a numeric column unset sorts as strings ("10" before "9"). There are also presentation types — `'select'`, `'rating'`, `'date'`, `'image'`, `'currency'`, `'avatar'`, `'badge'`, `'progress'`, `'sparkline'`, `'status'` — that change rendering while sorting/filtering as their underlying value (§4).
 
@@ -210,27 +235,30 @@ Applied defaults (`DEFAULT_COLUMN_CONFIG`): `{ type: 'string', resizable: false,
 | `'currency'` | `Intl.NumberFormat` (`currency`, `locale`). Numeric |
 | `'avatar'` | first letter in a tinted circle |
 | `'badge'` | colored pill (`badgeVariant`) |
-| `'progress'` | health bar, 0..`max` (default 100) |
+| `'progress'` | health bar, 0..`max` (default 100). Numeric |
 | `'sparkline'` | inline trend chart of a `number[]` (`showDelta`) |
 | `'status'` | dot + pill (`statusVariant`, or inferred) |
 
 > A `'date'` column **does** exist in 3.x — use `type: 'date'` (it accepts `Date`, ISO strings, or millisecond timestamps), not a string column with a custom comparer.
 
-### Column type → filter operands (primitive types)
+### Column type → filter operands
 
 | `type` | Operand keys in the filter UI |
 |---|---|
-| `'string'` | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
-| `'number'` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
-| `'boolean'` | `all`, `true`, `false`, `empty`, `notEmpty` (all **unary** — no `searchTerm`) |
+| `'string'`, and every type not listed below (`select`, `date`, `image`, `avatar`, `badge`, `sparkline`, `status`) | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
+| `'number'`, and the numeric types `'currency'`, `'rating'`, `'progress'` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
+| `'boolean'` | `all`, `true`, `false`, `empty`, `notEmpty` (all **unary**: no `searchTerm`) |
 
 ```ts
-grid.filter({ key: 'subscribed', condition: 'true' });   // unary — no searchTerm
+grid.filter({ key: 'subscribed', condition: 'true' });   // unary: no searchTerm
+grid.filter({ key: 'price', condition: 'greaterThan', searchTerm: 100 });   // a 'currency' column
 ```
 
+> **Changed in 3.6.0:** `currency`, `rating` and `progress` columns filter as numbers. On 3.5 they took the text operands. A text condition such as `contains` on one of them, from `filter()` or a saved state, is now dropped with a console warning.
+
 ### Cell template
 
-Receives `ApexCellContext<T, K>` (`{ parent, row, column, value, commit? }`). Must return a Lit `TemplateResult`:
+Receives `ApexCellContext<T, K>` (`{ parent, row, column, value, commit? }`, where `row` is the `<apex-grid-row>` element and `row.data` the record). Must return a Lit `TemplateResult`:
 
 ```ts
 import { html } from 'lit';
@@ -238,6 +266,8 @@ import { html } from 'lit';
 { key: 'name', cellTemplate: ({ value, row }) => html`<strong>${value}</strong>` }
 ```
 
+Since 3.6.0 a `cellTemplate` runs again for every visible row after each pipeline run (sort, filter, edit, quick filter, tree toggle), so a template that reads other fields of its row stays current. Keep templates cheap.
+
 ### Auto-generated columns — the 3-line demo
 
 ```ts
@@ -275,7 +305,7 @@ grid.sort({ key: 'name', direction: 'ascending' });       // programmatic (silen
 
 | Property | Type | Notes |
 |---|---|---|
-| `data` | `T[]` | Setting triggers a pipeline run. |
+| `data` | `T[]` | Setting triggers a pipeline run. `null` / `undefined` (a framework prop still loading) shows an empty grid and reads back as `[]` (3.6). Replacing it with new records clears undo history and drops expansion of rows that left (`references/state-and-features.md`). |
 | `columns` | `ColumnConfiguration<T>[]` | Each entry merged with column defaults. |
 | `autoGenerate` (attr `auto-generate`) | `boolean` | Ignored if `columns` is non-empty. |
 | `sortConfiguration` | `{ multiple, triState }` | Multi-column + tri-state sorting toggles. |
@@ -293,7 +323,7 @@ grid.sort({ key: 'name', direction: 'ascending' });       // programmatic (silen
 | `pinnedRows` *(getter)* | `{ top: T[]; bottom: T[] }` | Currently pinned rows per band. |
 | `canUndo` / `canRedo` *(getters)* | `boolean` | Undo/redo availability (needs `editing.history.enabled`). |
 | `exportFormats` *(getter)* | `readonly { id, label }[]` | Export menu formats (CSV in the community grid). |
-| `sortExpressions` / `filterExpressions` | `…[]` (get/set) | Current state. To clear, use `clearSort()` / `clearFilter()`. |
+| `sortExpressions` / `filterExpressions` | `…[]` (get/set) | Current state. Assigning **replaces** the whole sort / filter, and `[]` or `null` clears it (3.6; on 3.5 assignment merged and `[]` did nothing). `sort()` / `filter()` add instead. `clearSort()` / `clearFilter()` also clear. |
 | `selectedRows` / `expandedRows` | `T[]` (get/set) | Snapshots; set to replace (goes through cancellable events). |
 | `rows` *(getter)* | `ApexGridRow<T>[]` | **Currently rendered only** (virtualized). |
 | `dataView` *(getter)* | `readonly T[]` | Full post-filter/sort data. |
@@ -308,10 +338,10 @@ grid.sort({ key: 'name', direction: 'ascending' });       // programmatic (silen
 | `editing` | `{ enabled, mode?: 'cell' \| 'row', trigger?: 'click' \| 'doubleClick', history?: { enabled, stackSize? } }` — plus per-column `editable: true` |
 | `selection` | `{ enabled, mode?: 'single' \| 'multiple', showCheckboxColumn? }` |
 | `pagination` | `{ enabled, mode?: 'local' \| 'remote', page?, pageSize?, pageSizeOptions?, totalItems? }` |
-| `tree` | `{ enabled, getDataPath: (row) => string[], groupColumnKey?, defaultExpanded?, childIndent? }` — flat data, hierarchy derived |
-| `expansion` | `{ enabled, detailTemplate: (ctx) => TemplateResult, isExpandable?, showToggleColumn? }` — master-detail |
+| `tree` | `{ enabled, getDataPath: (row) => string[], groupColumnKey?, defaultExpanded?, childIndent? }`: flat data, hierarchy derived. Under a filter, the ancestors of a match show as their own rows (3.6) |
+| `expansion` | `{ enabled, detailTemplate: (ctx) => TemplateResult, isExpandable?, showToggleColumn?, exportParts? }`: master-detail. `exportParts` (3.6) re-exports parts used in the detail content |
 | `rowPinning` | `{ enabled }` — sticky top/bottom bands via `pinRow()` / `unpinRow()` |
-| `rowReordering` | `{ enabled, applyToData?, handle? }` — drag/keyboard reorder + `moveRow()`; manual order is mutually exclusive with sort |
+| `rowReordering` | `{ enabled, applyToData?, handle? }`: drag/keyboard reorder + `moveRow()`. A sort clears the manual order, and a move clears the sort (3.6) |
 
 ```ts
 grid.editing    = { enabled: true, mode: 'cell', trigger: 'doubleClick', history: { enabled: true } };
@@ -333,7 +363,7 @@ Declarative validators (`column.validators`), column groups (`columnGroups`), un
 | `updateColumns(col \| col[])` | Merge new fields into existing columns by `key`. Triggers a pipeline run. |
 | `moveColumn(fromKey, toKey, position?)` | Reorder a column (within its pinning group). |
 | `pinColumn(key, 'start' \| 'end' \| null)` / `unpinColumn(key)` | Programmatic column pinning → `Promise<boolean>`; emits `columnPinning`/`columnPinned`. |
-| `exportToCSV(options?)` / `exportAs(formatId, options?)` | Export the data. CSV is built in. `options.source`: `'view'`(def)/`'page'`/`'selected'`/`'all'`. |
+| `exportToCSV(options?)` / `exportAs(formatId, options?)` | Export the data. CSV is built in. `options.source`: `'view'`(def)/`'page'`/`'selected'`/`'all'`. Formula-like CSV text (leading `=`, `+`, `-`, `@`, tab or CR; a plain signed number such as `-5` excepted) gets a leading apostrophe unless `escapeFormulas: false` (3.6). |
 | pagination | `gotoPage(n)`, `setPageSize(n)`, `nextPage()`, `previousPage()`, `firstPage()`, `lastPage()` → `Promise<boolean>`; emit `pageChanging`/`pageChanged`. |
 | `setQuickFilter(value)` | Apply global search (`''` clears) → `Promise<boolean>`; emits `quickFilterChanging`/`quickFilterChanged`. |
 | selection | `selectRow`, `deselectRow`, `toggleRowSelection`, `selectAllRows`, `clearSelection`, `isRowSelected` |
@@ -342,7 +372,8 @@ Declarative validators (`column.validators`), column groups (`columnGroups`), un
 | row pinning | `pinRow(row, 'top' \| 'bottom')`, `unpinRow(row)` (needs `rowPinning.enabled`) |
 | row reorder | `moveRow(from, to, position?)` (needs `rowReordering.enabled`) |
 | editing | `commitEdit()`, `cancelEdit()` (used with `mode: 'row'`) |
-| `applyEdits(edits)` | Write many cells as **one** operation: one undo step, one pipeline run. Returns a tally, not a count. (3.5) |
+| `applyEdits(edits)` | Write many cells as **one** operation: one undo step, one pipeline run. Returns a tally, not a count. (3.5) Each entry names its row by `rowIndex` (current page) or, since 3.6, by record: `{ row, column, value }` reaches any page, pinned rows and collapsed tree children. |
+| `ownsEvent(event)` | `true` when an event came from this grid, `false` when from a grid nested in one of its master-detail panels. (3.6) |
 | undo/redo | `undo()`, `redo()`, `clearHistory()` (needs `editing.history.enabled`) |
 | state | `getState(options?)` → `GridState`, `setState(partial, options?)` → `SetStateResult`, `getSchema()` → `GridSchema` |
 | `ApexGrid.register()` / `ApexGrid.tagName` | Static element registration / `'apex-grid'`. |
@@ -367,7 +398,18 @@ Every event fires only for operations driven through the grid's own UI; programm
 | `rowPinning` / `rowPinned` | row pin / unpin (also fires for `pinRow()`/`unpinRow()`) |
 | `rowMoving` / `rowMoved` | row reorder (also fires for `moveRow()`) |
 
-**Exceptions to "UI-only".** The dedicated programmatic methods added for pagination (`gotoPage`, `nextPage`, …), quick-filter (`setQuickFilter`), column pinning (`pinColumn` / `unpinColumn`), row pinning (`pinRow` / `unpinRow`), and row reorder (`moveRow`) **do** emit their `*-ing` / `*-ed` pairs (unlike `sort()` / `filter()`, which stay silent).
+**Exceptions to "UI-only".** The dedicated programmatic methods added for pagination (`gotoPage`, `nextPage`, …), quick-filter (`setQuickFilter`), column pinning (`pinColumn` / `unpinColumn`), row pinning (`pinRow` / `unpinRow`), and row reorder (`moveRow`) **do** emit their `*-ing` / `*-ed` pairs (unlike `sort()` / `filter()`, which stay silent). Since 3.6, `setQuickFilter` also fires `pageChanged` when it moves the grid back to the first page; assigning the `quickFilter` property stays silent.
+
+**Timing (3.6).** `sorted`, `filtered`, `pageChanged` and `quickFilterChanged` fire after the pipeline run they caused, so a listener that reads `grid.dataView`, `grid.pageItems` or `grid.totalItems` sees the new rows, even with an async `dataPipelineConfiguration` hook. On 3.5 they could fire before an async hook resolved.
+
+**Nested grids (3.6).** Grid events bubble and are composed, so a listener on a grid also hears the events of a grid nested in one of its master-detail panels. Filter them inside the listener:
+
+```ts
+grid.addEventListener('cellValueChanged', (e) => {
+  if (!grid.ownsEvent(e)) return;          // came from a grid inside a detail panel
+  save(e.detail.data);
+});
+```
 
 Single-shot events (no `-ing` pair):
 
@@ -379,7 +421,7 @@ Single-shot events (no `-ing` pair):
 
 Operand reference, multi-column sort, and server-side hooks: `references/sort-and-filter.md` and `references/data-pipeline.md`. Row pinning/reorder, undo/redo, validators, column groups, state/schema, and localization: `references/state-and-features.md`.
 
-### Keyboard & accessibility (3.4, 3.5)
+### Keyboard & accessibility (3.4 and later)
 
 The grid ships full keyboard operation and screen-reader support out of the box; there's nothing to enable. The body uses a **roving-tabindex** focus model: the active cell is the body's single tab stop, so `Tab` moves into and out of the grid in one step, and real focus follows arrow-key navigation (screen readers track cell-to-cell movement).
 
@@ -388,12 +430,12 @@ The grid ships full keyboard operation and screen-reader support out of the box;
 | Arrow keys | Move the active cell one cell up / down / left / right |
 | Home / End | Move to the **first / last cell of the current row** |
 | Ctrl/Cmd+Home / Ctrl/Cmd+End | Jump to the grid's first / last cell |
-| PageUp / PageDown | Page-scroll by a viewport |
+| PageUp / PageDown | Move the active cell by the rows that fit in the visible body (below the sticky header and pinned rows) |
 | Enter or F2 | Open the active cell's editor (editing is no longer pointer-only) |
 
-Keyboard-driven commit (Enter) or cancel (Escape) returns focus to the cell, so navigation continues from where you left off.
+Keyboard-driven commit (Enter) or cancel (Escape) returns focus to the cell, so navigation continues from where you left off. Since 3.6.0, after tabbing into the body with no cell active yet, the first arrow, Home or PageUp key activates the first cell instead of moving past it (ArrowDown lands on row 0).
 
-**Editing behavior:** clearing a `number` or `currency` editor now commits `null` (previously it wrote `NaN`). An empty or unparseable numeric input leaves the cell empty rather than poisoning the row.
+**Editing behavior:** clearing a `number` or `currency` editor now commits `null` (previously it wrote `NaN`). An empty or unparseable numeric input leaves the cell empty rather than poisoning the row. Since 3.6.0 an open editor stays on the record it was opened for when the data, sort, filter or page change under it, and the edit is cancelled if that record leaves the view; row mode edits a staged copy (`references/state-and-features.md`).
 
 **Announcements:** sorting, filtering, selection, paging, row pinning, row reorder, expansion, and undo / redo each announce through a localized live region, and the host applies a localized `aria-label` ("Data grid") plus `aria-multiselectable` when multi-row selection is on. The strings are locale keys (`announce.*`, `header.*`, `grid.label`, `editor.rating`); override them via `localeText` (see `references/state-and-features.md`).
 
@@ -433,7 +475,7 @@ Arrow-key navigation, column resize and column reorder all follow inline order r
 
 ### 5. `column.key` not a real key of `T`
 ❌ `{ key: 'fullName' }` when `User` has only `firstName` + `lastName`.
-✅ Compute via template: `cellTemplate: ({ row }) => html\`${row.firstName} ${row.lastName}\``.
+✅ Compute via template: `cellTemplate: ({ row }) => html\`${row.data.firstName} ${row.data.lastName}\``. The context's `row` is the row element; the record is `row.data`.
 
 ### 6. String from `cellTemplate`
 ❌ `cellTemplate: ({ value }) => \`<strong>\${value}</strong>\`` — renders as escaped text.
@@ -449,12 +491,20 @@ Arrow-key navigation, column resize and column reorder all follow inline order r
 
 ### 9. Clearing sort/filter
 ❌ Assuming you must rebuild state to clear it.
-✅ `grid.clearSort()` / `grid.clearFilter()` (optionally per `key`).
+✅ `grid.clearSort()` / `grid.clearFilter()` (optionally per `key`), or `grid.sortExpressions = []` / `grid.filterExpressions = []` (3.6).
 
 ### 10. Expecting events from programmatic operations
 ❌ Listening for `sorting` after calling `grid.sort(...)` — never fires.
 ✅ Wrap the programmatic call yourself, or watch `grid.dataView` for any state change.
 
+### 11. Building a multi-column sort one assignment at a time
+❌ `grid.sortExpressions = [byCity]; grid.sortExpressions = [byAge];` expecting both: since 3.6 each assignment **replaces** the sort (the same for `filterExpressions`), so only `byAge` applies.
+✅ Assign the full list, `grid.sortExpressions = [byCity, byAge]`, or add with `grid.sort(byAge)` / `grid.filter(expr)`.
+
+### 12. Theming a dark grid with the light tokens
+❌ `apex-grid[theme='dark'] { --ag-surface: #111827; --ag-text: #f9fafb; }`: since 3.6 a dark grid ignores the light colour tokens, even on its own element.
+✅ `apex-grid { --ag-dark-surface: #111827; --ag-dark-text: #f9fafb; }` (or on any ancestor). Brand, sizing and typography tokens are shared, so `--ag-brand` still applies to both.
+
 ---
 
 ## 7. Reference Routing Table
@@ -464,6 +514,6 @@ Arrow-key navigation, column resize and column reorder all follow inline order r
 | Column types, templates, auto-generation, per-column styling, header/editor templates | `references/columns-and-templates.md` |
 | Sort & filter — operands, expressions, multi-column, quick-filter, events | `references/sort-and-filter.md` |
 | Server-side data hooks (sort/filter/pagination/quickFilter), virtualization, `dataView` | `references/data-pipeline.md` |
-| Row pinning / reordering, undo-redo, batch edits (`applyEdits`), validators, column groups, state & schema (`getState`/`setState`/`getSchema`), localization, export source | `references/state-and-features.md` |
+| Row pinning / reordering, undo-redo, batch edits (`applyEdits`), validators, row-mode editing, column groups, state & schema (`getState`/`setState`/`getSchema`), localization, export source and CSV escaping, master-detail parts and nested grids (`exportParts`, `ownsEvent`) | `references/state-and-features.md` |
 | End-to-end vanilla JS (no Lit `render`) | `references/vanilla-js.md` |
 | Lit, React, Vue, Angular integration | `references/framework-integration.md` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apexgrid-skill",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "AI coding skill for the apex-grid web component — structured reference docs that help AI assistants (Claude, Cursor, Copilot, etc.) generate correct apex-grid code.",
   "keywords": [
     "apex-grid",

package/references/columns-and-templates.md

@@ -45,7 +45,7 @@ interface BaseColumnConfiguration<T extends object, K extends keyof T = keyof T>
 
 ### Column types (`DataType`)
 
-`'string'` / `'number'` / `'boolean'` are the primitive types driving sort, filter, and the default editor. The rest are presentation renderers over a primitive value (and sort/filter as that value): `'select'` (label from `options`, `<select>` editor), `'rating'` (stars, 0..`max`), `'date'` (locale date via `format`; accepts `Date`/ISO/timestamp; `<input type="date">` editor), `'image'` (`<img>`, `shape`/`alt`), `'currency'` (`Intl.NumberFormat`, `currency`/`locale`), `'avatar'`, `'badge'` (`badgeVariant`), `'progress'` (0..`max`), `'sparkline'` (`number[]`, `showDelta`), `'status'` (`statusVariant`).
+`'string'` / `'number'` / `'boolean'` are the primitive types driving sort, filter, and the default editor. The rest are presentation renderers over a primitive value (and sort/filter as that value): `'select'` (label from `options`, `<select>` editor), `'rating'` (stars, 0..`max`), `'date'` (locale date via `format`; accepts `Date`/ISO/timestamp; `<input type="date">` editor), `'image'` (`<img>`, `shape`/`alt`), `'currency'` (`Intl.NumberFormat`, `currency`/`locale`), `'avatar'`, `'badge'` (`badgeVariant`), `'progress'` (0..`max`), `'sparkline'` (`number[]`, `showDelta`), `'status'` (`statusVariant`). Of these, `'currency'`, `'rating'` and `'progress'` are numeric: since 3.6 they filter with the number operands and export as numbers, like `'number'`.
 
 Defaults applied on assignment (`DEFAULT_COLUMN_CONFIG`):
 
@@ -61,7 +61,7 @@ Defaults applied on assignment (`DEFAULT_COLUMN_CONFIG`):
 | `'number'` | numeric `<` / `>` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
 | `'boolean'` | `false < true` | `all`, `true`, `false`, `empty`, `notEmpty` |
 
-The table above lists the three **primitive** types. The presentation types (`'select'`, `'rating'`, `'date'`, `'image'`, `'currency'`, `'avatar'`, `'badge'`, `'progress'`, `'sparkline'`, `'status'`) sort and filter as their underlying value. For dates, use the real `'date'` type — it accepts `Date`, ISO strings, or millisecond timestamps, renders a locale date (`format`), and sorts chronologically. No timestamp/comparer workaround needed:
+The table above lists the three **primitive** types. The presentation types (`'select'`, `'rating'`, `'date'`, `'image'`, `'currency'`, `'avatar'`, `'badge'`, `'progress'`, `'sparkline'`, `'status'`) sort as their underlying value. For filtering, `'currency'`, `'rating'` and `'progress'` take the `'number'` operands (since 3.6; on 3.5 they took the text ones), and the others take the `'string'` operands. With the built-in comparison, empty cells (`null`, `undefined`, `NaN`, invalid `Date`) sort last in both directions (3.6). For dates, use the real `'date'` type: it accepts `Date`, ISO strings, or millisecond timestamps, renders a locale date (`format`), and sorts chronologically. No timestamp/comparer workaround needed:
 
 ```ts
 { key: 'createdAt', type: 'date', format: 'medium', sort: true, filter: true }
@@ -83,7 +83,7 @@ The table above lists the three **primitive** types. The presentation types (`'s
 }
 ```
 
-The `comparer` signature is fully typed against `T[K]`.
+The `comparer` signature is fully typed against `T[K]`. Since 3.6 it receives the **raw** cell values, original casing and `null` / `undefined` included, and owns their order (a descending sort reverses its result). On 3.5 it received strings already lower-cased (unless `caseSensitive`), so a lookup written in the data's casing (`'High'`, `'Low'`) never matched and the sort did nothing. Now the lookup above matches only values stored in lower case: write it in the data's own casing, and decide where empty values go.
 
 ## Filter configuration per column
 
@@ -101,12 +101,15 @@ Receives `ApexCellContext<T, K>`:
 ```ts
 interface BaseApexCellContext<T, K> {
   parent: ApexGridCell<T>;          // <apex-grid-cell> element
-  row:    ApexGridRow<T>;           // <apex-grid-row> element
+  row:    ApexGridRow<T>;           // <apex-grid-row> element; the record is row.data
   column: ColumnConfiguration<T, K>;
   value:  T[K];                     // T[K] — fully typed
+  commit?: (value: T[K]) => Promise<boolean>;   // editable columns only: write without opening the editor
 }
 ```
 
+Since 3.6 a `cellTemplate` runs again for every visible row, body and pinned, after each pipeline run (sort, filter, quick filter, edit, tree toggle), so a template that reads other fields of `row.data` stays current after an edit to another cell. Keep templates cheap; plain and typed cells are not re-rendered this way. In row edit mode, `commit(value)` stages the value with the row edit instead of writing straight to the record (3.6), so `cancelEdit()` rolls it back.
+
 ```ts
 import { html } from 'lit';
 
@@ -118,11 +121,11 @@ const columns: ColumnConfiguration<User>[] = [
   { key: 'name',
     cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
 
-  // Conditional render with row context
+  // Conditional render with row context (row is the element, row.data the record)
   { key: 'subscribed', type: 'boolean',
     cellTemplate: ({ value, row }) => html`
       <input type="checkbox" .checked=${value} disabled />
-      <small>${row.name}</small>` },
+      <small>${row.data.name}</small>` },
 
   // Prefer the built-in type over a template where one exists:
   // `avatar` and `rating` are column types, no template needed.
@@ -173,7 +176,7 @@ import { required, min, max, pattern, custom } from 'apex-grid';
   validators: [custom((value, ctx) => (value === ctx.data.id ? 'Cannot equal id' : null))] }
 ```
 
-Built-in factories: `required(message?)`, `min(limit, message?)`, `max(limit, message?)`, `pattern(regex, message?)`, `custom(fn)`. `min`/`max`/`pattern` pass on empty / non-numeric values — compose with `required`. See `references/state-and-features.md` for the `Validator` / `ValidatorContext` shapes and the `cellValidationFailed` payload.
+Built-in factories: `required(message?)`, `min(limit, message?)`, `max(limit, message?)`, `pattern(regex, message?)`, `custom(fn)`. `min`/`max`/`pattern` pass on empty / non-numeric values, so compose with `required`. In row edit mode `ctx.data` is the staged row (the record with the row's pending values applied) since 3.6, so a cross-field rule such as `ctx.data.end >= ctx.data.start` sees the row being saved. See `references/state-and-features.md` for the `Validator` / `ValidatorContext` shapes and the `cellValidationFailed` payload.
 
 **Numeric editing (3.4):** clearing a `number` or `currency` editor now commits `null`, not `NaN`. An empty or unparseable numeric input leaves the cell empty instead of writing `NaN` into the row. Editing also opens from the keyboard now (Enter or F2 on the active cell), not only by pointer; see SKILL.md §5 for the full keyboard model. Separately, a spreadsheet-style error value (an object carrying a `#...` code, such as an enterprise formula engine's `#VALUE!`) renders as its code in typed `number` / `currency` columns rather than coercing to `NaN` and showing an empty cell.
 
@@ -246,7 +249,8 @@ The grid renders a drag handle on the right edge of the column header. Minimum r
 
 | ❌ | ✅ |
 |---|---|
-| `{ key: 'fullName' }` when `fullName` isn't in `T` | Add to `T`, or compute via `cellTemplate: ({ row }) => html\`${row.firstName} ${row.lastName}\`` |
+| `{ key: 'fullName' }` when `fullName` isn't in `T` | Add to `T`, or compute via `cellTemplate: ({ row }) => html\`${row.data.firstName} ${row.data.lastName}\`` |
+| `cellTemplate: ({ row }) => row.name` | `row` is the `<apex-grid-row>` element: read the record as `row.data.name` |
 | `cellTemplate: ({ value }) => \`<b>\${value}</b>\`` (string) | `cellTemplate: ({ value }) => html\`<b>\${value}</b>\`` |
 | `{ key: 'age', sort: true }` (default `type: 'string'`) | Set `type: 'number'` |
 | `{ key: 'created', type: 'string', sort: { comparer } }` to fake dates | `{ key: 'created', type: 'date', format: 'medium' }` — a real type (accepts `Date`/ISO/timestamp) |

package/references/data-pipeline.md

@@ -66,7 +66,7 @@ The grid runs the stages in a fixed order: **quick-filter → column filter →
 
 ### Hooks fire on every state change
 
-The pipeline runs whenever `data`, `columns`, sort state, or filter state changes — including programmatic `sort()` / `filter()` calls. If your server endpoint is expensive, debounce inside the hook:
+The pipeline runs whenever `data`, `columns`, sort state, or filter state changes, including programmatic `sort()` / `filter()` calls. Since 3.6 only the latest run's result is applied: a slower earlier run that resolves after a newer one is discarded, and no longer holds back the newer run's events. If your server endpoint is expensive, still abort or debounce inside the hook, so the superseded requests are not sent at all:
 
 ```ts
 let pending: AbortController | null = null;
@@ -143,6 +143,10 @@ grid.addEventListener('sorted', updateSummary);
 grid.addEventListener('filtered', updateSummary);
 ```
 
+Since 3.6 this is reliable with async hooks too: `sorted`, `filtered`, `pageChanged` and `quickFilterChanged` fire after the pipeline run they caused, so `dataView` already holds the new rows. On 3.5 they could fire before an async hook resolved and read the previous view. (They remain UI-only, except the page and quick-filter methods listed in SKILL.md §5.)
+
+Assigning `grid.data = null` or `undefined` (a framework prop still loading) shows an empty grid and reads back as `[]` since 3.6; on 3.5 it threw and kept the previous rows.
+
 ## Common pitfalls
 
 | ❌ | ✅ |

package/references/framework-integration.md

@@ -19,7 +19,7 @@ import { setup } from 'apex-grid';
 setup();                         // registers <apex-grid> + adopts a bounded host height
 ```
 
-No theme import needed — the grid self-styles. Retheme by overriding `--ag-*` CSS variables on `apex-grid`. If you prefer manual control over sizing, call `setup({ hostStyles: false })` (or use `import 'apex-grid/define'`) and add your own rule:
+No theme import needed: the grid self-styles. Retheme by overriding `--ag-*` CSS variables on `apex-grid` or on any ancestor (an app shell, a component's shadow host), and use the `--ag-dark-*` variables for grids with `theme="dark"` (SKILL.md §1.3). If you prefer manual control over sizing, call `setup({ hostStyles: false })` (or use `import 'apex-grid/define'`) and add your own rule:
 
 ```css
 apex-grid {
@@ -109,7 +109,7 @@ export function UsersGrid({ data }: { data: User[] }) {
 }
 ```
 
-If you'd rather size per instance instead of globally, replace the global CSS rule with a `style` prop: `style={{ height: '500px', display: 'block' }}`.
+If you'd rather size per instance instead of globally, replace the global CSS rule with a `style` prop: `style={{ height: '500px' }}`. Never add `display` there: the grid needs its own `display: grid`, collapses without it, and logs a console warning on first render when something overrides it.
 
 For full TypeScript / JSX intrinsic-element support:
 

package/references/sort-and-filter.md

@@ -35,25 +35,39 @@ grid.sort({
 });
 ```
 
-`grid.sort(...)` does **not** fire `sorting` / `sorted` events.
+`grid.sort(...)` does **not** fire `sorting` / `sorted` events. It **adds** to the current sort (a key already sorted is updated in place); to replace the sort, assign `sortExpressions`.
 
-### Reading the active sort state
+### How rows compare
+
+With the built-in comparison, strings compare with `localeCompare` (case folded unless `caseSensitive: true`) and other values with `<` / `>`. Since 3.6:
+
+- **Empty cells** (`null`, `undefined`, `NaN`, an invalid `Date`) sort after every real value in **both** directions. Rows that tie keep their incoming order (a stable sort).
+- **A custom `comparer` receives the raw cell values**, original casing and empty values included, and owns their order; a descending sort reverses its result. On 3.5 it received strings already lower-cased, so a lookup comparer over mixed-case values (`'High'`, `'Low'`) ranked every row the same. Write the lookup in the data's own casing, and decide where `null` goes.
+
+### Reading and assigning the sort state
 
 ```ts
 grid.sortExpressions;            // SortExpression<T>[]
+
+grid.sortExpressions = [         // 3.6: REPLACES the current sort
+  { key: 'subscribed', direction: 'descending' },
+  { key: 'age',        direction: 'ascending' },
+];
+grid.sortExpressions = [];       // clears it (so does null)
 ```
 
 The array is in the order operations were applied (insertion order on the underlying `Map`).
 
+> **Changed in 3.6.0:** assigning `sortExpressions` replaces the sort, as `setState` does; on 3.5 it merged into it and `[]` was a no-op. Code that assigned one expression at a time to build a multi-column sort now keeps only the last one: assign the full list, or call `grid.sort()`, which still adds. The list applies at the next update against the columns as they are then, so a framework template may bind `sortExpressions` before `columns`. Entries naming an unknown column, or with an unknown direction, are dropped with a console warning (an omitted direction sorts ascending).
+
 ### Clearing sort
 
 ```ts
 grid.clearSort();                // clear everything
 grid.clearSort('name');          // clear only the `name` column
+grid.sortExpressions = [];       // 3.6: same as clearSort()
 ```
 
-> **Heads-up:** assigning an empty array (`grid.sortExpressions = []`) is a no-op. Always call `clearSort()` to reset.
-
 ### `sortConfiguration`
 
 ```ts
@@ -72,25 +86,29 @@ interface BaseFilterExpression<T, K extends keyof T> {
   key: K;
   condition: FilterOperation<T[K]> | OperandKeys<T[K]>;   // operand object or string key
   searchTerm?: T[K];                                       // optional for unary operands (empty / notEmpty / true / false / all)
-  criteria?: 'and' | 'or';                                 // for combining with previous expression on same column
+  criteria?: 'and' | 'or';                                 // default 'and'; combines expressions of the SAME column
   caseSensitive?: boolean;                                 // overrides column config
 }
 ```
 
+Within one column, a row passes when **all** of its `and` expressions pass **or any one** of its `or` expressions passes. Columns always combine with AND: criteria never reach across columns (3.6; on 3.5 an `or` on one column could cancel the `or` conditions of another).
+
 ### Operand sets
 
 ```ts
 import { StringOperands, NumberOperands, BooleanOperands } from 'apex-grid';
 ```
 
-| Type | Operand keys |
+| Column `type` | Operand keys |
 |---|---|
-| `'string'` | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
-| `'number'` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
+| `'string'` and every other type not listed below | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
+| `'number'`, `'currency'`, `'rating'`, `'progress'` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
 | `'boolean'` | `all`, `true`, `false`, `empty`, `notEmpty` |
 
 Unary operands (no `searchTerm` needed): `empty`, `notEmpty`, `all`, `true`, `false`.
 
+Since 3.6 the numeric presentation types `currency`, `rating` and `progress` take the number operands (on 3.5 they took the text ones). A condition name that does not belong to the column's set, such as `contains` on a `currency` column, is dropped with a console warning, from `filter()` and from a saved state alike. Text conditions read `null` / `undefined` as empty text and match other values (numbers, dates) on their text instead of throwing, and the range conditions (`greaterThan`, `lessThan`, ...) no longer match an empty cell as if it were 0.
+
 ### Programmatic filter
 
 ```ts
@@ -120,14 +138,21 @@ grid.filter([
 ]);
 ```
 
-`grid.filter(...)` does **not** fire `filtering` / `filtered` events.
+`grid.filter(...)` does **not** fire `filtering` / `filtered` events. Like `grid.sort()`, it **adds** to the current filter; assign `filterExpressions` to replace it.
 
-### Reading the active filter state
+### Reading and assigning the filter state
 
 ```ts
 grid.filterExpressions;          // FilterExpression<T>[]
+
+grid.filterExpressions = [       // 3.6: REPLACES the current filter
+  { key: 'age', condition: 'greaterThan', searchTerm: 30 },
+];
+grid.filterExpressions = [];     // clears it (so does null)
 ```
 
+Assignment follows the same 3.6 rules as `sortExpressions`: it replaces (3.5 merged, and `[]` was a no-op), applies at the next update, and assigning a list equal to the current one (a wrapper that re-binds it on every render) keeps the scroll position. Any other filter change scrolls the grid back to its first row.
+
 Combined across columns. To get state for a single column, find by `key`:
 
 ```ts
@@ -175,6 +200,8 @@ grid.addEventListener('filtered', (e) => {
 | `filtering` | yes | `{ key, expressions, type }` | no |
 | `filtered` | no | `{ key, state }` | no |
 
+Since 3.6, `sorted` and `filtered` fire after the pipeline run they caused, so a listener reading `grid.dataView` or `grid.totalItems` sees the new rows, even when a `dataPipelineConfiguration` hook is async. On 3.5 they fired after the next render, which could come before an async hook resolved.
+
 If you need a side-effect on every change regardless of source, watch `grid.dataView` (after `requestUpdate` / via `updated()` in a Lit parent) or wrap your programmatic calls.
 
 ## Combining UI + programmatic operations
@@ -186,18 +213,22 @@ UI operations and programmatic operations write to the **same underlying state**
 const savedSort = grid.sortExpressions;
 const savedFilter = grid.filterExpressions;
 
-// ... later, after re-mounting
-grid.sort(savedSort);
-grid.filter(savedFilter);
+// ... later, after re-mounting: assignment replaces whatever is there (3.6)
+grid.sortExpressions = savedSort;
+grid.filterExpressions = savedFilter;
 ```
 
+`grid.sort(savedSort)` / `grid.filter(savedFilter)` would add onto any sort or filter already applied instead. For a full snapshot (columns, paging, selection too), use `getState()` / `setState()` (`references/state-and-features.md`).
+
 ## Common pitfalls
 
 | ❌ | ✅ |
 |---|---|
 | Listening for events on programmatic calls | Wrap the call yourself, or watch `grid.dataView` |
-| `grid.filter({ key: 'age', condition: 'contains' })` (string operand on number column) | Match operand to type — `condition: 'greaterThan'` for number columns |
-| `grid.sortExpressions = []` to clear | `grid.clearSort()` |
+| `grid.filter({ key: 'age', condition: 'contains' })` (string operand on number column) | Match operand to type: `condition: 'greaterThan'` for `number`, `currency`, `rating` and `progress` columns (a mismatched name is dropped with a console warning) |
+| `grid.sortExpressions = [a]; grid.sortExpressions = [b];` to build a two-column sort | Each assignment replaces (3.6): assign `[a, b]`, or `grid.sort(b)` to add |
+| Restoring with `grid.sort(saved)` onto a grid that already has a sort | `grid.sortExpressions = saved` replaces it (3.6) |
+| A `comparer` that expects lower-cased strings | Since 3.6 it receives raw values (original casing, `null` included) |
 | Multi-column sort with `sortConfiguration.multiple = false` | Either set `multiple: true` or call `grid.sort` with a single expression |
 | Forgetting `searchTerm` on a non-unary operand | Add `searchTerm`, or use a unary operand (`empty` / `notEmpty` / `true` / `false` / `all`) |
 | Mutating `e.detail` in a `sorted` / `filtered` listener | Only `sorting` / `filtering` are cancellable / mutable; the post-events are read-only by design |

package/references/state-and-features.md

@@ -1,6 +1,6 @@
 # State, Localization & Interaction Features (3.1+)
 
-> Everything here landed in **apex-grid 3.1 – 3.4** on top of the 3.0 API. The setup rules from `SKILL.md` (register + bounded host height, no theme import) still apply. Row pinning / reordering, undo-redo, and validators are all **opt-in** via a config object — off by default.
+> Everything here landed in **apex-grid 3.1 and later** on top of the 3.0 API; version tags mark what is newer. The setup rules from `SKILL.md` (register + bounded host height, no theme import) still apply. Row pinning / reordering, undo-redo, and validators are all **opt-in** via a config object, off by default.
 
 ## Row pinning — sticky top / bottom bands
 
@@ -21,7 +21,7 @@ grid.pinnedRows;                                // getter → { top: T[]; bottom
 | `unpinRow(row)` | `(T) => boolean` | No-op (returns `true`) when not pinned. |
 | `pinnedRows` *(getter)* | `{ top: T[]; bottom: T[] }` | In pin order. |
 
-Events: `rowPinning` (cancellable) → `rowPinned`, both `CustomEvent<{ row: T; position: 'top' | 'bottom' | null }>` (`null` when unpinning). Pins survive sort / filter / pagination as long as row identity is preserved; re-pin after a wholesale `data` swap.
+Events: `rowPinning` (cancellable) → `rowPinned`, both `CustomEvent<{ row: T; position: 'top' | 'bottom' | null }>` (`null` when unpinning). Pins survive sort / filter / pagination as long as row identity is preserved. Since 3.6, replacing `grid.data` carries the pins onto the new rows: matched by `rowId` when it is set, otherwise a pin whose object left the data is dropped (re-pin those). While `rowPinning.enabled` is `false`, `pinnedRows` reports none and the rows return to the body, but the pins are kept (`getState` still saves them) and come back when pinning is re-enabled.
 
 ## Row reordering — drag / keyboard / API
 
@@ -36,7 +36,26 @@ grid.moveRow(2, 0, 'before');                   // (from, to, position?: 'before
 | `applyToData` | `boolean` | `false` | `true` also splices `grid.data` in place; otherwise the order lives in the grid and you persist via `rowMoved`. |
 | `handle` | `boolean` | `true` | `true` renders a leading grip cell (drag only from it); `false` drags from anywhere on the row. |
 
-`moveRow(from, to, position?)` indices are into `grid.pageItems`; returns `boolean`. A manual order is **mutually exclusive with column sorting** — applying a sort clears it. Events: `rowMoving` (cancellable) → `rowMoved`, both `CustomEvent<{ from: number; to: number; data: T }>`.
+`moveRow(from, to, position?)` indices are into `grid.pageItems`; returns `boolean`, `false` when disabled, out of range, cancelled, or (3.6) a no-op move that would leave the row where it is, which fires no events. A manual order is **mutually exclusive with column sorting**: applying a sort clears the manual order, and since 3.6 a move on a sorted grid clears the sort and keeps the moved order (on 3.5 an `applyToData` move was undone by the re-sort). Rows hidden by a filter keep their place when a visible row moves, and replacing `grid.data` carries the order onto the new rows (by `rowId` when set).
+
+Events: `rowMoving` (cancellable) → `rowMoved`, both `CustomEvent<ApexRowMovingEvent<T>>`:
+
+```ts
+interface ApexRowMovingEvent<T> {
+  from: number;                     // view index before the move
+  to: number;                       // the target row's view index
+  position: 'before' | 'after';     // 3.6: which side of the target it lands
+  toIndex: number;                  // 3.6: the view index it lands at (moveRow(0, 3) lands at 2)
+  data: T;                          // the moved record
+}
+
+// Mirror a move in your own array ordered like the view (the indices are view indices):
+grid.addEventListener('rowMoved', ({ detail: { from, toIndex } }) => {
+  order.splice(toIndex, 0, ...order.splice(from, 1));
+});
+```
+
+Pressing Escape after keyboard grab-and-move steps restores the original order (and `grid.data` with `applyToData`, and any sort) and fires `rowMoved` for the way back, so a persisted order stays in sync.
 
 ## Inline-edit undo / redo
 
@@ -52,6 +71,8 @@ grid.canUndo;  grid.canRedo;                    // getters (false unless history
 
 `stackSize` defaults to `100` (older commands evicted past the cap). Event: `historyChanged` — `CustomEvent<{ canUndo: boolean; canRedo: boolean }>`, fires after any record / undo / redo / clear (drive toolbar button enablement from it).
 
+**Data reloads (3.6).** Replacing `grid.data` with new records clears the history and fires `historyChanged`; before, undo replayed onto the old, detached objects and nothing changed on screen. Data that keeps the edited records, such as `grid.data = [...grid.data, newRow]`, keeps its history, and so do in-place edits. A `cellValueChanged` fired by undo / redo reports `rowIndex: -1` when the record is pinned or on another page, so identify the row by `event.detail.data`, not by index.
+
 ## Batch edits: `applyEdits()` (3.5)
 
 Writes many cells as a single operation. Each write still goes through the same choke point interactive editing uses, so it emits the cancellable `cellValueChanging` and then `cellValueChanged`, and runs the column's validators. What differs from looping `editCell` + `commitEdit` is that the whole set lands as **one undo step and one pipeline run**: a thousand round-trips would otherwise mean a thousand undo entries and a thousand re-renders.
@@ -62,9 +83,17 @@ const tally = grid.applyEdits([
   { rowIndex: 3, column: 'discount', value: 0 },
 ]);
 // { applied: 2, unchanged: 0, invalid: 0, cancelled: 0, skipped: 0 }
+
+// 3.6: name the row by record to reach every selected row, on any page
+grid.applyEdits(grid.selectedRows.map((row) => ({ row, column: 'discount', value: 0 })));
 ```
 
-`rowIndex` is **view-relative** and matches `grid.pageItems`, the same as `editCell`. Order is preserved, so a later edit to the same cell wins.
+Each entry names its row one of two ways:
+
+- `rowIndex` is **view-relative** and matches `grid.pageItems`, the same as `editCell`, so it reaches the current page only. It must be a whole number from `0` to `pageItems.length - 1`.
+- `row` (3.6) is the record itself, the same object held in `grid.data`. It also reaches rows on other pages, pinned rows and rows under a collapsed tree parent; the events and validators for those see `rowIndex` -1.
+
+Order is preserved, so a later edit to the same cell wins.
 
 It returns a per-outcome tally rather than a count, because "nothing changed" and "everything was rejected" are different answers:
 
@@ -74,7 +103,7 @@ It returns a per-outcome tally rather than a count, because "nothing changed" an
 | `unchanged` | The cell already held that value. |
 | `invalid` | A `column.validators` rule rejected it. |
 | `cancelled` | A `cellValueChanging` listener called `preventDefault()`. |
-| `skipped` | Unknown column, `rowIndex` out of range, or a column the user could not edit either (editing off, not `editable`, or hidden). |
+| `skipped` | Unknown column, a `rowIndex` that is negative, fractional or past the end of the page (3.5 counted a negative index from the end and rounded a fraction down), or a column the user could not edit either (editing off, not `editable`, or hidden). |
 
 Skipping rather than throwing means a partially stale batch still applies what it can. Needs `editing.enabled` and per-column `editable`, the same gate as interactive editing; without `editing.history.enabled` the batch simply is not recorded.
 
@@ -110,8 +139,15 @@ type Validator<T, K> = (value: unknown, context: ValidatorContext<T, K>) => stri
 interface ValidatorContext<T, K> { column: ColumnConfiguration<T, K>; data: T; rowIndex: number; }
 ```
 
+`rowIndex` is view-relative, or -1 for a pinned row or a record on another page (3.6). In row edit mode `ctx.data` is the **staged row** (3.6): a copy of the record (same prototype) with the row's staged values applied, so a cross-field rule judges the row being saved rather than the stored record. A row commit also re-validates the row's other editable cells against it.
+
 Event: `cellValidationFailed` — `CustomEvent<{ key; rowIndex; data: T; value: unknown; errors: readonly string[] }>`.
 
+## Editing behaviour (3.6)
+
+- **Row mode edits a staged row.** The cells of the row in edit show their staged values. A boolean checkbox click, or a `cellTemplate` calling `ctx.commit(value)`, joins the row edit instead of writing straight to the record, so `cancelEdit()` rolls it back and `commitEdit()` writes it with the rest. Every cell passes validation and its `cellValueChanging` gate before any is written: one invalid or cancelled cell aborts the whole row.
+- **An open editor stays on its record.** When the data, sort, filter or page changes while a cell is in edit, the editor follows the record it was opened for (on 3.5 it could jump to another row, and Enter wrote into the wrong record). The edit is cancelled when that record leaves the view (removed, filtered out, or replaced by a copy). `editingCell`, `editingRow` and the `rowIndex` of the edit events are -1 while the record is pinned or on another page; identify it by the event's `data`.
+
 ## Column groups — spanning headers
 
 A presentational header layer above the column header row. `columns` stays flat; a column joins a group via its `group` id. Members must be **contiguous within one pin region** (the grid warns and skips the spanning cell otherwise). v1 ships static spanning headers only (`collapsible` is reserved / inert).
@@ -163,7 +199,7 @@ interface GetStateOptions<T> { rowId?: (row: T) => string | number; }
 interface SetStateOptions<T> { rowId?: (row: T) => string | number; strict?: boolean; }
 ```
 
-Event: `stateChanged` — `CustomEvent<{ state: GridState }>`, debounced after the render pipeline settles. Fires for programmatic (including `setState`) and UI changes. The payload is only computed while a listener is attached (zero-cost otherwise); identical snapshots don't re-fire, so compare before persisting to avoid a save loop.
+Event: `stateChanged`: `CustomEvent<{ state: GridState }>`, debounced after the render pipeline settles. Fires for programmatic (including `setState`) and UI changes. The payload is only computed while a listener is attached (zero-cost otherwise); identical snapshots don't re-fire, so compare before persisting to avoid a save loop. Attach the listener to the grid element itself: the grid counts only listeners registered on it, so a delegated listener on an ancestor receives nothing while none is attached to the grid.
 
 ## Programmatic pagination, quick-filter, and column pinning
 
@@ -181,7 +217,7 @@ await grid.pinColumn('name', 'start');   // 'start' | 'end' | null
 await grid.unpinColumn('actions');       // = pinColumn(key, null)
 ```
 
-`gotoPage` / `setPageSize` / `nextPage` / `previousPage` / `firstPage` / `lastPage` emit `pageChanging` → `pageChanged`. `setQuickFilter` emits `quickFilterChanging` → `quickFilterChanged`. `pinColumn` / `unpinColumn` emit `columnPinning` → `columnPinned` and only change the visual render order (the `columns` array isn't reordered).
+`gotoPage` / `setPageSize` / `nextPage` / `previousPage` / `firstPage` / `lastPage` emit `pageChanging` → `pageChanged`. `setQuickFilter` emits `quickFilterChanging` → `quickFilterChanged`, plus (3.6) `pageChanged` when it moves the grid back to the first page. Since 3.6 the `*-ed` events fire after the pipeline run they caused, so awaiting the returned promise, or reading `grid.pageItems` in the listener, sees the new rows even with an async pipeline hook. `pinColumn` / `unpinColumn` emit `columnPinning` → `columnPinned` and only change the visual render order (the `columns` array isn't reordered).
 
 ## Localization — `localeText`
 
@@ -200,6 +236,8 @@ Exports: `EN_LOCALE` (the default dictionary / source of truth for keys), `esLoc
 
 **3.4 key changes** (both English and Spanish): the accessibility work added live-region announcement keys (`announce.*`, e.g. `announce.sortedAscending`, `announce.page`, `announce.rowSelected`, `announce.undoOne`), header control / sort-state labels (`header.*`, e.g. `header.sortedAscending`, `header.filterColumn`, `header.columnMenu`), the host label `grid.label` ("Data grid"), and `editor.rating`. The `ai.noAdapter` key was **removed** (drop it from any `localeText` override you kept). `EN_LOCALE` remains the source of truth for the full, current key list.
 
+**3.6 key additions** (English and Spanish) are used only by enterprise panels: `toolPanel.valueColumn`, `toolPanel.columnLabelColumn`, `chart.mapCategoryNone`, `setFilter.more`, `pivot.columnsTruncated`. A partial `localeText` map needs none of them; a full translation typed as `Record<GridLocaleKey, string>` must add them to compile.
+
 ## Column menu & column separator
 
 | Property | Type | Default | Notes |
@@ -220,13 +258,45 @@ grid.columnSeparator = false;
 |---|---|
 | `'view'` *(default)* | post-filter, post-sort rows across all pages |
 | `'page'` | current page slice only |
-| `'selected'` | current row selection (insertion order) |
+| `'selected'` | the selected rows in the order the grid shows them, then selected rows the view hides (3.6; on 3.5, selection order) |
 | `'all'` | the raw `data` array |
 
 ```ts
 grid.exportToCSV();                                       // download data.csv (view)
 grid.exportToCSV({ filename: 'users', source: 'selected' });
 const text = grid.exportToCSV({ filename: '' });          // string only, no download
+grid.exportToCSV({ escapeFormulas: false });              // 3.6: opt out of formula escaping
 ```
 
-`exportFormats` *(getter)* → `readonly ExportFormat[]` (`{ id, label }`) — the community grid offers CSV only; it drives the toolbar export menu, one item per entry, dispatching to `exportAs(formatId, options?)`. Other `ExportOptions` fields: `columns?` (keys to include), `includeHeader?` (default `true`), `formatter?`; CSV adds `delimiter?` (`','`), `bom?` (`true`), `newline?` (`'\r\n'`).
+`exportFormats` *(getter)* → `readonly ExportFormat[]` (`{ id, label }`). The community grid offers CSV only; it drives the toolbar export menu, one item per entry, dispatching to `exportAs(formatId, options?)`. Other `ExportOptions` fields: `columns?` (narrows to these keys among the visible, exportable columns, kept in display order), `includeHeader?` (default `true`), `formatter?`; CSV (`CSVExportOptions`) adds `delimiter?` (`','`), `bom?` (`true`), `newline?` (`'\r\n'`), `escapeFormulas?` (`true`, 3.6).
+
+**Export output changes in 3.6:**
+
+- **Formula escaping.** A CSV text cell or header that starts with `=`, `+`, `-`, `@`, a tab or a carriage return is written with a leading apostrophe, so a spreadsheet shows it as text instead of running it. Numbers are untouched, and so is text that is a plain signed decimal (`-5`, `+1.5`). Other text with a leading sign gains the apostrophe too: a phone number such as `+44 20 7946 0958`, or formatter output such as `-$5.00`. Pass `escapeFormulas: false` for the 3.5 output.
+- **Typed values.** `boolean` columns export `true` only for the value `true` (as the checkbox shows), so strings such as `'false'` or `'yes'` and the number `1` export as `false`. `currency` and `progress` columns export as numbers, like `number` and `rating`; a value that is not a number exports as an empty cell.
+
+## Master-detail: styling detail content and nested grids (3.6)
+
+Parts used inside your own `detailTemplate` content are not reachable with `apex-grid::part()` until you list them in `expansion.exportParts`. The panel itself is always reachable as `detail-panel`.
+
+```ts
+grid.expansion = {
+  enabled: true,
+  exportParts: ['order-summary'],
+  detailTemplate: ({ data }) => html`<div part="order-summary">${data.total}</div>`,
+};
+```
+
+```css
+apex-grid::part(detail-panel)  { padding: 12px; }
+apex-grid::part(order-summary) { font-weight: 600; }
+```
+
+A grid rendered inside a detail panel is nested in the outer grid's rows, and grid events bubble and are composed, so a listener on the outer grid also receives the inner grid's events (`cellValueChanged`, `rowSelected`, `sorted`, ...). `grid.ownsEvent(event)` returns `true` only for the grid's own events; call it inside the listener, while the event is dispatching. The grid applies the same test to its own interactions, so since 3.6 clicks, Space selection, Ctrl+Z and pointer drags in a nested grid no longer drive the outer one.
+
+```ts
+outer.addEventListener('rowSelected', (e) => {
+  if (!outer.ownsEvent(e)) return;          // a nested grid's selection
+  updateToolbar(outer.selectedRows);
+});
+```

package/references/vanilla-js.md

@@ -134,13 +134,16 @@ grid.clearSort();
 grid.clearFilter();
 ```
 
-Programmatic calls don't fire `sorting` / `sorted` / `filtering` / `filtered` events. If you need a hook for every state change regardless of source, watch `grid.dataView` after each programmatic call:
+Programmatic calls don't fire `sorting` / `sorted` / `filtering` / `filtered` events. If you need a hook for every state change regardless of source, read `grid.dataView` once the grid has updated after each programmatic call:
 
 ```js
 grid.sort({ key: 'age', direction: 'descending' });
-queueMicrotask(() => console.log('post-sort:', grid.dataView));
+await grid.updateComplete;                 // the in-memory pipeline has run by now
+console.log('post-sort:', grid.dataView);
 ```
 
+A `queueMicrotask` callback is too early: it runs before the pipeline assigns the new view. With an async `dataPipelineConfiguration` hook the new rows exist only once your hook resolves, so act on them there.
+
 ---
 
 ## 5. Common vanilla-JS gotchas