use-scroll-animate 5.2.0 → 5.4.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.4.0] - 2026-10-08
+
+### Added
+- **`<usa-story template="…">`** (`defineStory()` from `use-scroll-animate/components/effects`; `defineEffectElements()` defines every element of the entry) — six scroll-storytelling templates:
+  - `pin` — a sticky `[data-stage]` while `[data-step]` sections scroll past; the active step gets `data-active`, the stage `data-active-step="<i>"`.
+  - `gallery` — a horizontal `[data-track]` slides sideways as you scroll down.
+  - `zoom` — zoom-through: the stage scales up to `zoom="6"` and fades.
+  - `compare` — before / after wipe driven by scroll, with a draggable, keyboard-accessible handle (`role="slider"`, ←/→, Shift for ×5, Home/End).
+  - `counter` — `[data-count="12,480"]` numbers count up on entering view (separators, decimals, prefix / suffix kept).
+  - `highlight` — the paragraph (or `[data-step]`) crossing the viewport center is highlighted.
+- Every template sets `--usa-story-progress` (0–1), exposes `progress` / `step` / `update()` and fires `usa-story-step`. Helpers: `storyProgress(el)`, `formatCount(target, t)`, `STORY_TEMPLATES`.
+- Showcase: new **[Scroll stories](./showcase/story.html)** page with all six templates full-page; gallery cards **Story: before / after**, **Story: data counters**, **Story: step highlight**. Gallery code tabs import from the card’s own entry.
+
+### Accessibility
+- Under reduced motion nothing slides or zooms (the gallery stacks vertically), counters show their final values immediately; counted numbers carry the final value as `aria-label`.
+
+## [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

package/dist/components/effects.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var components_fx = require('./fx.cjs');
-require('../chunks/base-B5i8qQPR.cjs');
+var base = require('../chunks/base-B5i8qQPR.cjs');
 require('../chunks/core-BDcszY4L.cjs');
 require('./tokens.cjs');
 require('../chunks/fx-B8hk1Fby.cjs');
@@ -439,6 +439,396 @@ const PHYSICS_FX = [
     },
 ];
 
