@humanspeak/svelte-motion 0.1.16 → 0.1.17

package/dist/components/AnimatePresence.svelte

@@ -1,6 +1,10 @@
 <script lang="ts">
     import type { Snippet } from 'svelte'
-    import { createAnimatePresenceContext, setAnimatePresenceContext } from '../utils/presence'
+    import {
+        createAnimatePresenceContext,
+        setAnimatePresenceContext,
+        setPresenceDepth
+    } from '../utils/presence'
     import { pwLog } from '../utils/log'
 
     /**
@@ -27,6 +31,10 @@
     pwLog('[AnimatePresence] mounting', { initial, hasOnExitComplete: !!onExitComplete })
     const context = createAnimatePresenceContext({ initial, onExitComplete })
     setAnimatePresenceContext(context)
+
+    // Initialize presence depth to 0 for direct children
+    // Only direct children (depth 0) require explicit key props, matching Framer Motion behavior
+    setPresenceDepth(0)
 </script>
 
 <div class="animate-presence-container">
@@ -35,6 +43,6 @@
 
 <style>
     .animate-presence-container {
-        position: relative;
+        display: contents;
     }
 </style>

package/dist/html/_MotionContainer.svelte

@@ -36,7 +36,12 @@
     import type { SvelteHTMLElements } from 'svelte/elements'
     import { mergeInlineStyles } from '../utils/style'
     import { isNativelyFocusable } from '../utils/a11y'
-    import { usePresence, getAnimatePresenceContext } from '../utils/presence'
+    import {
+        usePresence,
+        getAnimatePresenceContext,
+        getPresenceDepth,
+        setPresenceDepth
+    } from '../utils/presence'
     import { getInitialKeyframes } from '../utils/initial'
     import { attachDrag } from '../utils/drag'
     import { resolveInitial, resolveAnimate, resolveExit } from '../utils/variants'
@@ -47,7 +52,12 @@
         getInitialFalseContext
     } from '../components/variantContext.context'
     import { writable } from 'svelte/store'
-    import { transformSVGPathProperties, computeNormalizedSVGInitialAttrs } from '../utils/svg'
+    import {
+        transformSVGPathProperties,
+        computeNormalizedSVGInitialAttrs,
+        isSVGTag,
+        SVG_NAMESPACE
+    } from '../utils/svg'
 
     type Props = MotionProps & {
         children?: Snippet
@@ -108,18 +118,33 @@
     // Get presence context to check if we're inside AnimatePresence
     const context = getAnimatePresenceContext()
 
-    // Validate key prop when inside AnimatePresence
-    if (context && !keyProp) {
+    // Get current presence depth (0 = direct child of AnimatePresence, undefined = not in AnimatePresence)
+    const presenceDepth = getPresenceDepth()
+
+    // Validate key prop only for direct children of AnimatePresence (depth 0)
+    // This matches Framer Motion behavior where only immediate children need keys
+    if (context && presenceDepth === 0 && !keyProp) {
         throw new Error(
-            'motion elements inside AnimatePresence must have a `key` prop. ' +
+            'motion elements that are direct children of AnimatePresence must have a `key` prop. ' +
                 'Example: <motion.div key="unique-id" />'
         )
     }
 
+    // Increment depth for descendants so nested motion elements don't require keys
+    if (presenceDepth !== undefined) {
+        setPresenceDepth(presenceDepth + 1)
+    }
+
     // Use the provided key for presence tracking
     // When not inside AnimatePresence, use a stable identifier based on component instance
     const presenceKey = keyProp ?? `motion-${++keyCounter}`
 
+    // Track previous key for key-change detection (simulates React's key-based remounting)
+    // Using $state for idiomatic Svelte 5 reactivity
+    let keyTrackerPrev = $state(keyProp)
+    let keyTrackerIsTransitioning = $state(false)
+    let keyTransitionStopped = $state(false)
+
     // Compute merged transition without mutating props to avoid effect write loops
     const mergedTransition = $derived<AnimationOptions>(
         mergeTransitions(
@@ -556,6 +581,92 @@
         )
     })
 
+    // Handle key prop changes inside AnimatePresence (simulates React's key-based remounting)
+    // When key changes, run exit → initial → animate sequence on the same element
+    $effect(() => {
+        // Access keyProp to create reactive dependency
+        const currentKey = keyProp
+
+        // Only handle key changes when:
+        // 1. We're inside AnimatePresence (context exists)
+        // 2. Element is ready (not during initial mount)
+        // 3. Key actually changed (not undefined → value on mount)
+        // 4. Not already transitioning
+        if (
+            !context ||
+            !element ||
+            isLoaded !== 'ready' ||
+            keyTrackerIsTransitioning ||
+            currentKey === keyTrackerPrev ||
+            keyTrackerPrev === undefined
+        ) {
+            // Update prev for next comparison
+            if (currentKey !== keyTrackerPrev) {
+                keyTrackerPrev = currentKey
+            }
+            return
+        }
+
+        pwLog('[motion] key changed, running exit→initial→animate', {
+            prevKey: keyTrackerPrev,
+            newKey: currentKey
+        })
+
+        // Mark as transitioning to prevent re-entry
+        keyTrackerIsTransitioning = true
+        keyTrackerPrev = currentKey
+
+        // Run the key transition sequence
+        const runKeyTransition = async () => {
+            try {
+                // 1. Run exit animation if defined
+                if (resolvedExit && element && !keyTransitionStopped) {
+                    const exitKeyframes = { ...(resolvedExit as Record<string, unknown>) }
+                    // Remove transition from keyframes (it's passed separately)
+                    delete exitKeyframes.transition
+
+                    pwLog('[motion] key transition: running exit', { exitKeyframes })
+                    await animate(
+                        element,
+                        exitKeyframes as DOMKeyframesDefinition,
+                        mergedTransition
+                    ).finished
+                }
+
+                // Check if component was unmounted during exit animation
+                if (keyTransitionStopped || !element) return
+
+                // 2. Snap to initial state
+                if (initialKeyframes && element) {
+                    const transformedInitial = transformSVGPathProperties(
+                        element,
+                        initialKeyframes as Record<string, unknown>
+                    )
+                    pwLog('[motion] key transition: snapping to initial', { transformedInitial })
+                    animate(element, transformedInitial as DOMKeyframesDefinition, { duration: 0 })
+                }
+
+                // Check again before running enter animation
+                if (keyTransitionStopped || !element) return
+
+                // 3. Run enter animation
+                pwLog('[motion] key transition: running enter animation')
+                runAnimation()
+            } finally {
+                if (!keyTransitionStopped) {
+                    keyTrackerIsTransitioning = false
+                }
+            }
+        }
+
+        runKeyTransition()
+
+        // Cleanup on unmount
+        return () => {
+            keyTransitionStopped = true
+        }
+    })
+
     // Re-run animate when animateProp changes while ready
     $effect(() => {
         if (!(element && isLoaded === 'ready')) return
@@ -765,7 +876,15 @@
 </script>
 
 {#if isVoidTag}
-    <svelte:element this={tag} bind:this={element} {...derivedAttrs} />
+    {#if isSVGTag(String(tag))}
+        <svelte:element this={tag} bind:this={element} xmlns={SVG_NAMESPACE} {...derivedAttrs} />
+    {:else}
+        <svelte:element this={tag} bind:this={element} {...derivedAttrs} />
+    {/if}
+{:else if isSVGTag(String(tag))}
+    <svelte:element this={tag} bind:this={element} xmlns={SVG_NAMESPACE} {...derivedAttrs}>
+        {@render children?.()}
+    </svelte:element>
 {:else}
     <svelte:element this={tag} bind:this={element} {...derivedAttrs}>
         {@render children?.()}

package/dist/index.d.ts

@@ -7,7 +7,11 @@ export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition,
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
 export { useSpring } from './utils/spring';
+/**
+ * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
+ */
 export { stringifyStyleObject } from './utils/styleObject';
