@humanspeak/svelte-motion 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -6,7 +6,11 @@ export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cub
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionOnInViewEnd, MotionOnInViewStart, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, ReducedMotionConfig, Variants } from './types';
 export { useAnimationFrame } from './utils/animationFrame';
+export { useCycle } from './utils/cycle';
+export type { Cycle, CycleState } from './utils/cycle';
 export { createDragControls } from './utils/dragControls';
+export { useInView } from './utils/inView';
+export type { UseInViewOptions } from './utils/inView';
 export { useMotionTemplate } from './utils/motionTemplate';
 export { useMotionValue } from './utils/motionValue';
 export type { MotionValue } from './utils/motionValue';

package/dist/index.js

@@ -8,7 +8,9 @@ export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cub
 // Re-export utility functions
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export { useAnimationFrame } from './utils/animationFrame';
+export { useCycle } from './utils/cycle';
 export { createDragControls } from './utils/dragControls';
+export { useInView } from './utils/inView';
 export { useMotionTemplate } from './utils/motionTemplate';
 export { useMotionValue } from './utils/motionValue';
 export { useMotionValueEvent } from './utils/motionValueEvent';

package/dist/utils/attachable.d.ts

@@ -0,0 +1,74 @@
+import { type ElementOrGetter } from './dom.js';
+/**
+ * Reference set of DOM `ElementOrGetter` inputs keyed by name.
+ *
+ * Each value is either a resolved element, a getter that returns one (used
+ * with Svelte's `bind:this` post-mount timing), or `undefined` when the
+ * caller does not need this slot.
+ */
+export type AttachableRefs = Record<string, ElementOrGetter | undefined>;
+/**
+ * Map of resolved elements supplied to `onAttach`. Slots whose ref was
+ * `undefined` resolve to `undefined`.
+ */
+export type ResolvedRefs<R extends AttachableRefs> = {
+    [K in keyof R]: HTMLElement | undefined;
+};
+export type AttachableConfig<R extends AttachableRefs> = {
+    /** DOM refs that must resolve before `onAttach` runs. */
+    refs: R;
+    /**
+     * Called when every supplied ref has resolved. Receives a `stop` function
+     * that synchronously tears down the attachment - useful for one-shot
+     * latches that need to detach inside their own callback.
+     *
+     * Return a cleanup function for the standard "tear down on last
+     * unsubscribe" path.
+     */
+    onAttach: (els: ResolvedRefs<R>, stop: VoidFunction) => VoidFunction | void;
+    /**
+     * When this returns `true`, `subscribe` short-circuits without attaching.
+     * Used by hooks that latch a value and stop observing (e.g. `once`).
+     * Subscribers added after the latch increment the refcount but never
+     * trigger `onAttach`; their unsubscribe is a clean no-op.
+     */
+    isLatched?: () => boolean;
+};
+export type Attachable = {
+    /**
+     * Register a subscriber. Triggers `onAttach` on the first subscriber,
+     * polls on `requestAnimationFrame` until refs resolve. Returns a release
+     * function that cleans up when the last subscriber leaves.
+     *
+     * Callers must eventually unsubscribe; the rAF poll loop continues until
+     * either every ref resolves or the last subscriber releases.
+     */
+    subscribe: () => () => void;
+};
+/**
+ * Builds a subscriber-refcounted DOM-attachment primitive. Both `useScroll`
+ * and `useInView` use this to defer observer setup until a subscriber arrives,
+ * poll for `bind:this` element resolution, and tear down on the last
+ * unsubscribe.
+ *
+ * @param config Attachment configuration: refs to resolve, an `onAttach`
+ *   callback that returns a cleanup function, and an optional `isLatched`
+ *   short-circuit.
+ * @returns An `Attachable` exposing `subscribe()` for use inside Svelte
+ *   `readable(..., start)` callbacks.
+ * @example
+ * ```ts
+ * const attachable = createAttachable({
+ *     refs: { target },
+ *     onAttach: ({ target }) => {
+ *         const stopObserving = startObserver(target!, ...)
+ *         return stopObserving
+ *     }
+ * })
+ * return readable(initial, (set) => {
+ *     const release = attachable.subscribe()
+ *     return release
+ * })
+ * ```
+ */
+export declare const createAttachable: <R extends AttachableRefs>(config: AttachableConfig<R>) => Attachable;

