use-scroll-animate 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-10-07
+
+### Added
+- `watch(root?)` instance method: automatically observes `[data-sa]` elements added to the DOM later; returns a stop function, and `destroy()` stops all watchers.
+- `progressVar` option and `data-sa-progress-var` attribute: expose scroll progress (0–1) as a CSS custom property.
+
+### Fixed
+- Stopping `staggerChildren` or cancelling a triggered `sequence()` before the content entered the viewport left it at `opacity: 0`; it is now restored (also affects React/Vue `useScrollStagger` unmounting off-screen).
+
+### Tests / CI
+- 47 new tests covering reduced motion, SSR, unmount cleanup and lifecycle; CI job timeout and `npm pack --dry-run`.
+
 ## [1.4.0] - 2026-10-06
 
 ### Added

package/README.md

@@ -144,19 +144,42 @@ We've added high-quality physics-based easing presets:
 | `onStart` / `onComplete` / `onEnter` / `onLeave` | `(el) => void` | – | Lifecycle callbacks |
 | `onProgress` | `(el, progress) => void` | – | Progress (0–1) as the element scrolls — visible ratio, or true scroll progress with `progressMode: 'scroll'` |
 | `progressMode` | `'ratio'` \| `'scroll'` | `'ratio'` | How `onProgress`/parallax progress is measured (`'scroll'`: 0 = top enters at the bottom, 1 = bottom leaves at the top) |
+| `progressVar` | `string` | – | Write progress (0–1, same value as `onProgress`) to this CSS custom property, e.g. `'--sa-progress'`, for scroll-driven effects in plain CSS |
 
-Every option is also available as a data attribute: `data-sa-animation`, `data-sa-duration`, `data-sa-delay`, `data-sa-easing`, `data-sa-threshold`, `data-sa-root-margin`, `data-sa-once`, `data-sa-repeat`, `data-sa-offset`, `data-sa-stagger`, `data-sa-progress`, `data-sa-parallax-x|y|rotate|scale|speed`.
+Every option is also available as a data attribute: `data-sa-animation`, `data-sa-duration`, `data-sa-delay`, `data-sa-easing`, `data-sa-threshold`, `data-sa-root-margin`, `data-sa-once`, `data-sa-repeat`, `data-sa-offset`, `data-sa-stagger`, `data-sa-progress`, `data-sa-progress-var` (bare attribute = `--sa-progress`), `data-sa-parallax-x|y|rotate|scale|speed`.
 
 **Presets:** `fade-in`, `fade-in-up|down|left|right`, `zoom-in`, `zoom-out`, `scale-up`, `flip-x`, `flip-y`, `flip-up`, `flip-down`, `slide-up|down|left|right`, `bounce`, `rotate-in`, `rotate-left`, `rotate-right`, `blur-in`, `blur-in-up`, `skew-in`, `scale-x`, `scale-y`, `clip-up|down|left|right`, `clip-circle`, `shimmer`, `pulse`, `swing`. Combine them with an array, e.g. `['fade-in', 'clip-up']`.
 
 **Global config** (`createScrollAnimate(config)` / `configure()`): `defaultAnimation`, `defaultDuration`, `defaultDelay`, `defaultEasing`, `defaultThreshold`, `defaultRootMargin`, `defaultRepeat`, `defaultOnce`, `defaultOffset`, `hiddenClass`, `visibleClass`, `useClassNames`, `disabled`, `root`, `autoUnregister` (default `true`).
 
+### Progress as a CSS variable (`progressVar`)
+
+Drive any CSS property from scroll position without writing JavaScript callbacks. The element's progress is written to a custom property on the element itself:
+
+```html
+<div data-sa data-sa-progress="scroll" data-sa-progress-var class="hero">…</div>
+
+<style>
+  @media (prefers-reduced-motion: no-preference) {
+    .hero { transform: translateY(calc((1 - var(--sa-progress, 0)) * 60px)); opacity: calc(0.4 + var(--sa-progress, 0)); }
+  }
+</style>
+```
+
+```js
+ScrollAnimate.observe('.bar', { progressVar: '--fill', progressMode: 'scroll' });
+// .bar::after { transform: scaleX(var(--fill, 0)); }
+```
+
+It uses the same rAF-throttled / IntersectionObserver pipeline as `onProgress`, keeps updating after the entrance animation, and is still written under reduced motion (it is data) — guard motion in your CSS with `prefers-reduced-motion` as above.
+
 ## Instance API
 
 ```js
 import ScrollAnimate, { createScrollAnimate } from 'use-scroll-animate';
 
 ScrollAnimate.init(root?);            // observe every [data-sa] element (safe to call again after DOM changes)
+const stop = ScrollAnimate.watch(root?); // init() + auto-observe [data-sa] elements added later; stop() to end
 ScrollAnimate.observe(target, opts);  // selector, Element, NodeList or Element[]
 ScrollAnimate.unobserve(target);      // stop observing (elements that never animated are made visible)
 ScrollAnimate.animate(target, opts);  // play an animation right now
@@ -170,6 +193,22 @@ const sa = createScrollAnimate({ root: document.querySelector('#scroller') }); /
 import { sequence, staggerChildren, getScrollProgress } from 'use-scroll-animate';
 ```
 
