@humanspeak/svelte-motion 0.3.3 → 0.3.4

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { animate, delay, hover, inView, press, resize, scroll, stagger, transfor
 export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cubicBezier, easeIn, easeInOut, easeOut } from 'motion';
 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 { 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';

package/dist/index.js

@@ -7,6 +7,7 @@ export { animate, delay, hover, inView, press, resize, scroll, stagger, transfor
 export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cubicBezier, easeIn, easeInOut, easeOut } from 'motion';
 // Re-export utility functions
 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 { createDragControls } from './utils/dragControls';

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

@@ -0,0 +1,66 @@
+import { createScopedAnimate } from 'motion';
+import type { AnimationPlaybackControlsWithThen } from 'motion-dom';
+/**
+ * The scope returned by {@link useAnimate}. Functions as a Svelte 5
+ * attachment — pass it as `{@attach scope}` on the parent element so the
+ * scoped `animate` function can resolve string selectors against it.
+ *
+ * Mirrors framer-motion's `AnimationScope`. `current` is hydrated once the
+ * attachment runs; `animations` tracks every in-flight animation started
+ * through the scoped `animate` so they can be stopped together when the
+ * element detaches.
+ */
+export type AnimationScope<T extends Element = HTMLElement> = ((node: T) => () => void) & {
+    /** The parent element, populated when the attachment fires. `undefined` before mount or after detach. */
+    current: T | undefined;
+    /** Animations currently scoped to this element. */
+    animations: AnimationPlaybackControlsWithThen[];
+};
+/**
+ * Imperative animation API mirroring framer-motion's `useAnimate`. Returns a
+ * tuple `[scope, animate]`:
+ *
+ * - `scope` is a Svelte 5 attachment: spread it on the parent element with
+ *   `{@attach scope}`. Once mounted, `scope.current` is the element and
+ *   `animate('selector', ...)` resolves selectors against it.
+ * - `animate(target, keyframes, transition)` accepts the same overloads as
+ *   motion's standalone `animate` — strings, elements, motion values, and
+ *   sequences.
+ *
+ * When the attached element detaches, every animation started through the
+ * scoped `animate` is stopped and `scope.animations` is cleared.
+ *
+ * `animate` ignores calls before the attachment fires — `scope.current` is
+ * still `undefined`, and motion throws when asked to query selectors against
+ * a missing root. Trigger animations from user events or `$effect` after
+ * mount.
+ *
+ * @template T The parent element type. Defaults to `HTMLElement`.
+ * @returns A `[scope, animate]` tuple.
+ * @see https://motion.dev/docs/react-use-animate
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useAnimate } from '@humanspeak/svelte-motion'
+ *
+ *   const [scope, animate] = useAnimate()
+ *
+ *   const run = () =>
+ *     animate(
+ *       [
+ *         ['li', { opacity: 1, x: 0 }, { delay: stagger(0.1) }],
+ *         ['button', { scale: 1.05 }, { at: '-0.2' }]
+ *       ]
+ *     )
+ * </script>
+ *
+ * <ul {@attach scope}>
+ *   <li>One</li>
+ *   <li>Two</li>
+ *   <li>Three</li>
+ * </ul>
+ * <button onclick={run}>Animate</button>
+ * ```
+ */
+export declare const useAnimate: <T extends Element = HTMLElement>() => [AnimationScope<T>, ReturnType<typeof createScopedAnimate>];

package/dist/utils/animate.svelte.js

@@ -0,0 +1,66 @@
+import { createScopedAnimate } from 'motion';
+/**
+ * Imperative animation API mirroring framer-motion's `useAnimate`. Returns a
+ * tuple `[scope, animate]`:
+ *
+ * - `scope` is a Svelte 5 attachment: spread it on the parent element with
+ *   `{@attach scope}`. Once mounted, `scope.current` is the element and
+ *   `animate('selector', ...)` resolves selectors against it.
+ * - `animate(target, keyframes, transition)` accepts the same overloads as
+ *   motion's standalone `animate` — strings, elements, motion values, and
+ *   sequences.
+ *
+ * When the attached element detaches, every animation started through the
+ * scoped `animate` is stopped and `scope.animations` is cleared.
+ *
+ * `animate` ignores calls before the attachment fires — `scope.current` is
+ * still `undefined`, and motion throws when asked to query selectors against
+ * a missing root. Trigger animations from user events or `$effect` after
+ * mount.
+ *
+ * @template T The parent element type. Defaults to `HTMLElement`.
+ * @returns A `[scope, animate]` tuple.
+ * @see https://motion.dev/docs/react-use-animate
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useAnimate } from '@humanspeak/svelte-motion'
+ *
+ *   const [scope, animate] = useAnimate()
+ *
+ *   const run = () =>
+ *     animate(
+ *       [
+ *         ['li', { opacity: 1, x: 0 }, { delay: stagger(0.1) }],
+ *         ['button', { scale: 1.05 }, { at: '-0.2' }]
+ *       ]
+ *     )
+ * </script>
+ *
+ * <ul {@attach scope}>
+ *   <li>One</li>
+ *   <li>Two</li>
+ *   <li>Three</li>
+ * </ul>
+ * <button onclick={run}>Animate</button>
+ * ```
+ */
+export const useAnimate = () => {
+    const scope = ((node) => {
+        scope.current = node;
+        return () => {
+            for (const animation of scope.animations) {
+                animation.stop();
+            }
+            scope.animations.length = 0;
+            scope.current = undefined;
+        };
+    });
+    scope.current = undefined;
+    scope.animations = [];
+    const animate = createScopedAnimate({
+        scope: scope
+    });
+    return [scope, animate];
+};

package/package.json

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