use-scroll-animate 1.5.0 → 2.0.1

package/dist/solid.d.cts

@@ -0,0 +1,245 @@
+/**
+ * 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 - Solid integration
+ *
+ * ```tsx
+ * import { scrollAnimate, scrollStagger, useScrollAnimate } from 'use-scroll-animate/solid';
+ * false && scrollAnimate; // keep the directive import (TypeScript)
+ *
+ * <div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>
+ * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>
+ * <div ref={useScrollAnimate({ animation: 'fade-in-up' })}>…</div>
+ * ```
+ *
+ * `solid-js` is an optional peer dependency (only needed for this entry).
+ */
+
+interface SolidScrollAnimateOptions extends AnimateOptions {
+    instance?: ScrollAnimateInstance;
+}
+interface SolidScrollStaggerOptions extends StaggerOptions {
+    instance?: ScrollAnimateInstance;
+}
+declare module 'solid-js' {
+    namespace JSX {
+        interface Directives {
+            scrollAnimate: SolidScrollAnimateOptions | true;
+            scrollStagger: SolidScrollStaggerOptions | true;
+        }
+    }
+}
+/** Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />` */
+declare function scrollAnimate(el: Element, accessor?: () => SolidScrollAnimateOptions | true | undefined): void;
+/** Directive: `<ul use:scrollStagger={{ stagger: 60, observeChildren: true }} />` */
+declare function scrollStagger(el: Element, accessor?: () => SolidScrollStaggerOptions | true | undefined): void;
+/** Primitive returning a `ref` callback: `<div ref={useScrollAnimate({ animation: 'fade-in-up' })} />` */
+declare function useScrollAnimate(options?: SolidScrollAnimateOptions): (el: Element) => void;
+
+export { scrollAnimate, scrollStagger, useScrollAnimate };
+export type { SolidScrollAnimateOptions, SolidScrollStaggerOptions };

package/dist/solid.d.ts

@@ -0,0 +1,245 @@
+/**
+ * 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 - Solid integration
+ *
+ * ```tsx
+ * import { scrollAnimate, scrollStagger, useScrollAnimate } from 'use-scroll-animate/solid';
+ * false && scrollAnimate; // keep the directive import (TypeScript)
+ *
+ * <div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>
+ * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>
+ * <div ref={useScrollAnimate({ animation: 'fade-in-up' })}>…</div>
+ * ```
+ *
+ * `solid-js` is an optional peer dependency (only needed for this entry).
+ */
+
+interface SolidScrollAnimateOptions extends AnimateOptions {
+    instance?: ScrollAnimateInstance;
+}
+interface SolidScrollStaggerOptions extends StaggerOptions {
+    instance?: ScrollAnimateInstance;
+}
+declare module 'solid-js' {
+    namespace JSX {
+        interface Directives {
+            scrollAnimate: SolidScrollAnimateOptions | true;
+            scrollStagger: SolidScrollStaggerOptions | true;
+        }
+    }
+}
+/** Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />` */
+declare function scrollAnimate(el: Element, accessor?: () => SolidScrollAnimateOptions | true | undefined): void;
+/** Directive: `<ul use:scrollStagger={{ stagger: 60, observeChildren: true }} />` */
+declare function scrollStagger(el: Element, accessor?: () => SolidScrollStaggerOptions | true | undefined): void;
+/** Primitive returning a `ref` callback: `<div ref={useScrollAnimate({ animation: 'fade-in-up' })} />` */
+declare function useScrollAnimate(options?: SolidScrollAnimateOptions): (el: Element) => void;
+
+export { scrollAnimate, scrollStagger, useScrollAnimate };
+export type { SolidScrollAnimateOptions, SolidScrollStaggerOptions };

package/dist/solid.js

