@humanspeak/svelte-motion 0.4.7 → 0.4.8

package/dist/index.d.ts

@@ -10,8 +10,8 @@ export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition,
 export { useAnimate } from './utils/animate.svelte';
 export type { AnimationScope } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
-export { useCycle } from './utils/cycle';
-export type { Cycle, CycleState } from './utils/cycle';
+export { useCycle } from './utils/cycle.svelte';
+export type { Cycle, CycleState } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
 export { useInView } from './utils/inView';
 export type { UseInViewOptions } from './utils/inView';
@@ -22,7 +22,8 @@ export { useMotionValueEvent } from './utils/motionValueEvent';
 export { useReducedMotion } from './utils/reducedMotion';
 export { useReducedMotionConfig } from './utils/reducedMotionConfig';
 export { useScroll } from './utils/scroll';
-export { useSpring } from './utils/spring';
+export { useSpring } from './utils/spring.svelte';
+export type { SpringMotionValue, UseSpringOptions } from './utils/spring.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';
 export type { UsePresenceState } from './utils/usePresence';
 export { useVelocity } from './utils/velocity';

package/dist/index.js

@@ -11,7 +11,7 @@ export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cub
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export { useAnimate } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
-export { useCycle } from './utils/cycle';
+export { useCycle } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
 export { useInView } from './utils/inView';
 export { useMotionTemplate } from './utils/motionTemplate';
@@ -20,7 +20,7 @@ export { useMotionValueEvent } from './utils/motionValueEvent';
 export { useReducedMotion } from './utils/reducedMotion';
 export { useReducedMotionConfig } from './utils/reducedMotionConfig';
 export { useScroll } from './utils/scroll';
-export { useSpring } from './utils/spring';
+export { useSpring } from './utils/spring.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';
 export { useVelocity } from './utils/velocity';
 /**

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

@@ -0,0 +1,98 @@
+/** Function returned by {@link useCycle} for advancing or jumping the index. */
+export type Cycle = (next?: number) => void;
+/**
+ * State returned by {@link useCycle}: an object with a reactive `.current`
+ * getter and a `cycle` function. Both reads and writes flow through the
+ * same object, so consumers don't need to destructure (which would
+ * snapshot `.current` and lose reactivity under runes).
+ */
+export type CycleState<T> = {
+    readonly current: T;
+    cycle: Cycle;
+};
+/**
+ * Function that returns the current items list, used by the reactive
+ * overload of {@link useCycle}. The function is re-invoked on every read
+ * so changes to the underlying reactive source propagate automatically.
+ */
+export type CycleItemsGetter<T> = () => readonly T[];
+/**
+ * Cycles through a series of values. Mirrors framer-motion's `useCycle`.
+ *
+ * Two call forms:
+ *
+ * - **Varargs** — `useCycle(...items)` — items are captured once and stay
+ *   fixed for the cycle's lifetime. Matches React framer-motion's signature.
+ * - **Reactive getter** — `useCycle(() => items)` — items are read on every
+ *   access, so passing a `$state`/`$derived` source lets the cycle pick up
+ *   list changes without recreating it.
+ *
+ * In both forms:
+ *
+ * - `state.current` is reactive — read it in templates / `$derived` / `$effect`
+ *   and it tracks both index changes and (in the getter form) item changes.
+ * - `state.cycle()` advances to the next item (wrapping at the end).
+ * - `state.cycle(i)` jumps to index `i`. The index is stored as-given;
+ *   `.current` then clamps on read so any out-of-range index — negative,
+ *   overflow, or items shrinking underneath the reactive-getter form —
+ *   resolves to the nearest valid edge (`items[0]` or `items[length - 1]`)
+ *   instead of `undefined`. This is a defensive divergence from React
+ *   framer-motion (which returns `items[i]`, possibly undefined) so the
+ *   reactive form stays safe and `.current` always honors its `T` type.
+ *   If the reactive getter ever returns an empty list, `.current` throws.
+ * - Calls that resolve to the current index are no-ops, matching React
+ *   `useState`'s `Object.is` bail-out.
+ *
+ * Two deliberate divergences from React's `useCycle`:
+ *
+ * 1. Return shape — React's `[value, cycle]` tuple can't survive
+ *    destructuring under Svelte 5 runes (snapshots the value, loses
+ *    reactivity), so we return `{ current, cycle }`.
+ * 2. Out-of-range reads always clamp (see above) instead of returning
+ *    `items[i]` undefined.
+ *
+ * Otherwise 1:1 with React, including same-index no-op bail-out and
+ * the `wrap(0, length, index + 1)` advance semantics.
+ *
+ * Ambiguity: `useCycle(fn)` with a single function value is treated as the
+ * reactive overload, not as a single-item cycle. To cycle through one
+ * function value, use `useCycle(() => [fn])` or just call it directly —
+ * a single-item cycle is a no-op anyway.
+ *
+ * @see https://motion.dev/docs/react-use-cycle
+ *
+ * @example Static varargs
+ * ```svelte
+ * <script lang="ts">
+ *   import { motion, useCycle } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useCycle(0, 50, 100)
+ * </script>
+ *
+ * <motion.div animate={{ x: x.current }} onclick={() => x.cycle()} />
+ * ```
+ *
+ * @example Reactive items
+ * ```svelte
+ * <script lang="ts">
+ *   let { labels }: { labels: string[] } = $props()
+ *   const variant = useCycle(() => labels)
+ * </script>
+ *
+ * <motion.div animate={variant.current} onclick={() => variant.cycle()} />
+ * ```
+ *
+ * @param itemsGetter Function returning the current items list; re-invoked
+ *   on every `.current` read so reactive sources propagate. Use this form
+ *   when items can change between mount and unmount. (Reactive overload.)
+ * @param items One or more values to cycle through. Captured once at call
+ *   time and fixed for the cycle's lifetime. (Varargs overload.)
+ * @returns A `CycleState<T>` with a reactive `.current` getter and a
+ *   `cycle(next?: number)` advance/jump function. `.current` always
+ *   honors its `T` type by clamping out-of-range indexes; it throws
+ *   if a reactive getter empties the items list mid-cycle.
+ *   `.cycle()` throws on non-integer (`NaN`, `1.5`, `Infinity`)
+ *   indexes and returns early as a no-op on empty items.
+ */
+export declare function useCycle<T>(itemsGetter: CycleItemsGetter<T>): CycleState<T>;
+export declare function useCycle<T>(...items: T[]): CycleState<T>;

