@adia-ai/web-components 0.2.3 → 0.2.5

package/traits/droppable.js

@@ -0,0 +1,136 @@
+import { defineTrait } from './define.js';
+
+/**
+ * `droppable` — marks an element as a drop target for `draggable-list-item`.
+ *
+ * Authored for the Tasks UI playground (docs/projects/tasks-playground/spec/).
+ * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'input-interaction').
+ *
+ * Pairs with `draggable-list-item` (motion-positioning) which lifts a list
+ * item and emits `dnd-lift` / `dnd-drop-target-change` / `dnd-drop` /
+ * `dnd-drop-cancel` ON THE DOCUMENT. This trait observes the drag in
+ * flight and emits target-side events ON THE HOST:
+ *
+ *   `dnd-drop-enter`    pointer entered this droppable
+ *   `dnd-drop-leave`    pointer left this droppable
+ *   `dnd-drop-receive`  the drop landed here (source-side `dnd-drop`
+ *                       on the document is the lifter's "release"
+ *                       signal; the target-side event MUST be named
+ *                       differently or it bubbles back to the
+ *                       document and re-triggers this same listener
+ *                       in an infinite loop)
+ *
+ * Coordination: pure DOM events (light-DOM, bubbles: true). No shared
+ * runtime state. The dragging item dispatches `dnd-drop-target-change`
+ * with the candidate target id; the targeted droppable receives a
+ * synthetic `dnd-drop-enter` from a tiny internal coordinator.
+ *
+ * For v1 the coordinator is a single shared module-level Map keyed by
+ * `data-droppable-id`. Future versions may promote to a registry trait.
+ */
+
+const ATTR_ID = 'data-droppable-id';
+const ATTR_OVER = 'data-droppable-over';
+const ATTR_VALID = 'data-droppable-valid';
+
+/** @type {Map<string, HTMLElement>} */
+const REGISTRY = new Map();
+/** @type {string | null} */
+let CURRENT_TARGET_ID = null;
+
+export const droppable = defineTrait({
+  name: 'droppable',
+  category: 'input-interaction',
+  description: 'Marks an element as a drop target for draggable-list-item; emits dnd-drop-enter / leave / receive',
+  attributes: [ATTR_ID, ATTR_OVER, ATTR_VALID],
+  events: ['dnd-drop-enter', 'dnd-drop-leave', 'dnd-drop-receive'],
+  config: [],
+  setup({ host }) {
+    // Assign a stable id for the registry. Authoring code may set it
+    // explicitly via the attribute; otherwise generate.
+    let id = host.getAttribute(ATTR_ID);
+    if (!id) {
+      id = `drop-${crypto.randomUUID().slice(0, 8)}`;
+      host.setAttribute(ATTR_ID, id);
+    }
+    REGISTRY.set(id, host);
+
+    // Listen for drag-in-flight signals on the document so this droppable
+    // knows when it should self-mark as the target.
+    //
+    // Bug guard (2026-05-04): per-host attribute is the source of truth.
+    // The previous implementation gated the leave branch on a shared
+    // module variable CURRENT_TARGET_ID, which made the result dependent
+    // on listener-execution order — when the target swap fired and the
+    // NEW target's listener ran before the OLD target's, the old one
+    // saw CURRENT_TARGET_ID already moved and skipped clearing its
+    // ATTR_OVER, leaving multiple columns visually marked as the drop
+    // target. Per-host hasAttribute() is independent of order.
+    function onTargetChange(/** @type {CustomEvent} */ e) {
+      const detail = e.detail;
+      if (!detail) return;
+      const isMe = detail.target_container_id === id;
+      const wasOver = host.hasAttribute(ATTR_OVER);
+      if (isMe && !wasOver) {
+        host.setAttribute(ATTR_OVER, '');
+        CURRENT_TARGET_ID = id;
+        host.dispatchEvent(new CustomEvent('dnd-drop-enter', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: detail.source_id, pointer_position: detail.pointer ?? { x: 0, y: 0 } },
+        }));
+      } else if (!isMe && wasOver) {
+        host.removeAttribute(ATTR_OVER);
+        if (CURRENT_TARGET_ID === id) CURRENT_TARGET_ID = null;
+        host.dispatchEvent(new CustomEvent('dnd-drop-leave', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: detail.source_id ?? null },
+        }));
+      }
+    }
+
+    function onDrop(/** @type {CustomEvent} */ e) {
+      const detail = e.detail;
+      if (!detail || detail.target_container_id !== id) return;
+      host.removeAttribute(ATTR_OVER);
+      CURRENT_TARGET_ID = null;
+      host.dispatchEvent(new CustomEvent('dnd-drop-receive', {
+        bubbles: true,
+        composed: false,
+        detail: {
+          source_id: detail.source_id,
+          source_index: detail.source_index,
+          source_container_id: detail.source_container_id,
+          target_container_id: id,
+          target_index: detail.target_index,
+        },
+      }));
+    }
+
+    function onDragEnd() {
+      // Whatever happened, reset the over state.
+      host.removeAttribute(ATTR_OVER);
+      if (CURRENT_TARGET_ID === id) CURRENT_TARGET_ID = null;
+    }
+
+    document.addEventListener('dnd-drop-target-change', onTargetChange);
+    document.addEventListener('dnd-drop', onDrop);
+    document.addEventListener('dnd-drop-cancel', onDragEnd);
+
+    return () => {
+      document.removeEventListener('dnd-drop-target-change', onTargetChange);
+      document.removeEventListener('dnd-drop', onDrop);
+      document.removeEventListener('dnd-drop-cancel', onDragEnd);
+      REGISTRY.delete(id);
+      host.removeAttribute(ATTR_ID);
+      host.removeAttribute(ATTR_OVER);
+      host.removeAttribute(ATTR_VALID);
+    };
+  },
+});
+
+/** Internal: lookup a droppable host by id. Used by `draggable-list-item`. */
+export function getDroppable(id) {
+  return REGISTRY.get(id) ?? null;
+}

