use-scroll-animate 5.8.0 → 6.0.0

package/dist/components/effects.cjs

@@ -3,7 +3,7 @@
 var components_fx = require('./fx.cjs');
 var base = require('../chunks/base-B5i8qQPR.cjs');
 var components_tokens = require('./tokens.cjs');
-require('../chunks/core-BDcszY4L.cjs');
+var core = require('../chunks/core-BDcszY4L.cjs');
 require('../chunks/fx-B8hk1Fby.cjs');
 
 let layer = null;
@@ -2162,6 +2162,306 @@ function defineTheme(tag = 'usa-theme') {
     }, { id: 'usa-theme-el', text: 'usa-theme{display:block}' });
 }
 
+/**
+ * 5.9 — `<usa-player>`: plays JSON animations.
+ *
+ * Format `use-scroll-animate/animation` v1:
+ *
+ * ```json
+ * { "format": "use-scroll-animate/animation", "version": 1, "name": "Hero",
+ *   "loop": false,
+ *   "tracks": [
+ *     { "target": "h1", "start": 0, "duration": 600, "preset": "fade-up" },
+ *     { "target": ".cta", "start": 500, "duration": 500, "keyframes": [{ "opacity": 0 }, { "opacity": 1 }], "easing": "ease-out" },
+ *     { "target": ".cta", "start": 1100, "effect": "jelly", "options": {} }
+ *   ] }
+ * ```
+ *
+ * A track animates `target` (a selector inside the player; `:scope` for the
+ * player itself) with a timeline preset, its own keyframes, or fires any
+ * registered effect at `start`. Playground presets (format
+ * `use-scroll-animate/playground`) are accepted too — their tracks map to the
+ * player's children in order.
+ *
+ * Keyframe tracks are WAAPI animations driven by one clock, so the player can
+ * play, pause, seek, change rate and be scrubbed by scroll
+ * (`trigger="scroll"`). Reduced motion: jumps to the end state, effects skipped.
+ */
+const ANIMATION_FORMAT = 'use-scroll-animate/animation';
+function decodePlayground(state) {
+    try {
+        const b64 = state.replace(/-/g, '+').replace(/_/g, '/');
+        const json = decodeURIComponent(escape(atob(b64)));
+        const t = (JSON.parse(json).t || []);
+        return t.map(([preset, start, duration, label], i) => ({ target: `:scope > :nth-child(${i + 1})`, preset, start, duration, label }));
+    }
+    catch {
+        return [];
+    }
+}
+/** Validate / normalise an animation (object or JSON text). Throws on anything unusable. */
+function normalizeAnimation(input) {
+    const d = typeof input === 'string' ? JSON.parse(input) : input;
+    if (!d || typeof d !== 'object')
+        throw new Error('[use-scroll-animate] animation: expected an object');
+    let tracks;
+    if (d.format === 'use-scroll-animate/playground')
+        tracks = decodePlayground(String(d.state || ''));
+    else if (Array.isArray(d.tracks))
+        tracks = d.tracks;
+    else
+        throw new Error('[use-scroll-animate] animation: missing "tracks"');
+    if (d.format && d.format !== ANIMATION_FORMAT && d.format !== 'use-scroll-animate/playground')
+        throw new Error(`[use-scroll-animate] animation: unknown format "${d.format}"`);
+    if (d.version && d.version > 1 && d.format === ANIMATION_FORMAT)
+        throw new Error(`[use-scroll-animate] animation: version ${d.version} needs a newer use-scroll-animate`);
+    const out = tracks
+        .filter((t) => t && (t.effect || t.preset || Array.isArray(t.keyframes)))
+        .map((t) => ({ ...t, target: t.target || ':scope', start: Math.max(0, Number(t.start) || 0), duration: t.effect ? 0 : Math.max(1, Number(t.duration) || 600) }));
+    const end = out.reduce((m, t) => Math.max(m, t.start + t.duration), 0);
+    return { tracks: out, duration: Math.max(end, Number(d.duration) || 0), loop: !!d.loop, name: String(d.name || 'animation') };
+}
+const pick = (root, sel) => {
+    if (sel === ':scope')
+        return [root];
+    try {
+        return Array.from(root.querySelectorAll(sel));
+    }
+    catch {
+        return [];
+    }
+};
+/** Bind an animation to `root` and return its controller (paused at 0 unless `autoplay`). */
+function createPlayer(root, animation, o = {}) {
+    const a = normalizeAnimation(animation);
+    const loop = o.loop ?? a.loop;
+    const anims = [];
+    const effects = [];
+    for (const t of a.tracks) {
+        const els = pick(root, t.target);
+        if (t.effect)
+            effects.push({ els, t, fired: false });
+        else {
+            const kf = t.keyframes || core.TIMELINE_PRESETS[t.preset] || core.TIMELINE_PRESETS.fade;
+            for (const el of els) {
+                if (typeof el.animate !== 'function')
+                    continue;
+                const an = el.animate(kf, { duration: t.duration, delay: t.start, easing: t.easing || 'cubic-bezier(0.22, 1, 0.36, 1)', fill: 'both' });
+                an.pause();
+                an.currentTime = 0;
+                anims.push(an);
+            }
+        }
+    }
+    let time = 0;
+    let playing = false;
+    let raf = 0;
+    let last = 0;
+    let resolve;
+    let finished = new Promise((r) => (resolve = r));
+    const set = (ms) => {
+        time = Math.min(a.duration, Math.max(0, ms));
+        for (const an of anims)
+            an.currentTime = time;
+    };
+    const fireDue = () => {
+        if (base.prefersReducedMotion())
+            return;
+        for (const e of effects)
+            if (!e.fired && time >= e.t.start) {
+                e.fired = true;
+                for (const el of e.els)
+                    components_fx.playEffect(el, e.t.effect, e.t.options || {}).catch(() => undefined);
+            }
+    };
+    const done = () => {
+        resolve();
+        o.onFinish?.();
+        finished = new Promise((r) => (resolve = r));
+    };
+    const frame = (now) => {
+        raf = 0;
+        if (!playing)
+            return;
+        set(time + (now - last) * player.rate);
+        last = now;
+        fireDue();
+        if (time >= a.duration) {
+            if (loop) {
+                effects.forEach((e) => (e.fired = false));
+                set(0);
+            }
+            else {
+                playing = false;
+                done();
+                return;
+            }
+        }
+        raf = requestAnimationFrame(frame);
+    };
+    const player = {
+        get duration() {
+            return a.duration;
+        },
+        get currentTime() {
+            return time;
+        },
+        get playing() {
+            return playing;
+        },
+        rate: o.rate ?? 1,
+        get finished() {
+            return finished;
+        },
+        play() {
+            if (base.prefersReducedMotion()) {
+                set(a.duration);
+                effects.forEach((e) => (e.fired = true));
+                done();
+                return;
+            }
+            if (playing)
+                return;
+            if (time >= a.duration) {
+                effects.forEach((e) => (e.fired = false));
+                set(0);
+            }
+            playing = true;
+            last = performance.now();
+            fireDue();
+            raf = requestAnimationFrame(frame);
+        },
+        pause() {
+            playing = false;
+            cancelAnimationFrame(raf);
+            raf = 0;
+        },
+        seek(ms) {
+            set(ms);
+            effects.forEach((e) => (e.fired = e.t.start < time));
+        },
+        destroy() {
+            player.pause();
+            anims.forEach((an) => an.cancel());
+        },
+    };
+    if (o.autoplay)
+        player.play();
+    return player;
+}
+/**
+ * `<usa-player src="hero.json" | <script type="application/json"> child
+ * trigger="load | view | scroll | click | manual" loop rate controls>`.
+ * Emits `usa-player-ready` and `usa-player-finish`; sets `data-error` when the
+ * animation cannot be loaded.
+ */
+function definePlayer(tag = 'usa-player') {
+    return base.defineElement(tag, (Base) => class UsaPlayer extends Base {
+        constructor() {
+            super(...arguments);
+            this.player = null;
+            this.json = null;
+        }
+        static get observedAttributes() {
+            return ['src', 'trigger', 'loop', 'rate'];
+        }
+        load(animation) {
+            this.json = animation;
+            this.start();
+        }
+        play() {
+            this.player?.play();
+        }
+        pause() {
+            this.player?.pause();
+        }
+        seek(ms) {
+            this.player?.seek(ms);
+        }
+        start() {
+            this.player?.destroy();
+            this.player = null;
+            if (!this.json)
+                return;
+            try {
+                this.player = createPlayer(this, this.json, {
+                    loop: this.hasAttribute('loop') ? true : undefined,
+                    rate: this.num('rate', 1),
+                    onFinish: () => this.dispatchEvent(new CustomEvent('usa-player-finish', { bubbles: true })),
+                });
+                this.removeAttribute('data-error');
+            }
+            catch (err) {
+                this.setAttribute('data-error', String(err.message || err));
+                return;
+            }
+            const p = this.player;
+            this.dispatchEvent(new CustomEvent('usa-player-ready', { detail: { duration: p.duration }, bubbles: true }));
+            const trig = this.str('trigger', 'view');
+            if (trig === 'load')
+                p.play();
+            else if (trig === 'view')
+                this.inView((v) => v && p.play(), { threshold: 0.25 });
+            else if (trig === 'click')
+                this.listen(this, 'click', () => (p.playing ? p.pause() : p.play()));
+            else if (trig === 'scroll') {
+                let f = 0;
+                const upd = () => {
+                    f = 0;
+                    p.seek(storyProgress(this) * p.duration);
+                };
+                const kick = () => void (f || (f = requestAnimationFrame(upd)));
+                this.listen(window, 'scroll', kick, { passive: true });
+                this.listen(window, 'resize', kick);
+                this.onCleanup(() => cancelAnimationFrame(f));
+                upd();
+            }
+            if (this.flag('controls'))
+                this.mountControls(p);
+        }
+        mountControls(p) {
+            const b = document.createElement('button');
+            b.type = 'button';
+            b.setAttribute('data-player-toggle', '');
+            b.textContent = '▶︎ / ❚❚';
+            b.setAttribute('aria-label', 'Play / pause animation');
+            this.listen(b, 'click', (e) => {
+                e.stopPropagation();
+                if (p.playing)
+                    p.pause();
+                else
+                    p.play();
+                b.setAttribute('aria-pressed', String(p.playing));
+            });
+            this.append(b);
+            this.onCleanup(() => b.remove());
+        }
+        changed(name) {
+            if (name === 'src')
+                this.json = null;
+            super.changed(name);
+        }
+        mount() {
+            this.onCleanup(() => {
+                this.player?.destroy();
+                this.player = null;
+            });
+            const inline = this.querySelector('script[type="application/json"]');
+            const src = this.str('src');
+            if (inline && !this.json)
+                this.json = inline.textContent || '';
+            if (src && !this.json) {
+                fetch(src)
+                    .then((r) => (r.ok ? r.text() : Promise.reject(new Error(`HTTP ${r.status}`))))
+                    .then((t) => this.isConnected && this.load(t))
+                    .catch((err) => this.setAttribute('data-error', String(err.message || err)));
+                return;
+            }
+            this.start();
+        }
+    }, { id: 'usa-player', text: 'usa-player{display:block;position:relative}usa-player>script{display:none}usa-player [data-player-toggle]{position:absolute;right:8px;bottom:8px}' });
+}
+
 /**
  * use-scroll-animate/components/effects — the 5.x effect packs, all
  * registered through `registerEffect()` (5.0) and playable with
@@ -2220,6 +2520,7 @@ function defineEffectElements() {
     defineAudio();
     defineGestureFx();
     defineTheme();
+    definePlayer();
 }
 /** Register the built-ins and every pack (idempotent). */
 function registerAllEffects() {
@@ -2228,6 +2529,7 @@ function registerAllEffects() {
         components_fx.registerEffects(defs);
 }
 
+exports.ANIMATION_FORMAT = ANIMATION_FORMAT;
 exports.AUDIO_FX = AUDIO_FX;
 exports.CARD_FX = CARD_FX;
 exports.CLICK_FX = CLICK_FX;
@@ -2251,9 +2553,11 @@ exports.bounceKeyframes = bounceKeyframes;
 exports.bumpCount = bumpCount;
 exports.canvasBackground = canvasBackground;
 exports.createBeatDetector = createBeatDetector;
+exports.createPlayer = createPlayer;
 exports.defineAudio = defineAudio;
 exports.defineEffectElements = defineEffectElements;
 exports.defineGestureFx = defineGestureFx;
+exports.definePlayer = definePlayer;
 exports.defineStory = defineStory;
 exports.defineTheme = defineTheme;
 exports.disableAudio = disableAudio;
@@ -2264,6 +2568,7 @@ exports.fxLayer = fxLayer;
 exports.getAudio = getAudio;
 exports.hexRgb = hexRgb;
 exports.noise2 = noise2;
+exports.normalizeAnimation = normalizeAnimation;
 exports.onBeat = onBeat;
 exports.playThemeEffect = playThemeEffect;
 exports.registerAllEffects = registerAllEffects;