solid-drift 0.2.0 → 0.7.1

package/dist/flip.js

@@ -0,0 +1,108 @@
+import { animate, } from "./animate.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * FLIP layout animation around a DOM mutation.
+ *
+ * Records the element's position and size (First), runs your `mutate()`
+ * which changes the layout (Last), then Inverts the delta as a transform
+ * and Plays it back to identity. List reorders, expanding panels, and
+ * grid reshuffles glide to their new spots instead of jumping.
+ *
+ * The element's pre-existing `transform` is captured and restored after
+ * the animation, so FLIP composes with other transform animations.
+ * `stop()` halts mid-flight and restores the original transform.
+ *
+ * SSR-safe and reduced-motion safe: the mutation runs with no animation.
+ * If the element does not move, no animation runs either.
+ *
+ * ```tsx
+ * import { animateFlip } from "solid-drift"
+ *
+ * const [items, setItems] = createSignal(["a", "b", "c"])
+ * let list!: HTMLUListElement
+ *
+ * const shuffle = () =>
+ *   animateFlip(
+ *     () => list,
+ *     () => setItems((prev) => [...prev].reverse()),
+ *     { duration: 450 },
+ *   )
+ * ```
+ */
+export function animateFlip(ref, mutate, options = {}) {
+    const { duration = 400, delay = 0, easing = "easeOutCubic", scale = true, } = options;
+    let resolveFinished;
+    const finished = new Promise((resolve) => {
+        resolveFinished = resolve;
+    });
+    let done = false;
+    const finish = () => {
+        if (done)
+            return;
+        done = true;
+        resolveFinished();
+    };
+    const el = ref();
+    if (typeof window === "undefined" || !el || prefersReducedMotion()) {
+        mutate();
+        finish();
+        return { stop: () => { }, finished };
+    }
+    const target = el;
+    const prevTransform = target.style.transform;
+    const first = target.getBoundingClientRect();
+    mutate();
+    let stopped = false;
+    let step = null;
+    const controls = {
+        stop: () => {
+            stopped = true;
+            step?.stop();
+            target.style.transform = prevTransform;
+            finish();
+        },
+        finished,
+    };
+    // Two frames: one for Solid's DOM update to flush, one to measure it.
+    requestAnimationFrame(() => requestAnimationFrame(() => {
+        if (stopped) {
+            finish();
+            return;
+        }
+        const last = target.getBoundingClientRect();
+        const dx = first.left - last.left;
+        const dy = first.top - last.top;
+        const sx = scale && last.width > 0 ? first.width / last.width : 1;
+        const sy = scale && last.height > 0 ? first.height / last.height : 1;
+        const moved = Math.abs(dx) >= 0.5 ||
+            Math.abs(dy) >= 0.5 ||
+            Math.abs(sx - 1) >= 0.001 ||
+            Math.abs(sy - 1) >= 0.001;
+        if (!moved) {
+            finish();
+            return;
+        }
+        const render = (eased) => {
+            const rest = 1 - eased;
+            target.style.transform =
+                `translate3d(${(dx * rest).toFixed(2)}px, ${(dy * rest).toFixed(2)}px, 0)` +
+                    (scale
+                        ? ` scale(${(1 + (sx - 1) * rest).toFixed(4)}, ${(1 + (sy - 1) * rest).toFixed(4)})`
+                        : "");
+        };
+        render(0);
+        // Force the inverted state to apply before the animation runs.
+        void target.offsetHeight;
+        step = animate(0, 1, {
+            duration,
+            delay,
+            easing,
+            onUpdate: render,
+            onComplete: () => {
+                target.style.transform = prevTransform;
+                finish();
+            },
+        });
+    }));
+    return controls;
+}

package/dist/horizontal.d.ts

