apex-grid 3.4.0 → 3.6.0

package/components/grid.js

@@ -10,16 +10,18 @@ import { eventOptions, property, query, queryAll, state } from 'lit/decorators.j
 import { styleMap } from 'lit/directives/style-map.js';
 import { DataOperationsController } from '../controllers/data-operation.js';
 import { GridDOMController } from '../controllers/dom.js';
+import { viewIndexer } from '../controllers/history.js';
 import { gridStateContext, StateController } from '../controllers/state.js';
 import { localize as resolveLocaleText, } from '../i18n/index.js';
 import { DEFAULT_COLUMN_CONFIG, PIPELINE, SENTINEL_NODE } from '../internal/constants.js';
+import { adoptGridDocumentStyles } from '../internal/document-styles.js';
 import { buildCSV, downloadBlob, } from '../internal/export.js';
 import { EventEmitterBase } from '../internal/mixins/event-emitter.js';
 import { registerComponent } from '../internal/register.js';
 import { columnSchema, operandsByType } from '../internal/state-schema.js';
-import { applyColumnLayout, deserializeFilter, resolveRowRefs, serializeColumnLayout, serializeFilter, serializeRowRefs, serializeSort, } from '../internal/state-snapshot.js';
+import { applyColumnLayout, deserializeFilter, resolveFilterOperand, resolveRowRefs, SET_STATE_SLICES, serializeColumnLayout, serializeFilter, serializeRowRefs, serializeSort, } from '../internal/state-snapshot.js';
 import { GRID_TAG } from '../internal/tags.js';
-import { asArray, autoGenerateColumns, getDisplayColumns, getFilterOperandsFor, } from '../internal/utils.js';
+import { asArray, autoGenerateColumns, getDisplayColumns } from '../internal/utils.js';
 import { watch } from '../internal/watch.js';
 import { styles as gridStyles } from '../styles/grid/grid.css.js';
 import ApexGridCell from './cell.js';
@@ -30,19 +32,33 @@ import ApexGridPaginator from './paginator.js';
 import ApexGridRow from './row.js';
 import ApexGridToolbar from './toolbar.js';
 import ApexVirtualizer from './virtualizer.js';