+export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
 export { AnimatePresence, MotionConfig };

package/dist/index.js

@@ -8,7 +8,11 @@ export { animate, hover } from 'motion';
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
 export { useSpring } from './utils/spring';
+/**
+ * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
+ */
 export { stringifyStyleObject } from './utils/styleObject';
+export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
 export { AnimatePresence, MotionConfig };

package/dist/utils/presence.d.ts

@@ -58,6 +58,45 @@ export declare function getAnimatePresenceContext(): AnimatePresenceContext | un
  * Note: Trivial wrapper - ignored for coverage.
  */
 export declare function setAnimatePresenceContext(context: AnimatePresenceContext): void;
+/**
+ * Get the current presence depth from Svelte component context.
+ *
+ * Returns undefined if not inside an AnimatePresence, or the depth level
+ * where 0 means direct child of AnimatePresence.
+ *
+ * @returns The current depth level (0 for direct children), or undefined if outside AnimatePresence.
+ * @example
+ * ```ts
+ * const depth = getPresenceDepth()
+ * if (depth === 0) {
+ *   // Direct child of AnimatePresence - key prop required
+ * }
+ * ```
+ *
+ * Note: Trivial wrapper - ignored for coverage.
+ */
+export declare const getPresenceDepth: () => number | undefined;
+/**
+ * Set the presence depth in Svelte component context.
+ *
+ * AnimatePresence sets this to 0, and each motion element increments it
+ * for its descendants so only direct children (depth 0) require keys.
+ *
+ * @param depth - The nesting depth to set (0 for direct children of AnimatePresence).
+ * @returns void
+ * @example
+ * ```ts
+ * // In AnimatePresence component
+ * setPresenceDepth(0)
+ *
+ * // In nested motion element
+ * const currentDepth = getPresenceDepth() ?? 0
+ * setPresenceDepth(currentDepth + 1)
+ * ```
+ *
+ * Note: Trivial wrapper - ignored for coverage.
+ */
+export declare const setPresenceDepth: (depth: number) => void;
 /**
  * Hook used by motion elements to participate in presence.
  * Registers the element and ensures its exit animation runs on teardown.

package/dist/utils/presence.js

@@ -8,6 +8,13 @@ import { getContext, onDestroy, setContext } from 'svelte';
  * Used with Svelte's context API to provide/register presence management.
  */
 const ANIMATE_PRESENCE_CONTEXT = Symbol('animate-presence-context');
