@humanspeak/svelte-motion 0.3.0 → 0.3.2

package/dist/components/MotionConfig.svelte

@@ -6,15 +6,29 @@
     /**
      * Provide default Motion configuration to descendants.
      *
-     * Wraps content and supplies defaults such as `transition` that are merged
-     * with per-element props. Descendants can retrieve config via context.
+     * Wraps content and supplies defaults such as `transition` and
+     * `reducedMotion` that are merged with per-element props. Descendants can
+     * retrieve config via context.
      *
      * @prop transition Default `AnimationOptions` merged with element props.
+     * @prop reducedMotion Reduced-motion policy: `'user' | 'always' | 'never'`.
+     *   Defaults to `'never'`.
      * @prop children Slotted content receiving this configuration.
      */
-    let { transition, children }: MotionConfigProps & { children?: Snippet } = $props()
+    let { transition, reducedMotion, children }: MotionConfigProps & { children?: Snippet } =
+        $props()
 
-    let motionConfig = $state<MotionConfigProps>({ transition })
+    // Use property getters so descendants always read the parent's current
+    // prop values — including remounted children inside `{#key}` blocks, which
+    // would otherwise see a stale snapshot if we cached the value in $state.
+    const motionConfig: MotionConfigProps = {
+        get transition() {
+            return transition
+        },
+        get reducedMotion() {
+            return reducedMotion
+        }
+    }
     createMotionConfig(motionConfig)
 </script>
 

package/dist/html/_MotionContainer.svelte

@@ -5,6 +5,10 @@
 
 <script lang="ts">
     import { getMotionConfig } from '../components/motionConfig.context'
+    import {
+        filterReducedMotionKeyframes,
+        useReducedMotionConfig
+    } from '../utils/reducedMotionConfig'
     import type {
         MotionProps,
         MotionTransition,
@@ -50,7 +54,7 @@
         setInitialFalseContext,
         getInitialFalseContext
     } from '../components/variantContext.context'
