solid-drift 0.2.0 → 0.8.0

package/dist/text.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Internal text utilities shared by the motion-graphics primitives.
+ *
+ * Not part of the public API: family modules import from here, but
+ * nothing in this file is re-exported from the package index.
+ */
+/** Document owning the element, with an SSR-safe fallback. */
+export declare function ownerDoc(el: Element): 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. Any previous
+ * content is replaced.
+ */
+export declare function splitUnits(el: Element, unit: "chars" | "words"): HTMLElement[];
+/**
+ * Append per-unit inline-block spans for `text` to the element's
+ * existing content, without clearing it. Used by streaming text, where
+ * each flushed batch adds new units while earlier units keep playing.
+ */
+export declare function appendUnits(el: Element, text: string, unit: "chars" | "words"): HTMLElement[];
+/**
+ * Deterministic pseudo-random generator (mulberry32). Used for
+ * per-unit variance so seeded jitter renders identically on every
+ * run, which keeps tests stable and output reproducible.
+ */
+export declare function mulberry32(seed: number): () => number;

package/dist/text.js

@@ -0,0 +1,84 @@
+/**
+ * Internal text utilities shared by the motion-graphics primitives.
+ *
+ * Not part of the public API: family modules import from here, but
+ * nothing in this file is re-exported from the package index.
+ */
+/** Document owning the element, with an SSR-safe fallback. */
+export function ownerDoc(el) {
+    const od = el
+        .ownerDocument;
+    if (od)
+        return od ?? undefined;
+    return typeof document !== "undefined" ? document : undefined;
+}
+function pushUnit(doc, parent, 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";
+    parent.appendChild(s);
+    return s;
+}
+function appendTokens(doc, parent, text, unit) {
+    const spans = [];
+    if (unit === "words") {
+        for (const word of text.split(/(\s+)/)) {
+            if (word.length === 0)
+                continue;
+            if (/^\s+$/.test(word)) {
+                parent.appendChild(doc.createTextNode(word));
+            }
+            else {
+                spans.push(pushUnit(doc, parent, word));
+            }
+        }
+    }
+    else {
+        for (const ch of text)
+            spans.push(pushUnit(doc, parent, ch === " " ? " " : ch));
+    }
+    return spans;
+}
+/**
+ * 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. Any previous
+ * content is replaced.
+ */
+export function splitUnits(el, unit) {
+    const doc = ownerDoc(el);
+    if (!doc)
+        return [];
+    const text = el.textContent ?? "";
+    el.textContent = "";
+    el.setAttribute("aria-label", text);
+    return appendTokens(doc, el, text, unit);
+}
+/**
+ * Append per-unit inline-block spans for `text` to the element's
+ * existing content, without clearing it. Used by streaming text, where
+ * each flushed batch adds new units while earlier units keep playing.
+ */
+export function appendUnits(el, text, unit) {
+    const doc = ownerDoc(el);
+    if (!doc)
+        return [];
+    return appendTokens(doc, el, text, unit);
+}
+/**
+ * Deterministic pseudo-random generator (mulberry32). Used for
+ * per-unit variance so seeded jitter renders identically on every
+ * run, which keeps tests stable and output reproducible.
+ */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/timeline.d.ts