+/**
+ * Context key for tracking nesting depth within AnimatePresence.
+ *
+ * Used to enforce key requirements only on direct children (depth 0),
+ * matching Framer Motion behavior where only immediate children need keys.
+ */
+const PRESENCE_DEPTH_CONTEXT = Symbol('presence-depth-context');
 /**
  * Reset any CSS transforms on the element's inline style.
  *
@@ -331,6 +338,49 @@ export function getAnimatePresenceContext() {
 export function setAnimatePresenceContext(context) {
     setContext(ANIMATE_PRESENCE_CONTEXT, context);
 }
+/**
+ * Get the current presence depth from Svelte component context.
+ *
+ * Returns undefined if not inside an AnimatePresence, or the depth level
+ * where 0 means direct child of AnimatePresence.
+ *
+ * @returns The current depth level (0 for direct children), or undefined if outside AnimatePresence.
+ * @example
+ * ```ts
+ * const depth = getPresenceDepth()
+ * if (depth === 0) {
+ *   // Direct child of AnimatePresence - key prop required
+ * }
+ * ```
+ *
+ * Note: Trivial wrapper - ignored for coverage.
+ */
+/* c8 ignore next */
+export const getPresenceDepth = () => getContext(PRESENCE_DEPTH_CONTEXT);
+/**
+ * Set the presence depth in Svelte component context.
+ *
+ * AnimatePresence sets this to 0, and each motion element increments it
+ * for its descendants so only direct children (depth 0) require keys.
+ *
+ * @param depth - The nesting depth to set (0 for direct children of AnimatePresence).
+ * @returns void
+ * @example
+ * ```ts
+ * // In AnimatePresence component
+ * setPresenceDepth(0)
+ *
+ * // In nested motion element
+ * const currentDepth = getPresenceDepth() ?? 0
+ * setPresenceDepth(currentDepth + 1)
+ * ```
+ *
+ * Note: Trivial wrapper - ignored for coverage.
+ */
+/* c8 ignore next */
+export const setPresenceDepth = (depth) => {
+    setContext(PRESENCE_DEPTH_CONTEXT, depth);
+};
 /**
  * Hook used by motion elements to participate in presence.
  * Registers the element and ensures its exit animation runs on teardown.

package/dist/utils/styleObject.d.ts

@@ -1 +1,20 @@
-export declare function stringifyStyleObject(obj: Record<string, string | number>): string;
+/**
+ * Converts a style object to a CSS style string.
+ *
+ * @deprecated Use `styleString` from `@humanspeak/svelte-motion` instead for reactive styles.
+ * This function is non-reactive and will not update when values change.
+ *
+ * @param obj - Style object with camelCase keys and string/number values
+ * @returns CSS style string with kebab-case properties and appropriate units
+ * @example
+ * ```ts
+ * // Old (deprecated, non-reactive):
+ * import { stringifyStyleObject } from '..'
+ * const style = stringifyStyleObject({ rotate: 45, opacity: 0.5 })
+ *
+ * // New (reactive):
+ * import { styleString } from '@humanspeak/svelte-motion'
+ * const style = styleString(() => ({ rotate, opacity }))
+ * ```
+ */
+export declare const stringifyStyleObject: (obj: Record<string, string | number>) => string;

