use-scroll-animate 1.4.0 → 2.0.0

package/dist/svelte.d.cts

@@ -0,0 +1,244 @@
+/**
+ * use-scroll-animate - Core Type Definitions
+ * A lightweight, high-performance scroll animation library
+ */
+/** Built-in animation presets */
+type AnimationPreset = 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left' | 'fade-in-right' | 'zoom-in' | 'zoom-out' | 'flip-x' | 'flip-y' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'bounce' | 'rotate-in' | 'blur-in' | 'skew-in' | 'scale-x' | 'scale-y' | 'shimmer' | 'pulse' | 'swing' | 'scale-up' | 'blur-in-up' | 'flip-up' | 'flip-down' | 'rotate-left' | 'rotate-right' | 'clip-up' | 'clip-down' | 'clip-left' | 'clip-right' | 'clip-circle';
+/**
+ * How `onProgress` (and parallax) progress is measured.
+ * - `'ratio'` (default): the element's visible ratio (IntersectionObserver `intersectionRatio`).
+ * - `'scroll'`: true scroll progress, 0 when the element's top touches the bottom of the
+ *   viewport and 1 when its bottom leaves the top. Works for elements taller than the screen.
+ */
+type ProgressMode = 'ratio' | 'scroll';
+/**
+ * Which engine runs the entrance animation.
+ * - `'js'`: IntersectionObserver triggers a time-based Web Animation.
+ * - `'css'`: the preset runs on the browser's native scroll-driven timeline
+ *   (`animation-timeline: view()`), so its progress follows the scroll position
+ *   off the main thread. Falls back to `'js'` where unsupported.
+ * - `'auto'` (default since 2.0): native when supported, JS otherwise — and JS
+ *   whenever the element sets `duration`, `delay`, `offset` or `stagger` itself,
+ *   since those only mean something for a time-based animation.
+ */
+type ScrollEngine = 'auto' | 'js' | 'css';
+/** Easing function types */
+type EasingType = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'soft-spring' | 'heavy-bounce' | [number, number, number, number] | ((t: number) => number) | string;
+/** Keyframe definition for custom animations */
+interface AnimationKeyframe {
+    [property: string]: string | number;
+}
+/** Custom animation definition */
+interface CustomAnimation {
+    from: AnimationKeyframe;
+    to: AnimationKeyframe;
+}
+/** Parallax configuration */
+interface ParallaxOptions {
+    /** Movement on X axis (e.g., '100px', '20%') */
+    x?: string | number;
+    /** Movement on Y axis (e.g., '100px', '20%') */
+    y?: string | number;
+    /** Rotation in degrees */
+    rotate?: number;
+    /** Scale factor */
+    scale?: number;
+    /** Speed multiplier (default: 1) */
+    speed?: number;
+}
+/** Per-element animation options */
+interface AnimateOptions {
+    /** Animation preset name, array of presets, or custom animation object */
+    animation?: AnimationPreset | AnimationPreset[] | CustomAnimation;
+    /** Duration in milliseconds (default: 600) */
+    duration?: number;
+    /** Delay in milliseconds (default: 0) */
+    delay?: number;
+    /** Easing function (default: 'ease') */
+    easing?: EasingType;
+    /** Intersection threshold 0-1 (default: 0.1) */
+    threshold?: number | number[];
+    /** Root margin for IntersectionObserver (default: '0px') */
+    rootMargin?: string;
+    /** Whether to replay animation each time element enters viewport (default: false) */
+    repeat?: boolean;
+    /** Whether to trigger animation only once (default: true if repeat is false) */
+    once?: boolean;
+    /** Offset in pixels from the viewport edge to trigger animation (default: 0) */
+    offset?: number;
+    /** Stagger delay for child elements in ms (default: 0) */
+    stagger?: number;
+    /** Parallax effect configuration */
+    parallax?: ParallaxOptions;
+    /** Callback fired when animation starts */
+    onStart?: (element: Element) => void;
+    /** Callback fired when animation completes */
+    onComplete?: (element: Element) => void;
+    /** Callback fired when element enters viewport */
+    onEnter?: (element: Element) => void;
+    /** Callback fired when element leaves viewport */
+    onLeave?: (element: Element) => void;
+    /** Callback fired with scroll progress (0 to 1) */
+    onProgress?: (element: Element, progress: number) => void;
+    /** How progress for `onProgress`/parallax is measured (default: 'ratio') */
+    progressMode?: ProgressMode;
+    /**
+     * Name of a CSS custom property (e.g. `'--sa-progress'`) that receives the
+     * element's progress (0 to 1, same value as `onProgress`) as an inline
+     * style, for scroll-driven effects written in plain CSS. Off by default.
+     */
+    progressVar?: string;
+    /**
+     * Animation engine (default: `'auto'`, see `ScrollEngine`). With the native
+     * engine the animation is linked to scroll position: `duration`, `delay`,
+     * `threshold`, `offset` and `stagger` do not apply; `viewRange` does.
+     */
+    engine?: ScrollEngine;
+    /**
+     * Native engine only: the view-timeline range the entrance animation spans,
+     * as `[rangeStart, rangeEnd]` (default: `['entry 0%', 'entry 100%']`).
+     */
+    viewRange?: [string, string];
+    /**
+     * Animate out when the element leaves the viewport, and back in when it
+     * re-enters (implies `repeat: true` unless `repeat` is set).
+     * - `true`: play the entrance animation in reverse.
+     * - a preset / presets / `{ from, to }`: play that animation in reverse
+     *   (e.g. `exit: 'fade-in-down'` leaves upwards).
+     * Skipped under reduced motion. (default: `false`)
+     */
+    exit?: boolean | AnimationPreset | AnimationPreset[] | CustomAnimation;
+}
+/** Global configuration for ScrollAnimate instance */
+interface ScrollAnimateConfig {
+    /** Default animation preset (default: 'fade-in-up') */
+    defaultAnimation?: AnimationPreset | AnimationPreset[] | CustomAnimation;
+    /** Default duration in ms (default: 600) */
+    defaultDuration?: number;
+    /** Default delay in ms (default: 0) */
+    defaultDelay?: number;
+    /** Default easing (default: 'ease') */
+    defaultEasing?: EasingType;
+    /** Default threshold (default: 0.1) */
+    defaultThreshold?: number | number[];
+    /** Default root margin (default: '0px') */
+    defaultRootMargin?: string;
+    /** Whether animations replay by default (default: false) */
+    defaultRepeat?: boolean;
+    /** Default once setting (default: true) */
+    defaultOnce?: boolean;
+    /** Default offset in pixels (default: 0) */
+    defaultOffset?: number;
+    /** CSS class added before animation (default: 'sa-hidden') */
+    hiddenClass?: string;
+    /** CSS class added when element is visible (default: 'sa-visible') */
+    visibleClass?: string;
+    /** Whether to use CSS class-based animation instead of Web Animations API */
+    useClassNames?: boolean;
+    /** Disable all animations (useful for reduced-motion preference) */
+    disabled?: boolean;
+    /** Custom IntersectionObserver root element */
+    root?: Element | null;
+    /**
+     * Drop `once` elements from the registry as soon as their entrance animation
+     * has been triggered (unless they still need parallax/onProgress), so they can
+     * be garbage-collected. They are remembered in a WeakSet, so `init()`/`observe()`
+     * never re-hide or replay them. (default: true)
+     */
+    autoUnregister?: boolean;
+    /** Default animation engine (default: `'auto'`; `'js'` restores the 1.x behaviour) */
+    defaultEngine?: ScrollEngine;
+}
+/** Registered element entry */
+interface AnimatedElement {
+    element: Element;
+    options: Required<AnimateOptions>;
+    observer: IntersectionObserver;
+    animated: boolean;
+    progressObserver?: IntersectionObserver;
+    /** Engine actually used for this element (`'css'` = native scroll-driven timeline) */
+    engine?: 'js' | 'css';
+}
+/** ScrollAnimate public API */
+interface ScrollAnimateInstance {
+    /** Observe a single element or CSS selector */
+    observe(target: string | Element | NodeList | Element[], options?: AnimateOptions): void;
+    /** Stop observing a single element or CSS selector */
+    unobserve(target: string | Element | NodeList | Element[]): void;
+    /** Observe all elements matching the data-sa attribute */
+    init(rootElement?: Element | Document): void;
+    /**
+     * Like `init()`, then keep watching `rootElement` (default: `document`) with a
+     * MutationObserver: `[data-sa]` elements added later (or that gain the
+     * attribute) are observed automatically, and removed ones are released.
+     * Returns a function that stops watching. `destroy()` stops every watcher.
+     * SSR-safe: a no-op without a DOM / MutationObserver.
+     */
+    watch(rootElement?: Element | Document): () => void;
+    /** Destroy the instance and clean up all observers */
+    destroy(): void;
+    /** Refresh all observers (useful after DOM changes) */
+    refresh(): void;
+    /** Manually trigger animation on an element */
+    animate(target: string | Element, options?: AnimateOptions): void;
+    /** Get all currently observed elements */
+    getObservedElements(): AnimatedElement[];
+    /** Update global configuration */
+    configure(config: Partial<ScrollAnimateConfig>): void;
+}
+
+/**
+ * use-scroll-animate - Staggered children
+ * Reveal a container's children one after another when the container scrolls
+ * into view, optionally also animating children that are added later.
+ */
+
+interface StaggerOptions extends AnimateOptions {
+    /** Delay between consecutive children in ms (default: 80) */
+    stagger?: number;
+    /**
+     * Watch the container with a MutationObserver and animate children added
+     * later (e.g. infinite lists). Children added after the container was
+     * revealed animate when they scroll into view, staggered per batch.
+     * (default: false)
+     */
+    observeChildren?: boolean;
+}
+
+/**
+ * use-scroll-animate - Svelte integration
+ *
+ * Svelte actions (no import from `svelte` needed, works with Svelte 3, 4 and 5):
+ *
+ * ```svelte
+ * <script>
+ *   import { scrollAnimate, scrollStagger } from 'use-scroll-animate/svelte';
+ * </script>
+ * <div use:scrollAnimate={{ animation: 'fade-in-up', duration: 800 }}>…</div>
+ * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>
+ * ```
+ */
+
+interface ScrollAnimateActionOptions extends AnimateOptions {
+    /** Instance to register with (default: a shared instance created on first use) */
+    instance?: ScrollAnimateInstance;
+}
+interface ScrollStaggerActionOptions extends StaggerOptions {
+    instance?: ScrollAnimateInstance;
+}
+/** Shape of a Svelte action's return value. */
+interface ActionReturn<P> {
+    update?: (parameter: P) => void;
+    destroy?: () => void;
+}
+/**
+ * Animate `node` when it scrolls into view. Changing the parameter updates the
+ * callbacks right away; other options are applied if the element has not
+ * animated yet.
+ */
+declare function scrollAnimate(node: Element, options?: ScrollAnimateActionOptions): ActionReturn<ScrollAnimateActionOptions | undefined>;
+/** Stagger the children of `node` when it scrolls into view (`observeChildren: true` also animates children added later). */
+declare function scrollStagger(node: Element, options?: ScrollStaggerActionOptions): ActionReturn<ScrollStaggerActionOptions | undefined>;
+
+export { scrollAnimate, scrollStagger };
+export type { ActionReturn, ScrollAnimateActionOptions, ScrollStaggerActionOptions };

