apex-grid 3.5.0 → 4.0.0-beta.1

package/components/grid.js

@@ -4,22 +4,26 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var _a;
 import { ContextProvider } from '@lit/context';
 import { html, nothing } from 'lit';
 import { eventOptions, property, query, queryAll, state } from 'lit/decorators.js';
 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 { DEFAULT_PAGINATION } from '../controllers/pagination.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';
@@ -29,20 +33,37 @@ import ApexGridHeaderRow from './header-row.js';
 import ApexGridPaginator from './paginator.js';
 import ApexGridRow from './row.js';
 import ApexGridToolbar from './toolbar.js';
-import ApexVirtualizer from './virtualizer.js';
-const SET_STATE_SLICES = [
+import ApexVirtualizer, { quietResizeObserverLoopNotice } from './virtualizer.js';
+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', '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 keyChanged(key, previous) {
+    return key.some((value, i) => value !== previous[i]);
+}
+function warnDropped(message) {
+    console.warn(`[apex-grid] ${message}`);
+}
 export class ApexGrid extends EventEmitterBase {
     constructor() {
         super(...arguments);
@@ -55,36 +76,75 @@ 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.#rowRecycling = _a.defaultRowRecycling;
         this.coordinateHints = false;
         this.columnMenu = true;
-        this.#autoAriaLabel = null;
-        this.#stateChangedListeners = 0;
+        this.showHeader = true;
+        this.#bodyKey = [];
+        this.#bodyRows = [];
+        this.#pageKey = [];
+        this.#pageItems = [];
+        this.#viewChangePending = false;
+        this.#shapingPending = false;
+        this.#pipelineRun = 0;
+        this.#pipelineSettled = Promise.resolve();
+        this.#settlePipeline = null;
+        this.#pinKey = [];
+        this.#stateChangedListeners = new Map();
         this.#lastStateJson = null;
+        this.#labelObserver = new MutationObserver(() => this.requestUpdate());
     }
     static get tagName() {
         return GRID_TAG;
     }
     static { this.styles = gridStyles; }
+    static { this.defaultRowRecycling = globalThis.__apexRowKeying !== 'item'; }
     static register() {
-        registerComponent(ApexGrid, ApexVirtualizer, ApexGridRow, ApexGridGroupHeaderRow, ApexGridHeaderRow, ApexFilterRow, ApexGridPaginator, ApexGridToolbar);
+        registerComponent(_a, ApexVirtualizer, ApexGridRow, ApexGridGroupHeaderRow, ApexGridHeaderRow, ApexFilterRow, ApexGridPaginator, ApexGridToolbar);
     }
     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);
     }
+    get rowRecycling() {
+        return this.#rowRecycling;
+    }
+    set rowRecycling(value) {
+        this.#rowRecycling = value ?? _a.defaultRowRecycling;
+    }
+    #rowRecycling;
     get selectedRows() {
         return this.stateController.selection.selectedRows();
     }
@@ -160,26 +220,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);
     }
