Vanilla Breeze

HTML-first + JS-first data API

How VB components support both declarative HTML markup and reactive property assignment without forcing a choice.

VB components accept the same data through two doors. Author them in HTML and they work without a single line of script. Drive them from a reactive framework via .items and .data and they diff against existing markup, preserving in-flight state. Either mode is valid; you can mix them.

Why both modes

Pure HTML-first components are great for static pages, server rendering, and progressive enhancement, but they fight back when a framework re-renders the same DOM. Pure JS-first components are convenient for SPAs but require ceremony to ship anything visible before hydration. VB picks both: the same element accepts declarative children at upgrade and property assignments after — without a separate hydration step.

  • HTML-first: SSR / Eleventy / Astro emit normal markup. The component upgrades in place, parses children, and works.
  • JS-first: A reactive framework (Montane, Lit, Solid, React) creates an empty element and assigns .columns / .items / .data. The component renders accordingly.
  • Mixed: SSR the initial state for fast first paint, then take over with property assignments after hydration. Existing nodes are reused; nothing rebuilds.

Two roles, two contracts

Each component declares one of two roles in its data API.

Record components — .data

One element represents one logical record. Examples: <work-item>, <user-story>. The .data property accepts a plain object whose fields map to the component's state attributes and slotted children. Reading .data returns the current shape.

The preservation guarantee

VB's collection diff makes a formal promise: any element whose key is present in both the previous and the next .items list is never destroyed and recreated. The same DOM node may be moved across containers or reordered within one, but its identity — and any state held against that identity — is preserved.

This matters for:

  • Drag-and-drop. A user can be mid-drag when a remote update arrives; the dragged element survives the diff.
  • Focus. The currently focused element does not lose focus when an unrelated item is added or removed.
  • CSS animations / transitions. Active animations don't restart from scratch on every framework re-render.
  • Iframe / video / canvas children. Long-lived embedded content keeps its connection / playback / paint state.

The diff is keyed by an id field on each item by default. Components can override with a static keyOf.

Lifecycle: the upgrade signal

VB components fire <localName>:upgraded exactly once after their initial setup() succeeds. Frameworks should wait on this event before assigning .items or .data from outside, to avoid races where a property arrives before the element's internal structure is ready.

Source-tagged events for loop avoidance

Reactive systems often listen to a component's own change events to update external state. Without a source tag, programmatic updates trigger a feedback loop: assignment → event → handler updates state → state pushes new .items → event again.

VB collection components emit <localName>:items-changed with a source field. Filter on it:

Possible source values:

  • api — set programmatically via .items = ...
  • drag — user dragged a card to a new column or position
  • attribute — set via attribute mutation (rare for collections)
  • internal — component-internal mutation

Custom rendering with .renderItem

Collection components ship with a default item renderer that reproduces today's markup. To take over rendering — say, to inject your design system's card or wrap the work-item with extra chrome — assign a function to .renderItem.

The renderer must return an Element. Strings and tagged templates are not accepted in v1 — see issue VB-XG5X for the open decision.

Building your own dual-mode component

VB exposes the building blocks under src/lib/:

  • VBElement — minimal base class with setup() / teardown() lifecycle and :upgraded event.
  • VBRecord — mixin that adds .data with attribute reflection per a static dataSchema.
  • VBCollection — mixin that adds .items with the keyed diff and the preservation guarantee.
  • diffByKey — the pure reconciler under VBCollection; useable directly if you want the algorithm without the mixin.

Open decisions

  • String / template return from renderItem. v1 ships Element-only to avoid a parse step on every diff. We'll revisit after pilot consumers report their needs.
  • Form-associated controls. <color-picker>, <date-picker>, <combo-box>, etc. expose .value as their canonical property; they do not get .data bolted on.
  • Async data loading. Out of scope. Consumers handle fetch / framework resources and feed the result into .items or .data.

Related
↑