use-scroll-animate 5.1.0 → 5.3.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.3.0] - 2026-10-08
+
+### Added
+- **Page-wide pack** (`use-scroll-animate/components/effects`, `registerPageEffects()`, `PAGE_FX`):
+  - Transitions — `curtain`, `iris` (closes on the click point), `pixel-dissolve` (`cols` × `rows`), `blinds` (`slats`). Each covers the viewport, awaits `onCovered()` (swap your route / content there), optionally `hold`s, then reveals; `playEffect()` resolves when the page is visible again.
+  - Persistent — `velocity-skew` (skews with scroll speed, eases back), `spotlight` (dims everything but a circle at the pointer), `edge-glow` (lights the viewport edge you scroll toward).
+- Showcase: **Page transitions** and **Velocity skew & edge glow** cards.
+
+### Accessibility
+- Transition layers are `aria-hidden`; under reduced motion every transition becomes a 150 ms cross-fade that still calls `onCovered()`. `velocity-skew`, `spotlight` and `edge-glow` don’t run under reduced motion.
+
+## [5.2.0] - 2026-10-08
+
+### Added
+- **Bounce & physics pack** (`use-scroll-animate/components/effects`, `registerPhysicsEffects()`, `PHYSICS_FX`): `bounce-in` (spring overshoot), `rubber-band`, `elastic-hover` (springy lift, persistent), `drop-bounce` (gravity + restitution), `gravity-text` (per-character drop, keeps `aria-label`), `spring-follow` (element springs toward the pointer), `bell-swing` (damped swing from the top).
+- Physics helpers: `solveSpring({ stiffness, damping, mass, steps })` → progress samples + settle time, `springKeyframes(map, spring)`, `bounceKeyframes(restitution, steps)` — physical motion that still runs on the Web Animations API.
+- Showcase: **Bounce & physics**, **Gravity text** and **Elastic hover & spring follow** cards.
+
+### Accessibility
+- Under reduced motion `bounce-in` / `drop-bounce` become a short fade; `rubber-band`, `bell-swing`, `gravity-text`, `elastic-hover` and `spring-follow` don’t move.
+
 ## [5.1.0] - 2026-10-08
 
 ### Added

package/dist/components/effects.cjs

@@ -229,6 +229,396 @@ const CLICK_FX = [
     },
 ];
 
