@ponchia/ui 0.4.1 → 0.5.0

package/behaviors/internal.js

@@ -0,0 +1,50 @@
+// 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).
+
+export const noop = () => {};
+
+export const hasDom = () => typeof document !== 'undefined';
+
+// Monotonic counter for auto-minted field / list ids, shared across
+// initFormValidation and initCombobox so separate calls (and separate
+// behaviors) never collide on an id.
+let fieldUid = 0;
+export const nextFieldUid = () => ++fieldUid;
+
+// 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');
+
+export 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;
+}
+
+export function byIdInHost(host, id) {
+  if (!id) return null;
+  if (host === document) return document.getElementById(id);
+  if (host.id === id) return host;
+  return (
+    Array.from(host.querySelectorAll?.('[id]') || []).find((el) => el.id === id) ||
+    document.getElementById(id)
+  );
+}
+
+export function closestSafe(el, selector) {
+  try {
+    return el.closest(selector);
+  } catch {
+    return null;
+  }
+}

package/behaviors/legend.js

@@ -0,0 +1,46 @@
+import { hasDom, noop, bindOnce } from './internal.js';
+
+/**
+ * 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.
+ */
+export function initLegend({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  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;
+    const active = item.getAttribute('aria-pressed') !== 'false';
+    const next = !active;
+    item.setAttribute('aria-pressed', String(next));
+    item.classList.toggle('is-inactive', !next);
+    // This legend's own items only — an item inside a nested [data-bronto-legend]
+    // belongs to that inner legend, so it must not shift this one's indices.
+    const items = [...legend.querySelectorAll('.ui-legend__item')].filter(
+      (el) => el.closest('[data-bronto-legend]') === legend,
+    );
+    legend.dispatchEvent(
+      new CustomEvent('bronto:legend:toggle', {
+        bubbles: true,
+        detail: { series: item.dataset.series ?? items.indexOf(item), active: next },
+      }),
+    );
+  };
+  return bindOnce(host, 'legend', () => {
+    host.addEventListener('click', onClick);
+    return () => host.removeEventListener('click', onClick);
+  });
+}

package/behaviors/menu.js

