Vanilla-Grid Technical Docs

This folder contains implementation-focused documentation for core Vanilla-Grid features.

Related component: Vanilla Grid Toolbar (<vn-grid-toolbar>) — a state-aware command surface bound to a grid. It consumes the additive grid API (getSearchTerm(), getSearchFields(), isBusy(), the vn-grid-total-row-count-changed event).

Documents

Listed in reading order — foundations first, then the features that build on them. See Suggested Reading Order for a shorter path through the set.

1. Core engine

• Web Component Implementation (<vn-grid>) — element lifecycle, markup generation, API forwarding, event dispatch.
• Row Virtualization and Custom Scrollbars — the rendering and scroll engine every other feature sits on.

2. Data access

• DataManager Implementation — the data access contract, the built-in managers, and <vn-grid> lifecycle wiring.
• Row Key Management — stable row identity: key strategies, compound keys, OData considerations.
• Infinite Scroll Implementation — prefetch thresholds, load chaining, known-total resolution.

3. Sorting, filtering, and column types

• Sorting Implementation — single/multi-sort state, comparator chaining, server-sort delegation.
• Column Filters Implementation — filter model, header menu UI, client/server filter dispatch.
• Date, DateTime, and Time Types Implementation — how the three temporal types parse, sort, filter, and render.

4. Row interaction

• Selection Implementation — key resolution, mode semantics, sticky select-all, event payloads.
• Keyboard Navigation Implementation — key event gating, delta computation, momentum guards.

5. Column management

• Column Resizing Implementation — pointer resize math, guide rendering, width persistence.
• Columns Reordering Implementation — drag/drop normalization, touch hold behavior, order persistence.
• Column Visibility Implementation — hide/show projection, guards, refresh behavior.
• Column Freezing Implementation — left-pinned grouping, offset computation, freeze guide rendering.

6. Presentation

• Themes Implementation — how visual systems layer on top of the core behavior.
• Localization Implementation — locale resolution, message dictionaries, number and scroll-indicator formatting.

7. Export

• Export to Excel Implementation — the exportToExcel() API, the streaming .xlsx writer and export Worker, progress / Cancel / errors, header label resolution, formatCell usage.
• Excel Export Theming Implementation — how an export matches the active theme, and how custom themes declare an export palette.

8. Persistence, delivery, and performance

• Local Storage Settings Implementation — which settings persist and in what JSON format.
• Cache-Bust Strategy — dev vs. build token strategy for feature-script and asset loading.
• Performance Analysis — audit of potential performance improvements, grouped by category and ranked by impact.

9. Row grouping

• Row Grouping Implementation — multi-level client-side grouping: the renderEntries render projection, the canonical path-based group-key encoder, degradation over a partial dataset, persistence, the keyboard/focus contract for caption toggles, and the grouped-column removal + group bar that make a grouped column reachable again.

Architecture

Vanilla-Grid splits responsibilities into feature modules loaded automatically from features/:

vanilla-grid.js auto-loads these scripts relative to its own path, so consumers only need a single <script> tag.

Loading strategy

