@ponchia/ui 0.5.0 → 0.6.3

package/behaviors/inert.js

@@ -0,0 +1,46 @@
+import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
+
+const DISABLED = '[aria-disabled="true"]';
+
+/**
+ * Make `aria-disabled="true"` controls keyboard-inert, not just pointer-inert.
+ *
+ * CSS can dim an `aria-disabled` control and set `pointer-events: none`, but it
+ * cannot block keyboard activation: a focused `<a aria-disabled>` or
+ * `<button aria-disabled>` still fires on Enter/Space, so a keyboard user can
+ * activate a control that looks dead. (Native `disabled` is already fully inert;
+ * this guard brings the ARIA path up to parity.) The element intentionally stays
+ * focusable and announced — the WAI-ARIA disabled pattern keeps it in the tab
+ * order — but it no longer *acts*.
+ *
+ * Wire once near the root, like {@link applyStoredTheme}. Capturing listeners
+ * intercept activation before any component handler (tabs, pagination, menus)
+ * sees it. (component audit C4.)
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initDisabledGuard({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const block = (e) => {
+    const el = e.target.closest?.(DISABLED);
+    if (el && host.contains(el)) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  };
+  const onKeydown = (e) => {
+    // Only the activation keys; Tab/arrows must still move focus PAST the control.
+    if (e.key === 'Enter' || e.key === ' ' || e.key === 'Spacebar') block(e);
+  };
+  return bindOnce(host, 'disabled-guard', () => {
+    host.addEventListener('click', block, true);
+    host.addEventListener('keydown', onKeydown, true);
+    return () => {
+      host.removeEventListener('click', block, true);
+      host.removeEventListener('keydown', onKeydown, true);
+    };
+  });
+}

package/behaviors/internal.d.ts

@@ -0,0 +1,25 @@
+export function resolveHost(root: any, fallback?: Document): any;
+export function bindOnce(target: any, key: any, add: any): () => void;
+export function byIdInHost(host: any, id: any): any;
+export function closestSafe(el: any, selector: any): any;
+export function collectHosts(host: any, selector: any): any[];
+export function scrollIntoViewSafe(el: any, opts?: {
+    block: string;
+}): void;
+export function focusInto(container: any): void;
+export function wrapIndex(cur: any, delta: any, len: any): any;
+export function noop(): void;
+export function hasDom(): boolean;
+export function nextFieldUid(): number;
+/**
+ * Cleanup function returned by every initializer; calling it tears down the
+ * behavior's listeners/observers.
+ */
+export type Cleanup = () => void;
+export type DelegateOpts = {
+    /**
+     * Event-delegation root; also scopes which controls are queried. Default: `document`.
+     */
+    root?: Document | Element | undefined;
+};
+//# sourceMappingURL=internal.d.ts.map

package/behaviors/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["internal.js"],"names":[],"mappings":"AA8BA,iEAGC;AAeD,sEAUC;AAED,oDAQC;AAED,yDAMC;AAMD,8DAIC;AAID;;SAMC;AAUD,gDAQC;AAMD,+DAKC;AA9GM,6BAAqB;AAErB,kCAAoD;AAsBpD,uCAAqC;;;;;sBAjC/B,MAAM,IAAI"}

package/behaviors/internal.js

@@ -1,11 +1,38 @@
 // Shared, dependency-free DOM helpers for the behavior modules.
 // Not part of the public @ponchia/ui/behaviors surface (the barrel
-// re-exports only the documented behaviors).
+// re-exports only the documented behaviors' values — these shared option
+// types are re-exported by name from index.js).
+
+/**
+ * @typedef {() => void} Cleanup
+ *   Cleanup function returned by every initializer; calling it tears down the
+ *   behavior's listeners/observers.
+ *
+ * @typedef {object} DelegateOpts
+ * @property {Document | Element} [root]
+ *   Event-delegation root; also scopes which controls are queried. Default: `document`.
+ */
 
 export const noop = () => {};
 
 export const hasDom = () => typeof document !== 'undefined';
 