@@ -0,0 +1,45 @@
+import { type Accessor } from "solid-js";
+import { type AnimateOptions } from "./animate.js";
+export interface TimelineStep extends AnimateOptions {
+    /** Start value of this step. */
+    from: number;
+    /** End value of this step. */
+    to: number;
+}
+export type TimelineStatus = "idle" | "running" | "done";
+export interface TimelineControls {
+    /** Play every step in order. Resolves when the last step completes. */
+    start: () => Promise<void>;
+    /** Stop the timeline wherever it is. The start() promise resolves. */
+    stop: () => void;
+    /** Stop and play again from the first step. */
+    replay: () => Promise<void>;
+    /** Reactive status: "idle" | "running" | "done". */
+    status: Accessor<TimelineStatus>;
+}
+/**
+ * Plays a sequence of one-shot animations back to back.
+ *
+ * Each step is an `animate()` call: `from`/`to` plus duration, delay,
+ * easing, and `onUpdate`. Steps run strictly in order, so one step's
+ * `onUpdate` can drive one element while the next step drives another,
+ * building choreographed entrances without nested callbacks.
+ *
+ * `stop()` halts mid-step and resolves the in-flight `start()` promise.
+ * `replay()` restarts from the first step. The timeline also stops
+ * itself on cleanup.
+ *
+ * Under reduced motion every step jumps straight to its end value (each
+ * step's `onUpdate(to)` still runs, so the final state is always
+ * correct). SSR-safe: steps apply their end values instantly.
+ *
+ * ```ts
+ * const intro = createTimeline([
+ *   { from: 0, to: 1, duration: 400, onUpdate: (v) => (title.style.opacity = String(v)) },
+ *   { from: 24, to: 0, duration: 500, easing: "easeOutExpo", onUpdate: (v) => (title.style.transform = `translateY(${v}px)`) },
+ *   { from: 0, to: 1, duration: 300, onUpdate: (v) => (cta.style.opacity = String(v)) },
+ * ])
+ * await intro.start()
+ * ```
+ */
+export declare function createTimeline(steps: TimelineStep[]): TimelineControls;

package/dist/timeline.js

@@ -0,0 +1,93 @@
+import { createSignal, onCleanup } from "solid-js";
+import { animate, } from "./animate.js";
+/**
+ * Plays a sequence of one-shot animations back to back.
+ *
+ * Each step is an `animate()` call: `from`/`to` plus duration, delay,
+ * easing, and `onUpdate`. Steps run strictly in order, so one step's
+ * `onUpdate` can drive one element while the next step drives another,
+ * building choreographed entrances without nested callbacks.
+ *
+ * `stop()` halts mid-step and resolves the in-flight `start()` promise.
+ * `replay()` restarts from the first step. The timeline also stops
+ * itself on cleanup.
+ *
+ * Under reduced motion every step jumps straight to its end value (each
+ * step's `onUpdate(to)` still runs, so the final state is always
+ * correct). SSR-safe: steps apply their end values instantly.
+ *
+ * ```ts
+ * const intro = createTimeline([
+ *   { from: 0, to: 1, duration: 400, onUpdate: (v) => (title.style.opacity = String(v)) },
+ *   { from: 24, to: 0, duration: 500, easing: "easeOutExpo", onUpdate: (v) => (title.style.transform = `translateY(${v}px)`) },
+ *   { from: 0, to: 1, duration: 300, onUpdate: (v) => (cta.style.opacity = String(v)) },
+ * ])
+ * await intro.start()
+ * ```
+ */
+export function createTimeline(steps) {
+    const [status, setStatus] = createSignal("idle");
+    let current = null;
+    let runToken = 0;
+    const play = async () => {
+        const token = ++runToken;
+        const alive = () => token === runToken;
+        setStatus("running");
+        for (const step of steps) {
+            if (!alive())
+                break;
+            const { from, to, ...options } = step;
+            if (typeof window === "undefined") {
+                options.onUpdate?.(to);
+                options.onComplete?.();
+                continue;
+            }
+            await new Promise((resolve) => {
+                // Declared before animate() runs: under reduced motion animate()
+                // calls onComplete synchronously, before its return value exists.
+                // The completed flag keeps `current` from pointing at a control
+                // that already finished in that synchronous path.
+                let stepControls = null;
+                let completed = false;
+                stepControls = animate(from, to, {
+                    ...options,
+                    onComplete: () => {
+                        completed = true;
+                        options.onComplete?.();
+                        if (current === stepControls)
+                            current = null;
+                        resolve();
+                    },
+                });
+                if (!completed)
+                    current = stepControls;
+                // `finished` also resolves when the step is stopped, which
+                // unblocks the chain, the alive() check then ends the run.
+                void stepControls.finished.then(() => {
+                    if (current === stepControls)
+                        current = null;
+                    resolve();
+                });
+            });
+        }
+        if (alive())
+            setStatus("done");
+    };
+    const stop = () => {
+        runToken++;
+        current?.stop();
+        current = null;
+        setStatus("idle");
+    };
+    const controls = {
+        start: () => play(),
+        stop,
+        replay: () => {
+            stop();
+            return play();
+        },
+        status,
+    };
+    onCleanup(stop);
+    return controls;
+}