package/traits/droppable.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { droppable } from './droppable.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
+
+// Minimal smoke coverage. The droppable trait is authored against the
+// docs/projects/tasks-playground/ DnD coordinator and assumes a sibling
+// `draggable-list-item` trait dispatches `dnd:drop-target-change` /
+// `dnd:drop` on the document. The cases below only exercise the trait's
+// own surface (schema, attribute lifecycle, registry entry, cleanup) so
+// the verify:traits gate stays green; the higher-fidelity DnD-flow tests
+// belong with the Tasks UI initiative that owns the coordinator.
+
+describe('droppable', () => {
+  beforeEach(resetDOM);
+
+  it('schema shape is defined', () => {
+    expect(droppable.schema.name).toBe('droppable');
+    expect(droppable.schema.category).toBe('input-interaction');
+    expect(droppable.schema.description.length).toBeGreaterThanOrEqual(11);
+    expect(droppable.schema.events).toContain('dnd-drop-enter');
+    // Source-side `dnd-drop` (on document, from the lifter) and target-side
+    // `dnd-drop-receive` (on host) MUST be distinct names — sharing the name
+    // recurses infinitely when the host event bubbles back to the document.
+    expect(droppable.schema.events).toContain('dnd-drop-receive');
+    expect(droppable.schema.events).not.toContain('dnd-drop');
+  });
+
+  it('connect assigns an id + sets the host attribute', () => {
+    const host = mountHost('div');
+    connectTrait(droppable, host);
+    expect(host.getAttribute('data-droppable-id')).toBeTruthy();
+  });
+
+  it('disconnect removes the over attribute if set', () => {
+    const host = mountHost('div');
+    const inst = droppable();
+    inst.connect(host);
+    host.setAttribute('data-droppable-over', '');
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-droppable-over')).toBe(false);
+  });
+
+  it('reconnect with the same host does not throw', () => {
+    const host = mountHost('div');
+    const inst = droppable();
+    inst.connect(host);
+    inst.disconnect(host);
+    expect(() => {
+      const inst2 = droppable();
+      inst2.connect(host);
+      inst2.disconnect(host);
+    }).not.toThrow();
+  });
+});

