npm - @adia-ai/web-components - Versions diffs - 0.2.2 → 0.2.4 - Mend

@adia-ai/web-components 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

package/components/agent-trace/agent-trace.css +24 -3
package/components/button/button.js +3 -0
package/components/demo-toggle/demo-toggle.a2ui.json +144 -0
package/components/demo-toggle/demo-toggle.css +120 -0
package/components/demo-toggle/demo-toggle.js +144 -0
package/components/demo-toggle/demo-toggle.test.js +102 -0
package/components/demo-toggle/demo-toggle.yaml +144 -0
package/components/index.js +1 -0
package/components/input/input.js +11 -0
package/components/list/list.css +66 -3
package/components/nav-group/nav-group.a2ui.json +1 -1
package/components/nav-group/nav-group.css +5 -5
package/components/nav-group/nav-group.yaml +1 -1
package/components/nav-item/nav-item.a2ui.json +1 -1
package/components/nav-item/nav-item.css +3 -4
package/components/nav-item/nav-item.yaml +1 -1
package/components/textarea/textarea.js +10 -0
package/core/icons.js +13 -1
package/package.json +1 -1
package/styles/components.css +1 -0
package/styles/typography.css +1 -1
package/traits/_catalog.json +258 -5
package/traits/active-state.test.js +1 -1
package/traits/anchor-positioning.js +205 -52
package/traits/anchor-positioning.test.js +77 -4
package/traits/announcer-stage.js +157 -0
package/traits/announcer.js +145 -0
package/traits/announcer.test.js +268 -0
package/traits/arrow-grid-nav.js +234 -0
package/traits/arrow-grid-nav.test.js +375 -0
package/traits/attention-pulse.js +1 -1
package/traits/attention-pulse.test.js +1 -1
package/traits/confetti-burst.js +90 -60
package/traits/confetti-burst.test.js +16 -8
package/traits/confetti-stage.js +143 -0
package/traits/confetti.js +44 -47
package/traits/confetti.test.js +24 -5
package/traits/count-up.js +31 -6
package/traits/count-up.test.js +1 -1
package/traits/declarative.test.js +1 -1
package/traits/dirty-state.test.js +1 -1
package/traits/drag-ghost.js +55 -3
package/traits/drag-ghost.test.js +1 -1
package/traits/draggable-list-item.js +279 -0
package/traits/draggable-list-item.test.js +51 -0
package/traits/draggable.js +14 -4
package/traits/draggable.test.js +1 -1
package/traits/drop-target.js +223 -0
package/traits/drop-target.test.js +241 -0
package/traits/droppable-collection.js +89 -0
package/traits/droppable-collection.test.js +99 -0
package/traits/droppable.js +125 -0
package/traits/droppable.test.js +54 -0
package/traits/error-shake.js +157 -0
package/traits/error-shake.test.js +114 -0
package/traits/fade-presence.test.js +1 -1
package/traits/focus-restore.js +135 -0
package/traits/focus-restore.test.js +202 -0
package/traits/focus-trap.test.js +1 -1
package/traits/focusable.test.js +1 -1
package/traits/glow-focus.js +1 -1
package/traits/glow-focus.test.js +1 -1
package/traits/gradient-shift.js +1 -1
package/traits/gradient-shift.test.js +1 -1
package/traits/haptic-feedback.test.js +1 -1
package/traits/hotkey.test.js +1 -1
package/traits/hoverable.test.js +1 -1
package/traits/index.js +15 -0
package/traits/inertia-drag.js +9 -0
package/traits/inertia-drag.test.js +1 -1
package/traits/input-mask.js +328 -0
package/traits/input-mask.test.js +151 -0
package/traits/intersection-observer.test.js +1 -1
package/traits/keyboard-nav.test.js +1 -1
package/traits/keyboard-reorderable.js +254 -0
package/traits/keyboard-reorderable.test.js +45 -0
package/traits/layout-animation.js +229 -0
package/traits/layout-animation.test.js +114 -0
package/traits/long-press.js +212 -0
package/traits/long-press.test.js +244 -0
package/traits/magnetic-hover.js +1 -1
package/traits/magnetic-hover.test.js +1 -1
package/traits/noise-texture.js +7 -3
package/traits/noise-texture.test.js +1 -1
package/traits/parallax.js +1 -1
package/traits/parallax.test.js +1 -1
package/traits/portal.test.js +1 -1
package/traits/pressable.test.js +1 -1
package/traits/resettable.js +29 -3
package/traits/resettable.test.js +34 -1
package/traits/resizable.test.js +1 -1
package/traits/resize-observer.test.js +1 -1
package/traits/ripple.js +1 -1
package/traits/ripple.test.js +1 -1
package/traits/roving-tabindex.test.js +1 -1
package/traits/scale-press.test.js +1 -1
package/traits/scroll-lock.test.js +1 -1
package/traits/scroll-progress.js +201 -0
package/traits/scroll-progress.test.js +182 -0
package/traits/shimmer-loading.js +1 -1
package/traits/shimmer-loading.test.js +1 -1
package/traits/{_smoke.test.js → smoke.test.js} +1 -1
package/traits/snap-to-grid.test.js +1 -1
package/traits/sound-feedback.test.js +1 -1
package/traits/spring-animate.js +8 -3
package/traits/spring-animate.test.js +1 -1
package/traits/success-checkmark.js +222 -0
package/traits/success-checkmark.test.js +120 -0
package/traits/tilt-hover.js +1 -1
package/traits/tilt-hover.test.js +1 -1
package/traits/tossable.js +9 -0
package/traits/tossable.test.js +1 -1
package/traits/traits-host.test.js +1 -1
package/traits/typeahead.test.js +1 -1
package/traits/typewriter.js +1 -1
package/traits/typewriter.test.js +1 -1
package/traits/validation.test.js +1 -1
package/traits/view-transition.js +140 -0
package/traits/view-transition.test.js +268 -0
/package/traits/{_motion.js → motion.js} +0 -0
/package/traits/{_test-helpers.js → test-helpers.js} +0 -0

