@adia-ai/web-components 0.2.3 → 0.2.4

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');
+    };
+  },
+});

package/traits/announcer.test.js

@@ -0,0 +1,268 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { announcer } from './announcer.js';
+import { _resetRegions, getRegion } from './announcer-stage.js';
+import { mountHost, connectTrait, spyEvent, resetDOM, tick, wait } from './test-helpers.js';
+
+// happy-dom doesn't speak — we assert region textContent instead.
+async function settleAnnounce() {
+  // The stage's blank-then-write uses queueMicrotask. Two ticks lets
+  // both the blank + the message land before we read.
+  await tick();
+  await tick();
+}
+
+describe('announcer', () => {
+  beforeEach(() => {
+    resetDOM();
+    _resetRegions();
+  });
+
+  it('schema: declares announcement-made event + four config attrs', () => {
+    expect(announcer.schema.name).toBe('announcer');
+    expect(announcer.schema.category).toBe('audio-haptics-sensory');
+    expect(announcer.schema.events).toContain('announcement-made');
+    expect(announcer.schema.config).toEqual([
+      'data-announce-on',
+      'data-announce-message',
+      'data-announce-priority',
+      'data-announce-throttle',
+    ]);
+  });
+
+  it('flips data-announcer-active on connect and cleans up on disconnect', () => {
+    const host = mountHost('div', { 'data-announce-on': 'click' });
+    const inst = connectTrait(announcer, host);
+    expect(host.hasAttribute('data-announcer-active')).toBe(true);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-announcer-active')).toBe(false);
+  });
+
+  it('with no data-announce-on: trait connects + disconnects without listening', () => {
+    const host = mountHost();
+    const inst = connectTrait(announcer, host);
+    expect(host.hasAttribute('data-announcer-active')).toBe(true);
+    // Firing some random event should not crash and not announce anything.
+    host.dispatchEvent(new CustomEvent('foo', { detail: 'bar' }));
+    expect(document.getElementById('adia-live-polite')).toBeNull();
+    inst.disconnect(host);
+  });
+
+  it('writes data-announce-message into the polite region by default', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'submit-success',
+      'data-announce-message': 'Form submitted successfully.',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    host.dispatchEvent(new CustomEvent('submit-success', { bubbles: true }));
+    await settleAnnounce();
+    const region = document.getElementById('adia-live-polite');
+    expect(region).not.toBeNull();
+    expect(region.getAttribute('aria-live')).toBe('polite');
+    expect(region.textContent).toBe('Form submitted successfully.');
+    // Assertive region should NOT exist when only polite messages have fired.
+    expect(document.getElementById('adia-live-assertive')).toBeNull();
+  });
+
+  it('routes data-announce-priority="assertive" to the assertive region', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'invalid',
+      'data-announce-message': 'Email is required.',
+      'data-announce-priority': 'assertive',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    host.dispatchEvent(new CustomEvent('invalid', { bubbles: true }));
+    await settleAnnounce();
+    const assertiveRegion = document.getElementById('adia-live-assertive');
+    expect(assertiveRegion).not.toBeNull();
+    expect(assertiveRegion.getAttribute('aria-live')).toBe('assertive');
+    expect(assertiveRegion.getAttribute('role')).toBe('alert');
+    expect(assertiveRegion.textContent).toBe('Email is required.');
+  });
+
+  it('substitutes {detail} placeholder from a scalar event detail', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'count-up-done',
+      'data-announce-message': 'Counted to {detail}.',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    host.dispatchEvent(new CustomEvent('count-up-done', { detail: 18931, bubbles: true }));
+    await settleAnnounce();
+    const region = document.getElementById('adia-live-polite');
+    expect(region.textContent).toBe('Counted to 18931.');
+  });
+
+  it('substitutes {detail} placeholder from object detail.message', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'validated',
+      'data-announce-message': 'Validation: {detail}.',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { valid: false, message: 'Invalid email address' },
+      bubbles: true,
+    }));
+    await settleAnnounce();
+    const region = document.getElementById('adia-live-polite');
+    expect(region.textContent).toBe('Validation: Invalid email address.');
+  });
+
+  it('falls back to event.detail.message when no template is set', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'validated',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { message: 'Required field is empty' },
+      bubbles: true,
+    }));
+    await settleAnnounce();
+    const region = document.getElementById('adia-live-polite');
+    expect(region.textContent).toBe('Required field is empty');
+  });
+
+  it('falls back to data-validation-message when no detail and no template', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'validated',
+      'data-validation-message': 'This field is required',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    host.dispatchEvent(new CustomEvent('validated', { bubbles: true }));
+    await settleAnnounce();
+    const region = document.getElementById('adia-live-polite');
+    expect(region.textContent).toBe('This field is required');
+  });
+
+  it('skips announce when there is no resolvable message', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'noop',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    const spy = spyEvent(host, 'announcement-made');
+    host.dispatchEvent(new CustomEvent('noop', { bubbles: true }));
+    await settleAnnounce();
+    expect(spy.count).toBe(0);
+    // No region created either — nothing to write into.
+    const region = document.getElementById('adia-live-polite');
+    expect(region == null || region.textContent === '').toBe(true);
+  });
+
+  it('throttle: suppresses a second announce inside the window', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'tick',
+      'data-announce-message': 'Tick at {detail}',
+      'data-announce-throttle': '1000',
+    });
+    connectTrait(announcer, host);
+    const spy = spyEvent(host, 'announcement-made');
+    host.dispatchEvent(new CustomEvent('tick', { detail: 1, bubbles: true }));
+    host.dispatchEvent(new CustomEvent('tick', { detail: 2, bubbles: true }));
+    host.dispatchEvent(new CustomEvent('tick', { detail: 3, bubbles: true }));
+    await settleAnnounce();
+    expect(spy.count).toBe(1);
+    expect(spy.last.message).toBe('Tick at 1');
+  });
+
+  it('throttle=0 lets every event through', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'tick',
+      'data-announce-message': 'Tick at {detail}',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    const spy = spyEvent(host, 'announcement-made');
+    host.dispatchEvent(new CustomEvent('tick', { detail: 1 }));
+    host.dispatchEvent(new CustomEvent('tick', { detail: 2 }));
+    await settleAnnounce();
+    expect(spy.count).toBe(2);
+  });
+
+  it('dispatches announcement-made with { message, priority } detail', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'go',
+      'data-announce-message': 'Hello',
+      'data-announce-priority': 'assertive',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    const spy = spyEvent(host, 'announcement-made');
+    host.dispatchEvent(new CustomEvent('go', { bubbles: true }));
+    await settleAnnounce();
+    expect(spy.count).toBe(1);
+    expect(spy.last.message).toBe('Hello');
+    expect(spy.last.priority).toBe('assertive');
+  });
+
+  it('singleton regions: two announcer instances share one polite region', async () => {
+    const a = mountHost('div', {
+      'data-announce-on': 'go',
+      'data-announce-message': 'A says hi',
+      'data-announce-throttle': '0',
+    });
+    const b = mountHost('div', {
+      'data-announce-on': 'go',
+      'data-announce-message': 'B says hi',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, a);
+    connectTrait(announcer, b);
+    a.dispatchEvent(new CustomEvent('go'));
+    await settleAnnounce();
+    b.dispatchEvent(new CustomEvent('go'));
+    await settleAnnounce();
+    // Only one polite region in the document.
+    const regions = document.querySelectorAll('#adia-live-polite');
+    expect(regions.length).toBe(1);
+    expect(regions[0].textContent).toBe('B says hi');
+  });
+
+  it('regions are created with sr-only clipping (visually hidden, AT-visible)', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'go',
+      'data-announce-message': 'hi',
+      'data-announce-throttle': '0',
+    });
+    connectTrait(announcer, host);
+    host.dispatchEvent(new CustomEvent('go'));
+    await settleAnnounce();
+    const region = document.getElementById('adia-live-polite');
+    expect(region.classList.contains('adia-sr-only')).toBe(true);
+    expect(region.getAttribute('aria-atomic')).toBe('true');
+    // The role is 'status' for polite, 'alert' for assertive.
+    expect(region.getAttribute('role')).toBe('status');
+  });
+
+  it('disconnect leaves the singleton regions in place for other consumers', () => {
+    const host = mountHost('div', { 'data-announce-on': 'go' });
+    // Pre-create the region by hand so we know it's there before connect.
+    getRegion('polite');
+    const inst = connectTrait(announcer, host);
+    inst.disconnect(host);
+    expect(document.getElementById('adia-live-polite')).not.toBeNull();
+  });
+
+  it('reconnect after disconnect re-listens cleanly', async () => {
+    const host = mountHost('div', {
+      'data-announce-on': 'go',
+      'data-announce-message': 'reconnected',
+      'data-announce-throttle': '0',
+    });
+    const inst1 = connectTrait(announcer, host);
+    inst1.disconnect(host);
+    host.dispatchEvent(new CustomEvent('go'));
+    await settleAnnounce();
+    expect(document.getElementById('adia-live-polite')?.textContent || '').toBe('');
+
+    const inst2 = connectTrait(announcer, host);
+    host.dispatchEvent(new CustomEvent('go'));
+    await settleAnnounce();
+    expect(document.getElementById('adia-live-polite').textContent).toBe('reconnected');
+    inst2.disconnect(host);
+  });
+});