+### Watching the DOM (`watch()`)
+
+For SPAs, CMS content, infinite lists or anything rendered after page load, `watch()` replaces "call `init()` again after every DOM change":
+
+```js
+import ScrollAnimate from 'use-scroll-animate';
+
+const stop = ScrollAnimate.watch();              // or watch(document.querySelector('#app'))
+// [data-sa] elements inserted later — even deep inside a new subtree, or an existing
+// element that gains the data-sa attribute — are observed with their data-sa-* options.
+// Elements removed from the DOM are released; finished `once` elements are never replayed.
+stop();                                          // stop watching (destroy() also stops every watcher)
+```
+
+It uses a single `MutationObserver` per call and is a no-op on the server or without `MutationObserver`.
+
 Via a `<script>` tag (UMD build), the default instance lives at `ScrollAnimate.default`:
 
 ```html

package/dist/index.d.mts

@@ -71,6 +71,12 @@ 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;
 }
 /** Global configuration for ScrollAnimate instance */
 interface ScrollAnimateConfig {
@@ -126,6 +132,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) */

package/dist/index.d.ts

@@ -71,6 +71,12 @@ 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;
 }
 /** Global configuration for ScrollAnimate instance */
 interface ScrollAnimateConfig {
@@ -126,6 +132,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) */

package/dist/index.esm.js

@@ -252,6 +252,14 @@ function lengthValue(value) {
     const v = value.trim();
     return /^-?(\d+\.?\d*|\.\d+)$/.test(v) ? parseFloat(v) : v;
 }
+const DEFAULT_PROGRESS_VAR = '--sa-progress';
+/** `''` (bare attribute) -> default name; `sa-progress` -> `--sa-progress`. */
+function normalizeVar(name) {
+    const v = name.trim();
+    if (!v)
+        return DEFAULT_PROGRESS_VAR;
+    return v.startsWith('--') ? v : `--${v}`;
+}
 function parseDataAttributes(el, config) {
     var _a;
     const dataset = el.dataset || {};
@@ -290,6 +298,8 @@ function parseDataAttributes(el, config) {
         opts.once = dataset.saOnce !== 'false';
     opts.offset = num(dataset.saOffset);
     opts.stagger = num(dataset.saStagger);
+    if (dataset.saProgressVar !== undefined)
+        opts.progressVar = normalizeVar(dataset.saProgressVar);
     if (dataset.saProgress)
         opts.progressMode = dataset.saProgress.trim() === 'scroll' ? 'scroll' : 'ratio';
     if (dataset.saParallaxX || dataset.saParallaxY || dataset.saParallaxRotate || dataset.saParallaxScale) {
@@ -325,6 +335,7 @@ function mergeOptions(opts, config) {
         onLeave: (_q = opts.onLeave) !== null && _q !== void 0 ? _q : noop,
         onProgress: (_r = opts.onProgress) !== null && _r !== void 0 ? _r : noop,
         progressMode: (_s = opts.progressMode) !== null && _s !== void 0 ? _s : 'ratio',
+        progressVar: opts.progressVar ? normalizeVar(opts.progressVar) : '',
     };
 }
 function resolveTargets(target) {
@@ -361,7 +372,7 @@ function hasParallax(p) {
     return !!p && Object.keys(p).some((k) => p[k] !== undefined);
 }
 function needsProgress(opts) {
-    return hasParallax(opts.parallax) || opts.onProgress !== noop;
+    return hasParallax(opts.parallax) || opts.onProgress !== noop || !!opts.progressVar;
 }
 /**
  * True scroll progress of `el` through the viewport (or `root`): 0 when its top
@@ -622,6 +633,8 @@ function createScrollAnimate(userConfig = {}) {
     const scrolling = new Set();
     let frame = 0;
     let listening = null;
+    // Active watch() MutationObservers, disconnected by destroy().
+    const watchers = new Set();
     // Observers are shared between elements with the same root/threshold/rootMargin,
     // instead of one (or two) IntersectionObservers per element.
     const pools = new Map();
@@ -656,6 +669,11 @@ function createScrollAnimate(userConfig = {}) {
     function emitProgress(el, record, progress) {
         const opts = record.options;
         opts.onProgress(el, progress);
+        if (opts.progressVar) {
+            const style = el.style;
+            if (style)
+                style.setProperty(opts.progressVar, String(+progress.toFixed(4)));
+        }
         if (hasParallax(opts.parallax) && !motionDisabled(config))
             applyParallax(el, progress, opts.parallax);
     }
@@ -800,6 +818,10 @@ function createScrollAnimate(userConfig = {}) {
         registry.set(el, record);
         attach(el, record, true);
     }
+    function observeDataElement(el) {
+        if (!registry.has(el))
+            observeElement(el, parseDataAttributes(el, config));
+    }
     const instance = {
         observe(target, options = {}) {
             pruneDetached();
@@ -817,12 +839,48 @@ function createScrollAnimate(userConfig = {}) {
             if (!scope)
                 return;
             pruneDetached();
-            scope.querySelectorAll('[data-sa]').forEach((el) => {
-                if (!registry.has(el))
-                    observeElement(el, parseDataAttributes(el, config));
+            scope.querySelectorAll('[data-sa]').forEach(observeDataElement);
+        },
+        watch(rootElement) {
+            const scope = rootElement !== null && rootElement !== void 0 ? rootElement : (hasDOM() ? document : null);
+            if (!scope || typeof MutationObserver === 'undefined')
+                return noop;
+            instance.init(scope);
+            const observeTree = (node) => {
+                if (node.hasAttribute('data-sa'))
+                    observeDataElement(node);
+                node.querySelectorAll('[data-sa]').forEach(observeDataElement);
+            };
+            const mo = new MutationObserver((records) => {
+                let removed = false;
+                records.forEach((record) => {
+                    if (record.type === 'attributes') {
+                        const target = record.target;
+                        if (target.isConnected !== false)
+                            observeTree(target);
+                        return;
+                    }
+                    record.addedNodes.forEach((node) => {
+                        if (node instanceof Element && node.isConnected !== false)
+                            observeTree(node);
+                    });
+                    if (record.removedNodes.length)
+                        removed = true;
+                });
+                // Free elements that left the DOM (they can't animate any more).
+                if (removed)
+                    pruneDetached();
             });
+            mo.observe(scope, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-sa'] });
+            watchers.add(mo);
+            return () => {
+                mo.disconnect();
+                watchers.delete(mo);
+            };
         },
         destroy() {
+            watchers.forEach((mo) => mo.disconnect());
+            watchers.clear();
             registry.forEach((record, el) => {
                 if (!record.animated)
                     reveal(el, config);
@@ -932,6 +990,12 @@ function staggerChildren(container, options = {}, instance) {
     return () => {
         io.disconnect();
         mo === null || mo === void 0 ? void 0 : mo.disconnect();
+        // Stopped before the container was revealed: never leave the children hidden.
+        if (!revealed) {
+            revealed = true;
+            items.forEach((child) => stopAnimation(child));
+            items = [];
+        }
         late.forEach((el) => sa.unobserve(el));
         late.length = 0;
     };
@@ -979,6 +1043,8 @@ function sequence(steps, options = {}) {
     let io;
     let active = [];
     let settle;
+    // Targets hidden while waiting for `trigger`; revealed if cancelled before it fires.
+    let prepared = [];
     const controller = {
         play() {
             controller.cancel();
@@ -1010,6 +1076,8 @@ function sequence(steps, options = {}) {
         cancel() {
             io === null || io === void 0 ? void 0 : io.disconnect();
             io = undefined;
+            prepared.forEach((el) => stopAnimation(el));
+            prepared = [];
             active.forEach(({ el }) => stopAnimation(el));
             active = [];
             settle === null || settle === void 0 ? void 0 : settle();
@@ -1021,12 +1089,14 @@ function sequence(steps, options = {}) {
     if (trigger && hasDOM() && supportsObserver()) {
         const el = resolveTargets(trigger)[0];
         if (el) {
-            plan(steps, defaults).forEach(({ el: target }) => prepareElement(target));
+            prepared = plan(steps, defaults).map(({ el: target }) => target);
+            prepared.forEach((target) => prepareElement(target));
             io = new IntersectionObserver((entries) => {
                 if (!entries.some((e) => e.isIntersecting))
                     return;
                 io === null || io === void 0 ? void 0 : io.disconnect();
                 io = undefined;
+                prepared = []; // play() takes over from here
                 controller.play();
             }, { threshold: (_a = defaults.threshold) !== null && _a !== void 0 ? _a : 0.1, rootMargin: (_b = defaults.rootMargin) !== null && _b !== void 0 ? _b : '0px' });
             io.observe(el);