Vanilla Breeze

Vanilla Breeze v0.5.0 released

0.5.0 is the first element quality release, covering every A, B and C element. Components rebuild cleanly when moved or re-populated, keyboard and screen-reader access is fixed across the C components, and several XSS paths are closed. Themes gain a --btn-border-width hook,…

Read the release notes

content-lens

Universal switchable host for VB lens components. Wraps a set of light-DOM lens children and exposes reader controls to switch which one is active.

Overview

The <content-lens> component is the universal host for VB's lens family. It wraps any number of lens children (each carrying a data-lens-name attribute) and renders a reader-facing radio control so visitors can switch between views over the same underlying data.

Without JavaScript, every lens child is rendered stacked — the page remains usable.

Attributes

AttributeTypeDefaultDescription
data-lens-defaultstringfirst childLens to activate on first load
data-lens-controls"on" | "off""on"Render the reader chip group
data-lens-srcstring—Shared data URL forwarded to every child unless the child sets its own
data-lens-storagestringpathnameKey for sessionStorage so the reader's last choice persists per page
data-active-lensstringcomputedReflects the active lens (state, not config)

Child attributes

Set these on each direct lens child. Children without data-lens-name are left alone (always visible, not switchable).

AttributeTypeDefaultDescription
data-lens-namestring—Required. Registers the child as a lens; the value is what data-lens-default, setLens() and the event detail refer to
data-lens-labelstringhumanised nameChip text. Defaults to data-lens-name with dashes turned into spaces and words capitalised (by-topic → “By Topic”)

Shared source forwarding

data-lens-src is copied onto every lens child that has neither its own data-lens-src nor a src. Forwarding does not depend on upgrade order: a child that was already upgraded before the host (its definition loaded first) is re-initialised once the attribute arrives. <popularity-index> treats the forwarded URL as its metadata source only; its analytics endpoint lives on its own analytics-src attribute.

JavaScript API

MemberTypeDescription
activeLensstring (read-only)Name of the visible lens; empty before the element upgrades
setLens(name)methodShow the named lens, check its chip and persist the choice. Unknown names are ignored

Events

EventDetailWhen
content-lens:change{ lens: string }Reader switches lenses, or setLens() changes the active lens. Not fired for the initial selection (default or restored from sessionStorage), on reconnect, or when setLens() names the lens already showing — read activeLens or data-active-lens for the starting state

Keyboard

The chips are native radio buttons, so the browser's radio-group keyboard model applies.

KeyAction
TabMoves focus into the group (onto the checked chip) and out again
Arrow keysMove to the previous / next chip and switch to that lens
SpaceSelects the focused chip if it is not already checked

Accessibility

  • The controls are a <fieldset> with a “View” <legend> wrapping real radio inputs, so screen readers announce the group name, each lens label and the checked state. No extra landmark is added.
  • The radio inputs are visually clipped, not hidden: the chip (<label>) shows the focus ring whenever its radio has :focus-visible, using the theme focus-ring tokens.
  • Inactive lenses get hidden, which removes them from the accessibility tree and the tab order.

Progressive Enhancement

Before the script upgrades the host (or without JavaScript), every lens child is shown, stacked and separated by a top border, and no chips are rendered. Lens children that render from data-lens-src need JavaScript themselves, so author meaningful light-DOM fallback content inside them where you can.

Reader sovereignty

The lens family follows VB's reader-sovereignty principle: the author defines the exposed view, the reader can always reframe. <content-lens> exposes the radio chips by default; authors who want to lock to a single view can set data-lens-controls="off", but the underlying data is still discoverable via the shared data-lens-src.

Related
↑