@humanspeak/svelte-motion 0.1.26 → 0.1.27

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

@@ -8,7 +8,7 @@ export declare const getMotionConfig: () => MotionConfigProps | undefined;
 /**
  * Provide motion configuration to descendant components via Svelte context.
  *
- * @param motionConfig The configuration to propagate (e.g. `reducedMotion`, `transition`).
+ * @param motionConfig The configuration to propagate (e.g. `transition`).
  * @returns The same `MotionConfigProps` that was set.
  */
 export declare const createMotionConfig: (motionConfig: MotionConfigProps) => MotionConfigProps;

package/dist/components/motionConfig.context.js

@@ -11,7 +11,7 @@ export const getMotionConfig = () => {
 /**
  * Provide motion configuration to descendant components via Svelte context.
  *
- * @param motionConfig The configuration to propagate (e.g. `reducedMotion`, `transition`).
+ * @param motionConfig The configuration to propagate (e.g. `transition`).
  * @returns The same `MotionConfigProps` that was set.
  */
 export const createMotionConfig = (motionConfig) => {

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition,
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
 export { useMotionTemplate } from './utils/motionTemplate';
+export { useMotionValueEvent } from './utils/motionValueEvent';
+export { useScroll } from './utils/scroll';
 export { useSpring } from './utils/spring';
 export { useVelocity } from './utils/velocity';
 /**

package/dist/index.js

@@ -12,6 +12,8 @@ export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } f
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
 export { useMotionTemplate } from './utils/motionTemplate';
+export { useMotionValueEvent } from './utils/motionValueEvent';
+export { useScroll } from './utils/scroll';
 export { useSpring } from './utils/spring';
 export { useVelocity } from './utils/velocity';
 /**

package/dist/utils/dragMath.d.ts

@@ -17,5 +17,20 @@ export type ConstraintElastic = {
  * Apply float-safe constraints with optional elastic mixing.
  * Mirrors Framer Motion behavior: clamp via Math.min/Math.max with no rounding.
  * If `elastic` provided, blends toward the bound using its side-specific factor.
+ *
+ * @param point The unconstrained value to clamp.
+ * @param range Min/max boundaries. Either or both may be omitted.
+ * @param elastic Optional per-side elastic factor(s) in [0,1]. When provided,
+ *   the value is interpolated toward the boundary instead of hard-clamped.
+ * @returns The constrained (and optionally elastically blended) value.
+ *
+ * @example
+ * ```ts
+ * // Hard clamp to [0, 100]
+ * applyConstraints(120, { min: 0, max: 100 }) // 100
+ *
+ * // Elastic overshoot (50 % blend toward max)
+ * applyConstraints(120, { min: 0, max: 100 }, 0.5) // 110
+ * ```
  */
 export declare const applyConstraints: (point: number, range: ConstraintRange, elastic?: ConstraintElastic) => number;

package/dist/utils/dragMath.js

@@ -7,6 +7,21 @@ export const mixNumber = (from, to, t) => from + (to - from) * t;
  * Apply float-safe constraints with optional elastic mixing.
  * Mirrors Framer Motion behavior: clamp via Math.min/Math.max with no rounding.
  * If `elastic` provided, blends toward the bound using its side-specific factor.
+ *
+ * @param point The unconstrained value to clamp.
+ * @param range Min/max boundaries. Either or both may be omitted.
+ * @param elastic Optional per-side elastic factor(s) in [0,1]. When provided,
+ *   the value is interpolated toward the boundary instead of hard-clamped.
+ * @returns The constrained (and optionally elastically blended) value.
+ *
+ * @example
+ * ```ts
+ * // Hard clamp to [0, 100]
+ * applyConstraints(120, { min: 0, max: 100 }) // 100
+ *
+ * // Elastic overshoot (50 % blend toward max)
+ * applyConstraints(120, { min: 0, max: 100 }, 0.5) // 110
+ * ```
  */
 export const applyConstraints = (point, range, elastic) => {
     const hasMin = range.min !== undefined;

package/dist/utils/inertia.d.ts

@@ -42,5 +42,15 @@ export type StepResult = {
  * @param bounds Min/max boundaries for the axis.
  * @param opts Physics parameters for decay and boundary spring.
  * @returns A function that accepts elapsed time in ms and returns the current `StepResult`.
+ *
+ * @example
+ * ```ts
+ * const step = createInertiaToBoundary(
+ *     { value: 50, velocity: 200 },
+ *     { min: 0, max: 300 },
+ *     { timeConstantMs: 350, restDelta: 0.5, restSpeed: 10, bounceStiffness: 500, bounceDamping: 25 }
+ * )
+ * const { value, done } = step(16) // advance 16 ms
+ * ```
  */
 export declare const createInertiaToBoundary: (initial: AxisState, bounds: Bounds, opts: InertiaHandoffOptions) => ((tMs: number) => StepResult);

package/dist/utils/inertia.js

@@ -56,6 +56,16 @@ const solveCrossTimeMs = (x0, v0, tauMs, boundary) => {
  * @param bounds Min/max boundaries for the axis.
  * @param opts Physics parameters for decay and boundary spring.
  * @returns A function that accepts elapsed time in ms and returns the current `StepResult`.
+ *
+ * @example
+ * ```ts
+ * const step = createInertiaToBoundary(
+ *     { value: 50, velocity: 200 },
+ *     { min: 0, max: 300 },
+ *     { timeConstantMs: 350, restDelta: 0.5, restSpeed: 10, bounceStiffness: 500, bounceDamping: 25 }
+ * )
+ * const { value, done } = step(16) // advance 16 ms
+ * ```
  */
 export const createInertiaToBoundary = (initial, bounds, opts) => {
     const min = bounds.min;

package/dist/utils/layoutId.d.ts

@@ -21,6 +21,13 @@ export declare const layoutIdRegistry: LayoutIdRegistry;
  * Get the global layoutId registry.
  *
  * @returns The singleton `LayoutIdRegistry` instance.
+ *
+ * @example
+ * ```ts
+ * const registry = getLayoutIdRegistry()
+ * registry.snapshot('hero', element.getBoundingClientRect())
+ * const entry = registry.consume('hero') // one-shot: returns and deletes
+ * ```
  */
 export declare const getLayoutIdRegistry: () => LayoutIdRegistry;
 export {};

package/dist/utils/layoutId.js

@@ -19,6 +19,13 @@ export const layoutIdRegistry = {
  * Get the global layoutId registry.
  *
  * @returns The singleton `LayoutIdRegistry` instance.
+ *
+ * @example
+ * ```ts
+ * const registry = getLayoutIdRegistry()
+ * registry.snapshot('hero', element.getBoundingClientRect())
+ * const entry = registry.consume('hero') // one-shot: returns and deletes
+ * ```
  */
 export const getLayoutIdRegistry = () => {
     return layoutIdRegistry;

package/dist/utils/motionValueEvent.d.ts

@@ -0,0 +1,29 @@
+import type { Readable } from 'svelte/store';
+/**
+ * Subscribes to a Svelte store and fires a callback on every *change*,
+ * skipping the initial synchronous emission that Svelte stores produce
+ * on subscribe.
+ *
+ * Returns an unsubscribe function. Use inside `$effect` or `onDestroy`
+ * for automatic cleanup.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useMotionValueEvent, useSpring } from '@humanspeak/svelte-motion'
+ *   import { onDestroy } from 'svelte'
+ *
+ *   const x = useSpring(0)
+ *   const unsub = useMotionValueEvent(x, 'change', (latest) => {
+ *     console.log('x changed to', latest)
+ *   })
+ *   onDestroy(unsub)
+ * </script>
+ * ```
+ *
+ * @param store A readable Svelte store to observe.
+ * @param event The event type — currently only `'change'` is supported.
+ * @param callback Invoked with the latest value on each change after the initial emission.
+ * @returns An unsubscribe function.
+ */
+export declare const useMotionValueEvent: <T>(store: Readable<T>, event: "change", callback: (latest: T) => void) => (() => void);

package/dist/utils/motionValueEvent.js

@@ -0,0 +1,38 @@
+/**
+ * Subscribes to a Svelte store and fires a callback on every *change*,
+ * skipping the initial synchronous emission that Svelte stores produce
+ * on subscribe.
+ *
+ * Returns an unsubscribe function. Use inside `$effect` or `onDestroy`
+ * for automatic cleanup.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useMotionValueEvent, useSpring } from '@humanspeak/svelte-motion'
+ *   import { onDestroy } from 'svelte'
+ *
+ *   const x = useSpring(0)
+ *   const unsub = useMotionValueEvent(x, 'change', (latest) => {
+ *     console.log('x changed to', latest)
+ *   })
+ *   onDestroy(unsub)
+ * </script>
+ * ```
+ *
+ * @param store A readable Svelte store to observe.
+ * @param event The event type — currently only `'change'` is supported.
+ * @param callback Invoked with the latest value on each change after the initial emission.
+ * @returns An unsubscribe function.
+ */
+export const useMotionValueEvent = (store, event, callback) => {
+    let initialized = false;
+    const unsub = store.subscribe((value) => {
+        if (!initialized) {
+            initialized = true;
+            return;
+        }
+        callback(value);
+    });
+    return unsub;
+};

package/dist/utils/scroll.d.ts

@@ -0,0 +1,68 @@
+import { type Readable } from 'svelte/store';
+/**
+ * A scroll offset edge defined as a string (e.g. `"start"`, `"end"`, `"center"`)
+ * or a number (0–1 progress). Each offset entry is a pair of `[target, container]`.
+ */
+type ScrollOffset = Array<[number | string, number | string]> | string[];
+/**
+ * An element reference — either an element directly or a getter function
+ * that returns one (useful with Svelte's `bind:this` where the element
+ * isn't available until after mount).
+ */
+type ElementOrGetter = HTMLElement | (() => HTMLElement | undefined);
+/**
+ * Options accepted by `useScroll`.
+ */
+type UseScrollOptions = {
+    /** Scrollable container to track. Defaults to the page. Accepts an element or a getter function. */
+    container?: ElementOrGetter;
+    /** Target element to track position of within the container. Accepts an element or a getter function. */
+    target?: ElementOrGetter;
+    /** Scroll offset configuration for element position tracking. */
+    offset?: ScrollOffset;
+    /** Which axis to use for the single-axis `progress` value supplied to `scroll()`. */
+    axis?: 'x' | 'y';
+};
+/**
+ * Return type of `useScroll` — four readable Svelte stores representing
+ * scroll position and normalised progress for both axes.
+ */
+type UseScrollReturn = {
+    scrollX: Readable<number>;
+    scrollY: Readable<number>;
+    scrollXProgress: Readable<number>;
+    scrollYProgress: Readable<number>;
+};
+/**
+ * Creates scroll-linked Svelte stores for building scroll-driven animations
+ * such as progress indicators and parallax effects.
+ *
+ * When the returned stores are used with `opacity` / `transform` CSS properties
+ * the animations can be hardware accelerated by the browser.
+ *
+ * SSR-safe: returns static `readable(0)` stores on the server.
+ *
+ * `container` and `target` accept either an `HTMLElement` directly or a
+ * getter function `() => HTMLElement | undefined`. This is useful with
+ * Svelte's `bind:this` where the element isn't available until after mount.
+ * When a getter is provided, element resolution is deferred until the
+ * first subscriber arrives, and if the element isn't available yet the
+ * stores poll on each animation frame until it is.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
+ *
+ *   const { scrollYProgress } = useScroll()
+ *   const scaleX = useSpring(scrollYProgress)
+ * </script>
+ *
+ * <div style="transform: scaleX({$scaleX}); transform-origin: left;" />
+ * ```
+ *
+ * @param options Optional scroll tracking configuration.
+ * @returns An object with `scrollX`, `scrollY`, `scrollXProgress`, and `scrollYProgress` stores.
+ */
+export declare const useScroll: (options?: UseScrollOptions) => UseScrollReturn;
+export {};

package/dist/utils/scroll.js

@@ -0,0 +1,119 @@
+import { scroll } from 'motion';
+import { readable, writable } from 'svelte/store';
+/**
+ * Resolves an element-or-getter to an HTMLElement (or undefined).
+ */
+const resolveElement = (ref) => {
+    if (!ref)
+        return undefined;
+    return typeof ref === 'function' ? ref() : ref;
+};
+/**
+ * Creates scroll-linked Svelte stores for building scroll-driven animations
+ * such as progress indicators and parallax effects.
+ *
+ * When the returned stores are used with `opacity` / `transform` CSS properties
+ * the animations can be hardware accelerated by the browser.
+ *
+ * SSR-safe: returns static `readable(0)` stores on the server.
+ *
+ * `container` and `target` accept either an `HTMLElement` directly or a
+ * getter function `() => HTMLElement | undefined`. This is useful with
+ * Svelte's `bind:this` where the element isn't available until after mount.
+ * When a getter is provided, element resolution is deferred until the
+ * first subscriber arrives, and if the element isn't available yet the
+ * stores poll on each animation frame until it is.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
+ *
+ *   const { scrollYProgress } = useScroll()
+ *   const scaleX = useSpring(scrollYProgress)
+ * </script>
+ *
+ * <div style="transform: scaleX({$scaleX}); transform-origin: left;" />
+ * ```
+ *
+ * @param options Optional scroll tracking configuration.
+ * @returns An object with `scrollX`, `scrollY`, `scrollXProgress`, and `scrollYProgress` stores.
+ */
+export const useScroll = (options) => {
+    if (typeof window === 'undefined') {
+        return {
+            scrollX: readable(0),
+            scrollY: readable(0),
+            scrollXProgress: readable(0),
+            scrollYProgress: readable(0)
+        };
+    }
+    const stores = {
+        scrollX: writable(0),
+        scrollY: writable(0),
+        scrollXProgress: writable(0),
+        scrollYProgress: writable(0)
+    };
+    let cleanup;
+    let pollRaf = 0;
+    let subscriberCount = 0;
+    const attach = () => {
+        if (cleanup)
+            return;
+        // Resolve elements — they may not be available yet when using getters
+        const container = resolveElement(options?.container);
+        const target = resolveElement(options?.target);
+        // If a getter was provided but returned undefined, the element isn't
+        // mounted yet. Poll on the next frame until it appears.
+        const needsContainer = options?.container && !container;
+        const needsTarget = options?.target && !target;
+        if (needsContainer || needsTarget) {
+            if (!pollRaf) {
+                pollRaf = requestAnimationFrame(() => {
+                    pollRaf = 0;
+                    attach();
+                });
+            }
+            return;
+        }
+        cleanup = scroll((_progress, info) => {
+            stores.scrollX.set(info.x.current);
+            stores.scrollY.set(info.y.current);
+            stores.scrollXProgress.set(info.x.progress);
+            stores.scrollYProgress.set(info.y.progress);
+        }, {
+            container,
+            target,
+            offset: options?.offset,
+            axis: options?.axis
+        });
+    };
+    const detach = () => {
+        if (subscriberCount <= 0) {
+            if (pollRaf) {
+                cancelAnimationFrame(pollRaf);
+                pollRaf = 0;
+            }
+            if (cleanup) {
+                cleanup();
+                cleanup = undefined;
+            }
+        }
+    };
+    const make = (key) => readable(0, (set) => {
+        subscriberCount++;
+        const unsub = stores[key].subscribe(set);
+        attach();
+        return () => {
+            unsub();
+            subscriberCount--;
+            detach();
+        };
+    });
+    return {
+        scrollX: make('scrollX'),
+        scrollY: make('scrollY'),
+        scrollXProgress: make('scrollXProgress'),
+        scrollYProgress: make('scrollYProgress')
+    };
+};

package/dist/utils/testing.d.ts

@@ -3,5 +3,10 @@
  *
  * @param ms Delay in milliseconds.
  * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * ```ts
+ * await sleep(100) // pause for 100 ms
+ * ```
  */
 export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/utils/testing.js

@@ -3,5 +3,10 @@
  *
  * @param ms Delay in milliseconds.
  * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * ```ts
+ * await sleep(100) // pause for 100 ms
+ * ```
  */
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/package.json

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