@humanspeak/svelte-motion 0.1.23 → 0.1.25

package/README.md

@@ -44,7 +44,7 @@ Goal: Framer Motion API parity for Svelte where common React examples can be tra
 | Drag (`drag`, constraints, momentum, controls, callbacks) | Supported                       |
 | `AnimatePresence` (`initial`, `mode`, `onExitComplete`)   | Supported                       |
 | Layout (`layout`, `layout="position"`)                    | Supported (single-element FLIP) |
-| Shared layout (`layoutId`)                                | Not yet supported               |
+| Shared layout (`layoutId`)                                | Supported                       |
 | Pan gesture API (`whilePan`, `onPan*`)                    | Not yet supported               |
 | `MotionConfig` parity beyond `transition`                 | Partial                         |
 | `reducedMotion`, `features`, `transformPagePoint`         | Not yet supported               |
@@ -231,9 +231,11 @@ Single-element FLIP layout animation:
 ## Utilities
 
 - `useAnimationFrame`
+- `useMotionTemplate`
 - `useSpring`
 - `useTime`
 - `useTransform`
+- `useVelocity`
 - `styleString`
 - `stringifyStyleObject` (deprecated)
 - `createDragControls`

package/dist/html/_MotionContainer.svelte

@@ -57,6 +57,7 @@
         isSVGTag,
         SVG_NAMESPACE
     } from '../utils/svg'
+    import { getLayoutIdRegistry } from '../utils/layoutId'
 
     type Props = MotionProps & {
         children?: Snippet
@@ -107,6 +108,7 @@
         dragListener: dragListenerProp,
         dragControls: dragControlsProp,
         layout: layoutProp,
+        layoutId: layoutIdProp,
         ref: element = $bindable(null),
         ...rest
     }: Props = $props()
@@ -117,6 +119,9 @@
     // Get presence context to check if we're inside AnimatePresence
     const context = getAnimatePresenceContext()
 
+    // Get layoutId registry (provided by AnimatePresence or a parent LayoutGroup)
+    const layoutIdRegistry = getLayoutIdRegistry()
+
     // Get current presence depth (0 = direct child of AnimatePresence, undefined = not in AnimatePresence)
     const presenceDepth = getPresenceDepth()
 
@@ -163,6 +168,36 @@
         })
     }
 
+    // Keep a live snapshot of the layoutId element's rect so the next element can FLIP from it.
+    // We store the last-known-good rect and push it to the registry on cleanup,
+    // because onDestroy fires after the element is removed from DOM (rect would be zeros).
+    let layoutIdLastRect: DOMRect | null = null
+    $effect(() => {
+        if (!(element && layoutIdProp && layoutIdRegistry)) return
+
+        // Capture rect on every frame while mounted
+        let rafId: number
+        const captureRect = () => {
+            if (element) {
+                layoutIdLastRect = element.getBoundingClientRect()
+            }
+            rafId = requestAnimationFrame(captureRect)
+        }
+        rafId = requestAnimationFrame(captureRect)
+
+        // On cleanup (before DOM removal), push last-known rect to registry
+        return () => {
+            cancelAnimationFrame(rafId)
+            if (layoutIdLastRect && layoutIdProp) {
+                layoutIdRegistry.snapshot(
+                    layoutIdProp,
+                    layoutIdLastRect,
+                    (mergedTransition ?? {}) as AnimationOptions
+                )
+            }
+        }
+    })
+
     // Reactively update registration when element/exit/transition props change
     $effect(() => {
         if (element && context && resolvedExit) {
@@ -611,6 +646,25 @@
         }
     })
 
