apex-grid 3.4.0 → 3.6.0

package/README.md

@@ -29,7 +29,7 @@ A Lit-based, framework-agnostic web component data grid. Ships as a single custo
 - **CSV export**: programmatic method plus an optional toolbar dropdown. (Excel/XLSX export is in `apex-grid-enterprise`.)
 - **Toolbar**: opt-in `<apex-grid-toolbar>` with debounced quick filter and export menu.
 - **Templating**: slot-based templates for cells, headers, editors, and detail panels.
-- **Theming**: styled out-of-the-box; fully customizable through `--ag-*` CSS custom properties (no theme import or build step). Auto-matches an `igniteui-webcomponents` host app when one is present.
+- **Theming**: styled out-of-the-box; fully customizable through `--ag-*` CSS custom properties (no theme import or build step). Auto-tints to an Ignite UI host app's palette when one is present, with no dependency on it.
 - **Accessibility**: WCAG 2.2 AA semantics (`role="grid"` / `role="treegrid"`, `aria-rowcount`, `aria-colcount`, focus + keyboard navigation).
 - **Provenance-signed npm releases** with OIDC trusted publishing.
 
@@ -45,7 +45,7 @@ import { setup } from 'apex-grid';
 setup();
 ```
 
-That single call registers `<apex-grid>` and adopts a default host stylesheet (`height: 100%; min-height: 240px`). The grid is styled out-of-the-box; no theme CSS import is required.
+That single call registers `<apex-grid>` and adopts a default host stylesheet (`height: 100%; min-height: 240px`), also inside any shadow root a grid connects in. The grid is styled out-of-the-box; no theme CSS import is required.
 
 ### Render the grid
 
@@ -94,8 +94,6 @@ If you'd rather not use `setup()`, this is what it does under the hood. Skipping
 npm install apex-grid lit
 ```
 