package/traits/error-shake.js

@@ -0,0 +1,157 @@
+import { defineTrait } from './define.js';
+import { prefersReducedMotion } from './motion.js';
+
+/**
+ * `error-shake` — horizontal lateral oscillation on validation failure.
+ *
+ * The de-facto "wrong password" affordance. Listens for the `validated`
+ * event with `detail.valid === false` (fired by the `validation` trait),
+ * watches the `data-validation-invalid` attribute for false→true
+ * transitions, and supports a programmatic `data-error-shake-trigger`
+ * attribute toggle so non-form contexts can fire shakes too.
+ *
+ * Composes naturally with `validation`:
+ *   <input-ui traits="validation error-shake" data-validate="required, email">
+ *
+ * On trigger, the host shakes for ~400ms via a translateX-only keyframe
+ * animation — never `margin`/`width`, so siblings don't reflow. The
+ * keyframes run on the compositor and the keyframe `<style>` is owned
+ * by the trait instance (not shared) so disconnect is clean.
+ *
+ * Reduced-motion: skip the animation entirely, but still mark
+ * `data-error-shake-active` for 200ms before removing — gives consumer
+ * stylesheets a CSS hook to swap in a static error-tint or border
+ * without re-querying the media query themselves.
+ */
+
+const DEFAULT_AMPLITUDE = 8;     // px lateral travel
+const DEFAULT_DURATION = 400;    // ms total
+const REDUCED_MOTION_HOLD = 200; // ms — how long the marker sits in reduced-motion mode
+
+export const errorShake = defineTrait({
+  name: 'error-shake',
+  category: 'animation-feedback',
+  description: 'Horizontal lateral oscillation on validation failure',
+  attributes: ['data-error-shake-active'],
+  events: ['error-shake-done'],
+  config: ['data-error-shake-amplitude', 'data-error-shake-duration', 'data-error-shake-trigger'],
+  setup({ host }) {
+    const activeTimers = new Set();
+    let styleEl = null;
+    let keyframeName = null;
+    let lastInvalid = host.hasAttribute('data-validation-invalid');
+
+    function readAmplitude() {
+      const v = parseFloat(host.getAttribute('data-error-shake-amplitude'));
+      return Number.isFinite(v) && v > 0 ? v : DEFAULT_AMPLITUDE;
+    }
+
+    function readDuration() {
+      const v = parseInt(host.getAttribute('data-error-shake-duration'), 10);
+      return Number.isFinite(v) && v > 0 ? v : DEFAULT_DURATION;
+    }
+
+    function ensureKeyframes(amp) {
+      if (styleEl) styleEl.remove();
+      keyframeName = `adia-error-shake-${Math.random().toString(36).slice(2, 8)}`;
+      styleEl = document.createElement('style');
+      // 4-cycle oscillation. translateX only — never margin/width — so
+      // the host's siblings don't reflow during the shake.
+      styleEl.textContent = `
+        @keyframes ${keyframeName} {
+          0%, 100% { transform: translateX(0); }
+          15% { transform: translateX(-${amp}px); }
+          30% { transform: translateX(${amp}px); }
+          45% { transform: translateX(-${amp * 0.7}px); }
+          60% { transform: translateX(${amp * 0.7}px); }
+          75% { transform: translateX(-${amp * 0.4}px); }
+          90% { transform: translateX(${amp * 0.4}px); }
+        }
+      `;
+      document.head.appendChild(styleEl);
+    }
+
+    function fireDone() {
+      host.removeAttribute('data-error-shake-active');
+      host.dispatchEvent(new CustomEvent('error-shake-done', { bubbles: true }));
+    }
+
+    function reducedMotionShake() {
+      host.setAttribute('data-error-shake-active', '');
+      const t = setTimeout(() => {
+        activeTimers.delete(t);
+        fireDone();
+      }, REDUCED_MOTION_HOLD);
+      activeTimers.add(t);
+    }
+
+    function shake() {
+      if (prefersReducedMotion()) {
+        reducedMotionShake();
+        return;
+      }
+
+      const amp = readAmplitude();
+      const dur = readDuration();
+      ensureKeyframes(amp);
+
+      // Force-reset any in-flight animation so back-to-back triggers
+      // restart cleanly (e.g. user mashes submit on an invalid form).
+      host.style.animation = '';
+      // Reading offsetWidth flushes the style change — the next assignment
+      // is then guaranteed to be seen as a transition by the engine.
+      void host.offsetWidth;
+      host.style.animation = `${keyframeName} ${dur}ms ease-in-out`;
+      host.setAttribute('data-error-shake-active', '');
+
+      const t = setTimeout(() => {
+        activeTimers.delete(t);
+        host.style.animation = '';
+        fireDone();
+      }, dur);
+      activeTimers.add(t);
+    }
+
+    function onValidated(e) {
+      if (e?.detail && e.detail.valid === false) shake();
+    }
+
+    // Watch data-validation-invalid + data-error-shake-trigger for
+    // attribute changes. validation trait sets data-validation-invalid
+    // synchronously *before* dispatching `validated`, so the observer
+    // and event listener can both fire — we de-dupe by tracking the
+    // last-known invalid state and only triggering on false → true.
+    const observer = new MutationObserver((muts) => {
+      for (const m of muts) {
+        if (m.attributeName === 'data-validation-invalid') {
+          const nowInvalid = host.hasAttribute('data-validation-invalid');
+          if (nowInvalid && !lastInvalid) shake();
+          lastInvalid = nowInvalid;
+        } else if (m.attributeName === 'data-error-shake-trigger') {
+          // Toggle (any change) fires a shake. Empty-string and "" are
+          // both treated as "present" — the convention for boolean attrs.
+          if (host.hasAttribute('data-error-shake-trigger')) shake();
+        }
+      }
+    });
+    observer.observe(host, {
+      attributes: true,
+      attributeFilter: ['data-validation-invalid', 'data-error-shake-trigger'],
+    });
+
+    host.addEventListener('validated', onValidated);
+
+    return () => {
+      observer.disconnect();
+      host.removeEventListener('validated', onValidated);
+      for (const t of activeTimers) clearTimeout(t);
+      activeTimers.clear();
+      if (styleEl) {
+        styleEl.remove();
+        styleEl = null;
+      }
+      host.style.animation = '';
+      host.removeAttribute('data-error-shake-active');
+    };
+  },
+});

