@humanspeak/svelte-motion 0.4.7 → 0.4.9

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

@@ -0,0 +1,83 @@
+import { type FollowValueOptions, type MotionValue, type SpringOptions } from 'motion-dom';
+import { type Readable } from 'svelte/store';
+/**
+ * Spring + follow options for {@link useSpring}.
+ *
+ * Mirrors framer-motion's `useSpring` options 1:1: every `SpringOptions` key
+ * (`stiffness`, `damping`, `mass`, `duration`, `visualDuration`, `bounce`,
+ * `velocity`, `restDelta`, `restSpeed`) plus `skipInitialAnimation` for
+ * scroll-restoration scenarios.
+ *
+ * @see https://motion.dev/docs/react-use-spring
+ */
+export type UseSpringOptions = SpringOptions & Pick<FollowValueOptions, 'skipInitialAnimation'>;
+/**
+ * The augmented `MotionValue` returned by {@link useSpring}.
+ *
+ * It IS a real `MotionValue<T>` (so it passes `isMotionValue`, composes with
+ * `animate()`, `useTransform`, and the rest of motion-dom). On top of that it
+ * adds two affordances:
+ *
+ * - `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.
+ */
+export type SpringMotionValue<T extends number | string> = Omit<MotionValue<T>, 'current'> & {
+    /** Reactive read in Svelte 5 templates / `$derived` / `$effect`. */
+    readonly current: T;
+    /** Svelte readable store compatibility. */
+    subscribe: (run: (value: T) => void) => () => void;
+};
+/**
+ * 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:
+ *
+ * - `.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.
+ *
+ * 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.
+ *
+ * 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`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useSpring } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useSpring(0, { stiffness: 300, damping: 30 })
+ * </script>
+ *
+ * <button onclick={() => x.set(100)}>Animate</button>
+ * <div>{x.current}</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-spring
+ */
+export declare function useSpring(source: number, options?: UseSpringOptions): SpringMotionValue<number>;
+export declare function useSpring(source: string, options?: UseSpringOptions): SpringMotionValue<string>;
+export declare function useSpring(source: MotionValue<number>, options?: UseSpringOptions): SpringMotionValue<number>;
+export declare function useSpring(source: MotionValue<string>, options?: UseSpringOptions): SpringMotionValue<string>;
+export declare function useSpring<T extends number | string>(source: Readable<T>, options?: UseSpringOptions): SpringMotionValue<T>;

package/dist/utils/spring.svelte.js

