@tipolox/litgrid-web 1.0.2 → 1.1.0

package/dist/components/DataGrid.js

@@ -1,5 +1,5 @@
 // src/components/DataGrid.ts
-import { LitElement, css, html, render as litRender } from 'lit';
+import { LitElement, css, html, nothing, render as litRender } from 'lit';
 import { cache } from 'lit/directives/cache.js';
 import { createGridEngine } from '@tipolox/litgrid-core';
 import { calculateDisplayLayout, createVariableVirtualizer, createVirtualizer, mapDisplayScrollOffset } from '@tipolox/litgrid-renderer';
@@ -11,6 +11,7 @@ import { normalizeRowHeight } from '../sizing/rowSizing.js';
 import { serializeSelectedCells } from '../clipboard/serializeSelectedCells.js';
 import { serializeSelectedRows } from '../clipboard/serializeSelectedRows.js';
 import { createColumnState, parseColumnState, resolveColumnState } from '../columnState/columnState.js';
+const CELL_CONTROL_SELECTOR = 'a[href], area[href], button, input, select, textarea, summary, audio[controls], video[controls], [tabindex], [contenteditable]:not([contenteditable="false"])';
 const FILTER_OPERATORS = [
     { value: 'contains', label: 'Contains' },
     { value: 'equals', label: 'Equals' },
@@ -60,6 +61,7 @@ export class DataGrid extends LitElement {
         this.scrollbarWidth = 0;
         this.columnDefs = [];
         this.sourceColumnDefs = [];
+        this._inferColumns = true;
         this.columnWidths = new Map();
         this.hiddenColumnKeys = new Set();
         this._columnStateStorageKey = null;
@@ -88,6 +90,11 @@ export class DataGrid extends LitElement {
         this.headerRowElement = null;
         this.activeCell = null;
         this.shouldFocusActiveCell = false;
+        this.gridCellHasFocus = false;
+        this.shouldFocusViewport = false;
+        this.renderedActiveCellId = null;
+        this.renderedRowStart = 0;
+        this.renderedColumnStart = 0;
         this.headerMenuTrigger = null;
         this.shouldFocusHeaderMenu = false;
         this.shouldRestoreHeaderMenuFocus = false;
@@ -143,22 +150,7 @@ export class DataGrid extends LitElement {
             this.requestUpdate();
         };
         this.stopColumnReorder = () => {
-            const state = this.columnReorderState;
-            if (!state)
-                return;
-            this.columnReorderState = null;
-            window.removeEventListener('pointermove', this.handleColumnReorder);
-            window.removeEventListener('pointerup', this.stopColumnReorder);
-            window.removeEventListener('pointercancel', this.stopColumnReorder);
-            this.removeColumnDragPreview();
-            if (state.hasMoved)
-                this.stopBodyResize();
-            if (state.hasMoved && state.sourceIndex !== state.targetIndex) {
-                this.moveColumn(state.columnKey, state.targetIndex);
-            }
-            else {
-                this.requestUpdate();
-            }
+            this.finishColumnReorder();
         };
         this.handleColumnResize = (event) => {
             if (!this.columnResizeState) {
@@ -169,14 +161,7 @@ export class DataGrid extends LitElement {
             this.requestUpdate();
         };
         this.stopColumnResize = () => {
-            if (!this.columnResizeState) {
-                return;
-            }
-            this.columnResizeState = null;
-            this.commitColumnState('resize');
-            this.stopBodyResize();
-            window.removeEventListener('pointermove', this.handleColumnResize);
-            window.removeEventListener('pointerup', this.stopColumnResize);
+            this.finishColumnResize();
         };
         this.handleRowResize = (event) => {
             if (!this.rowResizeState) {
@@ -241,6 +226,8 @@ export class DataGrid extends LitElement {
     static { this.styles = [lightThemeStyles, darkThemeStyles, css `
     :host {
       display: block;
+      min-width: 0;
+      max-width: 100%;
       color: var(--litgrid-color-text);
       font: 14px/1.4 system-ui, sans-serif;
     }
@@ -368,6 +355,8 @@ export class DataGrid extends LitElement {
 
     .header-row-header {
       position: relative;
+      /* Cover translated headers without clipping menus below the header. */
+      z-index: 4;
       height: 36px;
       border-right: 1px solid var(--litgrid-color-border);
     }
@@ -706,6 +695,7 @@ export class DataGrid extends LitElement {
 
     .pagination {
       display: flex;
+      flex-wrap: wrap;
       align-items: center;
       justify-content: flex-end;
       gap: 10px;
@@ -716,8 +706,29 @@ export class DataGrid extends LitElement {
       font-size: 13px;
     }
 
+    .pagination-summary,
+    .pagination-navigation {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: 10px;
+      min-width: 0;
+    }
+
+    .pagination span,
+    .pagination label {
+      white-space: nowrap;
+    }
+
+    .pagination label {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+    }
+
     .pagination button,
     .pagination select {
+      flex-shrink: 0;
       border: 1px solid var(--litgrid-color-border);
       border-radius: 6px;
       background: var(--litgrid-color-surface);
@@ -740,6 +751,10 @@ export class DataGrid extends LitElement {
     }
     updated() {
         this.updateScrollbarWidth();
+        if (this.shouldFocusViewport) {
+            this.shouldFocusViewport = false;
+            this.viewportElement?.focus({ preventScroll: true });
+        }
         this.focusActiveCell();
         this.focusHeaderMenu();
         // Detect actual DOM spacer height after render. Some browsers clamp
@@ -775,6 +790,7 @@ export class DataGrid extends LitElement {
             viewportElement.removeEventListener('scroll', this.handleScroll);
         }
         this.headerRowElement = null;
+        this.viewportElement = null;
         if (this.measureContainer && this.measureContainer.parentNode) {
             this.measureContainer.parentNode.removeChild(this.measureContainer);
         }
@@ -805,6 +821,7 @@ export class DataGrid extends LitElement {
         if (!(viewport instanceof HTMLElement)) {
             return;
         }
+        this.viewportElement = viewport;
         const nextWidth = viewport.offsetWidth - viewport.clientWidth;
         const nextViewportWidth = viewport.clientWidth;
         if (nextWidth !== this.scrollbarWidth || nextViewportWidth !== this.viewportWidth) {
@@ -814,7 +831,7 @@ export class DataGrid extends LitElement {
         }
     }
     getResolvedColumns() {
-        if (this.columnDefs.length > 0) {
+        if (this.columnDefs.length > 0 || !this._inferColumns) {
             return this.columnDefs;
         }
         const firstRow = this.engine.getRows()[0];
@@ -1046,7 +1063,7 @@ export class DataGrid extends LitElement {
             return null;
         }
     }
-    restorePersistedColumnState() {
+    restorePersistedColumnState(notify = true) {
         if (!this._columnStateStorageKey || this.sourceColumnDefs.length === 0)
             return;
         const storage = this.getColumnStateStorage();
@@ -1062,7 +1079,8 @@ export class DataGrid extends LitElement {
             this.hiddenColumnKeys = resolvedState.hiddenKeys;
             this.activeCell = null;
             this.requestUpdate();
-            this.dispatchColumnStateChange('restore');
+            if (notify)
+                this.dispatchColumnStateChange('restore');
         }
         catch {
             // Storage may be unavailable or blocked by browser privacy settings.
@@ -1138,7 +1156,7 @@ export class DataGrid extends LitElement {
         this.columnChooserOpen = false;
         this.columnChooserPosition = null;
         this.shouldFocusHeaderMenu = false;
-        this.shouldRestoreHeaderMenuFocus = restoreFocus && this.headerMenuTrigger !== null;
+        this.shouldRestoreHeaderMenuFocus = restoreFocus;
         this.requestUpdate();
     }
     toggleColumnChooser(event) {
@@ -1147,6 +1165,9 @@ export class DataGrid extends LitElement {
             return;
         }
         if (event?.currentTarget instanceof HTMLElement) {
+            if (!this.activeHeaderMenu && event.currentTarget instanceof HTMLButtonElement) {
+                this.headerMenuTrigger = event.currentTarget;
+            }
             const shell = this.renderRoot.querySelector('.shell');
             const menu = event.currentTarget.closest('.header-menu');
             const anchorBounds = (menu ?? event.currentTarget).getBoundingClientRect();
@@ -1172,13 +1193,17 @@ export class DataGrid extends LitElement {
         this.columnChooserOpen = false;
         this.columnChooserPosition = null;
         this.shouldFocusHeaderMenu = false;
-        this.shouldRestoreHeaderMenuFocus = restoreFocus && this.headerMenuTrigger !== null;
+        this.shouldRestoreHeaderMenuFocus = restoreFocus;
         this.requestUpdate();
     }
     focusHeaderMenu() {
         if (this.shouldRestoreHeaderMenuFocus) {
             this.shouldRestoreHeaderMenuFocus = false;
-            this.headerMenuTrigger?.focus();
+            const target = this.headerMenuTrigger?.isConnected
+                ? this.headerMenuTrigger
+                : this.renderRoot.querySelector('.header-action-button, .columns-button')
+                    ?? this.viewportElement;
+            target?.focus();
             this.headerMenuTrigger = null;
             return;
         }
@@ -1199,12 +1224,16 @@ export class DataGrid extends LitElement {
         this.closeHeaderMenu(true);
     }
     handleViewportFocus(event) {
-        if (event.target !== event.currentTarget || this.activeCell) {
+        if (event.target !== event.currentTarget || this.activeCell || this.engine.getRowCount() === 0 || this.getVisibleColumns().length === 0) {
             return;
         }
         this.setActiveCell(0, 0);
         this.requestUpdate();
     }
+    handleGridFocusIn(event) {
+        const target = event.composedPath()[0];
+        this.gridCellHasFocus = target instanceof HTMLElement && target.classList.contains('cell');
+    }
     announceScreenReader(message) {
         if (!this.screenReaderAnnouncements || !message || message === this.lastScreenReaderAnnouncement) {
             return;
@@ -1214,7 +1243,18 @@ export class DataGrid extends LitElement {
         this.requestUpdate();
     }
     getScreenReaderDescription() {
-        return this.ariaDescription || 'Use arrow keys to move between cells. Press Enter or Space to select. Press Control or Command C to copy selected cells or rows.';
+        if (this.ariaDescription)
+            return this.ariaDescription;
+        const mode = this.engine.getConfig().selection.mode;
+        const navigation = 'Use arrow keys to move between cells. Press F2 to interact with controls in a cell and Escape to return to cell navigation.';
+        if (mode === 'none')
+            return navigation;
+        const selection = mode === 'multi-row'
+            ? 'Press Enter or Space to select a row. Hold Control or Command to toggle a row, or Shift to select a range of rows.'
+            : mode === 'multi-cell'
+                ? 'Press Enter or Space to toggle a cell.'
+                : `Press Enter or Space to select a ${mode === 'row' ? 'row' : 'cell'}.`;
+        return `${navigation} ${selection} Press Control or Command C to copy selected cells or rows.`;
     }
     getColumnLabel(columnKey) {
         const column = this.getVisibleColumns().find((item) => item.key === columnKey)
@@ -1238,8 +1278,11 @@ export class DataGrid extends LitElement {
     announceActiveCell() {
         this.announceScreenReader(this.getActiveCellAnnouncement());
     }
-    announceRowSelection(rowIndex) {
-        this.announceScreenReader(`Row ${rowIndex + 1} ${this.engine.isRowSelected(rowIndex) ? 'selected' : 'deselected'}.`);
+    announceRowSelection(rowIndex, intent = 'replace') {
+        const anchor = this.engine.getSelection().anchorRowIndex ?? rowIndex;
+        this.announceScreenReader(intent === 'range' && anchor !== rowIndex
+            ? `Rows ${Math.min(anchor, rowIndex) + 1} through ${Math.max(anchor, rowIndex) + 1} selected.`
+            : `Row ${rowIndex + 1} ${this.engine.isRowSelected(rowIndex) ? 'selected' : 'deselected'}.`);
     }
     announceCellSelection(rowIndex, columnKey) {
         this.announceScreenReader(`${this.getColumnLabel(columnKey)}, row ${rowIndex + 1} ${this.engine.isCellSelected(rowIndex, columnKey) ? 'selected' : 'deselected'}.`);
@@ -1252,27 +1295,27 @@ export class DataGrid extends LitElement {
         this.engine.sortBy(columnKey, 'asc');
         this.announceScreenReader(`${this.getColumnLabel(columnKey)} sorted ascending.`);
         this.requestUpdate();
-        this.closeHeaderMenu();
+        this.closeHeaderMenu(true);
     }
     handleSortDescending(columnKey) {
         this.engine.sortBy(columnKey, 'desc');
         this.announceScreenReader(`${this.getColumnLabel(columnKey)} sorted descending.`);
         this.requestUpdate();
-        this.closeHeaderMenu();
+        this.closeHeaderMenu(true);
     }
     handleClearSort() {
         this.engine.clearSort();
         this.announceScreenReader('Sorting cleared.');
         this.requestUpdate();
-        this.closeHeaderMenu();
+        this.closeHeaderMenu(true);
     }
     handleBestFit(columnKey) {
         this.bestFitColumn(columnKey);
-        this.closeHeaderMenu();
+        this.closeHeaderMenu(true);
     }
     handleBestFitAllColumns() {
         this.bestFitAllColumns();
-        this.closeHeaderMenu();
+        this.closeHeaderMenu(true);
     }
     getTextMeasureContext() {
         if (this.textMeasureContext) {
@@ -1428,7 +1471,7 @@ export class DataGrid extends LitElement {
     }
     toggleQuickSearch() {
         this.quickSearchVisible = !this.quickSearchVisible;
-        this.closeHeaderMenu();
+        this.closeHeaderMenu(true);
     }
     handleQuickSearchInput(query) {
         this.quickSearchDraft = query;
@@ -1488,18 +1531,35 @@ export class DataGrid extends LitElement {
         return this.engine.getTotalRowCount();
     }
     selectRow(rowIndex, intent) {
-        this.engine.selectRow(rowIndex, intent);
-        this.announceRowSelection(rowIndex);
+        if (!this.isRowSelectionMode() || !Number.isInteger(rowIndex) || rowIndex < 0 || rowIndex >= this.engine.getRowCount())
+            return;
+        const effectiveIntent = this.engine.getConfig().selection.mode === 'row' ? 'replace' : intent ?? 'replace';
+        const previous = this.engine.getSelection();
+        // The engine's range operation always produces a contiguous anchored range.
+        // Its endpoint and size identify a repeated operation without scanning rows.
+        const unchanged = effectiveIntent === 'range'
+            ? previous.rowIndex === rowIndex && previous.rowIndexes.size === Math.abs((previous.anchorRowIndex ?? rowIndex) - rowIndex) + 1
+            : effectiveIntent === 'replace' && previous.rowIndexes.size === 1 && previous.rowIndexes.has(rowIndex);
+        this.engine.selectRow(rowIndex, effectiveIntent);
+        if (!unchanged)
+            this.announceRowSelection(rowIndex, effectiveIntent);
         this.requestUpdate();
     }
     selectAllRows() {
+        if (this.engine.getConfig().selection.mode !== 'multi-row' || this.engine.getRowCount() === 0)
+            return;
+        const unchanged = this.engine.getSelection().rowIndexes.size === this.engine.getRowCount();
         this.engine.selectAllRows();
-        this.announceScreenReader(`All ${this.engine.getRowCount()} displayed rows selected.`);
+        if (!unchanged)
+            this.announceScreenReader(`All ${this.engine.getRowCount()} displayed rows selected.`);
         this.requestUpdate();
     }
     clearSelection() {
+        const previous = this.engine.getSelection();
+        const hadSelection = previous.rowIndexes.size > 0 || previous.cells.size > 0;
         this.engine.clearSelection();
-        this.announceScreenReader('Selection cleared.');
+        if (hadSelection)
+            this.announceScreenReader('Selection cleared.');
         this.requestUpdate();
     }
     getSelection() {
@@ -1561,11 +1621,11 @@ export class DataGrid extends LitElement {
             ...filter,
             value: this.isValueFreeFilter(filter.operator) ? undefined : filter.value
         });
-        this.closeHeaderMenu();
+        this.closeHeaderMenu(true);
     }
     clearHeaderFilter(columnKey) {
         this.clearFilter(columnKey);
-        this.closeHeaderMenu();
+        this.closeHeaderMenu(true);
     }
     isColumnFiltered(columnKey) {
         return this.engine.getFilters().some((filter) => filter.columnKey === columnKey);
@@ -1663,6 +1723,24 @@ export class DataGrid extends LitElement {
         this.columnDragPreview?.remove();
         this.columnDragPreview = null;
     }
+    finishColumnReorder(commit = true) {
+        const state = this.columnReorderState;
+        if (!state)
+            return;
+        this.columnReorderState = null;
+        window.removeEventListener('pointermove', this.handleColumnReorder);
+        window.removeEventListener('pointerup', this.stopColumnReorder);
+        window.removeEventListener('pointercancel', this.stopColumnReorder);
+        this.removeColumnDragPreview();
+        if (state.hasMoved)
+            this.stopBodyResize();
+        if (commit && state.hasMoved && state.sourceIndex !== state.targetIndex) {
+            this.moveColumn(state.columnKey, state.targetIndex);
+        }
+        else {
+            this.requestUpdate();
+        }
+    }
     getGridCellId(rowIndex, columnIndex) {
         return `${this.gridId}-cell-${rowIndex}-${columnIndex}`;
     }
@@ -1709,6 +1787,17 @@ export class DataGrid extends LitElement {
         window.addEventListener('pointermove', this.handleColumnResize);
         window.addEventListener('pointerup', this.stopColumnResize);
     }
+    finishColumnResize(commit = true) {
+        if (!this.columnResizeState) {
+            return;
+        }
+        this.columnResizeState = null;
+        if (commit)
+            this.commitColumnState('resize');
+        this.stopBodyResize();
+        window.removeEventListener('pointermove', this.handleColumnResize);
+        window.removeEventListener('pointerup', this.stopColumnResize);
+    }
     startRowResize(event, rowIndex) {
         event.preventDefault();
         event.stopPropagation();
@@ -1787,8 +1876,23 @@ export class DataGrid extends LitElement {
         this.shouldFocusActiveCell = shouldFocus;
         this.announceActiveCell();
     }
+    reconcileActiveCell(rowCount, columnCount) {
+        if (!this.activeCell)
+            return;
+        if (rowCount === 0 || columnCount === 0) {
+            this.activeCell = null;
+            this.shouldFocusActiveCell = false;
+            return;
+        }
+        const rowIndex = Math.min(this.activeCell.rowIndex, rowCount - 1);
+        const columnIndex = Math.min(this.activeCell.columnIndex, columnCount - 1);
+        if (rowIndex !== this.activeCell.rowIndex || columnIndex !== this.activeCell.columnIndex) {
+            this.activeCell = { rowIndex, columnIndex };
+            this.shouldFocusActiveCell = this.gridCellHasFocus;
+        }
+    }
     focusActiveCell() {
-        if (!this.shouldFocusActiveCell || !this.activeCell) {
+        if (!this.shouldFocusActiveCell || !this.activeCell || !this.renderedActiveCellId) {
             return;
         }
         const cell = this.renderRoot.querySelector(`.cell[data-row-index="${this.activeCell.rowIndex}"][data-column-index="${this.activeCell.columnIndex}"]`);
@@ -1892,32 +1996,115 @@ export class DataGrid extends LitElement {
             viewport.scrollLeft = Math.max(0, columnRight - bodyViewportWidth);
         }
     }
+    getCellControls(cell) {
+        // Only inspect the cell explicitly entered by the user, never a render or
+        // virtualization path. Custom focusable hosts can own shadow controls.
+        return Array.from(cell.querySelectorAll(CELL_CONTROL_SELECTOR))
+            .filter((control) => !control.matches(':disabled, input[type="hidden"]')
+            && !control.closest('[hidden], [inert]'));
+    }
+    focusCellControl(control) {
+        control.focus({ preventScroll: true });
+        return control.getRootNode().activeElement === control;
+    }
+    syncInteractionCell(cell) {
+        const rowIndex = Number(cell.dataset.rowIndex);
+        const columnIndex = Number(cell.dataset.columnIndex);
+        if (this.activeCell?.rowIndex !== rowIndex || this.activeCell.columnIndex !== columnIndex) {
+            this.setActiveCell(rowIndex, columnIndex);
+            this.requestUpdate();
+        }
+    }
     handleKeyDown(event) {
-        const target = event.target;
-        if (target instanceof HTMLInputElement || target instanceof HTMLSelectElement || target instanceof HTMLButtonElement) {
+        if (event.defaultPrevented)
             return;
+        let owningCell;
+        let insideControl = false;
+        // The composed path also protects nested markup and renderer shadow controls.
+        for (const target of event.composedPath()) {
+            if (!(target instanceof Element))
+                continue;
+            if (target.matches('.cell[role="gridcell"]')) {
+                owningCell = target;
+                break;
+            }
+            if (target === event.currentTarget)
+                break;
+            if (target.matches(CELL_CONTROL_SELECTOR))
+                insideControl = true;
+        }
+        if (insideControl) {
+            if (!owningCell)
+                return;
+            if (event.key === 'Escape') {
+                event.preventDefault();
+                event.stopPropagation();
+                this.syncInteractionCell(owningCell);
+                owningCell.focus({ preventScroll: true });
+                return;
+            }
+            const focused = this.renderRoot.activeElement;
+            if (event.key !== 'Tab' || !focused || focused === owningCell || !owningCell.contains(focused))
+                return;
+            // An open shadow widget owns the Tab order of its internal controls.
+            if (focused.shadowRoot?.activeElement)
+                return;
+            const controls = this.getCellControls(owningCell).filter((control) => control.tabIndex >= 0
+                || control === focused || control.matches('[contenteditable]:not([tabindex])'));
+            const current = controls.indexOf(focused);
+            // Shadow widgets own their internal Tab order; a focusable host is their entry point.
+            if (current < 0)
+                return;
+            const direction = event.shiftKey ? -1 : 1;
+            for (let index = current + direction; index >= 0 && index < controls.length; index += direction) {
+                if (this.focusCellControl(controls[index])) {
+                    event.preventDefault();
+                    return;
+                }
+            }
+            this.syncInteractionCell(owningCell);
+            if (event.shiftKey) {
+                event.preventDefault();
+                owningCell.focus({ preventScroll: true });
+                return;
+            }
+            // At the last control, resume the existing forward cell Tab navigation.
         }
         const rowCount = this.engine.getRowCount();
         const columnCount = this.getVisibleColumns().length;
+        this.reconcileActiveCell(rowCount, columnCount);
         if (rowCount === 0 || columnCount === 0) {
             return;
         }
-        if ((event.key === 'Enter' || event.key === ' ') && !event.ctrlKey && !event.metaKey && !event.altKey) {
+        if (event.key === 'F2' && !event.altKey && !event.ctrlKey && !event.metaKey && !event.shiftKey) {
+            const active = this.activeCell ?? { rowIndex: 0, columnIndex: 0 };
+            const cell = owningCell ?? this.renderRoot.querySelector(`.cell[data-row-index="${active.rowIndex}"][data-column-index="${active.columnIndex}"]`);
+            if (cell) {
+                for (const control of this.getCellControls(cell)) {
+                    if (this.focusCellControl(control)) {
+                        event.preventDefault();
+                        break;
+                    }
+                }
+            }
+            return;
+        }
+        if ((event.key === 'Enter' || event.key === ' ') && !event.altKey) {
             const activeCell = this.activeCell ?? { rowIndex: 0, columnIndex: 0 };
-            if (this.isCellSelectionMode()) {
+            if (this.isCellSelectionMode() && !event.ctrlKey && !event.metaKey) {
                 const column = this.getVisibleColumns()[activeCell.columnIndex];
                 if (column) {
                     event.preventDefault();
+                    const unchanged = this.engine.getConfig().selection.mode === 'cell' && this.engine.isCellSelected(activeCell.rowIndex, column.key);
                     this.engine.selectCell(activeCell.rowIndex, column.key);
-                    this.announceCellSelection(activeCell.rowIndex, column.key);
+                    if (!unchanged)
+                        this.announceCellSelection(activeCell.rowIndex, column.key);
                     this.requestUpdate();
                 }
             }
             else if (this.isRowSelectionMode()) {
                 event.preventDefault();
-                this.engine.selectRow(activeCell.rowIndex, 'replace');
-                this.announceRowSelection(activeCell.rowIndex);
-                this.requestUpdate();
+                this.selectRow(activeCell.rowIndex, this.getRowSelectionIntent(event));
             }
             return;
         }
@@ -1996,9 +2183,7 @@ export class DataGrid extends LitElement {
         if (!this.isRowSelectionMode()) {
             return;
         }
-        this.engine.selectRow(rowIndex, this.getRowSelectionIntent(event));
-        this.announceRowSelection(rowIndex);
-        this.requestUpdate();
+        this.selectRow(rowIndex, this.getRowSelectionIntent(event));
     }
     handleRowMouseDown(event) {
         if (this.isRowSelectionMode() && event.shiftKey) {
@@ -2012,8 +2197,10 @@ export class DataGrid extends LitElement {
             return;
         }
         event.stopPropagation();
+        const unchanged = this.engine.getConfig().selection.mode === 'cell' && this.engine.isCellSelected(rowIndex, column.key);
         this.engine.selectCell(rowIndex, column.key);
-        this.announceCellSelection(rowIndex, column.key);
+        if (!unchanged)
+            this.announceCellSelection(rowIndex, column.key);
         this.requestUpdate();
     }
     renderCell(column, row, rowIndex) {
@@ -2066,7 +2253,6 @@ export class DataGrid extends LitElement {
     `;
     }
     set data(value) {
-        this.activeCell = null;
         this.clearQuickSearchDebounce();
         this.sourceRowCount = Array.isArray(value) ? value.length : 0;
         this.engine.setData(value ?? []);
@@ -2076,9 +2262,7 @@ export class DataGrid extends LitElement {
         this.requestUpdate();
     }
     handleRowCheckboxChange(rowIndex) {
-        this.engine.selectRow(rowIndex, 'toggle');
-        this.announceRowSelection(rowIndex);
-        this.requestUpdate();
+        this.selectRow(rowIndex, 'toggle');
     }
     getDisplayedSelectedRowCount() {
         const rowCount = this.engine.getRowCount();
@@ -2109,13 +2293,89 @@ export class DataGrid extends LitElement {
         }
         this.requestUpdate();
     }
+    get inferColumns() {
+        return this._inferColumns;
+    }
+    set inferColumns(value) {
+        if (this._inferColumns === value)
+            return;
+        this._inferColumns = value;
+        this.requestUpdate();
+    }
+    /** Reconcile an explicit schema, optionally switching its persistence namespace atomically. */
+    updateColumnSchema(value, applyOrder = false, storageKey = this._columnStateStorageKey) {
+        const columns = value.map(column => ({ ...column }));
+        const nextByKey = new Map(columns.map(column => [column.key, column]));
+        if (nextByKey.size !== columns.length)
+            throw new Error('Duplicate column schema keys.');
+        const previousByKey = new Map(this.sourceColumnDefs.map(column => [column.key, column]));
+        const activeCell = this.activeCell;
+        const activeColumnKey = activeCell
+            ? this.getVisibleColumns()[activeCell.columnIndex]?.key
+            : undefined;
+        const nextStorageKey = typeof storageKey === 'string' && storageKey.trim() ? storageKey : null;
+        const storageChanged = nextStorageKey !== this._columnStateStorageKey;
+        this.finishColumnResize(false);
+        this.finishColumnReorder(false);
+        if (storageChanged) {
+            // Install the target schema and defaults before restoring its namespace.
+            // Do not reconcile/persist the outgoing view, or carry its customization
+            // into an unsaved target. A namespace switch itself performs no writes.
+            this._columnStateStorageKey = nextStorageKey;
+            this.sourceColumnDefs = columns;
+            this.columnDefs = [...columns];
+            this.columnWidths.clear();
+            this.hiddenColumnKeys = new Set(columns.filter(column => column.hidden).map(column => column.key));
+            this.restorePersistedColumnState(false);
+        }
+        else {
+            for (const key of this.columnWidths.keys()) {
+                if (!nextByKey.has(key))
+                    this.columnWidths.delete(key);
+            }
+            for (const key of this.hiddenColumnKeys) {
+                if (!nextByKey.has(key))
+                    this.hiddenColumnKeys.delete(key);
+            }
+            for (const column of columns) {
+                const previous = previousByKey.get(column.key);
+                if (!previous || previous.width !== column.width)
+                    this.columnWidths.delete(column.key);
+                if (!previous || previous.hidden !== column.hidden) {
+                    if (column.hidden)
+                        this.hiddenColumnKeys.add(column.key);
+                    else
+                        this.hiddenColumnKeys.delete(column.key);
+                }
+            }
+            // Surviving columns keep user order; newly registered columns follow them.
+            // An explicit Order change reapplies the complete deterministic schema order.
+            const retained = this.columnDefs.filter(column => nextByKey.has(column.key))
+                .map(column => nextByKey.get(column.key));
+            const retainedKeys = new Set(retained.map(column => column.key));
+            this.columnDefs = applyOrder ? columns : [
+                ...retained, ...columns.filter(column => !retainedKeys.has(column.key))
+            ];
+            this.sourceColumnDefs = columns;
+            this.persistColumnState();
+        }
+        this.clearBestFitWidths();
+        if (activeCell) {
+            const columnIndex = this.getVisibleColumns().findIndex(column => column.key === activeColumnKey);
+            this.activeCell = columnIndex < 0 ? null : { ...activeCell, columnIndex };
+        }
+        this.requestUpdate();
+    }
     set columns(value) {
-        this.activeCell = null;
+        const activeCell = this.activeCell;
         this.sourceColumnDefs = Array.isArray(value) ? [...value] : [];
         this.columnDefs = [...this.sourceColumnDefs];
         this.hiddenColumnKeys = new Set(this.sourceColumnDefs.filter((column) => column.hidden).map((column) => column.key));
         this.clearBestFitWidths();
         this.restorePersistedColumnState();
+        // Structural synchronization must not discard navigation. This also
+        // restores the position after persisted column state has been applied.
+        this.activeCell = activeCell;
         this.requestUpdate();
     }
     get columnStateStorageKey() {
@@ -2210,6 +2470,7 @@ export class DataGrid extends LitElement {
         }
         // Ensure start/end indices are within valid bounds to avoid empty renders
         const safeStartIndex = Math.max(0, Math.min(range.startIndex, Math.max(0, count)));
+        let renderedRowStart = safeStartIndex;
         const safeEndIndex = Math.max(safeStartIndex, Math.min(range.endIndex, count));
         let rows = this.engine.getVisibleRows(safeStartIndex, safeEndIndex);
         if (rows.length === 0 && count > 0) {
@@ -2219,6 +2480,7 @@ export class DataGrid extends LitElement {
             const fallbackStart = Math.max(0, count - visibleCountFallback);
             const fallbackEnd = count;
             rows = this.engine.getVisibleRows(fallbackStart, fallbackEnd);
+            renderedRowStart = fallbackStart;
         }
         const columns = this.getVisibleColumns();
         const columnWidths = columns.map((column) => this.getColumnWidth(column));
@@ -2230,6 +2492,23 @@ export class DataGrid extends LitElement {
         });
         const columnRange = this.columnVirtualizer.getState();
         const visibleColumns = columns.slice(columnRange.startIndex, columnRange.endIndex);
+        this.reconcileActiveCell(count, columns.length);
+        const activeCellIsRendered = this.activeCell !== null
+            && this.activeCell.rowIndex >= renderedRowStart
+            && this.activeCell.rowIndex < renderedRowStart + rows.length
+            && this.activeCell.columnIndex >= columnRange.startIndex
+            && this.activeCell.columnIndex < columnRange.endIndex;
+        this.renderedActiveCellId = activeCellIsRendered && this.activeCell
+            ? this.getGridCellId(this.activeCell.rowIndex, this.activeCell.columnIndex)
+            : null;
+        if (!activeCellIsRendered || this.renderedRowStart !== renderedRowStart || this.renderedColumnStart !== columnRange.startIndex) {
+            // Preserve logical navigation when the cell leaves either rendered range.
+            // A focused node can also be reused for another cell when the range moves.
+            // Hand off once; later scroll renders don't touch focus on the viewport.
+            this.shouldFocusViewport = this.gridCellHasFocus;
+        }
+        this.renderedRowStart = renderedRowStart;
+        this.renderedColumnStart = columnRange.startIndex;
         const visibleColumnWidths = columnWidths.slice(columnRange.startIndex, columnRange.endIndex);
         const isFirstVisibleColumn = (column, index) => index === 0;
         const gridTemplate = [
@@ -2439,22 +2718,25 @@ export class DataGrid extends LitElement {
         </div>
                 ${visibleColumns.length === 0
             ? html `<div class="column-chooser-empty">
-              <button type="button" @click=${() => this.toggleColumnChooser()}>Columns</button>
+              <button class="columns-button" type="button" @click=${(event) => this.toggleColumnChooser(event)}>Columns</button>
             </div>`
             : ''}
                 <div
                     class="viewport"
           role="grid"
+          aria-multiselectable=${['multi-row', 'multi-cell'].includes(this.engine.getConfig().selection.mode) ? 'true' : nothing}
           aria-label=${this.ariaLabel || 'Data grid'}
           aria-rowcount=${count + 1}
           aria-colcount=${columns.length + (this.isRowHeaderVisible() ? 1 : 0)}
-          aria-activedescendant=${this.activeCell ? this.getGridCellId(this.activeCell.rowIndex, this.activeCell.columnIndex) : undefined}
+          aria-activedescendant=${this.renderedActiveCellId ?? nothing}
           aria-describedby=${`${this.gridId}-description`}
           aria-owns=${this.getHeaderRowId()}
           style=${`--grid-height: ${this.height}px;`}
           tabindex="0"
           @scroll=${this.handleScroll}
           @focus=${this.handleViewportFocus}
+          @focusin=${this.handleGridFocusIn}
+          @focusout=${() => { this.gridCellHasFocus = false; }}
 
           @keydown=${this.handleKeyDown}
           @click=${() => this.closeHeaderMenu()}
@@ -2466,7 +2748,7 @@ export class DataGrid extends LitElement {
               style=${`--offset-top: ${displayOffsetTop}px; padding-bottom: ${displayBottomPadding}px;`}
             >
               ${rows.map((row, index) => {
-            const rowIndex = range.startIndex + index;
+            const rowIndex = renderedRowStart + index;
             const height = this.getRowHeight(rowIndex);
             return html `
                                     <div
@@ -2491,31 +2773,35 @@ export class DataGrid extends LitElement {
         ${pagination.enabled
             ? html `
               <div class="pagination" role="navigation" aria-label="Pagination">
-                <span>${pagination.totalRows} rows</span>
-                <label>
-                  Rows per page
-                  <select
-                    aria-label="Rows per page"
-                    @change=${(event) => this.setPageSize(Number(event.target.value))}
-                  >
-                    ${pageSizeOptions.map((pageSize) => html `
-                      <option value=${pageSize} ?selected=${pageSize === pagination.pageSize}>
-                        ${pageSize}
-                      </option>
-                    `)}
-                  </select>
-                </label>
-                <span>Page ${pagination.pageCount === 0 ? 0 : pagination.pageIndex + 1} of ${pagination.pageCount}</span>
-                <button
-                  type="button"
-                  ?disabled=${pagination.pageIndex === 0}
-                  @click=${() => this.setPage(pagination.pageIndex - 1)}
-                >Previous</button>
-                <button
-                  type="button"
-                  ?disabled=${pagination.pageCount === 0 || pagination.pageIndex >= pagination.pageCount - 1}
-                  @click=${() => this.setPage(pagination.pageIndex + 1)}
-                >Next</button>
+                <div class="pagination-summary">
+                  <span>${pagination.totalRows} rows</span>
+                  <label>
+                    Rows per page
+                    <select
+                      aria-label="Rows per page"
+                      @change=${(event) => this.setPageSize(Number(event.target.value))}
+                    >
+                      ${pageSizeOptions.map((pageSize) => html `
+                        <option value=${pageSize} ?selected=${pageSize === pagination.pageSize}>
+                          ${pageSize}
+                        </option>
+                      `)}
+                    </select>
+                  </label>
+                </div>
+                <div class="pagination-navigation">
+                  <span>Page ${pagination.pageCount === 0 ? 0 : pagination.pageIndex + 1} of ${pagination.pageCount}</span>
+                  <button
+                    type="button"
+                    ?disabled=${pagination.pageIndex === 0}
+                    @click=${() => this.setPage(pagination.pageIndex - 1)}
+                  >Previous</button>
+                  <button
+                    type="button"
+                    ?disabled=${pagination.pageCount === 0 || pagination.pageIndex >= pagination.pageCount - 1}
+                    @click=${() => this.setPage(pagination.pageIndex + 1)}
+                  >Next</button>
+                </div>
               </div>
             `
             : ''}