@adia-ai/web-components 0.2.3 → 0.2.4

package/traits/scale-press.test.js

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

package/traits/scroll-lock.test.js

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

package/traits/scroll-progress.js

@@ -0,0 +1,201 @@
+import { defineTrait } from './define.js';
+
+/**
+ * scroll-progress — surfaces page or element scroll progress as a 0..1
+ * attribute, CSS custom property, and event. Building block for sticky
+ * headers, ToC highlighting, scroll-linked animations, and reading-time
+ * indicators.
+ *
+ * Modes (via `data-scroll-progress-mode`):
+ *   - "in-view" (default) — 0 = host top edge meets viewport bottom;
+ *     1 = host bottom edge crosses viewport top. Useful for fade-in /
+ *     parallax-on-scroll patterns.
+ *   - "page" — 0 = page at top, 1 = page fully scrolled. Independent of
+ *     host position.
+ *   - "scrolled" — 0 = host content scrollTop is 0, 1 = fully scrolled.
+ *     For overflow:auto containers.
+ *
+ * Container override (`data-scroll-container`) accepts a CSS selector;
+ * resolves to the scrolling ancestor explicitly. Falls back to the
+ * nearest auto/scroll overflow ancestor or `window`.
+ *
+ * Throttling — scroll events fire frequently. The trait coalesces
+ * updates via rAF: at most one progress update per frame. Cleanup
+ * cancels any pending rAF + removes the listener.
+ */
+export const scrollProgress = defineTrait({
+  name: 'scroll-progress',
+  category: 'layout-measurement',
+  description: 'Page or element scroll progress as 0..1 attribute + CSS variable + event',
+  attributes: ['data-scroll-progress-active', 'data-scroll-progress'],
+  events: ['scroll-progress'],
+  config: ['data-scroll-progress-mode', 'data-scroll-container'],
+  setup({ host }) {
+    const mode = host.getAttribute('data-scroll-progress-mode') || 'in-view';
+    const containerSelector = host.getAttribute('data-scroll-container');
+
+    // Resolve scroll container — explicit selector wins; otherwise walk
+    // up looking for an overflow:auto/scroll ancestor; fall back to window.
+    function resolveContainer() {
+      if (containerSelector) {
+        try {
+          const root = host.getRootNode?.() || document;
+          const node = root.querySelector?.(containerSelector)
+            || document.querySelector(containerSelector);
+          if (node) return node;
+        } catch {
+          // Invalid selector — fall through.
+        }
+      }
+      let node = host.parentElement;
+      while (node) {
+        const style = (typeof getComputedStyle === 'function')
+          ? getComputedStyle(node)
+          : null;
+        if (style) {
+          const flow = style.overflow + style.overflowY + style.overflowX;
+          if (/(auto|scroll)/.test(flow)) return node;
+        }
+        node = node.parentElement;
+      }
+      return (typeof window !== 'undefined') ? window : null;
+    }
+
+    const container = resolveContainer();
+    if (!container) {
+      // No place to listen — mark active and bail. Keeps cleanup
+      // contract intact (attribute is still removed on disconnect).
+      host.setAttribute('data-scroll-progress-active', '');
+      return () => {
+        host.removeAttribute('data-scroll-progress-active');
+        host.removeAttribute('data-scroll-progress');
+        host.style.removeProperty('--scroll-progress');
+      };
+    }
+
+    const isWindow = container === (typeof window !== 'undefined' ? window : null);
+
+    function clamp01(v) {
+      if (!Number.isFinite(v)) return 0;
+      if (v < 0) return 0;
+      if (v > 1) return 1;
+      return v;
+    }
+
+    function compute() {
+      // "page" — scrollY / (scrollHeight - innerHeight)
+      if (mode === 'page') {
+        if (isWindow) {
+          const max = (document.documentElement.scrollHeight || 0) - (window.innerHeight || 0);
+          if (max <= 0) return 0;
+          return clamp01((window.scrollY || 0) / max);
+        }
+        const max = (container.scrollHeight || 0) - (container.clientHeight || 0);
+        if (max <= 0) return 0;
+        return clamp01((container.scrollTop || 0) / max);
+      }
+
+      // "scrolled" — host's own scrollTop / max-scroll
+      if (mode === 'scrolled') {
+        const max = (host.scrollHeight || 0) - (host.clientHeight || 0);
+        if (max <= 0) return 0;
+        return clamp01((host.scrollTop || 0) / max);
+      }
+
+      // "in-view" (default) — 0 when host top meets viewport bottom,
+      // 1 when host bottom crosses viewport top.
+      // We measure the host rect against the container's viewport.
+      if (typeof host.getBoundingClientRect !== 'function') return 0;
+      const rect = host.getBoundingClientRect();
+      let viewTop;
+      let viewBottom;
+      if (isWindow) {
+        viewTop = 0;
+        viewBottom = window.innerHeight || 0;
+      } else if (typeof container.getBoundingClientRect === 'function') {
+        const cRect = container.getBoundingClientRect();
+        viewTop = cRect.top;
+        viewBottom = cRect.bottom;
+      } else {
+        viewTop = 0;
+        viewBottom = window.innerHeight || 0;
+      }
+
+      const viewHeight = viewBottom - viewTop;
+      const total = viewHeight + (rect.height || 0);
+      if (total <= 0) return 0;
+
+      // Distance from "host fully below view" to current position.
+      // When rect.top === viewBottom → 0. When rect.bottom === viewTop → 1.
+      const distance = viewBottom - rect.top;
+      return clamp01(distance / total);
+    }
+
+    let rafId = null;
+    let lastWritten = -1;
+
+    function update() {
+      rafId = null;
+      const progress = compute();
+      // De-dup writes when nothing meaningful changed (3-decimal precision
+      // is enough for any visual or reading-progress consumer).
+      const rounded = Math.round(progress * 1000) / 1000;
+      if (rounded === lastWritten) return;
+      lastWritten = rounded;
+
+      const str = rounded.toFixed(3);
+      host.setAttribute('data-scroll-progress', str);
+      host.style.setProperty('--scroll-progress', str);
+      host.dispatchEvent(new CustomEvent('scroll-progress', {
+        bubbles: true,
+        detail: { progress: rounded },
+      }));
+    }
+
+    function schedule() {
+      if (rafId !== null) return;
+      if (typeof requestAnimationFrame === 'function') {
+        rafId = requestAnimationFrame(update);
+      } else {
+        // Fallback for environments without rAF — write synchronously.
+        update();
+      }
+    }
+
+    const target = container;
+    const listenerOpts = { passive: true };
+
+    target.addEventListener?.('scroll', schedule, listenerOpts);
+    // For "scrolled" mode the host itself is the scroll surface — also
+    // listen on host so progress updates without requiring the resolved
+    // container to be the host.
+    if (mode === 'scrolled' && target !== host) {
+      host.addEventListener?.('scroll', schedule, listenerOpts);
+    }
+    // Window resize affects in-view + page math; update on resize too.
+    if (typeof window !== 'undefined') {
+      window.addEventListener?.('resize', schedule, listenerOpts);
+    }
+
+    host.setAttribute('data-scroll-progress-active', '');
+    // Seed the initial value on next frame so first paint has the value.
+    schedule();
+
+    return () => {
+      if (rafId !== null && typeof cancelAnimationFrame === 'function') {
+        cancelAnimationFrame(rafId);
+      }
+      rafId = null;
+      target.removeEventListener?.('scroll', schedule, listenerOpts);
+      if (mode === 'scrolled' && target !== host) {
+        host.removeEventListener?.('scroll', schedule, listenerOpts);
+      }
+      if (typeof window !== 'undefined') {
+        window.removeEventListener?.('resize', schedule, listenerOpts);
+      }
+      host.removeAttribute('data-scroll-progress-active');
+      host.removeAttribute('data-scroll-progress');
+      host.style.removeProperty('--scroll-progress');
+    };
+  },
+});

