use-scroll-animate 1.2.0 → 1.5.0

package/README.md

@@ -1,214 +1,256 @@
-<div align="center">
-
-# use-scroll-animate 🚀
-
-**A lightweight (~2.9KB gzipped), dependency-free scroll animation library for the modern web.**
-
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/HarrisonCN/use-scroll-animate?style=flat-square)](https://github.com/HarrisonCN/use-scroll-animate/releases)
-[![GitHub repo size](https://img.shields.io/github/repo-size/HarrisonCN/use-scroll-animate?style=flat-square)](https://github.com/HarrisonCN/use-scroll-animate)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
-
-</div>
-
-## Why `use-scroll-animate`?
-
-In 2025, performance is everything. Traditional scroll animation libraries often bundle heavy dependencies, rely on outdated scroll event listeners, or force you into a specific framework.
-
-`use-scroll-animate` is built differently:
-- ⚡ **Zero Dependencies**: Pure Vanilla JS/TypeScript.
-- 🚀 **High Performance**: Powered by `IntersectionObserver` and the native `Web Animations API`. No scroll event listeners, no layout thrashing.
-- 🪶 **Ultra Lightweight**: Only ~2.9KB gzipped.
-- 🧩 **Framework Agnostic**: Works seamlessly with Vanilla JS, React, Vue, Svelte, and more. First-class React Hooks and Vue Composables included.
-- ♿ **Accessible**: Respects `prefers-reduced-motion` out of the box.
-
-## Installation
-
-```bash
-npm install use-scroll-animate
-# or
-yarn add use-scroll-animate
-# or
-pnpm add use-scroll-animate
-```
-
-## Quick Start (Vanilla JS / HTML)
-
-The easiest way to use it is via HTML `data-sa` attributes.
-
-```html
-<!-- 1. Add data-sa attributes to your elements -->
-<div data-sa data-sa-animation="fade-in-up" data-sa-duration="800">
-  I will animate when scrolled into view!
-</div>
-
-<div data-sa data-sa-animation="zoom-in" data-sa-delay="200">
-  Me too, with a delay!
-</div>
-
-<script type="module">
-  // 2. Import and initialize
-  import ScrollAnimate from 'use-scroll-animate';
-  
-  ScrollAnimate.init();
-</script>
-```
-
-## React Integration
-
-We provide a dedicated hook for React users.
-
-```tsx
-import { createReactHooks } from 'use-scroll-animate/react';
-import React from 'react';
-
-const { useScrollAnimate, useScrollStagger } = createReactHooks(React);
-
-function App() {
-  // Single element animation
-  const titleRef = useScrollAnimate({ animation: 'fade-in-down', duration: 1000 });
-  
-  // Staggered list animation
-  const listRef = useScrollStagger({ animation: 'fade-in-up', stagger: 100 });
-
-  return (
-    <main>
-      <h1 ref={titleRef}>Welcome to my site</h1>
-      
-      <ul ref={listRef}>
-        <li>Item 1</li>
-        <li>Item 2</li>
-        <li>Item 3</li>
-      </ul>
-    </main>
-  );
-}
-```
-
-## Vue 3 Integration
-
-First-class support for Vue 3 Composition API.
-
-```vue
-<template>
-  <main>
-    <h1 :ref="el => titleRef = el">Welcome to my site</h1>
-  </main>
-</template>
-
-<script setup>
-import { ref, onMounted, onUnmounted } from 'vue';
-import { createVueComposables } from 'use-scroll-animate/vue';
-
-const { useScrollAnimate } = createVueComposables({ ref, onMounted, onUnmounted });
-
-const { animateRef: titleRef } = useScrollAnimate({ 
-  animation: 'slide-right',
-  duration: 800 
-});
-</script>
-```
-
-## Built-in Animations
-
-Choose from 19 highly optimized built-in presets:
-
-- `fade-in`, `fade-in-up`, `fade-in-down`, `fade-in-left`, `fade-in-right`
-- `zoom-in`, `zoom-out`
-- `slide-up`, `slide-down`, `slide-left`, `slide-right`
-- `flip-x`, `flip-y`
-- `bounce`, `rotate-in`, `blur-in`
-- `skew-in`, `scale-x`, `scale-y`
-
-## Configuration Options
-
-You can pass these options via JavaScript or as `data-sa-*` attributes in HTML.
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `animation` | `string` \| `string[]` \| `object` | `['fade-in-up']` | Preset name, array of presets, or custom keyframes |
-| `duration` | `number` | `600` | Animation duration in ms |
-| `delay` | `number` | `0` | Delay before animation starts in ms |
-| `easing` | `string` | `ease` | CSS easing function (`linear`, `ease-out`, `spring`, etc.) |
-| `threshold` | `number` \| `number[]` | `0.1` | Intersection threshold (0 to 1) or array for progress |
-| `rootMargin` | `string` | `0px` | Root margin for IntersectionObserver |
-| `repeat` | `boolean` | `false` | Replay animation every time it enters viewport |
-| `stagger` | `number` | `0` | Delay between sibling elements in ms |
-| `parallax` | `object` | `{}` | Parallax effect configuration (x, y, rotate, scale, speed) |
-| `onProgress` | `(el, progress) => void` | `undefined` | Callback with scroll progress (0 to 1) |
-
-## Advanced Usage
-
-### Multiple Animations
-
-Combine multiple built-in presets for richer effects. For example, `['fade-in-up', 'zoom-in']`.
-
-```html
-<div data-sa data-sa-animation="fade-in-up, zoom-in" data-sa-duration="1200">
-  I will fade in from bottom and zoom in!
-</div>
-```
-
-### Parallax Effect
-
-Apply a parallax effect based on scroll position. Use `data-sa-parallax-x`, `data-sa-parallax-y`, `data-sa-parallax-rotate`, `data-sa-parallax-scale`.
-
-```html
-<div data-sa data-sa-parallax-y="-100px" data-sa-parallax-speed="0.5">
-  I will move up 100px as you scroll!
-</div>
-
-<div data-sa data-sa-parallax-rotate="30" data-sa-parallax-speed="0.8">
-  I will rotate 30 degrees as you scroll!
-</div>
-```
-
-### Scroll Progress Listener
-
-Get real-time scroll progress (0 to 1) for an element.
-
-```javascript
-import ScrollAnimate from 'use-scroll-animate';
-
-ScrollAnimate.observe('.progress-bar', {
-  onProgress: (el, progress) => {
-    (el as HTMLElement).style.width = `${progress * 100}%`;
-  }
-});
-```
-
-### Custom Animations
-
-You can define your own animations using the Web Animations API keyframe format:
-
-```javascript
-import ScrollAnimate from 'use-scroll-animate';
-
-ScrollAnimate.observe('.custom-box', {
-  animation: {
-    from: { opacity: 0, transform: 'scale(0.5) rotate(-45deg)' },
-    to: { opacity: 1, transform: 'scale(1) rotate(0deg)' }
-  },
-  duration: 1000,
-  easing: 'spring'
-});
-```
-
-### Callbacks
-
-```javascript
-ScrollAnimate.observe('.track-me', {
-  onStart: (el) => console.log('Animation started on', el),
-  onComplete: (el) => console.log('Animation finished on', el),
-  onEnter: (el) => console.log('Element entered viewport'),
-  onLeave: (el) => console.log('Element left viewport')
-});
-```
-
-## Contributing
-
-Contributions are always welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+<div align="center">
+
+# use-scroll-animate 🚀
+
+**A lightweight (~5KB gzipped), dependency-free scroll animation library for the modern web.**
+
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/HarrisonCN/use-scroll-animate?style=flat-square)](https://github.com/HarrisonCN/use-scroll-animate/releases)
+[![GitHub repo size](https://img.shields.io/github/repo-size/HarrisonCN/use-scroll-animate?style=flat-square)](https://github.com/HarrisonCN/use-scroll-animate)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+[English](./README.md) | [简体中文](./README_zh.md) | [日本語](./README_ja.md)
+
+</div>
+
+## Why `use-scroll-animate`?
+
+In 2025, performance is everything. Traditional scroll animation libraries often bundle heavy dependencies, rely on outdated scroll event listeners, or force you into a specific framework.
+
+`use-scroll-animate` is built differently:
+- ⚡ **Zero Dependencies**: Pure Vanilla JS/TypeScript.
+- 🚀 **High Performance**: Powered by `IntersectionObserver` and the native `Web Animations API`. No scroll event listeners by default (the opt-in scroll-progress mode uses a single passive, rAF-throttled listener, only while tracked elements are on screen).
+- 🪶 **Ultra Lightweight**: ~4.8KB gzipped for the core (tree-shaken, minified ESM); everything incl. `sequence`, `staggerChildren` and the React/Vue helpers is ~6.1KB (UMD ~6.2KB).
+- 🧩 **Framework Agnostic**: Works seamlessly with Vanilla JS, React, Vue, Svelte, and more. First-class React Hooks and Vue Composables included.
+- ♿ **Accessible**: Respects `prefers-reduced-motion` out of the box (content is shown immediately, no entrance or parallax motion).
+- 🖥️ **SSR-safe**: Importing (and even calling) the API on the server is a no-op.
+
+## Installation
+
+```bash
+npm install use-scroll-animate
+```
+
+## v1.4.0 New Features ✨
+
+### True scroll progress (`progressMode: 'scroll'`)
+By default `onProgress` reports the element's *visible ratio*, which never reaches 1 for elements taller than the screen. Opt in to real scroll progress: `0` when the element's top reaches the bottom of the viewport, `1` when its bottom leaves the top.
+
+```js
+ScrollAnimate.observe('.chapter', {
+  progressMode: 'scroll',
+  onProgress: (el, p) => el.style.setProperty('--progress', p),
+});
+```
+
+Parallax uses the same progress, so `progressMode: 'scroll'` also gives smooth parallax on tall sections. HTML: `data-sa-progress="scroll"`. Also exported as a helper: `getScrollProgress(el, root?)`.
+
+### Stagger dynamically added children
+`staggerChildren()` (vanilla), `useScrollStagger()` (React **and now Vue**) accept `observeChildren: true`. A `MutationObserver` picks up children added later (infinite lists, "load more"): those added before the reveal join the stagger; those added after it animate when they scroll into view, staggered per batch.
+
+```js
+import { staggerChildren } from 'use-scroll-animate';
+const stop = staggerChildren(document.querySelector('#feed'), {
+  animation: 'fade-in-up', stagger: 60, observeChildren: true,
+});
+// later: stop();
+```
+
+### Timelines with `sequence()`
+Chain animations across elements. Each step starts when the previous one ends; `gap` adds a pause (negative values overlap) and `at` sets an absolute start time.
+
+```js
+import { sequence } from 'use-scroll-animate';
+
+const tl = sequence([
+  { target: '.hero h1', animation: 'fade-in-up', duration: 700 },
+  { target: '.hero p', animation: 'blur-in', gap: -300 },
+  { target: '.hero .btn', animation: 'scale-up', stagger: 80 },
+], { trigger: '.hero', easing: 'soft-spring' }); // auto-plays once when .hero enters
+
+await tl.play();   // or play manually; resolves when every step is done
+tl.cancel();       // stop and leave everything visible
+```
+
+### New presets
+`scale-up`, `blur-in-up`, `flip-up`, `flip-down`, `rotate-left`, `rotate-right`, and clip-path reveals `clip-up`, `clip-down`, `clip-left`, `clip-right`, `clip-circle`.
+
+### Smaller memory footprint
+Finished `once` elements are dropped from the registry right after they animate (unless they still need parallax/`onProgress`), so long pages and SPAs don't keep thousands of records alive. They're remembered in a `WeakSet`, so `init()`/`observe()` never replay them. Set `createScrollAnimate({ autoUnregister: false })` to keep them listed in `getObservedElements()` as before.
+
+### Proper `exports` map
+Node ESM (`import`) resolves to `dist/index.mjs`, CommonJS (`require`) to `dist/index.js`, each with matching bundled types. The legacy `main`/`module`/`unpkg` fields and `dist/*` deep imports keep working.
+
+## v1.3.0: Custom Easing 🎨
+
+You can now use custom cubic-bezier curves or even JavaScript functions to create complex physical effects.
+
+### 1. Cubic-Bezier Array
+Pass an array of 4 numbers to define a custom cubic-bezier curve.
+
+```javascript
+ScrollAnimate.observe('.box', {
+  animation: 'fade-in-up',
+  easing: [0.68, -0.55, 0.265, 1.55] // Custom bounce effect
+});
+```
+
+### 2. Custom Easing Function
+Pass a function `(t: number) => number` for complete control over the animation timing.
+
+```javascript
+ScrollAnimate.observe('.box', {
+  easing: (t) => t * t * (3 - 2 * t) // Custom smooth-step
+});
+```
+
+### 3. New Physics Presets
+We've added high-quality physics-based easing presets:
+- `spring`: Standard spring effect.
+- `soft-spring`: Gentle, bouncy entrance.
+- `heavy-bounce`: Dramatic bounce effect.
+
+## Quick Start (Vanilla JS / HTML)
+
+```html
+<div data-sa data-sa-animation="fade-in-up" data-sa-easing="soft-spring">
+  I have a soft spring effect!
+</div>
+
+<div data-sa data-sa-animation="zoom-in" data-sa-easing="[0.34, 1.56, 0.64, 1]">
+  I use a custom cubic-bezier array!
+</div>
+
+<script type="module">
+  import ScrollAnimate from 'use-scroll-animate';
+  ScrollAnimate.init();
+</script>
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `animation` | `string` \| `string[]` \| `{ from, to }` | `'fade-in-up'` | Preset name, array of presets to combine, or custom keyframes |
+| `duration` | `number` | `600` | Duration in ms |
+| `delay` | `number` | `0` | Delay in ms |
+| `easing` | `string` \| `number[]` \| `function` | `'ease'` | CSS easing, preset (`spring`, `soft-spring`, `heavy-bounce`), cubic-bezier array, or `(t) => number` |
+| `threshold` | `number` \| `number[]` | `0.1` | IntersectionObserver threshold(s) |
+| `rootMargin` | `string` | `'0px'` | IntersectionObserver root margin |
+| `once` | `boolean` | `true` | Animate only the first time the element enters |
+| `repeat` | `boolean` | `false` | Re-hide on leave and replay on every entry |
+| `offset` | `number` | `0` | Trigger the animation this many px after the element enters the viewport |
+| `stagger` | `number` | `0` | Extra delay (ms) per sibling revealed in the same batch |
+| `parallax` | `{ x, y, rotate, scale, speed }` | `{}` | Scroll-driven parallax (keeps running after the entrance animation) |
+| `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-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
+ScrollAnimate.refresh();              // rebuild observers, e.g. after configure({ root })
+ScrollAnimate.configure({ ... });     // update global defaults
+ScrollAnimate.destroy();              // disconnect everything
+
+const sa = createScrollAnimate({ root: document.querySelector('#scroller') }); // isolated instance
+
+// Helpers (tree-shakeable)
+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
+<script src="https://unpkg.com/use-scroll-animate"></script>
+<script>ScrollAnimate.default.init();</script>
+```
+
+## React & Vue
+
+```jsx
+import React from 'react';
+import { createReactHooks } from 'use-scroll-animate';
+const { useScrollAnimate, useScrollStagger } = createReactHooks(React);
+
+function Card() {
+  const ref = useScrollAnimate({ animation: 'zoom-in', easing: 'spring' });
+  return <div ref={ref}>Hello</div>;
+}
+```
+
+```js
+import { ref, onMounted, onUnmounted } from 'vue';
+import { createVueComposables } from 'use-scroll-animate';
+const { useScrollAnimate, useScrollStagger } = createVueComposables({ ref, onMounted, onUnmounted });
+const { animateRef } = useScrollAnimate({ animation: 'fade-in-left' });
+const { staggerRef } = useScrollStagger({ stagger: 60, observeChildren: true }); // <ul ref="staggerRef">
+```
+
+```jsx
+// React: also animate items appended later
+function Feed({ items }) {
+  const ref = useScrollStagger({ animation: 'fade-in-up', stagger: 60, observeChildren: true });
+  return <ul ref={ref}>{items.map((i) => <li key={i.id}>{i.title}</li>)}</ul>;
+}
+```
+
+Hooks and composables share the core engine, so `once`, `offset`, custom easing functions, parallax and reduced-motion handling behave exactly like the vanilla API.
+
+## Contributing
+
+Contributions are always welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.