@humanspeak/svelte-motion 0.4.3 → 0.4.5

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

@@ -0,0 +1,36 @@
+/**
+ * Deferred references to the chain of `layoutScroll` ancestors for the
+ * current subtree. Returned as a thunk because element refs are bound
+ * after mount; consumers invoke at measurement time.
+ *
+ * Order is closest-first. Order doesn't matter for the current scroll-
+ * offset sum, but is preserved so future per-container semantics (e.g.
+ * a `scroll.wasRoot` marker like framer-motion) can iterate deterministically.
+ */
+export type LayoutScrollContainerRef = () => Array<HTMLElement | null | undefined>;
+/**
+ * Publish the scroll-container chain for descendant motion components.
+ *
+ * Called on a `motion.*` component with `layoutScroll` enabled during
+ * its init phase. The provided thunk should resolve to `[...ancestorChain,
+ * ownElement]` — descendants get the full chain in one call.
+ *
+ * Mirrors framer-motion's `removeElementScroll`, which walks the path
+ * and sums every `layoutScroll` ancestor's offset.
+ *
+ * @param ref Thunk returning the full ancestor chain (closest first).
+ */
+export declare const setLayoutScrollContainer: (ref: LayoutScrollContainerRef) => void;
+/**
+ * Capture the ancestor chain thunk at component init.
+ *
+ * Important: call this **before** the same component calls
+ * `setLayoutScrollContainer(...)`. Otherwise the lookup returns the
+ * component's own thunk (Svelte `setContext` shadows from the call site
+ * down) and the chain collapses.
+ *
+ * Returns `undefined` when no ancestor has `layoutScroll`.
+ *
+ * @returns Ancestor chain thunk, or `undefined`.
+ */
+export declare const getLayoutScrollContainerRef: () => LayoutScrollContainerRef | undefined;

package/dist/components/layoutScroll.context.js

@@ -0,0 +1,32 @@
+import { getContext, setContext } from 'svelte';
+const LAYOUT_SCROLL_CONTEXT_KEY = Symbol('layout-scroll-container');
+/**
+ * Publish the scroll-container chain for descendant motion components.
+ *
+ * Called on a `motion.*` component with `layoutScroll` enabled during
+ * its init phase. The provided thunk should resolve to `[...ancestorChain,
+ * ownElement]` — descendants get the full chain in one call.
+ *
+ * Mirrors framer-motion's `removeElementScroll`, which walks the path
+ * and sums every `layoutScroll` ancestor's offset.
+ *
+ * @param ref Thunk returning the full ancestor chain (closest first).
+ */
+export const setLayoutScrollContainer = (ref) => {
+    setContext(LAYOUT_SCROLL_CONTEXT_KEY, ref);
+};
+/**
+ * Capture the ancestor chain thunk at component init.
+ *
+ * Important: call this **before** the same component calls
+ * `setLayoutScrollContainer(...)`. Otherwise the lookup returns the
+ * component's own thunk (Svelte `setContext` shadows from the call site
+ * down) and the chain collapses.
+ *
+ * Returns `undefined` when no ancestor has `layoutScroll`.
+ *
+ * @returns Ancestor chain thunk, or `undefined`.
+ */
+export const getLayoutScrollContainerRef = () => {
+    return getContext(LAYOUT_SCROLL_CONTEXT_KEY);
+};

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 {
@@ -63,6 +65,10 @@
         SVG_NAMESPACE
     } from '../utils/svg'
     import { getLayoutIdRegistry } from '../utils/layoutId'
+    import {
+        getLayoutScrollContainerRef,
+        setLayoutScrollContainer
+    } from '../components/layoutScroll.context'
 
     type Props = MotionProps & {
         children?: Snippet
@@ -75,6 +81,7 @@
         tag = 'div',
         key: keyProp,
         variants: variantsProp,
+        custom: customProp,
         initial: initialProp,
         animate: animateProp,
         exit: exitProp,
@@ -115,6 +122,7 @@
         dragControls: dragControlsProp,
         layout: layoutProp,
         layoutId: layoutIdProp,
+        layoutScroll: layoutScrollProp,
         ref: element = $bindable(null),
         ...rest
     }: Props = $props()
@@ -139,6 +147,30 @@
     // Get layoutId registry (provided by AnimatePresence or a parent LayoutGroup)
     const layoutIdRegistry = getLayoutIdRegistry()
 