+// Resolve the delegation host from an init call's `root` option, distinguishing
+// three cases so an unattached/null root never silently widens to whole-document
+// delegation (the "scoped island hijacks every control" foot-gun):
+//   • root absent/undefined → no scope requested → delegate from `fallback`
+//     (default `document`). This is the intended global-wiring path.
+//   • root === null         → a scope WAS requested but isn't ready yet (e.g. a
+//     framework ref still null at mount). Return null so the caller no-ops
+//     instead of hijacking the whole document.
+//   • root is an element    → use it.
+// The bindings (@ponchia/ui/{react,solid,qwik}) emit `root: null` for the
+// not-ready case precisely so this distinction survives across the boundary.
+export function resolveHost(root, fallback = document) {
+  if (root === null) return null;
+  return root || fallback;
+}
+
 // Monotonic counter for auto-minted field / list ids, shared across
 // initFormValidation and initCombobox so separate calls (and separate
 // behaviors) never collide on an id.
@@ -48,3 +75,52 @@ export function closestSafe(el, selector) {
     return null;
   }
 }
+
+// Collect the hosts an initializer should wire: the descendants matching
+// `selector` PLUS `host` itself when it matches (querySelectorAll only sees
+// descendants, so a `root` that *is* a target would otherwise be skipped).
+// Self-first, null-safe — the shape ~9 delegated behaviors hand-rolled.
+export function collectHosts(host, selector) {
+  const out = host !== document && host.matches?.(selector) ? [host] : [];
+  out.push(...(host.querySelectorAll?.(selector) ?? []));
+  return out;
+}
+
+// scrollIntoView is a pure affordance and throws in jsdom/layout-less envs;
+// never let that break a keyboard/roving handler. (combobox/command/carousel.)
+export function scrollIntoViewSafe(el, opts = { block: 'nearest' }) {
+  try {
+    el?.scrollIntoView(opts);
+  } catch {
+    /* headless / no layout — the scroll is cosmetic */
+  }
+}
+
+// The focusable-element selector + "move focus into a container" helper shared
+// by the modal and popover focus paths (a dialog/modal must move focus into
+// itself on open). Focus the first focusable descendant, else make the
+// container programmatically focusable and focus it, so a content-only
+// panel/modal still receives focus. (code-quality audit Q4.)
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export function focusInto(container) {
+  const first = container.querySelector(FOCUSABLE);
+  if (first) {
+    first.focus?.();
+    return;
+  }
+  if (!container.hasAttribute('tabindex')) container.setAttribute('tabindex', '-1');
+  container.focus?.();
+}
+
+// Wrap an index by `delta` within [0, len), the roving keyboard math shared by
+// the combobox and command listboxes (a -1 `cur` lands on the first/last as
+// before). Only this core is shared — the surrounding setActive/filter/group
+// logic diverges between the two for real reasons. (code-quality audit Q12.)
+export function wrapIndex(cur, delta, len) {
+  let next = cur + delta;
+  if (next < 0) next = len - 1;
+  if (next >= len) next = 0;
+  return next;
+}

package/behaviors/legend.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @typedef {object} LegendToggleDetail
+ * @property {string | number} series The entry's `data-series`, or its 0-based index when unset.
+ * @property {boolean} active The new state (`true` ⇒ series shown).
+ */
+/**
+ * Wire `[data-bronto-legend]` interactive legends. Each entry is a
+ * `.ui-legend__item` authored as a `<button aria-pressed>`; clicking it (or
+ * Enter/Space, native to `<button>`) flips `aria-pressed`, toggles the
+ * `.is-inactive` class, and dispatches `bronto:legend:toggle` on the legend
+ * with `{ detail: { series, active } }` (`series` is the entry's
+ * `data-series`, or its 0-based index if unset).
+ *
+ * Bronto owns only the control and its pressed/inactive *state*. It does not
+ * know the chart's series, hide anything, or announce the change: the host
+ * listens for the event, hides its own series, and owns any `aria-live`
+ * announcement. The convention is `aria-pressed="true"` ⇒ the series is shown
+ * (the default); the entry's label never changes on toggle (WAI-ARIA). SSR-safe
+ * and idempotent per host; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initLegend({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export type LegendToggleDetail = {
+    /**
+     * The entry's `data-series`, or its 0-based index when unset.
+     */
+    series: string | number;
+    /**
+     * The new state (`true` ⇒ series shown).
+     */
+    active: boolean;
+};
+//# sourceMappingURL=legend.d.ts.map

package/behaviors/legend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legend.d.ts","sourceRoot":"","sources":["legend.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAmD3C;;;;;YAvEa,MAAM,GAAG,MAAM;;;;YACf,OAAO"}

package/behaviors/legend.js