package/traits/error-shake.test.js

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { errorShake } from './error-shake.js';
+import { mountHost, connectTrait, spyEvent, resetDOM, wait } from './test-helpers.js';
+
+describe('error-shake', () => {
+  beforeEach(resetDOM);
+
+  it('schema declares animation-feedback category', () => {
+    expect(errorShake.schema.category).toBe('animation-feedback');
+    expect(errorShake.schema.events).toContain('error-shake-done');
+    expect(errorShake.schema.attributes).toContain('data-error-shake-active');
+  });
+
+  it('connect → disconnect leaves no managed attribute', () => {
+    const host = mountHost();
+    const inst = connectTrait(errorShake, host);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-error-shake-active')).toBe(false);
+  });
+
+  it('fires on validated event with detail.valid === false', async () => {
+    const host = mountHost();
+    connectTrait(errorShake, host);
+    const spy = spyEvent(host, 'error-shake-done');
+
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { valid: false, errors: ['nope'] },
+    }));
+
+    expect(host.hasAttribute('data-error-shake-active')).toBe(true);
+    // Wait through the default 400ms duration + a small grace window.
+    await wait(450);
+    expect(spy.count).toBe(1);
+    expect(host.hasAttribute('data-error-shake-active')).toBe(false);
+  });
+
+  it('does not fire on validated event with detail.valid === true', async () => {
+    const host = mountHost();
+    connectTrait(errorShake, host);
+    const spy = spyEvent(host, 'error-shake-done');
+
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { valid: true, errors: [] },
+    }));
+
+    await wait(50);
+    expect(spy.count).toBe(0);
+    expect(host.hasAttribute('data-error-shake-active')).toBe(false);
+  });
+
+  it('fires when data-validation-invalid is set (false → true)', async () => {
+    const host = mountHost();
+    connectTrait(errorShake, host);
+    const spy = spyEvent(host, 'error-shake-done');
+
+    host.setAttribute('data-validation-invalid', '');
+    // MutationObserver microtask flush.
+    await wait(0);
+    expect(host.hasAttribute('data-error-shake-active')).toBe(true);
+    await wait(450);
+    expect(spy.count).toBe(1);
+  });
+
+  it('does not re-fire when data-validation-invalid stays true across mutations', async () => {
+    const host = mountHost('div', { 'data-validation-invalid': '' });
+    connectTrait(errorShake, host);
+    const spy = spyEvent(host, 'error-shake-done');
+
+    // Re-set the attribute (no false→true edge — it was already true).
+    host.setAttribute('data-validation-invalid', '');
+    await wait(20);
+    expect(spy.count).toBe(0);
+  });
+
+  it('respects data-error-shake-trigger attribute toggle', async () => {
+    const host = mountHost();
+    connectTrait(errorShake, host);
+    const spy = spyEvent(host, 'error-shake-done');
+
+    host.setAttribute('data-error-shake-trigger', '');
+    await wait(0);
+    expect(host.hasAttribute('data-error-shake-active')).toBe(true);
+    await wait(450);
+    expect(spy.count).toBe(1);
+  });
+
+  it('respects data-error-shake-duration config', async () => {
+    const host = mountHost('div', { 'data-error-shake-duration': '100' });
+    connectTrait(errorShake, host);
+    const spy = spyEvent(host, 'error-shake-done');
+
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { valid: false, errors: [''] },
+    }));
+
+    // Should resolve in ~100ms, not the default 400ms.
+    await wait(150);
+    expect(spy.count).toBe(1);
+  });
+
+  it('disconnect clears the keyframe <style> from the document', () => {
+    const host = mountHost();
+    const inst = connectTrait(errorShake, host);
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { valid: false, errors: [''] },
+    }));
+    const styleCount = document.querySelectorAll('style').length;
+    inst.disconnect(host);
+    // After disconnect the keyframe style should be gone — exact count
+    // depends on what other styles exist, so we just assert non-greater.
+    expect(document.querySelectorAll('style').length).toBeLessThan(styleCount + 1);
+    expect(host.style.animation).toBe('');
+  });
+});