+/**
+ * Sample a damped spring from 0 → 1 and return the progress values plus the
+ * time (ms) it takes to settle. Pure, deterministic.
+ */
+function solveSpring({ stiffness = 180, damping = 12, mass = 1, steps = 40 } = {}) {
+    const dt = 1 / 120;
+    let x = 0;
+    let v = 0;
+    const trace = [];
+    let t = 0;
+    for (; t < 4; t += dt) {
+        const a = (-stiffness * (x - 1) - damping * v) / mass;
+        v += a * dt;
+        x += v * dt;
+        trace.push(x);
+        if (t > 0.1 && Math.abs(x - 1) < 0.001 && Math.abs(v) < 0.01)
+            break;
+    }
+    const values = Array.from({ length: steps + 1 }, (_, i) => +trace[Math.min(trace.length - 1, Math.round((i / steps) * (trace.length - 1)))].toFixed(4));
+    values[0] = 0;
+    values[steps] = 1;
+    return { values, duration: Math.round(trace.length * dt * 1000) };
+}
+/** Keyframes for a property driven by a spring: `map(progress)` → keyframe. */
+function springKeyframes(map, spring) {
+    const { values, duration } = solveSpring(spring);
+    return { frames: values.map(map), duration };
+}
+/** Height (0 = floor, 1 = drop height) of a ball dropped with restitution `bounce`, sampled `steps` times. */
+function bounceKeyframes(bounce = 0.5, steps = 48) {
+    // segment durations scale with sqrt(height); heights scale with bounce^2 per hop
+    const hops = [1];
+    let h = 1;
+    while (hops.length < 6 && h > 0.01) {
+        h *= bounce * bounce;
+        hops.push(h);
+    }
+    const segT = hops.map((hh, i) => (i === 0 ? Math.sqrt(hh) : 2 * Math.sqrt(hh)));
+    const total = segT.reduce((a, b) => a + b, 0);
+    return Array.from({ length: steps + 1 }, (_, i) => {
+        let t = (i / steps) * total;
+        for (let k = 0; k < hops.length; k++) {
+            if (t <= segT[k] || k === hops.length - 1) {
+                const tt = Math.min(t, segT[k]);
+                if (k === 0)
+                    return +(1 - (tt / segT[0]) ** 2).toFixed(4);
+                const half = segT[k] / 2;
+                return +(hops[k] * (1 - ((tt - half) / half) ** 2)).toFixed(4);
+            }
+            t -= segT[k];
+        }
+        return 0;
+    });
+}
+const fade = (el, ctx) => ctx.animate(el, [{ opacity: 0 }, { opacity: 1 }], { duration: 200 });
+const PHYSICS_FX = [
+    {
+        name: 'bounce-in',
+        kind: 'enter',
+        description: 'Springs in from small with an overshoot (spring solver; stiffness / damping options).',
+        defaults: { stiffness: 220, damping: 11, from: 0.3 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return fade(el, ctx);
+            const { frames, duration } = springKeyframes((p) => ({ transform: `scale(${(o.from + (1 - o.from) * p).toFixed(4)})`, opacity: Math.min(1, p * 3) }), o);
+            return ctx.animate(el, frames, { duration, easing: 'linear' });
+        },
+    },
+    {
+        name: 'rubber-band',
+        kind: 'attention',
+        description: 'Stretches wide, snaps back thin and settles like a rubber band.',
+        defaults: { duration: 900, amount: 0.25 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            const a = o.amount;
+            return ctx.animate(el, [{ transform: 'scale(1,1)' }, { transform: `scale(${1 + a},${1 - a})`, offset: 0.3 }, { transform: `scale(${1 - a},${1 + a})`, offset: 0.4 }, { transform: `scale(${1 + a / 2},${1 - a / 2})`, offset: 0.5 }, { transform: `scale(${1 - a / 5},${1 + a / 5})`, offset: 0.65 }, { transform: `scale(${1 + a / 10},${1 - a / 10})`, offset: 0.75 }, { transform: 'scale(1,1)' }], { duration: o.duration });
+        },
+    },
+    {
+        name: 'elastic-hover',
+        kind: 'hover',
+        description: 'Hover lifts with a springy overshoot; leaving springs back (persistent; trigger="load").',
+        defaults: { lift: 6, scale: 1.04, stiffness: 260, damping: 10 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            const to = (on) => {
+                const from = on ? 0 : 1;
+                const { frames, duration } = springKeyframes((p) => {
+                    const k = from + (on ? p : -p);
+                    return { transform: `translateY(${(-o.lift * k).toFixed(2)}px) scale(${(1 + (o.scale - 1) * k).toFixed(4)})` };
+                }, o);
+                ctx.animate(el, frames, { duration, fill: 'forwards', easing: 'linear' });
+            };
+            const enter = () => to(true);
+            const leave = () => to(false);
+            el.addEventListener('pointerenter', enter);
+            el.addEventListener('pointerleave', leave);
+            return () => {
+                el.removeEventListener('pointerenter', enter);
+                el.removeEventListener('pointerleave', leave);
+            };
+        },
+    },
+    {
+        name: 'drop-bounce',
+        kind: 'enter',
+        description: 'Falls in under gravity and bounces to rest (`height`, `bounce` restitution 0–0.9).',
+        defaults: { height: 120, bounce: 0.5, duration: 1100 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return fade(el, ctx);
+            const hs = bounceKeyframes(Math.min(0.9, Math.max(0, o.bounce)));
+            return ctx.animate(el, hs.map((h, i) => ({ transform: `translateY(${(-h * o.height).toFixed(1)}px)`, opacity: i === 0 ? 0 : 1 })), { duration: o.duration, easing: 'linear' });
+        },
+    },
+    {
+        name: 'gravity-text',
+        kind: 'text',
+        description: 'Each character drops in under gravity with a bounce, staggered (splits the text into aria-hidden spans; the label stays readable).',
+        defaults: { height: 60, bounce: 0.45, duration: 900, stagger: 45 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            if (!el.dataset.usaSplit) {
+                const text = el.textContent || '';
+                el.setAttribute('aria-label', text);
+                el.textContent = '';
+                for (const ch of Array.from(text)) {
+                    const s = document.createElement('span');
+                    s.setAttribute('aria-hidden', 'true');
+                    s.style.display = 'inline-block';
+                    s.style.whiteSpace = 'pre';
+                    s.textContent = ch;
+                    el.appendChild(s);
+                }
+                el.dataset.usaSplit = '1';
+            }
+            const hs = bounceKeyframes(o.bounce, 32);
+            return all(Array.from(el.children).map((s, i) => ctx.animate(s, hs.map((h) => ({ transform: `translateY(${(-h * o.height).toFixed(1)}px)` })), { duration: o.duration, delay: i * o.stagger, easing: 'linear', fill: 'backwards' })));
+        },
+    },
+    {
+        name: 'spring-follow',
+        kind: 'cursor',
+        description: 'The element springs toward the pointer while it moves over its parent, and back home on leave (persistent).',
+        defaults: { stiffness: 0.12, damping: 0.75, range: 40 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            const host = el.parentElement || el;
+            let tx = 0;
+            let ty = 0;
+            let x = 0;
+            let y = 0;
+            let vx = 0;
+            let vy = 0;
+            let raf = 0;
+            const tick = () => {
+                vx = (vx + (tx - x) * o.stiffness) * o.damping;
+                vy = (vy + (ty - y) * o.stiffness) * o.damping;
+                x += vx;
+                y += vy;
+                el.style.translate = `${x.toFixed(2)}px ${y.toFixed(2)}px`;
+                raf = Math.abs(vx) + Math.abs(vy) + Math.abs(tx - x) + Math.abs(ty - y) > 0.05 ? requestAnimationFrame(tick) : 0;
+            };
+            const kick = () => {
+                if (!raf)
+                    raf = requestAnimationFrame(tick);
+            };
+            const move = (e) => {
+                const r = host.getBoundingClientRect();
+                const nx = (e.clientX - r.left) / (r.width || 1) - 0.5;
+                const ny = (e.clientY - r.top) / (r.height || 1) - 0.5;
+                tx = nx * 2 * o.range;
+                ty = ny * 2 * o.range;
+                kick();
+            };
+            const leave = () => {
+                tx = ty = 0;
+                kick();
+            };
+            host.addEventListener('pointermove', move);
+            host.addEventListener('pointerleave', leave);
+            return () => {
+                host.removeEventListener('pointermove', move);
+                host.removeEventListener('pointerleave', leave);
+                cancelAnimationFrame(raf);
+                el.style.translate = '';
+            };
+        },
+    },
+    {
+        name: 'bell-swing',
+        kind: 'attention',
+        description: 'Swings from its top like a ringing bell with damped oscillation.',
+        defaults: { angle: 22, stiffness: 120, damping: 4 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            el.style.transformOrigin = 'top center';
+            const { frames, duration } = springKeyframes((p) => ({ transform: `rotate(${(o.angle * (1 - p)).toFixed(2)}deg)` }), { stiffness: o.stiffness, damping: o.damping, steps: 48 });
+            frames[0] = { transform: 'rotate(0deg)' };
+            return ctx.animate(el, frames, { duration: Math.min(duration, 2400), easing: 'linear' });
+        },
+    },
+];
+
+/** A full-viewport, aria-hidden, pointer-blocking (while covering) transition layer. */
+function screen(css = '') {
+    const s = document.createElement('div');
+    s.setAttribute('aria-hidden', 'true');
+    s.setAttribute('data-usa-page-fx', '');
+    s.style.cssText = `position:fixed;inset:0;z-index:2147483001;pointer-events:auto;${css}`;
+    document.body.appendChild(s);
+    return s;
+}
+const wait = (a) => (a ? a.finished.catch(() => undefined) : Promise.resolve());
+const call = async (fn) => {
+    if (typeof fn === 'function')
+        await fn();
+};
+/** Reduced-motion version of every transition: a quick cross-fade through the cover colour. */
+async function crossFade(o, ctx) {
+    const s = screen(`background:${o.color};opacity:0`);
+    await wait(ctx.animate(s, [{ opacity: 0 }, { opacity: 1 }], { duration: 150, fill: 'forwards' }));
+    await call(o.onCovered);
+    await wait(ctx.animate(s, [{ opacity: 1 }, { opacity: 0 }], { duration: 150, fill: 'forwards' }));
+    s.remove();
+}
+/** Build a transition from a cover layer and cover / reveal animations of its parts. */
+function transition(build) {
+    return async (el, o, ctx) => {
+        if (ctx.reduced)
+            return crossFade(o, ctx);
+        const s = screen('pointer-events:auto');
+        const { parts, cover, delay } = build(s, o, ctx, el);
+        const frames = (i) => (typeof cover === 'function' ? cover(i) : cover);
+        const half = o.duration / 2;
+        await Promise.all(parts.map((p, i) => wait(ctx.animate(p, frames(i), { duration: half, delay: delay?.(i) ?? 0, easing: 'cubic-bezier(0.65, 0, 0.35, 1)', fill: 'both' }))));
+        await call(o.onCovered);
+        if (o.hold)
+            await new Promise((r) => setTimeout(r, o.hold));
+        await Promise.all(parts.map((p, i) => wait(ctx.animate(p, [...frames(i)].reverse(), { duration: half, delay: delay?.(i) ?? 0, easing: 'cubic-bezier(0.65, 0, 0.35, 1)', fill: 'both' }))));
+        s.remove();
+    };
+}
+const part = (s, css) => {
+    const p = document.createElement('div');
+    p.style.cssText = `position:absolute;${css}`;
+    s.appendChild(p);
+    return p;
+};
+const TRANSITION_DEFAULTS = { color: '#0f0f1a', duration: 1000, hold: 0, onCovered: undefined };
+const PAGE_FX = [
+    {
+        name: 'curtain',
+        kind: 'page',
+        description: 'Two curtain panels close from the sides, call onCovered(), then open.',
+        reduced: 'run',
+        defaults: TRANSITION_DEFAULTS,
+        run: transition((s, o) => ({
+            parts: [part(s, `top:0;bottom:0;left:0;width:50.5%;background:${o.color}`), part(s, `top:0;bottom:0;right:0;width:50.5%;background:${o.color}`)],
+            cover: (i) => [{ transform: `translateX(${i ? 100 : -100}%)` }, { transform: 'translateX(0)' }],
+        })),
+    },
+    {
+        name: 'iris',
+        kind: 'page',
+        description: 'A circle closes on the click point (or the element’s center), calls onCovered(), then opens.',
+        reduced: 'run',
+        defaults: TRANSITION_DEFAULTS,
+        run: transition((s, o, ctx, el) => {
+            const { x, y } = origin(el, ctx);
+            const r = Math.hypot(Math.max(x, innerWidth - x), Math.max(y, innerHeight - y)) + 2;
+            // a huge box-shadow ring around a hole: the hole shrinks to 0 to cover
+            const p = part(s, `left:${x}px;top:${y}px;width:0;height:0;border-radius:50%;box-shadow:0 0 0 ${Math.ceil(r)}px ${o.color}`);
+            s.style.background = 'transparent';
+            return { parts: [p], cover: [{ width: `${r * 2}px`, height: `${r * 2}px`, margin: `${-r}px 0 0 ${-r}px` }, { width: '0px', height: '0px', margin: '0px 0 0 0px' }] };
+        }),
+    },
+    {
+        name: 'pixel-dissolve',
+        kind: 'page',
+        description: 'The screen fills with pixels in random order, calls onCovered(), then dissolves (`cols` × `rows`).',
+        reduced: 'run',
+        defaults: { ...TRANSITION_DEFAULTS, cols: 16, rows: 10 },
+        run: transition((s, o) => {
+            const n = o.cols * o.rows;
+            const order = Array.from({ length: n }, (_, i) => i).sort(() => Math.random() - 0.5);
+            const parts = Array.from({ length: n }, (_, i) => part(s, `left:${((i % o.cols) * 100) / o.cols}%;top:${(Math.floor(i / o.cols) * 100) / o.rows}%;width:${100 / o.cols + 0.2}%;height:${100 / o.rows + 0.2}%;background:${o.color};opacity:0`));
+            return { parts, cover: [{ opacity: 0 }, { opacity: 1 }], delay: (i) => (order[i] / n) * (o.duration / 2) * 0.6 };
+        }),
+    },
+    {
+        name: 'blinds',
+        kind: 'page',
+        description: 'Horizontal slats rotate shut like venetian blinds, call onCovered(), then open (`slats`).',
+        reduced: 'run',
+        defaults: { ...TRANSITION_DEFAULTS, slats: 8 },
+        run: transition((s, o) => ({
+            parts: Array.from({ length: o.slats }, (_, i) => part(s, `left:0;right:0;top:${(i * 100) / o.slats}%;height:${100 / o.slats + 0.3}%;background:${o.color};transform-origin:top`)),
+            cover: [{ transform: 'scaleY(0)' }, { transform: 'scaleY(1)' }],
+            delay: (i) => i * 30,
+        })),
+    },
+    {
+        name: 'velocity-skew',
+        kind: 'scroll',
+        description: 'Skews the element with scroll velocity and eases back when scrolling stops (persistent).',
+        defaults: { max: 8, factor: 0.25 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            let last = scrollY;
+            let skew = 0;
+            let raf = 0;
+            const tick = () => {
+                const y = scrollY;
+                const target = Math.max(-o.max, Math.min(o.max, (y - last) * o.factor));
+                last = y;
+                skew += (target - skew) * 0.2;
+                el.style.transform = `skewY(${skew.toFixed(3)}deg)`;
+                raf = Math.abs(skew) > 0.01 || Math.abs(target) > 0.01 ? requestAnimationFrame(tick) : 0;
+                if (!raf)
+                    el.style.transform = '';
+            };
+            const onScroll = () => {
+                if (!raf)
+                    raf = requestAnimationFrame(tick);
+            };
+            addEventListener('scroll', onScroll, { passive: true });
+            return () => {
+                removeEventListener('scroll', onScroll);
+                cancelAnimationFrame(raf);
+                el.style.transform = '';
+            };
+        },
+    },
+    {
+        name: 'spotlight',
+        kind: 'cursor',
+        description: 'Dims the page except a soft circle that follows the pointer (persistent; `radius`, `dim`).',
+        defaults: { radius: 180, dim: 0.72 },
+        run: (_el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            const s = screen(`pointer-events:none;background:radial-gradient(circle ${o.radius}px at var(--x,50%) var(--y,50%),transparent 0,transparent 60%,rgba(0,0,0,${o.dim}) 100%)`);
+            const move = (e) => {
+                s.style.setProperty('--x', `${e.clientX}px`);
+                s.style.setProperty('--y', `${e.clientY}px`);
+            };
+            addEventListener('pointermove', move, { passive: true });
+            return () => {
+                removeEventListener('pointermove', move);
+                s.remove();
+            };
+        },
+    },
+    {
+        name: 'edge-glow',
+        kind: 'scroll',
+        description: 'A soft glow lights the top / bottom edge of the viewport while scrolling in that direction (persistent).',
+        defaults: { color: '#7c5cff', size: 90 },
+        run: (_el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            const s = screen('pointer-events:none;opacity:0;transition:opacity .35s ease-out');
+            let last = scrollY;
+            let t = 0;
+            const onScroll = () => {
+                const down = scrollY >= last;
+                last = scrollY;
+                s.style.background = `linear-gradient(${down ? 'to top' : 'to bottom'},${o.color}55,transparent ${o.size}px)`;
+                s.style.opacity = '1';
+                clearTimeout(t);
+                t = setTimeout(() => (s.style.opacity = '0'), 160);
+            };
+            addEventListener('scroll', onScroll, { passive: true });
+            return () => {
+                removeEventListener('scroll', onScroll);
+                clearTimeout(t);
+                s.remove();
+            };
+        },
+    },
+];
+
 /**
  * use-scroll-animate/components/effects — the 5.x effect packs, all
  * registered through `registerEffect()` (5.0) and playable with
@@ -244,11 +634,21 @@ const CLICK_FX = [
 /** The effect packs by version, in release order. */
 const EFFECT_PACKS = {
     'cards-click': [...CARD_FX, ...CLICK_FX],
+    physics: PHYSICS_FX,
+    page: PAGE_FX,
 };
 /** 5.1: card & click effects 2.0. */
 function registerCardClickEffects() {
     components_fx.registerEffects(EFFECT_PACKS['cards-click']);
 }
