@ponchia/ui 0.3.6 → 0.4.1

package/README.md

@@ -3,12 +3,12 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![dist](https://img.shields.io/badge/dist-~73kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![dist](https://img.shields.io/badge/dist-~75kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
 
-**A CSS-first, framework-agnostic UI framework with a "Nothing"-inspired look — monochrome surfaces, one rationed red accent, dot-matrix display type, hairline borders, restrained motion. Zero runtime dependencies. Re-brand the whole thing with one CSS variable.**
+**A CSS-first, framework-agnostic UI framework built on token-driven restraint — monochrome by default, one rationed accent, dot-matrix display type, hairline borders. Color is _tiered_: we don't decorate with it, we signal with it. The "Nothing"-inspired look is the default skin, not the architecture — opt-in colorways (amber CRT · phosphor green · e-ink), a dot-matrix icon set, and a colourblind-safe data-viz palette prove the one knob is real. Zero runtime dependencies; re-brand the whole thing with one CSS variable.**
 
 ### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
 
@@ -34,7 +34,7 @@ Or drop it in with no build step, straight from a CDN:
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified bundle — the whole framework, one request (~73 kB raw / ~13 kB gzip):
+**1. Load the CSS.** One flattened, minified bundle — the whole framework, one request (~75 kB raw / ~13 kB gzip):
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */
@@ -79,7 +79,7 @@ toast('Saved', { tone: 'success' });   // body-anchored stack, no markup needed
 
 Behaviors cover theme persistence, disclosure, dropdown menus, native-`<dialog>` modals/drawers, tabs, combobox, form validation, table sort, carousel and toasts — wired by `data-bronto-*` attributes.
 
-**5. (Optional) display glyphs — a 43-glyph dot-matrix icon set:**
+**5. (Optional) display glyphs — a 48-glyph dot-matrix icon set:**
 
 ```js
 import { renderGlyph } from '@ponchia/ui/glyphs';
@@ -89,7 +89,7 @@ el.innerHTML = renderGlyph('search', { label: 'Search' });  // role="img"
 // import { initDotGlyph } from '@ponchia/ui/behaviors'; initDotGlyph();
 ```
 
-Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lock, home/user/heart/star/spark — rendered on the same `.ui-dotmatrix` primitive and re-skinned by the `--field-dot*` tokens (no SVG, no font). Default dot look is for **display** sizes; pass **`{ solid: true }`** to fuse the cells into a crisp pixel glyph that works as an **inline icon down to ~16px**.
+Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lock, home/user/heart/star/spark and circle-family marks are rendered on the same `.ui-dotmatrix` primitive and re-skinned by the `--field-dot*` tokens. Default dot look is for **display** sizes; pass **`{ solid: true }`** to fuse the cells into a crisp pixel glyph that works as an **inline icon down to ~16px**. For dense lists/tables, `renderGlyph(name, { render: 'mask' })` emits one `.ui-icon` element backed by an internal CSS mask.
 
 ## What's in the box
 
@@ -100,7 +100,11 @@ Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lo
 - **Disclosure & nav** — tabs, accordion, segmented, breadcrumb, pagination, `ui-steps`, `ui-timeline`, `ui-pagehead`, `ui-kbd`.
 - **Shells** — an admin dashboard shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
 - **Prose** — `.ui-prose` styles raw, unclassed semantic HTML (Markdown / CMS / LLM output) with zero classes.
+- **Reports** _(opt-in)_ — `@ponchia/ui/css/report.css`, a static/PDF-first report grammar for LLM-authored HTML: covers, sections, findings, evidence, figures, chart wrappers and print utilities.
 - **Motion & dots** — the dot-matrix motif kit: dot grid, status dots, dot loaders, the orbital spinner, matrix reveal — all reduced-motion aware.
+- **Glyphs** — `@ponchia/ui/glyphs`, a 48-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).
+- **Colorways** _(opt-in)_ — `data-bronto-skin="amber-crt | phosphor-green | e-ink"`: a root-level recolour of the one accent (OKLCH, per-theme, contrast-gated), never in the default bundle.
+- **Data-viz** _(opt-in)_ — a colourblind-safe chart palette (`--chart-*` + dot-matrix pattern fills, resolved hex in `charts.json`), gated under simulated protan/deutan/tritan vision. Charts only, never UI chrome.
 
 Full generated catalog of every class: **[docs/reference.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/reference.md)**. The decision guide (which primitive when): **[docs/usage.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/usage.md)**.
 