@@ -0,0 +1,107 @@
+import { type Accessor } from "solid-js";
+export interface HorizontalScrollOptions {
+    /**
+     * The tall wrapper the user scrolls through. Its height beyond one
+     * viewport becomes the scroll range that drives the horizontal slide.
+     * Give it e.g. `height: 300vh` in CSS.
+     */
+    pin: () => HTMLElement | null | undefined;
+    /**
+     * The wide track that slides horizontally. Usually a flex row wider
+     * than the viewport, e.g. `display: flex; width: max-content`.
+     */
+    track: () => HTMLElement | null | undefined;
+    /**
+     * The sticky viewport showing one screenful of the track at a time,
+     * e.g. `position: sticky; top: 0; height: 100vh; overflow: hidden`.
+     * Defaults to the track's parent element.
+     */
+    stage?: () => HTMLElement | null | undefined;
+    /**
+     * Horizontal travel in pixels. Pass a number for a fixed distance or a
+     * function for a dynamic one (re-evaluated on every resize). Default:
+     * measured live as `track.scrollWidth - stage.clientWidth`.
+     */
+    distance?: number | (() => number);
+    /** Fraction of the scroll range where the slide begins. Default 0. */
+    start?: number;
+    /** Fraction of the scroll range where the slide ends. Default 1. */
+    end?: number;
+    /** Spring stiffness smoothing vertical scroll into horizontal motion. Default 120. */
+    stiffness?: number;
+    /** Spring damping for the smoothing. Default 20. */
+    damping?: number;
+    /**
+     * Called with the smoothed progress (0 to 1) whenever it updates,
+     * including once on mount. Useful for per-panel parallax driven by
+     * the same timeline.
+     */
+    onProgress?: (progress: number) => void;
+}
+export interface HorizontalScrollResult {
+    /**
+     * Smoothed progress through the pinned range, 0 to 1. Drive panel
+     * parallax or progress indicators from this signal.
+     */
+    progress: Accessor<number>;
+    /** The current horizontal travel in pixels. */
+    distance: Accessor<number>;
+    /** Re-measure the distance and recompute progress immediately. */
+    refresh: () => void;
+}
+/**
+ * Pin a tall section and slide a wide track through it as the user
+ * scrolls vertically: the classic horizontal-scroll storytelling chapter.
+ *
+ * The pinning itself is plain CSS (`position: sticky` on the stage), so
+ * this primitive never hijacks scrolling. It only translates the track
+ * with `translate3d`, smoothed by a spring that retargets seamlessly
+ * mid-scroll. Touch stays native: vertical swipes scroll the page, and
+ * the stage should keep `touch-action: pan-y` in your CSS.
+ *
+ * Reduced motion is a first-class path, not an afterthought. When the
+ * user prefers reduced motion the stage unpins (the tall section scrolls
+ * normally), the track renders as a plain vertical stack, nothing slides,
+ * and `progress` still reports 0 to 1 through the section so indicators
+ * keep working.
+ *
+ * SSR-safe: returns constant `0` accessors on the server (never touches
+ * `window` or `document` outside the browser).
+ *
+ * ```tsx
+ * import { createHorizontalScroll } from "solid-drift"
+ *
+ * function Story() {
+ *   let pin!: HTMLElement
+ *   let track!: HTMLElement
+ *   const { progress } = createHorizontalScroll({
+ *     pin: () => pin,
+ *     track: () => track,
+ *     stiffness: 120,
+ *     damping: 20,
+ *   })
+ *   return (
+ *     <section ref={pin} style={{ height: "300vh" }}>
+ *       <div
+ *         class="h-stage"
+ *         style={{
+ *           position: "sticky", top: 0, height: "100vh",
+ *           overflow: "hidden", "touch-action": "pan-y",
+ *         }}
+ *       >
+ *         <div
+ *           ref={track}
+ *           class="h-track"
+ *           style={{ display: "flex", width: "max-content", height: "100%" }}
+ *         >
+ *           <article style={{ width: "100vw" }}>Chapter one</article>
+ *           <article style={{ width: "100vw" }}>Chapter two</article>
+ *           <article style={{ width: "100vw" }}>Chapter three</article>
+ *         </div>
+ *       </div>
+ *     </section>
+ *   )
+ * }
+ * ```
+ */
+export declare function createHorizontalScroll(options: HorizontalScrollOptions): HorizontalScrollResult;