package/dist/trail.d.ts

@@ -0,0 +1,27 @@
+import { type Accessor } from "solid-js";
+export interface TrailOptions {
+    /** How far behind the source the trail follows, in ms. Default 120. */
+    delay?: number;
+}
+/**
+ * A signal that replays another signal's past: it returns the value the
+ * source had `delay` milliseconds ago, interpolated between samples.
+ *
+ * Chain trails off one source for follower effects (a cursor with a
+ * comet tail, cascading highlights), or trail a scroll progress for a
+ * delayed echo of the page. The trail catches up and parks exactly on
+ * the latest value when the source rests.
+ *
+ * The follow loop runs on the shared clock only while the trail is
+ * behind: it starts when the source changes and stops once caught up.
+ *
+ * SSR-safe: returns the source itself on the server. Under reduced
+ * motion it also returns the source directly (no trailing motion).
+ *
+ * ```tsx
+ * const [tab, setTab] = createSignal(0)
+ * // The indicator glides behind the selection instead of jumping.
+ * const ghost = createTrail(tab, { delay: 150 })
+ * ```
+ */
+export declare function createTrail(source: Accessor<number>, options?: TrailOptions): Accessor<number>;

package/dist/trail.js

@@ -0,0 +1,75 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * A signal that replays another signal's past: it returns the value the
+ * source had `delay` milliseconds ago, interpolated between samples.
+ *
+ * Chain trails off one source for follower effects (a cursor with a
+ * comet tail, cascading highlights), or trail a scroll progress for a
+ * delayed echo of the page. The trail catches up and parks exactly on
+ * the latest value when the source rests.
+ *
+ * The follow loop runs on the shared clock only while the trail is
+ * behind: it starts when the source changes and stops once caught up.
+ *
+ * SSR-safe: returns the source itself on the server. Under reduced
+ * motion it also returns the source directly (no trailing motion).
+ *
+ * ```tsx
+ * const [tab, setTab] = createSignal(0)
+ * // The indicator glides behind the selection instead of jumping.
+ * const ghost = createTrail(tab, { delay: 150 })
+ * ```
+ */
+export function createTrail(source, options = {}) {
+    const { delay = 120 } = options;
+    if (typeof window === "undefined" || prefersReducedMotion() || delay <= 0) {
+        return source;
+    }
+    const [value, setValue] = createSignal(untrack(source));
+    const samples = [
+        [now(), untrack(source)],
+    ];
+    let cancel = null;
+    const tick = (t) => {
+        const target = t - delay;
+        // Drop samples the trail has already passed (keep one for context).
+        while (samples.length > 2 && samples[1][0] <= target)
+            samples.shift();
+        const [firstT, firstV] = samples[0];
+        const [lastT, lastV] = samples[samples.length - 1];
+        let current;
+        if (samples.length === 1 || target <= firstT) {
+            current = firstV;
+        }
+        else if (target >= lastT) {
+            current = lastV;
+        }
+        else {
+            const [ta, va] = samples[0];
+            const [tb, vb] = samples[1];
+            const p = (target - ta) / Math.max(tb - ta, 0.0001);
+            current = va + (vb - va) * p;
+        }
+        setValue(current);
+        if (target >= lastT) {
+            cancel = null; // caught up: park exactly on the latest value
+            return false;
+        }
+        return true;
+    };
+    const kick = () => {
+        if (!cancel)
+            cancel = schedule(tick);
+    };
+    createEffect(() => {
+        const v = source();
+        samples.push([now(), v]);
+        if (samples.length > 600)
+            samples.splice(0, samples.length - 600);
+        kick();
+    });
+    onCleanup(() => cancel?.());
+    return value;
+}