-`igniteui-webcomponents` ships as a transitive dependency; no separate install.
-
 ### 2. Register the custom element
 
 ```ts
@@ -113,7 +111,7 @@ Without this, `<apex-grid>` is an inert unknown element.
 
 ### 3. (Optional) Customize the look
 
-The grid is styled out-of-the-box; there is no theme to import. Customize it by overriding the `--ag-*` CSS custom properties on `apex-grid` (or any ancestor); a one-line brand override cascades to every tint:
+The grid is styled out-of-the-box; there is no theme to import. Customize it by overriding the `--ag-*` CSS custom properties on `apex-grid` or on any ancestor: `:root`, a dashboard panel, or the shadow host of a web component the grid renders in (custom properties inherit through shadow boundaries, however deep). A one-line brand override cascades to every tint:
 
 ```css
 apex-grid {
@@ -124,16 +122,40 @@ apex-grid {
 }
 ```
 
-See [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full token list (brand, surfaces, text, semantic state colors, typography, spacing, motion).
+See [`src/styles/_token-values.scss`](src/styles/_token-values.scss) for the full token list and defaults (surfaces, text, semantic state colors, typography, spacing, motion).
+
+**Where the defaults live.** The first grid to connect adopts the token defaults into its document, on `:where(:root)`, through `adoptedStyleSheets` (no `<style>` element, so no CSP nonce). Zero specificity means any value you set wins, and `var(--ag-*)` reads in your own CSS resolve to the defaults. If you manage your own CSS, opt out with `setup({ tokenStyles: false })` and import the same defaults as a file (also the way to get them into server-rendered HTML):
+
+```ts
+import 'apex-grid/tokens.css';
+```
+
+The grid renders the same without the sheet; it carries the defaults as fallbacks. Three groups have no root default, so page CSS reading them needs its own fallback:
+
+- `--ag-brand` and `--ag-brand-strong`, so an Ignite UI palette set on any ancestor keeps tinting the grid (see below).
+- The derived washes `--ag-brand-soft`, `--ag-brand-softer`, `--ag-brand-line`, `--ag-row-hover` and `--ag-surface-alt`. The grid mixes them from the brand and surface in effect, so they follow a brand set on an ancestor. Set them only to override the mix.
+
+**Dark mode.** `theme="dark"` reads its own colour inputs, `--ag-dark-*` (`--ag-dark-surface`, `--ag-dark-text`, `--ag-dark-hairline`, `--ag-dark-shadow-card`, and so on), so a light palette set on a shared ancestor never puts a white surface under the dark theme's light text. Sizing, typography, motion, the brand and the base state colours are shared by both modes. To theme both from one place, set both palettes:
+
+```css
+.dashboard {
+  --ag-brand: #7c3aed;
+  --ag-surface: #fdfcff;
+  --ag-dark-surface: #140f24;
+}
+```
+
+`theme="tinted"` mixes a little brand into the surface, gridline and muted-text values in effect, including any you set. Its row separators are the brand alone, so a tinted grid ignores `--ag-border` and `--ag-dark-border`.
 
 **Grid edge / shadow.** By default the grid shows a flat 1px hairline edge (no drop shadow). Control it with the `--ag-grid-shadow` hook, an opt-in override that is not one of the `_tokens.scss` defaults:
 
 ```css
-apex-grid { --ag-grid-shadow: var(--ag-shadow-card); } /* elevated floating-card look */
-apex-grid { --ag-grid-shadow: none; }                  /* remove the edge entirely */
+apex-grid { --ag-grid-shadow: var(--ag-shadow-card); }                     /* elevated floating-card look */
+apex-grid[theme~='dark'] { --ag-grid-shadow: var(--ag-dark-shadow-card); } /* the same, for dark grids */
+apex-grid { --ag-grid-shadow: none; }                                      /* remove the edge entirely */
 ```
 
-If you embed the grid alongside `igniteui-webcomponents`, the brand tokens automatically re-tint from the igniteui palette (`--ig-primary-500`); no configuration needed.
+If you embed the grid in an Ignite UI app, the brand tokens automatically re-tint from its palette, wherever it is declared: they read `--ig-primary-500` with the grid's own default as the fallback. That is a plain CSS variable lookup, so the grid neither depends on nor bundles Ignite UI.
 
 ### 4. Size the host
 
@@ -281,7 +303,7 @@ A persistent vertical divider on each column header's trailing edge, on by defau
 grid.columnSeparator = false;                     // hide the dividers
 ```
 
-Theme the line with `--ag-header-separator` (or the `--header-separator-color` / `--igx-header-separator-color` override hooks) and set its vertical inset with `--apex-header-separator-inset`. Because the default is `true`, disable it through the property rather than markup (a default-on boolean attribute cannot be turned off by attribute alone). Attribute: `column-separator`.
+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`.
 
 ### Column groups (spanning headers)
 
@@ -317,6 +339,33 @@ grid.cancelEdit();
 
 `mode: 'row'` puts all editable cells in the row into edit together. Properties: `editingCell`, `editingRow`. Events: `cellValueChanging` (cancellable), `cellValueChanged`, plus `rowEditStarted` / `rowEditEnded` in row mode.
 
+For programmatic writes, `applyEdits()` takes many cells at once:
+
+```ts
+const { applied, invalid, skipped } = grid.applyEdits([
+  { rowIndex: 0, column: 'name', value: 'Ada' },
+  { rowIndex: 1, column: 'age', value: 36 },
+]);
+```
+
+Each write goes through the same choke point interactive editing uses, so it
+emits `cellValueChanging` / `cellValueChanged` and runs the column's validators.
+What differs from looping over `editCell` + `commitEdit` is that the whole batch
+lands as **one** undo step and triggers **one** pipeline run — a thousand
+round-trips would otherwise mean a thousand undo entries and a thousand
+re-renders. The returned tally splits `applied` from `unchanged`, `invalid`,
+`cancelled`, and `skipped`, so a rejected batch is distinguishable from a no-op
+one. Edits naming a row out of range or a column the user could not edit either
+are skipped rather than throwing.
+
+`rowIndex` is view-relative, so it reaches the current page only. To edit rows
+anywhere (other pages, pinned rows, rows under a collapsed tree parent), name
+the record itself with `row`:
+
+```ts
+grid.applyEdits(grid.selectedRows.map((row) => ({ row, column: 'discount', value: 0 })));
+```
+
 ### Keyboard navigation and accessibility
 
 The grid body is a single tab stop: Tab enters the grid, and the active cell
@@ -399,7 +448,7 @@ grid.unpinRow(data[0]);
 grid.pinnedRows;                    // { top: T[], bottom: T[] }
 ```
 
-Pinned rows render in sticky top / bottom bands outside the virtualizer and are lifted out of the scrollable set (no duplication). Selection and styling work by row reference. Events: `rowPinning` (cancellable), `rowPinned`.
+Pinned rows render in sticky top / bottom bands outside the virtualizer and are lifted out of the scrollable set (no duplication). Selection and styling work by row reference. Replacing `grid.data` carries the pins onto the new rows (by `rowId` when set, else a pin whose row left the data is dropped). While `rowPinning.enabled` is false the pinned rows return to the body and `pinnedRows` reports none, but the pins are kept (`getState` still saves them) and re-enabling brings them back. Events: `rowPinning` (cancellable), `rowPinned`.
 
 ### Row drag-reorder
 
@@ -409,7 +458,7 @@ grid.rowReordering = { enabled: true };   // add applyToData: true to splice gri
 grid.moveRow(0, 4, 'after');
 ```
 
-By default (`rowReordering.handle`, boolean, default `true`) a six-dot grip handle shows at the start of every reorderable row, and dragging lifts a full-row floating ghost that follows the cursor. Both interaction modes are supported: **handle mode** (only the grip starts a drag, so the rest of the row stays free for selection and editing) and **whole-row mode** (set `handle: false` to drag from anywhere on the row, excluding interactive sub-parts like inputs and buttons). Or use the keyboard: focus a row, **Space** to grab, **Arrow** keys to move, **Space / Enter** to drop, **Esc** to cancel. The grid holds a manual order that is mutually exclusive with sorting (applying a sort clears it). By default the app persists the order via the `rowMoved` event; set `applyToData: true` to splice `grid.data` directly. Events: `rowMoving` (cancellable), `rowMoved { from, to, data }`.
+By default (`rowReordering.handle`, boolean, default `true`) a six-dot grip handle shows at the start of every reorderable row, and dragging lifts a full-row floating ghost that follows the cursor. Both interaction modes are supported: **handle mode** (only the grip starts a drag, so the rest of the row stays free for selection and editing) and **whole-row mode** (set `handle: false` to drag from anywhere on the row, excluding interactive sub-parts like inputs and buttons). Or use the keyboard: focus a row, **Space** to grab, **Arrow** keys to move, **Space / Enter** to drop, **Esc** to cancel. The grid holds a manual order that is mutually exclusive with sorting (applying a sort clears it, and a move clears the sort). Rows hidden by a filter keep their place when a visible row moves, and the order follows `grid.data` when it is replaced (by `rowId` when set). By default the app persists the order via the `rowMoved` event; set `applyToData: true` to splice `grid.data` directly. Events: `rowMoving` (cancellable), `rowMoved { from, to, position, toIndex, data }`, where `toIndex` is the view index the row lands at.
 
 ### Row expansion (master-detail)
 
@@ -497,7 +546,7 @@ Search input has a `debounce` attribute (default `200`ms).
 
 ### Theming
 
-The grid styles itself through `--ag-*` CSS custom properties; override them on `apex-grid` (or any ancestor) to rebrand; see [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full list. When `igniteui-webcomponents` is present, the brand tokens auto-tint from its palette.
+The grid styles itself through `--ag-*` CSS custom properties; override them on `apex-grid` or any ancestor (shadow hosts included) to rebrand, and use `--ag-dark-*` for dark grids. See [Customize the look](#3-optional-customize-the-look) and [`src/styles/_token-values.scss`](src/styles/_token-values.scss) for the full list. Where an Ignite UI palette is present, the brand tokens auto-tint from `--ig-primary-500`.
 
 Style with CSS parts on the grid, paginator, and toolbar:
 
@@ -506,6 +555,50 @@ apex-grid::part(paginator) { background: var(--surface-2); }
 apex-grid-toolbar::part(search-input) { font-family: var(--font-mono); }
 ```
 
+Body rows re-export these parts, so `apex-grid::part(name)` reaches them:
+
+| Part | What |
+|---|---|
+| `cell` | A data cell |
+| `selection-cell`, `selection-checkbox` | Selection column cell and its checkbox |
+| `expansion-cell`, `expansion-toggle`, `expansion-chevron` | Expansion column cell, its button and the chevron icon |
+| `detail-panel` | Expanded detail panel container |
+| `row-number-cell`, `row-number` | Row-number gutter cell and its label (`coordinateHints`) |
+| `reorder-handle-cell`, `reorder-handle`, `reorder-grip` | Row-reorder grip cell, handle and icon (handle mode) |
+| `group-row` | Default container of a row a feature module renders full width |
+
+Parts used inside your own `detailTemplate` content are re-exported when you list them in `expansion.exportParts`:
+
+```js
+grid.expansion = {
+  enabled: true,
+  exportParts: ['order-summary'],
+  detailTemplate: ({ data }) => html`<div part="order-summary">${data.total}</div>`,
+};
+```
+
+### Right-to-left
+
+Set `dir="rtl"` on the grid or any ancestor and the whole grid mirrors — no
+separate stylesheet, build flag, or option:
+
+```html
+<html dir="rtl">
+  <apex-grid id="grid"></apex-grid>
+</html>
+```
+
+The stylesheets are written entirely in logical properties (`inline-size`,
+`inset-inline-start`, `border-inline-end`, …), so layout, pinning, and the fill
+handle follow the text direction on their own. The direction is read from the
+*computed* style, so inheriting it from `<html>` or a wrapper works as well as
+setting it on the grid.
+
+Behaviour that reasons in physical directions mirrors too: ArrowLeft moves to the
+next column rather than the previous one, column resize grows the column as the
+pointer moves toward the (now left-hand) inline-end edge, and a column drag drops
+on the side the cursor actually crossed.
+
 ### Spreadsheet coordinates
 
 ```ts
@@ -649,7 +742,7 @@ All events bubble and are composed across shadow boundaries. Names ending in `-i
 | `historyChanged` | no | `{ canUndo, canRedo }` |
 | `rowSelecting` / `rowSelected` | yes / no | `{ added, removed }` |
 | `rowPinning` / `rowPinned` | yes / no | `{ row, position }` |
-| `rowMoving` / `rowMoved` | yes / no | `{ from, to, data }` |
+| `rowMoving` / `rowMoved` | yes / no | `{ from, to, position, toIndex, data }` |
 | `rowExpanding` / `rowExpanded` | yes / no | row context |
 | `treeRowExpanding` / `treeRowExpanded` | yes / no | row context |
 | `stateChanged` | no | `{ state }` (debounced; only while listened) |

package/components/cell.d.ts

@@ -46,13 +46,30 @@ export default class ApexGridCell<T extends object> extends LitElement {
      * auto-rendered selection + expansion columns ahead of the data columns.
      */
     colindex: number;
+    /**
+     * The parent row's view index, set by the row. Changing it re-decorates the
+     * cell (decoration such as a range selection is positional), so a row that
+     * moves with the same data (sort, filter, an expand above it) never keeps a
+     * stale highlight.
+     *
+     * @internal
+     */
+    rowIndex: number;
     /**
      * Reactive token forwarded from {@link StateController.decorationVersion}.
-     * Changing it re-runs {@link willUpdate} so module-driven cell decoration is
-     * re-evaluated when it changes (e.g. while dragging a selection range). Stays
-     * `0` for the community grid, so cells are never re-decorated there.
+     * Changing it re-applies module-driven cell decoration (e.g. while dragging a
+     * selection range) without re-rendering the cell content. Stays `0` for the
+     * community grid, so cells are never re-decorated there.
      */
     decorationVersion: number;
+    /**
+     * Reactive token forwarded from {@link StateController.dataVersion}, bumped
+     * once per pipeline run. Re-renders only a cell that reads its row beyond
+     * its own value (see {@link shouldUpdate}).
+     *
+     * @internal
+     */
+    dataVersion: number;
     /**
      * Reactive token forwarded from {@link EditingController.validationVersion}.
      * Changing it re-runs {@link willUpdate} so the cell re-reads its validation
@@ -62,7 +79,16 @@ export default class ApexGridCell<T extends object> extends LitElement {
     validationVersion: number;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    protected willUpdate(): void;
+    /**
+     * Skips the render when only positional or decoration tokens changed: the
+     * decoration is host attributes, so it is reconciled here and the cell
+     * template (type renderers, user templates) is not re-run. A cell that reads
+     * its row beyond {@link value} (a `cellTemplate`, which may read other fields
+     * or the row index, or the tree group cell, whose chevron shows the row's
+     * expansion) still renders when the row index or the data token moves.
+     */
+    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