@ornery/ui-grid-vanilla 0.1.7 → 0.1.8-hotfix

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

@@ -1,9 +1,11 @@
 import {
   GRID_CORE_CSS,
   SORT_DIRECTIONS,
+  buildGridHeaderContext,
   canGridMoveColumns,
   downloadGridCsvFile,
   exportCsvRows,
+  formatGridHeaderDisplayValue,
   getCellValue,
   sanitizeDownloadFilename,
   type DisplayItem,
@@ -42,6 +44,12 @@ export type VanillaUiGridElement = HTMLElement & {
   options: GridOptions;
   getState(): GridSaveState | null;
   setState(state: Partial<GridSaveState>): void;
+  /**
+   * Fast-path data update: patches only visible cell content in the existing
+   * shadow DOM. Does NOT rebuild the scroll container or header, so scrolling
+   * remains completely smooth while data ticks in the background.
+   */
+  setData(rows: GridRecord[]): void;
 };
 
 export type UiGridControlIconKey =
@@ -95,6 +103,8 @@ export class UiGridStandaloneElement extends HTMLElement {
   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;
@@ -109,6 +119,53 @@ export class UiGridStandaloneElement extends HTMLElement {
   private measuredFilterStickyHeight = 0;
   private stickyHeightRelayoutQueued = false;
   private benchmarkAverage = '—';
+  private skipNextRender = false;
+  private dataFrame: number | null = null;
+
+  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',
+    ];
+  }
 
   get options(): GridOptions {
     return (
@@ -126,6 +183,197 @@ export class UiGridStandaloneElement extends HTMLElement {
     this.ensureController(this.buildEffectiveOptions(this.activeOptions));
   }
 
+  attributeChangedCallback(
+    _name: string,
+    _oldValue: string | null,
+    _newValue: string | null,
+  ): void {
+    // Debounce multiple rapid attribute changes via microtask.
+    if (!this.attributeSyncScheduled) {
+      this.attributeSyncScheduled = true;
+      queueMicrotask(() => {
+        this.attributeSyncScheduled = false;
+        this.syncAttributesToOptions();
+      });
+    }
+  }
+
+  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 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;
+
+    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.
+    if (this.activeOptions) {
+      this.ensureController(this.buildEffectiveOptions(this.activeOptions));
+    }
+  }
+
+  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;
+    }
+  }
+
   get controlIcons(): UiGridIconOverrides {
     return this.iconOverrides;
   }
