@humanspeak/svelte-motion 0.4.6 → 0.4.8

package/README.md

@@ -36,18 +36,18 @@ npm install @humanspeak/svelte-motion
 
 Goal: Framer Motion API parity for Svelte where common React examples can be translated with minimal changes.
 
-| Capability                                                | Status                          |
-| --------------------------------------------------------- | ------------------------------- |
-| `initial` / `animate` / `transition`                      | Supported                       |
-| `variants` (string keys + inheritance)                    | Supported                       |
-| `whileHover` / `whileTap` / `whileFocus` / `whileInView`  | Supported                       |
-| Drag (`drag`, constraints, momentum, controls, callbacks) | Supported                       |
-| `AnimatePresence` (`initial`, `mode`, `onExitComplete`)   | Supported                       |
-| Layout (`layout`, `layout="position"`)                    | Supported (single-element FLIP) |
-| Shared layout (`layoutId`, `LayoutGroup`, `layoutScroll`) | Supported                       |
-| Pan gesture API (`whilePan`, `onPan*`)                    | Not yet supported               |
-| `MotionConfig` parity beyond `transition`                 | Partial                         |
-| `reducedMotion`, `features`, `transformPagePoint`         | Not yet supported               |
+| Capability                                                             | Status                                     |
+| ---------------------------------------------------------------------- | ------------------------------------------ |
+| `initial` / `animate` / `transition`                                   | Supported                                  |
+| `variants` (string keys + inheritance, function-form `custom`)         | Supported                                  |
+| `whileHover` / `whileTap` / `whileFocus` / `whileDrag` / `whileInView` | Supported (inline + variant keys / arrays) |
+| Drag (`drag`, constraints, momentum, controls, callbacks)              | Supported                                  |
+| `AnimatePresence` (`initial`, `mode`, `onExitComplete`)                | Supported                                  |
+| Layout (`layout`, `layout="position"`)                                 | Supported (single-element FLIP)            |
+| Shared layout (`layoutId`, `LayoutGroup`, `layoutScroll`)              | Supported                                  |
+| Pan gesture API (`whilePan`, `onPan*`)                                 | Not yet supported                          |
+| `MotionConfig` parity beyond `transition`                              | Partial                                    |
+| `reducedMotion`, `features`, `transformPagePoint`                      | Not yet supported                          |
 
 ## Supported elements
 

package/dist/html/_MotionContainer.svelte

@@ -48,7 +48,7 @@
     } from '../utils/presence'
     import { getInitialKeyframes } from '../utils/initial'
     import { attachDrag } from '../utils/drag'
-    import { resolveInitial, resolveAnimate, resolveExit } from '../utils/variants'
+    import { resolveInitial, resolveAnimate, resolveExit, resolveWhile } from '../utils/variants'
     import {
         setVariantContext,
         getVariantContext,
@@ -446,6 +446,19 @@
     )
     const resolvedExit = $derived(resolveExit(exitProp, variantsProp, effectiveCustom))
 
