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

@ponchia/ui 0.2.2 → 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 (44) 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,30 +21,33 @@ npm i @ponchia/ui
 > deliberately distinct from the package name. See
 > [`docs/architecture.md`](docs/architecture.md).
-Import the full theme (includes responsive breakpoints):
-```css
-@import '@ponchia/ui/css';
-```
-Or the core bundle if the app manages its own responsive layer:
+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/core.css';
+@import '@ponchia/ui/css';        /* === @ponchia/ui/css/core.css */
 ```
 **Prebuilt single file (recommended for apps without a CSS bundler).**
-`@ponchia/ui/css` is a 17-deep `@import` graph — fine through a bundler,
-a load waterfall over plain HTTP. The package also ships flattened,
-minified bundles with no `@import` chain:
+`@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';               /* → dist/bronto.css, full   */
-@import '@ponchia/ui/dist/bronto-core.css';   /* core, no responsive */
+@import '@ponchia/ui';   /* → dist/bronto.css, the whole framework */
 ```
-~62 kB raw / ~11 kB gzip, one request, same `@layer bronto`. Source CSS,
-tokens/classes/behaviors entrypoints are unchanged — use whichever fits.
+~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
@@ -59,10 +65,14 @@ 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`.
@@ -90,7 +100,9 @@ themeColor('dark').accent; // → "#ff3b41"
 ```
 `behaviors` wires `[data-bronto-theme-toggle]`, `[data-bronto-dismiss]` /
-`[data-bronto-dismissible]`, `[data-bronto-disclosure]`, and native
+`[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
@@ -112,13 +124,10 @@ modules, so it is also a live integration test.
 | `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`                  |
-| `content.css`    | `.ui-prose` — Markdown/raw-HTML long-form, zero per-element classes |
-| `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
@@ -145,18 +154,52 @@ exports/import-graph integrity, `tokens.css` ⇄ `tokens/index.{js,json}`, the
 `classes` registry ⇄ the `.ui-*` selectors, `dist/` ⇄ `css/` (fresh + in
 budget), and that the published tarball ships only the intended files.
-Visual + a11y regression is a separate suite (real browser, so not in the
+End-to-end regression is a separate suite (real browsers, so not in the
 zero-dep core check):
 ```bash
-npx playwright test   # demo screenshots (light/dark/RTL) + axe-core WCAG
+npx playwright test   # visual snapshots + axe a11y + cross-engine + modes
 ```
-It is pinned to a Playwright container so baselines are byte-stable; the
-committed baselines under `test/e2e/__screenshots__` were authored in that
-same image. CI (`.github/workflows/ci.yml`) runs both the `check` job and a
-containerised `visual` job on every branch push and PR. It never publishes —
-a push to `main` ships nothing.
+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
@@ -168,18 +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).
-Published: `@ponchia/ui` is live on npm (latest `0.2.1`), 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.
+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

@@ -39,6 +39,13 @@ 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).

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,10 @@ 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);
+  });
 }
 /**
@@ -122,13 +157,19 @@ export function dismissible({ root } = {}) {
  * 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; returns a cleanup function.
+ * 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 = [];
-  let uid = 0;
   // querySelectorAll only matches descendants, so a `root` that *is* a
   // tab group would be skipped — include it explicitly.
   const groups = [];
@@ -149,7 +190,7 @@ export function initTabs({ root } = {}) {
     for (const t of tabs) {
       const p = panels.find((x) => x.dataset.panel === t.dataset.tab);
       if (!p) continue;
-      const n = ++uid;
+      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);
@@ -183,7 +224,8 @@ export function initTabs({ root } = {}) {
       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 === '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;
@@ -191,13 +233,17 @@ export function initTabs({ root } = {}) {
       select(tabs[n]);
       tabs[n].focus();
     };
-    group.addEventListener('click', onClick);
-    group.addEventListener('keydown', onKey);
     select(tabs.find((t) => t.classList.contains('is-active')) || tabs[0]);
-    cleanups.push(() => {
-      group.removeEventListener('click', onClick);
-      group.removeEventListener('keydown', onKey);
-    });
+    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());
 }
@@ -207,7 +253,11 @@ export function initTabs({ root } = {}) {
  * 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. SSR-safe; returns cleanup.
+ * `[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
@@ -222,7 +272,16 @@ export function initDialog({ root } = {}) {
     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.showModal();
+      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]');
@@ -243,20 +302,29 @@ export function initDialog({ root } = {}) {
       dlg.close();
     }
   };
-  host.addEventListener('click', onClick);
-  return () => host.removeEventListener('click', onClick);
+  return bindOnce(host, 'dialog', () => {
+    host.addEventListener('click', onClick);
+    return () => host.removeEventListener('click', onClick);
+  });
 }
 /**
- * Push a transient toast into a shared, screen-anchored stack (created
- * once and appended to <body>, `aria-live="polite"`). `tone` is one of
- * 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).
+ * 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';
@@ -276,13 +344,40 @@ export function toast(message, { tone, title, duration = 4000 } = {}) {
   const body = document.createElement('div');
   body.textContent = message;
   el.appendChild(body);
-  stack.appendChild(el);
+  // 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();
-    if (stack && !stack.childElementCount) stack.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;
@@ -306,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);
+    };
+  });
 }