-const SET_STATE_SLICES = [
+const SORT_DIRECTIONS = ['ascending', 'descending', 'none'];
+const VIEW_SHAPING_SLICES = new Set([
     'columns',
-    'sort',
     'filter',
     'quickFilter',
     'modules',
-    'rowOrder',
     'tree',
-    'expansion',
-    'rowPinning',
-    'selection',
-    'pagination',
-];
+]);
+const VIEW_SHAPING_PROPERTIES = new Map([
+    ['data', null],
+    ['quickFilter', null],
+    ['pagination', ['enabled', 'mode', 'pageSize', 'totalItems']],
+    ['tree', ['enabled', 'getDataPath', 'defaultExpanded']],
+    ['dataPipelineConfiguration', ['sort', 'filter', 'pagination', 'quickFilter']],
+]);
+function viewShapeChanged(fields, before, after) {
+    if (Object.is(before, after))
+        return false;
+    if (!fields)
+        return true;
+    const a = (before ?? {});
+    const b = (after ?? {});
+    return fields.some((field) => !Object.is(a[field], b[field]));
+}
+function warnDropped(message) {
+    console.warn(`[apex-grid] ${message}`);
+}
 export class ApexGrid extends EventEmitterBase {
     constructor() {
         super(...arguments);
@@ -55,21 +71,27 @@ export class ApexGrid extends EventEmitterBase {
         });
         this.dataState = [];
         this.columns = [];
-        this.data = [];
+        this.#data = [];
         this.autoGenerate = false;
         this.sortConfiguration = {
             multiple: true,
             triState: true,
         };
-        this.quickFilter = '';
+        this.#quickFilter = '';
+        this.#quickFilterWrites = 0;
         this.showQuickFilter = false;
         this.showExport = false;
         this.columnReordering = false;
         this.columnSeparator = true;
         this.coordinateHints = false;
         this.columnMenu = true;
+        this.#viewChangePending = false;
+        this.#shapingPending = false;
+        this.#pipelineRun = 0;
+        this.#pipelineSettled = Promise.resolve();
+        this.#settlePipeline = null;
         this.#autoAriaLabel = null;
-        this.#stateChangedListeners = 0;
+        this.#stateChangedListeners = new Map();
         this.#lastStateJson = null;
     }
     static get tagName() {
@@ -82,6 +104,24 @@ export class ApexGrid extends EventEmitterBase {
     createStateController() {
         return new StateController(this);
     }
+    #data;
+    get data() {
+        return this.#data;
+    }
+    set data(value) {
+        if (value == null && !this.#data.length)
+            return;
+        this.#data = value ?? [];
+    }
+    get quickFilter() {
+        return this.#quickFilter;
+    }
+    set quickFilter(value) {
+        this.#quickFilter = value;
+        this.#quickFilterWrites++;
+    }
+    #quickFilter;
+    #quickFilterWrites;
     localize(key, params, fallback) {
         return resolveLocaleText(this.localeText, key, params, fallback);
     }
@@ -160,26 +200,50 @@ export class ApexGrid extends EventEmitterBase {
     isTreeRowExpanded(row) {
         return this.stateController.tree.isExpanded(row);
     }
+    #pendingSort;
+    #pendingFilter;
     set sortExpressions(expressions) {
-        if (expressions.length) {
-            this.sort(expressions);
-        }
+        this.#pendingSort = [...(expressions ?? [])];
+        this.requestUpdate(PIPELINE);
     }
     get sortExpressions() {
+        if (this.#pendingSort)
+            return [...this.#pendingSort];
         return Array.from(this.stateController.sorting.state.values());
     }
     set filterExpressions(expressions) {
-        if (expressions.length) {
-            this.filter(expressions);
-        }
+        this.#pendingFilter = [...(expressions ?? [])];
+        this.#markViewChange();
     }
     get filterExpressions() {
+        if (this.#pendingFilter) {
+            return this.#pendingFilter.map((each) => {
+                const resolved = this.#resolveFilter(each);
+                return typeof resolved === 'string' ? each : resolved;
+            });
+        }
         const expressions = [];
         for (const each of this.stateController.filtering.state.values) {
             expressions.push(...each.all);
         }
         return expressions;
     }
+    #resolveFilter(each) {
+        const column = each ? this.getColumn(each.key) : undefined;
+        if (!column)
+            return `filter: unknown column "${String(each?.key)}"; dropped`;
+        const defaults = this.stateController.filtering.getDefaultExpression(column);
+        const named = each.condition ?? defaults.condition;
+        const condition = typeof named === 'string' ? resolveFilterOperand(column, named) : named;
+        if (!condition)
+            return `filter: unknown operand "${named}" for "${String(each.key)}"; dropped`;
+        return {
+            ...defaults,
+            ...each,
+            condition,
+            criteria: each.criteria ?? 'and',
+        };
+    }
     get rows() {
         return Array.from(this._rows);
     }
@@ -197,7 +261,7 @@ export class ApexGrid extends EventEmitterBase {
     }
     get pageItems() {
         const rowPin = this.stateController.rowPin;
-        const base = rowPin?.enabled && rowPin.hasPinnedRows
+        const base = rowPin?.hasPinnedRows
             ? this.dataState.filter((row) => !rowPin.isPinned(row))
             : this.dataState;
         if (!this.stateController.pagination.enabled)
@@ -214,7 +278,33 @@ export class ApexGrid extends EventEmitterBase {
         return this.stateController.pagination.page;
     }
     set page(value) {
-        this.stateController.pagination.gotoPage(value);
+        if (this.#viewStale) {
+            this.stateController.pagination.page = Number.isFinite(value)
+                ? Math.max(0, Math.trunc(value))
+                : 0;
+            this.requestUpdate(PIPELINE);
+        }
+        else {
+            this.stateController.pagination.gotoPage(value);
+        }
+    }
+    #viewChangePending;
+    #shapingPending;
+    get #viewStale() {
+        return !this.hasUpdated || this.#viewChangePending || this.#shapingPending;
+    }
+    #markViewChange() {
+        this.#viewChangePending = true;
+        this.requestUpdate(PIPELINE);
+    }
+    requestUpdate(name, oldValue, options, useNewValue, newValue) {
+        const fields = name === undefined ? undefined : VIEW_SHAPING_PROPERTIES.get(name);
+        if (this.hasUpdated &&
+            fields !== undefined &&
+            viewShapeChanged(fields, oldValue, useNewValue ? newValue : this[name])) {
+            this.#viewChangePending = true;
+        }
+        super.requestUpdate(name, oldValue, options, useNewValue, newValue);
     }
     get pageSize() {
         return this.stateController.pagination.pageSize;
@@ -228,21 +318,31 @@ export class ApexGrid extends EventEmitterBase {
     watchColumns(_, newConfig = []) {
         this.columns = newConfig.map((config) => ({ ...DEFAULT_COLUMN_CONFIG, ...config }));
     }
+    historyRecords() {
+        return this.data;
+    }
     dataChanged() {
         let next = [...this.data];
         autoGenerateColumns(this);
+        this.stateController?.history?.reconcile(() => this.historyRecords());
         this.stateController?.tree?.resetForDataChange();
+        const carry = (rows) => this.#carryRows(rows);
+        this.stateController?.rowReorder.resetForDataChange(carry);
+        this.stateController?.rowPin.resetForDataChange(carry);
         if (this.stateController?.tree?.enabled) {
             next = this.stateController.tree.process(next);
         }
         this.dataState = this.stateController ? this.stateController.applyModuleTransforms(next) : next;
-        if (this.hasUpdated) {
-            this.pipeline();
-        }
+        if (this.hasUpdated)
+            this.requestUpdate(PIPELINE);
     }
-    async pipeline() {
-        this.dataState = await this.dataController.apply([...this.data], this.stateController);
-        this.stateController.pagination.reclamp();
+    #carryRows(rows) {
+        const rowId = this.rowId;
+        const records = [...this.historyRecords()];
+        if (rowId)
+            return resolveRowRefs(serializeRowRefs(rows, [], rowId), records, rowId);
+        const present = new Set(records);
+        return rows.filter((row) => present.has(row));
     }
     paginationChanged() {
         const ctrl = this.stateController?.pagination;
@@ -255,16 +355,103 @@ export class ApexGrid extends EventEmitterBase {
         if (typeof next.page === 'number') {
             ctrl.page = next.page;
         }
-        if (this.hasUpdated) {
-            this.pipeline();
-        }
+        if (this.hasUpdated)
+            this.requestUpdate(PIPELINE);
     }
     quickFilterChanged() {
-        if (this.hasUpdated) {
-            this.pipeline();
+        if (this.hasUpdated || this.quickFilter)
+            this.requestUpdate(PIPELINE);
+    }
+    treeChanged(previous) {
+        if (!viewShapeChanged(VIEW_SHAPING_PROPERTIES.get('tree'), previous, this.tree))
+            return;
+        this.stateController.tree.resetForDataChange();
+        this.requestUpdate(PIPELINE);
+    }
+    #pipelineRun;
+    #pipelineSettled;
+    #settlePipeline;
+    pipeline() {
+        if (!this.#settlePipeline) {
+            this.#pipelineSettled = new Promise((settle) => {
+                this.#settlePipeline = settle;
+            });
+        }
+        return this.#runPipeline(++this.#pipelineRun);
+    }
+    async #runPipeline(run) {
+        try {
+            this.#flushPendingExpressions();
+            if (this.#viewChangePending || !this.hasUpdated)
+                this.#shapingPending = true;
+            this.#viewChangePending = false;
+            const next = await this.dataController.apply([...this.data], this.stateController);
+            if (run !== this.#pipelineRun)
+                return;
+            this.dataState = next;
+            this.stateController.dataVersion++;
+            this.stateController.pagination.reclamp();
+        }
+        finally {
+            if (run === this.#pipelineRun) {
+                this.#settlePipeline?.();
+                this.#settlePipeline = null;
+                if (this.#shapingPending) {
+                    this.#shapingPending = false;
+                    this.#baselineStateIfUnset();
+                }
+            }
         }
     }
+    async pipelineSettled() {
+        await this.updateComplete;
+        let settled;
+        do {
+            settled = this.#pipelineSettled;
+            await settled;
+            await this.updateComplete;
+        } while (settled !== this.#pipelineSettled);
+    }
+    #flushPendingExpressions() {
+        const sort = this.#pendingSort;
+        const filter = this.#pendingFilter;
+        this.#pendingSort = undefined;
+        this.#pendingFilter = undefined;
+        if (sort)
+            this.#replaceSort(sort, warnDropped);
+        if (filter)
+            this.#replaceFilter(filter);
+    }
+    #replaceSort(entries, warn) {
+        this.stateController.sorting.reset();
+        const valid = [];
+        for (const entry of entries) {
+            const { direction, ...rest } = (entry ?? {});
+            if (typeof entry !== 'object' || entry === null || !this.getColumn(rest.key)) {
+                warn(`sort: unknown column "${String(rest.key)}"; dropped`);
+            }
+            else if (direction === undefined) {
+                valid.push(rest);
+            }
+            else if (SORT_DIRECTIONS.includes(direction)) {
+                valid.push(entry);
+            }
+            else {
+                warn(`sort: invalid direction "${String(direction)}"; dropped`);
+            }
+        }
+        if (valid.length)
+            this.sort(valid);
+        this.requestUpdate(PIPELINE);
+    }
+    #replaceFilter(entries) {
+        this.#markViewChange();
+        this.stateController.filtering.reset();
+        if (entries.length)
+            this.filter([...entries]);
+    }
     updated() {
+        this.#viewChangePending = false;
         this.setAttribute('role', this.stateController.tree.enabled ? 'treegrid' : 'grid');
         const pinned = this.stateController.rowPin.pinnedRows;
         this.setAttribute('aria-rowcount', String(this.headerRowCount + pinned.top.length + this.pageItems.length + pinned.bottom.length));
@@ -279,9 +466,7 @@ export class ApexGrid extends EventEmitterBase {
         else {
             this.removeAttribute('aria-multiselectable');
         }
-        if (this.scrollContainer) {
-            this.scrollContainer.tabIndex = this.stateController.active === SENTINEL_NODE ? 0 : -1;
-        }
+        this.#syncBodyTabStop();
         const currentLabel = this.getAttribute('aria-label');
         const authorLabeled = this.hasAttribute('aria-labelledby') ||
             (currentLabel !== null && currentLabel !== this.#autoAriaLabel);
@@ -297,21 +482,54 @@ export class ApexGrid extends EventEmitterBase {
     #stateChangedListeners;
     #lastStateJson;
     addEventListener(type, listener, options) {
-        if (type === 'stateChanged') {
-            this.#stateChangedListeners += 1;
-            this.#lastStateJson = this.hasUpdated ? JSON.stringify(this.getState()) : null;
-        }
+        if (type === 'stateChanged' && listener)
+            this.#trackStateChangedListener(listener, options);
         super.addEventListener(type, listener, options);
     }
+    #trackStateChangedListener(listener, options) {
+        const capture = typeof options === 'boolean' ? options : Boolean(options?.capture);
+        const captures = this.#stateChangedListeners.get(listener) ?? new Map();
+        if (!captures.has(capture) && !options?.signal?.aborted) {
+            if (!this.#stateChangedListeners.size) {
+                this.#lastStateJson = this.hasUpdated ? JSON.stringify(this.getState()) : null;
+            }
+            const token = {};
+            captures.set(capture, token);
+            this.#stateChangedListeners.set(listener, captures);
+            const forget = () => this.#forgetStateChangedListener(listener, capture, token);
+            if (typeof options === 'object') {
+                if (options.once) {
+                    HTMLElement.prototype.addEventListener.call(this, 'stateChanged', forget, {
+                        capture,
+                        once: true,
+                    });
+                }
+                options.signal?.addEventListener('abort', forget, { once: true });
+            }
+        }
+    }
+    #forgetStateChangedListener(listener, capture, token) {
+        const captures = this.#stateChangedListeners.get(listener);
+        if (!captures || (token && captures.get(capture) !== token))
+            return;
+        captures.delete(capture);
+        if (!captures.size)
+            this.#stateChangedListeners.delete(listener);
+    }
     removeEventListener(type, listener, options) {
-        if (type === 'stateChanged') {
-            this.#stateChangedListeners = Math.max(0, this.#stateChangedListeners - 1);
+        if (type === 'stateChanged' && listener) {
+            const capture = typeof options === 'boolean' ? options : Boolean(options?.capture);
+            this.#forgetStateChangedListener(listener, capture);
         }
         super.removeEventListener(type, listener, options);
     }
     #emitStateChangedIfNeeded() {
-        if (this.#stateChangedListeners === 0)
+        if (!this.#stateChangedListeners.size)
             return;
+        if (this.#lastStateJson === null) {
+            this.#baselineStateIfUnset();
+            return;
+        }
         const snapshot = this.getState();
         const json = JSON.stringify(snapshot);
         if (json === this.#lastStateJson)
@@ -319,6 +537,15 @@ export class ApexGrid extends EventEmitterBase {
         this.#lastStateJson = json;
         this.emitEvent('stateChanged', { detail: { state: snapshot } });
     }
+    #baselineStateIfUnset() {
+        if (this.#lastStateJson === null && this.#stateChangedListeners.size && !this.#shapingPending) {
+            this.#lastStateJson = JSON.stringify(this.getState());
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        adoptGridDocumentStyles(this);
+    }
     firstUpdated() {
         if (typeof getComputedStyle === 'function' && getComputedStyle(this).display !== 'grid') {
             console.warn('[apex-grid] Host `display` has been overridden. The grid requires ' +
@@ -328,26 +555,44 @@ export class ApexGrid extends EventEmitterBase {
         }
     }
     filter(config) {
-        this.stateController.filtering.filter(asArray(config).map((each) => typeof each.condition === 'string'
-            ?
-                Object.assign(each, {
-                    condition: getFilterOperandsFor(this.getColumn(each.key))[each.condition],
-                })
-            : each));
+        if (this.#pendingFilter) {
+            const added = asArray(config);
+            this.#pendingFilter.push(...added);
+            if (added.length)
+                this.#markViewChange();
+            return;
+        }
+        const expressions = [];
+        for (const each of asArray(config)) {
+            const resolved = this.#resolveFilter(each);
+            if (typeof resolved === 'string')
+                warnDropped(resolved);
+            else
+                expressions.push(resolved);
+        }
+        if (!expressions.length)
+            return;
+        this.#markViewChange();
+        this.stateController.filtering.filter(expressions);
     }
     sort(expressions) {
+        if (this.#pendingSort) {
+            this.#pendingSort.push(...asArray(expressions));
+            this.requestUpdate(PIPELINE);
+            return;
+        }
         this.stateController.sorting.sort(expressions);
     }
     getState(options) {
         const rowId = options?.rowId ?? this.rowId;
-        const pinned = this.stateController.rowPin.pinnedRows;
+        const pinned = this.stateController.rowPin.pins;
         const manualOrder = this.stateController.rowReorder.getManualOrder();
         return {
             version: 1,
             columns: serializeColumnLayout(this.columns),
             sort: serializeSort(this.sortExpressions),
             filter: serializeFilter(this.filterExpressions),
-            quickFilter: this.quickFilter,
+            quickFilter: this.quickFilter ?? '',
             pagination: { page: this.page, pageSize: this.pageSize },
             selection: serializeRowRefs(this.selectedRows, this.data, rowId),
             expansion: serializeRowRefs(this.expandedRows, this.data, rowId),
@@ -367,7 +612,7 @@ export class ApexGrid extends EventEmitterBase {
             columns: this.columns.map((column) => columnSchema(column)),
             capabilities: {
                 sort: {
-                    directions: ['ascending', 'descending'],
+                    directions: SORT_DIRECTIONS.filter((direction) => direction !== 'none'),
                     multi: Boolean(this.sortConfiguration?.multiple),
                 },
                 filter: { operandsByType: operandsByType(this.columns) },
@@ -384,6 +629,7 @@ export class ApexGrid extends EventEmitterBase {
         const strict = options?.strict ?? false;
         const applied = [];
         const warnings = [];
+        const viewSettled = !this.#viewStale;
         const warn = (message) => {
             if (strict)
                 throw new Error(`[apex-grid] setState: ${message}`);
@@ -410,31 +656,23 @@ export class ApexGrid extends EventEmitterBase {
         }
         const columns = asArray(state.columns, 'columns');
         if (columns) {
+            const unkeyed = columns.filter((entry) => typeof entry?.key !== 'string').length;
+            if (unkeyed)
+                warn(`columns: ${unkeyed} entr${unkeyed === 1 ? 'y' : 'ies'} without a key; dropped`);
             this.columns = applyColumnLayout(this.columns, columns);
             applied.push('columns');
         }
         const sort = asArray(state.sort, 'sort');
         if (sort) {
-            this.stateController.sorting.reset();
-            const valid = [];
-            for (const entry of sort) {
-                if (this.getColumn(entry.key)) {
-                    valid.push(entry);
-                }
-                else {
-                    warn(`sort: unknown column "${entry.key}"; dropped`);
-                }
-            }
-            if (valid.length)
-                this.sort(valid);
+            this.#pendingSort = undefined;
+            this.#replaceSort(sort, warn);
             applied.push('sort');
         }
         const filter = asArray(state.filter, 'filter');
         if (filter) {
-            this.stateController.filtering.reset();
+            this.#pendingFilter = undefined;
             const expressions = deserializeFilter(filter, (key) => this.getColumn(key), (snapshot, reason) => warn(`filter: "${snapshot.key}" dropped (${reason})`));
-            if (expressions.length)
-                this.filter(expressions);
+            this.#replaceFilter(expressions);
             applied.push('filter');
         }
         if (state.quickFilter !== undefined) {
@@ -449,6 +687,7 @@ export class ApexGrid extends EventEmitterBase {
         if (state.modules !== undefined) {
             if (state.modules && typeof state.modules === 'object') {
                 this.stateController.restoreModuleState(state.modules);
+                this.#markViewChange();
                 applied.push('modules');
             }
             else {
@@ -476,13 +715,22 @@ export class ApexGrid extends EventEmitterBase {
         if (state.treeExpanded !== undefined || state.treeExpandedKeys !== undefined) {
             const refs = asArray(state.treeExpanded, 'treeExpanded') ?? [];
             const keys = asArray(state.treeExpandedKeys, 'treeExpandedKeys') ?? [];
-            this.stateController.tree.restoreExpansion(resolveCounted(refs, 'treeExpanded'), keys);
+            this.stateController.tree.restoreExpansion(resolveCounted(refs, 'treeExpanded'), keys.filter((key) => typeof key === 'string'));
+            this.#markViewChange();
             applied.push('tree');
         }
         const expansion = asArray(state.expansion, 'expansion');
         if (expansion) {
-            this.expandedRows = resolveCounted(expansion, 'expansion');
-            applied.push('expansion');
+            const ctrl = this.stateController.expansion;
+            const predicate = this.expansion?.isExpandable;
+            const rows = resolveCounted(expansion, 'expansion');
+            const expected = predicate ? rows.filter((row) => predicate(row)) : rows;
+            if (this.#replaceRows('expansion', ctrl.enabled, expected, warn, () => {
+                void ctrl.replaceExpansion(expected);
+                return ctrl.expandedRows();
+            })) {
+                applied.push('expansion');
+            }
         }
         if (state.rowPinning !== undefined) {
             const pinning = state.rowPinning;
@@ -496,8 +744,15 @@ export class ApexGrid extends EventEmitterBase {
         }
         const selection = asArray(state.selection, 'selection');
         if (selection) {
-            this.selectedRows = resolveCounted(selection, 'selection');
-            applied.push('selection');
+            const ctrl = this.stateController.selection;
+            const rows = resolveCounted(selection, 'selection');
+            const expected = ctrl.mode === 'single' ? rows.slice(0, 1) : rows;
+            if (this.#replaceRows('selection', ctrl.enabled, expected, warn, () => {
+                void ctrl.replaceSelection(expected);
+                return ctrl.selectedRows();
+            })) {
+                applied.push('selection');
+            }
         }
         if (state.pagination !== undefined) {
             const pagination = state.pagination;
@@ -514,10 +769,13 @@ export class ApexGrid extends EventEmitterBase {
                 if (page !== undefined) {
                     if (typeof page === 'number' && Number.isFinite(page)) {
                         const requested = Math.trunc(page);
-                        this.page = requested;
-                        if (this.page !== requested) {
-                            warn(`pagination: page ${requested} out of range; clamped to ${this.page}`);
+                        const reshaped = applied.some((slice) => VIEW_SHAPING_SLICES.has(slice));
+                        const ctrl = this.stateController.pagination;
+                        const next = viewSettled && !reshaped ? ctrl.clamp(requested) : Math.max(0, requested);
+                        if (next !== requested) {
+                            warn(`pagination: page ${requested} out of range; clamped to ${next}`);
                         }
+                        ctrl.page = next;
                     }
                     else {
                         warn(`pagination: invalid page ${String(page)}; ignored`);
@@ -533,13 +791,37 @@ export class ApexGrid extends EventEmitterBase {
         const skipped = SET_STATE_SLICES.filter((slice) => !applied.includes(slice));
         return { applied, skipped, warnings };
     }
+    #replaceRows(label, enabled, expected, warn, replace) {
+        if (!enabled) {
+            if (expected.length)
+                warn(`${label}: the feature is disabled on this grid; skipped`);
+            return !expected.length;
+        }
+        const actual = new Set(replace());
+        const took = actual.size === new Set(expected).size && expected.every((row) => actual.has(row));
+        if (!took)
+            warn(`${label}: the change was cancelled by a listener; skipped`);
+        return took;
+    }
     clearSort(key) {
+        if (this.#pendingSort && key !== undefined) {
+            this.#pendingSort = this.#pendingSort.filter((each) => each.key !== key);
+        }
+        else {
+            this.#pendingSort = undefined;
+        }
         this.stateController.sorting.reset(key);
         this.requestUpdate(PIPELINE);
     }
     clearFilter(key) {
+        if (this.#pendingFilter && key !== undefined) {
+            this.#pendingFilter = this.#pendingFilter.filter((each) => each.key !== key);
+        }
+        else {
+            this.#pendingFilter = undefined;
+        }
+        this.#markViewChange();
         this.stateController.filtering.reset(key);
-        this.requestUpdate(PIPELINE);
     }
     gotoPage(page) {
         return this.stateController.pagination.gotoPage(page);
@@ -563,15 +845,21 @@ export class ApexGrid extends EventEmitterBase {
         const next = value ?? '';
         if (next === this.quickFilter)
             return false;
+        const previous = this.quickFilter;
+        const writes = this.#quickFilterWrites;
         const proceed = this.emitEvent('quickFilterChanging', {
-            detail: { value: this.quickFilter, nextValue: next },
+            detail: { value: previous, nextValue: next },
             cancelable: true,
         });
         if (!proceed)
             return false;
-        this.quickFilter = next;
-        this.stateController.pagination.page = 0;
-        await this.updateComplete;
+        if (this.#quickFilterWrites === writes)
+            this.quickFilter = next;
+        if (this.quickFilter === previous)
+            return false;
+        const pageReset = this.stateController.pagination.resetPage();
+        await this.pipelineSettled();
+        await pageReset;
         this.emitEvent('quickFilterChanged', { detail: { value: this.quickFilter } });
         return true;
     }
@@ -637,6 +925,39 @@ 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;
+        const indexOf = viewIndexer(items, edits.length);
+        const version = editing.validationVersion;
+        this.stateController.history.beginBatch();
+        try {
+            for (const { row, rowIndex, column, value } of edits) {
+                const record = row ?? items[rowIndex];
+                const config = this.getColumn(column);
+                if (!record ||
+                    !config ||
+                    !editing.isEditable(config) ||
+                    !this.stateController.isDataRow(record)) {
+                    tally.skipped += 1;
+                    continue;
+                }
+                const index = row ? indexOf(row) : rowIndex;
+                tally[editing.applyCellEdit(index, column, record, value)] += 1;
+            }
+        }
+        finally {
+            this.stateController.history.endBatch();
+        }
+        if (tally.applied > 0)
+            this.requestUpdate(PIPELINE);
+        else if (editing.validationVersion !== version)
+            this.requestUpdate();
+        return tally;
+    }
     cancelEdit() {
         const editing = this.stateController.editing;
         if (editing.mode === 'row') {
@@ -706,22 +1027,20 @@ export class ApexGrid extends EventEmitterBase {
         const target = this.columns[toIndex];
         if ((source.pinned ?? null) !== (target.pinned ?? null))
             return false;
-        const proceed = this.emitEvent('columnMoving', {
-            detail: { key: fromKey, fromIndex, toKey, position },
-            cancelable: true,
-        });
-        if (!proceed)
-            return false;
         const next = this.columns.slice();
         const [moved] = next.splice(fromIndex, 1);
         let insertIndex = next.findIndex((column) => column.key === toKey);
-        if (insertIndex < 0)
-            return false;
         if (position === 'after')
             insertIndex += 1;
         next.splice(insertIndex, 0, moved);
         if (next.every((column, index) => column === this.columns[index]))
             return false;
+        const proceed = this.emitEvent('columnMoving', {
+            detail: { key: fromKey, fromIndex, toKey, position },
+            cancelable: true,
+        });
+        if (!proceed)
+            return false;
         this.columns = next;
         await this.updateComplete;
         const resolvedIndex = this.columns.findIndex((column) => column.key === fromKey);
@@ -730,8 +1049,42 @@ export class ApexGrid extends EventEmitterBase {
         });
         return true;
     }
+    ownsEvent(event) {
+        for (const node of event.composedPath()) {
+            if (node === this || node === this.scrollContainer)
+                return true;
+            if (node instanceof ApexGrid || node instanceof ApexVirtualizer)
+                return false;
+        }
+        return false;
+    }
+    #syncBodyTabStop() {
+        const body = this.scrollContainer;
+        if (!body)
+            return;
+        const active = this.stateController.active;
+        body.tabIndex = active !== SENTINEL_NODE && body.isRendered(active.row) ? -1 : 0;
+    }
+    bodyRangeChanged(event) {
+        const { first, last } = event;
+        this.#syncBodyTabStop();
+        const focused = this.renderRoot instanceof ShadowRoot ? this.renderRoot.activeElement : null;
+        if (focused instanceof ApexGridRow &&
+            focused.parentElement === this.scrollContainer &&
+            (focused.index < first || focused.index > last)) {
+            this.scrollContainer.focus({ preventScroll: true });
+        }
+    }
+    #ownCell(event) {
+        if (!this.ownsEvent(event))
+            return undefined;
+        return event.composedPath().find((el) => el instanceof ApexGridCell);
+    }
     bodyClickHandler(event) {
-        const target = event.composedPath().find((el) => el instanceof ApexGridCell);
+        if (!this.ownsEvent(event))
+            return;
+        const path = event.composedPath();
+        const target = path.find((el) => el instanceof ApexGridCell);
         if (target) {
             this.stateController.active = {
                 column: target.column.key,
@@ -740,11 +1093,22 @@ export class ApexGrid extends EventEmitterBase {
             if (!target.editing)
                 target.focus({ preventScroll: true });
         }
+        else {
+            const row = path.find((el) => el instanceof ApexGridRow);
+            const cell = row?.presentedCell;
+            if (row && cell && path.includes(cell)) {
+                const { column } = this.stateController.active;
+                this.stateController.active = { column, row: row.index };
+            }
+        }
     }
     bodyKeydownHandler(event) {
+        if (!this.ownsEvent(event))
+            return;
         const origin = event.composedPath()[0];
         const fromBody = this.scrollContainer.isSameNode(event.target);
-        const fromCell = origin instanceof ApexGridCell && !origin.editing;
+        const fromCell = (origin instanceof ApexGridCell && !origin.editing) ||
+            (event.target instanceof ApexGridRow && event.target.presentedCell === origin);
         if (fromBody || fromCell) {
             this.stateController.navigation.navigate(event);
         }
@@ -759,7 +1123,7 @@ export class ApexGrid extends EventEmitterBase {
             return;
         if (event.type === 'pointermove' && event.buttons === 0)
             return;
-        const target = event.composedPath().find((el) => el instanceof ApexGridCell);
+        const target = this.#ownCell(event);
         if (!target?.row)
             return;
         const kind = event.type === 'pointerdown' ? 'down' : event.type === 'pointerup' ? 'up' : 'over';
@@ -804,6 +1168,7 @@ export class ApexGrid extends EventEmitterBase {
         @click=${this.bodyClickHandler}
         @keydown=${this.bodyKeydownHandler}
         @focusin=${this.bodyFocusHandler}
+        @rangeChanged=${this.bodyRangeChanged}
         @pointerdown=${this.bodyPointerHandler}
         @pointermove=${this.bodyPointerHandler}
         @pointerup=${this.bodyPointerHandler}
@@ -815,8 +1180,6 @@ export class ApexGrid extends EventEmitterBase {
     }
     renderPinnedTop() {
         const rowPin = this.stateController.rowPin;
-        if (!rowPin.enabled)
-            return nothing;
         const rows = rowPin.pinnedRows.top;
         if (rows.length === 0)
             return nothing;
@@ -826,8 +1189,6 @@ export class ApexGrid extends EventEmitterBase {
     }
     renderPinnedBottom() {
         const rowPin = this.stateController.rowPin;
-        if (!rowPin.enabled)
-            return nothing;
         const rows = rowPin.pinnedRows.bottom;
         if (rows.length === 0)
             return nothing;
@@ -948,7 +1309,7 @@ __decorate([
 ], ApexGrid.prototype, "columns", void 0);
 __decorate([
     property({ attribute: false })
-], ApexGrid.prototype, "data", void 0);
+], ApexGrid.prototype, "data", null);
 __decorate([
     property({ attribute: false })
 ], ApexGrid.prototype, "rowId", void 0);
@@ -966,7 +1327,7 @@ __decorate([
 ], ApexGrid.prototype, "pagination", void 0);
 __decorate([
     property({ type: String, attribute: 'quick-filter' })
-], ApexGrid.prototype, "quickFilter", void 0);
+], ApexGrid.prototype, "quickFilter", null);
 __decorate([
     property({ type: Boolean, attribute: 'show-quick-filter' })
 ], ApexGrid.prototype, "showQuickFilter", void 0);
@@ -1027,15 +1388,18 @@ __decorate([
 __decorate([
     watch('data')
 ], ApexGrid.prototype, "dataChanged", null);
-__decorate([
-    watch(PIPELINE)
-], ApexGrid.prototype, "pipeline", null);
 __decorate([
     watch('pagination')
 ], ApexGrid.prototype, "paginationChanged", null);
 __decorate([
     watch('quickFilter')
 ], ApexGrid.prototype, "quickFilterChanged", null);
+__decorate([
+    watch('tree', { waitUntilFirstUpdate: true })
+], ApexGrid.prototype, "treeChanged", null);
+__decorate([
+    watch(PIPELINE)
+], ApexGrid.prototype, "pipeline", null);
 __decorate([
     eventOptions({ capture: true })
 ], ApexGrid.prototype, "bodyClickHandler", null);