@humanspeak/svelte-motion 0.4.7 → 0.4.9

package/dist/html/_MotionContainer.svelte

@@ -8,7 +8,7 @@
     import {
         filterReducedMotionKeyframes,
         useReducedMotionConfig
-    } from '../utils/reducedMotionConfig'
+    } from '../utils/reducedMotionConfig.svelte'
     import type {
         MotionProps,
         MotionTransition,
@@ -29,7 +29,7 @@
     import { attachWhileTap } from '../utils/interaction'
     import { attachWhileHover } from '../utils/hover'
     import { attachWhileFocus } from '../utils/focus'
-    import { attachWhileInView } from '../utils/inView'
+    import { attachWhileInView } from '../utils/inView.svelte'
     import {
         measureRect,
         computeFlipTransforms,
@@ -57,7 +57,7 @@
         setCustomContext,
         getCustomContext
     } from '../components/variantContext.context'
-    import { get, writable } from 'svelte/store'
+    import { writable } from 'svelte/store'
     import {
         transformSVGPathProperties,
         computeNormalizedSVGInitialAttrs,
@@ -130,11 +130,11 @@
     let isLoaded = $state<'mounting' | 'initial' | 'ready' | 'animated'>('mounting')
     let dataPath = $state<number>(-1)
     const motionConfig = $derived(getMotionConfig())
-    const reducedMotionStore = useReducedMotionConfig()
-    // Seed synchronously so the first render filters keyframes correctly —
-    // otherwise transforms could flash before the subscribe effect runs.
-    let reducedMotion = $state(get(reducedMotionStore))
-    $effect(() => reducedMotionStore.subscribe((value) => (reducedMotion = value)))
+    const reducedMotionState = useReducedMotionConfig()
+    // `.current` is $state-backed inside reducedMotionState; tracking it via
+    // $derived makes `reducedMotion` re-evaluate whenever the OS preference
+    // or `<MotionConfig reducedMotion>` policy changes.
+    const reducedMotion = $derived(reducedMotionState.current)
 
     // Get presence context to check if we're inside AnimatePresence
     const context = getAnimatePresenceContext()

package/dist/index.d.ts

@@ -10,19 +10,21 @@ export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition,
 export { useAnimate } from './utils/animate.svelte';
 export type { AnimationScope } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
-export { useCycle } from './utils/cycle';
-export type { Cycle, CycleState } from './utils/cycle';
+export { useCycle } from './utils/cycle.svelte';
+export type { Cycle, CycleState } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
-export { useInView } from './utils/inView';
-export type { UseInViewOptions } from './utils/inView';
+export { useInView } from './utils/inView.svelte';
+export type { InViewState, UseInViewOptions } from './utils/inView.svelte';
 export { useMotionTemplate } from './utils/motionTemplate';
 export { useMotionValue } from './utils/motionValue';
 export type { MotionValue } from './utils/motionValue';
 export { useMotionValueEvent } from './utils/motionValueEvent';
-export { useReducedMotion } from './utils/reducedMotion';
-export { useReducedMotionConfig } from './utils/reducedMotionConfig';
+export { useReducedMotion } from './utils/reducedMotion.svelte';
+export type { ReducedMotionState } from './utils/reducedMotion.svelte';
+export { useReducedMotionConfig } from './utils/reducedMotionConfig.svelte';
 export { useScroll } from './utils/scroll';
-export { useSpring } from './utils/spring';
+export { useSpring } from './utils/spring.svelte';
+export type { SpringMotionValue, UseSpringOptions } from './utils/spring.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';
 export type { UsePresenceState } from './utils/usePresence';
 export { useVelocity } from './utils/velocity';

package/dist/index.js

@@ -11,16 +11,16 @@ export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cub
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export { useAnimate } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
-export { useCycle } from './utils/cycle';
+export { useCycle } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
-export { useInView } from './utils/inView';
+export { useInView } from './utils/inView.svelte';
 export { useMotionTemplate } from './utils/motionTemplate';
 export { useMotionValue } from './utils/motionValue';
 export { useMotionValueEvent } from './utils/motionValueEvent';
-export { useReducedMotion } from './utils/reducedMotion';
-export { useReducedMotionConfig } from './utils/reducedMotionConfig';
+export { useReducedMotion } from './utils/reducedMotion.svelte';
+export { useReducedMotionConfig } from './utils/reducedMotionConfig.svelte';
 export { useScroll } from './utils/scroll';
-export { useSpring } from './utils/spring';
+export { useSpring } from './utils/spring.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';
 export { useVelocity } from './utils/velocity';
 /**

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

@@ -0,0 +1,37 @@
+/**
+ * Shared `{ current, subscribe }` shape returned by the Wave 2 boolean
+ * snapshot hooks — `useReducedMotion`, `useReducedMotionConfig`,
+ * `useInView`. `.current` is `$state`-backed; `.subscribe(run)` is the
+ * Svelte readable store contract preserved for legacy consumers during
+ * the Tier 2 migration.
+ */
+export type BooleanSnapshot = {
+    /** Reactive read in Svelte 5 templates / `$derived` / `$effect`. */
+    readonly current: boolean;
+    /** Svelte readable store contract — emits synchronously on subscribe. */
+    subscribe: (run: (value: boolean) => void) => () => void;
+};
+/**
+ * Build a `{ current, subscribe }` snapshot + an internal `set`
+ * function. Centralises the dedupe + subscriber-fanout that all three
+ * boolean-snapshot hooks need.
+ *
+ * Returns a tuple so consumers can hand the snapshot to callers while
+ * keeping `set` internal (it's not on the returned state object).
+ *
+ * Same-value writes via `set` are no-ops — saves a fanout call and
+ * means callers don't need their own change-detection guard.
+ *
+ * @param initial Starting value for the `current` cell.
+ * @returns A `[state, set]` tuple where `state` is the publicly-shared
+ *   `{ current, subscribe }` and `set` is the internal updater the hook
+ *   uses to push values from its event source.
+ *
+ * @example
+ * ```ts
+ * const [state, set] = createBooleanSnapshot(media.matches)
+ * media.addEventListener('change', (e) => set(e.matches))
+ * return state // { current, subscribe }
+ * ```
+ */
+export declare const createBooleanSnapshot: (initial: boolean) => [BooleanSnapshot, (value: boolean) => void];

package/dist/utils/booleanSnapshot.svelte.js

@@ -0,0 +1,48 @@
+import { SvelteSet } from 'svelte/reactivity';
+/**
+ * Build a `{ current, subscribe }` snapshot + an internal `set`
+ * function. Centralises the dedupe + subscriber-fanout that all three
+ * boolean-snapshot hooks need.
+ *
+ * Returns a tuple so consumers can hand the snapshot to callers while
+ * keeping `set` internal (it's not on the returned state object).
+ *
+ * Same-value writes via `set` are no-ops — saves a fanout call and
+ * means callers don't need their own change-detection guard.
+ *
+ * @param initial Starting value for the `current` cell.
+ * @returns A `[state, set]` tuple where `state` is the publicly-shared
+ *   `{ current, subscribe }` and `set` is the internal updater the hook
+ *   uses to push values from its event source.
+ *
+ * @example
+ * ```ts
+ * const [state, set] = createBooleanSnapshot(media.matches)
+ * media.addEventListener('change', (e) => set(e.matches))
+ * return state // { current, subscribe }
+ * ```
+ */
+export const createBooleanSnapshot = (initial) => {
+    let current = $state(initial);
+    const subscribers = new SvelteSet();
+    const state = {
+        get current() {
+            return current;
+        },
+        subscribe(run) {
+            subscribers.add(run);
+            run(current);
+            return () => {
+                subscribers.delete(run);
+            };
+        }
+    };
+    const set = (value) => {
+        if (value === current)
+            return;
+        current = value;
+        for (const sub of subscribers)
+            sub(value);
+    };
+    return [state, set];
+};

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

@@ -0,0 +1,98 @@
+/** Function returned by {@link useCycle} for advancing or jumping the index. */
+export type Cycle = (next?: number) => void;
+/**
+ * State returned by {@link useCycle}: an object with a reactive `.current`
+ * getter and a `cycle` function. Both reads and writes flow through the
+ * same object, so consumers don't need to destructure (which would
+ * snapshot `.current` and lose reactivity under runes).
+ */
+export type CycleState<T> = {
+    readonly current: T;
+    cycle: Cycle;
+};
+/**
+ * Function that returns the current items list, used by the reactive
+ * overload of {@link useCycle}. The function is re-invoked on every read
+ * so changes to the underlying reactive source propagate automatically.
+ */
+export type CycleItemsGetter<T> = () => readonly T[];
+/**
+ * Cycles through a series of values. Mirrors framer-motion's `useCycle`.
+ *
+ * Two call forms:
+ *
+ * - **Varargs** — `useCycle(...items)` — items are captured once and stay
+ *   fixed for the cycle's lifetime. Matches React framer-motion's signature.
+ * - **Reactive getter** — `useCycle(() => items)` — items are read on every
+ *   access, so passing a `$state`/`$derived` source lets the cycle pick up
+ *   list changes without recreating it.
+ *
+ * In both forms:
+ *
+ * - `state.current` is reactive — read it in templates / `$derived` / `$effect`
+ *   and it tracks both index changes and (in the getter form) item changes.
+ * - `state.cycle()` advances to the next item (wrapping at the end).
+ * - `state.cycle(i)` jumps to index `i`. The index is stored as-given;
+ *   `.current` then clamps on read so any out-of-range index — negative,
+ *   overflow, or items shrinking underneath the reactive-getter form —
+ *   resolves to the nearest valid edge (`items[0]` or `items[length - 1]`)
+ *   instead of `undefined`. This is a defensive divergence from React
+ *   framer-motion (which returns `items[i]`, possibly undefined) so the
+ *   reactive form stays safe and `.current` always honors its `T` type.
+ *   If the reactive getter ever returns an empty list, `.current` throws.
+ * - Calls that resolve to the current index are no-ops, matching React
+ *   `useState`'s `Object.is` bail-out.
+ *
+ * Two deliberate divergences from React's `useCycle`:
+ *
+ * 1. Return shape — React's `[value, cycle]` tuple can't survive
+ *    destructuring under Svelte 5 runes (snapshots the value, loses
+ *    reactivity), so we return `{ current, cycle }`.
+ * 2. Out-of-range reads always clamp (see above) instead of returning
+ *    `items[i]` undefined.
+ *
+ * Otherwise 1:1 with React, including same-index no-op bail-out and
+ * the `wrap(0, length, index + 1)` advance semantics.
+ *
+ * Ambiguity: `useCycle(fn)` with a single function value is treated as the
+ * reactive overload, not as a single-item cycle. To cycle through one
+ * function value, use `useCycle(() => [fn])` or just call it directly —
+ * a single-item cycle is a no-op anyway.
+ *
+ * @see https://motion.dev/docs/react-use-cycle
+ *
+ * @example Static varargs
+ * ```svelte
+ * <script lang="ts">
+ *   import { motion, useCycle } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useCycle(0, 50, 100)
+ * </script>
+ *
+ * <motion.div animate={{ x: x.current }} onclick={() => x.cycle()} />
+ * ```
+ *
+ * @example Reactive items
+ * ```svelte
+ * <script lang="ts">
+ *   let { labels }: { labels: string[] } = $props()
+ *   const variant = useCycle(() => labels)
+ * </script>
+ *
+ * <motion.div animate={variant.current} onclick={() => variant.cycle()} />
+ * ```
+ *
+ * @param itemsGetter Function returning the current items list; re-invoked
+ *   on every `.current` read so reactive sources propagate. Use this form
+ *   when items can change between mount and unmount. (Reactive overload.)
+ * @param items One or more values to cycle through. Captured once at call
+ *   time and fixed for the cycle's lifetime. (Varargs overload.)
+ * @returns A `CycleState<T>` with a reactive `.current` getter and a
+ *   `cycle(next?: number)` advance/jump function. `.current` always
+ *   honors its `T` type by clamping out-of-range indexes; it throws
+ *   if a reactive getter empties the items list mid-cycle.
+ *   `.cycle()` throws on non-integer (`NaN`, `1.5`, `Infinity`)
+ *   indexes and returns early as a no-op on empty items.
+ */
+export declare function useCycle<T>(itemsGetter: CycleItemsGetter<T>): CycleState<T>;
+export declare function useCycle<T>(...items: T[]): CycleState<T>;

package/dist/utils/cycle.svelte.js

@@ -0,0 +1,44 @@
+import { wrap } from 'motion';
+export function useCycle(...args) {
+    const getItems = args.length === 1 && typeof args[0] === 'function'
+        ? args[0]
+        : () => args;
+    if (getItems().length === 0) {
+        throw new Error('useCycle requires at least one item');
+    }
+    let index = $state(0);
+    return {
+        get current() {
+            const items = getItems();
+            // Reactive-getter form: if the consumer's source emptied
+            // mid-cycle the public type can no longer be honored. Throw
+            // loudly so the bug surfaces immediately rather than leaking
+            // `undefined` through a `T`-typed read.
+            if (items.length === 0) {
+                throw new Error('useCycle items getter returned an empty list');
+            }
+            // Clamp on read so out-of-range indexes (from `cycle(-5)` or
+            // `cycle(99)`, or items shrinking under us in the getter form)
+            // resolve to the nearest valid edge instead of `undefined`.
+            const safeIndex = index < 0 ? 0 : index >= items.length ? items.length - 1 : index;
+            return items[safeIndex];
+        },
+        cycle: (next) => {
+            const items = getItems();
+            if (items.length === 0)
+                return;
+            // Reject non-finite / non-integer indexes up-front: `NaN` slips
+            // past the read-time clamp (NaN comparisons return false for
+            // both `< 0` and `>= length`) and would silently make `.current`
+            // resolve to `undefined`, breaking the `T` contract. Throw
+            // loudly to surface the consumer bug at write-time.
+            if (typeof next === 'number' && !Number.isInteger(next)) {
+                throw new Error('useCycle index must be a finite integer');
+            }
+            const target = typeof next === 'number' ? next : wrap(0, items.length, index + 1);
+            if (target === index)
+                return;
+            index = target;
+        }
+    };
+}

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

@@ -0,0 +1,209 @@
+import { type AnimationOptions, type DOMKeyframesDefinition } from 'motion';
+import type { MotionViewport } from '../types.js';
+import { type BooleanSnapshot } from './booleanSnapshot.svelte.js';
+import { type ElementOrGetter } from './dom.js';
+/**
+ * Split a `whileInView` definition into the visual keyframes and an
+ * optional nested `transition`. Mirrors the shape framer-motion uses
+ * where a single object carries both the target values and their
+ * timing config.
+ *
+ * Defensive against `undefined` / `null` input: `def ?? {}` ensures
+ * destructuring never throws, and the returned `keyframes` is then an
+ * empty record.
+ *
+ * @param def `whileInView` record possibly carrying a nested
+ *   `transition` config. May be `null` / `undefined` defensively (the
+ *   spread normalises to `{}`).
+ * @returns Object with the keyframes (everything *except* `transition`)
+ *   and the extracted `transition` (or `undefined` if none was nested).
+ *
+ * @example
+ * ```ts
+ * splitInViewDefinition({ opacity: 1, y: 0, transition: { duration: 0.5 } })
+ * // → { keyframes: { opacity: 1, y: 0 }, transition: { duration: 0.5 } }
+ *
+ * splitInViewDefinition({ opacity: 1 })
+ * // → { keyframes: { opacity: 1 }, transition: undefined }
+ * ```
+ */
+export declare const splitInViewDefinition: (def: Record<string, unknown>) => {
+    keyframes: Record<string, unknown>;
+    transition?: AnimationOptions;
+};
+/**
+ * Compute the baseline values to restore to when an element leaves the
+ * viewport — only for the keys named in `whileInView`. Any key the
+ * element is not animating into stays as it was.
+ *
+ * For each key in `whileInView`, resolve a baseline by walking sources
+ * in this preference order:
+ *
+ * 1. `animate[key]` — the user's declared resting state
+ * 2. `initial[key]` — the pre-animation state
+ * 3. Neutral transform defaults (e.g. `x: 0`, `scale: 1`, `opacity: 1`)
+ *    when the key is a known transform property
+ * 4. Inline CSS function value (`var(...)`, `calc(...)`, `url(...)`)
+ *    read off `style.getPropertyValue` — handles cases where nested
+ *    semicolons (e.g. `url(data:...;base64,...)`) would break a
+ *    string-scrape
+ * 5. `getComputedStyle(el)[key]` — last resort
+ *
+ * The walk is per-key, so different baseline keys may be sourced from
+ * different layers.
+ *
+ * @param el Element whose computed style is read as the final fallback.
+ *   Must be a real DOM node (the function reads inline style and
+ *   `getComputedStyle`).
+ * @param opts Layered animation definitions:
+ * @param opts.initial Optional `initial` record from the component.
+ * @param opts.animate Optional `animate` record from the component.
+ * @param opts.whileInView The `whileInView` record — its keys drive
+ *   which baseline entries get computed. Nested `transition` is
+ *   stripped before walking.
+ * @returns A new record containing one entry per key found in
+ *   `opts.whileInView`. May be empty if `whileInView` is empty.
+ *
+ * @example
+ * ```ts
+ * computeInViewBaseline(element, {
+ *   initial: { opacity: 0, y: 50 },
+ *   animate: { opacity: 1, y: 0 },
+ *   whileInView: { opacity: 1, scale: 1.1 }
+ * })
+ * // → { opacity: 1, scale: 1 }
+ * //   opacity sourced from animate; scale falls to the neutral default.
+ * ```
+ */
+export declare const computeInViewBaseline: (el: HTMLElement, opts: {
+    initial?: Record<string, unknown>;
+    animate?: Record<string, unknown>;
+    whileInView?: Record<string, unknown>;
+}) => Record<string, unknown>;
+/**
+ * Wire a `whileInView` interaction onto an element using motion's
+ * `inView` primitive. On viewport entry the element animates to the
+ * supplied keyframes; on exit it animates back to a baseline computed
+ * via {@link computeInViewBaseline}.
+ *
+ * Used internally by `motion.<tag>` components to power the
+ * `whileInView` prop, and exposed for callers that want the same
+ * declarative behavior without going through a motion component.
+ *
+ * When `viewport.once` is `true`, the element latches on first entry
+ * — no exit animation runs, and the IntersectionObserver is detached
+ * via a `queueMicrotask(stop)` after the entry handler returns.
+ *
+ * @param el Target element to observe and animate.
+ * @param whileInView Keyframes to apply on entry. May carry a nested
+ *   `transition` config (extracted via {@link splitInViewDefinition}).
+ *   If `undefined`, the function returns a no-op cleanup without
+ *   creating an observer.
+ * @param mergedTransition Default transition used both when
+ *   `whileInView` has no nested `transition` and for the exit
+ *   animation back to baseline.
+ * @param callbacks Optional lifecycle hooks:
+ *   - `onStart` — fires on viewport entry, before the entry animation.
+ *   - `onEnd` — fires on viewport exit, after the baseline restore
+ *     animation kicks off. Not called when `viewport.once` is `true`.
+ *   - `onAnimationComplete` — fires when the entry animation
+ *     resolves; passed the keyframes that ran.
+ * @param baselineSources Sources for {@link computeInViewBaseline}'s
+ *   per-key walk:
+ *   - `initial` — the component's `initial` record.
+ *   - `animate` — the component's `animate` record.
+ * @param viewport IntersectionObserver options:
+ *   - `root` — scroll container (default page).
+ *   - `margin` — `rootMargin` string.
+ *   - `amount` — fraction visible required (defaults to `0` here so
+ *     any pixel counts).
+ *   - `once` — latch on first entry; skip exit animation.
+ * @returns A cleanup function that detaches the IntersectionObserver
+ *   on call. Safe to invoke after a `once` latch has already fired.
+ *
+ * @example
+ * ```ts
+ * const cleanup = attachWhileInView(
+ *   element,
+ *   { opacity: 1, y: 0, transition: { duration: 0.5 } },
+ *   { duration: 0.3 },
+ *   {
+ *     onStart: () => trackImpression(),
+ *     onEnd: () => console.log('left viewport')
+ *   },
+ *   { initial: { opacity: 0, y: 50 } },
+ *   { once: true, amount: 0.5 }
+ * )
+ * // Later — typically component teardown:
+ * cleanup()
+ * ```
+ */
+export declare const attachWhileInView: (el: HTMLElement, whileInView: Record<string, unknown> | undefined, mergedTransition: AnimationOptions, callbacks?: {
+    onStart?: () => void;
+    onEnd?: () => void;
+    onAnimationComplete?: (definition: DOMKeyframesDefinition | undefined) => void;
+}, baselineSources?: {
+    initial?: Record<string, unknown>;
+    animate?: Record<string, unknown>;
+}, viewport?: MotionViewport) => (() => void);
+/**
+ * Options accepted by `useInView`.
+ */
+export type UseInViewOptions = {
+    /** Element to use as the IntersectionObserver root. Defaults to the viewport. */
+    root?: ElementOrGetter;
+    /** CSS margin string applied to the root bounding box (e.g. `"100px 0px"`). */
+    margin?: string;
+    /** Fraction (0-1) or `"some"` / `"all"` of the target that must be visible. */
+    amount?: 'some' | 'all' | number;
+    /** When `true`, the state latches to `true` on first entry and never flips back. */
+    once?: boolean;
+    /** Initial value emitted before the first IntersectionObserver callback. */
+    initial?: boolean;
+};
+/**
+ * State returned by {@link useInView}.
+ */
+export type InViewState = BooleanSnapshot;
+/**
+ * Returns an `InViewState` that tracks whether `target` is in the viewport.
+ * Mirrors framer-motion's `useInView` adapted for Svelte 5 runes.
+ *
+ * `target` (and `options.root`) accept either an `HTMLElement` directly or
+ * a getter `() => HTMLElement | undefined`. With Svelte's `bind:this` the
+ * element isn't available until after mount, so element resolution is
+ * deferred — if the element isn't ready, the hook polls on
+ * `requestAnimationFrame` until it is.
+ *
+ * Lifecycle: the IntersectionObserver is bound to the surrounding reactive
+ * scope via `$effect`. The observer attaches at mount and detaches at
+ * unmount, regardless of how many consumers are reading `.current` or
+ * `.subscribe()`. This is a deliberate divergence from the previous
+ * store-based impl, which attached lazily on first subscribe.
+ *
+ * SSR-safe: returns a static `{ current: options.initial ?? false }` when
+ * `window` or `IntersectionObserver` is unavailable.
+ *
+ * @param target - Element (or getter) to observe.
+ * @param options - Optional `UseInViewOptions` (`root`, `margin`, `amount`,
+ *   `once`, `initial`).
+ * @returns A `InViewState` reflecting the target's viewport intersection.
+ * @see https://motion.dev/docs/react-use-in-view
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useInView } from '@humanspeak/svelte-motion'
+ *
+ *   let ref
+ *   const inView = useInView(() => ref, { once: true })
+ *
+ *   $effect(() => {
+ *     if (inView.current) trackImpression()
+ *   })
+ * </script>
+ *
+ * <div bind:this={ref}>{inView.current ? 'visible' : 'hidden'}</div>
+ * ```
+ */
+export declare const useInView: (target: ElementOrGetter, options?: UseInViewOptions) => InViewState;