@@ -190,31 +274,75 @@ export class ApexGrid extends EventEmitterBase {
         return getDisplayColumns(this.columns);
     }
     get totalItems() {
-        if (this.pagination?.mode === 'remote') {
-            return Math.max(0, this.pagination?.totalItems ?? 0);
+        return this.stateController.pagination.totalItems;
+    }
+    get bodyRows() {
+        const { rowPin, dataVersion } = this.stateController;
+        const key = [this.dataState, dataVersion, rowPin.version, rowPin.enabled];
+        if (keyChanged(key, this.#bodyKey)) {
+            this.#bodyKey = key;
+            this.#bodyRows = rowPin.hasPinnedRows
+                ? this.dataState.filter((row) => !rowPin.isPinned(row))
+                : this.dataState;
         }
-        return this.dataState.length;
+        return this.#bodyRows;
     }
+    #bodyKey;
+    #bodyRows;
     get pageItems() {
-        const rowPin = this.stateController.rowPin;
-        const base = rowPin?.enabled && rowPin.hasPinnedRows
-            ? this.dataState.filter((row) => !rowPin.isPinned(row))
-            : this.dataState;
-        if (!this.stateController.pagination.enabled)
-            return base;
-        if (this.pagination?.mode === 'remote')
-            return base;
-        const { page, pageSize } = this.stateController.pagination;
-        if (!pageSize)
-            return base;
-        const start = page * pageSize;
-        return base.slice(start, start + pageSize);
+        const { pagination, dataVersion } = this.stateController;
+        const key = [
+            this.bodyRows,
+            dataVersion,
+            pagination.enabled,
+            this.pagination?.mode,
+            pagination.page,
+            pagination.pageSize,
+        ];
+        if (keyChanged(key, this.#pageKey)) {
+            this.#pageKey = key;
+            const base = this.bodyRows;
+            const { page, pageSize } = pagination;
+            this.#pageItems =
+                !pagination.enabled || this.pagination?.mode === 'remote' || !pageSize
+                    ? base
+                    : base.slice(page * pageSize, (page + 1) * pageSize);
+        }
+        return this.#pageItems;
     }
+    #pageKey;
+    #pageItems;
     get page() {
         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 +356,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,63 +393,169 @@ 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);
     }
-    updated() {
-        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));
-        const visibleColumns = this.columns.filter((column) => !column.hidden).length;
-        const extras = (this.stateController.selection.showCheckboxColumn ? 1 : 0) +
-            (this.stateController.expansion.showToggleColumn ? 1 : 0);
-        this.setAttribute('aria-colcount', String(visibleColumns + extras));
-        const selection = this.stateController.selection;
-        if (selection.enabled && selection.mode === 'multiple') {
-            this.setAttribute('aria-multiselectable', 'true');
+    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();
         }
-        else {
-            this.removeAttribute('aria-multiselectable');
+        finally {
+            if (run === this.#pipelineRun) {
+                this.#settlePipeline?.();
+                this.#settlePipeline = null;
+                if (this.#shapingPending) {
+                    this.#shapingPending = false;
+                    this.#baselineStateIfUnset();
+                }
+            }
         }
-        if (this.scrollContainer) {
-            this.scrollContainer.tabIndex = this.stateController.active === SENTINEL_NODE ? 0 : -1;
+    }
+    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`);
+            }
         }
-        const currentLabel = this.getAttribute('aria-label');
-        const authorLabeled = this.hasAttribute('aria-labelledby') ||
-            (currentLabel !== null && currentLabel !== this.#autoAriaLabel);
-        if (!authorLabeled) {
-            const label = this.localize('grid.label');
-            if (currentLabel !== label)
-                this.setAttribute('aria-label', label);
-            this.#autoAriaLabel = label;
+        if (valid.length)
+            this.sort(valid);
+        this.requestUpdate(PIPELINE);
+    }
+    #replaceFilter(entries) {
+        this.#markViewChange();
+        this.stateController.filtering.reset();
+        if (entries.length)
+            this.filter([...entries]);
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        const { rowPin, pagination } = this.stateController;
+        const key = [rowPin.version, rowPin.enabled];
+        if (keyChanged(key, this.#pinKey)) {
+            this.#pinKey = key;
+            if (!changed.has(PIPELINE) && !this.#viewStale)
+                pagination.reclamp();
         }
+    }
+    #pinKey;
+    updated() {
+        this.#viewChangePending = false;
+        this.#syncBodyTabStop();
+        this.stateController.navigation.reconcileFocus();
         this.#emitStateChangedIfNeeded();
     }
-    #autoAriaLabel;
     #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 +563,20 @@ 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);
+        quietResizeObserverLoopNotice();
+        this.#labelObserver.observe(this, {
+            attributeFilter: ['aria-label', 'aria-labelledby', 'aria-describedby'],
+        });
+    }
+    #labelObserver;
     firstUpdated() {
         if (typeof getComputedStyle === 'function' && getComputedStyle(this).display !== 'grid') {
             console.warn('[apex-grid] Host `display` has been overridden. The grid requires ' +
@@ -328,26 +586,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 +643,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 +660,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 +687,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 +718,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 +746,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 +775,19 @@ 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 resolved = resolveCounted(selection, 'selection');
+            const rows = ctrl.selectable(resolved);
+            if (rows.length < resolved.length) {
+                warn(`selection: ${resolved.length - rows.length} row(s) are not selectable; skipped`);
+            }
+            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 +804,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 +826,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 +880,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;
     }
@@ -643,16 +966,22 @@ export class ApexGrid extends EventEmitterBase {
             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 { rowIndex, column, value } of edits) {
-                const record = items.at(rowIndex);
+            for (const { row, rowIndex, column, value } of edits) {
+                const record = row ?? items[rowIndex];
                 const config = this.getColumn(column);
-                if (!record || rowIndex < 0 || !config || !editing.isEditable(config)) {
+                if (!record ||
+                    !config ||
+                    !editing.isEditable(config) ||
+                    !this.stateController.isDataRow(record)) {
                     tally.skipped += 1;
                     continue;
                 }
-                tally[editing.applyCellEdit(rowIndex, column, record, value)] += 1;
+                const index = row ? indexOf(row) : rowIndex;
+                tally[editing.applyCellEdit(index, column, record, value)] += 1;
             }
         }
         finally {
@@ -660,6 +989,8 @@ export class ApexGrid extends EventEmitterBase {
         }
         if (tally.applied > 0)
             this.requestUpdate(PIPELINE);
+        else if (editing.validationVersion !== version)
+            this.requestUpdate();
         return tally;
     }
     cancelEdit() {
@@ -731,22 +1062,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);
@@ -755,8 +1084,43 @@ 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 _a || 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 });
+        }
+        this.stateController.navigation.reconcileFocus();
+    }
+    #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,
@@ -765,26 +1129,43 @@ 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);
         }
     }
     bodyFocusHandler(event) {
-        if (this.scrollContainer.isSameNode(event.target)) {
-            this.stateController.navigation.focusActiveCell();
+        const navigation = this.stateController.navigation;
+        navigation.focusEntered(event, this.ownsEvent(event));
+        if (this.scrollContainer.isSameNode(event.target) &&
+            navigation.forwardsBodyFocus) {
+            navigation.focusActiveCell();
         }
     }
+    bodyFocusOutHandler(event) {
+        this.stateController.navigation.focusLeft(event, this.ownsEvent(event));
+    }
     bodyPointerHandler(event) {
         if (this.stateController.modules.size === 0)
             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 +1185,7 @@ export class ApexGrid extends EventEmitterBase {
             return nothing;
         return html `
       <apex-grid-group-header-row
+        ?data-visually-hidden=${!this.showHeader}
         style=${styleMap(this.DOM.columnSizes)}
         .columns=${this.DOM.displayColumns}
         .pinOffsets=${this.DOM.pinOffsets}
@@ -814,6 +1196,7 @@ export class ApexGrid extends EventEmitterBase {
     renderHeaderRow() {
         return html `
       <apex-grid-header-row
+      ?data-visually-hidden=${!this.showHeader}
       style=${styleMap(this.DOM.columnSizes)}
       .columns=${this.DOM.displayColumns}
       .pinOffsets=${this.DOM.pinOffsets}
@@ -824,45 +1207,42 @@ export class ApexGrid extends EventEmitterBase {
     renderBody() {
         return html `
       <apex-virtualizer
+        role="rowgroup"
         .items=${this.pageItems}
         .renderItem=${this.DOM.rowRenderer}
+        .rowMode=${this.rowRecycling ? 'slot' : 'item'}
         @click=${this.bodyClickHandler}
         @keydown=${this.bodyKeydownHandler}
         @focusin=${this.bodyFocusHandler}
+        @focusout=${this.bodyFocusOutHandler}
+        @rangeChanged=${this.bodyRangeChanged}
         @pointerdown=${this.bodyPointerHandler}
         @pointermove=${this.bodyPointerHandler}
         @pointerup=${this.bodyPointerHandler}
       ></apex-virtualizer>
     `;
     }
-    get headerRowCount() {
-        return this.columnGroupDepth + 1 + (this.columns.some((column) => column.filter) ? 1 : 0);
-    }
     renderPinnedTop() {
         const rowPin = this.stateController.rowPin;
-        if (!rowPin.enabled)
-            return nothing;
         const rows = rowPin.pinnedRows.top;
         if (rows.length === 0)
             return nothing;
         return html `<div part="pinned-rows pinned-top">
-      ${rows.map((data, i) => this.DOM.pinnedRowRenderer(data, i, this.headerRowCount))}
+      ${rows.map((data, i) => this.DOM.pinnedRowRenderer(data, i, this.DOM.headerRowCount))}
     </div>`;
     }
     renderPinnedBottom() {
         const rowPin = this.stateController.rowPin;
-        if (!rowPin.enabled)
-            return nothing;
         const rows = rowPin.pinnedRows.bottom;
         if (rows.length === 0)
             return nothing;
-        const offset = this.headerRowCount + rowPin.pinnedRows.top.length + this.pageItems.length;
+        const offset = this.DOM.headerRowCount + rowPin.pinnedRows.top.length + this.pageItems.length;
         return html `<div part="pinned-rows pinned-bottom">
       ${rows.map((data, i) => this.DOM.pinnedRowRenderer(data, i, offset))}
     </div>`;
     }
     renderFilterRow() {
-        return this.columns.some((column) => column.filter)
+        return this.showHeader && this.columns.some((column) => column.filter)
             ? html `<apex-filter-row></apex-filter-row>`
             : nothing;
     }
@@ -871,22 +1251,27 @@ export class ApexGrid extends EventEmitterBase {
             return nothing;
         }
         return html `<apex-grid-toolbar
+      part="toolbar-host"
+      exportparts="toolbar,toolbar-search,search-field,search-icon,search-input,toolbar-actions,toolbar-action,export,export-trigger,export-icon,export-caret,export-menu,export-menu-item"
       .value=${this.quickFilter}
       .showQuickFilter=${this.showQuickFilter}
       .showExport=${this.showExport}
       @apex-quick-filter=${(event) => {
             event.stopPropagation();
             this.setQuickFilter(event.detail);
+            if (this.quickFilter !== event.detail)
+                event.preventDefault();
         }}
     ></apex-grid-toolbar>`;
     }
     renderPaginator() {
         if (!this.stateController.pagination.enabled)
             return nothing;
-        const options = this.pagination?.pageSizeOptions && this.pagination.pageSizeOptions.length > 0
-            ? this.pagination.pageSizeOptions
-            : [10, 25, 50, 100];
-        return html `<apex-grid-paginator .pageSizeOptions=${options}></apex-grid-paginator>`;
+        return html `<apex-grid-paginator
+      part="paginator-host"
+      exportparts="paginator,paginator-size,paginator-info,paginator-controls,paginator-page,paginator-button,paginator-first,paginator-prev,paginator-next,paginator-last"
+      .pageSizeOptions=${this.pagination?.pageSizeOptions ?? DEFAULT_PAGINATION.pageSizeOptions}
+    ></apex-grid-paginator>`;
     }
     renderLiveRegion() {
         return html `<div
@@ -899,6 +1284,22 @@ export class ApexGrid extends EventEmitterBase {
       ${this.stateController.announcement}
     </div>`;
     }
+    renderColumnDragGhost() {
+        const state = this.stateController.reordering.state;
+        if (!state)
+            return nothing;
+        return html `<div
+      part="drag-ghost"
+      style=${styleMap({
+            left: `${state.ghostX}px`,
+            top: `${state.ghostY}px`,
+            width: `${state.ghostWidth}px`,
+            height: `${state.ghostHeight}px`,
+        })}
+    >
+      ${state.label}
+    </div>`;
+    }
     renderRowDragGhost() {
         const ghost = this.stateController.rowReorder.ghost;
         if (!ghost)
@@ -928,18 +1329,45 @@ export class ApexGrid extends EventEmitterBase {
           >`)}
     </div>`;
     }
+    #refs(attr) {
+        const root = this.getRootNode();
+        const found = (this.getAttribute(attr) ?? '')
+            .split(/\s+/)
+            .flatMap((id) => (id && root.getElementById?.(id)) || []);
+        return found.length ? found : null;
+    }
+    renderTable() {
+        const state = this.stateController;
+        const { top, bottom } = state.rowPin.pinnedRows;
+        const selection = state.selection;
+        const labelledBy = this.#refs('aria-labelledby');
+        const describedBy = this.#refs('aria-describedby');
+        const copy = (refs) => !('ariaLabelledByElements' in Element.prototype) &&
+            refs?.map((el) => el.textContent?.trim()).join(' ');
+        return html `<div
+      part="table"
+      role=${state.hierarchical ? 'treegrid' : 'grid'}
+      aria-rowcount=${this.DOM.headerRowCount + top.length + this.pageItems.length + bottom.length}
+      aria-colcount=${state.colCount}
+      aria-multiselectable=${selection.enabled && selection.mode === 'multiple' ? 'true' : nothing}
+      aria-label=${copy(labelledBy) || this.getAttribute('aria-label') || this.localize('grid.label')}
+      aria-description=${copy(describedBy) || nothing}
+      .ariaLabelledByElements=${labelledBy}
+      .ariaDescribedByElements=${describedBy}
+    >
+      ${this.renderGroupHeaderRow()} ${this.renderHeaderRow()} ${this.renderPinnedTop()}
+      ${this.renderBody()} ${this.renderPinnedBottom()}
+    </div>`;
+    }
     render() {
         return html `
       ${this.stateController.resizing.renderIndicator()}
       ${this.renderToolbar()}
-      ${this.renderGroupHeaderRow()}
-      ${this.renderHeaderRow()}
+      ${this.renderTable()}
       ${this.renderFilterRow()}
-      ${this.renderPinnedTop()}
-      ${this.renderBody()}
-      ${this.renderPinnedBottom()}
       ${this.renderPaginator()}
       ${this.renderLiveRegion()}
+      ${this.renderColumnDragGhost()}
       ${this.renderRowDragGhost()}
     `;
     }
@@ -947,6 +1375,7 @@ export class ApexGrid extends EventEmitterBase {
         this.stateController.setAnnouncement(message);
     }
 }
+_a = ApexGrid;
 __decorate([
     query(ApexVirtualizer.tagName)
 ], ApexGrid.prototype, "scrollContainer", void 0);
@@ -973,7 +1402,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);
@@ -991,7 +1420,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);
@@ -1007,6 +1436,9 @@ __decorate([
 __decorate([
     property({ type: Boolean, attribute: 'column-separator', reflect: true })
 ], ApexGrid.prototype, "columnSeparator", void 0);
+__decorate([
+    property({ attribute: 'row-recycling', converter: (value) => value !== 'false' })
+], ApexGrid.prototype, "rowRecycling", null);
 __decorate([
     property({ attribute: false })
 ], ApexGrid.prototype, "editing", void 0);
@@ -1028,6 +1460,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], ApexGrid.prototype, "columnMenu", void 0);
+__decorate([
+    property({ attribute: 'show-header', converter: (value) => value !== 'false' })
+], ApexGrid.prototype, "showHeader", void 0);
 __decorate([
     property({ attribute: false })
 ], ApexGrid.prototype, "columnGroups", void 0);
@@ -1052,16 +1487,22 @@ __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);
+__decorate([
+    eventOptions({ capture: true })
+], ApexGrid.prototype, "bodyFocusOutHandler", null);
 //# sourceMappingURL=grid.js.map