@adia-ai/web-components 0.2.3 → 0.2.4

package/traits/success-checkmark.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { successCheckmark } from './success-checkmark.js';
+import { mountHost, connectTrait, spyEvent, resetDOM, wait } from './test-helpers.js';
+
+// Helper: query the SVG that the trait stamps. As of the overflow:hidden
+// fix, the SVG renders at body level (position: fixed) so it can't be
+// clipped by the host's ancestors — query document.body, not the host.
+const findSvg = () => document.body.querySelector('svg');
+
+describe('success-checkmark', () => {
+  beforeEach(resetDOM);
+
+  it('schema declares animation-feedback category', () => {
+    expect(successCheckmark.schema.category).toBe('animation-feedback');
+    expect(successCheckmark.schema.events).toContain('success-checkmark-done');
+    expect(successCheckmark.schema.attributes).toContain('data-success-checkmark-active');
+  });
+
+  it('connect → disconnect leaves no managed attribute', () => {
+    const host = mountHost();
+    const inst = connectTrait(successCheckmark, host);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-success-checkmark-active')).toBe(false);
+  });
+
+  it('stamps an SVG on validated event with detail.valid === true', () => {
+    const host = mountHost();
+    connectTrait(successCheckmark, host);
+
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { valid: true, errors: [] },
+    }));
+
+    expect(host.hasAttribute('data-success-checkmark-active')).toBe(true);
+    const svg = findSvg();
+    expect(svg).not.toBeNull();
+    expect(svg.querySelector('path')).not.toBeNull();
+  });
+
+  it('does not stamp on validated event with detail.valid === false', () => {
+    const host = mountHost();
+    connectTrait(successCheckmark, host);
+
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { valid: false, errors: ['nope'] },
+    }));
+
+    expect(host.hasAttribute('data-success-checkmark-active')).toBe(false);
+    expect(findSvg()).toBeNull();
+  });
+
+  it('fires on data-validation-valid (false → true)', async () => {
+    const host = mountHost();
+    connectTrait(successCheckmark, host);
+
+    host.setAttribute('data-validation-valid', '');
+    await wait(0);
+    expect(host.hasAttribute('data-success-checkmark-active')).toBe(true);
+    expect(findSvg()).not.toBeNull();
+  });
+
+  it('respects data-success-checkmark-trigger attribute toggle', async () => {
+    const host = mountHost();
+    connectTrait(successCheckmark, host);
+
+    host.setAttribute('data-success-checkmark-trigger', '');
+    await wait(0);
+    expect(findSvg()).not.toBeNull();
+  });
+
+  it('renders position: fixed at viewport coordinates (no longer clipped by host overflow)', () => {
+    const host = mountHost();
+    connectTrait(successCheckmark, host);
+
+    host.dispatchEvent(new CustomEvent('validated', {
+      detail: { valid: true, errors: [] },
+    }));
+
+    const svg = findSvg();
+    expect(svg).not.toBeNull();
+    // Body-level rendering with position: fixed escapes any
+    // overflow:hidden ancestor that the host might be inside.
+    expect(svg.style.position).toBe('fixed');
+    expect(svg.parentElement).toBe(document.body);
+  });
+
+  it('removes the SVG and fires success-checkmark-done after the visible+fade window', async () => {
+    const host = mountHost();
+    connectTrait(successCheckmark, host);
+    const spy = spyEvent(host, 'success-checkmark-done');
+
+    host.dispatchEvent(new CustomEvent('validated', { detail: { valid: true } }));
+    expect(findSvg()).not.toBeNull();
+
+    // 1500ms hold + 300ms fade = ~1800ms; give a small grace window.
+    await wait(1900);
+    expect(findSvg()).toBeNull();
+    expect(spy.count).toBe(1);
+    expect(host.hasAttribute('data-success-checkmark-active')).toBe(false);
+  });
+
+  it('disconnect removes any in-flight SVG', () => {
+    const host = mountHost();
+    const inst = connectTrait(successCheckmark, host);
+    host.dispatchEvent(new CustomEvent('validated', { detail: { valid: true } }));
+    expect(findSvg()).not.toBeNull();
+
+    inst.disconnect(host);
+    expect(findSvg()).toBeNull();
+    expect(host.hasAttribute('data-success-checkmark-active')).toBe(false);
+  });
+
+  it('does not mutate host.style.position (body-level rendering means the host needs no positioning context)', () => {
+    const host = mountHost();
+    const before = host.style.position;
+    connectTrait(successCheckmark, host);
+    host.dispatchEvent(new CustomEvent('validated', { detail: { valid: true } }));
+    expect(host.style.position).toBe(before);
+  });
+});

