@humanspeak/svelte-motion 0.4.8 → 0.5.0

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

@@ -0,0 +1,61 @@
+import { type MotionValue as MotionDomMotionValue } from 'motion-dom';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * The shape returned by {@link useMotionValue}: a real motion-dom
+ * `MotionValue<T>` (so it composes with `animate()`, `useTransform`,
+ * `useSpring`, etc. and passes `isMotionValue`) plus a Svelte 5 reactive
+ * `.current` getter and a Svelte readable store `.subscribe` shim.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @see {@link AugmentedMotionValue}
+ */
+export type MotionValue<T = number> = AugmentedMotionValue<T>;
+/**
+ * Re-export of motion-dom's raw `MotionValue` type for cases where the
+ * un-augmented shape is needed (e.g. typing follow sources, function
+ * dependencies). Most call sites should prefer {@link MotionValue}.
+ */
+export type RawMotionValue<T = number> = MotionDomMotionValue<T>;
+/**
+ * Creates a tracked, mutable value backed by motion-dom's `MotionValue`.
+ *
+ * Use `.set(v)` to write the value imperatively, `.get()` to sample it
+ * imperatively, and `.current` to read it inside Svelte 5 reactive scopes
+ * (templates, `$derived`, `$effect`). The same value also implements the
+ * Svelte readable store contract via `.subscribe(run)`, so legacy `$mv`
+ * template syntax and `svelte/store`'s `get()` keep working.
+ *
+ * Returned object is a real motion-dom `MotionValue` — it composes with
+ * `useTransform`, `useSpring`, `useVelocity`, the `animate()` driver, and
+ * passes `isMotionValue`. Unlike `useSpring`, writes are immediate — there
+ * is no follow source and no animation.
+ *
+ * Lifecycle: must be called during component initialization. Cleanup is
+ * registered via `$effect`; motion-dom's internal listeners and animation
+ * subscriptions are released when the surrounding component / effect tears
+ * down. Call `.destroy()` to clean up early.
+ *
+ * SSR-safe: motion-dom's `motionValue` runs without DOM access; on the
+ * server reads return the initial value and writes still work, with no
+ * timers or listeners attached.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @param initial The starting value.
+ * @returns A `MotionValue<T>` augmented with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMotionValue, useTransform } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *   const opacity = useTransform(x, [0, 200], [0, 1])
+ * </script>
+ *
+ * <input type="range" min="0" max="200" oninput={(e) => x.set(+e.currentTarget.value)} />
+ * <div style="opacity: {opacity.current}">x = {x.current}</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-motion-value
+ */
+export declare const useMotionValue: <T = number>(initial: T) => MotionValue<T>;

package/dist/utils/motionValue.svelte.js

@@ -0,0 +1,49 @@
+import { motionValue } from 'motion-dom';
+import { augmentMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Creates a tracked, mutable value backed by motion-dom's `MotionValue`.
+ *
+ * Use `.set(v)` to write the value imperatively, `.get()` to sample it
+ * imperatively, and `.current` to read it inside Svelte 5 reactive scopes
+ * (templates, `$derived`, `$effect`). The same value also implements the
+ * Svelte readable store contract via `.subscribe(run)`, so legacy `$mv`
+ * template syntax and `svelte/store`'s `get()` keep working.
+ *
+ * Returned object is a real motion-dom `MotionValue` — it composes with
+ * `useTransform`, `useSpring`, `useVelocity`, the `animate()` driver, and
+ * passes `isMotionValue`. Unlike `useSpring`, writes are immediate — there
+ * is no follow source and no animation.
+ *
+ * Lifecycle: must be called during component initialization. Cleanup is
+ * registered via `$effect`; motion-dom's internal listeners and animation
+ * subscriptions are released when the surrounding component / effect tears
+ * down. Call `.destroy()` to clean up early.
+ *
+ * SSR-safe: motion-dom's `motionValue` runs without DOM access; on the
+ * server reads return the initial value and writes still work, with no
+ * timers or listeners attached.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @param initial The starting value.
+ * @returns A `MotionValue<T>` augmented with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMotionValue, useTransform } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *   const opacity = useTransform(x, [0, 200], [0, 1])
+ * </script>
+ *
+ * <input type="range" min="0" max="200" oninput={(e) => x.set(+e.currentTarget.value)} />
+ * <div style="opacity: {opacity.current}">x = {x.current}</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-motion-value
+ */
+export const useMotionValue = (initial) => {
+    const value = motionValue(initial);
+    $effect(() => () => value.destroy());
+    return augmentMotionValue(value);
+};

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

