@coreui/data-grid 0.1.0-rc.0

package/src/data-grid.ts

@@ -0,0 +1,2208 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+import type { Table, TableState } from '@tanstack/table-core'
+import BaseComponent from './base-component.js'
+import EventHandler from './dom/event-handler.js'
+import {
+  createActiveCellManager, resolveNavigation, type ActiveCell, type ActiveCellContext, type ActiveCellManager
+} from './engine/active-cell'
+import { createDataSource, type GridDataSource } from './engine/data-source'
+import { createScheduler, type Scheduler } from './engine/scheduler'
+import { createGridTable } from './engine/table'
+import { createGridVirtualizer, type GridVirtualizer } from './engine/virtualizer'
+import {
+  DEFAULT_COLUMN_MENU_ICON, DEFAULT_FILTER_ICON, DEFAULT_HIDE_COLUMN_ICON, DEFAULT_MOVE_LEFT_ICON, DEFAULT_MOVE_RIGHT_ICON,
+  DEFAULT_PIN_LEFT_ICON, DEFAULT_PIN_RIGHT_ICON, DEFAULT_SORT_ASCENDING_ICON, DEFAULT_SORT_DESCENDING_ICON,
+  DEFAULT_SORT_NEUTRAL_ICON, DEFAULT_TOOLBAR_COLUMNS_ICON, DEFAULT_TOOLBAR_EXPORT_ICON,
+  DEFAULT_TOOLBAR_REDO_ICON, DEFAULT_TOOLBAR_UNDO_ICON, DEFAULT_UNPIN_ICON
+} from './icons'
+import { DEFAULT_LABELS, interpolate } from './labels'
+import type {
+ DataGridColumn, DataGridColumnFilterValue, DataGridEditableOptions, DataGridEditor, DataGridEditorContext,
+ DataGridItem, DataGridLabels, DataGridMenuAction, DataGridOptions, DataGridSlot, DataGridSlotContext, DataGridState
+} from './types'
+import { createBody, type GridBody } from './ui/body'
+import { createBuiltInEditor } from './ui/editor'
+import { createHeader, type GridHeader } from './ui/header'
+import { createLoading, type GridLoading } from './ui/loading'
+import { createFilterMenu, type GridFilterMenu } from './ui/filter-menu'
+import { createMenu, type GridMenu } from './ui/menu'
+import { createPagination } from './ui/pagination'
+import type { GridPinning, PinnedCellInfo } from './ui/pinning'
+import { createColumnChooser, type ColumnChooserColumn, type GridColumnChooser } from './ui/column-chooser'
+import { createToolbar, resolveToolbar, type ResolvedToolbar } from './ui/toolbar'
+import { createTooltip, type GridTooltip } from './ui/tooltip'
+import {
+ downloadCsv, exportCsv, type CsvDownloadOptions, type CsvOptions
+} from './util/csv'
+import { debounce } from './util/debounce'
+import { defineJQueryPlugin } from './util/index.js'
+import { DefaultAllowlist, sanitizeHtml, SVGAllowlist } from './util/sanitizer.js'
+
+/**
+ * Constants
+ */
+
+const NAME = 'data-grid'
+const DATA_KEY = 'coreui.data-grid'
+const EVENT_KEY = `.${DATA_KEY}`
+
+const EVENT_CHANGE = `change${EVENT_KEY}`
+const EVENT_CLICK = `click${EVENT_KEY}`
+const EVENT_DATA_ERROR = `dataError${EVENT_KEY}`
+const EVENT_DATA_LOAD = `dataLoad${EVENT_KEY}`
+const EVENT_DBLCLICK = `dblclick${EVENT_KEY}`
+const EVENT_EDIT_CANCEL = `editCancel${EVENT_KEY}`
+const EVENT_EDIT_COMMIT = `editCommit${EVENT_KEY}`
+const EVENT_EDIT_START = `editStart${EVENT_KEY}`
+const EVENT_FILTER_CHANGE = `filterChange${EVENT_KEY}`
+const EVENT_INPUT = `input${EVENT_KEY}`
+const EVENT_ORDER_CHANGE = `orderChange${EVENT_KEY}`
+const EVENT_PAGINATION_CHANGE = `paginationChange${EVENT_KEY}`
+const EVENT_PINNING_CHANGE = `pinningChange${EVENT_KEY}`
+const EVENT_SELECTION_CHANGE = `selectionChange${EVENT_KEY}`
+const EVENT_SIZING_CHANGE = `sizingChange${EVENT_KEY}`
+const EVENT_SORTING_CHANGE = `sortingChange${EVENT_KEY}`
+const EVENT_VISIBILITY_CHANGE = `visibilityChange${EVENT_KEY}`
+
+const EVENT_FOCUSIN = `focusin${EVENT_KEY}`
+const EVENT_FOCUSOUT = `focusout${EVENT_KEY}`
+const EVENT_KEYDOWN = `keydown${EVENT_KEY}`
+
+const EVENT_DRAGEND = `dragend${EVENT_KEY}`
+const EVENT_DRAGLEAVE = `dragleave${EVENT_KEY}`
+const EVENT_DRAGOVER = `dragover${EVENT_KEY}`
+const EVENT_DRAGSTART = `dragstart${EVENT_KEY}`
+const EVENT_DROP = `drop${EVENT_KEY}`
+const EVENT_MOUSEDOWN = `mousedown${EVENT_KEY}`
+const EVENT_POINTERDOWN = `pointerdown${EVENT_KEY}`
+const EVENT_TOUCHSTART = `touchstart${EVENT_KEY}`
+
+const CLASS_NAME_DATA_GRID = 'data-grid'
+const CLASS_NAME_DRAGGING = 'data-grid-dragging'
+const CLASS_NAME_EDITOR_POPUP = 'data-grid-editor-popup'
+const CLASS_NAME_DROP_TARGET = 'data-grid-drop-target'
+const CLASS_NAME_PAGINATION_TOP = 'data-grid-pagination-top'
+const CLASS_NAME_PINNED = 'data-grid-pinned'
+const CLASS_NAME_RESIZABLE = 'data-grid-resizable'
+const CLASS_NAME_TABLE = 'table'
+const CLASS_NAME_VIEWPORT = 'data-grid-viewport'
+
+const SELECTOR_COLUMN_FILTER = 'input[data-coreui-column-filter]'
+const SELECTOR_DRAGGABLE = 'th[data-coreui-draggable]'
+const SELECTOR_MENU_BUTTON = 'button[data-coreui-menu]'
+const SELECTOR_FILTER_BUTTON = 'button[data-coreui-filter]'
+const SELECTOR_GLOBAL_FILTER = 'input[data-coreui-global-filter]'
+const SELECTOR_PAGE = 'button[data-coreui-page]'
+const SELECTOR_PAGE_SIZE = 'select[data-coreui-page-size]'
+const SELECTOR_RESIZER = '[data-coreui-resizer]'
+const SELECTOR_ROW_SELECT = 'input[data-coreui-row-select]'
+const SELECTOR_SELECT_ALL = 'input[data-coreui-select-all]'
+const SELECTOR_SORT_BUTTON = '.data-grid-sort-button'
+const SELECTOR_TOOLBAR_COLUMNS = 'button[data-coreui-toolbar-columns]'
+const SELECTOR_TOOLBAR_EXPORT = 'button[data-coreui-toolbar-export]'
+const SELECTOR_TOOLBAR_REDO = 'button[data-coreui-toolbar-redo]'
+const SELECTOR_TOOLBAR_UNDO = 'button[data-coreui-toolbar-undo]'
+
+const FILTER_DEBOUNCE_MS = 250
+const DEFAULT_PAGE_SIZE_OPTIONS = [5, 10, 20, 50]
+
+let editorErrorCount = 0
+
+// History entries hold the ROW ID, not the item reference - an immutable
+// app replaces the object on every commit, so undo/redo resolve the current
+// item from the core row model at emit time.
+interface DataGridEditCommitEntry {
+  rowId: string
+  columnId: string
+  value: unknown
+  previousValue: unknown
+}
+
+const STATE_STORAGE_PREFIX = 'coreui-data-grid:'
+const STATE_AUTOSAVE_DEBOUNCE_MS = 250
+const HISTORY_LIMIT = 100
+
+const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]'
+
+const applyTabIndex = (cellElement: HTMLElement, isTabbable: boolean) => {
+  const value = isTabbable ? 0 : -1
+  if (cellElement.tabIndex !== value) {
+    cellElement.tabIndex = value
+  }
+}
+
+const Default: DataGridOptions = {
+  cellNavigation: false,
+  columnFilters: false,
+  columnMenu: false,
+  columnMenuIcon: DEFAULT_COLUMN_MENU_ICON,
+  columnOrder: false,
+  columnPinning: false,
+  columnSizing: false,
+  columnVisibility: false,
+  columns: [],
+  dataProvider: null,
+  editing: false,
+  empty: 'No items found',
+  filterIcon: DEFAULT_FILTER_ICON,
+  globalFilter: false,
+  hideColumnIcon: DEFAULT_HIDE_COLUMN_ICON,
+  history: false,
+  itemKey: null,
+  items: [],
+  labels: {},
+  moveLeftIcon: DEFAULT_MOVE_LEFT_ICON,
+  moveRightIcon: DEFAULT_MOVE_RIGHT_ICON,
+  overscan: 10,
+  pagination: false,
+  pinLeftIcon: DEFAULT_PIN_LEFT_ICON,
+  pinRightIcon: DEFAULT_PIN_RIGHT_ICON,
+  rowHeight: 44,
+  rowSelection: false,
+  sanitize: true,
+  sanitizeFn: null,
+  slots: {},
+  sortAscendingIcon: DEFAULT_SORT_ASCENDING_ICON,
+  sortDescendingIcon: DEFAULT_SORT_DESCENDING_ICON,
+  sortNeutralIcon: DEFAULT_SORT_NEUTRAL_ICON,
+  sorterVisibility: false,
+  sorting: true,
+  stateKey: null,
+  toolbar: false,
+  toolbarColumnsIcon: DEFAULT_TOOLBAR_COLUMNS_ICON,
+  toolbarExportIcon: DEFAULT_TOOLBAR_EXPORT_ICON,
+  toolbarRedoIcon: DEFAULT_TOOLBAR_REDO_ICON,
+  toolbarUndoIcon: DEFAULT_TOOLBAR_UNDO_ICON,
+  unpinIcon: DEFAULT_UNPIN_ICON,
+  virtualization: true
+}
+
+const DefaultType = {
+  cellNavigation: 'boolean',
+  columnFilters: 'boolean',
+  columnMenu: '(boolean|function)',
+  columnMenuIcon: 'string',
+  columnOrder: '(boolean|array)',
+  columnPinning: '(boolean|object)',
+  columnSizing: '(boolean|object)',
+  columnVisibility: '(boolean|object)',
+  columns: 'array',
+  dataProvider: '(function|null)',
+  editing: 'boolean',
+  empty: '(string|function)',
+  filterIcon: 'string',
+  globalFilter: 'boolean',
+  hideColumnIcon: 'string',
+  history: 'boolean',
+  itemKey: '(function|null)',
+  items: 'array',
+  labels: 'object',
+  moveLeftIcon: 'string',
+  moveRightIcon: 'string',
+  overscan: 'number',
+  pagination: '(boolean|object)',
+  pinLeftIcon: 'string',
+  pinRightIcon: 'string',
+  rowHeight: 'number',
+  rowSelection: '(boolean|object)',
+  sanitize: 'boolean',
+  sanitizeFn: '(function|null)',
+  slots: 'object',
+  sortAscendingIcon: 'string',
+  sortDescendingIcon: 'string',
+  sortNeutralIcon: 'string',
+  sorterVisibility: '(string|boolean)',
+  sorting: '(boolean|object)',
+  stateKey: '(string|null)',
+  toolbar: '(boolean|object)',
+  toolbarColumnsIcon: 'string',
+  toolbarExportIcon: 'string',
+  toolbarRedoIcon: 'string',
+  toolbarUndoIcon: 'string',
+  unpinIcon: 'string',
+  virtualization: 'boolean'
+}
+
+/**
+ * Class definition
+ */
+
+class DataGrid extends BaseComponent {
+  declare _config: DataGridOptions
+  private _table!: Table<DataGridItem>
+  private _scheduler!: Scheduler
+  private _virtualizer: GridVirtualizer | null = null
+  private _header!: GridHeader
+  private _body!: GridBody
+  private _toolbar: DataGridSlot | null = null
+  private _paginations: Array<{ element: HTMLElement; refresh: () => void; dispose?: () => void }> = []
+  private _emptySlot: DataGridSlot | null = null
+  private _dataSource: GridDataSource | null = null
+  private _loading: GridLoading | null = null
+  private _loadFailed = false
+  private _dataVersion = 0
+  private _viewportElement!: HTMLDivElement
+  private _tableElement!: HTMLTableElement
+  private _liveRegion: HTMLElement | null = null
+  private _labels!: DataGridLabels
+  private _selectionAnchorIndex: number | null = null
+  private _activeCell: ActiveCellManager | null = null
+  private _containsFocus = false
+  private _editingCell: {
+    rowId: string
+    columnId: string
+    rowIndex: number
+    item: DataGridItem
+    previousValue: unknown
+  } | null = null
+private _undoStack: DataGridEditCommitEntry[] = []
+  private _redoStack: DataGridEditCommitEntry[] = []
+  private _persistState: (() => void) | null = null
+  private _editor: DataGridEditor | null = null
+  // Removed by reference - a namespace-wide off(document, ...) would tear
+  // down every other grid instance's outside-commit handler with it.
+  private _editorPointerdownHandler: ((event: Event) => void) | null = null
+  private _editorPopup: HTMLElement | null = null
+  private _editorErrorElement: HTMLElement | null = null
+  private _editorFocusPending = false
+  private _columnsByKey = new Map<string, DataGridColumn>()
+  private _dragColumn: string | null = null
+  private _menu: GridMenu | null = null
+  private _tooltip: GridTooltip | null = null
+  private _filterMenu: GridFilterMenu | null = null
+  private _columnChooser: GridColumnChooser | null = null
+  private _toolbarConfig: ResolvedToolbar | null = null
+
+  constructor(element: Element | string, config?: Partial<DataGridOptions>) {
+    super(element, config)
+
+    if (!this._element) {
+      return
+    }
+
+    this._labels = { ...DEFAULT_LABELS, ...this._config.labels }
+    this._scheduler = createScheduler(() => this._update())
+    this._table = this._createTable()
+
+    this._liveRegion = document.createElement('div')
+    this._liveRegion.classList.add('visually-hidden')
+    this._liveRegion.setAttribute('aria-live', 'polite')
+    this._element.append(this._liveRegion)
+
+    this._render()
+    this._addEventListeners()
+    this._tooltip = createTooltip(this._element)
+    // A persisted view restores before the first server fetch, so the initial
+    // request already carries the user's sorting/filters/page.
+    this._restorePersistedState()
+    this._initDataSource()
+  }
+
+  // Getters
+  get table(): Table<DataGridItem> {
+    return this._table
+  }
+
+  static get Default(): DataGridOptions {
+    return Default
+  }
+
+  static get DefaultType(): Record<string, string> {
+    return DefaultType
+  }
+
+  static get NAME(): string {
+    return NAME
+  }
+
+  static getInstance(element: Element | string | null): DataGrid | null {
+    return super.getInstance(element) as DataGrid | null
+  }
+
+  static getOrCreateInstance(element: Element | string, config?: Partial<DataGridOptions>): DataGrid {
+    return super.getOrCreateInstance(element, config) as DataGrid
+  }
+
+  // Public
+  getSelectedItems(): DataGridItem[] {
+    return this._table.getSelectedRowModel().rows.map(row => row.original)
+  }
+
+  getCsv(options?: CsvOptions): string {
+    return exportCsv(this._table, options)
+  }
+
+  downloadCsv(options?: CsvDownloadOptions): void {
+    downloadCsv(this._table, options)
+  }
+
+  // A serializable snapshot of every user-adjustable state slice. Feed it
+  // back through restoreState() - scroll position and edit drafts excluded.
+  getState(): DataGridState {
+    const state = this._table.getState()
+    return {
+      columnFilters: state.columnFilters,
+      columnOrder: state.columnOrder,
+      columnPinning: state.columnPinning,
+      columnSizing: state.columnSizing,
+      columnVisibility: state.columnVisibility,
+      globalFilter: (state.globalFilter as string | undefined) ?? '',
+      pagination: state.pagination,
+      rowSelection: state.rowSelection,
+      sorting: state.sorting
+    }
+  }
+
+  restoreState(state: Partial<DataGridState>): void {
+    this._table.setState(previous => ({ ...previous, ...state }))
+
+    // The built-in search input is uncontrolled - sync it to the restored
+    // filter so the UI matches the state.
+    if (state.globalFilter !== undefined) {
+      const input = this._element.querySelector<HTMLInputElement>(SELECTOR_GLOBAL_FILTER)
+      if (input) {
+        input.value = state.globalFilter
+      }
+    }
+
+    this._scheduler.schedule()
+  }
+
+  // Re-emits the last edit commit inverted (value and previousValue swap) -
+  // the app reverts the data through the same editCommit channel it already
+  // handles. New commits clear the redo stack.
+  undo(): void {
+    this._applyHistoryEntry(this._undoStack, this._redoStack, true)
+  }
+
+  redo(): void {
+    this._applyHistoryEntry(this._redoStack, this._undoStack, false)
+  }
+
+  private _applyHistoryEntry(
+    from: DataGridEditCommitEntry[],
+    to: DataGridEditCommitEntry[],
+    inverted: boolean
+  ): void {
+    const entry = from.pop()
+    if (!entry) {
+      return
+    }
+
+    // The row may be gone (data replaced without it) - drop the entry.
+    const row = this._table.getCoreRowModel().rowsById[entry.rowId]
+    if (!row) {
+      this._updateHistoryButtons()
+      return
+    }
+
+    to.push(entry)
+    EventHandler.trigger(this._element, EVENT_EDIT_COMMIT, {
+      item: row.original,
+      columnId: entry.columnId,
+      value: inverted ? entry.previousValue : entry.value,
+      previousValue: inverted ? entry.value : entry.previousValue
+    })
+    this._announce(inverted ? this._labels.undoneAnnouncement : this._labels.redoneAnnouncement)
+    this._updateHistoryButtons()
+  }
+
+  // Replaces the data in place, preserving sorting/filters/selection/scroll.
+  // No-op in server-side mode - the dataProvider owns the data there.
+  setItems(items: DataGridItem[]): void {
+    if (this._config.dataProvider) {
+      return
+    }
+
+    // External data replacement invalidates the draft - the app owns the data.
+    this._stopEditing({ commit: false })
+    this._config.items = items
+    this._dataVersion++
+    this._table.setOptions(previous => ({ ...previous, data: items }))
+    this._scheduler.schedule()
+  }
+
+  // Full rebuild: recreates the table, wiping sorting/filters/selection/scroll.
+  // Use setItems() to swap data while keeping user state.
+  update(config: Partial<DataGridOptions>): void {
+    this._config = this._getConfig({ ...this._config, ...config })
+    this._labels = { ...DEFAULT_LABELS, ...this._config.labels }
+
+    this._teardownUi()
+    this._selectionAnchorIndex = null
+    this._loadFailed = false
+    this._dataVersion++
+    this._table = this._createTable()
+    this._render()
+    this._initDataSource()
+  }
+
+  dispose(): void {
+    this._teardownUi()
+    this._scheduler.dispose()
+    this._tooltip?.dispose()
+    this._tooltip = null
+    if (this._liveRegion) {
+      this._liveRegion.remove()
+    }
+
+    this._element.classList.remove(CLASS_NAME_DATA_GRID)
+    this._element.removeAttribute('data-coreui-sorter-visibility')
+
+    super.dispose()
+  }
+
+  // Private
+  // Editing needs the active-cell substrate (Enter/F2 target the active cell).
+  _configAfterMerge(config: DataGridOptions): DataGridOptions {
+    if (config.editing) {
+      config.cellNavigation = true
+    }
+
+    return config
+  }
+
+  private _createTable(): Table<DataGridItem> {
+    return createGridTable(this._config, (previous, next) => {
+      this._notifyStateChange(previous, next)
+      this._scheduler.schedule()
+    })
+  }
+
+  private _teardownUi(): void {
+    this._stopEditing({ commit: false })
+
+    if (this._dataSource) {
+      this._dataSource.dispose()
+      this._dataSource = null
+    }
+
+    this._header?.dispose()
+
+    if (this._menu) {
+      this._menu.dispose()
+      this._menu = null
+    }
+
+    if (this._filterMenu) {
+      this._filterMenu.dispose()
+      this._filterMenu = null
+    }
+
+    if (this._columnChooser) {
+      this._columnChooser.dispose()
+      this._columnChooser = null
+    }
+
+    if (this._loading) {
+      this._loading.element.remove()
+      this._loading = null
+    }
+
+    if (this._virtualizer) {
+      this._virtualizer.destroy()
+      this._virtualizer = null
+    }
+
+    if (this._toolbar) {
+      this._toolbar.dispose?.()
+      this._toolbar.element.remove()
+      this._toolbar = null
+    }
+
+    for (const pagination of this._paginations) {
+      pagination.dispose?.()
+      pagination.element.remove()
+    }
+
+    this._paginations = []
+
+    if (this._emptySlot) {
+      this._emptySlot.dispose?.()
+      this._emptySlot = null
+    }
+
+    if (this._viewportElement) {
+      this._viewportElement.remove()
+    }
+  }
+
+  private _slotContext(): DataGridSlotContext {
+    return { table: this._table, labels: this._labels }
+  }
+
+  private _isColumnSortable(column: DataGridColumn): boolean {
+    return Boolean(this._config.sorting) && column.sortable !== false
+  }
+
+  private _isColumnFilterable(column: DataGridColumn): boolean {
+    return this._config.columnFilters && column.filterable !== false
+  }
+
+  private _isColumnResizable(column: DataGridColumn): boolean {
+    return Boolean(this._config.columnSizing) && column.resizable !== false
+  }
+
+  private _sanitizeIcon(icon: string): string {
+    return this._config.sanitize ? sanitizeHtml(icon, SVGAllowlist, this._config.sanitizeFn) : icon
+  }
+
+  private _hasColumnMenu(column: DataGridColumn): boolean {
+    if (!this._config.columnMenu) {
+      return false
+    }
+
+    // A builder can add items regardless of enabled features, so ask it directly.
+    if (typeof this._config.columnMenu === 'function') {
+      return this._getMenuActions(column.key).length > 0
+    }
+
+    return (
+      this._isColumnSortable(column) ||
+      Boolean(this._config.columnPinning) ||
+      (Boolean(this._config.columnVisibility) && column.hideable !== false) ||
+      (Boolean(this._config.columnOrder) && column.movable !== false)
+    )
+  }
+
+  private _renderToolbar(): void {
+    const toolbarConfig = resolveToolbar(this._config)
+    this._toolbarConfig = toolbarConfig
+
+    if (this._config.slots.toolbar) {
+      this._toolbar = this._config.slots.toolbar(this._slotContext())
+      this._element.append(this._toolbar.element)
+      return
+    }
+
+    if (!toolbarConfig.columns && !toolbarConfig.export && !toolbarConfig.search && !toolbarConfig.history) {
+      return
+    }
+
+    this._toolbar = createToolbar({
+      columns: toolbarConfig.columns,
+      export: toolbarConfig.export,
+      icons: {
+        columns: this._sanitizeIcon(this._config.toolbarColumnsIcon),
+        export: this._sanitizeIcon(this._config.toolbarExportIcon),
+        redo: this._sanitizeIcon(this._config.toolbarRedoIcon),
+        undo: this._sanitizeIcon(this._config.toolbarUndoIcon)
+      },
+      history: toolbarConfig.history,
+      labels: this._labels,
+      search: toolbarConfig.search
+    })
+    this._element.append(this._toolbar.element)
+
+    if (toolbarConfig.columns) {
+      this._columnChooser = createColumnChooser({
+        root: this._element as HTMLElement,
+        labels: this._labels,
+        getColumns: () => this._chooserColumns(),
+        toggleVisibility: (columnId, visible) => {
+          this._table.getColumn(columnId)?.toggleVisibility(visible)
+        },
+        showAll: () => this._table.toggleAllColumnsVisible(true),
+        reset: () => this._table.setColumnVisibility(this._table.initialState.columnVisibility ?? {})
+      })
+    }
+  }
+
+  private _render(): void {
+    this._columnsByKey = new Map(this._config.columns.map(column => [column.key, column]))
+    this._activeCell = this._config.cellNavigation ?
+      createActiveCellManager(() => this._scheduler.schedule()) :
+      null
+    this._element.classList.add(CLASS_NAME_DATA_GRID)
+    this._element.classList.toggle(CLASS_NAME_RESIZABLE, Boolean(this._config.columnSizing))
+    this._element.classList.toggle(CLASS_NAME_PINNED, Boolean(this._config.columnPinning))
+    if (this._config.sorterVisibility) {
+      this._element.setAttribute('data-coreui-sorter-visibility', this._config.sorterVisibility)
+    } else {
+      this._element.removeAttribute('data-coreui-sorter-visibility')
+    }
+
+    const { slots } = this._config
+    this._renderToolbar()
+
+    if (slots.empty) {
+      this._emptySlot = slots.empty(this._slotContext())
+    }
+
+    const selectionEnabled = Boolean(this._config.rowSelection)
+    const selectionOptions = typeof this._config.rowSelection === 'object' ? this._config.rowSelection : {}
+    // Server-side mode implies pagination — virtualized infinite scroll over a
+    // dataProvider is out of scope until 0.3.0.
+    const paginationEnabled = Boolean(this._config.pagination) || Boolean(this._config.dataProvider)
+    const paginationOptions = typeof this._config.pagination === 'object' ? this._config.pagination : {}
+
+    if (this._config.columnMenu) {
+      this._menu = createMenu({
+        root: this._element as HTMLElement,
+        getActions: columnKey => this._getMenuActions(columnKey)
+      })
+    }
+
+    if (this._config.columnFilters) {
+      this._filterMenu = createFilterMenu({
+        root: this._element as HTMLElement,
+        labels: this._labels,
+        getColumn: columnKey => this._columnsByKey.get(columnKey) ?? null,
+        getFacetedValues: columnKey =>
+          [...(this._table.getColumn(columnKey)?.getFacetedUniqueValues().keys() ?? [])],
+        getFilterValue: columnKey =>
+          this._table.getColumn(columnKey)?.getFilterValue() as DataGridColumnFilterValue | undefined,
+        applyFilter: (columnKey, value) => {
+          this._table.getColumn(columnKey)?.setFilterValue(value)
+        }
+      })
+    }
+
+    this._header = createHeader({
+      cellNavigation: this._config.cellNavigation,
+      columns: this._config.columns,
+      draggable: Boolean(this._config.columnOrder),
+      filterRow:
+        this._config.columnFilters &&
+        this._config.columns.some(column => column.filter && this._isColumnFilterable(column)),
+      hasMenu: column => this._hasColumnMenu(column),
+      hasFilterMenu: column =>
+        Boolean(this._filterMenu) && this._isColumnFilterable(column) && !column.filter,
+      icons: {
+        columnMenu: this._sanitizeIcon(this._config.columnMenuIcon),
+        filter: this._sanitizeIcon(this._config.filterIcon),
+        sortAscending: this._sanitizeIcon(this._config.sortAscendingIcon),
+        sortDescending: this._sanitizeIcon(this._config.sortDescendingIcon),
+        sortNeutral: this._sanitizeIcon(this._config.sortNeutralIcon)
+      },
+      isFilterable: column => this._isColumnFilterable(column),
+      isResizable: column => this._isColumnResizable(column),
+      isSortable: column => this._isColumnSortable(column),
+      labels: this._labels,
+      resizable: Boolean(this._config.columnSizing),
+      selection: selectionEnabled,
+      selectAll: selectionEnabled && selectionOptions.selectAll !== false,
+      table: this._table
+    })
+    this._body = createBody({
+      cellNavigation: this._config.cellNavigation,
+      getDataVersion: () => this._dataVersion,
+      getEditingCell: () =>
+        (this._editingCell ? { rowId: this._editingCell.rowId, columnId: this._editingCell.columnId } : null),
+      // Popup editors overlay the cell; its content stays in place.
+      getEditorElement: () => (this._editor && !this._editor.popup ? this._editor.element : null),
+      getPinning: () => (this._config.columnPinning ? this._getPinning() : null),
+      getRowIndexOffset: () => {
+        if (!this._config.pagination && !this._config.dataProvider) {
+          return 0
+        }
+
+        const { pageIndex, pageSize } = this._table.getState().pagination
+        return pageIndex * pageSize
+      },
+      getRows: () => this._table.getRowModel().rows,
+      getVisibleColumns: () => this._visibleColumns(),
+      getVirtualizer: () => this._virtualizer?.instance ?? null,
+      headerRowCount: this._header.rowCount,
+      labels: this._labels,
+      renderEmpty: () => {
+        if (this._emptySlot) {
+          return this._emptySlot.element
+        }
+
+        if (this._loadFailed) {
+          return this._labels.loadError
+        }
+
+        return typeof this._config.empty === 'function' ? this._config.empty() : this._config.empty
+      },
+      sanitizeContent: html =>
+        (this._config.sanitize ? sanitizeHtml(html, DefaultAllowlist, this._config.sanitizeFn) : html),
+      selection: selectionEnabled
+    })
+
+    this._tableElement = document.createElement('table')
+    this._tableElement.classList.add(CLASS_NAME_TABLE)
+    if (this._config.cellNavigation) {
+      this._tableElement.setAttribute('role', 'grid')
+    }
+
+    this._tableElement.append(this._header.element, this._body.element)
+
+    this._viewportElement = document.createElement('div')
+    this._viewportElement.classList.add(CLASS_NAME_VIEWPORT)
+    if (this._config.cellNavigation) {
+      // Focus parks here when the focused row is recycled out of the window;
+      // the keydown fallback then scrolls the active cell back and refocuses.
+      this._viewportElement.tabIndex = -1
+    }
+
+    this._viewportElement.append(this._tableElement)
+
+    if (this._config.dataProvider) {
+      this._loading = createLoading(this._labels)
+      this._viewportElement.append(this._loading.element)
+    }
+
+    this._element.append(this._viewportElement)
+
+    if (paginationEnabled) {
+      const position = paginationOptions.position ?? 'bottom'
+      const paginationSlot = slots.pagination
+      const createInstance = () => {
+        if (paginationSlot) {
+          const slot = paginationSlot(this._slotContext())
+          return { element: slot.element, refresh: () => slot.update?.(), dispose: () => slot.dispose?.() }
+        }
+
+        const instance = createPagination({
+          info: paginationOptions.info ?? true,
+          labels: this._labels,
+          pageSizeOptions: paginationOptions.pageSizeOptions ?? DEFAULT_PAGE_SIZE_OPTIONS
+        })
+        return { element: instance.element, refresh: () => instance.update(this._paginationState()), dispose: undefined }
+      }
+
+      if (position === 'top' || position === 'both') {
+        const pagination = createInstance()
+        // The top-margin class styles the built-in module; a custom slot owns
+        // its own markup, so don't impose it (keeps vanilla/React in parity).
+        if (!paginationSlot) {
+          pagination.element.classList.add(CLASS_NAME_PAGINATION_TOP)
+        }
+
+        this._viewportElement.before(pagination.element)
+        this._paginations.push(pagination)
+      }
+
+      if (position === 'bottom' || position === 'both') {
+        const pagination = createInstance()
+        this._element.append(pagination.element)
+        this._paginations.push(pagination)
+      }
+    } else if (this._config.virtualization) {
+      this._virtualizer = createGridVirtualizer({
+        count: this._table.getRowModel().rows.length,
+        getScrollElement: () => this._viewportElement,
+        onChange: () => this._scheduler.schedule(),
+        overscan: this._config.overscan,
+        rowHeight: this._config.rowHeight
+      })
+    }
+
+    this._update()
+  }
+
+  private _addEventListeners(): void {
+    // Registered unconditionally (update() can flip cellNavigation on later);
+    // the handlers bail out when the feature is off.
+    EventHandler.on(this._element, EVENT_KEYDOWN, event => {
+      this._onCellNavigationKeydown(event as unknown as KeyboardEvent)
+    })
+
+    EventHandler.on(this._element, EVENT_FOCUSIN, event => {
+      this._containsFocus = true
+      this._onCellFocusIn(event as unknown as FocusEvent)
+    })
+
+    EventHandler.on(this._element, EVENT_FOCUSOUT, event => {
+      const related = (event as unknown as FocusEvent).relatedTarget as Node | null
+      if (!related || !this._element.contains(related)) {
+        this._containsFocus = false
+      }
+    })
+
+    EventHandler.on(this._element, EVENT_DBLCLICK, event => {
+      if (!this._config.editing) {
+        return
+      }
+
+      const found = this._navigableCellFromTarget(event.target as HTMLElement)
+      if (found && found.cell.rowIndex >= 0) {
+        this._activeCell?.set(found.cell)
+        this._startEditing(found.cell)
+      }
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_SORT_BUTTON, event => {
+      this._toggleColumnSorting(event)
+    })
+
+    const applyColumnFilter = debounce((key: string, value: string) => {
+      if (this._table) {
+        this._table.getColumn(key)?.setFilterValue(value === '' ? undefined : value)
+      }
+    }, FILTER_DEBOUNCE_MS)
+
+    EventHandler.on(this._element, EVENT_INPUT, SELECTOR_COLUMN_FILTER, event => {
+      const input = (event.delegateTarget ?? event.target) as HTMLInputElement
+      applyColumnFilter(input.dataset.coreuiColumnFilter!, input.value)
+    })
+
+    const applyGlobalFilter = debounce((value: string) => {
+      if (this._table) {
+        this._table.setGlobalFilter(value === '' ? undefined : value)
+      }
+    }, FILTER_DEBOUNCE_MS)
+
+    EventHandler.on(this._element, EVENT_INPUT, SELECTOR_GLOBAL_FILTER, event => {
+      const input = (event.delegateTarget ?? event.target) as HTMLInputElement
+      applyGlobalFilter(input.value)
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_MENU_BUTTON, event => {
+      const button = (event.delegateTarget ?? event.target) as HTMLElement
+      this._menu?.toggle(button, button.dataset.coreuiMenu!)
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_FILTER_BUTTON, event => {
+      const button = (event.delegateTarget ?? event.target) as HTMLElement
+      this._filterMenu?.toggle(button, button.dataset.coreuiFilter!)
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_TOOLBAR_COLUMNS, event => {
+      const button = (event.delegateTarget ?? event.target) as HTMLElement
+      this._columnChooser?.toggle(button)
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_TOOLBAR_EXPORT, () => {
+      this.downloadCsv({ scope: 'filtered', ...this._toolbarConfig?.exportOptions })
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_TOOLBAR_UNDO, () => {
+      this.undo()
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_TOOLBAR_REDO, () => {
+      this.redo()
+    })
+
+    EventHandler.on(this._element, EVENT_DRAGSTART, SELECTOR_DRAGGABLE, event => {
+      this._onColumnDragStart(event)
+    })
+
+    EventHandler.on(this._element, EVENT_DRAGOVER, SELECTOR_DRAGGABLE, event => {
+      if (!this._dragColumn) {
+        return
+      }
+
+      const target = (event.delegateTarget ?? event.target) as HTMLElement
+      const targetKey = target.dataset.coreuiColumn
+      // A drop is only valid within the drag source's pinned region; leaving
+      // other targets un-prevented shows the browser's no-drop cursor there.
+      const source = this._table.getColumn(this._dragColumn)
+      const targetColumn = targetKey ? this._table.getColumn(targetKey) : undefined
+      if (!source || !targetColumn || targetKey === this._dragColumn || source.getIsPinned() !== targetColumn.getIsPinned()) {
+        return
+      }
+
+      event.preventDefault()
+      target.classList.add(CLASS_NAME_DROP_TARGET)
+    })
+
+    EventHandler.on(this._element, EVENT_DRAGLEAVE, SELECTOR_DRAGGABLE, event => {
+      const target = (event.delegateTarget ?? event.target) as HTMLElement
+      target.classList.remove(CLASS_NAME_DROP_TARGET)
+    })
+
+    EventHandler.on(this._element, EVENT_DROP, SELECTOR_DRAGGABLE, event => {
+      this._onColumnDrop(event)
+    })
+
+    EventHandler.on(this._element, EVENT_DRAGEND, SELECTOR_DRAGGABLE, () => {
+      this._endColumnDrag()
+    })
+
+    EventHandler.on(this._element, EVENT_MOUSEDOWN, SELECTOR_RESIZER, event => {
+      this._startColumnResize(event)
+    })
+
+    EventHandler.on(this._element, EVENT_TOUCHSTART, SELECTOR_RESIZER, event => {
+      this._startColumnResize(event)
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_ROW_SELECT, event => {
+      this._toggleRowSelection(event)
+    })
+
+    EventHandler.on(this._element, EVENT_CHANGE, SELECTOR_SELECT_ALL, event => {
+      const input = (event.delegateTarget ?? event.target) as HTMLInputElement
+      this._table.toggleAllRowsSelected(input.checked)
+    })
+
+    EventHandler.on(this._element, EVENT_CLICK, SELECTOR_PAGE, event => {
+      const button = (event.delegateTarget ?? event.target) as HTMLButtonElement
+      const page = button.dataset.coreuiPage!
+
+      if (page === 'first') {
+        this._table.firstPage()
+        return
+      }
+
+      if (page === 'prev') {
+        this._table.previousPage()
+        return
+      }
+
+      if (page === 'next') {
+        this._table.nextPage()
+        return
+      }
+
+      if (page === 'last') {
+        this._table.lastPage()
+        return
+      }
+
+      this._table.setPageIndex(Number(page))
+    })
+
+    EventHandler.on(this._element, EVENT_CHANGE, SELECTOR_PAGE_SIZE, event => {
+      const select = (event.delegateTarget ?? event.target) as HTMLSelectElement
+      this._table.setPageSize(Number(select.value))
+    })
+  }
+
+  private _toggleColumnSorting(event: Event & Record<string, unknown>): void {
+    const button = (event.delegateTarget ?? event.target) as HTMLElement
+    const key = button.closest('th')?.dataset.coreuiColumn
+    if (!key) {
+      return
+    }
+
+    const column = this._table.getColumn(key)
+    column?.getToggleSortingHandler()?.(event)
+  }
+
+  // Maps an event target to the navigable cell that holds it: a data cell
+  // (rowIndex from the row model) or a header label-row cell (rowIndex -1).
+  // Selection cells, the filter row, and grid chrome outside the table map to
+  // null.
+  private _navigableCellFromTarget(target: HTMLElement): { cellElement: HTMLElement; cell: ActiveCell } | null {
+    const cellElement = target.closest<HTMLElement>('td, th')
+    if (!cellElement || !this._tableElement.contains(cellElement)) {
+      return null
+    }
+
+    const columnId = cellElement.dataset.coreuiColumn
+    if (!columnId) {
+      return null
+    }
+
+    const rowElement = cellElement.closest('tr')!
+
+    if (rowElement.parentElement === this._body.element) {
+      const index = rowElement.dataset.coreuiIndex
+      if (index === undefined) {
+        return null
+      }
+
+      return { cellElement, cell: { rowIndex: Number(index), columnId } }
+    }
+
+    if (rowElement === this._header.element.firstElementChild) {
+      return { cellElement, cell: { rowIndex: -1, columnId } }
+    }
+
+    return null
+  }
+
+  private _onCellFocusIn(event: FocusEvent): void {
+    if (!this._activeCell) {
+      return
+    }
+
+    const found = this._navigableCellFromTarget(event.target as HTMLElement)
+    if (found) {
+      // The browser already moved focus (click, descend) - only sync state.
+      this._activeCell.set(found.cell)
+    }
+  }
+
+  private _onCellNavigationKeydown(event: KeyboardEvent): void {
+    if (!this._activeCell) {
+      return
+    }
+
+    const target = event.target as HTMLElement
+
+    // Ctrl/Cmd+Z / Ctrl+Shift+Z / Ctrl+Y - edit history (MUI/AG parity).
+    // Not while an editor is open (the input's native undo wins) and not
+    // from form controls (filter/search inputs own their undo).
+    if (
+      this._config.history &&
+      (event.ctrlKey || event.metaKey) &&
+      !this._editingCell &&
+      !target.matches('input, textarea, select')
+    ) {
+      const key = event.key.toLowerCase()
+      if (key === 'z' && !event.shiftKey) {
+        event.preventDefault()
+        this.undo()
+        return
+      }
+
+      if ((key === 'z' && event.shiftKey) || key === 'y') {
+        event.preventDefault()
+        this.redo()
+        return
+      }
+    }
+
+    if (this._editingCell && this._editScopeContains(target)) {
+      // A defaultPrevented key was consumed by the editor (a rich editor
+      // closing its own overlay on Escape, an autocomplete accepting on
+      // Enter) - one key, one layer.
+      if (event.key === 'Enter') {
+        if (!event.defaultPrevented) {
+          event.preventDefault()
+          this._stopEditing({ commit: true })
+        }
+
+        return
+      }
+
+      if (event.key === 'Escape') {
+        if (!event.defaultPrevented) {
+          this._cancelEdit()
+        }
+
+        return
+      }
+
+      if (event.key === 'Tab') {
+        event.preventDefault()
+        this._moveEditing(event.shiftKey ? -1 : 1)
+        return
+      }
+
+      // Everything else (arrows, typing) stays native inside the editor.
+      return
+    }
+
+    // Focus fell back to the viewport after the active row was recycled out
+    // of the window: any navigation key scrolls the active cell back in view
+    // and refocuses it.
+    if (target === this._viewportElement) {
+      const active = this._activeCell.get()
+      if (active && event.key !== 'Tab') {
+        event.preventDefault()
+        this._setActiveCell(active)
+      }
+
+      return
+    }
+
+    const found = this._navigableCellFromTarget(target)
+    if (!found) {
+      return
+    }
+
+    if (target !== found.cellElement) {
+      // Focus is descended into the cell's content; Escape ascends back.
+      if (event.key === 'Escape') {
+        found.cellElement.focus({ preventScroll: true })
+      }
+
+      return
+    }
+
+    if (event.key === 'Enter' || event.key === 'F2') {
+      event.preventDefault()
+      const config = this._columnsByKey.get(found.cell.columnId)
+      if (found.cell.rowIndex === -1) {
+        if (event.key === 'Enter' && config && this._isColumnSortable(config)) {
+          this._table.getColumn(found.cell.columnId)?.getToggleSortingHandler()?.(event)
+        }
+
+        return
+      }
+
+      if (config && this._isColumnEditable(config)) {
+        this._startEditing(found.cell)
+        return
+      }
+
+      if (event.key === 'Enter') {
+        this._descendIntoCell(found.cellElement)
+      }
+
+      return
+    }
+
+    if (event.key === ' ') {
+      if (this._config.rowSelection && found.cell.rowIndex >= 0) {
+        event.preventDefault()
+        const row = this._table.getRowModel().rows[found.cell.rowIndex]
+        row?.toggleSelected()
+        this._selectionAnchorIndex = found.cell.rowIndex
+      }
+
+      return
+    }
+
+    const result = resolveNavigation(event.key, event.ctrlKey || event.metaKey, found.cell, this._activeCellContext())
+    if (!result) {
+      return
+    }
+
+    event.preventDefault()
+
+    if (result.pageDelta === 1 && this._table.getCanNextPage()) {
+      this._table.nextPage()
+    } else if (result.pageDelta === -1 && this._table.getCanPreviousPage()) {
+      this._table.previousPage()
+    }
+
+    this._setActiveCell(result.cell)
+  }
+
+  private _descendIntoCell(cellElement: HTMLElement): void {
+    cellElement.querySelector<HTMLElement>(FOCUSABLE_SELECTOR)?.focus({ preventScroll: true })
+  }
+
+  private _isColumnEditable(column: DataGridColumn): boolean {
+    if (!this._config.editing) {
+      return false
+    }
+
+    // Opt-IN, unlike the opt-out feature booleans - editing is invasive. A
+    // custom editor is itself the opt-in.
+    return Boolean(column.editor) || column.editable === true || typeof column.editable === 'object'
+  }
+
+  private _startEditing(cell: ActiveCell): void {
+    const config = this._columnsByKey.get(cell.columnId)
+    if (!config || !this._isColumnEditable(config)) {
+      return
+    }
+
+    this._stopEditing({ commit: true, force: true })
+
+    const row = this._table.getRowModel().rows[cell.rowIndex]
+    if (!row) {
+      return
+    }
+
+    const value = row.getValue(cell.columnId)
+    const context: DataGridEditorContext = {
+      item: row.original,
+      column: config,
+      value,
+      commit: committed => this._commitEdit(committed),
+      cancel: () => this._cancelEdit(),
+      labels: this._labels
+    }
+    const editable: DataGridEditableOptions = typeof config.editable === 'object' ? config.editable : {}
+    const editor = config.editor ? config.editor(context) : createBuiltInEditor(editable, context)
+
+    this._editingCell = {
+      rowId: row.id,
+      columnId: cell.columnId,
+      rowIndex: cell.rowIndex,
+      item: row.original,
+      previousValue: value
+    }
+    this._editor = editor
+    this._editorFocusPending = true
+
+    EventHandler.trigger(this._element, EVENT_EDIT_START, { item: row.original, columnId: cell.columnId })
+
+    if (editor.popup) {
+      this._mountEditorPopup(cell)
+    }
+
+    // Commit on blur (inline editors) and on pointerdown outside the edit
+    // scope (popup editors, portaled overlays) - blur alone cannot commit,
+    // picking a date in a calendar blurs the input mid-edit.
+    this._editorPointerdownHandler = (domEvent: Event) => {
+      if (!this._editScopeContains(domEvent.target as Node)) {
+        this._stopEditing({ commit: true })
+      }
+    }
+
+    EventHandler.on(document, EVENT_POINTERDOWN, this._editorPointerdownHandler)
+    EventHandler.on(editor.element, EVENT_FOCUSOUT, (domEvent: Event) => {
+      const related = (domEvent as FocusEvent).relatedTarget as Node | null
+      if (related && !this._editScopeContains(related)) {
+        this._stopEditing({ commit: true })
+      }
+    })
+
+    this._scheduler.schedule()
+  }
+
+  // The edit scope: the editing cell, the editor element, its popup layer,
+  // and anything the editor claims via contains() (portaled overlays).
+  private _editScopeContains(target: Node | null): boolean {
+    if (!target || !this._editingCell || !this._editor) {
+      return false
+    }
+
+    if (this._editor.contains?.(target) || this._editor.element.contains(target) || this._editorPopup?.contains(target)) {
+      return true
+    }
+
+    const cellElement = this._cellElementFor({
+      rowIndex: this._editingCell.rowIndex,
+      columnId: this._editingCell.columnId
+    })
+    return Boolean(cellElement?.contains(target))
+  }
+
+  private _mountEditorPopup(cell: ActiveCell): void {
+    const cellElement = this._cellElementFor(cell)
+    const popup = document.createElement('div')
+    popup.classList.add(CLASS_NAME_EDITOR_POPUP)
+
+    if (cellElement) {
+      const rootRect = this._element.getBoundingClientRect()
+      const cellRect = cellElement.getBoundingClientRect()
+      popup.style.top = `${cellRect.top - rootRect.top}px`
+      popup.style.left = `${cellRect.left - rootRect.left}px`
+      popup.style.minWidth = `${cellRect.width}px`
+    }
+
+    popup.append(this._editor!.element)
+    this._element.append(popup)
+    this._editorPopup = popup
+  }
+
+  private _commitEdit(value: unknown): void {
+    const editing = this._editingCell
+    if (!editing) {
+      return
+    }
+
+    const validate = this._columnsByKey.get(editing.columnId)?.editValidate
+    if (validate) {
+      const result = validate(value, editing.item)
+      if (result !== true) {
+        this._showEditorInvalid(typeof result === 'string' ? result : '')
+        return
+      }
+    }
+
+    this._teardownEditor()
+    // The grid never mutates items - the app applies the change (setItems /
+    // items prop) and stays the single source of truth.
+    if (this._config.history) {
+      this._undoStack.push({
+        rowId: editing.rowId, columnId: editing.columnId, value, previousValue: editing.previousValue
+      })
+      if (this._undoStack.length > HISTORY_LIMIT) {
+        this._undoStack.shift()
+      }
+
+      this._redoStack = []
+      this._updateHistoryButtons()
+    }
+
+    EventHandler.trigger(this._element, EVENT_EDIT_COMMIT, {
+      item: editing.item,
+      columnId: editing.columnId,
+      value,
+      previousValue: editing.previousValue
+    })
+    this._activeCell?.set({ rowIndex: editing.rowIndex, columnId: editing.columnId }, { focus: true })
+  }
+
+  private _cancelEdit(): void {
+    const editing = this._editingCell
+    if (!editing) {
+      return
+    }
+
+    this._teardownEditor()
+    EventHandler.trigger(this._element, EVENT_EDIT_CANCEL, { item: editing.item, columnId: editing.columnId })
+    this._activeCell?.set({ rowIndex: editing.rowIndex, columnId: editing.columnId }, { focus: true })
+  }
+
+  private _stopEditing(options: { commit: boolean; force?: boolean }): void {
+    if (!this._editingCell) {
+      return
+    }
+
+    if (options.commit && this._editor?.getValue) {
+      this._commitEdit(this._editor.getValue())
+      // An invalid value blocks the commit; when the edit cannot survive
+      // anyway (row recycled away, row set changed), drop the draft.
+      if (this._editingCell && options.force) {
+        this._cancelEdit()
+      }
+
+      return
+    }
+
+    // A custom editor without getValue owns its commits - stopping from the
+    // outside can only cancel.
+    this._cancelEdit()
+  }
+
+  private _showEditorInvalid(message: string): void {
+    const editor = this._editor
+    if (!editor) {
+      return
+    }
+
+    const input = editor.element.matches('input, select, textarea') ?
+      editor.element :
+      editor.element.querySelector<HTMLElement>('input, select, textarea')
+    if (!input) {
+      return
+    }
+
+    if (!this._editorErrorElement) {
+      this._editorErrorElement = document.createElement('div')
+      this._editorErrorElement.classList.add('visually-hidden')
+      this._editorErrorElement.id = `data-grid-editor-error-${++editorErrorCount}`
+      this._element.append(this._editorErrorElement)
+    }
+
+    this._editorErrorElement.textContent = message
+    input.classList.add('is-invalid')
+    input.setAttribute('aria-invalid', 'true')
+    input.setAttribute('aria-errormessage', this._editorErrorElement.id)
+  }
+
+  private _moveEditing(direction: -1 | 1): void {
+    const editing = this._editingCell
+    if (!editing) {
+      return
+    }
+
+    const columns = this._visibleColumns()
+    const currentIndex = columns.findIndex(column => column.key === editing.columnId)
+    let next: DataGridColumn | null = null
+    for (let index = currentIndex + direction; index >= 0 && index < columns.length; index += direction) {
+      if (this._isColumnEditable(columns[index])) {
+        next = columns[index]
+        break
+      }
+    }
+
+    this._stopEditing({ commit: true })
+    if (this._editingCell) {
+      // An invalid value blocked the commit - stay.
+      return
+    }
+
+    if (next) {
+      const cell = { rowIndex: editing.rowIndex, columnId: next.key }
+      this._activeCell?.set(cell, { focus: true })
+      this._startEditing(cell)
+    }
+  }
+
+  private _teardownEditor(): void {
+    if (this._editorPointerdownHandler) {
+      EventHandler.off(document, EVENT_POINTERDOWN, this._editorPointerdownHandler)
+      this._editorPointerdownHandler = null
+    }
+
+    if (this._editor) {
+      EventHandler.off(this._editor.element, EVENT_FOCUSOUT)
+      this._editor.dispose?.()
+    }
+
+    if (this._editorPopup) {
+      this._editorPopup.remove()
+      this._editorPopup = null
+    }
+
+    if (this._editorErrorElement) {
+      this._editorErrorElement.remove()
+      this._editorErrorElement = null
+    }
+
+    this._editor = null
+    this._editingCell = null
+    this._editorFocusPending = false
+    this._scheduler.schedule()
+  }
+
+  private _setActiveCell(cell: ActiveCell): void {
+    this._activeCell?.set(cell, { focus: true })
+    if (this._virtualizer && cell.rowIndex >= 0) {
+      // No-op when the row is already in view (align: auto); otherwise the
+      // focus request stays pending until the row renders on the next flush.
+      this._virtualizer.instance.scrollToIndex(cell.rowIndex)
+    }
+  }
+
+  private _activeCellContext(): ActiveCellContext {
+    const rowCount = this._table.getRowModel().rows.length
+    const paginated = Boolean(this._config.pagination) || Boolean(this._config.dataProvider)
+    const viewportRows = Math.floor((this._viewportElement?.clientHeight ?? 0) / this._config.rowHeight)
+
+    return {
+      columnIds: this._visibleLeafColumns().map(column => column.id),
+      rowCount,
+      pageStep: paginated ?
+        this._table.getState().pagination.pageSize :
+        Math.max(1, viewportRows || rowCount),
+      paginated
+    }
+  }
+
+  private _cellElementFor(cell: ActiveCell): HTMLElement | null {
+    if (cell.rowIndex === -1) {
+      return this._header.element.querySelector<HTMLElement>(
+        `tr:first-child th[data-coreui-column="${cell.columnId}"]`
+      )
+    }
+
+    const rowElement = this._body.element.querySelector<HTMLElement>(`tr[data-coreui-index="${cell.rowIndex}"]`)
+    return rowElement?.querySelector<HTMLElement>(`td[data-coreui-column="${cell.columnId}"]`) ?? null
+  }
+
+  // The roving-tabindex pass: runs after every render/recycle flush, in the
+  // same slot as the aria attributes, so focus is always re-derived from
+  // state (never from what the recycler left in the DOM).
+  private _applyCellNavigation(): void {
+    if (!this._activeCell) {
+      return
+    }
+
+    const context = this._activeCellContext()
+    this._activeCell.clamp(context)
+
+    this._tableElement.setAttribute(
+      'aria-colcount',
+      String(context.columnIds.length + (this._config.rowSelection ? 1 : 0))
+    )
+
+    const active = this._activeCell.get()
+    // With no active cell yet, the first data cell (or first header cell in
+    // an empty grid) is the grid's single tab stop.
+    const tabbable = active ?? (context.columnIds.length > 0 ?
+      { rowIndex: context.rowCount > 0 ? 0 : -1, columnId: context.columnIds[0] } :
+      null)
+
+    for (const cellElement of this._header.element.querySelectorAll<HTMLElement>('tr:first-child th[data-coreui-column]')) {
+      applyTabIndex(
+        cellElement,
+        tabbable !== null && tabbable.rowIndex === -1 && cellElement.dataset.coreuiColumn === tabbable.columnId
+      )
+    }
+
+    for (const rowElement of this._body.element.querySelectorAll<HTMLElement>('tr[data-coreui-index]')) {
+      const isActiveRow = tabbable !== null && rowElement.dataset.coreuiIndex === String(tabbable.rowIndex)
+      for (const cellElement of rowElement.querySelectorAll<HTMLElement>('td[data-coreui-column]')) {
+        applyTabIndex(cellElement, isActiveRow && cellElement.dataset.coreuiColumn === tabbable!.columnId)
+      }
+    }
+
+    if (!active) {
+      return
+    }
+
+    const activeElement = this._cellElementFor(active)
+
+    if (activeElement) {
+      if (this._activeCell.consumeFocusRequest()) {
+        activeElement.focus({ preventScroll: true })
+      }
+
+      return
+    }
+
+    // The active cell scrolled out of the rendered window while focused: park
+    // focus on the viewport so the keydown fallback stays inside the grid.
+    if (this._containsFocus && !this._element.contains(document.activeElement)) {
+      this._viewportElement.focus({ preventScroll: true })
+    }
+  }
+
+  private _getMenuActions(columnKey: string): DataGridMenuAction[] {
+    const column = this._table.getColumn(columnKey)
+    const config = this._columnsByKey.get(columnKey)
+    if (!column || !config) {
+      return []
+    }
+
+    const actions: DataGridMenuAction[] = []
+
+    if (this._isColumnSortable(config)) {
+      const sorted = column.getIsSorted()
+      actions.push(
+        {
+          key: 'sort-asc',
+          label: this._labels.sortAscending,
+          disabled: sorted === 'asc',
+          group: 'sorting',
+          icon: this._sanitizeIcon(this._config.sortAscendingIcon),
+          run: () => column.toggleSorting(false)
+        },
+        {
+          key: 'sort-desc',
+          label: this._labels.sortDescending,
+          disabled: sorted === 'desc',
+          group: 'sorting',
+          icon: this._sanitizeIcon(this._config.sortDescendingIcon),
+          run: () => column.toggleSorting(true)
+        }
+      )
+
+      if (sorted) {
+        actions.push({
+          key: 'clear-sort',
+          label: this._labels.clearSort,
+          group: 'sorting',
+          icon: this._sanitizeIcon(this._config.sortNeutralIcon),
+          run: () => column.clearSorting()
+        })
+      }
+    }
+
+    if (this._config.columnPinning) {
+      const pinned = column.getIsPinned()
+      if (pinned !== 'left') {
+        actions.push({
+          key: 'pin-left',
+          label: this._labels.pinLeft,
+          group: 'pinning',
+          icon: this._sanitizeIcon(this._config.pinLeftIcon),
+          run: () => column.pin('left')
+        })
+      }
+
+      if (pinned !== 'right') {
+        actions.push({
+          key: 'pin-right',
+          label: this._labels.pinRight,
+          group: 'pinning',
+          icon: this._sanitizeIcon(this._config.pinRightIcon),
+          run: () => column.pin('right')
+        })
+      }
+
+      if (pinned) {
+        actions.push({
+          key: 'unpin',
+          label: this._labels.unpin,
+          group: 'pinning',
+          icon: this._sanitizeIcon(this._config.unpinIcon),
+          run: () => column.pin(false)
+        })
+      }
+    }
+
+    if (this._config.columnOrder && config.movable !== false) {
+      const region = this._visibleLeafColumns().filter(item => item.getIsPinned() === column.getIsPinned())
+      const index = region.findIndex(item => item.id === columnKey)
+      actions.push(
+        {
+          key: 'move-left',
+          label: this._labels.moveLeft,
+          disabled: index <= 0,
+          group: 'ordering',
+          icon: this._sanitizeIcon(this._config.moveLeftIcon),
+          run: () => this._moveColumn(columnKey, -1)
+        },
+        {
+          key: 'move-right',
+          label: this._labels.moveRight,
+          disabled: index === region.length - 1,
+          group: 'ordering',
+          icon: this._sanitizeIcon(this._config.moveRightIcon),
+          run: () => this._moveColumn(columnKey, 1)
+        }
+      )
+    }
+
+    if (this._config.columnVisibility && column.getCanHide()) {
+      actions.push({
+        key: 'hide',
+        label: this._labels.hideColumn,
+        group: 'visibility',
+        icon: this._sanitizeIcon(this._config.hideColumnIcon),
+        run: () => column.toggleVisibility(false)
+      })
+    }
+
+    // A builder receives the built-in actions (icons already sanitized) and the
+    // column, and returns the final list — reorder, filter, or add custom items.
+    const builder = typeof this._config.columnMenu === 'function' ? this._config.columnMenu : null
+    const finalActions = builder ? builder({ column: config, defaultActions: actions }) : actions
+
+    // Sanitize again so custom items' icons pass through the SVG allow list too
+    // (re-sanitizing the built-in icons is a no-op).
+    return finalActions.map(action =>
+      (action.icon ? { ...action, icon: this._sanitizeIcon(action.icon) } : action)
+    )
+  }
+
+  // All leaf ids in the current order, hidden columns included - building a new
+  // order from visible ids only would drop hidden columns, and TanStack appends
+  // missing ids at the end when they are shown again.
+  private _orderedLeafIds(): string[] {
+    const allIds = this._table.getAllLeafColumns().map(column => column.id)
+    const order = this._table.getState().columnOrder
+    if (order.length === 0) {
+      return allIds
+    }
+
+    const known = new Set(allIds)
+    const ordered = order.filter(id => known.has(id))
+    const seen = new Set(ordered)
+    return [...ordered, ...allIds.filter(id => !seen.has(id))]
+  }
+
+  private _moveColumn(columnKey: string, direction: -1 | 1): void {
+    const column = this._table.getColumn(columnKey)
+    if (!column) {
+      return
+    }
+
+    const region = column.getIsPinned()
+    const ids = this._orderedLeafIds()
+    const regionIds = this._visibleLeafColumns()
+      .filter(item => item.getIsPinned() === region)
+      .map(item => item.id)
+    const neighbor = regionIds[regionIds.indexOf(columnKey) + direction]
+    if (!neighbor) {
+      return
+    }
+
+    const from = ids.indexOf(columnKey)
+    const to = ids.indexOf(neighbor)
+    ids[from] = neighbor
+    ids[to] = columnKey
+    this._table.setColumnOrder(ids)
+  }
+
+  private _onColumnDragStart(event: Event & Record<string, unknown>): void {
+    // A drag started from the resize handle is a resize, not a reorder. The
+    // handle's mousedown is preventDefault'd so the browser never starts a drag
+    // there; this ancestry check is a secondary guard.
+    if ((event.target as HTMLElement).closest?.(SELECTOR_RESIZER)) {
+      event.preventDefault()
+      return
+    }
+
+    const target = (event.delegateTarget ?? event.target) as HTMLElement
+    this._dragColumn = target.dataset.coreuiColumn ?? null
+    target.classList.add(CLASS_NAME_DRAGGING)
+
+    const { dataTransfer } = event as unknown as DragEvent
+    if (dataTransfer) {
+      dataTransfer.effectAllowed = 'move'
+      dataTransfer.setData('text/plain', this._dragColumn ?? '')
+    }
+  }
+
+  private _onColumnDrop(event: Event & Record<string, unknown>): void {
+    event.preventDefault()
+    const target = (event.delegateTarget ?? event.target) as HTMLElement
+    const targetKey = target.dataset.coreuiColumn
+    const sourceKey = this._dragColumn
+    this._endColumnDrag()
+
+    if (!sourceKey || !targetKey || sourceKey === targetKey) {
+      return
+    }
+
+    const source = this._table.getColumn(sourceKey)
+    const targetColumn = this._table.getColumn(targetKey)
+    // Reordering never crosses a pinning boundary — pin membership is state,
+    // not position.
+    if (!source || !targetColumn || source.getIsPinned() !== targetColumn.getIsPinned()) {
+      return
+    }
+
+    const ids = this._orderedLeafIds()
+    const from = ids.indexOf(sourceKey)
+    const to = ids.indexOf(targetKey)
+    if (from === -1 || to === -1) {
+      return
+    }
+
+    // Removing the source first makes inserting at the target's original index
+    // land after it when dragging right and before it when dragging left.
+    ids.splice(from, 1)
+    ids.splice(to, 0, sourceKey)
+    this._table.setColumnOrder(ids)
+  }
+
+  private _endColumnDrag(): void {
+    this._dragColumn = null
+    for (const cell of this._element.querySelectorAll(`.${CLASS_NAME_DRAGGING}, .${CLASS_NAME_DROP_TARGET}`)) {
+      cell.classList.remove(CLASS_NAME_DRAGGING, CLASS_NAME_DROP_TARGET)
+    }
+  }
+
+  private _startColumnResize(event: Event & Record<string, unknown>): void {
+    const target = (event.delegateTarget ?? event.target) as HTMLElement
+    const key = target.closest('th')?.dataset.coreuiColumn
+    if (!key) {
+      return
+    }
+
+    // Stop the browser from starting a native column-reorder drag from the
+    // draggable th when the press lands on the resize handle inside it.
+    if (event.type === 'mousedown') {
+      event.preventDefault()
+    }
+
+    const header = this._table.getHeaderGroups()[0]?.headers.find(item => item.column.id === key)
+    header?.getResizeHandler()(event)
+  }
+
+  private _toggleRowSelection(event: Event & Record<string, unknown>): void {
+    const input = (event.delegateTarget ?? event.target) as HTMLInputElement
+    const rowElement = input.closest('tr')
+    if (!rowElement) {
+      return
+    }
+
+    const index = Number(rowElement.dataset.coreuiIndex)
+    const { rows } = this._table.getRowModel()
+    const selected = input.checked
+
+    if ((event as unknown as MouseEvent).shiftKey && this._selectionAnchorIndex !== null) {
+      const start = Math.min(this._selectionAnchorIndex, index)
+      const end = Math.max(this._selectionAnchorIndex, index)
+      this._table.setRowSelection(previous => {
+        const next = { ...previous }
+        for (const row of rows.slice(start, end + 1)) {
+          if (selected) {
+            next[row.id] = true
+          } else {
+            delete next[row.id]
+          }
+        }
+
+        return next
+      })
+    } else {
+      rows[index]?.toggleSelected(selected)
+    }
+
+    this._selectionAnchorIndex = index
+  }
+
+  private _initDataSource(): void {
+    const { dataProvider } = this._config
+    if (!dataProvider) {
+      return
+    }
+
+    this._dataSource = createDataSource({
+      provider: request => dataProvider(request),
+      getRequest: () => {
+        const state = this._table.getState()
+        return {
+          columnFilters: state.columnFilters,
+          globalFilter: (state.globalFilter as string | undefined) ?? '',
+          pagination: state.pagination,
+          sorting: state.sorting
+        }
+      },
+      onLoad: response => {
+        this._stopEditing({ commit: false })
+        this._loadFailed = false
+        this._dataVersion++
+        this._table.setOptions(previous => ({
+          ...previous,
+          data: response.items,
+          rowCount: response.totalRows
+        }))
+        EventHandler.trigger(this._element, EVENT_DATA_LOAD, {
+          items: response.items,
+          totalRows: response.totalRows
+        })
+        this._announceResults(response.totalRows)
+        this._scheduler.schedule()
+      },
+      onError: error => {
+        this._stopEditing({ commit: false })
+        this._loadFailed = true
+        this._dataVersion++
+        this._table.setOptions(previous => ({ ...previous, data: [], rowCount: 0 }))
+        EventHandler.trigger(this._element, EVENT_DATA_ERROR, { error })
+        this._scheduler.schedule()
+      },
+      onLoadingChange: loading => {
+        if (this._loading) {
+          this._loading.setVisible(loading)
+        }
+
+        this._viewportElement.setAttribute('aria-busy', String(loading))
+      }
+    })
+
+    this._dataSource.load()
+  }
+
+  // Visible leaf columns in VISUAL order: left-pinned, center (columnOrder),
+  // right-pinned — getVisibleLeafColumns() alone does not regroup pinning.
+  private _visibleLeafColumns() {
+    return [
+      ...this._table.getLeftVisibleLeafColumns(),
+      ...this._table.getCenterVisibleLeafColumns(),
+      ...this._table.getRightVisibleLeafColumns()
+    ]
+  }
+
+  private _chooserColumns(): ColumnChooserColumn[] {
+    const columns: ColumnChooserColumn[] = []
+    for (const id of this._orderedLeafIds()) {
+      const column = this._table.getColumn(id)
+      const config = this._columnsByKey.get(id)
+      if (!column || !config) {
+        continue
+      }
+
+      columns.push({
+        id,
+        label: config.label ?? config.key,
+        canHide: column.getCanHide(),
+        visible: column.getIsVisible()
+      })
+    }
+
+    return columns
+  }
+
+  private _visibleColumns(): DataGridColumn[] {
+    const columns: DataGridColumn[] = []
+    for (const column of this._visibleLeafColumns()) {
+      const config = this._columnsByKey.get(column.id)
+      if (config) {
+        columns.push(config)
+      }
+    }
+
+    return columns
+  }
+
+  private _getColumnSizes(): Record<string, number> {
+    const sizes: Record<string, number> = {}
+    for (const header of this._table.getHeaderGroups()[0]?.headers ?? []) {
+      sizes[header.column.id] = header.getSize()
+    }
+
+    return sizes
+  }
+
+  private _getFilteredColumns(): string[] {
+    return this._table.getState().columnFilters.map(filter => filter.id)
+  }
+
+  private _getPinning(): GridPinning {
+    // Visible columns only - getLeftLeafColumns/getPinnedIndex include hidden
+    // columns, which would leave the edge class on a column nobody sees.
+    const leftColumns = this._table.getLeftLeafColumns().filter(column => column.getIsVisible())
+    const rightColumns = this._table.getRightLeafColumns().filter(column => column.getIsVisible())
+    // The selection cell is not a TanStack column; anchor it to the left as
+    // soon as any data column is pinned there so the checkbox travels with them.
+    const selectPinned = Boolean(this._config.rowSelection) && leftColumns.length > 0
+    const columns: Record<string, PinnedCellInfo> = {}
+
+    for (const [index, column] of leftColumns.entries()) {
+      columns[column.id] = {
+        side: 'left',
+        offset: column.getStart('left'),
+        edge: index === leftColumns.length - 1,
+        afterSelect: selectPinned
+      }
+    }
+
+    for (const [index, column] of rightColumns.entries()) {
+      columns[column.id] = {
+        side: 'right',
+        offset: column.getAfter('right'),
+        edge: index === 0,
+        afterSelect: false
+      }
+    }
+
+    return {
+      columns,
+      select: selectPinned ?
+{
+ side: 'left', offset: 0, edge: false, afterSelect: false
+} :
+null
+    }
+  }
+
+  private _storageKey(): string | null {
+    return this._config.stateKey ? `${STATE_STORAGE_PREFIX}${this._config.stateKey}` : null
+  }
+
+  private _restorePersistedState(): void {
+    const key = this._storageKey()
+    if (!key) {
+      return
+    }
+
+    let state: Partial<DataGridState> | null = null
+    try {
+      const raw = window.localStorage.getItem(key)
+      state = raw ? (JSON.parse(raw) as Partial<DataGridState>) : null
+    } catch {
+      return
+    }
+
+    if (!state) {
+      return
+    }
+
+    this.restoreState(state)
+  }
+
+  private _updateHistoryButtons(): void {
+    const undoButton = this._element.querySelector<HTMLButtonElement>(SELECTOR_TOOLBAR_UNDO)
+    if (undoButton) {
+      undoButton.disabled = this._undoStack.length === 0
+    }
+
+    const redoButton = this._element.querySelector<HTMLButtonElement>(SELECTOR_TOOLBAR_REDO)
+    if (redoButton) {
+      redoButton.disabled = this._redoStack.length === 0
+    }
+  }
+
+  private _announceResults(count: number): void {
+    this._announce(interpolate(this._labels.resultsAnnouncement, { count }))
+  }
+
+  private _announce(message: string): void {
+    if (this._liveRegion) {
+      this._liveRegion.textContent = message
+    }
+  }
+
+  private _getTotalRows(): number {
+    if (this._config.dataProvider) {
+      return this._table.options.rowCount ?? 0
+    }
+
+    return this._table.getFilteredRowModel().rows.length
+  }
+
+  private _notifyStateChange(previous: TableState, next: TableState): void {
+    // TanStack's resize handler keeps document-level listeners until mouseup;
+    // a dispose mid-drag would re-enter here against a torn-down instance.
+    if (!this._element) {
+      return
+    }
+
+    // stateKey persistence is automatic - every state change (debounced)
+    // rewrites the snapshot, so the view survives a reload with no explicit
+    // save step.
+    if (this._config.stateKey) {
+      if (!this._persistState) {
+        this._persistState = debounce(() => {
+          const key = this._storageKey()
+          if (!key) {
+            return
+          }
+
+          try {
+            window.localStorage.setItem(key, JSON.stringify(this.getState()))
+          } catch {
+            // Quota/privacy-mode failures degrade to a non-persistent grid.
+          }
+        }, STATE_AUTOSAVE_DEBOUNCE_MS)
+      }
+
+      this._persistState()
+    }
+
+    // The shift-click range anchor and the active cell are indexes into the
+    // current row set; any transition that reshuffles rows would make them
+    // point at arbitrary ones. An in-flight edit stops (commit) first.
+    // Pagination compares by VALUE: a data replacement makes TanStack
+    // auto-reset the page index, which replaces the state object without
+    // changing it - identity alone would kill an edit right after its
+    // editCommit handler applied the change.
+    if (
+      previous.sorting !== next.sorting ||
+      previous.columnFilters !== next.columnFilters ||
+      previous.globalFilter !== next.globalFilter ||
+      previous.pagination.pageIndex !== next.pagination.pageIndex ||
+      previous.pagination.pageSize !== next.pagination.pageSize
+    ) {
+      this._stopEditing({ commit: true, force: true })
+      this._selectionAnchorIndex = null
+      this._activeCell?.reset()
+    }
+
+    if (previous.sorting !== next.sorting) {
+      EventHandler.trigger(this._element, EVENT_SORTING_CHANGE, {
+        sorting: next.sorting
+      })
+    }
+
+    const filtersChanged =
+      previous.columnFilters !== next.columnFilters || previous.globalFilter !== next.globalFilter
+
+    if (filtersChanged) {
+      EventHandler.trigger(this._element, EVENT_FILTER_CHANGE, {
+        columnFilters: next.columnFilters,
+        globalFilter: next.globalFilter ?? ''
+      })
+
+      if (!this._config.dataProvider) {
+        this._announceResults(this._table.getFilteredRowModel().rows.length)
+      }
+    }
+
+    if (previous.rowSelection !== next.rowSelection) {
+      EventHandler.trigger(this._element, EVENT_SELECTION_CHANGE, {
+        rowSelection: next.rowSelection,
+        selectedItems: this.getSelectedItems()
+      })
+    }
+
+    if (previous.pagination !== next.pagination) {
+      EventHandler.trigger(this._element, EVENT_PAGINATION_CHANGE, {
+        pagination: next.pagination
+      })
+    }
+
+    if (previous.columnSizing !== next.columnSizing) {
+      EventHandler.trigger(this._element, EVENT_SIZING_CHANGE, {
+        columnSizing: next.columnSizing
+      })
+    }
+
+    if (previous.columnPinning !== next.columnPinning) {
+      EventHandler.trigger(this._element, EVENT_PINNING_CHANGE, {
+        columnPinning: next.columnPinning
+      })
+    }
+
+    if (previous.columnOrder !== next.columnOrder) {
+      EventHandler.trigger(this._element, EVENT_ORDER_CHANGE, {
+        columnOrder: next.columnOrder
+      })
+    }
+
+    if (previous.columnVisibility !== next.columnVisibility) {
+      EventHandler.trigger(this._element, EVENT_VISIBILITY_CHANGE, {
+        columnVisibility: next.columnVisibility
+      })
+    }
+
+    if (this._dataSource) {
+      const refetchNeeded = filtersChanged || previous.sorting !== next.sorting
+
+      if (refetchNeeded && next.pagination.pageIndex !== 0) {
+        // Back to page one first; the resulting pagination change re-enters
+        // this handler and triggers the (debounced) fetch exactly once.
+        this._table.setPageIndex(0)
+        return
+      }
+
+      if (refetchNeeded || previous.pagination !== next.pagination) {
+        this._dataSource.load()
+      }
+    }
+  }
+
+  private _update(): void {
+    if (this._virtualizer) {
+      this._virtualizer.setCount(this._table.getRowModel().rows.length)
+      this._virtualizer.instance._willUpdate()
+    }
+
+    // Scrolling the editing row out of the rendered window commits the edit
+    // (AG behavior) - BEFORE the recycler wipes the editor's DOM.
+    if (this._editingCell && this._virtualizer) {
+      const { rowIndex } = this._editingCell
+      const rendered = this._virtualizer.instance.getVirtualItems().some(item => item.index === rowIndex)
+      if (!rendered) {
+        this._stopEditing({ commit: true, force: true })
+      }
+    }
+
+    this._tableElement.setAttribute(
+      'aria-rowcount',
+      String(this._header.rowCount + this._getTotalRows())
+    )
+
+    this._header.update({
+      filteredColumns: this._config.columnFilters ? this._getFilteredColumns() : null,
+      order: this._visibleLeafColumns().map(column => column.id),
+      pinning: this._config.columnPinning ? this._getPinning() : null,
+      resizingColumn: this._config.columnSizing ?
+        this._table.getState().columnSizingInfo.isResizingColumn :
+        false,
+      sizes: (this._config.columnSizing || this._config.columnPinning) ? this._getColumnSizes() : null,
+      sorting: this._table.getState().sorting,
+      selectAll: this._config.rowSelection ?
+        {
+          checked: this._table.getIsAllRowsSelected(),
+          indeterminate: this._table.getIsSomeRowsSelected()
+        } :
+        null
+    })
+    this._body.update()
+    this._applyCellNavigation()
+
+    // The editor element enters the DOM during the body pass (inline) or at
+    // mount (popup) - focus it once it is connected.
+    if (this._editorFocusPending && this._editor?.element.isConnected) {
+      this._editorFocusPending = false
+      if (this._editor.focus) {
+        this._editor.focus()
+      } else {
+        (this._editor.element.querySelector<HTMLElement>(FOCUSABLE_SELECTOR) ?? this._editor.element).focus({
+          preventScroll: true
+        })
+      }
+    }
+
+    this._toolbar?.update?.()
+    this._emptySlot?.update?.()
+
+    for (const instance of this._paginations) {
+      instance.refresh()
+    }
+  }
+
+  private _paginationState() {
+    const { pagination } = this._table.getState()
+    return {
+      pageCount: this._table.getPageCount(),
+      pageIndex: pagination.pageIndex,
+      pageSize: pagination.pageSize,
+      totalRows: this._getTotalRows()
+    }
+  }
+
+  // Static
+  static jQueryInterface(
+    this: { each: (callback: (this: HTMLElement) => void) => unknown },
+    config?: string | Partial<DataGridOptions>
+  ) {
+    return this.each(function () {
+      const data = DataGrid.getOrCreateInstance(this, typeof config === 'string' ? undefined : config)
+
+      if (typeof config !== 'string') {
+        return
+      }
+
+      const methods = data as unknown as Record<string, (() => void) | undefined>
+      if (methods[config] === undefined || config.startsWith('_') || config === 'constructor') {
+        throw new TypeError(`No method named "${config}"`)
+      }
+
+      methods[config]!()
+    })
+  }
+}
+
+defineJQueryPlugin(DataGrid)
+
+export default DataGrid