@humanspeak/svelte-motion 0.5.0 → 0.5.1

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export type { AugmentedMotionValue } from './utils/augmentMotionValue.svelte';
 export { useCycle } from './utils/cycle.svelte';
 export type { Cycle, CycleState } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
+export { useFollowValue } from './utils/followValue.svelte';
+export type { FollowMotionValue, UseFollowValueOptions } from './utils/followValue.svelte';
 export { useInView } from './utils/inView.svelte';
 export type { InViewState, UseInViewOptions } from './utils/inView.svelte';
 export { useMotionTemplate } from './utils/motionTemplate.svelte';

package/dist/index.js

@@ -13,6 +13,7 @@ export { useAnimate } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
 export { useCycle } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
+export { useFollowValue } from './utils/followValue.svelte';
 export { useInView } from './utils/inView.svelte';
 export { useMotionTemplate } from './utils/motionTemplate.svelte';
 export { useMotionValue } from './utils/motionValue.svelte';

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

@@ -0,0 +1,84 @@
+import { type FollowValueOptions, type MotionValue } from 'motion-dom';
+import { type Readable } from 'svelte/store';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Options accepted by {@link useFollowValue}. Mirrors framer-motion's
+ * `FollowValueOptions` 1:1 — any `ValueAnimationTransition` shape (spring /
+ * tween / inertia / keyframes) plus `skipInitialAnimation` for
+ * scroll-restoration scenarios.
+ *
+ * The shape is re-exported from motion-dom so consumers don't have to
+ * cross-import.
+ *
+ * @see https://motion.dev/docs/react-use-follow-value
+ */
+export type UseFollowValueOptions = FollowValueOptions;
+/**
+ * The augmented `MotionValue` returned by {@link useFollowValue} (and, since
+ * `useSpring` now delegates here, by `useSpring` too).
+ */
+export type FollowMotionValue<T extends number | string> = AugmentedMotionValue<T>;
+/**
+ * Creates an animated `MotionValue` that, when `.set(v)` is called, animates
+ * toward `v` using **any** transition type — spring, tween, inertia, or
+ * keyframes. Pass another `MotionValue` (or Svelte readable) as the source
+ * and the result follows it: every source emit kicks off a new animation
+ * toward the latest value.
+ *
+ * Mirrors React framer-motion's `useFollowValue` 1:1. `useSpring` in this
+ * library is now a thin wrapper that delegates here with the default
+ * `{ type: 'spring' }`.
+ *
+ * Returned object is a real motion-dom `MotionValue` (composes with
+ * `useTransform`, `useVelocity`, `animate()`, etc.) augmented with a
+ * `$state`-backed `.current` getter and a Svelte readable `.subscribe`
+ * shim.
+ *
+ * Lifecycle: must be called during component initialization. Cleanup is
+ * registered via `$effect`; the follow animation stops, the source bridge
+ * (if any) tears down, and `value.destroy()` runs when the surrounding
+ * `$effect` scope unmounts.
+ *
+ * SSR-safe: returns a static augmented `MotionValue` with no animation on
+ * the server. `.set` and `.jump` become no-ops to avoid drifting away from
+ * the server-rendered snapshot.
+ *
+ * @template T The value type — `number` or `string` (unit strings preserved).
+ * @param source Initial value, a `MotionValue` to follow, or a Svelte readable.
+ * @param options Transition + follow configuration (`type: 'spring' | 'tween' | 'inertia' | 'keyframes'`, plus the corresponding per-type options).
+ * @returns A `MotionValue<T>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useFollowValue, useMotionValue } from '@humanspeak/svelte-motion'
+ *
+ *   const target = useMotionValue(0)
+ *
+ *   // Spring follow (default — same as `useSpring(target)`).
+ *   const spring = useFollowValue(target, { stiffness: 300, damping: 30 })
+ *
+ *   // Tween follow — eased linear interpolation.
+ *   const eased = useFollowValue(target, {
+ *     type: 'tween',
+ *     duration: 0.4,
+ *     ease: 'easeInOut'
+ *   })
+ *
+ *   // Inertia — decays from initial velocity.
+ *   const drifting = useFollowValue(0, { type: 'inertia', velocity: 800, power: 0.6 })
+ * </script>
+ *
+ * <button onclick={() => target.set(target.get() === 0 ? 200 : 0)}>Toggle</button>
+ * <div style="transform: translateX({spring.current}px)">spring</div>
+ * <div style="transform: translateX({eased.current}px)">tween</div>
+ * <div style="transform: translateX({drifting.current}px)">inertia</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-follow-value
+ */
+export declare function useFollowValue(source: number, options?: UseFollowValueOptions): FollowMotionValue<number>;
+export declare function useFollowValue(source: string, options?: UseFollowValueOptions): FollowMotionValue<string>;
+export declare function useFollowValue(source: MotionValue<number>, options?: UseFollowValueOptions): FollowMotionValue<number>;
+export declare function useFollowValue(source: MotionValue<string>, options?: UseFollowValueOptions): FollowMotionValue<string>;
+export declare function useFollowValue<T extends number | string>(source: Readable<T>, options?: UseFollowValueOptions): FollowMotionValue<T>;