package/dist/svelte.d.ts

@@ -0,0 +1,244 @@
+/**
+ * use-scroll-animate - Core Type Definitions
+ * A lightweight, high-performance scroll animation library
+ */
+/** Built-in animation presets */
+type AnimationPreset = 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left' | 'fade-in-right' | 'zoom-in' | 'zoom-out' | 'flip-x' | 'flip-y' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'bounce' | 'rotate-in' | 'blur-in' | 'skew-in' | 'scale-x' | 'scale-y' | 'shimmer' | 'pulse' | 'swing' | 'scale-up' | 'blur-in-up' | 'flip-up' | 'flip-down' | 'rotate-left' | 'rotate-right' | 'clip-up' | 'clip-down' | 'clip-left' | 'clip-right' | 'clip-circle';
+/**
+ * How `onProgress` (and parallax) progress is measured.
+ * - `'ratio'` (default): the element's visible ratio (IntersectionObserver `intersectionRatio`).
+ * - `'scroll'`: true scroll progress, 0 when the element's top touches the bottom of the
+ *   viewport and 1 when its bottom leaves the top. Works for elements taller than the screen.
+ */
+type ProgressMode = 'ratio' | 'scroll';
+/**
+ * Which engine runs the entrance animation.
+ * - `'js'`: IntersectionObserver triggers a time-based Web Animation.
+ * - `'css'`: the preset runs on the browser's native scroll-driven timeline
+ *   (`animation-timeline: view()`), so its progress follows the scroll position
+ *   off the main thread. Falls back to `'js'` where unsupported.
+ * - `'auto'` (default since 2.0): native when supported, JS otherwise — and JS
+ *   whenever the element sets `duration`, `delay`, `offset` or `stagger` itself,
+ *   since those only mean something for a time-based animation.
+ */
+type ScrollEngine = 'auto' | 'js' | 'css';
+/** Easing function types */
+type EasingType = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'soft-spring' | 'heavy-bounce' | [number, number, number, number] | ((t: number) => number) | string;
+/** Keyframe definition for custom animations */
+interface AnimationKeyframe {
+    [property: string]: string | number;
+}
+/** Custom animation definition */
+interface CustomAnimation {
+    from: AnimationKeyframe;
+    to: AnimationKeyframe;
+}
+/** Parallax configuration */
+interface ParallaxOptions {
+    /** Movement on X axis (e.g., '100px', '20%') */
+    x?: string | number;
+    /** Movement on Y axis (e.g., '100px', '20%') */
+    y?: string | number;
+    /** Rotation in degrees */
+    rotate?: number;
+    /** Scale factor */
+    scale?: number;
+    /** Speed multiplier (default: 1) */
+    speed?: number;
+}
+/** Per-element animation options */
+interface AnimateOptions {
+    /** Animation preset name, array of presets, or custom animation object */
+    animation?: AnimationPreset | AnimationPreset[] | CustomAnimation;
+    /** Duration in milliseconds (default: 600) */
+    duration?: number;
+    /** Delay in milliseconds (default: 0) */
+    delay?: number;
+    /** Easing function (default: 'ease') */
+    easing?: EasingType;
+    /** Intersection threshold 0-1 (default: 0.1) */
+    threshold?: number | number[];
+    /** Root margin for IntersectionObserver (default: '0px') */
+    rootMargin?: string;
+    /** Whether to replay animation each time element enters viewport (default: false) */
+    repeat?: boolean;
+    /** Whether to trigger animation only once (default: true if repeat is false) */
+    once?: boolean;
+    /** Offset in pixels from the viewport edge to trigger animation (default: 0) */
+    offset?: number;
+    /** Stagger delay for child elements in ms (default: 0) */
+    stagger?: number;
+    /** Parallax effect configuration */
+    parallax?: ParallaxOptions;
+    /** Callback fired when animation starts */
+    onStart?: (element: Element) => void;
+    /** Callback fired when animation completes */
+    onComplete?: (element: Element) => void;
+    /** Callback fired when element enters viewport */
+    onEnter?: (element: Element) => void;
+    /** Callback fired when element leaves viewport */
+    onLeave?: (element: Element) => void;
+    /** Callback fired with scroll progress (0 to 1) */
+    onProgress?: (element: Element, progress: number) => void;
+    /** How progress for `onProgress`/parallax is measured (default: 'ratio') */
+    progressMode?: ProgressMode;
+    /**
+     * Name of a CSS custom property (e.g. `'--sa-progress'`) that receives the
+     * element's progress (0 to 1, same value as `onProgress`) as an inline
+     * style, for scroll-driven effects written in plain CSS. Off by default.
+     */
+    progressVar?: string;
+    /**
+     * Animation engine (default: `'auto'`, see `ScrollEngine`). With the native
+     * engine the animation is linked to scroll position: `duration`, `delay`,
+     * `threshold`, `offset` and `stagger` do not apply; `viewRange` does.
+     */
+    engine?: ScrollEngine;
+    /**
+     * Native engine only: the view-timeline range the entrance animation spans,
+     * as `[rangeStart, rangeEnd]` (default: `['entry 0%', 'entry 100%']`).
+     */
+    viewRange?: [string, string];
+    /**
+     * Animate out when the element leaves the viewport, and back in when it
+     * re-enters (implies `repeat: true` unless `repeat` is set).
+     * - `true`: play the entrance animation in reverse.
+     * - a preset / presets / `{ from, to }`: play that animation in reverse
+     *   (e.g. `exit: 'fade-in-down'` leaves upwards).
+     * Skipped under reduced motion. (default: `false`)
+     */
+    exit?: boolean | AnimationPreset | AnimationPreset[] | CustomAnimation;
+}
+/** Global configuration for ScrollAnimate instance */
+interface ScrollAnimateConfig {
+    /** Default animation preset (default: 'fade-in-up') */
+    defaultAnimation?: AnimationPreset | AnimationPreset[] | CustomAnimation;
+    /** Default duration in ms (default: 600) */
+    defaultDuration?: number;
+    /** Default delay in ms (default: 0) */
+    defaultDelay?: number;
+    /** Default easing (default: 'ease') */
+    defaultEasing?: EasingType;
+    /** Default threshold (default: 0.1) */
+    defaultThreshold?: number | number[];
+    /** Default root margin (default: '0px') */
+    defaultRootMargin?: string;
+    /** Whether animations replay by default (default: false) */
+    defaultRepeat?: boolean;
+    /** Default once setting (default: true) */
+    defaultOnce?: boolean;
+    /** Default offset in pixels (default: 0) */
+    defaultOffset?: number;
+    /** CSS class added before animation (default: 'sa-hidden') */
+    hiddenClass?: string;
+    /** CSS class added when element is visible (default: 'sa-visible') */
+    visibleClass?: string;
+    /** Whether to use CSS class-based animation instead of Web Animations API */
+    useClassNames?: boolean;
+    /** Disable all animations (useful for reduced-motion preference) */
+    disabled?: boolean;
+    /** Custom IntersectionObserver root element */
+    root?: Element | null;
+    /**
+     * Drop `once` elements from the registry as soon as their entrance animation
+     * has been triggered (unless they still need parallax/onProgress), so they can
+     * be garbage-collected. They are remembered in a WeakSet, so `init()`/`observe()`
+     * never re-hide or replay them. (default: true)
+     */
+    autoUnregister?: boolean;
+    /** Default animation engine (default: `'auto'`; `'js'` restores the 1.x behaviour) */
+    defaultEngine?: ScrollEngine;
+}
+/** Registered element entry */
+interface AnimatedElement {
+    element: Element;
+    options: Required<AnimateOptions>;
+    observer: IntersectionObserver;
+    animated: boolean;
+    progressObserver?: IntersectionObserver;
+    /** Engine actually used for this element (`'css'` = native scroll-driven timeline) */
+    engine?: 'js' | 'css';
+}
+/** ScrollAnimate public API */
+interface ScrollAnimateInstance {
+    /** Observe a single element or CSS selector */
+    observe(target: string | Element | NodeList | Element[], options?: AnimateOptions): void;
+    /** Stop observing a single element or CSS selector */
+    unobserve(target: string | Element | NodeList | Element[]): void;
+    /** Observe all elements matching the data-sa attribute */
+    init(rootElement?: Element | Document): void;
+    /**
+     * Like `init()`, then keep watching `rootElement` (default: `document`) with a
+     * MutationObserver: `[data-sa]` elements added later (or that gain the
+     * attribute) are observed automatically, and removed ones are released.
+     * Returns a function that stops watching. `destroy()` stops every watcher.
+     * SSR-safe: a no-op without a DOM / MutationObserver.
+     */
+    watch(rootElement?: Element | Document): () => void;
+    /** Destroy the instance and clean up all observers */
+    destroy(): void;
+    /** Refresh all observers (useful after DOM changes) */
+    refresh(): void;
+    /** Manually trigger animation on an element */
+    animate(target: string | Element, options?: AnimateOptions): void;
+    /** Get all currently observed elements */
+    getObservedElements(): AnimatedElement[];
+    /** Update global configuration */
+    configure(config: Partial<ScrollAnimateConfig>): void;
+}
+
+/**
+ * use-scroll-animate - Staggered children
+ * Reveal a container's children one after another when the container scrolls
+ * into view, optionally also animating children that are added later.
+ */
+
+interface StaggerOptions extends AnimateOptions {
+    /** Delay between consecutive children in ms (default: 80) */
+    stagger?: number;
+    /**
+     * Watch the container with a MutationObserver and animate children added
+     * later (e.g. infinite lists). Children added after the container was
+     * revealed animate when they scroll into view, staggered per batch.
+     * (default: false)
+     */
+    observeChildren?: boolean;
+}
+
+/**
+ * use-scroll-animate - Svelte integration
+ *
+ * Svelte actions (no import from `svelte` needed, works with Svelte 3, 4 and 5):
+ *
+ * ```svelte
+ * <script>
+ *   import { scrollAnimate, scrollStagger } from 'use-scroll-animate/svelte';
+ * </script>
+ * <div use:scrollAnimate={{ animation: 'fade-in-up', duration: 800 }}>…</div>
+ * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>
+ * ```
+ */
+
+interface ScrollAnimateActionOptions extends AnimateOptions {
+    /** Instance to register with (default: a shared instance created on first use) */
+    instance?: ScrollAnimateInstance;
+}
+interface ScrollStaggerActionOptions extends StaggerOptions {
+    instance?: ScrollAnimateInstance;
+}
+/** Shape of a Svelte action's return value. */
+interface ActionReturn<P> {
+    update?: (parameter: P) => void;
+    destroy?: () => void;
+}
+/**
+ * Animate `node` when it scrolls into view. Changing the parameter updates the
+ * callbacks right away; other options are applied if the element has not
+ * animated yet.
+ */
+declare function scrollAnimate(node: Element, options?: ScrollAnimateActionOptions): ActionReturn<ScrollAnimateActionOptions | undefined>;
+/** Stagger the children of `node` when it scrolls into view (`observeChildren: true` also animates children added later). */
+declare function scrollStagger(node: Element, options?: ScrollStaggerActionOptions): ActionReturn<ScrollStaggerActionOptions | undefined>;
+
+export { scrollAnimate, scrollStagger };
+export type { ActionReturn, ScrollAnimateActionOptions, ScrollStaggerActionOptions };

