@adia-ai/web-components 0.2.3 → 0.2.4

package/traits/anchor-positioning.js

@@ -1,10 +1,48 @@
+/**
+ * anchor-positioning — pin a host element to a named anchor.
+ *
+ * Native path (Chromium 125+, Safari 18.0+):
+ *   - Promotes the host into the top layer via `popover="manual"` +
+ *     `host.showPopover()` so it escapes any `overflow: hidden` ancestor.
+ *   - Names the anchor with `anchor-name: --anchor-{slug}` and points the
+ *     host at it with `position-anchor: --anchor-{slug}`.
+ *   - Lays out via `position-area`; the browser drives reflow on its own,
+ *     no JS scroll/resize loop needed.
+ *
+ * Fallback path (Firefox 129+ today, Safari < 18.0):
+ *   - Plain `position: fixed` + measured top/left from getBoundingClientRect.
+ *   - scroll (capture) + resize listeners drive re-layout.
+ *   - Mirrors the v0 behavior so the public attribute API is unchanged.
+ *
+ * `data-anchor-mode="native"|"fallback"` is reflected on the host so
+ * consumers and DevTools sessions can see which path actually ran.
+ */
+
 import { defineTrait } from './define.js';
 
+/**
+ * Feature-detect both halves of the API we depend on. Chrome 125+ and
+ * Safari 18.0+ pass both; Firefox 129's partial implementation typically
+ * fails the `position-area` half and lands on the fallback. Mirrors the
+ * detection used in core/anchor.js so the trait + the popover helper
+ * agree on which path ran.
+ */
+const supportsNative =
+  typeof CSS !== 'undefined' &&
+  (CSS.supports?.('anchor-name', '--x') ?? false) &&
+  (CSS.supports?.('position-area', 'bottom') ?? false);
+
+let anchorIdCounter = 0;
+
 export const anchorPositioning = defineTrait({
   name: 'anchor-positioning',
   category: 'layout-measurement',
   description: 'Positions relative to an anchor element',
-  attributes: ['data-anchor-positioning-placed', 'data-anchor-placement-actual'],
+  attributes: [
+    'data-anchor-positioning-placed',
+    'data-anchor-placement-actual',
+    'data-anchor-mode',
+  ],
   events: ['anchor-placed'],
   config: ['data-anchor', 'data-anchor-placement', 'data-anchor-gap'],
   setup({ host }) {
@@ -12,57 +50,172 @@ export const anchorPositioning = defineTrait({
     const placement = host.getAttribute('data-anchor-placement') || 'bottom';
     const gap = parseInt(host.getAttribute('data-anchor-gap'), 10) || 0;
 
-    function position() {
-      const anchor = document.querySelector(anchorSel) ||
-        document.getElementById(anchorSel);
-      if (!anchor) return;
-
-      const ar = anchor.getBoundingClientRect();
-      const hr = host.getBoundingClientRect();
-      const vw = window.innerWidth;
-      const vh = window.innerHeight;
-
-      let top, left;
-      let actual = placement;
-
-      if (placement.startsWith('bottom')) {
-        top = ar.bottom + gap;
-        left = ar.left + (ar.width - hr.width) / 2;
-        if (top + hr.height > vh) { top = ar.top - hr.height - gap; actual = 'top'; }
-      } else if (placement.startsWith('top')) {
-        top = ar.top - hr.height - gap;
-        left = ar.left + (ar.width - hr.width) / 2;
-        if (top < 0) { top = ar.bottom + gap; actual = 'bottom'; }
-      } else if (placement.startsWith('left')) {
-        top = ar.top + (ar.height - hr.height) / 2;
-        left = ar.left - hr.width - gap;
-        if (left < 0) { left = ar.right + gap; actual = 'right'; }
-      } else {
-        top = ar.top + (ar.height - hr.height) / 2;
-        left = ar.right + gap;
-        if (left + hr.width > vw) { left = ar.left - hr.width - gap; actual = 'left'; }
-      }
-
-      left = Math.max(0, Math.min(left, vw - hr.width));
-      top = Math.max(0, Math.min(top, vh - hr.height));
-
-      host.style.position = 'fixed';
-      host.style.top = `${top}px`;
-      host.style.left = `${left}px`;
-      host.setAttribute('data-anchor-positioning-placed', '');
-      host.setAttribute('data-anchor-placement-actual', actual);
-      host.dispatchEvent(new CustomEvent('anchor-placed', { bubbles: true, detail: { actual } }));
-    }
+    const anchor = resolveAnchor(anchorSel);
+    if (!anchor) return () => {};
 
-    position();
-    window.addEventListener('scroll', position, true);
-    window.addEventListener('resize', position);
-
-    return () => {
-      window.removeEventListener('scroll', position, true);
-      window.removeEventListener('resize', position);
-      host.removeAttribute('data-anchor-positioning-placed');
-      host.removeAttribute('data-anchor-placement-actual');
-    };
+    return supportsNative
+      ? setupNative({ host, anchor, placement, gap })
+      : setupFallback({ host, anchor, placement, gap });
   },
 });
+
+function resolveAnchor(sel) {
+  if (!sel) return null;
+  try {
+    return document.querySelector(sel) || document.getElementById(sel);
+  } catch (_) {
+    // Bare ids ("anchor-x" without a leading "#") throw on querySelector.
+    return document.getElementById(sel);
+  }
+}
+
+// ── Native path ─────────────────────────────────────────────────────────
+
+function setupNative({ host, anchor, placement, gap }) {
+  const name = `--anchor-${++anchorIdCounter}`;
+  const prevAnchorName = anchor.style.anchorName;
+  const prevPopover = host.getAttribute('popover');
+
+  // Tag the anchor + the host so the layout engine can wire them up.
+  anchor.style.anchorName = name;
+  host.style.position = 'fixed';
+  host.style.positionAnchor = name;
+  host.style.positionArea = placementToPositionArea(placement);
+  host.style.margin = placementToGapMargin(placement, gap);
+  // Clear any v0 fallback-leftover coordinates so they don't fight CSS.
+  host.style.top = '';
+  host.style.left = '';
+  // Let the browser flip across either axis when the requested edge clips.
+  host.style.positionTryFallbacks = 'flip-block, flip-inline, flip-block flip-inline';
+
+  // Promote into the top layer so overflow:hidden ancestors can't clip.
+  if (!prevPopover) host.setAttribute('popover', 'manual');
+  let didShow = false;
+  try {
+    host.showPopover();
+    didShow = true;
+  } catch (_) {
+    // Already-shown / unsupported in the test env — both are non-fatal.
+  }
+
+  host.setAttribute('data-anchor-mode', 'native');
+  host.setAttribute('data-anchor-positioning-placed', '');
+  host.setAttribute('data-anchor-placement-actual', placement);
+  host.dispatchEvent(new CustomEvent('anchor-placed', {
+    bubbles: true,
+    detail: { actual: placement, mode: 'native' },
+  }));
+
+  return () => {
+    anchor.style.anchorName = prevAnchorName;
+    host.style.positionAnchor = '';
+    host.style.positionArea = '';
+    host.style.positionTryFallbacks = '';
+    host.style.margin = '';
+    if (didShow) {
+      try { host.hidePopover(); } catch (_) { /* already-hidden / unsupported */ }
+    }
+    if (!prevPopover) host.removeAttribute('popover');
+    host.removeAttribute('data-anchor-mode');
+    host.removeAttribute('data-anchor-positioning-placed');
+    host.removeAttribute('data-anchor-placement-actual');
+  };
+}
+
+// ── Fallback path ───────────────────────────────────────────────────────
+
+function setupFallback({ host, anchor, placement, gap }) {
+  function position() {
+    const ar = anchor.getBoundingClientRect();
+    const hr = host.getBoundingClientRect();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+
+    let top, left;
+    let actual = placement;
+
+    if (placement.startsWith('bottom')) {
+      top = ar.bottom + gap;
+      left = ar.left + (ar.width - hr.width) / 2;
+      if (top + hr.height > vh) { top = ar.top - hr.height - gap; actual = 'top'; }
+    } else if (placement.startsWith('top')) {
+      top = ar.top - hr.height - gap;
+      left = ar.left + (ar.width - hr.width) / 2;
+      if (top < 0) { top = ar.bottom + gap; actual = 'bottom'; }
+    } else if (placement.startsWith('left')) {
+      top = ar.top + (ar.height - hr.height) / 2;
+      left = ar.left - hr.width - gap;
+      if (left < 0) { left = ar.right + gap; actual = 'right'; }
+    } else {
+      top = ar.top + (ar.height - hr.height) / 2;
+      left = ar.right + gap;
+      if (left + hr.width > vw) { left = ar.left - hr.width - gap; actual = 'left'; }
+    }
+
+    left = Math.max(0, Math.min(left, vw - hr.width));
+    top = Math.max(0, Math.min(top, vh - hr.height));
+
+    host.style.position = 'fixed';
+    host.style.top = `${top}px`;
+    host.style.left = `${left}px`;
+    host.setAttribute('data-anchor-positioning-placed', '');
+    host.setAttribute('data-anchor-placement-actual', actual);
+    host.dispatchEvent(new CustomEvent('anchor-placed', {
+      bubbles: true,
+      detail: { actual, mode: 'fallback' },
+    }));
+  }
+
+  host.setAttribute('data-anchor-mode', 'fallback');
+  position();
+  window.addEventListener('scroll', position, true);
+  window.addEventListener('resize', position);
+
+  return () => {
+    window.removeEventListener('scroll', position, true);
+    window.removeEventListener('resize', position);
+    host.removeAttribute('data-anchor-mode');
+    host.removeAttribute('data-anchor-positioning-placed');
+    host.removeAttribute('data-anchor-placement-actual');
+  };
+}
+
+// ── Placement → CSS helpers ─────────────────────────────────────────────
+
+/**
+ * Map our placement vocabulary (top|bottom|left|right + -start|-end) to
+ * the CSS `position-area` keyword pair that produces equivalent layout.
+ *
+ * The bare cardinals span the cross-axis ("span-all") so the host
+ * centers; the -start / -end variants pin to the named edge.
+ */
+function placementToPositionArea(placement) {
+  switch (placement) {
+    case 'bottom':       return 'bottom span-all';
+    case 'bottom-start': return 'bottom span-right';
+    case 'bottom-end':   return 'bottom span-left';
+    case 'top':          return 'top span-all';
+    case 'top-start':    return 'top span-right';
+    case 'top-end':      return 'top span-left';
+    case 'left':         return 'left span-all';
+    case 'left-start':   return 'left span-bottom';
+    case 'left-end':     return 'left span-top';
+    case 'right':        return 'right span-all';
+    case 'right-start':  return 'right span-bottom';
+    case 'right-end':    return 'right span-top';
+    default:             return 'bottom span-all';
+  }
+}
+
+/**
+ * Apply gap on the main (anchor-adjacent) axis only — the cross-axis
+ * spans the anchor and shouldn't carry margin or alignment will drift.
+ */
+function placementToGapMargin(placement, gap) {
+  if (!gap) return '';
+  if (placement.startsWith('bottom')) return `${gap}px 0 0 0`;
+  if (placement.startsWith('top'))    return `0 0 ${gap}px 0`;
+  if (placement.startsWith('left'))   return `0 ${gap}px 0 0`;
+  if (placement.startsWith('right'))  return `0 0 0 ${gap}px`;
+  return `${gap}px`;
+}

package/traits/anchor-positioning.test.js

@@ -1,11 +1,19 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { anchorPositioning } from './anchor-positioning.js';
-import { mountHost, connectTrait, spyEvent, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './test-helpers.js';
 
+/**
+ * Note on test environment: happy-dom does not implement
+ * `CSS.supports('anchor-name', '--x')` or the Popover API surface that
+ * actually moves an element into the top layer. Tests therefore land on
+ * the fallback path and assert the public contract (attrs, event,
+ * connect/disconnect symmetry) — not specific viewport coordinates.
+ * Real layout is exercised in the live browser demo.
+ */
 describe('anchor-positioning', () => {
   beforeEach(resetDOM);
 
-  it('connect with valid anchor sets placed + actual attributes', () => {
+  it('connect with valid anchor sets placed + actual + mode attributes', () => {
     const anchor = document.createElement('div');
     anchor.id = 'anchor-x';
     document.body.appendChild(anchor);
@@ -16,10 +24,14 @@ describe('anchor-positioning', () => {
     connectTrait(anchorPositioning, host);
     expect(host.hasAttribute('data-anchor-positioning-placed')).toBe(true);
     expect(host.getAttribute('data-anchor-placement-actual')).toBeTruthy();
+    expect(host.getAttribute('data-anchor-mode')).toMatch(/^(native|fallback)$/);
+    // Both paths set position:fixed — native because that's what the
+    // CSS Anchor Positioning helpers expect, fallback because it's the
+    // measured-coords positioning context.
     expect(host.style.position).toBe('fixed');
   });
 
-  it('dispatches anchor-placed event with the actual placement in detail', () => {
+  it('dispatches anchor-placed event with the actual placement + mode in detail', () => {
     const anchor = document.createElement('div');
     anchor.id = 'anchor-y';
     document.body.appendChild(anchor);
@@ -28,15 +40,32 @@ describe('anchor-positioning', () => {
     connectTrait(anchorPositioning, host);
     expect(spy.count).toBeGreaterThanOrEqual(1);
     expect(spy.last.actual).toBeTruthy();
+    expect(spy.last.mode).toMatch(/^(native|fallback)$/);
+  });
+
+  it('resolves anchor by selector OR by bare id', () => {
+    const anchor = document.createElement('div');
+    anchor.id = 'bare-id-anchor';
+    document.body.appendChild(anchor);
+    const host = mountHost('div', { 'data-anchor': 'bare-id-anchor' });
+    connectTrait(anchorPositioning, host);
+    expect(host.hasAttribute('data-anchor-positioning-placed')).toBe(true);
   });
 
   it('missing anchor: does not throw, does not place', () => {
     const host = mountHost('div', { 'data-anchor': '#nope' });
     expect(() => connectTrait(anchorPositioning, host)).not.toThrow();
     expect(host.hasAttribute('data-anchor-positioning-placed')).toBe(false);
+    expect(host.hasAttribute('data-anchor-mode')).toBe(false);
   });
 
-  it('disconnect clears both attributes and stops listening', () => {
+  it('missing data-anchor attribute: does not throw, does not place', () => {
+    const host = mountHost('div');
+    expect(() => connectTrait(anchorPositioning, host)).not.toThrow();
+    expect(host.hasAttribute('data-anchor-positioning-placed')).toBe(false);
+  });
+
+  it('disconnect clears all three managed attributes and stops listening', () => {
     const anchor = document.createElement('div');
     anchor.id = 'anchor-z';
     document.body.appendChild(anchor);
@@ -45,5 +74,49 @@ describe('anchor-positioning', () => {
     inst.disconnect(host);
     expect(host.hasAttribute('data-anchor-positioning-placed')).toBe(false);
     expect(host.hasAttribute('data-anchor-placement-actual')).toBe(false);
+    expect(host.hasAttribute('data-anchor-mode')).toBe(false);
+  });
+
+  it('connect → disconnect → connect again does not throw', () => {
+    const anchor = document.createElement('div');
+    anchor.id = 'anchor-recycle';
+    document.body.appendChild(anchor);
+    const host = mountHost('div', { 'data-anchor': '#anchor-recycle' });
+    const inst1 = connectTrait(anchorPositioning, host);
+    inst1.disconnect(host);
+    expect(() => {
+      const inst2 = connectTrait(anchorPositioning, host);
+      inst2.disconnect(host);
+    }).not.toThrow();
+  });
+
+  it('honors explicit placements (top / left / right)', () => {
+    for (const placement of ['top', 'left', 'right', 'bottom-start', 'top-end']) {
+      const anchor = document.createElement('div');
+      anchor.id = `anchor-${placement}`;
+      document.body.appendChild(anchor);
+      const host = mountHost('div', {
+        'data-anchor': `#anchor-${placement}`,
+        'data-anchor-placement': placement,
+      });
+      const inst = connectTrait(anchorPositioning, host);
+      expect(host.hasAttribute('data-anchor-positioning-placed')).toBe(true);
+      expect(host.getAttribute('data-anchor-placement-actual')).toBeTruthy();
+      inst.disconnect(host);
+      anchor.remove();
+      host.remove();
+    }
+  });
+
+  it('honors data-anchor-gap (numeric, defaults to 0)', () => {
+    const anchor = document.createElement('div');
+    anchor.id = 'anchor-gap';
+    document.body.appendChild(anchor);
+    const host = mountHost('div', {
+      'data-anchor': '#anchor-gap',
+      'data-anchor-gap': '12',
+    });
+    expect(() => connectTrait(anchorPositioning, host)).not.toThrow();
+    expect(host.hasAttribute('data-anchor-positioning-placed')).toBe(true);
   });
 });

package/traits/announcer-stage.js

@@ -0,0 +1,157 @@
+/**
+ * Shared aria-live regions for the `announcer` trait.
+ *
+ * Strategy: two body-level singleton `<div>` elements — one with
+ * `aria-live="polite"`, one with `aria-live="assertive"` — both with
+ * `aria-atomic="true"` so AT re-reads the full message on every change
+ * (instead of diffing the previous value, which can drop short
+ * messages or read fragments). The regions are visually clipped via
+ * the `.adia-sr-only` class so sighted users never see them, but
+ * remain in the accessibility tree so screen readers announce their
+ * contents.
+ *
+ * Both regions are created lazily on first `getRegion()` call and
+ * never torn down — they're cheap (two empty divs + one `<style>`)
+ * and many traits can share them. Multiple announcer instances on
+ * the same page route through the same two regions.
+ *
+ * The clip-path / sr-only recipe is the canonical "visually hidden,
+ * AT-visible" pattern: zero clip-path, position absolute off-screen,
+ * 1px size with overflow hidden. WCAG-friendly; works in every
+ * browser the project supports (Chromium 125+, Safari 18.0+,
+ * Firefox 129+).
+ *
+ * Notes:
+ * - happy-dom does not actually announce anything — these tests assert
+ *   the *contents* of the region, not the AT speech. Real-browser
+ *   verification happens on the demo page.
+ * - The regions are created on first call from any module, so importing
+ *   this file is side-effect-free until something invokes `getRegion()`.
+ */
+
+const POLITE_ID = 'adia-live-polite';
+const ASSERTIVE_ID = 'adia-live-assertive';
+const STYLE_ID = 'adia-live-styles';
+
+let politeRegion = null;
+let assertiveRegion = null;
+let stylesInjected = false;
+
+/**
+ * Get (or lazily create) one of the two singleton live regions.
+ * `priority` selects which region: `'polite'` for non-urgent updates
+ * (the default), `'assertive'` for urgent messages that should
+ * interrupt current speech (validation errors, destructive
+ * confirmations).
+ *
+ * Returns the region element. If `document` is unavailable (SSR,
+ * worker), returns `null` — callers should bail.
+ */
+export function getRegion(priority = 'polite') {
+  if (typeof document === 'undefined') return null;
+  ensureStyles();
+
+  if (priority === 'assertive') {
+    if (assertiveRegion && assertiveRegion.isConnected) return assertiveRegion;
+    const existing = document.getElementById(ASSERTIVE_ID);
+    if (existing) {
+      assertiveRegion = existing;
+      return assertiveRegion;
+    }
+    assertiveRegion = createRegion(ASSERTIVE_ID, 'assertive');
+    return assertiveRegion;
+  }
+
+  if (politeRegion && politeRegion.isConnected) return politeRegion;
+  const existing = document.getElementById(POLITE_ID);
+  if (existing) {
+    politeRegion = existing;
+    return politeRegion;
+  }
+  politeRegion = createRegion(POLITE_ID, 'polite');
+  return politeRegion;
+}
+
+function createRegion(id, liveValue) {
+  const el = document.createElement('div');
+  el.id = id;
+  el.setAttribute('aria-live', liveValue);
+  el.setAttribute('aria-atomic', 'true');
+  el.setAttribute('role', liveValue === 'assertive' ? 'alert' : 'status');
+  el.className = 'adia-sr-only';
+  // Defensive inline styles — if the consumer's CSS strips the class
+  // or the stylesheet failed to inject, the region must still be
+  // visually hidden. Belt-and-suspenders for production reliability.
+  el.style.cssText =
+    'position:absolute;width:1px;height:1px;padding:0;margin:-1px;' +
+    'overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;';
+  document.body.appendChild(el);
+  return el;
+}
+
+/**
+ * Inject the `.adia-sr-only` class once. Idempotent. The class is
+ * the canonical "visually hidden, AT-visible" recipe — zero in the
+ * visual layout, full presence in the accessibility tree.
+ */
+function ensureStyles() {
+  if (stylesInjected) return;
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(STYLE_ID)) {
+    stylesInjected = true;
+    return;
+  }
+  const styleEl = document.createElement('style');
+  styleEl.id = STYLE_ID;
+  styleEl.textContent = `
+    .adia-sr-only {
+      position: absolute !important;
+      width: 1px !important;
+      height: 1px !important;
+      padding: 0 !important;
+      margin: -1px !important;
+      overflow: hidden !important;
+      clip: rect(0, 0, 0, 0) !important;
+      white-space: nowrap !important;
+      border: 0 !important;
+    }
+  `;
+  document.head?.appendChild(styleEl);
+  stylesInjected = true;
+}
+
+/**
+ * Write a message into the chosen live region. `aria-atomic="true"`
+ * means AT re-reads the full new value on every change — but if the
+ * caller writes the *same* string back-to-back, some screen readers
+ * skip the re-announce. We blank the region first via a microtask
+ * gap, then write the message, to defeat that diffing.
+ */
+export function announce(message, priority = 'polite') {
+  const region = getRegion(priority);
+  if (!region) return false;
+  // Blank then write. The microtask ensures AT sees a true content
+  // change even when the same message fires twice in a row.
+  region.textContent = '';
+  // queueMicrotask (or a microtask via Promise.resolve) keeps this
+  // synchronous-feeling for callers but gives the AT layer a chance
+  // to register the empty state before the new message lands.
+  queueMicrotask(() => {
+    region.textContent = String(message ?? '');
+  });
+  return true;
+}
+
+/**
+ * Test-only: tear down both regions + the style block so test cases
+ * don't leak state across each other. Not part of the public API.
+ */
+export function _resetRegions() {
+  if (politeRegion && politeRegion.parentNode) politeRegion.remove();
+  if (assertiveRegion && assertiveRegion.parentNode) assertiveRegion.remove();
+  const styleEl = typeof document !== 'undefined' ? document.getElementById(STYLE_ID) : null;
+  if (styleEl) styleEl.remove();
+  politeRegion = null;
+  assertiveRegion = null;
+  stylesInjected = false;
+}