npm - @ponchia/ui - Versions diffs - 0.2.1 → 0.3.0 - Mend

@ponchia/ui 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

package/README.md CHANGED Viewed

@@ -4,6 +4,9 @@ Shared UI framework for Bronto personal projects. Nothing-inspired:
 monochrome surfaces, a single red accent, dot-matrix display type (Doto),
 flat hairline borders, restrained motion. CSS-first and framework-agnostic.
+**[Live demo →](https://ponchia.github.io/bronto-ui/)** — the kitchen
+sink (every component, light/dark, RTL, theming) deployed from `demo/`.
 ## Use
 Install from npm (public, no registry config):
@@ -18,31 +21,42 @@ npm i @ponchia/ui
 > deliberately distinct from the package name. See
 > [`docs/architecture.md`](docs/architecture.md).
-> Not published yet — the only remaining blocker is npm-account side
-> (create the `@ponchia` scope + `NPM_TOKEN`; see [Release](#release)).
-> Until the first publish, depend on a `file:` link to a checkout or a
-> pinned git tag:
->
-> ```json
-> { "dependencies": { "@ponchia/ui": "file:../bronto-ui" } }
-> ```
->
-> ```json
-> { "dependencies": { "@ponchia/ui": "github:Ponchia/bronto-ui#semver:^0.2.0" } }
-> ```
-Import the full theme (includes responsive breakpoints):
+Import the theme (one bundle — `ui-*` components carry their own
+breakpoints, so there is no separate core/full split as of 0.3.0):
 ```css
-@import '@ponchia/ui/css';
+@import '@ponchia/ui/css';        /* === @ponchia/ui/css/core.css */
 ```
-Or the core bundle if the app manages its own responsive layer:
+**Prebuilt single file (recommended for apps without a CSS bundler).**
+`@ponchia/ui/css` is a wide `@import` fan-out (~14 leaves, one level
+deep) — fine through a bundler, a load waterfall over plain HTTP. The
+package also ships one flattened, minified bundle with no `@import`
+chain:
 ```css
-@import '@ponchia/ui/css/core.css';
+@import '@ponchia/ui';   /* → dist/bronto.css, the whole framework */
 ```
+~54 kB raw / ~10 kB gzip, one request, same `@layer bronto`. (The
+enforced ceiling lives in `scripts/check-dist.mjs`, not this prose —
+treat these figures as indicative.) Source CSS, tokens/classes/behaviors
+entrypoints are unchanged — use whichever fits.
+> **The package root is CSS-only.** `@ponchia/ui` (the `.` export)
+> resolves to a stylesheet — `@import '@ponchia/ui'` in CSS, never
+> `import '@ponchia/ui'` in JS. There is no JS module at the root; the
+> JS entrypoints are the explicit subpaths `@ponchia/ui/tokens`,
+> `/classes`, and `/behaviors` (see [Entrypoints](#entrypoints)).
+### Browser support
+Evergreen only — the framework relies on cascade layers (`@layer`),
+`: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 is shipped; pin an older tag if you must
+support below this.
 The Doto `@font-face` ships in `css/fonts.css` (bundled by both `css` and
 `css/core.css`) with URLs relative to the package, so it resolves through a
 bundler or static serving with no `/fonts` path assumption. To self-host the
@@ -51,14 +65,23 @@ font instead, import everything except `fonts.css` and override `--display` /
 Everything ships inside a single `@layer bronto`, so any un-layered CSS in
 your app overrides the framework without a specificity fight or `!important`.
-The layer is applied by the `css` and `css/core.css` bundles only —
-importing an individual leaf such as `@ponchia/ui/css/primitives.css`
-directly is **unlayered** (full specificity), which is an intentional
-escape hatch, not the default path.
+> **Leaf imports are layer-safe by default.** Every per-leaf export —
+> `@ponchia/ui/css/primitives.css`, etc. — is self-wrapped in
+> `@layer bronto`, so mixing the bundle with individual leaves (e.g.
+> per-route CSS splitting in SvelteKit/Astro) is safe: no silent
+> cascade inversion. The deliberate full-specificity escape hatch is
+> the explicit `@ponchia/ui/css/unlayered/<leaf>.css` path — use it
+> only when you *want* an unlayered override, never by accident.
 Set `data-theme="light"` or `data-theme="dark"` on `<html>`; defaults follow
 `prefers-color-scheme`.
+**Re-brand with one knob:** `--accent` drives the whole accent family
+(`color-mix`-derived). `:root { --accent: #2f6df6 }` — or scope it to a
+subtree — restyles everything, both themes. Plus `data-density` and
+`data-contrast` presets. Full contract: [`docs/theming.md`](docs/theming.md).
 ## Entrypoints
 The CSS is the framework. These optional sibling entrypoints are thin layers
@@ -77,9 +100,14 @@ themeColor('dark').accent; // → "#ff3b41"
 ```
 `behaviors` wires `[data-bronto-theme-toggle]`, `[data-bronto-dismiss]` /
-`[data-bronto-dismissible]`, and `[data-bronto-disclosure]`. Each initializer
-is SSR-safe and returns a cleanup function. `demo/index.html` drives itself
-with these modules, so it is also a live integration test.
+`[data-bronto-dismissible]`, `[data-bronto-disclosure]`,
+`[data-bronto-menu]` (`initMenu`: Escape / outside-click /
+close-on-activate for a `<details>` `.ui-menu` dropdown), and native
+`<dialog>` glue (`initDialog`: `[data-bronto-open]` / `[data-bronto-close]`
+/ `[data-bronto-dialog-light]`). `toast(message, { tone, title, duration })`
+pushes into a shared, body-anchored stack. Each initializer is SSR-safe and
+returns a cleanup function. `demo/index.html` drives itself with these
+modules, so it is also a live integration test.
 ## Layout
@@ -89,16 +117,17 @@ with these modules, so it is also a live integration test.
 | `fonts.css`      | Doto `@font-face` (relative URLs; optional if self-hosting)    |
 | `base.css`       | reset, element defaults, focus, scrollbars                    |
 | `motion.css`     | keyframes + animation utilities + reduced-motion              |
-| `dots.css`       | dot-grid, dot rule, status dot, dot loader/bar, matrix reveal |
+| `dots.css`       | dot-grid, dot rule, status dot, dot loader, orbital dot spinner, dot bar (+ indeterminate), matrix reveal |
 | `primitives.css` | `ui-*` buttons, cards, chips, badges, links, key/value        |
 | `forms.css`      | inputs, select, textarea, search, switch, checkbox            |
+| `feedback.css`   | alert / callout, toast, tooltip, linear progress              |
+| `overlay.css`    | modal + drawer (native `<dialog>`), dropdown menu             |
+| `disclosure.css` | tabs, accordion (`<details>`), segmented, breadcrumb, pagination, avatar |
 | `table.css`      | `ui-table` dense / comfortable                                |
-| `app.css`        | admin shell: rail, topbar, toolbar, panel, metrics            |
-| `navigation.css` | site nav, menu, theme toggle (dot indicator)                  |
-| `typography.css` | display headings, eyebrows, legacy `.button`                  |
-| `cards.css`      | semantic content cards (token-driven)                         |
-| `layout.css`     | site shell, hero, grids                                       |
-| `responsive.css` | breakpoint overrides                                          |
+| `app.css`        | admin shell: `ui-app-shell`/`-rail`/`-topbar`/`-toolbar`/`-panel`/`-nav`/`-metrics` |
+| `navigation.css` | `ui-themetoggle` (dot-thumb switch)                           |
+| `site.css`       | content-site shell: `ui-container`, `ui-siteheader`/`ui-sitenav` (aria-current), `ui-sitemenu`, `ui-sitefooter`, `ui-skiplink`, `ui-tags`, `ui-meta` |
+| `content.css`    | `.ui-prose` Markdown/raw-HTML long-form (zero classes) + `ui-quote` pull-quote |
 ## Demo
@@ -113,18 +142,64 @@ python3 -m http.server -d . 8080   # then open http://localhost:8080/demo/
 ```bash
 npm install        # stylelint + jsdom (test only)
-npm run check      # lint + 4 integrity checks (exports, tokens, classes, pack)
+npm run check      # lint + 5 integrity checks (exports, tokens, classes, dist, pack)
 npm test           # node:test — pure modules + jsdom behavior tests
-npm run lint:fix   # auto-fix the safe stylistic rules
+npm run lint:fix   # auto-fix the safe stylistic rules + logical properties
 npm run tokens:build  # regenerate tokens/index.json from tokens/index.js
+npm run dist:build    # rebuild the flattened dist/ bundles
 ```
 `npm run check` enforces that the data mirrors cannot drift from the CSS:
 exports/import-graph integrity, `tokens.css` ⇄ `tokens/index.{js,json}`, the
-`classes` registry ⇄ the `.ui-*` selectors, and that the published tarball
-ships only the intended files. CI
-(`.github/workflows/ci.yml`) runs it on every branch push and PR. It never
-publishes — a push to `main` ships nothing.
+`classes` registry ⇄ the `.ui-*` selectors, `dist/` ⇄ `css/` (fresh + in
+budget), and that the published tarball ships only the intended files.
+End-to-end regression is a separate suite (real browsers, so not in the
+zero-dep core check):
+```bash
+npx playwright test   # visual snapshots + axe a11y + cross-engine + modes
+```
+It covers: visual snapshots light/dark/RTL/modal (chromium); axe-core
+WCAG 2.1 A/AA **plus best-practice** in both themes; behavioural specs
+(`:has()`, `color-mix()`, native `<dialog>`, `:dir()`/logical) on
+**chromium + firefox + webkit**; forced-colors / reduced-motion / print
+mode assertions; and a no-console-error / no-404 / document-structure
+gate. Pinned to a Playwright container so baselines are byte-stable; the
+committed baselines under `test/e2e/__screenshots__` were authored in
+that same image. To (re)generate them after an intentional visual
+change, run the **“Update visual baselines”** workflow
+(`workflow_dispatch`) from your branch — it rebuilds them in the pinned
+container and commits them back (never author them on a dev machine —
+cross-OS rasterisation differs). CI (`.github/workflows/ci.yml`) runs the `check` job and
+a containerised `e2e` job on every branch push and PR (and `release.yml`
+gates publish on it). It never publishes — a push to `main` ships nothing.
+## 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 non-breaking. This is the
+standard 0.x reading of SemVer, stated explicitly because this framework
+dresses several apps:
+- Because breaking changes bump the **minor**, the protective range is
+  the patch range. At `0.x` npm resolves **both** `^0.3.0` and `~0.3.0`
+  to `>=0.3.0 <0.4.0` — they are equivalent here, and either gives you
+  only non-breaking `0.3.x` patches while holding back the next
+  (breaking) `0.4.0`. Pin either; pin an **exact** version if you want
+  zero surprise and to adopt each minor deliberately.
+- Every breaking change is called out in [`CHANGELOG.md`](CHANGELOG.md)
+  under a **BREAKING** heading with a migration note.
+**What is contractual** (changes are breaking): the `--accent`
+derivation and token **names** (incl. `--accent-text`, `--focus-ring`);
+the `.ui-*` class names and `cls`/recipe names; the `data-bronto-*`
+behavior attributes; each behavior's return-cleanup contract. **What is
+not** (may change in any release): token _values_ (visual tuning), the
+internal leaf-file boundaries and `@layer` internals, and anything
+explicitly marked legacy/deprecated. Full token contract:
+[`docs/theming.md`](docs/theming.md).
 ## Release
@@ -136,23 +211,22 @@ git tag vX.Y.Z && git push origin vX.Y.Z
 ```
 The tag triggers `.github/workflows/release.yml`: `validate` (read-only
-checks + tag↔version match) → `publish-npm` (only if validate passes) +
-`release-notes`. **The npm publish is the gate** — a failing check means
-the version never reaches npm, so consumers never resolve it. GitHub also
-serves the raw tag tarball ungated, but that is a legacy/fallback path, not
-the documented install. See [`docs/architecture.md`](docs/architecture.md).
-**Before the first real publish** — one npm-account step remains:
-- Create the `@ponchia` npm scope and add an `NPM_TOKEN` repo secret
-  (an npm automation token with publish rights to the scope).
-Done already: MIT `LICENSE`, `version` `0.2.0`, `publishConfig`, the
-gated publish workflow. After publishing, switch the consumer repos'
-dependency specifier to `@ponchia/ui`.
+checks + tag↔version match) **and** `e2e` (Playwright visual + a11y) must
+both pass → `publish-npm` → `release-notes`. **The npm publish is the
+gate** — a failing check or e2e means the version never reaches npm, so
+consumers never resolve it. GitHub also serves the raw tag tarball
+ungated, but that is a legacy/fallback path, not the documented install.
+See [`docs/architecture.md`](docs/architecture.md).
+Published: `@ponchia/ui` is live on npm, released by CI with provenance.
+The `@ponchia` scope and the `NPM_TOKEN` repo secret are in place, so a
+pushed `vX.Y.Z` tag is all a release needs. (The current published
+version is whatever npm's `latest` dist-tag resolves to — this README
+deliberately does not restate it, so it can't drift from the registry.)
 ## Consumers
-Built for two shapes of app: a content/marketing site (imports
-`@ponchia/ui/css/core.css`) and an admin dashboard (imports the full
-`@ponchia/ui/css`). Consuming apps depend on it via `@ponchia/ui`.
+Built for two shapes of app: a content/marketing site (`ui-site*`,
+`ui-prose`) and an admin dashboard (`ui-app-*` shell). Both import the
+one bundle `@ponchia/ui` (or `@ponchia/ui/css`); consuming apps depend
+on it via `@ponchia/ui`.

package/behaviors/index.d.ts CHANGED Viewed

@@ -38,3 +38,39 @@ export declare function dismissible(opts?: DelegateOpts): Cleanup;
 /** Wire `[data-bronto-disclosure]` triggers. Returns a cleanup function. */
 export declare function initDisclosure(opts?: DelegateOpts): Cleanup;
+/**
+ * Close affordances (Escape, outside-click, close-on-activate) for a
+ * native `<details data-bronto-menu>` dropdown holding a `.ui-menu`.
+ * Not a full ARIA menu by design. Returns a cleanup function.
+ */
+export declare function initMenu(opts?: DelegateOpts): Cleanup;
+/**
+ * Wire `[data-bronto-tabs]` groups with the WAI-ARIA Tabs keyboard
+ * pattern (roving tabindex, Arrow/Home/End, aria-selected, panel sync).
+ * Returns a cleanup function.
+ */
+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.
+ */
+export declare function initDialog(opts?: DelegateOpts): Cleanup;
+export interface ToastOpts {
+  /** Status tone — maps to `ui-toast--<tone>`. */
+  tone?: 'accent' | 'success' | 'warning' | 'danger';
+  /** Optional uppercase label rendered above the message. */
+  title?: string;
+  /** Auto-dismiss delay in ms. 0 keeps it until dismissed. Default: 4000. */
+  duration?: number;
+}
+/**
+ * Push a transient toast into a shared, body-anchored stack. Returns a
+ * function that dismisses it early. No-op (returns noop) without a DOM.
+ */
+export declare function toast(message: string, opts?: ToastOpts): Cleanup;

package/behaviors/index.js CHANGED Viewed

@@ -18,6 +18,37 @@ const THEMES = ['light', 'dark'];
 const noop = () => {};
 const hasDom = () => typeof document !== 'undefined';
+// Module-global so tab ids stay unique across *every* initTabs() call.
+// A per-call counter makes separate islands/roots all mint `bronto-tab-1`,
+// which collides aria-controls/aria-labelledby across the document.
+let tabUid = 0;
+// First-toast deferral queue. The very first toast on a brand-new stack
+// is appended next frame so AT observes the empty aria-live region
+// before its first child. Any further toasts created *before* that frame
+// flushes are queued behind it so call order (FIFO) is preserved instead
+// of a synchronous later toast jumping ahead of the deferred first one.
+const toastQueue = [];
+let toastFlushScheduled = false;
+// Make delegated initializers idempotent. Re-binding the same logical
+// listener on the same host/element tears the previous binding down first,
+// so double-init (HMR, framework re-mount, repeated calls) never stacks
+// duplicate handlers (the "double-toggle" class of bug). The returned
+// cleanup removes the single live binding.
+const BOUND = Symbol('bronto-bound');
+function bindOnce(target, key, add) {
+  const reg = target[BOUND] || (target[BOUND] = Object.create(null));
+  if (reg[key]) reg[key]();
+  const remove = add();
+  const cleanup = () => {
+    remove();
+    if (reg[key] === cleanup) delete reg[key];
+  };
+  reg[key] = cleanup;
+  return cleanup;
+}
 /**
  * Apply the persisted theme to <html data-theme>. Call as early as
  * possible (an inline module in <head>) to avoid a flash before the
@@ -85,14 +116,16 @@ export function initThemeToggle({ storageKey = 'bronto-theme', root } = {}) {
     }
     reflect();
     docEl.dispatchEvent(
-      new CustomEvent('bronto:themechange', { detail: { theme: next }, bubbles: true })
+      new CustomEvent('bronto:themechange', { detail: { theme: next }, bubbles: true }),
     );
   };
   applyStoredTheme({ storageKey });
   reflect();
-  host.addEventListener('click', onClick);
-  return () => host.removeEventListener('click', onClick);
+  return bindOnce(host, 'themeToggle', () => {
+    host.addEventListener('click', onClick);
+    return () => host.removeEventListener('click', onClick);
+  });
 }
 /**
@@ -112,8 +145,242 @@ export function dismissible({ root } = {}) {
     const ev = new CustomEvent('bronto:dismiss', { bubbles: true, cancelable: true });
     if (target.dispatchEvent(ev)) target.remove();
   };
-  host.addEventListener('click', onClick);
-  return () => host.removeEventListener('click', onClick);
+  return bindOnce(host, 'dismissible', () => {
+    host.addEventListener('click', onClick);
+    return () => host.removeEventListener('click', onClick);
+  });
+}
+/**
+ * Wire `[data-bronto-tabs]` groups for full keyboard a11y. The framework
+ * ships the look + the ARIA/`.is-active` contract; this adds the WAI-ARIA
+ * Tabs pattern: roving `tabindex`, `aria-selected`, Arrow/Home/End
+ * navigation with automatic activation, and panel `hidden` sync. Tabs are
+ * `.ui-tab[data-tab]`; panels are `.ui-tabs__panel[data-panel]` with
+ * matching values. SSR-safe and idempotent (re-init replaces, never
+ * stacks, the per-group listeners); returns a cleanup function.
+ *
+ * Accessibility caveat: this is what makes tabs operable. Do **not**
+ * author `hidden` on `.ui-tabs__panel` in server-rendered markup unless
+ * `initTabs` is guaranteed to run client-side — without it the panels
+ * stay hidden with no keyboard/pointer way to reveal them. Prefer
+ * authoring all panels visible and letting `initTabs` add `hidden`.
+ */
+export function initTabs({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  const cleanups = [];
+  // querySelectorAll only matches descendants, so a `root` that *is* a
+  // tab group would be skipped — include it explicitly.
+  const groups = [];
+  if (host !== document && host.matches?.('[data-bronto-tabs]')) groups.push(host);
+  groups.push(...host.querySelectorAll('[data-bronto-tabs]'));
+  for (const group of groups) {
+    // Own group only — a tab/panel inside a nested [data-bronto-tabs]
+    // belongs to that inner group, not this one.
+    const owned = (el) => el.closest('[data-bronto-tabs]') === group;
+    const tabs = [...group.querySelectorAll('.ui-tab')].filter(owned);
+    const panels = [...group.querySelectorAll('.ui-tabs__panel')].filter(owned);
+    if (!tabs.length) continue;
+    const list = group.querySelector('.ui-tabs__list');
+    if (list) list.setAttribute('role', 'tablist');
+    // APG: bind each tab to its panel (aria-controls) and back
+    // (aria-labelledby), minting stable ids only where absent.
+    for (const t of tabs) {
+      const p = panels.find((x) => x.dataset.panel === t.dataset.tab);
+      if (!p) continue;
+      const n = ++tabUid;
+      if (!t.id) t.id = `bronto-tab-${n}`;
+      if (!p.id) p.id = `bronto-tabpanel-${n}`;
+      t.setAttribute('aria-controls', p.id);
+      p.setAttribute('aria-labelledby', t.id);
+    }
+    const select = (tab) => {
+      for (const t of tabs) {
+        const on = t === tab;
+        t.classList.toggle('is-active', on);
+        t.setAttribute('role', 'tab');
+        t.setAttribute('aria-selected', String(on));
+        t.tabIndex = on ? 0 : -1;
+      }
+      for (const p of panels) {
+        p.setAttribute('role', 'tabpanel');
+        p.hidden = p.dataset.panel !== tab.dataset.tab;
+      }
+    };
+    const onClick = (e) => {
+      // `tabs` is filtered to this group, so membership (not mere DOM
+      // containment) is what isolates nested [data-bronto-tabs] groups.
+      const tab = e.target.closest('.ui-tab');
+      if (tab && tabs.includes(tab)) {
+        select(tab);
+        tab.focus();
+      }
+    };
+    const onKey = (e) => {
+      const i = tabs.indexOf(e.target.closest('.ui-tab'));
+      if (i < 0) return;
+      let n = i;
+      if (e.key === 'ArrowRight' || e.key === 'ArrowDown') n = (i + 1) % tabs.length;
+      else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp')
+        n = (i - 1 + tabs.length) % tabs.length;
+      else if (e.key === 'Home') n = 0;
+      else if (e.key === 'End') n = tabs.length - 1;
+      else return;
+      e.preventDefault();
+      select(tabs[n]);
+      tabs[n].focus();
+    };
+    select(tabs.find((t) => t.classList.contains('is-active')) || tabs[0]);
+    cleanups.push(
+      bindOnce(group, 'tabs', () => {
+        group.addEventListener('click', onClick);
+        group.addEventListener('keydown', onKey);
+        return () => {
+          group.removeEventListener('click', onClick);
+          group.removeEventListener('keydown', onKey);
+        };
+      }),
+    );
+  }
+  return () => cleanups.forEach((fn) => fn());
+}
+/**
+ * Wire native <dialog> open/close glue (the one bit <dialog> can't do
+ * declaratively). Click `[data-bronto-open="dialogId"]` calls
+ * `showModal()` on `#dialogId`; click `[data-bronto-close]` closes the
+ * nearest enclosing <dialog>. Clicking the backdrop of a dialog that has
+ * `[data-bronto-dialog-light]` closes it too. On open the trigger is
+ * remembered and focus is returned to it on *every* close path (Esc,
+ * close button, backdrop light-dismiss, programmatic) via the native
+ * `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>).
+ */
+export function initDialog({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  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();
+      }
+      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();
+      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();
+    }
+  };
+  return bindOnce(host, 'dialog', () => {
+    host.addEventListener('click', onClick);
+    return () => host.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; `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 } = {}) {
+  if (!hasDom()) return noop;
+  let stack = document.querySelector('.ui-toast-stack');
+  const freshStack = !stack;
+  if (!stack) {
+    stack = document.createElement('div');
+    stack.className = 'ui-toast-stack';
+    stack.setAttribute('aria-live', 'polite');
+    document.body.appendChild(stack);
+  }
+  const el = document.createElement('div');
+  el.className = tone ? `ui-toast ui-toast--${tone}` : 'ui-toast';
+  // No per-item role: the stack is already aria-live=polite; a nested
+  // status live region risks double announcement in some SRs.
+  if (title) {
+    const t = document.createElement('p');
+    t.className = 'ui-toast__title';
+    t.textContent = title;
+    el.appendChild(t);
+  }
+  const body = document.createElement('div');
+  body.textContent = message;
+  el.appendChild(body);
+  // 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.
+  let dismissed = false;
+  // `dismissed` guard: a toast dismissed before its frame (e.g.
+  // duration:0 + immediate dismiss) must NOT be resurrected into the
+  // persistent aria-live region.
+  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();
+  }
+  let timer;
+  const dismiss = () => {
+    if (dismissed) return;
+    dismissed = true;
+    if (timer) clearTimeout(timer);
+    el.remove();
+    // The stack is a persistent live region — never removed on drain, so
+    // the next toast does not recreate (and thus mis-announce) it.
+  };
+  if (duration > 0) timer = setTimeout(dismiss, duration);
+  return dismiss;
 }
 /**
@@ -134,6 +401,53 @@ export function initDisclosure({ root } = {}) {
     trigger.setAttribute('aria-expanded', String(!open));
     panel.hidden = open;
   };
-  host.addEventListener('click', onClick);
-  return () => host.removeEventListener('click', onClick);
+  return bindOnce(host, 'disclosure', () => {
+    host.addEventListener('click', onClick);
+    return () => host.removeEventListener('click', onClick);
+  });
+}
+/**
+ * Dropdown-menu close affordances for a native `<details data-bronto-menu>`
+ * holding a `.ui-menu`. `<details>` alone won't close on Escape, on an
+ * outside click, or when a `.ui-menu__item` is activated — this adds
+ * exactly those, returning focus to the `<summary>` on Esc/activate.
+ *
+ * Deliberately NOT a full WAI-ARIA menu (no arrow-key roving): the items
+ * are real buttons, Tab-reachable; this is a disclosure of actions, and
+ * over-claiming `role="menu"` semantics would be worse. SSR-safe,
+ * idempotent; returns a cleanup function.
+ */
+export function initMenu({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  const openMenus = () => host.querySelectorAll?.('[data-bronto-menu][open]') ?? [];
+  const shut = (menu) => {
+    if (!menu || !menu.open) return;
+    menu.open = false;
+    menu.querySelector('summary')?.focus();
+  };
+  const onClick = (e) => {
+    const menu = e.target.closest('[data-bronto-menu]');
+    // Activate an item → close its menu (and return focus to summary).
+    if (menu && e.target.closest('.ui-menu__item')) {
+      shut(menu);
+      return;
+    }
+    // Click outside any open menu → close them all (no focus move).
+    for (const m of openMenus()) if (!m.contains(e.target)) m.open = false;
+  };
+  const onKey = (e) => {
+    if (e.key !== 'Escape') return;
+    const menu = e.target.closest?.('[data-bronto-menu][open]') || openMenus()[0];
+    shut(menu);
+  };
+  return bindOnce(host, 'menu', () => {
+    host.addEventListener('click', onClick);
+    host.addEventListener('keydown', onKey);
+    return () => {
+      host.removeEventListener('click', onClick);
+      host.removeEventListener('keydown', onKey);
+    };
+  });
 }