package/traits/success-checkmark.js ADDED Viewed

@@ -0,0 +1,222 @@
+import { defineTrait } from './define.js';
+import { prefersReducedMotion } from './motion.js';
+/**
+ * `success-checkmark` — SVG path stroke-draw animation. "I confirmed it
+ * worked." Pairs with the `validation` trait's success branch and any
+ * imperative success milestone (form-saved, payment-confirmed,
+ * email-sent).
+ *
+ * Listens for `validated` with `detail.valid === true`, watches the
+ * `data-success-checkmark-trigger` attribute for toggles, and
+ * declares a `data-success-checkmark-position` config attribute
+ * (`top-right` default, or `center`) to anchor the SVG overlay.
+ *
+ * On trigger:
+ *   1. Stamp an absolutely-positioned SVG checkmark on the host.
+ *   2. Animate stroke-dashoffset from full path length → 0 over ~400ms.
+ *   3. After ~1.5s total, fade opacity 1 → 0 over 300ms.
+ *   4. Remove the SVG, dispatch `success-checkmark-done`.
+ *
+ * Reduced-motion: render the checkmark instantly (no stroke-draw),
+ * still fade out cleanly. The done event fires either way so caller
+ * logic gated on it doesn't stall.
+ *
+ * Composes naturally with `validation`:
+ *   <input-ui traits="validation success-checkmark" data-validate="email">
+ */
+const STROKE_DRAW_MS = 400;
+const VISIBLE_HOLD_MS = 1500; // total visible time before fade starts
+const FADE_OUT_MS = 300;
+const PATH_LENGTH = 36;       // approximate path length for the checkmark below
+// Style ID — checkmark keyframes are shared across all instances since
+// they don't carry per-host config. Mounted once into <head>, never removed
+// (cheap, dedupe by id).
+const SHARED_STYLE_ID = 'adia-success-checkmark-keyframes';
+function ensureSharedStyles() {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(SHARED_STYLE_ID)) return;
+  const style = document.createElement('style');
+  style.id = SHARED_STYLE_ID;
+  style.textContent = `
+    @keyframes adia-success-checkmark-draw {
+      from { stroke-dashoffset: ${PATH_LENGTH}; }
+      to   { stroke-dashoffset: 0; }
+    }
+    @keyframes adia-success-checkmark-fade {
+      from { opacity: 1; }
+      to   { opacity: 0; }
+    }
+  `;
+  document.head.appendChild(style);
+}
+function buildSvg(position, reduced, hostRect) {
+  const SVG_NS = 'http://www.w3.org/2000/svg';
+  const svg = document.createElementNS(SVG_NS, 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('width', '24');
+  svg.setAttribute('height', '24');
+  svg.setAttribute('aria-hidden', 'true');
+  // Render in viewport coordinates against the body so `overflow: hidden`
+  // ancestors (cards, buttons, drawers) can't clip the checkmark. The
+  // anchor is the host's getBoundingClientRect() at draw time — for the
+  // ~1.8s animation window the host is unlikely to move enough to matter.
+  let top, left;
+  if (position === 'center') {
+    top  = hostRect.top + hostRect.height / 2 - 12;
+    left = hostRect.left + hostRect.width / 2 - 12;
+  } else {
+    // top-right (default) — protrude beyond the corner by ~8px so the
+    // checkmark reads as an applied stamp, not a content element.
+    top  = hostRect.top - 8;
+    left = hostRect.right - 16;
+  }
+  svg.style.cssText = `
+    position: fixed;
+    top: ${top}px;
+    left: ${left}px;
+    pointer-events: none;
+    color: var(--a-success, #22c55e);
+    z-index: 99999;
+  `;
+  // Optional disc background — gives the checkmark a visible bedding
+  // when stamped on photographic or low-contrast hosts.
+  const circle = document.createElementNS(SVG_NS, 'circle');
+  circle.setAttribute('cx', '12');
+  circle.setAttribute('cy', '12');
+  circle.setAttribute('r', '11');
+  circle.setAttribute('fill', 'currentColor');
+  svg.appendChild(circle);
+  const path = document.createElementNS(SVG_NS, 'path');
+  // ~36 unit path: M6 12 L10 16 L18 8.
+  path.setAttribute('d', 'M6 12 L10 16 L18 8');
+  path.setAttribute('fill', 'none');
+  path.setAttribute('stroke', 'var(--a-success-fg, white)');
+  path.setAttribute('stroke-width', '2.5');
+  path.setAttribute('stroke-linecap', 'round');
+  path.setAttribute('stroke-linejoin', 'round');
+  path.setAttribute('stroke-dasharray', String(PATH_LENGTH));
+  if (reduced) {
+    // Render the checkmark instantly — no stroke-draw — but still let
+    // the fade-out keyframe run so the surface tears down gracefully.
+    path.setAttribute('stroke-dashoffset', '0');
+  } else {
+    path.setAttribute('stroke-dashoffset', String(PATH_LENGTH));
+    path.style.animation = `adia-success-checkmark-draw ${STROKE_DRAW_MS}ms ease-out forwards`;
+  }
+  svg.appendChild(path);
+  return svg;
+}
+export const successCheckmark = defineTrait({
+  name: 'success-checkmark',
+  category: 'animation-feedback',
+  description: 'Stroke-draw checkmark on validation success',
+  attributes: ['data-success-checkmark-active'],
+  events: ['success-checkmark-done'],
+  config: ['data-success-checkmark-position', 'data-success-checkmark-trigger'],
+  setup({ host }) {
+    const activeTimers = new Set();
+    const liveSvgs = new Set();
+    let lastValid = host.hasAttribute('data-validation-valid');
+    function readPosition() {
+      const v = host.getAttribute('data-success-checkmark-position');
+      return v === 'center' ? 'center' : 'top-right';
+    }
+    function fireDone() {
+      // Only clear active when no in-flight checkmark remains.
+      if (liveSvgs.size === 0) host.removeAttribute('data-success-checkmark-active');
+      host.dispatchEvent(new CustomEvent('success-checkmark-done', { bubbles: true }));
+    }
+    function teardownSvg(svg) {
+      liveSvgs.delete(svg);
+      svg.remove();
+      fireDone();
+    }
+    function draw() {
+      ensureSharedStyles();
+      const reduced = prefersReducedMotion();
+      const position = readPosition();
+      // Anchor against host's viewport rect at trigger time. Detached
+      // or happy-dom hosts return zero rects, which renders the SVG at
+      // the viewport origin — fine for tests, fine in real browsers
+      // because real hosts have real rects.
+      const hostRect = host.getBoundingClientRect?.() ||
+        { top: 0, left: 0, right: 0, bottom: 0, width: 0, height: 0 };
+      const svg = buildSvg(position, reduced, hostRect);
+      // Append at body level so overflow:hidden ancestors can't clip.
+      document.body.appendChild(svg);
+      liveSvgs.add(svg);
+      host.setAttribute('data-success-checkmark-active', '');
+      // After the visible-hold window, kick off the fade-out. Use a
+      // single timer rather than chaining animationend so detached or
+      // early-removed SVGs don't strand listeners.
+      const fadeStart = setTimeout(() => {
+        activeTimers.delete(fadeStart);
+        if (!liveSvgs.has(svg)) return;
+        svg.style.animation = `adia-success-checkmark-fade ${FADE_OUT_MS}ms ease-out forwards`;
+        const fadeEnd = setTimeout(() => {
+          activeTimers.delete(fadeEnd);
+          if (liveSvgs.has(svg)) teardownSvg(svg);
+        }, FADE_OUT_MS);
+        activeTimers.add(fadeEnd);
+      }, VISIBLE_HOLD_MS);
+      activeTimers.add(fadeStart);
+    }
+    function onValidated(e) {
+      if (e?.detail && e.detail.valid === true) draw();
+    }
+    // Watch data-validation-valid (false → true) + the manual trigger.
+    const observer = new MutationObserver((muts) => {
+      for (const m of muts) {
+        if (m.attributeName === 'data-validation-valid') {
+          const nowValid = host.hasAttribute('data-validation-valid');
+          if (nowValid && !lastValid) draw();
+          lastValid = nowValid;
+        } else if (m.attributeName === 'data-success-checkmark-trigger') {
+          if (host.hasAttribute('data-success-checkmark-trigger')) draw();
+        }
+      }
+    });
+    observer.observe(host, {
+      attributes: true,
+      attributeFilter: ['data-validation-valid', 'data-success-checkmark-trigger'],
+    });
+    host.addEventListener('validated', onValidated);
+    return () => {
+      observer.disconnect();
+      host.removeEventListener('validated', onValidated);
+      for (const t of activeTimers) clearTimeout(t);
+      activeTimers.clear();
+      // SVGs live at body level (not host), so removing them is the
+      // only cleanup needed — no host.style.position to restore.
+      for (const svg of liveSvgs) svg.remove();
+      liveSvgs.clear();
+      host.removeAttribute('data-success-checkmark-active');
+    };
+  },
+});

package/traits/success-checkmark.test.js ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

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