package/dist/horizontal.js

@@ -0,0 +1,208 @@
+import { createEffect, createSignal, onCleanup } from "solid-js";
+import { createSpring } from "./spring.js";
+import { usePrefersReducedMotion } from "./reduced-motion.js";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * Pin a tall section and slide a wide track through it as the user
+ * scrolls vertically: the classic horizontal-scroll storytelling chapter.
+ *
+ * The pinning itself is plain CSS (`position: sticky` on the stage), so
+ * this primitive never hijacks scrolling. It only translates the track
+ * with `translate3d`, smoothed by a spring that retargets seamlessly
+ * mid-scroll. Touch stays native: vertical swipes scroll the page, and
+ * the stage should keep `touch-action: pan-y` in your CSS.
+ *
+ * Reduced motion is a first-class path, not an afterthought. When the
+ * user prefers reduced motion the stage unpins (the tall section scrolls
+ * normally), the track renders as a plain vertical stack, nothing slides,
+ * and `progress` still reports 0 to 1 through the section so indicators
+ * keep working.
+ *
+ * SSR-safe: returns constant `0` accessors on the server (never touches
+ * `window` or `document` outside the browser).
+ *
+ * ```tsx
+ * import { createHorizontalScroll } from "solid-drift"
+ *
+ * function Story() {
+ *   let pin!: HTMLElement
+ *   let track!: HTMLElement
+ *   const { progress } = createHorizontalScroll({
+ *     pin: () => pin,
+ *     track: () => track,
+ *     stiffness: 120,
+ *     damping: 20,
+ *   })
+ *   return (
+ *     <section ref={pin} style={{ height: "300vh" }}>
+ *       <div
+ *         class="h-stage"
+ *         style={{
+ *           position: "sticky", top: 0, height: "100vh",
+ *           overflow: "hidden", "touch-action": "pan-y",
+ *         }}
+ *       >
+ *         <div
+ *           ref={track}
+ *           class="h-track"
+ *           style={{ display: "flex", width: "max-content", height: "100%" }}
+ *         >
+ *           <article style={{ width: "100vw" }}>Chapter one</article>
+ *           <article style={{ width: "100vw" }}>Chapter two</article>
+ *           <article style={{ width: "100vw" }}>Chapter three</article>
+ *         </div>
+ *       </div>
+ *     </section>
+ *   )
+ * }
+ * ```
+ */
+export function createHorizontalScroll(options) {
+    // SSR: no window, no scrolling, nothing to pin.
+    if (typeof window === "undefined") {
+        const zero = () => 0;
+        return { progress: zero, distance: zero, refresh: () => { } };
+    }
+    const { pin, track, distance: distanceOption, start = 0, end = 1, stiffness = 120, damping = 20, onProgress, } = options;
+    const stage = options.stage ??
+        (() => (track()?.parentElement ?? null));
+    const s0 = clamp01(start);
+    const e0 = clamp01(end);
+    const reduced = usePrefersReducedMotion();
+    const [raw, setRaw] = createSignal(0);
+    const [travel, setTravel] = createSignal(0);
+    // Reading reduced() in the source keeps the spring reactive to the OS
+    // motion preference: toggling it mid-session re-runs the spring effect,
+    // which jumps straight to the target when reduced motion is preferred.
+    const progress = createSpring(() => (reduced(), raw()), {
+        stiffness,
+        damping,
+    });
+    const compute = () => {
+        const p = pin();
+        if (!p)
+            return;
+        const rect = p.getBoundingClientRect();
+        const viewport = window.innerHeight;
+        // -rect.top is how far the pin's top edge has scrolled past the top
+        // of the viewport. The slide runs over the pin's extra height.
+        const range = Math.max(0, rect.height - viewport);
+        const span = (e0 - s0) * range;
+        setRaw(span > 0 ? clamp01((-rect.top - s0 * range) / span) : 0);
+    };
+    const measure = () => {
+        const t = track();
+        if (!t)
+            return;
+        const explicit = typeof distanceOption === "function" ? distanceOption() : distanceOption;
+        if (typeof explicit === "number" && Number.isFinite(explicit)) {
+            setTravel(Math.max(0, explicit));
+            return;
+        }
+        const s = stage();
+        const viewportWidth = s ? s.clientWidth : window.innerWidth;
+        setTravel(Math.max(0, t.scrollWidth - viewportWidth));
+    };
+    const refresh = () => {
+        measure();
+        compute();
+    };
+    // Scroll and resize are rAF-throttled: at most one measure per frame.
+    let rafId = 0;
+    const requestRefresh = () => {
+        if (typeof requestAnimationFrame === "undefined") {
+            refresh();
+            return;
+        }
+        if (rafId)
+            return;
+        rafId = requestAnimationFrame(() => {
+            rafId = 0;
+            refresh();
+        });
+    };
+    // Reduced motion: unpin the stage, stack the track vertically, stop
+    // sliding. Inline styles are captured once and restored when the
+    // preference flips back.
+    const saved = { stagePosition: "", trackTransform: "", trackFlex: "" };
+    let reducedApplied = false;
+    createEffect(() => {
+        const s = stage();
+        const t = track();
+        const isReduced = reduced();
+        if (!s || !t)
+            return;
+        if (isReduced) {
+            if (!reducedApplied) {
+                saved.stagePosition = s.style.position;
+                saved.trackTransform = t.style.transform;
+                saved.trackFlex = t.style.flexDirection;
+                reducedApplied = true;
+            }
+            s.style.position = "static";
+            t.style.transform = "";
+            t.style.flexDirection = "column";
+        }
+        else if (reducedApplied) {
+            s.style.position = saved.stagePosition;
+            t.style.transform = saved.trackTransform;
+            t.style.flexDirection = saved.trackFlex;
+            reducedApplied = false;
+            refresh();
+        }
+    });
+    // Apply the slide. Skipped entirely under reduced motion, where the
+    // effect above owns the track's styles.
+    createEffect(() => {
+        const t = track();
+        if (!t)
+            return;
+        const d = travel();
+        const p = progress();
+        if (reduced())
+            return;
+        const x = -p * d;
+        t.style.willChange = "transform";
+        t.style.transform = x === 0 ? "" : `translate3d(${x}px, 0, 0)`;
+    });
+    createEffect(() => {
+        onProgress?.(progress());
+    });
+    // Initial measure once refs are bound, plus re-measure when the bound
+    // elements change.
+    createEffect(() => {
+        pin();
+        track();
+        stage();
+        refresh();
+    });
+    window.addEventListener("scroll", requestRefresh, { passive: true });
+    window.addEventListener("resize", requestRefresh, { passive: true });
+    let observer = null;
+    if (typeof ResizeObserver !== "undefined") {
+        observer = new ResizeObserver(requestRefresh);
+        const ro = observer;
+        createEffect(() => {
+            const p = pin();
+            const t = track();
+            const s = stage();
+            ro.disconnect();
+            if (p)
+                ro.observe(p);
+            if (t)
+                ro.observe(t);
+            if (s && s !== p)
+                ro.observe(s);
+        });
+    }
+    onCleanup(() => {
+        window.removeEventListener("scroll", requestRefresh);
+        window.removeEventListener("resize", requestRefresh);
+        if (rafId)
+            cancelAnimationFrame(rafId);
+        observer?.disconnect();
+    });
+    return { progress, distance: travel, refresh };
+}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 /**
- * solid-drift — signal-native animation for SolidJS.
+ * solid-drift: signal-native animation for SolidJS.
  *
  * Animate values, not elements: springs and tweens follow your signals, and
  * retargeting mid-flight is seamless by design.
  */
