use-scroll-animate 1.4.0 → 2.0.0

package/dist/{index.d.mts → index.d.cts}

@@ -11,6 +11,17 @@ type AnimationPreset = 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left
  *   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 */
@@ -71,6 +82,32 @@ interface AnimateOptions {
     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 {
@@ -109,6 +146,8 @@ interface ScrollAnimateConfig {
      * 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 {
@@ -117,6 +156,8 @@ interface AnimatedElement {
     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 {
@@ -126,6 +167,14 @@ interface ScrollAnimateInstance {
     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) */
@@ -144,6 +193,12 @@ interface ScrollAnimateInstance {
  * high-performance scroll-triggered animations.
  */
 
+/**
+ * Whether the browser can run presets on a native scroll-driven timeline:
+ * `CSS.supports('animation-timeline: view()')` plus the `ViewTimeline`
+ * constructor used to attach it from JavaScript. Cached. SSR-safe.
+ */
+declare function supportsScrollTimeline(): boolean;
 /**
  * True scroll progress of `el` through the viewport (or `root`): 0 when its top
  * edge reaches the bottom of the viewport, 1 when its bottom edge passes the top.
@@ -217,6 +272,47 @@ interface SequenceController {
  */
 declare function sequence(steps: SequenceStep[], options?: SequenceOptions): SequenceController;
 
+/**
+ * use-scroll-animate - parallax() helper
+ *
+ * Moves elements at a different speed than the page while they cross the
+ * viewport. Built on the same scroll progress as `progressVar` (0 when the
+ * element's top enters at the bottom, 1 when its bottom leaves at the top):
+ * the progress is written to a CSS custom property (default `--sa-parallax`)
+ * and the offset is applied with the individual `translate` property, so it
+ * composes with entrance animations and other `transform`s.
+ */
+interface ParallaxHelperOptions {
+    /**
+     * Total distance the element shifts while it crosses the viewport, as a
+     * fraction of the viewport size (`0.2` = 20vh on the y axis). Positive values
+     * lag behind the scroll (background-like), negative values move ahead of it
+     * (foreground-like). (default: `0.2`)
+     */
+    speed?: number;
+    /** `'y'` (default) or `'x'` (horizontal drift, in `vw`) */
+    axis?: 'x' | 'y';
+    /** CSS custom property receiving the progress (default: `'--sa-parallax'`) */
+    progressVar?: string;
+    /** Scroll container (default: the viewport) */
+    root?: Element | null;
+    /**
+     * Under `prefers-reduced-motion: reduce` no offset is applied (the progress
+     * variable is still written). Set to `false` to move anyway. (default: `true`)
+     */
+    respectReducedMotion?: boolean;
+}
+/**
+ * Apply a scroll parallax to `target` (selector, Element, NodeList or array).
+ * Returns a function that stops it and removes the inline styles it set.
+ * SSR-safe (no-op without a DOM / IntersectionObserver).
+ *
+ * @example
+ * const stop = parallax('.hero-bg', { speed: 0.3 });
+ * parallax('.badge', { speed: -0.15, axis: 'x' });
+ */
+declare function parallax(target: string | Element | NodeList | Element[], options?: ParallaxHelperOptions): () => void;
+
 /**
  * use-scroll-animate - Animation Presets
  * Defines keyframes for all built-in animation presets
@@ -232,55 +328,6 @@ declare function resolvePreset(animation: AnimationPreset | AnimationPreset[] |
 declare const EASING_MAP: Record<string, string>;
 declare function resolveEasing(easing: EasingType): string;
 
-/**
- * use-scroll-animate - React Integration
- * Provides useScrollAnimate and useScrollStagger hooks for React applications.
- * `useScrollStagger({ observeChildren: true })` also animates children added later.
- *
- * Both hooks are thin wrappers around the core engine, so they share its
- * behaviour: `once`, `offset`, custom easing functions, parallax,
- * `prefers-reduced-motion` support, and proper cleanup on unmount.
- */
-
-type ReactRef<T> = {
-    current: T | null;
-};
-declare function createReactHooks(React: {
-    useRef: <T>(initial: T | null) => ReactRef<T>;
-    useEffect: (effect: () => (() => void) | void, deps?: unknown[]) => void;
-}): {
-    useScrollAnimate: (options?: AnimateOptions) => ReactRef<Element>;
-    useScrollStagger: (options?: StaggerOptions) => ReactRef<Element>;
-};
-
-/**
- * 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;
-        };
-    };
-};
-
 /**
  * Default singleton instance of ScrollAnimate.
  * Ready to use out of the box with sensible defaults.
@@ -298,5 +345,5 @@ declare function createVueComposables(Vue: {
  */
 declare const ScrollAnimate: ScrollAnimateInstance;
 
-export { EASING_MAP, PRESETS, createReactHooks, createScrollAnimate, createVueComposables, ScrollAnimate as default, getScrollProgress, resolveEasing, resolvePreset, sequence, staggerChildren };
-export type { AnimateOptions, AnimatedElement, AnimationKeyframe, AnimationPreset, CustomAnimation, EasingType, ParallaxOptions, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, SequenceController, SequenceOptions, SequenceStep, StaggerOptions };
+export { EASING_MAP, PRESETS, createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax, resolveEasing, resolvePreset, sequence, staggerChildren, supportsScrollTimeline };
+export type { AnimateOptions, AnimatedElement, AnimationKeyframe, AnimationPreset, CustomAnimation, EasingType, ParallaxHelperOptions, ParallaxOptions, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, ScrollEngine, SequenceController, SequenceOptions, SequenceStep, StaggerOptions };

package/dist/index.d.ts

@@ -11,6 +11,17 @@ type AnimationPreset = 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left
  *   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 */
@@ -71,6 +82,32 @@ interface AnimateOptions {
     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 {
@@ -109,6 +146,8 @@ interface ScrollAnimateConfig {
      * 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 {
@@ -117,6 +156,8 @@ interface AnimatedElement {
     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 {
@@ -126,6 +167,14 @@ interface ScrollAnimateInstance {
     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) */
@@ -144,6 +193,12 @@ interface ScrollAnimateInstance {
  * high-performance scroll-triggered animations.
  */
 
+/**
+ * Whether the browser can run presets on a native scroll-driven timeline:
+ * `CSS.supports('animation-timeline: view()')` plus the `ViewTimeline`
+ * constructor used to attach it from JavaScript. Cached. SSR-safe.
+ */
+declare function supportsScrollTimeline(): boolean;
 /**
  * True scroll progress of `el` through the viewport (or `root`): 0 when its top
  * edge reaches the bottom of the viewport, 1 when its bottom edge passes the top.
@@ -217,6 +272,47 @@ interface SequenceController {
  */
 declare function sequence(steps: SequenceStep[], options?: SequenceOptions): SequenceController;
 
+/**
+ * use-scroll-animate - parallax() helper
+ *
+ * Moves elements at a different speed than the page while they cross the
+ * viewport. Built on the same scroll progress as `progressVar` (0 when the
+ * element's top enters at the bottom, 1 when its bottom leaves at the top):
+ * the progress is written to a CSS custom property (default `--sa-parallax`)
+ * and the offset is applied with the individual `translate` property, so it
+ * composes with entrance animations and other `transform`s.
+ */
+interface ParallaxHelperOptions {
+    /**
+     * Total distance the element shifts while it crosses the viewport, as a
+     * fraction of the viewport size (`0.2` = 20vh on the y axis). Positive values
+     * lag behind the scroll (background-like), negative values move ahead of it
+     * (foreground-like). (default: `0.2`)
+     */
+    speed?: number;
+    /** `'y'` (default) or `'x'` (horizontal drift, in `vw`) */
+    axis?: 'x' | 'y';
+    /** CSS custom property receiving the progress (default: `'--sa-parallax'`) */
+    progressVar?: string;
+    /** Scroll container (default: the viewport) */
+    root?: Element | null;
+    /**
+     * Under `prefers-reduced-motion: reduce` no offset is applied (the progress
+     * variable is still written). Set to `false` to move anyway. (default: `true`)
+     */
+    respectReducedMotion?: boolean;
+}
+/**
+ * Apply a scroll parallax to `target` (selector, Element, NodeList or array).
+ * Returns a function that stops it and removes the inline styles it set.
+ * SSR-safe (no-op without a DOM / IntersectionObserver).
+ *
+ * @example
+ * const stop = parallax('.hero-bg', { speed: 0.3 });
+ * parallax('.badge', { speed: -0.15, axis: 'x' });
+ */
+declare function parallax(target: string | Element | NodeList | Element[], options?: ParallaxHelperOptions): () => void;
+
 /**
  * use-scroll-animate - Animation Presets
  * Defines keyframes for all built-in animation presets
@@ -232,55 +328,6 @@ declare function resolvePreset(animation: AnimationPreset | AnimationPreset[] |
 declare const EASING_MAP: Record<string, string>;
 declare function resolveEasing(easing: EasingType): string;
 
-/**
- * use-scroll-animate - React Integration
- * Provides useScrollAnimate and useScrollStagger hooks for React applications.
- * `useScrollStagger({ observeChildren: true })` also animates children added later.
- *
- * Both hooks are thin wrappers around the core engine, so they share its
- * behaviour: `once`, `offset`, custom easing functions, parallax,
- * `prefers-reduced-motion` support, and proper cleanup on unmount.
- */
-
-type ReactRef<T> = {
-    current: T | null;
-};
-declare function createReactHooks(React: {
-    useRef: <T>(initial: T | null) => ReactRef<T>;
-    useEffect: (effect: () => (() => void) | void, deps?: unknown[]) => void;
-}): {
-    useScrollAnimate: (options?: AnimateOptions) => ReactRef<Element>;
-    useScrollStagger: (options?: StaggerOptions) => ReactRef<Element>;
-};
-
-/**
- * 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;
-        };
-    };
-};
-
 /**
  * Default singleton instance of ScrollAnimate.
  * Ready to use out of the box with sensible defaults.
@@ -298,5 +345,5 @@ declare function createVueComposables(Vue: {
  */
 declare const ScrollAnimate: ScrollAnimateInstance;
 
-export { EASING_MAP, PRESETS, createReactHooks, createScrollAnimate, createVueComposables, ScrollAnimate as default, getScrollProgress, resolveEasing, resolvePreset, sequence, staggerChildren };
-export type { AnimateOptions, AnimatedElement, AnimationKeyframe, AnimationPreset, CustomAnimation, EasingType, ParallaxOptions, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, SequenceController, SequenceOptions, SequenceStep, StaggerOptions };
+export { EASING_MAP, PRESETS, createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax, resolveEasing, resolvePreset, sequence, staggerChildren, supportsScrollTimeline };
+export type { AnimateOptions, AnimatedElement, AnimationKeyframe, AnimationPreset, CustomAnimation, EasingType, ParallaxHelperOptions, ParallaxOptions, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, ScrollEngine, SequenceController, SequenceOptions, SequenceStep, StaggerOptions };