@ornery/ui-grid-vanilla 0.1.10 → 1.0.1

package/src/ui-grid-standalone.element.ts

@@ -1,47 +1,105 @@
 import {
-  GRID_CORE_CSS,
-  SORT_DIRECTIONS,
-  buildGridHeaderContext,
   canGridMoveColumns,
-  downloadGridCsvFile,
-  exportCsvRows,
-  findNextGridCell,
-  formatGridHeaderDisplayValue,
-  getCellValue,
-  isGridNavigationKey,
-  isPrintableGridKey,
-  sanitizeDownloadFilename,
+  interpolateGridTemplate,
   type DisplayItem,
   type GridColumnDef,
   type GridOptions,
   type GridRecord,
-  type GroupItem,
   type GridRow,
+  type GroupItem,
 } from '@ornery/ui-grid-core';
+import {
+  FrameworkSlotBridge,
+  type FrameworkRenderedSlotsConfig,
+} from './framework-slots';
+export type {
+  FrameworkRenderedSlotsConfig,
+  FrameworkCellSlot,
+  FrameworkHeaderSlot,
+  FrameworkFilterSlot,
+  FrameworkGroupRowSlot,
+  FrameworkExpandableRowSlot,
+  FrameworkEmptyStateSlot,
+  FrameworkSlotDelta,
+} from './framework-slots';
+import {
+  OBSERVED_GRID_ATTRIBUTES,
+  parseGridAttributeOptions,
+} from './attribute-bridge';
+import {
+  getTemplateMarkup as getTemplateMarkupFromLightDom,
+  renderBodyCell,
+  renderCellTemplate,
+  renderCellTemplateFromMarkup,
+  renderDisplayItem,
+  renderEmptyState,
+  renderExpandableTemplate,
+  renderFilterCell,
+  renderHeaderCell,
+  renderPagination,
+  renderSlotRegistry,
+} from './render';
+import {
+  fingerprintItems,
+  patchBodyCell,
+  patchCells,
+  patchExistingRows,
+  patchFilterCells,
+  patchGroupRow,
+  patchPagination,
+  reconcileBodyRoot,
+  reconcilePagination,
+  renderPatch,
+} from './patch';
+import {
+  applyFocusedCellClass,
+  commitAndMove,
+  focusCellElement,
+  handleRowHeaderCheckboxClick,
+  handleRowSelectionClick,
+  matchesKeyOverride,
+  measureAutoColumnWidth,
+  moveGridFocus,
+  scrollFocusedRowIntoView,
+  type GridMoveDirection,
+} from './focus';
+import {
+  bindEvents,
+  maybeTriggerInfiniteScroll,
+  observeTemplateSlots,
+  syncHeaderHorizontalScroll,
+} from './events';
+import { bodyCellClass } from './utils/cell-class';
+import { asGroupItem, isRowItem } from './utils/display-items';
+import { escapeHtml } from './utils/dom';
+import {
+  IconRegistry,
+  type UiGridControlIconKey,
+  type UiGridIconDefinition,
+  type UiGridIconOverrides,
+} from './icons';
+export type { UiGridControlIconKey, UiGridIconDefinition, UiGridIconOverrides } from './icons';
 import {
   createVanillaGridController,
   type GridControllerSnapshot,
   type GridSaveState,
   type VanillaGridController,
 } from './grid-controller';