package/traits/scroll-progress.test.js

@@ -0,0 +1,182 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { scrollProgress } from './scroll-progress.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './test-helpers.js';
+
+describe('scroll-progress', () => {
+  let originalRAF;
+  let originalCAF;
+
+  beforeEach(() => {
+    resetDOM();
+    // Synchronous rAF — the trait's scheduler calls back immediately so
+    // we can assert post-update side-effects without awaiting frames.
+    originalRAF = globalThis.requestAnimationFrame;
+    originalCAF = globalThis.cancelAnimationFrame;
+    globalThis.requestAnimationFrame = (fn) => { fn(performance.now?.() ?? 0); return 1; };
+    globalThis.cancelAnimationFrame = vi.fn();
+  });
+
+  afterEach(() => {
+    globalThis.requestAnimationFrame = originalRAF;
+    globalThis.cancelAnimationFrame = originalCAF;
+  });
+
+  it('connect sets data-scroll-progress-active', () => {
+    const host = mountHost();
+    connectTrait(scrollProgress, host);
+    expect(host.hasAttribute('data-scroll-progress-active')).toBe(true);
+  });
+
+  it('disconnect clears active + progress + CSS variable', () => {
+    const host = mountHost();
+    const inst = connectTrait(scrollProgress, host);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-scroll-progress-active')).toBe(false);
+    expect(host.hasAttribute('data-scroll-progress')).toBe(false);
+    expect(host.style.getPropertyValue('--scroll-progress')).toBe('');
+  });
+
+  it('writes data-scroll-progress as a 0..1 string after connect', () => {
+    const host = mountHost();
+    connectTrait(scrollProgress, host);
+    // Synchronous rAF means the seed update has already run.
+    const v = host.getAttribute('data-scroll-progress');
+    expect(v).not.toBeNull();
+    const n = parseFloat(v);
+    expect(n).toBeGreaterThanOrEqual(0);
+    expect(n).toBeLessThanOrEqual(1);
+  });
+
+  it('writes the --scroll-progress CSS custom property', () => {
+    const host = mountHost();
+    connectTrait(scrollProgress, host);
+    const css = host.style.getPropertyValue('--scroll-progress');
+    expect(css).not.toBe('');
+    const n = parseFloat(css);
+    expect(n).toBeGreaterThanOrEqual(0);
+    expect(n).toBeLessThanOrEqual(1);
+  });
+
+  it('dispatches a scroll-progress event with { progress } detail', () => {
+    const host = mountHost();
+    const spy = spyEvent(host, 'scroll-progress');
+    connectTrait(scrollProgress, host);
+    // Initial seed fires once via synchronous rAF.
+    expect(spy.count).toBeGreaterThanOrEqual(1);
+    expect(typeof spy.last.progress).toBe('number');
+    expect(spy.last.progress).toBeGreaterThanOrEqual(0);
+    expect(spy.last.progress).toBeLessThanOrEqual(1);
+  });
+
+  it('mode="page" falls back to 0 when scroll range is zero', () => {
+    const host = mountHost('div', { 'data-scroll-progress-mode': 'page' });
+    connectTrait(scrollProgress, host);
+    // happy-dom reports zero scroll geometry by default.
+    expect(host.getAttribute('data-scroll-progress')).toBe('0.000');
+  });
+
+  it('mode="scrolled" reports 0..1 from host scrollTop / max', () => {
+    const host = mountHost('div', { 'data-scroll-progress-mode': 'scrolled' });
+    // Stub the geometry — happy-dom returns zeros for scroll metrics.
+    Object.defineProperty(host, 'scrollHeight', { configurable: true, value: 1000 });
+    Object.defineProperty(host, 'clientHeight', { configurable: true, value: 200 });
+    Object.defineProperty(host, 'scrollTop', { configurable: true, value: 200, writable: true });
+    connectTrait(scrollProgress, host);
+    const v = parseFloat(host.getAttribute('data-scroll-progress'));
+    // 200 / (1000 - 200) = 0.25
+    expect(v).toBeCloseTo(0.25, 2);
+  });
+
+  it('mode="in-view" clamps to [0,1] for offscreen rects', () => {
+    const host = mountHost();
+    // Far below the viewport.
+    host.getBoundingClientRect = () => ({ top: 99999, bottom: 100099, left: 0, right: 0, width: 0, height: 100, x: 0, y: 99999, toJSON() { return {}; } });
+    connectTrait(scrollProgress, host);
+    expect(parseFloat(host.getAttribute('data-scroll-progress'))).toBe(0);
+  });
+
+  it('mode="in-view" reports 1 for rects fully scrolled past', () => {
+    const host = mountHost();
+    // Far above the viewport.
+    host.getBoundingClientRect = () => ({ top: -2000, bottom: -1900, left: 0, right: 0, width: 0, height: 100, x: 0, y: -2000, toJSON() { return {}; } });
+    // Make sure window.innerHeight is sane.
+    Object.defineProperty(window, 'innerHeight', { configurable: true, value: 800 });
+    connectTrait(scrollProgress, host);
+    expect(parseFloat(host.getAttribute('data-scroll-progress'))).toBe(1);
+  });
+
+  it('data-scroll-container selector resolves an explicit ancestor', () => {
+    document.body.innerHTML = '<div id="custom-scroller" style="overflow:auto;"><div id="inner"></div></div>';
+    const host = document.getElementById('inner');
+    host.setAttribute('data-scroll-container', '#custom-scroller');
+    const scroller = document.getElementById('custom-scroller');
+    const addSpy = vi.spyOn(scroller, 'addEventListener');
+    connectTrait(scrollProgress, host);
+    // The trait should attach a scroll listener to the resolved container.
+    const calls = addSpy.mock.calls.filter(([type]) => type === 'scroll');
+    expect(calls.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('invalid data-scroll-container selector falls through to ancestor walk', () => {
+    document.body.innerHTML = '<div id="parent" style="overflow:auto;"><div id="child"></div></div>';
+    const host = document.getElementById('child');
+    host.setAttribute('data-scroll-container', '###not-a-valid-selector');
+    expect(() => connectTrait(scrollProgress, host)).not.toThrow();
+  });
+
+  it('schedules through rAF — second scroll within the same frame coalesces', () => {
+    let queued = 0;
+    let pending = null;
+    globalThis.requestAnimationFrame = (fn) => {
+      queued++;
+      pending = fn;
+      return queued;
+    };
+    globalThis.cancelAnimationFrame = vi.fn();
+    const host = mountHost();
+    const inst = connectTrait(scrollProgress, host);
+    const baseline = queued;
+    // Fire two scroll events back-to-back without flushing the rAF.
+    window.dispatchEvent(new Event('scroll'));
+    window.dispatchEvent(new Event('scroll'));
+    // Only one rAF should be queued in addition to the seed.
+    expect(queued - baseline).toBeLessThanOrEqual(1);
+    // Flush manually so disconnect has nothing pending.
+    if (pending) pending(0);
+    inst.disconnect(host);
+  });
+
+  it('disconnect cancels the pending rAF', () => {
+    let pendingId = null;
+    globalThis.requestAnimationFrame = () => { pendingId = 42; return 42; };
+    const cancelSpy = vi.fn();
+    globalThis.cancelAnimationFrame = cancelSpy;
+    const host = mountHost();
+    const inst = connectTrait(scrollProgress, host);
+    inst.disconnect(host);
+    // The trait queued one rAF on connect; disconnect should cancel it.
+    expect(cancelSpy).toHaveBeenCalled();
+  });
+
+  it('disconnect removes the scroll listener from the resolved container', () => {
+    document.body.innerHTML = '<div id="scr" style="overflow:auto;"><div id="h"></div></div>';
+    const host = document.getElementById('h');
+    host.setAttribute('data-scroll-container', '#scr');
+    const scroller = document.getElementById('scr');
+    const removeSpy = vi.spyOn(scroller, 'removeEventListener');
+    const inst = connectTrait(scrollProgress, host);
+    inst.disconnect(host);
+    const calls = removeSpy.mock.calls.filter(([type]) => type === 'scroll');
+    expect(calls.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('reconnect after disconnect does not throw and restores the active flag', () => {
+    const host = mountHost();
+    const inst1 = connectTrait(scrollProgress, host);
+    inst1.disconnect(host);
+    const inst2 = connectTrait(scrollProgress, host);
+    expect(host.hasAttribute('data-scroll-progress-active')).toBe(true);
+    inst2.disconnect(host);
+    expect(host.hasAttribute('data-scroll-progress-active')).toBe(false);
+  });
+});

package/traits/shimmer-loading.js

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

package/traits/shimmer-loading.test.js

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

package/traits/{_smoke.test.js → smoke.test.js}

@@ -8,7 +8,7 @@
 
 import { describe, it, expect, beforeEach } from 'vitest';
 import * as traits from './index.js';
-import { mountHost, connectTrait, expectValidSchema, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, expectValidSchema, resetDOM } from './test-helpers.js';
 
 const KNOWN_CATEGORIES = new Set([
   'input-interaction',

package/traits/snap-to-grid.test.js

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

package/traits/sound-feedback.test.js

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

package/traits/spring-animate.test.js

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

package/traits/success-checkmark.js

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