+    // Resolve `whileX` props against `variants` so each gesture's attach
+    // helper receives a plain keyframes object regardless of whether the
+    // consumer wrote inline keyframes, a variant key, or an array of
+    // variant keys. Mirrors framer-motion's `whileHover` etc. surface
+    // (#349).
+    const resolvedWhileTap = $derived(resolveWhile(whileTapProp, variantsProp, effectiveCustom))
+    const resolvedWhileHover = $derived(resolveWhile(whileHoverProp, variantsProp, effectiveCustom))
+    const resolvedWhileFocus = $derived(resolveWhile(whileFocusProp, variantsProp, effectiveCustom))
+    const resolvedWhileDrag = $derived(resolveWhile(whileDragProp, variantsProp, effectiveCustom))
+    const resolvedWhileInView = $derived(
+        resolveWhile(whileInViewProp, variantsProp, effectiveCustom)
+    )
+
     // Extract keyframes from resolved initial, handling initial={false}
     const initialKeyframes = $derived(
         filterReducedMotionKeyframes(
@@ -457,7 +470,12 @@
     // Derived attributes to keep both branches in sync (focusability, data flags, style, class)
     const derivedAttrs = $derived<Record<string, unknown>>({
         ...(rest as Record<string, unknown>),
-        ...(whileTapProp &&
+        // Gate on the *resolved* whileTap, not the raw prop. With
+        // variant-label support a truthy-but-unresolved value (unknown
+        // key, empty array) would otherwise add `tabindex=0` for an
+        // element that never actually receives a tap gesture — an
+        // unintended tab stop. (#349 CR feedback)
+        ...(isNotEmpty(resolvedWhileTap) &&
         !isNativelyFocusable(tag, rest as Record<string, unknown>) &&
         ((rest as Record<string, unknown>)?.tabindex ??
             (rest as Record<string, unknown>)?.tabIndex ??
@@ -541,7 +559,7 @@
             directionLock: !!dragDirectionLockProp,
             listener: dragListenerProp !== false,
             controls,
-            whileDrag: whileDragProp as MotionWhileDrag,
+            whileDrag: resolvedWhileDrag as MotionWhileDrag,
             mergedTransition: (mergedTransition ?? {}) as AnimationOptions,
             callbacks: {
                 onStart: onDragStartProp as (e: PointerEvent, info: DragInfo) => void,
@@ -801,18 +819,18 @@
 
     // whileTap handling via motion-dom's press()
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(whileTapProp))) return
+        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileTap))) return
         return attachWhileTap(
             element!,
-            (whileTapProp ?? {}) as Record<string, unknown>,
+            (resolvedWhileTap ?? {}) as Record<string, unknown>,
             (resolvedInitial ?? {}) as Record<string, unknown>,
             (resolvedAnimate ?? {}) as Record<string, unknown>,
             {
                 onTapStart: onTapStartProp,
                 onTap: onTapProp,
                 onTapCancel: onTapCancelProp,
-                hoverDef: isNotEmpty(whileHoverProp ?? {})
-                    ? ((whileHoverProp ?? {}) as Record<string, unknown>)
+                hoverDef: isNotEmpty(resolvedWhileHover ?? {})
+                    ? ((resolvedWhileHover ?? {}) as Record<string, unknown>)
                     : undefined,
                 hoverFallbackTransition: (mergedTransition ?? {}) as AnimationOptions
             }
@@ -821,10 +839,10 @@
 
     // whileHover handling, gated to true-hover devices to avoid sticky states on touch
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(whileHoverProp))) return
+        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileHover))) return
         return attachWhileHover(
             element!,
-            (whileHoverProp ?? {}) as Record<string, unknown>,
+            (resolvedWhileHover ?? {}) as Record<string, unknown>,
             (mergedTransition ?? {}) as AnimationOptions,
             { onStart: onHoverStartProp, onEnd: onHoverEndProp },
             {
@@ -836,10 +854,10 @@
 
     // whileFocus handling for keyboard focus interactions
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(whileFocusProp))) return
+        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileFocus))) return
         return attachWhileFocus(
             element!,
-            (whileFocusProp ?? {}) as Record<string, unknown>,
+            (resolvedWhileFocus ?? {}) as Record<string, unknown>,
             (mergedTransition ?? {}) as AnimationOptions,
             { onStart: onFocusStartProp, onEnd: onFocusEndProp },
             {
@@ -851,10 +869,10 @@
 
     // whileInView handling for viewport intersection
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(whileInViewProp))) return
+        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileInView))) return
         return attachWhileInView(
             element!,
-            (whileInViewProp ?? {}) as Record<string, unknown>,
+            (resolvedWhileInView ?? {}) as Record<string, unknown>,
             (mergedTransition ?? {}) as AnimationOptions,
             {
                 onStart: onInViewStartProp,

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/types.d.ts

@@ -59,7 +59,7 @@ export type Variants = Record<string, Variant>;
  * <motion.div variants={myVariants} initial="hidden" animate="visible" />
  * ```
  */
-export type MotionInitial = DOMKeyframesDefinition | string | false | undefined;
+export type MotionInitial = DOMKeyframesDefinition | string | string[] | false | undefined;
 /**
  * Target animation properties for a motion component.
  *
@@ -74,7 +74,7 @@ export type MotionInitial = DOMKeyframesDefinition | string | false | undefined;
  * <motion.div variants={myVariants} animate="visible" />
  * ```
  */
-export type MotionAnimate = DOMKeyframesDefinition | string | undefined;
+export type MotionAnimate = DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Exit animation properties for a motion component when unmounted.
  *
@@ -91,7 +91,7 @@ export type MotionAnimate = DOMKeyframesDefinition | string | undefined;
  */
 export type MotionExit = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | string | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation transition configuration.
  * @example
@@ -111,52 +111,80 @@ export type MotionExit = (Record<string, unknown> & {
 export type MotionTransition = AnimationOptions | undefined;
 /**
  * Animation properties for tap/click interactions.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys
+ * (later entries override earlier ones on key collisions).
+ *
  * @example
  * ```svelte
  * <motion.button whileTap={{ scale: 0.95 }} />
+ *
+ * <!-- Variant key -->
+ * <motion.button variants={{ pressed: { scale: 0.95 } }} whileTap="pressed" />
+ *
+ * <!-- Array — later wins on conflicts -->
+ * <motion.button whileTap={["pressed", "muted"]} />
  * ```
  */
-export type MotionWhileTap = DOMKeyframesDefinition | undefined;
+export type MotionWhileTap = (Record<string, unknown> & {
+    transition?: AnimationOptions;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation properties for hover interactions.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys.
+ *
  * @example
  * ```svelte
  * <motion.div whileHover={{ scale: 1.05 }} />
+ *
+ * <!-- Variant key -->
+ * <motion.div variants={{ hover: { scale: 1.05 } }} whileHover="hover" />
  * ```
  */
 export type MotionWhileHover = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation properties for focus interactions.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys.
+ *
  * @example
  * ```svelte
  * <motion.button whileFocus={{ scale: 1.05 }} />
+ * <motion.button variants={{ active: { outline: '2px solid blue' } }} whileFocus="active" />
  * ```
  */
 export type MotionWhileFocus = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation properties for drag interactions.
  * When a drag gesture starts, the element animates to this state; when it ends,
  * it animates back to its baseline (from animate/initial), restoring only the changed keys.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys.
  */
 export type MotionWhileDrag = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation properties for in-view interactions.
  * When the element enters the viewport, it animates to this state; when it leaves,
  * it animates back to its baseline (from animate/initial), restoring only the changed keys.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys.
+ *
  * @example
  * ```svelte
  * <motion.div whileInView={{ opacity: 1, y: 0 }} />
+ * <motion.div variants={{ inView: { opacity: 1 } }} whileInView="inView" />
  * ```
  */
 export type MotionWhileInView = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * IntersectionObserver configuration for `whileInView`. Mirrors framer-motion's
  * `viewport` prop. Same shape as `UseInViewOptions` minus `initial` (which is

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/dist/utils/variants.d.ts

@@ -1,4 +1,4 @@
-import type { MotionAnimate, MotionExit, MotionInitial, Variants } from '../types';
+import type { MotionAnimate, MotionExit, MotionInitial, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, Variants } from '../types';
 import type { DOMKeyframesDefinition } from 'motion';
 /**
  * Resolves a variant key to its keyframes definition.
@@ -27,6 +27,33 @@ import type { DOMKeyframesDefinition } from 'motion';
  * ```
  */
 export declare const resolveVariant: (variants: Variants | undefined, key: string | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;
+/**
+ * Resolves a single variant key or an ordered list of keys to merged
+ * keyframes. Matches framer-motion's `VariantLabels = string | string[]`
+ * surface: later keys in the list override earlier ones on key
+ * collisions (`Object.assign` semantics).
+ *
+ * Missing keys are skipped. An empty list, an empty string, or an
+ * undefined argument all resolve to `undefined`.
+ *
+ * @param variants - The variants object containing named animation states.
+ * @param keys - A single variant key or an array of variant keys.
+ * @param custom - Forwarded to function-form variants (per-entry).
+ * @returns Merged keyframes definition, or `undefined` when nothing resolved.
+ *
+ * @example
+ * ```ts
+ * const variants = {
+ *   hover:  { scale: 1.1 },
+ *   active: { scale: 1.2, color: 'red' }
+ * }
+ * resolveVariantList(variants, 'hover')             // { scale: 1.1 }
+ * resolveVariantList(variants, ['hover', 'active']) // { scale: 1.2, color: 'red' }
+ * resolveVariantList(variants, ['hover', 'missing']) // { scale: 1.1 }
+ * resolveVariantList(variants, [])                   // undefined
+ * ```
+ */
+export declare const resolveVariantList: (variants: Variants | undefined, keys: string | string[] | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;
 /**
  * Resolves the initial prop to keyframes, handling variant keys and `initial={false}`.
  *
@@ -52,25 +79,72 @@ export declare const resolveInitial: (initial: MotionInitial, variants: Variants
 /**
  * Resolves the animate prop to keyframes, handling variant keys.
  *
- * When `animate` is a string, looks it up in the variants object (invoking
- * dynamic variants with `custom`). Otherwise returns the keyframes directly.
+ * When `animate` is a string (or array of strings), looks it up in the
+ * variants object (invoking dynamic variants with `custom`). Otherwise
+ * returns the keyframes directly.
  *
- * @param animate - The animate prop value (keyframes, variant key, or undefined).
+ * @param animate - The animate prop value (keyframes, variant key, array
+ *     of variant keys, or undefined).
  * @param variants - The variants object for resolving string keys.
  * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
+ *
+ * @example
+ * ```ts
+ * const variants = { visible: { opacity: 1 }, shifted: { x: 100 } }
+ * resolveAnimate('visible', variants)              // { opacity: 1 }
+ * resolveAnimate(['visible', 'shifted'], variants) // { opacity: 1, x: 100 }
+ * resolveAnimate({ scale: 1.2 }, variants)         // { scale: 1.2 }  (pass-through)
+ * resolveAnimate(undefined, variants)              // undefined
+ * ```
  */
 export declare const resolveAnimate: (animate: MotionAnimate, variants: Variants | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;
 /**
  * Resolves the exit prop to keyframes, handling variant keys.
  *
- * When `exit` is a string, looks it up in the variants object (invoking
- * dynamic variants with `custom`). Otherwise returns the keyframes directly.
- * Used by AnimatePresence for exit animations.
+ * When `exit` is a string (or array of strings), looks it up in the
+ * variants object (invoking dynamic variants with `custom`). Otherwise
+ * returns the keyframes directly. Used by AnimatePresence for exit
+ * animations.
  *
- * @param exit - The exit prop value (keyframes, variant key, or undefined).
+ * @param exit - The exit prop value (keyframes, variant key, array of
+ *     variant keys, or undefined).
  * @param variants - The variants object for resolving string keys.
  * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
+ *
+ * @example
+ * ```ts
+ * const variants = { hidden: { opacity: 0 }, small: { scale: 0.8 } }
+ * resolveExit('hidden', variants)              // { opacity: 0 }
+ * resolveExit(['hidden', 'small'], variants)   // { opacity: 0, scale: 0.8 }
+ * resolveExit({ y: -20 }, variants)            // { y: -20 }
+ * resolveExit(undefined, variants)             // undefined
+ * ```
  */
 export declare const resolveExit: (exit: MotionExit, variants: Variants | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;
+/**
+ * Resolves a `whileX` prop (hover, tap, focus, drag, in-view) to
+ * keyframes. Mirrors `resolveAnimate` — pass-through for inline
+ * keyframes, look up variant keys via `resolveVariantList` (single
+ * string or array of strings, merged left-to-right).
+ *
+ * Used by `_MotionContainer.svelte` to feed the gesture attach helpers
+ * a consistent keyframes object regardless of whether the consumer
+ * wrote inline keyframes or a variant reference.
+ *
+ * @param value - The whileX prop value.
+ * @param variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
+ * @returns Keyframes definition or `undefined` when nothing applies.
+ *
+ * @example
+ * ```ts
+ * const variants = { hover: { scale: 1.1 }, active: { color: 'red' } }
+ * resolveWhile('hover', variants)            // { scale: 1.1 }
+ * resolveWhile(['hover', 'active'], variants) // { scale: 1.1, color: 'red' }
+ * resolveWhile({ scale: 1.2 }, variants)     // { scale: 1.2 }  (pass-through)
+ * resolveWhile(undefined, variants)          // undefined
+ * ```
+ */
+export declare const resolveWhile: (value: MotionWhileTap | MotionWhileHover | MotionWhileFocus | MotionWhileDrag | MotionWhileInView, variants: Variants | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;

package/dist/utils/variants.js

@@ -27,11 +27,69 @@
 export const resolveVariant = (variants, key, custom) => {
     if (!variants || !key)
         return undefined;
+    // Guard against built-in / inherited keys like 'toString' or
+    // 'constructor' — without this, `whileHover="toString"` would
+    // resolve to `Function.prototype.toString` and leak a function into
+    // the merge path.
+    if (!Object.prototype.hasOwnProperty.call(variants, key))
+        return undefined;
     const entry = variants[key];
     if (typeof entry === 'function')
         return entry(custom);
     return entry;
 };
+/**
+ * Resolves a single variant key or an ordered list of keys to merged
+ * keyframes. Matches framer-motion's `VariantLabels = string | string[]`
+ * surface: later keys in the list override earlier ones on key
+ * collisions (`Object.assign` semantics).
+ *
+ * Missing keys are skipped. An empty list, an empty string, or an
+ * undefined argument all resolve to `undefined`.
+ *
+ * @param variants - The variants object containing named animation states.
+ * @param keys - A single variant key or an array of variant keys.
+ * @param custom - Forwarded to function-form variants (per-entry).
+ * @returns Merged keyframes definition, or `undefined` when nothing resolved.
+ *
+ * @example
+ * ```ts
+ * const variants = {
+ *   hover:  { scale: 1.1 },
+ *   active: { scale: 1.2, color: 'red' }
+ * }
+ * resolveVariantList(variants, 'hover')             // { scale: 1.1 }
+ * resolveVariantList(variants, ['hover', 'active']) // { scale: 1.2, color: 'red' }
+ * resolveVariantList(variants, ['hover', 'missing']) // { scale: 1.1 }
+ * resolveVariantList(variants, [])                   // undefined
+ * ```
+ */
+export const resolveVariantList = (variants, keys, custom) => {
+    if (keys === undefined)
+        return undefined;
+    if (typeof keys === 'string')
+        return resolveVariant(variants, keys, custom);
+    if (keys.length === 0)
+        return undefined;
+    let merged;
+    for (const key of keys) {
+        const entry = resolveVariant(variants, key, custom);
+        // Defensive: only merge plain keyframe objects. A function-form
+        // variant could return something else (array, class instance,
+        // string) under a misuse, and spreading those would corrupt the
+        // merged result. Reject arrays explicitly and require the
+        // prototype to be `Object.prototype` (or `null` for objects
+        // created via `Object.create(null)`).
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const proto = Object.getPrototypeOf(entry);
+        if (proto !== Object.prototype && proto !== null)
+            continue;
+        const obj = entry;
+        merged = merged ? { ...merged, ...obj } : { ...obj };
+    }
+    return merged;
+};
 /**
  * Resolves the initial prop to keyframes, handling variant keys and `initial={false}`.
  *
@@ -58,44 +116,97 @@ export const resolveInitial = (initial, variants, custom) => {
         return false;
     if (initial === undefined)
         return undefined;
-    if (typeof initial === 'string')
-        return resolveVariant(variants, initial, custom);
+    if (typeof initial === 'string' || Array.isArray(initial))
+        return resolveVariantList(variants, initial, custom);
     return initial;
 };
 /**
  * Resolves the animate prop to keyframes, handling variant keys.
  *
- * When `animate` is a string, looks it up in the variants object (invoking
- * dynamic variants with `custom`). Otherwise returns the keyframes directly.
+ * When `animate` is a string (or array of strings), looks it up in the
+ * variants object (invoking dynamic variants with `custom`). Otherwise
+ * returns the keyframes directly.
  *
- * @param animate - The animate prop value (keyframes, variant key, or undefined).
+ * @param animate - The animate prop value (keyframes, variant key, array
+ *     of variant keys, or undefined).
  * @param variants - The variants object for resolving string keys.
  * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
+ *
+ * @example
+ * ```ts
+ * const variants = { visible: { opacity: 1 }, shifted: { x: 100 } }
+ * resolveAnimate('visible', variants)              // { opacity: 1 }
+ * resolveAnimate(['visible', 'shifted'], variants) // { opacity: 1, x: 100 }
+ * resolveAnimate({ scale: 1.2 }, variants)         // { scale: 1.2 }  (pass-through)
+ * resolveAnimate(undefined, variants)              // undefined
+ * ```
  */
 export const resolveAnimate = (animate, variants, custom) => {
     if (animate === undefined)
         return undefined;
-    if (typeof animate === 'string')
-        return resolveVariant(variants, animate, custom);
+    if (typeof animate === 'string' || Array.isArray(animate))
+        return resolveVariantList(variants, animate, custom);
     return animate;
 };
 /**
  * Resolves the exit prop to keyframes, handling variant keys.
  *
- * When `exit` is a string, looks it up in the variants object (invoking
- * dynamic variants with `custom`). Otherwise returns the keyframes directly.
- * Used by AnimatePresence for exit animations.
+ * When `exit` is a string (or array of strings), looks it up in the
+ * variants object (invoking dynamic variants with `custom`). Otherwise
+ * returns the keyframes directly. Used by AnimatePresence for exit
+ * animations.
  *
- * @param exit - The exit prop value (keyframes, variant key, or undefined).
+ * @param exit - The exit prop value (keyframes, variant key, array of
+ *     variant keys, or undefined).
  * @param variants - The variants object for resolving string keys.
  * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
+ *
+ * @example
+ * ```ts
+ * const variants = { hidden: { opacity: 0 }, small: { scale: 0.8 } }
+ * resolveExit('hidden', variants)              // { opacity: 0 }
+ * resolveExit(['hidden', 'small'], variants)   // { opacity: 0, scale: 0.8 }
+ * resolveExit({ y: -20 }, variants)            // { y: -20 }
+ * resolveExit(undefined, variants)             // undefined
+ * ```
  */
 export const resolveExit = (exit, variants, custom) => {
     if (exit === undefined)
         return undefined;
-    if (typeof exit === 'string')
-        return resolveVariant(variants, exit, custom);
+    if (typeof exit === 'string' || Array.isArray(exit))
+        return resolveVariantList(variants, exit, custom);
     return exit;
 };
+/**
+ * Resolves a `whileX` prop (hover, tap, focus, drag, in-view) to
+ * keyframes. Mirrors `resolveAnimate` — pass-through for inline
+ * keyframes, look up variant keys via `resolveVariantList` (single
+ * string or array of strings, merged left-to-right).
+ *
+ * Used by `_MotionContainer.svelte` to feed the gesture attach helpers
+ * a consistent keyframes object regardless of whether the consumer
+ * wrote inline keyframes or a variant reference.
+ *
+ * @param value - The whileX prop value.
+ * @param variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
+ * @returns Keyframes definition or `undefined` when nothing applies.
+ *
+ * @example
+ * ```ts
+ * const variants = { hover: { scale: 1.1 }, active: { color: 'red' } }
+ * resolveWhile('hover', variants)            // { scale: 1.1 }
+ * resolveWhile(['hover', 'active'], variants) // { scale: 1.1, color: 'red' }
+ * resolveWhile({ scale: 1.2 }, variants)     // { scale: 1.2 }  (pass-through)
+ * resolveWhile(undefined, variants)          // undefined
+ * ```
+ */
+export const resolveWhile = (value, variants, custom) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string' || Array.isArray(value))
+        return resolveVariantList(variants, value, custom);
+    return value;
+};

package/package.json

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