package/traits/arrow-grid-nav.js

@@ -0,0 +1,234 @@
+import { defineTrait } from './define.js';
+
+/**
+ * 2D arrow-key navigation for grids — calendars, menubars, color pickers,
+ * APG `grid` pattern. Sibling 1D trait `keyboard-nav` only fires intent
+ * events; this trait owns row+col state and physically moves the active
+ * cell.
+ *
+ *   <div role="grid" data-grid-columns="7">
+ *     <button-ui>1</button-ui>
+ *     <button-ui>2</button-ui>
+ *     ...
+ *   </div>
+ *
+ *   arrowGridNav().connect(grid);
+ *   grid.addEventListener('grid-activate', (e) => select(e.detail.row, e.detail.col));
+ *
+ * Two structural modes via `data-grid-mode`:
+ *   "row-flat"   (default) — children are grid items; row/col are inferred
+ *                            from index ÷ data-grid-columns.
+ *   "row-nested" — children are row containers; each row's children are cells.
+ */
+export const arrowGridNav = defineTrait({
+  name: 'arrow-grid-nav',
+  category: 'keyboard-navigation',
+  description: '2D arrow-key navigation for grids, calendars, menubars (APG grid pattern)',
+  attributes: ['data-arrow-grid-nav-active', 'data-grid-active-row', 'data-grid-active-col'],
+  events: ['grid-activate', 'grid-edge', 'grid-cell-change'],
+  config: ['data-grid-columns', 'data-grid-mode'],
+  setup({ host }) {
+    let activeRow = 0;
+    let activeCol = 0;
+    let activeCell = null;
+    let observer = null;
+
+    function getMode() {
+      return host.getAttribute('data-grid-mode') === 'row-nested' ? 'row-nested' : 'row-flat';
+    }
+
+    function getColumns() {
+      const raw = parseInt(host.getAttribute('data-grid-columns'), 10);
+      return Number.isFinite(raw) && raw > 0 ? raw : 1;
+    }
+
+    /**
+     * Returns a 2D matrix of cells: cells[row][col].
+     * Both modes return the same shape so navigation logic is uniform.
+     */
+    function discoverCells() {
+      const mode = getMode();
+      if (mode === 'row-nested') {
+        // Each direct child is a row container; its children are cells.
+        return [...host.children].map((rowEl) =>
+          [...rowEl.children].filter((c) => !c.hasAttribute('disabled')),
+        );
+      }
+      // row-flat: split a flat child list into rows by column count.
+      const cols = getColumns();
+      const flat = [...host.children].filter((c) => !c.hasAttribute('disabled'));
+      const rows = [];
+      for (let i = 0; i < flat.length; i += cols) {
+        rows.push(flat.slice(i, i + cols));
+      }
+      return rows;
+    }
+
+    function clearActiveCell() {
+      if (activeCell) {
+        activeCell.removeAttribute('data-grid-active');
+        activeCell.setAttribute('tabindex', '-1');
+        activeCell = null;
+      }
+    }
+
+    function paint(cells, prevRow, prevCol) {
+      const safeRow = Math.max(0, Math.min(activeRow, cells.length - 1));
+      const row = cells[safeRow] || [];
+      const safeCol = Math.max(0, Math.min(activeCol, row.length - 1));
+      activeRow = safeRow;
+      activeCol = safeCol;
+
+      clearActiveCell();
+
+      const cell = row[safeCol];
+      if (cell) {
+        activeCell = cell;
+        cell.setAttribute('data-grid-active', '');
+        cell.setAttribute('tabindex', '0');
+      }
+
+      host.setAttribute('data-grid-active-row', String(activeRow));
+      host.setAttribute('data-grid-active-col', String(activeCol));
+
+      const changed = prevRow !== activeRow || prevCol !== activeCol;
+      if (changed) {
+        host.dispatchEvent(new CustomEvent('grid-cell-change', {
+          bubbles: true,
+          detail: { row: activeRow, col: activeCol, element: cell || null },
+        }));
+      }
+    }
+
+    function paintInitial() {
+      const cells = discoverCells();
+      // Mark every cell as roving-tabindex -1 so Tab lands once on the host.
+      for (const row of cells) {
+        for (const cell of row) {
+          if (!cell.hasAttribute('tabindex')) cell.setAttribute('tabindex', '-1');
+        }
+      }
+      paint(cells, -1, -1);
+    }
+
+    function emitEdge(edge) {
+      host.dispatchEvent(new CustomEvent('grid-edge', {
+        bubbles: true,
+        detail: { edge, row: activeRow, col: activeCol },
+      }));
+    }
+
+    function onKeyDown(e) {
+      // Skip if the event is from a typing surface inside a cell.
+      const tag = (e.target?.tagName || '').toLowerCase();
+      if (tag === 'input' || tag === 'textarea' || e.target?.isContentEditable) return;
+
+      const cells = discoverCells();
+      if (cells.length === 0) return;
+
+      const prevRow = activeRow;
+      const prevCol = activeCol;
+      const lastRow = cells.length - 1;
+      const currentRow = cells[activeRow] || [];
+      const lastCol = currentRow.length - 1;
+
+      let handled = true;
+
+      switch (e.key) {
+        case 'ArrowRight':
+          if (activeCol < lastCol) activeCol++;
+          else { emitEdge('right'); handled = true; }
+          break;
+        case 'ArrowLeft':
+          if (activeCol > 0) activeCol--;
+          else { emitEdge('left'); handled = true; }
+          break;
+        case 'ArrowDown': {
+          if (activeRow < lastRow) {
+            activeRow++;
+            const newRow = cells[activeRow] || [];
+            // Clamp col to new row's length (rows can vary in row-nested mode).
+            if (activeCol > newRow.length - 1) activeCol = Math.max(0, newRow.length - 1);
+          } else {
+            emitEdge('bottom');
+          }
+          break;
+        }
+        case 'ArrowUp': {
+          if (activeRow > 0) {
+            activeRow--;
+            const newRow = cells[activeRow] || [];
+            if (activeCol > newRow.length - 1) activeCol = Math.max(0, newRow.length - 1);
+          } else {
+            emitEdge('top');
+          }
+          break;
+        }
+        case 'Home':
+          if (e.ctrlKey || e.metaKey) {
+            activeRow = 0;
+            activeCol = 0;
+          } else {
+            activeCol = 0;
+          }
+          break;
+        case 'End':
+          if (e.ctrlKey || e.metaKey) {
+            activeRow = lastRow;
+            const lastRowCells = cells[lastRow] || [];
+            activeCol = Math.max(0, lastRowCells.length - 1);
+          } else {
+            activeCol = lastCol;
+          }
+          break;
+        case 'Enter':
+        case ' ': {
+          // Activate without moving; paint not needed.
+          const cell = currentRow[activeCol];
+          host.dispatchEvent(new CustomEvent('grid-activate', {
+            bubbles: true,
+            detail: { row: activeRow, col: activeCol, element: cell || null },
+          }));
+          e.preventDefault();
+          return;
+        }
+        default:
+          handled = false;
+      }
+
+      if (!handled) return;
+
+      e.preventDefault();
+      paint(cells, prevRow, prevCol);
+      // Move physical focus to the new cell so screen readers + visible focus follow.
+      activeCell?.focus({ preventScroll: false });
+    }
+
+    function onMutate() {
+      // Children added / removed — re-paint with clamped indices.
+      const cells = discoverCells();
+      if (cells.length === 0) return;
+      paint(cells, -1, -1);
+    }
+
+    host.setAttribute('data-arrow-grid-nav-active', '');
+    if (!host.hasAttribute('tabindex')) host.setAttribute('tabindex', '0');
+    host.addEventListener('keydown', onKeyDown);
+
+    paintInitial();
+
+    if (typeof MutationObserver !== 'undefined') {
+      observer = new MutationObserver(onMutate);
+      observer.observe(host, { childList: true, subtree: getMode() === 'row-nested' });
+    }
+
+    return () => {
+      host.removeEventListener('keydown', onKeyDown);
+      if (observer) { observer.disconnect(); observer = null; }
+      clearActiveCell();
+      host.removeAttribute('data-arrow-grid-nav-active');
+      host.removeAttribute('data-grid-active-row');
+      host.removeAttribute('data-grid-active-col');
+    };
+  },
+});