+/** 5.2: bounce & physics micro-interactions. */
+function registerPhysicsEffects() {
+    components_fx.registerEffects(EFFECT_PACKS.physics);
+}
+/** 5.3: page-wide transitions and effects. */
+function registerPageEffects() {
+    components_fx.registerEffects(EFFECT_PACKS.page);
+}
 /** Register the built-ins and every pack (idempotent). */
 function registerAllEffects() {
     components_fx.registerBuiltinEffects();
@@ -259,7 +659,14 @@ function registerAllEffects() {
 exports.CARD_FX = CARD_FX;
 exports.CLICK_FX = CLICK_FX;
 exports.EFFECT_PACKS = EFFECT_PACKS;
+exports.PAGE_FX = PAGE_FX;
+exports.PHYSICS_FX = PHYSICS_FX;
+exports.bounceKeyframes = bounceKeyframes;
 exports.fxLayer = fxLayer;
 exports.registerAllEffects = registerAllEffects;
 exports.registerCardClickEffects = registerCardClickEffects;
+exports.registerPageEffects = registerPageEffects;
+exports.registerPhysicsEffects = registerPhysicsEffects;
+exports.solveSpring = solveSpring;
+exports.springKeyframes = springKeyframes;
 //# sourceMappingURL=effects.cjs.map