@humanspeak/svelte-motion 0.1.2 → 0.1.3

package/README.md

@@ -74,15 +74,16 @@ This package carefully selects its dependencies to provide a robust and maintain
 
 ### Examples
 
-| Motion                                                                                                   | Demo / Route                      | REPL                                                                                           |
-| -------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
-| [React - Enter Animation](https://examples.motion.dev/react/enter-animation)                             | `/tests/motion/enter-animation`   | [View Example](https://svelte.dev/playground/7f60c347729f4ea48b1a4590c9dedc02?version=5.38.10) |
-| [HTML Content (0→100 counter)](https://examples.motion.dev/react/html-content)                           | `/tests/motion/html-content`      | [View Example](https://svelte.dev/playground/31cd72df4a3242b4b4589501a25e774f?version=5.38.10) |
-| [Aspect Ratio](https://examples.motion.dev/react/aspect-ratio)                                           | `/tests/motion/aspect-ratio`      | [View Example](https://svelte.dev/playground/1bf60e745fae44f5becb4c830fde9b6e?version=5.38.10) |
-| [Hover + Tap (whileHover + whileTap)](https://motion.dev/docs/react?platform=react#hover-tap-animation)  | `/tests/motion/hover-and-tap`     | [View Example](https://svelte.dev/playground/674c7d58f2c740baa4886b01340a97ea?version=5.38.10) |
-| [Random - Shiny Button](https://www.youtube.com/watch?v=jcpLprT5F0I) by [@verse\_](https://x.com/verse_) | `/tests/random/shiny-button`      | [View Example](https://svelte.dev/playground/96f9e0bf624f4396adaf06c519147450?version=5.38.10) |
-| [Fancy Like Button](https://github.com/DRlFTER/fancyLikeButton)                                          | `/tests/random/fancy-like-button` | [View Example](https://svelte.dev/playground/c34b7e53d41c48b0ab1eaf21ca120c6e?version=5.38.10) |
-| [Keyframes (square → circle → square; scale 1→2→1)](https://motion.dev/docs/react-animation#keyframes)   | `/tests/motion/keyframes`         | [View Example](https://svelte.dev/playground/05595ce0db124c1cbbe4e74fda68d717?version=5.38.10) |
+| Motion                                                                                                   | Demo / Route                             | REPL                                                                                           |
+| -------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| [React - Enter Animation](https://examples.motion.dev/react/enter-animation)                             | `/tests/motion/enter-animation`          | [View Example](https://svelte.dev/playground/7f60c347729f4ea48b1a4590c9dedc02?version=5.38.10) |
+| [HTML Content (0→100 counter)](https://examples.motion.dev/react/html-content)                           | `/tests/motion/html-content`             | [View Example](https://svelte.dev/playground/31cd72df4a3242b4b4589501a25e774f?version=5.38.10) |
+| [Aspect Ratio](https://examples.motion.dev/react/aspect-ratio)                                           | `/tests/motion/aspect-ratio`             | [View Example](https://svelte.dev/playground/1bf60e745fae44f5becb4c830fde9b6e?version=5.38.10) |
+| [Hover + Tap (whileHover + whileTap)](https://motion.dev/docs/react?platform=react#hover-tap-animation)  | `/tests/motion/hover-and-tap`            | [View Example](https://svelte.dev/playground/674c7d58f2c740baa4886b01340a97ea?version=5.38.10) |
+| [Random - Shiny Button](https://www.youtube.com/watch?v=jcpLprT5F0I) by [@verse\_](https://x.com/verse_) | `/tests/random/shiny-button`             | [View Example](https://svelte.dev/playground/96f9e0bf624f4396adaf06c519147450?version=5.38.10) |
+| [Fancy Like Button](https://github.com/DRlFTER/fancyLikeButton)                                          | `/tests/random/fancy-like-button`        | [View Example](https://svelte.dev/playground/c34b7e53d41c48b0ab1eaf21ca120c6e?version=5.38.10) |
+| [Keyframes (square → circle → square; scale 1→2→1)](https://motion.dev/docs/react-animation#keyframes)   | `/tests/motion/keyframes`                | [View Example](https://svelte.dev/playground/05595ce0db124c1cbbe4e74fda68d717?version=5.38.10) |
+| [Animated Border Gradient (conic-gradient rotate)](https://www.youtube.com/watch?v=OgQI1-9T6ZA)          | `/tests/random/animated-border-gradient` | [View Example](https://svelte.dev/playground/6983a61b4c35441b8aa72a971de01a23?version=5.38.10) |
 
 ## Interactions
 
@@ -149,6 +150,91 @@ Notes:
 - Transform properties like `scale`/`rotate` are composed into a single `transform` style during SSR.
 - When `initial` is empty, the first keyframe from `animate` is used to seed SSR styles.
 
+## Utilities
+
+### useTime(id?)
+
+- Returns a Svelte readable store that updates once per animation frame with elapsed milliseconds since creation.
+- If you pass an `id`, calls with the same id return a shared timeline (kept in sync across components).
+- SSR-safe: Returns a static `0` store when `window` is not available.
+
+```svelte
+<script lang="ts">
+    import { motion, useTime } from '$lib'
+    import { derived } from 'svelte/store'
+
+    const time = useTime('global') // shared
+    const rotate = derived(time, (t) => ((t % 4000) / 4000) * 360)
+</script>
+
+<motion.div style={`rotate: ${$rotate}deg`} />
+```
+
+### useSpring
+
+`useSpring` creates a readable store that animates to its latest target with a spring. You can either control it directly with `set`/`jump`, or have it follow another readable (like a time-derived value).
+
+```svelte
+<script lang="ts">
+    import { useTime, useTransform, useSpring } from '$lib'
+
+    // Track another readable
+    const time = useTime()
+    const blurTarget = useTransform(() => {
+        const phase = ($time % 2000) / 2000
+        return 4 * (0.5 + 0.5 * Math.sin(phase * Math.PI * 2)) // 0..4
+    }, [time])
+    const blur = useSpring(blurTarget, { stiffness: 300 })
+
+    // Or direct control
+    const x = useSpring(0, { stiffness: 300 })
+    // x.set(100) // animates to 100
+    // x.jump(0)  // jumps without animation
+</script>
+
+<div style={`filter: blur(${$blur}px)`} />
+```
+
+- Accepts number or unit string (e.g., `"100vh"`) or a readable source.
+- Returns a readable with `{ set, jump }` methods when used in the browser; SSR-safe on the server.
+- Reference: Motion useSpring docs [motion.dev](https://motion.dev/docs/react-use-spring?platform=react).
+
+### useTransform
+
+`useTransform` creates a derived readable. It supports:
+
+- Range mapping: map a numeric source across input/output ranges with optional `{ clamp, ease, mixer }`.
+- Function form: compute from one or more dependencies.
+
+Range mapping example:
+
+```svelte
+<script lang="ts">
+    import { useTime, useTransform } from '$lib'
+    const time = useTime()
+    // Map 0..4000ms to 0..360deg, unclamped to allow wrap-around
+    const rotate = useTransform(time, [0, 4000], [0, 360], { clamp: false })
+</script>
+
+<div style={`rotate: ${$rotate}deg`} />
+```
+
+Function form example:
+
+```svelte
+<script lang="ts">
+    import { useTransform } from '$lib'
+    // Given stores a and b, compute their sum
+    const add = (a: number, b: number) => a + b
+    // deps are stores; body can access them via $ syntax
+    const total = useTransform(() => add($a, $b), [a, b])
+</script>
+
+<span>{$total}</span>
+```
+
+- Reference: Motion useTransform docs [motion.dev](https://motion.dev/docs/react-use-transform?platform=react).
+
 ## Access the underlying element (bind:ref)
 
 You can bind a ref to access the underlying DOM element rendered by a motion component:

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import MotionConfig from './components/MotionConfig.svelte';
-import type { MotionComponents } from './html/index.js';
+import type { MotionComponents } from './html/index';
 export declare const motion: MotionComponents;
 export { animate, hover } from 'motion';
-export type { MotionAnimate, MotionInitial, MotionTransition, MotionWhileTap } from './types.js';
+export type { MotionAnimate, MotionInitial, MotionTransition, MotionWhileTap } from './types';
+export { useSpring } from './utils/spring';
+export { useTime } from './utils/time';
+export { useTransform } from './utils/transform';
 export { MotionConfig };

package/dist/index.js

@@ -1,7 +1,10 @@
 import MotionConfig from './components/MotionConfig.svelte';
-import * as html from './html/index.js';
+import * as html from './html/index';
 // Create the motion object with all components
 export const motion = Object.fromEntries(Object.entries(html).map(([key, component]) => [key.toLowerCase(), component]));
 // Export all types
 export { animate, hover } from 'motion';
+export { useSpring } from './utils/spring';
+export { useTime } from './utils/time';
+export { useTransform } from './utils/transform';
 export { MotionConfig };

package/dist/utils/animation.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationOptions, DOMKeyframesDefinition } from 'motion';
+import { type AnimationOptions, type DOMKeyframesDefinition } from 'motion';
 /**
  * Merge two Motion `AnimationOptions` objects without mutating the inputs.
  *

package/dist/utils/animation.js

@@ -1,5 +1,5 @@
+import { hasFinishedPromise, isPromiseLike } from './promise';
 import { animate } from 'motion';
-import { hasFinishedPromise, isPromiseLike } from './promise.js';
 /**
  * Merge two Motion `AnimationOptions` objects without mutating the inputs.
  *

package/dist/utils/hover.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationOptions } from 'motion';
+import { type AnimationOptions } from 'motion';
 /**
  * Determine whether the current environment supports true hover.
  *

package/dist/utils/spring.d.ts

@@ -0,0 +1,38 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Spring configuration options.
+ *
+ * This is a minimal subset modeled after Motion's spring transition options.
+ * Values are tuned for sensible defaults, not parity.
+ *
+ * @typedef {Object} SpringOptions
+ * @property {number=} stiffness Spring stiffness (higher = snappier). Default 170.
+ * @property {number=} damping Spring damping (higher = less oscillation). Default 26.
+ * @property {number=} mass Mass of the object. Default 1.
+ * @property {number=} restDelta Threshold for absolute position delta to stop. Default 0.01.
+ * @property {number=} restSpeed Threshold for velocity magnitude to stop. Default 0.01.
+ */
+export type SpringOptions = {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    restDelta?: number;
+    restSpeed?: number;
+};
+/**
+ * Creates a spring-animated readable store. The store exposes `set` to
+ * animate towards a target, or `jump` to immediately set the value without
+ * animation. When constructed with another readable store, the spring
+ * automatically follows it.
+ *
+ * This is SSR-safe: On the server it returns a static store and no timers run.
+ *
+ * @template T
+ * @param {number|string|Readable<number|string>} source Initial value or a source store to follow.
+ * @param {SpringOptions=} options Spring configuration.
+ * @returns {Readable<number|string> & { set: (v: number|string) => void; jump: (v: number|string) => void; }}
+ */
+export declare const useSpring: (source: number | string | Readable<number | string>, options?: SpringOptions) => Readable<number | string> & {
+    set: (v: number | string) => void;
+    jump: (v: number | string) => void;
+};

package/dist/utils/spring.js

@@ -0,0 +1,157 @@
+import { readable, writable } from 'svelte/store';
+/**
+ * Parses a number or unit string into numeric value and unit.
+ * @param {number|string} v The input value.
+ * @returns {UnitValue} Parsed value and unit.
+ * @private
+ */
+const parseUnit = (v) => {
+    if (typeof v === 'number')
+        return { value: v, unit: '' };
+    const match = String(v).match(/^(-?\d*\.?\d+)(.*)$/);
+    if (!match || !match[1])
+        return { value: 0, unit: '' };
+    const parsed = Number.parseFloat(match[1]);
+    if (!Number.isFinite(parsed))
+        return { value: 0, unit: '' };
+    const unit = match[2] ?? '';
+    return { value: parsed, unit };
+};
+/**
+ * Formats a numeric value with a unit.
+ * @param {number} n Numeric value.
+ * @param {string} unit Unit suffix.
+ * @returns {number|string} Number or string with unit.
+ * @private
+ */
+const formatUnit = (n, unit) => (unit ? `${n}${unit}` : n);
+/**
+ * Creates a spring-animated readable store. The store exposes `set` to
+ * animate towards a target, or `jump` to immediately set the value without
+ * animation. When constructed with another readable store, the spring
+ * automatically follows it.
+ *
+ * This is SSR-safe: On the server it returns a static store and no timers run.
+ *
+ * @template T
+ * @param {number|string|Readable<number|string>} source Initial value or a source store to follow.
+ * @param {SpringOptions=} options Spring configuration.
+ * @returns {Readable<number|string> & { set: (v: number|string) => void; jump: (v: number|string) => void; }}
+ */
+export const useSpring = (source, options = {}) => {
+    if (typeof window === 'undefined') {
+        // Derive best-effort initial value for SSR to avoid hydration mismatch
+        let initial = 0;
+        if (typeof source === 'number' || typeof source === 'string') {
+            initial = source;
+        }
+        else if (source && typeof source === 'object') {
+            const anySource = source;
+            if (typeof anySource.get === 'function') {
+                const v = anySource.get();
+                if (typeof v === 'number' || typeof v === 'string')
+                    initial = v;
+            }
+            else if (typeof anySource.value === 'number' || typeof anySource.value === 'string') {
+                initial = anySource.value;
+            }
+        }
+        const store = readable(initial, () => { });
+        store.set = () => { };
+        store.jump = () => { };
+        return store;
+    }
+    const { stiffness = 170, damping = 26, mass = 1, restDelta = 0.01, restSpeed = 0.01 } = options;
+    const state = {
+        current: parseUnit(typeof source === 'object' ? 0 : source),
+        target: parseUnit(typeof source === 'object' ? 0 : source)
+    };
+    const unit = state.current.unit || state.target.unit;
+    const store = writable(formatUnit(state.current.value, unit));
+    let raf = 0;
+    let lastTime = 0;
+    let velocity = 0;
+    const step = (t) => {
+        if (!lastTime)
+            lastTime = t;
+        // Clamp dt to a safe range to avoid instability across large time gaps
+        const dt = Math.min(0.1, Math.max(0.001, (t - lastTime) / 1000));
+        lastTime = t;
+        const displacement = state.current.value - state.target.value;
+        // Spring force based on Hooke's Law: F = -k x; damping force: -c v
+        const spring = -stiffness * displacement;
+        const damper = -damping * velocity;
+        const accel = (spring + damper) / mass;
+        velocity += accel * dt;
+        state.current.value += velocity * dt;
+        const isNoVelocity = Math.abs(velocity) <= restSpeed;
+        const isNoDisplacement = Math.abs(state.current.value - state.target.value) <= restDelta;
+        const done = isNoVelocity && isNoDisplacement;
+        if (done) {
+            state.current.value = state.target.value;
+            store.set(formatUnit(state.current.value, unit));
+            raf = 0;
+            lastTime = 0;
+            return;
+        }
+        store.set(formatUnit(state.current.value, unit));
+        raf = requestAnimationFrame(step);
+    };
+    const start = () => {
+        if (raf)
+            return;
+        raf = requestAnimationFrame(step);
+    };
+    const api = {
+        set: (v) => {
+            state.target = parseUnit(v);
+            start();
+        },
+        jump: (v) => {
+            state.current = parseUnit(v);
+            state.target = parseUnit(v);
+            velocity = 0;
+            store.set(formatUnit(state.current.value, state.current.unit || state.target.unit));
+        }
+    };
+    // If following another store, subscribe and forward values to set()
+    if (typeof source === 'object' && 'subscribe' in source) {
+        let followSource = true;
+        const unsub = source.subscribe((v) => api.set(v));
+        const wrapped = readable(formatUnit(state.current.value, unit), (set) => {
+            const sub = store.subscribe(set);
+            return () => {
+                sub();
+                unsub();
+                followSource = false;
+                if (raf)
+                    cancelAnimationFrame(raf);
+            };
+        });
+        wrapped.set = (v) => {
+            if (followSource)
+                unsub();
+            followSource = false;
+            api.set(v);
+        };
+        wrapped.jump = (v) => {
+            if (followSource)
+                unsub();
+            followSource = false;
+            api.jump(v);
+        };
+        return wrapped;
+    }
+    // Standard readable wrapping internal writable
+    const wrapped = readable(formatUnit(state.current.value, unit), (set) => {
+        const sub = store.subscribe(set);
+        return () => {
+            sub();
+            if (raf)
+                cancelAnimationFrame(raf);
+        };
+    });
+    wrapped.set = api.set;
+    wrapped.jump = api.jump;
+    return wrapped;
+};

package/dist/utils/time.d.ts

@@ -0,0 +1,14 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Returns a time store that ticks once per animation frame.
+ *
+ * - Without an `id`, returns a fresh timeline per call.
+ * - With an `id`, callers sharing the same id receive the same store/timeline,
+ *   ensuring synchronized reads across components.
+ * - SSR-safe: Returns a static 0-valued store when `window` is unavailable.
+ *
+ * @param {string=} id Optional timeline identifier for sharing across calls.
+ * @returns {Readable<number>} A readable store of elapsed milliseconds.
+ * @see https://motion.dev/docs/react-use-time?platform=react
+ */
+export declare const useTime: (id?: string) => Readable<number>;

package/dist/utils/time.js

@@ -0,0 +1,68 @@
+import { readable } from 'svelte/store';
+const SSR_ZERO = readable(0, () => { });
+const sharedStores = new Map();
+// Clear shared timelines on HMR dispose to avoid stale entries across hot reloads
+if (import.meta &&
+    import.meta.hot) {
+    ;
+    import.meta.hot.dispose(() => {
+        sharedStores.clear();
+    });
+}
+/**
+ * Creates a new time store that updates once per animation frame.
+ *
+ * The store value represents elapsed milliseconds since the store was created.
+ * In SSR environments (no `window`), a static 0-valued store is returned.
+ *
+ * @returns {Readable<number>} A readable store of elapsed milliseconds.
+ * @see https://motion.dev/docs/react-use-time?platform=react
+ * @private
+ */
+const createTimeStore = () => {
+    if (typeof window === 'undefined')
+        return SSR_ZERO;
+    return readable(0, (set) => {
+        const start = performance.now();
+        let raf = 0;
+        /* c8 ignore start */
+        const loop = (t) => {
+            set(t - start);
+            raf = requestAnimationFrame(loop);
+        };
+        /* c8 ignore stop */
+        raf = requestAnimationFrame(loop);
+        return () => cancelAnimationFrame(raf);
+    });
+};
+/**
+ * Returns a time store that ticks once per animation frame.
+ *
+ * - Without an `id`, returns a fresh timeline per call.
+ * - With an `id`, callers sharing the same id receive the same store/timeline,
+ *   ensuring synchronized reads across components.
+ * - SSR-safe: Returns a static 0-valued store when `window` is unavailable.
+ *
+ * @param {string=} id Optional timeline identifier for sharing across calls.
+ * @returns {Readable<number>} A readable store of elapsed milliseconds.
+ * @see https://motion.dev/docs/react-use-time?platform=react
+ */
+export const useTime = (id) => {
+    if (!id)
+        return createTimeStore();
+    if (typeof window === 'undefined')
+        return SSR_ZERO;
+    const existing = sharedStores.get(id);
+    if (existing)
+        return existing;
+    const base = createTimeStore();
+    const store = readable(0, (set) => {
+        const unsub = base.subscribe(set);
+        return () => {
+            unsub();
+            sharedStores.delete(id);
+        };
+    });
+    sharedStores.set(id, store);
+    return store;
+};

package/dist/utils/transform.d.ts

@@ -0,0 +1,42 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Options for range-mapping transform.
+ *
+ * - clamp: If true, clamps the input to the active segment bounds.
+ * - ease: A single easing function or one per segment to shape interpolation.
+ * - mixer: Custom mixer factory to interpolate non-numeric outputs.
+ *
+ * @see https://motion.dev/docs/react-use-transform?platform=react
+ */
+export type TransformOptions = {
+    clamp?: boolean;
+    ease?: ((t: number) => number) | Array<(t: number) => number>;
+    mixer?: (from: unknown, to: unknown) => (t: number) => unknown;
+};
+/**
+ * Clamps a numeric value between two bounds, irrespective of their order.
+ *
+ * @param val Current value.
+ * @param a First bound.
+ * @param b Second bound.
+ * @returns Value clamped to [min(a,b), max(a,b)].
+ */
+export declare const clampBidirectional: (val: number, a: number, b: number) => number;
+/**
+ * Creates a derived Svelte store that transforms values.
+ *
+ * Two supported forms (API parity with Motion's useTransform):
+ * - Mapping form: Map a numeric source across input/output ranges.
+ *   Example: `useTransform(src, [0, 100], [0, 1], { clamp: true })`
+ * - Function form: Recompute from a function based on dependency stores.
+ *   Example: `useTransform(() => compute(), [depA, depB])`
+ *
+ * @template T
+ * @param {Readable<number>|(() => T)} sourceOrCompute Numeric source store (mapping form), or compute function (function form).
+ * @param {number[]|Readable<unknown>[]} inputOrDeps Input stops (mapping) or dependency stores (function form).
+ * @param {T[]=} output Output stops (mapping form only). Must match input length.
+ * @param {TransformOptions=} options Mapping options (mapping form only).
+ * @returns {Readable<T>} A derived Svelte readable store.
+ * @see https://motion.dev/docs/react-use-transform?platform=react
+ */
+export declare const useTransform: <T = number>(sourceOrCompute: Readable<number> | (() => T), inputOrDeps: number[] | Readable<unknown>[], output?: T[], options?: TransformOptions) => Readable<T>;

package/dist/utils/transform.js

@@ -0,0 +1,129 @@
+import { derived, readable } from 'svelte/store';
+/**
+ * Creates a linear mixer function for numeric values.
+ *
+ * @param from Starting numeric value.
+ * @param to Ending numeric value.
+ * @returns Function that linearly interpolates between from→to for progress t∈[0,1].
+ * @private
+ */
+const linearMix = (from, to) => (t) => from + (to - from) * t;
+/**
+ * Clamps a numeric value between two bounds, irrespective of their order.
+ *
+ * @param val Current value.
+ * @param a First bound.
+ * @param b Second bound.
+ * @returns Value clamped to [min(a,b), max(a,b)].
+ */
+export const clampBidirectional = (val, a, b) => {
+    const lower = a < b ? a : b;
+    const upper = a < b ? b : a;
+    return Math.min(Math.max(val, lower), upper);
+};
+/**
+ * Finds the segment index i such that x lies between input[i] and input[i+1].
+ * Handles both ascending and descending input ranges.
+ *
+ * @param input Monotonic list of input stops.
+ * @param x Current input value.
+ * @returns Segment index in range [0, input.length - 2].
+ * @private
+ */
+const findSegment = (input, x) => {
+    if (input.length < 2)
+        return 0;
+    const first = input[0];
+    const second = input[1];
+    const ascending = second > first;
+    if (ascending) {
+        if (x <= first)
+            return 0;
+        for (let i = 1; i < input.length; i++) {
+            const curr = input[i];
+            if (x <= curr)
+                return i - 1;
+        }
+        return input.length - 2;
+    }
+    else {
+        if (x >= first)
+            return 0;
+        for (let i = 1; i < input.length; i++) {
+            const curr = input[i];
+            if (x >= curr)
+                return i - 1;
+        }
+        return input.length - 2;
+    }
+};
+/**
+ * Creates a derived Svelte store that transforms values.
+ *
+ * Two supported forms (API parity with Motion's useTransform):
+ * - Mapping form: Map a numeric source across input/output ranges.
+ *   Example: `useTransform(src, [0, 100], [0, 1], { clamp: true })`
+ * - Function form: Recompute from a function based on dependency stores.
+ *   Example: `useTransform(() => compute(), [depA, depB])`
+ *
+ * @template T
+ * @param {Readable<number>|(() => T)} sourceOrCompute Numeric source store (mapping form), or compute function (function form).
+ * @param {number[]|Readable<unknown>[]} inputOrDeps Input stops (mapping) or dependency stores (function form).
+ * @param {T[]=} output Output stops (mapping form only). Must match input length.
+ * @param {TransformOptions=} options Mapping options (mapping form only).
+ * @returns {Readable<T>} A derived Svelte readable store.
+ * @see https://motion.dev/docs/react-use-transform?platform=react
+ */
+export const useTransform = (sourceOrCompute, inputOrDeps, output, options = {}) => {
+    // Function form: (compute, deps)
+    if (typeof sourceOrCompute === 'function') {
+        const compute = sourceOrCompute;
+        const deps = inputOrDeps;
+        if (!deps || deps.length === 0)
+            return readable(compute());
+        return derived(deps, () => compute());
+    }
+    // Mapping form: (source, input, output, options)
+    const source = sourceOrCompute;
+    const input = inputOrDeps;
+    const out = (output ?? []);
+    const { clamp = true, ease, mixer } = options;
+    if (input.length !== out.length) {
+        throw new Error(`useTransform: input and output arrays must be the same length (input: ${input.length}, output: ${out.length})`);
+    }
+    const easings = Array.isArray(ease)
+        ? ease
+        : ease
+            ? new Array(Math.max(0, out.length - 1)).fill(ease)
+            : [];
+    return derived(source, (x) => {
+        if (input.length === 0)
+            return out[0];
+        if (input.length === 1)
+            return out[0];
+        const seg = findSegment(input, x);
+        const i0 = input[seg];
+        const i1 = input[seg + 1];
+        const o0 = out[seg];
+        const o1 = out[seg + 1];
+        // Runtime validation to avoid non-null assertions
+        if (i0 === undefined || i1 === undefined || o0 === undefined || o1 === undefined) {
+            console.warn('useTransform: Invalid segment bounds', {
+                seg,
+                inputLength: input.length,
+                outputLength: out.length
+            });
+            return out[0];
+        }
+        const localClamp = clamp ? clampBidirectional : (val) => val;
+        const progress = i0 === i1 ? 0 : (localClamp(x, i0, i1) - i0) / (i1 - i0);
+        const e = easings[seg];
+        const p = e ? e(progress) : progress;
+        const mix = mixer
+            ? mixer(o0, o1)
+            : typeof o0 === 'number' && typeof o1 === 'number'
+                ? linearMix(o0, o1)
+                : (_t) => (p < 0.5 ? o0 : o1);
+        return mix(p);
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A lightweight animation library for Svelte 5 that provides smooth, hardware-accelerated animations. Features include spring physics, custom easing, and fluid transitions. Built on top of the motion library, it offers a simple API for creating complex animations with minimal code. Perfect for interactive UIs, micro-interactions, and engaging user experiences.",
   "keywords": [
     "svelte",