@@ -0,0 +1,58 @@
+import { onMount, onCleanup } from 'solid-js';
+import { c as createScrollAnimate } from './chunks/core-BP-a1iNc.js';
+import { s as staggerChildren } from './chunks/stagger-DTv_WiUQ.js';
+
+/**
+ * use-scroll-animate - Solid integration
+ *
+ * ```tsx
+ * import { scrollAnimate, scrollStagger, useScrollAnimate } from 'use-scroll-animate/solid';
+ * false && scrollAnimate; // keep the directive import (TypeScript)
+ *
+ * <div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>
+ * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>
+ * <div ref={useScrollAnimate({ animation: 'fade-in-up' })}>…</div>
+ * ```
+ *
+ * `solid-js` is an optional peer dependency (only needed for this entry).
+ */
+let shared = null;
+const getInstance = (own) => own || shared || (shared = createScrollAnimate());
+function read(accessor) {
+    const v = accessor?.();
+    return (v && v !== true ? v : {});
+}
+function observe(el, options) {
+    const { instance, ...opts } = options;
+    const sa = getInstance(instance);
+    // Wait until the element is in the document (directives/refs run before insertion).
+    onMount(() => sa.observe(el, opts));
+    onCleanup(() => sa.unobserve(el));
+}
+/** Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />` */
+function scrollAnimate(el, accessor) {
+    observe(el, read(accessor));
+}
+/** Directive: `<ul use:scrollStagger={{ stagger: 60, observeChildren: true }} />` */
+function scrollStagger(el, accessor) {
+    const { instance, ...opts } = read(accessor);
+    let stop;
+    onMount(() => {
+        stop = staggerChildren(el, opts, getInstance(instance));
+    });
+    onCleanup(() => stop?.());
+}
+/** Primitive returning a `ref` callback: `<div ref={useScrollAnimate({ animation: 'fade-in-up' })} />` */
+function useScrollAnimate(options = {}) {
+    let el;
+    const { instance, ...opts } = options;
+    const sa = getInstance(instance);
+    onMount(() => el && sa.observe(el, opts));
+    onCleanup(() => el && sa.unobserve(el));
+    return (node) => {
+        el = node;
+    };
+}
+
+export { scrollAnimate, scrollStagger, useScrollAnimate };
+//# sourceMappingURL=solid.js.map

