@humanspeak/svelte-motion 0.4.8 → 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

@@ -13,14 +13,15 @@ export { useAnimationFrame } from './utils/animationFrame';
 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.svelte';
 export type { SpringMotionValue, UseSpringOptions } from './utils/spring.svelte';

package/dist/index.js

@@ -13,12 +13,12 @@ export { useAnimate } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
 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.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';

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/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;