+    // Shared layout animation via layoutId.
+    // On mount, consume the previous snapshot and FLIP from its position.
+    $effect(() => {
+        if (!(element && layoutIdProp && layoutIdRegistry && isLoaded === 'ready')) return
+
+        const prev = layoutIdRegistry.consume(layoutIdProp)
+        if (!prev) return // First appearance, no animation needed
+
+        const next = measureRect(element)
+        const transforms = computeFlipTransforms(prev.rect, next, true)
+
+        setCompositorHints(element, true)
+        runFlipAnimation(
+            element,
+            transforms,
+            (prev.transition ?? mergedTransition ?? {}) as AnimationOptions
+        )
+    })
+
     // whileTap handling via motion-dom's press()
     $effect(() => {
         if (!(element && isLoaded === 'ready' && isNotEmpty(whileTapProp))) return

package/dist/index.d.ts

@@ -8,7 +8,9 @@ export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } f
 export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionOnInViewEnd, MotionOnInViewStart, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, Variants } from './types';
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
+export { useMotionTemplate } from './utils/motionTemplate';
 export { useSpring } from './utils/spring';
+export { useVelocity } from './utils/velocity';
 /**
  * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
  */

package/dist/index.js

@@ -11,7 +11,9 @@ export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cub
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
+export { useMotionTemplate } from './utils/motionTemplate';
 export { useSpring } from './utils/spring';
+export { useVelocity } from './utils/velocity';
 /**
  * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
  */

package/dist/types.d.ts

