@humanspeak/svelte-motion 0.1.1 → 0.1.2

package/README.md

@@ -79,6 +79,7 @@ This package carefully selects its dependencies to provide a robust and maintain
 | [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) |
@@ -111,6 +112,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

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/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/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/package.json

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