@humanspeak/svelte-motion 0.4.9 → 0.5.1

package/dist/utils/transform.svelte.js

@@ -0,0 +1,189 @@
+// Utilities for building and validating transform strings
+import { isMotionValue, mapValue, transformValue } from 'motion-dom';
+import {} from 'svelte/store';
+import { augmentMotionValue, bridgeReadableToMotionValue } from './augmentMotionValue.svelte.js';
+const DEFAULTS = {
+    x: 0,
+    y: 0,
+    scale: 1,
+    scaleX: 1,
+    scaleY: 1,
+    rotate: 0
+};
+/**
+ * Build a CSS transform string from numeric values (no matrices).
+ *
+ * @param values Partial map of translate/scale/rotate values.
+ * @returns A space-separated CSS `transform` string, or `""` when all values are defaults.
+ *
+ * @example
+ * ```ts
+ * buildTransform({ x: 10, y: 20, scale: 1.5 })
+ * // => "translate(10px, 20px) scale(1.5)"
+ *
+ * buildTransform({ x: 0, y: 0, rotate: 0 }) // all defaults
+ * // => ""
+ * ```
+ */
+export const buildTransform = (values) => {
+    const v = { ...DEFAULTS, ...values };
+    const useAxes = values.scaleX !== undefined || values.scaleY !== undefined;
+    const parts = [];
+    if (v.x !== 0 || v.y !== 0)
+        parts.push(`translate(${round(v.x)}px, ${round(v.y)}px)`);
+    if (v.rotate !== 0)
+        parts.push(`rotate(${round(v.rotate)}deg)`);
+    if (useAxes) {
+        parts.push(`scaleX(${round(v.scaleX)})`);
+        parts.push(`scaleY(${round(v.scaleY)})`);
+    }
+    else if (v.scale !== 1) {
+        parts.push(`scale(${round(v.scale)})`);
+    }
+    return parts.join(' ').trim();
+};
+/**
+ * Lightweight safety check for transform magnitudes and NaN values.
+ *
+ * @param values Transform values to validate.
+ * @param opts Optional configuration; `maxScale` caps allowable absolute scale (default 8).
+ * @returns `true` if all scale values are finite and within bounds.
+ *
+ * @example
+ * ```ts
+ * isSafeTransform({ scale: 2 })                  // true
+ * isSafeTransform({ scale: 100 })                // false (exceeds default maxScale=8)
+ * isSafeTransform({ scale: 100 }, { maxScale: 200 })  // true
+ * isSafeTransform({ scale: NaN })                // false
+ * ```
+ */
+export const isSafeTransform = (values, opts) => {
+    const maxScale = opts?.maxScale ?? 8;
+    const entries = [
+        ['scale', values.scale],
+        ['scaleX', values.scaleX],
+        ['scaleY', values.scaleY]
+    ];
+    for (const [, val] of entries) {
+        if (val === undefined)
+            continue;
+        if (!Number.isFinite(val))
+            return false;
+        if (Math.abs(val) > maxScale)
+            return false;
+    }
+    return true;
+};
+/**
+ * Extract the uniform scale factor from a CSS `matrix()` string.
+ *
+ * @param matrix A CSS `matrix(...)` value, `"none"`, `null`, or `undefined`.
+ * @returns The `a` component of the matrix (uniform scale), or `null` if unparseable.
+ *
+ * @example
+ * ```ts
+ * parseMatrixScale('matrix(1.5, 0, 0, 1.5, 0, 0)')  // 1.5
+ * parseMatrixScale('none')                          // null
+ * parseMatrixScale(null)                            // null
+ * ```
+ */
+export const parseMatrixScale = (matrix) => {
+    if (!matrix || matrix === 'none')
+        return null;
+    const m = matrix.match(/matrix\(([^)]+)\)/);
+    if (!m)
+        return null;
+    const [a] = m[1].split(',').map((s) => parseFloat(s.trim()));
+    return Number.isFinite(a) ? a : null;
+};
+/**
+ * Round a number to six decimal places to avoid excessive precision in CSS strings.
+ *
+ * @param n The number to round.
+ * @returns The rounded value.
+ */
+const round = (n) => {
+    return Math.round(n * 1e6) / 1e6;
+};
+/**
+ * Normalizes a `TransformSource<T>` into a `MotionValue<T>`. Returns the
+ * source as-is for any motion-value input (no bridge), or a bridge
+ * `MotionValue` + cleanup for `Readable` inputs. The cast at the
+ * motion-value branch is safe — both `MotionValue` and `AugmentedMotionValue`
+ * are the same instance at runtime.
+ */
+const toMotionValue = (source) => {
+    if (isMotionValue(source)) {
+        return { value: source, dispose: () => undefined };
+    }
+    return bridgeReadableToMotionValue(source);
+};
+export function useTransform(sourceOrCompute, inputOrTransformer, outputOrOutputMap, options) {
+    // Compute form: useTransform(() => compute).
+    if (typeof sourceOrCompute === 'function') {
+        const compute = sourceOrCompute;
+        const value = transformValue(compute);
+        $effect(() => () => value.destroy());
+        return augmentMotionValue(value);
+    }
+    // Multi-input list form: useTransform([mv, mv, …], ([a, b, …]) => O).
+    if (Array.isArray(sourceOrCompute) && typeof inputOrTransformer === 'function') {
+        const sources = sourceOrCompute;
+        const transformer = inputOrTransformer;
+        const value = transformValue(() => {
+            const latest = [];
+            for (let i = 0; i < sources.length; i++) {
+                latest.push(sources[i].get());
+            }
+            return transformer(latest);
+        });
+        $effect(() => () => value.destroy());
+        return augmentMotionValue(value);
+    }
+    // Single-MV transformer form: useTransform(mv, (latest) => O).
+    if (typeof inputOrTransformer === 'function') {
+        const source = sourceOrCompute;
+        const transformer = inputOrTransformer;
+        const value = transformValue(() => transformer(source.get()));
+        $effect(() => () => value.destroy());
+        return augmentMotionValue(value);
+    }
+    // Mapping forms (single output array or output map).
+    const source = sourceOrCompute;
+    const input = inputOrTransformer ?? [];
+    const { value: numericSource, dispose: disposeBridge } = toMotionValue(source);
+    // Multi-output mapping form: useTransform(source, [range], { key: [out], … }, options).
+    // The `outputOrOutputMap !== null` check is load-bearing — `typeof null`
+    // is `'object'`, so a `null` argument would otherwise enter this branch
+    // and crash at `Object.keys(null)`.
+    if (outputOrOutputMap !== undefined &&
+        outputOrOutputMap !== null &&
+        !Array.isArray(outputOrOutputMap) &&
+        typeof outputOrOutputMap === 'object') {
+        const outputMap = outputOrOutputMap;
+        const keys = Object.keys(outputMap);
+        const result = {};
+        const inners = [];
+        for (const key of keys) {
+            const inner = mapValue(numericSource, input, outputMap[key], options);
+            inners.push(inner);
+            result[key] = augmentMotionValue(inner);
+        }
+        // One cleanup effect for all per-key MVs plus the shared bridge —
+        // saves N effect nodes vs. registering one per key.
+        $effect(() => () => {
+            for (const inner of inners)
+                inner.destroy();
+            disposeBridge();
+        });
+        return result;
+    }
+    // Single-output mapping form: useTransform(source, [range], [out], options).
+    const output = outputOrOutputMap ?? [];
+    const value = mapValue(numericSource, input, output, options);
+    $effect(() => () => {
+        value.destroy();
+        disposeBridge();
+    });
+    return augmentMotionValue(value);
+}