@@ -0,0 +1,118 @@
+import { attachFollow, isMotionValue, motionValue } from 'motion-dom';
+import { get } from 'svelte/store';
+/**
+ * Detects a Svelte readable store. Excludes motion-dom `MotionValue` instances
+ * (which also expose `subscribe`-shaped APIs in some versions) so the
+ * MotionValue path is preferred.
+ */
+const isSvelteReadable = (value) => {
+    return (!!value &&
+        typeof value === 'object' &&
+        typeof value.subscribe === 'function' &&
+        !isMotionValue(value));
+};
+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 = readInitial(source);
+        const ssrValue = motionValue(initial);
+        ssrValue.set = () => undefined;
+        ssrValue.jump = () => undefined;
+        return augmentForSvelte(ssrValue, () => undefined);
+    }
+    // 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 = get(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 augmentForSvelte(value, dispose);
+}
+/**
+ * Pull the synchronous initial value out of any accepted source form.
+ */
+const readInitial = (source) => {
+    if (typeof source === 'number' || typeof source === 'string')
+        return source;
+    if (isMotionValue(source))
+        return source.get();
+    if (isSvelteReadable(source))
+        return get(source);
+    return 0;
+};
+/**
+ * Layer Svelte-friendly affordances onto a motion-dom MotionValue: a
+ * `$state`-tracked `.current` accessor (routing motion-dom's internal
+ * `this.current = v` writes through `$state` so templates and `$derived` /
+ * `$effect` re-run) and a Svelte readable store `.subscribe(run)` shim.
+ */
+const augmentForSvelte = (value, dispose) => {
+    let current = $state(value.get());
+    Object.defineProperty(value, 'current', {
+        get: () => current,
+        // Same-value writes are no-ops: motion-dom's `updateAndNotify` calls
+        // `setCurrent(v)` before its own change check, so spring frames at
+        // rest still hit this setter; skipping equal writes avoids gratuitous
+        // accessor work even though $state would itself dedupe.
+        set: (v) => {
+            if (v !== current)
+                current = v;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    const originalDestroy = value.destroy.bind(value);
+    let destroyed = false;
+    value.destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        dispose();
+        originalDestroy();
+    };
+    const subscribe = (run) => {
+        run(value.get());
+        return value.on('change', run);
+    };
+    Object.defineProperty(value, 'subscribe', {
+        value: subscribe,
+        writable: false,
+        enumerable: false,
+        configurable: true
+    });
+    return value;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "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",
@@ -95,8 +95,8 @@
   },
   "dependencies": {
     "acorn": "^8.16.0",
-    "motion": "^12.39.0",
-    "motion-dom": "^12.39.0"
+    "motion": "^12.40.0",
+    "motion-dom": "^12.40.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
@@ -115,7 +115,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
     "@types/node": "^25.9.1",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@vitest/coverage-v8": "^4.1.7",
     "eslint": "^10.4.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-import": "2.32.0",
@@ -127,7 +127,7 @@
     "html-void-elements": "^3.0.0",
     "husky": "^9.1.7",
     "jsdom": "^29.1.1",
-    "mprocs": "^0.9.2",
+    "mprocs": "^0.9.3",
     "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-sort-json": "^4.2.0",
@@ -135,7 +135,7 @@
     "prettier-plugin-tailwindcss": "^0.8.0",
     "publint": "^0.3.21",
     "runed": "0.37.1",
-    "svelte": "^5.55.8",
+    "svelte": "^5.55.9",
     "svelte-check": "^4.4.8",
     "svg-tags": "^1.0.0",
     "tailwind-merge": "^3.6.0",
@@ -145,9 +145,9 @@
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.4",
-    "vite": "^8.0.13",
+    "vite": "^8.0.14",
     "vite-tsconfig-paths": "^6.1.1",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.7"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"

package/dist/utils/cycle.d.ts

@@ -1,35 +0,0 @@
-import { type Readable } from 'svelte/store';
-export type Cycle = (next?: number) => void;
-export type CycleState<T> = [Readable<T>, Cycle];
-/**
- * Cycles through a series of values. Mirrors Framer Motion's `useCycle`.
- *
- * Returns a tuple `[value, cycle]`:
- *
- * - `value` is a Svelte readable store of the current item; subscribe with
- *   `$value` in templates.
- * - `cycle()` advances to the next item, wrapping back to index `0` when it
- *   passes the end.
- * - `cycle(i)` jumps to the item at index `i`. The index is taken as-is to
- *   match `framer-motion` &mdash; out-of-range values yield `items[i]`, which
- *   may be `undefined`.
- *
- * Calls that resolve to the current index are no-ops and do not notify
- * subscribers, matching React `useState`'s `Object.is` bail-out semantics.
- *
- * @param items - Items to cycle through. Must include at least one item.
- * @returns A `[Readable<T>, Cycle]` tuple.
- * @see https://motion.dev/docs/react-use-cycle
- *
- * @example
- * ```svelte
- * <script>
- *   import { motion, useCycle } from '@humanspeak/svelte-motion'
- *
- *   const [x, cycleX] = useCycle(0, 50, 100)
- * </script>
- *
- * <motion.div animate={{ x: $x }} onclick={() => cycleX()} />
- * ```
- */
-export declare const useCycle: <T>(...items: T[]) => CycleState<T>;

package/dist/utils/cycle.js

@@ -1,48 +0,0 @@
-import { wrap } from 'motion';
-import { writable } from 'svelte/store';
-/**
- * Cycles through a series of values. Mirrors Framer Motion's `useCycle`.
- *
- * Returns a tuple `[value, cycle]`:
- *
- * - `value` is a Svelte readable store of the current item; subscribe with
- *   `$value` in templates.
- * - `cycle()` advances to the next item, wrapping back to index `0` when it
- *   passes the end.
- * - `cycle(i)` jumps to the item at index `i`. The index is taken as-is to
- *   match `framer-motion` — out-of-range values yield `items[i]`, which
- *   may be `undefined`.
- *
- * Calls that resolve to the current index are no-ops and do not notify
- * subscribers, matching React `useState`'s `Object.is` bail-out semantics.
- *
- * @param items - Items to cycle through. Must include at least one item.
- * @returns A `[Readable<T>, Cycle]` tuple.
- * @see https://motion.dev/docs/react-use-cycle
- *
- * @example
- * ```svelte
- * <script>
- *   import { motion, useCycle } from '@humanspeak/svelte-motion'
- *
- *   const [x, cycleX] = useCycle(0, 50, 100)
- * </script>
- *
- * <motion.div animate={{ x: $x }} onclick={() => cycleX()} />
- * ```
- */
-export const useCycle = (...items) => {
-    if (items.length === 0) {
-        throw new Error('useCycle requires at least one item');
-    }
-    let index = 0;
-    const store = writable(items[0]);
-    const cycle = (next) => {
-        const target = typeof next === 'number' ? next : wrap(0, items.length, index + 1);
-        if (target === index)
-            return;
-        index = target;
-        store.set(items[target]);
-    };
-    return [{ subscribe: store.subscribe }, cycle];
-};

package/dist/utils/inView.d.ts

@@ -1,136 +0,0 @@
-import { type AnimationOptions, type DOMKeyframesDefinition } from 'motion';
-import { type Readable } from 'svelte/store';
-import type { MotionViewport } from '../types.js';
-import { type ElementOrGetter } from './dom.js';
-/**
- * Split a whileInView definition into keyframes and an optional nested transition.
- *
- * @param def While-in-view record that may include a nested `transition`.
- * @returns Object with `keyframes` (no `transition`) and optional `transition`.
- * @example
- * // With transition
- * splitInViewDefinition({ opacity: 1, y: 0, transition: { duration: 0.5 } })
- * // => { keyframes: { opacity: 1, y: 0 }, transition: { duration: 0.5 } }
- *
- * @example
- * // Without transition
- * splitInViewDefinition({ opacity: 1, scale: 1 })
- * // => { keyframes: { opacity: 1, scale: 1 }, transition: undefined }
- */
-export declare const splitInViewDefinition: (def: Record<string, unknown>) => {
-    keyframes: Record<string, unknown>;
-    transition?: AnimationOptions;
-};
-/**
- * Compute the baseline values to restore to when element leaves viewport.
- *
- * Preference order per key: `animate` → `initial` → neutral transform defaults
- * → computed style value if present.
- *
- * @param el Target element.
- * @param opts Source records for baseline computation.
- * @returns Minimal baseline record to restore when element leaves viewport.
- * @example
- * computeInViewBaseline(element, {
- *   initial: { opacity: 0, y: 50 },
- *   animate: { opacity: 1, y: 0 },
- *   whileInView: { opacity: 1, scale: 1.1 }
- * })
- * // => { opacity: 1, scale: 1 } (scale defaults to 1, opacity from animate)
- */
-export declare const computeInViewBaseline: (el: HTMLElement, opts: {
-    initial?: Record<string, unknown>;
-    animate?: Record<string, unknown>;
-    whileInView?: Record<string, unknown>;
-}) => Record<string, unknown>;
-/**
- * Attach whileInView interactions to an element via motion's `inView` primitive.
- *
- * On entry, animates to `whileInView` state (using the nested `transition` if
- * provided). On exit, restores the changed keys to a baseline computed from
- * `initial` / `animate` / neutral transform defaults / inline styles.
- *
- * Delegates to motion's `inView` so the IntersectionObserver implementation
- * is shared with the public `useInView` hook.
- *
- * @param el Target element.
- * @param whileInView While-in-view definition.
- * @param mergedTransition Root/component merged transition.
- * @param callbacks Optional lifecycle callbacks for in-view start/end and animation completion.
- * @param baselineSources Optional sources used to compute baseline.
- * @param viewport Optional IntersectionObserver options. `amount` defaults to `0` (any pixel visible).
- * @returns Cleanup function to stop observing.
- * @example
- * const cleanup = attachWhileInView(
- *   element,
- *   { opacity: 1, y: 0, transition: { duration: 0.5 } },
- *   { duration: 0.3 },
- *   {
- *     onStart: () => console.log('Entered viewport'),
- *     onEnd: () => console.log('Left viewport')
- *   },
- *   { initial: { opacity: 0, y: 50 } },
- *   { once: true, amount: 0.5 }
- * )
- * // Later: cleanup() to stop observing
- */
-export declare const attachWhileInView: (el: HTMLElement, whileInView: Record<string, unknown> | undefined, mergedTransition: AnimationOptions, callbacks?: {
-    onStart?: () => void;
-    onEnd?: () => void;
-    onAnimationComplete?: (definition: DOMKeyframesDefinition | undefined) => void;
-}, baselineSources?: {
-    initial?: Record<string, unknown>;
-    animate?: Record<string, unknown>;
-}, viewport?: MotionViewport) => (() => void);
-/**
- * Options accepted by `useInView`.
- */
-export type UseInViewOptions = {
-    /** Element to use as the IntersectionObserver root. Defaults to the viewport. */
-    root?: ElementOrGetter;
-    /** CSS margin string applied to the root bounding box (e.g. `"100px 0px"`). */
-    margin?: string;
-    /** Fraction (0-1) or `"some"` / `"all"` of the target that must be visible. */
-    amount?: 'some' | 'all' | number;
-    /** When `true`, the store latches to `true` on first entry and never flips back. */
-    once?: boolean;
-    /** Initial value emitted before the first IntersectionObserver callback. */
-    initial?: boolean;
-};
-/**
- * Returns a Svelte readable store that tracks whether `target` is in the
- * viewport. Mirrors Framer Motion's `useInView` so the same options
- * (`root`, `margin`, `amount`, `once`, `initial`) work as in React.
- *
- * `target` (and `options.root`) accept either an `HTMLElement` directly or a
- * getter `() => HTMLElement | undefined`. With Svelte's `bind:this`, the
- * element isn't available until after mount, so element resolution is
- * deferred until the first subscriber arrives; if the element isn't ready,
- * the hook polls on `requestAnimationFrame` until it is.
- *
- * SSR-safe: returns a static `readable(initial)` when `window` or
- * `IntersectionObserver` is unavailable.
- *
- * @param target - Element (or getter) to observe.
- * @param options - Optional `UseInViewOptions` (`root`, `margin`, `amount`,
- *   `once`, `initial`).
- * @returns A `Readable<boolean>` that flips to `true` while `target` is in view.
- * @see https://motion.dev/docs/react-use-in-view
- *
- * @example
- * ```svelte
- * <script>
- *   import { useInView } from '@humanspeak/svelte-motion'
- *
- *   let ref
- *   const inView = useInView(() => ref, { once: true })
- *
- *   $effect(() => {
- *     if ($inView) trackImpression()
- *   })
- * </script>
- *
- * <div bind:this={ref}>{$inView ? 'visible' : 'hidden'}</div>
- * ```
- */
-export declare const useInView: (target: ElementOrGetter, options?: UseInViewOptions) => Readable<boolean>;