-
-function escapeHtml(value: unknown): string {
-  const text = String(value ?? '');
-  return text
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
-}
-
-function asGroupItem(item: DisplayItem): GroupItem {
-  return item as GroupItem;
-}
-
-function isRowItem(item: DisplayItem): item is DisplayItem & { kind: 'row'; row: GridRow } {
-  return item.kind === 'row';
-}
+import emptyTemplate from './ui-grid-empty.template';
+import gridShellTemplate from './ui-grid-shell.template';
+import {
+  bodyStaticMarkup,
+  bodyVirtualMarkup,
+  emptyDataMarkup,
+  filterRowMarkup,
+} from './templates';
+import { UIGridFilterCell } from './components/grid-filter-cell';
+import { UIGridGroupRow } from './components/grid-group-row';
+import { UIGridPagination } from './components/grid-pagination';
+import { UIGridBodyCell } from './components/grid-body-cell';
+import { UIGridHeaderCell } from './components/grid-header-cell';
+import { UIGridTemplate } from './components/grid-template';
+import { UIGridCellEditor } from './components/grid-cell-editor';
 
 export type VanillaUiGridElement = HTMLElement & {
   options: GridOptions;
@@ -55,123 +113,71 @@ export type VanillaUiGridElement = HTMLElement & {
   setData(rows: GridRecord[]): void;
 };
 
-export type UiGridControlIconKey =
-  | 'sortNone'
-  | 'sortAsc'
-  | 'sortDesc'
-  | 'group'
-  | 'groupExpanded'
-  | 'groupCollapsed'
-  | 'treeExpanded'
-  | 'treeCollapsed'
-  | 'expandExpanded'
-  | 'expandCollapsed'
-  | 'pin'
-  | 'pinLeft'
-  | 'pinRight'
-  | 'paginationPrev'
-  | 'paginationNext';
-
-export interface UiGridIconDefinition {
-  viewBox?: string;
-  path: string;
-}
-
-export type UiGridIconOverrides = Partial<Record<UiGridControlIconKey, UiGridIconDefinition>>;
-
 type VanillaGridOptions = GridOptions & {
   iconOverrides?: UiGridIconOverrides;
 };
 
-const DEFAULT_ICONS: Record<UiGridControlIconKey, UiGridIconDefinition> = {
-  sortNone: { path: 'M7 6h10v2H7V6Zm0 5h7v2H7v-2Zm0 5h4v2H7v-2Z' },
-  sortAsc: { path: 'M12 5l-6 6h4v8h4v-8h4z' },
-  sortDesc: { path: 'M12 19l6-6h-4V5h-4v8H6z' },
-  group: { path: 'M4 6h8v4H4V6Zm0 8h8v4H4v-4Zm10-8h6v4h-6V6Zm0 8h6v4h-6v-4Z' },
-  groupExpanded: { path: 'M7 10l5 5 5-5z' },
-  groupCollapsed: { path: 'M10 7l5 5-5 5z' },
-  treeExpanded: { path: 'M7 10l5 5 5-5z' },
-  treeCollapsed: { path: 'M10 7l5 5-5 5z' },
-  expandExpanded: { path: 'M7 10l5 5 5-5z' },
-  expandCollapsed: { path: 'M10 7l5 5-5 5z' },
-  pin: { path: 'M16 12V4h1V2H7v2h1v8l-2 2v2h5v6l1 1 1-1v-6h5v-2l-2-2z' },
-  pinLeft: { path: 'M10 6 4 12l6 6v-4h10v-4H10V6z' },
-  pinRight: { path: 'M14 6v4H4v4h10v4l6-6-6-6z' },
-  paginationPrev: { path: 'M15.41 7.41 14 6l-6 6 6 6 1.41-1.41L10.83 12z' },
-  paginationNext: { path: 'M8.59 16.59 10 18l6-6-6-6-1.41 1.41L13.17 12z' },
-};
-
 export class UiGridStandaloneElement extends HTMLElement {
-  private controller: VanillaGridController | null = null;
-  private snapshot: GridControllerSnapshot | null = null;
-  private unsubscribe: (() => void) | null = null;
-  private activeOptions: VanillaGridOptions | null = null;
-  private attributeOptions: Partial<GridOptions> = {};
-  private attributeSyncScheduled = false;
-  private iconOverrides: UiGridIconOverrides = {};
-  private templateObserver: MutationObserver | null = null;
-  private openPinMenuColumn: string | null = null;
-  private focusedCell: { rowId: string; columnName: string } | null = null;
-  private draggedColumnName: string | null = null;
-  private dropTargetColumnName: string | null = null;
-  private scrollPosition = 0;
-  private horizontalScrollPosition = 0;
-  private scrollFrame: number | null = null;
-  private suppressScrollEvent = false;
-  private lastVirtualStartIndex = -1;
-  private measuredHeaderStickyHeight = 0;
-  private measuredFilterStickyHeight = 0;
-  private stickyHeightRelayoutQueued = false;
-  private benchmarkAverage = '—';
-  private skipNextRender = false;
-  private dataFrame: number | null = null;
-  private pendingPatchedRowIds: Set<string> | null = null;
-  private pendingDataRefreshMode: 'patch' | 'virtual' | 'full' | null = null;
-  private lastScrollActivityAt = 0;
+  // Internal fields. Marked `public` (no access modifier) rather than
+  // `private` because the render / patch / events / focus modules live in
+  // their own files and read this state directly. TypeScript has no real
+  // "module-internal" visibility, so we use `@internal` JSDoc to flag
+  // fields that aren't part of the public API. Consumers of the web
+  // component see only `options`, `controlIcons`, `setFrameworkRenderedSlots`,
+  // and the template-facing strings (`gridTitle`, etc.).
+  /** @internal */ controller: VanillaGridController | null = null;
+  /** @internal */ snapshot: GridControllerSnapshot | null = null;
+  /** @internal */ unsubscribe: (() => void) | null = null;
+  /** @internal */ activeOptions: VanillaGridOptions | null = null;
+  /** @internal */ attributeOptions: Partial<GridOptions> = {};
+  /** @internal */ attributeSyncScheduled = false;
+  /** @internal Owns the SVG-icon registry: defaults merged with consumer
+   * overrides plus rendering helpers. See `./icons.ts`. */
+  icons = new IconRegistry();
+  /** @internal */ templateObserver: MutationObserver | null = null;
+  /** @internal */ openPinMenuColumn: string | null = null;
+  /** @internal */ focusedCell: { rowId: string; columnName: string } | null = null;
+  /** @internal */ draggedColumnName: string | null = null;
+  /** @internal */ dropTargetColumnName: string | null = null;
+  /** @internal */ scrollPosition = 0;
+  /** @internal */ horizontalScrollPosition = 0;
+  /** @internal */ scrollFrame: number | null = null;
+  /** @internal */ suppressScrollEvent = false;
+  /** @internal */ lastVirtualStartIndex = -1;
+  /** @internal */ measuredHeaderStickyHeight = 0;
+  /** @internal */ measuredFilterStickyHeight = 0;
+  /** @internal */ stickyHeightRelayoutQueued = false;
+  /** @internal */ benchmarkAverage = '—';
+  /** @internal */ skipNextRender = false;
+  /** @internal */ autoResizeObserver: ResizeObserver | null = null;
+  /** @internal */ autoResizeDebounceHandle: number | null = null;
+
+  // Template-facing properties for the grid shell template
+  gridTitle = 'Data grid';
+  gridTableStyle = '';
+  bodyViewportStyle = '';
+  templateColumns = '';
+  slotRegistry = '';
+  headerContent = '';
+  filterRowContent = '';
+  bodyContent = '';
+  paginationContent = '';
+  /** @internal */ dataFrame: number | null = null;
+  /** @internal */ pendingPatchedRowIds: Set<string> | null = null;
+  /** @internal */ pendingDataRefreshMode: 'patch' | 'virtual' | 'full' | null = null;
+  /** @internal */ lastScrollActivityAt = 0;
+  /** @internal */ lastStructureKey: string | null = null;
+  /** @internal */ lastItemsFingerprint: string | null = null;
+  /** @internal */ lastVirtualOffset = 0;
+  /** @internal */ lastTotalVirtualHeight = 0;
+
+  /**
+   * @internal Framework-rendered slot bridge. See `./framework-slots.ts`.
+   */
+  frameworkSlots = new FrameworkSlotBridge(this);
 
   static get observedAttributes(): string[] {
-    return [
-      // Scalar attributes
-      'grid-id',
-      'title',
-      'row-height',
-      'header-row-height',
-      'viewport-height',
-      'pagination-page-size',
-      'pagination-current-page',
-      'total-items',
-      'virtualization-threshold',
-      'tree-children-field',
-      'tree-indent',
-      'expandable-row-height',
-      'expandable-row-header-width',
-      'empty-message',
-      'infinite-scroll-rows-from-end',
-      // JSON attributes
-      'column-defs',
-      'data',
-      'grouping',
-      'pagination-page-sizes',
-      // Boolean flags
-      'enable-sorting',
-      'enable-filtering',
-      'enable-grouping',
-      'enable-pinning',
-      'enable-column-moving',
-      'enable-cell-edit',
-      'enable-cell-edit-on-focus',
-      'enable-pagination',
-      'enable-pagination-controls',
-      'use-external-pagination',
-      'enable-expandable',
-      'enable-tree-view',
-      'show-tree-expand-no-children',
-      'tree-row-header-always-visible',
-      'enable-auto-resize',
-      'enable-virtualization',
-      'infinite-scroll-up',
-      'infinite-scroll-down',
-    ];
+    return [...OBSERVED_GRID_ATTRIBUTES];
   }
 
   get options(): GridOptions {
@@ -189,10 +195,36 @@ export class UiGridStandaloneElement extends HTMLElement {
 
   set options(value: GridOptions) {
     this.activeOptions = value as VanillaGridOptions;
-    this.iconOverrides = this.activeOptions.iconOverrides ?? {};
+    this.icons.setOverrides(this.activeOptions.iconOverrides ?? {});
     this.ensureController(this.buildEffectiveOptions(this.activeOptions));
   }
 
+  /**
+   * Declare which slots are framework-rendered. When a slot is flagged, the
+   * element renders a `<slot name="…">` placeholder at the usual site instead
+   * of running its string-interpolation template, and dispatches
+   * `*SlotsChanged` events so a wrapper can insert light-DOM content with a
+   * matching `slot` attribute.
+   *
+   * Pass an empty object (or `{}`) to revert every slot kind back to the
+   * default interpolation path. Individual fields behave the same way:
+   * omitting `cells` means the cells list is unchanged; passing
+   * `cells: []` clears it.
+   *
+   * This is the bridge the Angular / React wrappers use to project native
+   * templates (ng-template, JSX render props) into the grid. Consumers of
+   * the web component directly can ignore this method — the default
+   * `<template slot="cell-columnName">` workflow still works.
+   */
+  setFrameworkRenderedSlots(config: FrameworkRenderedSlotsConfig): void {
+    if (this.frameworkSlots.configure(config)) {
+      // The set of slot placeholders changed — force a structural re-render
+      // so framework-rendered slots transition to `<slot>` nodes (or the
+      // reverse, when a slot is revoked).
+      this.render();
+    }
+  }
+
   attributeChangedCallback(
     _name: string,
     _oldValue: string | null,
@@ -209,202 +241,47 @@ export class UiGridStandaloneElement extends HTMLElement {
   }
 
   private syncAttributesToOptions(): void {
-    this.attributeOptions = {};
-
-    // Scalar string attributes
-    const gridId = this.getAttribute('grid-id');
-    if (gridId !== null) this.attributeOptions.id = gridId;
-
-    const title = this.getAttribute('title');
-    if (title !== null) this.attributeOptions.title = title;
-
-    const emptyMessage = this.getAttribute('empty-message');
-    if (emptyMessage !== null) this.attributeOptions.emptyMessage = emptyMessage;
-
-    const treeChildrenField = this.getAttribute('tree-children-field');
-    if (treeChildrenField !== null) this.attributeOptions.treeChildrenField = treeChildrenField;
-
-    // Scalar number attributes
-    const rowHeight = this.parseNumberAttribute('row-height');
-    if (rowHeight !== undefined) this.attributeOptions.rowHeight = rowHeight;
-
-    const headerRowHeight = this.parseNumberAttribute('header-row-height');
-    if (headerRowHeight !== undefined)
-      this.attributeOptions.headerRowHeight = headerRowHeight;
-
-    const viewportHeight = this.parseNumberAttribute('viewport-height');
-    if (viewportHeight !== undefined) this.attributeOptions.viewportHeight = viewportHeight;
-
-    const paginationPageSize = this.parseNumberAttribute('pagination-page-size');
-    if (paginationPageSize !== undefined)
-      this.attributeOptions.paginationPageSize = paginationPageSize;
-
-    const paginationCurrentPage = this.parseNumberAttribute('pagination-current-page');
-    if (paginationCurrentPage !== undefined)
-      this.attributeOptions.paginationCurrentPage = paginationCurrentPage;
-
-    const totalItems = this.parseNumberAttribute('total-items');
-    if (totalItems !== undefined) this.attributeOptions.totalItems = totalItems;
-
-    const virtualizationThreshold = this.parseNumberAttribute('virtualization-threshold');
-    if (virtualizationThreshold !== undefined)
-      this.attributeOptions.virtualizationThreshold = virtualizationThreshold;
-
-    const treeIndent = this.parseNumberAttribute('tree-indent');
-    if (treeIndent !== undefined) this.attributeOptions.treeIndent = treeIndent;
-
-    const expandableRowHeight = this.parseNumberAttribute('expandable-row-height');
-    if (expandableRowHeight !== undefined)
-      this.attributeOptions.expandableRowHeight = expandableRowHeight;
-
-    const expandableRowHeaderWidth = this.parseNumberAttribute(
-      'expandable-row-header-width',
-    );
-    if (expandableRowHeaderWidth !== undefined)
-      this.attributeOptions.expandableRowHeaderWidth = expandableRowHeaderWidth;
-
-    const infiniteScrollRowsFromEnd = this.parseNumberAttribute(
-      'infinite-scroll-rows-from-end',
-    );
-    if (infiniteScrollRowsFromEnd !== undefined)
-      this.attributeOptions.infiniteScrollRowsFromEnd = infiniteScrollRowsFromEnd;
-
-    // Boolean attributes
-    const enableSorting = this.parseBooleanAttribute('enable-sorting');
-    if (enableSorting !== undefined) this.attributeOptions.enableSorting = enableSorting;
-
-    const enableFiltering = this.parseBooleanAttribute('enable-filtering');
-    if (enableFiltering !== undefined) this.attributeOptions.enableFiltering = enableFiltering;
-
-    const enableGrouping = this.parseBooleanAttribute('enable-grouping');
-    if (enableGrouping !== undefined) this.attributeOptions.enableGrouping = enableGrouping;
-
-    const enablePinning = this.parseBooleanAttribute('enable-pinning');
-    if (enablePinning !== undefined) this.attributeOptions.enablePinning = enablePinning;
-
-    const enableColumnMoving = this.parseBooleanAttribute('enable-column-moving');
-    if (enableColumnMoving !== undefined)
-      this.attributeOptions.enableColumnMoving = enableColumnMoving;
-
-    const enableColumnResizing = this.parseBooleanAttribute('enable-column-resizing');
-    if (enableColumnResizing !== undefined)
-      this.attributeOptions.enableColumnResizing = enableColumnResizing;
-
-    const enableCellEdit = this.parseBooleanAttribute('enable-cell-edit');
-    if (enableCellEdit !== undefined) this.attributeOptions.enableCellEdit = enableCellEdit;
-
-    const enableCellEditOnFocus = this.parseBooleanAttribute('enable-cell-edit-on-focus');
-    if (enableCellEditOnFocus !== undefined)
-      this.attributeOptions.enableCellEditOnFocus = enableCellEditOnFocus;
-
-    const enablePagination = this.parseBooleanAttribute('enable-pagination');
-    if (enablePagination !== undefined)
-      this.attributeOptions.enablePagination = enablePagination;
-
-    const enablePaginationControls = this.parseBooleanAttribute(
-      'enable-pagination-controls',
-    );
-    if (enablePaginationControls !== undefined)
-      this.attributeOptions.enablePaginationControls = enablePaginationControls;
-
-    const useExternalPagination = this.parseBooleanAttribute('use-external-pagination');
-    if (useExternalPagination !== undefined)
-      this.attributeOptions.useExternalPagination = useExternalPagination;
-
-    const enableExpandable = this.parseBooleanAttribute('enable-expandable');
-    if (enableExpandable !== undefined) this.attributeOptions.enableExpandable = enableExpandable;
+    this.attributeOptions = parseGridAttributeOptions(this);
 
-    const enableTreeView = this.parseBooleanAttribute('enable-tree-view');
-    if (enableTreeView !== undefined) this.attributeOptions.enableTreeView = enableTreeView;
-
-    const showTreeExpandNoChildren = this.parseBooleanAttribute(
-      'show-tree-expand-no-children',
-    );
-    if (showTreeExpandNoChildren !== undefined)
-      this.attributeOptions.showTreeExpandNoChildren = showTreeExpandNoChildren;
-
-    const treeRowHeaderAlwaysVisible = this.parseBooleanAttribute(
-      'tree-row-header-always-visible',
-    );
-    if (treeRowHeaderAlwaysVisible !== undefined)
-      this.attributeOptions.treeRowHeaderAlwaysVisible = treeRowHeaderAlwaysVisible;
-
-    const enableAutoResize = this.parseBooleanAttribute('enable-auto-resize');
-    if (enableAutoResize !== undefined) this.attributeOptions.enableAutoResize = enableAutoResize;
-
-    const enableVirtualization = this.parseBooleanAttribute('enable-virtualization');
-    if (enableVirtualization !== undefined)
-      this.attributeOptions.enableVirtualization = enableVirtualization;
-
-    const infiniteScrollUp = this.parseBooleanAttribute('infinite-scroll-up');
-    if (infiniteScrollUp !== undefined) this.attributeOptions.infiniteScrollUp = infiniteScrollUp;
-
-    const infiniteScrollDown = this.parseBooleanAttribute('infinite-scroll-down');
-    if (infiniteScrollDown !== undefined)
-      this.attributeOptions.infiniteScrollDown = infiniteScrollDown;
-
-    // JSON attributes
-    const columnDefs = this.parseJsonAttribute<GridColumnDef[]>('column-defs');
-    if (columnDefs !== undefined) this.attributeOptions.columnDefs = columnDefs;
-
-    const data = this.parseJsonAttribute<GridRecord[]>('data');
-    if (data !== undefined) this.attributeOptions.data = data;
-
-    const grouping = this.parseJsonAttribute('grouping');
-    if (grouping !== undefined && grouping !== null)
-      this.attributeOptions.grouping = grouping;
-
-    const paginationPageSizes = this.parseJsonAttribute<number[] | null>(
-      'pagination-page-sizes',
-    );
-    if (paginationPageSizes !== undefined)
-      this.attributeOptions.paginationPageSizes = paginationPageSizes;
-
-    // Re-render with the merged options.
+    // Re-render with the merged options. Both paths funnel through
+    // buildEffectiveOptions so derived fields (e.g. the default
+    // `expandableRowTemplate` when `enableExpandable` is true) are applied
+    // regardless of whether options came from an imperative `grid.options =`
+    // assignment or purely from HTML attributes.
     if (this.activeOptions !== null) {
       this.ensureController(this.buildEffectiveOptions(this.activeOptions));
     } else {
-      // Purely declarative path: attributes drive the grid without an imperative bridge.
-      this.ensureController({
-        id: '__ui-grid-pending__',
-        data: [],
-        columnDefs: [],
-        ...this.attributeOptions,
-      } as VanillaGridOptions);
-    }
-  }
-
-  private parseBooleanAttribute(name: string): boolean | undefined {
-    return this.hasAttribute(name) ? true : undefined;
-  }
-
-  private parseNumberAttribute(name: string): number | undefined {
-    const raw = this.getAttribute(name);
-    if (raw === null) return undefined;
-    const parsed = Number(raw);
-    return Number.isFinite(parsed) ? parsed : undefined;
-  }
-
-  private parseJsonAttribute<T = unknown>(name: string): T | undefined {
-    const raw = this.getAttribute(name);
-    if (raw === null) return undefined;
-    try {
-      return JSON.parse(raw) as T;
-    } catch (e) {
-      console.warn(`<ui-grid-element>: invalid JSON in "${name}" attribute`, e);
-      return undefined;
+      // Purely declarative path: the attribute-only options are already
+      // populated on `this.attributeOptions` (including `data` / `columnDefs`
+      // when the consumer set `[attr.data]` / `[attr.column-defs]`). Pass
+      // the minimum identity so `buildEffectiveOptions`'s merge doesn't
+      // clobber attribute-provided arrays with empty fallbacks — the
+      // attribute values always win because the spread order is
+      // `{ ...attributeOptions, ...options }`.
+      const fallbackId = this.attributeOptions.id ?? '__ui-grid-pending__';
+      this.ensureController(
+        this.buildEffectiveOptions({
+          id: fallbackId,
+          data: this.attributeOptions.data ?? [],
+          columnDefs: this.attributeOptions.columnDefs ?? [],
+        } as VanillaGridOptions),
+      );
     }
   }
 
   get controlIcons(): UiGridIconOverrides {
-    return this.iconOverrides;
+    return this.icons.getOverrides();
   }
 
   set controlIcons(value: UiGridIconOverrides) {
-    this.iconOverrides = { ...value };
+    this.icons.setOverrides(value);
     this.render();
   }
 
+  private resolveIcon(key: UiGridControlIconKey): UiGridIconDefinition {
+    return this.icons.resolve(key);
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Individual property accessors (mirrors of HTML attributes)
   // ─────────────────────────────────────────────────────────────────
@@ -443,14 +320,6 @@ export class UiGridStandaloneElement extends HTMLElement {
     this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
   }
 
-  get viewportHeight(): number {
-    return this.options.viewportHeight ?? 560;
-  }
-  set viewportHeight(value: number) {
-    this.activeOptions = { ...this.activeOptions, viewportHeight: value } as any;
-    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
-  }
-
   get paginationPageSize(): number {
     return this.options.paginationPageSize ?? 25;
   }
@@ -516,7 +385,10 @@ export class UiGridStandaloneElement extends HTMLElement {
   }
 
   get emptyMessage(): string {
-    return this.options.emptyMessage ?? 'No data available.';
+    // Fall back to the grid's label pack so consumers can re-localize the
+    // empty heading through `options.labels.emptyHeading` rather than
+    // hardcoding an English string here.
+    return this.options.emptyMessage ?? this.snapshot?.labels.emptyHeading ?? '';
   }
   set emptyMessage(value: string) {
     this.activeOptions = { ...this.activeOptions, emptyMessage: value } as any;
@@ -794,62 +666,14 @@ export class UiGridStandaloneElement extends HTMLElement {
   }
 
   private patchCells(changedRowIds?: ReadonlySet<string>): void {
-    const snapshot = this.snapshot;
-    if (!snapshot) {
-      return;
-    }
-
-    const root = this.shadowRoot;
-    if (!root) {
-      return;
-    }
-
-    // Build O(1) lookup maps from the current pipeline snapshot.
-    const rowMap = new Map<string, GridRow>();
-    const rowIndexMap = new Map<string, number>();
-    for (const row of snapshot.pipeline.visibleRows) {
-      rowMap.set(row.id, row);
-      rowIndexMap.set(row.id, rowIndexMap.size);
-    }
-    const colMap = new Map<string, GridColumnDef>();
-    const templateMarkupMap = new Map<string, string | null>();
-    for (const col of snapshot.visibleColumns) {
-      colMap.set(col.name, col);
-      templateMarkupMap.set(col.name, this.getTemplateMarkup(this.cellSlotName(col)));
-    }
-
-    // Patch every rendered body cell in-place.
-    const cells = root.querySelectorAll<HTMLElement>('[data-row][data-column]');
-    for (const cell of cells) {
-      const rowId = cell.dataset['row'];
-      const colName = cell.dataset['column'];
-      if (!rowId || !colName) continue;
-      if (changedRowIds && !changedRowIds.has(rowId)) continue;
-
-      const row = rowMap.get(rowId);
-      const column = colMap.get(colName);
-      if (!row || !column) continue;
-      if (cell.classList.contains('cell-editing')) continue;
-
-      const cellContent = cell.querySelector<HTMLElement>('.cell-content');
-      if (!cellContent) continue;
-
-      const newContent = this.renderCellTemplateFromMarkup(
-        row,
-        column,
-        rowIndexMap.get(rowId) ?? 0,
-        templateMarkupMap.get(colName) ?? null,
-      );
-      if (cellContent.innerHTML !== newContent) {
-        cellContent.innerHTML = newContent;
-      }
-    }
+    patchCells(this, changedRowIds);
   }
 
   connectedCallback(): void {
     this.ensureShadowRoot();
     this.bindEvents();
     this.observeTemplateSlots();
+    this.setupAutoResize();
 
     if (this.activeOptions) {
       this.ensureController(this.buildEffectiveOptions(this.activeOptions));
@@ -863,13 +687,18 @@ export class UiGridStandaloneElement extends HTMLElement {
     this.unsubscribe = null;
     this.templateObserver?.disconnect();
     this.templateObserver = null;
+    this.teardownAutoResize();
     if (this.scrollFrame !== null) {
       cancelAnimationFrame(this.scrollFrame);
       this.scrollFrame = null;
     }
+    // Emit `removed` events for every framework-rendered slot so wrappers
+    // can destroy their views.
+    this.frameworkSlots.flushRemovals();
   }
 
-  private ensureShadowRoot(): ShadowRoot {
+  /** @internal */
+  ensureShadowRoot(): ShadowRoot {
     if (!this.shadowRoot) {
       this.attachShadow({ mode: 'open' });
     }
@@ -877,41 +706,109 @@ export class UiGridStandaloneElement extends HTMLElement {
     return this.shadowRoot as ShadowRoot;
   }
 
-  private ensureController(options: VanillaGridOptions): void {
+  /** @internal */
+  ensureController(options: VanillaGridOptions): void {
     if (this.controller) {
+      if (this.clientWidth > 0) {
+        this.controller.setViewportWidth(this.clientWidth);
+      }
       this.controller.setOptions(options);
       return;
     }
 
     this.controller = createVanillaGridController(options);
+    if (this.clientWidth > 0) {
+      this.controller.setViewportWidth(this.clientWidth);
+    }
+    // Let the controller's cellNav.scrollToFocus delegate into our
+    // element's scroll-and-focus helpers.
+    this.controller.setCellNavScrollHandler((rowId, columnName) => {
+      if (!rowId || !columnName) return;
+      this.scrollFocusedRowIntoView(rowId);
+      this.focusCellElement(rowId, columnName);
+    });
+    // Infinite-scroll resetScroll() brings the viewport back to the top.
+    this.controller.setInfiniteScrollResetHandler(() => {
+      const bodyViewport = this.shadowRoot?.querySelector<HTMLElement>('.grid-body-viewport');
+      if (bodyViewport) {
+        bodyViewport.scrollTop = 0;
+        this.scrollPosition = 0;
+      }
+    });
+    // saveState scroll capture/restore — element owns the DOM element, so
+    // it provides the accessors the controller uses when save()/setState()
+    // handle scroll-position fields.
+    this.controller.setSaveStateScrollHandlers(
+      () => ({ scrollTop: this.scrollPosition, scrollLeft: this.horizontalScrollPosition }),
+      (scrollTop, scrollLeft) => {
+        const bodyViewport = this.shadowRoot?.querySelector<HTMLElement>('.grid-body-viewport');
+        if (!bodyViewport) return;
+        // Defer to a rAF so the body has finished laying out after refresh.
+        requestAnimationFrame(() => {
+          bodyViewport.scrollTop = scrollTop;
+          bodyViewport.scrollLeft = scrollLeft;
+          this.scrollPosition = scrollTop;
+          this.horizontalScrollPosition = scrollLeft;
+          // Keep header/filter strips aligned after a restore.
+          this.syncHeaderHorizontalScroll(scrollLeft);
+        });
+      },
+    );
+    // Importer file-picker: the element mounts a hidden <input type="file">
+    // the first time the controller asks for one, then keeps it around so
+    // subsequent imports reuse it. The controller stays DOM-free.
+    this.controller.setImporterFilePickerHandler(() => {
+      this.openImporterFilePicker();
+    });
     this.unsubscribe = this.controller.subscribe((snapshot) => {
       this.snapshot = snapshot;
       this.render();
     });
   }
 
-  private observeTemplateSlots(): void {
-    if (this.templateObserver) {
-      return;
+  /** Hidden file input used by `gridApi.importer.importAFile()`. Lazily
+   * created on first use and reused thereafter. */
+  private importerFileInput: HTMLInputElement | null = null;
+
+  private openImporterFilePicker(): void {
+    if (!this.controller) return;
+    if (!this.importerFileInput) {
+      const input = document.createElement('input');
+      input.type = 'file';
+      input.accept = '.csv,.json,text/csv,application/json,text/plain';
+      input.style.display = 'none';
+      input.addEventListener('change', () => {
+        const file = input.files?.[0];
+        if (file && this.controller) {
+          void this.controller.gridApi.importer.importThisFile(file);
+        }
+        // Clear so the same file can be re-imported.
+        input.value = '';
+      });
+      this.appendChild(input);
+      this.importerFileInput = input;
     }
+    this.importerFileInput.click();
+  }
 
-    this.templateObserver = new MutationObserver(() => {
-      if (this.activeOptions) {
-        this.ensureController(this.buildEffectiveOptions(this.activeOptions));
-      } else {
-        this.render();
-      }
-    });
+  private observeTemplateSlots(): void {
+    observeTemplateSlots(this);
+  }
 
-    this.templateObserver.observe(this, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      attributeFilter: ['slot'],
-    });
+  private bindEvents(): void {
+    bindEvents(this);
+  }
+
+  private syncHeaderHorizontalScroll(scrollLeft: number): void {
+    syncHeaderHorizontalScroll(this, scrollLeft);
+  }
+
+  private maybeTriggerInfiniteScroll(): void {
+    maybeTriggerInfiniteScroll(this);
   }
 
-  private buildEffectiveOptions(options: VanillaGridOptions): VanillaGridOptions {
+  /** @internal */
+  buildEffectiveOptions(options: VanillaGridOptions): VanillaGridOptions {
     // Merge: attributes are overridden by explicit JS property values.
     // JS property always wins: { ...attributeOptions, ...options }
     const merged = {
@@ -919,8 +816,7 @@ export class UiGridStandaloneElement extends HTMLElement {
       ...options,
     } as VanillaGridOptions;
 
-    const hasExpandableSlot = this.getTemplateMarkup('expandable-row') !== null;
-    if (merged.enableExpandable && hasExpandableSlot && !merged.expandableRowTemplate) {
+    if (merged.enableExpandable && !merged.expandableRowTemplate) {
       merged.expandableRowTemplate = {
         createEmbeddedView: () => undefined,
       };
@@ -929,450 +825,28 @@ export class UiGridStandaloneElement extends HTMLElement {
     return merged;
   }
 
-  private bindEvents(): void {
-    const root = this.ensureShadowRoot();
-    if ((root as ShadowRoot & { __uiGridBound?: boolean }).__uiGridBound) {
-      return;
-    }
-
-    root.addEventListener('click', (event) => {
-      const target = event.target as HTMLElement | null;
-      if (!target || !this.controller || !this.snapshot) {
-        return;
-      }
-
-      const actionNode = target.closest<HTMLElement>('[data-action]');
-      if (!actionNode) {
-        return;
-      }
-
-      const action = actionNode.dataset['action'];
-      if (!action) {
-        return;
-      }
-
-      if (this.openPinMenuColumn && !target.closest('.pin-control')) {
-        this.openPinMenuColumn = null;
-        this.render();
-        return;
-      }
-
-      if (action === 'sort') {
-        const columnName = actionNode.dataset['column'];
-        if (columnName) {
-          this.controller.toggleSort(columnName);
-        }
-        return;
-      }
-
-      if (action === 'group') {
-        const columnName = actionNode.dataset['column'];
-        if (columnName) {
-          this.controller.toggleGrouping(columnName);
-        }
-        return;
-      }
-
-      if (action === 'toggle-group') {
-        const groupId = actionNode.dataset['group'];
-        if (groupId) {
-          const collapsed = actionNode.dataset['collapsed'] !== 'true';
-          this.controller.setCollapsedGroup(groupId, collapsed);
-        }
-        return;
-      }
-
-      if (action === 'pin-trigger') {
-        const columnName = actionNode.dataset['column'];
-        const column = columnName
-          ? this.snapshot.visibleColumns.find((candidate) => candidate.name === columnName)
-          : undefined;
-
-        if (columnName && column) {
-          if (this.controller.isPinned(column)) {
-            this.openPinMenuColumn = null;
-            this.controller.pinColumn(columnName, 'none');
-            return;
-          }
-
-          this.openPinMenuColumn = this.openPinMenuColumn === columnName ? null : columnName;
-          this.render();
-        }
-        return;
-      }
-
-      if (action === 'pin-left' || action === 'pin-right') {
-        const columnName = actionNode.dataset['column'];
-        if (columnName) {
-          this.openPinMenuColumn = null;
-          this.controller.pinColumn(columnName, action === 'pin-left' ? 'left' : 'right');
-        }
-        return;
-      }
-
-      if (action === 'toggle-tree') {
-        const rowId = actionNode.dataset['row'];
-        if (rowId) {
-          this.controller.toggleTreeRow(rowId);
-        }
-        return;
-      }
-
-      if (action === 'toggle-expand') {
-        const rowId = actionNode.dataset['row'];
-        if (rowId) {
-          this.controller.toggleRowExpansion(rowId);
-        }
-        return;
-      }
-
-      if (action === 'page-prev') {
-        this.controller.seekPage(this.snapshot.currentPage - 1);
-        return;
-      }
-
-      if (action === 'page-next') {
-        this.controller.seekPage(this.snapshot.currentPage + 1);
-        return;
-      }
-
-      if (action === 'benchmark') {
-        const result = this.controller.gridApi.core.benchmark();
-        this.benchmarkAverage = result.averageMs.toFixed(2);
-        this.render();
-        return;
-      }
-
-      if (action === 'export-csv') {
-        this.downloadCsv();
-      }
-    });
-
-    root.addEventListener('focusin', (event) => {
-      const target = event.target as HTMLElement | null;
-      if (!target) {
-        return;
-      }
-
-      const cell = target.closest<HTMLElement>('.body-cell[data-row][data-column]');
-      const rowId = cell?.dataset['row'];
-      const columnName = cell?.dataset['column'];
-      if (rowId && columnName) {
-        this.focusedCell = { rowId, columnName };
-      }
-    });
-
-    root.addEventListener('focusout', (event) => {
-      const relatedTarget = (event as FocusEvent).relatedTarget as HTMLElement | null;
-      if (!relatedTarget?.closest('.body-cell[data-row][data-column]')) {
-        this.focusedCell = null;
-      }
-    });
-
-    root.addEventListener('input', (event) => {
-      const target = event.target as HTMLElement | null;
-      if (!target || !this.controller) {
-        return;
-      }
-
-      if (target instanceof HTMLInputElement && target.dataset['role'] === 'filter') {
-        const columnName = target.dataset['column'];
-        if (columnName) {
-          this.controller.setFilter(columnName, target.value);
-        }
-      }
-
-      if (target instanceof HTMLInputElement && target.dataset['role'] === 'editor') {
-        this.controller.updateEditingValue(target.value);
-      }
-    });
-
-    root.addEventListener('change', (event) => {
-      const target = event.target as HTMLElement | null;
-      if (!target || !this.controller) {
-        return;
-      }
-
-      if (target instanceof HTMLSelectElement && target.dataset['role'] === 'page-size') {
-        const value = Number.parseInt(target.value, 10);
-        this.controller.setPageSize(value);
-      }
-    });
-
-    root.addEventListener('mousedown', (event) => {
-      const target = event.target as HTMLElement | null;
-      if (!target || !this.controller) return;
-
-      const resizer = target.closest<HTMLElement>('.column-resizer[data-column]');
-      if (!resizer || !this.controller.canResizeColumns()) return;
-
-      const columnName = resizer.dataset['column'];
-      if (!columnName) return;
-
-      const headerCell = resizer.closest<HTMLElement>('.header-cell');
-      if (!headerCell) return;
-
-      event.preventDefault();
-      event.stopPropagation();
-
-      const startX = (event as MouseEvent).clientX;
-      const startWidth = headerCell.getBoundingClientRect().width;
-      let lastWidth = startWidth;
-
-      const handleMove = (moveEvent: MouseEvent): void => {
-        lastWidth = Math.max(88, startWidth + (moveEvent.clientX - startX));
-
-        // Write directly to DOM — skip full refresh while dragging.
-        const newTemplate = this.controller!.buildTemplateColumnsWithOverride(columnName, lastWidth);
-        const root = this.shadowRoot ?? this;
-        (root as ShadowRoot | HTMLElement).querySelectorAll<HTMLElement>('.header-grid, .filter-grid, .body-grid').forEach((el) => {
-          el.style.gridTemplateColumns = newTemplate;
-        });
-      };
-
-      const handleUp = (): void => {
-        window.removeEventListener('mousemove', handleMove);
-        window.removeEventListener('mouseup', handleUp);
-        // Commit final width once — triggers one full refresh.
-        this.controller!.setColumnWidthOverride(columnName, lastWidth);
-      };
-
-      window.addEventListener('mousemove', handleMove);
-      window.addEventListener('mouseup', handleUp);
-    });
-
-    root.addEventListener('dblclick', (event) => {
-      const target = event.target as HTMLElement | null;
-      if (!target || !this.controller) {
-        return;
-      }
-
-      const resizer = target.closest<HTMLElement>('.column-resizer[data-column]');
-      if (resizer && this.controller.canResizeColumns()) {
-        const columnName = resizer.dataset['column'];
-        if (columnName) {
-          event.preventDefault();
-          event.stopPropagation();
-          this.controller.setColumnWidthOverride(columnName, this.measureAutoColumnWidth(columnName));
-          return;
-        }
-      }
-
-      const cell = target.closest<HTMLElement>('.body-cell');
-      if (!cell) {
-        return;
-      }
-
-      const rowId = cell.dataset['row'];
-      const columnName = cell.dataset['column'];
-      if (rowId && columnName) {
-        this.controller.beginCellEdit(rowId, columnName, event);
-      }
-    });
-
-    root.addEventListener('keydown', (event) => {
-      const keyboardEvent = event as KeyboardEvent;
-      const target = event.target as HTMLElement | null;
-      if (!target || !this.controller) {
-        return;
-      }
-
-      if (target instanceof HTMLInputElement && target.dataset['role'] === 'editor') {
-        if (keyboardEvent.key === 'Enter') {
-          event.preventDefault();
-          this.controller.commitCellEdit();
-          return;
-        }
-
-        if (keyboardEvent.key === 'Escape') {
-          event.preventDefault();
-          this.controller.cancelCellEdit();
-        }
-
-        return;
-      }
-
-      const cell = target.closest<HTMLElement>('.body-cell');
-      if (!cell) {
-        return;
-      }
-
-      const rowId = cell.dataset['row'];
-      const columnName = cell.dataset['column'];
-      if (!rowId || !columnName) {
-        return;
-      }
-
-      if (keyboardEvent.key === 'Enter' || keyboardEvent.key === 'F2') {
-        event.preventDefault();
-        this.controller.beginCellEdit(rowId, columnName, event);
-        return;
-      }
-
-      if (
-        keyboardEvent.key.length === 1 &&
-        !keyboardEvent.ctrlKey &&
-        !keyboardEvent.metaKey &&
-        !keyboardEvent.altKey
-      ) {
-        event.preventDefault();
-        this.controller.beginCellEdit(rowId, columnName, event);
-        this.controller.updateEditingValue(keyboardEvent.key);
-      }
-    });
-
-    root.addEventListener(
-      'blur',
-      (event) => {
-        const target = event.target as HTMLElement | null;
-        if (!target || !this.controller) {
-          return;
-        }
-
-        if (target instanceof HTMLInputElement && target.dataset['role'] === 'editor') {
-          this.controller.commitCellEdit();
-        }
-      },
-      true,
-    );
-
-    root.addEventListener('dragstart', (event) => {
-      const dragEvent = event as DragEvent;
-      const target = event.target as HTMLElement | null;
-      const headerCell = target?.closest<HTMLElement>('.header-cell[data-column]');
-
-      if (!headerCell || !this.snapshot || !canGridMoveColumns(this.snapshot.options)) {
-        event.preventDefault();
-        return;
-      }
-
-      const columnName = headerCell.dataset['column'];
-      if (!columnName || !dragEvent.dataTransfer) {
-        event.preventDefault();
-        return;
-      }
-
-      this.draggedColumnName = columnName;
-      this.dropTargetColumnName = null;
-      dragEvent.dataTransfer.effectAllowed = 'move';
-      dragEvent.dataTransfer.setData('text/plain', columnName);
-      headerCell.classList.add('is-dragging');
-    });
-
-    root.addEventListener('dragover', (event) => {
-      const dragEvent = event as DragEvent;
-      const target = event.target as HTMLElement | null;
-      const headerCell = target?.closest<HTMLElement>('.header-cell[data-column]');
-
-      if (!headerCell || !this.draggedColumnName || !dragEvent.dataTransfer) {
-        return;
-      }
-
-      const columnName = headerCell.dataset['column'];
-      if (!columnName || columnName === this.draggedColumnName) {
-        return;
-      }
-
-      event.preventDefault();
-      dragEvent.dataTransfer.dropEffect = 'move';
-
-      if (this.dropTargetColumnName !== columnName) {
-        root
-          .querySelectorAll('.header-cell.is-drag-target')
-          .forEach((element) => element.classList.remove('is-drag-target'));
-        this.dropTargetColumnName = columnName;
-        headerCell.classList.add('is-drag-target');
-      }
-    });
-
-    root.addEventListener('dragleave', (event) => {
-      const target = event.target as HTMLElement | null;
-      const headerCell = target?.closest<HTMLElement>('.header-cell[data-column]');
-      if (headerCell && headerCell.dataset['column'] === this.dropTargetColumnName) {
-        headerCell.classList.remove('is-drag-target');
-      }
-    });
-
-    root.addEventListener('drop', (event) => {
-      event.preventDefault();
-      const dragEvent = event as DragEvent;
-      const target = event.target as HTMLElement | null;
-      const headerCell = target?.closest<HTMLElement>('.header-cell[data-column]');
-      const targetColumn = headerCell?.dataset['column'];
-      const sourceColumn =
-        this.draggedColumnName ?? dragEvent.dataTransfer?.getData('text/plain') ?? null;
-
-      this.draggedColumnName = null;
-      this.dropTargetColumnName = null;
-
-      root
-        .querySelectorAll('.header-cell.is-dragging, .header-cell.is-drag-target')
-        .forEach((element) => element.classList.remove('is-dragging', 'is-drag-target'));
-
-      if (!sourceColumn || !targetColumn || sourceColumn === targetColumn || !this.controller) {
-        return;
-      }
-
-      this.controller.moveVisibleColumn(sourceColumn, targetColumn);
-    });
-
-    root.addEventListener('dragend', () => {
-      this.draggedColumnName = null;
-      this.dropTargetColumnName = null;
-      root
-        .querySelectorAll('.header-cell.is-dragging, .header-cell.is-drag-target')
-        .forEach((element) => element.classList.remove('is-dragging', 'is-drag-target'));
-    });
-
-    root.addEventListener(
-      'scroll',
-      (event) => {
-        const target = event.target as HTMLElement | null;
-        if (!target?.classList.contains('grid-table') || this.suppressScrollEvent) {
-          return;
-        }
-
-        this.lastScrollActivityAt = Date.now();
-        this.scrollPosition = target.scrollTop;
-        this.horizontalScrollPosition = target.scrollLeft;
-        if (!this.snapshot?.pipeline.virtualizationEnabled) {
-          return;
-        }
-
-        const stickyChromeHeight =
-          this.measuredHeaderStickyHeight + this.measuredFilterStickyHeight;
-        const bodyScrollTop = Math.max(0, this.scrollPosition - stickyChromeHeight);
-        const overscan = 4;
-        const nextStartIndex = Math.max(
-          0,
-          Math.floor(bodyScrollTop / this.snapshot.rowSize) - overscan,
-        );
-        if (nextStartIndex === this.lastVirtualStartIndex) {
-          return;
-        }
-
-        if (this.scrollFrame !== null) {
-          cancelAnimationFrame(this.scrollFrame);
-        }
-
-        this.scrollFrame = requestAnimationFrame(() => {
-          this.scrollFrame = null;
-          this.renderVirtualBody();
-        });
-      },
-      true,
-    );
-
-    (root as ShadowRoot & { __uiGridBound?: boolean }).__uiGridBound = true;
-  }
-
+  /**
+   * Ask the controller to evaluate whether the current scroll position
+   * should request more data at the top or bottom — ports the old grid's
+   * handleScroll → loadData check. The controller does the actual
+   * needLoadMoreData / needLoadMoreDataTop raise.
+   */
+  /**
+   * Mirror horizontal scroll from the body viewport onto the header + filter
+   * strips by setting `scrollLeft` on them. Because those strips are real
+   * scroll containers (with their scrollbars hidden), `position: sticky` on
+   * pinned header / filter cells anchors to the strip's scroll position the
+   * same way body cells anchor to `.grid-body-viewport`. This is the
+   * imperative sync strategy the old ui-grid used in ui-grid-viewport.js.
+   */
   /**
    * Targeted update for virtual scroll: replaces only the rendered rows inside
    * the existing `.grid-virtual-body` without touching the scroll container.
    * This preserves momentum/inertia scrolling because the `.grid-table` element
    * is never destroyed.
    */
-  private renderVirtualBody(): void {
+  /** @internal */
+  renderVirtualBody(): void {
     const snapshot = this.snapshot;
     if (!snapshot?.pipeline.virtualizationEnabled) {
       this.render();
@@ -1393,12 +867,12 @@ export class UiGridStandaloneElement extends HTMLElement {
       this.dataFrame = null;
     }
 
-    const stickyChromeHeight = this.measuredHeaderStickyHeight + this.measuredFilterStickyHeight;
-    const viewportHeight = snapshot.options.viewportHeight ?? 560;
-    const bodyViewportHeight = Math.max(snapshot.rowSize, viewportHeight - stickyChromeHeight);
-    const bodyScrollTop = Math.max(0, this.scrollPosition - stickyChromeHeight);
+    const bodyViewport = root?.querySelector<HTMLElement>('.grid-body-viewport');
+    const bodyViewportHeight = bodyViewport
+      ? Math.max(snapshot.rowSize, bodyViewport.clientHeight)
+      : Math.max(snapshot.rowSize, (snapshot.options.minRowsToShow ?? 10) * snapshot.rowSize);
     const overscan = 4;
-    const startIndex = Math.max(0, Math.floor(bodyScrollTop / snapshot.rowSize) - overscan);
+    const startIndex = Math.max(0, Math.floor(this.scrollPosition / snapshot.rowSize) - overscan);
     this.lastVirtualStartIndex = startIndex;
     const visibleCount = Math.ceil(bodyViewportHeight / snapshot.rowSize) + overscan * 2;
     const itemsToRender = snapshot.pipeline.displayItems.slice(
@@ -1411,9 +885,16 @@ export class UiGridStandaloneElement extends HTMLElement {
     virtualBody.innerHTML = itemsToRender
       .map((item, index) => this.renderDisplayItem(item, startIndex + index))
       .join('');
+    // The body fingerprint now reflects the freshly-rendered slice so the
+    // next full render() can take the fast per-cell patch path.
+    this.lastItemsFingerprint = this.fingerprintItems(itemsToRender);
+    this.lastVirtualOffset = virtualOffset;
+
+    this.frameworkSlots.flush();
   }
 
-  private render(): void {
+  /** @internal */
+  render(): void {
     if (this.skipNextRender) {
       return;
     }
@@ -1429,17 +910,166 @@ export class UiGridStandaloneElement extends HTMLElement {
     }
     const root = this.ensureShadowRoot();
     const snapshot = this.snapshot;
-    const previousGridTable = root.querySelector<HTMLElement>('.grid-table');
-    if (previousGridTable && !this.suppressScrollEvent) {
-      this.scrollPosition = previousGridTable.scrollTop;
-      this.horizontalScrollPosition = previousGridTable.scrollLeft;
+    const previousViewport = root.querySelector<HTMLElement>('.grid-body-viewport');
+    if (previousViewport && !this.suppressScrollEvent) {
+      this.scrollPosition = previousViewport.scrollTop;
+      this.horizontalScrollPosition = previousViewport.scrollLeft;
     }
 
     if (!snapshot) {
-      root.innerHTML = `<style>${GRID_CORE_CSS}</style><section class="grid-shell ui-grid-shell"><div class="empty-state ui-grid-no-row-overlay"><strong>No grid options provided.</strong></div></section>`;
+      this.lastStructureKey = null;
+      this.lastItemsFingerprint = null;
+      emptyTemplate({ message: 'No grid options provided.' }).connect(root);
       return;
     }
 
+    const plan = this.buildRenderPlan(snapshot);
+
+    // The shadow-DOM structure is only safe to patch when the set of sub-regions,
+    // the visible column identity/order, and the pin/virt/filter/pagination
+    // toggles are unchanged. Otherwise the existing nodes don't line up with the
+    // new snapshot — fall back to a full re-mount.
+    const canPatch =
+      this.lastStructureKey !== null &&
+      this.lastStructureKey === plan.structureKey &&
+      root.querySelector('.grid-frame') !== null;
+
+    if (canPatch) {
+      this.renderPatch(plan, root);
+    } else {
+      this.renderFull(plan, root);
+    }
+    this.lastStructureKey = plan.structureKey;
+
+    const bodyViewport = root.querySelector<HTMLElement>('.grid-body-viewport');
+    if (bodyViewport && (this.scrollPosition > 0 || this.horizontalScrollPosition > 0)) {
+      this.suppressScrollEvent = true;
+      if (this.scrollPosition > 0) {
+        bodyViewport.scrollTop = this.scrollPosition;
+      }
+      if (this.horizontalScrollPosition > 0) {
+        bodyViewport.scrollLeft = this.horizontalScrollPosition;
+      }
+      // Keep the header/filter strips in sync on the first paint too.
+      this.syncHeaderHorizontalScroll(this.horizontalScrollPosition);
+      requestAnimationFrame(() => {
+        this.suppressScrollEvent = false;
+      });
+    }
+
+    const headerGrid = root.querySelector<HTMLElement>('.header-grid');
+    const filterGrid = root.querySelector<HTMLElement>('.filter-grid');
+    const nextHeaderStickyHeight = headerGrid?.offsetHeight ?? 0;
+    const nextFilterStickyHeight = filterGrid?.offsetHeight ?? 0;
+    const stickyHeightsChanged =
+      nextHeaderStickyHeight !== this.measuredHeaderStickyHeight ||
+      nextFilterStickyHeight !== this.measuredFilterStickyHeight;
+
+    this.measuredHeaderStickyHeight = nextHeaderStickyHeight;
+    this.measuredFilterStickyHeight = nextFilterStickyHeight;
+
+    if (stickyHeightsChanged && !this.stickyHeightRelayoutQueued) {
+      this.stickyHeightRelayoutQueued = true;
+      requestAnimationFrame(() => {
+        this.stickyHeightRelayoutQueued = false;
+        if (!this.snapshot) {
+          return;
+        }
+        this.render();
+      });
+    }
+
+    this.autoAdjustHeight(snapshot);
+  }
+
+  /** @internal */
+  private inAutoAdjust = false;
+  private lastAutoHeight = 0;
+
+  private autoAdjustHeight(snapshot: GridControllerSnapshot): void {
+    if (this.inAutoAdjust) return;
+    const options = snapshot.options;
+    if (options.enableMinHeightCheck === false) return;
+
+    const rowHeight = snapshot.rowSize;
+    const minRows = options.minRowsToShow ?? 10;
+    const headerHeight = this.measuredHeaderStickyHeight || options.headerRowHeight || 50;
+    const filterHeight = this.measuredFilterStickyHeight;
+    const paginationHeight = this.measuredPaginationHeight();
+    const minHeight = headerHeight + filterHeight + paginationHeight + (minRows * rowHeight);
+
+    if (this.clientHeight < minHeight || (paginationHeight > 0 && this.lastAutoHeight !== minHeight)) {
+      this.lastAutoHeight = minHeight;
+      this.style.height = `${minHeight}px`;
+      this.inAutoAdjust = true;
+      this.render();
+      this.inAutoAdjust = false;
+    }
+  }
+
+  measuredPaginationHeight(): number {
+    const paginationEl = this.shadowRoot?.querySelector<HTMLElement>('ui-grid-pagination');
+    if (!paginationEl) return 0;
+    return paginationEl.offsetHeight || 44;
+  }
+
+  /** @internal */
+  setupAutoResize(): void {
+    if (this.autoResizeObserver) return;
+    if (typeof ResizeObserver === 'undefined') return;
+
+    this.autoResizeObserver = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+
+      const newWidth = entry.contentRect.width;
+      if (this.controller && newWidth > 0) {
+        this.controller.setViewportWidth(newWidth);
+      }
+
+      if (this.autoResizeDebounceHandle !== null) {
+        cancelAnimationFrame(this.autoResizeDebounceHandle);
+      }
+      this.autoResizeDebounceHandle = requestAnimationFrame(() => {
+        this.autoResizeDebounceHandle = null;
+        if (!this.snapshot) return;
+        this.render();
+      });
+    });
+
+    this.autoResizeObserver.observe(this);
+  }
+
+  /** @internal */
+  teardownAutoResize(): void {
+    if (this.autoResizeObserver) {
+      this.autoResizeObserver.disconnect();
+      this.autoResizeObserver = null;
+    }
+    if (this.autoResizeDebounceHandle !== null) {
+      cancelAnimationFrame(this.autoResizeDebounceHandle);
+      this.autoResizeDebounceHandle = null;
+    }
+  }
+
+  private buildRenderPlan(snapshot: GridControllerSnapshot): {
+    snapshot: GridControllerSnapshot;
+    options: GridOptions;
+    labels: GridControllerSnapshot['labels'];
+    templateColumns: string;
+    sortEnabled: boolean;
+    filterEnabled: boolean;
+    groupingEnabled: boolean;
+    pinningEnabled: boolean;
+    paginationEnabled: boolean;
+    showPagination: boolean;
+    virtualizationEnabled: boolean;
+    itemsToRender: readonly DisplayItem[];
+    startIndex: number;
+    virtualOffset: number;
+    totalVirtualHeight: number;
+    structureKey: string;
+  } {
     const controller = this.controller!;
     const options = snapshot.options;
     const labels = snapshot.labels;
@@ -1451,19 +1081,22 @@ export class UiGridStandaloneElement extends HTMLElement {
     const paginationEnabled = controller.isPaginationEnabled();
     const showPagination = controller.shouldShowPaginationControls();
     const virtualizationEnabled = snapshot.pipeline.virtualizationEnabled;
-    const viewportHeight = options.viewportHeight ?? 560;
-    const headerStickyTop = this.measuredHeaderStickyHeight || options.headerRowHeight || 50;
-    const stickyChromeHeight = this.measuredHeaderStickyHeight + this.measuredFilterStickyHeight;
-    const bodyViewportHeight = Math.max(snapshot.rowSize, viewportHeight - stickyChromeHeight);
+    // Measure the body viewport from the DOM when available; on first paint
+    // fall back to a reasonable default so virtualisation has something to
+    // slice against until the element is measured.
+    const bodyViewport = this.shadowRoot?.querySelector<HTMLElement>('.grid-body-viewport');
+    const bodyViewportHeight = bodyViewport
+      ? Math.max(snapshot.rowSize, bodyViewport.clientHeight)
+      : Math.max(snapshot.rowSize, (options.minRowsToShow ?? 10) * snapshot.rowSize);
+
     let startIndex = 0;
-    let itemsToRender = snapshot.pipeline.displayItems;
+    let itemsToRender: readonly DisplayItem[] = snapshot.pipeline.displayItems;
     let virtualOffset = 0;
     const totalVirtualHeight = snapshot.pipeline.displayItems.length * snapshot.rowSize;
 
     if (virtualizationEnabled) {
-      const bodyScrollTop = Math.max(0, this.scrollPosition - stickyChromeHeight);
       const overscan = 4;
-      startIndex = Math.max(0, Math.floor(bodyScrollTop / snapshot.rowSize) - overscan);
+      startIndex = Math.max(0, Math.floor(this.scrollPosition / snapshot.rowSize) - overscan);
       this.lastVirtualStartIndex = startIndex;
       const visibleCount = Math.ceil(bodyViewportHeight / snapshot.rowSize) + overscan * 2;
       itemsToRender = snapshot.pipeline.displayItems.slice(
@@ -1475,6 +1108,65 @@ export class UiGridStandaloneElement extends HTMLElement {
       this.lastVirtualStartIndex = -1;
     }
 
+    // Structure key: only the outer-shell layout. Things that swap the body
+    // container (virtualization flip, empty state, viewport scroll) or the
+    // pagination element appearance are handled *inside* the patch path so a
+    // filter keystroke that crosses the virtualization threshold doesn't
+    // tear down the focused filter input.
+    const columnFingerprint = snapshot.visibleColumns
+      .map(
+        (c) =>
+          `${c.name}:${controller.isPinned(c) ? 'p' : ''}${controller.isPinnedLeftLast(c) ? 'L' : ''}${controller.isPinnedRightFirst(c) ? 'R' : ''}`,
+      )
+      .join('|');
+    const structureKey = [
+      columnFingerprint,
+      filterEnabled ? '1' : '0',
+      paginationEnabled ? '1' : '0',
+    ].join('#');
+
+    return {
+      snapshot,
+      options,
+      labels,
+      templateColumns,
+      sortEnabled,
+      filterEnabled,
+      groupingEnabled,
+      pinningEnabled,
+      paginationEnabled,
+      showPagination,
+      virtualizationEnabled,
+      itemsToRender,
+      startIndex,
+      virtualOffset,
+      totalVirtualHeight,
+      structureKey,
+    };
+  }
+
+  private renderFull(
+    plan: ReturnType<UiGridStandaloneElement['buildRenderPlan']>,
+    _root: ShadowRoot,
+  ): void {
+    const {
+      snapshot,
+      options,
+      labels,
+      templateColumns,
+      sortEnabled,
+      filterEnabled,
+      groupingEnabled,
+      pinningEnabled,
+      paginationEnabled,
+      showPagination,
+      virtualizationEnabled,
+      itemsToRender,
+      startIndex,
+      virtualOffset,
+      totalVirtualHeight,
+    } = plan;
+
     const slotRegistry = this.renderSlotRegistry(snapshot.visibleColumns);
     const header = snapshot.visibleColumns
       .map((column) =>
@@ -1483,9 +1175,10 @@ export class UiGridStandaloneElement extends HTMLElement {
       .join('');
 
     const filterRow = filterEnabled
-      ? `<div class="filter-grid ui-grid-header" style="grid-template-columns:${templateColumns}">${snapshot.visibleColumns
-          .map((column) => this.renderFilterCell(column))
-          .join('')}</div>`
+      ? filterRowMarkup(
+          templateColumns,
+          snapshot.visibleColumns.map((column) => this.renderFilterCell(column)).join(''),
+        )
       : '';
 
     const bodyContent = itemsToRender
@@ -1495,51 +1188,103 @@ export class UiGridStandaloneElement extends HTMLElement {
     const body =
       snapshot.pipeline.displayItems.length > 0
         ? virtualizationEnabled
-          ? `<div class="grid-virtual-spacer" style="height:${totalVirtualHeight}px"><div class="body-grid ui-grid-canvas grid-virtual-body" style="grid-template-columns:${templateColumns};top:${virtualOffset}px">${bodyContent}</div></div>`
-          : `<div class="body-grid ui-grid-canvas" style="grid-template-columns:${templateColumns}">${bodyContent}</div>`
-        : `<div class="empty-state ui-grid-no-row-overlay"><strong>${escapeHtml(options.emptyMessage ?? labels.emptyHeading)}</strong><p>${escapeHtml(labels.emptyDescription)}</p></div>`;
+          ? bodyVirtualMarkup(templateColumns, totalVirtualHeight, virtualOffset, bodyContent)
+          : bodyStaticMarkup(templateColumns, bodyContent)
+        : this.renderEmptyState(
+            options.emptyMessage ?? labels.emptyHeading,
+            labels.emptyDescription,
+          );
 
     const pagination = paginationEnabled && showPagination ? this.renderPagination(snapshot) : '';
-    const hasViewportScroll = virtualizationEnabled || options.viewportHeight !== undefined;
-    const gridTableStyle = `${hasViewportScroll ? `height:${viewportHeight}px;overflow-y:auto;` : ''}--ui-grid-header-sticky-top:${headerStickyTop}px;`;
 
-    root.innerHTML = `<style>${GRID_CORE_CSS}</style>${slotRegistry}<section class="grid-frame ui-grid" role="grid" aria-label="${escapeHtml(options.title ?? 'Data grid')}"><div class="grid-table ui-grid-contents-wrapper" style="${gridTableStyle}"><div class="header-grid ui-grid-header ui-grid-header-canvas" style="grid-template-columns:${templateColumns}">${header}</div>${filterRow}${body}</div>${pagination}</section>`;
+    this.gridTitle = escapeHtml(options.title ?? 'Data grid');
+    const stickyTop = this.measuredHeaderStickyHeight || options.headerRowHeight || 50;
+    const paginationHeight = this.measuredPaginationHeight();
+    const tableHeight = this.clientHeight || ((options.minRowsToShow ?? 10) * snapshot.rowSize + (this.measuredHeaderStickyHeight || options.headerRowHeight || 50) + this.measuredFilterStickyHeight + paginationHeight);
+    this.gridTableStyle = `--ui-grid-header-sticky-top:${stickyTop}px;height:${tableHeight}px;`;
+    this.bodyViewportStyle = '';
+    this.templateColumns = templateColumns;
+    this.slotRegistry = slotRegistry;
+    this.headerContent = header;
+    this.filterRowContent = filterRow;
+    this.bodyContent = body;
+    this.paginationContent = pagination;
+
+    gridShellTemplate(this).connect();
+
+    // Flush framework-rendered slot deltas — dispatches cellSlotsChanged /
+    // expandableRowSlotsChanged / groupRowSlotsChanged / headerSlotsChanged /
+    // filterSlotsChanged / emptyStateSlotChanged with the adds + removes
+    // relative to the previous render.
+    this.frameworkSlots.flush();
+
+    // After a full mount, the new DOM exactly matches the current item set —
+    // seed the fingerprint so the next render can take the fast patch path.
+    this.lastItemsFingerprint = this.fingerprintItems(plan.itemsToRender);
+    this.lastVirtualOffset = plan.virtualOffset;
+    this.lastTotalVirtualHeight = plan.totalVirtualHeight;
+  }
+
+  private renderPatch(
+    plan: ReturnType<UiGridStandaloneElement['buildRenderPlan']>,
+    root: ShadowRoot,
+  ): void {
+    renderPatch(this, plan, root);
+  }
 
-    const gridTable = root.querySelector<HTMLElement>('.grid-table');
-    if (gridTable && (this.scrollPosition > 0 || this.horizontalScrollPosition > 0)) {
-      this.suppressScrollEvent = true;
-      if (this.scrollPosition > 0) {
-        gridTable.scrollTop = this.scrollPosition;
-      }
-      if (this.horizontalScrollPosition > 0) {
-        gridTable.scrollLeft = this.horizontalScrollPosition;
-      }
-      requestAnimationFrame(() => {
-        this.suppressScrollEvent = false;
-      });
-    }
+  private reconcileBodyRoot(
+    root: ShadowRoot,
+    kind: 'empty' | 'virtual' | 'static',
+    options: GridOptions,
+    labels: GridControllerSnapshot['labels'],
+    templateColumns: string,
+    virtualOffset: number,
+    totalVirtualHeight: number,
+  ): HTMLElement | null {
+    return reconcileBodyRoot(this, root, kind, options, labels, templateColumns, virtualOffset, totalVirtualHeight);
+  }
+
+  private reconcilePagination(
+    root: ShadowRoot,
+    snapshot: GridControllerSnapshot,
+    shouldShow: boolean,
+  ): void {
+    reconcilePagination(this, root, snapshot, shouldShow);
+  }
 
-    const headerGrid = root.querySelector<HTMLElement>('.header-grid');
-    const filterGrid = root.querySelector<HTMLElement>('.filter-grid');
-    const nextHeaderStickyHeight = headerGrid?.offsetHeight ?? 0;
-    const nextFilterStickyHeight = filterGrid?.offsetHeight ?? 0;
-    const stickyHeightsChanged =
-      nextHeaderStickyHeight !== this.measuredHeaderStickyHeight ||
-      nextFilterStickyHeight !== this.measuredFilterStickyHeight;
+  private patchFilterCells(filterGrid: HTMLElement, snapshot: GridControllerSnapshot): void {
+    patchFilterCells(this, filterGrid, snapshot);
+  }
 
-    this.measuredHeaderStickyHeight = nextHeaderStickyHeight;
-    this.measuredFilterStickyHeight = nextFilterStickyHeight;
+  private fingerprintItems(items: readonly DisplayItem[]): string {
+    return fingerprintItems(items);
+  }
 
-    if (stickyHeightsChanged && !this.stickyHeightRelayoutQueued) {
-      this.stickyHeightRelayoutQueued = true;
-      requestAnimationFrame(() => {
-        this.stickyHeightRelayoutQueued = false;
-        if (!this.snapshot) {
-          return;
-        }
-        this.render();
-      });
-    }
+  private patchExistingRows(
+    bodyContainer: HTMLElement,
+    snapshot: GridControllerSnapshot,
+    itemsToRender: readonly DisplayItem[],
+    startIndex: number,
+  ): void {
+    patchExistingRows(this, bodyContainer, snapshot, itemsToRender, startIndex);
+  }
+
+  private patchGroupRow(el: HTMLElement, group: GroupItem): void {
+    patchGroupRow(this, el, group);
+  }
+
+  private patchBodyCell(
+    cell: HTMLElement,
+    row: GridRow,
+    column: GridColumnDef,
+    displayIndex: number,
+    templateMarkupMap: Map<string, string | null>,
+  ): void {
+    patchBodyCell(this, cell, row, column, displayIndex, templateMarkupMap);
+  }
+
+  private patchPagination(paginationEl: HTMLElement, snapshot: GridControllerSnapshot): void {
+    patchPagination(this, paginationEl, snapshot);
   }
 
   private renderHeaderCell(
@@ -1549,177 +1294,102 @@ export class UiGridStandaloneElement extends HTMLElement {
     pinningEnabled: boolean,
     options: GridOptions,
   ): string {
-    const controller = this.controller!;
-    const sortDirection = controller.getSortDirection(column);
-    const sortLabel = controller.sortButtonLabel(column);
-    const groupingLabel = controller.groupingButtonLabel(column);
-    const canSort = sortEnabled && controller.isColumnSortable(column);
-    const canGroup = groupingEnabled && column.enableGrouping !== false;
-    const canPin = pinningEnabled && controller.isColumnPinnable(column);
-    const isPinned = controller.isPinned(column);
-    const pinOffset = isPinned ? controller.pinnedOffset(column) : null;
-    const isPinnedLeftLast = controller.isPinnedLeftLast(column);
-    const isPinnedRightFirst = controller.isPinnedRightFirst(column);
-    const isDragTarget = this.dropTargetColumnName === column.name;
-    const isDragging = this.draggedColumnName === column.name;
-    const classes = [
-      'header-cell',
-      sortDirection !== SORT_DIRECTIONS.none ? 'is-active' : '',
-      isPinned ? 'is-pinned' : '',
-      isPinnedLeftLast ? 'is-pinned-left-last' : '',
-      isPinnedRightFirst ? 'is-pinned-right-first' : '',
-      this.openPinMenuColumn === column.name ? 'is-pin-menu-open' : '',
-      isDragTarget ? 'is-drag-target' : '',
-      isDragging ? 'is-dragging' : '',
-    ]
-      .filter(Boolean)
-      .join(' ');
-
-    const stickyStyle = pinOffset ? `${pinOffset.side}:${pinOffset.offset};` : '';
-
-    const sortIconKey =
-      sortDirection === SORT_DIRECTIONS.asc
-        ? 'sortAsc'
-        : sortDirection === SORT_DIRECTIONS.desc
-          ? 'sortDesc'
-          : 'sortNone';
-
-    const draggable = canGridMoveColumns(options) ? 'draggable="true"' : '';
-    const pinLabel = isPinned
-      ? (this.snapshot?.labels.unpin ?? 'Unpin')
-      : (this.snapshot?.labels.pinColumn ?? 'Pin');
-    const canResize = controller.canResizeColumns();
-    const headerValue = escapeHtml(formatGridHeaderDisplayValue(buildGridHeaderContext(column)));
-    const resizerHtml = canResize
-      ? `<button type="button" class="column-resizer" data-action="resize" data-column="${escapeHtml(column.name)}" aria-label="Resize ${escapeHtml(headerValue)} column" title="Drag to resize, double-click to auto fit"></button>`
-      : '';
-
-    return `<div class="${classes}" data-column="${escapeHtml(column.name)}" ${draggable} style="${stickyStyle}"><span class="header-label">${headerValue}</span><span class="header-actions">${sortEnabled ? `<button type="button" class="header-action" data-action="sort" data-column="${escapeHtml(column.name)}" aria-label="${escapeHtml(sortLabel)}" ${canSort ? '' : 'disabled'}>${this.renderControlIcon(sortIconKey)}<span class="sr-only">${escapeHtml(sortLabel)}</span></button>` : ''}${groupingEnabled ? `<button type="button" class="chip-action${controller.isColumnGrouped(column) ? ' chip-action-active' : ''}" data-action="group" data-column="${escapeHtml(column.name)}" aria-label="${escapeHtml(groupingLabel)}" ${canGroup ? '' : 'disabled'}>${this.renderControlIcon('group')}<span class="sr-only">${escapeHtml(groupingLabel)}</span></button>` : ''}${canPin ? `<div class="pin-control${this.openPinMenuColumn === column.name ? ' pin-control-open' : ''}"><button type="button" class="chip-action pin-trigger${isPinned ? ' chip-action-active' : ''}" data-action="pin-trigger" data-column="${escapeHtml(column.name)}" aria-label="${escapeHtml(pinLabel)}">${this.renderControlIcon('pin')}<span class="sr-only">${escapeHtml(pinLabel)}</span></button><div class="pin-menu" role="menu" aria-label="${escapeHtml(pinLabel)}"><button type="button" class="pin-menu-action" data-action="pin-left" data-column="${escapeHtml(column.name)}" aria-label="${escapeHtml(this.snapshot?.labels.pinLeft ?? 'Pin left')}">${this.renderIconWithClass('control-icon', 'pinLeft')}<span class="sr-only">${escapeHtml(this.snapshot?.labels.pinLeft ?? 'Pin left')}</span></button><button type="button" class="pin-menu-action" data-action="pin-right" data-column="${escapeHtml(column.name)}" aria-label="${escapeHtml(this.snapshot?.labels.pinRight ?? 'Pin right')}">${this.renderIconWithClass('control-icon', 'pinRight')}<span class="sr-only">${escapeHtml(this.snapshot?.labels.pinRight ?? 'Pin right')}</span></button></div></div>` : ''}</span>${resizerHtml}</div>`;
+    return renderHeaderCell(this, column, sortEnabled, groupingEnabled, pinningEnabled, options);
   }
 
   private renderFilterCell(column: GridColumnDef): string {
-    const value = this.snapshot?.activeFilters[column.name] ?? '';
-    const controller = this.controller!;
-    const canFilter = controller.isColumnFilterable(column);
-    const pinOffset = controller.isPinned(column) ? controller.pinnedOffset(column) : null;
-    const classes = [
-      'filter-cell',
-      controller.isPinned(column) ? 'is-pinned' : '',
-      controller.isPinnedLeftLast(column) ? 'is-pinned-left-last' : '',
-      controller.isPinnedRightFirst(column) ? 'is-pinned-right-first' : '',
-    ]
-      .filter(Boolean)
-      .join(' ');
-    const stickyStyle = pinOffset ? `${pinOffset.side}:${pinOffset.offset};` : '';
-    return `<label class="${classes}" style="${stickyStyle}"><input class="ui-grid-filter-input" data-role="filter" data-column="${escapeHtml(column.name)}" placeholder="${escapeHtml(controller.filterPlaceholder(column))}" value="${escapeHtml(value)}" ${canFilter ? '' : 'disabled'}></label>`;
+    return renderFilterCell(this, column);
   }
 
-  private measureAutoColumnWidth(columnName: string): number {
-    const root = this.shadowRoot;
-    if (root == null) return 176;
-    const escaped = CSS.escape ? CSS.escape(columnName) : columnName.replace(/([\\".#:[\](){}+~> ])/g, '\\$1');
-    const selectors = [
-      `.header-cell[data-column="${escaped}"]`,
-      `.filter-cell[data-column="${escaped}"]`,
-      `.body-cell[data-column="${escaped}"] .cell-shell`,
-    ];
-    let maxWidth = 0;
-    for (const selector of selectors) {
-      for (const el of root.querySelectorAll<HTMLElement>(selector)) {
-        maxWidth = Math.max(maxWidth, el.scrollWidth);
-      }
-    }
-    return maxWidth + 12;
+  /**
+   * Commit the in-flight edit, then move keyboard focus relative to the
+   * committed cell. Splits commit + focus across two paint frames: commit
+   * runs synchronously (editor unmounts, cell re-renders with the new value),
+   * then focus moves to the adjacent cell. Scheduling the focus in a
+   * microtask avoids racing the blur handler's re-entry guard and ensures
+   * the destination cell is fully reattached in the DOM.
+   *
+   * If the source cell was being edited, the destination cell enters edit
+   * mode too (provided the destination column is editable). This keeps
+   * Tab/Enter nav inside an edit session continuous — you keep editing as
+   * you move. Arrow nav outside an edit session does NOT auto-enter edit.
+   */
+  private commitAndMove(
+    fromRowId: string | null,
+    fromColumnName: string | null,
+    direction: 'left' | 'right' | 'up' | 'down',
+  ): void {
+    commitAndMove(this, fromRowId, fromColumnName, direction);
   }
 
-  private renderDisplayItem(item: DisplayItem, displayIndex: number): string {
-    if (!this.snapshot || !this.controller) {
-      return '';
-    }
+  private moveGridFocus(
+    direction: GridMoveDirection,
+    rowId: string | null,
+    columnName: string | null,
+    opts: { resumeEdit?: boolean } = {},
+  ): void {
+    moveGridFocus(this, direction, rowId, columnName, opts);
+  }
 
-    if (item.kind === 'group') {
-      const group = asGroupItem(item);
-      const iconKey = group.collapsed ? 'groupCollapsed' : 'groupExpanded';
-      const disclosureLabel = this.controller.groupDisclosureLabel(group);
-      return `<button type="button" class="group-row ui-grid-row ui-grid-group-row" data-action="toggle-group" data-group="${escapeHtml(group.id)}" data-collapsed="${group.collapsed ? 'true' : 'false'}" style="grid-column: 1 / -1; padding-inline-start:${group.depth * 20 + 10}px">${this.renderIconWithClass('toggle-icon group-disclosure-icon', iconKey)}<span class="sr-only">${escapeHtml(disclosureLabel)}</span><strong>${escapeHtml(group.field)}: ${escapeHtml(group.label)}</strong><span>${group.count} ${escapeHtml(this.snapshot.labels.groupRowsSuffix)}</span></button>`;
-    }
+  private scrollFocusedRowIntoView(rowId: string): void {
+    scrollFocusedRowIntoView(this, rowId);
+  }
 
-    if (item.kind === 'expandable') {
-      const row = (item as DisplayItem & { row: GridRow }).row;
-      return `<div class="expandable-row ui-grid-row ui-grid-expandable-row" style="grid-column:1 / -1">${this.renderExpandableTemplate(row)}</div>`;
-    }
+  private handleRowSelectionClick(rowId: string, columnName: string, event: Event): void {
+    handleRowSelectionClick(this, rowId, columnName, event);
+  }
 
-    if (!isRowItem(item)) {
-      return '';
-    }
+  private handleRowHeaderCheckboxClick(rowId: string, event: Event): void {
+    handleRowHeaderCheckboxClick(this, rowId, event);
+  }
 
-    return this.snapshot.visibleColumns
-      .map((column) => this.renderBodyCell(item.row, column, displayIndex))
-      .join('');
+  private matchesKeyOverride(
+    override: {
+      keyCode?: number;
+      key?: string;
+      shiftKey?: boolean;
+      ctrlKey?: boolean;
+      altKey?: boolean;
+      metaKey?: boolean;
+    },
+    event: KeyboardEvent,
+  ): boolean {
+    return matchesKeyOverride(override, event);
   }
 
-  private renderBodyCell(row: GridRow, column: GridColumnDef, displayIndex: number): string {
-    if (!this.snapshot || !this.controller) {
-      return '';
-    }
+  private applyFocusedCellClass(
+    previous: { rowId: string; columnName: string } | null,
+    next: { rowId: string; columnName: string } | null,
+  ): void {
+    applyFocusedCellClass(this, previous, next);
+  }
 
-    const controller = this.controller;
-    const rowId = row.id;
-    const columnName = column.name;
-    const editing = controller.isEditingCell(rowId, columnName);
-    const pinOffset = controller.isPinned(column) ? controller.pinnedOffset(column) : null;
-    const treeToggle = controller.showTreeToggle(row, column)
-      ? `<button type="button" class="row-toggle" data-action="toggle-tree" data-row="${escapeHtml(rowId)}" aria-label="${escapeHtml(controller.treeToggleLabel(row))}">${this.renderIconWithClass('toggle-icon', controller.isTreeRowExpanded(row) ? 'treeExpanded' : 'treeCollapsed')}<span class="sr-only">${escapeHtml(controller.treeToggleLabel(row))}</span></button>`
-      : '';
-    const expandToggle = controller.showExpandToggle(row, column)
-      ? `<button type="button" class="row-toggle row-toggle-expand" data-action="toggle-expand" data-row="${escapeHtml(rowId)}" aria-label="${escapeHtml(controller.expandToggleLabel(row))}">${this.renderIconWithClass('toggle-icon', row.expanded ? 'expandExpanded' : 'expandCollapsed')}<span class="sr-only">${escapeHtml(controller.expandToggleLabel(row))}</span></button>`
-      : '';
+  private focusCellElement(rowId: string | null, columnName: string | null): void {
+    focusCellElement(this, rowId, columnName);
+  }
 
-    const content = editing
-      ? `<input class="cell-editor" data-role="editor" data-row="${escapeHtml(rowId)}" data-column="${escapeHtml(columnName)}" type="${escapeHtml(controller.editorInputType(column))}" value="${escapeHtml(this.snapshot.editingValue)}">`
-      : this.renderCellTemplate(row, column, displayIndex);
-
-    const classes = [
-      'body-cell',
-      'ui-grid-cell',
-      displayIndex % 2 !== 0 ? 'body-cell-odd' : '',
-      column.align === 'center' ? 'align-center' : '',
-      column.align === 'end' ? 'align-end' : '',
-      controller.isPinned(column) ? 'is-pinned' : '',
-      controller.isPinnedLeftLast(column) ? 'is-pinned-left-last' : '',
-      controller.isPinnedRightFirst(column) ? 'is-pinned-right-first' : '',
-      this.focusedCell?.rowId === rowId && this.focusedCell.columnName === columnName
-        ? 'cell-focused'
-        : '',
-      editing ? 'cell-editing' : '',
-    ]
-      .filter(Boolean)
-      .join(' ');
-
-    const stickyStyle = pinOffset ? `${pinOffset.side}:${pinOffset.offset};` : '';
-    return `<div class="${classes}" tabindex="0" data-row="${escapeHtml(rowId)}" data-column="${escapeHtml(columnName)}" style="${stickyStyle}"><div class="cell-shell" style="padding-inline-start:${escapeHtml(controller.cellIndent(row, column))}">${treeToggle}${expandToggle}<div class="cell-content">${content}</div></div></div>`;
+  private measureAutoColumnWidth(columnName: string): number {
+    return measureAutoColumnWidth(this, columnName);
+  }
+
+  private renderDisplayItem(item: DisplayItem, displayIndex: number): string {
+    return renderDisplayItem(this, item, displayIndex);
+  }
+
+  private renderBodyCell(row: GridRow, column: GridColumnDef, displayIndex: number): string {
+    return renderBodyCell(this, row, column, displayIndex);
   }
 
   private renderPagination(snapshot: GridControllerSnapshot): string {
-    const pageSizes = snapshot.options.paginationPageSizes ?? [10, 25, 50, 100];
-    return `<footer class="pagination-bar ui-grid-pagination"><p>${snapshot.firstRowIndex + 1}-${snapshot.lastRowIndex + 1} of ${snapshot.pipeline.totalItems}</p><div class="pagination-controls"><button type="button" class="action action-secondary pagination-button" data-action="page-prev" aria-label="${escapeHtml(snapshot.labels.paginationPrevious)}" ${snapshot.currentPage <= 1 ? 'disabled' : ''}>${this.renderIconWithClass('pagination-icon', 'paginationPrev')}<span class="sr-only">${escapeHtml(snapshot.labels.paginationPrevious)}</span></button><span>${escapeHtml(snapshot.labels.paginationPage)} ${snapshot.currentPage} ${escapeHtml(snapshot.labels.paginationOf)} ${snapshot.totalPages}</span><button type="button" class="action action-secondary pagination-button" data-action="page-next" aria-label="${escapeHtml(snapshot.labels.paginationNext)}" ${snapshot.currentPage >= snapshot.totalPages ? 'disabled' : ''}>${this.renderIconWithClass('pagination-icon', 'paginationNext')}<span class="sr-only">${escapeHtml(snapshot.labels.paginationNext)}</span></button><label class="pagination-size"><span class="sr-only">${escapeHtml(snapshot.labels.paginationRows)}</span><select class="page-size" data-role="page-size">${pageSizes
-      .map(
-        (size) =>
-          `<option value="${size}" ${size === snapshot.pageSize ? 'selected' : ''}>${size}</option>`,
-      )
-      .join('')}</select></label></div></footer>`;
+    return renderPagination(this, snapshot);
   }
 
   private renderSlotRegistry(columns: readonly GridColumnDef[]): string {
-    const cellSlots = columns
-      .map((column) => `<slot name="${escapeHtml(this.cellSlotName(column))}"></slot>`)
-      .join('');
-    return `<div hidden class="slot-registry">${cellSlots}<slot name="expandable-row"></slot></div>`;
+    return renderSlotRegistry(columns);
   }
 
   private renderCellTemplate(row: GridRow, column: GridColumnDef, displayIndex: number): string {
-    const templateMarkup = this.getTemplateMarkup(this.cellSlotName(column));
-    return this.renderCellTemplateFromMarkup(row, column, displayIndex, templateMarkup);
+    return renderCellTemplate(this, row, column, displayIndex);
   }
 
   private renderCellTemplateFromMarkup(
@@ -1728,62 +1398,20 @@ export class UiGridStandaloneElement extends HTMLElement {
     displayIndex: number,
     templateMarkup: string | null,
   ): string {
-    if (!templateMarkup) {
-      return `<span class="cell-value">${escapeHtml(this.controller?.displayValue(row, column) ?? '')}</span>`;
-    }
-
-    const rawRow = row.entity as GridRecord;
-    const rawValue = getCellValue(rawRow, column);
-    const valueText = rawValue == null ? '' : String(rawValue);
-    return this.interpolateTemplate(templateMarkup, {
-      $implicit: rawValue,
-      value: rawValue,
-      valueText,
-      valueLower: valueText.toLowerCase(),
-      row: rawRow,
-      column,
-      rowIndex: this.rowIndexFor(row, displayIndex),
-    });
+    return renderCellTemplateFromMarkup(this, row, column, displayIndex, templateMarkup);
   }
 
   private renderExpandableTemplate(row: GridRow): string {
-    const templateMarkup = this.getTemplateMarkup('expandable-row');
-    if (!templateMarkup) {
-      return `<p>${escapeHtml(String(row.entity['name'] ?? row.id))}</p>`;
-    }
-
-    return this.interpolateTemplate(templateMarkup, {
-      $implicit: row.entity,
-      row: row.entity,
-      expanded: row.expanded,
-      rowIndex: this.rowIndexFor(row),
-    });
+    return renderExpandableTemplate(this, row);
   }
 
   private getTemplateMarkup(slotName: string): string | null {
-    const template = this.querySelector<HTMLTemplateElement>(`template[slot="${slotName}"]`);
-    return template?.innerHTML ?? null;
-  }
-
-  private interpolateTemplate(templateMarkup: string, context: Record<string, unknown>): string {
-    return templateMarkup.replace(/{{\s*([^}]+?)\s*}}/g, (_match, expression) => {
-      const value = this.resolveTemplateValue(context, String(expression).trim());
-      return escapeHtml(value);
-    });
+    return getTemplateMarkupFromLightDom(this, slotName);
   }
 
-  private resolveTemplateValue(context: Record<string, unknown>, expression: string): unknown {
-    const segments = expression.split('.').filter(Boolean);
-    let current: unknown = context;
-
-    for (const segment of segments) {
-      if (current == null || typeof current !== 'object') {
-        return '';
-      }
-      current = (current as Record<string, unknown>)[segment];
-    }
-
-    return current ?? '';
+  /** @internal Used by the render module to interpolate consumer templates. */
+  interpolateTemplate(templateMarkup: string, context: Record<string, unknown>): string {
+    return interpolateGridTemplate(templateMarkup, context, escapeHtml);
   }
 
   private rowIndexFor(row: GridRow, fallback = 0): number {
@@ -1813,7 +1441,9 @@ export class UiGridStandaloneElement extends HTMLElement {
     }
 
     for (let index = 0; index < previousSnapshot.visibleColumns.length; index += 1) {
-      if (previousSnapshot.visibleColumns[index]?.name !== nextSnapshot.visibleColumns[index]?.name) {
+      if (
+        previousSnapshot.visibleColumns[index]?.name !== nextSnapshot.visibleColumns[index]?.name
+      ) {
         return { mode: 'full', changedRowIds: null };
       }
     }
@@ -1871,12 +1501,12 @@ export class UiGridStandaloneElement extends HTMLElement {
       };
     }
 
-    const stickyChromeHeight = this.measuredHeaderStickyHeight + this.measuredFilterStickyHeight;
-    const viewportHeight = snapshot.options.viewportHeight ?? 560;
-    const bodyViewportHeight = Math.max(snapshot.rowSize, viewportHeight - stickyChromeHeight);
-    const bodyScrollTop = Math.max(0, this.scrollPosition - stickyChromeHeight);
+    const bodyViewport = this.shadowRoot?.querySelector<HTMLElement>('.grid-body-viewport');
+    const bodyViewportHeight = bodyViewport
+      ? Math.max(snapshot.rowSize, bodyViewport.clientHeight)
+      : Math.max(snapshot.rowSize, (snapshot.options.minRowsToShow ?? 10) * snapshot.rowSize);
     const overscan = 4;
-    const startIndex = Math.max(0, Math.floor(bodyScrollTop / snapshot.rowSize) - overscan);
+    const startIndex = Math.max(0, Math.floor(this.scrollPosition / snapshot.rowSize) - overscan);
     const visibleCount = Math.ceil(bodyViewportHeight / snapshot.rowSize) + overscan * 2;
 
     return {
@@ -1892,29 +1522,38 @@ export class UiGridStandaloneElement extends HTMLElement {
     return `cell-${column.name}`;
   }
 
-  private downloadCsv(): void {
-    if (!this.snapshot) {
+  private renderEmptyState(headingRaw: string, descriptionRaw: string): string {
+    return renderEmptyState(this, headingRaw, descriptionRaw);
+  }
+
+  /** @internal */
+  downloadCsv(
+    rowType: 'all' | 'visible' | 'selected' = 'visible',
+    colType: 'all' | 'visible' = 'visible',
+  ): void {
+    if (!this.controller) {
       return;
     }
-
-    const csv = exportCsvRows(this.snapshot.visibleColumns, this.snapshot.pipeline.visibleRows);
-    const filename = sanitizeDownloadFilename(`${this.snapshot.options.id}.csv`);
-    downloadGridCsvFile(csv, filename);
+    this.controller.gridApi.exporter.csvExport(rowType, colType);
   }
 
   private renderControlIcon(key: UiGridControlIconKey): string {
-    return this.renderIconWithClass('control-icon', key);
+    return this.icons.renderControlIcon(key);
   }
 
   private renderIconWithClass(svgClass: string, key: UiGridControlIconKey): string {
-    const icon = this.iconOverrides[key] ?? DEFAULT_ICONS[key];
-    const viewBox = escapeHtml(icon.viewBox ?? '0 0 24 24');
-    const path = escapeHtml(icon.path);
-    return `<svg class="${svgClass}" viewBox="${viewBox}" aria-hidden="true" focusable="false"><path d="${path}"></path></svg>`;
+    return this.icons.renderIconWithClass(svgClass, key);
   }
 }
 
 export async function defineStandaloneUiGridElement(tagName = 'ui-grid-element'): Promise<void> {
+  UIGridFilterCell.define();
+  UIGridGroupRow.define();
+  UIGridPagination.define();
+  UIGridBodyCell.define();
+  UIGridHeaderCell.define();
+  UIGridTemplate.define();
+  UIGridCellEditor.define();
   if (!customElements.get(tagName)) {
     customElements.define(tagName, UiGridStandaloneElement);
   }