package/dist/tween.d.ts

@@ -13,11 +13,11 @@ export interface TweenOptions {
 /**
  * A signal that tweens toward a source signal's value over a fixed duration.
  *
- * Interrupting mid-tween retargets from the current value — no snapping.
+ * Interrupting mid-tween retargets from the current value, with no snapping.
  *
  * ```tsx
- * const [open, setOpen] = createSignal(false);
- * const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 });
+ * const [open, setOpen] = createSignal(false)
+ * const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 })
  * <div style={{ opacity: opacity() }} />
  * ```
  */

package/dist/tween.js

@@ -5,11 +5,11 @@ import { prefersReducedMotion } from "./reduced-motion.js";
 /**
  * A signal that tweens toward a source signal's value over a fixed duration.
  *
- * Interrupting mid-tween retargets from the current value — no snapping.
+ * Interrupting mid-tween retargets from the current value, with no snapping.
  *
  * ```tsx
- * const [open, setOpen] = createSignal(false);
- * const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 });
+ * const [open, setOpen] = createSignal(false)
+ * const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 })
  * <div style={{ opacity: opacity() }} />
  * ```
  */

package/dist/typography.d.ts

@@ -0,0 +1,241 @@
+import { type Accessor } from "solid-js";
+import { type Easing, type EasingName } from "./easing.js";
+type MaybeElement = () => Element | null | undefined;
+export interface FontSwapOptions {
+    /** Font family to swap to on hover. */
+    to: string;
+    /** Font weight to swap to. Defaults to keeping the current weight. */
+    toWeight?: string | number;
+    /** Duration in ms for each half of the letter roll. Default 160. */
+    duration?: number;
+    /** Stagger in ms between letters. Default 24. */
+    stagger?: number;
+    /** Easing for the roll. Default "easeInOutCubic". */
+    easing?: Easing | EasingName;
+    /** On touch devices (no hover) a tap toggles the swap. Default true. */
+    tapToToggle?: boolean;
+}
+export interface FontSwapResult {
+    /** True while the swapped font is showing. */
+    swapped: Accessor<boolean>;
+    /** Swap to the alternate font (true) or back (false). */
+    swap: (to: boolean) => void;
+    /** Toggle between the two fonts. */
+    toggle: () => void;
+}
+/**
+ * Swap a heading's font family (and optionally weight) on hover with a
+ * per-letter roll: each letter flips away in the old font and lands in the
+ * new one. Because the letters roll individually, the metric change never
+ * reads as a layout jump.
+ *
+ * On touch devices a tap toggles the swap instead of hover. Under reduced
+ * motion the font swaps instantly with no roll.
+ */
+export declare function createFontSwap(ref: MaybeElement, options: FontSwapOptions): FontSwapResult;
+export interface TypingOptions {
+    /** Text to type. Defaults to the element's current text. */
+    text?: string;
+    /** Base milliseconds per character. Default 45. */
+    speed?: number;
+    /** Randomness 0..1 added to each character's timing. Default 0.4. */
+    variance?: number;
+    /** Extra pause in ms after specific characters. */
+    pauses?: Record<string, number>;
+    /** Cursor glyph. Set to "" for no cursor. Default "|". */
+    cursor?: string;
+    /** Cursor blink period in ms. Default 530. */
+    blinkRate?: number;
+    /** Start typing as soon as the element is available. Default true. */
+    autostart?: boolean;
+    /** Called when typing completes. */
+    onComplete?: () => void;
+}
+export interface TypingResult {
+    /** Start typing from the beginning. */
+    start: () => void;
+    /** Type again from an empty element. */
+    replay: () => void;
+    /** Stop typing where it is. */
+    stop: () => void;
+    /** True while characters are being typed. */
+    typing: Accessor<boolean>;
+    /** True once the full text is showing. */
+    completed: Accessor<boolean>;
+}
+/**
+ * Type out text character by character with human-like variable speed:
+ * each character's delay jitters around the base speed, and punctuation
+ * from `pauses` gets a beat of its own. A blinking block cursor rides
+ * along and parks itself when the text is done.
+ *
+ * Under reduced motion (or on the server) the full text appears instantly.
+ */
+export declare function createTyping(ref: MaybeElement, options?: TypingOptions): TypingResult;
+export interface TextPhysicsOptions {
+    /** How far above their slots (px) letters start falling. Default 320. */
+    dropHeight?: number;
+    /** Gravity in px/s^2. Default 2600. */
+    gravity?: number;
+    /** Bounciness 0..1 on each bounce. Default 0.45. */
+    bounciness?: number;
+    /** Max initial tumble in degrees. Default 200. */
+    tumble?: number;
+    /** Stagger in ms between letters. Default 45. */
+    stagger?: number;
+    /** Bounce speed below which a letter settles. Default 60. */
+    restThreshold?: number;
+    /** Called when every letter has settled. */
+    onSettle?: () => void;
+}
+export interface TextPhysicsResult {
+    /** Rain the letters in: they fall, tumble, bounce, and settle into place. */
+    drop: () => void;
+    /** Fling the letters apart so they can rain again. */
+    scatter: () => void;
+    /** True once every letter has settled. */
+    settled: Accessor<boolean>;
+}
+/**
+ * Per-letter cartoon physics: `drop()` rains each letter from above with
+ * gravity, tumbling rotation, and squashy bounces until every letter lands
+ * in its slot. `scatter()` flings the letters apart so they can rain again.
+ *
+ * Pair it with `createInView` to rain a headline in as it scrolls into view.
+ * Under reduced motion (or on the server) letters simply sit in place.
+ */
+export declare function createTextPhysics(ref: MaybeElement, options?: TextPhysicsOptions): TextPhysicsResult;
+export interface TextTunnelOptions {
+    /** What drives the zoom: "time", "scroll", or your own 0..1 signal. Default "time". */
+    drive?: "time" | "scroll" | Accessor<number>;
+    /** Seconds per zoom cycle (time drive). Default 3. */
+    period?: number;
+    /** Number of depth layers. Default 6. */
+    layers?: number;
+    /** Scale of the front layer. Default 3. */
+    zoom?: number;
+}
+export interface TextTunnelResult {
+    /** The current 0..1 zoom phase. */
+    progress: Accessor<number>;
+    /** Stop a time-driven tunnel. */
+    stop: () => void;
+}
+/**
+ * An infinite 3D text tunnel: copies of the text at staggered depths zoom
+ * toward the viewer forever, each fading in from the distance and out past
+ * the camera. Drive it with time, with scroll progress, or with your own
+ * 0..1 signal.
+ *
+ * Under reduced motion (or on the server) the text renders as a single
+ * static line.
+ */
+export declare function createTextTunnel(ref: MaybeElement, options?: TextTunnelOptions): TextTunnelResult;
+export interface TextCutoutOptions {
+    /**
+     * "gradient": an animated inner world clipped inside the letterforms.
+     * "window": transparent fill with a stroked outline, made to overlay a
+     * live scene (canvas, video, 3D) so it shows through the letters.
+     * Default "gradient".
+     */
+    mode?: "gradient" | "window";
+    /** 0..1 signal driving the inner world. Defaults to a slow time drift. */
+    progress?: Accessor<number>;
+    /** The three colors of the inner world. */
+    palette?: [string, string, string];
+    /** Stroke color for "window" mode. Default "currentColor". */
+    stroke?: string;
+    /** Stroke width in px for "window" mode. Default 1.5. */
+    strokeWidth?: number;
+    /** Seconds per drift cycle (time drive). Default 9. */
+    period?: number;
+}
+/**
+ * Turn text into letter-shaped windows onto another world. In "gradient"
+ * mode an animated nebula drifts behind the letterforms via
+ * background-clip. In "window" mode the fill goes transparent with a
+ * stroked outline: overlay it on a canvas, video, or 3D scene and the live
+ * scene shows through the letters themselves.
+ */
+export declare function createTextCutout(ref: MaybeElement, options?: TextCutoutOptions): {
+    stop: () => void;
+};
+export interface TextGradientOptions {
+    /** 0..1 signal driving the hue cycle. Defaults to a slow time loop. */
+    progress?: Accessor<number>;
+    /** Hue degrees spread across the string. Default 140. */
+    spread?: number;
+    /** Base hue. Default 210. */
+    hue?: number;
+    /** Saturation percent. Default 85. */
+    saturation?: number;
+    /** Lightness percent. Default 62. */
+    lightness?: number;
+    /** Seconds per full hue cycle (time drive). Default 7. */
+    period?: number;
+}
+/**
+ * Paint each character its own hue and cycle the rainbow across the text:
+ * the hue shifts along the string by `spread` degrees and the whole cycle
+ * rotates over time (or with your own progress signal, e.g. scroll).
+ * Under reduced motion the gradient parks on its first frame.
+ */
+export declare function createTextGradient(ref: MaybeElement, options?: TextGradientOptions): {
+    stop: () => void;
+};
+export interface TextScrambleOptions {
+    /** Text to reveal. Defaults to the element's current text. */
+    text?: string;
+    /** Glyph pool the letters scramble through. */
+    charset?: string;
+    /** Stagger in ms between characters starting. Default 28. */
+    stagger?: number;
+    /** How long in ms each character scrambles before locking in. Default 500. */
+    duration?: number;
+    /** Milliseconds between glyph swaps. Default 50. */
+    frameRate?: number;
+    /** Start as soon as the element is available. Default true. */
+    autostart?: boolean;
+    /** Called when every character has locked in. */
+    onComplete?: () => void;
+}
+export interface TextScrambleResult {
+    /** Start the decode from the beginning. */
+    start: () => void;
+    /** Run the decode again. */
+    replay: () => void;
+    /** Stop mid-decode. */
+    stop: () => void;
+    /** True while glyphs are still resolving. */
+    scrambling: Accessor<boolean>;
+}
+/**
+ * A decoder-ring text reveal: every character cycles through random glyphs
+ * and locks into its final letter left to right, like a combination lock
+ * finding its code. Spaces resolve instantly.
+ *
+ * Under reduced motion (or on the server) the full text appears instantly.
+ */
+export declare function createTextScramble(ref: MaybeElement, options?: TextScrambleOptions): TextScrambleResult;
+export interface TextWaveOptions {
+    /** Wave height in px. Default 9. */
+    amplitude?: number;
+    /** Characters per full wave. Default 7. */
+    wavelength?: number;
+    /** Seconds per wave cycle. Default 1.8. */
+    period?: number;
+    /** Tilt each character with the wave slope. Default true. */
+    tilt?: boolean;
+    /** 0..1 signal driving the phase (e.g. scroll). Defaults to time. */
+    progress?: Accessor<number>;
+}
+/**
+ * A traveling sine wave across the text: each character bobs up and down
+ * (and tilts with the slope) as the wave passes through. Drive it with
+ * time for an ambient shimmer or with scroll progress for a wave that
+ * moves as you scroll. Under reduced motion the text sits still.
+ */
+export declare function createTextWave(ref: MaybeElement, options?: TextWaveOptions): {
+    stop: () => void;
+};
+export {};