package/dist/solid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solid.js","sources":["../src/solid.ts"],"sourcesContent":["/**\n * use-scroll-animate - Solid integration\n *\n * ```tsx\n * import { scrollAnimate, scrollStagger, useScrollAnimate } from 'use-scroll-animate/solid';\n * false && scrollAnimate; // keep the directive import (TypeScript)\n *\n * <div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>\n * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>\n * <div ref={useScrollAnimate({ animation: 'fade-in-up' })}>…</div>\n * ```\n *\n * `solid-js` is an optional peer dependency (only needed for this entry).\n */\n\nimport { onCleanup, onMount } from 'solid-js';\nimport type { AnimateOptions, ScrollAnimateInstance } from './types';\nimport { createScrollAnimate } from './core';\nimport { staggerChildren, type StaggerOptions } from './stagger';\n\nexport interface SolidScrollAnimateOptions extends AnimateOptions {\n  instance?: ScrollAnimateInstance;\n}\nexport interface SolidScrollStaggerOptions extends StaggerOptions {\n  instance?: ScrollAnimateInstance;\n}\n\ndeclare module 'solid-js' {\n  // eslint-disable-next-line @typescript-eslint/no-namespace\n  namespace JSX {\n    interface Directives {\n      scrollAnimate: SolidScrollAnimateOptions | true;\n      scrollStagger: SolidScrollStaggerOptions | true;\n    }\n  }\n}\n\nlet shared: ScrollAnimateInstance | null = null;\nconst getInstance = (own?: ScrollAnimateInstance) => own || shared || (shared = createScrollAnimate());\n\nfunction read<T>(accessor?: () => T | true | undefined): T {\n  const v = accessor?.();\n  return (v && v !== true ? v : {}) as T;\n}\n\nfunction observe(el: Element, options: SolidScrollAnimateOptions): void {\n  const { instance, ...opts } = options;\n  const sa = getInstance(instance);\n  // Wait until the element is in the document (directives/refs run before insertion).\n  onMount(() => sa.observe(el, opts));\n  onCleanup(() => sa.unobserve(el));\n}\n\n/** Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />` */\nexport function scrollAnimate(el: Element, accessor?: () => SolidScrollAnimateOptions | true | undefined): void {\n  observe(el, read(accessor));\n}\n\n/** Directive: `<ul use:scrollStagger={{ stagger: 60, observeChildren: true }} />` */\nexport function scrollStagger(el: Element, accessor?: () => SolidScrollStaggerOptions | true | undefined): void {\n  const { instance, ...opts } = read<SolidScrollStaggerOptions>(accessor);\n  let stop: (() => void) | undefined;\n  onMount(() => {\n    stop = staggerChildren(el, opts, getInstance(instance));\n  });\n  onCleanup(() => stop?.());\n}\n\n/** Primitive returning a `ref` callback: `<div ref={useScrollAnimate({ animation: 'fade-in-up' })} />` */\nexport function useScrollAnimate(options: SolidScrollAnimateOptions = {}): (el: Element) => void {\n  let el: Element | undefined;\n  const { instance, ...opts } = options;\n  const sa = getInstance(instance);\n  onMount(() => el && sa.observe(el, opts));\n  onCleanup(() => el && sa.unobserve(el));\n  return (node: Element) => {\n    el = node;\n  };\n}\n"],"names":[],"mappings":";;;;AAAA;;;;;;;;;;;;;AAaG;AAwBH,IAAI,MAAM,GAAiC,IAAI;AAC/C,MAAM,WAAW,GAAG,CAAC,GAA2B,KAAK,GAAG,IAAI,MAAM,KAAK,MAAM,GAAG,mBAAmB,EAAE,CAAC;AAEtG,SAAS,IAAI,CAAI,QAAqC,EAAA;AACpD,IAAA,MAAM,CAAC,GAAG,QAAQ,IAAI;AACtB,IAAA,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,GAAG,EAAE;AAClC;AAEA,SAAS,OAAO,CAAC,EAAW,EAAE,OAAkC,EAAA;IAC9D,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO;AACrC,IAAA,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC;;AAEhC,IAAA,OAAO,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACnC,SAAS,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AACnC;AAEA;AACM,SAAU,aAAa,CAAC,EAAW,EAAE,QAA6D,EAAA;IACtG,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC7B;AAEA;AACM,SAAU,aAAa,CAAC,EAAW,EAAE,QAA6D,EAAA;IACtG,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAA4B,QAAQ,CAAC;AACvE,IAAA,IAAI,IAA8B;IAClC,OAAO,CAAC,MAAK;AACX,QAAA,IAAI,GAAG,eAAe,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;AACzD,IAAA,CAAC,CAAC;IACF,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC;AAC3B;AAEA;AACM,SAAU,gBAAgB,CAAC,OAAA,GAAqC,EAAE,EAAA;AACtE,IAAA,IAAI,EAAuB;IAC3B,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO;AACrC,IAAA,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC;AAChC,IAAA,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AACzC,IAAA,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,IAAa,KAAI;QACvB,EAAE,GAAG,IAAI;AACX,IAAA,CAAC;AACH;;;;"}

package/dist/svelte.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+var core = require('./chunks/core-B_J4rXbC.cjs');
+var stagger = require('./chunks/stagger-DHw0ExuR.cjs');
+
+/**
+ * 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 = core.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 = stagger.staggerChildren(node, opts, getInstance(instance));
+    return { destroy: stop };
+}
+
+exports.scrollAnimate = scrollAnimate;
+exports.scrollStagger = scrollStagger;
+//# sourceMappingURL=svelte.cjs.map

package/dist/svelte.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"svelte.cjs","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":["createScrollAnimate","staggerChildren"],"mappings":";;;;;AAAA;;;;;;;;;;;;AAYG;AAqBH,IAAI,MAAM,GAAiC,IAAI;AAC/C,MAAM,WAAW,GAAG,CAAC,GAA2B,KAAK,GAAG,IAAI,MAAM,KAAK,MAAM,GAAGA,wBAAmB,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,GAAGC,uBAAe,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;AAC/D,IAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE;AAC1B;;;;;"}