-export { createSpring, type SpringOptions } from "./spring.js";
+export { createSpring, type SpringOptions, springPresets } from "./spring.js";
 export { createTween, type TweenOptions } from "./tween.js";
 export { animate, type AnimateOptions, type AnimationControls, } from "./animate.js";
 export { drift, type DriftProps } from "./directive.js";
@@ -12,4 +12,17 @@ export { createScrollProgress, type ScrollTarget } from "./scroll.js";
 export { createInView, type InViewOptions } from "./inview.js";
 export { usePrefersReducedMotion, prefersReducedMotion, } from "./reduced-motion.js";
 export { createStagger } from "./stagger.js";
-export { easings, cubicBezier, linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeOutExpo, easeOutBack, resolveEasing, type Easing, type EasingName, } from "./easing.js";
+export { createHorizontalScroll, type HorizontalScrollOptions, type HorizontalScrollResult, } from "./horizontal.js";
+export { createScrub, type ScrubKeyframe, type ScrubOptions } from "./scrub.js";
+export { createScrollColor, type ScrollColorStop, type ScrollColorOptions, type ScrollColorFormat, createScrollTracking, type ScrollTrackingOptions, createScrollLine, type ScrollLineOptions, type ScrollLineStyle, type ScrollLineAxis, type ScrollLineOrigin, } from "./scrollfx.js";
+export { createVelocity, type VelocityOptions } from "./velocity.js";
+export { createMagnetic, type MagneticOptions, type MagneticResult, createTilt, type TiltOptions, type TiltResult, } from "./pointer.js";
+export { createTrail, type TrailOptions } from "./trail.js";
+export { createTimeline, type TimelineStep, type TimelineStatus, type TimelineControls, } from "./timeline.js";
+export { animateFlip, type FlipOptions } from "./flip.js";
+export { createSquashStretch, type SquashStretchOptions, type SquashStretchResult, createFollowThrough, type FollowThroughOptions, createAnticipation, type AnticipationOptions, createWobble, type WobbleOptions, type WobbleResult, } from "./cartoon.js";
+export { createGravity, type GravityOptions, type GravityResult, createPendulum, type PendulumOptions, type PendulumResult, createFling, type FlingOptions, type FlingResult, } from "./physics.js";
+export { createFontSwap, type FontSwapOptions, type FontSwapResult, createTyping, type TypingOptions, type TypingResult, createTextPhysics, type TextPhysicsOptions, type TextPhysicsResult, createTextTunnel, type TextTunnelOptions, type TextTunnelResult, createTextCutout, type TextCutoutOptions, createTextGradient, type TextGradientOptions, createTextScramble, type TextScrambleOptions, type TextScrambleResult, createTextWave, type TextWaveOptions, } from "./typography.js";
+export { easings, cubicBezier, linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeOutExpo, easeOutBack, easeInBack, easeInOutBack, easeOutElastic, easeOutBounce, resolveEasing, type Easing, type EasingName, } from "./easing.js";
+export { createKineticType, createScenePlayer, createCamera, createColorShift, createTransition, createBeat, } from "./motion.js";
+export type { KineticTypeFrom, KineticTypeOptions, KineticTypeStatus, KineticTypeControls, MotionScene, ScenePlayerStatus, ScenePlayerControls, CameraKeyframe, CameraOptions, ColorShiftOptions, ColorShiftStatus, ColorShiftControls, TransitionType, TransitionDirection, TransitionOptions, TransitionLayerStyle, TransitionStatus, TransitionControls, BeatOptions, BeatStatus, BeatControls, } from "./motion.js";