@@ -115,11 +119,17 @@ Everything accent-colored derives from a single `--accent` variable via `color-m
 
 Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the "Nothing" look is the **default skin, not the architecture**.
 
+**One system, many skins.** That the knob is real isn't a claim — it ships: drop in `@ponchia/ui/css/skins.css` and set `data-bronto-skin="amber-crt | phosphor-green | e-ink"` on `<html>` for a complete, contrast-gated recolour (the derived accent family, focus ring, dot-matrix and glyphs all follow). Colour is governed in **tiers** — neutral canvas · one accent · locked status · display expression · opt-in data-viz — so it always earns its place; the full constitution is **[ADR-0001](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)**.
+
 > When you change `--accent`, contrast becomes yours: verify your hue in the **[theme playground](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)** (it shows the derived family and computed WCAG ratios). Full contract: **[docs/theming.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/theming.md)**.
 
+## Accessibility
+
+Not an afterthought — a gate. Every contractual token pairing has a declared WCAG 2.1 conformance level the build **fails** below (`docs/contrast.md`, regenerated + CI-checked), and the shipped colorways are held to the same floors. The data-viz palette is gated for distinctness under simulated protanopia/deuteranopia/tritanopia, and never relies on colour alone (dot-matrix pattern fills). APCA `Lc` is published advisory alongside WCAG. Components ship ARIA-correct markup and SSR-safe keyboard behaviors; `prefers-reduced-motion`, `prefers-contrast` and `forced-colors` are all honored.
+
 ## Works with anything
 
-The CSS is the framework, so it works with React, Svelte/SvelteKit, Astro, Vue, Solid or plain HTML — there's no component runtime to adopt. The optional `classes` and `behaviors` entrypoints pull in **no** UI framework and are SSR-safe.
+The CSS is the framework, so it works with React, Svelte/SvelteKit, Astro, Vue, Solid, Qwik or plain HTML — there's no component runtime to adopt. The optional `classes` and `behaviors` entrypoints pull in **no** UI framework and are SSR-safe. For React, Solid and Qwik there are also **optional thin bindings** — `@ponchia/ui/react`, `@ponchia/ui/solid` and `@ponchia/ui/qwik` wrap the behaviors as hooks (`useDialog`, `useToast`, …); `react`/`solid-js`/`@builder.io/qwik` are optional peer deps, so the core stays zero-dependency.
 
 Per-framework getting-started guides + runnable example apps live in the repo:
 
@@ -128,36 +138,43 @@ Per-framework getting-started guides + runnable example apps live in the repo:
 | Vanilla / Vite / plain HTML | [vanilla.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/vanilla.md) | [`examples/vanilla-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/vanilla-vite) |
 | Astro | [astro.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/astro.md) | [`examples/astro`](https://github.com/Ponchia/bronto-ui/tree/main/examples/astro) |
 | SvelteKit | [sveltekit.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/sveltekit.md) | [`examples/sveltekit`](https://github.com/Ponchia/bronto-ui/tree/main/examples/sveltekit) |
-| React / Solid (snippet) | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | — |
+| React | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/react-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/react-vite) |
+| Solid | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/solid-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/solid-vite) |
+| Qwik | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/qwik-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/qwik-vite) |
 | Tailwind / cascade-layer interop | [tailwind.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/interop/tailwind.md) | — |
 
 ## Extras
 