@@ -0,0 +1,43 @@
+import { type BooleanSnapshot } from './booleanSnapshot.svelte.js';
+/**
+ * State returned by {@link useReducedMotion}.
+ */
+export type ReducedMotionState = BooleanSnapshot;
+/**
+ * Returns a `{ current, subscribe }` object that reflects the user's
+ * `prefers-reduced-motion` setting. Mirrors framer-motion's
+ * `useReducedMotion` adapted for Svelte 5 runes.
+ *
+ * - `state.current` is reactive — read it in templates / `$derived` /
+ *   `$effect` and it tracks the underlying `matchMedia` listener.
+ * - `state.subscribe(run)` is the Svelte readable store contract:
+ *   synchronously emits the current value, then re-emits on every change.
+ *   Kept for compat with downstream hooks that still consume Svelte
+ *   readables until the Tier 2 wave lands.
+ *
+ * Diverges from React framer-motion's plain `boolean | null` return for
+ * the same reason as `useCycle`: a `$state`-backed value must live on an
+ * object so reads inside getters preserve tracking under runes.
+ *
+ * SSR-safe: returns a static `{ current: false }` when `window` /
+ * `matchMedia` is unavailable, including when `matchMedia` throws.
+ *
+ * The media listener is bound to the surrounding reactive scope via
+ * `$effect` — call this from a component `<script>` block (the standard
+ * hook contract). On unmount the listener is detached automatically.
+ *
+ * @returns A `ReducedMotionState` reflecting the OS reduced-motion setting.
+ * @see https://motion.dev/docs/react-reduced-motion
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useReducedMotion } from '@humanspeak/svelte-motion'
+ *
+ *   const reduced = useReducedMotion()
+ * </script>
+ *
+ * <div style:transform={reduced.current ? 'none' : 'rotate(45deg)'} />
+ * ```
+ */
+export declare const useReducedMotion: () => ReducedMotionState;

package/dist/utils/reducedMotion.svelte.js