package/dist/index.js

@@ -1,10 +1,10 @@
 /**
- * solid-drift — signal-native animation for SolidJS.
+ * solid-drift: signal-native animation for SolidJS.
  *
  * Animate values, not elements: springs and tweens follow your signals, and
  * retargeting mid-flight is seamless by design.
  */
-export { createSpring } from "./spring.js";
+export { createSpring, springPresets } from "./spring.js";
 export { createTween } from "./tween.js";
 export { animate, } from "./animate.js";
 export { drift } from "./directive.js";
@@ -12,4 +12,16 @@ export { createScrollProgress } from "./scroll.js";
 export { createInView } from "./inview.js";
 export { usePrefersReducedMotion, prefersReducedMotion, } from "./reduced-motion.js";
 export { createStagger } from "./stagger.js";
-export { easings, cubicBezier, linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeOutExpo, easeOutBack, resolveEasing, } from "./easing.js";
+export { createHorizontalScroll, } from "./horizontal.js";
+export { createScrub } from "./scrub.js";
+export { createScrollColor, createScrollTracking, createScrollLine, } from "./scrollfx.js";
+export { createVelocity } from "./velocity.js";
+export { createMagnetic, createTilt, } from "./pointer.js";
+export { createTrail } from "./trail.js";
+export { createTimeline, } from "./timeline.js";
+export { animateFlip } from "./flip.js";
+export { createSquashStretch, createFollowThrough, createAnticipation, createWobble, } from "./cartoon.js";
+export { createGravity, createPendulum, createFling, } from "./physics.js";
+export { createFontSwap, createTyping, createTextPhysics, createTextTunnel, createTextCutout, createTextGradient, createTextScramble, createTextWave, } from "./typography.js";
+export { easings, cubicBezier, linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeOutExpo, easeOutBack, easeInBack, easeInOutBack, easeOutElastic, easeOutBounce, resolveEasing, } from "./easing.js";
+export { createKineticType, createScenePlayer, createCamera, createColorShift, createTransition, createBeat, } from "./motion.js";

