use-scroll-animate 1.4.0 → 2.0.0

package/dist/vue.d.cts

@@ -0,0 +1,159 @@
+/**
+ * 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;
+}
+
+/**
+ * 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 - 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.
+ */
+
+declare function createVueComposables(Vue: {
+    ref: <T>(value: T | null) => {
+        value: T | null;
+    };
+    onMounted: (fn: () => void) => void;
+    onUnmounted: (fn: () => void) => void;
+}): {
+    useScrollAnimate: (options?: AnimateOptions) => {
+        animateRef: {
+            value: Element | null;
+        };
+    };
+    useScrollStagger: (options?: StaggerOptions) => {
+        staggerRef: {
+            value: Element | null;
+        };
+    };
+};
+
+export { createVueComposables };

package/dist/vue.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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;
+}
+
+/**
+ * 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 - 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.
+ */
+
+declare function createVueComposables(Vue: {
+    ref: <T>(value: T | null) => {
+        value: T | null;
+    };
+    onMounted: (fn: () => void) => void;
+    onUnmounted: (fn: () => void) => void;
+}): {
+    useScrollAnimate: (options?: AnimateOptions) => {
+        animateRef: {
+            value: Element | null;
+        };
+    };
+    useScrollStagger: (options?: StaggerOptions) => {
+        staggerRef: {
+            value: Element | null;
+        };
+    };
+};
+
+export { createVueComposables };

package/dist/vue.js