package/dist/utils/velocity.svelte.d.ts

@@ -0,0 +1,61 @@
+import { type Readable } from 'svelte/store';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Source for {@link useVelocity}: a motion-dom `MotionValue` or a Svelte
+ * readable. Svelte readables are bridged into a `MotionValue` so motion-dom's
+ * native velocity tracking can drive the result.
+ */
+export type VelocitySource = AugmentedMotionValue<number | string> | Readable<number | string>;
+/**
+ * Creates an augmented `MotionValue<number>` whose value tracks the velocity
+ * of `source` in units/second.
+ *
+ * Mirrors React framer-motion 1:1: on every `source` change, schedules an
+ * `updateVelocity` callback in motion-dom's frame loop via
+ * `frame.update(updateVelocity, false, true)`. `updateVelocity` reads
+ * `source.getVelocity()` (motion-dom tracks per-frame deltas + timestamps
+ * for free) and writes it to the result. If velocity is still non-zero,
+ * `updateVelocity` re-schedules itself for the next frame — so the loop
+ * only runs while there's actual motion and snaps to `0` the moment things
+ * settle. Idle CPU is zero.
+ *
+ * Returned value is a real motion-dom `MotionValue` (composes with
+ * `useTransform`, `useSpring`, `useMotionTemplate`, etc.) plus a
+ * `$state`-backed `.current` getter and a `.subscribe` shim.
+ *
+ * Lifecycle: must be called during component initialization. The change
+ * subscription, the frame-loop callback, and any Svelte-readable bridge are
+ * all torn down when the surrounding `$effect` unmounts.
+ *
+ * SSR-safe: returns a static augmented motion value with no subscriptions
+ * and no frame loop on the server.
+ *
+ * @param source A motion value or readable store of numeric or unit-string values.
+ * @returns A `MotionValue<number>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import {
+ *     useMotionValue,
+ *     useTransform,
+ *     useVelocity
+ *   } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *   const xVelocity = useVelocity(x)
+ *   // Map velocity to a momentum-driven skew. Skew goes positive when x is
+ *   // accelerating right, negative when accelerating left, and snaps to 0
+ *   // when motion settles.
+ *   const skew = useTransform(xVelocity, [-1000, 0, 1000], [-15, 0, 15])
+ * </script>
+ *
+ * <div
+ *   style="transform: translateX({x.current}px) skewX({skew.current}deg)"
+ *   onpointermove={(e) => x.set(e.clientX)}
+ * />
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-velocity
+ */
+export declare const useVelocity: (source: VelocitySource) => AugmentedMotionValue<number>;

