@humanspeak/svelte-motion 0.4.5 → 0.4.7

package/README.md

@@ -36,18 +36,18 @@ npm install @humanspeak/svelte-motion
 
 Goal: Framer Motion API parity for Svelte where common React examples can be translated with minimal changes.
 
-| Capability                                                | Status                          |
-| --------------------------------------------------------- | ------------------------------- |
-| `initial` / `animate` / `transition`                      | Supported                       |
-| `variants` (string keys + inheritance)                    | Supported                       |
-| `whileHover` / `whileTap` / `whileFocus` / `whileInView`  | Supported                       |
-| Drag (`drag`, constraints, momentum, controls, callbacks) | Supported                       |
-| `AnimatePresence` (`initial`, `mode`, `onExitComplete`)   | Supported                       |
-| Layout (`layout`, `layout="position"`)                    | Supported (single-element FLIP) |
-| Shared layout (`layoutId`)                                | Supported                       |
-| Pan gesture API (`whilePan`, `onPan*`)                    | Not yet supported               |
-| `MotionConfig` parity beyond `transition`                 | Partial                         |
-| `reducedMotion`, `features`, `transformPagePoint`         | Not yet supported               |
+| Capability                                                             | Status                                     |
+| ---------------------------------------------------------------------- | ------------------------------------------ |
+| `initial` / `animate` / `transition`                                   | Supported                                  |
+| `variants` (string keys + inheritance, function-form `custom`)         | Supported                                  |
+| `whileHover` / `whileTap` / `whileFocus` / `whileDrag` / `whileInView` | Supported (inline + variant keys / arrays) |
+| Drag (`drag`, constraints, momentum, controls, callbacks)              | Supported                                  |
+| `AnimatePresence` (`initial`, `mode`, `onExitComplete`)                | Supported                                  |
+| Layout (`layout`, `layout="position"`)                                 | Supported (single-element FLIP)            |
+| Shared layout (`layoutId`, `LayoutGroup`, `layoutScroll`)              | Supported                                  |
+| Pan gesture API (`whilePan`, `onPan*`)                                 | Not yet supported                          |
+| `MotionConfig` parity beyond `transition`                              | Partial                                    |
+| `reducedMotion`, `features`, `transformPagePoint`                      | Not yet supported                          |
 
 ## Supported elements
 
@@ -280,7 +280,6 @@ Validated against current source and test suite (local run):
 
 ## Known gaps vs Framer Motion
 
-- No shared layout API (`layoutId`, `LayoutGroup`).
 - No pan gesture API (`whilePan`, `onPan*`).
 - `whileInView` does not yet expose Framer-style viewport options.
 - `MotionConfig` currently only provides `transition` defaults.

package/dist/components/LayoutGroup.svelte

@@ -0,0 +1,68 @@
+<script lang="ts">
+    import type { Snippet } from 'svelte'
+    import {
+        chainLayoutGroupId,
+        getLayoutGroupContext,
+        setLayoutGroupContext
+    } from './layoutGroup.context'
+
+    /**
+     * Scope `layoutId` shared-layout animations to a subtree.
+     *
+     * Wrap a region in `<LayoutGroup id="…">` so descendants' `layoutId`
+     * snapshots / consumes are prefixed with the group's id. Two groups
+     * containing the same `layoutId` values won't cross-animate — useful
+     * for repeated UI patterns (multiple tab indicators, kanban columns,
+     * sibling carousels) where each instance should animate independently.
+     *
+     * Mirrors framer-motion's `<LayoutGroup>` (`inherit` defaults to true
+     * — descendants chain onto the parent group's id, so nested groups
+     * yield `"parent-child"`).
+     *
+     * @prop id Stable identifier for this group's scope. When omitted,
+     *     the LayoutGroup is a transparent grouping with no own id
+     *     (still useful for `inherit={false}` to break out of an outer
+     *     group's scope, e.g. an embedded widget).
+     * @prop inherit `true` (default) — chain onto the parent group's id.
+     *     `'id'` — same as `true` in this implementation; accepted for
+     *     drop-in compatibility with framer-motion examples. In
+     *     framer-motion, `'id'` inherits the id but breaks the internal
+     *     projection-tree group. We don't have a projection-tree group
+     *     (our snapshot/consume registry doesn't need sibling
+     *     coordination), so `'id'` and `true` behave identically.
+     *     `false` — start a fresh scope, ignoring any outer LayoutGroup.
+     * @prop children Slot rendered inside the group context.
+     *
+     * @example
+     * ```svelte
+     * <LayoutGroup id="tabs-a">
+     *     <Tabs />
+     * </LayoutGroup>
+     * <LayoutGroup id="tabs-b">
+     *     <Tabs /> <!-- same layoutId values, independent animations -->
+     * </LayoutGroup>
+     * ```
+     *
+     * @see https://motion.dev/docs/react-layout-animations#scoped-layout-animations
+     */
+    const {
+        id,
+        inherit = true,
+        children
+    }: {
+        id?: string
+        inherit?: boolean | 'id'
+        children?: Snippet
+    } = $props()
+
+    // setContext is one-shot at component init, so reading `id` and `inherit`
+    // here captures their initial values intentionally — the scope id is
+    // fixed for this subtree's lifetime. The warning would only matter if we
+    // wanted descendants to react to prop changes, which we explicitly don't.
+    // svelte-ignore state_referenced_locally
+    const shouldInheritId = inherit === true || inherit === 'id'
+    const effectiveId = shouldInheritId ? chainLayoutGroupId(getLayoutGroupContext(), id) : id
+    setLayoutGroupContext(effectiveId)
+</script>
+
+{@render children?.()}