@@ -0,0 +1,80 @@
+import { createBooleanSnapshot } from './booleanSnapshot.svelte.js';
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+/**
+ * Returns a `{ current, subscribe }` object that reflects the user's
+ * `prefers-reduced-motion` setting. Mirrors framer-motion's
+ * `useReducedMotion` adapted for Svelte 5 runes.
+ *
+ * - `state.current` is reactive — read it in templates / `$derived` /
+ *   `$effect` and it tracks the underlying `matchMedia` listener.
+ * - `state.subscribe(run)` is the Svelte readable store contract:
+ *   synchronously emits the current value, then re-emits on every change.
+ *   Kept for compat with downstream hooks that still consume Svelte
+ *   readables until the Tier 2 wave lands.
+ *
+ * Diverges from React framer-motion's plain `boolean | null` return for
+ * the same reason as `useCycle`: a `$state`-backed value must live on an
+ * object so reads inside getters preserve tracking under runes.
+ *
+ * SSR-safe: returns a static `{ current: false }` when `window` /
+ * `matchMedia` is unavailable, including when `matchMedia` throws.
+ *
+ * The media listener is bound to the surrounding reactive scope via
+ * `$effect` — call this from a component `<script>` block (the standard
+ * hook contract). On unmount the listener is detached automatically.
+ *
+ * @returns A `ReducedMotionState` reflecting the OS reduced-motion setting.
+ * @see https://motion.dev/docs/react-reduced-motion
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useReducedMotion } from '@humanspeak/svelte-motion'
+ *
+ *   const reduced = useReducedMotion()
+ * </script>
+ *
+ * <div style:transform={reduced.current ? 'none' : 'rotate(45deg)'} />
+ * ```
+ */
+export const useReducedMotion = () => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+        return staticState(false);
+    }
+    let media;
+    try {
+        media = window.matchMedia(REDUCED_MOTION_QUERY);
+    }
+    catch {
+        return staticState(false);
+    }
+    const [state, set] = createBooleanSnapshot(media.matches);
+    const handler = (event) => set(event.matches);
+    $effect(() => {
+        // Resync on (re-)mount in case the OS preference changed while
+        // the component was torn down between effect runs.
+        set(media.matches);
+        if (typeof media.addEventListener === 'function') {
+            media.addEventListener('change', handler);
+            return () => media.removeEventListener('change', handler);
+        }
+        // Safari < 14 / older WebKit — addListener/removeListener fallback.
+        media.addListener(handler);
+        return () => media.removeListener(handler);
+    });
+    return state;
+};
+/**
+ * SSR / no-matchMedia fallback. Static value, no listeners; `subscribe`
+ * is a one-shot sync emit + no-op unsubscribe so consumers can wire it
+ * the same way they do the live state.
+ */
+const staticState = (value) => ({
+    get current() {
+        return value;
+    },
+    subscribe(run) {
+        run(value);
+        return () => undefined;
+    }
+});

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

@@ -0,0 +1,74 @@
+import { type ReducedMotionState } from './reducedMotion.svelte.js';
+/**
+ * Returns a copy of `keyframes` with transform-related keys
+ * (`x`, `y`, `scale`, `rotate`, `skew`, `translate*`, etc.) removed
+ * when `reduced` is `true`. Returns `keyframes` unchanged otherwise.
+ *
+ * The `transition` key is preserved so per-key transitions still flow
+ * through to the animation engine; only the visual *targets* are
+ * stripped, not the timing config.
+ *
+ * @template T Keyframes record (or `undefined`).
+ * @param keyframes Source keyframes record — may be `undefined`, in
+ *   which case the same `undefined` is returned regardless of
+ *   `reduced`.
+ * @param reduced When `true`, strip transform keys; when `false`,
+ *   return `keyframes` unchanged (by reference).
+ * @returns The original `keyframes` when `reduced` is `false` (same
+ *   reference); otherwise a new record with transform keys filtered
+ *   out and other keys preserved.
+ *
+ * @example
+ * ```ts
+ * filterReducedMotionKeyframes(
+ *   { x: 100, scale: 1.2, opacity: 0.5 },
+ *   true
+ * )
+ * // → { opacity: 0.5 }
+ *
+ * filterReducedMotionKeyframes(
+ *   { x: 100, opacity: 0.5, transition: { duration: 0.3 } },
+ *   true
+ * )
+ * // → { opacity: 0.5, transition: { duration: 0.3 } }
+ * ```
+ */
+export declare const filterReducedMotionKeyframes: <T extends Record<string, unknown> | undefined>(keyframes: T, reduced: boolean) => T;
+/**
+ * Returns a `{ current, subscribe }` object reflecting the resolved
+ * reduced-motion policy for the current component subtree.
+ *
+ * Resolution combines the nearest `<MotionConfig reducedMotion>` ancestor
+ * with the OS-level `prefers-reduced-motion` setting:
+ *
+ * - `'always'` → always `true`
+ * - `'never'` (or no `<MotionConfig>` ancestor) → always `false`
+ * - `'user'` → mirrors the OS preference, defaulting to `false` in SSR
+ *
+ * Both reactive read paths fire on **both** sources changing:
+ *
+ * - `.current` re-evaluates inside any reactive scope that reads it
+ *   (templates, `$derived`, `$effect`) when either the OS preference *or*
+ *   a parent `<MotionConfig reducedMotion={...}>` policy reassigns.
+ * - `.subscribe(run)` callbacks are driven by both the OS path
+ *   (sync via `osReduced.subscribe`) and a `$effect` tracking the
+ *   `motionConfig.reducedMotion` prop. Legacy store consumers see policy
+ *   changes too — a fix vs. the prior `derived()`-based impl, which only
+ *   re-fired on OS changes.
+ *
+ * @returns A `ReducedMotionState` reflecting the merged policy + OS setting.
+ * @see https://motion.dev/docs/react-reduced-motion
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useReducedMotionConfig } from '@humanspeak/svelte-motion'
+ *   const reduced = useReducedMotionConfig()
+ * </script>
+ *
+ * {#if !reduced.current}
+ *   <motion.div animate={{ x: 100 }} />
+ * {/if}
+ * ```
+ */
+export declare const useReducedMotionConfig: () => ReducedMotionState;

