apex-grid 3.5.0 → 3.6.0

package/components/cell.d.ts

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

package/components/cell.js

@@ -11,7 +11,7 @@ import { property, query } from 'lit/decorators.js';
 import { gridStateContext } from '../controllers/state.js';
 import { getColumnTypeRenderer } from '../internal/column-types.js';
 import { registerComponent } from '../internal/register.js';
-import { GRID_CELL_TAG } from '../internal/tags.js';
+import { GRID_CELL_TAG, GRID_ROW_TAG } from '../internal/tags.js';
 import { styles } from '../styles/body-cell/body-cell.css.js';
 function isErrorLike(value) {
     return (typeof value === 'object' &&
@@ -19,16 +19,64 @@ function isErrorLike(value) {
         typeof value.code === 'string' &&
         value.code.startsWith('#'));
 }
+function renderedRows(body) {
+    if (!body)
+        return [];
+    return Array.from(body.children).filter((element) => element.localName === GRID_ROW_TAG);
+}
+function tabTarget(count, from, keys, key, step, isFullWidth) {
+    const column = keys[keys.indexOf(key) + step];
+    if (column !== undefined)
+        return { row: from, column };
+    const wrapColumn = keys[step > 0 ? 0 : keys.length - 1];
+    for (let index = from + step; index >= 0 && index < count; index += step) {
+        if (!isFullWidth(index))
+            return { row: index, column: wrapColumn };
+    }
+    return null;
+}
+function nearestCellRow(count, start, step, isFullWidth) {
+    const origin = Math.min(Math.max(start, 0), count - 1);
+    for (let distance = 0; distance < count; distance++) {
+        for (const index of [origin + distance * step, origin - distance * step]) {
+            if (index >= 0 && index < count && !isFullWidth(index))
+                return index;
+        }
+    }
+    return -1;
+}
+function findRenderedCell(body, node) {
+    return renderedRows(body)
+        .find((row) => row.index === node.row)
+        ?.cells.find((cell) => cell.column.key === node.column);
+}
+function scrollRowIntoRange(scroller, body, index) {
+    const rows = renderedRows(body).sort((a, b) => a.index - b.index);
+    const first = rows.at(0);
+    const last = rows.at(-1);
+    if (!first || !last)
+        return;
+    const top = first.getBoundingClientRect().top;
+    const height = (last.getBoundingClientRect().bottom - top) / (last.index - first.index + 1);
+    const view = scroller.getBoundingClientRect();
+    const rowCentre = top + (index - first.index + 0.5) * height;
+    scroller.scrollTop += rowCentre - (view.top + scroller.clientHeight / 2);
+}
 class ApexGridCell extends LitElement {
     constructor() {
         super(...arguments);
         this.active = false;
         this.editing = false;
         this.colindex = 0;
+        this.rowIndex = -1;
         this.decorationVersion = 0;
+        this.dataVersion = 0;
         this.validationVersion = 0;
         this.#decoratedKeys = [];
         this.#errors = null;
+        this.#staged = false;
+        this.#resumed = null;
+        this.#reconnected = false;
         this.#handleClick = (event) => {
             if (this.isEditing) {
                 event.stopPropagation();
@@ -56,9 +104,7 @@ class ApexGridCell extends LitElement {
             this.#startEdit();
         };
         this.#refocusAfterEdit = false;
-        this.#commitWith = async (value) => {
-            return this.editingController.commitCell(value ?? this.#pendingValue);
-        };
+        this.#commit = () => this.editingController.commitCell();
         this.#cancel = () => {
             this.editingController.cancelCell();
         };
@@ -68,7 +114,7 @@ class ApexGridCell extends LitElement {
                 case 'Enter':
                     event.preventDefault();
                     this.#refocusAfterEdit = true;
-                    this.#commitWith();
+                    this.#commit();
                     return;
                 case 'Escape':
                     event.preventDefault();
@@ -76,24 +122,12 @@ class ApexGridCell extends LitElement {
                     this.#cancel();
                     return;
                 case 'Tab':
-                    event.preventDefault();
-                    this.#refocusAfterEdit = true;
-                    this.#commitWith();
+                    this.#commitAndTab(event);
                     return;
                 default:
                     return;
             }
         };
-        this.#handleBlur = () => {
-            if (!this.isEditing)
-                return;
-            if (this.editingController.mode === 'cell') {
-                this.#commitWith();
-            }
-            else {
-                this.editingController.commitCell(this.#pendingValue);
-            }
-        };
         this.#handleCellKeydown = (event) => {
             if (!this.isEditing)
                 return;
@@ -103,11 +137,8 @@ class ApexGridCell extends LitElement {
                 this.#cancel();
                 return;
             }
-            if (event.key === 'Tab') {
-                event.preventDefault();
-                this.#refocusAfterEdit = true;
-                this.#commitWith();
-            }
+            if (event.key === 'Tab')
+                this.#commitAndTab(event);
         };
         this.#handleCellFocusOut = (event) => {
             if (!this.isEditing)
@@ -115,26 +146,23 @@ class ApexGridCell extends LitElement {
             const next = event.relatedTarget;
             if (next && (this.contains(next) || this.shadowRoot?.contains(next)))
                 return;
-            if (this.editingController.mode === 'cell') {
-                this.#commitWith();
-            }
-            else {
-                this.editingController.commitCell(this.#pendingValue);
-            }
+            this.#refocusAfterEdit = false;
+            this.#commit();
         };
         this.#handleTextInput = (event) => {
             const target = event.target;
-            if (this.column.type === 'number') {
+            if (this.#isNumeric) {
                 const numeric = target.valueAsNumber;
-                this.#pendingValue = target.value === '' || Number.isNaN(numeric) ? null : numeric;
+                this.editingController.setDraft(target.value === '' || Number.isNaN(numeric) ? null : numeric);
                 return;
             }
-            this.#pendingValue = target.value;
+            this.editingController.setDraft(target.value);
         };
-        this.#handleCheckboxChange = (event) => {
+        this.#handleCheckboxChange = async (event) => {
             const target = event.target;
-            this.#pendingValue = target.checked;
-            this.#commitWith(target.checked);
+            if (!(await this.editingController.commitCell(target.checked))) {
+                target.checked = !target.checked;
+            }
         };
     }
     static get tagName() {
@@ -152,7 +180,7 @@ class ApexGridCell extends LitElement {
             value: this.value,
         };
         if (this.isEditable) {
-            ctx.commit = (next) => this.editingController.commitImmediate(this.row.index, this.column.key, next);
+            ctx.commit = (next) => this.editingController.commitImmediate(this.row.data, this.column.key, next);
         }
         return ctx;
     }
@@ -167,10 +195,18 @@ class ApexGridCell extends LitElement {
             return false;
         return this.editingController.isEditable(this.column);
     }
+    get #inPinnedBand() {
+        const pin = this.state.rowPin;
+        return pin.hasPinnedRows && pin.enabled && pin.isPinned(this.row.data);
+    }
     #decoratedKeys;
     static #ERROR_ID = 'apex-cell-error';
     #errors;
