solid-drift 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Austin Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# 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 — no restarts, no jumps.
+
+Built with AI assistance.
+
+## Install
+
+```bash
+npm install solid-drift
+```
+
+## Quick start
+
+```tsx
+import { createSignal } from "solid-js";
+import { createSpring, createTween, drift } from "solid-drift";
+
+function Panel() {
+  const [open, setOpen] = createSignal(false);
+
+  // Springs follow the signal with physics; tweens use duration + easing.
+  const y = createSpring(() => (open() ? 0 : 24), { stiffness: 170, damping: 26 });
+  const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 });
+
+  return (
+    <>
+      <button onClick={() => setOpen(!open())}>toggle</button>
+      <div use:drift={{ y, opacity }}>slides and fades</div>
+    </>
+  );
+}
+```
+
+## API
+
+### `createSpring(source, options?)`
+
+Returns a signal that follows `source` with spring physics. Changing the source mid-flight bends the spring toward the new target, keeping its velocity.
+
+| Option      | Default | Description                          |
+| ----------- | ------- | ------------------------------------ |
+| `stiffness` | `170`   | Spring stiffness                     |
+| `damping`   | `26`    | Damping coefficient                   |
+| `mass`      | `1`     | Mass                                  |
+| `precision` | `0.01`  | Rest threshold for value and velocity |
+| `onRest`    | —       | Called once the spring settles        |
+
+### `createTween(source, options?)`
+
+Returns a signal that tweens toward `source` over a fixed duration. Interrupting retargets from the current value.
+
+| Option       | Default          | Description                    |
+| ------------ | ---------------- | ------------------------------ |
+| `duration`   | `300`            | Duration in milliseconds       |
+| `delay`      | `0`              | Delay before starting (ms)     |
+| `easing`     | `"easeOutCubic"` | Easing function or name        |
+| `onComplete` | —                | Called when the tween finishes |
+
+### `animate(from, to, options?)`
+
+Imperative one-shot animation. Returns `{ stop, finished }`.
+
+```ts
+const ctl = animate(0, 1, {
+  duration: 500,
+  easing: "easeOutExpo",
+  onUpdate: (v) => (el.style.opacity = String(v)),
+});
+await ctl.finished; // or ctl.stop()
+```
+
+### `drift` directive
+
+Binds animated values directly to an element's style. Each prop accepts a plain number or any signal.
+
+```tsx
+<div use:drift={{ x, y, opacity, scale, scaleX, scaleY, rotate }} />
+```
+
+`x`/`y` map to `translate3d` px, `rotate` to degrees.
+
+### Easings
+
+Named easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutExpo`, `easeOutBack` — plus `cubicBezier(x1, y1, x2, y2)` for CSS-style curves. Pass a name or a custom `(t) => number` function anywhere an easing is accepted.
+
+## How it works
+
+One shared `requestAnimationFrame` loop drives every animation in the app, so hundreds of springs cost a single rAF tick per frame. Springs integrate with semi-implicit Euler; tweens sample an easing curve. Everything is SSR-safe (animations simply don't run on the server).
+
+## License
+
+MIT © Austin Nguyen

package/dist/animate.d.ts

@@ -0,0 +1,32 @@
+import { type Easing, type EasingName } from "./easing.js";
+export interface AnimateOptions {
+    /** Duration in milliseconds. Default 300. */
+    duration?: number;
+    /** Delay before starting, in milliseconds. Default 0. */
+    delay?: number;
+    /** Easing function or name. Default "easeOutCubic". */
+    easing?: Easing | EasingName;
+    /** Called every frame with the current value. */
+    onUpdate?: (value: number) => void;
+    /** Called when the animation completes (not when stopped). */
+    onComplete?: () => void;
+}
+export interface AnimationControls {
+    /** Stop the animation immediately. */
+    stop: () => void;
+    /** Resolves when the animation completes or is stopped. */
+    finished: Promise<void>;
+}
+/**
+ * Imperative one-shot animation from `from` to `to`.
+ *
+ * ```ts
+ * const ctl = animate(0, 100, {
+ *   duration: 500,
+ *   easing: "easeOutExpo",
+ *   onUpdate: (v) => el.style.opacity = String(v / 100),
+ * });
+ * await ctl.finished;
+ * ```
+ */
+export declare function animate(from: number, to: number, options?: AnimateOptions): AnimationControls;

package/dist/animate.js

@@ -0,0 +1,58 @@
+import { now, schedule } from "./engine.js";
+import { resolveEasing } from "./easing.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * Imperative one-shot animation from `from` to `to`.
+ *
+ * ```ts
+ * const ctl = animate(0, 100, {
+ *   duration: 500,
+ *   easing: "easeOutExpo",
+ *   onUpdate: (v) => el.style.opacity = String(v / 100),
+ * });
+ * await ctl.finished;
+ * ```
+ */
+export function animate(from, to, options = {}) {
+    const { duration = 300, delay = 0, onUpdate, onComplete } = options;
+    const easing = resolveEasing(options.easing ?? "easeOutCubic");
+    let resolveFinished;
+    const finished = new Promise((resolve) => {
+        resolveFinished = resolve;
+    });
+    let done = false;
+    const finish = (completed) => {
+        if (done)
+            return;
+        done = true;
+        if (completed)
+            onComplete?.();
+        resolveFinished();
+    };
+    // Accessibility: skip the animation entirely, deliver the end value.
+    if (prefersReducedMotion()) {
+        onUpdate?.(to);
+        finish(true);
+        return { stop: () => finish(false), finished };
+    }
+    const startAt = now() + delay;
+    const span = Math.max(duration, 0.001);
+    const cancel = schedule((t) => {
+        if (t < startAt)
+            return true;
+        const p = Math.min((t - startAt) / span, 1);
+        onUpdate?.(from + (to - from) * easing(p));
+        if (p >= 1) {
+            finish(true);
+            return false;
+        }
+        return true;
+    });
+    return {
+        stop: () => {
+            cancel();
+            finish(false);
+        },
+        finished,
+    };
+}

package/dist/directive.d.ts

@@ -0,0 +1,44 @@
+import { type Accessor } from "solid-js";
+type MaybeAccessor<T> = T | Accessor<T>;
+export interface DriftProps {
+    /** Horizontal offset in px. */
+    x?: MaybeAccessor<number>;
+    /** Vertical offset in px. */
+    y?: MaybeAccessor<number>;
+    /** Opacity 0–1. */
+    opacity?: MaybeAccessor<number>;
+    /** Uniform scale. */
+    scale?: MaybeAccessor<number>;
+    /** Horizontal scale. */
+    scaleX?: MaybeAccessor<number>;
+    /** Vertical scale. */
+    scaleY?: MaybeAccessor<number>;
+    /** Rotation in degrees. */
+    rotate?: MaybeAccessor<number>;
+}
+declare module "solid-js" {
+    namespace JSX {
+        interface Directives {
+            drift: DriftProps | Accessor<DriftProps>;
+        }
+    }
+}
+/**
+ * Directive that binds animated values straight to an element's style.
+ * Each prop can be a plain number or any signal — combine with
+ * `createSpring` / `createTween` for buttery motion:
+ *
+ * ```tsx
+ * import { drift } from "solid-drift";
+ *
+ * const [open, setOpen] = createSignal(false);
+ * const y = createSpring(() => (open() ? 0 : 24));
+ * const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 });
+ *
+ * <div use:drift={{ y, opacity }}>slides and fades</div>
+ * ```
+ *
+ * Note: importing this module registers the `drift` directive type globally.
+ */
+export declare function drift(el: HTMLElement, props: Accessor<DriftProps>): void;
+export {};

package/dist/directive.js

@@ -0,0 +1,42 @@
+import { createEffect } from "solid-js";
+function resolve(value) {
+    return typeof value === "function" ? value() : value;
+}
+/**
+ * Directive that binds animated values straight to an element's style.
+ * Each prop can be a plain number or any signal — combine with
+ * `createSpring` / `createTween` for buttery motion:
+ *
+ * ```tsx
+ * import { drift } from "solid-drift";
+ *
+ * const [open, setOpen] = createSignal(false);
+ * const y = createSpring(() => (open() ? 0 : 24));
+ * const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 });
+ *
+ * <div use:drift={{ y, opacity }}>slides and fades</div>
+ * ```
+ *
+ * Note: importing this module registers the `drift` directive type globally.
+ */
+export function drift(el, props) {
+    createEffect(() => {
+        const p = props();
+        const parts = [];
+        const x = p.x !== undefined ? resolve(p.x) : 0;
+        const y = p.y !== undefined ? resolve(p.y) : 0;
+        if (x !== 0 || y !== 0)
+            parts.push(`translate3d(${x}px, ${y}px, 0)`);
+        const rotate = p.rotate !== undefined ? resolve(p.rotate) : 0;
+        if (rotate !== 0)
+            parts.push(`rotate(${rotate}deg)`);
+        const sx = p.scaleX !== undefined ? resolve(p.scaleX) : p.scale !== undefined ? resolve(p.scale) : 1;
+        const sy = p.scaleY !== undefined ? resolve(p.scaleY) : p.scale !== undefined ? resolve(p.scale) : 1;
+        if (sx !== 1 || sy !== 1)
+            parts.push(`scale(${sx}, ${sy})`);
+        el.style.transform = parts.join(" ");
+        if (p.opacity !== undefined) {
+            el.style.opacity = String(resolve(p.opacity));
+        }
+    });
+}

package/dist/easing.d.ts

@@ -0,0 +1,35 @@
+/** Easing function: maps progress [0, 1] to eased progress [0, 1]. */
+export type Easing = (t: number) => number;
+export declare const linear: Easing;
+export declare const easeInQuad: Easing;
+export declare const easeOutQuad: Easing;
+export declare const easeInOutQuad: Easing;
+export declare const easeInCubic: Easing;
+export declare const easeOutCubic: Easing;
+export declare const easeInOutCubic: Easing;
+export declare const easeInQuart: Easing;
+export declare const easeOutQuart: Easing;
+export declare const easeInOutQuart: Easing;
+export declare const easeOutExpo: Easing;
+export declare const easeOutBack: Easing;
+/**
+ * Cubic bezier easing, same parameters as CSS `cubic-bezier(x1, y1, x2, y2)`.
+ */
+export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): Easing;
+export declare const easings: {
+    readonly linear: Easing;
+    readonly easeInQuad: Easing;
+    readonly easeOutQuad: Easing;
+    readonly easeInOutQuad: Easing;
+    readonly easeInCubic: Easing;
+    readonly easeOutCubic: Easing;
+    readonly easeInOutCubic: Easing;
+    readonly easeInQuart: Easing;
+    readonly easeOutQuart: Easing;
+    readonly easeInOutQuart: Easing;
+    readonly easeOutExpo: Easing;
+    readonly easeOutBack: Easing;
+};
+export type EasingName = keyof typeof easings;
+/** Accept an easing function or its name; throws on unknown names. */
+export declare function resolveEasing(easing: Easing | EasingName | undefined): Easing;

package/dist/easing.js

@@ -0,0 +1,81 @@
+export const linear = (t) => t;
+export const easeInQuad = (t) => t * t;
+export const easeOutQuad = (t) => 1 - (1 - t) * (1 - t);
+export const easeInOutQuad = (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+export const easeInCubic = (t) => t * t * t;
+export const easeOutCubic = (t) => 1 - Math.pow(1 - t, 3);
+export const easeInOutCubic = (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+export const easeInQuart = (t) => t * t * t * t;
+export const easeOutQuart = (t) => 1 - Math.pow(1 - t, 4);
+export const easeInOutQuart = (t) => t < 0.5 ? 8 * t * t * t * t : 1 - Math.pow(-2 * t + 2, 4) / 2;
+export const easeOutExpo = (t) => t >= 1 ? 1 : 1 - Math.pow(2, -10 * t);
+export const easeOutBack = (t) => {
+    const c1 = 1.70158;
+    const c3 = c1 + 1;
+    return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+};
+/**
+ * Cubic bezier easing, same parameters as CSS `cubic-bezier(x1, y1, x2, y2)`.
+ */
+export function cubicBezier(x1, y1, x2, y2) {
+    // Newton-Raphson + bisection fallback, adapted from the CSS spec approach.
+    const cx = 3 * x1;
+    const bx = 3 * (x2 - x1) - cx;
+    const ax = 1 - cx - bx;
+    const cy = 3 * y1;
+    const by = 3 * (y2 - y1) - cy;
+    const ay = 1 - cy - by;
+    const sampleX = (t) => ((ax * t + bx) * t + cx) * t;
+    const sampleY = (t) => ((ay * t + by) * t + cy) * t;
+    const sampleDX = (t) => (3 * ax * t + 2 * bx) * t + cx;
+    return (x) => {
+        let t = x;
+        for (let i = 0; i < 5; i++) {
+            const dx = sampleDX(t);
+            if (Math.abs(dx) < 1e-6)
+                break;
+            const err = sampleX(t) - x;
+            t -= err / dx;
+        }
+        // Fallback bisection if Newton diverged.
+        let lo = 0;
+        let hi = 1;
+        t = Math.min(Math.max(t, 0), 1);
+        while (hi - lo > 1e-6) {
+            const v = sampleX(t);
+            if (Math.abs(v - x) < 1e-6)
+                break;
+            if (v < x)
+                lo = t;
+            else
+                hi = t;
+            t = (lo + hi) / 2;
+        }
+        return sampleY(t);
+    };
+}
+export const easings = {
+    linear,
+    easeInQuad,
+    easeOutQuad,
+    easeInOutQuad,
+    easeInCubic,
+    easeOutCubic,
+    easeInOutCubic,
+    easeInQuart,
+    easeOutQuart,
+    easeInOutQuart,
+    easeOutExpo,
+    easeOutBack,
+};
+/** Accept an easing function or its name; throws on unknown names. */
+export function resolveEasing(easing) {
+    if (!easing)
+        return easeOutCubic;
+    if (typeof easing === "function")
+        return easing;
+    const fn = easings[easing];
+    if (!fn)
+        throw new Error(`[solid-drift] unknown easing: "${easing}"`);
+    return fn;
+}

package/dist/engine.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared animation clock.
+ *
+ * A single requestAnimationFrame loop drives every active animation in the
+ * app, so hundreds of springs and tweens cost exactly one rAF tick per frame.
+ * Tasks return `false` when finished and are removed automatically.
+ */
+export type AnimationTask = (now: number) => boolean;
+/**
+ * Register a task on the shared clock. Returns a cancel function.
+ * Safe to call during SSR (no-op without requestAnimationFrame).
+ */
+export declare function schedule(task: AnimationTask): () => void;
+/** Monotonic clock in milliseconds. */
+export declare function now(): number;

package/dist/engine.js

@@ -0,0 +1,41 @@
+/**
+ * Shared animation clock.
+ *
+ * A single requestAnimationFrame loop drives every active animation in the
+ * app, so hundreds of springs and tweens cost exactly one rAF tick per frame.
+ * Tasks return `false` when finished and are removed automatically.
+ */
+const tasks = new Set();
+let rafId = 0;
+function tick(now) {
+    for (const task of tasks) {
+        let alive = false;
+        try {
+            alive = task(now);
+        }
+        catch {
+            alive = false;
+        }
+        if (!alive)
+            tasks.delete(task);
+    }
+    rafId = tasks.size > 0 ? requestAnimationFrame(tick) : 0;
+}
+/**
+ * Register a task on the shared clock. Returns a cancel function.
+ * Safe to call during SSR (no-op without requestAnimationFrame).
+ */
+export function schedule(task) {
+    if (typeof requestAnimationFrame === "undefined")
+        return () => { };
+    tasks.add(task);
+    if (!rafId)
+        rafId = requestAnimationFrame(tick);
+    return () => {
+        tasks.delete(task);
+    };
+}
+/** Monotonic clock in milliseconds. */
+export function now() {
+    return typeof performance !== "undefined" ? performance.now() : Date.now();
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { createTween, type TweenOptions } from "./tween.js";
+export { animate, type AnimateOptions, type AnimationControls, } from "./animate.js";
+export { drift, type DriftProps } from "./directive.js";
+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";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * 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 { createTween } from "./tween.js";
+export { animate, } from "./animate.js";
+export { drift } from "./directive.js";
+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";

package/dist/inview.d.ts

@@ -0,0 +1,25 @@
+import { type Accessor } from "solid-js";
+export interface InViewOptions {
+    /** Visibility ratio that counts as "in view". Default 0.15. */
+    threshold?: number;
+    /** Stop observing after the first intersection. Default true. */
+    once?: boolean;
+}
+/**
+ * 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
+ * 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 });
+ * <div ref={card} style={{ opacity: opacity() }}>…</div>
+ * ```
+ */
+export declare function createInView(ref: () => Element | null | undefined, options?: InViewOptions): Accessor<boolean>;

