@adia-ai/web-components 0.2.2 → 0.2.4

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;
+}

package/traits/announcer.js

@@ -0,0 +1,145 @@
+import { defineTrait } from './define.js';
+import { announce, getRegion } from './announcer-stage.js';
+
+/**
+ * `announcer` — aria-live mirror for AT (assistive tech) listeners.
+ *
+ * Every audio/haptic/visual trait above WCAG 4.1.3 (Status Messages)
+ * leaves AT users behind: count-up tickers, validation flips, typewriter
+ * reveals — none of these announce themselves. `announcer` is the missing
+ * pair. It hooks any host event into one of two body-level singleton
+ * `aria-live` regions; AT speaks the message, sighted users see nothing.
+ *
+ * Triggers
+ * --------
+ *   data-announce-on        the event name to listen for on the host
+ *   data-announce-message   the message to write. Supports `{detail}`
+ *                           which substitutes `event.detail` — useful for
+ *                           validation errors / count-up final values.
+ *                           If `event.detail` is an object, the
+ *                           `message` field is preferred when present.
+ *   data-announce-priority  'polite' (default) | 'assertive'
+ *   data-announce-throttle  minimum ms between two announcements from
+ *                           the same trait instance (default 1000).
+ *                           Burst-protect against rapid-fire updates.
+ *
+ * Singleton regions
+ * -----------------
+ * Two body-level regions are created lazily on first announce — one
+ * polite, one assertive. Both are visually clipped via `.adia-sr-only`
+ * so sighted users never see them, but stay in the accessibility tree
+ * so screen readers announce the contents. Multiple announcer traits
+ * share the same two regions; cleanup leaves them in place.
+ *
+ * Why a microtask blank-then-write
+ * --------------------------------
+ * `aria-atomic="true"` re-reads the full content on every change, but
+ * many screen readers skip a write if the new value equals the previous
+ * one. The stage helper blanks the region in a microtask, then writes
+ * the message — defeats the diff and forces a re-announce.
+ */
+export const announcer = defineTrait({
+  name: 'announcer',
+  category: 'audio-haptics-sensory',
+  description: 'aria-live mirror for AT — announces host state changes via singleton polite/assertive regions',
+  attributes: ['data-announcer-active'],
+  events: ['announcement-made'],
+  config: [
+    'data-announce-on',
+    'data-announce-message',
+    'data-announce-priority',
+    'data-announce-throttle',
+  ],
+  setup({ host }) {
+    const eventName = host.getAttribute('data-announce-on');
+    if (!eventName) {
+      // No trigger configured — quietly no-op. The trait still flips its
+      // active flag so authors can debug "is the trait wired?" via DevTools.
+      host.setAttribute('data-announcer-active', '');
+      return () => {
+        host.removeAttribute('data-announcer-active');
+      };
+    }
+
+    const throttleMs = parseInt(host.getAttribute('data-announce-throttle'), 10);
+    const throttle = Number.isFinite(throttleMs) && throttleMs >= 0 ? throttleMs : 1000;
+
+    // `null` so the first announce always wins regardless of throttle —
+    // the throttle is "minimum gap between two announcements," not a
+    // delay before the first one. Subsequent events compare against
+    // the previous timestamp.
+    let lastAnnouncedAt = null;
+
+    function readPriority() {
+      const raw = host.getAttribute('data-announce-priority');
+      return raw === 'assertive' ? 'assertive' : 'polite';
+    }
+
+    function resolveMessage(event) {
+      // Priority for message resolution:
+      //   1. event.detail.message (object detail with explicit field)
+      //   2. event.detail (scalar / serializable)
+      //   3. data-announce-message (with `{detail}` placeholder)
+      //   4. host.getAttribute('data-validation-message') as last-ditch
+      //      fallback — pairs cleanly with the validation trait.
+      const tmpl = host.getAttribute('data-announce-message');
+      const detail = event?.detail;
+
+      if (tmpl) {
+        const detailStr = detail == null
+          ? ''
+          : (typeof detail === 'object'
+              ? (detail.message ?? JSON.stringify(detail))
+              : String(detail));
+        return tmpl.includes('{detail}') ? tmpl.replace(/\{detail\}/g, detailStr) : tmpl;
+      }
+
+      if (detail != null) {
+        if (typeof detail === 'object') {
+          if (typeof detail.message === 'string') return detail.message;
+          // Fall through — opaque object detail without a message field
+          // isn't useful to AT. Return null to skip.
+          return null;
+        }
+        return String(detail);
+      }
+
+      const fallback = host.getAttribute('data-validation-message');
+      return fallback || null;
+    }
+
+    function onTrigger(event) {
+      const message = resolveMessage(event);
+      if (!message) return;
+
+      const now = (typeof performance !== 'undefined' && performance.now)
+        ? performance.now()
+        : Date.now();
+      if (throttle > 0 && lastAnnouncedAt != null && now - lastAnnouncedAt < throttle) return;
+      lastAnnouncedAt = now;
+
+      const priority = readPriority();
+      const ok = announce(message, priority);
+      if (!ok) return;
+
+      host.dispatchEvent(new CustomEvent('announcement-made', {
+        bubbles: true,
+        detail: { message, priority },
+      }));
+    }
+
+    host.addEventListener(eventName, onTrigger);
+    host.setAttribute('data-announcer-active', '');
+
+    // Pre-warm both regions so the first real announce doesn't pay
+    // the create-+-microtask-gap cost serially. Cheap (two empty divs)
+    // and idempotent if any other announcer instance already did it.
+    getRegion('polite');
+    if (readPriority() === 'assertive') getRegion('assertive');
+
+    return () => {
+      host.removeEventListener(eventName, onTrigger);
+      host.removeAttribute('data-announcer-active');
+    };
+  },
+});