Vanilla Grid Toolbar — Technical Docs
Implementation-focused documentation for the <vn-grid-toolbar> component, a
state-aware command surface bound to a vanilla-grid instance.
Documents
Listed in reading order — the numeric file-name prefixes match this list.
- Usage Guide — how to wire a toolbar into an app, author state templates, use built-in items, and write custom sub-components.
- Implementation — architecture, linking, state assembly, template engine, bindings, sub-component contract, theming, i18n, and the additive grid-API surface it consumes.
See also the component README. This directory (and Implementation in particular) is the authoritative design spec.
Architecture
The toolbar is a light-DOM custom element with no data of its own. On
connect it injects its stylesheets, reads its <template data-vn-grid-toolbar="…">
children (re-read on every grid relink and refresh(), so templates appended
after connect are supported), resolves and links a <vn-grid> (by grid="<id>"
attribute, .grid property, or a nearest-element DOM fallback), then subscribes
to the grid's events and renders the template matching the current state. A single
<script src="vanilla-grid-toolbar.js"> tag auto-loads the events registry and
exposes window.VanillaGridToolbarReady; the vanilla-grid-toolbar.bundle.js
build artifact inlines everything into one file. See
Implementation for the full lifecycle, linking rules,
and template engine.
| File | Responsibility |
|---|---|
vanilla-grid-toolbar-events.js |
Frozen VanillaGridToolbarEvents name registry — loaded first |
vanilla-grid-toolbar.js |
Element + VanillaGridToolbarItem base + built-in items + default i18n bundle + command allow-list |
vanilla-grid-toolbar.css |
Base structural styles; consumes --vn-grid-toolbar-* tokens |
themes/vn-grid-toolbar-<theme>.css |
Per-theme token values (8 themes) |
vanilla-grid-toolbar.d.ts |
Hand-authored TypeScript declarations |
Mobile / touch integration
The search input (.vn-grid-toolbar-search-input) raises its font-size to
max(current, 16px) under @media (pointer: coarse) so focusing it on a
touch device doesn't trigger iOS Safari's auto-zoom (which fires below 16px
and persists after blur). Buttons and labels keep the theme's compact
--vn-grid-toolbar-font-size. See
vanilla-grid's "Mobile / touch integration"
for the full host contract (document overscroll/pull-to-refresh, iOS-version
caveats) shared across both components.