package/dist/utils/cycle.svelte.js

@@ -0,0 +1,44 @@
+import { wrap } from 'motion';
+export function useCycle(...args) {
+    const getItems = args.length === 1 && typeof args[0] === 'function'
+        ? args[0]
+        : () => args;
+    if (getItems().length === 0) {
+        throw new Error('useCycle requires at least one item');
+    }
+    let index = $state(0);
+    return {
+        get current() {
+            const items = getItems();
+            // Reactive-getter form: if the consumer's source emptied
+            // mid-cycle the public type can no longer be honored. Throw
+            // loudly so the bug surfaces immediately rather than leaking
+            // `undefined` through a `T`-typed read.
+            if (items.length === 0) {
+                throw new Error('useCycle items getter returned an empty list');
+            }
+            // Clamp on read so out-of-range indexes (from `cycle(-5)` or
+            // `cycle(99)`, or items shrinking under us in the getter form)
+            // resolve to the nearest valid edge instead of `undefined`.
+            const safeIndex = index < 0 ? 0 : index >= items.length ? items.length - 1 : index;
+            return items[safeIndex];
+        },
+        cycle: (next) => {
+            const items = getItems();
+            if (items.length === 0)
+                return;
+            // Reject non-finite / non-integer indexes up-front: `NaN` slips
+            // past the read-time clamp (NaN comparisons return false for
+            // both `< 0` and `>= length`) and would silently make `.current`
+            // resolve to `undefined`, breaking the `T` contract. Throw
+            // loudly to surface the consumer bug at write-time.
+            if (typeof next === 'number' && !Number.isInteger(next)) {
+                throw new Error('useCycle index must be a finite integer');
+            }
+            const target = typeof next === 'number' ? next : wrap(0, items.length, index + 1);
+            if (target === index)
+                return;
+            index = target;
+        }
+    };
+}

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.8",
   "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/spring.d.ts

@@ -1,51 +0,0 @@
-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;
-};
-/**
- * Function type for updating the spring's target with animation.
- *
- * @param v New target value to animate towards (number or unit string).
- */
-type SetType = (v: number | string) => void;
-/**
- * Function type for immediately setting the spring's value without animation.
- *
- * @param v New value to set instantly (number or unit string).
- */
-type JumpType = (v: number | string) => void;
-/**
- * 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: SetType;
-    jump: JumpType;
-};
-export {};

package/dist/utils/spring.js

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