@ponchia/ui 0.4.1 → 0.6.0

package/behaviors/tabs.js

@@ -0,0 +1,103 @@
+import { hasDom, resolveHost, noop, bindOnce, nextFieldUid, collectHosts } from './internal.js';
+
+/**
+ * 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 = resolveHost(root);
+  if (!host) return noop;
+  const cleanups = [];
+  const groups = collectHosts(host, '[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 = nextFieldUid();
+      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;
+      }
+      // Only retarget panels when this tab actually controls one. A panel-less
+      // tab must NOT hide every panel — leave the prior panel visible (C30).
+      if (!panels.some((p) => p.dataset.panel === tab.dataset.tab)) return;
+      for (const p of panels) {
+        p.setAttribute('role', 'tabpanel');
+        const shown = p.dataset.panel === tab.dataset.tab;
+        p.hidden = !shown;
+        // APG: a tabpanel is focusable so keyboard users can reach a text-only
+        // panel; hidden panels drop out of the tab order (C30).
+        if (shown) p.tabIndex = 0;
+        else p.removeAttribute('tabindex');
+      }
+    };
+    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());
+}

package/behaviors/theme.js

@@ -0,0 +1,84 @@
+import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
+
+const THEMES = ['light', 'dark'];
+
+/**
+ * Apply the persisted theme to <html data-theme>. Call as early as
+ * possible (an inline module in <head>) to avoid a flash before the
+ * toggle wires up. No stored value → leaves prefers-color-scheme to act.
+ */
+export function applyStoredTheme({ storageKey = 'bronto-theme', root } = {}) {
+  if (!hasDom()) return;
+  const el = resolveHost(root, document.documentElement);
+  if (!el) return;
+  let stored = null;
+  try {
+    stored = localStorage.getItem(storageKey);
+  } catch {
+    /* storage blocked (private mode / sandbox) — fall through to OS default */
+  }
+  if (stored && THEMES.includes(stored)) el.setAttribute('data-theme', stored);
+}
+
+/**
+ * Wire `[data-bronto-theme-toggle]` controls. Click toggles light/dark,
+ * persists to localStorage, and **always** sets `data-theme` on <html>
+ * (a theme is document-global). State is reflected via `aria-pressed`
+ * and a `bronto:themechange` CustomEvent ({ detail: { theme } }) is
+ * dispatched on <html> so consumers can sync their own UI without
+ * racing the click handler. A control may set
+ * `data-bronto-theme-toggle="dark"` to force a specific theme.
+ *
+ * `root` scopes event delegation and which controls are queried/reflected
+ * (default `document`); it does not change where the theme is applied.
+ */
+export function initThemeToggle({ storageKey = 'bronto-theme', root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const docEl = document.documentElement;
+
+  const prefersDark = () =>
+    typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: dark)').matches;
+
+  const current = () => {
+    const attr = docEl.getAttribute('data-theme');
+    if (THEMES.includes(attr)) return attr;
+    return prefersDark() ? 'dark' : 'light';
+  };
+
+  const reflect = () => {
+    const c = current();
+    host.querySelectorAll('[data-bronto-theme-toggle]').forEach((el) => {
+      const forced = el.getAttribute('data-bronto-theme-toggle');
+      // A forced control is "pressed" when its theme is the active one;
+      // a plain toggle reflects whether dark is active.
+      const pressed = THEMES.includes(forced) ? c === forced : c === 'dark';
+      el.setAttribute('aria-pressed', String(pressed));
+    });
+  };
+
+  const onClick = (e) => {
+    const trigger = e.target.closest('[data-bronto-theme-toggle]');
+    if (!trigger || !host.contains(trigger)) return;
+    const forced = trigger.getAttribute('data-bronto-theme-toggle');
+    const next = THEMES.includes(forced) ? forced : current() === 'dark' ? 'light' : 'dark';
+    docEl.setAttribute('data-theme', next);
+    try {
+      localStorage.setItem(storageKey, next);
+    } catch {
+      /* storage blocked — theme still applies for this session */
+    }
+    reflect();
+    docEl.dispatchEvent(
+      new CustomEvent('bronto:themechange', { detail: { theme: next }, bubbles: true }),
+    );
+  };
+
+  applyStoredTheme({ storageKey });
+  reflect();
+  return bindOnce(host, 'themeToggle', () => {
+    host.addEventListener('click', onClick);
+    return () => host.removeEventListener('click', onClick);
+  });
+}

package/behaviors/toast.js

@@ -0,0 +1,164 @@
+import { hasDom, noop } from './internal.js';
+
+// The tones that have a `.ui-toast--*` rule. The TS type already unions these,
+// but a plain-JS / LLM caller can pass any string — and an unknown tone built a
+// `.ui-toast--error` class that matches no CSS, yielding a silent neutral toast.
+// Validate so an unknown tone degrades to neutral *and warns*, never lies. (C16)
+const TOAST_TONES = new Set(['accent', 'success', 'warning', 'danger', 'info']);
+
+// 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;
+
+function toastStack(isAssertive) {
+  const stackSel = isAssertive
+    ? '.ui-toast-stack--assertive'
+    : '.ui-toast-stack:not(.ui-toast-stack--assertive)';
+  let stack = document.querySelector(stackSel);
+  const fresh = !stack;
+  if (!stack) {
+    stack = document.createElement('div');
+    stack.className = isAssertive ? 'ui-toast-stack ui-toast-stack--assertive' : 'ui-toast-stack';
+    stack.setAttribute('aria-live', isAssertive ? 'assertive' : 'polite');
+    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');
+  const validTone = tone && TOAST_TONES.has(tone) ? tone : null;
+  if (tone && !validTone && typeof console !== 'undefined') {
+    console.warn(
+      `[bronto] toast(): unknown tone "${tone}" — expected ${[...TOAST_TONES].join('/')}. Rendering neutral.`,
+    );
+  }
+  el.className = validTone ? `ui-toast ui-toast--${validTone}` : 'ui-toast';
+  // No per-item role: the stack itself is the live region; a nested
+  // 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);
+  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.
+  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);
+  };
+  enqueueToast(place, freshStack);
+
+  let timer;
+  const dismiss = () => {
+    if (dismissed) return;
+    dismissed = true;
+    if (timer) clearTimeout(timer);
+    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.
+  };
+  // A sticky toast (duration:0) is unusable without a manual close, so
+  // 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) addToastClose(el, dismiss);
+  if (duration > 0) timer = setTimeout(dismiss, duration);
+  return dismiss;
+}