@humanspeak/svelte-motion 0.1.8 → 0.1.10

package/README.md

@@ -30,7 +30,7 @@ All standard HTML and SVG elements are supported as motion components (e.g., `mo
 
 ### MotionConfig
 
-This package includes support for `MotionConfig`, which allows you to set default motion settings for all child components. See the [Reach - Motion Config](https://motion.dev/docs/react-motion-config) for more details.
+This package includes support for `MotionConfig`, which allows you to set default motion settings for all child components. See the [React - Motion Config](https://motion.dev/docs/react-motion-config) for more details.
 
 ```svelte
 <MotionConfig transition={{ duration: 0.5 }}>
@@ -111,6 +111,7 @@ This package carefully selects its dependencies to provide a robust and maintain
 | [HTML Content (0→100 counter)](https://examples.motion.dev/react/html-content)                           | `/tests/motion/html-content`             | [View Example](https://motion.svelte.page/examples/html-content)                               |
 | [Aspect Ratio](https://examples.motion.dev/react/aspect-ratio)                                           | `/tests/motion/aspect-ratio`             | [View Example](https://svelte.dev/playground/1bf60e745fae44f5becb4c830fde9b6e?version=5.38.10) |
 | [Hover + Tap (whileHover + whileTap)](https://examples.motion.dev/react/gestures)                        | `/tests/motion/hover-and-tap`            | [View Example](https://motion.svelte.page/examples/hover-and-tap)                              |
+| [Focus (whileFocus)](https://motion.dev/docs/react-motion-component#focus)                               | `/tests/motion/while-focus`              | [View Example](https://motion.svelte.page/examples/while-focus)                                |
 | [Rotate](https://examples.motion.dev/react/rotate)                                                       | `/tests/motion/rotate`                   | [View Example](https://motion.svelte.page/examples/rotate)                                     |
 | [Random - Shiny Button](https://www.youtube.com/watch?v=jcpLprT5F0I) by [@verse\_](https://x.com/verse_) | `/tests/random/shiny-button`             | [View Example](https://svelte.dev/playground/96f9e0bf624f4396adaf06c519147450?version=5.38.10) |
 | [Fancy Like Button](https://github.com/DRlFTER/fancyLikeButton)                                          | `/tests/random/fancy-like-button`        | [View Example](https://svelte.dev/playground/c34b7e53d41c48b0ab1eaf21ca120c6e?version=5.38.10) |
@@ -153,6 +154,16 @@ Svelte Motion now supports hover interactions via the `whileHover` prop, similar
     - Blur while key is held → fires `onTapCancel`
     - `MotionContainer` sets `tabindex="0"` automatically when `whileTap` is present and no `tabindex`/`tabIndex` is provided.
 
+### Focus
+
+```svelte
+<motion.button whileFocus={{ scale: 1.05, outline: '2px solid blue' }} />
+```
+
+- Animates when the element receives keyboard focus and restores baseline on blur.
+- Callbacks: `onFocusStart`, `onFocusEnd` are supported.
+- Perfect for keyboard navigation and accessibility enhancements.
+
 ### Animation lifecycle
 
 ```svelte
@@ -166,6 +177,77 @@ Svelte Motion now supports hover interactions via the `whileHover` prop, similar
 />
 ```
 
+## Variants
+
+Variants allow you to define named animation states that can be referenced throughout your component tree. They're perfect for creating reusable animations and orchestrating complex sequences.
+
+### Basic usage
+
+Instead of defining animation objects inline, create a `Variants` object with named states:
+
+```svelte
+<script lang="ts">
+    import { motion, type Variants } from '@humanspeak/svelte-motion'
+
+    let isOpen = $state(false)
+
+    const variants: Variants = {
+        open: { opacity: 1, scale: 1 },
+        closed: { opacity: 0, scale: 0.8 }
+    }
+</script>
+
+<motion.div {variants} initial="closed" animate={isOpen ? 'open' : 'closed'}>Click me</motion.div>
+```
+
+### Variant propagation
+
+One of the most powerful features is **automatic propagation** through component trees. When a parent changes its animation state, all children with `variants` defined automatically inherit that state:
+
+```svelte
+<script lang="ts">
+    let isVisible = $state(false)
+
+    const containerVariants: Variants = {
+        visible: { opacity: 1 },
+        hidden: { opacity: 0 }
+    }
+
+    const itemVariants: Variants = {
+        visible: { opacity: 1, x: 0 },
+        hidden: { opacity: 0, x: -20 }
+    }
+</script>
+
+<motion.ul variants={containerVariants} initial="hidden" animate={isVisible ? 'visible' : 'hidden'}>
+    <!-- Children automatically inherit parent's variant state -->
+    <motion.li variants={itemVariants}>Item 1</motion.li>
+    <motion.li variants={itemVariants}>Item 2</motion.li>
+    <motion.li variants={itemVariants}>Item 3</motion.li>
+</motion.ul>
+```
+
+**How it works:**
+
+- Parent sets `animate="visible"`
+- Children with `variants` automatically inherit `"visible"` state
+- Each child resolves its own variant definition
+- No need to pass `animate` props to children!
+
+### Staggered animations
+
+Create staggered animations with transition delays:
+
+```svelte
+{#each items as item, i}
+    <motion.div variants={itemVariants} transition={{ delay: i * 0.1 }}>
+        {item}
+    </motion.div>
+{/each}
+```
+
+See the [Variants documentation](https://motion.svelte.page/docs/variants) for complete details and examples.
+
 ## Server-side rendering
 
 Motion components render their initial state during SSR. The container merges inline `style` with the first values from `initial` (or the first keyframes from `animate` when `initial` is empty) so the server HTML matches the starting appearance. On hydration, components promote to a ready state and animate without flicker.
@@ -204,6 +286,36 @@ Notes:
 <motion.div style={`rotate: ${$rotate}deg`} />
 ```
 
+### useAnimationFrame(callback)
+
+- Runs a callback on every animation frame with the current timestamp.
+- The callback receives a `DOMHighResTimeStamp` representing the time elapsed since the time origin.
+- Returns a cleanup function that stops the animation loop.
+- Best used inside a `$effect` to ensure proper cleanup when the component unmounts.
+- SSR-safe: Does nothing and returns a no-op cleanup function when `window` is unavailable.
+
+```svelte
+<script lang="ts">
+    import { useAnimationFrame } from '$lib'
+
+    let cubeRef: HTMLDivElement
+
+    $effect(() => {
+        return useAnimationFrame((t) => {
+            if (!cubeRef) return
+
+            const rotate = Math.sin(t / 10000) * 200
+            const y = (1 + Math.sin(t / 1000)) * -50
+            cubeRef.style.transform = `translateY(${y}px) rotateX(${rotate}deg) rotateY(${rotate}deg)`
+        })
+    })
+</script>
+
+<div bind:this={cubeRef}>Animated content</div>
+```
+
+- Reference: Motion useAnimationFrame docs [motion.dev](https://motion.dev/docs/react-use-animation-frame).
+
 ### useSpring
 
 `useSpring` creates a readable store that animates to its latest target with a spring. You can either control it directly with `set`/`jump`, or have it follow another readable (like a time-derived value).

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

@@ -0,0 +1,19 @@
+import type { Writable } from 'svelte/store';
+/**
+ * Provide a writable store for the current variant key so children can
+ * react to changes over time (true inheritance like Framer Motion).
+ */
+export declare function setVariantContext(store: Writable<string | undefined>): void;
+/**
+ * Read the parent's variant store (if any). Children subscribe to this store
+ * to inherit and react to parent `animate` changes.
+ */
+export declare function getVariantContext(): Writable<string | undefined> | undefined;
+/**
+ * Set initial={false} in context so children inherit it
+ */
+export declare function setInitialFalseContext(value: boolean): void;
+/**
+ * Check if parent has initial={false}
+ */
+export declare function getInitialFalseContext(): boolean;

package/dist/components/variantContext.context.js

@@ -0,0 +1,29 @@
+import { getContext, setContext } from 'svelte';
+const VARIANT_CONTEXT_KEY = Symbol('variant-context');
+const INITIAL_FALSE_CONTEXT_KEY = Symbol('initial-false-context');
+/**
+ * Provide a writable store for the current variant key so children can
+ * react to changes over time (true inheritance like Framer Motion).
+ */
+export function setVariantContext(store) {
+    setContext(VARIANT_CONTEXT_KEY, store);
+}
+/**
+ * Read the parent's variant store (if any). Children subscribe to this store
+ * to inherit and react to parent `animate` changes.
+ */
+export function getVariantContext() {
+    return getContext(VARIANT_CONTEXT_KEY);
+}
+/**
+ * Set initial={false} in context so children inherit it
+ */
+export function setInitialFalseContext(value) {
+    setContext(INITIAL_FALSE_CONTEXT_KEY, value);
+}
+/**
+ * Check if parent has initial={false}
+ */
+export function getInitialFalseContext() {
+    return getContext(INITIAL_FALSE_CONTEXT_KEY) ?? false;
+}

package/dist/html/_MotionContainer.svelte

@@ -9,6 +9,7 @@
     import { mergeTransitions, animateWithLifecycle } from '../utils/animation'
     import { attachWhileTap } from '../utils/interaction'
     import { attachWhileHover } from '../utils/hover'
+    import { attachWhileFocus } from '../utils/focus'
     import {
         measureRect,
         computeFlipTransforms,
@@ -21,6 +22,14 @@
     import { isNativelyFocusable } from '../utils/a11y'
     import { usePresence, getAnimatePresenceContext } from '../utils/presence'
     import { getInitialKeyframes } from '../utils/initial'
+    import { resolveInitial, resolveAnimate, resolveExit } from '../utils/variants'
+    import {
+        setVariantContext,
+        getVariantContext,
+        setInitialFalseContext,
+        getInitialFalseContext
+    } from '../components/variantContext.context'
+    import { writable } from 'svelte/store'
 
     type Props = MotionProps & {
         children?: Snippet
@@ -31,6 +40,7 @@
     let {
         children,
         tag = 'div',
+        variants: variantsProp,
         initial: initialProp,
         animate: animateProp,
         exit: exitProp,
@@ -41,8 +51,11 @@
         class: classProp,
         whileTap: whileTapProp,
         whileHover: whileHoverProp,
+        whileFocus: whileFocusProp,
         onHoverStart: onHoverStartProp,
         onHoverEnd: onHoverEndProp,
+        onFocusStart: onFocusStartProp,
+        onFocusEnd: onFocusEndProp,
         onTapStart: onTapStartProp,
         onTap: onTapProp,
         onTapCancel: onTapCancelProp,
@@ -71,7 +84,7 @@
             usePresence(
                 presenceKey,
                 element,
-                exitProp,
+                resolvedExit,
                 mergedTransition as unknown as MotionTransition
             )
         }
@@ -140,8 +153,67 @@
     // Recognized HTML void elements that cannot contain children
     const isVoidTag = $derived(VOID_TAGS.has(tag as string))
 
-    // Extract keyframes from initialProp, handling initial={false}
-    const initialKeyframes = $derived(getInitialKeyframes(initialProp))
+    // Variant inheritance and resolution
+    const parentVariantStore = getVariantContext()
+
+    // Get initial inherited variant synchronously
+    let initialInheritedVariant: string | undefined = undefined
+    if (parentVariantStore) {
+        parentVariantStore.subscribe((v) => (initialInheritedVariant = v))()
+    }
+
+    // Create store with initial value so children can inherit immediately
+    const initialVariantValue =
+        typeof animateProp === 'string'
+            ? animateProp
+            : (variantsProp && initialInheritedVariant) || undefined
+    const localVariantStore = writable<string | undefined>(initialVariantValue)
+
+    let inheritedVariant = $state<string | undefined>(initialInheritedVariant)
+
+    $effect(() => {
+        if (!parentVariantStore) {
+            inheritedVariant = undefined
+            return
+        }
+        const unsubscribe = parentVariantStore.subscribe((v) => (inheritedVariant = v))
+        return () => unsubscribe()
+    })
+
+    // Use the initial value first, then switch to reactive once mounted
+    const effectiveAnimate = $derived(
+        animateProp ?? (variantsProp ? (inheritedVariant ?? initialInheritedVariant) : undefined)
+    )
+
+    // Propagate initial={false} to children BEFORE setting variant context
+    const parentInitialFalse = getInitialFalseContext()
+    const effectiveInitialProp =
+        initialProp !== undefined
+            ? initialProp
+            : parentInitialFalse && variantsProp
+              ? false
+              : undefined
+
+    if (initialProp === false) {
+        setInitialFalseContext(true)
+    }
+
+    // Provide context immediately during initialization so children can inherit
+    setVariantContext(localVariantStore)
+
+    $effect(() => {
+        if (!variantsProp) return localVariantStore.set(undefined)
+        if (typeof animateProp === 'string') return localVariantStore.set(animateProp)
+        if (typeof effectiveAnimate === 'string') return localVariantStore.set(effectiveAnimate)
+        localVariantStore.set(undefined)
+    })
+
+    const resolvedInitial = $derived(resolveInitial(effectiveInitialProp, variantsProp))
+    const resolvedAnimate = $derived(resolveAnimate(effectiveAnimate, variantsProp))
+    const resolvedExit = $derived(resolveExit(exitProp, variantsProp))
+
+    // Extract keyframes from resolved initial, handling initial={false}
+    const initialKeyframes = $derived(getInitialKeyframes(resolvedInitial))
 
     // Derived attributes to keep both branches in sync (focusability, data flags, style, class)
     const derivedAttrs = $derived<Record<string, unknown>>({
@@ -163,15 +235,15 @@
         style: mergeInlineStyles(
             styleProp,
             initialKeyframes as unknown as Record<string, unknown>,
-            animateProp as unknown as Record<string, unknown>
+            resolvedAnimate as unknown as Record<string, unknown>
         ),
         class: classProp
     })
 
     const runAnimation = () => {
-        if (!element || !animateProp) return
+        if (!element || !resolvedAnimate) return
         const transitionAnimate: MotionTransition = mergedTransition ?? {}
-        const payload = $state.snapshot(animateProp)
+        const payload = $state.snapshot(resolvedAnimate)
         animateWithLifecycle(
             element,
             payload as unknown as DOMKeyframesDefinition,
@@ -181,6 +253,17 @@
         )
     }
 
+    // Track the last variant key we ran to avoid re-running on mount
+    let lastRanVariantKey = $state<string | undefined>(undefined)
+    let mountedWithInitialFalse = $state(false)
+    const currentAnimateKey = $derived(
+        typeof animateProp === 'string'
+            ? animateProp
+            : typeof effectiveAnimate === 'string'
+              ? effectiveAnimate
+              : undefined
+    )
+
     // Minimal layout animation using FLIP when `layout` is enabled.
     // When layout === 'position' we only translate.
     // When layout === true we also scale to smoothly interpolate size changes.
@@ -231,8 +314,8 @@
         return attachWhileTap(
             element!,
             (whileTapProp ?? {}) as Record<string, unknown>,
-            (initialProp ?? {}) as Record<string, unknown>,
-            (animateProp ?? {}) as Record<string, unknown>,
+            (resolvedInitial ?? {}) as Record<string, unknown>,
+            (resolvedAnimate ?? {}) as Record<string, unknown>,
             {
                 onTapStart: onTapStartProp,
                 onTap: onTapProp,
@@ -253,23 +336,93 @@
             { onStart: onHoverStartProp, onEnd: onHoverEndProp },
             undefined,
             {
-                initial: (initialProp ?? {}) as Record<string, unknown>,
-                animate: (animateProp ?? {}) as Record<string, unknown>
+                initial: (resolvedInitial ?? {}) as Record<string, unknown>,
+                animate: (resolvedAnimate ?? {}) as Record<string, unknown>
+            }
+        )
+    })
+
+    // whileFocus handling for keyboard focus interactions
+    $effect(() => {
+        if (!(element && isLoaded === 'ready' && isNotEmpty(whileFocusProp))) return
+        return attachWhileFocus(
+            element!,
+            (whileFocusProp ?? {}) as Record<string, unknown>,
+            (mergedTransition ?? {}) as AnimationOptions,
+            { onStart: onFocusStartProp, onEnd: onFocusEndProp },
+            {
+                initial: (resolvedInitial ?? {}) as Record<string, unknown>,
+                animate: (resolvedAnimate ?? {}) as Record<string, unknown>
             }
         )
     })
 
     // Re-run animate when animateProp changes while ready
     $effect(() => {
-        if (element && isLoaded === 'ready' && isNotEmpty(animateProp)) {
+        if (!(element && isLoaded === 'ready')) return
+        // Skip first run if we mounted with initial={false} AND the variant hasn't changed
+        if (mountedWithInitialFalse) {
+            // Only skip if the variant is the same as what we mounted with
+            if (typeof animateProp === 'string' && lastRanVariantKey === animateProp) {
+                mountedWithInitialFalse = false
+                return
+            }
+            // Variant has changed, so we should animate
+            mountedWithInitialFalse = false
+        }
+        if (typeof animateProp === 'string') {
+            if (lastRanVariantKey !== animateProp) {
+                lastRanVariantKey = animateProp
+                runAnimation()
+            }
+        } else if (animateProp) {
+            // Object animate props - always run
+            lastRanVariantKey = undefined
+            runAnimation()
+        }
+    })
+
+    // Also run when inherited/effective variant changes
+    $effect(() => {
+        void resolvedAnimate
+        if (!(element && isLoaded === 'ready' && !animateProp && resolvedAnimate)) return
+        // Skip first run if we mounted with initial={false} AND the variant hasn't changed
+        if (mountedWithInitialFalse) {
+            // Only skip if the variant is the same as what we mounted with
+            if (typeof currentAnimateKey === 'string' && lastRanVariantKey === currentAnimateKey) {
+                mountedWithInitialFalse = false
+                return
+            }
+            // Variant has changed, so we should animate
+            mountedWithInitialFalse = false
+        }
+        if (typeof currentAnimateKey === 'string') {
+            if (lastRanVariantKey !== currentAnimateKey) {
+                lastRanVariantKey = currentAnimateKey
+                runAnimation()
+            }
+        } else {
             runAnimation()
         }
     })
 
     $effect(() => {
         if (!(element && isLoaded === 'mounting')) return
-        if (animateProp) {
-            if (isNotEmpty(initialKeyframes)) {
+        if (effectiveAnimate) {
+            // If initial={false}, render at animate state immediately with no transition
+            if (effectiveInitialProp === false && resolvedAnimate) {
+                // Use Motion's animate() with duration:0 so it takes control of these properties
+                // This prevents inline styles from pinning the properties during future animations
+                const snapshot = $state.snapshot(resolvedAnimate) as Record<string, unknown>
+                animate(element!, snapshot as DOMKeyframesDefinition, { duration: 0 })
+                // Mark that we've already applied this variant to avoid a second animate pass
+                mountedWithInitialFalse = true
+                if (typeof currentAnimateKey === 'string') {
+                    lastRanVariantKey = currentAnimateKey
+                }
+                dataPath = 5
+                isLoaded = 'ready'
+            } else if (isNotEmpty(initialKeyframes)) {
                 // Apply initial instantly BEFORE exposing 'initial' state
                 animate(element!, initialKeyframes!, { duration: 0 })
                 // Mark initial after styles are applied so tests read CSS=0 while state=initial
@@ -286,7 +439,20 @@
             } else {
                 dataPath = 2
                 isLoaded = 'ready'
-                runAnimation()
+                // If we're inheriting a variant and parent had initial={false}, apply the variant instantly
+                // without animation, then mark it as applied
+                if (
+                    parentInitialFalse &&
+                    typeof currentAnimateKey === 'string' &&
+                    resolvedAnimate
+                ) {
+                    // Apply variant styles instantly with duration:0
+                    const snapshot = $state.snapshot(resolvedAnimate) as Record<string, unknown>
+                    animate(element!, snapshot as DOMKeyframesDefinition, { duration: 0 })
+                    lastRanVariantKey = currentAnimateKey
+                } else {
+                    runAnimation()
+                }
             }
         } else if (isNotEmpty(initialKeyframes)) {
             // Apply initial instantly BEFORE exposing 'initial' state

package/dist/index.d.ts

@@ -3,8 +3,10 @@ import MotionConfig from './components/MotionConfig.svelte';
 import type { MotionComponents } from './html/index';
 export declare const motion: MotionComponents;
 export { animate, hover } from 'motion';
-export type { MotionAnimate, MotionInitial, MotionTransition, MotionWhileTap } from './types';
+export type { MotionAnimate, MotionInitial, MotionTransition, MotionWhileFocus, MotionWhileHover, MotionWhileTap, Variants } from './types';
+export { useAnimationFrame } from './utils/animationFrame';
 export { useSpring } from './utils/spring';
+export { stringifyStyleObject } from './utils/styleObject';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
 export { AnimatePresence, MotionConfig };

package/dist/index.js

@@ -5,7 +5,9 @@ import * as html from './html/index';
 export const motion = Object.fromEntries(Object.entries(html).map(([key, component]) => [key.toLowerCase(), component]));
 // Export all types
 export { animate, hover } from 'motion';
+export { useAnimationFrame } from './utils/animationFrame';
 export { useSpring } from './utils/spring';
+export { stringifyStyleObject } from './utils/styleObject';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
 export { AnimatePresence, MotionConfig };

package/dist/types.d.ts

@@ -1,10 +1,27 @@
 import type { AnimationOptions, DOMKeyframesDefinition } from 'motion';
 import type { Snippet } from 'svelte';
+/**
+ * Variants define named animation states that can be referenced by string keys.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   const variants = {
+ *     open: { opacity: 1, scale: 1 },
+ *     closed: { opacity: 0, scale: 0.8 }
+ *   }
+ * </script>
+ *
+ * <motion.div variants={variants} animate="open" />
+ * ```
+ */
+export type Variants = Record<string, DOMKeyframesDefinition | undefined>;
 /**
  * Initial animation properties for a motion component.
  *
- * Set to `false` to skip the initial animation and render directly at the animated state.
- * Useful for elements that should not animate on mount (e.g., tab indicators).
+ * - Can be an object with animation properties
+ * - Can be a string key referencing a variant
+ * - Set to `false` to skip the initial animation and render directly at the animated state
  *
  * @example
  * ```svelte
@@ -13,27 +30,44 @@ import type { Snippet } from 'svelte';
  *
  * <!-- Skip initial animation, render at animate state -->
  * <motion.div initial={false} animate={{ opacity: 1 }} />
+ *
+ * <!-- Use variant key -->
+ * <motion.div variants={myVariants} initial="hidden" animate="visible" />
  * ```
  */
-export type MotionInitial = DOMKeyframesDefinition | false | undefined;
+export type MotionInitial = DOMKeyframesDefinition | string | false | undefined;
 /**
  * Target animation properties for a motion component.
+ *
+ * - Can be an object with animation properties
+ * - Can be a string key referencing a variant
+ *
  * @example
  * ```svelte
  * <motion.div animate={{ opacity: 1, scale: 1 }} />
+ *
+ * <!-- With variants -->
+ * <motion.div variants={myVariants} animate="visible" />
  * ```
  */
-export type MotionAnimate = DOMKeyframesDefinition | undefined;
+export type MotionAnimate = DOMKeyframesDefinition | string | undefined;
 /**
  * Exit animation properties for a motion component when unmounted.
+ *
+ * - Can be an object with animation properties
+ * - Can be a string key referencing a variant
+ *
  * @example
  * ```svelte
  * <motion.div exit={{ opacity: 0, scale: 0 }} />
+ *
+ * <!-- With variants -->
+ * <motion.div variants={myVariants} exit="hidden" />
  * ```
  */
 export type MotionExit = (Record<string, unknown> & {
     transition?: AnimationOptions;
-}) | DOMKeyframesDefinition | undefined;
+}) | DOMKeyframesDefinition | string | undefined;
 /**
  * Animation transition configuration.
  * @example
@@ -69,6 +103,16 @@ export type MotionWhileTap = DOMKeyframesDefinition | undefined;
 export type MotionWhileHover = (Record<string, unknown> & {
     transition?: AnimationOptions;
 }) | DOMKeyframesDefinition | undefined;
+/**
+ * Animation properties for focus interactions.
+ * @example
+ * ```svelte
+ * <motion.button whileFocus={{ scale: 1.05 }} />
+ * ```
+ */
+export type MotionWhileFocus = (Record<string, unknown> & {
+    transition?: AnimationOptions;
+}) | DOMKeyframesDefinition | undefined;
 /**
  * Animation transition configuration for hover interactions.
  * Overrides the global transition when provided.
@@ -81,6 +125,9 @@ export type MotionAnimationComplete = ((_definition: DOMKeyframesDefinition | un
 /** Hover lifecycle callbacks */
 export type MotionOnHoverStart = (() => void) | undefined;
 export type MotionOnHoverEnd = (() => void) | undefined;
+/** Focus lifecycle callbacks */
+export type MotionOnFocusStart = (() => void) | undefined;
+export type MotionOnFocusEnd = (() => void) | undefined;
 /** Tap lifecycle callbacks */
 export type MotionOnTapStart = (() => void) | undefined;
 export type MotionOnTap = (() => void) | undefined;
@@ -89,11 +136,13 @@ export type MotionOnTapCancel = (() => void) | undefined;
  * Base motion props shared by all motion components.
  */
 export type MotionProps = {
-    /** Initial state of the animation */
+    /** Variants define named animation states */
+    variants?: Variants;
+    /** Initial state of the animation (object or variant key) */
     initial?: MotionInitial;
-    /** Target state of the animation */
+    /** Target state of the animation (object or variant key) */
     animate?: MotionAnimate;
-    /** Exit animation state when component is removed */
+    /** Exit animation state when component is removed (object or variant key) */
     exit?: MotionExit;
     /** Animation configuration */
     transition?: MotionTransition;
@@ -101,6 +150,8 @@ export type MotionProps = {
     whileTap?: MotionWhileTap;
     /** Hover interaction animation */
     whileHover?: MotionWhileHover;
+    /** Focus interaction animation */
+    whileFocus?: MotionWhileFocus;
     /** Called right before a main animate transition starts */
     onAnimationStart?: MotionAnimationStart;
     /** Called after a main animate transition completes */
@@ -109,6 +160,10 @@ export type MotionProps = {
     onHoverStart?: MotionOnHoverStart;
     /** Called when a true hover gesture ends */
     onHoverEnd?: MotionOnHoverEnd;
+    /** Called when element receives keyboard focus */
+    onFocusStart?: MotionOnFocusStart;
+    /** Called when element loses keyboard focus */
+    onFocusEnd?: MotionOnFocusEnd;
     /** Called when a tap gesture starts (pointerdown recognized) */
     onTapStart?: MotionOnTapStart;
     /** Called when a tap gesture ends successfully (pointerup) */

package/dist/utils/a11y.d.ts

@@ -1,2 +1,22 @@
 import type { SvelteHTMLElements } from 'svelte/elements';
+/**
+ * Determines if an HTML element is natively focusable.
+ *
+ * Checks whether a given tag with provided attributes can receive keyboard
+ * focus without needing an explicit `tabindex`. Elements are considered
+ * natively focusable if they have `tabindex`, `tabIndex`, `contenteditable`,
+ * or are inherently focusable tags like `button`, `input`, or anchors with `href`.
+ *
+ * @param tag - The HTML element tag name.
+ * @param attrs - Attributes object that may contain focusability hints.
+ * @returns `true` if the element is natively focusable, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * isNativelyFocusable('button', {})                    // true
+ * isNativelyFocusable('div', { tabindex: '0' })        // true
+ * isNativelyFocusable('a', { href: '/home' })          // true
+ * isNativelyFocusable('div', {})                       // false
+ * ```
+ */
 export declare const isNativelyFocusable: (tag: keyof SvelteHTMLElements, attrs?: Record<string, unknown>) => boolean;