@humanspeak/svelte-motion 0.4.3 → 0.4.4

package/README.md

@@ -214,6 +214,29 @@ Supported drag props:
 
 - String variant keys are resolved from `variants`.
 - Variant state inherits through context.
+- A variant entry can be a `(custom) => keyframes` factory. The `custom` prop is forwarded — useful for staggered lists where each child needs its own offset or delay. Children without `custom` inherit the nearest motion ancestor's value.
+
+```svelte
+<script lang="ts">
+    import { motion, type Variants } from '@humanspeak/svelte-motion'
+
+    const variants: Variants = {
+        hidden: { opacity: 0, x: -100 },
+        visible: (i) => ({
+            opacity: 1,
+            x: 0,
+            transition: { delay: (i as number) * 0.1 }
+        })
+    }
+    const items = ['Alpha', 'Beta', 'Gamma', 'Delta']
+</script>
+
+{#each items as item, i}
+    <motion.li custom={i} {variants} initial="hidden" animate="visible">
+        {item}
+    </motion.li>
+{/each}
+```
 
 ## Layout animation
 

package/dist/components/variantContext.context.d.ts

@@ -25,3 +25,23 @@ export declare const setInitialFalseContext: (value: boolean) => void;
  * @returns `true` if a parent set `initial={false}`, otherwise `false`.
  */
 export declare const getInitialFalseContext: () => boolean;
+/**
+ * Provide a writable store carrying the current motion component's
+ * `custom` value so descendant motion components without their own
+ * `custom` prop can inherit it — and re-resolve their variants when the
+ * parent's `custom` changes.
+ *
+ * Mirrors framer-motion's variant-tree custom propagation. A store
+ * (rather than a snapshot) lets descendants react to changes the parent
+ * makes after mount.
+ *
+ * @param store Writable store holding the current component's effective `custom`.
+ */
+export declare const setCustomContext: (store: Writable<unknown>) => void;
+/**
+ * Read the nearest ancestor's `custom` store (if any).
+ *
+ * @returns The ancestor's writable store, or `undefined` when no motion
+ *     ancestor has set one.
+ */
+export declare const getCustomContext: () => Writable<unknown> | undefined;

package/dist/components/variantContext.context.js

@@ -1,6 +1,7 @@
 import { getContext, setContext } from 'svelte';
 const VARIANT_CONTEXT_KEY = Symbol('variant-context');
 const INITIAL_FALSE_CONTEXT_KEY = Symbol('initial-false-context');
+const CUSTOM_CONTEXT_KEY = Symbol('custom-context');
 /**
  * Provide a writable store for the current variant key so children can
  * react to changes over time (true inheritance like Framer Motion).
@@ -35,3 +36,27 @@ export const setInitialFalseContext = (value) => {
 export const getInitialFalseContext = () => {
     return getContext(INITIAL_FALSE_CONTEXT_KEY) ?? false;
 };
+/**
+ * Provide a writable store carrying the current motion component's
+ * `custom` value so descendant motion components without their own
+ * `custom` prop can inherit it — and re-resolve their variants when the
+ * parent's `custom` changes.
+ *
+ * Mirrors framer-motion's variant-tree custom propagation. A store
+ * (rather than a snapshot) lets descendants react to changes the parent
+ * makes after mount.
+ *
+ * @param store Writable store holding the current component's effective `custom`.
+ */
+export const setCustomContext = (store) => {
+    setContext(CUSTOM_CONTEXT_KEY, store);
+};
+/**
+ * Read the nearest ancestor's `custom` store (if any).
+ *
+ * @returns The ancestor's writable store, or `undefined` when no motion
+ *     ancestor has set one.
+ */
+export const getCustomContext = () => {
+    return getContext(CUSTOM_CONTEXT_KEY);
+};

package/dist/html/_MotionContainer.svelte

@@ -53,7 +53,9 @@
         setVariantContext,
         getVariantContext,
         setInitialFalseContext,