@@ -1,4 +1,10 @@
-import { hasDom, noop, bindOnce } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
+
+/**
+ * @typedef {object} LegendToggleDetail
+ * @property {string | number} series The entry's `data-series`, or its 0-based index when unset.
+ * @property {boolean} active The new state (`true` ⇒ series shown).
+ */
 
 /**
  * Wire `[data-bronto-legend]` interactive legends. Each entry is a
@@ -14,15 +20,24 @@ import { hasDom, noop, bindOnce } from './internal.js';
  * announcement. The convention is `aria-pressed="true"` ⇒ the series is shown
  * (the default); the entry's label never changes on toggle (WAI-ARIA). SSR-safe
  * and idempotent per host; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initLegend({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const isButton = (el) => el.tagName === 'BUTTON' || el.getAttribute('role') === 'button';
   const onClick = (e) => {
     const item = e.target.closest('.ui-legend__item');
     if (!item || !host.contains(item)) return;
     const legend = item.closest('[data-bronto-legend]');
     if (!legend || !host.contains(legend)) return;
+    // The contract requires a real `<button>` (keyboard-operable, focusable). A
+    // non-button item is mouse-only — refuse to toggle it rather than ship a
+    // pointer-only control (WCAG 2.1.1 — C11). The author is warned at bind.
+    if (!isButton(item)) return;
     const active = item.getAttribute('aria-pressed') !== 'false';
     const next = !active;
     item.setAttribute('aria-pressed', String(next));
@@ -40,6 +55,21 @@ export function initLegend({ root } = {}) {
     );
   };
   return bindOnce(host, 'legend', () => {
+    // Warn once per non-button item present at bind: it gets cursor:pointer from
+    // the CSS but is neither focusable nor keyboard-operable (C11).
+    if (typeof console !== 'undefined') {
+      for (const legend of host.querySelectorAll?.('[data-bronto-legend]') ?? []) {
+        const stray = [...legend.querySelectorAll('.ui-legend__item')].some(
+          (el) => el.closest('[data-bronto-legend]') === legend && !isButton(el),
+        );
+        if (stray) {
+          console.warn(
+            '[bronto] initLegend(): interactive legend entries must be <button> (or role="button") to be keyboard-operable — a non-button .ui-legend__item is ignored.',
+          );
+          break;
+        }
+      }
+    }
     host.addEventListener('click', onClick);
     return () => host.removeEventListener('click', onClick);
   });

package/behaviors/menu.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initMenu({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=menu.d.ts.map

package/behaviors/menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu.d.ts","sourceRoot":"","sources":["menu.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,oCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAmC3C"}

package/behaviors/menu.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
 
 /**
  * Dropdown-menu close affordances for a native `<details data-bronto-menu>`
@@ -10,10 +10,14 @@ import { hasDom, noop, bindOnce } from './internal.js';
  * 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.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initMenu({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const openMenus = () => host.querySelectorAll?.('[data-bronto-menu][open]') ?? [];
   const shut = (menu) => {
     if (!menu || !menu.open) return;

package/behaviors/modal.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @typedef {object} ModalCloseDetail
+ * @property {'escape'} reason What asked the modal to close (currently only Escape).
+ */
+/**
+ * Focus management for the **controlled, non-`<dialog>` modal** — the
+ * `.ui-modal.is-open` path a portal/React overlay uses when it genuinely can't
+ * be a native `<dialog>`. The native `<dialog>` path gets a focus trap, Escape,
+ * and the top layer for free (use `initDialog`); this supplies the equivalent
+ * for the `.is-open` path, which otherwise leaves focus management to the
+ * consumer.
+ *
+ * Mark the overlay `[data-bronto-modal]` (opt-in). On bind it gives the modal a
+ * `role="dialog"` + `aria-modal="true"` (unless the author set a role) and
+ * dev-warns when it has no accessible name, so it announces as a named modal
+ * dialog — parity with `initPopover`. The behavior watches its
+ * `class` for `is-open`: on open it remembers the focused element, moves focus
+ * into the modal (first focusable, else the panel itself), and **traps focus by
+ * marking every sibling at each ancestor level `inert`** so the rest of the page
+ * is non-focusable and non-interactive — the modern, robust trap. On close it
+ * un-inerts exactly what it inerted and returns focus to the opener. Bronto owns
+ * focus only: the **consumer still owns open/close state** (the `is-open`
+ * class). Escape dispatches a cancelable `bronto:modal:close`
+ * ({@link ModalCloseDetail}) on the modal so the consumer can drop `is-open` in
+ * response; the behavior never changes visibility itself.
+ *
+ * Best suited to a body-/portal-level overlay (the documented `.is-open` use
+ * case); a deeply-nested modal still gets focus-into, focus-return, and the
+ * Escape signal. SSR-safe, idempotent per modal; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initModal({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export type ModalCloseDetail = {
+    /**
+     * What asked the modal to close (currently only Escape).
+     */
+    reason: "escape";
+};
+//# sourceMappingURL=modal.d.ts.map