+    // Capture the ancestor `layoutScroll` chain BEFORE we potentially shadow
+    // the context with ourselves below — this element's own FLIP measurements
+    // must resolve against the *ancestors*' scroll containers, not against
+    // itself.
+    //
+    // We walk the full chain (not just the nearest) so a `layoutScroll`
+    // outside another `layoutScroll` still contributes to descendant
+    // measurements — matches framer-motion's `removeElementScroll` walking
+    // `this.path`.
+    const ancestorScrollContainerRef = getLayoutScrollContainerRef()
+    if (layoutScrollProp) {
+        // Publish [...ancestorChain, ownElement]. The chain is collected
+        // lazily because element refs bind after mount.
+        setLayoutScrollContainer(() => {
+            const inherited = ancestorScrollContainerRef?.() ?? []
+            return element ? [...inherited, element] : inherited
+        })
+    }
+    const resolveLayoutScrollAncestors = (): HTMLElement[] => {
+        const refs = ancestorScrollContainerRef?.() ?? []
+        // Filter out unbound refs (HTMLElement | null | undefined → HTMLElement[]).
+        return refs.filter((el): el is HTMLElement => Boolean(el))
+    }
+
     // Get current presence depth (0 = direct child of AnimatePresence, undefined = not in AnimatePresence)
     const presenceDepth = getPresenceDepth()
 