package/dist/inview.js

@@ -0,0 +1,47 @@
+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
+ * 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 });
+ * <div ref={card} style={{ opacity: opacity() }}>…</div>
+ * ```
+ */
+export function createInView(ref, options = {}) {
+    const { threshold = 0.15, once = true } = options;
+    // SSR (or browsers without IntersectionObserver): never "in view".
+    if (typeof window === "undefined" ||
+        typeof IntersectionObserver === "undefined") {
+        return () => false;
+    }
+    const [inView, setInView] = createSignal(false);
+    createEffect(() => {
+        const el = ref();
+        if (!el)
+            return;
+        const observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.isIntersecting) {
+                    setInView(true);
+                    if (once)
+                        observer.disconnect();
+                }
+                else if (!once) {
+                    setInView(false);
+                }
+            }
+        }, { threshold });
+        observer.observe(el);
+        onCleanup(() => observer.disconnect());
+    });
+    return inView;
+}

package/dist/reduced-motion.d.ts

@@ -0,0 +1,21 @@
+import { type Accessor } from "solid-js";
+/**
+ * Non-reactive check: does the user currently prefer reduced motion?
+ *
+ * SSR-safe — always `false` on the server. `createSpring`, `createTween`
+ * and `animate` sample this whenever they (re)start: when reduced motion
+ * is preferred they jump straight to the target value instead of animating.
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Reactive signal for the `(prefers-reduced-motion: reduce)` media query.
+ *
+ * Updates live if the OS preference changes while the app is running.
+ * SSR-safe: `false` on the server.
+ *
+ * ```tsx
+ * const reduced = usePrefersReducedMotion();
+ * const duration = () => (reduced() ? 0 : 400);
+ * ```
+ */
+export declare function usePrefersReducedMotion(): Accessor<boolean>;

package/dist/reduced-motion.js

@@ -0,0 +1,38 @@
+import { createSignal, onCleanup } from "solid-js";
+const QUERY = "(prefers-reduced-motion: reduce)";
+function queryMatches() {
+    return (typeof window !== "undefined" &&
+        typeof window.matchMedia === "function" &&
+        window.matchMedia(QUERY).matches);
+}
+/**
+ * Non-reactive check: does the user currently prefer reduced motion?
+ *
+ * SSR-safe — always `false` on the server. `createSpring`, `createTween`
+ * and `animate` sample this whenever they (re)start: when reduced motion
+ * is preferred they jump straight to the target value instead of animating.
+ */
+export function prefersReducedMotion() {
+    return queryMatches();
+}
+/**
+ * Reactive signal for the `(prefers-reduced-motion: reduce)` media query.
+ *
+ * Updates live if the OS preference changes while the app is running.
+ * SSR-safe: `false` on the server.
+ *
+ * ```tsx
+ * const reduced = usePrefersReducedMotion();
+ * const duration = () => (reduced() ? 0 : 400);
+ * ```
+ */
+export function usePrefersReducedMotion() {
+    const [reduced, setReduced] = createSignal(queryMatches());
+    if (typeof window !== "undefined" && typeof window.matchMedia === "function") {
+        const mq = window.matchMedia(QUERY);
+        const onChange = () => setReduced(mq.matches);
+        mq.addEventListener("change", onChange);
+        onCleanup(() => mq.removeEventListener("change", onChange));
+    }
+    return reduced;
+}

package/dist/scroll.d.ts

@@ -0,0 +1,26 @@
+import { type Accessor } from "solid-js";
+/** What to measure scroll progress against: the whole page or one element. */
+export type ScrollTarget = "page" | (() => Element | null | undefined);
+/**
+ * A signal tracking scroll progress as a number from 0 to 1.
+ *
+ * - `"page"` (default): 0 at the very top of the page, 1 when the bottom
+ *   of the page reaches the bottom of the viewport.
+ * - element accessor: 0 when the element's top edge touches the bottom of
+ *   the viewport, 1 when its bottom edge touches the top — i.e. the
+ *   element's full traversal through the viewport.
+ *
+ * Updates are rAF-throttled: no matter how many scroll/resize events fire,
+ * progress is measured at most once per frame. Listeners are passive and
+ * removed on cleanup.
+ *
+ * SSR-safe: returns a constant `0` accessor on the server (never touches
+ * `window` or `document`).
+ *
+ * ```tsx
+ * const progress = createScrollProgress(); // page progress
+ * const bar = createScrollProgress(() => sectionRef); // element progress
+ * <div style={{ transform: `scaleX(${progress()})` }} />
+ * ```
+ */
+export declare function createScrollProgress(target?: ScrollTarget): Accessor<number>;

package/dist/scroll.js

@@ -0,0 +1,74 @@
+import { createEffect, createSignal, onCleanup, } from "solid-js";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * A signal tracking scroll progress as a number from 0 to 1.
+ *
+ * - `"page"` (default): 0 at the very top of the page, 1 when the bottom
+ *   of the page reaches the bottom of the viewport.
+ * - element accessor: 0 when the element's top edge touches the bottom of
+ *   the viewport, 1 when its bottom edge touches the top — i.e. the
+ *   element's full traversal through the viewport.
+ *
+ * Updates are rAF-throttled: no matter how many scroll/resize events fire,
+ * progress is measured at most once per frame. Listeners are passive and
+ * removed on cleanup.
+ *
+ * SSR-safe: returns a constant `0` accessor on the server (never touches
+ * `window` or `document`).
+ *
+ * ```tsx
+ * const progress = createScrollProgress(); // page progress
+ * const bar = createScrollProgress(() => sectionRef); // element progress
+ * <div style={{ transform: `scaleX(${progress()})` }} />
+ * ```
+ */
+export function createScrollProgress(target = "page") {
+    // SSR: no window, no scrolling — report the top of the page.
+    if (typeof window === "undefined")
+        return () => 0;
+    const [progress, setProgress] = createSignal(0);
+    let rafId = 0;
+    const compute = () => {
+        if (target === "page") {
+            const max = document.documentElement.scrollHeight - window.innerHeight;
+            setProgress(max > 0 ? clamp01(window.scrollY / max) : 0);
+            return;
+        }
+        const el = target();
+        if (!el)
+            return;
+        const rect = el.getBoundingClientRect();
+        const viewport = window.innerHeight;
+        const travel = viewport + rect.height;
+        setProgress(travel > 0 ? clamp01((viewport - rect.top) / travel) : 0);
+    };
+    const requestCompute = () => {
+        if (typeof requestAnimationFrame === "undefined") {
+            compute();
+            return;
+        }
+        if (rafId)
+            return; // a measurement is already queued for this frame
+        rafId = requestAnimationFrame(() => {
+            rafId = 0;
+            compute();
+        });
+    };
+    // Track the element accessor so late-bound refs start measuring too.
+    createEffect(() => {
+        if (target !== "page")
+            target();
+        compute();
+    });
+    window.addEventListener("scroll", requestCompute, { passive: true });
+    window.addEventListener("resize", requestCompute, { passive: true });
+    onCleanup(() => {
+        window.removeEventListener("scroll", requestCompute);
+        window.removeEventListener("resize", requestCompute);
+        if (rafId)
+            cancelAnimationFrame(rafId);
+    });
+    return progress;
+}

package/dist/spring.d.ts

@@ -0,0 +1,28 @@
+import { type Accessor } from "solid-js";
+export interface SpringOptions {
+    /** Spring stiffness. Default 170. */
+    stiffness?: number;
+    /** Damping coefficient. Default 26. */
+    damping?: number;
+    /** Mass. Default 1. */
+    mass?: number;
+    /** Rest threshold for value and velocity. Default 0.01. */
+    precision?: number;
+    /** Called once the spring settles at its target. */
+    onRest?: () => void;
+}
+/**
+ * A signal that smoothly follows a source signal with spring physics.
+ *
+ * Retargeting is seamless: if the source changes mid-flight, the spring
+ * keeps its current velocity and bends toward the new target — no jumps,
+ * no restarts.
+ *
+ * ```tsx
+ * const [target, setTarget] = createSignal(0);
+ * const x = createSpring(target, { stiffness: 170, damping: 26 });
+ * <div style={{ transform: `translateX(${x()}px)` }} />
+ * setTarget(200); // glides there
+ * ```
+ */
+export declare function createSpring(source: Accessor<number>, options?: SpringOptions): Accessor<number>;

package/dist/spring.js

@@ -0,0 +1,68 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * A signal that smoothly follows a source signal with spring physics.
+ *
+ * Retargeting is seamless: if the source changes mid-flight, the spring
+ * keeps its current velocity and bends toward the new target — no jumps,
+ * no restarts.
+ *
+ * ```tsx
+ * const [target, setTarget] = createSignal(0);
+ * const x = createSpring(target, { stiffness: 170, damping: 26 });
+ * <div style={{ transform: `translateX(${x()}px)` }} />
+ * setTarget(200); // glides there
+ * ```
+ */
+export function createSpring(source, options = {}) {
+    const { stiffness = 170, damping = 26, mass = 1, precision = 0.01, onRest, } = options;
+    const [value, setValue] = createSignal(untrack(source));
+    let current = untrack(source);
+    let velocity = 0;
+    let cancel = null;
+    let lastTime = 0;
+    const step = (t) => {
+        const dt = Math.min(Math.max((t - lastTime) / 1000, 0), 0.064);
+        lastTime = t;
+        const target = untrack(source);
+        // Semi-implicit Euler: stable for the stiffness ranges used in UI.
+        const force = -stiffness * (current - target) - damping * velocity;
+        velocity += (force / mass) * dt;
+        current += velocity * dt;
+        setValue(current);
+        const settled = Math.abs(current - target) < precision &&
+            Math.abs(velocity) < precision;
+        if (settled) {
+            current = target;
+            velocity = 0;
+            setValue(target);
+            cancel = null;
+            onRest?.();
+            return false;
+        }
+        return true;
+    };
+    const kick = () => {
+        if (cancel)
+            return; // already running; step() reads the live target
+        lastTime = now();
+        cancel = schedule(step);
+    };
+    createEffect(() => {
+        const target = source(); // track
+        if (prefersReducedMotion()) {
+            // Accessibility: skip the animation, land exactly on the target.
+            cancel?.();
+            cancel = null;
+            current = target;
+            velocity = 0;
+            setValue(target);
+            onRest?.();
+            return;
+        }
+        kick();
+    });
+    onCleanup(() => cancel?.());
+    return value;
+}

package/dist/stagger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Builds a stagger-delay lookup for cascading animations across a list.
+ *
+ * Given an item index, returns its delay in milliseconds (`index * delayMs`).
+ * Pair with `createTween`'s `delay` option (or `animate`) so items entrance
+ * one after another instead of all at once. `count` is informational — the
+ * number of items being staggered.
+ *
+ * ```ts
+ * const at = createStagger(5, 80); // 5 items, 80ms apart
+ * at(0); // 0
+ * at(3); // 240
+ * ```
+ */
+export declare function createStagger(count: number, delayMs: number): (index: number) => number;

package/dist/stagger.js

@@ -0,0 +1,18 @@
+/**
+ * Builds a stagger-delay lookup for cascading animations across a list.
+ *
+ * Given an item index, returns its delay in milliseconds (`index * delayMs`).
+ * Pair with `createTween`'s `delay` option (or `animate`) so items entrance
+ * one after another instead of all at once. `count` is informational — the
+ * number of items being staggered.
+ *
+ * ```ts
+ * const at = createStagger(5, 80); // 5 items, 80ms apart
+ * at(0); // 0
+ * at(3); // 240
+ * ```
+ */
+export function createStagger(count, delayMs) {
+    void count;
+    return (index) => index * delayMs;
+}

package/dist/tween.d.ts

@@ -0,0 +1,24 @@
+import { type Accessor } from "solid-js";
+import { type Easing, type EasingName } from "./easing.js";
+export interface TweenOptions {
+    /** Duration in milliseconds. Default 300. */
+    duration?: number;
+    /** Delay before starting, in milliseconds. Default 0. */
+    delay?: number;
+    /** Easing function or name. Default "easeOutCubic". */
+    easing?: Easing | EasingName;
+    /** Called when the tween reaches its target. */
+    onComplete?: () => void;
+}
+/**
+ * A signal that tweens toward a source signal's value over a fixed duration.
+ *
+ * Interrupting mid-tween retargets from the current value — no snapping.
+ *
+ * ```tsx
+ * const [open, setOpen] = createSignal(false);
+ * const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 });
+ * <div style={{ opacity: opacity() }} />
+ * ```
+ */
+export declare function createTween(source: Accessor<number>, options?: TweenOptions): Accessor<number>;

package/dist/tween.js

@@ -0,0 +1,48 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { resolveEasing } from "./easing.js";
+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.
+ *
+ * ```tsx
+ * const [open, setOpen] = createSignal(false);
+ * const opacity = createTween(() => (open() ? 1 : 0), { duration: 250 });
+ * <div style={{ opacity: opacity() }} />
+ * ```
+ */
+export function createTween(source, options = {}) {
+    const { duration = 300, delay = 0, onComplete } = options;
+    const easing = resolveEasing(options.easing ?? "easeOutCubic");
+    const [value, setValue] = createSignal(untrack(source));
+    let cancel = null;
+    createEffect(() => {
+        const to = source();
+        const from = untrack(value);
+        cancel?.();
+        cancel = null;
+        if (prefersReducedMotion() || duration <= 0 || from === to) {
+            // Accessibility: jump straight to the target, no animation.
+            setValue(to);
+            onComplete?.();
+            return;
+        }
+        const startAt = now() + delay;
+        cancel = schedule((t) => {
+            if (t < startAt)
+                return true;
+            const p = Math.min((t - startAt) / duration, 1);
+            setValue(from + (to - from) * easing(p));
+            if (p >= 1) {
+                cancel = null;
+                onComplete?.();
+                return false;
+            }
+            return true;
+        });
+    });
+    onCleanup(() => cancel?.());
+    return value;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "author": "Austin Nguyen",
+  "description": "Signal-native animation library for SolidJS",
+  "devDependencies": {
+    "solid-js": "^1.9.0",
+    "typescript": "^5.6.0",
+    "vitest": "^5.0.2"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "solid",
+    "solidjs",
+    "animation",
+    "spring",
+    "tween",
+    "signals",
+    "motion"
+  ],
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "name": "solid-drift",
+  "peerDependencies": {
+    "solid-js": "^1.0.0 || ^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/austinpnguyen/solid-drift.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "0.2.0"
+}