@@ -0,0 +1,46 @@
+import { hasDom, noop, bindOnce } from './internal.js';
+
+/**
+ * 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);
+    };
+  });
+}

package/behaviors/popover.js

@@ -0,0 +1,108 @@
+import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
+
+/**
+ * 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.
+ */
+export function initPopover({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  const view = document.defaultView;
+  const GAP = 8;
+  let openPanel = null;
+  let openTrigger = null;
+
+  const place = (trigger, panel) => {
+    const r = trigger.getBoundingClientRect();
+    const pw = panel.offsetWidth;
+    const ph = panel.offsetHeight;
+    const vw = view?.innerWidth ?? 0;
+    const vh = view?.innerHeight ?? 0;
+    let top = r.bottom + GAP;
+    if (top + ph > vh && r.top - GAP - ph >= 0) top = r.top - GAP - ph;
+    let left = r.left;
+    if (vw) left = Math.max(GAP, Math.min(left, vw - pw - GAP));
+    panel.style.top = `${Math.max(GAP, top)}px`;
+    panel.style.left = `${left}px`;
+  };
+
+  const close = () => {
+    if (!openPanel) return;
+    const panel = openPanel;
+    const trigger = openTrigger;
+    openPanel = openTrigger = null;
+    if (panel.hasAttribute('popover') && typeof panel.hidePopover === 'function') {
+      try {
+        panel.hidePopover();
+      } catch {
+        /* already hidden */
+      }
+    } else {
+      panel.classList.remove('is-open');
+    }
+    if (trigger) trigger.setAttribute('aria-expanded', 'false');
+  };
+
+  const open = (trigger, panel) => {
+    close();
+    trigger.setAttribute('aria-controls', panel.id);
+    trigger.setAttribute('aria-expanded', 'true');
+    if (panel.hasAttribute('popover') && typeof panel.showPopover === 'function') {
+      try {
+        panel.showPopover();
+      } catch {
+        panel.classList.add('is-open');
+      }
+    } else {
+      panel.classList.add('is-open');
+    }
+    openPanel = panel;
+    openTrigger = trigger;
+    place(trigger, panel);
+  };
+
+  const onClick = (e) => {
+    const trigger = e.target.closest?.('[data-bronto-popover]');
+    if (trigger && host.contains(trigger)) {
+      const panel = byIdInHost(host, trigger.getAttribute('data-bronto-popover'));
+      if (!panel) return;
+      e.preventDefault();
+      if (openPanel === panel) close();
+      else open(trigger, panel);
+      return;
+    }
+    if (openPanel && !openPanel.contains(e.target)) close();
+  };
+  const onKey = (e) => {
+    if (e.key === 'Escape' && openPanel) {
+      const t = openTrigger;
+      close();
+      t?.focus?.();
+    }
+  };
+  const onReflow = () => {
+    if (openPanel && openTrigger) place(openTrigger, openPanel);
+  };
+
+  return bindOnce(host, 'popover', () => {
+    document.addEventListener('click', onClick);
+    document.addEventListener('keydown', onKey);
+    view?.addEventListener('scroll', onReflow, true);
+    view?.addEventListener('resize', onReflow);
+    return () => {
+      document.removeEventListener('click', onClick);
+      document.removeEventListener('keydown', onKey);
+      view?.removeEventListener('scroll', onReflow, true);
+      view?.removeEventListener('resize', onReflow);
+    };
+  });
+}

package/behaviors/spotlight.js

@@ -0,0 +1,53 @@
+import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
+
+/**
+ * Position a spotlight cutout over a target element. Each
+ * `[data-bronto-spotlight]` is a `.ui-spotlight` overlay; `data-target` is the
+ * id of the element to highlight. The behavior measures the target and sets
+ * `--spot-x/y/w/h` (viewport coordinates) on the overlay, re-placing on
+ * resize/scroll and whenever `data-target` changes.
+ *
+ * Bronto owns only positioning + the visual language. It is NOT a tour engine:
+ * the host decides which target is current, when to advance, and whether to
+ * show/hide the overlay — just update `data-target` (or toggle `hidden`) and
+ * the cutout follows. SSR-safe, idempotent per host; returns a cleanup.
+ */
+export function initSpotlight({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  const spots = [];
+  if (host !== document && host.matches?.('[data-bronto-spotlight]')) spots.push(host);
+  spots.push(...host.querySelectorAll('[data-bronto-spotlight]'));
+  if (!spots.length) return noop;
+
+  const place = () => {
+    for (const spot of spots) {
+      const target = byIdInHost(host, spot.dataset.target);
+      if (!target) continue;
+      const r = target.getBoundingClientRect();
+      spot.style.setProperty('--spot-x', `${r.left}px`);
+      spot.style.setProperty('--spot-y', `${r.top}px`);
+      spot.style.setProperty('--spot-w', `${r.width}px`);
+      spot.style.setProperty('--spot-h', `${r.height}px`);
+    }
+  };
+
+  return bindOnce(host, 'spotlight', () => {
+    place();
+    const view = host.defaultView || host.ownerDocument?.defaultView || null;
+    const MO = view?.MutationObserver;
+    const mo = MO ? new MO(place) : null;
+    if (mo) {
+      for (const spot of spots) {
+        mo.observe(spot, { attributes: true, attributeFilter: ['data-target'] });
+      }
+    }
+    view?.addEventListener('resize', place);
+    view?.addEventListener('scroll', place, true);
+    return () => {
+      mo?.disconnect();
+      view?.removeEventListener('resize', place);
+      view?.removeEventListener('scroll', place, true);
+    };
+  });
+}

package/behaviors/table.js

@@ -0,0 +1,109 @@
+import { hasDom, noop, bindOnce } from './internal.js';
+
+/**
+ * Client-side sortable + selectable data table. Wires
+ * `[data-bronto-sortable]`:
+ *
+ *  - clicking a header's `.ui-table__sort` (or a `th[data-sort]`)
+ *    sorts the tbody by that column, cycling `aria-sort`
+ *    none → ascending → descending and clearing the other headers.
+ *    Numeric columns (`data-sort="num"` or `.is-num` cells) sort
+ *    numerically; everything else, locale string compare.
+ *  - a `[data-bronto-select-all]` checkbox toggles every
+ *    `[data-bronto-select]` row checkbox and the rows'
+ *    `aria-selected`; toggling a row keeps the header checkbox's
+ *    checked/indeterminate state in sync. Emits `bronto:selectionchange`
+ *    ({ detail: { count } }) on the table.
+ *
+ * SSR-safe, idempotent per table; returns a cleanup function.
+ */
+export function initTableSort({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  const tables = [];
+  if (host !== document && host.matches?.('[data-bronto-sortable]')) tables.push(host);
+  tables.push(...(host.querySelectorAll?.('[data-bronto-sortable]') ?? []));
+  const cleanups = [];
+
+  for (const table of tables) {
+    const tbody = table.tBodies[0];
+    if (!tbody) continue;
+
+    const colIndex = (th) => [...th.parentElement.children].indexOf(th);
+    const cellText = (row, i) => row.children[i]?.textContent.trim() ?? '';
+
+    const sortBy = (th, numeric) => {
+      const headers = th.closest('tr').querySelectorAll('th');
+      const dir = th.getAttribute('aria-sort') === 'ascending' ? 'descending' : 'ascending';
+      headers.forEach((h) => h.removeAttribute('aria-sort'));
+      th.setAttribute('aria-sort', dir);
+      const i = colIndex(th);
+      const sign = dir === 'ascending' ? 1 : -1;
+      const rows = [...tbody.rows].filter((r) => !r.classList.contains('ui-table__empty'));
+      rows.sort((a, b) => {
+        const x = cellText(a, i);
+        const y = cellText(b, i);
+        const cmp = numeric
+          ? (parseFloat(x.replace(/[^\d.-]/g, '')) || 0) -
+            (parseFloat(y.replace(/[^\d.-]/g, '')) || 0)
+          : x.localeCompare(y);
+        return cmp * sign;
+      });
+      rows.forEach((r) => tbody.appendChild(r));
+    };
+
+    const allBox = table.querySelector('[data-bronto-select-all]');
+    const rowBoxes = () => [...table.querySelectorAll('[data-bronto-select]')];
+    const syncAll = () => {
+      const boxes = rowBoxes();
+      const on = boxes.filter((b) => b.checked).length;
+      if (allBox) {
+        allBox.checked = on > 0 && on === boxes.length;
+        allBox.indeterminate = on > 0 && on < boxes.length;
+      }
+      table.dispatchEvent(
+        new CustomEvent('bronto:selectionchange', { detail: { count: on }, bubbles: true }),
+      );
+    };
+    const markRow = (box) => {
+      const tr = box.closest('tr');
+      if (tr) tr.setAttribute('aria-selected', String(box.checked));
+    };
+
+    const onClick = (e) => {
+      const sorter = e.target.closest('.ui-table__sort, th[data-sort]');
+      if (sorter && table.contains(sorter)) {
+        const th = sorter.closest('th');
+        const numeric =
+          (sorter.getAttribute('data-sort') || th.getAttribute('data-sort')) === 'num' ||
+          th.classList.contains('is-num');
+        sortBy(th, numeric);
+      }
+    };
+    const onChange = (e) => {
+      const t = e.target;
+      if (t.matches?.('[data-bronto-select-all]')) {
+        rowBoxes().forEach((b) => {
+          b.checked = t.checked;
+          markRow(b);
+        });
+        syncAll();
+      } else if (t.matches?.('[data-bronto-select]')) {
+        markRow(t);
+        syncAll();
+      }
+    };
+
+    const bound = bindOnce(table, 'tableSort', () => {
+      table.addEventListener('click', onClick);
+      table.addEventListener('change', onChange);
+      return () => {
+        table.removeEventListener('click', onClick);
+        table.removeEventListener('change', onChange);
+      };
+    });
+    cleanups.push(bound);
+  }
+
+  return () => cleanups.forEach((fn) => fn());
+}

package/behaviors/tabs.js

@@ -0,0 +1,103 @@
+import { hasDom, noop, bindOnce } from './internal.js';
+
+// 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;
+
+/**
+ * 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());
+}

package/behaviors/theme.js

@@ -0,0 +1,82 @@
+import { hasDom, 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 = root || document.documentElement;
+  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 = root || document;
+  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);
+  });
+}