@ponchia/ui 0.4.1 → 0.6.0

package/behaviors/connectors.js

@@ -0,0 +1,95 @@
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost, collectHosts } from './internal.js';
+import { connectRects, arrowHead, dotMark } from '../connectors/index.js';
+
+const SVGNS = 'http://www.w3.org/2000/svg';
+
+/**
+ * Draw + keep leader lines in sync. Each `[data-bronto-connector]` is an
+ * `.ui-connector` SVG overlaying a positioned container; `data-from`/`data-to`
+ * are the ids of the elements to connect. Optional `data-shape`
+ * (`straight`|`elbow`|`curve`), `data-from-side`/`data-to-side`
+ * (`top`|`right`|`bottom`|`left`|`center`), and `data-end` (`arrow`|`dot`|`none`).
+ *
+ * Bronto computes the geometry (the pure `@ponchia/ui/connectors` helpers) and
+ * sets the path; it owns no layout. Redraws on resize/scroll via a
+ * ResizeObserver + listeners. SSR-safe, idempotent per host; returns a cleanup
+ * that disconnects everything. Re-run after adding/removing connectors.
+ */
+export function initConnectors({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const connectors = collectHosts(host, '[data-bronto-connector]');
+  if (!connectors.length) return noop;
+
+  const draw = () => {
+    for (const svg of connectors) {
+      const from = byIdInHost(host, svg.dataset.from);
+      const to = byIdInHost(host, svg.dataset.to);
+      if (!from || !to) continue;
+      const o = svg.getBoundingClientRect();
+      const rel = (el) => {
+        const r = el.getBoundingClientRect();
+        return { x: r.left - o.left, y: r.top - o.top, width: r.width, height: r.height };
+      };
+      const {
+        d,
+        to: end,
+        angle,
+      } = connectRects({
+        fromRect: rel(from),
+        toRect: rel(to),
+        shape: svg.dataset.shape || 'straight',
+        fromSide: svg.dataset.fromSide || undefined,
+        toSide: svg.dataset.toSide || undefined,
+      });
+      let path = svg.querySelector('.ui-connector__path');
+      if (!path) {
+        path = document.createElementNS(SVGNS, 'path');
+        path.setAttribute('class', 'ui-connector__path');
+        svg.appendChild(path);
+      }
+      path.setAttribute('d', d);
+      // pathLength="1" normalises the draw animation, but it would also reframe
+      // a dashed line's user-unit dasharray — so only set it for draw connectors.
+      if (svg.classList.contains('ui-connector--draw')) path.setAttribute('pathLength', '1');
+      else path.removeAttribute('pathLength');
+
+      const kind = svg.dataset.end || 'arrow';
+      let cap = svg.querySelector('.ui-connector__end');
+      if (kind === 'none') {
+        cap?.remove();
+        continue;
+      }
+      if (!cap) {
+        cap = document.createElementNS(SVGNS, 'path');
+        cap.setAttribute('class', 'ui-connector__end');
+        svg.appendChild(cap);
+      }
+      cap.setAttribute('d', kind === 'dot' ? dotMark(end, 3) : arrowHead(end, angle, 8));
+    }
+  };
+
+  return bindOnce(host, 'connectors', () => {
+    draw();
+    const view = host.defaultView || host.ownerDocument?.defaultView || null;
+    const RO = view?.ResizeObserver;
+    const ro = RO ? new RO(draw) : null;
+    if (ro) {
+      for (const svg of connectors) {
+        if (svg.parentElement) ro.observe(svg.parentElement);
+        const f = byIdInHost(host, svg.dataset.from);
+        const t = byIdInHost(host, svg.dataset.to);
+        if (f) ro.observe(f);
+        if (t) ro.observe(t);
+      }
+    }
+    view?.addEventListener('resize', draw);
+    view?.addEventListener('scroll', draw, true);
+    return () => {
+      ro?.disconnect();
+      view?.removeEventListener('resize', draw);
+      view?.removeEventListener('scroll', draw, true);
+    };
+  });
+}

package/behaviors/crosshair.js

@@ -0,0 +1,57 @@
+import { hasDom, resolveHost, noop, bindOnce, collectHosts } from './internal.js';
+
+/**
+ * Track the pointer over a plot and drive a crosshair. Each
+ * `[data-bronto-crosshair]` is the plot; it contains a `.ui-crosshair` overlay.
+ * On pointer move the behavior sets `--crosshair-x/y` (pixels within the plot)
+ * on the overlay, marks it `.is-active`, and dispatches
+ * `bronto:crosshair:move` with `{ x, y, fx, fy }` (px + 0..1 fractions);
+ * `bronto:crosshair:leave` on exit.
+ *
+ * Bronto reports WHERE the pointer is — it does not find the nearest datum or
+ * map pixels to data values (that needs the host's scales). SSR-safe,
+ * idempotent per plot; returns a cleanup function.
+ */
+export function initCrosshair({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const plots = collectHosts(host, '[data-bronto-crosshair]');
+  if (!plots.length) return noop;
+
+  const cleanups = [];
+  for (const plot of plots) {
+    const overlay = plot.querySelector('.ui-crosshair');
+    if (!overlay) continue;
+    const onMove = (e) => {
+      const r = plot.getBoundingClientRect();
+      if (!r.width || !r.height) return;
+      const x = e.clientX - r.left;
+      const y = e.clientY - r.top;
+      overlay.style.setProperty('--crosshair-x', `${x}px`);
+      overlay.style.setProperty('--crosshair-y', `${y}px`);
+      overlay.classList.add('is-active');
+      plot.dispatchEvent(
+        new CustomEvent('bronto:crosshair:move', {
+          bubbles: true,
+          detail: { x, y, fx: x / r.width, fy: y / r.height },
+        }),
+      );
+    };
+    const onLeave = () => {
+      overlay.classList.remove('is-active');
+      plot.dispatchEvent(new CustomEvent('bronto:crosshair:leave', { bubbles: true }));
+    };
+    cleanups.push(
+      bindOnce(plot, 'crosshair', () => {
+        plot.addEventListener('pointermove', onMove);
+        plot.addEventListener('pointerleave', onLeave);
+        return () => {
+          plot.removeEventListener('pointermove', onMove);
+          plot.removeEventListener('pointerleave', onLeave);
+        };
+      }),
+    );
+  }
+  return () => cleanups.forEach((fn) => fn());
+}

package/behaviors/dialog.js

@@ -0,0 +1,74 @@
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost } from './internal.js';
+
+/**
+ * Wire native <dialog> open/close glue (the one bit <dialog> can't do
+ * 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. 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 delegated triggers (default `document`). Controlled targets are
+ * resolved root-first, then document-wide, so scoped islands win duplicate-id
+ * conflicts without breaking body/portal-mounted overlays.
+ */
+export function initDialog({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const managedDialogs = new WeakSet();
+  const canManageDialog = (dlg, origin) => host.contains(origin) || managedDialogs.has(dlg);
+
+  const openFrom = (opener) => {
+    const dlg = byIdInHost(host, opener.getAttribute('data-bronto-open'));
+    if (!dlg || typeof dlg.showModal !== 'function' || dlg.open) return;
+    managedDialogs.add(dlg);
+    dlg.addEventListener(
+      'close',
+      () => {
+        if (opener.isConnected && typeof opener.focus === 'function') opener.focus();
+      },
+      { once: true },
+    );
+    dlg.showModal();
+  };
+
+  const closeFrom = (closer) => {
+    const dlg = closer.closest('dialog');
+    if (dlg && dlg.open && canManageDialog(dlg, closer)) dlg.close();
+  };
+
+  const lightDismiss = (dlg) => {
+    if (
+      dlg.tagName === 'DIALOG' &&
+      dlg.open &&
+      dlg.hasAttribute('data-bronto-dialog-light') &&
+      canManageDialog(dlg, dlg)
+    ) {
+      dlg.close();
+    }
+  };
+
+  const onClick = (e) => {
+    const opener = e.target.closest('[data-bronto-open]');
+    if (opener && host.contains(opener)) {
+      openFrom(opener);
+      return;
+    }
+    const closer = e.target.closest('[data-bronto-close]');
+    if (closer) {
+      closeFrom(closer);
+      return;
+    }
+    // Light-dismiss: a click whose target is the <dialog> itself is the
+    // backdrop (content sits in child elements).
+    lightDismiss(e.target);
+  };
+  return bindOnce(host, 'dialog', () => {
+    document.addEventListener('click', onClick);
+    return () => document.removeEventListener('click', onClick);
+  });
+}

package/behaviors/disclosure.js

@@ -0,0 +1,26 @@
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost } from './internal.js';
+
+/**
+ * Disclosure: a `[data-bronto-disclosure]` trigger toggles the element
+ * referenced by its `aria-controls` id, keeping `aria-expanded` and the
+ * panel's `hidden` attribute in sync.
+ */
+export function initDisclosure({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const onClick = (e) => {
+    const trigger = e.target.closest('[data-bronto-disclosure]');
+    if (!trigger || !host.contains(trigger)) return;
+    const id = trigger.getAttribute('aria-controls');
+    const panel = byIdInHost(host, id);
+    if (!panel) return;
+    const open = trigger.getAttribute('aria-expanded') === 'true';
+    trigger.setAttribute('aria-expanded', String(!open));
+    panel.hidden = open;
+  };
+  return bindOnce(host, 'disclosure', () => {
+    host.addEventListener('click', onClick);
+    return () => host.removeEventListener('click', onClick);
+  });
+}

package/behaviors/dismissible.js

@@ -0,0 +1,25 @@
+import { hasDom, resolveHost, noop, bindOnce, closestSafe } from './internal.js';
+
+/**
+ * Click on `[data-bronto-dismiss]` removes the nearest ancestor matching
+ * `[data-bronto-dismissible]` (or the selector given as the attribute
+ * value). Emits a cancelable `bronto:dismiss` event first.
+ */
+export function dismissible({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const onClick = (e) => {
+    const btn = e.target.closest('[data-bronto-dismiss]');
+    if (!btn || !host.contains(btn)) return;
+    const sel = btn.getAttribute('data-bronto-dismiss');
+    const target = sel ? closestSafe(btn, sel) : btn.closest('[data-bronto-dismissible]');
+    if (!target) return;
+    const ev = new CustomEvent('bronto:dismiss', { bubbles: true, cancelable: true });
+    if (target.dispatchEvent(ev)) target.remove();
+  };
+  return bindOnce(host, 'dismissible', () => {
+    host.addEventListener('click', onClick);
+    return () => host.removeEventListener('click', onClick);
+  });
+}

package/behaviors/forms.js

@@ -0,0 +1,186 @@
+import { hasDom, resolveHost, noop, bindOnce, nextFieldUid, collectHosts } from './internal.js';
+
+/**
+ * Accessible form validation glue for `<form data-bronto-validate>`.
+ * Progressive enhancement over the native Constraint Validation API —
+ * the framework already ships the `[aria-invalid]` / `.ui-hint--error`
+ * styling; this wires the a11y plumbing every consumer would otherwise
+ * re-implement (and usually get wrong):
+ *
+ *  - suppresses the native error bubbles (`form.noValidate`),
+ *  - on blur and on submit sets `aria-invalid` and writes the browser's
+ *    `validationMessage` into the field's error slot
+ *    (`[data-bronto-error]` inside the `.ui-field`, falling back to a
+ *    `.ui-hint`), linked via `aria-describedby`. When it falls back to a
+ *    `.ui-hint` the original help text is snapshotted and restored once the
+ *    field is valid again (so the error does not eat the help permanently); a
+ *    dedicated empty `[data-bronto-error]` node is still the recommended slot,
+ *  - on an invalid submit, fills the form's
+ *    `[data-bronto-error-summary]` (a `.ui-error-summary`) with
+ *    in-page links to each bad field, focuses it, and blocks submit.
+ *
+ * Pure enhancement: with JS off the form still submits and the browser
+ * validates natively. SSR-safe, idempotent; returns a cleanup function.
+ */
+export function initFormValidation({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+
+  const ensureId = (el, prefix) => {
+    if (!el.id) el.id = `${prefix}-${nextFieldUid()}`;
+    return el.id;
+  };
+
+  // When the field has no dedicated `[data-bronto-error]` node we fall back to
+  // the shared `.ui-hint` help slot. Snapshot its original help text the first
+  // time we overwrite it with an error, so the valid branch can RESTORE the help
+  // rather than blanking it permanently (component-audit C8).
+  const hintHelp = new WeakMap();
+
+  const slotFor = (control) => {
+    const field = control.closest('.ui-field');
+    if (!field) return null;
+    const dedicated = field.querySelector('[data-bronto-error]');
+    if (dedicated) return dedicated;
+    return field.querySelector('.ui-hint');
+  };
+
+  const link = (control, slot) => {
+    const slotId = ensureId(slot, 'bronto-err');
+    const ids = (control.getAttribute('aria-describedby') || '').split(/\s+/).filter(Boolean);
+    if (!ids.includes(slotId)) {
+      ids.push(slotId);
+      control.setAttribute('aria-describedby', ids.join(' '));
+    }
+  };
+
+  const unlink = (control, slot) => {
+    if (!slot.id) return;
+    const ids = (control.getAttribute('aria-describedby') || '')
+      .split(/\s+/)
+      .filter((id) => id && id !== slot.id);
+    if (ids.length) control.setAttribute('aria-describedby', ids.join(' '));
+    else control.removeAttribute('aria-describedby');
+  };
+
+  const validateField = (control) => {
+    if (!control.willValidate) return true;
+    const ok = control.validity.valid;
+    const slot = slotFor(control);
+    const isHint = slot?.classList.contains('ui-hint');
+    if (ok) {
+      control.removeAttribute('aria-invalid');
+      if (slot) {
+        if (isHint) {
+          // Restore the snapshotted help text (or clear if there was none); a
+          // help-bearing hint stays linked via aria-describedby (it describes
+          // the field in the valid state too).
+          slot.textContent = hintHelp.get(slot) ?? '';
+          slot.classList.remove('ui-hint--error');
+        } else {
+          // Dedicated error node: clear it and drop the now-stale describedby
+          // so AT doesn't announce an empty error association.
+          slot.textContent = '';
+          unlink(control, slot);
+        }
+      }
+    } else {
+      control.setAttribute('aria-invalid', 'true');
+      if (slot) {
+        if (isHint && !hintHelp.has(slot)) hintHelp.set(slot, slot.textContent);
+        slot.textContent = control.validationMessage;
+        if (isHint) slot.classList.add('ui-hint--error');
+        link(control, slot);
+      }
+    }
+    return ok;
+  };
+
+  const controlsOf = (form) =>
+    [...form.elements].filter(
+      (el) => el.willValidate && el.type !== 'submit' && el.type !== 'button',
+    );
+
+  const refreshSummary = (form, invalid) => {
+    const summary = form.querySelector('[data-bronto-error-summary]');
+    if (!summary) return;
+    if (!invalid.length) {
+      summary.hidden = true;
+      summary.replaceChildren();
+      return;
+    }
+    const title = document.createElement('p');
+    title.className = 'ui-error-summary__title';
+    title.textContent = 'There is a problem';
+    const list = document.createElement('ul');
+    list.className = 'ui-error-summary__list';
+    for (const c of invalid) {
+      const id = ensureId(c, 'bronto-field');
+      const li = document.createElement('li');
+      const a = document.createElement('a');
+      a.href = `#${id}`;
+      a.textContent = c.validationMessage;
+      a.addEventListener('click', (e) => {
+        e.preventDefault();
+        c.focus();
+      });
+      li.appendChild(a);
+      list.appendChild(li);
+    }
+    summary.replaceChildren(title, list);
+    summary.setAttribute('role', 'alert');
+    summary.tabIndex = -1;
+    summary.hidden = false;
+  };
+
+  const onSubmit = (e) => {
+    const form = e.target.closest?.('[data-bronto-validate]');
+    if (!form) return;
+    form.noValidate = true;
+    const invalid = controlsOf(form).filter((c) => !validateField(c));
+    refreshSummary(form, invalid);
+    if (invalid.length) {
+      e.preventDefault();
+      const summary = form.querySelector('[data-bronto-error-summary]');
+      (summary && !summary.hidden ? summary : invalid[0]).focus();
+    }
+  };
+
+  const onBlur = (e) => {
+    const control = e.target;
+    if (!control.willValidate) return;
+    const form = control.closest?.('[data-bronto-validate]');
+    if (!form) return;
+    form.noValidate = true;
+    validateField(control);
+    const summary = form.querySelector('[data-bronto-error-summary]');
+    if (summary && !summary.hidden)
+      refreshSummary(
+        form,
+        controlsOf(form).filter((c) => !c.validity.valid),
+      );
+  };
+
+  return bindOnce(host, 'formValidation', () => {
+    // Suppress native bubbles UP FRONT for forms present at init. The
+    // in-handler `noValidate = true` only fires after the first
+    // submit/blur, so the very first invalid real-browser submit would
+    // otherwise show the native UA bubble instead of the Bronto
+    // summary — contradicting the documented contract. (Forms added
+    // after init are still covered by the in-handler set.)
+    const forms = collectHosts(host, '[data-bronto-validate]');
+    const priorNoValidate = new Map();
+    for (const f of forms) {
+      priorNoValidate.set(f, f.noValidate);
+      f.noValidate = true;
+    }
+    host.addEventListener('submit', onSubmit, true);
+    host.addEventListener('focusout', onBlur);
+    return () => {
+      host.removeEventListener('submit', onSubmit, true);
+      host.removeEventListener('focusout', onBlur);
+      for (const [f, v] of priorNoValidate) f.noValidate = v;
+    };
+  });
+}

package/behaviors/glyph.js

@@ -0,0 +1,108 @@
+import { hasDom, resolveHost, noop, collectHosts } from './internal.js';
+import { GLYPH_SIZE, glyphCells } from '../glyphs/glyphs.js';
+
+function restoreAttr(el, name, prev) {
+  if (prev === null) el.removeAttribute(name);
+  else el.setAttribute(name, prev);
+}
+
+/**
+ * Expand `[data-bronto-glyph="name"]` placeholders into a `.ui-dotmatrix`
+ * grid of GLYPH_SIZE² cells — the DOM counterpart to renderGlyph() from
+ * `@ponchia/ui/glyphs`, for when you'd rather drop a placeholder than inline
+ * the markup. Decorative by default (`aria-hidden`); add
+ * `data-bronto-glyph-label` to expose it as `role="img"`. An unknown glyph
+ * name is left untouched. Idempotent (skips an already-expanded host); the
+ * returned cleanup removes the cells and restores the original attributes.
+ */
+export function initDotGlyph({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const els = collectHosts(host, '[data-bronto-glyph]');
+  const cleanups = [];
+
+  for (const el of els) {
+    // Scope to DIRECT-child cells (the ones we append) — so a placeholder that
+    // legitimately nests its own .ui-dotmatrix is neither mis-read as already
+    // expanded here nor have its inner cells removed by cleanup below.
+    if (el.querySelector(':scope > .ui-dotmatrix__cell')) continue; // already expanded
+    const cells = glyphCells(el.getAttribute('data-bronto-glyph'));
+    if (!cells.length) continue; // unknown glyph — leave the placeholder as-is
+
+    const label = el.getAttribute('data-bronto-glyph-label');
+    // `data-bronto-glyph-solid` → square, gapless pixel glyph (legible small),
+    // the DOM counterpart to renderGlyph's `solid` option. Implies glyph-only.
+    const solid = el.hasAttribute('data-bronto-glyph-solid');
+    // `data-bronto-glyph-anim="reveal|pulse"` → decorative animation (the DOM
+    // counterpart to renderGlyph's `anim`; reduced-motion-safe via CSS).
+    const animAttr = el.getAttribute('data-bronto-glyph-anim');
+    const animClass =
+      animAttr === 'reveal'
+        ? 'ui-dotmatrix--reveal'
+        : animAttr === 'pulse'
+          ? 'ui-dotmatrix--pulse'
+          : null;
+    const hadAnimClass = animClass ? el.classList.contains(animClass) : false;
+    const hadMatrix = el.classList.contains('ui-dotmatrix');
+    const hadCols = el.style.getPropertyValue('--dotmatrix-cols');
+    const hadRadius = el.style.getPropertyValue('--dotmatrix-dot-radius');
+    const hadGap = el.style.getPropertyValue('--dotmatrix-gap');
+    const hadAriaHidden = el.getAttribute('aria-hidden');
+    const hadRole = el.getAttribute('role');
+    const hadAriaLabel = el.getAttribute('aria-label');
+
+    el.classList.add('ui-dotmatrix');
+    if (animClass) el.classList.add(animClass);
+    el.style.setProperty('--dotmatrix-cols', String(GLYPH_SIZE));
+    if (solid) {
+      el.style.setProperty('--dotmatrix-dot-radius', '0');
+      el.style.setProperty('--dotmatrix-gap', '0');
+    }
+    if (label) {
+      el.setAttribute('role', 'img');
+      el.setAttribute('aria-label', label);
+      el.removeAttribute('aria-hidden'); // a labelled img must not also be hidden
+    } else {
+      el.setAttribute('aria-hidden', 'true');
+    }
+
+    const frag = document.createDocumentFragment();
+    cells.forEach((c, i) => {
+      const span = document.createElement('span');
+      span.className = !c.on
+        ? 'ui-dotmatrix__cell'
+        : c.tone === 'hot'
+          ? 'ui-dotmatrix__cell ui-dotmatrix__cell--hot'
+          : c.tone === 'accent'
+            ? 'ui-dotmatrix__cell ui-dotmatrix__cell--accent'
+            : 'ui-dotmatrix__cell';
+      if (!c.on && solid) span.style.background = 'transparent'; // glyph-only
+      if (animAttr === 'reveal') span.style.setProperty('--i', String(i)); // scan stagger
+      frag.appendChild(span);
+    });
+    el.appendChild(frag);
+
+    cleanups.push(() => {
+      el.querySelectorAll(':scope > .ui-dotmatrix__cell').forEach((n) => n.remove());
+      if (!hadMatrix) el.classList.remove('ui-dotmatrix');
+      if (animClass && !hadAnimClass) el.classList.remove(animClass);
+      if (solid) {
+        if (hadRadius) el.style.setProperty('--dotmatrix-dot-radius', hadRadius);
+        else el.style.removeProperty('--dotmatrix-dot-radius');
+        if (hadGap) el.style.setProperty('--dotmatrix-gap', hadGap);
+        else el.style.removeProperty('--dotmatrix-gap');
+      }
+      if (hadCols) el.style.setProperty('--dotmatrix-cols', hadCols);
+      else el.style.removeProperty('--dotmatrix-cols');
+      restoreAttr(el, 'aria-hidden', hadAriaHidden);
+      restoreAttr(el, 'role', hadRole);
+      restoreAttr(el, 'aria-label', hadAriaLabel);
+      // Don't leave behind empty class=""/style="" we ourselves created.
+      if (el.getAttribute('class') === '') el.removeAttribute('class');
+      if (el.getAttribute('style') === '') el.removeAttribute('style');
+    });
+  }
+
+  return () => cleanups.forEach((fn) => fn());
+}

package/behaviors/index.d.ts

@@ -156,3 +156,82 @@ export declare function toast(message: string, opts?: ToastOpts): Cleanup;
  * attributes.
  */
 export declare function initDotGlyph(opts?: DelegateOpts): Cleanup;
+
+/** `bronto:legend:toggle` CustomEvent detail. `series` is the entry's
+ *  `data-series`, or its 0-based index when unset. `active` is the new state
+ *  (`true` ⇒ series shown). */
+export interface LegendToggleDetail {
+  series: string | number;
+  active: boolean;
+}
+
+/**
+ * Wire `[data-bronto-legend]` interactive legends. Each `.ui-legend__item` is a
+ * `<button aria-pressed>`; activating it flips `aria-pressed`, toggles
+ * `.is-inactive`, and dispatches `bronto:legend:toggle`
+ * ({@link LegendToggleDetail}) on the legend. Bronto owns the control + its
+ * state only — the host hides its own series and owns any `aria-live`
+ * announcement (`aria-pressed="true"` ⇒ series shown). SSR-safe, idempotent per
+ * host. Returns a cleanup function.
+ */
+export declare function initLegend(opts?: DelegateOpts): Cleanup;
+
+/**
+ * Draw + keep leader lines in sync. Each `[data-bronto-connector]` is a
+ * `.ui-connector` SVG overlaying a positioned container; `data-from`/`data-to`
+ * are the ids of the elements to connect (with optional `data-shape`,
+ * `data-from-side`/`data-to-side`, `data-end`). Computes geometry via the
+ * `@ponchia/ui/connectors` helpers and redraws on resize/scroll. Bronto owns no
+ * layout. SSR-safe, idempotent per host; returns a cleanup that disconnects
+ * observers/listeners. Re-run after adding/removing connectors.
+ */
+export declare function initConnectors(opts?: DelegateOpts): Cleanup;
+
+/**
+ * Position a spotlight cutout over a target. Each `[data-bronto-spotlight]` is a
+ * `.ui-spotlight` overlay; `data-target` is the id of the element to highlight.
+ * Sets `--spot-x/y/w/h` and re-places on resize/scroll and when `data-target`
+ * changes. NOT a tour engine — the host owns step order/advancing/visibility.
+ * SSR-safe, idempotent per host; returns a cleanup function.
+ */
+export declare function initSpotlight(opts?: DelegateOpts): Cleanup;
+
+/** `bronto:crosshair:move` CustomEvent detail — pointer position over the plot
+ *  in pixels and as 0..1 fractions. Bronto reports where; mapping to data is
+ *  the host's. */
+export interface CrosshairMoveDetail {
+  x: number;
+  y: number;
+  fx: number;
+  fy: number;
+}
+
+/**
+ * Track the pointer over `[data-bronto-crosshair]` plots and drive a contained
+ * `.ui-crosshair` overlay: sets `--crosshair-x/y` (px), marks `.is-active`, and
+ * dispatches `bronto:crosshair:move` ({@link CrosshairMoveDetail}) /
+ * `bronto:crosshair:leave`. Reports the pointer position only — it does not find
+ * the nearest datum or map pixels to data. SSR-safe, idempotent per plot;
+ * returns a cleanup function.
+ */
+export declare function initCrosshair(opts?: DelegateOpts): Cleanup;
+
+/** `bronto:command:select` CustomEvent detail — the chosen command's value and
+ *  visible label. The host executes it; Bronto only filters and navigates. */
+export interface CommandSelectDetail {
+  value: string;
+  label: string;
+}
+
+/**
+ * Filter + keyboard-navigate a DOM-authored command list inside
+ * `[data-bronto-command]` (the `.ui-command` shell). 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. Emits
+ * `bronto:command:select` ({@link CommandSelectDetail}) on choose and
+ * `bronto:command:close` on Escape; the host owns the action registry, routing,
+ * and execution. No global Cmd/Ctrl+K. SSR-safe, idempotent per instance;
+ * returns a cleanup function.
+ */
+export declare function initCommand(opts?: DelegateOpts): Cleanup;