@humanspeak/svelte-motion 0.4.8 → 0.5.0

package/dist/utils/scroll.svelte.js

@@ -0,0 +1,259 @@
+import { scroll } from 'motion';
+import { cancelMicrotask, microtask, motionValue, supportsScrollTimeline, supportsViewTimeline } from 'motion-dom';
+import { augmentMotionValue } from './augmentMotionValue.svelte.js';
+import { isRefPending, resolveElement } from './dom.js';
+/**
+ * Named view-timeline presets — mirror framer-motion's ScrollOffset table.
+ * Each entry is a pair of `[target, container]` intersection points that
+ * defines a phase of the scroll relationship.
+ */
+const VIEW_TIMELINE_PRESETS = [
+    [
+        [
+            [0, 1],
+            [1, 1]
+        ],
+        'entry'
+    ],
+    [
+        [
+            [0, 0],
+            [1, 0]
+        ],
+        'exit'
+    ],
+    [
+        [
+            [1, 0],
+            [0, 1]
+        ],
+        'cover'
+    ],
+    [
+        [
+            [0, 0],
+            [1, 1]
+        ],
+        'contain'
+    ]
+];
+const PROGRESS_BY_STRING = { start: 0, end: 1 };
+/**
+ * Parse `"start end"` / `"end start"` / etc. into an explicit
+ * `[target, container]` intersection pair.
+ */
+const parseStringOffset = (s) => {
+    const parts = s.trim().split(/\s+/);
+    if (parts.length !== 2)
+        return undefined;
+    const a = PROGRESS_BY_STRING[parts[0]];
+    const b = PROGRESS_BY_STRING[parts[1]];
+    if (a === undefined || b === undefined)
+        return undefined;
+    return [a, b];
+};
+/**
+ * Normalize a {@link ScrollOffset} into an array of explicit intersection
+ * pairs, or `undefined` if the shape doesn't match the simple two-element
+ * preset form.
+ */
+const normaliseOffset = (offset) => {
+    if (offset.length !== 2)
+        return undefined;
+    const result = [];
+    for (const item of offset) {
+        if (Array.isArray(item)) {
+            result.push(item);
+        }
+        else if (typeof item === 'string') {
+            const parsed = parseStringOffset(item);
+            if (!parsed)
+                return undefined;
+            result.push(parsed);
+        }
+        else {
+            return undefined;
+        }
+    }
+    return result;
+};
+const matchesPreset = (offset, preset) => {
+    const normalised = normaliseOffset(offset);
+    if (!normalised)
+        return false;
+    for (let i = 0; i < 2; i++) {
+        const o = normalised[i];
+        const p = preset[i];
+        if (o[0] !== p[0] || o[1] !== p[1])
+            return false;
+    }
+    return true;
+};
+/**
+ * Map a {@link ScrollOffset} to its corresponding CSS view-timeline range, if
+ * any. Returning `undefined` signals the caller to fall back to JS-driven
+ * scroll tracking. Mirrors framer-motion's `offsetToViewTimelineRange`.
+ */
+const offsetToViewTimelineRange = (offset) => {
+    if (!offset)
+        return { rangeStart: 'contain 0%', rangeEnd: 'contain 100%' };
+    for (const [preset, name] of VIEW_TIMELINE_PRESETS) {
+        if (matchesPreset(offset, preset)) {
+            return { rangeStart: `${name} 0%`, rangeEnd: `${name} 100%` };
+        }
+    }
+    return undefined;
+};
+/**
+ * Whether this scroll configuration can be driven by a native CSS
+ * scroll-timeline / view-timeline. When `true`, the resulting motion value
+ * runs on the compositor thread without per-frame JS callbacks.
+ */
+const canAccelerateScroll = (target, offset) => {
+    if (typeof window === 'undefined')
+        return false;
+    return target
+        ? supportsViewTimeline() && !!offsetToViewTimelineRange(offset)
+        : supportsScrollTimeline();
+};
+/**
+ * Build the AccelerateConfig for a progress motion value driven by a native
+ * scroll-timeline / view-timeline animation. Mirrors framer-motion's
+ * `makeAccelerateConfig` 1:1: the `factory` defers `scroll()` until refs
+ * hydrate via `microtask.read`, then attaches the animation; the `times` /
+ * `keyframes` / `ease` / `duration` describe the 0→1 linear mapping.
+ */
+const makeAccelerateConfig = (axis, options) => ({
+    factory: (animation) => {
+        let cleanup;
+        const start = () => {
+            if (isRefPending(options.container) || isRefPending(options.target)) {
+                microtask.read(start);
+                return;
+            }
+            cleanup = scroll(animation, {
+                offset: options.offset,
+                axis,
+                container: resolveElement(options.container),
+                target: resolveElement(options.target)
+            });
+        };
+        microtask.read(start);
+        return () => {
+            cancelMicrotask(start);
+            cleanup?.();
+        };
+    },
+    times: [0, 1],
+    keyframes: [0, 1],
+    ease: (v) => v,
+    duration: 1
+});
+/**
+ * Creates scroll-linked motion values for building scroll-driven animations
+ * such as progress indicators and parallax effects.
+ *
+ * Returns four `MotionValue<number>`s: `scrollX` / `scrollY` (current
+ * position in px) and `scrollXProgress` / `scrollYProgress` (0–1
+ * normalised). Each is a real motion-dom `MotionValue` augmented with a
+ * `$state`-backed `.current` getter and a `.subscribe` shim, so they
+ * compose with `useTransform`, `useSpring`, and the rest of the Tier 2
+ * surface, and they read reactively in Svelte 5 templates.
+ *
+ * **GPU-accelerated when supported.** On browsers that implement CSS
+ * scroll-timeline (no `target`) or view-timeline (with a `target` and a
+ * preset `offset`), the *Progress motion values run on the compositor
+ * thread via WAAPI — no per-frame JS callback. The non-progress
+ * `scrollX` / `scrollY` motion values always use the JS-driven `scroll()`
+ * primitive since the absolute pixel offset isn't directly available from
+ * native timelines.
+ *
+ * `container` and `target` accept either an `HTMLElement` directly or a
+ * getter `() => HTMLElement | undefined`. The getter form is the right
+ * choice with `bind:this`. Element resolution is deferred to a microtask
+ * (matches React framer-motion 1:1, faster than rAF polling), so a getter
+ * that hasn't hydrated yet is retried as soon as Svelte's mount tick
+ * settles it.
+ *
+ * Lifecycle: the underlying `scroll()` observer and any accelerate factory
+ * attach at mount via `$effect` and detach at unmount, regardless of how
+ * many consumers are reading the values. The four motion values are torn
+ * down at the same time.
+ *
+ * SSR-safe: returns four static `motionValue(0)`s with no scroll observer
+ * on the server.
+ *
+ * @param options Optional scroll tracking configuration.
+ * @returns Four `MotionValue<number>`s — `scrollX`, `scrollY`, `scrollXProgress`, `scrollYProgress`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
+ *
+ *   const { scrollYProgress } = useScroll()
+ *   const scaleX = useSpring(scrollYProgress)
+ * </script>
+ *
+ * <div style="transform: scaleX({scaleX.current}); transform-origin: left;" />
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-scroll
+ */
+export const useScroll = (options = {}) => {
+    const scrollX = motionValue(0);
+    const scrollY = motionValue(0);
+    const scrollXProgress = motionValue(0);
+    const scrollYProgress = motionValue(0);
+    // SSR: return static motion values with no observer and no $effect.
+    if (typeof window === 'undefined') {
+        return {
+            scrollX: augmentMotionValue(scrollX),
+            scrollY: augmentMotionValue(scrollY),
+            scrollXProgress: augmentMotionValue(scrollXProgress),
+            scrollYProgress: augmentMotionValue(scrollYProgress)
+        };
+    }
+    // The *Progress MVs accelerate to the compositor thread when the browser
+    // supports CSS scroll/view-timelines; the non-progress scrollX/scrollY
+    // MVs always need the JS callback for absolute pixel offsets.
+    if (canAccelerateScroll(options.target, options.offset)) {
+        scrollXProgress.accelerate = makeAccelerateConfig('x', options);
+        scrollYProgress.accelerate = makeAccelerateConfig('y', options);
+    }
+    let cleanup;
+    const start = () => {
+        if (isRefPending(options.container) || isRefPending(options.target)) {
+            microtask.read(start);
+            return;
+        }
+        cleanup = scroll((_progress, info) => {
+            scrollX.set(info.x.current);
+            scrollY.set(info.y.current);
+            scrollXProgress.set(info.x.progress);
+            scrollYProgress.set(info.y.progress);
+        }, {
+            container: resolveElement(options.container),
+            target: resolveElement(options.target),
+            offset: options.offset,
+            axis: options.axis
+        });
+    };
+    $effect(() => {
+        microtask.read(start);
+        return () => {
+            cancelMicrotask(start);
+            cleanup?.();
+            scrollX.destroy();
+            scrollY.destroy();
+            scrollXProgress.destroy();
+            scrollYProgress.destroy();
+        };
+    });
+    return {
+        scrollX: augmentMotionValue(scrollX),
+        scrollY: augmentMotionValue(scrollY),
+        scrollXProgress: augmentMotionValue(scrollXProgress),
+        scrollYProgress: augmentMotionValue(scrollYProgress)
+    };
+};

