@adia-ai/web-components 0.2.2 → 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.js

@@ -14,10 +14,15 @@ export const springAnimate = defineTrait({
     let rafId = null;
     const target = 0;
 
-    // Read current translate as starting position
+    // Read current translate as starting position. The trait writes to
+    // `style.translate` (not `transform`), so read that first; fall back to
+    // the transform matrix for callers that nudged via `transform`.
     const cs = getComputedStyle(host);
-    const matrix = new DOMMatrixReadOnly(cs.transform);
-    let position = matrix.m41 || 0;
+    let position = parseFloat(cs.translate) || 0;
+    if (!position) {
+      const matrix = new DOMMatrixReadOnly(cs.transform);
+      position = matrix.m41 || 0;
+    }
     let velocity = 0;
 
     host.setAttribute('data-spring-animate-active', '');

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);