+    #staged;
+    #resumed;
+    #reconnected;
     connectedCallback() {
+        this.#reconnected = this.hasUpdated && !this.isUpdatePending;
         super.connectedCallback();
         this.setAttribute('role', 'gridcell');
         this.addEventListener('click', this.#handleClick);
@@ -185,7 +221,29 @@ class ApexGridCell extends LitElement {
         this.removeEventListener('focusout', this.#handleCellFocusOut);
         super.disconnectedCallback();
     }
-    willUpdate() {
+    shouldUpdate(changed) {
+        const reconnected = this.#reconnected;
+        this.#reconnected = false;
+        if (!this.hasUpdated || (!changed.size && !reconnected))
+            return true;
+        const tree = this.state?.tree;
+        const readsRow = this.column.cellTemplate || (tree?.enabled && tree.isGroupColumn(this.column.key));
+        for (const key of changed.keys()) {
+            const token = key === 'rowIndex' || key === 'dataVersion';
+            if (key !== 'decorationVersion' && (readsRow || !token))
+                return true;
+        }
+        if (changed.has('decorationVersion') || changed.has('rowIndex'))
+            this.#applyDecoration();
+        return false;
+    }
+    willUpdate(changed) {
+        this.#applyStaged();
+        if (changed.has('editing')) {
+            this.#resumed = this.editing
+                ? this.editingController.heldDraft(this.row.data, this.column.key)
+                : null;
+        }
         if (this.colindex > 0) {
             this.setAttribute('aria-colindex', String(this.colindex));
         }
@@ -210,6 +268,20 @@ class ApexGridCell extends LitElement {
         this.#applyValidation();
         this.#applyDecoration();
     }
+    #applyStaged() {
+        const staged = this.state?.editing?.activeRow
+            ? this.editingController.stagedValues(this.row.data)
+            : null;
+        const key = this.column.key;
+        if (staged?.has(key)) {
+            this.value = staged.get(key);
+            this.#staged = true;
+        }
+        else if (this.#staged) {
+            this.#staged = false;
+            this.value = this.row.data[key];
+        }
+    }
     #applyValidation() {
         const errors = this.state && this.row?.data
             ? (this.editingController?.getCellErrors(this.row.data, this.column.key) ?? null)
@@ -242,7 +314,7 @@ class ApexGridCell extends LitElement {
         const decoration = this.state && this.row
             ? this.state.decorateCell({
                 row: this.row.data,
-                rowIndex: this.row.index,
+                rowIndex: this.#inPinnedBand ? -1 : this.rowIndex,
                 column: this.column,
                 value: this.value,
             })
@@ -266,6 +338,8 @@ class ApexGridCell extends LitElement {
     }
     updated(changed) {
         if (this.isEditing) {
+            if (!changed.has('editing'))
+                return;
             const editor = this.editorElement;
             editor?.focus();
             if (editor instanceof HTMLInputElement) {
@@ -285,22 +359,94 @@ class ApexGridCell extends LitElement {
     #startEdit() {
         if (!this.row)
             return;
-        this.editingController.editCell(this.row.index, this.column.key);
+        this.editingController.editRecord(this.row.data, this.column.key);
     }
-    #pendingValue;
     #refocusAfterEdit;
-    #commitWith;
+    #commit;
     #cancel;
+    #commitAndTab(event) {
+        event.preventDefault();
+        if (this.#inPinnedBand) {
+            this.#refocusAfterEdit = true;
+            void this.#commit();
+            return;
+        }
+        const step = event.shiftKey ? -1 : 1;
+        const host = this.state.host;
+        const body = this.row.parentElement;
+        const record = this.row.data;
+        const origin = this.row.index;
+        const key = this.column.key;
+        const columns = this.row.columns;
+        const keys = this.row.cells.map((cell) => cell.column.key);
+        const settle = async () => {
+            await host.updateComplete;
+            await body?.updateComplete;
+            await Promise.all(renderedRows(body).map((row) => row.updateComplete));
+        };
+        void this.#commit().then(async (committed) => {
+            if (!committed)
+                return;
+            await settle();
+            const items = host.pageItems;
+            const isFullWidth = (index) => items[index] == null ||
+                this.state.presentRow(items[index], { columns, rowIndex: index }) !== null;
+            const from = items.indexOf(record);
+            let target;
+            if (from >= 0) {
+                target = tabTarget(items.length, from, keys, key, step, isFullWidth) ?? {
+                    row: from,
+                    column: key,
+                };
+            }
+            else {
+                const row = nearestCellRow(items.length, origin, step, isFullWidth);
+                target = row < 0 ? null : { row, column: key };
+            }
+            if (!target) {
+                body?.focus({ preventScroll: true });
+                return;
+            }
+            this.state.active = target;
+            await settle();
+            let cell = findRenderedCell(body, target);
+            for (let attempt = 0; !cell && attempt < 3; attempt++) {
+                scrollRowIntoRange(host, body, target.row);
+                await new Promise(requestAnimationFrame);
+                await new Promise(requestAnimationFrame);
+                await settle();
+                cell = findRenderedCell(body, target);
+            }
+            if (!cell) {
+                body?.focus({ preventScroll: true });
+                return;
+            }
+            cell.focus({ preventScroll: true });
+            cell.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+            await new Promise(requestAnimationFrame);
+            await new Promise(requestAnimationFrame);
+            const active = this.state.active;
+            const dropped = !document.activeElement || document.activeElement === document.body;
+            if (dropped && active.row === target.row && active.column === target.column) {
+                findRenderedCell(body, target)?.focus({ preventScroll: true });
+            }
+        });
+    }
     #handleKeydown;
-    #handleBlur;
     #handleCellKeydown;
     #handleCellFocusOut;
+    get #isNumeric() {
+        const type = this.column.type;
+        return type === 'number' || type === 'currency';
+    }
     #handleTextInput;
     #handleCheckboxChange;
+    get #editorValue() {
+        return this.#resumed ? this.#resumed.value : this.value;
+    }
     renderDefaultEditor() {
-        const value = this.value;
+        const value = this.#editorValue;
         if (this.column.type === 'boolean') {
-            this.#pendingValue = Boolean(value);
             return html `<input
         type="checkbox"
         part="editor"
@@ -308,11 +454,9 @@ class ApexGridCell extends LitElement {
         ?checked=${Boolean(value)}
         @change=${this.#handleCheckboxChange}
         @keydown=${this.#handleKeydown}
-        @blur=${this.#handleBlur}
       />`;
         }
-        if (this.column.type === 'number') {
-            this.#pendingValue = value;
+        if (this.#isNumeric) {
             return html `<input
         type="number"
         part="editor"
@@ -320,10 +464,8 @@ class ApexGridCell extends LitElement {
         .value=${value == null ? '' : String(value)}
         @input=${this.#handleTextInput}
         @keydown=${this.#handleKeydown}
-        @blur=${this.#handleBlur}
       />`;
         }
-        this.#pendingValue = value;
         return html `<input
       type="text"
       part="editor"
@@ -331,7 +473,6 @@ class ApexGridCell extends LitElement {
       .value=${value == null ? '' : String(value)}
       @input=${this.#handleTextInput}
       @keydown=${this.#handleKeydown}
-      @blur=${this.#handleBlur}
     />`;
     }
     renderEditor() {
@@ -340,17 +481,16 @@ class ApexGridCell extends LitElement {
             parent: this,
             row: this.row,
             column: this.column,
-            value: this.value,
+            value: this.#editorValue,
             commit: (next) => this.editingController.commitCell(next),
             cancel: () => this.editingController.cancelCell(),
+            setDraft: (next) => this.editingController.setDraft(next),
         };
         if (template) {
-            this.#pendingValue = this.value;
             return template(ctx);
         }
         const typeRenderer = getColumnTypeRenderer(this.column.type);
         if (typeRenderer?.editor) {
-            this.#pendingValue = this.value;
             return typeRenderer.editor(ctx);
         }
         return this.renderDefaultEditor();
@@ -470,9 +610,15 @@ __decorate([
 __decorate([
     property({ attribute: false, type: Number })
 ], ApexGridCell.prototype, "colindex", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGridCell.prototype, "rowIndex", void 0);
 __decorate([
     property({ attribute: false, type: Number })
 ], ApexGridCell.prototype, "decorationVersion", void 0);
+__decorate([
+    property({ attribute: false })
+], ApexGridCell.prototype, "dataVersion", void 0);
 __decorate([
     property({ attribute: false, type: Number })
 ], ApexGridCell.prototype, "validationVersion", void 0);