package/dist/components/LayoutGroup.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    id?: string;
+    inherit?: boolean | 'id';
+    children?: Snippet;
+};
+declare const LayoutGroup: import("svelte").Component<$$ComponentProps, {}, "">;
+type LayoutGroup = ReturnType<typeof LayoutGroup>;
+export default LayoutGroup;

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

@@ -0,0 +1,37 @@
+/**
+ * Identifier for a `<LayoutGroup>` subtree. Descendants prefix their
+ * `layoutId` lookups with this so two `<LayoutGroup>`s containing the
+ * same `layoutId` values don't cross-animate.
+ *
+ * `undefined` means "no enclosing LayoutGroup" — the descendant uses
+ * `layoutId` verbatim against the global registry, preserving the
+ * existing un-grouped behaviour.
+ */
+export type LayoutGroupContext = string | undefined;
+/**
+ * Publish a LayoutGroup id for descendants. Called by `<LayoutGroup>`
+ * after computing its own (possibly inherited and chained) id.
+ */
+export declare const setLayoutGroupContext: (id: LayoutGroupContext) => void;
+/**
+ * Read the nearest LayoutGroup id, or `undefined` if not inside one.
+ *
+ * `_MotionContainer.svelte` reads this to prefix `layoutId` when
+ * snapshotting and consuming against the registry, so shared-layout
+ * animations stay scoped to the surrounding group.
+ */
+export declare const getLayoutGroupContext: () => LayoutGroupContext;
+/**
+ * Combine a parent group's id with a descendant LayoutGroup's own id
+ * to produce the effective scope id. Mirrors framer-motion's chaining
+ * (`"parent-id"` + `"-"` + `"own-id"`).
+ *
+ * Either side can be `undefined`; the result is the other one, or
+ * `undefined` if both are absent.
+ */
+export declare const chainLayoutGroupId: (parent: LayoutGroupContext, own: string | undefined) => LayoutGroupContext;
+/**
+ * Apply a LayoutGroup scope to a raw `layoutId` for registry lookups.
+ * Returns the un-prefixed id when no group is in scope.
+ */
+export declare const scopeLayoutId: (groupId: LayoutGroupContext, layoutId: string) => string;

package/dist/components/layoutGroup.context.js