package/behaviors/modal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modal.d.ts","sourceRoot":"","sources":["modal.js"],"names":[],"mappings":"AAEA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAyF3C;;;;;YAvHa,QAAQ"}

package/behaviors/modal.js

@@ -0,0 +1,124 @@
+import { hasDom, resolveHost, noop, bindOnce, collectHosts, focusInto } from './internal.js';
+
+/**
+ * @typedef {object} ModalCloseDetail
+ * @property {'escape'} reason What asked the modal to close (currently only Escape).
+ */
+
+/**
+ * Focus management for the **controlled, non-`<dialog>` modal** — the
+ * `.ui-modal.is-open` path a portal/React overlay uses when it genuinely can't
+ * be a native `<dialog>`. The native `<dialog>` path gets a focus trap, Escape,
+ * and the top layer for free (use `initDialog`); this supplies the equivalent
+ * for the `.is-open` path, which otherwise leaves focus management to the
+ * consumer.
+ *
+ * Mark the overlay `[data-bronto-modal]` (opt-in). On bind it gives the modal a
+ * `role="dialog"` + `aria-modal="true"` (unless the author set a role) and
+ * dev-warns when it has no accessible name, so it announces as a named modal
+ * dialog — parity with `initPopover`. The behavior watches its
+ * `class` for `is-open`: on open it remembers the focused element, moves focus
+ * into the modal (first focusable, else the panel itself), and **traps focus by
+ * marking every sibling at each ancestor level `inert`** so the rest of the page
+ * is non-focusable and non-interactive — the modern, robust trap. On close it
+ * un-inerts exactly what it inerted and returns focus to the opener. Bronto owns
+ * focus only: the **consumer still owns open/close state** (the `is-open`
+ * class). Escape dispatches a cancelable `bronto:modal:close`
+ * ({@link ModalCloseDetail}) on the modal so the consumer can drop `is-open` in
+ * response; the behavior never changes visibility itself.
+ *
+ * Best suited to a body-/portal-level overlay (the documented `.is-open` use
+ * case); a deeply-nested modal still gets focus-into, focus-return, and the
+ * Escape signal. SSR-safe, idempotent per modal; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initModal({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const modals = collectHosts(host, '[data-bronto-modal]');
+  const cleanups = [];
+
+  for (const modal of modals) {
+    let opener = null;
+    let inerted = [];
+
+    // A controlled modal must announce AS a modal dialog, not a generic group —
+    // parity with initPopover. Apply a dialog role + aria-modal (unless the
+    // author set a role), and dev-warn on a missing accessible name since we
+    // can't invent a good one. (component audit C13.)
+    if (!modal.hasAttribute('role')) modal.setAttribute('role', 'dialog');
+    if (!modal.hasAttribute('aria-modal')) modal.setAttribute('aria-modal', 'true');
+    const named =
+      modal.hasAttribute('aria-label') ||
+      modal.hasAttribute('aria-labelledby') ||
+      modal.hasAttribute('title');
+    if (!named && typeof console !== 'undefined') {
+      console.warn(
+        `[bronto] initModal(): a [data-bronto-modal] has no accessible name — add aria-label or aria-labelledby so it is announced as a named dialog.`,
+      );
+    }
+
+    // Inert every sibling at each ancestor level up to <body>: the rest of the
+    // page becomes non-focusable/non-interactive while the modal subtree stays
+    // live. Skip already-inert nodes so release() can't un-inert something the
+    // app inerted for its own reasons.
+    const trap = () => {
+      if (opener) return; // already trapped
+      opener = document.activeElement;
+      let el = modal;
+      while (el && el.parentElement && el !== document.body) {
+        for (const sib of el.parentElement.children) {
+          if (sib !== el && !sib.inert) {
+            sib.inert = true;
+            inerted.push(sib);
+          }
+        }
+        el = el.parentElement;
+      }
+      focusInto(modal);
+    };
+
+    const release = () => {
+      if (!opener) return;
+      for (const el of inerted) el.inert = false;
+      inerted = [];
+      const back = opener;
+      opener = null;
+      if (back?.isConnected && typeof back.focus === 'function') back.focus();
+    };
+
+    const sync = () => (modal.classList.contains('is-open') ? trap() : release());
+
+    const onKey = (e) => {
+      if (e.key === 'Escape' && opener) {
+        modal.dispatchEvent(
+          new CustomEvent('bronto:modal:close', {
+            detail: { reason: 'escape' },
+            bubbles: true,
+            cancelable: true,
+          }),
+        );
+      }
+    };
+
+    const observer = typeof MutationObserver === 'function' ? new MutationObserver(sync) : null;
+
+    cleanups.push(
+      bindOnce(modal, 'modal', () => {
+        observer?.observe(modal, { attributes: true, attributeFilter: ['class'] });
+        document.addEventListener('keydown', onKey, true);
+        if (modal.classList.contains('is-open')) trap(); // already open at init
+        return () => {
+          observer?.disconnect();
+          document.removeEventListener('keydown', onKey, true);
+          release();
+        };
+      }),
+    );
+  }
+
+  return () => cleanups.forEach((fn) => fn());
+}

package/behaviors/popover.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Collision-aware popover, dependency-free. A `[data-bronto-popover]`
+ * trigger toggles the `.ui-popover` panel whose id it names. The panel
+ * is placed under the trigger and **flips above** when it would
+ * overflow the viewport, with its inline edge clamped on-screen — the
+ * thing the CSS-only tooltip can't do near edges / inside scroll
+ * containers. If the panel has the native `popover` attribute and the
+ * Popover API is available it is shown in the top layer (never
+ * clipped); otherwise an `.is-open` class is toggled. Manages
+ * `aria-expanded` / `aria-controls`, closes on Escape and outside
+ * click, and re-positions on scroll/resize while open. SSR-safe,
+ * idempotent; returns a cleanup function.
+ *
+ * The trigger advertises `aria-haspopup="dialog"`, so on open the panel is
+ * given `role="dialog"` (unless the author set a role) and focus is moved into
+ * it — the first focusable descendant, or the panel itself. It is a *non-modal*
+ * dialog: the rest of the page stays interactive and there is no focus trap.
+ * Author an accessible name on the panel (`aria-label` / `aria-labelledby`); a
+ * dev-time `console.warn` fires when it is missing.
+ *
+ * Escape returns focus to the trigger; closing via outside-click leaves focus
+ * where the click landed (treated as deliberate intent to move on).
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initPopover({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=popover.d.ts.map

package/behaviors/popover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.d.ts","sourceRoot":"","sources":["popover.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAwJ3C"}

package/behaviors/popover.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost, focusInto } from './internal.js';
 
 /**
  * Collision-aware popover, dependency-free. A `[data-bronto-popover]`
@@ -12,15 +12,33 @@ import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
  * `aria-expanded` / `aria-controls`, closes on Escape and outside
  * click, and re-positions on scroll/resize while open. SSR-safe,
  * idempotent; returns a cleanup function.
+ *
+ * The trigger advertises `aria-haspopup="dialog"`, so on open the panel is
+ * given `role="dialog"` (unless the author set a role) and focus is moved into
+ * it — the first focusable descendant, or the panel itself. It is a *non-modal*
+ * dialog: the rest of the page stays interactive and there is no focus trap.
+ * Author an accessible name on the panel (`aria-label` / `aria-labelledby`); a
+ * dev-time `console.warn` fires when it is missing.
+ *
+ * Escape returns focus to the trigger; closing via outside-click leaves focus
+ * where the click landed (treated as deliberate intent to move on).
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initPopover({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const view = document.defaultView;
   const GAP = 8;
   let openPanel = null;
   let openTrigger = null;
 
+  // The trigger advertises `aria-haspopup="dialog"`, so the open panel must BE a
+  // dialog: a role, an accessible name, and focus moved into it (C6) — see the
+  // shared `focusInto` in internal.js.
+
   const place = (trigger, panel) => {
     const r = trigger.getBoundingClientRect();
     const pw = panel.offsetWidth;
@@ -39,6 +57,10 @@ export function initPopover({ root } = {}) {
     if (!openPanel) return;
     const panel = openPanel;
     const trigger = openTrigger;
+    // Only steal focus back to the trigger when focus is still inside the panel
+    // (Escape / programmatic re-toggle). An outside-click leaves focus where the
+    // click landed — deliberate intent to move on, per the doc contract.
+    const focusWasInside = panel.contains(document.activeElement);
     openPanel = openTrigger = null;
     if (panel.hasAttribute('popover') && typeof panel.hidePopover === 'function') {
       try {
@@ -50,10 +72,15 @@ export function initPopover({ root } = {}) {
       panel.classList.remove('is-open');
     }
     if (trigger) trigger.setAttribute('aria-expanded', 'false');
+    if (focusWasInside && trigger?.isConnected) trigger.focus?.();
   };
 
   const open = (trigger, panel) => {
     close();
+    // Live up to the advertised `aria-haspopup="dialog"`: give the panel a
+    // dialog role (unless the author set one) so AT announces it as the promised
+    // dialog rather than a generic group (C6).
+    if (!panel.hasAttribute('role')) panel.setAttribute('role', 'dialog');
     trigger.setAttribute('aria-controls', panel.id);
     trigger.setAttribute('aria-expanded', 'true');
     if (panel.hasAttribute('popover') && typeof panel.showPopover === 'function') {
@@ -68,6 +95,7 @@ export function initPopover({ root } = {}) {
     openPanel = panel;
     openTrigger = trigger;
     place(trigger, panel);
+    focusInto(panel);
   };
 
   const onClick = (e) => {
@@ -83,22 +111,65 @@ export function initPopover({ root } = {}) {
     if (openPanel && !openPanel.contains(e.target)) close();
   };
   const onKey = (e) => {
-    if (e.key === 'Escape' && openPanel) {
-      const t = openTrigger;
-      close();
-      t?.focus?.();
-    }
+    // close() returns focus to the trigger because focus is inside the panel.
+    if (e.key !== 'Escape' || !openPanel) return;
+    // A popover open *inside* a <dialog>/modal owns this Escape. Without this,
+    // the same keypress closed BOTH: we hidePopover() the panel synchronously,
+    // the browser's close-request then finds the dialog as the new topmost
+    // element and dismisses it too. preventDefault() stops that native
+    // close-request and stopPropagation() keeps it off other delegated keydown
+    // listeners (e.g. initModal's), so only the popover closes — the documented
+    // "popover + dialog open together" contract.
+    e.preventDefault();
+    e.stopPropagation();
+    close();
   };
   const onReflow = () => {
     if (openPanel && openTrigger) place(openTrigger, openPanel);
   };
 
+  // Seed resting ARIA on every trigger and keep it in sync when the UA itself
+  // toggles a native popover (light-dismiss / Escape on the `popover` attribute
+  // never routes through close(), so aria-expanded would otherwise go stale).
+  const seedTeardowns = [];
+  const seed = () => {
+    for (const trigger of host.querySelectorAll('[data-bronto-popover]')) {
+      const panel = byIdInHost(host, trigger.getAttribute('data-bronto-popover'));
+      if (!panel) continue;
+      if (!trigger.hasAttribute('aria-haspopup')) trigger.setAttribute('aria-haspopup', 'dialog');
+      trigger.setAttribute('aria-controls', panel.id);
+      if (!trigger.hasAttribute('aria-expanded')) trigger.setAttribute('aria-expanded', 'false');
+      // A dialog with no accessible name is announced as just "dialog". We can't
+      // invent a good name, so warn the author at dev time (C6).
+      const named =
+        panel.hasAttribute('aria-label') ||
+        panel.hasAttribute('aria-labelledby') ||
+        panel.hasAttribute('title');
+      if (!named && typeof console !== 'undefined') {
+        console.warn(
+          `[bronto] initPopover(): panel #${panel.id} has no accessible name — add aria-label or aria-labelledby so it is announced as a named dialog.`,
+        );
+      }
+      if (panel.hasAttribute('popover')) {
+        const onToggle = (e) => {
+          const isOpen = e.newState === 'open';
+          trigger.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
+          if (!isOpen && openPanel === panel) openPanel = openTrigger = null;
+        };
+        panel.addEventListener('toggle', onToggle);
+        seedTeardowns.push(() => panel.removeEventListener('toggle', onToggle));
+      }
+    }
+  };
+
   return bindOnce(host, 'popover', () => {
+    seed();
     document.addEventListener('click', onClick);
     document.addEventListener('keydown', onKey);
     view?.addEventListener('scroll', onReflow, true);
     view?.addEventListener('resize', onReflow);
     return () => {
+      for (const t of seedTeardowns.splice(0)) t();
       document.removeEventListener('click', onClick);
       document.removeEventListener('keydown', onKey);
       view?.removeEventListener('scroll', onReflow, true);