package/dist/utils/styleObject.js

@@ -10,15 +10,63 @@ const UNITLESS_PROPERTIES = new Set([
     'order',
     'grid-column',
     'grid-row',
-    'column-count'
+    'column-count',
+    'scale',
+    'scale-x',
+    'scale-y',
+    'scale-z'
 ]);
-export function stringifyStyleObject(obj) {
+// CSS properties that need 'deg' unit instead of 'px'
+const DEGREE_PROPERTIES = new Set([
+    'rotate',
+    'rotate-x',
+    'rotate-y',
+    'rotate-z',
+    'skew',
+    'skew-x',
+    'skew-y'
+]);
+/**
+ * Converts a style object to a CSS style string.
+ *
+ * @deprecated Use `styleString` from `@humanspeak/svelte-motion` instead for reactive styles.
+ * This function is non-reactive and will not update when values change.
+ *
+ * @param obj - Style object with camelCase keys and string/number values
+ * @returns CSS style string with kebab-case properties and appropriate units
+ * @example
+ * ```ts
+ * // Old (deprecated, non-reactive):
+ * import { stringifyStyleObject } from '..'
+ * const style = stringifyStyleObject({ rotate: 45, opacity: 0.5 })
+ *
+ * // New (reactive):
+ * import { styleString } from '@humanspeak/svelte-motion'
+ * const style = styleString(() => ({ rotate, opacity }))
+ * ```
+ */
+export const stringifyStyleObject = (obj) => {
     return Object.entries(obj)
         .map(([key, value]) => {
         const cssKey = key.replace(/([A-Z])/g, '-$1').toLowerCase();
         const isUnitless = UNITLESS_PROPERTIES.has(cssKey);
-        const cssValue = typeof value === 'number' && !isUnitless ? `${value}px` : String(value);
+        const isDegree = DEGREE_PROPERTIES.has(cssKey);
+        let cssValue;
+        if (typeof value === 'number') {
+            if (isUnitless) {
+                cssValue = String(value);
+            }
+            else if (isDegree) {
+                cssValue = `${value}deg`;
+            }
+            else {
+                cssValue = `${value}px`;
+            }
+        }
+        else {
+            cssValue = String(value);
+        }
         return `${cssKey}: ${cssValue}`;
     })
         .join('; ');
-}
+};

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