+/** 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();
+            };
+        },
+    },
+];
+
+/**
+ * 5.4 — `<usa-story template="…">` scroll-storytelling templates.
+ *
+ * - `pin` — a sticky `[data-stage]` while `[data-step]` sections scroll past; the
+ *   step in view gets `data-active`, the stage gets `data-active-step="<index>"`.
+ * - `gallery` — a horizontal `[data-track]` slides sideways as you scroll down.
+ * - `zoom` — the `[data-stage]` zooms toward the viewer (`zoom="6"`) and fades.
+ * - `compare` — before / after (`[data-before]`, `[data-after]`) wipe driven by
+ *   scroll, plus a draggable, keyboard-accessible handle (`role="slider"`).
+ * - `counter` — `[data-count="1234"]` numbers count up when they enter view.
+ * - `highlight` — paragraphs dim except the one crossing the viewport center.
+ *
+ * Every template sets `--usa-story-progress` (0–1) on the host and dispatches
+ * `usa-story-step` (`detail: { index }`). Reduced motion: no sliding / zooming
+ * (the gallery stacks vertically), counters show final values, the rest is
+ * class changes only.
+ */
+const STORY_TEMPLATES = ['pin', 'gallery', 'zoom', 'compare', 'counter', 'highlight'];
+const CSS = `usa-story{display:block;position:relative}
+usa-story[template=pin] [data-stage],usa-story[template=gallery] [data-sticky],usa-story[template=zoom] [data-stage],usa-story[template=compare] [data-sticky]{position:sticky;top:0}
+usa-story[template=pin] [data-stage]{align-self:start}
+usa-story[template=pin] [data-step]{min-height:80vh;opacity:.35;transition:opacity .3s}
+usa-story[template=pin] [data-step][data-active]{opacity:1}
+usa-story[template=gallery] [data-sticky]{height:100vh;overflow:hidden;display:flex;align-items:center}
+usa-story[template=gallery] [data-track]{display:flex;gap:24px;will-change:transform}
+usa-story[template=gallery][data-static] [data-sticky]{position:static;height:auto;overflow:visible}
+usa-story[template=gallery][data-static] [data-track]{flex-direction:column;transform:none!important}
+usa-story[template=zoom] [data-stage]{height:100vh;overflow:hidden;display:grid;place-items:center}
+usa-story[template=compare] [data-sticky]{height:var(--usa-story-h,70vh);overflow:hidden}
+usa-story[template=compare] [data-before],usa-story[template=compare] [data-after]{position:absolute;inset:0}
+usa-story[template=compare] [data-after]{clip-path:inset(0 0 0 var(--usa-split,50%))}
+usa-story [data-handle]{position:absolute;top:0;bottom:0;left:var(--usa-split,50%);width:4px;margin-left:-2px;background:#fff;box-shadow:0 0 0 1px #0003;cursor:ew-resize;touch-action:none}
+usa-story [data-handle]:focus-visible{outline:3px solid #7c5cff;outline-offset:2px}
+usa-story[template=highlight] p,usa-story[template=highlight] [data-step]{opacity:.3;transition:opacity .25s}
+usa-story[template=highlight] [data-active]{opacity:1}`;
+const clamp = (v, a = 0, b = 1) => Math.min(b, Math.max(a, v));
+/** Progress of `el` through the viewport: 0 when its top hits the viewport top, 1 when its bottom hits the viewport bottom. */
+function storyProgress(el, vh = typeof innerHeight === 'number' ? innerHeight : 800) {
+    const r = el.getBoundingClientRect();
+    const span = r.height - vh;
+    return span > 0 ? clamp(-r.top / span) : clamp((vh - r.top) / (vh + r.height));
+}
+/** Format a counted value like the target (`1,234`, `12.5`, prefix / suffix kept). */
+function formatCount(target, t) {
+    const m = target.match(/^(\D*)([\d,]*\.?\d+)(.*)$/);
+    if (!m)
+        return target;
+    const [, pre, num, post] = m;
+    const n = parseFloat(num.replace(/,/g, ''));
+    const dec = (num.split('.')[1] || '').length;
+    let s = (n * t).toFixed(dec);
+    if (num.includes(','))
+        s = Number(s).toLocaleString('en-US', { minimumFractionDigits: dec, maximumFractionDigits: dec });
+    return pre + s + post;
+}
+function defineStory(tag = 'usa-story') {
+    return base.defineElement(tag, (Base) => class UsaStory extends Base {
+        constructor() {
+            super(...arguments);
+            this.progress = 0;
+            this.step = -1;
+            this.frame = 0;
+        }
+        static get observedAttributes() {
+            return ['template', 'zoom'];
+        }
+        get template() {
+            const t = this.str('template', 'pin');
+            return STORY_TEMPLATES.includes(t) ? t : 'pin';
+        }
+        steps() {
+            const own = Array.from(this.querySelectorAll('[data-step]:not([data-stage])'));
+            return own.length || this.template !== 'highlight' ? own : Array.from(this.querySelectorAll('p'));
+        }
+        setStep(i) {
+            if (i === this.step)
+                return;
+            this.step = i;
+            this.steps().forEach((s, k) => s.toggleAttribute('data-active', k === i));
+            const stage = this.querySelector('[data-stage]');
+            if (stage)
+                stage.dataset.activeStep = String(i);
+            this.dispatchEvent(new CustomEvent('usa-story-step', { detail: { index: i }, bubbles: true }));
+        }
+        /** Recompute from the current scroll position (called on scroll / resize). */
+        update() {
+            this.frame = 0;
+            const p = (this.progress = storyProgress(this));
+            this.style.setProperty('--usa-story-progress', p.toFixed(4));
+            const t = this.template;
+            const vh = innerHeight || 800;
+            if (t === 'pin' || t === 'highlight') {
+                const mid = vh / 2;
+                let best = -1;
+                let bestD = Infinity;
+                this.steps().forEach((s, i) => {
+                    const r = s.getBoundingClientRect();
+                    const d = r.top <= mid && r.bottom >= mid ? 0 : Math.min(Math.abs(r.top - mid), Math.abs(r.bottom - mid));
+                    if (d < bestD)
+                        (bestD = d), (best = i);
+                });
+                this.setStep(best);
+            }
+            else if (t === 'gallery' && !this.reduced) {
+                const track = this.querySelector('[data-track]');
+                const box = this.querySelector('[data-sticky]');
+                if (track && box)
+                    track.style.transform = `translateX(${(-p * Math.max(0, track.scrollWidth - box.clientWidth)).toFixed(1)}px)`;
+            }
+            else if (t === 'zoom' && !this.reduced) {
+                const inner = this.querySelector('[data-stage] > *');
+                if (inner) {
+                    inner.style.transform = `scale(${(1 + p * (this.num('zoom', 6) - 1)).toFixed(3)})`;
+                    inner.style.opacity = String(clamp(1.4 - p * 1.4).toFixed(3));
+                }
+            }
+            else if (t === 'compare' && !this.hasAttribute('data-dragged')) {
+                this.setSplit(p * 100);
+            }
+            else if (t === 'counter') {
+                this.querySelectorAll('[data-count]:not([data-counted])').forEach((el) => {
+                    const r = el.getBoundingClientRect();
+                    if (r.top < vh * 0.9 && r.bottom > 0)
+                        this.count(el);
+                });
+            }
+        }
+        setSplit(pct) {
+            const v = clamp(pct, 0, 100);
+            this.style.setProperty('--usa-split', `${v.toFixed(2)}%`);
+            const h = this.querySelector('[data-handle]');
+            if (h)
+                h.setAttribute('aria-valuenow', String(Math.round(v)));
+        }
+        count(el) {
+            el.dataset.counted = '';
+            const target = el.dataset.count || el.textContent || '0';
+            el.setAttribute('aria-label', target);
+            if (this.reduced) {
+                el.textContent = target;
+                return;
+            }
+            const dur = Number(el.dataset.duration) || 1600;
+            const t0 = performance.now();
+            const tick = (now) => {
+                const k = clamp((now - t0) / dur);
+                el.textContent = formatCount(target, 1 - (1 - k) ** 3);
+                if (k < 1)
+                    requestAnimationFrame(tick);
+            };
+            requestAnimationFrame(tick);
+        }
+        mount() {
+            this.toggleAttribute('data-static', this.reduced);
+            if (this.template === 'compare')
+                this.mountCompare();
+            const kick = () => {
+                if (!this.frame)
+                    this.frame = requestAnimationFrame(() => this.update());
+            };
+            this.listen(window, 'scroll', kick, { passive: true });
+            this.listen(window, 'resize', kick);
+            this.onCleanup(() => cancelAnimationFrame(this.frame));
+            this.update();
+        }
+        mountCompare() {
+            const box = this.querySelector('[data-sticky]') || this;
+            let h = this.querySelector('[data-handle]');
+            if (!h) {
+                h = document.createElement('div');
+                h.setAttribute('data-handle', '');
+                box.appendChild(h);
+                this.onCleanup(() => h.remove());
+            }
+            h.tabIndex = 0;
+            h.setAttribute('role', 'slider');
+            h.setAttribute('aria-label', this.str('label', 'Before / after'));
+            h.setAttribute('aria-valuemin', '0');
+            h.setAttribute('aria-valuemax', '100');
+            const at = (e) => {
+                const r = box.getBoundingClientRect();
+                this.dataset.dragged = '';
+                this.setSplit(((e.clientX - r.left) / (r.width || 1)) * 100);
+            };
+            let drag = false;
+            this.listen(h, 'pointerdown', (e) => {
+                drag = true;
+                h.setPointerCapture?.(e.pointerId);
+            });
+            this.listen(h, 'pointermove', (e) => drag && at(e));
+            this.listen(h, 'pointerup', () => (drag = false));
+            this.listen(h, 'keydown', (e) => {
+                const cur = parseFloat(h.getAttribute('aria-valuenow') || '50');
+                const step = e.shiftKey ? 10 : 2;
+                const next = e.key === 'ArrowLeft' || e.key === 'ArrowDown' ? cur - step : e.key === 'ArrowRight' || e.key === 'ArrowUp' ? cur + step : e.key === 'Home' ? 0 : e.key === 'End' ? 100 : null;
+                if (next == null)
+                    return;
+                e.preventDefault();
+                this.dataset.dragged = '';
+                this.setSplit(next);
+            });
+            this.setSplit(50);
+        }
+        unmount() {
+            this.step = -1;
+            delete this.dataset.dragged;
+        }
+    }, { id: 'usa-story', text: CSS });
+}
+
 /**
  * use-scroll-animate/components/effects — the 5.x effect packs, all
  * registered through `registerEffect()` (5.0) and playable with
@@ -455,6 +845,7 @@ const PHYSICS_FX = [
 const EFFECT_PACKS = {
     'cards-click': [...CARD_FX, ...CLICK_FX],
     physics: PHYSICS_FX,
+    page: PAGE_FX,
 };
 /** 5.1: card & click effects 2.0. */
 function registerCardClickEffects() {
@@ -464,6 +855,14 @@ function registerCardClickEffects() {
 function registerPhysicsEffects() {
     components_fx.registerEffects(EFFECT_PACKS.physics);
 }
+/** 5.3: page-wide transitions and effects. */
+function registerPageEffects() {
+    components_fx.registerEffects(EFFECT_PACKS.page);
+}
+/** Define the 5.x elements of this entry (`<usa-story>`, …) under their default tags. */
+function defineEffectElements() {
+    defineStory();
+}
 /** Register the built-ins and every pack (idempotent). */
 function registerAllEffects() {
     components_fx.registerBuiltinEffects();
@@ -474,12 +873,19 @@ 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.STORY_TEMPLATES = STORY_TEMPLATES;
 exports.bounceKeyframes = bounceKeyframes;
+exports.defineEffectElements = defineEffectElements;
+exports.defineStory = defineStory;
+exports.formatCount = formatCount;
 exports.fxLayer = fxLayer;
 exports.registerAllEffects = registerAllEffects;
 exports.registerCardClickEffects = registerCardClickEffects;
+exports.registerPageEffects = registerPageEffects;
 exports.registerPhysicsEffects = registerPhysicsEffects;
 exports.solveSpring = solveSpring;
 exports.springKeyframes = springKeyframes;
+exports.storyProgress = storyProgress;
 //# sourceMappingURL=effects.cjs.map