package/dist/inview.d.ts

@@ -9,16 +9,16 @@ export interface InViewOptions {
  * A boolean signal reporting whether an element is visible in the viewport.
  *
  * Built on IntersectionObserver: cheap, off-main-thread, and exact. With
- * `once: true` (default) the signal latches on first visibility — ideal
+ * `once: true` (default) the signal latches on first visibility, ideal
  * for entrance animations. Set `once: false` for a live in/out signal.
  *
  * The observer is created when the ref resolves and disconnected on
  * cleanup. SSR-safe: returns a constant `false` accessor on the server.
  *
  * ```tsx
- * let card: HTMLDivElement | undefined;
- * const inView = createInView(() => card);
- * const opacity = createTween(() => (inView() ? 1 : 0), { duration: 400 });
+ * let card: HTMLDivElement | undefined
+ * const inView = createInView(() => card)
+ * const opacity = createTween(() => (inView() ? 1 : 0), { duration: 400 })
  * <div ref={card} style={{ opacity: opacity() }}>…</div>
  * ```
  */

package/dist/inview.js

@@ -1,18 +1,18 @@
-import { createEffect, createSignal, onCleanup, } from "solid-js";
+import { createEffect, createSignal, onCleanup } from "solid-js";
 /**
  * A boolean signal reporting whether an element is visible in the viewport.
  *
  * Built on IntersectionObserver: cheap, off-main-thread, and exact. With
- * `once: true` (default) the signal latches on first visibility — ideal
+ * `once: true` (default) the signal latches on first visibility, ideal
  * for entrance animations. Set `once: false` for a live in/out signal.
  *
  * The observer is created when the ref resolves and disconnected on
  * cleanup. SSR-safe: returns a constant `false` accessor on the server.
  *
  * ```tsx
- * let card: HTMLDivElement | undefined;
- * const inView = createInView(() => card);
- * const opacity = createTween(() => (inView() ? 1 : 0), { duration: 400 });
+ * let card: HTMLDivElement | undefined
+ * const inView = createInView(() => card)
+ * const opacity = createTween(() => (inView() ? 1 : 0), { duration: 400 })
  * <div ref={card} style={{ opacity: opacity() }}>…</div>
  * ```
  */