@@ -0,0 +1,27 @@
+export type StyleObject = Record<string, string | number>;
+/**
+ * Creates a CSS style string from a style object or factory function.
+ *
+ * In Svelte 5, template expressions are reactive - when you use `$state` variables
+ * in a template, the expression re-evaluates when those values change. This means
+ * you can use `styleString` directly in templates and it will update reactively.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { styleString } from '@humanspeak/svelte-motion'
+ *
+ *   let rotate = $state(0)
+ *   let opacity = $state(1)
+ * </script>
+ *
+ * <!-- Both forms are reactive in Svelte 5 templates -->
+ * <div style={styleString({ rotate, opacity })}>Object form</div>
+ * <div style={styleString(() => ({ rotate, opacity }))}>Factory form</div>
+ * ```
+ *
+ * @param input - A style object or a function returning a style object
+ * @returns A CSS style string
+ */
+export declare const styleString: (input: StyleObject | (() => StyleObject)) => string;
+export { stringifyStyleObject } from './styleObject.js';

package/dist/utils/styleObject.svelte.js

@@ -0,0 +1,31 @@
+import { stringifyStyleObject } from './styleObject.js';
+/**
+ * Creates a CSS style string from a style object or factory function.
+ *
+ * In Svelte 5, template expressions are reactive - when you use `$state` variables
+ * in a template, the expression re-evaluates when those values change. This means
+ * you can use `styleString` directly in templates and it will update reactively.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { styleString } from '@humanspeak/svelte-motion'
+ *
+ *   let rotate = $state(0)
+ *   let opacity = $state(1)
+ * </script>
+ *
+ * <!-- Both forms are reactive in Svelte 5 templates -->
+ * <div style={styleString({ rotate, opacity })}>Object form</div>
+ * <div style={styleString(() => ({ rotate, opacity }))}>Factory form</div>
+ * ```
+ *
+ * @param input - A style object or a function returning a style object
+ * @returns A CSS style string
+ */
+export const styleString = (input) => {
+    const obj = typeof input === 'function' ? input() : input;
+    return stringifyStyleObject(obj);
+};
+// Re-export the pure function for backwards compatibility
+export { stringifyStyleObject } from './styleObject.js';

package/dist/utils/svg.d.ts

@@ -3,6 +3,25 @@
  * These properties are not standard CSS properties and need to be transformed.
  */
 export declare const SVG_PATH_PROPERTIES: Set<string>;
+/**
+ * The SVG namespace URI.
+ */
+export declare const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+/**
+ * Set of SVG tag names that should be created in the SVG namespace.
+ * This list covers all standard SVG elements.
+ */
+export declare const SVG_TAGS: Set<string>;
+/**
+ * Determines whether the provided tag name is an SVG element tag.
+ *
+ * @param {string} tag The tag name to test.
+ * @returns {boolean} True when the tag is an SVG element.
+ * @example
+ * isSVGTag('path') // true
+ * isSVGTag('div') // false
+ */
+export declare const isSVGTag: (tag: string) => boolean;
 /**
  * Check if an element is an SVG path element.
  */

package/dist/utils/svg.js

@@ -3,6 +3,89 @@
  * These properties are not standard CSS properties and need to be transformed.
  */
 export const SVG_PATH_PROPERTIES = new Set(['pathLength', 'pathOffset', 'pathSpacing']);