-        getInitialFalseContext
+        getInitialFalseContext,
+        setCustomContext,
+        getCustomContext
     } from '../components/variantContext.context'
     import { get, writable } from 'svelte/store'
     import {
@@ -75,6 +77,7 @@
         tag = 'div',
         key: keyProp,
         variants: variantsProp,
+        custom: customProp,
         initial: initialProp,
         animate: animateProp,
         exit: exitProp,
@@ -360,6 +363,32 @@
     // Provide context immediately during initialization so children can inherit
     setVariantContext(localVariantStore)
 
+    // Custom-value inheritance. Children with no `custom` prop adopt the
+    // nearest motion ancestor's value. Reactive via a writable store so a
+    // parent updating `custom` re-fires descendants' variant resolution.
+    const parentCustomStore = getCustomContext()
+    let inheritedCustom: unknown = undefined
+    if (parentCustomStore) {
+        parentCustomStore.subscribe((v) => (inheritedCustom = v))()
+    }
+    const initialCustomValue = customProp !== undefined ? customProp : inheritedCustom
+    const localCustomStore = writable<unknown>(initialCustomValue)
+    setCustomContext(localCustomStore)
+
+    let parentInheritedCustom = $state<unknown>(inheritedCustom)
+    $effect(() => {
+        if (!parentCustomStore) {
+            parentInheritedCustom = undefined
+            return
+        }
+        const unsubscribe = parentCustomStore.subscribe((v) => (parentInheritedCustom = v))
+        return () => unsubscribe()
+    })
+    const effectiveCustom = $derived(customProp !== undefined ? customProp : parentInheritedCustom)
+    $effect(() => {
+        localCustomStore.set(effectiveCustom)
+    })
+
     $effect(() => {
         if (!variantsProp) return localVariantStore.set(undefined)
         if (typeof animateProp === 'string') return localVariantStore.set(animateProp)
@@ -367,9 +396,13 @@
         localVariantStore.set(undefined)
     })
 
-    const resolvedInitial = $derived(resolveInitial(effectiveInitialProp, variantsProp))
-    const resolvedAnimate = $derived(resolveAnimate(effectiveAnimate, variantsProp))
-    const resolvedExit = $derived(resolveExit(exitProp, variantsProp))
+    const resolvedInitial = $derived(
+        resolveInitial(effectiveInitialProp, variantsProp, effectiveCustom)
+    )
+    const resolvedAnimate = $derived(
+        resolveAnimate(effectiveAnimate, variantsProp, effectiveCustom)
+    )
+    const resolvedExit = $derived(resolveExit(exitProp, variantsProp, effectiveCustom))
 
     // Extract keyframes from resolved initial, handling initial={false}
     const initialKeyframes = $derived(
@@ -639,6 +672,12 @@
 
     // Track the last variant key we ran to avoid re-running on mount
     let lastRanVariantKey = $state<string | undefined>(undefined)
+    // Companion to `lastRanVariantKey`: the JSON-serialized resolved
+    // keyframes for that variant. Lets us detect when a function-form
+    // variant produces new keyframes (because `custom` changed) while
+    // the variant key stayed the same — otherwise the animate effect
+    // would short-circuit and the element would never re-animate.
+    let lastRanResolvedJson = $state<string | undefined>(undefined)
     let mountedWithInitialFalse = $state(false)
     // Track if the initial->animate transition has already been triggered by main effect
     let initialAnimationTriggered = $state(false)
@@ -916,8 +955,14 @@
             return
         }
         if (typeof animateProp === 'string') {
-            if (lastRanVariantKey !== animateProp) {
+            // Compare BOTH the variant key and the resolved keyframes JSON.
+            // For static variants the JSON is constant per key; for
+            // function-form variants the JSON changes when `custom`
+            // changes, which we must treat as a new animation target.
+            const resolvedJson = resolvedAnimate ? JSON.stringify(resolvedAnimate) : undefined
+            if (lastRanVariantKey !== animateProp || lastRanResolvedJson !== resolvedJson) {
                 lastRanVariantKey = animateProp
+                lastRanResolvedJson = resolvedJson
                 runAnimation()
             }
         } else if (animateProp) {
@@ -956,8 +1001,10 @@
             mountedWithInitialFalse = false
         }
         if (typeof currentAnimateKey === 'string') {
-            if (lastRanVariantKey !== currentAnimateKey) {
+            const resolvedJson = resolvedAnimate ? JSON.stringify(resolvedAnimate) : undefined
+            if (lastRanVariantKey !== currentAnimateKey || lastRanResolvedJson !== resolvedJson) {
                 lastRanVariantKey = currentAnimateKey
+                lastRanResolvedJson = resolvedJson
                 runAnimation()
             }
         } else {
@@ -989,6 +1036,9 @@
                 mountedWithInitialFalse = true
                 if (typeof currentAnimateKey === 'string') {
                     lastRanVariantKey = currentAnimateKey
+                    lastRanResolvedJson = resolvedAnimate
+                        ? JSON.stringify(resolvedAnimate)
+                        : undefined
                 }
                 dataPath = 5
                 isLoaded = 'ready'
@@ -1081,6 +1131,9 @@
                     snapshot = transformSVGPathProperties(element!, snapshot)
                     animate(element!, snapshot as DOMKeyframesDefinition, { duration: 0 })
                     lastRanVariantKey = currentAnimateKey
+                    lastRanResolvedJson = resolvedAnimate
+                        ? JSON.stringify(resolvedAnimate)
+                        : undefined
                 } else {
                     runAnimation()
                 }

package/dist/types.d.ts

@@ -1,8 +1,32 @@
 import type { AnimationOptions, DOMKeyframesDefinition } from 'motion';
 import type { Snippet } from 'svelte';
+/**
+ * A variant value: either a static keyframes object, or a factory function
+ * that receives the consumer-provided `custom` value and returns keyframes.
+ *
+ * Dynamic (function-form) variants let a single variants object emit
+ * per-instance keyframes — common for staggered lists where each child
+ * needs its own offset or delay.
+ *
+ * @example
+ * ```svelte
+ * <motion.div
+ *   custom={index}
+ *   variants={{
+ *     visible: (i) => ({ opacity: 1, x: i * 50 }),
+ *     hidden:  { opacity: 0 }
+ *   }}
+ *   animate="visible"
+ * />
+ * ```
+ */
+export type Variant = DOMKeyframesDefinition | ((custom: unknown) => DOMKeyframesDefinition) | undefined;
 /**
  * Variants define named animation states that can be referenced by string keys.
  *
+ * Each entry can be a static keyframes object or a `(custom) => keyframes`
+ * factory function (see {@link Variant}).
+ *
  * @example
  * ```svelte
  * <script>
@@ -15,7 +39,7 @@ import type { Snippet } from 'svelte';
  * <motion.div variants={variants} animate="open" />
  * ```
  */
-export type Variants = Record<string, DOMKeyframesDefinition | undefined>;
+export type Variants = Record<string, Variant>;
 /**
  * Initial animation properties for a motion component.
  *
@@ -245,6 +269,12 @@ export type MotionProps = {
     key?: string;
     /** Variants define named animation states */
     variants?: Variants;
+    /**
+     * Value passed into function-form variants. Children without their own
+     * `custom` prop inherit this from the nearest motion ancestor — matching
+     * framer-motion's variant-tree custom propagation.
+     */
+    custom?: unknown;
     /** Initial state of the animation (object or variant key) */
     initial?: MotionInitial;
     /** Target state of the animation (object or variant key) */

package/dist/utils/variants.d.ts

@@ -3,80 +3,74 @@ import type { DOMKeyframesDefinition } from 'motion';
 /**
  * Resolves a variant key to its keyframes definition.
  *
- * Looks up a variant name in the variants object and returns the corresponding
- * keyframes. Returns `undefined` if the variants object or key is not provided.
+ * Looks up `key` in `variants`. When the entry is a function (dynamic
+ * variant), it's invoked with `custom` to produce keyframes — matching
+ * framer-motion's per-instance variant pattern.
  *
  * @param variants - The variants object containing named animation states.
  * @param key - The variant key to look up.
- * @returns The keyframes definition for the variant, or undefined if not found.
+ * @param custom - Value forwarded to function-form variants. Pass-through
+ *     `undefined` when no `custom` is in scope; the dynamic variant itself
+ *     decides how to handle the absent input.
+ * @returns The keyframes definition for the variant, or `undefined` if the
+ *     key is missing.
  *
  * @example
- * ```typescript
+ * ```ts
  * const variants = {
- *   visible: { opacity: 1 },
- *   hidden: { opacity: 0 }
+ *   visible: (i: number) => ({ x: i * 50 }),
+ *   hidden:  { opacity: 0 }
  * }
- * resolveVariant(variants, 'visible')  // { opacity: 1 }
- * resolveVariant(variants, 'foo')      // undefined
- * resolveVariant(undefined, 'visible') // undefined
+ * resolveVariant(variants, 'visible', 3)  // { x: 150 }
+ * resolveVariant(variants, 'hidden')      // { opacity: 0 }
+ * resolveVariant(undefined, 'visible')    // undefined
  * ```
  */
-export declare const resolveVariant: (variants: Variants | undefined, key: string | undefined) => DOMKeyframesDefinition | undefined;
+export declare const resolveVariant: (variants: Variants | undefined, key: string | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;
 /**
  * Resolves the initial prop to keyframes, handling variant keys and `initial={false}`.
  *
- * When `initial` is a string, looks it up in the variants object. When `initial={false}`,
- * returns `false` to skip initial animation. Otherwise returns the keyframes directly.
+ * When `initial` is a string, looks it up in the variants object (invoking
+ * dynamic variants with `custom`). When `initial={false}`, returns `false` to
+ * skip the initial animation. Otherwise returns the keyframes directly.
  *
  * @param initial - The initial prop value (keyframes, variant key, false, or undefined).
  * @param variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition, `false` to skip animation, or undefined.
  *
  * @example
- * ```typescript
- * const variants = { hidden: { opacity: 0 } }
- * resolveInitial('hidden', variants)     // { opacity: 0 }
- * resolveInitial({ x: 0 }, variants)     // { x: 0 }
- * resolveInitial(false, variants)        // false
- * resolveInitial(undefined, variants)    // undefined
+ * ```ts
+ * const variants = { hidden: (i: number) => ({ x: -i * 100 }) }
+ * resolveInitial('hidden', variants, 2)      // { x: -200 }
+ * resolveInitial({ x: 0 }, variants)         // { x: 0 }
+ * resolveInitial(false, variants)            // false
+ * resolveInitial(undefined, variants)        // undefined
  * ```
  */
-export declare const resolveInitial: (initial: MotionInitial, variants: Variants | undefined) => DOMKeyframesDefinition | false | undefined;
+export declare const resolveInitial: (initial: MotionInitial, variants: Variants | undefined, custom?: unknown) => DOMKeyframesDefinition | false | undefined;
 /**
  * Resolves the animate prop to keyframes, handling variant keys.
  *
- * When `animate` is a string, looks it up in the variants object.
- * Otherwise returns the keyframes directly.
+ * When `animate` is a string, 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 variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
- *
- * @example
- * ```typescript
- * const variants = { visible: { opacity: 1 } }
- * resolveAnimate('visible', variants)       // { opacity: 1 }
- * resolveAnimate({ scale: 1.2 }, variants)  // { scale: 1.2 }
- * resolveAnimate(undefined, variants)       // undefined
- * ```
  */
-export declare const resolveAnimate: (animate: MotionAnimate, variants: Variants | undefined) => DOMKeyframesDefinition | 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.
- * Otherwise returns the keyframes directly. Used by AnimatePresence for exit animations.
+ * 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.
  *
  * @param exit - The exit prop value (keyframes, variant key, or undefined).
  * @param variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
- *
- * @example
- * ```typescript
- * const variants = { hidden: { opacity: 0 } }
- * resolveExit('hidden', variants)          // { opacity: 0 }
- * resolveExit({ y: -100 }, variants)       // { y: -100 }
- * resolveExit(undefined, variants)         // undefined
- * ```
  */
-export declare const resolveExit: (exit: MotionExit, variants: Variants | undefined) => DOMKeyframesDefinition | undefined;
+export declare const resolveExit: (exit: MotionExit, variants: Variants | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;

package/dist/utils/variants.js

@@ -1,104 +1,101 @@
 /**
  * Resolves a variant key to its keyframes definition.
  *
- * Looks up a variant name in the variants object and returns the corresponding
- * keyframes. Returns `undefined` if the variants object or key is not provided.
+ * Looks up `key` in `variants`. When the entry is a function (dynamic
+ * variant), it's invoked with `custom` to produce keyframes — matching
+ * framer-motion's per-instance variant pattern.
  *
  * @param variants - The variants object containing named animation states.
  * @param key - The variant key to look up.
- * @returns The keyframes definition for the variant, or undefined if not found.
+ * @param custom - Value forwarded to function-form variants. Pass-through
+ *     `undefined` when no `custom` is in scope; the dynamic variant itself
+ *     decides how to handle the absent input.
+ * @returns The keyframes definition for the variant, or `undefined` if the
+ *     key is missing.
  *
  * @example
- * ```typescript
+ * ```ts
  * const variants = {
- *   visible: { opacity: 1 },
- *   hidden: { opacity: 0 }
+ *   visible: (i: number) => ({ x: i * 50 }),
+ *   hidden:  { opacity: 0 }
  * }
- * resolveVariant(variants, 'visible')  // { opacity: 1 }
- * resolveVariant(variants, 'foo')      // undefined
- * resolveVariant(undefined, 'visible') // undefined
+ * resolveVariant(variants, 'visible', 3)  // { x: 150 }
+ * resolveVariant(variants, 'hidden')      // { opacity: 0 }
+ * resolveVariant(undefined, 'visible')    // undefined
  * ```
  */
-export const resolveVariant = (variants, key) => {
+export const resolveVariant = (variants, key, custom) => {
     if (!variants || !key)
         return undefined;
-    return variants[key];
+    const entry = variants[key];
+    if (typeof entry === 'function')
+        return entry(custom);
+    return entry;
 };
 /**
  * Resolves the initial prop to keyframes, handling variant keys and `initial={false}`.
  *
- * When `initial` is a string, looks it up in the variants object. When `initial={false}`,
- * returns `false` to skip initial animation. Otherwise returns the keyframes directly.
+ * When `initial` is a string, looks it up in the variants object (invoking
+ * dynamic variants with `custom`). When `initial={false}`, returns `false` to
+ * skip the initial animation. Otherwise returns the keyframes directly.
  *
  * @param initial - The initial prop value (keyframes, variant key, false, or undefined).
  * @param variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition, `false` to skip animation, or undefined.
  *
  * @example
- * ```typescript
- * const variants = { hidden: { opacity: 0 } }
- * resolveInitial('hidden', variants)     // { opacity: 0 }
- * resolveInitial({ x: 0 }, variants)     // { x: 0 }
- * resolveInitial(false, variants)        // false
- * resolveInitial(undefined, variants)    // undefined
+ * ```ts
+ * const variants = { hidden: (i: number) => ({ x: -i * 100 }) }
+ * resolveInitial('hidden', variants, 2)      // { x: -200 }
+ * resolveInitial({ x: 0 }, variants)         // { x: 0 }
+ * resolveInitial(false, variants)            // false
+ * resolveInitial(undefined, variants)        // undefined
  * ```
  */
-export const resolveInitial = (initial, variants) => {
+export const resolveInitial = (initial, variants, custom) => {
     if (initial === false)
         return false;
     if (initial === undefined)
         return undefined;
     if (typeof initial === 'string')
-        return resolveVariant(variants, initial);
+        return resolveVariant(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.
- * Otherwise returns the keyframes directly.
+ * When `animate` is a string, 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 variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
- *
- * @example
- * ```typescript
- * const variants = { visible: { opacity: 1 } }
- * resolveAnimate('visible', variants)       // { opacity: 1 }
- * resolveAnimate({ scale: 1.2 }, variants)  // { scale: 1.2 }
- * resolveAnimate(undefined, variants)       // undefined
- * ```
  */
-export const resolveAnimate = (animate, variants) => {
+export const resolveAnimate = (animate, variants, custom) => {
     if (animate === undefined)
         return undefined;
     if (typeof animate === 'string')
-        return resolveVariant(variants, animate);
+        return resolveVariant(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.
- * Otherwise returns the keyframes directly. Used by AnimatePresence for exit animations.
+ * 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.
  *
  * @param exit - The exit prop value (keyframes, variant key, or undefined).
  * @param variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
- *
- * @example
- * ```typescript
- * const variants = { hidden: { opacity: 0 } }
- * resolveExit('hidden', variants)          // { opacity: 0 }
- * resolveExit({ y: -100 }, variants)       // { y: -100 }
- * resolveExit(undefined, variants)         // undefined
- * ```
  */
-export const resolveExit = (exit, variants) => {
+export const resolveExit = (exit, variants, custom) => {
     if (exit === undefined)
         return undefined;
     if (typeof exit === 'string')
-        return resolveVariant(variants, exit);
+        return resolveVariant(variants, exit, custom);
     return exit;
 };

package/package.json

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