@@ -278,6 +278,8 @@ export type MotionProps = {
     class?: string;
     /** Enable FLIP layout animations; "position" limits to translation only */
     layout?: boolean | 'position';
+    /** Shared layout animation identifier. Elements with matching layoutId animate between positions. */
+    layoutId?: string;
     /** Ref to the element */
     ref?: HTMLElement | null;
     /** Enable drag gestures. true for both axes, or lock to 'x'/'y'. */

package/dist/utils/layoutId.d.ts

@@ -0,0 +1,24 @@
+import type { AnimationOptions } from 'motion';
+/**
+ * Snapshot stored for a layoutId when an element unmounts.
+ */
+type LayoutIdEntry = {
+    rect: DOMRect;
+    transition?: AnimationOptions;
+};
+/**
+ * Registry that stores last-known rect + transition for each layoutId.
+ *
+ * - `snapshot(id, rect, transition)` — called when an element with a layoutId unmounts.
+ * - `consume(id)` — called by a newly mounted element. Returns and **deletes** the entry (one-shot).
+ */
+export type LayoutIdRegistry = {
+    snapshot(id: string, rect: DOMRect, transition?: AnimationOptions): void;
+    consume(id: string): LayoutIdEntry | undefined;
+};
+export declare const layoutIdRegistry: LayoutIdRegistry;
+/**
+ * Get the global layoutId registry.
+ */
+export declare function getLayoutIdRegistry(): LayoutIdRegistry;
+export {};

package/dist/utils/layoutId.js

@@ -0,0 +1,23 @@
+/**
+ * Module-level singleton registry shared across the entire component tree.
+ * This matches React Framer Motion's behavior where layoutId is shared globally
+ * (or within a LayoutGroup, which we can add later).
+ */
+const entries = new Map();
+export const layoutIdRegistry = {
+    snapshot(id, rect, transition) {
+        entries.set(id, { rect, transition });
+    },
+    consume(id) {
+        const entry = entries.get(id);
+        if (entry)
+            entries.delete(id);
+        return entry;
+    }
+};
+/**
+ * Get the global layoutId registry.
+ */
+export function getLayoutIdRegistry() {
+    return layoutIdRegistry;
+}

package/dist/utils/motionTemplate.d.ts

@@ -0,0 +1,21 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Tagged template literal that creates a derived store from interpolated
+ * readable stores. When any input store changes, the resulting store
+ * recomputes the template string.
+ *
+ * SSR-safe: `derived` from svelte/store works on the server.
+ *
+ * @example
+ * ```ts
+ * const blur = useSpring(0)
+ * const filter = useMotionTemplate`blur(${blur}px)`
+ * // $filter → "blur(0px)"
+ * ```
+ *
+ * @param strings Static template string parts.
+ * @param values Readable stores to interpolate.
+ * @returns A readable store of the composed string.
+ * @see https://motion.dev/docs/react-use-motion-template
+ */
+export declare const useMotionTemplate: (strings: TemplateStringsArray, ...values: Readable<number | string>[]) => Readable<string>;

package/dist/utils/motionTemplate.js

@@ -0,0 +1,33 @@
+import { derived } from 'svelte/store';
+/**
+ * Tagged template literal that creates a derived store from interpolated
+ * readable stores. When any input store changes, the resulting store
+ * recomputes the template string.
+ *
+ * SSR-safe: `derived` from svelte/store works on the server.
+ *
+ * @example
+ * ```ts
+ * const blur = useSpring(0)
+ * const filter = useMotionTemplate`blur(${blur}px)`
+ * // $filter → "blur(0px)"
+ * ```
+ *
+ * @param strings Static template string parts.
+ * @param values Readable stores to interpolate.
+ * @returns A readable store of the composed string.
+ * @see https://motion.dev/docs/react-use-motion-template
+ */
+export const useMotionTemplate = (strings, ...values) => {
+    if (values.length === 0)
+        return derived([], () => strings[0] ?? '');
+    return derived(values, (current) => {
+        let result = '';
+        for (let i = 0; i < strings.length; i++) {
+            result += strings[i] ?? '';
+            if (i < current.length)
+                result += String(current[i]);
+        }
+        return result;
+    });
+};

package/dist/utils/velocity.d.ts

@@ -0,0 +1,15 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Creates a readable store that tracks the velocity of a source store's value.
+ *
+ * Uses `motionValue` from motion-dom for built-in velocity tracking with
+ * timestamps. Polls velocity via `requestAnimationFrame` and settles to 0
+ * when movement stops.
+ *
+ * SSR-safe: returns a static `readable(0)` on the server.
+ *
+ * @param source A readable store of numeric or unit-string values.
+ * @returns A readable store of the current velocity in units/second.
+ * @see https://motion.dev/docs/react-use-velocity
+ */
+export declare const useVelocity: (source: Readable<number | string>) => Readable<number>;

package/dist/utils/velocity.js

@@ -0,0 +1,62 @@
+import { motionValue } from 'motion-dom';
+import { readable, writable } from 'svelte/store';
+/**
+ * Parses a numeric value from a number or unit string (e.g. "100px" → 100).
+ */
+const parseNumeric = (v) => {
+    if (typeof v === 'number')
+        return v;
+    const parsed = Number.parseFloat(String(v));
+    return Number.isFinite(parsed) ? parsed : 0;
+};
+/**
+ * Creates a readable store that tracks the velocity of a source store's value.
+ *
+ * Uses `motionValue` from motion-dom for built-in velocity tracking with
+ * timestamps. Polls velocity via `requestAnimationFrame` and settles to 0
+ * when movement stops.
+ *
+ * SSR-safe: returns a static `readable(0)` on the server.
+ *
+ * @param source A readable store of numeric or unit-string values.
+ * @returns A readable store of the current velocity in units/second.
+ * @see https://motion.dev/docs/react-use-velocity
+ */
+export const useVelocity = (source) => {
+    if (typeof window === 'undefined')
+        return readable(0, () => { });
+    const mv = motionValue(0);
+    const store = writable(0);
+    let raf = 0;
+    let settled = true;
+    const poll = () => {
+        const v = mv.getVelocity();
+        store.set(v);
+        if (Math.abs(v) < 0.001) {
+            settled = true;
+            store.set(0);
+            raf = 0;
+            return;
+        }
+        raf = requestAnimationFrame(poll);
+    };
+    const startPolling = () => {
+        if (!settled)
+            return;
+        settled = false;
+        raf = requestAnimationFrame(poll);
+    };
+    return readable(0, (set) => {
+        const unsubStore = store.subscribe(set);
+        const unsubSource = source.subscribe((v) => {
+            mv.set(parseNumeric(v));
+            startPolling();
+        });
+        return () => {
+            unsubStore();
+            unsubSource();
+            if (raf)
+                cancelAnimationFrame(raf);
+        };
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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",
@@ -111,7 +111,7 @@
     "svelte": "^5.0.0"
   },
   "volta": {
-    "node": "24.12.0"
+    "node": "22.16.0"
   },
   "publishConfig": {
     "access": "public"