package/dist/utils/attachable.js

@@ -0,0 +1,104 @@
+import { resolveElement } from './dom.js';
+/**
+ * Builds a subscriber-refcounted DOM-attachment primitive. Both `useScroll`
+ * and `useInView` use this to defer observer setup until a subscriber arrives,
+ * poll for `bind:this` element resolution, and tear down on the last
+ * unsubscribe.
+ *
+ * @param config Attachment configuration: refs to resolve, an `onAttach`
+ *   callback that returns a cleanup function, and an optional `isLatched`
+ *   short-circuit.
+ * @returns An `Attachable` exposing `subscribe()` for use inside Svelte
+ *   `readable(..., start)` callbacks.
+ * @example
+ * ```ts
+ * const attachable = createAttachable({
+ *     refs: { target },
+ *     onAttach: ({ target }) => {
+ *         const stopObserving = startObserver(target!, ...)
+ *         return stopObserving
+ *     }
+ * })
+ * return readable(initial, (set) => {
+ *     const release = attachable.subscribe()
+ *     return release
+ * })
+ * ```
+ */
+export const createAttachable = (config) => {
+    let cleanup;
+    let pollRaf = 0;
+    let subscriberCount = 0;
+    // When stop() runs synchronously inside onAttach, cleanup hasn't been
+    // assigned yet. Defer the teardown so the just-returned disposer still
+    // gets invoked.
+    let attaching = false;
+    let stopRequestedDuringAttach = false;
+    const cancelPoll = () => {
+        if (pollRaf) {
+            cancelAnimationFrame(pollRaf);
+            pollRaf = 0;
+        }
+    };
+    const stop = () => {
+        cancelPoll();
+        if (attaching) {
+            stopRequestedDuringAttach = true;
+            return;
+        }
+        if (cleanup) {
+            const fn = cleanup;
+            cleanup = undefined;
+            fn();
+        }
+    };
+    const tryAttach = () => {
+        if (cleanup || config.isLatched?.())
+            return;
+        const els = {};
+        let needsPoll = false;
+        for (const key of Object.keys(config.refs)) {
+            const ref = config.refs[key];
+            const el = resolveElement(ref);
+            if (ref && !el)
+                needsPoll = true;
+            els[key] = el;
+        }
+        if (needsPoll) {
+            if (!pollRaf) {
+                pollRaf = requestAnimationFrame(() => {
+                    pollRaf = 0;
+                    tryAttach();
+                });
+            }
+            return;
+        }
+        attaching = true;
+        let result;
+        try {
+            result = config.onAttach(els, stop);
+        }
+        finally {
+            attaching = false;
+        }
+        if (typeof result === 'function')
+            cleanup = result;
+        if (stopRequestedDuringAttach) {
+            stopRequestedDuringAttach = false;
+            stop();
+        }
+    };
+    return {
+        subscribe: () => {
+            subscriberCount++;
+            tryAttach();
+            return () => {
+                if (subscriberCount > 0)
+                    subscriberCount--;
+                if (subscriberCount > 0)
+                    return;
+                stop();
+            };
+        }
+    };
+};

package/dist/utils/cycle.d.ts