@@ -0,0 +1,59 @@
+import { c as createScrollAnimate } from './chunks/core-FUEi4ncH.js';
+import { s as staggerChildren } from './chunks/stagger-DabrnrcE.js';
+
+/**
+ * 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 = 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 = staggerChildren(target, options, getInstance());
+        });
+        Vue.onUnmounted(() => {
+            stop?.();
+            stop = undefined;
+        });
+        return { staggerRef };
+    }
+    return { useScrollAnimate, useScrollStagger };
+}
+
+export { createVueComposables };
+//# sourceMappingURL=vue.js.map

package/dist/vue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.js","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":[],"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,GAAG,mBAAmB,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,GAAG,eAAe,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;;;;"}

package/docs/API.md

@@ -0,0 +1,139 @@
+# API reference
+
+`use-scroll-animate` — every public export, option and attribute. See the [README](../README.md) for a tour, the [demo](../demo/index.html) to try every preset, and the migration guides for [AOS](./migration-from-aos.md) and [GSAP ScrollTrigger](./migration-from-gsap-scrolltrigger.md). Upgrading from 1.x: see [Upgrading to 2.0](./deprecations.md).
+
+- [Entry points](#entry-points)
+- [Default instance & `createScrollAnimate(config)`](#default-instance--createscrollanimateconfig)
+- [Instance methods](#instance-methods)
+- [Per-element options (`AnimateOptions`)](#per-element-options-animateoptions)
+- [Data attributes](#data-attributes)
+- [Global config (`ScrollAnimateConfig`)](#global-config-scrollanimateconfig)
+- [Presets & easings](#presets--easings)
+- [Helpers: `staggerChildren`, `sequence`, `parallax`, `getScrollProgress`, `supportsScrollTimeline`](#helpers)
+- [Framework integrations](#framework-integrations)
+- [Behaviour notes](#behaviour-notes)
+
+## Entry points
+
+| Import | Contents |
+|---|---|
+| `use-scroll-animate` | Default instance, `createScrollAnimate`, `staggerChildren`, `sequence`, `parallax`, `getScrollProgress`, `supportsScrollTimeline`, `PRESETS`, `resolvePreset`, `resolveEasing`, `EASING_MAP`, all types |
+| `use-scroll-animate/react` | `createReactHooks(React)` |
+| `use-scroll-animate/vue` | `createVueComposables({ ref, onMounted, onUnmounted })` |
+| `use-scroll-animate/svelte` | `scrollAnimate`, `scrollStagger` actions |
+| `use-scroll-animate/solid` | `scrollAnimate`, `scrollStagger` directives, `useScrollAnimate()` (needs `solid-js`) |
+| `use-scroll-animate/element` | `defineScrollAnimate(tagName?, instance?)` for `<scroll-animate>` |
+| `dist/index.umd.js` | Global `ScrollAnimate` (`ScrollAnimate.default` is the instance, other exports as properties) |
+| `dist/element.umd.js` | Registers `<scroll-animate>` on load; global `ScrollAnimateElement` |
+
+Every entry is ESM-first (`import` → `.js` + `.d.ts`) with a CommonJS build (`require` → `.cjs` + `.d.cts`), SSR-safe (no DOM access at import), and has zero runtime dependencies.
+
+## Default instance & `createScrollAnimate(config)`
+
+```ts
+import ScrollAnimate, { createScrollAnimate } from 'use-scroll-animate';
+
+ScrollAnimate.init();                               // shared default instance
+const sa = createScrollAnimate({ defaultDuration: 800, defaultEngine: 'auto' }); // isolated instance
+```
+
+`createScrollAnimate(config?: ScrollAnimateConfig): ScrollAnimateInstance`. Instances share no state: each has its own registry, observers, watchers and timers.
+
+## Instance methods
+
+| Method | Description |
+|---|---|
+| `init(root?: Element \| Document)` | Observe every `[data-sa]` element under `root` (default `document`). Already observed / finished elements are skipped. |
+| `watch(root?)` → `() => void` | `init()` and keep observing `[data-sa]` elements added later (MutationObserver); removed elements are released. Returns a stop function. |
+| `observe(target, options?)` | Observe a selector, `Element`, `NodeList` or `Element[]`. Elements are hidden until they enter (JS engine). |
+| `unobserve(target)` | Stop observing. Elements that never animated are made visible; native scroll-linked animations are cancelled. |
+| `animate(target, options?)` | Play the entrance animation now (time-based JS engine), without observing. |
+| `refresh()` | Rebuild the observers (e.g. after `configure({ root })`) without replaying finished elements. |
+| `configure(config)` | Merge new global config. |
+| `getObservedElements()` → `AnimatedElement[]` | Registered elements: `{ element, options, observer, animated, progressObserver?, engine? }`. Finished `once` elements are dropped when `autoUnregister` is on. |
+| `destroy()` | Disconnect everything (observers, watchers, scroll listeners, class-name timers), reveal elements that never animated, cancel native animations. |
+
+`target` is always `string | Element | NodeList | Element[]`.
+
+## Per-element options (`AnimateOptions`)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `animation` | `AnimationPreset \| AnimationPreset[] \| { from, to }` | `'fade-in-up'` | Preset, presets combined (transforms are concatenated), or custom keyframes |
+| `duration` | `number` (ms) | `600` | JS engine only (setting it makes `'auto'` pick JS) |
+| `delay` | `number` (ms) | `0` | JS engine only (setting it makes `'auto'` pick JS) |
+| `easing` | `EasingType` | `'ease'` | CSS easing string, named easing, `[x1, y1, x2, y2]`, or `(t) => number` (sampled into `linear()`) |
+| `threshold` | `number \| number[]` | `0.1` | IntersectionObserver threshold(s) |
+| `rootMargin` | `string` | `'0px'` | IntersectionObserver root margin |
+| `offset` | `number` (px) | `0` | Trigger this many px later (subtracted from the bottom root margin) |
+| `once` | `boolean` | `true` | Animate on the first entry only |
+| `repeat` | `boolean` | `false` | Re-hide on leave, replay on each entry |
+| `exit` | `boolean \| preset \| preset[] \| { from, to }` | `false` | Animate out (in reverse) when leaving; implies `repeat` |
+| `stagger` | `number` (ms) | `0` | Extra delay per sibling revealed in the same batch |
+| `engine` | `'auto' \| 'js' \| 'css'` | `'auto'` | `'auto'`: native scroll-driven timeline when supported, else JS — and JS when the element sets `duration`/`delay`/`offset`/`stagger`; `'css'`: native whenever supported; `'js'`: always time-based |
+| `viewRange` | `[string, string]` | `['entry 0%', 'entry 100%']` | Native engine: view-timeline range of the entrance |
+| `parallax` | `{ x?, y?, rotate?, scale?, speed? }` | `{}` | Legacy transform-based parallax (writes `transform`); see also `parallax()` |
+| `progressMode` | `'ratio' \| 'scroll'` | `'ratio'` | `onProgress` source: visible ratio, or true scroll progress (0 = top enters at the bottom, 1 = bottom leaves at the top) |
+| `progressVar` | `string` | – | CSS custom property that receives the progress |
+| `onEnter` / `onLeave` | `(el) => void` | – | Viewport entry / exit |
+| `onStart` / `onComplete` | `(el) => void` | – | Animation start / end (also fired under reduced motion, immediately) |
+| `onProgress` | `(el, progress) => void` | – | Progress 0–1 |
+
+## Data attributes
+
+Mark elements with `data-sa` and call `init()` / `watch()`. Every option has an attribute:
+
+`data-sa-animation` (comma-separated to combine), `data-sa-duration`, `data-sa-delay`, `data-sa-easing` (name, CSS string or JSON array), `data-sa-threshold` (comma-separated list allowed), `data-sa-root-margin`, `data-sa-offset`, `data-sa-once`, `data-sa-repeat`, `data-sa-exit` (bare = `true`, or preset name), `data-sa-stagger`, `data-sa-engine`, `data-sa-view-range` (`"entry 0%, cover 40%"`), `data-sa-progress` (`"scroll"`), `data-sa-progress-var` (bare = `--sa-progress`), `data-sa-parallax-x|y|rotate|scale|speed`.
+
+Boolean attributes are true when present unless their value is `"false"`.
+
+## Global config (`ScrollAnimateConfig`)
+
+| Key | Default | Description |
+|---|---|---|
+| `defaultAnimation`, `defaultDuration`, `defaultDelay`, `defaultEasing`, `defaultThreshold`, `defaultRootMargin`, `defaultRepeat`, `defaultOnce`, `defaultOffset` | as per-element defaults | Defaults for options not set per element |
+| `defaultEngine` | `'auto'` | Default `engine` (`'js'` = 1.x behaviour) |
+| `useClassNames` | `false` | Toggle `hiddenClass`/`visibleClass` instead of Web Animations (animate with your own CSS) |
+| `hiddenClass` / `visibleClass` | `'sa-hidden'` / `'sa-visible'` | Class names for class-name mode |
+| `disabled` | `false` | Show everything immediately, no motion (callbacks still fire) |
+| `root` | `null` | Scroll container for IntersectionObserver / progress |
+| `autoUnregister` | `true` | Drop finished `once` elements from the registry (remembered in a `WeakSet`, never replayed) |
+
+## Presets & easings
+
+`PRESETS` (`Record<AnimationPreset, { from, to }>`): `fade-in`, `fade-in-up`, `fade-in-down`, `fade-in-left`, `fade-in-right`, `zoom-in`, `zoom-out`, `scale-up`, `flip-x`, `flip-y`, `flip-up`, `flip-down`, `slide-up`, `slide-down`, `slide-left`, `slide-right`, `bounce`, `rotate-in`, `rotate-left`, `rotate-right`, `blur-in`, `blur-in-up`, `skew-in`, `scale-x`, `scale-y`, `clip-up`, `clip-down`, `clip-left`, `clip-right`, `clip-circle`, `shimmer`, `pulse`, `swing`.
+
+`EASING_MAP`: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`, `spring`, `soft-spring`, `heavy-bounce`. `resolvePreset(animation)` and `resolveEasing(easing)` expose the resolution used internally.
+
+## Helpers
+
+### `staggerChildren(container, options?, instance?)` → `() => void`
+Reveal the children of `container` one after another when it enters. `StaggerOptions` = `AnimateOptions` + `stagger` (default `80` ms) + `observeChildren` (MutationObserver for children added later). Stopping before the reveal makes the children visible.
+
+### `sequence(steps, options?)` → `SequenceController`
+Timeline across targets. `SequenceStep` = `AnimateOptions` + `target` + `gap` (ms after the previous step; negative overlaps) or `at` (absolute ms). `SequenceOptions` = `AnimateOptions` + `trigger` (play once when it enters) + `instance`. Controller: `play(): Promise<void>`, `cancel()`, `duration()`.
+
+### `parallax(target, options?)` → `() => void`
+`{ speed = 0.2, axis = 'y', progressVar = '--sa-parallax', root = null, respectReducedMotion = true }`. Offset `(progress − 0.5) × speed × 100vh` (or `vw`) on the `translate` property; progress (0–1) in the CSS variable. The stop function removes listeners and inline styles.
+
+### `getScrollProgress(el, root?)` → `number`
+True scroll progress 0–1 of `el` through the viewport or `root`. `0` without a DOM.
+
+### `supportsScrollTimeline()` → `boolean`
+`CSS.supports('animation-timeline: view()')` and `ViewTimeline` available — i.e. whether `engine: 'auto'` will use the native engine.
+
+## Framework integrations
+
+- **React** — `const { useScrollAnimate, useScrollStagger } = createReactHooks(React)`; both return a ref. Callbacks always call the latest render's version.
+- **Vue 3** — `createVueComposables({ ref, onMounted, onUnmounted })` → `useScrollAnimate()` (`{ animateRef }`), `useScrollStagger()` (`{ staggerRef }`); component refs (`$el`) are supported.
+- **Svelte** — `use:scrollAnimate={options}`, `use:scrollStagger={options}`; `update()` swaps callbacks (and other options before the element animated). Optional `instance`.
+- **Solid** — `use:scrollAnimate`, `use:scrollStagger` (typed via `JSX.Directives`), `ref={useScrollAnimate(options)}`.
+- **Web Component** — `<scroll-animate animation="…" …>` with the `data-sa-*` attribute names minus the prefix; events `sa:enter`, `sa:leave`, `sa:start`, `sa:complete`, `sa:progress` (`detail.progress`). Attribute changes before the element animated re-apply the options.
+
+## Behaviour notes
+
+- **Reduced motion**: with `prefers-reduced-motion: reduce` (or `disabled: true`) nothing is hidden or moved; callbacks still fire; `progressVar` is still written (it is data); `parallax()` writes only its variable.
+- **SSR**: every entry can be imported and called on the server; calls are no-ops without a DOM.
+- **No IntersectionObserver**: content is shown immediately.
+- **Native engine**: scroll-linked, so `duration`/`delay`/`threshold`/`offset`/`stagger` don't apply; `once` freezes the end state on completion; class-name mode, reduced motion, `animate()`, `sequence()` and `staggerChildren()` always use JS.
+- **Native engine by default**: in browsers without `animation-timeline: view()` everything runs on the JS engine.

package/docs/deprecations.md

@@ -0,0 +1,20 @@
+# Upgrading to 2.0 (removed APIs)
+
+Everything below was deprecated in 1.9 and is **removed in 2.0.0**. The full step-by-step list is the MIGRATION section of the [CHANGELOG](../CHANGELOG.md).
+
+| Removed in 2.0 | Use instead |
+|---|---|
+| `import { createReactHooks } from 'use-scroll-animate'` | `import { createReactHooks } from 'use-scroll-animate/react'` |
+| `import { createVueComposables } from 'use-scroll-animate'` | `import { createVueComposables } from 'use-scroll-animate/vue'` |
+| `module` field, `dist/index.esm.js`, `dist/index.mjs` | the `exports` map: `import` → `dist/index.js` (ESM) |
+| `dist/index.js` as CommonJS | `require('use-scroll-animate')` → `dist/index.cjs` (`main`) |
+| per-file declarations in `dist/types/*`, `dist/*.d.mts` | bundled `dist/*.d.ts` (ESM) / `dist/*.d.cts` (CJS), resolved through `exports` |
+| `use-scroll-animate/dist/*` deep imports | the named entry points (`use-scroll-animate`, `/react`, `/vue`, `/svelte`, `/solid`, `/element`) |
+
+Unchanged: the browser bundles at `dist/index.umd.js` (global `ScrollAnimate`) and `dist/element.umd.js` keep their CDN URLs (`https://unpkg.com/use-scroll-animate/dist/index.umd.js`).
+
+Behaviour changes in 2.0 (no API removed):
+
+- `engine` defaults to `'auto'`: the native scroll-driven timeline is used where `animation-timeline: view()` is supported, unless the element sets `duration`, `delay`, `offset` or `stagger` itself. `createScrollAnimate({ defaultEngine: 'js' })` (or `ScrollAnimate.configure({ defaultEngine: 'js' })`) restores the 1.x behaviour.
+- Output targets ES2020 (optional chaining / nullish coalescing are no longer down-levelled). Every browser with `Animation.commitStyles()` — which the library already relied on — supports ES2020.
+- Node ≥ 18 is declared in `engines` (only relevant for SSR imports).

package/docs/migration-from-aos.md

@@ -0,0 +1,67 @@
+# Migrating from AOS (Animate On Scroll)
+
+AOS and `use-scroll-animate` work the same way at the markup level — mark elements with attributes and call `init()` — so most pages migrate with a search-and-replace.
+
+## 1. Install and initialise
+
+```diff
+- import AOS from 'aos';
+- import 'aos/dist/aos.css';
+- AOS.init({ duration: 800, once: true, offset: 120 });
++ import ScrollAnimate from 'use-scroll-animate';
++ ScrollAnimate.configure({ defaultDuration: 800, defaultOnce: true, defaultOffset: 120 });
++ ScrollAnimate.watch(); // like init(), and also picks up elements added later (AOS.refreshHard())
+```
+
+No stylesheet is needed: animations run through the Web Animations API (or opt into CSS classes with `useClassNames: true`).
+
+## 2. Attributes
+
+| AOS | use-scroll-animate |
+|---|---|
+| `data-aos="fade-up"` | `data-sa data-sa-animation="fade-in-up"` |
+| `data-aos-duration="800"` | `data-sa-duration="800"` |
+| `data-aos-delay="200"` | `data-sa-delay="200"` |
+| `data-aos-easing="ease-in-out"` | `data-sa-easing="ease-in-out"` (also `spring`, `soft-spring`, `heavy-bounce`, `[x1,y1,x2,y2]`) |
+| `data-aos-offset="120"` | `data-sa-offset="120"` |
+| `data-aos-once="true"` | `data-sa-once` (default) |
+| `data-aos-mirror="true"` (animate out when scrolling past) | `data-sa-exit` |
+| `data-aos-anchor-placement="top-center"` | `data-sa-threshold="0.5"` or `data-sa-root-margin="0px 0px -50% 0px"` |
+| `data-aos-anchor=".other"` | `sequence([...], { trigger: '.other' })` |
+
+## 3. Animation names
+
+| AOS | use-scroll-animate |
+|---|---|
+| `fade` | `fade-in` |
+| `fade-up` / `fade-down` | `fade-in-up` / `fade-in-down` |
+| `fade-left` / `fade-right` | `fade-in-right` / `fade-in-left` (see the note below) |
+| `fade-up-right` etc. | `['fade-in-up', 'fade-in-left']` (combine presets) |
+| `flip-up` / `flip-down` | `flip-up` / `flip-down` |
+| `flip-left` / `flip-right` | `flip-y` |
+| `slide-up` / `slide-down` / `slide-left` / `slide-right` | `slide-up` / `slide-down` / `slide-right` / `slide-left` |
+| `zoom-in` / `zoom-out` | `zoom-in` / `zoom-out` |
+| `zoom-in-up` etc. | `['zoom-in', 'fade-in-up']` |
+
+**Left/right naming:** AOS names the direction of travel — `fade-left` moves *towards* the left, i.e. comes in from the right. Here presets name where the element comes *from*: `fade-in-right` comes in from the right. Same for `slide-*`.
+
+## 4. Global options
+
+| `AOS.init({...})` | `createScrollAnimate({...})` / `configure()` |
+|---|---|
+| `duration`, `delay`, `easing`, `offset`, `once` | `defaultDuration`, `defaultDelay`, `defaultEasing`, `defaultOffset`, `defaultOnce` |
+| `mirror: true` | per element `exit: true` (or `data-sa-exit`) |
+| `disable: 'mobile'` / function | `disabled: window.matchMedia('(max-width: 600px)').matches` |
+| `startEvent`, `initClassName`, `animatedClassName` | `useClassNames`, `hiddenClass`, `visibleClass` |
+| `throttleDelay`, `debounceDelay` | not needed (IntersectionObserver, no scroll listener) |
+
+## 5. Events and refresh
+
+| AOS | use-scroll-animate |
+|---|---|
+| `document.addEventListener('aos:in', ...)` | `onEnter` / `onStart` options, or `<scroll-animate>`'s `sa:enter` / `sa:start` events |
+| `aos:out` | `onLeave` |
+| `AOS.refresh()` | `ScrollAnimate.refresh()` |
+| `AOS.refreshHard()` | `ScrollAnimate.watch()` handles DOM changes automatically |
+
+`prefers-reduced-motion` is respected out of the box (AOS needs `disable`).