+/**
+ * The SVG namespace URI.
+ */
+export const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+/**
+ * Set of SVG tag names that should be created in the SVG namespace.
+ * This list covers all standard SVG elements.
+ */
+export const SVG_TAGS = new Set([
+    'svg',
+    'animate',
+    'animatemotion',
+    'animatetransform',
+    'circle',
+    'clippath',
+    'defs',
+    'desc',
+    'ellipse',
+    'feblend',
+    'fecolormatrix',
+    'fecomponenttransfer',
+    'fecomposite',
+    'feconvolvematrix',
+    'fediffuselighting',
+    'fedisplacementmap',
+    'fedistantlight',
+    'fedropshadow',
+    'feflood',
+    'fefunca',
+    'fefuncb',
+    'fefuncg',
+    'fefuncr',
+    'fegaussianblur',
+    'feimage',
+    'femerge',
+    'femergenode',
+    'femorphology',
+    'feoffset',
+    'fepointlight',
+    'fespecularlighting',
+    'fespotlight',
+    'fetile',
+    'feturbulence',
+    'filter',
+    'foreignobject',
+    'g',
+    'image',
+    'line',
+    'lineargradient',
+    'marker',
+    'mask',
+    'metadata',
+    'mpath',
+    'path',
+    'pattern',
+    'polygon',
+    'polyline',
+    'radialgradient',
+    'rect',
+    'set',
+    'stop',
+    'switch',
+    'symbol',
+    'text',
+    'textpath',
+    'title',
+    'tref',
+    'tspan',
+    'use',
+    'view'
+]);
+/**
+ * Determines whether the provided tag name is an SVG element tag.
+ *
+ * @param {string} tag The tag name to test.
+ * @returns {boolean} True when the tag is an SVG element.
+ * @example
+ * isSVGTag('path') // true
+ * isSVGTag('div') // false
+ */
+export const isSVGTag = (tag) => {
+    return SVG_TAGS.has(tag.toLowerCase());
+};
 /**
  * Check if an element is an SVG path element.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "A lightweight animation library for Svelte 5 that provides smooth, hardware-accelerated animations. Features include spring physics, custom easing, and fluid transitions. Built on top of the motion library, it offers a simple API for creating complex animations with minimal code. Perfect for interactive UIs, micro-interactions, and engaging user experiences.",
   "keywords": [
     "svelte",
@@ -53,8 +53,8 @@
     }
   },
   "dependencies": {
-    "motion": "^12.29.2",
-    "motion-dom": "^12.29.2"
+    "motion": "^12.31.0",
+    "motion-dom": "^12.30.1"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
@@ -62,7 +62,7 @@
     "@eslint/js": "^9.39.2",
     "@playwright/test": "^1.58.1",
     "@sveltejs/adapter-auto": "^7.0.0",
-    "@sveltejs/kit": "^2.50.1",
+    "@sveltejs/kit": "^2.50.2",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@tailwindcss/aspect-ratio": "^0.4.2",
@@ -72,7 +72,7 @@
     "@tailwindcss/typography": "^0.5.19",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
-    "@types/node": "^25.1.0",
+    "@types/node": "^25.2.0",
     "@vitest/coverage-v8": "^4.0.18",
     "concurrently": "^9.2.1",
     "eslint": "^9.39.2",
@@ -81,11 +81,11 @@
     "eslint-plugin-svelte": "3.14.0",
     "eslint-plugin-unused-imports": "4.3.0",
     "esm-env": "^1.2.2",
-    "globals": "^17.2.0",
+    "globals": "^17.3.0",
     "html-tags": "^5.1.0",
     "html-void-elements": "^3.0.0",
     "husky": "^9.1.7",
-    "jsdom": "^27.4.0",
+    "jsdom": "^28.0.0",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-sort-json": "^4.2.0",
@@ -93,7 +93,7 @@
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.17",
     "runed": "0.37.1",
-    "svelte": "^5.49.1",
+    "svelte": "^5.49.2",
     "svelte-check": "^4.3.6",
     "svg-tags": "^1.0.0",
     "tailwind-merge": "^3.4.0",