-- **Tokens as data** — `import tokens, { themeColor, cssVars } from '@ponchia/ui/tokens'` (plus `tokens.json`, W3C DTCG `tokens.dtcg.json`, and `tokens/resolved.json` for charts/data-viz).
+- **Tokens as data** — `import tokens, { themeColor, cssVars } from '@ponchia/ui/tokens'` (plus `tokens.json`, W3C DTCG `tokens.dtcg.json`, and `tokens/resolved.json` — concrete hex per theme for canvas/SVG/MapLibre).
+- **Chart colours for dashboards** — `import charts from '@ponchia/ui/charts.json' with { type: 'json' }` in Node ESM, or the same path through a bundler JSON import (resolved hex per theme; series 1 = your accent) plus the opt-in `@ponchia/ui/css/dataviz.css`.
+- **Static reports for LLMs** — add `@ponchia/ui/css/report.css` for report structure and print utilities; pair with `@ponchia/ui/css/dataviz.css` only when the report contains charts. Full cookbook: `docs/reporting.md`.
+- **Modern-platform motion** — overlays (modal/drawer/popover), toasts and the `<details>` accordion animate **in and out** with zero JS (`@starting-style` + `allow-discrete`, `::details-content` + `interpolate-size`). Progressive-enhancement extras: `.ui-scroll-progress` / `.ui-scroll-reveal` (scroll-driven, no JS) and `.ui-vt` for View Transitions. All degrade to a static end-state and respect `prefers-reduced-motion`. For smooth **cross-document** navigations, add the document-global one-liner to your own top-level (unlayered) CSS: `@view-transition { navigation: auto; }`.
 - **Editor IntelliSense** — point VS Code at the shipped custom-data file so every token autocompletes in `var(--…)`:
   ```json
   { "css.customData": ["node_modules/@ponchia/ui/classes/vscode.css-custom-data.json"] }
   ```
-- **For AI coding agents** — the package ships `llms.txt` at its root plus `docs/reference.md`, `docs/usage.md` and `docs/theming.md` inside the tarball, so an offline agent has the full API without guessing.
+- **For AI coding agents** — the package ships `llms.txt` at its root plus `docs/reference.md`, `docs/usage.md`, `docs/reporting.md`, `docs/theming.md`, `docs/contrast.md`, `docs/stability.md`, the color constitution `docs/adr/0001-color-system.md` and the `CHANGELOG` inside the tarball, so an offline agent has the full API and rationale without guessing.
 