package/traits/tilt-hover.js

@@ -1,5 +1,5 @@
 import { defineTrait } from './define.js';
-import { prefersReducedMotion } from './_motion.js';
+import { prefersReducedMotion } from './motion.js';
 
 export const tiltHover = defineTrait({
   name: 'tilt-hover',

package/traits/tilt-hover.test.js

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

package/traits/tossable.js

@@ -28,7 +28,16 @@ export const tossable = defineTrait({
     let lastClientY = 0;
 
     function parseTranslate() {
+      // The trait writes to `style.translate` (independent of `transform` in
+      // the modern CSS model). Read translate first so subsequent tosses pick
+      // up the current position, then fall back to the transform matrix for
+      // callers that nudged via `transform`.
       const style = getComputedStyle(host);
+      const t = style.translate;
+      if (t && t !== 'none') {
+        const parts = t.split(/\s+/).map(parseFloat);
+        return { x: parts[0] || 0, y: parts[1] || 0 };
+      }
       const matrix = new DOMMatrixReadOnly(style.transform);
       return { x: matrix.m41, y: matrix.m42 };
     }

package/traits/tossable.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { tossable } from './tossable.js';
-import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
 
 function pointer(host, type, x, y) {
   host.dispatchEvent(new PointerEvent(type, { clientX: x, clientY: y, pointerId: 1, bubbles: true }));

package/traits/traits-host.test.js

@@ -10,7 +10,7 @@ import { describe, it, expect, beforeEach } from 'vitest';
 import './traits-host.js';
 import './pressable.js';
 import './hoverable.js';
-import { resetDOM } from './_test-helpers.js';
+import { resetDOM } from './test-helpers.js';
 
 describe('<traits-host>', () => {
   beforeEach(resetDOM);

package/traits/typeahead.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { typeahead } from './typeahead.js';
-import { mountHost, connectTrait, spyEvent, resetDOM, wait } from './_test-helpers.js';
+import { mountHost, connectTrait, spyEvent, resetDOM, wait } from './test-helpers.js';
 
 function child(host, text) {
   const li = document.createElement('div');

package/traits/typewriter.js

@@ -1,5 +1,5 @@
 import { defineTrait } from './define.js';
-import { prefersReducedMotion } from './_motion.js';
+import { prefersReducedMotion } from './motion.js';
 
 export const typewriter = defineTrait({
   name: 'typewriter',

package/traits/typewriter.test.js

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

package/traits/validation.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { validation } from './validation.js';
-import { mountHost, connectTrait, spyEvent, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './test-helpers.js';
 
 function setValue(host, value) {
   host.value = value;

package/traits/view-transition.js

@@ -0,0 +1,140 @@
+import { defineTrait } from './define.js';
+import { prefersReducedMotion } from './motion.js';
+
+/**
+ * `view-transition` — declarative wrapper around the modern
+ * View Transitions API (`document.startViewTransition()`).
+ *
+ * Sets `view-transition-name: <slug>` on the host so the browser tags
+ * this element as a participant in any same-document transition. Reads
+ * configuration from data attributes — `data-view-transition-name`
+ * (the CSS slug), `data-view-transition-duration` (--vt-duration), and
+ * `data-view-transition-easing` (--vt-easing). The trait also installs
+ * a `host.startTransition(callback)` method so consumers can fire a
+ * transition without importing `document.startViewTransition` directly.
+ *
+ * Browser-support shape (project floor at Chromium 125+, Safari 18.0+,
+ * Firefox 129+): same-document is universal, cross-document is
+ * Chromium-only and explicitly out of scope. When the browser lacks
+ * the API, `startTransition()` runs the callback synchronously and
+ * fires start+end back-to-back so caller logic still resolves.
+ *
+ * Reduced-motion is honored automatically by the user-agent CSS
+ * (`view-transition-name: none` under `prefers-reduced-motion: reduce`),
+ * but the trait also detects the preference and runs the no-animation
+ * lifecycle synchronously so consumers can rely on the events.
+ *
+ *   <article-ui traits="view-transition" data-view-transition-name="card-42">
+ *     …
+ *   </article-ui>
+ *
+ *   const article = document.querySelector('article-ui');
+ *   article.startTransition(() => {
+ *     article.classList.add('detail-view');
+ *   });
+ */
+export const viewTransition = defineTrait({
+  name: 'view-transition',
+  category: 'motion-positioning',
+  description:
+    'Wraps document.startViewTransition() for morph animations between DOM states',
+  attributes: ['data-view-transition-active'],
+  events: ['view-transition-start', 'view-transition-end'],
+  config: [
+    'data-view-transition-name',
+    'data-view-transition-duration',
+    'data-view-transition-easing',
+  ],
+  setup({ host }) {
+    // ── Apply CSS configuration ─────────────────────────────────────────
+    // The browser keys participants by the CSS `view-transition-name`
+    // property; we mirror the data-attribute onto the host's inline
+    // style so the value can be set declaratively in markup.
+    const name = host.getAttribute('data-view-transition-name');
+    const duration = host.getAttribute('data-view-transition-duration');
+    const easing = host.getAttribute('data-view-transition-easing');
+
+    const prevName = host.style.viewTransitionName;
+    const prevDur = host.style.getPropertyValue('--vt-duration');
+    const prevEase = host.style.getPropertyValue('--vt-easing');
+
+    if (name) host.style.viewTransitionName = name;
+    if (duration) host.style.setProperty('--vt-duration', duration);
+    if (easing) host.style.setProperty('--vt-easing', easing);
+
+    // ── start / end event helpers ───────────────────────────────────────
+    function fireStart() {
+      host.setAttribute('data-view-transition-active', '');
+      host.dispatchEvent(
+        new CustomEvent('view-transition-start', { bubbles: true }),
+      );
+    }
+    function fireEnd() {
+      host.removeAttribute('data-view-transition-active');
+      host.dispatchEvent(
+        new CustomEvent('view-transition-end', { bubbles: true }),
+      );
+    }
+
+    // ── host.startTransition(callback) ──────────────────────────────────
+    // The unusual-for-a-trait method install. Returns a thin object that
+    // exposes `.finished` so consumers can await transition completion
+    // — matching the shape of `document.startViewTransition()` itself.
+    const supported =
+      typeof document !== 'undefined' &&
+      'startViewTransition' in document;
+
+    function startTransition(callback) {
+      const cb = typeof callback === 'function' ? callback : () => {};
+      const reduced = prefersReducedMotion();
+
+      // Graceful-degrade: no API support OR user prefers reduced motion.
+      // Run the mutation now; emit start+end synchronously so consumers
+      // can rely on the lifecycle even when no animation will play.
+      if (!supported || reduced) {
+        fireStart();
+        try { cb(); } catch (err) { fireEnd(); throw err; }
+        // Use queueMicrotask so callers attaching a one-shot 'view-transition-end'
+        // listener immediately AFTER startTransition() still see the event.
+        const finished = Promise.resolve().then(() => { fireEnd(); });
+        return { finished, ready: finished, updateCallbackDone: finished, skipTransition() {} };
+      }
+
+      // Real path. The browser's startViewTransition() takes the callback,
+      // snapshots the old state, runs the mutation, snapshots the new
+      // state, then morphs between them. We dispatch start synchronously
+      // (the browser has already snapshotted by the time we resume) and
+      // end once the transition resolves.
+      fireStart();
+      const transition = document.startViewTransition(() => cb());
+      transition.finished
+        .then(() => fireEnd())
+        .catch(() => fireEnd()); // user-skipped or thrown — still emit end
+      return transition;
+    }
+
+    // Attach the method. We track whether the host already had one so we
+    // can restore it on disconnect (rare, but keeps cleanup symmetric).
+    const hadStartTransition = Object.prototype.hasOwnProperty.call(
+      host,
+      'startTransition',
+    );
+    const prevStartTransition = host.startTransition;
+    host.startTransition = startTransition;
+
+    return () => {
+      // Restore inline styles
+      host.style.viewTransitionName = prevName;
+      if (prevDur) host.style.setProperty('--vt-duration', prevDur);
+      else host.style.removeProperty('--vt-duration');
+      if (prevEase) host.style.setProperty('--vt-easing', prevEase);
+      else host.style.removeProperty('--vt-easing');
+
+      // Restore the method (or delete if we added it fresh)
+      if (hadStartTransition) host.startTransition = prevStartTransition;
+      else delete host.startTransition;
+
+      host.removeAttribute('data-view-transition-active');
+    };
+  },
+});

package/traits/view-transition.test.js

@@ -0,0 +1,268 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { viewTransition } from './view-transition.js';
+import { _resetMotionCache } from './motion.js';
+import {
+  mountHost,
+  connectTrait,
+  spyEvent,
+  resetDOM,
+  expectValidSchema,
+  wait,
+} from './test-helpers.js';
+
+describe('view-transition', () => {
+  beforeEach(() => {
+    resetDOM();
+    _resetMotionCache();
+    // happy-dom has no startViewTransition; ensure we start clean each test.
+    delete document.startViewTransition;
+  });
+
+  afterEach(() => {
+    delete document.startViewTransition;
+    _resetMotionCache();
+  });
+
+  it('exposes a valid schema', () => {
+    expectValidSchema(viewTransition);
+    expect(viewTransition.schema.name).toBe('view-transition');
+    expect(viewTransition.schema.category).toBe('motion-positioning');
+    expect(viewTransition.schema.events).toContain('view-transition-start');
+    expect(viewTransition.schema.events).toContain('view-transition-end');
+    expect(viewTransition.schema.config).toContain('data-view-transition-name');
+    expect(viewTransition.schema.config).toContain('data-view-transition-duration');
+    expect(viewTransition.schema.config).toContain('data-view-transition-easing');
+  });
+
+  it('writes view-transition-name to the host inline style', () => {
+    const host = mountHost('div', { 'data-view-transition-name': 'card-42' });
+    connectTrait(viewTransition, host);
+    expect(host.style.viewTransitionName).toBe('card-42');
+  });
+
+  it('writes --vt-duration / --vt-easing custom props', () => {
+    const host = mountHost('div', {
+      'data-view-transition-name': 'hero',
+      'data-view-transition-duration': '450ms',
+      'data-view-transition-easing': 'cubic-bezier(0.2, 0.8, 0.2, 1)',
+    });
+    connectTrait(viewTransition, host);
+    expect(host.style.getPropertyValue('--vt-duration')).toBe('450ms');
+    expect(host.style.getPropertyValue('--vt-easing')).toBe(
+      'cubic-bezier(0.2, 0.8, 0.2, 1)',
+    );
+  });
+
+  it('omits CSS props when their data attrs are absent', () => {
+    const host = mountHost('div');
+    connectTrait(viewTransition, host);
+    // happy-dom returns undefined for unset viewTransitionName; real browsers
+    // return ''. Either is acceptable — the contract is "nothing was set."
+    expect(host.style.viewTransitionName || '').toBe('');
+    expect(host.style.getPropertyValue('--vt-duration')).toBe('');
+    expect(host.style.getPropertyValue('--vt-easing')).toBe('');
+  });
+
+  it('installs host.startTransition() method', () => {
+    const host = mountHost();
+    expect(typeof host.startTransition).toBe('undefined');
+    connectTrait(viewTransition, host);
+    expect(typeof host.startTransition).toBe('function');
+  });
+
+  it('removes host.startTransition() on disconnect', () => {
+    const host = mountHost();
+    const inst = connectTrait(viewTransition, host);
+    expect(typeof host.startTransition).toBe('function');
+    inst.disconnect(host);
+    expect(host.startTransition).toBeUndefined();
+  });
+
+  it('runs the callback when the API is missing (feature-detect fallback)', () => {
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    let ran = false;
+    host.startTransition(() => { ran = true; });
+    expect(ran).toBe(true);
+  });
+
+  it('fires start + end events when the API is missing', async () => {
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    const startSpy = spyEvent(host, 'view-transition-start');
+    const endSpy = spyEvent(host, 'view-transition-end');
+    host.startTransition(() => {});
+    // start fires synchronously; end fires on the next microtask.
+    expect(startSpy.count).toBe(1);
+    await Promise.resolve();
+    expect(endSpy.count).toBe(1);
+  });
+
+  it('toggles data-view-transition-active across start → end', async () => {
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    expect(host.hasAttribute('data-view-transition-active')).toBe(false);
+    host.startTransition(() => {
+      // Mutation runs while the attribute is set.
+      expect(host.hasAttribute('data-view-transition-active')).toBe(true);
+    });
+    // The end is queued on a microtask in the fallback path.
+    await Promise.resolve();
+    expect(host.hasAttribute('data-view-transition-active')).toBe(false);
+  });
+
+  it('returns a finished-promise even in the fallback path', async () => {
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    const transition = host.startTransition(() => {});
+    expect(transition).toBeTruthy();
+    expect(transition.finished).toBeInstanceOf(Promise);
+    await expect(transition.finished).resolves.toBeUndefined();
+  });
+
+  it('uses real document.startViewTransition when available', () => {
+    const finished = Promise.resolve();
+    const fakeTransition = { finished, ready: finished, updateCallbackDone: finished };
+    const stub = vi.fn((cb) => { cb(); return fakeTransition; });
+    document.startViewTransition = stub;
+
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    const cb = vi.fn();
+    const result = host.startTransition(cb);
+
+    expect(stub).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(result).toBe(fakeTransition);
+  });
+
+  it('fires end after the real transition resolves', async () => {
+    let resolveFinished;
+    const finished = new Promise((r) => { resolveFinished = r; });
+    document.startViewTransition = (cb) => {
+      cb();
+      return { finished, ready: finished, updateCallbackDone: finished };
+    };
+
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    const endSpy = spyEvent(host, 'view-transition-end');
+
+    host.startTransition(() => {});
+    // End hasn't fired yet — the transition is still in flight.
+    expect(endSpy.count).toBe(0);
+
+    resolveFinished();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(endSpy.count).toBe(1);
+  });
+
+  it('fires end even if the real transition rejects (user-skipped)', async () => {
+    const finished = Promise.reject(new Error('skipped'));
+    // Pre-attach a noop catch so the rejection isn't unhandled in the test runner.
+    finished.catch(() => {});
+    document.startViewTransition = (cb) => {
+      cb();
+      return { finished, ready: finished, updateCallbackDone: finished };
+    };
+
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    const endSpy = spyEvent(host, 'view-transition-end');
+
+    host.startTransition(() => {});
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(endSpy.count).toBe(1);
+  });
+
+  it('runs callback synchronously even with a missing/invalid argument', () => {
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    expect(() => host.startTransition()).not.toThrow();
+    expect(() => host.startTransition('not a function')).not.toThrow();
+  });
+
+  it('honors prefers-reduced-motion: reduce — synchronous lifecycle, no animation', async () => {
+    // Force prefersReducedMotion() to return true.
+    const origMatchMedia = window.matchMedia;
+    window.matchMedia = (q) => ({
+      matches: typeof q === 'string' && q.includes('prefers-reduced-motion'),
+      media: q,
+      addEventListener() {},
+      removeEventListener() {},
+      addListener() {},
+      removeListener() {},
+      dispatchEvent() { return false; },
+      onchange: null,
+    });
+    _resetMotionCache();
+
+    // Even if the API is "available", reduced-motion takes the fallback path.
+    document.startViewTransition = vi.fn();
+
+    const host = mountHost();
+    connectTrait(viewTransition, host);
+    const startSpy = spyEvent(host, 'view-transition-start');
+    const endSpy = spyEvent(host, 'view-transition-end');
+    let ran = false;
+    host.startTransition(() => { ran = true; });
+
+    expect(ran).toBe(true);
+    expect(startSpy.count).toBe(1);
+    await Promise.resolve();
+    expect(endSpy.count).toBe(1);
+    expect(document.startViewTransition).not.toHaveBeenCalled();
+
+    window.matchMedia = origMatchMedia;
+    _resetMotionCache();
+  });
+
+  it('disconnect clears active attr and restores inline styles', () => {
+    const host = mountHost('div', {
+      'data-view-transition-name': 'card-9',
+      'data-view-transition-duration': '300ms',
+    });
+    const inst = connectTrait(viewTransition, host);
+    // Force the attribute on so disconnect's cleanup is observable.
+    host.setAttribute('data-view-transition-active', '');
+    inst.disconnect(host);
+
+    expect(host.hasAttribute('data-view-transition-active')).toBe(false);
+    expect(host.style.viewTransitionName || '').toBe('');
+    expect(host.style.getPropertyValue('--vt-duration')).toBe('');
+  });
+
+  it('does not clobber an existing host.startTransition; restores it on disconnect', () => {
+    const host = mountHost();
+    const sentinel = () => 'pre-existing';
+    host.startTransition = sentinel;
+    const inst = connectTrait(viewTransition, host);
+    expect(host.startTransition).not.toBe(sentinel); // trait took over
+    inst.disconnect(host);
+    expect(host.startTransition).toBe(sentinel); // restored
+  });
+
+  it('connect → disconnect → connect-again does not throw', () => {
+    const host = mountHost('div', { 'data-view-transition-name': 'a' });
+    const inst1 = connectTrait(viewTransition, host);
+    inst1.disconnect(host);
+    expect(() => {
+      const inst2 = connectTrait(viewTransition, host);
+      inst2.disconnect(host);
+    }).not.toThrow();
+  });
+
+  it('two parallel hosts each get their own startTransition', () => {
+    const a = mountHost();
+    const b = mountHost();
+    const instA = connectTrait(viewTransition, a);
+    const instB = connectTrait(viewTransition, b);
+    expect(typeof a.startTransition).toBe('function');
+    expect(typeof b.startTransition).toBe('function');
+    expect(a.startTransition).not.toBe(b.startTransition);
+    instA.disconnect(a);
+    instB.disconnect(b);
+  });
+});