package/dist/utils/followValue.svelte.js

@@ -0,0 +1,51 @@
+import { attachFollow, isMotionValue, motionValue } from 'motion-dom';
+import {} from 'svelte/store';
+import { augmentMotionValue, isSvelteReadable, sampleSource } from './augmentMotionValue.svelte.js';
+export function useFollowValue(source, options = {}) {
+    // SSR: return a static MotionValue with no animation. Reads return the
+    // best-effort initial value; .set / .jump become no-ops to avoid drifting
+    // away from the server-rendered snapshot.
+    if (typeof window === 'undefined') {
+        const initial = sampleSource(source);
+        const ssrValue = motionValue(initial);
+        ssrValue.set = () => undefined;
+        ssrValue.jump = () => undefined;
+        return augmentMotionValue(ssrValue);
+    }
+    // Resolve initial + follow source. Svelte readables get bridged into a
+    // motion-dom MotionValue so `attachFollow` can subscribe to their emits.
+    let followSource;
+    let cleanupReadableBridge;
+    let svelteBridge;
+    if (isMotionValue(source)) {
+        followSource = source;
+    }
+    else if (isSvelteReadable(source)) {
+        const initialFromReadable = sampleSource(source);
+        svelteBridge = motionValue(initialFromReadable);
+        cleanupReadableBridge = source.subscribe((v) => {
+            // Svelte readable contract emits synchronously on subscribe. Skip
+            // the initial emit (already seeded above) so attachFollow doesn't
+            // fire an animation on attach.
+            if (svelteBridge.get() === v)
+                return;
+            svelteBridge.set(v);
+        });
+        followSource = svelteBridge;
+    }
+    else {
+        followSource = source;
+    }
+    const initial = isMotionValue(followSource) ? followSource.get() : followSource;
+    const value = motionValue(initial);
+    // Default transition is `spring` — matches React framer-motion's
+    // `useFollowValue` default. Caller's `type` (if set) overrides.
+    const stopFollow = attachFollow(value, followSource, { type: 'spring', ...options });
+    const dispose = () => {
+        stopFollow?.();
+        cleanupReadableBridge?.();
+        svelteBridge?.destroy();
+    };
+    $effect(() => () => value.destroy());
+    return augmentMotionValue(value, dispose);
+}

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

@@ -9,6 +9,10 @@ import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
  * `velocity`, `restDelta`, `restSpeed`) plus `skipInitialAnimation` for
  * scroll-restoration scenarios.
  *
+ * `useSpring` is a thin wrapper over {@link useFollowValue} that hard-codes
+ * `type: 'spring'`. For other transition types (tween, inertia, keyframes)
+ * use `useFollowValue` directly.
+ *
  * @see https://motion.dev/docs/react-use-spring
  */
 export type UseSpringOptions = SpringOptions & Pick<FollowValueOptions, 'skipInitialAnimation'>;
@@ -22,41 +26,36 @@ export type UseSpringOptions = SpringOptions & Pick<FollowValueOptions, 'skipIni
  * - `current` — a Svelte-5 reactive read backed by `$state`. Use in templates
  *   and `$derived` / `$effect` to track the spring value without subscribing.
  * - `subscribe` — Svelte readable store contract. Calls the run function once
