@adia-ai/web-components 0.4.5 → 0.4.7

package/components/toolbar/toolbar.js

@@ -1,384 +1,18 @@
 /**
- * <toolbar-ui>
- *   <toolbar-group-ui>
- *     <button-ui icon="text-bold" variant="ghost" size="sm"></button-ui>
- *     <button-ui icon="text-italic" variant="ghost" size="sm"></button-ui>
- *   </toolbar-group-ui>
- *   <divider-ui vertical></divider-ui>
- *   <toolbar-group-ui>
- *     <button-ui icon="text-align-left" variant="ghost" size="sm"></button-ui>
- *   </toolbar-group-ui>
- * </toolbar-ui>
+ * `<toolbar-ui>` — auto-registers the tag on import.
  *
- * Horizontal action bar with automatic overflow:
- *   • ResizeObserver measures available width.
- *   • Items that don't fit are moved (from the end) into a spillover popover.
- *   • `toolbar-group-ui` wraps siblings so they move as an atomic unit
- *     (no half-group split between visible bar and overflow menu).
- *   • Trailing dividers are trimmed. Dividers are not moved to the menu.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Platform: Popover API (top-layer) + CSS Anchor Positioning via @core/anchor.js.
- */
-
-import { UIElement } from '../../core/element.js';
-import { anchorPopover } from '../../core/anchor.js';
-
-const SPILLOVER_ATTR = 'data-toolbar-spillover';
-const SPILLOVER_MENU_ATTR = 'data-toolbar-spillover-menu';
-
-/* Headroom kept free at the right edge before an item starts spilling over.
-   A non-zero value makes overflow more responsive — items move to the menu
-   while there's still breathing room, instead of waiting until they actually
-   touch the toolbar's right edge. */
-const OVERFLOW_BUFFER = 8;
-
-class UIToolbar extends UIElement {
-  static properties = {
-    gap:      { type: String,  default: 'sm', reflect: true },
-    align:    { type: String,  default: 'start', reflect: true },
-    overflow: { type: String,  default: 'menu', reflect: true },
-  };
-
-  static template = () => null;
-
-  #ro = null;
-  #mo = null;
-  #trigger = null;
-  #popover = null;
-  #spilloverCleanup = null;
-  #measuring = false;
-  #reflowQueued = false;
-  #reflowRaf = null;
-  #rafId = null;
-
-  connected() {
-    this.setAttribute('role', 'toolbar');
-    this.#ensureSpillover();
-    this.#ro = new ResizeObserver(() => this.#queueReflow());
-    this.#ro.observe(this);
-    this.#mo = new MutationObserver(() => {
-      if (this.#measuring) return;
-      this.#queueReflow();
-    });
-    this.#moObserve();
-    this.#queueReflow();
-  }
-
-  disconnected() {
-    if (this.#reflowRaf != null) {
-      cancelAnimationFrame(this.#reflowRaf);
-      this.#reflowRaf = null;
-    }
-    this.#reflowQueued = false;
-    this.#ro?.disconnect();
-    this.#mo?.disconnect();
-    this.#closeSpillover();
-    this.#ro = null;
-    this.#mo = null;
-    this.#trigger = null;
-    this.#popover = null;
-  }
-
-  // ── Spillover infrastructure ──
-
-  #ensureSpillover() {
-    if (this.#trigger) return;
-
-    const trigger = document.createElement('button-ui');
-    trigger.setAttribute('icon', 'dots-three');
-    trigger.setAttribute('variant', 'ghost');
-    trigger.setAttribute('size', 'sm');
-    trigger.setAttribute(SPILLOVER_ATTR, '');
-    trigger.setAttribute('aria-label', 'More actions');
-    trigger.setAttribute('aria-haspopup', 'menu');
-    trigger.hidden = true;
-
-    const popover = document.createElement('div');
-    popover.setAttribute(SPILLOVER_MENU_ATTR, '');
-    popover.setAttribute('popover', 'manual');
-    popover.setAttribute('role', 'menu');
-
-    trigger.addEventListener('click', this.#onTriggerClick);
-    popover.addEventListener('click', this.#onMenuClick);
-    popover.addEventListener('toggle', this.#onToggle);
-
-    this.appendChild(trigger);
-    this.appendChild(popover);
-
-    this.#trigger = trigger;
-    this.#popover = popover;
-  }
-
-  #openSpillover() {
-    const menu = this.#popover;
-    if (!menu || menu.matches(':popover-open')) return;
-    menu.showPopover?.();
-    this.#spilloverCleanup?.();
-    this.#spilloverCleanup = anchorPopover(this.#trigger, menu, {
-      placement: 'bottom-end',
-      gap: 4,
-    });
-    this.#rafId = requestAnimationFrame(() => {
-      this.#rafId = null;
-      document.addEventListener('pointerdown', this.#onOutside, true);
-      document.addEventListener('keydown', this.#onKey, true);
-    });
-  }
-
-  #closeSpillover() {
-    this.#spilloverCleanup?.();
-    this.#spilloverCleanup = null;
-    if (this.#popover?.matches(':popover-open')) this.#popover.hidePopover?.();
-    if (this.#rafId != null) {
-      cancelAnimationFrame(this.#rafId);
-      this.#rafId = null;
-    }
-    document.removeEventListener('pointerdown', this.#onOutside, true);
-    document.removeEventListener('keydown', this.#onKey, true);
-  }
-
-  #onTriggerClick = (e) => {
-    e.stopPropagation();
-    if (this.#popover?.matches(':popover-open')) this.#closeSpillover();
-    else this.#openSpillover();
-  };
-
-  #onMenuClick = (e) => {
-    // Only auto-close after a "terminal" action (button-ui press). Composite
-    // controls inside the menu — select-ui, segmented-ui, etc. — manage their
-    // own state; clicking them must not dismiss the spillover.
-    const btn = e.target.closest('button-ui');
-    if (!btn) return;
-    if (btn.matches(`[${SPILLOVER_ATTR}]`)) return;
-    queueMicrotask(() => this.#closeSpillover());
-  };
-
-  #onOutside = (e) => {
-    if (this.#trigger?.contains(e.target)) return;
-    if (this.#popover?.contains(e.target)) return;
-    // Ignore clicks inside any other open popover (e.g., a select-ui dropdown
-    // launched from a select inside our spillover, which lives in the top
-    // layer outside the spillover popover's DOM subtree).
-    const path = e.composedPath?.() || [];
-    for (const node of path) {
-      if (node === document) break;
-      if (node?.nodeType === 1 && node.hasAttribute?.('popover')) return;
-    }
-    this.#closeSpillover();
-  };
-
-  #onKey = (e) => {
-    if (e.key === 'Escape') {
-      e.stopPropagation();
-      this.#closeSpillover();
-      this.#trigger?.focus?.({ preventScroll: true });
-    }
-  };
-
-  #onToggle = (e) => {
-    if (e.newState === 'closed') {
-      // Keep listeners cleaned up if closed externally.
-      this.#spilloverCleanup?.();
-      this.#spilloverCleanup = null;
-      if (this.#rafId != null) {
-        cancelAnimationFrame(this.#rafId);
-        this.#rafId = null;
-      }
-      document.removeEventListener('pointerdown', this.#onOutside, true);
-      document.removeEventListener('keydown', this.#onKey, true);
-    }
-  };
-
-  // ── Reflow / overflow ──
-
-  #queueReflow() {
-    if (this.#reflowQueued) return;
-    this.#reflowQueued = true;
-    this.#reflowRaf = requestAnimationFrame(() => {
-      this.#reflowRaf = null;
-      this.#reflowQueued = false;
-      if (!this.isConnected) return;
-      this.#reflow();
-    });
-  }
-
-  #moObserve() {
-    this.#mo?.observe(this, { childList: true });
-  }
-
-  #moPause() {
-    // MutationObserver delivers records asynchronously, so the #measuring
-    // flag alone doesn't stop self-triggered reflows — by the time the
-    // observer's microtask fires, the flag has already been cleared. We must
-    // physically disconnect during reflow, flush any pending records the
-    // observer had already queued, then reconnect on the next microtask.
-    if (!this.#mo) return;
-    this.#mo.disconnect();
-    this.#mo.takeRecords();
-  }
-
-  #reflow() {
-    if (!this.isConnected) return;
-    const trigger = this.#trigger;
-    const popover = this.#popover;
-    if (!trigger || !popover) return;
-
-    this.#measuring = true;
-    this.#moPause();
-    try {
-      // 1. Move everything from the popover back into the toolbar (before the trigger).
-      //    Strip injected spillover labels so the buttons measure as icon-only again.
-      while (popover.firstChild) {
-        stripSpilloverLabels(popover.firstChild);
-        this.insertBefore(popover.firstChild, trigger);
-      }
-
-      // Stamp the original DOM order on each item the first time we see it.
-      // (Items moved to the popover and back must restore their original slot —
-      // otherwise dividers end up clumped next to dividers and groups split.)
-      let idx = 0;
-      for (const el of this.children) {
-        if (el === trigger || el === popover) continue;
-        if (el.dataset.toolbarOrder == null) el.dataset.toolbarOrder = String(idx);
-        idx += 1;
-      }
-
-      // Sort items back into their original order before measurement.
-      const ordered = Array.from(this.children)
-        .filter(c => c !== trigger && c !== popover)
-        .sort((a, b) => Number(a.dataset.toolbarOrder) - Number(b.dataset.toolbarOrder));
-      for (const el of ordered) this.insertBefore(el, trigger);
-
-      const all = ordered;
-      for (const el of all) el.hidden = false;
-      trigger.hidden = true;
-
-      // 2. Measure.
-      const style = getComputedStyle(this);
-      const padL = parseFloat(style.paddingLeft) || 0;
-      const padR = parseFloat(style.paddingRight) || 0;
-      const gap = parseFloat(style.columnGap || style.gap) || 0;
-      const available = this.clientWidth - padL - padR;
-
-      // Include horizontal margins — components like divider-ui add their own
-      // margin-inline which getBoundingClientRect() does NOT include but flex
-      // layout DOES count toward the row width.
-      const widths = all.map(el => outerWidth(el));
-      const total = widths.reduce((a, w) => a + w, 0) + Math.max(0, all.length - 1) * gap;
-
-      // Reserve OVERFLOW_BUFFER worth of headroom — start spilling sooner
-      // rather than waiting until items literally touch the right edge.
-      const fitsCleanly = total <= available - OVERFLOW_BUFFER;
-
-      if (this.overflow === 'none' || fitsCleanly) {
-        return;
-      }
-
-      // 3. Need to move some items out. Reserve trigger width + buffer.
-      trigger.hidden = false;
-      const triggerW = outerWidth(trigger);
-
-      let fitIdx = all.length;
-      let running = total;
-      // Drop items from the end (and subtract their width + preceding gap)
-      // until visible items + trigger fit with buffer headroom.
-      while (fitIdx > 0) {
-        const wWithTrigger = running + gap + triggerW;
-        if (wWithTrigger <= available - OVERFLOW_BUFFER) break;
-        fitIdx -= 1;
-        running -= widths[fitIdx];
-        if (fitIdx > 0) running -= gap;
-      }
-
-      // 4. Trim trailing dividers from visible section.
-      while (fitIdx > 0 && isDivider(all[fitIdx - 1])) fitIdx -= 1;
-
-      // 5. Move overflowed items into popover (skip dividers entirely).
-      const toMove = all.slice(fitIdx);
-      for (const el of toMove) {
-        if (isDivider(el)) {
-          el.hidden = true;
-          continue;
-        }
-        // Inject derived labels on icon-only buttons so the spillover row
-        // shows "Bold" instead of just an unlabeled icon.
-        applySpilloverLabels(el);
-        popover.appendChild(el);
-      }
-
-      // 6. If nothing actually ended up in the popover (e.g. only a divider overflowed),
-      //    hide the trigger again.
-      if (!popover.firstElementChild) {
-        trigger.hidden = true;
-      }
-    } finally {
-      this.#measuring = false;
-      // Drop any mutation records our reflow produced before reconnecting,
-      // otherwise they'd fire as soon as we observe() again and loop forever.
-      queueMicrotask(() => {
-        this.#mo?.takeRecords();
-        this.#moObserve();
-      });
-    }
-  }
-}
-customElements.define('toolbar-ui', UIToolbar);
-
-/**
- * <toolbar-group-ui> — atomic group within a toolbar.
- * Its children are displayed together with matching gap and, during overflow,
- * are moved to the spillover menu as a single unit.
+ *   import { UIToolbar, UIToolbarGroup } from '@adia-ai/web-components/components/toolbar/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
-class UIToolbarGroup extends UIElement {
-  static template = () => null;
-  connected() {
-    this.setAttribute('role', 'group');
-  }
-}
-customElements.define('toolbar-group-ui', UIToolbarGroup);
-
-function isDivider(el) {
-  return el?.tagName && el.tagName.toLowerCase() === 'divider-ui';
-}
-
-const SPILLOVER_LABEL_FLAG = 'data-toolbar-spillover-label';
-
-function humanizeIcon(name) {
-  if (!name) return '';
-  return name
-    .split('-')
-    .filter(Boolean)
-    .map(w => w[0].toUpperCase() + w.slice(1))
-    .join(' ');
-}
-
-function applySpilloverLabels(root) {
-  const buttons = root.matches?.('button-ui') ? [root] : Array.from(root.querySelectorAll?.('button-ui') || []);
-  for (const btn of buttons) {
-    if (btn.hasAttribute(SPILLOVER_LABEL_FLAG)) continue;
-    if (btn.getAttribute('text')) continue; // user-provided text, leave alone
-    const label = btn.getAttribute('aria-label') || humanizeIcon(btn.getAttribute('icon'));
-    if (!label) continue;
-    btn.setAttribute(SPILLOVER_LABEL_FLAG, '');
-    btn.setAttribute('text', label);
-  }
-}
 
-function stripSpilloverLabels(root) {
-  const buttons = root.matches?.('button-ui') ? [root] : Array.from(root.querySelectorAll?.('button-ui') || []);
-  for (const btn of buttons) {
-    if (!btn.hasAttribute(SPILLOVER_LABEL_FLAG)) continue;
-    btn.removeAttribute(SPILLOVER_LABEL_FLAG);
-    btn.removeAttribute('text');
-  }
-}
+import { defineIfFree } from '../../core/register.js';
+import { UIToolbar, UIToolbarGroup } from './class.js';
 
-function outerWidth(el) {
-  const r = el.getBoundingClientRect();
-  const cs = getComputedStyle(el);
-  const ml = parseFloat(cs.marginLeft) || 0;
-  const mr = parseFloat(cs.marginRight) || 0;
-  return r.width + ml + mr;
-}
+defineIfFree('toolbar-ui', UIToolbar);
+defineIfFree('toolbar-group-ui', UIToolbarGroup);
 
 export { UIToolbar, UIToolbarGroup };

package/components/tooltip/class.js

@@ -0,0 +1,299 @@
+/**
+ * Non-side-effect class export for `<tooltip-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/tooltip`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <tooltip-ui text="Helpful tip" placement="top">
+ *   <button-ui text="Hover me"></button-ui>
+ * </tooltip-ui>
+ *
+ * <!-- Pointer-follow mode: used by chart-ui to show a richer card that
+ *      tracks the cursor across datums. -->
+ * <tooltip-ui follows="pointer" for="my-chart" indicator="dot"></tooltip-ui>
+ *
+ * Tooltip popup. Two modes:
+ *
+ * 1. `follows="trigger"` (default) — wraps children and shows on hover/focus,
+ *    anchored to the trigger via @core/anchor.js + Popover API.
+ * 2. `follows="pointer"` — subscribes to `chart-hover`/`chart-leave` events
+ *    from `[for]`, renders a card with label + indicator + value rows, and
+ *    positions at the pointer coordinates. Used by chart-ui / heatmap-ui.
+ *
+ * No click interaction — hover/focus only.
+ */
+
+import { UIElement } from '../../core/element.js';
+import { anchorPopover } from '../../core/anchor.js';
+
+export class UITooltip extends UIElement {
+  static properties = {
+    text:      { type: String,  default: '',         reflect: true },
+    placement: { type: String,  default: 'top',      reflect: true },
+    delay:     { type: Number,  default: 400,        reflect: true },
+    follows:   { type: String,  default: 'trigger',  reflect: true },
+    for:       { type: String,  default: '',         reflect: true },
+    indicator: { type: String,  default: 'none',     reflect: true },
+  };
+
+  static template = () => null;
+
+  #popover = null;
+  #timer = null;
+  #cleanup = null;
+
+  /* Pointer-follow mode state */
+  #target = null;
+  #lastDetail = null;
+
+  connected() {
+    if (this.follows === 'pointer') {
+      this.#attachPointerFollow();
+    } else {
+      this.addEventListener('mouseenter', this.#onEnter);
+      this.addEventListener('focusin', this.#onEnter);
+      this.addEventListener('mouseleave', this.#onLeave);
+      this.addEventListener('focusout', this.#onLeave);
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('mouseenter', this.#onEnter);
+    this.removeEventListener('focusin', this.#onEnter);
+    this.removeEventListener('mouseleave', this.#onLeave);
+    this.removeEventListener('focusout', this.#onLeave);
+    this.#detachPointerFollow();
+    this.#hide();
+  }
+
+  render() {
+    // Trigger mode: update popover text if already showing
+    if (this.#popover && this.follows !== 'pointer') {
+      this.#popover.textContent = this.text;
+    }
+    // Pointer mode: re-paint content with current indicator if visible
+    if (this.#popover && this.follows === 'pointer' && this.#lastDetail) {
+      this.#paintPointerContent(this.#lastDetail);
+    }
+  }
+
+  #onEnter = () => {
+    if (!this.text) return;
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => this.#show(), this.delay);
+  };
+
+  #onLeave = () => {
+    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null; }
+    this.#hide();
+  };
+
+  #show() {
+    if (this.#popover) return;
+
+    const el = document.createElement('div');
+    const id = `tooltip-${Date.now()}`;
+    el.id = id;
+    el.setAttribute('popover', 'manual');
+    el.setAttribute('role', 'tooltip');
+    el.classList.add('tooltip-popup');
+    el.textContent = this.text;
+    document.body.appendChild(el);
+
+    // Link trigger to tooltip for screen readers
+    this.setAttribute('aria-describedby', id);
+
+    try { el.showPopover(); } catch (_) { /* popover not supported */ }
+
+    this.#popover = el;
+    this.#cleanup = anchorPopover(this, el, { placement: this.placement, gap: 6 });
+  }
+
+  #hide() {
+    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null; }
+    if (!this.#popover) return;
+
+    this.removeAttribute('aria-describedby');
+    this.#cleanup?.();
+    this.#cleanup = null;
+
+    try { this.#popover.hidePopover(); } catch (_) { /* popover not supported */ }
+    this.#popover.remove();
+    this.#popover = null;
+    this.#lastDetail = null;
+  }
+
+  /* ── Pointer-follow mode (chart/heatmap integration) ─────────────── */
+
+  #attachPointerFollow() {
+    this.#detachPointerFollow();
+    if (!this.for) return;
+
+    const root = this.getRootNode();
+    this.#target = (root && root.getElementById) ? root.getElementById(this.for) : document.getElementById(this.for);
+    if (!this.#target) {
+      // Warn once per (element, id) pair
+      if (!UITooltip._warnedMissing) UITooltip._warnedMissing = new WeakSet();
+      if (!UITooltip._warnedMissing.has(this)) {
+        console.warn(`[tooltip-ui] follows="pointer" [for="${this.for}"] did not resolve to an element.`);
+        UITooltip._warnedMissing.add(this);
+      }
+      return;
+    }
+
+    this.#target.addEventListener('chart-hover', this.#onChartHover);
+    this.#target.addEventListener('chart-leave', this.#onChartLeave);
+  }
+
+  #detachPointerFollow() {
+    if (this.#target) {
+      this.#target.removeEventListener('chart-hover', this.#onChartHover);
+      this.#target.removeEventListener('chart-leave', this.#onChartLeave);
+    }
+    this.#target = null;
+  }
+
+  #onChartLeave = () => this.#hide();
+
+  #onChartHover = (event) => {
+    const detail = event.detail;
+    if (!detail) return;
+    this.#lastDetail = detail;
+
+    if (!this.#popover) {
+      this.#popover = this.#createPopover();
+      this.#copySeriesColorsFromTarget();
+      try { this.#popover.showPopover(); } catch (_) { /* unsupported */ }
+    }
+
+    this.#paintPointerContent(detail);
+    this.#positionAtPointer(detail.pointerX, detail.pointerY);
+  };
+
+  #createPopover() {
+    const el = document.createElement('div');
+    el.setAttribute('popover', 'manual');
+    el.setAttribute('role', 'tooltip');
+    el.setAttribute('data-follows', 'pointer');
+    el.setAttribute('data-indicator', this.indicator || 'none');
+    el.classList.add('tooltip-popup');
+    document.body.appendChild(el);
+    return el;
+  }
+
+  /* Copy per-series `--color-{key}` custom properties from the target chart
+     to the popover so inner rows can reference them. The popover lives in
+     the top layer and does NOT inherit custom properties from the host,
+     so we bridge them explicitly at show time. */
+  #copySeriesColorsFromTarget() {
+    if (!this.#target || !this.#popover) return;
+    /* Prefer inline style on the target (what chart-ui's #injectSeriesColors
+       writes). Fall back to computed style resolution for any --color-* vars
+       the author set on ancestors. */
+    const inline = this.#target.style;
+    for (let i = 0; i < inline.length; i++) {
+      const name = inline[i];
+      if (name.startsWith('--color-')) {
+        this.#popover.style.setProperty(name, inline.getPropertyValue(name));
+      }
+    }
+    /* Also copy the 10 categorical palette slots so the fallback
+       `var(--color-{key}, var(--chart-{slot}))` resolves. */
+    const cs = getComputedStyle(this.#target);
+    for (let i = 0; i < 10; i++) {
+      const v = cs.getPropertyValue(`--chart-${i}`).trim();
+      if (v) this.#popover.style.setProperty(`--chart-${i}`, v);
+    }
+  }
+
+  #paintPointerContent(detail) {
+    if (!this.#popover) return;
+    const { label, value, pct, series, slot, payload } = detail;
+    const indicator = this.indicator || 'none';
+
+    /* OD-CHART-05 — when `detail.payload` is an array (multi-series hover),
+       render one row per payload entry with the hovered series marked.
+       Fall back to the top-level single-datum shape for back-compat with
+       charts that don't emit a payload (categorical, single-series). */
+    const rows = Array.isArray(payload) && payload.length > 0
+      ? payload
+      : [{ series, label, value, pct, slot, hovered: true }];
+
+    const parts = [];
+
+    /* Label at the top — shared across all rows when a payload is
+       present (all series are at the same X column). */
+    if (label != null) {
+      parts.push(`<span data-tip-role="label">${this.#esc(String(label))}</span>`);
+    }
+
+    for (const row of rows) {
+      const rSeries = row.series ?? null;
+      const rValue  = row.value;
+      const rPct    = row.pct;
+      const rSlot   = row.slot != null ? row.slot : 0;
+      const indicatorColor = rSeries
+        ? `var(--color-${rSeries}, var(--chart-${rSlot}))`
+        : `var(--chart-${rSlot})`;
+
+      if (rValue == null && rPct == null) continue;
+
+      const valueStr = rValue != null ? this.#esc(String(rValue)) : '';
+      const pctStr = rPct != null ? `<span data-tip-role="pct"> (${rPct}%)</span>` : '';
+      const indEl = indicator !== 'none'
+        ? `<span data-indicator style="--tooltip-indicator-color: ${indicatorColor}"></span>`
+        : '';
+      const nameEl = rSeries
+        ? `<span data-tip-role="name">${this.#esc(rSeries)}</span>`
+        : '';
+      const hoveredAttr = row.hovered ? ' data-hovered' : '';
+
+      parts.push(`<span data-tip-row${hoveredAttr}>${indEl}${nameEl}<span data-tip-role="value">${valueStr}${pctStr}</span></span>`);
+    }
+
+    this.#popover.setAttribute('data-indicator', indicator);
+    this.#popover.setAttribute('aria-live', 'polite');
+    this.#popover.innerHTML = parts.join('');
+  }
+
+  #positionAtPointer(x, y) {
+    if (!this.#popover || x == null || y == null) return;
+    const gap = 12;
+    const edgePad = 8;
+    const popover = this.#popover;
+    popover.style.position = 'fixed';
+    popover.style.left = '0';
+    popover.style.top = '0';
+    /* Force reflow to read offset dimensions now that content changed */
+    const tw = popover.offsetWidth  || 0;
+    const th = popover.offsetHeight || 0;
+    /* Default: centered horizontally above the cursor, gap px clear of
+       the cursor. Clamp horizontally to viewport with edgePad on each
+       side (short tooltips near the viewport edge scoot inward rather
+       than drifting off-screen). Flip vertically when there's not
+       enough room above. */
+    let px = x - tw / 2;
+    let py = y - th - gap;
+    if (px < edgePad)                        px = edgePad;
+    if (px + tw > window.innerWidth - edgePad) px = window.innerWidth - tw - edgePad;
+    if (py < edgePad)                        py = y + gap;
+    popover.style.left = `${px}px`;
+    popover.style.top  = `${py}px`;
+  }
+
+  #esc(s) {
+    return String(s)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+}