Vanilla Grid Component

A lightweight, high-performance virtualized data grid component built with vanilla JavaScript (no dependencies).

Features

• Virtual Scrolling: Efficient rendering for large datasets (1000+ rows) using a recycled row pool; pool rows are rotated (not repopulated) on small scrolls, an engine-scoped virtual-height cap keeps large datasets in low-cost "natural" scroll mode on Blink/WebKit, and touch input gets a synchronous-render fast path plus a velocity-skewed buffer for smoother mobile momentum scrolling
• Column Resizing: Interactive column width adjustment with persistence; body columns update visually in real time during drag
• Resize Guide Overlay: Live vertical guide line aligned to the active resize handle, scoped to the viewport height, with automatic contrast via mix-blend-mode: difference
• Last Column Resize: Dedicated right-edge handle on the last column for independent resizing; table width auto-adjusts to remove/restore horizontal scroll as needed
• Horizontal Scrolling: Custom horizontal scrollbar when total column widths exceed the viewport, synchronized with header translate
• Header Horizontal Sync: Header stays aligned with body columns during horizontal scroll via GPU-accelerated translateX transform
• Multi-Column Sorting: Client-side and server-side sorting, single-click or Shift+click multi-sort, with a customizable compareValues callback; sortable columns also get Sort ascending / Sort descending / Clear sorting items in the right-click header context menu
• Column Reordering: Drag-and-drop header reordering (mouse and touch) with cross-group boundary enforcement for frozen columns; persisted to localStorage
• Column Visibility: Hide/show individual columns from a right-click header context menu or programmatically; at least one column is always visible; persisted to localStorage
• Column Freeze/Unfreeze: Sticky frozen columns anchored at the left edge with a visual guide line; context menu and API support; persisted to localStorage
• Row Selection: noselection, single, and multiple modes; stable key-based selection survives sort, page, and infinite-scroll reloads; header checkbox and selectionChanged event
• Row Grouping (client-side, multi-level): groupByColumn()/addGroupLevel()/setGroupState() collapse runs of equal values under a collapsible, nested caption row carrying the value and an exact member count; composes with sorting/filtering/selection/freeze/export; persists across reloads; "Group by this column" / "Add to grouping" / "Ungroup all" in the right-click header context menu, reason-coded and disabled over a partial (infinite-scroll) dataset rather than silently wrong. Each applied group level's column leaves the grid (its value lives in the caption) and becomes a chip in a grid-owned group bar above the header carrying its direction and an ungroup action, with "Expand all" / "Collapse all" / "Ungroup all" commands at the strip's trailing edge; chips can be dragged within the bar (or moved with Alt+arrow) to re-nest the levels; ungrouping restores the column at its original position, width, freeze state and filter
• Loading Skeletons: Shimmer skeleton rows shown during data fetch replace the spinner pattern
• Infinite Scroll: Automatic page-chaining via onLoadMore; optional total-row resolver; sticky select-all that extends to new pages
• DataManager Pattern: Swappable data layer with ODataDataManager, GraphQLDataManager, and StaticDataManager built-in
• Web Component Wrapper: Optional <vn-grid> custom element for declarative integration including <vn-grid-column> children
• Export to Excel: exportToExcel(options) method to export grid data (all rows or selected) to an .xlsx file, written by the grid itself (no third-party library). Rows are read in short chunks and the workbook is streamed through the browser's native compression — in a Web Worker from workerThreshold rows (default 5000) — so the page stays responsive and exports scale to Excel's own sheet limit (about 3 s for 100,000 rows × 21 columns, 30 s for 1,000,000). Themed to the active theme by default; the overlay shows progress and a Cancel button; failures reject with a coded VanillaGridExportError and are shown in the overlay. See Export to Excel.
• Cell Rendering: per-column renderCell callback for full control over per-cell DOM
• Themeable: Eight pre-built themes (Default, Material, Fiori, Carbon, Carbon Dark, Glow, Glow Dark, Fluent) plus host-registered custom themes; custom scrollbar and resize guide automatically adapt to theme colors
• Custom Scrollbars (Vertical + Horizontal): JavaScript-driven dual-axis scrollbars with styled thumbs, drag support, and consistent cross-browser behavior
• Responsive: Adapts to container size with smooth scrolling; flex layout chain prevents white gaps during browser resize
• Customizable Formatting: Full control over cell value rendering, header labels, and secondary header text
• Mobile Touch Hardening: Text-selection/long-press callout suppressed on header and body cells (opt back in per-grid via --vn-grid-cell-user-select), tap-highlight flash and header double-tap zoom disabled, and column-filter inputs auto-size to 16px on coarse-pointer devices to avoid iOS's input-focus page zoom
• Zero Dependencies: Pure JavaScript, no frameworks needed

Installation

Direct File Include

<script src="path/to/vanilla-grid/vanilla-grid.js"></script>