@@ -135,6 +383,308 @@ export class UiGridStandaloneElement extends HTMLElement {
     this.render();
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Individual property accessors (mirrors of HTML attributes)
+  // ─────────────────────────────────────────────────────────────────
+
+  get gridId(): string {
+    return this.options.id ?? '';
+  }
+  set gridId(value: string) {
+    this.activeOptions = { ...this.activeOptions, id: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  // @ts-ignore: Intentional override of HTMLElement.title
+  get title(): string {
+    return this.options.title ?? '';
+  }
+  // @ts-ignore: Intentional override of HTMLElement.title
+  set title(value: string) {
+    this.activeOptions = { ...this.activeOptions, title: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get rowHeight(): number {
+    return this.options.rowHeight ?? 40;
+  }
+  set rowHeight(value: number) {
+    this.activeOptions = { ...this.activeOptions, rowHeight: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get headerRowHeight(): number {
+    return this.options.headerRowHeight ?? 50;
+  }
+  set headerRowHeight(value: number) {
+    this.activeOptions = { ...this.activeOptions, headerRowHeight: value } as any;
+    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;
+  }
+  set paginationPageSize(value: number) {
+    this.activeOptions = { ...this.activeOptions, paginationPageSize: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get paginationCurrentPage(): number {
+    return this.options.paginationCurrentPage ?? 1;
+  }
+  set paginationCurrentPage(value: number) {
+    this.activeOptions = { ...this.activeOptions, paginationCurrentPage: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get totalItems(): number | undefined {
+    return this.options.totalItems;
+  }
+  set totalItems(value: number | undefined) {
+    this.activeOptions = { ...this.activeOptions, totalItems: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get virtualizationThreshold(): number {
+    return this.options.virtualizationThreshold ?? 40;
+  }
+  set virtualizationThreshold(value: number) {
+    this.activeOptions = { ...this.activeOptions, virtualizationThreshold: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get treeChildrenField(): string {
+    return this.options.treeChildrenField ?? 'children';
+  }
+  set treeChildrenField(value: string) {
+    this.activeOptions = { ...this.activeOptions, treeChildrenField: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get treeIndent(): number {
+    return this.options.treeIndent ?? 20;
+  }
+  set treeIndent(value: number) {
+    this.activeOptions = { ...this.activeOptions, treeIndent: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get expandableRowHeight(): number {
+    return this.options.expandableRowHeight ?? 150;
+  }
+  set expandableRowHeight(value: number) {
+    this.activeOptions = { ...this.activeOptions, expandableRowHeight: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get expandableRowHeaderWidth(): number {
+    return this.options.expandableRowHeaderWidth ?? 40;
+  }
+  set expandableRowHeaderWidth(value: number) {
+    this.activeOptions = { ...this.activeOptions, expandableRowHeaderWidth: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get emptyMessage(): string {
+    return this.options.emptyMessage ?? 'No data available.';
+  }
+  set emptyMessage(value: string) {
+    this.activeOptions = { ...this.activeOptions, emptyMessage: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get infiniteScrollRowsFromEnd(): number {
+    return this.options.infiniteScrollRowsFromEnd ?? 10;
+  }
+  set infiniteScrollRowsFromEnd(value: number) {
+    this.activeOptions = { ...this.activeOptions, infiniteScrollRowsFromEnd: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get columnDefs(): readonly GridColumnDef[] {
+    return this.options.columnDefs;
+  }
+  set columnDefs(value: readonly GridColumnDef[]) {
+    this.activeOptions = { ...this.activeOptions, columnDefs: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get data(): readonly GridRecord[] {
+    return this.options.data;
+  }
+  set data(value: readonly GridRecord[]) {
+    this.activeOptions = { ...this.activeOptions, data: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableSorting(): boolean {
+    return this.options.enableSorting ?? true;
+  }
+  set enableSorting(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableSorting: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableFiltering(): boolean {
+    return this.options.enableFiltering ?? true;
+  }
+  set enableFiltering(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableFiltering: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableGrouping(): boolean {
+    return this.options.enableGrouping ?? true;
+  }
+  set enableGrouping(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableGrouping: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enablePinning(): boolean {
+    return this.options.enablePinning ?? true;
+  }
+  set enablePinning(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enablePinning: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableColumnMoving(): boolean {
+    return this.options.enableColumnMoving ?? true;
+  }
+  set enableColumnMoving(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableColumnMoving: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableCellEdit(): boolean {
+    return this.options.enableCellEdit ?? false;
+  }
+  set enableCellEdit(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableCellEdit: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableCellEditOnFocus(): boolean {
+    return this.options.enableCellEditOnFocus ?? false;
+  }
+  set enableCellEditOnFocus(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableCellEditOnFocus: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enablePagination(): boolean {
+    return this.options.enablePagination ?? false;
+  }
+  set enablePagination(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enablePagination: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enablePaginationControls(): boolean {
+    return this.options.enablePaginationControls ?? true;
+  }
+  set enablePaginationControls(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enablePaginationControls: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get useExternalPagination(): boolean {
+    return this.options.useExternalPagination ?? false;
+  }
+  set useExternalPagination(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, useExternalPagination: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableExpandable(): boolean {
+    return this.options.enableExpandable ?? false;
+  }
+  set enableExpandable(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableExpandable: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableTreeView(): boolean {
+    return this.options.enableTreeView ?? false;
+  }
+  set enableTreeView(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableTreeView: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get showTreeExpandNoChildren(): boolean {
+    return this.options.showTreeExpandNoChildren ?? false;
+  }
+  set showTreeExpandNoChildren(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, showTreeExpandNoChildren: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get treeRowHeaderAlwaysVisible(): boolean {
+    return this.options.treeRowHeaderAlwaysVisible ?? false;
+  }
+  set treeRowHeaderAlwaysVisible(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, treeRowHeaderAlwaysVisible: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableAutoResize(): boolean {
+    return this.options.enableAutoResize ?? false;
+  }
+  set enableAutoResize(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableAutoResize: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get enableVirtualization(): boolean {
+    return this.options.enableVirtualization ?? true;
+  }
+  set enableVirtualization(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, enableVirtualization: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get infiniteScrollUp(): boolean {
+    return this.options.infiniteScrollUp ?? false;
+  }
+  set infiniteScrollUp(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, infiniteScrollUp: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get infiniteScrollDown(): boolean {
+    return this.options.infiniteScrollDown ?? false;
+  }
+  set infiniteScrollDown(value: boolean) {
+    this.activeOptions = { ...this.activeOptions, infiniteScrollDown: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get grouping(): unknown {
+    return this.options.grouping;
+  }
+  set grouping(value: unknown) {
+    this.activeOptions = { ...this.activeOptions, grouping: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
+  get paginationPageSizes(): number[] | null | undefined {
+    return this.options.paginationPageSizes;
+  }
+  set paginationPageSizes(value: number[] | null | undefined) {
+    this.activeOptions = { ...this.activeOptions, paginationPageSizes: value } as any;
+    this.ensureController(this.buildEffectiveOptions(this.activeOptions as VanillaGridOptions));
+  }
+
   getState(): GridSaveState | null {
     return this.controller?.getState() ?? null;
   }
@@ -143,6 +693,83 @@ export class UiGridStandaloneElement extends HTMLElement {
     this.controller?.setState(state);
   }
 
+  /**
+   * Fast-path: update only row data without rebuilding the shadow DOM.
+   * The pipeline is updated synchronously; DOM patching is deferred to the
+   * next animation frame so it never interrupts an in-progress scroll paint.
+   * If multiple ticks arrive before the frame fires, only the latest wins.
+   * If a scroll-triggered full render fires first, the frame is cancelled
+   * (the fresh innerHTML already reflects the latest data).
+   */
+  setData(rows: GridRecord[]): void {
+    const controller = this.controller;
+    if (!controller) {
+      return;
+    }
+
+    // Update the pipeline synchronously (cheap, no DOM work).
+    this.skipNextRender = true;
+    controller.refreshData(rows);
+    this.skipNextRender = false;
+
+    // Schedule DOM patching on the next paint — latest call wins.
+    if (this.dataFrame !== null) {
+      cancelAnimationFrame(this.dataFrame);
+    }
+    this.dataFrame = requestAnimationFrame(() => {
+      this.dataFrame = null;
+      this.patchCells();
+    });
+  }
+
+  private patchCells(): 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>();
+    for (const row of snapshot.pipeline.visibleRows) {
+      rowMap.set(row.id, row);
+    }
+    const colMap = new Map<string, GridColumnDef>();
+    for (const col of snapshot.visibleColumns) {
+      colMap.set(col.name, 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;
+
+      const row = rowMap.get(rowId);
+      const column = colMap.get(colName);
+      if (!row || !column) continue;
+
+      const cellShell = cell.querySelector<HTMLElement>('.cell-shell');
+      if (!cellShell) continue;
+
+      const newContent = this.renderCellTemplate(row, column, 0);
+      const toggles = cellShell.querySelectorAll<HTMLElement>('.row-toggle');
+      if (toggles.length === 0) {
+        cellShell.innerHTML = newContent;
+      } else {
+        const toggleHtml = Array.from(toggles)
+          .map((t) => t.outerHTML)
+          .join('');
+        cellShell.innerHTML = toggleHtml + newContent;
+      }
+    }
+  }
+
   connectedCallback(): void {
     this.ensureShadowRoot();
     this.bindEvents();
@@ -209,17 +836,21 @@ export class UiGridStandaloneElement extends HTMLElement {
   }
 
   private buildEffectiveOptions(options: VanillaGridOptions): VanillaGridOptions {
+    // Merge: attributes are overridden by explicit JS property values.
+    // JS property always wins: { ...attributeOptions, ...options }
+    const merged = {
+      ...this.attributeOptions,
+      ...options,
+    } as VanillaGridOptions;
+
     const hasExpandableSlot = this.getTemplateMarkup('expandable-row') !== null;
-    if (options.enableExpandable && hasExpandableSlot && !options.expandableRowTemplate) {
-      return {
-        ...options,
-        expandableRowTemplate: {
-          createEmbeddedView: () => undefined,
-        },
+    if (merged.enableExpandable && hasExpandableSlot && !merged.expandableRowTemplate) {
+      merged.expandableRowTemplate = {
+        createEmbeddedView: () => undefined,
       };
     }
 
-    return options;
+    return merged;
   }
 
   private bindEvents(): void {
@@ -595,7 +1226,7 @@ export class UiGridStandaloneElement extends HTMLElement {
 
         this.scrollFrame = requestAnimationFrame(() => {
           this.scrollFrame = null;
-          this.render();
+          this.renderVirtualBody();
         });
       },
       true,
@@ -604,7 +1235,67 @@ export class UiGridStandaloneElement extends HTMLElement {
     (root as ShadowRoot & { __uiGridBound?: boolean }).__uiGridBound = true;
   }
 
+  /**
+   * 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 {
+    const snapshot = this.snapshot;
+    if (!snapshot?.pipeline.virtualizationEnabled) {
+      this.render();
+      return;
+    }
+
+    const root = this.shadowRoot;
+    const virtualBody = root?.querySelector<HTMLElement>('.grid-virtual-body');
+    if (!root || !virtualBody) {
+      this.render();
+      return;
+    }
+
+    // Cancel any pending cell-only patch — the fresh rows we are about to
+    // render already reflect the latest snapshot data.
+    if (this.dataFrame !== null) {
+      cancelAnimationFrame(this.dataFrame);
+      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 overscan = 4;
+    const startIndex = Math.max(0, Math.floor(bodyScrollTop / snapshot.rowSize) - overscan);
+    this.lastVirtualStartIndex = startIndex;
+    const visibleCount = Math.ceil(bodyViewportHeight / snapshot.rowSize) + overscan * 2;
+    const itemsToRender = snapshot.pipeline.displayItems.slice(
+      startIndex,
+      Math.min(snapshot.pipeline.displayItems.length, startIndex + visibleCount),
+    );
+    const virtualOffset = startIndex * snapshot.rowSize;
+
+    virtualBody.style.top = `${virtualOffset}px`;
+    virtualBody.innerHTML = itemsToRender
+      .map((item, index) => this.renderDisplayItem(item, startIndex + index))
+      .join('');
+  }
+
   private render(): void {
+    if (this.skipNextRender) {
+      return;
+    }
+    // A full render already incorporates the latest data — cancel any pending
+    // frame-based updates to avoid redundant DOM mutations immediately after.
+    if (this.dataFrame !== null) {
+      cancelAnimationFrame(this.dataFrame);
+      this.dataFrame = null;
+    }
+    if (this.scrollFrame !== null) {
+      cancelAnimationFrame(this.scrollFrame);
+      this.scrollFrame = null;
+    }
     const root = this.ensureShadowRoot();
     const snapshot = this.snapshot;
     const previousGridTable = root.querySelector<HTMLElement>('.grid-table');
@@ -632,10 +1323,6 @@ export class UiGridStandaloneElement extends HTMLElement {
     const headerStickyTop = this.measuredHeaderStickyHeight || options.headerRowHeight || 50;
     const stickyChromeHeight = this.measuredHeaderStickyHeight + this.measuredFilterStickyHeight;
     const bodyViewportHeight = Math.max(snapshot.rowSize, viewportHeight - stickyChromeHeight);
-    const visibleRowCount = snapshot.pipeline.visibleRows.length;
-    const totalRows = options.data.length;
-    const pinnedCount = Object.keys(snapshot.pinnedColumns).length;
-
     let startIndex = 0;
     let itemsToRender = snapshot.pipeline.displayItems;
     let virtualOffset = 0;
@@ -681,12 +1368,9 @@ export class UiGridStandaloneElement extends HTMLElement {
         : `<div class="empty-state ui-grid-no-row-overlay"><strong>${escapeHtml(options.emptyMessage ?? labels.emptyHeading)}</strong><p>${escapeHtml(labels.emptyDescription)}</p></div>`;
 
     const pagination = paginationEnabled && showPagination ? this.renderPagination(snapshot) : '';
-    const hero = `<header class="grid-hero"><div><p class="eyebrow">Vanilla web component</p><h1>${escapeHtml(options.title ?? 'UI Grid')}</h1><p class="deck">Framework-neutral custom element with Shadow DOM styling, slot templates, pinning, virtualization, editing, tree view, grouping, and state restore.</p></div><div class="hero-actions"><button type="button" class="action action-secondary" data-action="benchmark">Benchmark</button><button type="button" class="action action-secondary" data-action="export-csv">Export CSV</button><div class="stats-card"><span>${visibleRowCount}</span><small>${escapeHtml(labels.statsVisibleRows)}</small></div></div></header>`;
-    const metrics = `<section class="metrics-strip" aria-label="Grid metrics"><article><strong>${snapshot.pipeline.pipelineMs.toFixed(2)} ms</strong><span>pipeline</span></article><article><strong>${virtualizationEnabled ? 'On' : 'Off'}</strong><span>virtualization</span></article><article><strong>${pinnedCount}</strong><span>pinned columns</span></article><article><strong>${escapeHtml(this.benchmarkAverage)}</strong><span>benchmark avg</span></article></section>`;
-    const toolbar = `<div class="grid-toolbar"><div><strong>${visibleRowCount}</strong><span>${escapeHtml(labels.toolbarOf)} ${totalRows} ${escapeHtml(labels.toolbarRows)}</span></div><p>${escapeHtml(options.id)}</p></div>`;
     const gridTableStyle = `${virtualizationEnabled ? `height:${viewportHeight}px;overflow-y:auto;` : ''}--ui-grid-header-sticky-top:${headerStickyTop}px;`;
 
-    root.innerHTML = `<style>${GRID_CORE_CSS}</style><section class="grid-shell ui-grid-shell">${slotRegistry}${hero}${metrics}<section class="grid-frame ui-grid" role="grid" aria-label="${escapeHtml(options.title ?? 'Data grid')}">${toolbar}<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></section>`;
+    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>`;
 
     const gridTable = root.querySelector<HTMLElement>('.grid-table');
     if (gridTable && this.scrollPosition > 0 && virtualizationEnabled) {
@@ -766,8 +1450,9 @@ export class UiGridStandaloneElement extends HTMLElement {
     const pinLabel = isPinned
       ? (this.snapshot?.labels.unpin ?? 'Unpin')
       : (this.snapshot?.labels.pinColumn ?? 'Pin');
+    const headerValue = escapeHtml(formatGridHeaderDisplayValue(buildGridHeaderContext(column)));
 
-    return `<div class="${classes}" data-column="${escapeHtml(column.name)}" ${draggable} style="${stickyStyle}"><span class="header-label">${escapeHtml(controller.headerLabel(column))}</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></div>`;
+    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></div>`;
   }
 
   private renderFilterCell(column: GridColumnDef): string {