-    import { writable } from 'svelte/store'
+    import { get, writable } from 'svelte/store'
     import {
         transformSVGPathProperties,
         computeNormalizedSVGInitialAttrs,
@@ -115,6 +119,11 @@
     let isLoaded = $state<'mounting' | 'initial' | 'ready' | 'animated'>('mounting')
     let dataPath = $state<number>(-1)
     const motionConfig = $derived(getMotionConfig())
+    const reducedMotionStore = useReducedMotionConfig()
+    // Seed synchronously so the first render filters keyframes correctly —
+    // otherwise transforms could flash before the subscribe effect runs.
+    let reducedMotion = $state(get(reducedMotionStore))
+    $effect(() => reducedMotionStore.subscribe((value) => (reducedMotion = value)))
 
     // Get presence context to check if we're inside AnimatePresence
     const context = getAnimatePresenceContext()
@@ -219,10 +228,14 @@
     // Reactively update registration when element/exit/transition props change
     $effect(() => {
         if (element && context && resolvedExit) {
+            const filteredExit = filterReducedMotionKeyframes(
+                resolvedExit as Record<string, unknown>,
+                reducedMotion
+            )
             context.registerChild(
                 presenceKey,
                 element,
-                resolvedExit,
+                filteredExit,
                 mergedTransition as unknown as MotionTransition
             )
         }
@@ -350,7 +363,12 @@
     const resolvedExit = $derived(resolveExit(exitProp, variantsProp))
 
     // Extract keyframes from resolved initial, handling initial={false}
-    const initialKeyframes = $derived(getInitialKeyframes(resolvedInitial))
+    const initialKeyframes = $derived(
+        filterReducedMotionKeyframes(
+            getInitialKeyframes(resolvedInitial) as Record<string, unknown>,
+            reducedMotion
+        )
+    )
 
     // Derived attributes to keep both branches in sync (focusability, data flags, style, class)
     const derivedAttrs = $derived<Record<string, unknown>>({
@@ -492,6 +510,13 @@
             payload as Record<string, unknown>
         ) as typeof payload
 
+        // Strip transform keys when reduced-motion is active so the element
+        // stays in place while opacity / color etc. still animate.
+        payload = filterReducedMotionKeyframes(
+            payload as Record<string, unknown>,
+            reducedMotion
+        ) as typeof payload
+
         // Ensure dash properties aren't pinned as inline styles
         if (element && (element as HTMLElement).style) {
             ;(element as HTMLElement).style.removeProperty('stroke-dasharray')
@@ -801,7 +826,10 @@
             try {
                 // 1. Run exit animation if defined
                 if (resolvedExit && element && !keyTransitionStopped) {
-                    const exitKeyframes = { ...(resolvedExit as Record<string, unknown>) }
+                    const exitKeyframes = filterReducedMotionKeyframes(
+                        { ...(resolvedExit as Record<string, unknown>) },
+                        reducedMotion
+                    )
                     // Remove transition from keyframes (it's passed separately)
                     delete exitKeyframes.transition
 

package/dist/index.d.ts

@@ -4,14 +4,17 @@ export { motion } from './motion';
 export { animate, delay, hover, inView, press, resize, scroll, stagger, transform } from 'motion';
 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, Variants } from './types';
+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';
 export type { MotionValue } from './utils/motionValue';
 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 { useVelocity } from './utils/velocity';

package/dist/index.js

@@ -8,11 +8,13 @@ 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';
 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 { useVelocity } from './utils/velocity';

package/dist/types.d.ts

@@ -323,9 +323,27 @@ export type MotionProps = {
  *   - delay: Time to wait before starting the animation
  *   - repeat: Number of times to repeat the animation
  */
+/**
+ * Reduced-motion policy for {@link MotionConfigProps.reducedMotion}.
+ *
+ * - `'never'` (default): Animations run as authored, regardless of OS preference.
+ * - `'always'`: Transform animations (x, y, scale, rotate, skew, translate) are
+ *   skipped. Other properties such as `opacity` and `color` still animate.
+ * - `'user'`: Honors the OS-level `prefers-reduced-motion: reduce` setting —
+ *   behaves like `'always'` when the user has opted in, otherwise `'never'`.
+ *
+ * @see https://motion.dev/docs/react-reduced-motion
+ */
+export type ReducedMotionConfig = 'user' | 'always' | 'never';
 export type MotionConfigProps = {
     /** Animation configuration */
     transition?: MotionTransition;
+    /**
+     * Reduced-motion policy applied to descendant motion elements.
+     *
+     * Defaults to `'never'`. See {@link ReducedMotionConfig}.
+     */
+    reducedMotion?: ReducedMotionConfig;
 };
 /**
  * AnimatePresence mode controls how enter and exit animations are coordinated.

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

@@ -0,0 +1,39 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Returns a copy of `keyframes` with transform-related keys removed when
+ * `reduced` is `true`. Returns `keyframes` unchanged otherwise.
+ *
+ * The `transition` key is preserved so per-key transitions still flow through
+ * to the animation engine.
+ */
+export declare function filterReducedMotionKeyframes<T extends Record<string, unknown> | undefined>(keyframes: T, reduced: boolean): T;
+/**
+ * Returns a readable store that reflects the resolved reduced-motion policy
+ * for the current component subtree.
+ *
+ * Resolution combines the nearest `<MotionConfig reducedMotion>` ancestor with
+ * the OS-level `prefers-reduced-motion` setting:
+ *
+ * - `'always'` → always `true`
+ * - `'never'` (or no `<MotionConfig>` ancestor) → always `false`
+ * - `'user'` → mirrors the OS preference, defaulting to `false` in SSR
+ *
+ * Use this from inside motion-aware components to decide whether to skip
+ * transform animations.
+ *
+ * @returns {Readable<boolean>} `true` when descendant motion should be reduced.
+ * @see https://motion.dev/docs/react-reduced-motion
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useReducedMotionConfig } from '@humanspeak/svelte-motion'
+ *   const reduced = useReducedMotionConfig()
+ * </script>
+ *
+ * {#if !$reduced}
+ *   <motion.div animate={{ x: 100 }} />
+ * {/if}
+ * ```
+ */
+export declare const useReducedMotionConfig: () => Readable<boolean>;

package/dist/utils/reducedMotionConfig.js

@@ -0,0 +1,92 @@
+import { getMotionConfig } from '../components/motionConfig.context.js';
+import { useReducedMotion } from './reducedMotion.js';
+import { derived } from 'svelte/store';
+/**
+ * CSS / motion property keys that move or rotate an element via `transform`.
+ * When reduced motion is active these keys are stripped from animate keyframes
+ * so the element stays in place while non-transform properties (opacity, color,
+ * etc.) continue to animate.
+ */
+const TRANSFORM_KEYS = new Set([
+    'x',
+    'y',
+    'z',
+    'translate',
+    'translateX',
+    'translateY',
+    'translateZ',
+    'scale',
+    'scaleX',
+    'scaleY',
+    'scaleZ',
+    'rotate',
+    'rotateX',
+    'rotateY',
+    'rotateZ',
+    'skew',
+    'skewX',
+    'skewY',
+    'transform',
+    'transformPerspective',
+    'perspective'
+]);
+/**
+ * Returns a copy of `keyframes` with transform-related keys removed when
+ * `reduced` is `true`. Returns `keyframes` unchanged otherwise.
+ *
+ * The `transition` key is preserved so per-key transitions still flow through
+ * to the animation engine.
+ */
+export function filterReducedMotionKeyframes(keyframes, reduced) {
+    if (!reduced || !keyframes)
+        return keyframes;
+    const out = {};
+    for (const key of Object.keys(keyframes)) {
+        if (!TRANSFORM_KEYS.has(key))
+            out[key] = keyframes[key];
+    }
+    return out;
+}
+/**
+ * Returns a readable store that reflects the resolved reduced-motion policy
+ * for the current component subtree.
+ *
+ * Resolution combines the nearest `<MotionConfig reducedMotion>` ancestor with
+ * the OS-level `prefers-reduced-motion` setting:
+ *
+ * - `'always'` → always `true`
+ * - `'never'` (or no `<MotionConfig>` ancestor) → always `false`
+ * - `'user'` → mirrors the OS preference, defaulting to `false` in SSR
+ *
+ * Use this from inside motion-aware components to decide whether to skip
+ * transform animations.
+ *
+ * @returns {Readable<boolean>} `true` when descendant motion should be reduced.
+ * @see https://motion.dev/docs/react-reduced-motion
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useReducedMotionConfig } from '@humanspeak/svelte-motion'
+ *   const reduced = useReducedMotionConfig()
+ * </script>
+ *
+ * {#if !$reduced}
+ *   <motion.div animate={{ x: 100 }} />
+ * {/if}
+ * ```
+ */
+export const useReducedMotionConfig = () => {
+    const motionConfig = getMotionConfig();
+    // Read motionConfig?.reducedMotion *inside* the derived so dynamic
+    // `<MotionConfig reducedMotion={...}>` updates surface to subscribers —
+    // motionConfig uses property getters, so the value is always fresh.
+    return derived(useReducedMotion(), ($osReduced) => {
+        const policy = motionConfig?.reducedMotion ?? 'never';
+        if (policy === 'always')
+            return true;
+        if (policy === 'never')
+            return false;
+        return $osReduced;
+    });
+};

package/package.json

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