vanilla-grid.js is the only tag needed: it auto-loads, relative to its own URL, every features/*.js module, the data managers (data-managers/data-manager.js, odata-data-manager.js, graphql-data-manager.js, static-data-manager.js) and, last, the <vn-grid> wrapper vanilla-grid-element.js. Await window.VanillaGridReady before using any of them. For a single-file deployment use the built vanilla-grid.bundle.js instead (it sets window.VanillaGridSkipAutoload = true internally).

When using the <vn-grid> web component, you do not need to add <link> tags for vanilla-grid.css or the theme files. The component automatically injects the base structural stylesheet and the active theme stylesheet into <head>.

If you are using VanillaGrid directly (without the web component), include the CSS manually:

<link rel="stylesheet" href="path/to/vanilla-grid/vanilla-grid.css">
<link rel="stylesheet" href="path/to/vanilla-grid/themes/vn-grid-default.css">

Usage

Web Component Setup

The custom element is designed as a light-DOM wrapper around VanillaGrid. It does not use Shadow DOM, so existing app and theme CSS continue to apply.

Markup declares presentation; data always comes from a DataManager (see DataManager):

<vn-grid
    id="myGrid"
    theme="default"
    locale="en-US"
    infinite-scroll="true"></vn-grid>

Theme Attributes

Supported themes are also available programmatically:

// List all built-in themes
console.log(VanillaGridElement.SUPPORTED_THEMES);
// → ['default', 'material', 'fiori', 'carbon', 'carbon-dark', 'glow', 'glow-dark', 'fluent']

// Switch theme at runtime
document.getElementById('myGrid').setTheme('carbon-dark');

// Or use a custom theme CSS file
document.getElementById('myGrid').themeCssPath = 'my-themes/grid-custom.css';

Attach a DataManager, initialize, then load:

await window.VanillaGridReady;
const myGridElement = document.getElementById('myGrid');

myGridElement.setDataManager(new ODataDataManager({
    baseUrl: 'http://localhost:3000/api/items',
    countUrl: 'http://localhost:3000/api/items/$count',
    headers: () => ({ Accept: 'application/json' }),
    pageSize: 1000
}));

const grid = myGridElement.initializeGrid({
    layout: {
        rowHeight: 24,
        bufferRows: 20,
    },
    infiniteScroll: { enabled: true }
});

await myGridElement.loadRowsAsync();

Request headers and fetch side effects are DataManager concerns (headers, onRowsLoaded, onFetchResponse, …); per-cell DOM is a column's renderCell.

Basic Setup

<div class="table-container">
    <div class="table-header-spacer">
        <table class="header-table">
            <colgroup id="myColGroup"></colgroup>
            <thead id="myTableHeader"></thead>
        </table>
    </div>
    <div id="myViewport" class="virtual-list-viewport">
        <table class="body-table">
            <colgroup></colgroup>
            <tbody id="myTableBody"></tbody>
        </table>
    </div>
</div>

const grid = new VanillaGrid({
    header: document.getElementById('myTableHeader'),
    body: document.getElementById('myTableBody'),
    headerColGroup: document.getElementById('myColGroup'),
    viewport: document.getElementById('myViewport'),
    headerSpacer: document.querySelector('.table-header-spacer'),
    formatting: {
        locale: 'en-US',
        emptyMessage: 'No data available'
    },
    layout: {
        rowHeight: 24,
        snapViewportToRows: true,
        bufferRows: 20,
        scrollSpeedMultiplier: 1.35
    }
});

// Set columns
grid.setColumns([
    { key: 'id', label: 'ID', width: 60 },
    { key: 'name', label: 'Name', width: 200 },
    { key: 'email', label: 'Email', width: 250 }
]);

// Load data
grid.setRows([
    { id: 1, name: 'John Doe', email: 'john@example.com' },
    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
]);

Configuration Options

DOM References (top-level, required)

Cell text is formatted by column type (with per-column formatOptions), and type: 'number' columns are right-aligned; per-cell DOM customization is the column's renderCell(cell, value, row, rowIndex) (see Column Definition).

formatting Group

layout Group

sorting Group

grouping Group

Client-side, multi-level (any number of ordered group columns). See Row Grouping Implementation.

Persistence: persistence.groupState ({ enabled, storageKey }) persists the requested group state across reloads, mirroring persistence.sortState — see the persistence group below.

columns Group

persistence Group

infiniteScroll Group

Total row count (push, not infinite-scroll-nested)

selection Group

messages Default Values

messages: {
    of: 'of',                           // Scroll indicator separator ("1–50 of 1000")
    hideColumn: 'Hide column',          // Header context menu
    showAllColumns: 'Show all columns', // Header context menu
    freezeColumn: 'Freeze column',      // Header context menu
    unfreezeColumn: 'Unfreeze column',  // Header context menu
    unfreezeAll: 'Unfreeze all',        // Header context menu
    loadingMore: 'Loading more rows…',  // Infinite-scroll busy banner
    groupByColumn: 'Group by this column',   // Header context menu (row grouping — replace)
    addToGrouping: 'Add to grouping',        // Header context menu (row grouping — append a level)
    ungroupColumn: 'Remove from grouping',   // Header context menu (row grouping)
    ungroupAll: 'Ungroup all',               // Header context menu + the group bar's trailing command (row grouping — clear every level; shown only while grouped)
    groupReasonDisabled: '…',                // Disabled-menu-item title, keyed by canGroupByColumn()'s/canAddGroupLevel()'s reason code
    groupReasonPartialDataset: '…',          // ditto — dataset not fully loaded
    groupReasonMultiLevelNotYetSupported: '…', // ditto — a second group column
    groupReasonNoVisibleColumnsLeft: '…',    // ditto — grouping would leave no visible data column
    groupItemsSuffix: 'items',               // Caption label suffix ("… — 42 items")
    groupBlankValue: '(Blank)',              // Caption label for a null/undefined group value
    groupPathAriaSeparator: ', ',            // Joins a nested group's path in caption/footer accessible names
    groupBarLabel: 'Grouped by',             // Group bar: leading label + the strip's aria-label
    groupBarRemove: 'Remove from grouping',  // Group bar: a chip's remove button
    groupBarSortAscending: 'Ascending',      // Group bar: a chip's direction control (asc)
    groupBarSortDescending: 'Descending',    // Group bar: a chip's direction control (desc)
    groupBarSuspended: 'Grouping is paused:',// Group bar: tooltip prefix while suspended
    groupBarExpandAll: 'Expand all',         // Group bar: trailing command (disabled while suspended)
    groupBarCollapseAll: 'Collapse all',     // Group bar: trailing command (disabled while suspended)
    aggregateFunctionLabels: {               // Group footer rows: each function's full name — accessible name,
        sum: 'Sum', avg: 'Average',          //   cell tooltip ("Average of Projects for Italy: 14.165") and header menu
        median: 'Median', min: 'Minimum', max: 'Maximum',
        countTrue: 'True count', countDistinct: 'Distinct count',
    },
    aggregateFunctionMarkers: {},            // Text markers (empty by default: built-in functions show SVG icons). An entry replaces the icon
                                             //   ({ avg: 'Ø' }), gives a registered function a marker ({ stdev: 'σ' }), or '' hides it

    aggregateFooterAria: 'Group summary',    // Group footer rows: the leading announcement of the row's accessible name
    aggregateOfLabel: 'of',                  // Group footer rows: joins function to column ("Sum of Projects")
    aggregateForLabel: 'for',                // Group footer rows: joins column to group path in the cell tooltip
    aggregatePathSeparator: ' › ',           // Group footer rows: joins the tooltip's path values (theme-independent; RTL: ' ‹ ')
    aggregateMenuLabel: 'Aggregate',         // Header menu: the submenu's parent entry
    aggregateRemove: 'Remove aggregate',     // Header menu: rendered only while the column carries one
    // Disabled-entry titles, keyed by canAggregateColumn()'s reason code and
    // derived from it the way the groupReason* keys are.
    aggregateReasonNoGrouping: 'Aggregates require an active grouping.',
    aggregateReasonColumnUnsupported: 'This column’s type cannot be aggregated.',
    aggregateReasonColumnNotFound: 'This column cannot be aggregated.',
    aggregateReasonPartialDataset: 'Aggregates require the full result set to be loaded.',
    aggregateReasonDisabled: 'Aggregates are unavailable.',
}

Infinite-scroll busy state

Once a page fetch has been in flight for infiniteScroll.shimmerDelay ms (default 500 — a fast backend paints neither), the grid shows two things:

• Skeleton rows at the tail of the data. These are positional — scroll away from the end and they are off-screen.
• A "loading more rows" banner pinned to the bottom edge of the grid, visible at any scroll position. It never covers the rows underneath (a load-more append leaves them valid), reads its label from messages.loadingMore, and carries role="status" for screen readers. It hangs off the grid container, so it works standalone — no <vn-grid-toolbar> and no custom scrollbar required.

Set shimmerDelay to a negative number to suppress both and paint your own indicator off the class below, which is never delayed.

Styling hooks:

Both the class and the banner clear between failed retries, since the grid is genuinely idle while it waits out the backoff.

Column Definition

Each column object passed to setColumns() supports the following properties:

Example:

grid.setColumns([
    { key: 'id',     label: 'ID',     width: 60,  sortable: false },
    { key: 'name',   label: 'Name',   width: 200 },
    { key: 'weight', label: 'Weight', secondaryLabel: 'kg', width: 120 },
    { key: 'active', label: 'Active', width: 80,  isKeyColumn: false }
]);

VanillaGrid Methods

Data Management

• setColumns(columns) — Set grid columns. When a sorted or grouped column's new definition orders differently (its field/valueGetter, type, nulls, sourceFormat/inputPattern, booleanCoerce or sortFields/sortFieldTypes changed), the rows are re-sorted under the same sort/group state — no sort or group event fires and the scroll position is kept. Re-declaring identical columns re-sorts nothing; note that an inline valueGetter re-created on every call counts as a change. See Sorting § 10.3
• setRows(rows) — Replace all grid data; resets scroll position
• appendRows(newRows) — Append rows without resetting current state (used by infinite scroll)
• loadData(dataLoaderFn, options) — Load rows via async callback with built-in loading state, skeleton rendering, and error handling
  • options.onSuccess(data, elapsedMs) — Called after successful load
  • options.onError(error) — Called on failure
  • options.onComplete() — Always called (finally)
• loadDataProgressively(dataLoaderFn, options) — Progressive chunked rendering for large payloads
  • options.chunkSize (default 200) — Rows per rendering chunk
  • options.chunkDelay (default 16) — Milliseconds between chunks
  • options.onProgress(loaded, total) — Progress callback
  • options.onSuccess, options.onError, options.onComplete — Same as loadData
• getLoadedRowCount() — Returns the number of rows currently loaded
• getTotalRowCount() — Returns the current known total row count, or undefined when unknown
• setTotalRowCount(count) — Pushes the total row count for the active query (wired automatically from the attached DataManager)
• hasMoreRows() — Returns true when more pages are available in infinite-scroll mode; always false for a non-infinite-scroll (static/in-memory) grid, including during the reset→requery window of a filter/sort/reload

State Management

• setLoading(isLoading) — Toggle loading state (shows shimmer skeletons, disables scroll)
• showEmpty(message) — Display an empty-state message
• showError(message) — Display an error-state message
• clearPersistedSettings(options?) — Wipe every grid-owned settings key (widths, order, hidden, frozen, sort state, group state, filter model, search term) from the active storage provider, reset the in-memory caches, and re-apply the declarative state — the columns from the most recent setColumns() call plus the declared group-by / sort-by (grouping.columns / sorting.columns) request. Returns undefined for sync providers and Promise<void> for async providers. Pass { deferToReload: true } when a data reload follows immediately: the sort and group state are cleared and the declarative ones re-parked but not applied, so the dataset is ordered once by that reload's setRows() rather than twice. Mirrors the option of the same name on clearSort(). See Local Storage Settings §6.5.
• refresh(options?) — Rebind every visible cell against the current rows (re-running formatters / renderCell) without querying the DataManager. Resets scroll position to the top-left by default; pass { preserveScroll: true } to keep it. Useful after a live theme swap.
• destroy() — Remove all event listeners and clean up internal state

Multi-Column Sorting

• sortColumn(columnIndex, direction, options) — Sort one column; direction is 'asc', 'desc', or null to clear; pass { multi: true } to add to the existing sort chain
• sortColumns(sortColumns, options) — Apply a full multi-sort chain: [{ columnIndex, direction }]
• clearSort() — Remove all active sorting
• getSortState() — Returns the full sort snapshot (see Multi-Column Sorting)

These four are index-based. To declare an initial sort — before the grid has columns, from markup or from an options object — use the key-based sort-by attribute or the sorting.columns option instead:

<vn-grid sort-by="lastName:asc, salary:desc"></vn-grid>

Entry order is the sort-chain order, primary column first, and the direction is required on every entry. See Sorting Implementation §12.1.

Column Visibility

• hideColumn(key) — Hide a column by key; returns false if it is the last visible column
• showColumn(key) — Restore a hidden column
• showAllColumns() — Restore all hidden columns
• getHiddenColumns() — Returns an array of hidden column keys
• canHideColumn(key) — Returns true if hiding this column is permitted (at least one other visible column must remain)

All four mutators rebuild the virtual row pool and preserve the current scroll position — hiding or showing a column does not jump the user back to the top of a scrolled grid.

Column Freeze

• freezeColumn(key) — Freeze a column (it moves to the left sticky group)
• unfreezeColumn(key) — Unfreeze one column
• unfreezeAll() — Unfreeze all columns
• isFrozenColumn(key) — Returns true if the column is currently frozen
• getFrozenColumns() — Returns an array of frozen column keys

Column Reordering

• reorderColumn(fromIndex, toIndex, options) — Move a column programmatically; pass { dropBefore: true|false } to control insertion side

Header Runtime

• refreshHeaderLayout(options?) — Re-render the header and synchronize header/body widths, scrollbar spacing, and tooltips; pass { clearExistingWidths: true } to reset all widths
• updateColumnHeaders(updater) — Batch-update column metadata; calls refreshHeaderLayout() once if any change is detected; updater(column, index) should return true when it modifies a column
• setColumnSecondaryLabel(columnKey, secondaryLabel) — Update one column's secondaryLabel and refresh the header layout

Row Selection

• getSelectedKeys() — Returns an array of the currently selected row keys
• getSelectedRows() — Returns an array of the currently selected row objects (O(1) lookup via internal key map)
• setSelectedKeys(keys) — Replace the current selection with the given keys array
• clearSelection() — Deselect all rows
• isRowSelected(row) — Returns true if the given row object is currently selected
• selectionState (getter) — Returns 'none', 'partial', or 'all'
• selectAllActive (getter) — Returns true when the sticky select-all flag is active (all incoming rows will also be auto-selected; relevant for infinite scroll)

Row Grouping

Client-side, multi-level. See Row Grouping Implementation for the full design — the render projection, availability gating over a partial dataset, and the caption keyboard/focus contract.

• groupByColumn(key, options?) — Replaces the whole group state with this one entry ("Group by this column" in the header menu), even if the grid is already grouped by other columns; options.direction is 'asc' (default) or 'desc'. Returns { available, strategy, reason }.
• addGroupLevel(key, options?) — Appends key as a new trailing group level instead of replacing ("Add to grouping" in the header menu) — the interactive way to build multi-level grouping one column at a time. No-op if key is already a group level. Same options/return shape as groupByColumn.
• ungroupColumn(key) — Remove key's level from the group state, wherever it sits, leaving every other level intact and in order.
• clearGrouping() — Remove grouping unconditionally ("Ungroup all" in the header menu, offered on every column's menu while any level is applied).
• getGroupState() — Returns the requested group state ([{ key, direction }, ...]), a defensive copy — intact even while grouping is unavailable (see canGroupByColumn).
• setGroupState(state) — The general-purpose multi-level entry point. Replaces the full group state with any number of ordered levels (outermost first) in one call — what addGroupLevel()/groupByColumn() are themselves built on.
• expandGroup(path, options?) / collapseGroup(path, options?) — Expand or collapse one caption by its raw-value path, outermost first (e.g. ['Italy'], or ['Italy', 'Rome'] for a nested level). options.descendants ('collapsed' or 'expanded') also sets every group below it, at every depth, in one step: expandGroup(['Italy'], { descendants: 'collapsed' }) opens Italy showing only its folded city captions. All or nothing — false, with nothing changed, when the subtree holds more groups than the cardinality ceiling or the grouping isn't applied.
• Shift-click a caption, or press Shift+Enter on a focused one, to fold or unfold the groups below it. The caption always ends up open: a collapsed caption, or an open one with any open child group, opens with everything below folded; an open one whose child groups are all folded opens everything below. At the deepest level it's a plain toggle. Captions that offer it carry a hover hint (messages.groupCaptionToggleHint) and aria-keyshortcuts="Shift+Enter". Shift rather than Alt because Linux window managers (Xfce by default) take Alt+click.
• expandAllGroups() / collapseAllGroups() — Expand or collapse every group at every level — nested groups under a collapsed parent included — in one call (also the group bar's "Expand all" / "Collapse all"). The state also becomes the one groups that appear later start in, instead of grouping.expandMode, until the grouping is fully cleared. Fires one vn-grid-group-expanded / vn-grid-group-collapsed with { path: null, groupKey: null, all: true, descendants: null }, or nothing when every group was already in that state.
• canGroupByColumn(key) — O(1) predicate, never scans rows. Whether groupByColumn(key) (replace) could apply right now. Returns { available, strategy, reason }; reason is one of 'ok', 'disabled', 'partial-dataset', 'multi-level-not-yet-supported', or 'column-unsupported'. Reports 'multi-level-not-yet-supported' whenever grouped by a different column — see canAddGroupLevel.
• canAddGroupLevel(key) — O(1) predicate, never scans rows. Whether addGroupLevel(key) (append) could apply right now — only available once some grouping already exists and key isn't already one of its levels. Same return shape as canGroupByColumn, minus the 'multi-level-not-yet-supported' reason. 'too-many-groups' is only ever returned by the three mutating calls (groupByColumn/addGroupLevel/setGroupState), never by either predicate, when a requested grouping would exceed the fixed cardinality ceiling — the group state is left unchanged.
• getGroupingStatus() — Returns { available, strategy, reason } for the current requested state, resolved fresh with no side effects. getGroupState() answers what was requested; this answers whether it is applied right now, and why not when it isn't.

Large grids: a group change is a reorder, and reorders defer. A group change moves as much data as a sort, so it runs on the same bracket: below sorting.shimmerThreshold (default 5000 rows) it is fully synchronous; at or above it the reorder is deferred behind the loading skeleton and offloaded to the sort Web Worker when every group level is worker-safe (string/number/boolean; a temporal group level falls back to the shimmered in-thread path). Two consequences for callers:

• On a deferred call, groupByColumn()/addGroupLevel()/setGroupState() return the capability resolvable before the row scan, so a 'too-many-groups' rejection arrives on vn-grid-group-changed instead of in the return value. 'no-visible-columns-left' is pure column arithmetic and is always in the return value. Read the event if you need the outcome on grids of any size.
• vn-grid-group-changed fires when the new order has actually landed, not when the call returned.

Events: vn-grid-group-changed, vn-grid-group-expanded, vn-grid-group-collapsed, vn-grid-aggregates-changed (all bubbling + composed — see the implementation doc's Event Contract section).

Group aggregates

A group footer row under each group, at every level, carrying a named reduction of one column's values in that column's own cell. Configured declaratively or at runtime; nothing renders until at least one column carries one.

new VanillaGrid({
    grouping: {
        columns:    [{ key: 'country', direction: 'asc' }],
        aggregates: [{ key: 'projects', fn: 'sum' }]
    }
});

• grouping.aggregates — Initial set, [{ key, fn }] with fn a registered reducer name. A default, not a lock: the user's persisted choice wins afterwards, and clearPersistedSettings() restores it. Applied after grouping.columns, so it has no effect on a grid with no grouping. There is no <vn-grid> attribute for it.
• getAggregates() — The configured set, a defensive copy.
• setAggregates(state) — Atomically replace it. Returns { available, reason }, where reason is one of 'ok', 'column-not-found', 'unknown-function', 'column-unsupported', 'column-grouped', 'no-grouping' or 'disabled'. Every refusal is resolved here rather than at render time, and it is all-or-nothing: one bad entry leaves the whole set untouched. Two entries naming the same column are not a refusal — the last wins. Clearing is setAggregates([]), accepted in every state.
• getGroupAggregates(path) — One group's computed values by column key, taking the same raw-value path expandGroup() does. A column with nothing to reduce reports null, never 0.
• canAggregateColumn(key) — O(1) predicate, never scans rows. Returns { available, reason, functions }, where functions is every registered function the column's declared type admits. This is what the header menu greys its entry out with; its reason set is wider than setAggregates()'s (it can report 'partial-dataset' for a suspended grouping), the same way canGroupByColumn()'s is wider than setGroupState()'s.
• VanillaGrid.registerAggregate(name, reducer) — Static. Extend the registry with { init, step, finalize, types }, plus two optional members: prepare(context) and resultType. types lists the column.type values the function may be applied to, so a host reducer passes the same eligibility gate the built-ins do. See The reducer contract below.

From the header menu. A column's right-click menu carries "Aggregate ▸", opening a flyout of the functions its type admits, plus "Remove aggregate" while one is set. Picking a function on a column that already has one replaces it. The entry is on every column's menu whatever the grid state — so the capability is discoverable before anything is grouped — and is disabled with an explained title when it cannot act: the column's type first ('column-unsupported'), then the grid's state ('no-grouping', or 'partial-dataset' while a grouping is suspended). A column that is ineligible both ways reports its type, since that is the reason grouping will not fix. A grouped column needs no rule: its column has left the grid, so its menu is not on screen.

What a v1 aggregate deliberately does not do, so none of it is a discovery:

• No plain count. The caption already carries the member count of every group. countTrue and countDistinct count something the caption does not.
• No grand total, as a row or through the API. getGroupAggregates([]) is the reserved address for one when a host asks.
• No group footer rows in the Excel export. The export is a data export of displayRows with the group columns composed back in, so captions, collapse state and footers are all structurally absent. The recipient reproduces the totals as live formulas with Excel's own Data ▸ Subtotal, which is a better artifact than pasted numbers — and writing them as cells would break the sheet's AutoFilter.
• No server-side aggregation — it belongs with server-side grouping, which is also not implemented.
• No cross-column formulas. A reducer's step(acc, value) receives a value, not a row: this is a named reduction over one column, not an expression language.
• No per-column override of the function set. The type gate screens what is computable, never what is meaningful, so every statistic is offered on every number column — an ID or a rating included. That judgment is the host's and the user's.
• A partial sum looks exactly like a complete one. In practice grouping suspends over an incomplete result set, so an aggregate is only ever computed over the full dataset.
• Nothing visible on a footer names the group it closes — hovering an aggregated cell does (see below), and so does its accessible name, but at a glance a sighted user who has scrolled past the caption sees only the totals.
• Tab reaches only the group rows currently in the virtual pool. Pre-existing behaviour of caption toggles; footers add stops within the pool without changing it.
• Aggregates never reflect the selection. Recomputing per click is a full projection build, 165–433 ms of main thread at a million rows.

Seven functions ship built in, offered by the column's declared type — the gate reads the declaration, never the runtime values, so an untyped or valueGetter column offers nothing. Registration order is menu order.

• Gaps are skipped, never coerced, and a group with nothing to reduce renders blank, never 0 — for avg that matters more than for sum, since a null counted as zero would pull the average down. Every level reduces its own rows, never its children's results: an outer avg, median or countDistinct is the true value over the group, not an average of averages.
• avg and median use the column's own formatter, so an average can show decimals no data cell above it shows (an average of integers is not an integer), and a maximumFractionDigits: 0 column rounds it. median is exact — it keeps each open group's values — never an approximation.
• Temporal min / max read each value the way the column's own cells read it (epoch numbers, ISO strings, sourceFormat, inputPattern) and report the winning row's raw value, so the footer renders exactly like that row's cell and getGroupAggregates() returns the raw value (a number, an ISO string, a Date), not an epoch.
• countTrue reads values through the column's booleanCoerce (so 'Yes'/'No' count under 'loose'); 0 is a real answer, blank means no known value at all. countDistinct counts with grouping's equality — the column's comparator — so Rome, rome and Róme are one city, exactly as grouping by City shows one group. Both render as right-aligned integers whatever the column's type.
• Hovering an aggregated footer cell shows the function's full name, the column, the group's full path and the value — "Average of Projects for Italy › Rome: 14.165". Each parent value longer than 28 characters is cut at the end with …; the innermost value never is. The localized pieces are the row's accessible name's, plus aggregateForLabel and aggregatePathSeparator.
• The header says so, too. While a column's footer cells show a total, its header carries a badge with the same marker (.vn-grid-aggregate-badge, after the secondary header text), and its title names the function ("Average of Height"). The badge follows every change to the set and disappears while grouping is suspended. A marker hidden with '' in aggregateFunctionMarkers hides it in the footer only; the badge keeps the built-in icon.
• Markers are icons. A built-in function's marker is a masked SVG (.vn-grid-aggregate-icon with data-fn), not a font glyph, so its weight and centering are the same in every theme. The shapes are --vn-grid-aggregate-icon-* tokens a theme can override (see Header parts). A messages.aggregateFunctionMarkers entry replaces an icon with text.
• Nested groups are announced by their full path. A nested caption's toggle and footer name every level ("Country: Italy, City: Rome — 12 items"), so two groups with the same inner value are told apart; the caption's visible text is unchanged and ends the announcement.

Cost at a million rows. In Chrome, on grid-minimal-js grouped by Country ▸ City, a whole aggregate change — the grouped rebuild included — settles in about 0.8–0.9 s for Median of Height plus Distinct count of Department, and about 0.9–1.2 s for Minimum of Hire Date plus True count of Active, with or without the --obfuscate build. Per function, one aggregated column adds roughly: sum, avg, min, max 30–60 ms; median 1.2–1.8× that; countTrue and low-cardinality countDistinct 60–110 ms; temporal min/max on epoch-number columns about the same as sum (per-function figures from a Node harness). Two cases are much dearer; both run behind the loading skeleton and only when someone picks that function on such a column:

• countDistinct on a string column of mostly unique values — about 23–26 s in Chrome for 1M unique emails at two group levels. Almost all of it is the main thread taking in each distinct string for the first time (hashing it into the exact-value set); the locale-aware sort of the uniques is a small part. A Node harness shows only +1.4 s (one level) / +4.4 s (two levels) for the same work, so do not size this from Node figures. countDistinct on numbers or epoch dates is unaffected (about +0.1–0.4 s even at 1M unique values), and so is a low-cardinality string column.
• ISO-string temporal columns under min/max pay one parse per distinct string: about +0.2–0.6 s for a date column's few thousand distinct days, +1.6–2.1 s for one distinct timestamp per row (Node harness; not yet measured in a browser, where it may be higher).

Aggregates are single-column: a reducer's step(acc, value) receives a value, not a row, and there is no cross-column expression language.

The reducer contract. { init(context), step(acc, value), finalize(acc), types }, plus optionally:

• context — { column, compare(a, b) }, frozen, built once per column per projection build and handed to init() and prepare(). compare is the grid's comparator for that column, the one grouping splits groups with.
• prepare(context) — a factory called once per column per build, returning a per-row mapper applied before step() (once per row, however deep the grouping) or null for a column that needs no conversion, which then costs nothing extra.
• resultType — 'column' (default: formatted and aligned by the column) or 'count' (formatted with formatting.formatInteger, right-aligned whatever the column's type).

step() runs once per row per open group level; state size is the reducer's business.

// Sample standard deviation (Welford), skipping gaps like the built-ins.
VanillaGrid.registerAggregate('stdev', {
    init: () => ({ n: 0, mean: 0, m2: 0 }),
    step: (acc, v) => {
        if (typeof v !== 'number' || Number.isNaN(v)) return;
        acc.n++;
        const d = v - acc.mean;
        acc.mean += d / acc.n;
        acc.m2 += d * (v - acc.mean);
    },
    finalize: (acc) => (acc.n > 1 ? Math.sqrt(acc.m2 / (acc.n - 1)) : null),
    types: ['number'],
});

A registered function's label and marker come from messages.aggregateFunctionLabels / aggregateFunctionMarkers, and its marker is text (only the built-ins have icons); with neither, the menu and tooltip show its name, the cell no marker, and the header badge the sum icon. samples/grid-minimal-js/ registers two, stdev and mode, as working examples.

Like a group change, an aggregate change runs on the reorder bracket: fully synchronous below sorting.shimmerThreshold, behind the loading skeleton at or above it. A change arriving while a group change is still deferred does not overtake it — the two coalesce into one settled pipeline, so the projection is always built from rows ordered for the grouping that was asked for, and each settled change is announced once. step() is main-thread work — a host reducer cannot be transferred to the sort Worker. vn-grid-aggregates-changed fires once per settled change and means the computed values have rendered, so getGroupAggregates() read inside the handler is always settled; a superseded recomputation emits nothing.

grid.setAggregates([{ key: 'projects', fn: 'sum' }]);
grid.addEventListener?.('vn-grid-aggregates-changed', () => {
    console.log(grid.getGroupAggregates(['Italy']));   // { projects: 1204 }
});

An aggregate and a group level never share a column. An applied level's column has left the grid, so its total would have no cell to render into — which is why the header menu can never offer one. The API is held to the same rule at both ends: setAggregates() refuses a column the grid is grouped by ('column-grouped'), and grouping by an already-aggregated column prunes that aggregate with one event, rather than leaving a configuration that computes and renders nowhere. An ineligible column type still outranks the conflict.

An aggregate lives and dies with the requested group state — one rule, three cases. Clearing the last group level discards the configuration (there is nothing left to reduce over), emitting one vn-grid-aggregates-changed with the emptied set; removing one level of a multi-level grouping keeps it, since the session is still alive. A suspension retains it with no event and no host action, and resuming recomputes — but while suspended the set is not editable, and setAggregates() refuses with 'disabled'. A setColumns() that removes, renames or retypes an aggregated column prunes that entry, revalidating against the same gate a fresh acquisition passes, and announces the settled set with exactly one event — so no stale key ever reaches a footer cell. All of it persists inside persistence.groupState: levels and aggregates share one key, one flag and one lifetime, and a blob stored before aggregates existed reads back as none configured. A declared grouping.aggregates with no grouping beside it is warned about and ignored.

Grouped columns leave the grid. An applied group level's column is removed from columns — its value lives in the caption row, not in a column repeating it on every member row — and a group bar above the header renders one chip per level with its label, its direction, and an ungroup action. This is unconditional; there is no option for it.

Re-nesting: drag a chip. Chips are draggable within the bar, and dropping one on the other side of a sibling re-nests the grouping — dragging Country before City turns City ▸ Country into Country ▸ City, with the captions, the effective sort and the projection all re-deriving. Alt+ArrowLeft/ArrowRight (or Ctrl+Shift+arrow, for window managers that swallow Alt+arrow) does the same from the keyboard, in the logical direction, with focus following the level it moved. A drop is setGroupState() with a reordered array and nothing else: no new API, no new event, and a drop that would not change the order emits nothing at all. It is not gated on columns.behavior.reorderable — that flag governs column order, not group state. Pointer and keyboard only; touch is not supported for this gesture.

The bar's trailing edge carries three text commands acting on the whole grouping — Expand all, Collapse all and Ungroup all — each one calling the public API (expandAllGroups(), collapseAllGroups(), clearGrouping()), so a bar click is indistinguishable from a host call or a header-menu click. Expand/collapse are disabled while the grouping is suspended (no captions to act on); Ungroup all never is. Their appearance is theme-owned via --vn-grid-group-bar-action-*.

• A grouped column is not "hidden": getHiddenColumns() never lists it, showAllColumns() never brings it back, and showColumn(key) returns false for it. ungroupColumn(key) is what restores it — at its original position, saved width, freeze state and column filter.
• Grouping a column that carries a user sort transfers that sort: the direction seeds the group level and the entry leaves the sort state (firing vn-grid-sort-changed), so the sort is never silently deleted along with the column. Ungrouping does not restore it — the chip is where that direction lives now.
• The Excel export re-composes the applied group columns back in, first and in group order, so a grouped grid never exports a sheet missing the field it is organised by. An explicit exportToExcel({ columns }) allow-list stays authoritative.
• A grouping that would leave no visible, non-internal column is refused with reason: 'no-visible-columns-left', from the predicates as well as the mutating calls, and the state is left unchanged.
• A suspended grouping (partial dataset) gives its columns back and keeps its chips in a suspended style, so removing a level never requires fixing the dataset first.
• A grid with no resolvable .vn-grid-table-container (hand-built markup) cannot mount the bar; it logs once and keeps its grouped columns visible. Grouping itself still works. The same applies to a partial bundle without features/grouping-bar.feature.js.

While grouped, a column filter on a grouped column stays applied but can only be edited by ungrouping first (its funnel icon left with the header). The toolbar's hasFilterOrSort predicate and clearColumnFiltersAndSorting command still see and clear it.

Web Component API

vanilla-grid-element.js exposes VanillaGridElement, registered as <vn-grid>.

Declarative Columns

Columns can be declared as child elements instead of (or as a fallback to) calling setColumns() imperatively:

<vn-grid id="myGrid" infinite-scroll="true" selection-mode="multiple" row-key-field="id">
    <vn-grid-column field="id"     label="ID"     width="60"></vn-grid-column>
    <vn-grid-column field="name"   label="Name"   width="200"></vn-grid-column>
    <vn-grid-column field="weight" label="Weight" secondary-label="kg" width="120"></vn-grid-column>
</vn-grid>

<vn-grid-column> attributes map directly to column definition properties: field (or key), label, width, secondary-label, is-key-column.

Observed Attributes

Element Properties

Element Methods

• initializeGrid(options) — Create an internal VanillaGrid instance bound to the element markup; returns the VanillaGrid instance
• attachGridInstance(instance) — Attach an externally created VanillaGrid instance to this element
• setDataManager(dm) — Attach a DataManager instance (OData, Static, or custom)
• getDataManager() — Returns the currently attached DataManager
• setGridOptions(options) — Merge reusable grid options without recreating the element markup
• reload(options?) — Re-query the attached DataManager via loadRowsAsync() and reset the scrollbars; pass { preserveScrollBars: true } to keep them
• refresh(options?) — Rebind every visible cell against the grid's current in-memory rows without querying the DataManager. Resets scroll position to the top-left by default; pass { preserveScroll: true } to keep it. Unlike reload(), never touches the network.
• loadRowsAsync() — Load rows (awaits ready() first; recommended entry point)
• setColumns(columns) — Push columns into the internal grid instance
• setData(rows) — Push rows into the internal grid instance
• setTheme(theme) — Update the theme attribute
• getGridElements() — Return internal DOM references used by VanillaGrid
• hideColumn(key), showColumn(key), showAllColumns(), getHiddenColumns(), canHideColumn(key) — Column visibility forwarded to the internal grid
• freezeColumn(key), unfreezeColumn(key), unfreezeAll(), isFrozenColumn(key), getFrozenColumns() — Column freeze forwarded to the internal grid
• getSelectedKeys(), getSelectedRows(), setSelectedKeys(keys), clearSelection() — Selection API forwarded to the internal grid
• groupByColumn(key, options?), addGroupLevel(key, options?), ungroupColumn(key), clearGrouping(), getGroupState(), setGroupState(state), expandGroup(path), collapseGroup(path), expandAllGroups(), collapseAllGroups(), canGroupByColumn(key), canAddGroupLevel(key), getGroupingStatus(), getAggregates(), setAggregates(state), getGroupAggregates(path), canAggregateColumn(key) — Row grouping API forwarded to the internal grid (see Row Grouping)
• clearPersistedSettings() — Wipe persisted layout settings and reset to declarative defaults. Always returns Promise<void> (regardless of the underlying provider). Dispatches vn-grid-persistence-cleared on success. Re-queries the DataManager afterwards only when the reset actually changed the query — an active column filter, an active search term, or server-sort. With none of those in effect the rows the grid already holds are the rows the cleared state describes, so the backend is never contacted; use the reload command when a re-fetch is what you want.

DataManager Hooks

The element has no fetch logic of its own — every load goes through the attached DataManager (see DataManager). A custom subclass overrides:

• buildRequestHeaders() — Return the headers object for row/count requests
• fetchRows() — Async row loader; return an array of row objects
• transformRows(rows) — Optional row post-processing before render
• onRowsLoaded(rows) — Side effects after rows are loaded
• handleSort(column, direction, sortState) — Receives grid sort events; server-side managers update their query here

Element Events

• vn-grid-attribute-changed — Fired when any observed attribute changes; detail contains { attribute, value, context }
• vn-grid-loading — Fired before rows are loaded
• vn-grid-loaded — Fired after rows are loaded successfully
• vn-grid-error — Fired when row loading fails
• vn-grid-busy-changed — Fired whenever isBusy() changes value, and only when it actually changes; detail contains { busy }. This is the whole busy lifecycle, which the three events above are not: they bracket a data fetch, while the grid is also busy whenever a large sort, group change or freshly-set dataset reorders behind the shimmer, and while an infinite-scroll page is in flight. Listen here — not to vn-grid-loading/vn-grid-loaded — for spinners, busy-gated controls and other "the grid is working" affordances; on a large grid vn-grid-loaded can arrive while the rows are still being reordered. A grid-level onBusyChanged(busy) callback is also available when using VanillaGrid directly
• vn-grid-persistence-cleared — Fired after clearPersistedSettings() finishes successfully
• vn-grid-group-changed — Fired whenever the requested group state changes, or on a suspend/resume transition over a partial dataset; detail: { groupState, active, reason }
• vn-grid-group-expanded / vn-grid-group-collapsed — Fired when a group caption is expanded/collapsed; detail: { path, groupKey, all, descendants }. all: false for a single group (expandGroup()/collapseGroup() or its toggle); all: true, with path and groupKey both null, once for a whole expandAllGroups()/collapseAllGroups() or the group bar's Expand all / Collapse all. descendants is 'collapsed'/'expanded' for a descendants call or a caption's Shift-click — one event however many groups changed, typed by the caption's resulting state (so a Shift-click on an open caption fires vn-grid-group-expanded) — and null otherwise
• vn-grid-selection-changed — Fired on the viewport element when selection changes; detail is the full selection payload (see Row Selection)
• vn-grid-row-dblclick — Fired when a row is double-clicked; detail contains { row, rowIndex }. Double-clicking a row does not alter its selection state
• vn-grid-load-more-failed — Fired every time an infinite-scroll "load more" page fetch fails; detail contains { error, failureCount, retryDelayMs }. The grid retries automatically with an exponential backoff (1 s doubling to a 30 s cap) and never gives up — a successful load or reloadDataManager() resets the backoff. A grid-level infiniteScroll.onLoadMoreError callback is also available when using VanillaGrid directly
• vn-grid-load-more-succeeded — Fired every time an infinite-scroll "load more" page fetch resolves and its rows are appended (even when the page is empty); detail contains { rows, loadedRowCount, hasMoreRows }. appendRows() itself dispatches no event and vn-grid-loaded only covers the initial load/reload path, so this is the signal to listen for if you need to reflect scroll-triggered pagination (e.g. a row-count status line). A grid-level infiniteScroll.onLoadMoreSuccess callback is also available when using VanillaGrid directly
• vn-grid-total-row-count-changed — Fired whenever the attached DataManager pushes a new total row count (initial load, then again after every reload/filter/search/sort change); detail contains { totalRowCount } (null when unknown)
• export-ready — Not emitted; exportToExcel() returns a Promise<void> (resolves once the file has been handed to the browser, rejects with a coded VanillaGridExportError)

Column Resizing

Real-time Feedback

During a column resize drag, the body columns update in lock-step with the header. Both the header and body tables are kept at an explicit pixel width matching the sum of all column widths, ensuring table-layout: fixed distributes space immediately on every animation frame.

Last Column

Every column — including the last — has a resize handle on its right edge. The last column resizes independently (not paired with a neighbour), so dragging its handle left shrinks it without affecting other columns. After release, the table width is recalculated:

• If all columns fit within the viewport → no horizontal scroll.
• If columns exceed the viewport → horizontal scroll is enabled automatically.

Resize Guide Overlay

A thin vertical guide line appears during column resize drag:

• Positioned at the center of the active resize handle.
• Height is scoped to the scrollable viewport (not the full container).
• Color uses mix-blend-mode: difference with a white base, making it always visible regardless of theme background.
• Hidden for the last column handle (where it would conflict with the horizontal scrollbar area).

Horizontal Scrolling

When the total column width exceeds the viewport, a custom horizontal scrollbar appears at the bottom of the grid. The header table stays aligned with the body during horizontal scroll via a GPU-accelerated transform: translateX() applied on every scroll event.

The custom vertical scrollbar remains active alongside the horizontal one. Both scrollbars are styled to match via CSS custom properties and WebKit pseudo-element rules.

Custom Scrollbars

The grid replaces native scrollbars with JavaScript-driven custom scrollbars (vertical and horizontal):

• Smooth thumb drag with a position indicator showing the current row range.
• Expand on hover/drag; collapse when idle.
• Styled via .vg-scrollbar-track, .vg-scrollbar-thumb, and .vg-scroll-indicator CSS classes — override in your theme file.
• Vertical custom scrollbar can be disabled per instance: layout: { customScrollbar: false }.
• The horizontal scrollbar is always custom when horizontal scroll is needed.

Column Reordering

Users can rearrange columns by dragging a header to a new position. A drop indicator line shows the insertion point.

Mouse Drag

Click and hold a header cell, then drag left or right. Release to drop.

Touch Reorder

On touch devices, press and hold a header for touchReorderHoldDelay milliseconds (default: 220 ms) to activate reorder mode, then drag.

Disable touch reorder with columns: { touchReorder: false }.

Frozen Column Boundary Enforcement

Frozen and unfrozen columns form separate groups. You can reorder within a group freely, but dragging across the frozen/unfrozen boundary is blocked. To move a column across the boundary, use the context menu to freeze or unfreeze it first.

Persistence

Column order is saved to localStorage automatically when persistence.columnOrder.enabled is true (default). The key is derived from the table/viewport/header element IDs and the page path, or can be overridden with persistence.columnOrder.storageKey.

Programmatic Reordering

grid.reorderColumn(fromIndex, toIndex, { dropBefore: true });

Column Visibility

Individual columns can be hidden and shown again without removing them from the column definition.

Context Menu

Right-click any column header to open the context menu. Select Hide column to hide the current column. If any columns are hidden, a Show all columns option appears to restore them all.

API

grid.hideColumn('weight');        // Hide by key
grid.showColumn('weight');        // Restore by key
grid.showAllColumns();            // Restore all hidden columns
grid.getHiddenColumns();          // ['weight', ...]
grid.canHideColumn('name');       // false when it is the last visible column

Behavior

• At least one data column is always visible — the last visible column cannot be hidden.
• Hiding a frozen column also unfreezes it automatically.
• The selection checkbox column is never hidden.

Persistence

Hidden column state is saved to localStorage when persistence.hiddenColumns.enabled is true (default). Override the key with persistence.hiddenColumns.storageKey.

Localization

messages: {
    hideColumn: 'Hide column',
    showAllColumns: 'Show all columns'
}

Column Freeze / Unfreeze

Frozen columns stay anchored at the left edge of the viewport and never scroll out of view horizontally. A blue vertical guide line marks the freeze boundary.

Context Menu

Right-click a column header to open the context menu. Select Freeze column to freeze it, Unfreeze column to release it, or Unfreeze all when multiple columns are frozen.

API

grid.freezeColumn('name');         // Freeze by key
grid.unfreezeColumn('name');       // Unfreeze by key
grid.unfreezeAll();                // Release all frozen columns
grid.isFrozenColumn('name');       // true / false
grid.getFrozenColumns();           // ['name', ...]

Behavior

• Frozen columns are always moved to the front (left side) of the column order, after the selection checkbox column if present.
• Multiple columns can be frozen simultaneously.
• The selection checkbox column is always implicitly frozen — it is never included in getFrozenColumns().
• Frozen header cells use a counter-translateX to cancel the header table's scroll shift, keeping them visually pinned.
• Body frozen cells use position: sticky with computed left offsets.

Persistence

Frozen column state is saved to localStorage when persistence.frozenColumns.enabled is true (default). Override the key with persistence.frozenColumns.storageKey.

CSS Custom Properties

Localization

messages: {
    freezeColumn: 'Freeze column',
    unfreezeColumn: 'Unfreeze column',
    unfreezeAll: 'Unfreeze all'
}

Multi-Column Sorting

• Click a header to cycle sort for that column: none → asc → desc → none.
• Shift+Click adds/removes a column in the active multi-sort chain.
• Sort priority follows the order in which columns are added to the chain.

Context Menu

Right-click a sortable column header to open the context menu. Select Sort ascending or Sort descending to sort by that column, or Clear sorting to remove just that column from the sort chain — each item disables itself when it no longer applies (e.g. Sort ascending is disabled once the column is already sorted ascending). These items only touch the clicked column's place in the sort chain, leaving any other column's sort untouched; they are omitted entirely for a column with sortable: false or when sorting.enabled is false.

// getSortState() return shape
{
    columnIndex: 1,       // Primary sort column index
    direction: 'asc',     // Primary sort direction
    column: { ... },      // Primary sort column object
    sortColumns: [        // Full multi-sort chain
        { columnIndex: 1, direction: 'asc',  column: { key: 'name', ... } },
        { columnIndex: 4, direction: 'desc', column: { key: 'weight', ... } }
    ]
}

For server-side / OData sorting:

const grid = new VanillaGrid({
    sorting: {
        serverSide: true,
        onSort: (_column, _direction, sortState) => {
            const orderBy = (sortState.sortColumns || [])
                .map(entry => `${entry.column.key} ${entry.direction}`)
                .join(', ');
            // Re-fetch with the new $orderby
            reloadWithOrderBy(orderBy);
        }
    }
});

Localization

messages: {
    sortAscending: 'Sort ascending',
    sortDescending: 'Sort descending',
    clearColumnSort: 'Clear sorting'
}

Row Selection

Modes

const grid = new VanillaGrid({
    selection: {
        mode: 'multiple',
        rowKeyField: 'id',          // Field used as stable key
        showCheckboxes: true
    }
});

Key Strategy (Precedence)

1. rowKeyGetter(row) — custom function, takes priority
2. Column marked with isKeyColumn: true in column definitions
3. rowKeyField option (default 'id')
4. Auto-generated UUID per row (fallback; a console warning is emitted)

Selection API

grid.getSelectedKeys();          // ['1', '42', ...]
grid.getSelectedRows();          // [{ id: 1, ... }, { id: 42, ... }]
grid.setSelectedKeys(['1', '2']); // Replace current selection
grid.clearSelection();
grid.isRowSelected(rowObject);   // true / false
grid.selectionState;             // 'none' | 'partial' | 'all'
grid.selectAllActive;            // true when sticky select-all is active

selectionChanged Event

Dispatched on the viewport element (bubbles):

viewport.addEventListener('selectionChanged', (e) => {
    const {
        mode,            // 'single' | 'multiple'
        selectionState,  // 'none' | 'partial' | 'all'
        selectAllActive, // boolean
        selectedKeys,    // string[]
        selectedCount,   // number
        selectedRows     // object[]
    } = e.detail;
});

Note: selectedKeys and selectedRows are lazy compute-once getters — the arrays are materialized on first access, so listeners that never read them cost nothing even with select-all active on large datasets. Read them within the event dispatch (as above) for values that match the change being reported.

rowDblClick Event

Dispatched on the viewport element (bubbles) when a row is double-clicked. Selection is not toggled by a double-click — the row keeps its current selected/unselected state.

Double-click detection uses pointerdown timing instead of the native dblclick event, ensuring reliable firing even when custom renderCell content (e.g. thermometer bars) replaces cell DOM between clicks.

viewport.addEventListener('rowDblClick', (e) => {
    const {
        row,       // object — the row data
        rowIndex   // number — index in displayRows
    } = e.detail;
});

On the <vn-grid> web component, this is bridged as vn-grid-row-dblclick:

document.querySelector('vn-grid').addEventListener('vn-grid-row-dblclick', (e) => {
    console.log('Double-clicked row:', e.detail.row);
});

Infinite Scroll + Select All

When all currently-loaded rows are selected (selectionState === 'all'), VanillaGrid sets a sticky select-all flag (selectAllActive). Any rows appended by subsequent infinite-scroll pages are automatically selected too.

Deselecting a single row in this state clears the sticky flag.

DataManager

The DataManager pattern decouples data fetching from grid rendering. Attach a DataManager to a <vn-grid> element with setDataManager().

Base DataManager API

Subclass DataManager and override any of these async methods:

Total row count is a push, not a method to override: call this._fireTotalRowCountChanged(count) from within fetchRows() (or wherever your subclass determines the total for its current query) — see Total Row Count.

ODataDataManager

A full-featured DataManager for OData endpoints.

const dm = new ODataDataManager({
    baseUrl: 'http://localhost:3000/api/items',
    countUrl: 'http://localhost:3000/api/items/$count',
    headers: { 'X-Custom-Header': 'value' },
    defaultOrderBy: 'name asc',
    defaultFilter: "active eq true",
    pageSize: 500,
    onSortChanged: (orderBy) => console.log('Sort:', orderBy),
    onRowsLoaded: (rows, ctx) => console.log('Loaded', rows.length),
    onFetchResponse: (response) => { /* inspect raw Response (headers, status) */ },
    onBeforeFetch: () => { /* e.g. clear a status line */ },
    onFetchError: (error) => console.error(error)
});