@@ -0,0 +1,35 @@
+import { type Readable } from 'svelte/store';
+export type Cycle = (next?: number) => void;
+export type CycleState<T> = [Readable<T>, Cycle];
+/**
+ * Cycles through a series of values. Mirrors Framer Motion's `useCycle`.
+ *
+ * Returns a tuple `[value, cycle]`:
+ *
+ * - `value` is a Svelte readable store of the current item; subscribe with
+ *   `$value` in templates.
+ * - `cycle()` advances to the next item, wrapping back to index `0` when it
+ *   passes the end.
+ * - `cycle(i)` jumps to the item at index `i`. The index is taken as-is to
+ *   match `framer-motion` &mdash; out-of-range values yield `items[i]`, which
+ *   may be `undefined`.
+ *
+ * Calls that resolve to the current index are no-ops and do not notify
+ * subscribers, matching React `useState`'s `Object.is` bail-out semantics.
+ *
+ * @param items - Items to cycle through. Must include at least one item.
+ * @returns A `[Readable<T>, Cycle]` tuple.
+ * @see https://motion.dev/docs/react-use-cycle
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { motion, useCycle } from '@humanspeak/svelte-motion'
+ *
+ *   const [x, cycleX] = useCycle(0, 50, 100)
+ * </script>
+ *
+ * <motion.div animate={{ x: $x }} onclick={() => cycleX()} />
+ * ```
+ */
+export declare const useCycle: <T>(...items: T[]) => CycleState<T>;

package/dist/utils/cycle.js

@@ -0,0 +1,48 @@
+import { wrap } from 'motion';
+import { writable } from 'svelte/store';
+/**
+ * Cycles through a series of values. Mirrors Framer Motion's `useCycle`.
+ *
+ * Returns a tuple `[value, cycle]`:
+ *
+ * - `value` is a Svelte readable store of the current item; subscribe with
+ *   `$value` in templates.
+ * - `cycle()` advances to the next item, wrapping back to index `0` when it
+ *   passes the end.
+ * - `cycle(i)` jumps to the item at index `i`. The index is taken as-is to
+ *   match `framer-motion` — out-of-range values yield `items[i]`, which
+ *   may be `undefined`.
+ *
+ * Calls that resolve to the current index are no-ops and do not notify
+ * subscribers, matching React `useState`'s `Object.is` bail-out semantics.
+ *
+ * @param items - Items to cycle through. Must include at least one item.
+ * @returns A `[Readable<T>, Cycle]` tuple.
+ * @see https://motion.dev/docs/react-use-cycle
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { motion, useCycle } from '@humanspeak/svelte-motion'
+ *
+ *   const [x, cycleX] = useCycle(0, 50, 100)
+ * </script>
+ *
+ * <motion.div animate={{ x: $x }} onclick={() => cycleX()} />
+ * ```
+ */
+export const useCycle = (...items) => {
+    if (items.length === 0) {
+        throw new Error('useCycle requires at least one item');
+    }
+    let index = 0;
+    const store = writable(items[0]);
+    const cycle = (next) => {
+        const target = typeof next === 'number' ? next : wrap(0, items.length, index + 1);
+        if (target === index)
+            return;
+        index = target;
+        store.set(items[target]);
+    };
+    return [{ subscribe: store.subscribe }, cycle];
+};

package/dist/utils/dom.d.ts

@@ -14,3 +14,30 @@
  * @return Whether the value is a DOM `Element`.
  */
 export declare const isDomElement: (v: unknown) => v is Element;
+/**
+ * An element reference - either an element directly or a getter function
+ * that returns one. Getters defer resolution past mount, which is useful
+ * with Svelte's `bind:this` where the element isn't available synchronously.
+ *
+ * Both `null` and `undefined` returns from the getter are normalised to
+ * `undefined` by `resolveElement`, so either nullable shape works.
+ */
+export type ElementOrGetter = HTMLElement | (() => HTMLElement | null | undefined);
+/**
+ * Resolves an `ElementOrGetter` to an `HTMLElement`, or `undefined` if not
+ * yet available (e.g. a getter is supplied but the bound element hasn't
+ * mounted).
+ *
+ * Coerces a `null` getter result to `undefined` so the common
+ * `let el: HTMLElement | null = null` `bind:this` pattern lines up with the
+ * declared return type.
+ *
+ * @param ref Element or getter to resolve.
+ * @returns The resolved element, or `undefined` when not yet available.
+ * @example
+ * ```ts
+ * let node: HTMLElement | null = null
+ * resolveElement(() => node) // => undefined until bind:this fires
+ * ```
+ */
+export declare const resolveElement: (ref?: ElementOrGetter) => HTMLElement | undefined;