package/dist/svelte.js

@@ -0,0 +1,62 @@
+import { c as createScrollAnimate } from './chunks/core-FUEi4ncH.js';
+import { s as staggerChildren } from './chunks/stagger-DabrnrcE.js';
+
+/**
+ * use-scroll-animate - Svelte integration
+ *
+ * Svelte actions (no import from `svelte` needed, works with Svelte 3, 4 and 5):
+ *
+ * ```svelte
+ * <script>
+ *   import { scrollAnimate, scrollStagger } from 'use-scroll-animate/svelte';
+ * </script>
+ * <div use:scrollAnimate={{ animation: 'fade-in-up', duration: 800 }}>…</div>
+ * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>
+ * ```
+ */
+let shared = null;
+const getInstance = (own) => own || shared || (shared = createScrollAnimate());
+const CALLBACKS = ['onStart', 'onComplete', 'onEnter', 'onLeave', 'onProgress'];
+/** Callbacks always call the latest parameter's version. */
+function liveCallbacks(opts, latest) {
+    const out = { ...opts };
+    CALLBACKS.forEach((name) => {
+        if (typeof opts[name] === 'function')
+            out[name] = (...args) => latest()[name]?.(...args);
+    });
+    return out;
+}
+/**
+ * Animate `node` when it scrolls into view. Changing the parameter updates the
+ * callbacks right away; other options are applied if the element has not
+ * animated yet.
+ */
+function scrollAnimate(node, options = {}) {
+    let current = options;
+    const { instance, ...opts } = options;
+    const sa = getInstance(instance);
+    sa.observe(node, liveCallbacks(opts, () => current));
+    return {
+        update(next = {}) {
+            current = next;
+            const record = sa.getObservedElements().find((r) => r.element === node);
+            if (record && !record.animated) {
+                const { instance: _ignored, ...nextOpts } = next;
+                sa.unobserve(node);
+                sa.observe(node, liveCallbacks(nextOpts, () => current));
+            }
+        },
+        destroy() {
+            sa.unobserve(node);
+        },
+    };
+}
+/** Stagger the children of `node` when it scrolls into view (`observeChildren: true` also animates children added later). */
+function scrollStagger(node, options = {}) {
+    const { instance, ...opts } = options;
+    const stop = staggerChildren(node, opts, getInstance(instance));
+    return { destroy: stop };
+}
+
+export { scrollAnimate, scrollStagger };
+//# sourceMappingURL=svelte.js.map