gridElement.setDataManager(dm);
gridElement.initializeGrid({
    infiniteScroll: { enabled: true },
    sorting: { serverSide: true },
    onTotalRowCountChanged: (count) => console.log('Total:', count)
});
gridElement.setAutoReloadOnConfigChange(true); // re-fetch page 0 on sort/filter/search
await gridElement.loadRowsAsync();

Server-side sort re-fetch: handleSort() updates $orderby and fires a config-change, so with setAutoReloadOnConfigChange(true) a sort re-fetches page 0 automatically — no onSortChanged reload callback needed (it is a notification-only hook). Without auto-reload, reload yourself (e.g. call loadRowsAsync() from onSortChanged).

Loading state is automatic: loadRowsAsync() brackets every load — the first one included — with setLoading(true/false) itself (error path included, guarded against superseded concurrent loads). Do not wire setLoading into onBeforeFetch/onFetchResponse/onFetchError; those are pure app hooks (status text, raw-Response inspection, error UI). onBeforeFetch/onFetchResponse fire once per user-visible load (fetchRows()), never per infinite-scroll load-more page (which has its own inline skeleton); onFetchError fires for load-more failures too.

Runtime OData methods:

dm.getBaseUrl() / dm.setBaseUrl(url)
dm.getCountUrl() / dm.setCountUrl(url)
dm.getOrderBy() / dm.setOrderBy(orderBy)
dm.getFilter() / dm.setFilter(filter)
dm.getSearchTerm() / dm.setSearchTerm(term)   // $search (default) or $filter contains()
dm.getSearchMode() / dm.setSearchMode(mode)   // 'search' | 'filter'
dm.getSearchFields() / dm.setSearchFields(fields)

Construct with searchMode: 'search' | 'filter' (default 'search') and, for 'filter' mode, searchFields: ['Name', 'City']. getSearchFields() returns null (unrestricted) unless searchMode: 'filter' is active and the list is non-empty — in 'search' mode the server owns $search's field scope, so the configured list is inert. See Generic Search.

GraphQLDataManager

A DataManager for GraphQL endpoints. GraphQL standardizes only transport and envelope (POST { query, variables } → 200 OK { data?, errors? } — a GraphQL error is an HTTP 200 with a populated errors array, not a 4xx/5xx), so this manager owns everything universal (transport, envelope/errors handling, cancellation, last-wins version guarding, total-count push, config-changed events, response unwrapping via a declared dot-path) while the host supplies the query document plus small builder hooks that translate grid state into the schema's variables. Two-tier config: declare variableNames for the common case, or pass buildVariables (which then fully owns assembly) plus the per-slice buildSort / buildFilter / buildSearch hooks. Supports both offset paging and Relay cursor paging (paginationStyle: 'offset' | 'cursor'), and a total from either an inline totalPath or a separate countQuery.

const dm = new GraphQLDataManager({
    endpoint: 'https://graphql.anilist.co',
    query: ANILIST_QUERY,
    paginationStyle: 'offset',
    pageSize: 50,
    infiniteScroll: true,
    dataPath: 'Page.media',                     // where the rows array lives in `data`
    totalPath: 'Page.pageInfo.total',           // inline total — no second request
    buildVariables: (state) => ({
        page: state.page, perPage: state.perPage,
        search: state.search, sort: state.orderBy, ...state.filter,
    }),
    buildSort: (column, direction) => [mapToMediaSort(column, direction)],
    buildFilter: (model) => mapToAniListArgs(model),
    onFetchError: (error) => console.error(error),
    onGraphQLErrors: (errors, data) => { /* default throws GraphQLDataManager.GraphQLError */ },
});

gridElement.setDataManager(dm);
gridElement.initializeGrid({
    infiniteScroll: { enabled: true },
    sorting: { serverSide: true },
    onTotalRowCountChanged: (count) => console.log('Total:', count)
});
await gridElement.loadRowsAsync();

Runtime methods: getEndpoint() / setEndpoint(url), getQuery() / setQuery(query), getSearchTerm() / setSearchTerm(term), getColumnFilters() / setColumnFilters(model), isInfiniteScroll() / setInfiniteScroll(enabled), getMaxRows() / setMaxRows(n).

A populated errors array throws GraphQLDataManager.GraphQLError (carrying .graphQLErrors) by default — even alongside partial data; a non-throwing onGraphQLErrors override tolerates partial data. In cursor mode the manager unwraps a Relay connection's edges[].node and reads pageInfo automatically. See GraphQLDataManager Internals and anilist-anime-js (AniList) for a working demo.

StaticDataManager

For pre-loaded in-memory datasets with client-side paging.

const dm = new StaticDataManager({
    rows: myDataArray,
    pageSize: 500
});

gridElement.setDataManager(dm);
gridElement.initializeGrid({ infiniteScroll: { enabled: true } });
await gridElement.loadRowsAsync();

Runtime methods: setRows(rows), getRows(), getPageSize(), setSearchTerm(term) / getSearchTerm(), setSearchFields(fields) / getSearchFields(), prewarmSearchIndex()

Pre-warming search (large datasets). On a large dataset the first search pays a one-time haystack extraction (later searches are instant). prewarmSearchIndex() builds that index ahead of time so the first search is a cache hit too. It's best-effort and idempotent, and nothing warms unless you ask it to.

The simplest way is to let the manager schedule it, via the prewarmSearchIndex option — right next to searchFields, which defines what the index covers:

const dm = new StaticDataManager({
    rows,
    searchFields: ['firstName', 'lastName', 'email'],
    prewarmSearchIndex: true        // default false
});

When on, the manager warms the index at idle after each row ingestion (construction with rows, and every setRows()), so the build lands after first paint and never competes with the initial render — the extraction is chunked and rAF-yielded, so running it during a render would steal frames from it. A bounded timeout means "at idle" can never become "never". Re-warming is cheap: the pre-warm resolves immediately while the index is resident, so only a genuine data or searchFields change costs anything.

Off by default — warming spends CPU and memory up front that is wasted on users who never search, so nothing happens unless you ask. It also only pays off at scale: below workerThreshold (50,000 rows) the build runs on the main thread and a first search over that many rows is fast anyway, so leaving it off is usually right for small datasets.

This is a StaticDataManager option, not a grid one — a server-backed manager searches remotely and has no local index to warm — so it also works for a manager used standalone, with no <vn-grid> attached. To control the timing yourself instead, leave it off and call the method directly:

gridEl.addEventListener('vn-grid-loaded', () => {
    requestIdleCallback(() => gridEl.getDataManager().prewarmSearchIndex());
});

Measuring the build (dev mode). Set window.VanillaGridDevMode = true — before the grid loads — and StaticDataManager emits console.info messages on the VanillaGrid: channel when it builds the search index:

VanillaGrid: search index build started — 500,000 rows × all fields (worker)
VanillaGrid: search index built in 5,182 ms — 500,000 rows × all fields (worker)

Each line names the row count, the searched fields and the path (worker or in-thread) — the three things that determine the cost — so you can confirm the pre-warm really starts early and see what scoping searchFields saves. A "started" line is only emitted when a build actually begins, never on an already-resident no-op, and a failed build reports its own outcome rather than leaving a dangling start line. The flag is off by default and there is no build-time dev/prod split, so production stays silent unless a host opts in. Only the pre-warm is instrumented — an index built lazily by the first search is not.

Search matches a case-insensitive substring against the raw field values. By default every scalar field is searched; pass searchFields: ['name', 'address.city'] (dotted paths allowed) to the constructor — or call setSearchFields(...) — to restrict the scope. Trigger from the element with await gridElement.search(term). getSearchFields() returns null when unrestricted — consumed by <vn-grid-toolbar-search> to show a fields-restricted tooltip, and by gridElement.getSearchFields().

Memory & performance on large datasets. For very large in-memory datasets (hundreds of thousands to millions of rows), two opt-in levers reduce client-side memory and first-search time without any cross-origin isolation:

• Set searchFields. All-fields search keeps a lowercased copy of every field of every row resident (and pays a large one-time build). Scoping to the columns users actually search cuts both roughly in proportion. When a search runs over a large dataset (≥ workerThreshold) with searchFields unset, the manager logs a one-shot console.warn advising you to set it.

• internStringColumns: ['department', 'city', …] deduplicates those low-cardinality columns' string values on ingestion so equal cells share one instance — reclaiming significant memory with no data-model change. Top-level fields only. Interns in place by default (the manager owns the rows it's given); pass copyOnIntern: true to intern into shallow copies instead.

  Pick columns that meet both conditions, or the pass costs time and reclaims nothing: the column must be low-cardinality (few distinct values) and must hold a distinct string instance per row. The second condition is the one that gets missed. It holds whenever rows are produced by a parser or by per-row computation — JSON.parse() of a fetched payload allocates a fresh string for every cell, which is the normal case for a StaticDataManager fed from a server, and the case this option is for. It does not hold when rows are built in-page by assigning values out of a shared lookup array or from string literals: those cells already point at one shared instance, so there is nothing left to dedup. Interning effectively-unique columns (IDs, emails, free text) is likewise wasted work — it builds a pool entry per row and never gets a hit.

  Measured on 500,000 rows of the grid-minimal-js shape, arriving via JSON.parse(): 207.8 MB retained with no interning, 124.8 MB with the seven low-cardinality string columns interned (a 40% reduction, one ~270 ms pass). The identical rows synthesized in-page from literal arrays instead show zero reduction from the same option, because they were already sharing instances.

const dm = new StaticDataManager({
    // Rows parsed from a server payload: every cell is its own string
    // instance, so the low-cardinality columns below dedup heavily.
    rows: await response.json(),
    searchFields: ['name', 'email', 'city'],
    internStringColumns: ['department', 'city', 'country', 'role'],
});

Viewport Row Snapping

When layout.snapViewportToRows is enabled (default), VanillaGrid snaps the viewport body height to the nearest lower multiple of the effective row height. This avoids partial-row viewport artifacts such as bottom-border misalignment and clipped-looking last rows.

• Recommended for fixed-row-height virtualized grids.
• Reapplies automatically on initial render, resize, and row-height remeasurement.
• Set layout: { snapViewportToRows: false } if you need unconstrained full-height fill.

Resize Scroll Stabilization

VanillaGrid includes guards to prevent resize-induced scroll feedback loops and accidental load cascades when the viewport height changes.

What this protects against:

• Continuous or jittery scrolling right after browser/container resize.
• Infinite-scroll prefetch loops triggered by resize-only geometry changes.
• Incorrect momentum-guard corrections caused by non-user scrollTop updates during resize.

Current behavior:

• A short resize phase is tracked internally while the viewport settles.
• During that phase, virtualization still re-renders, but uncontrolled-scroll rejection is bypassed.
• Infinite-scroll prefetch is paused until resize settle completes.
• When resize lands near the top, the viewport is normalized to true top (scrollTop = 0) so row 1 remains the first visible row.

Related tuning knobs: layout.rowHeight, layout.bufferRows, layout.snapViewportToRows.

Localization Hooks

VanillaGrid stays locale-agnostic by default and exposes formatting hooks so the host app can provide localization logic:

• formatting.locale — used by default Intl.NumberFormat behavior.
• formatting.messages — all built-in UI labels (context menu items, scroll indicator separator).
• formatting.formatInteger(value) — formats row counters.
• formatting.formatScrollIndicator(context) — fully custom indicator text formatter. context.firstRow/context.lastRow are positions in the full row order; with row grouping active a collapsed group's rows count as passed once its caption is passed, so the pair spans the range of the dataset the viewport represents rather than the number of rows physically on screen.
• onTotalRowCountChanged(count) — optional top-level callback fired whenever the total row count changes, to sync host-app status text.

Example:

const grid = new VanillaGrid({
    formatting: {
        locale: 'it-IT',
        messages: {
            of: 'di',
            hideColumn: 'Nascondi colonna',
            showAllColumns: 'Mostra tutte le colonne',
            freezeColumn: 'Blocca colonna',
            unfreezeColumn: 'Sblocca colonna',
            unfreezeAll: 'Sblocca tutto',
            sortAscending: 'Ordina crescente',
            sortDescending: 'Ordina decrescente',
            clearColumnSort: 'Rimuovi ordinamento'
        },
        formatInteger: (value) => new Intl.NumberFormat('it-IT').format(value),
        formatScrollIndicator: ({ firstRow, lastRow, displayedRowCount, totalRowCount, formatInteger, messages }) => {
            const denominator = Number.isFinite(totalRowCount) ? totalRowCount : displayedRowCount;
            return `${formatInteger(firstRow)} - ${formatInteger(lastRow)} ${messages.of} ${formatInteger(denominator)}`;
        }
    },
    infiniteScroll: {
        enabled: true
    },
    onTotalRowCountChanged: (count) => console.log('Known total:', count)
});

Keyboard Navigation

When the viewport is focused or hovered, the following keys scroll the grid:

Themes

The component includes eight pre-built themes in themes/:

Switching Themes

Via the web component (it swaps the injected theme stylesheet itself):

gridElement.setTheme('carbon-dark');

Creating Custom Themes

Copy themes/TEMPLATE-vn-grid-theme.css, override the CSS custom properties listed in the template, and register it with VanillaGridElement.registerTheme('mytheme', 'path/to/vn-grid-mytheme.css').

Sort Icons (required per-theme tokens)

The sort glyphs are theme tokens with no base default — every theme declares its own full set on .vn-grid-header-table th (a theme that omits them renders no sort glyphs at all):

.vn-grid-header-table th {
    --vn-grid-sort-icon-asc: '▲';               /* ascending glyph */
    --vn-grid-sort-icon-desc: '▼';              /* descending glyph */
    --vn-grid-sort-icon-sortable: none;         /* unsorted "sortable" affordance; none = off */
    --vn-grid-sort-icon-sortable-opacity: 0;    /* affordance resting opacity */
    --vn-grid-sort-icon-sortable-hover-opacity: 0; /* …while the header is hovered */
}