- *   synchronously with the current value, then on every change. Lets the
- *   spring be used with `$spring` template syntax, `get(spring)`, and as a
- *   dependency in `useTransform`'s function form.
+ *   synchronously with the current value, then on every change.
  */
 export type SpringMotionValue<T extends number | string> = AugmentedMotionValue<T>;
 /**
  * Creates a spring-animated `MotionValue`.
  *
  * Set a target with `.set(v)` to animate to it using spring physics, or
- * `.jump(v)` to skip the animation. Pass another `MotionValue` (or, for
- * backwards compatibility, a Svelte readable store like the ones from
- * `useScroll` / `useTime`) as `source` and the spring will animate towards
- * whatever that source emits.
- *
- * Returned object is a real motion-dom `MotionValue` — composes with
- * `animate()`, `useTransform`, `useVelocity`, and motion-dom's animation
- * engine. On top, it exposes:
+ * `.jump(v)` to skip the animation. Pass another `MotionValue` (or a Svelte
+ * readable store from `useScroll` / `useTime`) as `source` and the spring
+ * will animate toward whatever that source emits.
  *
- * - `.current` — Svelte-5 reactive read for templates and `$derived` /
- *   `$effect`.
- * - `.subscribe(run)` — Svelte readable store contract so `$spring` template
- *   syntax and `useTransform(() => …, [spring])` keep working during the
- *   Tier 2 migration window.
+ * Returned object is a real motion-dom `MotionValue` augmented with a
+ * `$state`-backed `.current` getter and a Svelte readable `.subscribe` shim.
+ * Composes with `useTransform`, `useVelocity`, `animate()`, and the rest of
+ * the motion-value surface.
  *
- * Lifecycle: must be called during component initialization. Cleanup is
- * registered via `$effect`; the spring stops animating and unsubscribes from
- * its source when the surrounding component / effect tears down. Call
- * `.destroy()` to clean up early.
+ * Lifecycle: must be called during component initialization. The follow
+ * animation, source bridge (if any), and motion value teardown are bound to
+ * the surrounding `$effect` scope.
  *
  * SSR-safe: returns a static `MotionValue` with no animation on the server.
  *
- * @template T
- * @param {number|string|MotionValue<number>|MotionValue<string>|Readable<number|string>} source Initial value or a source to follow.
- * @param {UseSpringOptions} [options] Spring + follow configuration.
- * @returns {SpringMotionValue<T>} A `MotionValue` with `.current` and `.subscribe`.
+ * Implementation: thin wrapper over {@link useFollowValue} that hard-codes
+ * `type: 'spring'`. For tween / inertia / keyframes follows, call
+ * `useFollowValue` directly.
+ *
+ * @template T The value type — `number` or `string` (unit strings preserved).
+ * @param source Initial value, a `MotionValue` to follow, or a Svelte readable.
+ * @param options Spring + follow configuration.
+ * @returns A `MotionValue<T>` with `.current` and `.subscribe`.
  *
  * @example
  * ```svelte
@@ -67,7 +66,7 @@ export type SpringMotionValue<T extends number | string> = AugmentedMotionValue<
  * </script>
  *
  * <button onclick={() => x.set(100)}>Animate</button>
- * <div>{x.current}</div>
+ * <div style="transform: translateX({x.current}px)">{x.current}</div>
  * ```
  *
  * @see https://motion.dev/docs/react-use-spring

package/dist/utils/spring.svelte.js

@@ -1,54 +1,10 @@
-import { attachFollow, isMotionValue, motionValue } from 'motion-dom';
+import {} from 'motion-dom';
 import {} from 'svelte/store';
-import { augmentMotionValue, isSvelteReadable, sampleSource } from './augmentMotionValue.svelte.js';
+import {} from './augmentMotionValue.svelte.js';
+import { useFollowValue } from './followValue.svelte.js';
 export function useSpring(source, options = {}) {
-    // SSR: return a static MotionValue with no animation. Reads return the
-    // best-effort initial value; .set / .jump become no-ops to avoid drifting
-    // away from the server-rendered snapshot.
-    if (typeof window === 'undefined') {
-        const initial = sampleSource(source);
-        const ssrValue = motionValue(initial);
-        ssrValue.set = () => undefined;
-        ssrValue.jump = () => undefined;
-        return augmentMotionValue(ssrValue);
-    }
-    // Resolve initial + follow source.
-    let followSource;
-    let cleanupReadableBridge;
-    let svelteBridge;
-    if (isMotionValue(source)) {
-        followSource = source;
-    }
-    else if (isSvelteReadable(source)) {
-        // Bridge a Svelte readable into a MotionValue so attachFollow can
-        // track it. Synchronous initial sample comes from svelte/store's get().
-        const initialFromReadable = sampleSource(source);
-        svelteBridge = motionValue(initialFromReadable);
-        cleanupReadableBridge = source.subscribe((v) => {
-            // The Svelte readable contract calls the subscriber synchronously
-            // with the current value on subscribe. Skip if it equals the
-            // already-seeded bridge value so attachFollow doesn't fire a
-            // spring on the initial emit. Subsequent emits go through set()
-            // and trigger animation.
-            if (svelteBridge.get() === v)
-                return;
-            svelteBridge.set(v);
-        });
-        followSource = svelteBridge;
-    }
-    else {
-        followSource = source;
-    }
-    const initial = isMotionValue(followSource) ? followSource.get() : followSource;
-    const value = motionValue(initial);
-    const stopFollow = attachFollow(value, followSource, { type: 'spring', ...options });
-    // Side-cleanup for our augmentations. Single-shot guard lives in the
-    // augmented `value.destroy` (the only caller), so no flag here.
-    const dispose = () => {
-        stopFollow?.();
-        cleanupReadableBridge?.();
-        svelteBridge?.destroy();
-    };
-    $effect(() => () => value.destroy());
-    return augmentMotionValue(value, dispose);
+    // Cast through `unknown` because TypeScript can't narrow the multi-form
+    // `source` against `useFollowValue`'s overload set; runtime behavior is
+    // identical — `useFollowValue` dispatches on the same shapes.
+    return useFollowValue(source, { type: 'spring', ...options });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.5.0",
+  "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",