package/traits/fade-presence.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { fadePresence } from './fade-presence.js';
-import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
 
 describe('fade-presence', () => {
   beforeEach(resetDOM);

package/traits/focus-restore.js

@@ -0,0 +1,135 @@
+import { defineTrait } from './define.js';
+
+/**
+ * `focus-restore` — capture the previously-focused element on connect,
+ * restore focus to it on disconnect.
+ *
+ * The canonical "modal-close returns focus to the trigger" pattern. Pairs
+ * with `focus-trap` (which holds Tab inside a container) + `portal` (which
+ * moves the container into a top-layer root). focus-restore closes the
+ * loop: when the container goes away, focus returns to where the user was
+ * before it appeared.
+ *
+ * Without this trait, modals / dialogs / drawers leave focus dangling on
+ * `<body>` after dismiss — keyboard users have to tab from the start of
+ * the document to get back to the trigger they pressed.
+ *
+ * On connect:
+ *   1. Captures `document.activeElement` as the restore target.
+ *   2. Sets `data-focus-restore-active` on the host.
+ *   3. (Optional) Moves focus per `data-focus-restore-on-mount`:
+ *      - absent / `"none"`: capture only, don't move focus.
+ *      - `"host"`: focus the host itself.
+ *      - `"first-focusable"`: focus the first tabbable descendant.
+ *
+ * On disconnect:
+ *   1. If the captured target is still in the document AND focusable,
+ *      `el.focus({ preventScroll: true })` it.
+ *   2. Otherwise fall back to `<body>` (or the host's parent if body is
+ *      gone for some reason).
+ *   3. Removes `data-focus-restore-active`.
+ *   4. Dispatches `focus-restored` so consumers can observe.
+ */
+
+const FOCUSABLE_SELECTOR =
+  'a[href], [role="button"][tabindex], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"]), [contenteditable]';
+
+function isFocusable(el) {
+  if (!el || !(el instanceof Element)) return false;
+  if (typeof el.focus !== 'function') return false;
+  if (el.hasAttribute('disabled')) return false;
+  // Element must still be connected to the document for focus to land.
+  if (!el.isConnected) return false;
+  return true;
+}
+
+function findFirstFocusable(host) {
+  // Try descendants in document order.
+  const candidates = host.querySelectorAll(FOCUSABLE_SELECTOR);
+  for (const el of candidates) {
+    if (!el.hasAttribute('disabled')) return el;
+  }
+  return null;
+}
+
+export const focusRestore = defineTrait({
+  name: 'focus-restore',
+  category: 'keyboard-navigation',
+  description:
+    'Capture previously-focused element on connect, restore focus on disconnect',
+  attributes: ['data-focus-restore-active'],
+  events: ['focus-restored'],
+  config: ['data-focus-restore-on-mount'],
+  setup({ host }) {
+    // Capture BEFORE we move focus — otherwise step 3 below would set the
+    // restore target to the host (or first-focusable) and the trait would
+    // restore to itself on disconnect, defeating the contract.
+    const restoreTarget = document.activeElement;
+
+    host.setAttribute('data-focus-restore-active', '');
+
+    const onMount = host.getAttribute('data-focus-restore-on-mount') || 'none';
+    if (onMount === 'host') {
+      // Host needs to be focusable for this to land — common pattern is
+      // tabindex="-1" on the dialog container.
+      try {
+        host.focus({ preventScroll: true });
+      } catch {
+        /* host not focusable — silent no-op, matches focus-trap's tolerance */
+      }
+    } else if (onMount === 'first-focusable') {
+      const first = findFirstFocusable(host);
+      if (first) {
+        try {
+          first.focus({ preventScroll: true });
+        } catch {
+          /* swallow — graceful degrade */
+        }
+      }
+    }
+    // onMount === 'none' (or absent / unrecognized): capture only, don't
+    // move focus. Pointer-opened surfaces shouldn't shift focus on mount.
+
+    return () => {
+      host.removeAttribute('data-focus-restore-active');
+
+      let restoredTo = null;
+
+      if (isFocusable(restoreTarget)) {
+        try {
+          restoreTarget.focus({ preventScroll: true });
+          restoredTo = restoreTarget;
+        } catch {
+          /* fall through to fallback */
+        }
+      }
+
+      if (!restoredTo) {
+        // Fallback: focus body (or host's parent if body is somehow gone).
+        const fallback =
+          (document.body && document.body.isConnected ? document.body : null) ||
+          host.parentElement ||
+          null;
+        if (fallback && typeof fallback.focus === 'function') {
+          try {
+            // <body> needs a tabindex to receive .focus() in some engines;
+            // we don't mutate it (no trait should leave document-level
+            // attribute residue). If focus doesn't land, the browser
+            // gracefully drops to no-active — same as the no-trait baseline.
+            fallback.focus({ preventScroll: true });
+            restoredTo = fallback;
+          } catch {
+            /* nothing more we can do — accept the dangle */
+          }
+        }
+      }
+
+      host.dispatchEvent(
+        new CustomEvent('focus-restored', {
+          bubbles: true,
+          detail: { restoredTo, capturedTarget: restoreTarget },
+        }),
+      );
+    };
+  },
+});