The affordance supports three modes per theme: off (none), hover-only (opacity 0 → 1 — the Carbon themes show a hover-only ⇅ with ↑/↓ direction glyphs; the Material theme shows an alphabetical "AZ" SVG glyph via content: url("data:image/svg+xml,…") — both triangles on hover, a single accent-colored triangle when sorted asc/desc, colors baked into the SVGs since url() images ignore currentColor), or always visible (resting opacity > 0). See 15-themes-implementation.md §4.5.1 for the full matrix and the migration note for pre-existing custom themes.

Header parts

The header label is one row: .vn-grid-header-text (with its sort indicator), then .vn-grid-header-secondary-text (e.g. [kg]), then, on an aggregated column, .vn-grid-aggregate-badge. In a narrow column the label ellipsizes first, then the secondary text; the badge never shrinks. The badge reads five optional tokens, each with a fallback:

.vn-grid-table-container {
    --vn-grid-aggregate-badge-color: inherit;
    --vn-grid-aggregate-badge-bg: color-mix(in srgb, var(--vn-grid-filter-accent) 16%, transparent);
    --vn-grid-aggregate-badge-radius: 999px;
    --vn-grid-aggregate-badge-padding-x: 5px;
    --vn-grid-aggregate-badge-font-size: 0.8em;
}

The badge and each group footer cell show the function as an icon: a masked SVG painted in the text colour, one token per built-in function. The defaults live in vanilla-grid.css; a theme overrides any of them with a 24×24, round-capped, stroke-width='2.5' SVG:

.vn-grid-table-container {
    --vn-grid-aggregate-icon-sum: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'><path d='M18 4H6l7 8-7 8h12'/></svg>");
    /* also -avg, -median, -min, -max, -countTrue, -countDistinct */
    --vn-grid-aggregate-icon-size: 1em;
}

See 15-themes-implementation.md §4.8.

Implementation Docs

For implementation-level details, see the technical docs. They are listed in the same reading order as 00-index.md's Documents section — foundations first, then the features that build on them.

• 00-index.md

Core engine

• 01-web-component-implementation.md
• 02-row-virtualization-and-custom-scroll-implementation.md

Data access

• 03-data-manager-implementation.md
• 04-row-key-management.md
• 05-infinite-scroll-implementation.md

Sorting, filtering, and column types

• 06-sorting-implementation.md
• 07-column-filters-implementation.md
• 08-date-time-types-implementation.md

Row interaction

• 09-selection-implementation.md
• 10-keyboard-navigation-implementation.md

Column management

• 11-column-resizing-implementation.md
• 12-columns-reordering-implementation.md
• 13-column-visibility-implementation.md
• 14-column-freezing-implementation.md

Presentation

• 15-themes-implementation.md
• 16-localization-implementation.md

Export

• 17-export-to-excel-implementation.md
• 18-excel-export-theming-implementation.md

Persistence, delivery, and performance

• 19-local-storage-settings-implementation.md
• 20-cache-bust-implementation.md
• 21-performance-analysis.md

Row grouping

• 22-grouping-implementation.md

Browser Support

• Chrome / Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: Latest 2 versions

Performance

• Handles 100,000+ rows smoothly with recycled row pool virtual scrolling
• Real-time column resize feedback via explicit pixel-width table-layout: fixed
• GPU-accelerated header horizontal sync (transform: translateX) — no reflow on scroll
• DocumentFragment-based pool initialization — single DOM insertion per rebuild
• RequestAnimationFrame-based scroll rendering with threshold-based short-circuit
• Infinite-scroll prefetch at 30% of page size remaining — preloads the next page without waiting for the user to reach the absolute end
• O(1) row key lookups via internal Map for selection state

License

MIT

Contributing

Contributions are welcome! Please ensure:

• Code follows existing style
• All features are documented
• Performance is maintained

Changelog

Version 1.40.0

