apex-grid 3.2.0 → 3.4.0

package/components/grid.js

@@ -11,21 +11,38 @@ import { styleMap } from 'lit/directives/style-map.js';
 import { DataOperationsController } from '../controllers/data-operation.js';
 import { GridDOMController } from '../controllers/dom.js';
 import { gridStateContext, StateController } from '../controllers/state.js';
-import { DEFAULT_COLUMN_CONFIG, PIPELINE } from '../internal/constants.js';
+import { localize as resolveLocaleText, } from '../i18n/index.js';
+import { DEFAULT_COLUMN_CONFIG, PIPELINE, SENTINEL_NODE } from '../internal/constants.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 { GRID_TAG } from '../internal/tags.js';
 import { asArray, autoGenerateColumns, getDisplayColumns, getFilterOperandsFor, } 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';
 import ApexFilterRow from './filter-row.js';
+import ApexGridGroupHeaderRow from './group-header-row.js';
 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 = [
+    'columns',
+    'sort',
+    'filter',
+    'quickFilter',
+    'modules',
+    'rowOrder',
+    'tree',
+    'expansion',
+    'rowPinning',
+    'selection',
+    'pagination',
+];
 export class ApexGrid extends EventEmitterBase {
     constructor() {
         super(...arguments);
@@ -48,17 +65,26 @@ export class ApexGrid extends EventEmitterBase {
         this.showQuickFilter = false;
         this.showExport = false;
         this.columnReordering = false;
+        this.columnSeparator = true;
+        this.coordinateHints = false;
+        this.columnMenu = true;
+        this.#autoAriaLabel = null;
+        this.#stateChangedListeners = 0;
+        this.#lastStateJson = null;
     }
     static get tagName() {
         return GRID_TAG;
     }
     static { this.styles = gridStyles; }
     static register() {
-        registerComponent(ApexGrid, ApexVirtualizer, ApexGridRow, ApexGridHeaderRow, ApexFilterRow, ApexGridPaginator, ApexGridToolbar);
+        registerComponent(ApexGrid, ApexVirtualizer, ApexGridRow, ApexGridGroupHeaderRow, ApexGridHeaderRow, ApexFilterRow, ApexGridPaginator, ApexGridToolbar);
     }
     createStateController() {
         return new StateController(this);
     }
+    localize(key, params, fallback) {
+        return resolveLocaleText(this.localeText, key, params, fallback);
+    }
     get selectedRows() {
         return this.stateController.selection.selectedRows();
     }
@@ -83,6 +109,15 @@ export class ApexGrid extends EventEmitterBase {
     isRowSelected(row) {
         return this.stateController.selection.isSelected(row);
     }
+    get hasColumnGroups() {
+        if (!this.columnGroups?.length)
+            return false;
+        const ids = new Set(this.columnGroups.map((group) => group.id));
+        return this.columns.some((column) => !column.hidden && column.group && ids.has(column.group));
+    }
+    get columnGroupDepth() {
+        return this.hasColumnGroups ? 1 : 0;
+    }
     get expandedRows() {
         return this.stateController.expansion.expandedRows();
     }
@@ -161,15 +196,19 @@ export class ApexGrid extends EventEmitterBase {
         return this.dataState.length;
     }
     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 this.dataState;
+            return base;
         if (this.pagination?.mode === 'remote')
-            return this.dataState;
+            return base;
         const { page, pageSize } = this.stateController.pagination;
         if (!pageSize)
-            return this.dataState;
+            return base;
         const start = page * pageSize;
-        return this.dataState.slice(start, start + pageSize);
+        return base.slice(start, start + pageSize);
     }
     get page() {
         return this.stateController.pagination.page;
@@ -227,13 +266,58 @@ export class ApexGrid extends EventEmitterBase {
     }
     updated() {
         this.setAttribute('role', this.stateController.tree.enabled ? 'treegrid' : 'grid');
-        const hasFilter = this.columns.some((column) => column.filter);
-        const headerRows = hasFilter ? 2 : 1;
-        this.setAttribute('aria-rowcount', String(headerRows + this.pageItems.length));
+        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');
+        }
+        else {
+            this.removeAttribute('aria-multiselectable');
+        }
+        if (this.scrollContainer) {
+            this.scrollContainer.tabIndex = this.stateController.active === SENTINEL_NODE ? 0 : -1;
+        }
+        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;
+        }
+        this.#emitStateChangedIfNeeded();
+    }
+    #autoAriaLabel;
+    #stateChangedListeners;
+    #lastStateJson;
+    addEventListener(type, listener, options) {
+        if (type === 'stateChanged') {
+            this.#stateChangedListeners += 1;
+            this.#lastStateJson = this.hasUpdated ? JSON.stringify(this.getState()) : null;
+        }
+        super.addEventListener(type, listener, options);
+    }
+    removeEventListener(type, listener, options) {
+        if (type === 'stateChanged') {
+            this.#stateChangedListeners = Math.max(0, this.#stateChangedListeners - 1);
+        }
+        super.removeEventListener(type, listener, options);
+    }
+    #emitStateChangedIfNeeded() {
+        if (this.#stateChangedListeners === 0)
+            return;
+        const snapshot = this.getState();
+        const json = JSON.stringify(snapshot);
+        if (json === this.#lastStateJson)
+            return;
+        this.#lastStateJson = json;
+        this.emitEvent('stateChanged', { detail: { state: snapshot } });
     }
     firstUpdated() {
         if (typeof getComputedStyle === 'function' && getComputedStyle(this).display !== 'grid') {
@@ -254,6 +338,201 @@ export class ApexGrid extends EventEmitterBase {
     sort(expressions) {
         this.stateController.sorting.sort(expressions);
     }
+    getState(options) {
+        const rowId = options?.rowId ?? this.rowId;
+        const pinned = this.stateController.rowPin.pinnedRows;
+        const manualOrder = this.stateController.rowReorder.getManualOrder();
+        return {
+            version: 1,
+            columns: serializeColumnLayout(this.columns),
+            sort: serializeSort(this.sortExpressions),
+            filter: serializeFilter(this.filterExpressions),
+            quickFilter: this.quickFilter,
+            pagination: { page: this.page, pageSize: this.pageSize },
+            selection: serializeRowRefs(this.selectedRows, this.data, rowId),
+            expansion: serializeRowRefs(this.expandedRows, this.data, rowId),
+            treeExpanded: serializeRowRefs([...this.stateController.tree.expanded], this.data, rowId),
+            treeExpandedKeys: [...this.stateController.tree.expandedKeys],
+            rowPinning: {
+                top: serializeRowRefs(pinned.top, this.data, rowId),
+                bottom: serializeRowRefs(pinned.bottom, this.data, rowId),
+            },
+            rowOrder: manualOrder ? serializeRowRefs(manualOrder, this.data, rowId) : null,
+            modules: this.stateController.serializeModuleState(),
+        };
+    }
+    getSchema() {
+        return {
+            version: 1,
+            columns: this.columns.map((column) => columnSchema(column)),
+            capabilities: {
+                sort: {
+                    directions: ['ascending', 'descending'],
+                    multi: Boolean(this.sortConfiguration?.multiple),
+                },
+                filter: { operandsByType: operandsByType(this.columns) },
+                pagination: Boolean(this.pagination?.enabled),
+                selection: this.selection?.enabled ? (this.selection.mode ?? 'multiple') : false,
+                rowPinning: Boolean(this.rowPinning?.enabled),
+                rowReordering: Boolean(this.rowReordering?.enabled),
+            },
+            state: this.getState(),
+        };
+    }
+    setState(state, options) {
+        const rowId = options?.rowId ?? this.rowId;
+        const strict = options?.strict ?? false;
+        const applied = [];
+        const warnings = [];
+        const warn = (message) => {
+            if (strict)
+                throw new Error(`[apex-grid] setState: ${message}`);
+            warnings.push(message);
+        };
+        const asArray = (value, label) => {
+            if (value === undefined)
+                return null;
+            if (!Array.isArray(value)) {
+                warn(`${label}: expected an array, got ${typeof value}; skipped`);
+                return null;
+            }
+            return value;
+        };
+        const resolveCounted = (refs, label) => {
+            const rows = resolveRowRefs(refs, this.data, rowId);
+            if (rows.length < refs.length) {
+                warn(`${label}: ${refs.length - rows.length} of ${refs.length} row(s) could not be resolved`);
+            }
+            return rows;
+        };
+        if (state.version !== undefined && state.version !== 1) {
+            warn(`unsupported snapshot version ${String(state.version)}; applying recognized slices best-effort`);
+        }
+        const columns = asArray(state.columns, 'columns');
+        if (columns) {
+            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);
+            applied.push('sort');
+        }
+        const filter = asArray(state.filter, 'filter');
+        if (filter) {
+            this.stateController.filtering.reset();
+            const expressions = deserializeFilter(filter, (key) => this.getColumn(key), (snapshot, reason) => warn(`filter: "${snapshot.key}" dropped (${reason})`));
+            if (expressions.length)
+                this.filter(expressions);
+            applied.push('filter');
+        }
+        if (state.quickFilter !== undefined) {
+            if (typeof state.quickFilter === 'string') {
+                this.quickFilter = state.quickFilter;
+                applied.push('quickFilter');
+            }
+            else {
+                warn(`quickFilter: expected a string, got ${typeof state.quickFilter}; skipped`);
+            }
+        }
+        if (state.modules !== undefined) {
+            if (state.modules && typeof state.modules === 'object') {
+                this.stateController.restoreModuleState(state.modules);
+                applied.push('modules');
+            }
+            else {
+                warn(`modules: expected an object, got ${typeof state.modules}; skipped`);
+            }
+        }
+        if (state.rowOrder !== undefined) {
+            if (state.rowOrder === null) {
+                this.stateController.rowReorder.restoreManualOrder(null);
+                applied.push('rowOrder');
+            }
+            else {
+                const order = asArray(state.rowOrder, 'rowOrder');
+                if (order) {
+                    if (this.sortExpressions.length) {
+                        warn('rowOrder dropped: a manual order is mutually exclusive with an active sort');
+                    }
+                    else {
+                        this.stateController.rowReorder.restoreManualOrder(resolveCounted(order, 'rowOrder'));
+                    }
+                    applied.push('rowOrder');
+                }
+            }
+        }
+        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);
+            applied.push('tree');
+        }
+        const expansion = asArray(state.expansion, 'expansion');
+        if (expansion) {
+            this.expandedRows = resolveCounted(expansion, 'expansion');
+            applied.push('expansion');
+        }
+        if (state.rowPinning !== undefined) {
+            const pinning = state.rowPinning;
+            if (pinning && typeof pinning === 'object') {
+                this.stateController.rowPin.restore(resolveCounted(asArray(pinning.top, 'rowPinning.top') ?? [], 'rowPinning.top'), resolveCounted(asArray(pinning.bottom, 'rowPinning.bottom') ?? [], 'rowPinning.bottom'));
+                applied.push('rowPinning');
+            }
+            else {
+                warn(`rowPinning: expected an object, got ${typeof pinning}; skipped`);
+            }
+        }
+        const selection = asArray(state.selection, 'selection');
+        if (selection) {
+            this.selectedRows = resolveCounted(selection, 'selection');
+            applied.push('selection');
+        }
+        if (state.pagination !== undefined) {
+            const pagination = state.pagination;
+            if (pagination && typeof pagination === 'object') {
+                const { page, pageSize } = pagination;
+                if (pageSize !== undefined) {
+                    if (typeof pageSize === 'number' && Number.isFinite(pageSize) && pageSize > 0) {
+                        this.pageSize = pageSize;
+                    }
+                    else {
+                        warn(`pagination: invalid pageSize ${String(pageSize)}; ignored`);
+                    }
+                }
+                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}`);
+                        }
+                    }
+                    else {
+                        warn(`pagination: invalid page ${String(page)}; ignored`);
+                    }
+                }
+                applied.push('pagination');
+            }
+            else {
+                warn(`pagination: expected an object, got ${typeof pagination}; skipped`);
+            }
+        }
+        this.requestUpdate(PIPELINE);
+        const skipped = SET_STATE_SLICES.filter((slice) => !applied.includes(slice));
+        return { applied, skipped, warnings };
+    }
     clearSort(key) {
         this.stateController.sorting.reset(key);
         this.requestUpdate(PIPELINE);
@@ -367,6 +646,33 @@ export class ApexGrid extends EventEmitterBase {
             editing.cancelCell();
         }
     }
+    get canUndo() {
+        return this.stateController.history.canUndo;
+    }
+    get canRedo() {
+        return this.stateController.history.canRedo;
+    }
+    undo() {
+        this.stateController.history.undo();
+    }
+    redo() {
+        this.stateController.history.redo();
+    }
+    clearHistory() {
+        this.stateController.history.clear();
+    }
+    pinRow(row, position = 'top') {
+        return this.stateController.rowPin.pinRow(row, position);
+    }
+    unpinRow(row) {
+        return this.stateController.rowPin.unpinRow(row);
+    }
+    get pinnedRows() {
+        return this.stateController.rowPin.pinnedRows;
+    }
+    moveRow(from, to, position = 'before') {
+        return this.stateController.rowReorder.moveRow(from, to, position);
+    }
     exportToCSV(options = {}) {
         const csv = buildCSV(this, options);
         const filename = options.filename;
@@ -381,6 +687,9 @@ export class ApexGrid extends EventEmitterBase {
     get exportFormats() {
         return [{ id: 'csv', label: 'Export CSV' }];
     }
+    get toolbarActions() {
+        return [];
+    }
     exportAs(formatId, options = {}) {
         if (formatId === 'csv') {
             this.exportToCSV(options);
@@ -428,16 +737,28 @@ export class ApexGrid extends EventEmitterBase {
                 column: target.column.key,
                 row: target.row.index,
             };
+            if (!target.editing)
+                target.focus({ preventScroll: true });
         }
     }
     bodyKeydownHandler(event) {
-        if (this.scrollContainer.isSameNode(event.target)) {
+        const origin = event.composedPath()[0];
+        const fromBody = this.scrollContainer.isSameNode(event.target);
+        const fromCell = origin instanceof ApexGridCell && !origin.editing;
+        if (fromBody || fromCell) {
             this.stateController.navigation.navigate(event);
         }
     }
+    bodyFocusHandler(event) {
+        if (this.scrollContainer.isSameNode(event.target)) {
+            this.stateController.navigation.focusActiveCell();
+        }
+    }
     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);
         if (!target?.row)
             return;
@@ -453,12 +774,25 @@ export class ApexGrid extends EventEmitterBase {
             originalEvent: event,
         });
     }
+    renderGroupHeaderRow() {
+        if (!this.hasColumnGroups)
+            return nothing;
+        return html `
+      <apex-grid-group-header-row
+        style=${styleMap(this.DOM.columnSizes)}
+        .columns=${this.DOM.displayColumns}
+        .pinOffsets=${this.DOM.pinOffsets}
+        .groups=${this.columnGroups ?? []}
+      ></apex-grid-group-header-row>
+    `;
+    }
     renderHeaderRow() {
         return html `
       <apex-grid-header-row
       style=${styleMap(this.DOM.columnSizes)}
       .columns=${this.DOM.displayColumns}
       .pinOffsets=${this.DOM.pinOffsets}
+      .coordinateHints=${this.coordinateHints}
       ></apex-grid-header-row>
     `;
     }
@@ -469,20 +803,48 @@ export class ApexGrid extends EventEmitterBase {
         .renderItem=${this.DOM.rowRenderer}
         @click=${this.bodyClickHandler}
         @keydown=${this.bodyKeydownHandler}
+        @focusin=${this.bodyFocusHandler}
         @pointerdown=${this.bodyPointerHandler}
-        @pointerover=${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))}
+    </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;
+        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)
-            ? html `<apex-filter-row style=${styleMap(this.DOM.columnSizes)}></apex-filter-row>`
+            ? html `<apex-filter-row></apex-filter-row>`
             : nothing;
     }
     renderToolbar() {
-        if (!this.showQuickFilter && !this.showExport)
+        if (!this.showQuickFilter && !this.showExport && this.toolbarActions.length === 0) {
             return nothing;
+        }
         return html `<apex-grid-toolbar
       .value=${this.quickFilter}
       .showQuickFilter=${this.showQuickFilter}
@@ -512,15 +874,48 @@ export class ApexGrid extends EventEmitterBase {
       ${this.stateController.announcement}
     </div>`;
     }
+    renderRowDragGhost() {
+        const ghost = this.stateController.rowReorder.ghost;
+        if (!ghost)
+            return nothing;
+        return html `<div
+      part="row-drag-ghost"
+      style=${styleMap({
+            left: `${ghost.x}px`,
+            top: `${ghost.y}px`,
+            height: `${ghost.height}px`,
+        })}
+    >
+      <span part="row-drag-ghost-grip" aria-hidden="true">
+        <svg viewBox="0 0 16 16" width="16" height="16">
+          <circle cx="6" cy="3.5" r="1.25" />
+          <circle cx="10" cy="3.5" r="1.25" />
+          <circle cx="6" cy="8" r="1.25" />
+          <circle cx="10" cy="8" r="1.25" />
+          <circle cx="6" cy="12.5" r="1.25" />
+          <circle cx="10" cy="12.5" r="1.25" />
+        </svg>
+      </span>
+      ${ghost.cells.map((cell) => html `<span
+            part="row-drag-ghost-cell"
+            style=${styleMap({ width: `${cell.width}px`, textAlign: cell.align })}
+            >${cell.text}</span
+          >`)}
+    </div>`;
+    }
     render() {
         return html `
       ${this.stateController.resizing.renderIndicator()}
       ${this.renderToolbar()}
+      ${this.renderGroupHeaderRow()}
       ${this.renderHeaderRow()}
       ${this.renderFilterRow()}
+      ${this.renderPinnedTop()}
       ${this.renderBody()}
+      ${this.renderPinnedBottom()}
       ${this.renderPaginator()}
       ${this.renderLiveRegion()}
+      ${this.renderRowDragGhost()}
     `;
     }
     announce(message) {
@@ -554,6 +949,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], ApexGrid.prototype, "data", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGrid.prototype, "rowId", void 0);
 __decorate([
     property({ type: Boolean, attribute: 'auto-generate' })
 ], ApexGrid.prototype, "autoGenerate", void 0);
@@ -575,9 +973,15 @@ __decorate([
 __decorate([
     property({ type: Boolean, attribute: 'show-export' })
 ], ApexGrid.prototype, "showExport", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGrid.prototype, "localeText", void 0);
 __decorate([
     property({ type: Boolean, attribute: 'column-reordering' })
 ], ApexGrid.prototype, "columnReordering", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'column-separator', reflect: true })
+], ApexGrid.prototype, "columnSeparator", void 0);
 __decorate([
     property({ attribute: false })
 ], ApexGrid.prototype, "editing", void 0);
@@ -587,6 +991,21 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], ApexGrid.prototype, "expansion", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGrid.prototype, "rowPinning", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGrid.prototype, "rowReordering", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'coordinate-hints' })
+], ApexGrid.prototype, "coordinateHints", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGrid.prototype, "columnMenu", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGrid.prototype, "columnGroups", void 0);
 __decorate([
     property({ attribute: false })
 ], ApexGrid.prototype, "tree", void 0);