-> The package root is **CSS-only**: `@import '@ponchia/ui'` in CSS, never `import '@ponchia/ui'` in JS. The JS entrypoints are the explicit subpaths `/tokens`, `/classes`, `/behaviors`, `/glyphs`.
+> The package root is **CSS-only**. Use `@import '@ponchia/ui'` in CSS, or `import '@ponchia/ui'` only as a CSS side-effect import in a CSS-aware bundler (Vite, Astro, SvelteKit, webpack). Do not import the package root from Node/runtime JS. JS entrypoints are explicit subpaths: `/tokens`, `/classes`, `/behaviors`, `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, and `/charts`.
+> JS subpaths are **ESM-only**. CommonJS consumers should use dynamic
+> `import('@ponchia/ui/behaviors')`.
 
 ## Browser support
 
-Evergreen only. The framework relies on cascade layers, `:has()`, `color-mix()`, CSS logical properties and native `<dialog>`. Floor: **Chrome/Edge 111+, Safari 16.4+, Firefox 121+** (early 2023 onward). No build-time fallback ships; pin an older tag if you need below this.
+Recent-evergreen, by design. The framework targets the modern web platform — cascade layers, `:has()`, `color-mix()`/`oklch()`, logical properties, native `<dialog>`, and the 2026 interaction primitives (`@starting-style`, `transition-behavior: allow-discrete`, `light-dark()`). Floor: **Chrome/Edge 125+, Safari 18+, Firefox 129+** (early–mid 2025). No fallback ships below this — pin an older tag if you need it. See [ADR-0002](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0002-scope-and-2026-baseline.md) for the scope/greenfield rationale.
 
 ## Versioning
 
-Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.3.0` (and equivalently `^0.3.0`) resolves to `>=0.3.0 <0.4.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
+Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.4.0` (and equivalently `^0.4.0`) resolves to `>=0.4.0 <0.5.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
 
-Contractual (changes are breaking): the `--accent` derivation and token **names**, the `.ui-*` class and recipe names, the `data-bronto-*` attributes, and each behavior's cleanup contract. Not contractual (may change any release): token **values** (visual tuning) and internal leaf-file / `@layer` boundaries.
+Contractual (changes are breaking): token **names** and documented token roles, `.ui-*` class and recipe names, `data-bronto-*` attributes, exported behavior/glyph/binding function names and each behavior's cleanup contract. Not contractual (may change any release): exact token **values** and generated colour math outputs (visual tuning) unless a doc explicitly says the value is stable, plus internal leaf-file / `@layer` boundaries. See **[docs/stability.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/stability.md)** for the full public-surface matrix.
 
 Release candidates publish to the `next` dist-tag, never to `latest` — opt in with `npm i @ponchia/ui@next` to try an upcoming version early. A plain `npm i @ponchia/ui` only ever resolves a stable release.
 
 ## Links
 
 - **[Live demo](https://ponchia.github.io/bronto-ui/)** · **[Theme playground](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)**
-- **[Class reference](https://github.com/Ponchia/bronto-ui/blob/main/docs/reference.md)** · **[Usage guide](https://github.com/Ponchia/bronto-ui/blob/main/docs/usage.md)** · **[Theming](https://github.com/Ponchia/bronto-ui/blob/main/docs/theming.md)** · **[Contrast](https://github.com/Ponchia/bronto-ui/blob/main/docs/contrast.md)**
+- **[Class reference](https://github.com/Ponchia/bronto-ui/blob/main/docs/reference.md)** · **[Usage guide](https://github.com/Ponchia/bronto-ui/blob/main/docs/usage.md)** · **[Theming](https://github.com/Ponchia/bronto-ui/blob/main/docs/theming.md)** · **[Contrast](https://github.com/Ponchia/bronto-ui/blob/main/docs/contrast.md)** · **[Color system (ADR-0001)](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)** · **[Scope & 2026 baseline (ADR-0002)](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0002-scope-and-2026-baseline.md)**
 - **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** · **[Roadmap](https://github.com/Ponchia/bronto-ui/blob/main/ROADMAP.md)** · **[Contributing](https://github.com/Ponchia/bronto-ui/blob/main/CONTRIBUTING.md)**
 
 ## License

package/behaviors/index.d.ts

@@ -102,7 +102,9 @@ export declare function initTabs(opts?: DelegateOpts): Cleanup;
 /**
  * Wire native <dialog> open/close glue: `[data-bronto-open="id"]`,
  * `[data-bronto-close]`, and backdrop light-dismiss for dialogs marked
- * `[data-bronto-dialog-light]`. Returns a cleanup function.
+ * `[data-bronto-dialog-light]`. `root` scopes delegated controls; dialog ids
+ * resolve root-first, then document-wide for body/portal-mounted overlays.
+ * Returns a cleanup function.
  */
 export declare function initDialog(opts?: DelegateOpts): Cleanup;
 

package/behaviors/index.js

@@ -54,6 +54,24 @@ function bindOnce(target, key, add) {
   return cleanup;
 }
 
+function byIdInHost(host, id) {
+  if (!id) return null;
+  if (host === document) return document.getElementById(id);
+  if (host.id === id) return host;
+  return (
+    Array.from(host.querySelectorAll?.('[id]') || []).find((el) => el.id === id) ||
+    document.getElementById(id)
+  );
+}
+
+function closestSafe(el, selector) {
+  try {
+    return el.closest(selector);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Apply the persisted theme to <html data-theme>. Call as early as
  * possible (an inline module in <head>) to avoid a flash before the
@@ -145,7 +163,7 @@ export function dismissible({ root } = {}) {
     const btn = e.target.closest('[data-bronto-dismiss]');
     if (!btn || !host.contains(btn)) return;
     const sel = btn.getAttribute('data-bronto-dismiss');
-    const target = sel ? btn.closest(sel) : btn.closest('[data-bronto-dismissible]');
+    const target = sel ? closestSafe(btn, sel) : btn.closest('[data-bronto-dismissible]');
     if (!target) return;
     const ev = new CustomEvent('bronto:dismiss', { bubbles: true, cancelable: true });
     if (target.dispatchEvent(ev)) target.remove();
@@ -264,81 +282,73 @@ export function initTabs({ root } = {}) {
  * `close` event, so keyboard/SR users are never dropped at `<body>`.
  * SSR-safe and idempotent; returns cleanup.
  *
- * `root` scopes which triggers are delegated (default `document`); the
- * dialog itself is still resolved by id document-wide, because a modal
- * <dialog> is promoted to the top layer and is inherently document-global
- * (same model as `initThemeToggle`, where `root` scopes controls but the
- * theme applies to <html>).
+ * `root` scopes delegated triggers (default `document`). Controlled targets are
+ * resolved root-first, then document-wide, so scoped islands win duplicate-id
+ * conflicts without breaking body/portal-mounted overlays.
  */
 export function initDialog({ root } = {}) {
   if (!hasDom()) return noop;
   const host = root || document;
+  const managedDialogs = new WeakSet();
+  const canManageDialog = (dlg, origin) => host.contains(origin) || managedDialogs.has(dlg);
+
+  const openFrom = (opener) => {
+    const dlg = byIdInHost(host, opener.getAttribute('data-bronto-open'));
+    if (!dlg || typeof dlg.showModal !== 'function' || dlg.open) return;
+    managedDialogs.add(dlg);
+    dlg.addEventListener(
+      'close',
+      () => {
+        if (opener.isConnected && typeof opener.focus === 'function') opener.focus();
+      },
+      { once: true },
+    );
+    dlg.showModal();
+  };
+
+  const closeFrom = (closer) => {
+    const dlg = closer.closest('dialog');
+    if (dlg && dlg.open && canManageDialog(dlg, closer)) dlg.close();
+  };
+
+  const lightDismiss = (dlg) => {
+    if (
+      dlg.tagName === 'DIALOG' &&
+      dlg.open &&
+      dlg.hasAttribute('data-bronto-dialog-light') &&
+      canManageDialog(dlg, dlg)
+    ) {
+      dlg.close();
+    }
+  };
+
   const onClick = (e) => {
     const opener = e.target.closest('[data-bronto-open]');
     if (opener && host.contains(opener)) {
-      const dlg = document.getElementById(opener.getAttribute('data-bronto-open'));
-      if (dlg && typeof dlg.showModal === 'function' && !dlg.open) {
-        dlg.addEventListener(
-          'close',
-          () => {
-            if (opener.isConnected && typeof opener.focus === 'function') opener.focus();
-          },
-          { once: true },
-        );
-        dlg.showModal();
-      }
+      openFrom(opener);
       return;
     }
     const closer = e.target.closest('[data-bronto-close]');
-    if (closer && host.contains(closer)) {
-      const dlg = closer.closest('dialog');
-      if (dlg && dlg.open) dlg.close();
+    if (closer) {
+      closeFrom(closer);
       return;
     }
     // Light-dismiss: a click whose target is the <dialog> itself is the
     // backdrop (content sits in child elements).
-    const dlg = e.target;
-    if (
-      dlg.tagName === 'DIALOG' &&
-      dlg.open &&
-      dlg.hasAttribute('data-bronto-dialog-light') &&
-      host.contains(dlg)
-    ) {
-      dlg.close();
-    }
+    lightDismiss(e.target);
   };
   return bindOnce(host, 'dialog', () => {
-    host.addEventListener('click', onClick);
-    return () => host.removeEventListener('click', onClick);
+    document.addEventListener('click', onClick);
+    return () => document.removeEventListener('click', onClick);
   });
 }
 
-/**
- * Push a transient toast into a shared, screen-anchored stack. The stack
- * is the `aria-live="polite"` region: it is created once, appended to
- * <body>, and **kept resident even when empty** so the live region is
- * always present before content is inserted (a freshly created region
- * that receives its first child in the same tick is not reliably
- * announced by VoiceOver/NVDA). On first creation the empty region is
- * inserted and the toast is appended on the next frame for the same
- * reason. `tone` is accent/success/warning/danger/info; `title` is an
- * optional uppercase label; `duration` ms before auto-dismiss (0 keeps
- * it until dismissed). Returns a function that dismisses the toast
- * early. SSR-safe (no-op).
- */
-export function toast(message, { tone, title, duration = 4000, assertive, closable } = {}) {
-  if (!hasDom()) return noop;
-  // Errors must interrupt: danger toasts (or an explicit `assertive`)
-  // go to a SEPARATE assertive region so they announce immediately,
-  // while status toasts stay polite. Two regions — not a per-item
-  // role=alert nested in a polite parent — avoids the double
-  // announcement that nesting causes in some screen readers.
-  const isAssertive = assertive ?? tone === 'danger';
+function toastStack(isAssertive) {
   const stackSel = isAssertive
     ? '.ui-toast-stack--assertive'
     : '.ui-toast-stack:not(.ui-toast-stack--assertive)';
   let stack = document.querySelector(stackSel);
-  const freshStack = !stack;
+  const fresh = !stack;
   if (!stack) {
     stack = document.createElement('div');
     stack.className = isAssertive ? 'ui-toast-stack ui-toast-stack--assertive' : 'ui-toast-stack';
@@ -346,6 +356,26 @@ export function toast(message, { tone, title, duration = 4000, assertive, closab
     if (isAssertive) stack.setAttribute('role', 'alert');
     document.body.appendChild(stack);
   }
+  return { stack, fresh };
+}
+
+function enqueueToast(place, freshStack) {
+  const canDefer = typeof requestAnimationFrame === 'function';
+  if (freshStack && canDefer) {
+    toastQueue.push(place);
+    toastFlushScheduled = true;
+    requestAnimationFrame(() => {
+      toastFlushScheduled = false;
+      for (const fn of toastQueue.splice(0)) fn();
+    });
+  } else if (toastFlushScheduled) {
+    toastQueue.push(place);
+  } else {
+    place();
+  }
+}
+
+function toastElement(message, { tone, title }) {
   const el = document.createElement('div');
   el.className = tone ? `ui-toast ui-toast--${tone}` : 'ui-toast';
   // No per-item role: the stack itself is the live region; a nested
@@ -359,6 +389,72 @@ export function toast(message, { tone, title, duration = 4000, assertive, closab
   const body = document.createElement('div');
   body.textContent = message;
   el.appendChild(body);
+  return el;
+}
+
+// Remove a toast, animating its exit when — and only when — a transition
+// is actually in effect. Detached nodes, reduced-motion, and the no-CSS
+// test/SSR env all resolve to instant removal, so the dismiss contract
+// (toast gone now, the aria-live stack stays resident) is unchanged there;
+// a real browser with motion gets the CSS `.is-leaving` fade-out, with a
+// timeout fallback so an interrupted/never-firing transitionend can't strand
+// a toast in the live region.
+function removeToast(el) {
+  const reduce =
+    typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const cs =
+    !reduce && el.isConnected && typeof getComputedStyle === 'function'
+      ? getComputedStyle(el)
+      : null;
+  const dur = cs ? parseFloat(cs.transitionDuration) || 0 : 0;
+  if (dur <= 0) {
+    el.remove();
+    return;
+  }
+  el.classList.add('is-leaving');
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    el.remove();
+  };
+  el.addEventListener('transitionend', finish, { once: true });
+  const timer = setTimeout(finish, dur * 1000 + 120);
+  timer?.unref?.(); // don't keep a Node test process alive
+}
+
+function addToastClose(el, dismiss) {
+  const close = document.createElement('button');
+  close.type = 'button';
+  close.className = 'ui-toast__close';
+  close.setAttribute('aria-label', 'Dismiss');
+  close.addEventListener('click', dismiss);
+  el.appendChild(close);
+}
+
+/**
+ * Push a transient toast into a shared, screen-anchored stack. The stack
+ * is the `aria-live="polite"` region: it is created once, appended to
+ * <body>, and **kept resident even when empty** so the live region is
+ * always present before content is inserted (a freshly created region
+ * that receives its first child in the same tick is not reliably
+ * announced by VoiceOver/NVDA). On first creation the empty region is
+ * inserted and the toast is appended on the next frame for the same
+ * reason. `tone` is accent/success/warning/danger/info; `title` is an
+ * optional uppercase label; `duration` ms before auto-dismiss (0 keeps
+ * it until dismissed). Returns a function that dismisses the toast
+ * early. SSR-safe (no-op).
+ */
+export function toast(message, { tone, title, duration = 4000, assertive, closable } = {}) {
+  if (!hasDom()) return noop;
+  // Errors must interrupt: danger toasts (or an explicit `assertive`)
+  // go to a SEPARATE assertive region so they announce immediately,
+  // while status toasts stay polite. Two regions — not a per-item
+  // role=alert nested in a polite parent — avoids the double
+  // announcement that nesting causes in some screen readers.
+  const isAssertive = assertive ?? tone === 'danger';
+  const { stack, fresh: freshStack } = toastStack(isAssertive);
+  const el = toastElement(message, { tone, title });
   // Append after a frame the *first* time so the empty live region is
   // observed by AT before its first child arrives; once the region has
   // been observed, later toasts append synchronously.
@@ -369,28 +465,14 @@ export function toast(message, { tone, title, duration = 4000, assertive, closab
   const place = () => {
     if (!dismissed) stack.appendChild(el);
   };
-  const canDefer = typeof requestAnimationFrame === 'function';
-  if (freshStack && canDefer) {
-    toastQueue.push(place);
-    toastFlushScheduled = true;
-    requestAnimationFrame(() => {
-      toastFlushScheduled = false;
-      for (const fn of toastQueue.splice(0)) fn();
-    });
-  } else if (toastFlushScheduled) {
-    // A first-frame deferral is in flight — queue behind it so FIFO
-    // order holds and the region still isn't populated synchronously.
-    toastQueue.push(place);
-  } else {
-    place();
-  }
+  enqueueToast(place, freshStack);
 
   let timer;
   const dismiss = () => {
     if (dismissed) return;
     dismissed = true;
     if (timer) clearTimeout(timer);
-    el.remove();
+    removeToast(el);
     // The stack is a persistent live region — never removed on drain, so
     // the next toast does not recreate (and thus mis-announce) it.
   };
@@ -398,14 +480,7 @@ export function toast(message, { tone, title, duration = 4000, assertive, closab
   // it gets a dismiss affordance by default; any toast can opt in via
   // `closable`. The button carries no text node (glyph is a CSS
   // ::before) so the toast's announced/textContent stays the message.
-  if (closable ?? duration === 0) {
-    const close = document.createElement('button');
-    close.type = 'button';
-    close.className = 'ui-toast__close';
-    close.setAttribute('aria-label', 'Dismiss');
-    close.addEventListener('click', dismiss);
-    el.appendChild(close);
-  }
+  if (closable ?? duration === 0) addToastClose(el, dismiss);
   if (duration > 0) timer = setTimeout(dismiss, duration);
   return dismiss;
 }
@@ -422,7 +497,7 @@ export function initDisclosure({ root } = {}) {
     const trigger = e.target.closest('[data-bronto-disclosure]');
     if (!trigger || !host.contains(trigger)) return;
     const id = trigger.getAttribute('aria-controls');
-    const panel = id && document.getElementById(id);
+    const panel = byIdInHost(host, id);
     if (!panel) return;
     const open = trigger.getAttribute('aria-expanded') === 'true';
     trigger.setAttribute('aria-expanded', String(!open));
@@ -755,6 +830,24 @@ export function initCombobox({ root } = {}) {
       active = options.indexOf(vis[next]);
       setActive(options[active]);
     };
+    const activateEdge = (which) => {
+      if (list.hidden) return false;
+      const v = visible();
+      if (!v.length) return true;
+      active = options.indexOf(which === 'first' ? v[0] : v[v.length - 1]);
+      setActive(options[active]);
+      return true;
+    };
+    const selectActive = () => {
+      if (list.hidden || active < 0 || options[active].hidden) return false;
+      select(options[active]);
+      return true;
+    };
+    const closeIfOpen = () => {
+      if (list.hidden) return false;
+      close();
+      return true;
+    };
 
     const onInput = () => filter();
     const onKey = (e) => {
@@ -768,36 +861,16 @@ export function initCombobox({ root } = {}) {
           move(-1);
           break;
         case 'Home':
-          if (!list.hidden) {
-            e.preventDefault();
-            const v = visible();
-            if (v.length) {
-              active = options.indexOf(v[0]);
-              setActive(options[active]);
-            }
-          }
+          if (activateEdge('first')) e.preventDefault();
           break;
         case 'End':
-          if (!list.hidden) {
-            e.preventDefault();
-            const v = visible();
-            if (v.length) {
-              active = options.indexOf(v[v.length - 1]);
-              setActive(options[active]);
-            }
-          }
+          if (activateEdge('last')) e.preventDefault();
           break;
         case 'Enter':
-          if (!list.hidden && active >= 0 && !options[active].hidden) {
-            e.preventDefault();
-            select(options[active]);
-          }
+          if (selectActive()) e.preventDefault();
           break;
         case 'Escape':
-          if (!list.hidden) {
-            e.preventDefault();
-            close();
-          }
+          if (closeIfOpen()) e.preventDefault();
           break;
         case 'Tab':
           close();
@@ -904,8 +977,8 @@ export function initPopover({ root } = {}) {
 
   const onClick = (e) => {
     const trigger = e.target.closest?.('[data-bronto-popover]');
-    if (trigger) {
-      const panel = document.getElementById(trigger.getAttribute('data-bronto-popover'));
+    if (trigger && host.contains(trigger)) {
+      const panel = byIdInHost(host, trigger.getAttribute('data-bronto-popover'));
       if (!panel) return;
       e.preventDefault();
       if (openPanel === panel) close();
@@ -926,12 +999,12 @@ export function initPopover({ root } = {}) {
   };
 
   return bindOnce(host, 'popover', () => {
-    host.addEventListener('click', onClick);
+    document.addEventListener('click', onClick);
     document.addEventListener('keydown', onKey);
     view?.addEventListener('scroll', onReflow, true);
     view?.addEventListener('resize', onReflow);
     return () => {
-      host.removeEventListener('click', onClick);
+      document.removeEventListener('click', onClick);
       document.removeEventListener('keydown', onKey);
       view?.removeEventListener('scroll', onReflow, true);
       view?.removeEventListener('resize', onReflow);

package/classes/index.d.ts

@@ -65,6 +65,7 @@ export declare const cls: {
   readonly dotmatrixCellAccent: 'ui-dotmatrix__cell--accent';
   readonly dotmatrixReveal: 'ui-dotmatrix--reveal';
   readonly dotmatrixPulse: 'ui-dotmatrix--pulse';
+  readonly icon: 'ui-icon';
   readonly dotfield: 'ui-dotfield';
   readonly dotrule: 'ui-dotrule';
   readonly dotbar: 'ui-dotbar';
@@ -231,6 +232,43 @@ export declare const cls: {
   readonly timeline: 'ui-timeline';
   readonly timelineItem: 'ui-timeline__item';
   readonly timelineTime: 'ui-timeline__time';
+  readonly report: 'ui-report';
+  readonly reportCompact: 'ui-report--compact';
+  readonly reportNumbered: 'ui-report--numbered';
+  readonly reportCover: 'ui-report__cover';
+  readonly reportCoverCompact: 'ui-report__cover--compact';
+  readonly reportHeader: 'ui-report__header';
+  readonly reportTitle: 'ui-report__title';
+  readonly reportSubtitle: 'ui-report__subtitle';
+  readonly reportMeta: 'ui-report__meta';
+  readonly reportToc: 'ui-report__toc';
+  readonly reportSummary: 'ui-report__summary';
+  readonly reportSection: 'ui-report__section';
+  readonly reportSectionUnnumbered: 'ui-report__section--unnumbered';
+  readonly reportSectionHead: 'ui-report__section-head';
+  readonly reportFinding: 'ui-report__finding';
+  readonly reportEvidence: 'ui-report__evidence';
+  readonly reportFigure: 'ui-report__figure';
+  readonly reportCaption: 'ui-report__caption';
+  readonly reportSources: 'ui-report__sources';
+  readonly reportAppendix: 'ui-report__appendix';
+  readonly reportFootnotes: 'ui-report__footnotes';
+  readonly chart: 'ui-chart';
+  readonly chartLegend: 'ui-chart__legend';
+  readonly chartSwatch: 'ui-chart__swatch';
+  readonly chartCaption: 'ui-chart__caption';
+  readonly chartPlot: 'ui-chart__plot';
+  readonly chartBar: 'ui-chart__bar';
+  readonly chartLabel: 'ui-chart__label';
+  readonly chartTrack: 'ui-chart__track';
+  readonly chartFill: 'ui-chart__fill';
+  readonly chartFallback: 'ui-chart__fallback';
+  readonly printOnly: 'ui-print-only';
+  readonly screenOnly: 'ui-screen-only';
+  readonly breakBefore: 'ui-break-before';
+  readonly breakAfter: 'ui-break-after';
+  readonly keep: 'ui-keep';
+  readonly printExact: 'ui-print-exact';
   readonly kbd: 'ui-kbd';
   readonly display: 'ui-display';
   readonly mono: 'ui-mono';
@@ -247,6 +285,9 @@ export declare const cls: {
   readonly animateFade: 'ui-animate-fade';
   readonly animateDot: 'ui-animate-dot';
   readonly animateMatrix: 'ui-animate-matrix';
+  readonly scrollProgress: 'ui-scroll-progress';
+  readonly scrollReveal: 'ui-scroll-reveal';
+  readonly vt: 'ui-vt';
   readonly appShell: 'ui-app-shell';
   readonly appShellFull: 'ui-app-shell--full';
   readonly appRail: 'ui-app-rail';