• Changed (vanilla-grid) — breaking for exportToExcel() callers using format, xlsxWorkerUrl or SheetJS globals: the Excel export no longer uses SheetJS. The grid writes the .xlsx itself, streaming rows in short chunks into a writer that compresses the sheet XML with the browser's native CompressionStream('deflate-raw'), in the warm export Worker from workerThreshold rows and on the main thread (same writer, still chunked) below it or with useWorker: false.
  • Why. A large export froze the page and then failed. On grid-minimal-js with 21 columns, SheetJS hit RangeError: Invalid array length above about 140,000 rows (its ZIP output went through a JS array with one element per byte), and the coordinator then retried the whole export synchronously on the main thread, freezing the tab for about 100 s before failing the same way. At 300,000 rows the tab crashed. Cell styling was not the cause: an unstyled export failed identically.
  • Result, same machine and dataset: 100,000 rows in about 3 s instead of 40 s, 14 MB instead of 92 MB, about 500 MB peak memory instead of 1.9 GB, and no main-thread task over 50 ms. 1,000,000 rows now export in about 30 s. Rows past Excel's 1,048,575-row sheet limit continue on sheets named '<sheetName> (2)', …, each with its own header, frozen pane and AutoFilter.
  • No main-thread retry. A Worker that ran and failed now rejects at once instead of repeating the export synchronously.
  • Coded failures. exportToExcel() rejects with a VanillaGridExportError (new in vanilla-grid.d.ts) whose code is EXPORT_FAILED (cause holds the reason), EXPORT_TOO_LARGE (a sheet would pass the ZIP format's 4 GiB entry limit, only reachable with about 90+ columns at a full sheet; carries rows, columns), EXPORT_CANCELLED, or EXPORT_IN_PROGRESS (a second call while one runs on the same grid). A failure turns the overlay into an alertdialog that says why, with a Close button (Escape closes it) instead of silently disappearing; overlayThreshold: Infinity leaves the rejection to the host.
  • Progress and Cancel. The overlay shows Exporting to Excel… {n}% and a Cancel button on both the Worker and main-thread paths; the Worker stays warm for the next export.
  • iOS. When navigator.share() rejects with NotAllowedError because the user activation expired during a long export, the overlay offers a Save file button instead of doing nothing. Not yet verified on a device.
  • Fixed along the way. Date and datetime columns now carry the documented yyyy-mm-dd / yyyy-mm-dd hh:mm:ss formats; SheetJS silently replaced them with the locale's short date, dropping the time. Cell values and date serials are unchanged.
  • Removed. The format option ('csv' and 'ods' existed only through SheetJS): a leftover format other than 'xlsx' exports .xlsx and logs one warning. Also removed: xlsxWorkerUrl, window.VanillaGridXlsxURL, window.VanillaGridBaseURL, the XLSX global, features/xlsx-js-style.bundle.min.js and the exportRequiresXlsx message. Every page load sheds about 425 KB (142 KB gzipped) of script, and the components contain no third-party code. Migration: drop format / xlsxWorkerUrl; code that read window.XLSX must bring its own copy.
  • styleHeaderCell / styleDataCell and the static style options keep the same object shape (VanillaGridExportCellStyle); only the documented subset (font, fill, border, alignment, numFmt) is honoured.
  • New message keys: exportingToExcelProgress, exportCancel, exportClose, exportTooLarge, exportFailed, exportSaveFile.
  • A host that registers its own exportToExcel toolbar command should return the export's promise, so the toolbar can ignore a cancel and log real failures; every sample now does.
  • build.js: features/excel-export.feature.js joins BUNDLE_FAST_PATH (its per-cell loop is a hot path); the SheetJS copy and bundle steps are gone. See Export to Excel.
• Maintenance (vanilla-grid, sample apps, eslint.config.js, package.json, .claude/ agent commands): a unit test now pins the aggregate walk to one visit per row; the README's cost figure for recomputing aggregates per selection was corrected against current measurements; the performance analysis was updated for the export rewrite; the SheetJS lint globals and coverage exclusion were removed; every sample gained the new export message keys; shipped feature specs were cleaned out of specs/.

Version 1.39.1

• Fixed (vanilla-grid): the vertical scrollbar thumb now re-sizes immediately after expandAllGroups(), collapseAllGroups(), expandGroup() / collapseGroup(), a caption toggle, and a setGroupState() that re-nests the same levels (e.g. Country ▸ City → City ▸ Country), instead of keeping the previous projection's size until the next scroll. The vertical track hides or reappears in the same pass when the collapsed groups fit in the viewport, or stop fitting after an expand. A thumb drag started right after one of these gestures no longer jumps the grid in the wrong direction.
• Maintenance: package.json version bumped to 1.8.1.

Version 1.39.0

• Added (vanilla-grid): group aggregates — a named reduction over one column's values, rendered into a group footer row under each group at each level. Seven functions ship built in, offered by the column's declared type: sum, avg, median, min, max on number; min/max also on date/datetime/time (reporting the winning row's raw value); countTrue on boolean (through booleanCoerce); countDistinct on every type but boolean, counting with grouping's equality. Hovering an aggregated footer cell names the function in full ("Average of Projects: 14.165"). Nothing renders until a column carries one: a grouped grid with no aggregate is exactly the grid it was.
  • Configuration. grouping.aggregates: [{ key, fn }] declaratively (a default, not a lock — the user's choice persists and wins afterwards, and clearPersistedSettings() restores the declaration); setAggregates(state) at runtime, returning { available, reason } over a closed reason-code set; or the header menu's new "Aggregate ▸" submenu, present on every column's menu whatever the grid state and disabled with an explained title when it cannot act. fn is always a registered reducer name, so the configured set is plain serializable data in every direction.
  • Reading it back. getAggregates(), getGroupAggregates(path) (one group's computed values by column key, taking expandGroup()'s path shape), and canAggregateColumn(key) — an O(1), row-scan-free predicate returning { available, reason, functions }. New vn-grid-aggregates-changed event, fired once per settled change; a superseded recomputation emits nothing of its own — the set it installed is announced by whichever operation settles.
  • Extending it. Static VanillaGrid.registerAggregate(name, reducer) takes the same { init(context), step, finalize, types } shape the built-ins have, so a host reducer passes the same column.type eligibility gate, plus optional prepare(context) (a per-row mapper factory) and resultType: 'count'. New .d.ts types VanillaGridAggregateReducer and VanillaGridAggregateContext; VanillaGridAggregateValues values are unknown.
  • Lifetime. An aggregate belongs to the grouping session: it is discarded when the last group level goes, retained (but not editable) through a partial-dataset suspension, and pruned when setColumns() removes, renames or retypes its column — each settling persisted and announced with exactly one event. It persists inside the existing persistence.groupState flag: levels and aggregates share one key and one lifetime, and a value stored before aggregates existed reads back as none configured with no migration.
  • An aggregate and a group level never share a column. setAggregates() refuses one the grid is grouped by ('column-grouped'), and grouping by an aggregated column prunes that aggregate.
  • Auto-fit sizes an aggregated column from its computed totals rather than from whichever footer rows are materialized, so the fitted width is the same from any scroll position.
  • Eight new --vn-grid-group-footer-* tokens across all eight themes, the theme template and the sample's vn-grid-apple.css; new localizable aggregateFunctionLabels / aggregateFunctionMarkers maps and six aggregate* message scalars. New features/header-menu-submenu.feature.js provides a general submenu mechanism the menu's other entries can reuse.
  • Header badge. While a column's footer cells show a total, its header shows the footer's marker as a pill after the secondary header text (.vn-grid-aggregate-badge, with data-fn), and the th's title names the function. The footer is often scrolled out of view, and the header never is. It follows every settled change to the set, including the ones no setAggregates() call made, hides while grouping is suspended, and updates in place without rebuilding the header. Not interactive: a click is a header click. Five new --vn-grid-aggregate-badge-* tokens, all with fallbacks, set by all eight themes, the template and vn-grid-apple.css.
  • Marker icons. A built-in function's marker, in the footer and the badge, is a masked SVG (.vn-grid-aggregate-icon, data-fn) drawn from seven --vn-grid-aggregate-icon-* tokens plus --vn-grid-aggregate-icon-size, declared in vanilla-grid.css and overridable per theme; font glyphs came out too heavy or off-centre in some themes. Visible in forced-colors mode. messages.aggregateFunctionMarkers is now empty by default: an entry replaces the icon with text, which is also how a registered function gets a marker, and '' still hides it.
  • Auto-fit fits a string aggregate result (e.g. a registered most-common-value function) to the longest result, not the first group's.
  • grid-minimal-js ships Sum of Projects and Average of Height over its Country ▸ City grouping, and registers two custom functions, stdev (σ) and mode (Mo), as working registerAggregate() examples.
  • Not in v1: count, a grand total, group footers in the Excel export, server-side aggregation, cross-column formulas, per-column function sets, and selection-scoped values. See the feature's section above.
  • See docs/vanilla-grid/22-grouping-implementation.md §5.2 and docs/vanilla-grid/19-local-storage-settings-implementation.md §6.7.
• Changed (vanilla-grid) — breaking for custom themes and for columns using unit: the text after a header label is called secondary header text everywhere, as the public API already called it (column.secondaryLabel, formatting.getHeaderSecondaryText).
  • The CSS class .vn-grid-unit-label is renamed .vn-grid-header-secondary-text, with no alias. Migration: rename the selector in any custom theme.
  • The undocumented column.unit alias for column.secondaryLabel is gone, from the default getHeaderSecondaryText and from the Excel export's header. <vn-grid-column unit="…"> is now an ignored attribute. Migration: use secondaryLabel / secondary-label.
  • In a narrow column the secondary text now ellipsizes instead of running on under the filter funnel.
• Changed (vanilla-grid) — breaking for custom themes that set the group toggle tokens: the group caption's expand/collapse marker is now a masked SVG painted in currentColor (like the aggregate marker icons) instead of a ▾/▸ font glyph, so its weight and centring no longer depend on the theme's font — it sat small and low in Carbon dark. --vn-grid-group-toggle-icon-expanded / -collapsed now take an SVG url() used as a mask, defaulting to a down / right chevron; a string value renders no marker. --vn-grid-group-toggle-icon-size is now the icon box's width and height (same 1em default). The collapsed icon is mirrored in RTL, and the marker paints ButtonText in forced-colors mode. The default and Glow themes show filled triangles and the Carbon themes a boxed minus / plus (at 1.2em) instead of chevrons. Migration: set the two tokens to a url("data:image/svg+xml,…"), or delete the declarations to get the default chevrons.
• Added (vanilla-grid): fold or unfold the groups below a caption in one step. Shift-click or Shift+Enter on a caption with child groups opens it and switches everything below it between all folded and all open; the first Shift-click on a caption shows it as a summary of its folded child groups. From code, expandGroup(path, { descendants }) / collapseGroup(path, { descendants }) set a group and its whole subtree in any combination, all or nothing (refused past the cardinality ceiling). One vn-grid-group-expanded / -collapsed per call, whose detail gains descendants ('collapsed' / 'expanded', null on every other event). New message groupCaptionToggleHint (the toggle's hover hint), and aria-keyshortcuts="Shift+Enter" on toggles that offer it.
• Fixed (vanilla-grid): hovering a group caption showed a tooltip repeating its own label ("City: Amsterdam — 5 items"). The overflow-tooltip pass took the label, which deliberately runs past its cell, for truncated text. Caption cells no longer get one.
• Fixed (vanilla-grid): the secondary-label attribute on <vn-grid-column> was ignored. It now maps to secondaryLabel, so anilist-anime-js's Duration [min] and Score [0–100] headers, and their Excel export, show their secondary text.
• Fixed (vanilla-grid): auto-fit sized a header for the wider of its label and its secondary text, as if they sat on separate lines. They share one row, so every column with secondary text was fitted too narrow ("Temperature [°C]" came out as "Temp…"). It now sums label, secondary text and aggregate badge, counts the label's 2em ellipsis floor, and measures the secondary text at the theme's own font size. Applies to autoFitColumn(), autoFitAllColumns() and the resizer double-click.
• Fixed (vanilla-grid): expandAllGroups() / collapseAllGroups() (and the group bar's Expand all / Collapse all) now reach nested groups under a collapsed parent. Before, expandMode: 'collapsed' needed one click per level, and a Collapse all skipped the children of an already-collapsed parent. The result is now the default state for groups that appear later, until the grouping is cleared. Each effective call fires exactly one vn-grid-group-expanded / vn-grid-group-collapsed with all: true, path and groupKey null. Before, it fired nothing, despite the documentation.
• Fixed (vanilla-grid): setColumns() left the rows in the order the old column definitions produced when a new definition changed how a sorted or grouped column orders (its accessor, type, null placement, temporal parsing, boolean coercion or sortFields). A grouped grid then showed one value as several captions. setColumns() now re-applies the ordering, only when a column the active ordering uses actually orders differently, so a call that changes nothing about ordering stays free. A custom sorting.compareValues reading a display-only property, or anything outside the column, can't be detected; re-sort with sortColumns().
• Maintenance: people-cities-js (isNumericColumn reads secondaryLabel only), .d.ts comments for secondaryLabel and getHeaderSecondaryText; build.js bundles the new aggregate-registry.js and header-menu-submenu.feature.js, with the reducers on the fast (hot-path) profile; eslint.config.js lints the benchmark scripts under specs/; playwright.config.js gains a firefox-keyboard project for the caption's Shift+Enter; grid-minimal-js registers two custom aggregates (stdev, mode) and uses the new toggle markers.
• Fixed (vanilla-grid): an aggregate change arriving while a group change was still deferred behind the loading skeleton superseded it, building the new levels' projection over the old row order — one caption per contiguous run of a value instead of one per group. The two now coalesce into a single settled pipeline, and neither loses the other's change event.
• Fixed (vanilla-grid): the header menu's aggregate submenu read the configured set as it stood when the menu was built, so a set changed by host code while the menu was open showed a stale check mark and could be overwritten by a later pick. It is now resolved when the flyout opens and again when an item is activated.
• Fixed (vanilla-grid): a group change overtaken by a header sort, a setRows() reload or an appendRows() before it settled was never persisted or announced — a page reload restored the previous grouping, the toolbar missed vn-grid-group-changed, and a 'too-many-groups' rejection stayed on screen unreported. It now settles when the overtaking operation finishes: persisted, announced once, and rolled back on too-many-groups. An aggregate change overtaken the same way is likewise persisted and announced once, by whichever operation settles.
• Fixed (vanilla-grid): a second setAggregates() while a group change was still deferred no longer loses the group ordering (captions split per contiguous run).
• Fixed (vanilla-grid): a group change rejected for too many groups no longer leaves behind an aggregate set that a joined setAggregates() installed. A restored flat grid clears the set; a restored grouping keeps only the entries that still fit it, and announces only a net change.
• Fixed (vanilla-grid): column keys and reducer names such as __proto__, constructor or toString no longer break getGroupAggregates() or pick up inherited footer labels and markers.
• Fixed (vanilla-grid): expanding or collapsing one group no longer costs as much as expanding every group. A caption toggle, or expandGroup()/collapseGroup() on a visible group, now splices that group's rows in or out of the projection instead of rebuilding it, so its cost follows the group's size, not the dataset's (~0.6 s → a few tens of ms at a million rows). Every group-boundary scan — Collapse all, a group change, sort, filter or search — finds each group's end with a galloping search instead of comparing every row. Toggling a group whose parent is collapsed only records the new state. A custom sorting.compareValues must be a consistent ordering; grouping relies on it.
• Fixed (vanilla-grid): an expandGroup(), caption toggle or expandAllGroups() refused because it would cross the too-many-groups ceiling now leaves the collapse state untouched. Before, the group was recorded as expanded while its caption still showed it collapsed.

Version 1.38.0

• Added (vanilla-grid): opt-in search-match highlighting. New highlightSearchMatches option / highlight-search-matches attribute (off by default) wraps every occurrence of the active search term inside a visible cell's formatted text in <mark class="vn-grid-search-match">. New per-column column.highlightSearchMatches: false opts a single column out (e.g. an id column where a coincidental numeric substring match would be noise) while the grid-wide flag stays on.
  • Purely a visual re-match computed at render time from the active search term and each cell's already-formatted text — decoupled from however the attached DataManager decided a row matched, so it works identically for StaticDataManager, ODataDataManager, and GraphQLDataManager, including rows arriving via infinite-scroll "load more". A row can therefore match with no cell highlighted (matched a hidden field, a raw value differing from its formatted text, or a server's fuzzy/stemmed ranking) — expected behavior for a visual affordance, not proof of match.
  • New base CSS rule in vanilla-grid.css tokenizes six independent visual aspects (--vn-grid-search-match-bg/-color/-weight/-radius/-shadow/-decoration), each with a neutral/off default. Every built-in theme (and TEMPLATE-vn-grid-theme.css) sets its own effect: flat accent-tint fills for default/material/fluent, the same plus squared corners for fiori/carbon/carbon-dark, and a shadow-based glow (transparent background, accent text, box-shadow) for glow/glow-dark.
  • grid-minimal-js and people-cities-js (both grids) now ship with highlight-search-matches on; grid-minimal-js's id column demonstrates the per-column opt-out.
  • See docs/vanilla-grid/02-row-virtualization-and-custom-scroll-implementation.md §1.17 and docs/vanilla-grid/03-data-manager-implementation.md §11.5.

Version 1.37.0

• Added (vanilla-grid, events): vn-grid-busy-changed — fired whenever isBusy() changes value, and only when it actually changes. Detail is { busy }. Registered as VanillaGridEvents.BUSY_CHANGED, with a matching onBusyChanged(busy) grid option for callback-style hosts.

  This is the whole busy lifecycle, which vn-grid-loading / vn-grid-loaded are not: those bracket a data fetch, while the grid is also busy whenever a large sort, group change or freshly-set dataset reorders behind the shimmer, and while an infinite-scroll page is in flight. Use the new event for anything that tracks whether the grid is working — spinners, busy-gated controls, "please wait" affordances.

• Fixed (vanilla-grid, loading lifecycle): the end of a busy window that no fetch closed was previously unobservable. setRows() raises the deferred reorder's shimmer before the element emits vn-grid-loaded, so a host that greyed itself out on the load pair saw the grid as busy at the exact moment it was told the load had finished — and the shimmer's release fired nothing at all, so it stayed that way. Every load above sortShimmerThreshold on a sorted or grouped grid was affected, including the initial one.

• Maintenance (grid-minimal-js, tests): the sample now persists the whole view rather than half of it. Its persistence override is gone, so sort state and the filter model join the layout and group domains already stored under storage-mode="local" — the declared group-by / sort-by become defaults for a first visit only. The selected theme and row count are the sample's own state and cannot ride on the component's persistence, so a new prefs.js stores them under a grid-minimal-js: key prefix that both in-toolbar selectors read while building their dropdowns; the theme is restored during parsing, before <vn-grid> upgrades. ?rows= still overrides the stored row count, so the Playwright suite can pin a dataset size. New grid-minimal-js-persistence.spec.js covers both stores.

Version 1.36.1

• Fixed (vanilla-grid, row grouping): grouping a large grid no longer spends the whole reorder looking finished and wrong. The chip appeared at once, and then the grid kept showing the ungrouped rows — grouped column still in place, no captions and no shimmer — until everything changed in one frame about a second later (1279 ms of it at 1,000,000 rows, 97 ms at 300,000). Two independent causes, both now fixed:
  • The visible column set was re-derived at the very end of the group change, behind the reorder, though it depends on nothing the reorder produces. It is now re-derived up front, in the same frame as the chip, so the grouped column leaves the grid with the chip that grouped it. The tail-end re-derivation is kept, because it is what restores the column when a too-many-groups abort reverts the state.
  • A viewport resize during a load re-rendered real rows over the raised loading skeleton and never put it back. Mounting the group bar resizes the viewport, so every grouped reorder above sortShimmerThreshold destroyed its own shimmer ~25 ms in. A resize while loading now re-paints the skeleton at the new size instead, which fixes the same collision for a window resize, a container settling or a theme swap during any load — not only grouping's. The first paint of a group gesture moves from ~5 ms to ~70 ms, because the column set is now re-laid-out before the skeleton goes up.
• Behaviour change (vanilla-grid, getVisibleColumns() / columns): on a grid above sortShimmerThreshold, code that reads the column set synchronously after groupByColumn() / setGroupState() now sees the post-group column set, where it previously saw the pre-group one until vn-grid-group-changed fired. No signature changed.

Version 1.36.0

• Fixed (vanilla-grid, clearPersistedSettings()): resetting the layout no longer freezes the tab. On a 1,000,000-row grid the toolbar's reset command blocked the main thread for about four seconds; it now blocks for about 0.7 s, and 300,000 rows went from 1102 ms to 224 ms. The reset was reordering the same dataset repeatedly and rebuilding the million-entry selection key map twice, with the last and largest reorder running fully synchronously — no shimmer, no sort Worker — while an eligible Worker sort it had already dispatched was thrown away. Four changes, each removing one whole pass:
  • <vn-grid>.clearPersistedSettings() now re-queries the DataManager only when the reset actually changed the query (an active column filter, an active search term, or server-sort). See the behaviour note below.
  • When a reload is needed, the in-memory reset no longer reorders ahead of it: the declarative sort and grouping stay parked and the reload's own setRows() consumes them, so the dataset is ordered once.
  • setRows() routes its ordering through the shared reorder bracket (runReorderPipeline()) instead of sorting in-thread, so a large reload gets the shimmer and, when the sort is worker-eligible, the off-thread path. Below sortShimmerThreshold it stays synchronous, and a load with nothing to order skips the bracket entirely, so small grids keep their exact previous timing and synchronous post-conditions. This benefits every large reload — the reload command, a filter change, a search — not only the reset.
  • setColumns() rebuilds the selection key map only when the resolved key column actually moved (or no map exists yet). Re-applying an unchanged declaration spent ~750 ms producing an identical map.
• Fixed (vanilla-grid, row grouping): the grouping projection was being built twice per grouped reorder — once by the internal displayRows writer and once by the reorder's own completion step. The writer now does the zero-allocation re-alias only, and leaves the build to the reorder. Worth ~600 ms per grouped reorder at a million rows, on every grouped sort and every group change.
• Added (vanilla-grid): a deferToReload option on clearPersistedSettings(), mirroring the existing option of the same name on clearSort() — clear the sort and group state and re-park the declarative ones without applying them, because a coordinated reload is about to order every row anyway. Declared in vanilla-grid.d.ts.
• Behaviour change (<vn-grid>.clearPersistedSettings()): a reset with no column filter, no search term and no server-sort no longer issues a DataManager request. Hosts that relied on reset doubling as a "refresh everything" button see one fewer request; the reload command is the correct button for that. vn-grid-persistence-cleared still fires either way, and the return type is unchanged. With infinite-scroll enabled the skipped reload means an already-loaded prefix is kept rather than snapping back to page one — reset is a layout reset, not a data reset.
• Behaviour change (vanilla-grid, setRows()): at or above sortShimmerThreshold rows with an active sort or grouping, setRows() now returns before displayRows is ordered and the grid shows its shimmer in the interval. Callers that read displayRows synchronously after a large load must wait for vn-grid-loaded. Unsorted loads and every grid below the threshold are unaffected.

Version 1.35.2

• Fixed (vanilla-grid, row grouping + viewport sizing): the last row of a grouped grid is reachable again. The group bar's height was missing from _computeAvailableViewportHeight(), so the row snap pinned the viewport to an inline height one bar taller than the space left for it and the container's overflow: hidden clipped a strip just under one row tall — the scrollbar reported "fully scrolled" with the final row painted below the visible edge. The bar is now subtracted alongside the header spacer, and it is registered with the grid's ResizeObserver so showing, hiding, or wrapping it to a second line re-snaps the viewport — without moving the scroll position, which the resize path would otherwise snap back to the first row. This also corrects the values that read through _getViewportHeight(): vertical scrollbar metrics, page-up/page-down stepping, and the scroll indicator's visible-row count. No public API change.
• Fixed (vanilla-grid, autoFitColumn() / autoFitAllColumns()): auto-fit no longer measures group caption rows. A caption puts its whole label (Country: Australia — 85 items) into the toggle cell and lets it overflow across the rest of the row by design, so measuring it sized that one column to hold a country name — 210px instead of 90px for an ID column — and made the fitted width depend on which captions happened to be materialized, and therefore on the scroll offset. Caption rows are now skipped, matching the guard measureActualRowHeight() already applies in the height dimension. Affects every auto-fit entry point (header menu, resize-handle double-click, the toolbar's autoFitAllColumns command, and the programmatic API). No public API change.

Version 1.35.1

• Fixed (vanilla-grid, row grouping): freezing columns no longer shifts every group caption to the right. The caption toggle (.vn-grid-group-toggle) is now always placed in the first visible non-internal column; it previously moved to the last frozen column whenever a freeze was configured, so applying a freeze pushed the whole group hierarchy right by the width of the frozen run and unfreezing snapped it back. The toggle stays pinned while scrolling horizontally exactly as before — frozen columns are a contiguous leading run, so the first column is itself frozen whenever any freeze exists. The placement cell now carries a vn-grid-group-toggle-cell class that lifts it above the frozen cells its label overflows across, which would otherwise repaint over the caption and clip it at the freeze boundary. No public API change.
• Maintenance (grid-minimal-js): the sample's in-toolbar theme and row-count selectors now grey out in place for the grid's busy window instead of hiding themselves, so a multi-second load (re-grouping and re-sorting 1,000,000 rows after the toolbar's reset command) no longer empties out the middle of the toolbar row. The busy signal still comes from the toolbar's state.busy, and the guard against starting a switch mid-load is unchanged.

Version 1.35.0

• Added (vanilla-grid, row grouping): client-side, multi-level row grouping. Runs of equal values collapse under a nested, collapsible caption row carrying the value and an exact member count, and it composes with sorting, filtering, selection, freeze and Excel export. Public API: groupByColumn(columnKey, { direction }) (establish or replace a single-column grouping), addGroupLevel(columnKey, { direction }) (append a level), setGroupState(state) / getGroupState() (read or write the whole ordered chain), clearGrouping(), expandAllGroups() / collapseAllGroups(), and the canGroupByColumn(columnKey) predicate. The four state-changing calls and the predicate all return a VanillaGridGroupCapability — whether the grouping is (or would be) applied plus a machine-readable reason — so a caller is never left guessing why a request was refused; 'too-many-groups' is only ever produced by an operation, never by the predicate. Configure via the grouping option group (grouping.columns, grouping.expandMode, grouping.showCount) — with the requested state persisted via persistence.groupState, on by default — or declaratively with the group-by attribute on <vn-grid> (e.g. group-by="country:asc, city:desc"). New events: vn-grid-group-changed, vn-grid-group-expanded, vn-grid-group-collapsed. Grouping is reason-coded and disabled over a partial (infinite-scroll) dataset rather than being silently wrong.
• Added (vanilla-grid, group bar): each applied group level's column leaves the grid — its value lives in the caption — and becomes a chip in a grid-owned group bar above the header, carrying the level's sort direction and an ungroup action, with "Expand all" / "Collapse all" / "Ungroup all" commands at the strip's trailing edge. Chips can be dragged within the bar (or moved with Alt+arrow) to re-nest the levels. Ungrouping restores the column at its original position, width, freeze state and filter. <vn-grid> always supplies the strip; hosts using VanillaGrid directly can pass one as the groupBar element or let the grid create it. New messages keys cover the bar and the header-menu items ("Group by this column", "Add to grouping", "Remove from grouping", "Ungroup all") including the reason-coded disabled-item titles.
• Maintenance (vanilla-grid, grid-minimal-js, docs, tests): grouping brought supporting work across the grid — the shared reorder pipeline that sorting and grouping now both use, group-aware render projection and virtual pooling, persistence of the requested group state, theming for the caption and bar across every bundled theme, and a ?group=none switch in grid-minimal-js for specs that need the flat grid. Documented in docs/vanilla-grid/22-grouping-implementation.md.

Version 1.34.0

• Fixed (vanilla-grid, sorting): the precomputed-key sort path — the Schwartzian O(n) key extraction that keeps Date parsing, String() allocation and locale lookup out of the O(n log n) comparison loop — never ran in a real grid. applySorting() selected it by testing whether the injected compareValues was callable, but the grid resolves that option to the host's function or to its own bound built-in, so it was always callable: every client-side sort took the raw-value pairwise path and paid an extra hop per comparison through VanillaGrid.prototype.defaultCompareValues. Path selection now uses hasCustomCompareValues, the flag derived from options.sorting.compareValues and already the authority for the same decision in _isWorkerSortEligible(). A host-supplied comparator keeps the pairwise path and its contract (raw cell values plus the real column object) exactly as before. Measured ~5.9x faster on a 300k-row in-thread sort in an --obfuscate build.
• Fixed (vanilla-grid, grouping): _scanLevel()'s group-boundary scan called the comparator once per row through the public grid.compareValues, which — absent a host override — only forwards to the sorting feature's built-in. It now resolves through _effectiveCompareValues() and calls that built-in directly. Ordering semantics are unchanged (it is the same function); a grouped rebuild of 300k rows measured ~3x faster in an --obfuscate build.
• Changed (vanilla-grid, build): the compiled column accessors (column._getValue) and the tri-state boolean coercion moved out of vanilla-grid.js into a new shared column-access.js (window.VanillaGridColumnAccess). Both run once per row on every render, sort, group-boundary scan and export, and build.js's BUNDLE_FAST_PATH can only exempt whole files from the heavy obfuscator profile — so a hot helper inside vanilla-grid.js could not be exempted at all. vanilla-grid.js binds both at load time and keeps an inline fallback for partial bundles. No public API change.
• Fixed (vanilla-grid, worker sort): a search, filter, reload or append landing while a deferred sort is in flight can no longer leave the grid showing rows it does not have. VanillaGrid#setRows() / #appendRows() replace or extend the dataset a running reorder was computed against, and on the Worker path that reorder resolves a precomputed array whose elements were read out of the row array captured at dispatch — so its late reply overwrote the correct, freshly-filtered displayRows with rows drawn from an array the grid no longer referenced, breaking the invariant that displayRows is a permutation of rows (a search narrowing 200,000 rows to 15,062 could leave 200,000 on screen, 184,938 of them foreign, under a status bar reading "Loaded 15,062/15,062"). Both row-mutation sites already funnel through bumpDatasetVersion(), which now supersedes any in-flight reorder as well as invalidating the Worker's key cache — so the reload's own synchronous re-sort stands, a chunked extraction still running is abandoned at its next yield, and a future row-mutation site inherits the guard by calling the method it must call anyway. Because a row-data change is not a reorder, the pipeline now also tracks whether it raised the loading state and clears it when superseded this way, so a host calling setRows() directly with no surrounding load lifecycle cannot strand the shimmer; ownership is what is tested, never isLoading, so the progressive-chunk load path (loadDataInChunks()) still shimmers across its chunks. No public API, option, attribute, persisted-state or .d.ts change.
• Fixed (vanilla-grid, worker sort): an off-thread sort can no longer order rows by a column definition that has since been replaced. The persistent sort Worker caches each column's precomputed sort keys, and the main thread tracked which columns it held with a boolean residency map keyed by column.key and invalidated only by bumpDatasetVersion(). Because setColumns() recompiles _getValue/_sortGetters/_sortFieldTypes without notifying the sorting feature, a grid could sort a large dataset by a column, then receive a different column under the same key — a changed field / valueGetter / sortFields, or merely a changed type or booleanCoerce — and the next eligible worker sort would send "reuse what you already have" and get back rows in the wrong order. Residency is now decided per column by a signature covering everything that determines the cached bytes: the dataset version, the identity of the compiled accessor, and the type / booleanCoerce that encode its values — the same design the filter Worker already used (StaticDataManager#_computeColumnSignatures()). Signatures are committed only after the message carrying the values has been posted, which also closes two races by construction: a setColumns() landing mid-extraction can no longer have its stale values re-marked resident by the in-flight pass, and concurrent sorts can no longer claim residency for a column not yet sent (previously a sort worker cache miss and a silent fall back to the in-thread path). Reuse is unchanged where it was correct — a direction toggle, adding a tiebreaker, or sorting by A, then B, then A still extracts nothing. No public API, option, attribute, persisted-state or .d.ts change.
• Changed (vanilla-grid, worker sort): a sort superseded while its main-thread extraction is still running now abandons the pass instead of finishing it. runReorderPipeline() threads its _sortGeneration token into _sortViaWorker() as a liveness predicate, re-checked after every chunk yield; an abandoned pass posts no message, bumps no sequence, and leaves no residency claim. A rapid sequence of header clicks over a dataset above SORT_EXTRACTION_CHUNK_SIZE (100,000 rows) no longer runs several full O(n) extraction passes to completion for results that are all discarded but the last. The Worker's own scan of an already-posted message still cannot be un-posted and runs to completion off-main-thread, as before.
• Changed (vanilla-grid, worker sort + filter/search offload): both chunked main-thread extraction passes now yield through one shared primitive, the new main-thread-yield.js (window.VanillaGridYield). The sort side previously yielded on requestAnimationFrame, which resolves at a frame boundary and caps a pass at one slice per frame regardless of slice length — roughly a 30% duty cycle. It now uses the same fast-macrotask ladder (scheduler.yield() → MessageChannel → setTimeout) the filter side already used, which keeps the same slice length while raising the duty cycle to ~98%, so a large first-ever sort by a new column spends its wall clock working rather than waiting. StaticDataManager moved its own copy of the implementation into the shared module; dom-scheduler.js keeps requestAnimationFrame, which is correct for paint-aligned work. Internal utility only — nothing added to the public API or the .d.ts files.

Version 1.33.3

• Fixed (vanilla-grid, row-height auto-measurement): body rows no longer come out at a different height on some page loads than others. The grid corrects rowHeight upward by measuring a rendered row, but that measurement could run before the base stylesheet (vanilla-grid.css) had applied — the row then reported the height its unstyled line-height: normal produces, which is both too tall and dependent on the platform's fonts. Because .vn-grid-body-table td takes its height from --vn-grid-row-height and a table row can only grow past that minimum, the inflated value pinned the rows to itself, so every later measurement read it back and confirmed it for the rest of the session. The base sheet is requested before the theme sheet but is several times the size of one, so it regularly resolves second — Firefox lost this race often enough to show visibly different row heights across reloads of grid-minimal-js (37px vs. up to ~59px on SAP Fiori), while Chromium happened to win it almost every time. The post-load resync now waits for the base stylesheet as well as the theme's, and re-measures from the baseline (the explicit layout.rowHeight, or the theme's declared --vn-grid-row-height) rather than from the standing correction, so the measurement is idempotent and recovers in both directions. This also closes a smaller mismatch where rowHeight could sit 1px below the real rendered row (e.g. 36 vs. 37 on Material) and quietly skew the virtual scroller's spacer maths — rowHeight now always equals the rendered row height. No public API, option, attribute or persisted-state change; measureActualRowHeight() gains an internal { fromBaseline: true } option used only by the resync path, leaving the render hot path's cost unchanged. Guarded by tests/playwright/theme-load-row-height-race.spec.js, which forces both stylesheet orderings and pins the recovery (verified to fail against the previous implementation).

Version 1.33.2

• Fixed (vanilla-grid, autoFitColumn / autoFitAllColumns): auto-fit no longer freezes the page on grids with many columns. _measureColumnFitWidth measured one string at a time — append a hidden probe <span> into the live th/td, read its getBoundingClientRect(), remove it — so every read followed a write and forced a full synchronous re-layout of the table, once per cell. On the 25-column northwind-orders-js sample (51 pool rows) one autoFitAllColumns() drove ~2000 forced reflows and blocked the main thread for ~1.5s with zero frames painted: the grid appeared hung, then snapped to the fitted widths. Measurement now runs in three phases — append every probe span, read every rect plus the sort-indicator offsetWidth, cell widget rects and computed styles in one pass, then detach and compute — collapsing roughly one reflow per cell into one per column. Measured 1514.8ms → 352.9ms (4.3x) on that sample, with all 25 header and body <col> widths byte-identical to the previous implementation. No public API, option, event or persisted-state change: autoFitColumn and autoFitAllColumns keep their signatures, return values and fitted widths. The internal _measureSpan singleton is replaced by a reused span pool (N probes are now live at once), and the internal _measureTextWidth helper is removed as unused. Guarded by a new tests/playwright/autofit-performance.spec.js (800ms budget, verified to fail against the previous implementation) and an idempotence test in tests/playwright/autofit.spec.js pinning that a probe span never perturbs a neighbouring measurement.

Version 1.33.1

• Maintenance (people-cities-js, build.js, playwright.config.js, docs/testing-and-coverage.md, tests/): sample-app, build and test tuning only — no component source touched. people-cities-js now points at the project's own hosted backend, MINT (Measurement INterface Translator) at https://people-cities-app.mthome.org, instead of http://localhost:3000: state.js's BFF_BASE_URL is renamed MINT_BASE_URL and ships the hosted URL as written, so a fresh clone runs the sample with no backend to start locally. build.js loses the FILE_REPLACEMENTS table and the per-file string substitution it drove in buildFiles() — the only entry rewrote that localhost URL at build time, which meant the source and the deployed build disagreed about the endpoint. The app's README gains a "The backend: MINT" section describing the BFF's unit-environment translation (X-MU-Environment) and its $metadata unit/decimal declarations.
• Maintenance (tests/, playwright.config.js): de-flaked three specs that were fetching a live third-party service purely to populate a grid. search-term-persistence, filter-panel-localization and theme-applies-on-load asserted on persistence, i18n labels and theming respectively, never on Northwind's data, but Northwind's tail latency under concurrent queries combined with full-suite worker contention could push search-term-persistence past its 30s row wait — a failure that never reproduced in isolation. They now use a new tests/playwright/_northwind-stub.js route handler serving canned rows that honour $top / $skip and the contains() disjunction the grid emits in searchMode: 'filter'; no assertion was weakened. _helpers.js's BACKEND_URL_PATTERNS was repointed at the MINT host so bootGrid's backend-blocking route still matches, and INSTRUMENTATION_SENSITIVE_SPECS now names every spec that lets a remote service respond (adding people-cities-js-smoke, wikipedia-pages-js-smoke, late-children-framework-integration and sample-search-box) rather than only the two third-party ones. New people-cities-js-smoke.spec.js is the deliberate live-backend exception: an end-to-end check that the sample still works against the real MINT instance.

Version 1.33.0

• Added (vanilla-grid, temporal columns): new shared temporal parser features/datetime.feature.js, exposed as window.VanillaGridDateTimeFeature. date, datetime and time columns previously had four independent new Date(value) call sites — cell formatting, the two sorting paths, and the data managers' filter predicates — which could disagree about the same malformed cell. All of them now route through one parser with an explicit { ok, kind, numeric, raw } envelope that distinguishes null from invalid instead of silently collapsing both. Public API: parseDateValue / parseDateTimeValue / parseTimeValue / parseTemporalValue, compareTemporalValues, formatTemporalValue, and the isDateType / isDateTimeType / isTimeType / isTemporalColumn guards.
• Added (vanilla-grid, column options): sourceFormat ('auto' | 'epochMs' | 'epochSec' | 'strict-pattern'), inputPattern, nulls ('first' | 'last') and timeZone on VanillaGridColumnDef. sourceFormat: 'strict-pattern' with an inputPattern such as 'DD/MM/YYYY' gives locale-ordered feeds a deterministic parse; patterns use fixed-width YYYY MM DD HH mm ss SSS tokens, reject out-of-range values instead of rolling them over (31/02/2026 is invalid, never March 3rd), and fall back to 'auto' with a console warning when a pattern contains an unrecognized token.
• Changed (vanilla-grid, sorting): temporal ordering is now bucketed — nulls, values, then invalid — honouring the new column.nulls. The default 'first' reproduces the previous hardcoded nulls-first ordering exactly, so no existing grid changes order unless it opts in.
• Changed (vanilla-grid, parsing): locale-ambiguous strings such as 03/04/2026 are now reported as invalid rather than silently resolved by engine-specific heuristics (which produced March 4th on some inputs and Invalid Date on others, depending on the day number). ISO 8601 with 1 to 9+ fractional-second digits is accepted and truncated toward zero to milliseconds, so .NET DateTime "O" round-trip timestamps (1960-08-07T14:10:08.2353749Z) parse. Bare finite numbers remain epoch milliseconds. What instant an accepted value resolves to is unchanged.
• Fixed (vanilla-grid, formatValue / _formatByType): the per-column Intl.DateTimeFormat cache now also invalidates on column.timeZone, and type: 'time' columns render a formatted clock value instead of falling through to the raw source string.
• Changed (vanilla-grid, StaticDataManager filter Worker): temporal filter operands and boxed temporal row values are now resolved to epoch numbers on the main thread (_packCondition, and a numeric sidecar from _packColumnValuesChunked) before postMessage. The Worker — a separate realm that cannot reach the shared parser — no longer parses date strings at all, so a filter can no longer return different results depending on whether the worker offload engaged.
• Maintenance (people-cities-js, northwind-orders-js, github-repos-js, wikipedia-pages-js, github-repos-react, wikipedia-pages-vue, northwind-orders-angular): the seven hand-rolled detail-panel date formatters now delegate to formatTemporalValue, gaining the per-column Intl cache they lacked. people-cities-js's panel had no temporal branch at all, so BirthDate rendered as the raw wire string; its Hometown object also rendered as a JSON.stringify dump and now reuses the Cities grid's composite presentation via a shared formatHometownValue() in modules/utils.js.
• Maintenance (vanilla-grid, documentation): docs/vanilla-grid/'s 22 documents are now NN--prefixed in a defined reading order — core engine, data access, sorting/filtering/column types, row interaction, column management, presentation, export, then persistence and performance — so the folder lists in that order. 00-index.md's Documents section groups them under those headings, and performance-analysis.md, previously listed nowhere, is included. Every reference was updated in step (component and sample READMEs, source comments, tests, CLAUDE.md), including four comments that pointed at a cache-bust-spec.md that has never existed. build.js's generated docs site (dist/docs/index.html) now sorts each group by file name rather than by page title, so it lists the documents in the same order.

Version 1.32.1

• Fixed (vanilla-grid, column resizing): manually dragging a column that is both sortable and filterable could shrink it past the point where its header still fits — the sort chevron and the filter funnel would overlap and paint on top of each other. The header CSS already reserved space for the funnel (th:has(.vn-grid-filter-icon) .vn-grid-header-label padding-right), and autoFitColumn already measured that reserve correctly, but manual drag-resize used a flat, DOM-independent _getMinColumnWidth() floor of 60px regardless of what the header actually needed. Columns with both affordances now get a 96px floor instead — derived from the same header chrome autoFitColumn measures (padding, ellipsis-floor text box, indicator, funnel reserve) — so manual dragging can no longer push the header into the collision. No public API change; column.minWidth, when explicitly set, still overrides this floor as before. See docs/vanilla-grid/11-column-resizing-implementation.md §5.1.

Version 1.32.0

• Added (vanilla-grid, infinite scroll): a position-independent busy signal for load-more fetches. The grid now toggles a vn-grid-loading-more class on its container for the whole duration of a page fetch, and paints a small role="status" banner ("Loading more rows…") pinned to the bottom edge of the viewport. Previously the only load-more affordance was the skeleton rows at the tail of the data — scroll up mid-fetch and nothing on screen said the grid was still loading, even though isBusy() returned true. The banner does not occlude the rows underneath (a load-more append leaves them valid) and needs neither a <vn-grid-toolbar> nor layout.customScrollbar to work. The banner waits out the same infiniteScroll.shimmerDelay grace period as the tail skeleton rows, so a fast backend paints neither and a negative shimmerDelay still means "no built-in load-more affordance"; the vn-grid-loading-more class is never delayed, so a host indicator can be instant. New messages.loadingMore key (default 'Loading more rows…', .d.ts updated); new styling hooks .vn-grid-loading-more, .vn-grid-load-more-banner, .vn-grid-load-more-banner-shimmer, .vn-grid-load-more-banner-text.
• Fixed (vanilla-grid, infinite scroll): load-more skeleton rows were inserted before the bottom spacer row, i.e. immediately after the virtual pool window rather than after the last row of the dataset. Those coincide only while the user sits at the tail; scrolling up moved the skeleton block into the middle of the data, where _rotatePool()'s own insertBefore(rowEl, bottomSpacerRow) interleaved recycled data rows through it — the reported "only half the rows shimmer, with real rows below them". The skeletons are now appended past the bottom spacer, which also keeps their extra height out of the per-row offset arithmetic. Rendering at the tail (the only position that triggers a load) is unchanged. No API change.
• Fixed (vanilla-grid, infinite scroll): scrolling up during the shimmerDelay grace period no longer yanks the viewport back to the bottom when the timer fires. The auto-scroll that reveals the skeleton rows is now gated on the viewport still being near the end of the loaded data; the scrollbar drag-to-bottom hold is unaffected, since a thumb pinned at the end of the track satisfies the same check.
• Maintenance (people-cities-js, northwind-orders-js, github-repos-js, wikipedia-pages-js, wikipedia-pages-vue, anilist-anime-js, github-repos-react, northwind-orders-angular): added the gridLoadingMore string (en-US / it-IT) to each app's i18n bundle and wired it to the grid's messages.loadingMore.
• Maintenance (vanilla-grid, all nine sample apps, build.js, playwright.config.js, eslint.config.js, docs/, tests/): every sample app folder renamed from the numbered sample-frontend-N scheme to a descriptive <domain>-<framework> name (e.g. sample-frontend-2 → northwind-orders-js, sample-frontend-9 → northwind-orders-angular), so a framework port now sorts next to the plain-JS app it mirrors and adding a tenth sample needs no renumbering. Every path reference, spec filename, <title>, and localStorage key prefix was updated to match; no component API or behaviour changed.

Version 1.31.1

• Maintenance (vanilla-grid): test and tooling pass across both suites — new Node unit coverage for the interaction feature's scroll arithmetic (wheel normalization, scroll-delta clamping, the momentum guard, near-bottom and horizontal-overflow detection) and for ODataDataManager's $filter operator/literal serialization; new Playwright specs for the custom scrollbars (including the previously untested horizontal scrollbar) and the wheel gesture state machine. No behaviour change from this bullet. Also removed stale working-notes references from the theme stylesheets' comments.
• Fixed (vanilla-grid, hideColumn() / showColumn() / showAllColumns()): changing which columns are visible while the grid was scrolled dumped the user back up the list. Rebuilding the virtual row pool momentarily empties the spacer rows, which collapses the scroll surface and makes the browser clamp scrollTop; the code that pre-sized the spacers to prevent that had never run, because it looked the two cells up by class names (vn-top-spacer / vn-bottom-spacer) that no spacer has ever carried — the real cells are held as grid references and their shared class is vn-grid-row-spacer-cell. Measured on a 400-row grid, hiding a column from a scroll offset of 3000 px landed at 1278 px; it now stays at 3000 px. No API change.
• Removed (vanilla-grid, columns feature): getHiddenColumnKeys(). It was a bare alias for getHiddenColumns() that returned exactly the same array, was never delegated onto VanillaGrid or <vn-grid>, was absent from vanilla-grid.d.ts and from every README, and was called by nothing but a unit test. Migration: none for hosts — the method was unreachable through any supported surface; use getHiddenColumns(), which is unchanged.

Version 1.31.0

• Removed (vanilla-grid, <vn-grid>): getMetadata() and the metadata field of the lifecycle-event/DataManager context object. Both were dead: the backing _metadata field was only ever initialised to null and never assigned anywhere in the codebase, so getMetadata() always returned null and context.metadata was permanently null for every host listener. The README described getMetadata() as returning "a snapshot of element attributes and context", which it never did. Hosts needing to attach their own data to the context should use the host sub-bag (context.host.*), which is the supported pass-through and is unchanged. Migration: delete any getMetadata() call — it can only have been returning null; read context.host instead of context.metadata.
• Fixed (vanilla-grid, TypeScript declarations): vanilla-grid.d.ts had drifted from the runtime in three ways, all of which broke TypeScript hosts. VanillaGrid.unfreezeAllColumns() was declared but does not exist — the method is unfreezeAll(), so a typed call compiled and then threw at runtime. VanillaGridElement.setRows() and setMetadata() were declared but never implemented — the element's method is setData(). And eleven implemented public element methods were missing declarations entirely (hideColumn, showColumn, showAllColumns, getHiddenColumns, canHideColumn, freezeColumn, unfreezeColumn, unfreezeAll, isFrozenColumn, getFrozenColumns, attachGridInstance), so working calls were compile errors. No runtime behaviour changed; docs/ was already correct throughout. A new tests/node/dts-conformance.test.js now cross-checks every declaration in all three .d.ts files against the corresponding prototype, in both directions, so this class of drift cannot recur.
• Maintenance (vanilla-grid, vanilla-grid-toolbar, vanilla-resize-box, tests/, build/tooling): test-infrastructure work with no component behaviour change. npm test now runs the Node unit suite and the Playwright suite (previously Playwright only, so 666 unit tests were skipped by anyone running the documented command); new test:unit, test:e2e, test:coverage and test:coverage:e2e scripts; coverage instrumentation for both suites with ratcheting thresholds; a GitHub Actions workflow running lint, unit tests and build. Thirteen files were normalised from CRLF to LF and pinned with a new .gitattributes. Test coverage was raised across the previously thin modules — odata-data-manager (65 → 97% lines), excel-export-delivery (49 → 100%), columns-reorder, columns-resize, interaction-keyboard, the toolbar's command/status/format API and <vn-resize-box>.resize().

Version 1.30.3

• Fixed (vanilla-grid, header rendering): narrowing a column past a certain point made its header show more characters and drop the ellipsis entirely — Active degrading to A… and then to Acti, Act, Ac, and finally to a blank header. CSS Overflow lets an engine fall back to clip when there is no room to paint the ellipsis, and Firefox takes that option once the text box is narrower than one glyph plus U+2026; Chromium keeps painting the ellipsis, so the defect was invisible in a Chromium-only test matrix. .vn-grid-header-text now carries a min-width: 2em floor that keeps the box above that threshold (font-relative, because the threshold is font-dependent — SAP 72 renders the ellipsis alone at a full 14px). No public API change. A sorted column whose label is narrower than 2em now renders its sort chevron up to 2em from the text rather than hard against it; a theme overriding min-width on .vn-grid-header-text re-opens the defect.
• Maintenance (grid-minimal-js): demo-app tuning only, no component source touched. The salary and bonus columns now pass formatOptions: { minimumFractionDigits: 0, maximumFractionDigits: 0 } so currency renders as whole numbers (display only — sorting, filtering and Excel export still see the full figure); the star-rating column is pinned at 130 px with resizable: false and exposes its numeric value as a cell title tooltip, which the clipped-star rendering alone can't convey; and the in-toolbar theme and row-count selectors now share one 190 px shell so the two dropdowns line up and the widest row-count label stops being clipped.
• Maintenance (grid-minimal-js, people-cities-js, wikipedia-pages-js, docs/vanilla-grid/15-themes-implementation.md, tests/): sample-app and guard tuning only, no component source touched. grid-minimal-js's frontend-local Apple theme was missing the five required --vn-grid-sort-icon-* tokens and so rendered no sort glyph at all; it now declares them (macOS convention — a thin ⌃/⌄ chevron on the active sort column only, nothing on unsorted columns at rest or on hover), overrides --vn-grid-filter-icon / --vn-grid-filter-icon-active with SF Symbols' line.3.horizontal.decrease in place of the base funnel, and stops painting the row-hover tint behind the empty-data message. The static guard tests/node/sort-icon-theme-tokens.test.js — which previously scanned only src/vanilla-grid/themes/, which is why the gap shipped — now also scans hand-authored samples/<app>/themes/vn-grid-*.css (generated dist/, vendor/, public/ trees excluded), so any theme registered via VanillaGridElement.registerTheme() from a sample app owes the same token set; the theming doc records that the obligation is on the stylesheet, not on where it lives. people-cities-js's People grid and wikipedia-pages-js's pages grid no longer ship columns frozen by default, and the three Playwright specs that leaned on those defaults (freezing, pool-rotation, reorder-frozen) now establish their own frozen set via freezeColumn().

Version 1.30.2

• Fixed (vanilla-grid, autoFitColumn() / autoFitAllColumns()): auto-fitting a filterable column left its header still ellipsized. The header measurement reserved a flat 22px for the sort indicator against roughly 45px of real chrome — the .vn-grid-header-label padding-right that holds the filter funnel (th:has(.vn-grid-filter-icon)) plus the indicator and the header-text wrapper's flex gap — so every such column was fitted about 23px too narrow and a user who explicitly asked the grid to fit a column got Act… back. Both reserves are now read from the live DOM, the same way the th padding already was, so a theme that restyles them (e.g. the Material indicator box) stays measured correctly. No public API change: signatures and options of autoFitColumn / autoFitAllColumns are untouched, but auto-fitted filterable columns are now visibly wider.
• Fixed (vanilla-grid, auto-fit header measurement): the fitted width is now rounded up with a 1px cushion. The text measurement is fractional, so a column could settle a fraction of a pixel under what its own label needed and ellipsize anyway — a sub-pixel shortfall that integer scrollWidth/clientWidth comparisons cannot detect. Residual truncation remains possible where auto-fit does not govern the final width: a column pinned at the dynamic maxWidth cap, and, under stretch-to-fit, a column the redistribution pass settles below its fit width.

Version 1.30.1

• Fixed (vanilla-grid, StaticDataManager search/filter extraction): the chunked haystack and column-value passes yielded through requestAnimationFrame, which capped them at one batch per frame regardless of batch length — a ~5ms batch followed by a ~11ms wait, i.e. a ~30% duty cycle, so most of a large search-index build's wall clock was the main thread sitting idle. They now yield through the fastest available cooperative channel (scheduler.yield(), else a MessageChannel macrotask, else setTimeout). Measured on a 300,000-row, 21-field pack: 2.49s → 1.07s (~2.3x) at a ~98% duty cycle, with the same batch length, so responsiveness is unchanged. A pre-warm also no longer stalls indefinitely in a backgrounded tab (requestAnimationFrame stops firing when a tab is hidden). No public API change and no change to search results.
• Fixed (vanilla-grid, StaticDataManager search/filter extraction): a slice is now bounded by elapsed time (5ms, probed every 256 rows) as well as by its row count, so very wide rows or an expensive filterValueGetter can no longer overrun a frame — a row count is only a proxy for cost. Measured on a pathological 4,000-row x 300-field dataset: one 116ms blocking slice before, a 14.1ms worst case after. The row caps remain the upper bound, and search haystack blob boundaries are unchanged (the Worker addresses rows by fixed blob stride, so a budget-triggered yield never closes a blob early).
• Fixed (vanilla-grid, StaticDataManager survivor-subset search): a search over a column-filtered subset no longer waits for an in-flight full-dataset search-index pre-warm when packing the subset itself is cheaper. Below one eighth of the dataset it packs immediately instead of inheriting the whole remaining warm — previously a 60,000-row survivor set on a 5,000,000-row dataset could wait tens of seconds for a warm it barely benefited from. Results are identical on either path.
• Changed (vanilla-grid, StaticDataManager searchFields advisory): the "searching every field of N rows" warning now also fires when prewarmSearchIndex() starts a real build, not only on the first search. With pre-warming the all-fields extraction happens at load, so a search-only advisory arrived after the cost was already sunk — or never, for hosts whose users don't search. Still one message per dataset version, and still silent when searchFields is configured.
• Documented (vanilla-grid, StaticDataManagerOptions.internStringColumns): the option's precondition is now stated wherever it is described (component README, 03-data-manager-implementation.md §5.3, the .d.ts and the constructor JSDoc). Interning only reclaims memory for a column that is low-cardinality and holds a distinct string instance per row — the latter true of rows from JSON.parse() or per-row computation, false when a field is assigned out of a shared lookup array or a string literal, where every row already references one shared instance. Listing columns that fail either test costs an ingestion pass and reclaims nothing, which the previous "low-cardinality columns" wording did not convey. Adds the measured comparison (500,000 rows: 207.8 MB → 124.8 MB when parsed from a payload, versus no reduction at all for the same rows built in-page) and records why the option lives on StaticDataManager rather than the server-paged managers. No behavior change.
• Maintenance (grid-minimal-js): the demo now scopes free-text search with searchFields covering 10 of its 21 columns (id, firstName, lastName, email, country, city, department, role, manager, notes) instead of indexing all 21, roughly halving its search-index build and resident haystack memory. All columns remain independently filterable.
• Maintenance (grid-minimal-js): the demo now also sets internStringColumns: ['manager'], trimming ~16 MB from a 500,000-row run. manager is the only column that qualifies — it is built by concatenation, so every cell is a separate allocation despite ~572 distinct values, whereas the demo's other low-cardinality columns come straight out of literal arrays and are already shared instances. Commented in place so the app is not read as endorsing a column list that would be wrong for server-fed data.

Version 1.30.0

• Added (vanilla-grid, StaticDataManagerOptions.prewarmSearchIndex): the manager can now schedule its own search-index pre-warm. Set prewarmSearchIndex: true and it calls prewarmSearchIndex() at idle after every row ingestion (construction with rows, and each setRows()), so the one-time haystack extraction lands after first paint instead of on the user's first keystroke — no host wiring. Deferred to idle (a bounded requestIdleCallback timeout, setTimeout fallback) so the chunked extraction never competes with the initial render; strictly === true, default false, and re-warming while the index stays resident is an idempotent no-op.
• Added (vanilla-grid, window.VanillaGridDevMode): opt-in development-only diagnostics. With the global set to true, StaticDataManager emits console.info messages on the VanillaGrid: channel when it builds the search index — a start line and an elapsed-time line, each naming the row count, the searched fields and the worker/in-thread path. Emitted only when a build actually begins (never on an already-resident no-op), with a failed build reporting its own outcome. Off by default, so production stays silent.
• Removed (vanilla-grid, VanillaGridElement.prewarmSearchIndex()): the element-level delegate is gone — call gridEl.getDataManager().prewarmSearchIndex() or use the new prewarmSearchIndex option instead. The index is a StaticDataManager asset (server-backed managers search remotely and have nothing to warm), so the option and the method now live on the one surface that owns it, and both work for a manager used standalone with no <vn-grid> attached.
• Fixed (vanilla-grid, VanillaGridOptions.dataLoading): the documented dataLoading option threw "unknown option" when passed to initializeGrid(). The element forwards its whole options bag to the VanillaGrid constructor, which did not list dataLoading among its valid keys; it is now accepted (and ignored) there, since the forced-skeleton and Worker-offload mechanisms it drives live at the element level.
• Maintenance (grid-minimal-js): the 500k-row demo now enables prewarmSearchIndex: true on its StaticDataManager and sets window.VanillaGridDevMode = true, replacing its hand-rolled vn-grid-loaded + requestIdleCallback pre-warm listener.

Version 1.29.1

• Fixed (vanilla-grid, StaticDataManager column filters, Web Worker path): switching an existing filter on a numerically-packed column (number/uid/ date/datetime/time) to a type-agnostic unary operator (isEmpty, isNotEmpty, isTrue, isFalse) silently dropped matching rows. The Worker kept the column's numeric packing, in which empty values are NaN and can never satisfy an emptiness test. The same stale-payload reuse also affected a column type change over unchanged fields.
• Fixed (vanilla-grid, StaticDataManager.setFilterValueGetters(), Web Worker path): swapping a column's value getter for a different function left the Worker filtering against values extracted by the previous getter, returning stale results. Getter identity is now part of the column's residency signature.
• Changed (vanilla-grid, StaticDataManagerOptions.searchFields): the one-shot "searching every field of a large dataset" advisory now triggers at a fixed 50,000-row threshold instead of tracking workerThreshold, so it is no longer silenced by disabling the Worker offload (workerThreshold: false) — a host that does so pays the same all-fields cost on the main thread.
• Performance (vanilla-grid, StaticDataManager search over filtered data): a survivor-subset search now addresses the Worker's resident full-dataset haystack by row index instead of repacking survivor haystacks on every filter change, and the two are held in independent slots so a filtered search no longer evicts the full-dataset index. A prewarmSearchIndex() investment therefore survives filtered sessions, and clearing filters while a search is active is a cache hit rather than a full re-extraction. Results are unchanged.
• Performance (vanilla-grid, StaticDataManager): when column filters and the search term change together, both are evaluated in a single Worker round trip instead of two sequential ones.
• Performance (vanilla-grid, StaticDataManager column filters): Worker column payloads are tracked per column, so adding or removing one filter column re-extracts only that column instead of re-sending every active column's dataset-sized payload.

Version 1.29.0

• Added (vanilla-grid, StaticDataManager): scaling work for large in-memory datasets — incremental filter narrowing (re-filtering only re-scans the previous survivor set instead of the full dataset), an indexed survivor search that runs free-text search over the current filtered survivors via the Web Worker path, staged search, and cooperative search cancellation so a superseded search's main-thread result build is skipped instead of racing a newer one to completion.
• Added (vanilla-grid, StaticDataManagerOptions): internStringColumns (top-level string columns deduplicated on ingestion, for memory savings on low-cardinality columns over very large datasets) and copyOnIntern (write interned values into shallow row copies instead of mutating the caller's rows in place; default false).
• Added (vanilla-grid, StaticDataManager.prewarmSearchIndex() / VanillaGridElement.prewarmSearchIndex()): opt-in, host-driven search-index pre-warm so the user's first search is a cache hit — typically called on vn-grid-loaded inside requestIdleCallback. No-op for data managers without a local index (e.g. ODataDataManager, GraphQLDataManager).
• Fixed (vanilla-grid, header filter panel): changing a filter's operator via pointer (mouse/touch/pen) now moves focus straight into the newly rendered value input, saving a click; operator changes via keyboard are left alone so arrow-key navigation through the <select> isn't hijacked.
• Fixed (vanilla-grid, clearColumnFiltersAndSorting): the coordinated clear-sort step no longer runs its own client-side re-sort/shimmer bracket ahead of the reload, which previously tore down the loading shimmer in ~2 frames and left a blank grid until a slower worker-backed filter/search reload finished landing rows.
• vanilla-grid, grid-minimal-js, build.js: general tuning and fixes across the StaticDataManager search/filter path (search preload, filter behavior) accumulated during development of the above.

Version 1.28.0

• Changed (vanilla-grid, Material theme): the header filter funnel now uses the Google filter_alt silhouette (outline at rest, filled + accent when a filter is active) via the existing --vn-grid-filter-icon / --vn-grid-filter-icon-active tokens, replacing the legacy straight-sided funnel — authored on a taller-than-wide 20×24 viewBox with a Material-only 18×21 glyph-box enlargement (base is 16×16) so it renders larger and taller.
• Added (vanilla-grid, Material theme): SVG "AZ" sort glyphs via the sort-icon theme tokens — a hover-only both-triangle "sortable" affordance on unsorted sortable headers, and single-triangle accent glyphs when sorted (up = asc, down = desc). First content: url() consumer of the token mechanism (colors baked into the SVGs, since replaced images ignore currentColor); all three SVGs share one 16×20 intrinsic size and the Material sort-indicator box is enlarged to match, so state changes cause no layout shift.

Version 1.27.0

• Changed (vanilla-grid, all themes): sort glyphs are now per-theme tokens with no base default. The base stylesheet no longer hardcodes ▲/▼ — it only provides the mechanism, reading --vn-grid-sort-icon-asc, --vn-grid-sort-icon-desc, --vn-grid-sort-icon-sortable, --vn-grid-sort-icon-sortable-opacity, and --vn-grid-sort-icon-sortable-hover-opacity on .vn-grid-header-table th. All eight built-in themes declare the full set; the Carbon themes use it for a hover-only ⇅ sortable affordance with ↑/↓ direction glyphs. Migration: a custom theme that does not declare the content tokens renders no sort glyphs at all — copy the block from themes/TEMPLATE-vn-grid-theme.css (see README "Sort Icons" section and 15-themes-implementation.md §4.5.1).
• Changed (vanilla-grid, Carbon themes): the header filter funnel in carbon/carbon-dark now uses IBM Carbon's own filter icon (outline at rest, solid silhouette when a filter is active) via the existing --vn-grid-filter-icon / --vn-grid-filter-icon-active tokens, instead of the shared lucide toolbar funnel.

Version 1.26.0

• Added (vanilla-grid): automatic loading state on every data-manager load. VanillaGridElement.loadRowsAsync() now brackets every load — the very first one included — with setLoading(true/false) itself (error path included, generation-guarded so a superseded load can never clear a newer load's state). Hosts no longer wire setLoading into onBeforeFetch/onFetchResponse/onFetchError — those are pure app hooks (status text, raw-Response inspection, error UI). dataLoading.shimmerThreshold changed meaning accordingly: it no longer gates whether the loading state is set, only whether the skeleton paint is forced (two-rAF checkpoint) before the fetch begins — below it, a fast same-task load resolves without a skeleton flicker. Public API: loadRowsAsync, setLoading, dataLoading.shimmerThreshold.
• Changed (vanilla-grid, GraphQLDataManager): onFetchResponse now fires once per user-visible load (fetchRows()), no longer on every infinite-scroll fetchMoreRows() page — matching ODataDataManager's timing. onFetchError still fires for load-more failures. Public API: GraphQLDataManager onFetchResponse/onBeforeFetch/onFetchError options.
• Maintenance (anilist-anime-js): theme-selector polish and AniList-tab tuning (rate-limit status handling, README sync) with matching Playwright coverage; the Year column now renders a - placeholder for titles whose seasonYear and startDate are both unknown (the AniList API emits these first under both sort directions — documented in the app README). All sample apps (people-cities-js … -4, -6 … -9) dropped their hand-rolled setLoading fetch-hook wiring in favor of the automatic loading state above.

Version 1.25.0

• Added (vanilla-grid): server-side sort now participates in auto-reload. Both built-in server-side data managers — ODataDataManager and GraphQLDataManager — fire a config-change from handleSort() after updating their sort clause, mirroring setFilter / setSearchTerm. A grid with setAutoReloadOnConfigChange(true) therefore re-fetches page 0 on sort automatically, so host code no longer needs an onSortChanged: () => reload() callback (that hook is now notification-only). Backward compatible: with auto-reload off (the default), handleSort()'s config-change is a no-op and hosts that reload from onSortChanged keep working unchanged. Public API: DataManager.handleSort, onSortChanged, setAutoReloadOnConfigChange.

Version 1.24.3

• Fixed (vanilla-grid, Carbon & Carbon Dark themes): the active filter-funnel icon was invisible on a column that was both sorted and filtered. These themes fill the sorted header with a solid accent background and flip its text/sort-indicator to an on-accent foreground, but the active funnel — normally the same accent color — was left colliding with that background. It now flips to the on-accent foreground too, matching the sort glyph. Other themes (which use a subtle tint for the sorted background) were unaffected.

Version 1.24.2

• Maintenance (vanilla-grid, vanilla-grid-toolbar, vanilla-resize-box, people-cities-js through northwind-orders-angular, build.js, docs/, tests/): repo-wide folder restructure — the three vanilla-* component folders moved under src/, and people-cities-js through northwind-orders-angular moved under samples/. All internal script paths, test references, and documentation links were updated accordingly. No code or public API change.

Version 1.24.1

• Maintenance (vanilla-grid, docs): corrected the implementation-docs links in this README to point at the repo-level ../docs/vanilla-grid/ folder (they referenced a stale Docs/ path). No code or public API change.

Version 1.24.0

• New getSearchFields() accessor — DataManager (base, returns null), StaticDataManager, ODataDataManager, and VanillaGridElement (gridElement.getSearchFields(), delegating to the attached manager) all gain a read accessor for the fields free-text search is restricted to, mirroring the existing getSearchTerm() accessor tier. null means unrestricted. Powers vanilla-grid-toolbar's new search-fields tooltip (see that component's changelog).
• BREAKING: StaticDataManager's searchableFields renamed to searchFields — the constructor option and setSearchableFields() / getSearchableFields() accessors are now searchFields / setSearchFields() / getSearchFields(), matching ODataDataManager's existing naming. No shipped sample app used the old name.
• ODataDataManager.getSearchFields() is now mode-aware: it returns null (not the raw configured list) whenever searchMode isn't 'filter' or the list is empty — in searchMode: 'search' the field list was already inert (the server owns $search's scope), but the accessor previously reported it as active regardless.
• .d.ts: VanillaGrid.getHeaderMainText() / .getHeaderSecondaryText() — already existed at runtime (the resolved header-text functions, formatting.getHeaderMainText/getHeaderSecondaryText or their column.label ?? column.key / column.secondaryLabel ?? column.unit defaults) but were undeclared; now typed, since vanilla-grid-toolbar's search-fields tooltip calls grid.getHeaderMainText(column) to resolve a searched field to its column's header label.
• Maintenance: vanilla-grid (.d.ts touch-ups for the above).

Version 1.23.0

• New refresh(options?) method on VanillaGrid and <vn-grid> — rebinds every visible cell (re-running column formatters / renderCell) against the grid's current in-memory rows, without querying the DataManager. Resets scroll to the top-left by default; pass { preserveScroll: true } to keep it. This is a new, unrelated method sharing a name with the refresh(options) alias for reload(options) removed as breaking in 1.10.0 — unlike that alias, the new method never re-fetches data, it only re-renders. The internal theme-swap handler (_updateThemeStylesheet()'s theme <link> load callback, which used to call _grid.render() — a method that never existed on the prototype, so the call was silently a no-op) now calls refresh({ preserveScroll: true }) once the new theme stylesheet loads. people-cities-js through -4 and -7 call refresh() right after setTheme(); grid-minimal-js now calls refresh() instead of reload() after a theme switch, avoiding a full re-fetch of its 500k-row in-memory dataset; wikipedia-pages-vue (Vue) exposes it through VnGrid/PagesTab and calls it from onThemeChange.
• exportToExcel()'s themeStyle option now defaults to 'auto' (previously unset/unstyled by default) — a bare exportToExcel() call is themed to match the active grid theme automatically; pass themeStyle: false for unstyled output. people-cities-js through -4 dropped their now-redundant explicit themeStyle: 'auto' opt-in.
• Maintenance: vanilla-grid (strict-mode / .d.ts touch-ups), people-cities-js through anilist-anime-js, build.js, eslint.config.js — general tuning and fixing.

Version 1.22.0

• Per-column filter operator allow-list — new column-def options filterOperators (attribute filter-operators="in,equals") and defaultFilterOperator (attribute default-filter-operator="in"). The filter panel's operator dropdown becomes type catalog ∩ fan-out-safe set ∩ allow-list (catalog order preserved) and preselects defaultFilterOperator when the column has no active filter; normalizeFilterModel drops conditions using a disallowed operator (the allow-list is carried on the model entry as operators, like fields), so persisted models and host setColumnFilters() calls are enforced too. setColumns() validates both options against the resolved filter type (strict mode throws). Public API: VanillaGridColumnDef.filterOperators / defaultFilterOperator, VanillaGridColumnFilter.operators, operatorsForColumn(type, fieldCount, allowed?). Lets server-side sources whose backend can't honor every operator (e.g. exact-match GraphQL args) offer only mappable operators — adopted by anilist-anime-js.

Version 1.21.0

• New built-in GraphQLDataManager (window.GraphQLDataManager, auto-loaded and bundled under the heavy obfuscation profile) — a supported DataManager for GraphQL endpoints matching ODataDataManager's generality (server-side sort, structured column filters, free-text search, offset and Relay cursor pagination, total-row-count push, last-wins cancellation). The manager owns everything universal to GraphQL (transport, the { data, errors } envelope where a GraphQL error is an HTTP 200, cancellation, version-guarded total-count push, config-changed events, response unwrapping via a declared dot-path); hosts supply a query document plus a two-tier config — declarative variableNames or imperative buildVariables / buildSort / buildFilter / buildSearch hooks. A populated errors array throws GraphQLDataManager.GraphQLError (carrying .graphQLErrors) by default, overridable via onGraphQLErrors. New public API: the GraphQLDataManager constructor and its runtime setters/getters. Demonstrated by the new anilist-anime-js (AniList) app.
• Shared filter-model utility gains sameFilterModel(a, b) — a key-order-independent structural equality check lifted out of ODataDataManager._sameModel, now on window.VanillaGridFilterModel and reused by both ODataDataManager and GraphQLDataManager for setter no-op detection (single source of truth).
• TypeScript declarations: all three built-in data managers (ODataDataManager, GraphQLDataManager, StaticDataManager) are now on the typed window surface with constructor-option interfaces, alongside the base DataManager.

Version 1.20.0

• New --vn-grid-filter-actions-justify CSS custom property controls the layout of the column filter panel's Clear/Apply button row. Defaults to flex-end (both buttons grouped at the trailing edge, matching Carbon's own dialog convention — vn-grid-carbon/vn-grid-carbon-dark don't override it). Every other built-in theme (vn-grid-default, vn-grid-material, vn-grid-fiori, vn-grid-glow, vn-grid-glow-dark, vn-grid-fluent) now sets it to space-between, pinning Clear to the leading edge and Apply to the trailing edge instead. Custom themes can opt in the same way; the token is also applied to grid-minimal-js's custom Apple theme (themes/vn-grid-apple.css). See docs/vanilla-grid/15-themes-implementation.md §4.6. No breaking change — themes that don't set the token keep today's flex-end behavior.
• Fixed the filter panel's Apply button losing contrast on hover in every built-in theme, in some cases (vn-grid-glow-dark) to a literal background/text color match that made the label fully invisible. The :hover rule used to reuse --vn-grid-menu-item-hover-bg — a tint sized for color: inherit menu items — against the button's fixed --vn-grid-filter-apply-color. It now derives the hover background from the button's own accent instead (darkened for themes with light Apply text; vn-grid-carbon-dark/vn-grid-glow-dark override it to lighten instead, since their accent is lighter than their fixed dark Apply text).
• Fixed Carbon/Carbon Dark's row height (--vn-grid-row-height) — was 40px while the header was 48px; Carbon uses one row-height tier for both header and body rows, so it's now 48px in both vn-grid-carbon.css and vn-grid-carbon-dark.css. Also fixed the Carbon toolbar (vn-grid-toolbar-carbon(-dark).css) sitting 6px shorter than the grid header (42px vs. 48px) by adjusting its padding and command-button height.
• Fixed --vn-grid-row-height/--vn-grid-header-height sometimes never picking up the active theme's value when multiple <vn-grid> instances on a page share the same theme stylesheet <link>: the post-load resync used a single link.onload assignment, so whichever instance called _updateThemeStylesheet() last silently overwrote every earlier instance's callback, and an instance that started observing an already-loaded shared link never got notified at all. Replaced with a per-link waiter list (vanilla-grid-element.js) so every instance gets its own callback, including when the link already finished loading before it attached.

Version 1.19.3

• Fixed the search/filter/sort Web Worker offload blocking the main thread on very large datasets, and made it dramatically cheaper on repeat calls: the offload only ever covered the actual match/compare step — extracting haystack strings and column values (search/filter) or column._getValue results (sort) always ran synchronously on the main thread and was re-done from scratch on every call, even a search-term-only keystroke or a sort direction toggle. Measured on a 5,000,000-row dataset, this extraction pass alone took ~31 seconds and its postMessage() clone cost alone could exhaust memory. Fixed with four changes, applied to both StaticDataManager's filter/search worker and the sort worker: (1) both Workers are now persistent across calls (search/filter already was; sorting's _cancelPendingWorkerSort() — which killed and recreated the Worker before every sort — is removed) and cache already-extracted data keyed by an extraction signature (search/filter: two INDEPENDENT signatures — dataset version + searchable fields for haystacks, dataset version + active filter columns' field/getter shape for column values) or per sort-column (column.key + dataset version), so a call that doesn't change the underlying data reuses what's already resident instead of re-extracting and re-cloning it; (2) search haystacks are packed into a handful of moderately-sized "chunk blob" strings (one per 2,000-row batch) + two Uint32Array offset/length arrays instead of one boxed string per row, and number/date filter values as a transferable Float64Array instead of a boxed array, cutting the one-time clone cost that caused the measured out-of-memory case — deliberately an array of chunk blobs rather than one joined string for the whole dataset, since joining 5,000,000 rows' worth of haystack content into a single string hit V8's RangeError: Invalid string length ceiling even after the per-row clone cost was fixed; (3) the one-time (re)extraction pass, when it does need to run, is chunked across animation frames so it never blocks the main thread for its whole duration in one synchronous sweep — haystack building (2,000 rows/batch) and column value extraction (100,000 rows/batch, ~2 orders of magnitude cheaper per row) use different batch sizes so neither starves the other; (4) haystack building/sending is now gated on whether a search term is actually active (StaticDataManager's _workerHaystackSignature, tracked independently of _workerColumnSignatures) — a pure column-filter call with no search term never builds or sends haystacks at all, since a postMessage() clone of that payload is itself an un-chunkable synchronous main-thread stall that would otherwise defeat the point of the offload for a call that will never search them (measured: a 250,000-row, 21-column dataset's haystack clone alone cost ~215ms). A cache-miss safety net (main-thread/Worker bookkeeping desync, e.g. after a Worker error) surfaces as an explicit error and falls back to the in-thread path rather than silently mis-filtering/mis-sorting. No public API or matching/sorting semantics changes — same results, faster and non-blocking. Verified on real datasets up to several million rows: extraction time scales linearly with no memory blowup; remaining slowness at the extreme end traces to the browser tab's own heap ceiling (holding both the raw rows and the derived search index at once), a capacity limit rather than a defect — see docs/vanilla-grid/03-data-manager-implementation.md §5.2. Affects vanilla-grid (data-managers/static-data-manager.js, features/sorting-worker.feature.js, features/sorting.feature.js, vanilla-grid.js).

Version 1.19.2

• Fixed selected rows silently vanishing from getSelectedRows() and exportToExcel({ scope: 'selected' }) after a filter/reload excluded them: selection state was split across _selectedKeys (never pruned by a filter) and _keyToRow (rebuilt from scratch on every setRows(), so a filtered-out row's key silently lost its lookup entry). getSelectedRows() read from _keyToRow, so it quietly returned fewer rows than selectedCount implied — in the worst case producing an empty Excel export while the toolbar still read "N selected". Added _selectedRowsCache: Map<string, row> in selection.feature.js, a row snapshot keyed identically to _selectedKeys and populated/cleared at every point a key is added to or removed from the selection; rebuildKeyToRowMap/addRowsToKeyMap additionally refresh cache entries for rows that come back into view. getSelectedRows() now reads from this cache instead of _keyToRow, so selection survives filter/reload the same way sticky select-all already does, and the existing filtered-out-rows-appended-last reconciliation logic in excel-export.feature.js's exportToExcel({ scope: 'selected' }) now runs for real instead of having nothing left to reconcile. No public API changes.

Version 1.19.1

• Fixed a rendering glitch on the "no rows" empty state: showEmpty()'s single centered .vn-grid-empty-message row never fills the viewport height, which left two artifacts visible below/on it — a meaningless row-hover tint on the message row itself, and the viewport's repeating-linear-gradient placeholder-stripe backstop (normally there to cover transient loading gaps) bleeding through as a series of phantom empty rows. Fixed with two CSS-only rules: every theme's .vn-grid-body-table tbody tr:hover now excludes :has(.vn-grid-empty-message) (all 8 official themes + TEMPLATE-vn-grid-theme.css), and .vn-grid-virtual-list-viewport:has(.vn-grid-empty-message) drops just the striped background-image, keeping each theme's own flat --vn-grid-placeholder-gap tone. No JS or public API changes.

Version 1.19.0

• Sorting now flips isLoading like filter/search already did: a local sort deferred past sorting.shimmerThreshold (default 5000) — whether running in-thread or offloaded to a Web Worker past sorting.workerThreshold — now flips grid.isLoading (and therefore isBusy()) true for its duration, exactly mirroring how filter/search/reload already gate isLoading around DataManager.fetchRows() (dataLoading.shimmerThreshold). Previously a large sort left isLoading untouched, so wheel/keyboard scrolling stayed live and any disabled-when="isLoading" <vn-grid-toolbar-command> stayed enabled during a sort, while an equally large filter/search froze both — the two operations now follow the same rule. Sorts below shimmerThreshold are unaffected (no isLoading flip, matching the existing no-shimmer behavior). No new public option was added; sorting.shimmerThreshold is the only gate, same as before.

Version 1.18.0

• Mobile touch interaction hardening (iOS long-press selection/callout, page bounce/pull-to-refresh, input focus-zoom, tap-highlight/double-tap zoom):
  • .vn-grid-table-container sets -webkit-tap-highlight-color: transparent and -webkit-touch-callout: none.
  • Header-cell selection suppression moved from the fragile th[style*="cursor: pointer"] (sortable columns only) to a blanket .vn-grid-header-table th rule covering every header cell, and gained the -webkit-user-select twin for pre-16.4 iOS Safari; header cells also get touch-action: manipulation (previously only th[draggable="true"]) to stop double-tap zoom on the whole header strip.
  • Body cells (.vn-grid-body-table td) and the export overlay gained the -webkit-user-select twin alongside their existing unprefixed rule. Body cells now read user-select/-webkit-user-select from a new --vn-grid-cell-user-select token (default none) so a host can opt a specific grid back into selectable cell text (e.g. copyable IDs/emails in renderCell output).
  • Column-filter panel inputs (.vn-grid-filter-operator, .vn-grid-filter-value) raise their font-size to max(current, 16px) under @media (pointer: coarse), avoiding iOS Safari's input-focus page zoom (triggered below 16px, persists after blur).
  • New "Mobile / touch integration" section in docs/vanilla-grid/00-index.md documents the full contract, including the host-owed overscroll-behavior-y: none line needed to stop document-level rubber-band bounce and pull-to-refresh (the component's own overscroll-behavior: none on the viewport only contains gestures that start inside it) — adopted in people-cities-js through wikipedia-pages-vue.
  • No .d.ts changes — CSS-only.
• Maintenance (vanilla-grid, vanilla-grid-toolbar, people-cities-js through grid-minimal-js, build.js): fixed an npm run build:obfuscate bug where vanilla-grid.bundle.js / vanilla-grid-toolbar.bundle.js concatenate many independently-obfuscated feature files — each javascript-obfuscator call generated its own hexadecimal helper names (string array, decoder, control-flow dispatch) with no awareness of sibling chunks, so two files could end up declaring the same top-level name; the one loaded second silently clobbered the first's string-array state, surfacing as random <name> is undefined runtime errors in the built bundle. Every chunk in both bundles now gets a unique identifiersPrefix (javascript-obfuscator's documented fix for this exact scenario), verified across repeated fresh builds with no collisions and no runtime errors. Also: people-cities-js through grid-minimal-js are no longer obfuscated at all under --obfuscate (only minified, same as a plain npm run build) — the demo/integration code isn't the IP the build protects; wikipedia-pages-vue (Vite build) was already unaffected.

Version 1.17.0

• Improved scrolling performance and feel, especially on touch/mobile devices:
  • Touch-aware synchronous rendering: while a touch gesture or its momentum tail was recently observed (tracked via passive touchstart / touchmove listeners on the viewport), handleScroll skips the rAF deferral for small scroll deltas and renders synchronously, removing a frame of latency from the input mode with the least compositor headroom.
  • Velocity-skewed buffer window: recent scroll velocity is EMA-smoothed and used to skew renderVisibleRows' buffer rows toward the direction of travel (up to a 75/25 split of the fixed-size buffer at high velocity) instead of splitting it symmetrically — same row budget, spent where the compositor is heading.
  • Coarse-pointer default buffer: layout.bufferRows now defaults to 40 on matchMedia('(pointer: coarse)') devices (touchscreens) instead of the desktop default of 20, since touch momentum sustains far higher per-frame deltas than wheel input. vanilla-grid.d.ts updated.
  • Pool rotation on small scrolls: when a new render window overlaps the previous one, _rotatePool physically moves only the rows that scrolled out of view to the other end of the pool (insertBefore + array reorder) instead of repopulating every row — a 5-row scroll now re-renders 5 rows, not the whole pool.
  • Engine-scoped virtual-DOM height cap: MAX_VIRTUAL_DOM_HEIGHT is now 16M px on Blink/WebKit (detected via Gecko-exclusive -moz-appearance CSS support, not UA sniffing) instead of a universal 4M px, keeping more large datasets in low-cost "natural" scroll mode on those engines; Gecko keeps the original 4M px cap where the sub-pixel artifact was measured. Manual real-device verification (iOS Safari, Android Chrome/Edge, a fractionally-scaled Windows touch display) is still outstanding — see docs/vanilla-grid/02-row-virtualization-and-custom-scroll-implementation.md.
  • Deferred buffer-row fill in scaled mode: on a scaled-mode render pass, only on-screen rows are populated synchronously; off-screen buffer rows are filled in a following scheduler write, halving the worst-case synchronous cost of the most expensive render path.
  • Added a themeable placeholder-stripe background (--vn-grid-placeholder-gap / --vn-grid-placeholder-stripe) on the viewport and row-spacer cells, so any compositor-exposed gap before the row pool catches up reads as a striped placeholder instead of a flat white/void flash. All built-in themes and TEMPLATE-vn-grid-theme.css set these two tokens.
  • New Playwright coverage: tests/playwright/pool-rotation.spec.js, tests/playwright/scaled-mode-boundary.spec.js, tests/playwright/touch-momentum-sync-render.spec.js.
• grid-minimal-js: the rating and height column renderCells now reuse their wrapper elements across virtual-pool re-renders (updating only the parts that depend on the row's value) instead of rebuilding from scratch every render pass, since these renderers sit in the grid's hottest loop.

Version 1.16.0

• Added Sort ascending / Sort descending / Clear sorting items to the header right-click context menu for sortable columns (omitted when sorting.enabled is false or a column has sortable: false, matching the existing "Filter…" gating). Each item self-disables when it no longer applies (e.g. "Sort ascending" once already ascending); all three act on only the clicked column's place in the sort chain (sortColumn(index, direction, { multi: true })), leaving any other column's multi-sort untouched. New messages.sortAscending / messages.sortDescending / messages.clearColumnSort keys (.d.ts updated).
• Fixed a header-menu theming bug: --vn-grid-filter-accent / --vn-grid-filter-apply-color always resolved to the neutral default, never a theme's override, because the default (declared on the more-specific .vn-grid-header-context-menu.vn-grid-filter-panel selector) outranked a theme's override (on the plain menu class) by CSS specificity regardless of <link> order — the column filter panel's Apply button never actually reflected the active theme's accent color. All --vn-grid-menu-* / --vn-grid-filter-accent / --vn-grid-filter-apply-color tokens are now declared on a single dual selector (.vn-grid-table-container, .vn-grid-header-context-menu) across the base stylesheet, all 8 built-in themes, TEMPLATE-vn-grid-theme.css, and grid-minimal-js's apple theme — header-menu.feature.js copies them from the owning grid's container onto the (body-appended) menu/filter panel at open time, keeping the menu in sync with its own grid's active theme. Custom themes must adopt this dual-selector convention going forward (documented in themes/README.md and the TEMPLATE); this does not provide true CSS isolation for two <vn-grid> instances running genuinely different themes at the same time — a known, pre-existing, wider gap in container-level theming — see docs/vanilla-grid/15-themes-implementation.md.

Version 1.15.2

• Fixed hasMoreRows() transiently returning true for a non-infinite-scroll (static/in-memory) grid during the reset→requery window of a filter, sort, or reload. _resetInfiniteScrollState() now seeds _hasMoreData from the grid's infinite-scroll mode (!!infiniteScroll) instead of forcing it true, so hasMoreRows() is always false for such a grid — matching the load-success invariant. This stops a spurious (scroll to load more) hint from flashing in <vn-grid-toolbar-status> mid-reload. .d.ts doc for hasMoreRows() updated.

Version 1.15.1

• Documentation / inline-comment accuracy pass (comments only — no behavior or API change): corrected the DataManager usage example's option shapes (infiniteScroll: { enabled: true }, sorting: { serverSide: true } — the old serverSort: true form would have thrown on the constructor's unknown-option guard), and repointed stale pre-implementation spec references (_TODO/FEATURE-COLUMN-FILTERS.md, _TODO/FEATURE-TEMPLATE-COLUMN-SORT-FIELDS.md) to the shipped docs/vanilla-grid/07-column-filters-implementation.md and docs/vanilla-grid/06-sorting-implementation.md across the data managers, filter-model.js, vanilla-grid-element.js, and vanilla-grid.js.

Version 1.15.0

• Added persistence of the free-text search term alongside the existing layout / sort / filter settings. New grouped option persistence.searchTerm.{enabled, storageKey} — unlike the other domains it defaults to false (opt-in), since the search term is transient session state. New VanillaGrid.persistSearchTermToStorage(term) and getPendingSearchTerm() (a term loaded from storage before the DataManager is attached is parked and applied once on the first data load, then cleared, mirroring the filter-model restore). clearPersistedSettings() / vn-grid-persistence-cleared now also wipe the persisted search term and clear the DataManager's active term. New searchTerm field on the VanillaGridPersistenceOptions .d.ts.
• .d.ts / README doc sync: documented the persistence.sortState and persistence.filterModel option groups (implemented in 1.6.0 but missing from VanillaGridPersistenceOptions and the options table) alongside the new persistence.searchTerm group.
• Fixed: infiniteScroll.shimmerDelay — a negative value (the documented "never show the load-more skeleton" sentinel) was silently coerced to the 500 ms default by the option parser, so "never show" was unreachable even though interaction.feature.js gates the skeleton on loadMoreShimmerDelay >= 0. The parser now preserves negative values; only a non-finite value falls back to the default. Corrected the documented default (150 → 500) in the README and the infinite-scroll doc. New tests/node/load-more-shimmer-delay.test.js regression test.
• Maintenance (vanilla-grid): inline-comment / JSDoc accuracy pass across vanilla-grid.js, vanilla-grid-element.js, and vanilla-grid.css (corrected _formatByType's handled-types list, a misplaced _autoFitMissingWidthColumnsOnFirstData JSDoc, and a stale frozen-column freeze-guide CSS comment), and de-duplicated the declarative-column boolean attribute parsing in vanilla-grid-element.js behind the shared _parseBoolAttr / new _parseBoolAttrDefaultTrue helpers.

Version 1.14.0

• New dataLoading option group for VanillaGridElement.initializeGrid() — shimmerThreshold (default 5000), useWorker (default true), and workerThreshold (default 50000). Above shimmerThreshold, search() / setColumnFilter(s) / clearColumnFilters() / clearColumnFiltersAndSorting() / reload() now show the grid's loading shimmer while the DataManager's fetchRows() resolves (never on the very first load), gated on a running high-water mark of the largest row count ever loaded rather than the current (possibly already-filtered) count, so the worst case — clearColumnFilters() going from a small filtered set back to the full dataset — is covered. useWorker/workerThreshold are forwarded to the attached DataManager's new optional setWorkerOptions() (a no-op for managers that don't implement it). New VanillaGridDataLoadingOptions .d.ts interface.
• StaticDataManager: filter/search evaluation (search term + column filters) can now offload to a Web Worker above workerThreshold rows, keeping the main thread responsive during a large synchronous scan — new useWorker (default true) / workerThreshold (default 50000; false / negative / Infinity disables) constructor options, plus a setWorkerOptions(opts) method (wired automatically from initializeGrid()'s dataLoading option above). Falls back to the existing in-thread path when Worker/Blob are unavailable, the worker path is disabled, or the dataset is below threshold — filtering results are identical either way. New destroy() method to explicitly terminate the worker and revoke its Blob URL (not called automatically by <vn-grid>).
• .d.ts sync: documented the already-existing VanillaGridElement.reload({ preserveScrollBars }) method, which had no type declaration.

Version 1.13.0

• Added infiniteScroll.onLoadMoreSuccess(rows, { loadedRowCount, hasMoreRows }) callback + paired vn-grid-load-more-succeeded event (VanillaGridEvents.LOAD_MORE_SUCCEEDED), dispatched on <vn-grid> every time an infinite-scroll page fetch resolves and its rows are appended (mirrors the existing onLoadMoreError/vn-grid-load-more-failed pair). Fixes a gap where appendRows() dispatches no event of its own and vn-grid-loaded only fires for the initial load/reload path — consumers that reflect the running row count (e.g. vanilla-grid-toolbar's <vn-grid-toolbar-status>) had no signal to react to scroll-triggered pagination and appeared stuck at the initial count.

Version 1.12.0

• Breaking: total-row-count state is now push-based, not pull-based. Replaces the one-shot onResolveTotalRows/onTotalRowsResolved resolver (gated by a single grid-owned "attempted once" flag + generation counter) with setTotalRowCount(count) / getTotalRowCount() grid state, written by whichever DataManager is attached via a new onTotalRowCountChanged field
  • _fireTotalRowCountChanged(count) protected helper on DataManager. Fixes a structural bug where two independent reload paths for the same user action (e.g. clearColumnFiltersAndSorting(), which fires both a DataManager onSortChanged reload and its own reloadDataManager()) could race over the shared one-shot flag, silently discarding the real total. Staleness is now resolved per-manager, per-request via each manager's own monotonic version counter (ODataDataManager._queryVersion) instead of a grid-level generation guard.
  • Removed entirely, no shim: infiniteScroll.onResolveTotalRows, infiniteScroll.onTotalRowsResolved, VanillaGrid.getKnownTotalRows(), VanillaGridElement.loadTotalCount(), DataManager.fetchTotalCount() (all managers, including ODataDataManager and StaticDataManager), ODataDataManager's onTotalCountLoaded constructor option, and the VanillaGridEvents.TOTAL_ROWS_RESOLVED (vn-grid-total-rows-resolved) event — replaced by TOTAL_ROW_COUNT_CHANGED (vn-grid-total-row-count-changed).
  • Added: onTotalRowCountChanged grid constructor option (top-level, not nested under infiniteScroll — total-row-count applies to any grid a DataManager is attached to), VanillaGrid.setTotalRowCount(count) / getTotalRowCount().
  • VanillaGridElement.setDataManager() now unconditionally wires the attached manager's onTotalRowCountChanged to grid.setTotalRowCount() — passive state sync, independent of setAutoReloadOnConfigChange().
  • Naming cleanup (also breaking): formatScrollIndicator's argument keys are renamed for a uniform <qualifier>RowCount vocabulary — totalRows → displayedRowCount, loadedRows → loadedRowCount, totalRowsKnown → totalRowCount. The internal _totalRowsLoaded field is renamed _loadedRowCount (matches the already-correct getLoadedRowCount(), which is unchanged).
  • Third-party DataManager subclasses that override fetchTotalCount() stop feeding the grid a total (silent) — migrate to calling this._fireTotalRowCountChanged(count) from fetchRows() instead.

Version 1.11.0

• Infinite scroll: failed onLoadMore loads now back off exponentially (1s doubling to a 30s cap) instead of retrying on every scroll event. The grid never gives up — a new vn-grid-load-more-failed event (and a VanillaGrid-level infiniteScroll.onLoadMoreError callback) fires on every failure so hosts can surface an error state; a successful load or reloadDataManager() resets the backoff.
• Selection events: selectedKeys / selectedRows on the vn-grid-selection-changed detail are now lazy compute-once getters — listeners that never read them no longer pay for two full-array allocations on every selection change (e.g. select-all over large infinite-scroll datasets). Event shape and values are unchanged for consumers that do read them.
• Sorting: date/datetime/time/string comparators precompute sort keys in one O(n) pass instead of re-parsing values per comparison (main thread and worker), cutting large sorts ~3-5x. Custom compareValues hosts are unaffected. _builtinCompare and defaultCompareValues are unified into one shared comparator.
• Infinite scroll internals: appendRows now adds only the newly appended rows to the row-key map instead of rebuilding it from scratch each page, making large paginated loads roughly linear instead of quadratic.
• Startup: the feature-script autoloader now injects all <script> tags in one pass (parallel download, guaranteed in-order execution) instead of chaining them one at a time, cutting multi-file boot latency dramatically on high-latency connections. A window.VanillaGridSequentialLoad = true escape hatch restores the old chained loader for one release.
• Header rendering: per-column event listeners (click/drag/resize/ context-menu) are now delegated once per grid instead of re-created on every header rebuild, and the per-instance window.resize listener leak in renderHeader() is fixed.
• Keyboard navigation: the per-instance document keydown/keyup and window resize/blur listeners are now consolidated into one module-level singleton registry shared across all grid instances (hover-without-focus scrolling behavior is unchanged). A window.VanillaGridKeyboardSingleton = false escape hatch restores the old per-instance listeners.
• <vn-grid> reparenting: moving a populated grid element to a new DOM parent (drag-and-drop layouts, some framework re-renders) no longer destroys and re-requires re-initialization; teardown is deferred one microtask and skipped if the element is still connected.
• Fixed: setColumns() no longer bakes measured pixel widths back onto the caller's minWidth/maxWidth column fields for non-resizable columns — the same column array can now be reused across grids/relayouts without carrying over stale constraints, and frozen/immutable column objects no longer throw.
• Fixed: the header-checkbox size-sync selector typo (vg-selection-checkbox vs. the actual vn-grid-selection-checkbox class) that silently no-op'd header/body checkbox size matching.
• Tuning: default bufferRows halved (40 → 20), reducing force-render and tooltip work on large datasets with no observed blank-row regression; pass layout.bufferRows: 40 to restore the previous pool size.
• OData data manager: fetchTotalCount() now has its own abort controller (previously unwired), so cancel() reliably aborts an in-flight count request independently of a concurrent row fetch.
• Various lifecycle/CSS/micro-perf hardening: destroy() now clears the load-more shimmer timer and viewport-adaptation rAF and removes the delegated header listeners; will-change: contents and redundant GPU layer-promotion hacks removed from viewport/scrollbar CSS; render-loop micro-allocations (checkbox aria-label, per-row selection class checks) moved behind change-gates.

Version 1.10.2

• Maintenance: adopted ESLint (see eslint.config.js) and cleaned up the findings from its first run — removed a dead thumbHeight computation in features/interaction.feature.js's _isHoldingScrollbarAtBottom, fixed three regex over-escapes (vanilla-grid.js, root build.js), and normalized pre-existing CRLF/tab and quote-style drift across most component source files (mechanical only — verified with git diff --ignore-all-space and the full Node + Playwright suites, no runtime behavior changed). Also touched: people-cities-js through grid-minimal-js, build.js.

Version 1.10.1

• .d.ts sync fix: filled in several public API declarations that had drifted from the runtime implementation — renderCell now types as (cell: HTMLElement, value: unknown, row: unknown, rowIndex: number) => void (full DOM control over the live cell element, return value ignored) instead of the old value-returning signature; initializeGrid() is now declared to return the constructed VanillaGrid instance; formatScrollIndicator now takes a single VanillaGridScrollIndicatorInfo argument instead of three positional numbers; and autoFitColumn, autoFitAllColumns, clearPersistedSettings, setTheme, and window.DataManager (the concrete VanillaGridBaseDataManager base class for custom data managers) are now declared. No runtime behavior changed — the gaps surfaced while converting wikipedia-pages-vue to TypeScript.

Version 1.10.0

• Added <vn-grid>.getColumnFilters(): returns a shallow-copied { [columnKey]: filter } map of every column with an active filter (an empty object when none, or when the attached DataManager doesn't support filtering). Additive accessor for filter-aware UIs — introduced for <vn-grid-toolbar>'s clearColumnFiltersAndSorting gating, but usable standalone.
• exportToExcel()'s style precedence changed from all-or-nothing to per-slot: headerCellStyle / dataCellStyle / dataCellStyleAlt each independently use their own explicit value if given, else fall back to the resolved themeStyle palette's value for that slot, else stay unstyled. { headerCellStyle: myStyle, themeStyle: 'auto' } now themes the data rows too, instead of leaving them unstyled. Callers passing explicit styles for all three slots, or with no themeStyle at all, are unaffected. See 18-excel-export-theming-implementation.md.
• Multi-instance theme <link> support: <vn-grid>'s theme <link> is now keyed by its resolved stylesheet URL (with a refcount), not a single fixed id, so two <vn-grid> instances with different theme attributes on the same page no longer fight over one shared link — last writer no longer wins for both. See 15-themes-implementation.md §6.1.2.
• Breaking: removed the refresh(options) alias for reload(options). Call reload() directly. grid-minimal-js updated accordingly.
• Maintenance: column-key.js (the shared column-key normalizer) is now wired into build.js's bundle parts alongside the multi-file loader, so the bundled artifact and the multi-file build share the same single normalizer instead of the bundle silently falling back to per-feature inline copies; build.js also gained support for building vanilla-grid-toolbar as a component. General tuning/fixing also touched people-cities-js through wikipedia-pages-vue (mostly Carbon-theme spacing polish and toolbar integration).

Version 1.9.0

• Grid-owned, opt-in themed Excel export. exportToExcel({ themeStyle: 'auto' }) now colours the spreadsheet to match the grid's active theme; the default exportToExcel() call stays unstyled (fully back-compatible). The styling logic that hosts previously duplicated now lives in the grid.
  • New exportToExcel options: themeStyle ('auto' | VanillaGridExportPalette | false) and headersOnly (keep the header style, drop data-cell styling).
  • Each built-in theme stylesheet (and TEMPLATE-vn-grid-theme.css) declares a --vn-grid-export-* palette on .vn-grid-table-container, read at export time via the new VanillaGrid.prototype._readThemeExportPalette() (mirrors _readThemeRowHeight()). Custom CSS themes get themed export for free.
  • New static registry on <vn-grid>: VanillaGridElement.registerThemeExportStyle(name, palette) / getThemeExportStyle(name) — the export-palette analog of registerTheme.
  • people-cities-js dropped its duplicated getExcelThemeStyles() palette and opts into themeStyle: 'auto'.
  • See Excel Export Theming.

Version 1.8.0

• Added <vn-grid>.clearColumnFiltersAndSorting(): clears every column filter and all sorting (including their persisted values) with a single coordinated reload, while preserving persisted column layout (widths, order, hidden, frozen). A middle-ground reset between clearColumnFilters() (filters only) and clearPersistedSettings() (everything).

Version 1.7.0

• Added additive, backward-compatible API consumed by the new <vn-grid-toolbar> component (all optional; the grid behaves identically when unused):
  • VanillaGrid.isBusy() and <vn-grid>.isBusy() / <vn-grid>.isLoading — a busy flag spanning the initial/full load and infinite-scroll "load more".
  • <vn-grid>.getSearchTerm() — reflects the attached DataManager's active free-text term (companion to the existing search()).
  • New vn-grid-total-rows-resolved event (in VanillaGridEvents) dispatched when the infinite-scroll total resolves (or is determined unknown); detail.totalRows is null when unknown. Any host onTotalRowsResolved callback still runs.

Version 1.6.0

• Added persistence of sort state and column filter model alongside the existing layout settings. New grouped options persistence.sortState.{enabled, storageKey} and persistence.filterModel.{enabled, storageKey} (both enabled by default) control whether the active sort columns and filters are written to the configured storage provider and restored on the next load.
• Added persistFilterModelToStorage(model) and getPendingFilterModel() on VanillaGrid. A filter model loaded from storage before the DataManager is attached is parked and applied once on the first data load, then cleared (_pendingFilterModel), avoiding a write-back cycle during restoration.
• Extended clearPersistedSettings() / vn-grid-persistence-cleared to also wipe persisted sort state and filters, clear the DataManager's active column filters, and reload so the grid reflects the cleared state instead of the previously filtered/sorted rows.
• Maintenance (generic tuning & fixing):
  • build.js: fixed the build script — skip copying .d.ts files into dist/, and auto-run npm install inside wikipedia-pages-vue/ when node_modules is absent so clean CI/cloud builds no longer fail on the Vite step.
  • sample apps: tuning of the sample frontends to exercise the new filter/sort persistence.

Version 1.5.0

• Added column filters: a type-aware filtering UI in the header context menu plus a shared filter model (filter-model.js) used by both the UI and the data managers. Operator catalog covers string (contains, notContains, equals, notEquals, startsWith, endsWith, isEmpty, isNotEmpty, in), number/date (between, notBetween, ordering comparisons) and boolean columns, with per-operator arity driving the input count.
• Added filter API on both <vn-grid> and the data managers: setColumnFilter(), setColumnFilters(), getColumnFilters(), clearColumnFilters().
• Added vn-grid-column-filter-changed event ({ columnKey, columnFilter }) dispatched when a filter is applied or cleared from the header-menu UI; the element listens and calls setColumnFilter().
• Added multi-field fan-out filter semantics: negative/exclusion operators join across backing fields with AND, positive operators with OR, keeping fanned-out columns honest. Server-side OData filtering is delegated through the OData data manager.

Version 1.4.3

• Fixed the infinite-scroll "double-load glitch": on server-side grids the total-row count (onResolveTotalRows, e.g. OData $count) was fetched after the data page rendered, staging a late second round-trip and a visible reload flicker on every filter/sort change. The count is now requested at load start (concurrently with the data page, via setLoading(true)) — same number of requests, no staggered re-render. The post-render call remains as a fallback for synchronous setRows() paths and is de-duplicated by the one-time flag.
• Added a generation guard (_totalRowsGeneration, bumped on every _resetInfiniteScrollState()): a slow in-flight count for a superseded predicate (e.g. the previous filter) is discarded instead of overwriting the current total / hasMoreRows / scroll indicator. No public API change.

Version 1.4.2

• Added clearPersistedSettings() on both VanillaGrid and <vn-grid> to wipe persisted layout settings (widths, order, hidden, frozen) and restore the declarative defaults in one call. The web-component proxy always returns a Promise<void> and dispatches vn-grid-persistence-cleared on completion.
• Added clear(keys) to the storage-provider contract. The base class provides a default per-key removeItem implementation; VanillaGridLocalStorageProvider inherits it; VanillaGridNullStorageProvider overrides it as a no-op; VanillaGridRemoteStorageProvider.clear() is now an explicit interface method that throws unless the subclass overrides it.
• Added stretchToFit (alias layout.stretchToFit, attribute stretch-to-fit). Default remains the historical "natural width" behaviour (false) but is now documented and gated explicitly.
• Fixed a persistence regression in non-stretch mode where the post-setRows flex-column pass silently shrank the last resizable column to absorb the vertical-scrollbar gutter, causing the user's last-column resize to be lost on the next reload or layout-mutating action.

Version 1.4.1

• Breaking: Constructor options refactored from flat parameters to grouped configuration objects
  • formatting: locale, emptyMessage, messages, getHeaderMainText, getHeaderSecondaryText, formatInteger, formatScrollIndicator
  • layout: rowHeight, bufferRows, snapViewportToRows, customScrollbar, scrollSpeed, scrollSpeedMultiplier
  • sorting: enabled (was sortable), serverSide (was serverSort), onSort, compareValues
  • columns: reorderable (was reorderableColumns), touchReorder, touchReorderHoldDelay, reorderMarkerDeadZonePx
  • persistence: columnWidths.{enabled,storageKey}, columnOrder.{enabled,storageKey}, hiddenColumns.{enabled,storageKey}, frozenColumns.{enabled,storageKey}
  • infiniteScroll: enabled (was boolean infiniteScroll), pageSize, onLoadMore, onResolveTotalRows, onTotalRowsResolved, shimmerDelay (was loadMoreShimmerDelay)
  • selection: mode (was selectionMode), rowKeyField, rowKeyGetter, showCheckboxes (was showSelectionCheckboxes)
• Added rowDblClick / vn-grid-row-dblclick event: fires on row double-click without altering selection state; uses pointerdown-based detection for reliable operation with custom renderCell content
• Added exportToExcel(options) method on both VanillaGrid and <vn-grid> for exporting grid data to XLSX/CSV/ODS via SheetJS CE
• Updated VanillaGridElement.initializeGrid() to build grouped options
• DOM references (header, body, viewport, headerColGroup, headerSpacer) and top-level callbacks (formatValue, isNumericColumn, decorateCell) remain at top level

Version 1.4.0

• Added row selection: noselection, single, and multiple modes with stable key-based selection, header checkbox, and selectionChanged event
• Added sticky select-all for infinite-scroll mode
• Added <vn-grid> attributes: selection-mode, row-key-field
• Added declarative <vn-grid-column> children support
• Added setDataManager(), getDataManager() element methods
• Added ODataDataManager and StaticDataManager data layer classes
• Added column freeze / unfreeze: context menu, freezeColumn() / unfreezeColumn() / unfreezeAll() API, persistence, freeze guide line
• Added column hide / show: context menu, hideColumn() / showColumn() / showAllColumns() API, persistence
• Added frozen column boundary enforcement in column drag-and-drop
• Added decorateCell callback option
• Added getHeaderMainText and getHeaderSecondaryText callback options
• Added compareValues custom sort comparator option
• Added touch hold-to-reorder (touchReorder, touchReorderHoldDelay, reorderMarkerDeadZonePx)
• Added selection API to web component element: getSelectedKeys(), getSelectedRows(), setSelectedKeys(), clearSelection()
• Extended messages with freezeColumn, unfreezeColumn, unfreezeAll keys
• Added loadDataProgressively() method for chunked rendering of large payloads
• Added keyboard navigation: Arrow, Page, Home, End, Space keys

Version 1.3.0

• Added vanilla-grid-element.js custom element support
• Added hybrid attribute-driven plus provider-hook integration model
• Added element APIs for reload(), loadRowsAsync(), and setDataProvider()
• Added reusable endpoint attributes (data-source, count-source, page-size, infinite-scroll)

Version 1.2.0

• Added optional infinite-scroll total resolver hooks: onResolveTotalRows(), onTotalRowsResolved(totalRows)
• Added resize scroll stabilization for virtualized/infinite grids

Version 1.1.0

• Added column reordering (drag-and-drop), with persistence to localStorage

Version 1.0.0

• Initial release
• Virtual scrolling support
• Column resizing and sorting
• Multiple themes
• Persistent column widths