@humanspeak/svelte-motion 0.1.1 → 0.1.3

package/README.md

@@ -74,14 +74,16 @@ This package carefully selects its dependencies to provide a robust and maintain
 
 ### Examples
 
-| Motion                                                                                                   | Demo / Route                      | REPL                                                                                           |
-| -------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
-| [React - Enter Animation](https://examples.motion.dev/react/enter-animation)                             | `/tests/motion/enter-animation`   | [View Example](https://svelte.dev/playground/7f60c347729f4ea48b1a4590c9dedc02?version=5.38.10) |
-| [HTML Content (0→100 counter)](https://examples.motion.dev/react/html-content)                           | `/tests/motion/html-content`      | [View Example](https://svelte.dev/playground/31cd72df4a3242b4b4589501a25e774f?version=5.38.10) |
-| [Aspect Ratio](https://examples.motion.dev/react/aspect-ratio)                                           | `/tests/motion/aspect-ratio`      | [View Example](https://svelte.dev/playground/1bf60e745fae44f5becb4c830fde9b6e?version=5.38.10) |
-| [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) |
-| [Keyframes (square → circle → square; scale 1→2→1)](https://motion.dev/docs/react-animation#keyframes)   | `/tests/motion/keyframes`         | [View Example](https://svelte.dev/playground/05595ce0db124c1cbbe4e74fda68d717?version=5.38.10) |
+| Motion                                                                                                   | Demo / Route                             | REPL                                                                                           |
+| -------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| [React - Enter Animation](https://examples.motion.dev/react/enter-animation)                             | `/tests/motion/enter-animation`          | [View Example](https://svelte.dev/playground/7f60c347729f4ea48b1a4590c9dedc02?version=5.38.10) |
+| [HTML Content (0→100 counter)](https://examples.motion.dev/react/html-content)                           | `/tests/motion/html-content`             | [View Example](https://svelte.dev/playground/31cd72df4a3242b4b4589501a25e774f?version=5.38.10) |
+| [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://motion.dev/docs/react?platform=react#hover-tap-animation)  | `/tests/motion/hover-and-tap`            | [View Example](https://svelte.dev/playground/674c7d58f2c740baa4886b01340a97ea?version=5.38.10) |
+| [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) |
+| [Keyframes (square → circle → square; scale 1→2→1)](https://motion.dev/docs/react-animation#keyframes)   | `/tests/motion/keyframes`                | [View Example](https://svelte.dev/playground/05595ce0db124c1cbbe4e74fda68d717?version=5.38.10) |
+| [Animated Border Gradient (conic-gradient rotate)](https://www.youtube.com/watch?v=OgQI1-9T6ZA)          | `/tests/random/animated-border-gradient` | [View Example](https://svelte.dev/playground/6983a61b4c35441b8aa72a971de01a23?version=5.38.10) |
 
 ## Interactions
 
@@ -111,6 +113,13 @@ Svelte Motion now supports hover interactions via the `whileHover` prop, similar
 <motion.button whileTap={{ scale: 0.95 }} />
 ```
 
+- Callbacks: `onTapStart`, `onTap`, `onTapCancel` are supported.
+- Accessibility: Elements with `whileTap` are keyboard-accessible (Enter and Space).
+    - Enter or Space down → fires `onTapStart` and applies `whileTap` (Space prevents default scrolling)
+    - Enter or Space up → fires `onTap`
+    - Blur while key is held → fires `onTapCancel`
+    - `MotionContainer` sets `tabindex="0"` automatically when `whileTap` is present and no `tabindex`/`tabIndex` is provided.
+
 ### Animation lifecycle
 
 ```svelte
@@ -141,6 +150,91 @@ Notes:
 - Transform properties like `scale`/`rotate` are composed into a single `transform` style during SSR.
 - When `initial` is empty, the first keyframe from `animate` is used to seed SSR styles.
 
+## Utilities
+
+### useTime(id?)
+
+- Returns a Svelte readable store that updates once per animation frame with elapsed milliseconds since creation.
+- If you pass an `id`, calls with the same id return a shared timeline (kept in sync across components).
+- SSR-safe: Returns a static `0` store when `window` is not available.
+
+```svelte
+<script lang="ts">
+    import { motion, useTime } from '$lib'
+    import { derived } from 'svelte/store'
+
+    const time = useTime('global') // shared
+    const rotate = derived(time, (t) => ((t % 4000) / 4000) * 360)
+</script>
+
+<motion.div style={`rotate: ${$rotate}deg`} />
+```
+
+### 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).
+
+```svelte
+<script lang="ts">
+    import { useTime, useTransform, useSpring } from '$lib'
+
+    // Track another readable
+    const time = useTime()
+    const blurTarget = useTransform(() => {
+        const phase = ($time % 2000) / 2000
+        return 4 * (0.5 + 0.5 * Math.sin(phase * Math.PI * 2)) // 0..4
+    }, [time])
+    const blur = useSpring(blurTarget, { stiffness: 300 })
+
+    // Or direct control
+    const x = useSpring(0, { stiffness: 300 })
+    // x.set(100) // animates to 100
+    // x.jump(0)  // jumps without animation
+</script>
+
+<div style={`filter: blur(${$blur}px)`} />
+```
+
+- Accepts number or unit string (e.g., `"100vh"`) or a readable source.
+- Returns a readable with `{ set, jump }` methods when used in the browser; SSR-safe on the server.
+- Reference: Motion useSpring docs [motion.dev](https://motion.dev/docs/react-use-spring?platform=react).
+
+### useTransform
+
+`useTransform` creates a derived readable. It supports:
+
+- Range mapping: map a numeric source across input/output ranges with optional `{ clamp, ease, mixer }`.
+- Function form: compute from one or more dependencies.
+
+Range mapping example:
+
+```svelte
+<script lang="ts">
+    import { useTime, useTransform } from '$lib'
+    const time = useTime()
+    // Map 0..4000ms to 0..360deg, unclamped to allow wrap-around
+    const rotate = useTransform(time, [0, 4000], [0, 360], { clamp: false })
+</script>
+
+<div style={`rotate: ${$rotate}deg`} />
+```
+
+Function form example:
+
+```svelte
+<script lang="ts">
+    import { useTransform } from '$lib'
+    // Given stores a and b, compute their sum
+    const add = (a: number, b: number) => a + b
+    // deps are stores; body can access them via $ syntax
+    const total = useTransform(() => add($a, $b), [a, b])
+</script>
+
+<span>{$total}</span>
+```
+
+- Reference: Motion useTransform docs [motion.dev](https://motion.dev/docs/react-use-transform?platform=react).
+
 ## Access the underlying element (bind:ref)
 
 You can bind a ref to access the underlying DOM element rendered by a motion component:

package/dist/html/_MotionContainer.svelte

@@ -3,7 +3,7 @@
     import type { MotionProps, MotionTransition } from '../types.js'
     import { isNotEmpty } from '../utils/objects.js'
     import { sleep } from '../utils/testing.js'
-    import { animate } from 'motion'
+    import { animate, type AnimationOptions, type DOMKeyframesDefinition } from 'motion'
     import { type Snippet } from 'svelte'
     import { VOID_TAGS } from '../utils/constants.js'
     import { mergeTransitions, animateWithLifecycle } from '../utils/animation.js'
@@ -18,6 +18,7 @@
     } from '../utils/layout.js'
     import type { SvelteHTMLElements } from 'svelte/elements'
     import { mergeInlineStyles } from '../utils/style.js'
+    import { isNativelyFocusable } from '../utils/a11y.js'
 
     type Props = MotionProps & {
         children?: Snippet
@@ -37,10 +38,13 @@
         class: classProp,
         whileTap: whileTapProp,
         whileHover: whileHoverProp,
-        ref: element = $bindable(null),
         onHoverStart: onHoverStartProp,
         onHoverEnd: onHoverEndProp,
+        onTapStart: onTapStartProp,
+        onTap: onTapProp,
+        onTapCancel: onTapCancelProp,
         layout: layoutProp,
+        ref: element = $bindable(null),
         ...rest
     }: Props = $props()
     let isLoaded = $state<'mounting' | 'initial' | 'ready' | 'animated'>('mounting')
@@ -54,26 +58,45 @@
     const isVoidTag = $derived(VOID_TAGS.has(tag as string))
 
     // Compute merged transition without mutating props to avoid effect write loops
-    let mergedTransition = $derived<MotionTransition>(
+    const mergedTransition = $derived<MotionTransition>(
         mergeTransitions(motionConfig?.transition, transitionProp)
     )
 
+    // 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 &&
+        !isNativelyFocusable(tag, rest as Record<string, unknown>) &&
+        ((rest as Record<string, unknown>)?.tabindex ??
+            (rest as Record<string, unknown>)?.tabIndex ??
+            undefined) === undefined
+            ? { tabindex: 0 }
+            : {}),
+        ...(isPlaywright
+            ? {
+                  'data-playwright': isPlaywright,
+                  'data-is-loaded': isLoaded,
+                  'data-path': dataPath
+              }
+            : {}),
+        style: mergeInlineStyles(
+            styleProp,
+            initialProp as unknown as Record<string, unknown>,
+            animateProp as unknown as Record<string, unknown>
+        ),
+        class: classProp
+    })
+
     const runAnimation = () => {
         if (!element || !animateProp) return
-        const transitionAmimate: MotionTransition = mergedTransition ?? {}
+        const transitionAnimate: MotionTransition = mergedTransition ?? {}
         const payload = $state.snapshot(animateProp)
         animateWithLifecycle(
             element,
-            payload as unknown as import('motion').DOMKeyframesDefinition,
-            transitionAmimate as unknown as import('motion').AnimationOptions,
-            (def) =>
-                onAnimationStartProp?.(
-                    def as unknown as import('motion').DOMKeyframesDefinition | undefined
-                ),
-            (def) =>
-                onAnimationCompleteProp?.(
-                    def as unknown as import('motion').DOMKeyframesDefinition | undefined
-                )
+            payload as unknown as DOMKeyframesDefinition,
+            transitionAnimate as unknown as AnimationOptions,
+            (def) => onAnimationStartProp?.(def as unknown as DOMKeyframesDefinition | undefined),
+            (def) => onAnimationCompleteProp?.(def as unknown as DOMKeyframesDefinition | undefined)
         )
     }
 
@@ -97,11 +120,7 @@
             }
             const next = measureRect(element!)
             const transforms = computeFlipTransforms(lastRect, next, layoutProp ?? false)
-            runFlipAnimation(
-                element!,
-                transforms,
-                (mergedTransition ?? {}) as import('motion').AnimationOptions
-            )
+            runFlipAnimation(element!, transforms, (mergedTransition ?? {}) as AnimationOptions)
             lastRect = next
         }
 
@@ -134,7 +153,14 @@
             element!,
             (whileTapProp ?? {}) as Record<string, unknown>,
             (initialProp ?? {}) as Record<string, unknown>,
-            (animateProp ?? {}) as Record<string, unknown>
+            (animateProp ?? {}) as Record<string, unknown>,
+            {
+                onTapStart: onTapStartProp,
+                onTap: onTapProp,
+                onTapCancel: onTapCancelProp,
+                hoverDef: (whileHoverProp ?? {}) as Record<string, unknown>,
+                hoverFallbackTransition: (mergedTransition ?? {}) as AnimationOptions
+            }
         )
     })
 
@@ -144,7 +170,7 @@
         return attachWhileHover(
             element!,
             (whileHoverProp ?? {}) as Record<string, unknown>,
-            (mergedTransition ?? {}) as import('motion').AnimationOptions,
+            (mergedTransition ?? {}) as AnimationOptions,
             { onStart: onHoverStartProp, onEnd: onHoverEndProp },
             undefined,
             {
@@ -202,35 +228,9 @@
 </script>
 
 {#if isVoidTag}
-    <svelte:element
-        this={tag}
-        bind:this={element}
-        {...rest}
-        data-playwright={isPlaywright ? isPlaywright : undefined}
-        data-is-loaded={isPlaywright ? isLoaded : undefined}
-        data-path={isPlaywright ? dataPath : undefined}
-        style={mergeInlineStyles(
-            styleProp,
-            initialProp as unknown as Record<string, unknown>,
-            animateProp as unknown as Record<string, unknown>
-        )}
-        class={classProp}
-    />
+    <svelte:element this={tag} bind:this={element} {...derivedAttrs} />
 {:else}
-    <svelte:element
-        this={tag}
-        bind:this={element}
-        {...rest}
-        data-playwright={isPlaywright ? isPlaywright : undefined}
-        data-is-loaded={isPlaywright ? isLoaded : undefined}
-        data-path={isPlaywright ? dataPath : undefined}
-        style={mergeInlineStyles(
-            styleProp,
-            initialProp as unknown as Record<string, unknown>,
-            animateProp as unknown as Record<string, unknown>
-        )}
-        class={classProp}
-    >
+    <svelte:element this={tag} bind:this={element} {...derivedAttrs}>
         {#if isLoaded === 'ready'}
             {@render children?.()}
         {/if}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import MotionConfig from './components/MotionConfig.svelte';
-import type { MotionComponents } from './html/index.js';
+import type { MotionComponents } from './html/index';
 export declare const motion: MotionComponents;
 export { animate, hover } from 'motion';
-export type { MotionAnimate, MotionInitial, MotionTransition, MotionWhileTap } from './types.js';
+export type { MotionAnimate, MotionInitial, MotionTransition, MotionWhileTap } from './types';
+export { useSpring } from './utils/spring';
+export { useTime } from './utils/time';
+export { useTransform } from './utils/transform';
 export { MotionConfig };

package/dist/index.js

@@ -1,7 +1,10 @@
 import MotionConfig from './components/MotionConfig.svelte';
-import * as html from './html/index.js';
+import * as html from './html/index';
 // Create the motion object with all components
 export const motion = Object.fromEntries(Object.entries(html).map(([key, component]) => [key.toLowerCase(), component]));
 // Export all types
 export { animate, hover } from 'motion';
+export { useSpring } from './utils/spring';
+export { useTime } from './utils/time';
+export { useTransform } from './utils/transform';
 export { MotionConfig };

package/dist/types.d.ts

@@ -58,11 +58,15 @@ export type MotionWhileHover = (Record<string, unknown> & {
 /**
  * Animation lifecycle callbacks for motion components.
  */
-export type MotionAnimationStart = ((definition: DOMKeyframesDefinition | undefined) => void) | undefined;
-export type MotionAnimationComplete = ((definition: DOMKeyframesDefinition | undefined) => void) | undefined;
+export type MotionAnimationStart = ((_definition: DOMKeyframesDefinition | undefined) => void) | undefined;
+export type MotionAnimationComplete = ((_definition: DOMKeyframesDefinition | undefined) => void) | undefined;
 /** Hover lifecycle callbacks */
 export type MotionOnHoverStart = (() => void) | undefined;
 export type MotionOnHoverEnd = (() => void) | undefined;
+/** Tap lifecycle callbacks */
+export type MotionOnTapStart = (() => void) | undefined;
+export type MotionOnTap = (() => void) | undefined;
+export type MotionOnTapCancel = (() => void) | undefined;
 /**
  * Base motion props shared by all motion components.
  */
@@ -85,6 +89,12 @@ export type MotionProps = {
     onHoverStart?: MotionOnHoverStart;
     /** Called when a true hover gesture ends */
     onHoverEnd?: MotionOnHoverEnd;
+    /** Called when a tap gesture starts (pointerdown recognized) */
+    onTapStart?: MotionOnTapStart;
+    /** Called when a tap gesture ends successfully (pointerup) */
+    onTap?: MotionOnTap;
+    /** Called when a tap gesture is cancelled (pointercancel) */
+    onTapCancel?: MotionOnTapCancel;
     /** Inline styles */
     style?: string;
     /** CSS classes */

package/dist/utils/a11y.d.ts

@@ -0,0 +1,2 @@
+import type { SvelteHTMLElements } from 'svelte/elements';
+export declare const isNativelyFocusable: (tag: keyof SvelteHTMLElements, attrs?: Record<string, unknown>) => boolean;

package/dist/utils/a11y.js

@@ -0,0 +1,20 @@
+export const isNativelyFocusable = (tag, attrs = {}) => {
+    if (attrs.tabindex != null)
+        return true;
+    if (attrs.tabIndex != null)
+        return true;
+    if (attrs.contenteditable != null)
+        return true;
+    switch (tag) {
+        case 'a':
+            return Boolean(attrs.href);
+        case 'button':
+        case 'input':
+        case 'select':
+        case 'textarea':
+        case 'summary':
+            return true;
+        default:
+            return false;
+    }
+};

package/dist/utils/animation.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationOptions, DOMKeyframesDefinition } from 'motion';
+import { type AnimationOptions, type DOMKeyframesDefinition } from 'motion';
 /**
  * Merge two Motion `AnimationOptions` objects without mutating the inputs.
  *

package/dist/utils/animation.js

@@ -1,5 +1,5 @@
+import { hasFinishedPromise, isPromiseLike } from './promise';
 import { animate } from 'motion';
-import { hasFinishedPromise, isPromiseLike } from './promise.js';
 /**
  * Merge two Motion `AnimationOptions` objects without mutating the inputs.
  *

package/dist/utils/hover.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationOptions } from 'motion';
+import { type AnimationOptions } from 'motion';
 /**
  * Determine whether the current environment supports true hover.
  *

package/dist/utils/interaction.d.ts

@@ -1,3 +1,4 @@
+import type { AnimationOptions } from 'motion';
 /**
  * Build a reset record for whileTap on pointerup.
  *
@@ -24,4 +25,10 @@ export declare const buildTapResetRecord: (initial: Record<string, unknown>, ani
  * @param animateDef Animate keyframe record.
  * @return Cleanup function to remove listeners.
  */
-export declare const attachWhileTap: (el: HTMLElement, whileTap: Record<string, unknown> | undefined, initial?: Record<string, unknown>, animateDef?: Record<string, unknown>) => (() => void);
+export declare const attachWhileTap: (el: HTMLElement, whileTap: Record<string, unknown> | undefined, initial?: Record<string, unknown>, animateDef?: Record<string, unknown>, callbacks?: {
+    onTapStart?: () => void;
+    onTap?: () => void;
+    onTapCancel?: () => void;
+    hoverDef?: Record<string, unknown> | undefined;
+    hoverFallbackTransition?: AnimationOptions | undefined;
+}) => (() => void);

package/dist/utils/interaction.js

@@ -1,3 +1,4 @@
+import { isHoverCapable, splitHoverDefinition } from './hover';
 import { animate } from 'motion';
 /**
  * Build a reset record for whileTap on pointerup.
@@ -38,15 +39,139 @@ export const buildTapResetRecord = (initial, animateDef, whileTap) => {
  * @param animateDef Animate keyframe record.
  * @return Cleanup function to remove listeners.
  */
-export const attachWhileTap = (el, whileTap, initial, animateDef) => {
+export const attachWhileTap = (el, whileTap, initial, animateDef, callbacks) => {
     if (!whileTap)
         return () => { };
-    const handlePointerDown = () => {
+    let keyboardActive = false;
+    let activePointerId = null;
+    const handlePointerDown = (event) => {
+        // Capture pointer so we receive up/cancel even if pointer leaves the element
+        if (typeof event.pointerId === 'number') {
+            try {
+                if ('setPointerCapture' in el) {
+                    el.setPointerCapture(event.pointerId);
+                }
+            }
+            catch {
+                // noop if not supported
+            }
+            activePointerId = event.pointerId;
+            // Attach global listeners to catch off-element releases (even if capture unsupported)
+            window.addEventListener('pointerup', handlePointerUp);
+            window.addEventListener('pointercancel', handlePointerCancel);
+            document.addEventListener('pointerup', handlePointerUp);
+            document.addEventListener('pointercancel', handlePointerCancel);
+        }
+        callbacks?.onTapStart?.();
         animate(el, whileTap);
     };
-    const handlePointerUp = () => {
+    const reapplyHoverIfActive = () => {
+        if (!callbacks?.hoverDef)
+            return false;
+        if (!isHoverCapable())
+            return false;
+        try {
+            if (!el.matches(':hover'))
+                return false;
+        }
+        catch {
+            return false;
+        }
+        const { keyframes, transition } = splitHoverDefinition(callbacks.hoverDef);
+        animate(el, keyframes, (transition ?? callbacks.hoverFallbackTransition));
+        return true;
+    };
+    const handlePointerUp = (event) => {
+        if (typeof event.pointerId === 'number' && activePointerId !== null) {
+            if (event.pointerId !== activePointerId)
+                return;
+            try {
+                if ('releasePointerCapture' in el)
+                    el.releasePointerCapture(event.pointerId);
+            }
+            catch {
+                // noop
+            }
+            activePointerId = null;
+            window.removeEventListener('pointerup', handlePointerUp);
+            window.removeEventListener('pointercancel', handlePointerCancel);
+            document.removeEventListener('pointerup', handlePointerUp);
+            document.removeEventListener('pointercancel', handlePointerCancel);
+        }
+        callbacks?.onTap?.();
         if (!whileTap)
             return;
+        if (reapplyHoverIfActive())
+            return;
+        if (initial || animateDef) {
+            const resetRecord = buildTapResetRecord(initial ?? {}, animateDef ?? {}, whileTap ?? {});
+            if (Object.keys(resetRecord).length > 0) {
+                animate(el, resetRecord);
+            }
+        }
+    };
+    const handlePointerCancel = (event) => {
+        if (typeof event.pointerId === 'number' && activePointerId !== null) {
+            if (event.pointerId !== activePointerId)
+                return;
+            try {
+                if ('releasePointerCapture' in el)
+                    el.releasePointerCapture(event.pointerId);
+            }
+            catch {
+                // noop
+            }
+            activePointerId = null;
+            window.removeEventListener('pointerup', handlePointerUp);
+            window.removeEventListener('pointercancel', handlePointerCancel);
+            document.removeEventListener('pointerup', handlePointerUp);
+            document.removeEventListener('pointercancel', handlePointerCancel);
+        }
+        callbacks?.onTapCancel?.();
+        // On cancel, also restore baseline if available
+        if (initial || animateDef) {
+            const resetRecord = buildTapResetRecord(initial ?? {}, animateDef ?? {}, whileTap ?? {});
+            if (Object.keys(resetRecord).length > 0) {
+                animate(el, resetRecord);
+            }
+        }
+    };
+    const handleKeyDown = (e) => {
+        if (!(e.key === 'Enter' || e.key === ' ' || e.key === 'Space'))
+            return;
+        // Prevent page scroll/activation for Space
+        if (e.key === ' ' || e.key === 'Space')
+            e.preventDefault?.();
+        if (keyboardActive)
+            return;
+        keyboardActive = true;
+        callbacks?.onTapStart?.();
+        animate(el, whileTap);
+    };
+    const handleKeyUp = (e) => {
+        if (!(e.key === 'Enter' || e.key === ' ' || e.key === 'Space'))
+            return;
+        // Prevent page scroll/activation for Space
+        if (e.key === ' ' || e.key === 'Space')
+            e.preventDefault?.();
+        if (!keyboardActive)
+            return;
+        keyboardActive = false;
+        callbacks?.onTap?.();
+        if (reapplyHoverIfActive())
+            return;
+        if (initial || animateDef) {
+            const resetRecord = buildTapResetRecord(initial ?? {}, animateDef ?? {}, whileTap ?? {});
+            if (Object.keys(resetRecord).length > 0) {
+                animate(el, resetRecord);
+            }
+        }
+    };
+    const handleBlur = () => {
+        if (!keyboardActive)
+            return;
+        keyboardActive = false;
+        callbacks?.onTapCancel?.();
         if (initial || animateDef) {
             const resetRecord = buildTapResetRecord(initial ?? {}, animateDef ?? {}, whileTap ?? {});
             if (Object.keys(resetRecord).length > 0) {
@@ -56,10 +181,20 @@ export const attachWhileTap = (el, whileTap, initial, animateDef) => {
     };
     el.addEventListener('pointerdown', handlePointerDown);
     el.addEventListener('pointerup', handlePointerUp);
-    el.addEventListener('pointercancel', handlePointerUp);
+    el.addEventListener('pointercancel', handlePointerCancel);
+    el.addEventListener('keydown', handleKeyDown);
+    el.addEventListener('keyup', handleKeyUp);
+    el.addEventListener('blur', handleBlur);
     return () => {
         el.removeEventListener('pointerdown', handlePointerDown);
         el.removeEventListener('pointerup', handlePointerUp);
-        el.removeEventListener('pointercancel', handlePointerUp);
+        el.removeEventListener('pointercancel', handlePointerCancel);
+        window.removeEventListener('pointerup', handlePointerUp);
+        window.removeEventListener('pointercancel', handlePointerCancel);
+        document.removeEventListener('pointerup', handlePointerUp);
+        document.removeEventListener('pointercancel', handlePointerCancel);
+        el.removeEventListener('keydown', handleKeyDown);
+        el.removeEventListener('keyup', handleKeyUp);
+        el.removeEventListener('blur', handleBlur);
     };
 };

package/dist/utils/spring.d.ts

@@ -0,0 +1,38 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Spring configuration options.
+ *
+ * This is a minimal subset modeled after Motion's spring transition options.
+ * Values are tuned for sensible defaults, not parity.
+ *
+ * @typedef {Object} SpringOptions
+ * @property {number=} stiffness Spring stiffness (higher = snappier). Default 170.
+ * @property {number=} damping Spring damping (higher = less oscillation). Default 26.
+ * @property {number=} mass Mass of the object. Default 1.
+ * @property {number=} restDelta Threshold for absolute position delta to stop. Default 0.01.
+ * @property {number=} restSpeed Threshold for velocity magnitude to stop. Default 0.01.
+ */
+export type SpringOptions = {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    restDelta?: number;
+    restSpeed?: number;
+};
+/**
+ * Creates a spring-animated readable store. The store exposes `set` to
+ * animate towards a target, or `jump` to immediately set the value without
+ * animation. When constructed with another readable store, the spring
+ * automatically follows it.
+ *
+ * This is SSR-safe: On the server it returns a static store and no timers run.
+ *
+ * @template T
+ * @param {number|string|Readable<number|string>} source Initial value or a source store to follow.
+ * @param {SpringOptions=} options Spring configuration.
+ * @returns {Readable<number|string> & { set: (v: number|string) => void; jump: (v: number|string) => void; }}
+ */
+export declare const useSpring: (source: number | string | Readable<number | string>, options?: SpringOptions) => Readable<number | string> & {
+    set: (v: number | string) => void;
+    jump: (v: number | string) => void;
+};

package/dist/utils/spring.js

@@ -0,0 +1,157 @@
+import { readable, writable } from 'svelte/store';
+/**
+ * Parses a number or unit string into numeric value and unit.
+ * @param {number|string} v The input value.
+ * @returns {UnitValue} Parsed value and unit.
+ * @private
+ */
+const parseUnit = (v) => {
+    if (typeof v === 'number')
+        return { value: v, unit: '' };
+    const match = String(v).match(/^(-?\d*\.?\d+)(.*)$/);
+    if (!match || !match[1])
+        return { value: 0, unit: '' };
+    const parsed = Number.parseFloat(match[1]);
+    if (!Number.isFinite(parsed))
+        return { value: 0, unit: '' };
+    const unit = match[2] ?? '';
+    return { value: parsed, unit };
+};
+/**
+ * Formats a numeric value with a unit.
+ * @param {number} n Numeric value.
+ * @param {string} unit Unit suffix.
+ * @returns {number|string} Number or string with unit.
+ * @private
+ */
+const formatUnit = (n, unit) => (unit ? `${n}${unit}` : n);
+/**
+ * Creates a spring-animated readable store. The store exposes `set` to
+ * animate towards a target, or `jump` to immediately set the value without
+ * animation. When constructed with another readable store, the spring
+ * automatically follows it.
+ *
+ * This is SSR-safe: On the server it returns a static store and no timers run.
+ *
+ * @template T
+ * @param {number|string|Readable<number|string>} source Initial value or a source store to follow.
+ * @param {SpringOptions=} options Spring configuration.
+ * @returns {Readable<number|string> & { set: (v: number|string) => void; jump: (v: number|string) => void; }}
+ */
+export const useSpring = (source, options = {}) => {
+    if (typeof window === 'undefined') {
+        // Derive best-effort initial value for SSR to avoid hydration mismatch
+        let initial = 0;
+        if (typeof source === 'number' || typeof source === 'string') {
+            initial = source;
+        }
+        else if (source && typeof source === 'object') {
+            const anySource = source;
+            if (typeof anySource.get === 'function') {
+                const v = anySource.get();
+                if (typeof v === 'number' || typeof v === 'string')
+                    initial = v;
+            }
+            else if (typeof anySource.value === 'number' || typeof anySource.value === 'string') {
+                initial = anySource.value;
+            }
+        }
+        const store = readable(initial, () => { });
+        store.set = () => { };
+        store.jump = () => { };
+        return store;
+    }
+    const { stiffness = 170, damping = 26, mass = 1, restDelta = 0.01, restSpeed = 0.01 } = options;
+    const state = {
+        current: parseUnit(typeof source === 'object' ? 0 : source),
+        target: parseUnit(typeof source === 'object' ? 0 : source)
+    };
+    const unit = state.current.unit || state.target.unit;
+    const store = writable(formatUnit(state.current.value, unit));
+    let raf = 0;
+    let lastTime = 0;
+    let velocity = 0;
+    const step = (t) => {
+        if (!lastTime)
+            lastTime = t;
+        // Clamp dt to a safe range to avoid instability across large time gaps
+        const dt = Math.min(0.1, Math.max(0.001, (t - lastTime) / 1000));
+        lastTime = t;
+        const displacement = state.current.value - state.target.value;
+        // Spring force based on Hooke's Law: F = -k x; damping force: -c v
+        const spring = -stiffness * displacement;
+        const damper = -damping * velocity;
+        const accel = (spring + damper) / mass;
+        velocity += accel * dt;
+        state.current.value += velocity * dt;
+        const isNoVelocity = Math.abs(velocity) <= restSpeed;
+        const isNoDisplacement = Math.abs(state.current.value - state.target.value) <= restDelta;
+        const done = isNoVelocity && isNoDisplacement;
+        if (done) {
+            state.current.value = state.target.value;
+            store.set(formatUnit(state.current.value, unit));
+            raf = 0;
+            lastTime = 0;
+            return;
+        }
+        store.set(formatUnit(state.current.value, unit));
+        raf = requestAnimationFrame(step);
+    };
+    const start = () => {
+        if (raf)
+            return;
+        raf = requestAnimationFrame(step);
+    };
+    const api = {
+        set: (v) => {
+            state.target = parseUnit(v);
+            start();
+        },
+        jump: (v) => {
+            state.current = parseUnit(v);
+            state.target = parseUnit(v);
+            velocity = 0;
+            store.set(formatUnit(state.current.value, state.current.unit || state.target.unit));
+        }
+    };
+    // If following another store, subscribe and forward values to set()
+    if (typeof source === 'object' && 'subscribe' in source) {
+        let followSource = true;
+        const unsub = source.subscribe((v) => api.set(v));
+        const wrapped = readable(formatUnit(state.current.value, unit), (set) => {
+            const sub = store.subscribe(set);
+            return () => {
+                sub();
+                unsub();
+                followSource = false;
+                if (raf)
+                    cancelAnimationFrame(raf);
+            };
+        });
+        wrapped.set = (v) => {
+            if (followSource)
+                unsub();
+            followSource = false;
+            api.set(v);
+        };
+        wrapped.jump = (v) => {
+            if (followSource)
+                unsub();
+            followSource = false;
+            api.jump(v);
+        };
+        return wrapped;
+    }
+    // Standard readable wrapping internal writable
+    const wrapped = readable(formatUnit(state.current.value, unit), (set) => {
+        const sub = store.subscribe(set);
+        return () => {
+            sub();
+            if (raf)
+                cancelAnimationFrame(raf);
+        };
+    });
+    wrapped.set = api.set;
+    wrapped.jump = api.jump;
+    return wrapped;
+};

package/dist/utils/time.d.ts

@@ -0,0 +1,14 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Returns a time store that ticks once per animation frame.
+ *
+ * - Without an `id`, returns a fresh timeline per call.
+ * - With an `id`, callers sharing the same id receive the same store/timeline,
+ *   ensuring synchronized reads across components.
+ * - SSR-safe: Returns a static 0-valued store when `window` is unavailable.
+ *
+ * @param {string=} id Optional timeline identifier for sharing across calls.
+ * @returns {Readable<number>} A readable store of elapsed milliseconds.
+ * @see https://motion.dev/docs/react-use-time?platform=react
+ */
+export declare const useTime: (id?: string) => Readable<number>;

package/dist/utils/time.js

@@ -0,0 +1,68 @@
+import { readable } from 'svelte/store';
+const SSR_ZERO = readable(0, () => { });
+const sharedStores = new Map();
+// Clear shared timelines on HMR dispose to avoid stale entries across hot reloads
+if (import.meta &&
+    import.meta.hot) {
+    ;
+    import.meta.hot.dispose(() => {
+        sharedStores.clear();
+    });
+}
+/**
+ * Creates a new time store that updates once per animation frame.
+ *
+ * The store value represents elapsed milliseconds since the store was created.
+ * In SSR environments (no `window`), a static 0-valued store is returned.
+ *
+ * @returns {Readable<number>} A readable store of elapsed milliseconds.
+ * @see https://motion.dev/docs/react-use-time?platform=react
+ * @private
+ */
+const createTimeStore = () => {
+    if (typeof window === 'undefined')
+        return SSR_ZERO;
+    return readable(0, (set) => {
+        const start = performance.now();
+        let raf = 0;
+        /* c8 ignore start */
+        const loop = (t) => {
+            set(t - start);
+            raf = requestAnimationFrame(loop);
+        };
+        /* c8 ignore stop */
+        raf = requestAnimationFrame(loop);
+        return () => cancelAnimationFrame(raf);
+    });
+};
+/**
+ * Returns a time store that ticks once per animation frame.
+ *
+ * - Without an `id`, returns a fresh timeline per call.
+ * - With an `id`, callers sharing the same id receive the same store/timeline,
+ *   ensuring synchronized reads across components.
+ * - SSR-safe: Returns a static 0-valued store when `window` is unavailable.
+ *
+ * @param {string=} id Optional timeline identifier for sharing across calls.
+ * @returns {Readable<number>} A readable store of elapsed milliseconds.
+ * @see https://motion.dev/docs/react-use-time?platform=react
+ */
+export const useTime = (id) => {
+    if (!id)
+        return createTimeStore();
+    if (typeof window === 'undefined')
+        return SSR_ZERO;
+    const existing = sharedStores.get(id);
+    if (existing)
+        return existing;
+    const base = createTimeStore();
+    const store = readable(0, (set) => {
+        const unsub = base.subscribe(set);
+        return () => {
+            unsub();
+            sharedStores.delete(id);
+        };
+    });
+    sharedStores.set(id, store);
+    return store;
+};

package/dist/utils/transform.d.ts

@@ -0,0 +1,42 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Options for range-mapping transform.
+ *
+ * - clamp: If true, clamps the input to the active segment bounds.
+ * - ease: A single easing function or one per segment to shape interpolation.
+ * - mixer: Custom mixer factory to interpolate non-numeric outputs.
+ *
+ * @see https://motion.dev/docs/react-use-transform?platform=react
+ */
+export type TransformOptions = {
+    clamp?: boolean;
+    ease?: ((t: number) => number) | Array<(t: number) => number>;
+    mixer?: (from: unknown, to: unknown) => (t: number) => unknown;
+};
+/**
+ * Clamps a numeric value between two bounds, irrespective of their order.
+ *
+ * @param val Current value.
+ * @param a First bound.
+ * @param b Second bound.
+ * @returns Value clamped to [min(a,b), max(a,b)].
+ */
+export declare const clampBidirectional: (val: number, a: number, b: number) => number;
+/**
+ * Creates a derived Svelte store that transforms values.
+ *
+ * Two supported forms (API parity with Motion's useTransform):
+ * - Mapping form: Map a numeric source across input/output ranges.
+ *   Example: `useTransform(src, [0, 100], [0, 1], { clamp: true })`
+ * - Function form: Recompute from a function based on dependency stores.
+ *   Example: `useTransform(() => compute(), [depA, depB])`
+ *
+ * @template T
+ * @param {Readable<number>|(() => T)} sourceOrCompute Numeric source store (mapping form), or compute function (function form).
+ * @param {number[]|Readable<unknown>[]} inputOrDeps Input stops (mapping) or dependency stores (function form).
+ * @param {T[]=} output Output stops (mapping form only). Must match input length.
+ * @param {TransformOptions=} options Mapping options (mapping form only).
+ * @returns {Readable<T>} A derived Svelte readable store.
+ * @see https://motion.dev/docs/react-use-transform?platform=react
+ */
+export declare const useTransform: <T = number>(sourceOrCompute: Readable<number> | (() => T), inputOrDeps: number[] | Readable<unknown>[], output?: T[], options?: TransformOptions) => Readable<T>;

package/dist/utils/transform.js

@@ -0,0 +1,129 @@
+import { derived, readable } from 'svelte/store';
+/**
+ * Creates a linear mixer function for numeric values.
+ *
+ * @param from Starting numeric value.
+ * @param to Ending numeric value.
+ * @returns Function that linearly interpolates between from→to for progress t∈[0,1].
+ * @private
+ */
+const linearMix = (from, to) => (t) => from + (to - from) * t;
+/**
+ * Clamps a numeric value between two bounds, irrespective of their order.
+ *
+ * @param val Current value.
+ * @param a First bound.
+ * @param b Second bound.
+ * @returns Value clamped to [min(a,b), max(a,b)].
+ */
+export const clampBidirectional = (val, a, b) => {
+    const lower = a < b ? a : b;
+    const upper = a < b ? b : a;
+    return Math.min(Math.max(val, lower), upper);
+};
+/**
+ * Finds the segment index i such that x lies between input[i] and input[i+1].
+ * Handles both ascending and descending input ranges.
+ *
+ * @param input Monotonic list of input stops.
+ * @param x Current input value.
+ * @returns Segment index in range [0, input.length - 2].
+ * @private
+ */
+const findSegment = (input, x) => {
+    if (input.length < 2)
+        return 0;
+    const first = input[0];
+    const second = input[1];
+    const ascending = second > first;
+    if (ascending) {
+        if (x <= first)
+            return 0;
+        for (let i = 1; i < input.length; i++) {
+            const curr = input[i];
+            if (x <= curr)
+                return i - 1;
+        }
+        return input.length - 2;
+    }
+    else {
+        if (x >= first)
+            return 0;
+        for (let i = 1; i < input.length; i++) {
+            const curr = input[i];
+            if (x >= curr)
+                return i - 1;
+        }
+        return input.length - 2;
+    }
+};
+/**
+ * Creates a derived Svelte store that transforms values.
+ *
+ * Two supported forms (API parity with Motion's useTransform):
+ * - Mapping form: Map a numeric source across input/output ranges.
+ *   Example: `useTransform(src, [0, 100], [0, 1], { clamp: true })`
+ * - Function form: Recompute from a function based on dependency stores.
+ *   Example: `useTransform(() => compute(), [depA, depB])`
+ *
+ * @template T
+ * @param {Readable<number>|(() => T)} sourceOrCompute Numeric source store (mapping form), or compute function (function form).
+ * @param {number[]|Readable<unknown>[]} inputOrDeps Input stops (mapping) or dependency stores (function form).
+ * @param {T[]=} output Output stops (mapping form only). Must match input length.
+ * @param {TransformOptions=} options Mapping options (mapping form only).
+ * @returns {Readable<T>} A derived Svelte readable store.
+ * @see https://motion.dev/docs/react-use-transform?platform=react
+ */
+export const useTransform = (sourceOrCompute, inputOrDeps, output, options = {}) => {
+    // Function form: (compute, deps)
+    if (typeof sourceOrCompute === 'function') {
+        const compute = sourceOrCompute;
+        const deps = inputOrDeps;
+        if (!deps || deps.length === 0)
+            return readable(compute());
+        return derived(deps, () => compute());
+    }
+    // Mapping form: (source, input, output, options)
+    const source = sourceOrCompute;
+    const input = inputOrDeps;
+    const out = (output ?? []);
+    const { clamp = true, ease, mixer } = options;
+    if (input.length !== out.length) {
+        throw new Error(`useTransform: input and output arrays must be the same length (input: ${input.length}, output: ${out.length})`);
+    }
+    const easings = Array.isArray(ease)
+        ? ease
+        : ease
+            ? new Array(Math.max(0, out.length - 1)).fill(ease)
+            : [];
+    return derived(source, (x) => {
+        if (input.length === 0)
+            return out[0];
+        if (input.length === 1)
+            return out[0];
+        const seg = findSegment(input, x);
+        const i0 = input[seg];
+        const i1 = input[seg + 1];
+        const o0 = out[seg];
+        const o1 = out[seg + 1];
+        // Runtime validation to avoid non-null assertions
+        if (i0 === undefined || i1 === undefined || o0 === undefined || o1 === undefined) {
+            console.warn('useTransform: Invalid segment bounds', {
+                seg,
+                inputLength: input.length,
+                outputLength: out.length
+            });
+            return out[0];
+        }
+        const localClamp = clamp ? clampBidirectional : (val) => val;
+        const progress = i0 === i1 ? 0 : (localClamp(x, i0, i1) - i0) / (i1 - i0);
+        const e = easings[seg];
+        const p = e ? e(progress) : progress;
+        const mix = mixer
+            ? mixer(o0, o1)
+            : typeof o0 === 'number' && typeof o1 === 'number'
+                ? linearMix(o0, o1)
+                : (_t) => (p < 0.5 ? o0 : o1);
+        return mix(p);
+    });
+};

package/package.json

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