package/dist/utils/reducedMotionConfig.svelte.js

@@ -0,0 +1,144 @@
+import { getMotionConfig } from '../components/motionConfig.context.js';
+import { createBooleanSnapshot } from './booleanSnapshot.svelte.js';
+import { useReducedMotion } from './reducedMotion.svelte.js';
+/**
+ * CSS / motion property keys that move or rotate an element via `transform`.
+ * When reduced motion is active these keys are stripped from animate keyframes
+ * so the element stays in place while non-transform properties (opacity, color,
+ * etc.) continue to animate.
+ */
+const TRANSFORM_KEYS = new Set([
+    'x',
+    'y',
+    'z',
+    'translate',
+    'translateX',
+    'translateY',
+    'translateZ',
+    'scale',
+    'scaleX',
+    'scaleY',
+    'scaleZ',
+    'rotate',
+    'rotateX',
+    'rotateY',
+    'rotateZ',
+    'skew',
+    'skewX',
+    'skewY',
+    'transform',
+    'transformPerspective',
+    'perspective'
+]);
+/**
+ * Returns a copy of `keyframes` with transform-related keys
+ * (`x`, `y`, `scale`, `rotate`, `skew`, `translate*`, etc.) removed
+ * when `reduced` is `true`. Returns `keyframes` unchanged otherwise.
+ *
+ * The `transition` key is preserved so per-key transitions still flow
+ * through to the animation engine; only the visual *targets* are
+ * stripped, not the timing config.
+ *
+ * @template T Keyframes record (or `undefined`).
+ * @param keyframes Source keyframes record — may be `undefined`, in
+ *   which case the same `undefined` is returned regardless of
+ *   `reduced`.
+ * @param reduced When `true`, strip transform keys; when `false`,
+ *   return `keyframes` unchanged (by reference).
+ * @returns The original `keyframes` when `reduced` is `false` (same
+ *   reference); otherwise a new record with transform keys filtered
+ *   out and other keys preserved.
+ *
+ * @example
+ * ```ts
+ * filterReducedMotionKeyframes(
+ *   { x: 100, scale: 1.2, opacity: 0.5 },
+ *   true
+ * )
+ * // → { opacity: 0.5 }
+ *
+ * filterReducedMotionKeyframes(
+ *   { x: 100, opacity: 0.5, transition: { duration: 0.3 } },
+ *   true
+ * )
+ * // → { opacity: 0.5, transition: { duration: 0.3 } }
+ * ```
+ */
+export const filterReducedMotionKeyframes = (keyframes, reduced) => {
+    if (!reduced || !keyframes)
+        return keyframes;
+    const out = {};
+    for (const key of Object.keys(keyframes)) {
+        if (!TRANSFORM_KEYS.has(key))
+            out[key] = keyframes[key];
+    }
+    return out;
+};
+/**
+ * Returns a `{ current, subscribe }` object reflecting the resolved
+ * reduced-motion policy for the current component subtree.
+ *
+ * Resolution combines the nearest `<MotionConfig reducedMotion>` ancestor
+ * with the OS-level `prefers-reduced-motion` setting:
+ *
+ * - `'always'` → always `true`
+ * - `'never'` (or no `<MotionConfig>` ancestor) → always `false`
+ * - `'user'` → mirrors the OS preference, defaulting to `false` in SSR
+ *
+ * Both reactive read paths fire on **both** sources changing:
+ *
+ * - `.current` re-evaluates inside any reactive scope that reads it
+ *   (templates, `$derived`, `$effect`) when either the OS preference *or*
+ *   a parent `<MotionConfig reducedMotion={...}>` policy reassigns.
+ * - `.subscribe(run)` callbacks are driven by both the OS path
+ *   (sync via `osReduced.subscribe`) and a `$effect` tracking the
+ *   `motionConfig.reducedMotion` prop. Legacy store consumers see policy
+ *   changes too — a fix vs. the prior `derived()`-based impl, which only
+ *   re-fired on OS changes.
+ *
+ * @returns A `ReducedMotionState` reflecting the merged policy + OS setting.
+ * @see https://motion.dev/docs/react-reduced-motion
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useReducedMotionConfig } from '@humanspeak/svelte-motion'
+ *   const reduced = useReducedMotionConfig()
+ * </script>
+ *
+ * {#if !reduced.current}
+ *   <motion.div animate={{ x: 100 }} />
+ * {/if}
+ * ```
+ */
+export const useReducedMotionConfig = () => {
+    const motionConfig = getMotionConfig();
+    const osReduced = useReducedMotion();
+    const resolve = () => {
+        const policy = motionConfig?.reducedMotion ?? 'never';
+        if (policy === 'always')
+            return true;
+        if (policy === 'never')
+            return false;
+        return osReduced.current;
+    };
+    const [state, set] = createBooleanSnapshot(resolve());
+    // Sync path: `osReduced.subscribe` fires the run callback on every OS
+    // preference change (and once synchronously on subscribe). The
+    // snapshot's same-value dedupe absorbs that initial duplicate emit.
+    const osUnsub = osReduced.subscribe(() => set(resolve()));
+    // Async path: `<MotionConfig reducedMotion>` is exposed via a
+    // property getter over the config component's prop, so reading it
+    // inside `$effect` tracks reassignments and fires the same `set` —
+    // closing the gap the legacy `derived()`-based impl had. Returning
+    // `osUnsub` installs it as the effect's cleanup, so the OS
+    // subscription is released on unmount.
+    $effect(() => {
+        // Void the read so the lint unused-expression rule doesn't fire
+        // on a deliberate dependency touch.
+        void motionConfig?.reducedMotion;
+        set(resolve());
+        return osUnsub;
+    });
+    return state;
+};

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

@@ -0,0 +1,91 @@
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+import { type ElementOrGetter } from './dom.js';
+/**
+ * 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]`.
+ *
+ * Intentionally looser than motion's internal `ScrollOffset` type — that
+ * uses template-literal types (`` `${Edge} ${Edge}` ``) we don't want to
+ * surface to consumers. The runtime call paths through `scroll(...)` cast
+ * `options.offset as never` to bridge the two; safe because every shape our
+ * type allows is structurally a member of motion's union.
+ */
+type ScrollOffset = Array<[number | string, number | string]> | string[];
+/**
+ * Options accepted by {@link useScroll}.
+ */
+export 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 {@link useScroll} — four motion-dom `MotionValue<number>`s
+ * representing scroll position and normalised progress for both axes, each
+ * augmented with `.current` + `.subscribe`.
+ */
+export type UseScrollReturn = {
+    scrollX: AugmentedMotionValue<number>;
+    scrollY: AugmentedMotionValue<number>;
+    scrollXProgress: AugmentedMotionValue<number>;
+    scrollYProgress: AugmentedMotionValue<number>;
+};
+/**
+ * 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 declare const useScroll: (options?: UseScrollOptions) => UseScrollReturn;
+export {};