apex-grid 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -4,6 +4,107 @@ 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/).
 
+## [3.5.0] - 2026-09-12
+
+A feature and accessibility release. No exported symbol was removed or renamed.
+Two consumer-visible changes are listed under Changed and Removed: the Ignite UI
+dependencies are gone, and `setup({ theme })` is now inert.
+
+### Added
+- **Right-to-left support.** `dir="rtl"` on the grid or any ancestor mirrors it
+  completely. Direction is read from the computed style rather than the `dir`
+  attribute, so an inherited direction works. The stylesheets were already
+  written in logical properties; what changed is the code that reasoned in
+  physical pixels or physical key names: ArrowLeft / ArrowRight map onto
+  previous / next column by inline order, column resize takes width off the
+  inline-start edge, and column reorder flips its midpoint comparison. (The
+  enterprise range and chart-range handles had a matching fix; see that
+  package's 0.7.0 entry.)
+- **`grid.applyEdits(edits)`**, a programmatic batch write. Previously the only
+  write path was `editCell` + `commitEdit`, which drives the editor, so a bulk
+  write meant a thousand undo entries and a thousand re-renders. Each write still
+  emits cancellable `cellValueChanging` then `cellValueChanged` and still runs
+  the column's validators, while the batch lands as one undo step and one
+  pipeline run. It returns a tally rather than a count, splitting `applied` from
+  `unchanged`, `invalid`, `cancelled` and `skipped`, since "nothing changed" and
+  "everything was rejected" are different answers. Out-of-range rows and
+  non-editable columns are skipped rather than thrown on, so a partially stale
+  batch still applies what it can.
+- **Reduced-motion support.** Every transition now routes through one of the
+  `--ag-dur-*` tokens, and those zero under `prefers-reduced-motion: reduce`:
+  24 transitions across 9 stylesheets go instant with their end states
+  unchanged. The JS-driven row reorder and expansion animations already bailed
+  out.
+- **Forced-colors support.** Forced colors paints no `box-shadow`, and the grid
+  leaned on inset shadows for exactly the indicators that matter most, so in
+  Windows High Contrast a keyboard user had no visible cursor and no visible
+  selection. The active-cell ring, invalid-cell ring, selected-row bar and every
+  toolbar and filter focus ring are restated as outlines, which forced colors
+  recolours rather than drops and which sit outside layout, so nothing shifts.
+- **The Custom Elements Manifest is now authoritative for `<apex-grid>`.** The
+  element was missing from `custom-elements.json` entirely: no `tagName`, not
+  flagged `customElement`, and zero named events. It now resolves
+  `customElement`, `tagName`, all 29 `ApexGridEventMap` events, the `theme`
+  attribute and the public `@property` fields, and a build-time drift check
+  fails the build when any of them diverge. This is what the new
+  `react-apex-grid` wrapper package generates from, and what editor tooling
+  reads for completions.
+
+### Changed
+- **Target sizes meet WCAG 2.2 AA 2.5.8 (24x24).** The selection cell and the
+  select-all header cell forward clicks to their checkbox rather than growing a
+  deliberately small 14x14 mark. The header sort / filter / menu buttons reach
+  24x24 through the invisible chip that already expanded them, so the visible
+  16px box and the packed header layout are unchanged and nothing paints at
+  rest. **Paginator buttons grow from 22 to 24, which makes the paginator bar
+  2px taller.** The range fill handle stays a 10px grab band, now documented as
+  a criterion-permitted exception rather than a gap: it is reachable through
+  controls that do meet 24x24, and its position at the range corner is
+  essential to what it means.
+- **`setup({ theme })` is inert and warns once.** It only ever forwarded to
+  Ignite UI's `configureTheme()`, which was already documented as not affecting
+  the grid's appearance. It still compiles, so no consumer code breaks; the
+  warning is there because silently dropping the forwarding would leave an
+  Ignite UI host app unthemed with no clue why.
+
+### Removed
+- **The `igniteui-webcomponents` and `igniteui-theming` dependencies.** Core
+  carried the first as a runtime dependency and enterprise as a peer, so every
+  consumer installed a whole component library (plus `@floating-ui`) for one
+  inert pass-through. The grid registers no Ignite UI element.
+  `igniteui-theming` was a Sass dependency for exactly one function, `rem()`,
+  now reimplemented locally with the same conversion, and it emitted 55 Sass
+  deprecation warnings per build. Five packages leave the lockfile, and the
+  compiled CSS is 3,718 bytes smaller with every `rem()` output byte-identical.
+- **The `--igx-*` custom-property level.** Every colour rule resolved through
+  three levels and the first never fired: `--igx-*` is the igniteui-angular
+  naming convention, not the web-components one, so it was dead indirection in
+  front of the two levels that work. `--ag-*` overrides and the unprefixed
+  semantic variables behave exactly as before. The `--ig-primary-*` and
+  `--ig-font-family` hooks stay, since those are what an Ignite UI theme
+  actually sets and reading a variable with a default costs nothing when absent.
+
+### Fixed
+- **A grid could settle with zero rendered rows at first paint**, silently,
+  while reporting a correct `ariaRowCount` and a correctly sized scroll region
+  ([#31](https://github.com/apexcharts/apex-grid/issues/31)). The virtualizer
+  derives its viewport from the intersection of the body, its clipping ancestors
+  and the window, and clears the rendered range when that intersection is
+  zero-height while still sizing the scroll extent from the full item count. It
+  could not recover, because the only invalidation signals it listens for are
+  size changes and scroll events: a body that moves into view, or a window that
+  resizes around a fixed-size host, fires neither. An iframe sized by its host
+  page after load hits this, as does content above the grid that is still
+  settling. The body now watches its own intersection with the window and
+  re-measures when it gains a visible slice with nothing rendered, bounded to
+  three attempts per geometry change and skipped entirely when there is no
+  visible slice.
+- **A grid moved to another parent left its body permanently stale**, still
+  rendering the old rows after `data` was reassigned. The body awaited
+  virtualizer state before calling `super.connectedCallback()`, which deadlocks
+  on a reconnect: the promise waits on a layout that only runs once the update
+  cycle that call starts.
+
 ## [3.4.0] - 2026-07-17
 
 An accessibility-focused release. The public module API is unchanged (no

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.
 
@@ -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
@@ -133,7 +131,7 @@ apex-grid { --ag-grid-shadow: var(--ag-shadow-card); } /* elevated floating-card
 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: 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 +279,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 +315,25 @@ 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.
+
 ### Keyboard navigation and accessibility
 
 The grid body is a single tab stop: Tab enters the grid, and the active cell
@@ -497,7 +514,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) to rebrand; see [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full list. Where an Ignite UI palette is present, the brand tokens auto-tint from `--ig-primary-500`.
 
 Style with CSS parts on the grid, paginator, and toolbar:
 
@@ -506,6 +523,28 @@ apex-grid::part(paginator) { background: var(--surface-2); }
 apex-grid-toolbar::part(search-input) { font-family: var(--font-mono); }
 ```
 
+### 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

package/components/grid.d.ts

@@ -649,6 +649,88 @@ export interface ApexGridEventMap<T extends object> {
      */
     rowSelected: CustomEvent<ApexRowSelectedEvent<T>>;
 }
+/**
+ * Apex grid is a web component for displaying data in a tabular format quick and easy.
+ *
+ * Out of the box it provides row virtualization, sort and filter operations (client and server side),
+ * the ability to template cells and headers and column hiding.
+ *
+ * @remarks
+ * A working, styled grid requires three things:
+ *  1. Register the element: `import 'apex-grid/define'` (or `ApexGrid.register()`).
+ *  2. Give the host element a bounded height, e.g. `apex-grid { height: 480px }` —
+ *     the virtualizer collapses without one.
+ *  3. Do NOT set `display` on the host — the component declares `:host { display: grid }`
+ *     internally and any override breaks the track layout.
+ *
+ * The grid is styled out of the box through `--ag-*` CSS custom properties —
+ * there is no theme to import and no `configureTheme()` call. Override `--ag-*`
+ * tokens on the host (or any ancestor) to rebrand; where an Ignite UI palette is
+ * present, the brand tokens auto-tint from it. For dark mode, set
+ * the `theme="dark"` attribute on the host for the built-in slate dark palette
+ * (further `--ag-*` overrides still compose on top). Add `tinted` (e.g.
+ * `theme="tinted"` or `theme="dark tinted"`) to mix the brand into the chrome
+ * so the grid wears its brand even at rest. See the README "Getting Started"
+ * and "Theming" sections for the full example and token list.
+ *
+ * @element apex-grid
+ *
+ * @attr {string} theme - Space-separated theme flags. `dark` opts into the built-in dark palette; `tinted` mixes `--ag-brand` into the chrome surfaces. Combine as `theme="dark tinted"`.
+ *
+ * @fires sorting - Emitted when sorting is initiated through the UI.
+ * @fires sorted - Emitted when a sort operation initiated through the UI has completed.
+ * @fires filtering - Emitted when filtering is initiated through the UI.
+ * @fires filtered - Emitted when a filter operation initiated through the UI has completed.
+ * @fires pageChanging - Cancellable. Emitted before page/page-size changes are applied.
+ * @fires pageChanged - Emitted after a page/page-size change has been applied.
+ * @fires quickFilterChanging - Cancellable. Emitted before a quick-filter value is applied.
+ * @fires quickFilterChanged - Emitted after a quick-filter change has been applied.
+ * @fires columnPinning - Cancellable. Emitted before a column's pin position changes.
+ * @fires columnPinned - Emitted after a column's pin position has changed.
+ * @fires columnMoving - Cancellable. Emitted before a column is moved.
+ * @fires columnMoved - Emitted after a column has been moved.
+ * @fires cellValueChanging - Cancellable. Emitted before a cell value is committed.
+ * @fires cellValueChanged - Emitted after a cell value has been committed.
+ * @fires rowEditStarted - Emitted when a row enters edit mode (row mode only).
+ * @fires rowEditEnded - Emitted when a row leaves edit mode (row mode only).
+ * @fires rowSelecting - Cancellable. Emitted before a selection-set change is applied.
+ * @fires rowSelected - Emitted after a selection-set change has been applied.
+ * @fires rowExpanding - Cancellable. Emitted before the row-expansion set changes (master-detail).
+ * @fires rowExpanded - Emitted after a row-expansion change has been applied.
+ * @fires treeRowExpanding - Cancellable. Emitted before a tree-row expansion change (tree mode).
+ * @fires treeRowExpanded - Emitted after a tree-row expansion change has been applied.
+ *
+ * @csspart live-region - Visually-hidden ARIA live region used for screen-reader announcements.
+ *
+ * @cssprop [--ag-brand] - Brand color for selection, focus rings, and accents. Auto-tints from `--ig-primary-500` where an Ignite UI palette is present.
+ * @cssprop [--ag-brand-strong] - Brand color for hover / pressed states.
+ * @cssprop [--ag-grid-shadow] - Grid edge/shadow override. Default is a flat 1px hairline edge; set to `var(--ag-shadow-card)` for the elevated card look, or `none` to remove it.
+ * @cssprop [--ag-grid-bg] - Host card background. Defaults to a subtle light gradient; override with a flat color (or use `theme="dark"`) for dark themes.
+ * @cssprop [--ag-surface] - Grid card background (must be opaque).
+ * @cssprop [--ag-surface-alt] - Alternating row tint.
+ * @cssprop [--ag-surface-elevated] - Header background.
+ * @cssprop [--ag-hairline] - Header / structural gridline color.
+ * @cssprop [--ag-border] - Row separator color.
+ * @cssprop [--ag-text] - Primary text color.
+ * @cssprop [--ag-text-body] - Row text color.
+ * @cssprop [--ag-text-muted] - Muted text (roles, labels).
+ * @cssprop [--ag-row-hover] - Row hover wash.
+ * @cssprop [--ag-row-h] - Row height.
+ * @cssprop [--ag-header-h] - Header height.
+ * @cssprop [--ag-radius] - Outer card corner radius.
+ * @cssprop [--ag-font] - Grid font family.
+ * @cssprop [--ag-fs-cell] - Cell font size.
+ *
+ * @see {@link https://github.com/apexcharts/apex-grid/blob/main/packages/core/src/styles/_tokens.scss | _tokens.scss} for the complete `--ag-*` token list.
+ *
+ * @fires cellValidationFailed - Emitted when a candidate cell value is rejected by a column validator; the value is not written.
+ * @fires historyChanged - Emitted after the undo / redo stacks change; carries the current `canUndo` / `canRedo`.
+ * @fires stateChanged - Emitted (debounced) whenever the grid's restorable state changes; carries the new `getState` snapshot.
+ * @fires rowPinning - Cancellable. Emitted before a row is pinned, moved between bands, or unpinned.
+ * @fires rowPinned - Emitted after a row's pin state has changed.
+ * @fires rowMoving - Cancellable. Emitted before a row is moved via drag, keyboard, or `moveRow`.
+ * @fires rowMoved - Emitted after a row has been moved.
+ */
 export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGridEventMap<T>> {
     #private;
     static get tagName(): string;
@@ -1365,6 +1447,51 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * `rowEditEnded` in row mode.
      */
     commitEdit(): Promise<boolean>;
+    /**
+     * Applies many cell edits as a **single** operation.
+     *
+     * Every write goes through the same choke point interactive editing uses, so
+     * each one emits the cancellable `cellValueChanging` and then
+     * `cellValueChanged`, and runs the column's validators. What differs from
+     * calling {@link editCell} + {@link commitEdit} in a loop is that the whole
+     * set lands as one undo step and triggers one pipeline run, which is the
+     * point: a thousand `editCell` round-trips would be a thousand entries in the
+     * undo stack and a thousand re-renders.
+     *
+     * `rowIndex` is view-relative and matches {@link ApexGrid.pageItems}, the same
+     * as {@link editCell}. Edits naming an unknown column, a row index out of
+     * range, or a column the user could not edit either (editing off, not
+     * `editable`, or hidden — the same gate interactive editing uses) are skipped
+     * rather than throwing, so a partially-stale batch still applies what it can.
+     *
+     * @param edits Cells to write. Order is preserved, so later edits to the same
+     * cell win.
+     * @returns A per-outcome tally. `applied` counts cells whose value actually
+     * changed; `unchanged`, `invalid` and `cancelled` explain the rest, so a caller
+     * can tell a rejected batch from a no-op one.
+     *
+     * @example Bulk-clear a column for the rows the user selected
+     * ```ts
+     * grid.applyEdits(
+     *   grid.selectedRows.map((row) => ({
+     *     rowIndex: grid.pageItems.indexOf(row),
+     *     column: 'discount',
+     *     value: 0,
+     *   }))
+     * );
+     * ```
+     */
+    applyEdits(edits: ReadonlyArray<{
+        rowIndex: number;
+        column: Keys<T>;
+        value: unknown;
+    }>): {
+        applied: number;
+        unchanged: number;
+        invalid: number;
+        cancelled: number;
+        skipped: number;
+    };
     /**
      * Discards the current edit without writing back to {@link ApexGrid.data}.
      */

package/components/grid.js

@@ -637,6 +637,31 @@ export class ApexGrid extends EventEmitterBase {
         const editing = this.stateController.editing;
         return editing.mode === 'row' ? editing.commitRow() : editing.commitCell();
     }
+    applyEdits(edits) {
+        const tally = { applied: 0, unchanged: 0, invalid: 0, cancelled: 0, skipped: 0 };
+        if (!edits.length)
+            return tally;
+        const editing = this.stateController.editing;
+        const items = this.pageItems;
+        this.stateController.history.beginBatch();
+        try {
+            for (const { rowIndex, column, value } of edits) {
+                const record = items.at(rowIndex);
+                const config = this.getColumn(column);
+                if (!record || rowIndex < 0 || !config || !editing.isEditable(config)) {
+                    tally.skipped += 1;
+                    continue;
+                }
+                tally[editing.applyCellEdit(rowIndex, column, record, value)] += 1;
+            }
+        }
+        finally {
+            this.stateController.history.endBatch();
+        }
+        if (tally.applied > 0)
+            this.requestUpdate(PIPELINE);
+        return tally;
+    }
     cancelEdit() {
         const editing = this.stateController.editing;
         if (editing.mode === 'row') {