package/dist/utils/spring.svelte.d.ts

@@ -1,5 +1,6 @@
 import { type FollowValueOptions, type MotionValue, type SpringOptions } from 'motion-dom';
 import { type Readable } from 'svelte/store';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
 /**
  * Spring + follow options for {@link useSpring}.
  *
@@ -25,12 +26,7 @@ export type UseSpringOptions = SpringOptions & Pick<FollowValueOptions, 'skipIni
  *   spring be used with `$spring` template syntax, `get(spring)`, and as a
  *   dependency in `useTransform`'s function form.
  */
-export type SpringMotionValue<T extends number | string> = Omit<MotionValue<T>, 'current'> & {
-    /** Reactive read in Svelte 5 templates / `$derived` / `$effect`. */
-    readonly current: T;
-    /** Svelte readable store compatibility. */
-    subscribe: (run: (value: T) => void) => () => void;
-};
+export type SpringMotionValue<T extends number | string> = AugmentedMotionValue<T>;
 /**
  * Creates a spring-animated `MotionValue`.
  *

package/dist/utils/spring.svelte.js

@@ -1,26 +1,16 @@
 import { attachFollow, isMotionValue, motionValue } from 'motion-dom';
-import { get } from 'svelte/store';
-/**
- * Detects a Svelte readable store. Excludes motion-dom `MotionValue` instances
- * (which also expose `subscribe`-shaped APIs in some versions) so the
- * MotionValue path is preferred.
- */
-const isSvelteReadable = (value) => {
-    return (!!value &&
-        typeof value === 'object' &&
-        typeof value.subscribe === 'function' &&
-        !isMotionValue(value));
-};
+import {} from 'svelte/store';
+import { augmentMotionValue, isSvelteReadable, sampleSource } from './augmentMotionValue.svelte.js';
 export function useSpring(source, options = {}) {
     // SSR: return a static MotionValue with no animation. Reads return the
     // best-effort initial value; .set / .jump become no-ops to avoid drifting
     // away from the server-rendered snapshot.
     if (typeof window === 'undefined') {
-        const initial = readInitial(source);
+        const initial = sampleSource(source);
         const ssrValue = motionValue(initial);
         ssrValue.set = () => undefined;
         ssrValue.jump = () => undefined;
-        return augmentForSvelte(ssrValue, () => undefined);
+        return augmentMotionValue(ssrValue);
     }
     // Resolve initial + follow source.
     let followSource;
@@ -32,7 +22,7 @@ export function useSpring(source, options = {}) {
     else if (isSvelteReadable(source)) {
         // Bridge a Svelte readable into a MotionValue so attachFollow can
         // track it. Synchronous initial sample comes from svelte/store's get().
-        const initialFromReadable = get(source);
+        const initialFromReadable = sampleSource(source);
         svelteBridge = motionValue(initialFromReadable);
         cleanupReadableBridge = source.subscribe((v) => {
             // The Svelte readable contract calls the subscriber synchronously
@@ -60,59 +50,5 @@ export function useSpring(source, options = {}) {
         svelteBridge?.destroy();
     };
     $effect(() => () => value.destroy());
-    return augmentForSvelte(value, dispose);
+    return augmentMotionValue(value, dispose);
 }
-/**
- * Pull the synchronous initial value out of any accepted source form.
- */
-const readInitial = (source) => {
-    if (typeof source === 'number' || typeof source === 'string')
-        return source;
-    if (isMotionValue(source))
-        return source.get();
-    if (isSvelteReadable(source))
-        return get(source);
-    return 0;
-};
-/**
- * Layer Svelte-friendly affordances onto a motion-dom MotionValue: a
- * `$state`-tracked `.current` accessor (routing motion-dom's internal
- * `this.current = v` writes through `$state` so templates and `$derived` /
- * `$effect` re-run) and a Svelte readable store `.subscribe(run)` shim.
- */
-const augmentForSvelte = (value, dispose) => {
-    let current = $state(value.get());
-    Object.defineProperty(value, 'current', {
-        get: () => current,
-        // Same-value writes are no-ops: motion-dom's `updateAndNotify` calls
-        // `setCurrent(v)` before its own change check, so spring frames at
-        // rest still hit this setter; skipping equal writes avoids gratuitous
-        // accessor work even though $state would itself dedupe.
-        set: (v) => {
-            if (v !== current)
-                current = v;
-        },
-        enumerable: true,
-        configurable: true
-    });
-    const originalDestroy = value.destroy.bind(value);
-    let destroyed = false;
-    value.destroy = () => {
-        if (destroyed)
-            return;
-        destroyed = true;
-        dispose();
-        originalDestroy();
-    };
-    const subscribe = (run) => {
-        run(value.get());
-        return value.on('change', run);
-    };
-    Object.defineProperty(value, 'subscribe', {
-        value: subscribe,
-        writable: false,
-        enumerable: false,
-        configurable: true
-    });
-    return value;
-};

package/dist/utils/time.svelte.d.ts

@@ -0,0 +1,47 @@
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Returns an augmented `MotionValue<number>` that ticks once per render
+ * frame with the milliseconds elapsed since the value was created.
+ *
+ * Mirrors React framer-motion's `useTime` 1:1: a `MotionValue<number>`
+ * driven by motion-dom's `frame.update(tick, true)` keep-alive callback.
+ * The frame loop dedupes per-frame work across all motion-dom consumers,
+ * so multiple `useTime()` calls share the same render schedule.
+ *
+ * Two modes:
+ *
+ * - **Unique timeline** — `useTime()` starts its own keep-alive callback.
+ *   The motion value and the callback are torn down when the surrounding
+ *   `$effect` scope unmounts.
+ * - **Shared timeline** — `useTime(id)` callers passing the same `id` all
+ *   observe a single shared frame-loop callback. Each call still returns
+ *   an independent motion value (so destroying one consumer's value
+ *   doesn't ripple to others) but the values stay in lockstep. The
+ *   shared callback cancels the moment the last consumer unmounts; the
+ *   next `useTime(id)` call restarts it.
+ *
+ * The result is augmented with a `$state`-backed `.current` getter and a
+ * `.subscribe` shim — it composes with `useTransform`, `useSpring`, and
+ * the rest of the Tier 2 surface.
+ *
+ * Lifecycle: must be called during component initialization. SSR-safe:
+ * returns a static `motionValue(0)` with no frame loop on the server.
+ *
+ * @param id Optional timeline identifier for sharing across components.
+ * @returns A `MotionValue<number>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTime, useTransform } from '@humanspeak/svelte-motion'
+ *
+ *   const time = useTime()
+ *   const rotate = useTransform(time, [0, 4000], [0, 360], { clamp: false })
+ * </script>
+ *
+ * <div style="transform: rotate({rotate.current}deg)">↻</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-time
+ */
+export declare const useTime: (id?: string) => AugmentedMotionValue<number>;

package/dist/utils/time.svelte.js

@@ -0,0 +1,128 @@
+import { cancelFrame, frame, motionValue } from 'motion-dom';
+import { SvelteMap } from 'svelte/reactivity';
+import { augmentMotionValue } from './augmentMotionValue.svelte.js';
+// `SvelteMap` (not plain Map) per `eslint/svelte/prefer-svelte-reactivity`
+// inside `.svelte.ts` files. The contents aren't read in reactive scopes —
+// this is a plain keyed cache — but the linter rule applies uniformly.
+const sharedTimelines = new SvelteMap();
+// Clear shared timelines on HMR dispose to avoid stale entries across hot
+// reloads.
+const hot = import.meta.hot;
+if (hot) {
+    hot.dispose(() => {
+        for (const t of sharedTimelines.values()) {
+            t.cancel();
+            t.base.destroy();
+        }
+        sharedTimelines.clear();
+    });
+}
+/**
+ * Starts a keep-alive frame-loop callback that writes elapsed-milliseconds
+ * into a fresh `MotionValue<number>`. Returns the value and a cancel
+ * function that stops the loop. Caller owns the value's destroy lifecycle.
+ *
+ * Uses motion-dom's `frame.update(cb, true)` — `true` is the `keepAlive`
+ * flag, telling the frame loop to re-schedule the callback every frame
+ * automatically. Matches React framer-motion's `useAnimationFrame`.
+ */
+const startTimeBase = () => {
+    const base = motionValue(0);
+    let start = 0;
+    const tick = ({ timestamp }) => {
+        if (!start)
+            start = timestamp;
+        base.set(timestamp - start);
+    };
+    frame.update(tick, true);
+    return {
+        base,
+        cancel: () => cancelFrame(tick)
+    };
+};
+/**
+ * Returns an augmented `MotionValue<number>` that ticks once per render
+ * frame with the milliseconds elapsed since the value was created.
+ *
+ * Mirrors React framer-motion's `useTime` 1:1: a `MotionValue<number>`
+ * driven by motion-dom's `frame.update(tick, true)` keep-alive callback.
+ * The frame loop dedupes per-frame work across all motion-dom consumers,
+ * so multiple `useTime()` calls share the same render schedule.
+ *
+ * Two modes:
+ *
+ * - **Unique timeline** — `useTime()` starts its own keep-alive callback.
+ *   The motion value and the callback are torn down when the surrounding
+ *   `$effect` scope unmounts.
+ * - **Shared timeline** — `useTime(id)` callers passing the same `id` all
+ *   observe a single shared frame-loop callback. Each call still returns
+ *   an independent motion value (so destroying one consumer's value
+ *   doesn't ripple to others) but the values stay in lockstep. The
+ *   shared callback cancels the moment the last consumer unmounts; the
+ *   next `useTime(id)` call restarts it.
+ *
+ * The result is augmented with a `$state`-backed `.current` getter and a
+ * `.subscribe` shim — it composes with `useTransform`, `useSpring`, and
+ * the rest of the Tier 2 surface.
+ *
+ * Lifecycle: must be called during component initialization. SSR-safe:
+ * returns a static `motionValue(0)` with no frame loop on the server.
+ *
+ * @param id Optional timeline identifier for sharing across components.
+ * @returns A `MotionValue<number>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTime, useTransform } from '@humanspeak/svelte-motion'
+ *
+ *   const time = useTime()
+ *   const rotate = useTransform(time, [0, 4000], [0, 360], { clamp: false })
+ * </script>
+ *
+ * <div style="transform: rotate({rotate.current}deg)">↻</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-time
+ */
+export const useTime = (id) => {
+    // SSR: return a static motion value with no frame loop. Matches
+    // useSpring / useScroll's SSR branch — no $effect is registered.
+    if (typeof window === 'undefined') {
+        return augmentMotionValue(motionValue(0));
+    }
+    // Unique timeline: own callback, own MV, own lifecycle.
+    if (!id) {
+        const { base, cancel } = startTimeBase();
+        $effect(() => () => {
+            cancel();
+            base.destroy();
+        });
+        return augmentMotionValue(base);
+    }
+    // Shared timeline: one frame callback per `id`, mirrored into per-
+    // consumer MVs.
+    let timeline = sharedTimelines.get(id);
+    if (!timeline) {
+        const { base, cancel } = startTimeBase();
+        timeline = { base, refcount: 0, cancel };
+        sharedTimelines.set(id, timeline);
+    }
+    timeline.refcount++;
+    const consumerMv = motionValue(timeline.base.get());
+    const unsubBase = timeline.base.on('change', (t) => consumerMv.set(t));
+    $effect(() => () => {
+        unsubBase();
+        consumerMv.destroy();
+        const t = sharedTimelines.get(id);
+        if (!t)
+            return;
+        t.refcount--;
+        if (t.refcount > 0)
+            return;
+        t.cancel();
+        t.base.destroy();
+        sharedTimelines.delete(id);
+    });
+    return augmentMotionValue(consumerMv);
+};