@@ -0,0 +1,41 @@
+import { getContext, setContext } from 'svelte';
+const LAYOUT_GROUP_CONTEXT_KEY = Symbol('layout-group');
+/**
+ * Publish a LayoutGroup id for descendants. Called by `<LayoutGroup>`
+ * after computing its own (possibly inherited and chained) id.
+ */
+export const setLayoutGroupContext = (id) => {
+    setContext(LAYOUT_GROUP_CONTEXT_KEY, id);
+};
+/**
+ * Read the nearest LayoutGroup id, or `undefined` if not inside one.
+ *
+ * `_MotionContainer.svelte` reads this to prefix `layoutId` when
+ * snapshotting and consuming against the registry, so shared-layout
+ * animations stay scoped to the surrounding group.
+ */
+export const getLayoutGroupContext = () => {
+    return getContext(LAYOUT_GROUP_CONTEXT_KEY);
+};
+/**
+ * Combine a parent group's id with a descendant LayoutGroup's own id
+ * to produce the effective scope id. Mirrors framer-motion's chaining
+ * (`"parent-id"` + `"-"` + `"own-id"`).
+ *
+ * Either side can be `undefined`; the result is the other one, or
+ * `undefined` if both are absent.
+ */
+export const chainLayoutGroupId = (parent, own) => {
+    if (!parent)
+        return own;
+    if (!own)
+        return parent;
+    return `${parent}-${own}`;
+};
+/**
+ * Apply a LayoutGroup scope to a raw `layoutId` for registry lookups.
+ * Returns the un-prefixed id when no group is in scope.
+ */
+export const scopeLayoutId = (groupId, layoutId) => {
+    return groupId ? `${groupId}::${layoutId}` : layoutId;
+};

package/dist/html/_MotionContainer.svelte

@@ -48,7 +48,7 @@
     } from '../utils/presence'
     import { getInitialKeyframes } from '../utils/initial'
     import { attachDrag } from '../utils/drag'
-    import { resolveInitial, resolveAnimate, resolveExit } from '../utils/variants'
+    import { resolveInitial, resolveAnimate, resolveExit, resolveWhile } from '../utils/variants'
     import {
         setVariantContext,
         getVariantContext,
@@ -69,6 +69,7 @@
         getLayoutScrollContainerRef,
         setLayoutScrollContainer
     } from '../components/layoutScroll.context'