@@ -210,11 +242,14 @@
     $effect(() => {
         if (!(element && layoutIdProp && layoutIdRegistry)) return
 
-        // Capture rect on every frame while mounted
+        // Capture rect on every frame while mounted. Re-express in the
+        // nearest layoutScroll ancestor's coordinate space so the FLIP-from
+        // rect stored at unmount stays correct even if the scroll container
+        // moved between the snapshot and the next element's mount.
         let rafId: number
         const captureRect = () => {
             if (element) {
-                layoutIdLastRect = element.getBoundingClientRect()
+                layoutIdLastRect = measureRect(element, resolveLayoutScrollAncestors())
             }
             rafId = requestAnimationFrame(captureRect)
         }
@@ -360,6 +395,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 +428,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 +704,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)
@@ -662,17 +733,18 @@
         if (!(element && layoutProp && isLoaded === 'ready')) return
 
         // Initialize last rect on first ready frame
-        lastRect = measureRect(element!)
+        lastRect = measureRect(element!, resolveLayoutScrollAncestors())
         // Hint compositor for smoother FLIP transforms
         setCompositorHints(element!, true)
 
         let rafId: number | null = null
         const runFlip = () => {
+            const scrollContainers = resolveLayoutScrollAncestors()
             if (!lastRect) {
-                lastRect = measureRect(element!)
+                lastRect = measureRect(element!, scrollContainers)
                 return
             }
-            const next = measureRect(element!)
+            const next = measureRect(element!, scrollContainers)
             const transforms = computeFlipTransforms(lastRect, next, layoutProp ?? false)
             runFlipAnimation(element!, transforms, (mergedTransition ?? {}) as AnimationOptions)
             lastRect = next
@@ -706,7 +778,7 @@
         const prev = layoutIdRegistry.consume(layoutIdProp)
         if (!prev) return // First appearance, no animation needed
 
-        const next = measureRect(element)
+        const next = measureRect(element, resolveLayoutScrollAncestors())
         const transforms = computeFlipTransforms(prev.rect, next, true)
 
         setCompositorHints(element, true)
@@ -916,8 +988,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 +1034,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 +1069,9 @@
                 mountedWithInitialFalse = true
                 if (typeof currentAnimateKey === 'string') {
                     lastRanVariantKey = currentAnimateKey
+                    lastRanResolvedJson = resolvedAnimate
+                        ? JSON.stringify(resolvedAnimate)
+                        : undefined
                 }
                 dataPath = 5
                 isLoaded = 'ready'
@@ -1081,6 +1164,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) */
@@ -305,6 +335,22 @@ export type MotionProps = {
     layout?: boolean | 'position';
     /** Shared layout animation identifier. Elements with matching layoutId animate between positions. */
     layoutId?: string;
+    /**
+     * Mark this element as a scroll container so descendant `layout` animations
+     * measure rects in this container's coordinate space. Without it, scrolling
+     * mid-animation makes the FLIP transform fight the scroll and the layout
+     * animation drifts.
+     *
+     * Apply on the same element as `overflow: scroll` / `overflow: auto`.
+     *
+     * @example
+     * ```svelte
+     * <motion.div layoutScroll style="overflow: auto">
+     *   <motion.div layout />
+     * </motion.div>
+     * ```
+     */
+    layoutScroll?: boolean;
     /** Ref to the element */
     ref?: HTMLElement | null;
     /** Enable drag gestures. true for both axes, or lock to 'x'/'y'. */

package/dist/utils/layout.d.ts

@@ -5,10 +5,32 @@ import { type AnimationOptions } from 'motion';
  * Temporarily clears `transform` to avoid skewing measurements, restoring it
  * immediately after reading the rect.
  *
+ * When `scrollContainers` are provided, the returned rect is shifted by the
+ * **sum** of each container's `scrollLeft` / `scrollTop`. FLIP deltas
+ * computed from two such measures stay correct even when the user scrolls
+ * any of the containers between measurements — including a nested
+ * `layoutScroll` inside another `layoutScroll`. Mirrors framer-motion's
+ * `removeElementScroll`, which walks every ancestor in the path.
+ *
+ * Pass an empty array (or omit) for viewport-relative behaviour.
+ *
  * @param el Element to measure.
- * @return DOMRect snapshot of the element.
+ * @param scrollContainers Optional ancestor chain with `layoutScroll` enabled.
+ * @returns DOMRect snapshot of the element.
+ *
+ * @example
+ * ```ts
+ * // No scroll containers — viewport-relative rect.
+ * const rect = measureRect(node)
+ *
+ * // Single ancestor scroll container (one `layoutScroll`).
+ * const rect = measureRect(node, [scrollPanel])
+ *
+ * // Nested `layoutScroll` ancestors — sums offsets from every container.
+ * const rect = measureRect(node, [innerScroll, outerScroll])
+ * ```
  */
-export declare const measureRect: (el: HTMLElement) => DOMRect;
+export declare const measureRect: (el: HTMLElement, scrollContainers?: HTMLElement[]) => DOMRect;
 /**
  * Compute FLIP transform deltas between two rects.
  *

package/dist/utils/layout.js

@@ -5,14 +5,49 @@ import { animate } from 'motion';
  * Temporarily clears `transform` to avoid skewing measurements, restoring it
  * immediately after reading the rect.
  *
+ * When `scrollContainers` are provided, the returned rect is shifted by the
+ * **sum** of each container's `scrollLeft` / `scrollTop`. FLIP deltas
+ * computed from two such measures stay correct even when the user scrolls
+ * any of the containers between measurements — including a nested
+ * `layoutScroll` inside another `layoutScroll`. Mirrors framer-motion's
+ * `removeElementScroll`, which walks every ancestor in the path.
+ *
+ * Pass an empty array (or omit) for viewport-relative behaviour.
+ *
  * @param el Element to measure.
- * @return DOMRect snapshot of the element.
+ * @param scrollContainers Optional ancestor chain with `layoutScroll` enabled.
+ * @returns DOMRect snapshot of the element.
+ *
+ * @example
+ * ```ts
+ * // No scroll containers — viewport-relative rect.
+ * const rect = measureRect(node)
+ *
+ * // Single ancestor scroll container (one `layoutScroll`).
+ * const rect = measureRect(node, [scrollPanel])
+ *
+ * // Nested `layoutScroll` ancestors — sums offsets from every container.
+ * const rect = measureRect(node, [innerScroll, outerScroll])
+ * ```
  */
-export const measureRect = (el) => {
+export const measureRect = (el, scrollContainers) => {
     const prev = el.style.transform;
     try {
         el.style.transform = 'none';
-        return el.getBoundingClientRect();
+        const rect = el.getBoundingClientRect();
+        if (!scrollContainers || scrollContainers.length === 0)
+            return rect;
+        // Re-express the rect in the *combined* scroll-container coordinate
+        // space so a subsequent scroll on any of them doesn't show up as
+        // movement. DOMRect's left/top are read-only, so allocate a fresh
+        // one with the summed offsets applied.
+        let offsetLeft = 0;
+        let offsetTop = 0;
+        for (const container of scrollContainers) {
+            offsetLeft += container.scrollLeft;
+            offsetTop += container.scrollTop;
+        }
+        return new DOMRect(rect.left + offsetLeft, rect.top + offsetTop, rect.width, rect.height);
     }
     finally {
         el.style.transform = prev;

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.5",
   "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",