All dependency <script> tags are injected in one synchronous pass with async = false: the HTML spec guarantees in-order execution while the downloads proceed fully in parallel, so boot latency is ~1×RTT + max(download) instead of the ~N×RTT of one-at-a-time injection. The bootstrap exposes window.VanillaGridReady, a Promise that resolves once every feature has loaded (and rejects with the failing URL if any script errors). Hosts must await window.VanillaGridReady (directly, or via the <vn-grid> element's ready() method which delegates to it) before instantiating a grid. Setting window.VanillaGridSequentialLoad = true before vanilla-grid.js runs restores the previous strictly-sequential injection as a temporary escape hatch. For synchronous bootstraps use the pre-built vanilla-grid.bundle.js artifact (see below), which inlines every feature.

Historical note: a document.write-based synchronous path used to handle the parser-active case but was removed — it triggered warnings in every modern browser, blocked the parser on slow networks, and was incompatible with HTTP/2 server push and ad-blockers.

Auto-loading can be disabled by either of:

• setting window.VanillaGridSkipAutoload = true before vanilla-grid.js runs, or
• adding data-skip-autoload to the <script src="vanilla-grid.js"> tag.

TypeScript declarations

Hand-authored declaration file src/vanilla-grid/vanilla-grid.d.ts ships alongside the JavaScript sources. It covers:

• All constructor option types (VanillaGridOptions and every nested bag)
• VanillaGrid class with every public method and property
• VanillaGridElement (<vn-grid>) class with every public property, attribute, and method
• Every CustomEvent.detail shape keyed to VanillaGridEvents constants (incl. vn-grid-sort-changed)
• VanillaGridStorageProvider and the three built-in subclasses
• VanillaGridDataManager abstract base contract
• Window global augmentations (VanillaGridReady, VanillaGridLogger, VanillaGridScheduler, etc.)
• HTMLElementTagNameMap extension so document.querySelector('vn-grid') infers VanillaGridElement

Usage (TypeScript project):

/// <reference path="path/to/vanilla-grid/vanilla-grid.d.ts" />
// or add to tsconfig.json:
// "typeRoots": ["node_modules/@types", "path/to/vanilla-grid"]

const grid = document.querySelector('vn-grid') as VanillaGridElement;
await grid.ready();
grid.addEventListener('vn-grid-loaded', (e: CustomEvent<VanillaGridLoadedDetail>) => {
    console.log(e.detail.rows);
});

Pre-bundled artifact

The npm run build step produces dist/vanilla-components/latest/vanilla-grid/vanilla-grid.bundle.js, a single file that concatenates the storage provider, every feature, all data managers, vanilla-grid.js, and vanilla-grid-element.js in the correct order. The bundle declares window.VanillaGridSkipAutoload = true at the top, so the runtime auto-loader is a no-op and only one <script> tag is required:

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

Module load-order enforcement (build-time)

Every non-minified JS file in src/vanilla-grid/ carries Depends on: and Used by: header comments that make its evaluation-time requirements explicit:

// VanillaGridPersistenceFeature
// Depends on:  storage/grid-storage-provider.js (VanillaGridStorageProvider)
// Used by:     vanilla-grid.js (instantiates as this._persistence)

build.js reads these annotations at the start of every build and runs a topological sort (checkModuleLoadOrder()). The build fails immediately if:

• any declared dependency would be evaluated after the file that needs it (ordering violation), or
• a circular dependency is detected between any two modules.

This makes load-order constraints self-documenting and guarantees that BUNDLE_PARTS (and the auto-loader array in vanilla-grid.js) is always consistent with the declared dependency graph.

Constructor Architecture

VanillaGrid's constructor delegates to a fixed sequence of private _init*() helpers so each concern is independently readable and testable:

The call order in the constructor is load-order-sensitive. The two non-obvious rules are:

1. Logger before storage — _resolveStorageProvider receives this.logger as a parameter.
2. All option resolution before _initFeatures — the four feature constructors consume every field set by the preceding helpers via getter-function closures.

Host Integration Points (injectable adapters)

VanillaGrid's constructor accepts a few host-replaceable adapters so the same code path serves browsers, SSR, sandboxed iframes, and tests:

• options.logger — { debug, info, warn, error }. Defaults to a thin wrapper over console. Pass false (or null) to silence the grid completely. The <vn-grid> web component element also routes its own warnings through the grid instance logger (falling back to console before the grid is initialised). The normalisation helper is exposed as window.VanillaGridLogger.normalizeLogger(candidate) so host code and vanilla-grid-element.js can reuse the same duck-typing logic; window.VanillaGridLogger.NOOP_LOGGER provides the canonical silent-logger constant.
• options.strict — boolean (default true). Controls how setColumns() handles malformed column definitions. When true (the default), every misconfiguration is detected in a single-pass validator (_validateColumns()) and a descriptive Error is thrown listing every violation, so developers see all problems at once. When false, the same checks emit logger.warn calls instead of throwing, preserving the historically lenient behaviour for applications that need a gradual migration. Validated conditions include: non-object entries, missing/non-string keys, case-insensitive duplicate keys, frozen + hidden on the same column, unknown type, non-positive width/minWidth/maxWidth, minWidth > maxWidth, and non-function renderCell/valueGetter/sortFields fields.
• options.storageMode — 'none' | 'local' | 'remote' (default 'none' — opt-in). Selects the persistence back-end.
  • 'none' → no settings are read or written. (Default.)
  • 'local' → wraps window.localStorage (synchronous; falls back to in-memory when unavailable).
  • 'remote' → uses options.storageProvider, an async provider subclassed from VanillaGridRemoteStorageProvider. Reads must be awaited via grid.ready(); writes are debounced and flushed in the background.
• options.storageProvider — explicit provider instance. Always wins over storageMode when both are present.

Removed (May 2026): the legacy options.storage Web-Storage-like adapter ({ getItem, setItem, removeItem, hasItem? }) is no longer accepted. Hosts that previously passed options.storage should switch to options.storageProvider (or storageMode: 'local' | 'remote').

Static, host-wide configuration (call once at startup, before constructing grids):

• VanillaGrid.defaultLocale = 'it-IT' — overrides the global fallback locale (default 'en-US').
• VanillaGrid.registerLocale('it', { … }) — registers/replaces a message bundle. The grid resolves the longest matching prefix (e.g. 'en-US' → 'en').
• VanillaGrid.getLocaleMessages('en') — inspect a registered bundle.
• VanillaGridElement.registerTheme('corporate', '/themes/grid-corporate.css') — adds a named theme so the theme attribute accepts it like a built-in.
• VanillaGridElement.getSupportedThemes() — returns built-in + registered theme names.

See Localization Implementation, Themes Implementation, and Local Storage Settings Implementation for full details.

Public API — Return-type contract

All public methods on VanillaGrid and <vn-grid> (VanillaGridElement) follow these invariants:

isRowSelected(row) on <vn-grid>

VanillaGridElement now exposes isRowSelected(row) as a first-class public method, mirroring the same method on the internal VanillaGrid instance. Returns false when the grid has not been initialized yet (safe to call before initializeGrid()).

Mobile / touch integration

Touch-platform hardening distinct from scroll-performance tuning (see Row Virtualization and Custom Scrollbars for the momentum-scrolling side). What the component guarantees vs. what the host page owes:

Guaranteed by the component:

• No text-selection/callout on chrome. Header cells (.vn-grid-header-table th) and body cells (.vn-grid-body-table td) are user-select: none (with the -webkit-user-select twin for pre-16.4 iOS Safari, which ignores the unprefixed property). .vn-grid-table-container sets -webkit-touch-callout: none so a long-press over custom renderCell content (links, images) never shows the iOS Copy/Look-Up sheet. Body cells can opt back into selectable text (e.g. renderCell output with IDs/emails users legitimately copy) by setting --vn-grid-cell-user-select: text on .vn-grid-table-container for that grid instance — the property has no effect on header cells, which are never user-copyable content.
• No tap-highlight flash / double-tap zoom. -webkit-tap-highlight-color: transparent on the container suppresses the platform tap rectangle; header cells carry touch-action: manipulation so a fast double-tap on the header never triggers browser zoom.
• Viewport overscroll containment. .vn-grid-virtual-list-viewport sets overscroll-behavior: none, which stops scroll chaining to the document for gestures that start inside the viewport, on engines that support it (iOS Safari 16+, all current Chromium/Firefox). It cannot do anything for gestures that start on the header, toolbar, or page padding — those pan the document scroller directly and are outside the component's DOM.
• No input focus-zoom inside the component. The column-filter panel's operator/value inputs (.vn-grid-filter-operator, .vn-grid-filter-value) raise their font-size to max(current, 16px) under @media (pointer: coarse) — iOS Safari auto-zooms the page when a focused input's computed font-size is below 16px, and the zoom persists after blur until the user pinches back out. The toolbar's search input has the equivalent fix; see vanilla-grid-toolbar.

Owed by the host page: the component cannot suppress document-level rubber-band bounce or pull-to-refresh from inside — that requires styling html/body, which a well-behaved web component must never do on its own (it would break embedders that want PTR elsewhere on the page). A full-viewport grid app needs one line of host CSS:

html, body {
    overscroll-behavior-y: none;   /* stops PTR on Chrome/Edge Android and
                                       chaining/PTR on iOS Safari 16+ */
}

plus a fixed app shell — height: 100dvh on body (the modern viewport unit; see people-cities-js through wikipedia-pages-vue) is the recommended pattern. overscroll-behavior is silently ignored on iOS Safari < 16, so hosts that must support it need the classic fallback instead: position: fixed; inset: 0; on the app shell, which prevents any document panning at all regardless of engine support.

iOS-version caveats: unprefixed user-select: none is honored from iOS Safari 16.4 (March 2023) — every earlier version needs the -webkit-user-select twin the component already ships. overscroll-behavior is supported from iOS Safari 16 — earlier versions ignore both the component's viewport rule and the host's html/body rule; the position: fixed shell is the only way to fully cover them.

Suggested Reading Order

The Documents list above is already ordered: read the nine groups in sequence and each one only depends on the groups before it. Group 1 explains what the element is and how rows reach the screen; group 2 explains where rows come from; groups 3–5 are the features that operate on those rows and columns; groups 6–8 layer presentation, export, and persistence on top; group 9 (row grouping) depends on group 1's render pipeline and group 3's sort machinery.

If you only need enough context to work on one feature, read this short path first:

1. Web Component Implementation — how <vn-grid> wraps and exposes the core grid.
2. Row Virtualization and Custom Scrollbars — the rendering and scroll engine.
3. DataManager Implementation — the data access contract and lifecycle wiring.
4. Row Key Management — stable row identity, which selection and re-render both depend on.
5. Themes Implementation — the CSS variable system every feature's UI is styled through.

Then jump straight to the document for the feature you are changing.