package/dist/utils/velocity.svelte.js

@@ -0,0 +1,132 @@
+import { cancelFrame, frame, isMotionValue, motionValue } from 'motion-dom';
+import {} from 'svelte/store';
+import { augmentMotionValue, bridgeReadableToMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Parses a numeric value from a number or unit string (e.g. `"100px"` → `100`).
+ */
+const parseNumeric = (v) => {
+    if (typeof v === 'number')
+        return v;
+    const parsed = Number.parseFloat(String(v));
+    return Number.isFinite(parsed) ? parsed : 0;
+};
+/**
+ * Creates an augmented `MotionValue<number>` whose value tracks the velocity
+ * of `source` in units/second.
+ *
+ * Mirrors React framer-motion 1:1: on every `source` change, schedules an
+ * `updateVelocity` callback in motion-dom's frame loop via
+ * `frame.update(updateVelocity, false, true)`. `updateVelocity` reads
+ * `source.getVelocity()` (motion-dom tracks per-frame deltas + timestamps
+ * for free) and writes it to the result. If velocity is still non-zero,
+ * `updateVelocity` re-schedules itself for the next frame — so the loop
+ * only runs while there's actual motion and snaps to `0` the moment things
+ * settle. Idle CPU is zero.
+ *
+ * Returned value is a real motion-dom `MotionValue` (composes with
+ * `useTransform`, `useSpring`, `useMotionTemplate`, etc.) plus a
+ * `$state`-backed `.current` getter and a `.subscribe` shim.
+ *
+ * Lifecycle: must be called during component initialization. The change
+ * subscription, the frame-loop callback, and any Svelte-readable bridge are
+ * all torn down when the surrounding `$effect` unmounts.
+ *
+ * SSR-safe: returns a static augmented motion value with no subscriptions
+ * and no frame loop on the server.
+ *
+ * @param source A motion value or readable store of numeric or unit-string values.
+ * @returns A `MotionValue<number>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import {
+ *     useMotionValue,
+ *     useTransform,
+ *     useVelocity
+ *   } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *   const xVelocity = useVelocity(x)
+ *   // Map velocity to a momentum-driven skew. Skew goes positive when x is
+ *   // accelerating right, negative when accelerating left, and snaps to 0
+ *   // when motion settles.
+ *   const skew = useTransform(xVelocity, [-1000, 0, 1000], [-15, 0, 15])
+ * </script>
+ *
+ * <div
+ *   style="transform: translateX({x.current}px) skewX({skew.current}deg)"
+ *   onpointermove={(e) => x.set(e.clientX)}
+ * />
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-velocity
+ */
+export const useVelocity = (source) => {
+    // Bridge non-numeric sources into a MotionValue<number> so motion-dom's
+    // getVelocity() tracks deltas correctly. Two paths feed this:
+    //   1. Svelte readables — always bridged (motion-dom doesn't know how to
+    //      read them).
+    //   2. MotionValue<string> — bridged too, because motion-dom samples
+    //      `canTrackVelocity` ONCE from the initial value via
+    //      `!isNaN(parseFloat(value))`. A string MV that starts non-numeric
+    //      (e.g. `""`) gets stuck at velocity = 0 forever, even if it later
+    //      becomes a unit string like `"100px"`. The bridge runs every emit
+    //      through `parseNumeric` so the tracker MV is always numeric.
+    let tracker;
+    let disposeBridge;
+    if (isMotionValue(source)) {
+        const initial = source.get();
+        if (typeof initial === 'number') {
+            tracker = source;
+        }
+        else if (typeof window !== 'undefined') {
+            const bridge = motionValue(parseNumeric(initial));
+            const unsub = source.on('change', (v) => {
+                bridge.set(parseNumeric(v));
+            });
+            tracker = bridge;
+            disposeBridge = () => {
+                unsub();
+                bridge.destroy();
+            };
+        }
+        else {
+            // SSR: parse the initial value but don't subscribe — the change
+            // listener would leak past the early SSR return below (no
+            // $effect runs to call dispose).
+            tracker = motionValue(parseNumeric(initial));
+        }
+    }
+    else if (typeof window !== 'undefined') {
+        const bridge = bridgeReadableToMotionValue(source, parseNumeric);
+        tracker = bridge.value;
+        disposeBridge = bridge.dispose;
+    }
+    else {
+        tracker = motionValue(0);
+    }
+    const result = motionValue(tracker.getVelocity());
+    // SSR: skip the frame-loop wiring entirely and return a static MV.
+    if (typeof window === 'undefined') {
+        return augmentMotionValue(result);
+    }
+    const updateVelocity = () => {
+        const latest = tracker.getVelocity();
+        result.set(latest);
+        if (latest)
+            frame.update(updateVelocity);
+    };
+    const unsubChange = tracker.on('change', () => {
+        // keepAlive: false, immediate: true — run at end of current frame if
+        // we're already in one. Matches React framer-motion's useVelocity.
+        frame.update(updateVelocity, false, true);
+    });
+    $effect(() => () => {
+        unsubChange();
+        cancelFrame(updateVelocity);
+        disposeBridge?.();
+        result.destroy();
+    });
+    return augmentMotionValue(result);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.4.9",
+  "version": "0.5.1",
   "description": "Framer Motion for Svelte 5. Declarative motion.<tag> components with AnimatePresence exit animations, gestures (hover, tap, drag, focus, in-view), variants, FLIP layout animations, shared-layout transitions, spring physics, and scroll-linked motion values. The drop-in Framer Motion alternative for Svelte and SvelteKit.",
   "keywords": [
     "svelte",

package/dist/utils/motionTemplate.d.ts

@@ -1,21 +0,0 @@
-import { type Readable } from 'svelte/store';
-/**
- * Tagged template literal that creates a derived store from interpolated
- * readable stores. When any input store changes, the resulting store
- * recomputes the template string.
- *
- * SSR-safe: `derived` from svelte/store works on the server.
- *
- * @example
- * ```ts
- * const blur = useSpring(0)
- * const filter = useMotionTemplate`blur(${blur}px)`
- * // $filter → "blur(0px)"
- * ```
- *
- * @param strings Static template string parts.
- * @param values Readable stores to interpolate.
- * @returns A readable store of the composed string.
- * @see https://motion.dev/docs/react-use-motion-template
- */
-export declare const useMotionTemplate: (strings: TemplateStringsArray, ...values: Readable<number | string>[]) => Readable<string>;

package/dist/utils/motionTemplate.js

@@ -1,33 +0,0 @@
-import { derived } from 'svelte/store';
-/**
- * Tagged template literal that creates a derived store from interpolated
- * readable stores. When any input store changes, the resulting store
- * recomputes the template string.
- *
- * SSR-safe: `derived` from svelte/store works on the server.
- *
- * @example
- * ```ts
- * const blur = useSpring(0)
- * const filter = useMotionTemplate`blur(${blur}px)`
- * // $filter → "blur(0px)"
- * ```
- *
- * @param strings Static template string parts.
- * @param values Readable stores to interpolate.
- * @returns A readable store of the composed string.
- * @see https://motion.dev/docs/react-use-motion-template
- */
-export const useMotionTemplate = (strings, ...values) => {
-    if (values.length === 0)
-        return derived([], () => strings[0] ?? '');
-    return derived(values, (current) => {
-        let result = '';
-        for (let i = 0; i < strings.length; i++) {
-            result += strings[i] ?? '';
-            if (i < current.length)
-                result += String(current[i]);
-        }
-        return result;
-    });
-};

package/dist/utils/motionValue.d.ts

@@ -1,6 +0,0 @@
-import { type Readable } from 'svelte/store';
-export type MotionValue<T = number> = Readable<T> & {
-    set: (v: T) => void;
-    get: () => T;
-};
-export declare const useMotionValue: <T = number>(initial: T) => MotionValue<T>;

package/dist/utils/motionValue.js

@@ -1,13 +0,0 @@
-import { writable } from 'svelte/store';
-export const useMotionValue = (initial) => {
-    let current = initial;
-    const store = writable(initial);
-    return {
-        subscribe: store.subscribe,
-        set: (v) => {
-            current = v;
-            store.set(v);
-        },
-        get: () => current
-    };
-};

package/dist/utils/scroll.d.ts

@@ -1,63 +0,0 @@
-import { type Readable } from 'svelte/store';
-import { type ElementOrGetter } from './dom.js';
-/**
- * A scroll offset edge defined as a string (e.g. `"start"`, `"end"`, `"center"`)
- * or a number (0–1 progress). Each offset entry is a pair of `[target, container]`.
- */
-type ScrollOffset = Array<[number | string, number | string]> | string[];
-/**
- * Options accepted by `useScroll`.
- */
-type UseScrollOptions = {
-    /** Scrollable container to track. Defaults to the page. Accepts an element or a getter function. */
-    container?: ElementOrGetter;
-    /** Target element to track position of within the container. Accepts an element or a getter function. */
-    target?: ElementOrGetter;
-    /** Scroll offset configuration for element position tracking. */
-    offset?: ScrollOffset;
-    /** Which axis to use for the single-axis `progress` value supplied to `scroll()`. */
-    axis?: 'x' | 'y';
-};
-/**
- * Return type of `useScroll` — four readable Svelte stores representing
- * scroll position and normalised progress for both axes.
- */
-type UseScrollReturn = {
-    scrollX: Readable<number>;
-    scrollY: Readable<number>;
-    scrollXProgress: Readable<number>;
-    scrollYProgress: Readable<number>;
-};
-/**
- * Creates scroll-linked Svelte stores for building scroll-driven animations
- * such as progress indicators and parallax effects.
- *
- * When the returned stores are used with `opacity` / `transform` CSS properties
- * the animations can be hardware accelerated by the browser.
- *
- * SSR-safe: returns static `readable(0)` stores on the server.
- *
- * `container` and `target` accept either an `HTMLElement` directly or a
- * getter function `() => HTMLElement | undefined`. This is useful with
- * Svelte's `bind:this` where the element isn't available until after mount.
- * When a getter is provided, element resolution is deferred until the
- * first subscriber arrives, and if the element isn't available yet the
- * stores poll on each animation frame until it is.
- *
- * @example
- * ```svelte
- * <script>
- *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
- *
- *   const { scrollYProgress } = useScroll()
- *   const scaleX = useSpring(scrollYProgress)
- * </script>
- *
- * <div style="transform: scaleX({$scaleX}); transform-origin: left;" />
- * ```
- *
- * @param options Optional scroll tracking configuration.
- * @returns An object with `scrollX`, `scrollY`, `scrollXProgress`, and `scrollYProgress` stores.
- */
-export declare const useScroll: (options?: UseScrollOptions) => UseScrollReturn;
-export {};

package/dist/utils/scroll.js

@@ -1,79 +0,0 @@
-import { scroll } from 'motion';
-import { readable, writable } from 'svelte/store';
-import { createAttachable } from './attachable.js';
-import {} from './dom.js';
-/**
- * Creates scroll-linked Svelte stores for building scroll-driven animations
- * such as progress indicators and parallax effects.
- *
- * When the returned stores are used with `opacity` / `transform` CSS properties
- * the animations can be hardware accelerated by the browser.
- *
- * SSR-safe: returns static `readable(0)` stores on the server.
- *
- * `container` and `target` accept either an `HTMLElement` directly or a
- * getter function `() => HTMLElement | undefined`. This is useful with
- * Svelte's `bind:this` where the element isn't available until after mount.
- * When a getter is provided, element resolution is deferred until the
- * first subscriber arrives, and if the element isn't available yet the
- * stores poll on each animation frame until it is.
- *
- * @example
- * ```svelte
- * <script>
- *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
- *
- *   const { scrollYProgress } = useScroll()
- *   const scaleX = useSpring(scrollYProgress)
- * </script>
- *
- * <div style="transform: scaleX({$scaleX}); transform-origin: left;" />
- * ```
- *
- * @param options Optional scroll tracking configuration.
- * @returns An object with `scrollX`, `scrollY`, `scrollXProgress`, and `scrollYProgress` stores.
- */
-export const useScroll = (options) => {
-    if (typeof window === 'undefined') {
-        return {
-            scrollX: readable(0),
-            scrollY: readable(0),
-            scrollXProgress: readable(0),
-            scrollYProgress: readable(0)
-        };
-    }
-    const stores = {
-        scrollX: writable(0),
-        scrollY: writable(0),
-        scrollXProgress: writable(0),
-        scrollYProgress: writable(0)
-    };
-    const attachable = createAttachable({
-        refs: { container: options?.container, target: options?.target },
-        onAttach: ({ container, target }) => scroll((_progress, info) => {
-            stores.scrollX.set(info.x.current);
-            stores.scrollY.set(info.y.current);
-            stores.scrollXProgress.set(info.x.progress);
-            stores.scrollYProgress.set(info.y.progress);
-        }, {
-            container,
-            target,
-            offset: options?.offset,
-            axis: options?.axis
-        })
-    });
-    const make = (key) => readable(0, (set) => {
-        const release = attachable.subscribe();
-        const unsub = stores[key].subscribe(set);
-        return () => {
-            unsub();
-            release();
-        };
-    });
-    return {
-        scrollX: make('scrollX'),
-        scrollY: make('scrollY'),
-        scrollXProgress: make('scrollXProgress'),
-        scrollYProgress: make('scrollYProgress')
-    };
-};

package/dist/utils/time.d.ts

@@ -1,14 +0,0 @@
-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>;