package/dist/svelte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"svelte.js","sources":["../src/svelte.ts"],"sourcesContent":["/**\n * use-scroll-animate - Svelte integration\n *\n * Svelte actions (no import from `svelte` needed, works with Svelte 3, 4 and 5):\n *\n * ```svelte\n * <script>\n *   import { scrollAnimate, scrollStagger } from 'use-scroll-animate/svelte';\n * </script>\n * <div use:scrollAnimate={{ animation: 'fade-in-up', duration: 800 }}>…</div>\n * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>\n * ```\n */\n\nimport type { AnimateOptions, ScrollAnimateInstance } from './types';\nimport { createScrollAnimate } from './core';\nimport { staggerChildren, type StaggerOptions } from './stagger';\n\nexport interface ScrollAnimateActionOptions extends AnimateOptions {\n  /** Instance to register with (default: a shared instance created on first use) */\n  instance?: ScrollAnimateInstance;\n}\n\nexport interface ScrollStaggerActionOptions extends StaggerOptions {\n  instance?: ScrollAnimateInstance;\n}\n\n/** Shape of a Svelte action's return value. */\nexport interface ActionReturn<P> {\n  update?: (parameter: P) => void;\n  destroy?: () => void;\n}\n\nlet shared: ScrollAnimateInstance | null = null;\nconst getInstance = (own?: ScrollAnimateInstance) => own || shared || (shared = createScrollAnimate());\n\nconst CALLBACKS = ['onStart', 'onComplete', 'onEnter', 'onLeave', 'onProgress'] as const;\n\n/** Callbacks always call the latest parameter's version. */\nfunction liveCallbacks(opts: AnimateOptions, latest: () => AnimateOptions): AnimateOptions {\n  const out: AnimateOptions = { ...opts };\n  CALLBACKS.forEach((name) => {\n    if (typeof opts[name] === 'function') (out as any)[name] = (...args: unknown[]) => (latest()[name] as any)?.(...args);\n  });\n  return out;\n}\n\n/**\n * Animate `node` when it scrolls into view. Changing the parameter updates the\n * callbacks right away; other options are applied if the element has not\n * animated yet.\n */\nexport function scrollAnimate(\n  node: Element,\n  options: ScrollAnimateActionOptions = {}\n): ActionReturn<ScrollAnimateActionOptions | undefined> {\n  let current = options;\n  const { instance, ...opts } = options;\n  const sa = getInstance(instance);\n  sa.observe(node, liveCallbacks(opts, () => current));\n\n  return {\n    update(next = {}) {\n      current = next;\n      const record = sa.getObservedElements().find((r) => r.element === node);\n      if (record && !record.animated) {\n        const { instance: _ignored, ...nextOpts } = next;\n        sa.unobserve(node);\n        sa.observe(node, liveCallbacks(nextOpts, () => current));\n      }\n    },\n    destroy() {\n      sa.unobserve(node);\n    },\n  };\n}\n\n/** Stagger the children of `node` when it scrolls into view (`observeChildren: true` also animates children added later). */\nexport function scrollStagger(\n  node: Element,\n  options: ScrollStaggerActionOptions = {}\n): ActionReturn<ScrollStaggerActionOptions | undefined> {\n  const { instance, ...opts } = options;\n  const stop = staggerChildren(node, opts, getInstance(instance));\n  return { destroy: stop };\n}\n"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;AAYG;AAqBH,IAAI,MAAM,GAAiC,IAAI;AAC/C,MAAM,WAAW,GAAG,CAAC,GAA2B,KAAK,GAAG,IAAI,MAAM,KAAK,MAAM,GAAG,mBAAmB,EAAE,CAAC;AAEtG,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,CAAU;AAExF;AACA,SAAS,aAAa,CAAC,IAAoB,EAAE,MAA4B,EAAA;AACvE,IAAA,MAAM,GAAG,GAAmB,EAAE,GAAG,IAAI,EAAE;AACvC,IAAA,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,KAAI;AACzB,QAAA,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,UAAU;YAAG,GAAW,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAe,KAAM,MAAM,EAAE,CAAC,IAAI,CAAS,GAAG,GAAG,IAAI,CAAC;AACvH,IAAA,CAAC,CAAC;AACF,IAAA,OAAO,GAAG;AACZ;AAEA;;;;AAIG;SACa,aAAa,CAC3B,IAAa,EACb,UAAsC,EAAE,EAAA;IAExC,IAAI,OAAO,GAAG,OAAO;IACrB,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO;AACrC,IAAA,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC;AAChC,IAAA,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC;IAEpD,OAAO;QACL,MAAM,CAAC,IAAI,GAAG,EAAE,EAAA;YACd,OAAO,GAAG,IAAI;YACd,MAAM,MAAM,GAAG,EAAE,CAAC,mBAAmB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC;AACvE,YAAA,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;gBAC9B,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI;AAChD,gBAAA,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;AAClB,gBAAA,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,aAAa,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC;YAC1D;QACF,CAAC;QACD,OAAO,GAAA;AACL,YAAA,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;QACpB,CAAC;KACF;AACH;AAEA;SACgB,aAAa,CAC3B,IAAa,EACb,UAAsC,EAAE,EAAA;IAExC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO;AACrC,IAAA,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;AAC/D,IAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE;AAC1B;;;;"}

package/dist/vue.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+var core = require('./chunks/core-CH41ekIo.cjs');
+var stagger = require('./chunks/stagger-XD-0-FQz.cjs');
+
+/**
+ * use-scroll-animate - Vue 3 Integration
+ * Provides useScrollAnimate and useScrollStagger composables for Vue 3 applications.
+ *
+ * A thin wrapper around the core engine, so it shares its behaviour: `once`,
+ * `offset`, custom easing functions, parallax, `prefers-reduced-motion`
+ * support, and cleanup on unmount.
+ */
+/** Support refs on components (`$el`) as well as plain elements. */
+function unwrap(value) {
+    if (value && typeof Element !== 'undefined' && !(value instanceof Element) && value.$el instanceof Element) {
+        return value.$el;
+    }
+    return value || null;
+}
+function createVueComposables(Vue) {
+    // Created lazily on the client so importing on the server is side-effect free.
+    let instance = null;
+    const getInstance = () => instance || (instance = core.createScrollAnimate());
+    function useScrollAnimate(options = {}) {
+        const animateRef = Vue.ref(null);
+        let el = null;
+        Vue.onMounted(() => {
+            const target = unwrap(animateRef.value);
+            if (!target)
+                return;
+            el = target;
+            getInstance().observe(el, options);
+        });
+        Vue.onUnmounted(() => {
+            if (el)
+                getInstance().unobserve(el);
+            el = null;
+        });
+        return { animateRef };
+    }
+    /** Stagger the children of `staggerRef`; `observeChildren: true` also animates children added later. */
+    function useScrollStagger(options = {}) {
+        const staggerRef = Vue.ref(null);
+        let stop;
+        Vue.onMounted(() => {
+            const target = unwrap(staggerRef.value);
+            if (target)
+                stop = stagger.staggerChildren(target, options, getInstance());
+        });
+        Vue.onUnmounted(() => {
+            stop?.();
+            stop = undefined;
+        });
+        return { staggerRef };
+    }
+    return { useScrollAnimate, useScrollStagger };
+}
+
+exports.createVueComposables = createVueComposables;
+//# sourceMappingURL=vue.cjs.map

package/dist/vue.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.cjs","sources":["../src/vue.ts"],"sourcesContent":["/**\n * use-scroll-animate - Vue 3 Integration\n * Provides useScrollAnimate and useScrollStagger composables for Vue 3 applications.\n *\n * A thin wrapper around the core engine, so it shares its behaviour: `once`,\n * `offset`, custom easing functions, parallax, `prefers-reduced-motion`\n * support, and cleanup on unmount.\n */\n\nimport type { AnimateOptions, ScrollAnimateInstance } from './types';\nimport { createScrollAnimate } from './core';\nimport { staggerChildren, type StaggerOptions } from './stagger';\n\n/** Support refs on components (`$el`) as well as plain elements. */\nfunction unwrap(value: unknown): Element | null {\n  if (value && typeof Element !== 'undefined' && !(value instanceof Element) && (value as any).$el instanceof Element) {\n    return (value as any).$el as Element;\n  }\n  return (value as Element | null) || null;\n}\n\nexport function createVueComposables(Vue: {\n  ref: <T>(value: T | null) => { value: T | null };\n  onMounted: (fn: () => void) => void;\n  onUnmounted: (fn: () => void) => void;\n}) {\n  // Created lazily on the client so importing on the server is side-effect free.\n  let instance: ScrollAnimateInstance | null = null;\n  const getInstance = () => instance || (instance = createScrollAnimate());\n\n  function useScrollAnimate(options: AnimateOptions = {}) {\n    const animateRef = Vue.ref<Element>(null);\n    let el: Element | null = null;\n\n    Vue.onMounted(() => {\n      const target = unwrap(animateRef.value);\n      if (!target) return;\n      el = target;\n      getInstance().observe(el, options);\n    });\n\n    Vue.onUnmounted(() => {\n      if (el) getInstance().unobserve(el);\n      el = null;\n    });\n\n    return { animateRef };\n  }\n\n  /** Stagger the children of `staggerRef`; `observeChildren: true` also animates children added later. */\n  function useScrollStagger(options: StaggerOptions = {}) {\n    const staggerRef = Vue.ref<Element>(null);\n    let stop: (() => void) | undefined;\n\n    Vue.onMounted(() => {\n      const target = unwrap(staggerRef.value);\n      if (target) stop = staggerChildren(target, options, getInstance());\n    });\n\n    Vue.onUnmounted(() => {\n      stop?.();\n      stop = undefined;\n    });\n\n    return { staggerRef };\n  }\n\n  return { useScrollAnimate, useScrollStagger };\n}\n"],"names":["createScrollAnimate","staggerChildren"],"mappings":";;;;;AAAA;;;;;;;AAOG;AAMH;AACA,SAAS,MAAM,CAAC,KAAc,EAAA;IAC5B,IAAI,KAAK,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,EAAE,KAAK,YAAY,OAAO,CAAC,IAAK,KAAa,CAAC,GAAG,YAAY,OAAO,EAAE;QACnH,OAAQ,KAAa,CAAC,GAAc;IACtC;IACA,OAAQ,KAAwB,IAAI,IAAI;AAC1C;AAEM,SAAU,oBAAoB,CAAC,GAIpC,EAAA;;IAEC,IAAI,QAAQ,GAAiC,IAAI;AACjD,IAAA,MAAM,WAAW,GAAG,MAAM,QAAQ,KAAK,QAAQ,GAAGA,wBAAmB,EAAE,CAAC;IAExE,SAAS,gBAAgB,CAAC,OAAA,GAA0B,EAAE,EAAA;QACpD,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,CAAU,IAAI,CAAC;QACzC,IAAI,EAAE,GAAmB,IAAI;AAE7B,QAAA,GAAG,CAAC,SAAS,CAAC,MAAK;YACjB,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC;AACvC,YAAA,IAAI,CAAC,MAAM;gBAAE;YACb,EAAE,GAAG,MAAM;YACX,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC;AACpC,QAAA,CAAC,CAAC;AAEF,QAAA,GAAG,CAAC,WAAW,CAAC,MAAK;AACnB,YAAA,IAAI,EAAE;AAAE,gBAAA,WAAW,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,EAAE,GAAG,IAAI;AACX,QAAA,CAAC,CAAC;QAEF,OAAO,EAAE,UAAU,EAAE;IACvB;;IAGA,SAAS,gBAAgB,CAAC,OAAA,GAA0B,EAAE,EAAA;QACpD,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,CAAU,IAAI,CAAC;AACzC,QAAA,IAAI,IAA8B;AAElC,QAAA,GAAG,CAAC,SAAS,CAAC,MAAK;YACjB,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC;AACvC,YAAA,IAAI,MAAM;gBAAE,IAAI,GAAGC,uBAAe,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AACpE,QAAA,CAAC,CAAC;AAEF,QAAA,GAAG,CAAC,WAAW,CAAC,MAAK;YACnB,IAAI,IAAI;YACR,IAAI,GAAG,SAAS;AAClB,QAAA,CAAC,CAAC;QAEF,OAAO,EAAE,UAAU,EAAE;IACvB;AAEA,IAAA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE;AAC/C;;;;"}