+    import { getLayoutGroupContext, scopeLayoutId } from '../components/layoutGroup.context'
 
     type Props = MotionProps & {
         children?: Snippet
@@ -147,6 +148,15 @@
     // Get layoutId registry (provided by AnimatePresence or a parent LayoutGroup)
     const layoutIdRegistry = getLayoutIdRegistry()
 
+    // Scope layoutId by the surrounding <LayoutGroup>, so identical
+    // layoutId values in two sibling groups don't cross-animate (#311).
+    // Undefined when no group is in scope — descendants behave exactly
+    // as before relative to the global registry.
+    const layoutGroupId = getLayoutGroupContext()
+    const scopedLayoutId = $derived(
+        layoutIdProp ? scopeLayoutId(layoutGroupId, layoutIdProp) : undefined
+    )
+
     // 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
@@ -258,9 +268,9 @@
         // On cleanup (before DOM removal), push last-known rect to registry
         return () => {
             cancelAnimationFrame(rafId)
-            if (layoutIdLastRect && layoutIdProp) {
+            if (layoutIdLastRect && scopedLayoutId) {
                 layoutIdRegistry.snapshot(
-                    layoutIdProp,
+                    scopedLayoutId,
                     layoutIdLastRect,
                     (mergedTransition ?? {}) as AnimationOptions
                 )
@@ -436,6 +446,19 @@
     )
     const resolvedExit = $derived(resolveExit(exitProp, variantsProp, effectiveCustom))
 
+    // Resolve `whileX` props against `variants` so each gesture's attach
+    // helper receives a plain keyframes object regardless of whether the
+    // consumer wrote inline keyframes, a variant key, or an array of
+    // variant keys. Mirrors framer-motion's `whileHover` etc. surface
+    // (#349).
+    const resolvedWhileTap = $derived(resolveWhile(whileTapProp, variantsProp, effectiveCustom))
+    const resolvedWhileHover = $derived(resolveWhile(whileHoverProp, variantsProp, effectiveCustom))
+    const resolvedWhileFocus = $derived(resolveWhile(whileFocusProp, variantsProp, effectiveCustom))
+    const resolvedWhileDrag = $derived(resolveWhile(whileDragProp, variantsProp, effectiveCustom))
+    const resolvedWhileInView = $derived(
+        resolveWhile(whileInViewProp, variantsProp, effectiveCustom)
+    )
+
     // Extract keyframes from resolved initial, handling initial={false}
     const initialKeyframes = $derived(
         filterReducedMotionKeyframes(
@@ -447,7 +470,12 @@
     // Derived attributes to keep both branches in sync (focusability, data flags, style, class)
     const derivedAttrs = $derived<Record<string, unknown>>({
         ...(rest as Record<string, unknown>),
-        ...(whileTapProp &&
+        // Gate on the *resolved* whileTap, not the raw prop. With
+        // variant-label support a truthy-but-unresolved value (unknown
+        // key, empty array) would otherwise add `tabindex=0` for an
+        // element that never actually receives a tap gesture — an
+        // unintended tab stop. (#349 CR feedback)
+        ...(isNotEmpty(resolvedWhileTap) &&
         !isNativelyFocusable(tag, rest as Record<string, unknown>) &&
         ((rest as Record<string, unknown>)?.tabindex ??
             (rest as Record<string, unknown>)?.tabIndex ??
@@ -531,7 +559,7 @@
             directionLock: !!dragDirectionLockProp,
             listener: dragListenerProp !== false,
             controls,
-            whileDrag: whileDragProp as MotionWhileDrag,
+            whileDrag: resolvedWhileDrag as MotionWhileDrag,
             mergedTransition: (mergedTransition ?? {}) as AnimationOptions,
             callbacks: {
                 onStart: onDragStartProp as (e: PointerEvent, info: DragInfo) => void,
@@ -773,9 +801,9 @@
     // Shared layout animation via layoutId.
     // On mount, consume the previous snapshot and FLIP from its position.
     $effect(() => {
-        if (!(element && layoutIdProp && layoutIdRegistry && isLoaded === 'ready')) return
+        if (!(element && scopedLayoutId && layoutIdRegistry && isLoaded === 'ready')) return
 
-        const prev = layoutIdRegistry.consume(layoutIdProp)
+        const prev = layoutIdRegistry.consume(scopedLayoutId)
         if (!prev) return // First appearance, no animation needed
 
         const next = measureRect(element, resolveLayoutScrollAncestors())
@@ -791,18 +819,18 @@
 
     // whileTap handling via motion-dom's press()
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(whileTapProp))) return
+        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileTap))) return
         return attachWhileTap(
             element!,
-            (whileTapProp ?? {}) as Record<string, unknown>,
+            (resolvedWhileTap ?? {}) as Record<string, unknown>,
             (resolvedInitial ?? {}) as Record<string, unknown>,
             (resolvedAnimate ?? {}) as Record<string, unknown>,
             {
                 onTapStart: onTapStartProp,
                 onTap: onTapProp,
                 onTapCancel: onTapCancelProp,
-                hoverDef: isNotEmpty(whileHoverProp ?? {})
-                    ? ((whileHoverProp ?? {}) as Record<string, unknown>)
+                hoverDef: isNotEmpty(resolvedWhileHover ?? {})
+                    ? ((resolvedWhileHover ?? {}) as Record<string, unknown>)
                     : undefined,
                 hoverFallbackTransition: (mergedTransition ?? {}) as AnimationOptions
             }
@@ -811,10 +839,10 @@
 
     // whileHover handling, gated to true-hover devices to avoid sticky states on touch
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(whileHoverProp))) return
+        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileHover))) return
         return attachWhileHover(
             element!,
-            (whileHoverProp ?? {}) as Record<string, unknown>,
+            (resolvedWhileHover ?? {}) as Record<string, unknown>,
             (mergedTransition ?? {}) as AnimationOptions,
             { onStart: onHoverStartProp, onEnd: onHoverEndProp },
             {
@@ -826,10 +854,10 @@
 
     // whileFocus handling for keyboard focus interactions
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(whileFocusProp))) return
+        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileFocus))) return
         return attachWhileFocus(
             element!,
-            (whileFocusProp ?? {}) as Record<string, unknown>,
+            (resolvedWhileFocus ?? {}) as Record<string, unknown>,
             (mergedTransition ?? {}) as AnimationOptions,
             { onStart: onFocusStartProp, onEnd: onFocusEndProp },
             {
@@ -841,10 +869,10 @@
 
     // whileInView handling for viewport intersection
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(whileInViewProp))) return
+        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileInView))) return
         return attachWhileInView(
             element!,
-            (whileInViewProp ?? {}) as Record<string, unknown>,
+            (resolvedWhileInView ?? {}) as Record<string, unknown>,
             (mergedTransition ?? {}) as AnimationOptions,
             {
                 onStart: onInViewStartProp,

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
+import LayoutGroup from './components/LayoutGroup.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
 import PresenceChild from './components/PresenceChild.svelte';
 export { motion } from './motion';
@@ -32,7 +33,7 @@ export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
-export { AnimatePresence, MotionConfig, PresenceChild };
+export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';
 export { default as MotionAddress } from './html/Address.svelte';

package/dist/index.js

@@ -1,4 +1,5 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
+import LayoutGroup from './components/LayoutGroup.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
 import PresenceChild from './components/PresenceChild.svelte';
 export { motion } from './motion';
@@ -29,7 +30,7 @@ export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
-export { AnimatePresence, MotionConfig, PresenceChild };
+export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
 // Named component exports — tree-shakeable alternative to the `motion` object
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';

package/dist/types.d.ts

@@ -59,7 +59,7 @@ export type Variants = Record<string, Variant>;
  * <motion.div variants={myVariants} initial="hidden" animate="visible" />
  * ```
  */
-export type MotionInitial = DOMKeyframesDefinition | string | false | undefined;
+export type MotionInitial = DOMKeyframesDefinition | string | string[] | false | undefined;
 /**
  * Target animation properties for a motion component.
  *
@@ -74,7 +74,7 @@ export type MotionInitial = DOMKeyframesDefinition | string | false | undefined;
  * <motion.div variants={myVariants} animate="visible" />
  * ```
  */
-export type MotionAnimate = DOMKeyframesDefinition | string | undefined;
+export type MotionAnimate = DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Exit animation properties for a motion component when unmounted.
  *
@@ -91,7 +91,7 @@ export type MotionAnimate = DOMKeyframesDefinition | string | undefined;
  */
 export type MotionExit = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | string | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation transition configuration.
  * @example
@@ -111,52 +111,80 @@ export type MotionExit = (Record<string, unknown> & {
 export type MotionTransition = AnimationOptions | undefined;
 /**
  * Animation properties for tap/click interactions.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys
+ * (later entries override earlier ones on key collisions).
+ *
  * @example
  * ```svelte
  * <motion.button whileTap={{ scale: 0.95 }} />
+ *
+ * <!-- Variant key -->
+ * <motion.button variants={{ pressed: { scale: 0.95 } }} whileTap="pressed" />
+ *
+ * <!-- Array — later wins on conflicts -->
+ * <motion.button whileTap={["pressed", "muted"]} />
  * ```
  */
-export type MotionWhileTap = DOMKeyframesDefinition | undefined;
+export type MotionWhileTap = (Record<string, unknown> & {
+    transition?: AnimationOptions;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation properties for hover interactions.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys.
+ *
  * @example
  * ```svelte
  * <motion.div whileHover={{ scale: 1.05 }} />
+ *
+ * <!-- Variant key -->
+ * <motion.div variants={{ hover: { scale: 1.05 } }} whileHover="hover" />
  * ```
  */
 export type MotionWhileHover = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation properties for focus interactions.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys.
+ *
  * @example
  * ```svelte
  * <motion.button whileFocus={{ scale: 1.05 }} />
+ * <motion.button variants={{ active: { outline: '2px solid blue' } }} whileFocus="active" />
  * ```
  */
 export type MotionWhileFocus = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation properties for drag interactions.
  * When a drag gesture starts, the element animates to this state; when it ends,
  * it animates back to its baseline (from animate/initial), restoring only the changed keys.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys.
  */
 export type MotionWhileDrag = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * Animation properties for in-view interactions.
  * When the element enters the viewport, it animates to this state; when it leaves,
  * it animates back to its baseline (from animate/initial), restoring only the changed keys.
+ *
+ * Accepts inline keyframes, a variant key, or an array of variant keys.
+ *
  * @example
  * ```svelte
  * <motion.div whileInView={{ opacity: 1, y: 0 }} />
+ * <motion.div variants={{ inView: { opacity: 1 } }} whileInView="inView" />
  * ```
  */
 export type MotionWhileInView = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | string[] | undefined;
 /**
  * IntersectionObserver configuration for `whileInView`. Mirrors framer-motion's
  * `viewport` prop. Same shape as `UseInViewOptions` minus `initial` (which is

package/dist/utils/variants.d.ts

@@ -1,4 +1,4 @@
-import type { MotionAnimate, MotionExit, MotionInitial, Variants } from '../types';
+import type { MotionAnimate, MotionExit, MotionInitial, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, Variants } from '../types';
 import type { DOMKeyframesDefinition } from 'motion';
 /**
  * Resolves a variant key to its keyframes definition.
@@ -27,6 +27,33 @@ import type { DOMKeyframesDefinition } from 'motion';
  * ```
  */
 export declare const resolveVariant: (variants: Variants | undefined, key: string | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;
+/**
+ * Resolves a single variant key or an ordered list of keys to merged
+ * keyframes. Matches framer-motion's `VariantLabels = string | string[]`
+ * surface: later keys in the list override earlier ones on key
+ * collisions (`Object.assign` semantics).
+ *
+ * Missing keys are skipped. An empty list, an empty string, or an
+ * undefined argument all resolve to `undefined`.
+ *
+ * @param variants - The variants object containing named animation states.
+ * @param keys - A single variant key or an array of variant keys.
+ * @param custom - Forwarded to function-form variants (per-entry).
+ * @returns Merged keyframes definition, or `undefined` when nothing resolved.
+ *
+ * @example
+ * ```ts
+ * const variants = {
+ *   hover:  { scale: 1.1 },
+ *   active: { scale: 1.2, color: 'red' }
+ * }
+ * resolveVariantList(variants, 'hover')             // { scale: 1.1 }
+ * resolveVariantList(variants, ['hover', 'active']) // { scale: 1.2, color: 'red' }
+ * resolveVariantList(variants, ['hover', 'missing']) // { scale: 1.1 }
+ * resolveVariantList(variants, [])                   // undefined
+ * ```
+ */
+export declare const resolveVariantList: (variants: Variants | undefined, keys: string | string[] | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;
 /**
  * Resolves the initial prop to keyframes, handling variant keys and `initial={false}`.
  *
@@ -52,25 +79,72 @@ export declare const resolveInitial: (initial: MotionInitial, variants: Variants
 /**
  * Resolves the animate prop to keyframes, handling variant keys.
  *
- * When `animate` is a string, looks it up in the variants object (invoking
- * dynamic variants with `custom`). Otherwise returns the keyframes directly.
+ * When `animate` is a string (or array of strings), 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 animate - The animate prop value (keyframes, variant key, array
+ *     of variant keys, or undefined).
  * @param variants - The variants object for resolving string keys.
  * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
+ *
+ * @example
+ * ```ts
+ * const variants = { visible: { opacity: 1 }, shifted: { x: 100 } }
+ * resolveAnimate('visible', variants)              // { opacity: 1 }
+ * resolveAnimate(['visible', 'shifted'], variants) // { opacity: 1, x: 100 }
+ * resolveAnimate({ scale: 1.2 }, variants)         // { scale: 1.2 }  (pass-through)
+ * resolveAnimate(undefined, variants)              // 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 (invoking
- * dynamic variants with `custom`). Otherwise returns the keyframes directly.
- * Used by AnimatePresence for exit animations.
+ * When `exit` is a string (or array of strings), 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 exit - The exit prop value (keyframes, variant key, array of
+ *     variant keys, or undefined).
  * @param variants - The variants object for resolving string keys.
  * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
+ *
+ * @example
+ * ```ts
+ * const variants = { hidden: { opacity: 0 }, small: { scale: 0.8 } }
+ * resolveExit('hidden', variants)              // { opacity: 0 }
+ * resolveExit(['hidden', 'small'], variants)   // { opacity: 0, scale: 0.8 }
+ * resolveExit({ y: -20 }, variants)            // { y: -20 }
+ * resolveExit(undefined, variants)             // undefined
+ * ```
  */
 export declare const resolveExit: (exit: MotionExit, variants: Variants | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;
+/**
+ * Resolves a `whileX` prop (hover, tap, focus, drag, in-view) to
+ * keyframes. Mirrors `resolveAnimate` — pass-through for inline
+ * keyframes, look up variant keys via `resolveVariantList` (single
+ * string or array of strings, merged left-to-right).
+ *
+ * Used by `_MotionContainer.svelte` to feed the gesture attach helpers
+ * a consistent keyframes object regardless of whether the consumer
+ * wrote inline keyframes or a variant reference.
+ *
+ * @param value - The whileX prop value.
+ * @param variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
+ * @returns Keyframes definition or `undefined` when nothing applies.
+ *
+ * @example
+ * ```ts
+ * const variants = { hover: { scale: 1.1 }, active: { color: 'red' } }
+ * resolveWhile('hover', variants)            // { scale: 1.1 }
+ * resolveWhile(['hover', 'active'], variants) // { scale: 1.1, color: 'red' }
+ * resolveWhile({ scale: 1.2 }, variants)     // { scale: 1.2 }  (pass-through)
+ * resolveWhile(undefined, variants)          // undefined
+ * ```
+ */
+export declare const resolveWhile: (value: MotionWhileTap | MotionWhileHover | MotionWhileFocus | MotionWhileDrag | MotionWhileInView, variants: Variants | undefined, custom?: unknown) => DOMKeyframesDefinition | undefined;

package/dist/utils/variants.js

@@ -27,11 +27,69 @@
 export const resolveVariant = (variants, key, custom) => {
     if (!variants || !key)
         return undefined;
+    // Guard against built-in / inherited keys like 'toString' or
+    // 'constructor' — without this, `whileHover="toString"` would
+    // resolve to `Function.prototype.toString` and leak a function into
+    // the merge path.
+    if (!Object.prototype.hasOwnProperty.call(variants, key))
+        return undefined;
     const entry = variants[key];
     if (typeof entry === 'function')
         return entry(custom);
     return entry;
 };
+/**
+ * Resolves a single variant key or an ordered list of keys to merged
+ * keyframes. Matches framer-motion's `VariantLabels = string | string[]`
+ * surface: later keys in the list override earlier ones on key
+ * collisions (`Object.assign` semantics).
+ *
+ * Missing keys are skipped. An empty list, an empty string, or an
+ * undefined argument all resolve to `undefined`.
+ *
+ * @param variants - The variants object containing named animation states.
+ * @param keys - A single variant key or an array of variant keys.
+ * @param custom - Forwarded to function-form variants (per-entry).
+ * @returns Merged keyframes definition, or `undefined` when nothing resolved.
+ *
+ * @example
+ * ```ts
+ * const variants = {
+ *   hover:  { scale: 1.1 },
+ *   active: { scale: 1.2, color: 'red' }
+ * }
+ * resolveVariantList(variants, 'hover')             // { scale: 1.1 }
+ * resolveVariantList(variants, ['hover', 'active']) // { scale: 1.2, color: 'red' }
+ * resolveVariantList(variants, ['hover', 'missing']) // { scale: 1.1 }
+ * resolveVariantList(variants, [])                   // undefined
+ * ```
+ */
+export const resolveVariantList = (variants, keys, custom) => {
+    if (keys === undefined)
+        return undefined;
+    if (typeof keys === 'string')
+        return resolveVariant(variants, keys, custom);
+    if (keys.length === 0)
+        return undefined;
+    let merged;
+    for (const key of keys) {
+        const entry = resolveVariant(variants, key, custom);
+        // Defensive: only merge plain keyframe objects. A function-form
+        // variant could return something else (array, class instance,
+        // string) under a misuse, and spreading those would corrupt the
+        // merged result. Reject arrays explicitly and require the
+        // prototype to be `Object.prototype` (or `null` for objects
+        // created via `Object.create(null)`).
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const proto = Object.getPrototypeOf(entry);
+        if (proto !== Object.prototype && proto !== null)
+            continue;
+        const obj = entry;
+        merged = merged ? { ...merged, ...obj } : { ...obj };
+    }
+    return merged;
+};
 /**
  * Resolves the initial prop to keyframes, handling variant keys and `initial={false}`.
  *
@@ -58,44 +116,97 @@ export const resolveInitial = (initial, variants, custom) => {
         return false;
     if (initial === undefined)
         return undefined;
-    if (typeof initial === 'string')
-        return resolveVariant(variants, initial, custom);
+    if (typeof initial === 'string' || Array.isArray(initial))
+        return resolveVariantList(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 (invoking
- * dynamic variants with `custom`). Otherwise returns the keyframes directly.
+ * When `animate` is a string (or array of strings), 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 animate - The animate prop value (keyframes, variant key, array
+ *     of variant keys, or undefined).
  * @param variants - The variants object for resolving string keys.
  * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
+ *
+ * @example
+ * ```ts
+ * const variants = { visible: { opacity: 1 }, shifted: { x: 100 } }
+ * resolveAnimate('visible', variants)              // { opacity: 1 }
+ * resolveAnimate(['visible', 'shifted'], variants) // { opacity: 1, x: 100 }
+ * resolveAnimate({ scale: 1.2 }, variants)         // { scale: 1.2 }  (pass-through)
+ * resolveAnimate(undefined, variants)              // undefined
+ * ```
  */
 export const resolveAnimate = (animate, variants, custom) => {
     if (animate === undefined)
         return undefined;
-    if (typeof animate === 'string')
-        return resolveVariant(variants, animate, custom);
+    if (typeof animate === 'string' || Array.isArray(animate))
+        return resolveVariantList(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 (invoking
- * dynamic variants with `custom`). Otherwise returns the keyframes directly.
- * Used by AnimatePresence for exit animations.
+ * When `exit` is a string (or array of strings), 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 exit - The exit prop value (keyframes, variant key, array of
+ *     variant keys, or undefined).
  * @param variants - The variants object for resolving string keys.
  * @param custom - Forwarded to function-form variants.
  * @returns Keyframes definition or undefined.
+ *
+ * @example
+ * ```ts
+ * const variants = { hidden: { opacity: 0 }, small: { scale: 0.8 } }
+ * resolveExit('hidden', variants)              // { opacity: 0 }
+ * resolveExit(['hidden', 'small'], variants)   // { opacity: 0, scale: 0.8 }
+ * resolveExit({ y: -20 }, variants)            // { y: -20 }
+ * resolveExit(undefined, variants)             // undefined
+ * ```
  */
 export const resolveExit = (exit, variants, custom) => {
     if (exit === undefined)
         return undefined;
-    if (typeof exit === 'string')
-        return resolveVariant(variants, exit, custom);
+    if (typeof exit === 'string' || Array.isArray(exit))
+        return resolveVariantList(variants, exit, custom);
     return exit;
 };
+/**
+ * Resolves a `whileX` prop (hover, tap, focus, drag, in-view) to
+ * keyframes. Mirrors `resolveAnimate` — pass-through for inline
+ * keyframes, look up variant keys via `resolveVariantList` (single
+ * string or array of strings, merged left-to-right).
+ *
+ * Used by `_MotionContainer.svelte` to feed the gesture attach helpers
+ * a consistent keyframes object regardless of whether the consumer
+ * wrote inline keyframes or a variant reference.
+ *
+ * @param value - The whileX prop value.
+ * @param variants - The variants object for resolving string keys.
+ * @param custom - Forwarded to function-form variants.
+ * @returns Keyframes definition or `undefined` when nothing applies.
+ *
+ * @example
+ * ```ts
+ * const variants = { hover: { scale: 1.1 }, active: { color: 'red' } }
+ * resolveWhile('hover', variants)            // { scale: 1.1 }
+ * resolveWhile(['hover', 'active'], variants) // { scale: 1.1, color: 'red' }
+ * resolveWhile({ scale: 1.2 }, variants)     // { scale: 1.2 }  (pass-through)
+ * resolveWhile(undefined, variants)          // undefined
+ * ```
+ */
+export const resolveWhile = (value, variants, custom) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string' || Array.isArray(value))
+        return resolveVariantList(variants, value, custom);
+    return value;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "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",
@@ -114,7 +114,7 @@
     "@tailwindcss/vite": "^4.3.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
-    "@types/node": "^25.9.0",
+    "@types/node": "^25.9.1",
     "@vitest/coverage-v8": "^4.1.6",
     "eslint": "^10.4.0",
     "eslint-config-prettier": "10.1.8",
@@ -135,16 +135,16 @@
     "prettier-plugin-tailwindcss": "^0.8.0",
     "publint": "^0.3.21",
     "runed": "0.37.1",
-    "svelte": "^5.55.7",
+    "svelte": "^5.55.8",
     "svelte-check": "^4.4.8",
     "svg-tags": "^1.0.0",
     "tailwind-merge": "^3.6.0",
     "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.3.0",
     "tailwindcss-animate": "^1.0.7",
-    "tsx": "^4.22.2",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.3",
+    "typescript-eslint": "^8.59.4",
     "vite": "^8.0.13",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.6"