@ponchia/ui 0.4.1 → 0.6.0

package/behaviors/carousel.js

@@ -0,0 +1,198 @@
+import {
+  hasDom,
+  resolveHost,
+  noop,
+  bindOnce,
+  scrollIntoViewSafe,
+  collectHosts,
+} from './internal.js';
+
+/**
+ * Image carousel / gallery, built on CSS scroll-snap so touch + trackpad
+ * swipe (and momentum) are the browser's, not hand-rolled. This wires the
+ * parts scroll-snap can't do alone: prev/next buttons, keyboard nav, a
+ * thumbnail strip, the position counter, and ARIA — keeping a JS index in
+ * sync with the scroll position both ways.
+ *
+ * Markup: `[data-bronto-carousel]` containing a `.ui-carousel__viewport`
+ * of `.ui-carousel__slide` children; optionally
+ * `[data-bronto-carousel-prev]` / `[data-bronto-carousel-next]` controls,
+ * a `.ui-carousel__thumbs` list of `.ui-carousel__thumb` buttons, and a
+ * `.ui-carousel__status` counter slot. Add `data-bronto-carousel-loop` to
+ * wrap at the ends, `data-bronto-carousel-label` to name the region.
+ *
+ * A full-screen **lightbox** is the same markup inside a native
+ * `<dialog class="ui-lightbox">` opened by {@link initDialog}: the
+ * `<dialog>` provides the top layer, focus-trap, Escape and focus-return,
+ * so this behavior never touches focus management.
+ *
+ * Emits `bronto:change` ({ detail: { index } }) on every index change
+ * (button, key, thumbnail, or swipe). SSR-safe, idempotent per carousel;
+ * returns a cleanup function.
+ */
+export function initCarousel({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const boxes = collectHosts(host, '[data-bronto-carousel]');
+  const cleanups = [];
+
+  for (const box of boxes) {
+    const viewport = box.querySelector('.ui-carousel__viewport');
+    if (!viewport) continue;
+    const slides = [...viewport.children].filter((el) =>
+      el.classList.contains('ui-carousel__slide'),
+    );
+    if (!slides.length) continue;
+    const n = slides.length;
+    const thumbs = [...box.querySelectorAll('.ui-carousel__thumb')];
+    const status = box.querySelector('.ui-carousel__status');
+    const prevBtn = box.querySelector('[data-bronto-carousel-prev]');
+    const nextBtn = box.querySelector('[data-bronto-carousel-next]');
+    const loop = box.hasAttribute('data-bronto-carousel-loop');
+
+    // ARIA scaffolding — pragmatic carousel semantics (not the full APG
+    // tablist), the same restraint initMenu takes.
+    viewport.setAttribute('role', 'group');
+    viewport.setAttribute('aria-roledescription', 'carousel');
+    if (!viewport.hasAttribute('aria-label'))
+      viewport.setAttribute(
+        'aria-label',
+        box.getAttribute('data-bronto-carousel-label') || 'Carousel',
+      );
+    if (!viewport.hasAttribute('tabindex')) viewport.tabIndex = 0;
+    slides.forEach((s, i) => {
+      s.setAttribute('role', 'group');
+      s.setAttribute('aria-roledescription', 'slide');
+      if (!s.hasAttribute('aria-label')) s.setAttribute('aria-label', `${i + 1} of ${n}`);
+    });
+    if (status) status.setAttribute('aria-live', 'polite');
+    for (const b of [prevBtn, nextBtn]) {
+      if (!b) continue;
+      if (b.tagName === 'BUTTON' && !b.hasAttribute('type')) b.type = 'button';
+    }
+    if (prevBtn && !prevBtn.hasAttribute('aria-label'))
+      prevBtn.setAttribute('aria-label', 'Previous');
+    if (nextBtn && !nextBtn.hasAttribute('aria-label')) nextBtn.setAttribute('aria-label', 'Next');
+
+    let index = Math.max(
+      0,
+      slides.findIndex((s) => s.hasAttribute('data-bronto-carousel-current')),
+    );
+
+    // While a button/keyboard nav is smooth-scrolling, the IntersectionObserver
+    // would observe the intermediate slides crossing its threshold and re-fire
+    // `bronto:change` for each — a feedback burst on a single Home→End jump.
+    // This flag makes the IO drive the index on *user* swipes only; a timeout
+    // (not the patchy `scrollend` event) releases it once the scroll settles.
+    let programmatic = false;
+    let progTimer = null;
+    const holdProgrammatic = () => {
+      programmatic = true;
+      if (progTimer) clearTimeout(progTimer);
+      progTimer = setTimeout(() => {
+        programmatic = false;
+      }, 500);
+      progTimer?.unref?.(); // don't keep a Node test process alive
+    };
+
+    const render = () => {
+      if (status) status.textContent = `${index + 1} / ${n}`;
+      thumbs.forEach((t, i) => {
+        if (i === index) t.setAttribute('aria-current', 'true');
+        else t.removeAttribute('aria-current');
+      });
+      if (prevBtn && !loop) prevBtn.disabled = index === 0;
+      if (nextBtn && !loop) nextBtn.disabled = index === n - 1;
+    };
+
+    const emit = () =>
+      box.dispatchEvent(new CustomEvent('bronto:change', { detail: { index }, bubbles: true }));
+
+    const reveal = (el) => scrollIntoViewSafe(el, { block: 'nearest', inline: 'center' });
+
+    const goTo = (i, { emitChange = true } = {}) => {
+      const next = loop ? (i + n) % n : Math.max(0, Math.min(n - 1, i));
+      const changed = next !== index;
+      index = next;
+      holdProgrammatic(); // suppress IO echo from the smooth-scroll this triggers
+      reveal(slides[index]);
+      reveal(thumbs[index]);
+      render();
+      if (changed && emitChange) emit();
+    };
+
+    const onKey = (e) => {
+      let target = null;
+      if (e.key === 'ArrowRight') target = index + 1;
+      else if (e.key === 'ArrowLeft') target = index - 1;
+      else if (e.key === 'Home') target = 0;
+      else if (e.key === 'End') target = n - 1;
+      else return;
+      e.preventDefault();
+      goTo(target);
+    };
+    const onClick = (e) => {
+      if (prevBtn && e.target.closest('[data-bronto-carousel-prev]')) {
+        goTo(index - 1);
+        return;
+      }
+      if (nextBtn && e.target.closest('[data-bronto-carousel-next]')) {
+        goTo(index + 1);
+        return;
+      }
+      const thumb = e.target.closest('.ui-carousel__thumb');
+      if (thumb) {
+        const i = thumbs.indexOf(thumb);
+        if (i >= 0) goTo(i);
+      }
+    };
+
+    // Swipe sync (enhancement): when the user scrolls the viewport, snap
+    // the JS index to the slide that's settled into view. Feature-detected
+    // so the buttons/keyboard still work where IntersectionObserver is
+    // absent (jsdom, older engines).
+    let io = null;
+    if (typeof IntersectionObserver === 'function') {
+      io = new IntersectionObserver(
+        (entries) => {
+          if (programmatic) return; // ignore the echo of a button/key-driven scroll
+          let best = null;
+          for (const ent of entries) {
+            if (ent.isIntersecting && (!best || ent.intersectionRatio > best.intersectionRatio))
+              best = ent;
+          }
+          if (!best) return;
+          const i = slides.indexOf(best.target);
+          if (i >= 0 && i !== index) {
+            index = i;
+            render();
+            reveal(thumbs[index]);
+            emit();
+          }
+        },
+        { root: viewport, threshold: 0.6 },
+      );
+    }
+
+    render();
+    const bound = bindOnce(box, 'carousel', () => {
+      viewport.addEventListener('keydown', onKey);
+      box.addEventListener('click', onClick);
+      // Observe inside the add callback so observe/disconnect pair with the
+      // binding lifecycle: a re-init tears down the prior binding (which
+      // disconnects the old observer) before this starts, so two observers
+      // never watch the same slides — even for one tick.
+      slides.forEach((s) => io?.observe(s));
+      return () => {
+        viewport.removeEventListener('keydown', onKey);
+        box.removeEventListener('click', onClick);
+        io?.disconnect();
+        if (progTimer) clearTimeout(progTimer);
+      };
+    });
+    cleanups.push(bound);
+  }
+
+  return () => cleanups.forEach((fn) => fn());
+}

package/behaviors/combobox.js

@@ -0,0 +1,226 @@
+import {
+  hasDom,
+  resolveHost,
+  noop,
+  bindOnce,
+  nextFieldUid,
+  scrollIntoViewSafe,
+  wrapIndex,
+  collectHosts,
+} from './internal.js';
+
+/**
+ * Editable combobox with a filtered listbox popup, implementing the
+ * WAI-ARIA APG combobox pattern (the widget the framework most lacked
+ * and consumers most often build badly). Dependency-free, no
+ * positioning library — the list is CSS-anchored under the input.
+ *
+ * The input MUST have an accessible name — a `<label>`, `aria-label`, or
+ * `aria-labelledby` (a placeholder does not count). A nameless `role="combobox"`
+ * is a silent screen-reader failure, so the behavior warns at dev time when it
+ * finds one, and mirrors the input's name onto the listbox.
+ *
+ * Markup: `[data-bronto-combobox]` wrapping an `<input role="combobox">`
+ * (`.ui-combobox__input`) and a `<ul role="listbox">`
+ * (`.ui-combobox__list`) of `<li role="option">` (`.ui-combobox__option`,
+ * optional `data-value`). An optional `.ui-combobox__empty` shows when
+ * nothing matches. The behavior owns ids, `aria-expanded`,
+ * `aria-controls`, `aria-activedescendant`, roving active option,
+ * type-to-filter, full keyboard (Down/Up/Home/End/Enter/Escape/Tab),
+ * pointer select, and outside-click close; it emits a `bronto:change`
+ * CustomEvent ({ detail: { value } }) on selection. SSR-safe,
+ * idempotent per instance; returns a cleanup function.
+ *
+ * Options are read from the DOM at init; if you replace the listbox contents
+ * (e.g. async/remote results) without re-initialising, filtering and keyboard
+ * nav act on the stale nodes — re-run initCombobox after mutating the options.
+ */
+export function initCombobox({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const boxes = collectHosts(host, '[data-bronto-combobox]');
+  const cleanups = [];
+
+  for (const box of boxes) {
+    const input = box.querySelector('[role="combobox"], .ui-combobox__input');
+    const list = box.querySelector('[role="listbox"], .ui-combobox__list');
+    if (!input || !list) continue;
+    const empty = box.querySelector('.ui-combobox__empty');
+    const options = [...list.querySelectorAll('[role="option"], .ui-combobox__option')];
+
+    const listId = list.id || (list.id = `bronto-cb-list-${nextFieldUid()}`);
+    options.forEach((o, i) => {
+      if (!o.id) o.id = `${listId}-opt-${i}`;
+      o.setAttribute('role', 'option');
+    });
+    list.setAttribute('role', 'listbox');
+    // Give the listbox its own accessible name (a bare role=listbox is unnamed
+    // to a screen reader) by mirroring the input's name. (a11y review C30.)
+    if (!list.hasAttribute('aria-label') && !list.hasAttribute('aria-labelledby')) {
+      const name =
+        input.getAttribute('aria-label') ||
+        input.labels?.[0]?.textContent?.trim() ||
+        input.getAttribute('placeholder');
+      if (name) list.setAttribute('aria-label', name);
+    }
+    // A `role="combobox"` with no accessible name is a silent AT failure. A
+    // placeholder is not a robust name (it can vanish and is ignored by some
+    // AT), so warn unless there is a real label/aria-label/aria-labelledby/title
+    // (C7). We can't invent a good name, hence a dev-time warning, not a guess.
+    const inputNamed =
+      input.hasAttribute('aria-label') ||
+      input.hasAttribute('aria-labelledby') ||
+      !!input.labels?.length ||
+      input.hasAttribute('title');
+    if (!inputNamed && typeof console !== 'undefined') {
+      console.warn(
+        '[bronto] initCombobox(): the combobox input has no accessible name — add a <label>, aria-label, or aria-labelledby (a placeholder is not enough).',
+      );
+    }
+    input.setAttribute('role', 'combobox');
+    input.setAttribute('aria-controls', listId);
+    input.setAttribute('aria-autocomplete', 'list');
+    input.setAttribute('aria-expanded', 'false');
+    input.setAttribute('autocomplete', 'off');
+    list.hidden = true;
+
+    let active = -1;
+    const visible = () => options.filter((o) => !o.hidden);
+
+    const setActive = (opt) => {
+      options.forEach((o) => o.classList.remove('is-active'));
+      if (opt) {
+        opt.classList.add('is-active');
+        input.setAttribute('aria-activedescendant', opt.id);
+        scrollIntoViewSafe(opt);
+      } else {
+        input.removeAttribute('aria-activedescendant');
+      }
+    };
+
+    const open = () => {
+      if (!list.hidden) return;
+      list.hidden = false;
+      input.setAttribute('aria-expanded', 'true');
+    };
+    const close = () => {
+      list.hidden = true;
+      input.setAttribute('aria-expanded', 'false');
+      active = -1;
+      setActive(null);
+    };
+
+    const filter = () => {
+      const q = input.value.trim().toLowerCase();
+      let any = false;
+      for (const o of options) {
+        const match = !q || o.textContent.toLowerCase().includes(q);
+        o.hidden = !match;
+        if (match) any = true;
+      }
+      if (empty) empty.hidden = any;
+      // The active option may have just been filtered out — drop the
+      // stale activedescendant so Enter can't select a hidden option.
+      if (active >= 0 && options[active]?.hidden) {
+        active = -1;
+        setActive(null);
+      }
+      open();
+    };
+
+    const select = (opt) => {
+      input.value = opt.dataset.value ?? opt.textContent.trim();
+      options.forEach((o) => o.setAttribute('aria-selected', String(o === opt)));
+      close();
+      input.focus();
+      box.dispatchEvent(
+        new CustomEvent('bronto:change', {
+          detail: { value: input.value },
+          bubbles: true,
+        }),
+      );
+    };
+
+    const move = (delta) => {
+      const vis = visible();
+      if (!vis.length) return;
+      open();
+      const next = wrapIndex(vis.indexOf(options[active]), delta, vis.length);
+      active = options.indexOf(vis[next]);
+      setActive(options[active]);
+    };
+    const activateEdge = (which) => {
+      if (list.hidden) return false;
+      const v = visible();
+      if (!v.length) return true;
+      active = options.indexOf(which === 'first' ? v[0] : v[v.length - 1]);
+      setActive(options[active]);
+      return true;
+    };
+    const selectActive = () => {
+      if (list.hidden || active < 0 || options[active].hidden) return false;
+      select(options[active]);
+      return true;
+    };
+    const closeIfOpen = () => {
+      if (list.hidden) return false;
+      close();
+      return true;
+    };
+
+    const onInput = () => filter();
+    const onKey = (e) => {
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault();
+          list.hidden ? filter() : move(1);
+          break;
+        case 'ArrowUp':
+          e.preventDefault();
+          move(-1);
+          break;
+        case 'Home':
+          if (activateEdge('first')) e.preventDefault();
+          break;
+        case 'End':
+          if (activateEdge('last')) e.preventDefault();
+          break;
+        case 'Enter':
+          if (selectActive()) e.preventDefault();
+          break;
+        case 'Escape':
+          if (closeIfOpen()) e.preventDefault();
+          break;
+        case 'Tab':
+          close();
+          break;
+        default:
+          break;
+      }
+    };
+    const onOptionClick = (e) => {
+      const opt = e.target.closest('[role="option"], .ui-combobox__option');
+      if (opt) select(opt);
+    };
+    const onDocClick = (e) => {
+      if (!box.contains(e.target)) close();
+    };
+
+    const bound = bindOnce(box, 'combobox', () => {
+      input.addEventListener('input', onInput);
+      input.addEventListener('keydown', onKey);
+      list.addEventListener('click', onOptionClick);
+      document.addEventListener('click', onDocClick);
+      return () => {
+        input.removeEventListener('input', onInput);
+        input.removeEventListener('keydown', onKey);
+        list.removeEventListener('click', onOptionClick);
+        document.removeEventListener('click', onDocClick);
+      };
+    });
+    cleanups.push(bound);
+  }
+
+  return () => cleanups.forEach((fn) => fn());
+}

package/behaviors/command.js

@@ -0,0 +1,190 @@
+import {
+  hasDom,
+  resolveHost,
+  noop,
+  bindOnce,
+  nextFieldUid,
+  collectHosts,
+  scrollIntoViewSafe,
+  wrapIndex,
+} from './internal.js';
+
+/**
+ * Command palette — filter + keyboard-navigate a DOM-authored command list.
+ * The CSS shell (`.ui-command`) is opt-in; this wires the listbox behavior the
+ * shell needs. Bronto filters and navigates; the HOST owns the action registry,
+ * permission checks, routing, async effects, and command execution (it listens
+ * for `bronto:command:select`). There is no global Cmd/Ctrl+K — open the palette
+ * yourself (e.g. a `<dialog>` via `initDialog`).
+ *
+ * Markup: `[data-bronto-command]` wrapping an `<input>` (`.ui-command__input`)
+ * and a list (`.ui-command__list`) of `.ui-command__item` rows (optional
+ * `data-value`), interleaved with `.ui-command__group` labels and an optional
+ * `.ui-command__empty`. The behavior owns ids, `role=combobox/listbox/option`,
+ * `aria-activedescendant`, a roving active item, substring filtering (hiding
+ * empty groups), full keyboard (Down/Up/Home/End/Enter/Escape), and pointer
+ * select. It emits `bronto:command:select` ({ detail: { value, label } }) on
+ * choose and `bronto:command:close` on Escape. SSR-safe, idempotent per
+ * instance; returns a cleanup function.
+ *
+ * Items are read from the DOM at init; re-run initCommand after replacing the
+ * command list so filtering/navigation see the current nodes.
+ */
+export function initCommand({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const palettes = collectHosts(host, '[data-bronto-command]');
+  const cleanups = [];
+
+  for (const box of palettes) {
+    const input = box.querySelector('.ui-command__input, input');
+    const list = box.querySelector('.ui-command__list, [role="listbox"]');
+    if (!input || !list) continue;
+    const empty = box.querySelector('.ui-command__empty');
+    const items = [...list.querySelectorAll('.ui-command__item, [role="option"]')];
+    const groups = [...list.querySelectorAll('.ui-command__group')];
+
+    const listId = list.id || (list.id = `bronto-cmd-${nextFieldUid()}`);
+    items.forEach((it, i) => {
+      if (!it.id) it.id = `${listId}-opt-${i}`;
+      it.setAttribute('role', 'option');
+    });
+    groups.forEach((g) => g.setAttribute('role', 'presentation'));
+    list.setAttribute('role', 'listbox');
+    input.setAttribute('role', 'combobox');
+    input.setAttribute('aria-controls', listId);
+    input.setAttribute('aria-autocomplete', 'list');
+    input.setAttribute('aria-expanded', 'true');
+    input.setAttribute('autocomplete', 'off');
+
+    let active = -1;
+    const visible = () => items.filter((it) => !it.hidden);
+
+    const setActive = (item) => {
+      items.forEach((it) => {
+        it.classList.toggle('is-active', it === item);
+        it.setAttribute('aria-selected', String(it === item));
+      });
+      if (item) {
+        active = items.indexOf(item);
+        input.setAttribute('aria-activedescendant', item.id);
+        scrollIntoViewSafe(item);
+      } else {
+        active = -1;
+        input.removeAttribute('aria-activedescendant');
+      }
+    };
+
+    // Hide a group whose items are all filtered out.
+    const syncGroups = () => {
+      for (const g of groups) {
+        let any = false;
+        for (
+          let n = g.nextElementSibling;
+          n && !n.matches('.ui-command__group');
+          n = n.nextElementSibling
+        ) {
+          if (n.matches('.ui-command__item, [role="option"]') && !n.hidden) any = true;
+        }
+        g.hidden = !any;
+      }
+    };
+
+    const filter = () => {
+      const q = input.value.trim().toLowerCase();
+      let any = false;
+      for (const it of items) {
+        const match = !q || it.textContent.toLowerCase().includes(q);
+        it.hidden = !match;
+        if (match) any = true;
+      }
+      syncGroups();
+      if (empty) empty.hidden = any;
+      const vis = visible();
+      setActive(vis[0] || null);
+    };
+
+    const move = (delta) => {
+      const vis = visible();
+      if (!vis.length) return;
+      setActive(vis[wrapIndex(vis.indexOf(items[active]), delta, vis.length)]);
+    };
+
+    const choose = (item) => {
+      if (!item || item.hidden) return;
+      // Label = the command name only — strip the shortcut/meta hints so the
+      // host doesn't get "Open settings G S".
+      const clone = item.cloneNode(true);
+      clone.querySelectorAll('.ui-command__shortcut, .ui-command__meta').forEach((n) => n.remove());
+      const label = clone.textContent.replace(/\s+/g, ' ').trim();
+      box.dispatchEvent(
+        new CustomEvent('bronto:command:select', {
+          detail: { value: item.dataset.value ?? label, label },
+          bubbles: true,
+        }),
+      );
+    };
+
+    const onInput = () => filter();
+    const onKey = (e) => {
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault();
+          move(1);
+          break;
+        case 'ArrowUp':
+          e.preventDefault();
+          move(-1);
+          break;
+        case 'Home': {
+          const v = visible();
+          if (v.length) {
+            setActive(v[0]);
+            e.preventDefault();
+          }
+          break;
+        }
+        case 'End': {
+          const v = visible();
+          if (v.length) {
+            setActive(v[v.length - 1]);
+            e.preventDefault();
+          }
+          break;
+        }
+        case 'Enter':
+          if (active >= 0 && !items[active].hidden) {
+            choose(items[active]);
+            e.preventDefault();
+          }
+          break;
+        case 'Escape':
+          box.dispatchEvent(new CustomEvent('bronto:command:close', { bubbles: true }));
+          break;
+        default:
+          break;
+      }
+    };
+    const onClick = (e) => {
+      const item = e.target.closest('.ui-command__item, [role="option"]');
+      if (item && list.contains(item)) choose(item);
+    };
+
+    const bound = bindOnce(box, 'command', () => {
+      input.addEventListener('input', onInput);
+      input.addEventListener('keydown', onKey);
+      list.addEventListener('click', onClick);
+      return () => {
+        input.removeEventListener('input', onInput);
+        input.removeEventListener('keydown', onKey);
+        list.removeEventListener('click', onClick);
+      };
+    });
+    // Seed the initial active item (first visible).
+    filter();
+    cleanups.push(bound);
+  }
+
+  return () => cleanups.forEach((fn) => fn());
+}