solid-drift 0.2.0 → 0.7.1

package/dist/motion.js

@@ -0,0 +1,729 @@
+/**
+ * Motion-graphics family: showreel and launch-film primitives.
+ *
+ * These are the building blocks of code-driven motion design: kinetic
+ * typography, scene orchestration, camera moves, time-based color
+ * shifts, match-cut transitions, and a beat clock for cutting on the
+ * music. Each primitive is small and composable; a showreel is a
+ * `createScenePlayer` driving a few of these together, not one mega-API.
+ *
+ * All primitives are signal-native, SSR-safe, dependency-free, and
+ * define sensible static behavior under `prefers-reduced-motion`.
+ */
+import { createSignal, onCleanup, } from "solid-js";
+import { animate } from "./animate.js";
+import { parseColorStops, sampleColorStops, } from "./color.js";
+import { resolveEasing } from "./easing.js";
+import { now, schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+function ownerDoc(el) {
+    const od = el
+        .ownerDocument;
+    if (od)
+        return od ?? undefined;
+    return typeof document !== "undefined" ? document : undefined;
+}
+/**
+ * Split an element's text into per-unit inline-block spans so each
+ * letter (or word) can be transformed independently. The original text
+ * is preserved as an aria-label for screen readers.
+ */
+function splitUnits(el, unit) {
+    const doc = ownerDoc(el);
+    if (!doc)
+        return [];
+    const text = el.textContent ?? "";
+    el.textContent = "";
+    el.setAttribute("aria-label", text);
+    const spans = [];
+    const push = (content) => {
+        const s = doc.createElement("span");
+        s.textContent = content;
+        s.setAttribute("aria-hidden", "true");
+        s.style.display = "inline-block";
+        s.style.willChange = "transform, opacity, filter";
+        el.appendChild(s);
+        spans.push(s);
+    };
+    if (unit === "words") {
+        for (const word of text.split(/(\s+)/)) {
+            if (word.length === 0)
+                continue;
+            if (/^\s+$/.test(word)) {
+                el.appendChild(doc.createTextNode(word));
+            }
+            else {
+                push(word);
+            }
+        }
+    }
+    else {
+        for (const ch of text)
+            push(ch === " " ? " " : ch);
+    }
+    return spans;
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/** Round to 2 decimals for style values. */
+function fmt(v) {
+    return String(Math.round(v * 100) / 100);
+}
+function applyKineticStyle(el, e, from) {
+    const t = 1 - e;
+    const y = from.y * t;
+    const scale = from.scale + (1 - from.scale) * e;
+    const rotate = from.rotate * t;
+    const blur = from.blur * t;
+    const opacity = from.opacity + (1 - from.opacity) * e;
+    el.style.transform =
+        `translateY(${fmt(y)}px) scale(${fmt(scale)}) rotate(${fmt(rotate)}deg)`;
+    el.style.filter = blur > 0.05 ? `blur(${fmt(blur)}px)` : "none";
+    el.style.opacity = fmt(opacity);
+}
+/**
+ * Kinetic typography: each character (or word) flies in with position,
+ * blur, scale, and opacity, staggered for that showreel title feel.
+ *
+ * One master clock drives every unit, so a headline with 40 characters
+ * costs a single rAF task, not 40 timers. Units animate through the
+ * same `from` state with per-unit easing.
+ *
+ * SSR-safe: no-op on the server. Under reduced motion every unit jumps
+ * to its final state when `play()` runs, so the text is fully readable.
+ *
+ * ```tsx
+ * let title!: HTMLHeadingElement
+ * const kinetic = createKineticType(() => title, {
+ *   unit: "chars",
+ *   stagger: 35,
+ *   from: { y: 40, blur: 12, scale: 0.8 },
+ *   easing: "easeOutExpo",
+ * })
+ * onMount(() => kinetic.play())
+ * <h1 ref={title}>Showreel</h1>
+ * ```
+ */
+export function createKineticType(ref, options = {}) {
+    const { unit = "chars", duration = 550, stagger = 45, easing: easingOpt = "easeOutExpo", } = options;
+    const from = {
+        y: options.from?.y ?? 28,
+        blur: options.from?.blur ?? 10,
+        scale: options.from?.scale ?? 0.85,
+        opacity: options.from?.opacity ?? 0,
+        rotate: options.from?.rotate ?? 0,
+    };
+    const easing = resolveEasing(easingOpt);
+    const [status, setStatus] = createSignal("idle");
+    let units = [];
+    let controls = null;
+    let runToken = 0;
+    const play = () => {
+        const token = ++runToken;
+        controls?.stop();
+        controls = null;
+        units = [];
+        if (typeof window !== "undefined") {
+            const el = ref();
+            if (el)
+                units = splitUnits(el, unit);
+        }
+        if (units.length === 0) {
+            setStatus("done");
+            return Promise.resolve();
+        }
+        setStatus("running");
+        const total = duration + stagger * (units.length - 1);
+        return new Promise((resolve) => {
+            // Declared before animate() runs: under reduced motion animate()
+            // calls onComplete synchronously, before its return value exists.
+            let stepControls = null;
+            let completed = false;
+            stepControls = animate(0, total, {
+                duration: total,
+                easing: "linear",
+                onUpdate: (elapsed) => {
+                    for (let i = 0; i < units.length; i++) {
+                        const local = clamp01((elapsed - i * stagger) / duration);
+                        applyKineticStyle(units[i], easing(local), from);
+                    }
+                },
+                onComplete: () => {
+                    completed = true;
+                    if (token === runToken) {
+                        controls = null;
+                        setStatus("done");
+                    }
+                    resolve();
+                },
+            });
+            if (!completed)
+                controls = stepControls;
+            // `finished` also resolves when the reveal is stopped, which
+            // unblocks the play() promise. The token check in onComplete keeps
+            // a stale stop from marking a newer run done.
+            void stepControls.finished.then(() => {
+                if (controls === stepControls)
+                    controls = null;
+                resolve();
+            });
+        });
+    };
+    const stop = () => {
+        runToken++;
+        controls?.stop();
+        controls = null;
+        setStatus("idle");
+    };
+    onCleanup(stop);
+    return {
+        play,
+        stop,
+        replay: () => {
+            stop();
+            return play();
+        },
+        status,
+    };
+}
+/**
+ * Scene orchestrator for showreels and launch films: an ordered list of
+ * scenes, each with a duration and enter/exit hooks. Think of it as the
+ * paused-master-timeline pattern from motion-design tools, expressed as
+ * signals: `scene()` tells your view which scene is live, and the hooks
+ * trigger each scene's choreography (a `createKineticType`, a camera
+ * move, a color shift).
+ *
+ * SSR-safe: scenes never advance on the server. Under reduced motion
+ * `play()` jumps straight to the last scene (the clean final frame)
+ * instead of stepping through.
+ *
+ * ```ts
+ * const player = createScenePlayer([
+ *   { duration: 1200, onEnter: () => hookTitle.play() },
+ *   { duration: 2000, onEnter: () => cameraZoom.play() },
+ *   { duration: 1500, onEnter: () => showLogo() }, // final frame
+ * ])
+ * player.scene() // 0, 1, 2 as the reel plays
+ * await player.play()
+ * ```
+ */
+export function createScenePlayer(scenes) {
+    const [scene, setScene] = createSignal(-1);
+    const [status, setStatus] = createSignal("idle");
+    let cancel = null;
+    let index = -1;
+    let elapsed = 0;
+    let lastTick = 0;
+    let resolvePlay = null;
+    const finish = () => {
+        cancel?.();
+        cancel = null;
+        const done = resolvePlay;
+        resolvePlay = null;
+        done?.();
+        setStatus("done");
+    };
+    const enter = (i) => {
+        index = i;
+        elapsed = 0;
+        setScene(i);
+        scenes[i].onEnter?.(i);
+    };
+    const advance = () => {
+        const prev = index;
+        scenes[prev]?.onExit?.(prev);
+        if (prev + 1 >= scenes.length) {
+            finish();
+        }
+        else {
+            enter(prev + 1);
+        }
+    };
+    const tick = (t) => {
+        const dt = t - lastTick;
+        lastTick = t;
+        elapsed += dt;
+        if (elapsed >= Math.max(scenes[index].duration, 0)) {
+            advance();
+        }
+        return status() === "running";
+    };
+    const startClock = () => {
+        cancel?.();
+        lastTick = now();
+        cancel = schedule(tick);
+    };
+    const play = () => {
+        cancel?.();
+        cancel = null;
+        // A superseded play() must not leave its caller hanging.
+        const prev = resolvePlay;
+        resolvePlay = null;
+        prev?.();
+        if (scenes.length === 0) {
+            setScene(-1);
+            setStatus("done");
+            return Promise.resolve();
+        }
+        if (prefersReducedMotion() || typeof window === "undefined") {
+            // Reduced motion / SSR: jump to the clean final frame.
+            const last = scenes.length - 1;
+            if (index >= 0)
+                scenes[index]?.onExit?.(index);
+            enter(last);
+            setStatus("done");
+            return Promise.resolve();
+        }
+        const resuming = status() === "paused" && index >= 0 && index < scenes.length;
+        if (!resuming) {
+            // Fresh start, including after done(): begin at the first scene.
+            enter(0);
+        }
+        setStatus("running");
+        startClock();
+        return new Promise((resolve) => {
+            resolvePlay = resolve;
+        });
+    };
+    const pause = () => {
+        if (status() !== "running")
+            return;
+        cancel?.();
+        cancel = null;
+        // Resolve the pending play() promise: the reel is suspended, and the
+        // caller must not hang forever waiting for the last scene.
+        const done = resolvePlay;
+        resolvePlay = null;
+        done?.();
+        setStatus("paused");
+    };
+    const stop = () => {
+        cancel?.();
+        cancel = null;
+        if (index >= 0)
+            scenes[index]?.onExit?.(index);
+        const done = resolvePlay;
+        resolvePlay = null;
+        done?.();
+        index = -1;
+        elapsed = 0;
+        setScene(-1);
+        setStatus("idle");
+    };
+    const goTo = (i) => {
+        if (scenes.length === 0)
+            return;
+        const clamped = Math.max(0, Math.min(scenes.length - 1, i));
+        const wasRunning = status() === "running";
+        if (index >= 0 && index !== clamped)
+            scenes[index]?.onExit?.(index);
+        enter(clamped);
+        if (wasRunning) {
+            setStatus("running");
+            startClock();
+        }
+    };
+    onCleanup(stop);
+    return {
+        scene,
+        status,
+        play,
+        pause,
+        stop,
+        replay: () => {
+            stop();
+            return play();
+        },
+        next: () => goTo(index + 1),
+        prev: () => goTo(index - 1),
+        goTo,
+    };
+}
+/**
+ * Camera moves for a motion-design stage: pan and zoom driven by a
+ * 0-to-1 progress signal, returned as a compositor-friendly transform
+ * string (`translate3d(...) scale(...)`).
+ *
+ * Drive `progress` with anything: a `createScenePlayer` scene's own
+ * clock, an `animate()` tween, or scroll. Keyframes sort themselves by
+ * `at`; progress outside the range clamps to the end poses.
+ *
+ * Pure computation, no listeners, no rAF: SSR-safe by construction.
+ * Under reduced motion it holds the final keyframe's pose.
+ *
+ * ```tsx
+ * const [p, setP] = createSignal(0)
+ * // Slow dolly-in across the scene.
+ * const cam = createCamera({
+ *   progress: p,
+ *   keyframes... // via options below
+ * })
+ * ```
+ */
+export function createCamera(keyframes, options) {
+    if (keyframes.length === 0) {
+        throw new Error("createCamera needs at least one keyframe.");
+    }
+    const sorted = [...keyframes]
+        .sort((a, b) => a.at - b.at)
+        .map((k) => ({
+        at: k.at,
+        x: k.x ?? 0,
+        y: k.y ?? 0,
+        scale: k.scale ?? 1,
+        easing: resolveEasing(k.easing ?? options.easing ?? "linear"),
+    }));
+    const pose = (p) => {
+        const t = clamp01(p);
+        let a = sorted[0];
+        let b = sorted[sorted.length - 1];
+        let local = 0;
+        if (t <= sorted[0].at) {
+            a = sorted[0];
+            b = sorted[0];
+        }
+        else if (t >= sorted[sorted.length - 1].at) {
+            a = sorted[sorted.length - 1];
+            b = sorted[sorted.length - 1];
+        }
+        else {
+            let i = 0;
+            while (i < sorted.length - 2 && sorted[i + 1].at <= t)
+                i++;
+            a = sorted[i];
+            b = sorted[i + 1];
+            const span = b.at - a.at;
+            local = span <= 0 ? 0 : b.easing((t - a.at) / span);
+        }
+        const x = a.x + (b.x - a.x) * local;
+        const y = a.y + (b.y - a.y) * local;
+        const s = a.scale + (b.scale - a.scale) * local;
+        return `translate3d(${fmt(x)}px, ${fmt(y)}px, 0) scale(${fmt(s)})`;
+    };
+    if (prefersReducedMotion()) {
+        const end = pose(1);
+        return () => end;
+    }
+    return () => pose(options.progress());
+}
+/**
+ * Time-based color interpolation across stops: the sibling of
+ * `createScrollColor` for motion graphics, where color shifts run on a
+ * clock instead of scroll. Colors interpolate in linear light, so
+ * midpoints stay vivid, and alpha channels interpolate too.
+ *
+ * Under reduced motion `play()` jumps straight to the final stop's
+ * color. SSR-safe: `color()` returns the final stop's color.
+ *
+ * ```ts
+ * const shift = createColorShift(
+ *   [
+ *     { at: 0, color: "#0a1220" },
+ *     { at: 0.5, color: "#2f8fdd" },
+ *     { at: 1, color: "#d9a441", easing: "easeInOutQuad" },
+ *   ],
+ *   { duration: 2000 },
+ * )
+ * shift.color() // "#0a1220" ... "#d9a441" as it plays
+ * await shift.play()
+ * ```
+ */
+export function createColorShift(stops, options = {}) {
+    if (stops.length === 0) {
+        throw new Error("createColorShift needs at least one color stop.");
+    }
+    const { duration = 1200, delay = 0, format = "hex", } = options;
+    const parsed = parseColorStops(stops, options.easing);
+    const [progress, setProgress] = createSignal(0);
+    const [status, setStatus] = createSignal("idle");
+    let controls = null;
+    let runToken = 0;
+    const color = () => sampleColorStops(parsed, progress(), format);
+    const play = () => {
+        const token = ++runToken;
+        controls?.stop();
+        controls = null;
+        setProgress(0);
+        setStatus("running");
+        return new Promise((resolve) => {
+            // Declared before animate() runs: under reduced motion animate()
+            // calls onComplete synchronously, before its return value exists.
+            let shiftControls = null;
+            let completed = false;
+            shiftControls = animate(0, 1, {
+                duration,
+                delay,
+                easing: "linear",
+                onUpdate: (v) => {
+                    if (token === runToken)
+                        setProgress(v);
+                },
+                onComplete: () => {
+                    completed = true;
+                    if (token === runToken) {
+                        controls = null;
+                        setStatus("done");
+                    }
+                    resolve();
+                },
+            });
+            if (!completed)
+                controls = shiftControls;
+            // `finished` also resolves when the shift is stopped, which
+            // unblocks the play() promise.
+            void shiftControls.finished.then(() => {
+                if (controls === shiftControls)
+                    controls = null;
+                resolve();
+            });
+        });
+    };
+    const stop = () => {
+        runToken++;
+        controls?.stop();
+        controls = null;
+        setStatus("idle");
+    };
+    onCleanup(stop);
+    return {
+        color,
+        play,
+        stop,
+        replay: () => {
+            stop();
+            return play();
+        },
+        status,
+    };
+}
+function transitionStyles(type, direction, p) {
+    const inv = fmt((1 - p) * 100);
+    const none = {
+        opacity: "1",
+        transform: "none",
+        clipPath: "none",
+    };
+    if (type === "cut") {
+        return p >= 1
+            ? {
+                out: { ...none, opacity: "0" },
+                in: { ...none, opacity: "1" },
+            }
+            : {
+                out: { ...none, opacity: "1" },
+                in: { ...none, opacity: "0" },
+            };
+    }
+    if (type === "fade") {
+        return {
+            out: { ...none, opacity: fmt(1 - p) },
+            in: { ...none, opacity: fmt(p) },
+        };
+    }
+    if (type === "slide") {
+        const axis = direction === "left" || direction === "right" ? "X" : "Y";
+        const sign = direction === "left" || direction === "up" ? -1 : 1;
+        return {
+            out: {
+                ...none,
+                transform: `translate${axis}(${fmt(sign * p * 100)}%)`,
+            },
+            in: {
+                ...none,
+                transform: `translate${axis}(${fmt(-sign * (1 - p) * 100)}%)`,
+                opacity: "1",
+            },
+        };
+    }
+    // wipe: the incoming scene reveals over the outgoing one.
+    const inset = p >= 1
+        ? "none"
+        : direction === "left"
+            ? `inset(0 ${inv}% 0 0)`
+            : direction === "right"
+                ? `inset(0 0 0 ${inv}%)`
+                : direction === "up"
+                    ? `inset(0 0 ${inv}% 0)`
+                    : `inset(${inv}% 0 0 0)`;
+    return {
+        out: { ...none, opacity: "1" },
+        in: { ...none, opacity: "1", clipPath: inset },
+    };
+}
+/**
+ * Match-cut style scene handoffs: `outgoing()` and `incoming()` return
+ * style objects for the two scene layers, driven by one 0-to-1 progress.
+ *
+ * - "cut": instant swap, no animation.
+ * - "fade": crossfade.
+ * - "slide": the outgoing scene exits one way while the incoming scene
+ *   enters from the opposite side.
+ * - "wipe": the incoming scene reveals over the outgoing one with a
+ *   clip-path wipe.
+ *
+ * Everything animates on opacity, transform, or clip-path, so handoffs
+ * stay on the compositor. Under reduced motion every type degrades to a
+ * cut: the swap happens instantly.
+ *
+ * ```tsx
+ * const cut = createTransition({ type: "wipe", direction: "left", duration: 600 })
+ * const go = async () => {
+ *   showSceneB()
+ *   await cut.play()
+ * }
+ * <div style={cut.outgoing()}>{sceneA}</div>
+ * <div style={cut.incoming()}>{sceneB}</div>
+ * ```
+ */
+export function createTransition(options = {}) {
+    const { type = "fade", direction = "left", duration = 500, easing: easingOpt = "easeInOutCubic", } = options;
+    const easing = resolveEasing(easingOpt);
+    const [raw, setRaw] = createSignal(0);
+    const [status, setStatus] = createSignal("idle");
+    let controls = null;
+    let runToken = 0;
+    const progress = () => easing(clamp01(raw()));
+    const outgoing = () => transitionStyles(type, direction, progress()).out;
+    const incoming = () => transitionStyles(type, direction, progress()).in;
+    const play = () => {
+        const token = ++runToken;
+        controls?.stop();
+        controls = null;
+        // Reduced motion (or an explicit cut) degrades to an instant swap.
+        if (type === "cut" || prefersReducedMotion()) {
+            setRaw(1);
+            setStatus("done");
+            return Promise.resolve();
+        }
+        setRaw(0);
+        setStatus("running");
+        return new Promise((resolve) => {
+            // Declared before animate() runs: under reduced motion animate()
+            // calls onComplete synchronously, before its return value exists.
+            let cutControls = null;
+            let completed = false;
+            cutControls = animate(0, 1, {
+                duration,
+                easing: "linear",
+                onUpdate: (v) => {
+                    if (token === runToken)
+                        setRaw(v);
+                },
+                onComplete: () => {
+                    completed = true;
+                    if (token === runToken) {
+                        controls = null;
+                        setStatus("done");
+                    }
+                    resolve();
+                },
+            });
+            if (!completed)
+                controls = cutControls;
+            // `finished` also resolves when the handoff is stopped, which
+            // unblocks the play() promise.
+            void cutControls.finished.then(() => {
+                if (controls === cutControls)
+                    controls = null;
+                resolve();
+            });
+        });
+    };
+    const stop = () => {
+        runToken++;
+        controls?.stop();
+        controls = null;
+        setStatus("idle");
+    };
+    onCleanup(stop);
+    return {
+        progress,
+        outgoing,
+        incoming,
+        play,
+        stop,
+        replay: () => {
+            stop();
+            return play();
+        },
+        status,
+    };
+}
+/**
+ * A beat clock for cutting on the music: at 120 BPM it ticks twice a
+ * second, and `onBeat` fires your scene cuts, kinetic type replays, or
+ * color shifts in time. `phase()` gives the fractional position inside
+ * the current beat for syncing continuous motion to the rhythm.
+ *
+ * Beats are timing, not motion, so the clock keeps ticking under
+ * reduced motion (your callbacks decide what that means visually).
+ * SSR-safe: `start()` is a no-op without requestAnimationFrame.
+ *
+ * ```ts
+ * const beat = createBeat({ bpm: 128 })
+ * const off = beat.onBeat((b) => {
+ *   if (b % 8 === 0) player.next() // cut scenes every 2 bars
+ * })
+ * beat.start()
+ * ```
+ */
+export function createBeat(options = {}) {
+    const { bpm = 120, beatsPerBar = 4 } = options;
+    const msPerBeat = 60000 / Math.max(bpm, 1);
+    const perBar = Math.max(1, Math.floor(beatsPerBar));
+    const [beat, setBeat] = createSignal(0);
+    const [bar, setBar] = createSignal(0);
+    const [phase, setPhase] = createSignal(0);
+    const [status, setStatus] = createSignal("idle");
+    const listeners = new Set();
+    let cancel = null;
+    let t0 = 0;
+    let lastBeat = -1;
+    const start = () => {
+        if (status() === "running")
+            return;
+        if (typeof window === "undefined")
+            return;
+        t0 = now();
+        lastBeat = -1;
+        setBeat(0);
+        setBar(0);
+        setPhase(0);
+        setStatus("running");
+        cancel = schedule((t) => {
+            const floating = (t - t0) / msPerBeat;
+            const b = Math.floor(floating);
+            if (b !== lastBeat) {
+                lastBeat = b;
+                setBeat(b);
+                setBar(Math.floor(b / perBar));
+                for (const cb of listeners)
+                    cb(b);
+            }
+            setPhase(floating - b);
+            return status() === "running";
+        });
+    };
+    const stop = () => {
+        cancel?.();
+        cancel = null;
+        setStatus("idle");
+    };
+    onCleanup(stop);
+    return {
+        beat,
+        bar,
+        phase,
+        onBeat: (cb) => {
+            listeners.add(cb);
+            return () => {
+                listeners.delete(cb);
+            };
+        },
+        start,
+        stop,
+        status,
+    };
+}