@humanspeak/svelte-motion 0.3.1 → 0.3.2

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cub
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionOnInViewEnd, MotionOnInViewStart, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, ReducedMotionConfig, Variants } from './types';
 export { useAnimationFrame } from './utils/animationFrame';
+export { useCycle } from './utils/cycle';
+export type { Cycle, CycleState } from './utils/cycle';
 export { createDragControls } from './utils/dragControls';
 export { useMotionTemplate } from './utils/motionTemplate';
 export { useMotionValue } from './utils/motionValue';

package/dist/index.js

@@ -8,6 +8,7 @@ export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cub
 // Re-export utility functions
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export { useAnimationFrame } from './utils/animationFrame';
+export { useCycle } from './utils/cycle';
 export { createDragControls } from './utils/dragControls';
 export { useMotionTemplate } from './utils/motionTemplate';
 export { useMotionValue } from './utils/motionValue';

package/dist/utils/cycle.d.ts

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

@@ -0,0 +1,48 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "A Framer Motion-compatible animation library for Svelte 5 that provides smooth, hardware-accelerated animations. Features include spring physics, custom easing, and fluid transitions. Built on top of the motion library, it offers a simple API for creating complex animations with minimal code. Perfect for interactive UIs, micro-interactions, and engaging user experiences.",
   "keywords": [
     "svelte",