package/dist/utils/dom.js

@@ -16,3 +16,26 @@
 export const isDomElement = (v) => {
     return !!v && typeof v.getBoundingClientRect === 'function';
 };
+/**
+ * Resolves an `ElementOrGetter` to an `HTMLElement`, or `undefined` if not
+ * yet available (e.g. a getter is supplied but the bound element hasn't
+ * mounted).
+ *
+ * Coerces a `null` getter result to `undefined` so the common
+ * `let el: HTMLElement | null = null` `bind:this` pattern lines up with the
+ * declared return type.
+ *
+ * @param ref Element or getter to resolve.
+ * @returns The resolved element, or `undefined` when not yet available.
+ * @example
+ * ```ts
+ * let node: HTMLElement | null = null
+ * resolveElement(() => node) // => undefined until bind:this fires
+ * ```
+ */
+export const resolveElement = (ref) => {
+    if (!ref)
+        return undefined;
+    const value = typeof ref === 'function' ? ref() : ref;
+    return value ?? undefined;
+};

package/dist/utils/inView.d.ts

@@ -1,4 +1,6 @@
 import { type AnimationOptions, type DOMKeyframesDefinition } from 'motion';
+import { type Readable } from 'svelte/store';
+import { type ElementOrGetter } from './dom.js';
 /**
  * Split a whileInView definition into keyframes and an optional nested transition.
  *
@@ -41,21 +43,21 @@ export declare const computeInViewBaseline: (el: HTMLElement, opts: {
     whileInView?: Record<string, unknown>;
 }) => Record<string, unknown>;
 /**
- * Attach whileInView interactions to an element using IntersectionObserver.
+ * Attach whileInView interactions to an element via motion's `inView` primitive.
  *
- * On intersection (element enters viewport), animates to `whileInView` state
- * (using nested `transition` if provided). On un-intersection, restores changed
- * keys to the baseline using the merged root/component transition.
+ * On entry, animates to `whileInView` state (using the nested `transition` if
+ * provided). On exit, restores the changed keys to a baseline computed from
+ * `initial` / `animate` / neutral transform defaults / inline styles.
  *
- * Critical fix for issue #230: Checks `entry.isIntersecting` immediately on
- * first callback to handle elements already in viewport on mount.
+ * Delegates to motion's `inView` so the IntersectionObserver implementation
+ * is shared with the public `useInView` hook.
  *
  * @param el Target element.
  * @param whileInView While-in-view definition.
  * @param mergedTransition Root/component merged transition.
  * @param callbacks Optional lifecycle callbacks for in-view start/end and animation completion.
  * @param baselineSources Optional sources used to compute baseline.
- * @returns Cleanup function to disconnect the IntersectionObserver.
+ * @returns Cleanup function to stop observing.
  * @example
  * const cleanup = attachWhileInView(
  *   element,
@@ -67,7 +69,7 @@ export declare const computeInViewBaseline: (el: HTMLElement, opts: {
  *   },
  *   { initial: { opacity: 0, y: 50 } }
  * )
- * // Later: cleanup() to disconnect observer
+ * // Later: cleanup() to stop observing
  */
 export declare const attachWhileInView: (el: HTMLElement, whileInView: Record<string, unknown> | undefined, mergedTransition: AnimationOptions, callbacks?: {
     onStart?: () => void;
@@ -77,3 +79,55 @@ export declare const attachWhileInView: (el: HTMLElement, whileInView: Record<st
     initial?: Record<string, unknown>;
     animate?: Record<string, unknown>;
 }) => (() => 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 store latches to `true` on first entry and never flips back. */
+    once?: boolean;
+    /** Initial value emitted before the first IntersectionObserver callback. */
+    initial?: boolean;
+};
+/**
+ * Returns a Svelte readable store that tracks whether `target` is in the
+ * viewport. Mirrors Framer Motion's `useInView` so the same options
+ * (`root`, `margin`, `amount`, `once`, `initial`) work as in React.
+ *
+ * `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 until the first subscriber arrives; if the element isn't ready,
+ * the hook polls on `requestAnimationFrame` until it is.
+ *
+ * SSR-safe: returns a static `readable(initial)` when `window` or
+ * `IntersectionObserver` is unavailable.
+ *
+ * @param target - Element (or getter) to observe.
+ * @param options - Optional `UseInViewOptions` (`root`, `margin`, `amount`,
+ *   `once`, `initial`).
+ * @returns A `Readable<boolean>` that flips to `true` while `target` is in view.
+ * @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) trackImpression()
+ *   })
+ * </script>
+ *
+ * <div bind:this={ref}>{$inView ? 'visible' : 'hidden'}</div>
+ * ```
+ */
+export declare const useInView: (target: ElementOrGetter, options?: UseInViewOptions) => Readable<boolean>;

package/dist/utils/inView.js

@@ -1,4 +1,30 @@
-import { animate } from 'motion';
+import { animate, inView as motionInView } from 'motion';
+import { readable, writable } from 'svelte/store';
+import { createAttachable } from './attachable.js';
+import {} from './dom.js';
+const CSS_FUNCTION_RE = /\b(var|calc|min|max|clamp|rgb|rgba|hsl|hsla|url)\s*\(/i;
+/**
+ * Read an inline CSS-function value (var/calc/url/etc.) for `propName`
+ * directly from the element's style declaration. Returns `null` for missing
+ * or non-function values so the caller can fall back to `getComputedStyle`.
+ *
+ * Uses `style.getPropertyValue` so values like `url(data:image/svg+xml;...)`
+ * with nested semicolons are preserved intact - the browser has already
+ * parsed the declaration, no string scraping required.
+ *
+ * @param el Element whose inline style is read.
+ * @param propName Camel-case JS property name (e.g. `borderColor`).
+ * @returns The inline CSS function value, or `null`.
+ * @example
+ * getInlineCssFunction(node, 'background') // => 'var(--brand)' | null
+ */
+const getInlineCssFunction = (el, propName) => {
+    const kebab = propName.replace(/([A-Z])/g, '-$1').toLowerCase();
+    const value = el.style.getPropertyValue(kebab).trim();
+    if (!value)
+        return null;
+    return CSS_FUNCTION_RE.test(value) ? value : null;
+};
 /**
  * Split a whileInView definition into keyframes and an optional nested transition.
  *
@@ -59,27 +85,6 @@ export const computeInViewBaseline = (el, opts) => {
         opacity: 1
     };
     const cs = getComputedStyle(el);
-    const inlineStyle = el.getAttribute('style') || '';
-    // Helper to escape regex metacharacters to prevent ReDoS and ensure literal matching
-    const escapeRegExp = (str) => {
-        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    };
-    // Helper to extract CSS function (var, calc, min, max, etc.) from inline style if present
-    const getInlineStyleValue = (propName) => {
-        const kebabCase = propName.replace(/([A-Z])/g, '-$1').toLowerCase();
-        const escapedKebabCase = escapeRegExp(kebabCase);
-        // Match property name at start of string or after semicolon
-        const regex = new RegExp(`(?:^|;)\\s*${escapedKebabCase}\\s*:\\s*([^;]+)`, 'i');
-        const match = inlineStyle.match(regex);
-        if (match) {
-            const value = match[1].trim();
-            // Preserve CSS functions: var(), calc(), min(), max(), clamp(), rgb(), hsl(), url(), etc.
-            if (/\b(var|calc|min|max|clamp|rgb|rgba|hsl|hsla|url)\s*\(/.test(value)) {
-                return value;
-            }
-        }
-        return null;
-    };
     for (const key of Object.keys(whileInViewRecord)) {
         if (Object.prototype.hasOwnProperty.call(animateRecord, key)) {
             baseline[key] = animateRecord[key];
@@ -91,8 +96,7 @@ export const computeInViewBaseline = (el, opts) => {
             baseline[key] = neutralTransformDefaults[key];
         }
         else {
-            // Check if inline style has a CSS variable for this property
-            const inlineValue = getInlineStyleValue(key);
+            const inlineValue = getInlineCssFunction(el, key);
             if (inlineValue) {
                 baseline[key] = inlineValue;
             }
@@ -104,21 +108,21 @@ export const computeInViewBaseline = (el, opts) => {
     return baseline;
 };
 /**
- * Attach whileInView interactions to an element using IntersectionObserver.
+ * Attach whileInView interactions to an element via motion's `inView` primitive.
  *
- * On intersection (element enters viewport), animates to `whileInView` state
- * (using nested `transition` if provided). On un-intersection, restores changed
- * keys to the baseline using the merged root/component transition.
+ * On entry, animates to `whileInView` state (using the nested `transition` if
+ * provided). On exit, restores the changed keys to a baseline computed from
+ * `initial` / `animate` / neutral transform defaults / inline styles.
  *
- * Critical fix for issue #230: Checks `entry.isIntersecting` immediately on
- * first callback to handle elements already in viewport on mount.
+ * Delegates to motion's `inView` so the IntersectionObserver implementation
+ * is shared with the public `useInView` hook.
  *
  * @param el Target element.
  * @param whileInView While-in-view definition.
  * @param mergedTransition Root/component merged transition.
  * @param callbacks Optional lifecycle callbacks for in-view start/end and animation completion.
  * @param baselineSources Optional sources used to compute baseline.
- * @returns Cleanup function to disconnect the IntersectionObserver.
+ * @returns Cleanup function to stop observing.
  * @example
  * const cleanup = attachWhileInView(
  *   element,
@@ -130,50 +134,113 @@ export const computeInViewBaseline = (el, opts) => {
  *   },
  *   { initial: { opacity: 0, y: 50 } }
  * )
- * // Later: cleanup() to disconnect observer
+ * // Later: cleanup() to stop observing
  */
 export const attachWhileInView = (el, whileInView, mergedTransition, callbacks, baselineSources) => {
     if (!whileInView)
         return () => { };
-    let hasAnimated = false;
-    let inViewBaseline = null;
-    const observer = new IntersectionObserver((entries) => {
-        for (const entry of entries) {
-            if (entry.isIntersecting && !hasAnimated) {
-                // Element entered viewport: animate to whileInView state
-                hasAnimated = true;
-                inViewBaseline = computeInViewBaseline(el, {
-                    initial: baselineSources?.initial,
-                    animate: baselineSources?.animate,
-                    whileInView
-                });
-                callbacks?.onStart?.();
-                const { keyframes, transition } = splitInViewDefinition(whileInView);
-                const animation = animate(el, keyframes, (transition ?? mergedTransition));
-                // Call onAnimationComplete when animation finishes
-                animation.finished
-                    .then(() => {
-                    callbacks?.onAnimationComplete?.(keyframes);
-                })
-                    .catch(() => {
-                    // Animation was cancelled, don't call completion callback
-                });
-            }
-            else if (!entry.isIntersecting && hasAnimated) {
-                // Element left viewport: animate back to baseline
-                if (inViewBaseline && Object.keys(inViewBaseline).length > 0) {
-                    animate(el, inViewBaseline, mergedTransition);
-                }
-                callbacks?.onEnd?.();
-                hasAnimated = false;
+    return motionInView(el, () => {
+        const inViewBaseline = computeInViewBaseline(el, {
+            initial: baselineSources?.initial,
+            animate: baselineSources?.animate,
+            whileInView
+        });
+        callbacks?.onStart?.();
+        const { keyframes, transition } = splitInViewDefinition(whileInView);
+        const animation = animate(el, keyframes, (transition ?? mergedTransition));
+        animation.finished
+            .then(() => {
+            callbacks?.onAnimationComplete?.(keyframes);
+        })
+            .catch(() => {
+            /* animation cancelled — skip completion callback */
+        });
+        return () => {
+            if (Object.keys(inViewBaseline).length > 0) {
+                animate(el, inViewBaseline, mergedTransition);
             }
-        }
-    }, { threshold: 0 } // Fire as soon as any part is visible
-    );
-    // Start observing - IntersectionObserver fires immediately for already-visible elements
-    observer.observe(el);
-    // Return cleanup function
-    return () => {
-        observer.disconnect();
+            callbacks?.onEnd?.();
+        };
+    }, { amount: 0 });
+};
+/**
+ * Returns a Svelte readable store that tracks whether `target` is in the
+ * viewport. Mirrors Framer Motion's `useInView` so the same options
+ * (`root`, `margin`, `amount`, `once`, `initial`) work as in React.
+ *
+ * `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 until the first subscriber arrives; if the element isn't ready,
+ * the hook polls on `requestAnimationFrame` until it is.
+ *
+ * SSR-safe: returns a static `readable(initial)` when `window` or
+ * `IntersectionObserver` is unavailable.
+ *
+ * @param target - Element (or getter) to observe.
+ * @param options - Optional `UseInViewOptions` (`root`, `margin`, `amount`,
+ *   `once`, `initial`).
+ * @returns A `Readable<boolean>` that flips to `true` while `target` is in view.
+ * @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) trackImpression()
+ *   })
+ * </script>
+ *
+ * <div bind:this={ref}>{$inView ? 'visible' : 'hidden'}</div>
+ * ```
+ */
+export const useInView = (target, options = {}) => {
+    const initial = options.initial ?? false;
+    if (typeof window === 'undefined' || typeof IntersectionObserver === 'undefined') {
+        return readable(initial);
+    }
+    const store = writable(initial);
+    let current = initial;
+    const update = (next) => {
+        if (next === current)
+            return;
+        current = next;
+        store.set(next);
     };
+    let latched = false;
+    const attachable = createAttachable({
+        refs: { target, root: options.root },
+        isLatched: () => latched,
+        onAttach: ({ target: el, root }, stop) => motionInView(el, () => {
+            update(true);
+            if (options.once) {
+                // Detach inside the entry callback; motion's inView
+                // handles re-entry safely via observer.unobserve.
+                latched = true;
+                stop();
+                return;
+            }
+            return () => update(false);
+        }, {
+            root: root,
+            // framer-motion types `margin` as a CSS-shorthand template
+            // literal; we expose plain `string` so the public API is
+            // ergonomic and forward-compat with future motion changes.
+            margin: options.margin,
+            amount: options.amount
+        })
+    });
+    return readable(initial, (set) => {
+        const release = attachable.subscribe();
+        const unsub = store.subscribe(set);
+        return () => {
+            unsub();
+            release();
+        };
+    });
 };

package/dist/utils/scroll.d.ts

@@ -1,15 +1,10 @@
 import { type Readable } from 'svelte/store';
+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]`.
  */
 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`.
  */

package/dist/utils/scroll.js

@@ -1,13 +1,7 @@
 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;
-};
+import { createAttachable } from './attachable.js';
+import {} from './dom.js';
 /**
  * Creates scroll-linked Svelte stores for building scroll-driven animations
  * such as progress indicators and parallax effects.
@@ -54,29 +48,9 @@ export const useScroll = (options) => {
         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) => {
+    const attachable = createAttachable({
+        refs: { container: options?.container, target: options?.target },
+        onAttach: ({ container, target }) => scroll((_progress, info) => {
             stores.scrollX.set(info.x.current);
             stores.scrollY.set(info.y.current);
             stores.scrollXProgress.set(info.x.progress);
@@ -86,28 +60,14 @@ export const useScroll = (options) => {
             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 release = attachable.subscribe();
         const unsub = stores[key].subscribe(set);
-        attach();
         return () => {
             unsub();
-            subscriberCount--;
-            detach();
+            release();
         };
     });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A Framer Motion-compatible 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",