use-scroll-animate 1.2.0 → 1.4.0

package/README.md

@@ -1,214 +1,217 @@
-<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) |
+
+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`.
+
+**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`).
+
+## 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)
+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';
+```
+
+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.

package/README_ja.md

@@ -1,69 +1,106 @@
-<div align="center">
-
-# use-scroll-animate 🚀
-
-**軽量（~2.9KB gzipped）、依存関係なしのモダン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)
-
-</div>
-
-## なぜ `use-scroll-animate` なのか？
-
-2025年、パフォーマンスはすべてです。従来のスクロールアニメーションライブラリは、重い依存関係をバンドルしたり、古いスクロールイベントリスナーに依存したり、特定のフレームワークを強制したりすることがよくあります。
-
-`use-scroll-animate` は違います：
-- ⚡ **依存関係なし**：純粋な Vanilla JS/TypeScript。
-- 🚀 **高パフォーマンス**：`IntersectionObserver` とネイティブの `Web Animations API` で駆動。スクロールイベントリスナーなし、レイアウトスラッシングなし。
-- 🪶 **超軽量**：Gzip後わずか約2.9KB。
-- 🧩 **フレームワークに依存しない**：Vanilla JS、React、Vue、Svelteなどとシームレスに動作。一流の React Hooks と Vue Composables を内蔵。
-- ♿ **アクセシブル**：`prefers-reduced-motion` を標準でサポート。
-
-## インストール
-
-```bash
-npm install use-scroll-animate
-```
-
-## クイックスタート (Vanilla JS / HTML)
-
-最も簡単な方法は、HTML の `data-sa` 属性を使用することです。
-
-```html
-<!-- 1. 要素に data-sa 属性を追加 -->
-<div data-sa data-sa-animation="fade-in-up" data-sa-duration="800">
-  スクロールされるとアニメーションします！
-</div>
-
-<script type="module">
-  // 2. インポートして初期化
-  import ScrollAnimate from 'use-scroll-animate';
-  ScrollAnimate.init();
-</script>
-```
-
-## v1.2.0 の新機能
-
-- **一度だけ実行 (Once)**：アニメーション実行後に監視を自動停止し、リソースを節約。
-- **オフセット (Offset)**：要素がビューポートに入ってから何ピクセル後にアニメーションを開始するかを指定可能。
-- **新しいプリセット**：`shimmer`（シマー）、`pulse`（パルス）、`swing`（スイング）を追加。
-- **多言語サポート**：中国語と日本語のドキュメントを追加。
-
-## 主な設定
-
-| オプション | 型 | デフォルト | 説明 |
-|--------|------|---------|-------------|
-| `animation` | `string` \| `string[]` | `'fade-in-up'` | プリセット名またはプリセットの配列 |
-| `duration` | `number` | `600` | アニメーションの長さ (ms) |
-| `delay` | `number` | `0` | アニメーションの遅延 (ms) |
-| `once` | `boolean` | `true` | 一度だけ実行するかどうか |
-| `offset` | `number` | `0` | アニメーションを開始するビューポートのオフセット (px) |
-| `parallax` | `object` | `{}` | パララックス効果の設定 |
-
-## ライセンス
-
-このプロジェクトは MIT ライセンスの下でライセンスされています - 詳細は [LICENSE](LICENSE) ファイルを参照してください。
+<div align="center">
+
+# use-scroll-animate 🚀
+
+**軽量（~5KB gzipped）、依存関係なしのモダン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>
+
+## なぜ `use-scroll-animate` なのか？
+
+2025年、パフォーマンスはすべてです。従来のスクロールアニメーションライブラリは、重い依存関係をバンドルしたり、古いスクロールイベントリスナーに依存したり、特定のフレームワークを強制したりすることがよくあります。
+
+`use-scroll-animate` は違います：
+- ⚡ **依存関係なし**：純粋な Vanilla JS/TypeScript。
+- 🚀 **高パフォーマンス**：`IntersectionObserver` とネイティブの `Web Animations API` で駆動。デフォルトではスクロールイベントリスナーなし（オプトインのスクロール進捗モードは、対象要素が画面内にある間だけ passive・rAF スロットルのリスナーを1つ使用）、レイアウトスラッシングなし。
+- 🪶 **超軽量**：Gzip後コア約4.8KB（`sequence`・`staggerChildren`・React/Vue ヘルパーを含む全体で約6.1KB）。
+- 🧩 **フレームワークに依存しない**：Vanilla JS、React、Vue、Svelteなどとシームレスに動作。一流の React Hooks と Vue Composables を内蔵。
+- ♿ **アクセシブル**：`prefers-reduced-motion` を標準でサポート。
+
+## インストール
+
+```bash
+npm install use-scroll-animate
+```
+
+## クイックスタート (Vanilla JS / HTML)
+
+最も簡単な方法は、HTML の `data-sa` 属性を使用することです。
+
+```html
+<!-- 1. 要素に data-sa 属性を追加 -->
+<div data-sa data-sa-animation="fade-in-up" data-sa-duration="800">
+  スクロールされるとアニメーションします！
+</div>
+
+<script type="module">
+  // 2. インポートして初期化
+  import ScrollAnimate from 'use-scroll-animate';
+  ScrollAnimate.init();
+</script>
+```
+
+## v1.4.0 の新機能 ✨
+
+- **本当のスクロール進捗 `progressMode: 'scroll'`**（オプトイン）：`onProgress` はデフォルトで要素の表示比率を返すため、画面より高い要素では 1 に到達しません。有効にすると、要素の上端がビューポート下端に達したとき `0`、下端がビューポート上端を抜けたとき `1` になります。パララックスも同じ進捗を使用します。HTML では `data-sa-progress="scroll"`。ヘルパー `getScrollProgress(el, root?)` もエクスポートされています。
+
+  ```js
+  ScrollAnimate.observe('.chapter', {
+    progressMode: 'scroll',
+    onProgress: (el, p) => el.style.setProperty('--progress', p),
+  });
+  ```
+
+- **動的に追加された子要素のスタッガー**：`staggerChildren()`（Vanilla）と `useScrollStagger()`（React、**Vue にも新たに対応**）に `observeChildren: true` を追加。`MutationObserver` で後から追加された子要素（無限リスト、「もっと見る」）を検出します。表示前に追加された要素はスタッガーに加わり、表示後に追加された要素はビューポートに入ったときにバッチ単位でスタッガー再生されます。
+
+  ```js
+  import { staggerChildren } from 'use-scroll-animate';
+  const stop = staggerChildren(document.querySelector('#feed'), { stagger: 60, observeChildren: true });
+  ```
+
+- **タイムライン `sequence()`**：複数要素のアニメーションを連結。各ステップは前のステップの終了後に開始し、`gap` で間隔（負の値で重ね合わせ）、`at` で絶対開始時刻を指定できます。`trigger` を指定するとその要素が表示されたときに一度だけ自動再生します。
+
+  ```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' });
+  await tl.play(); // すべて完了すると resolve。tl.cancel() で停止し要素は表示されたまま
+  ```
+
+- **新しいプリセット**：`scale-up`、`blur-in-up`、`flip-up`、`flip-down`、`rotate-left`、`rotate-right`、clip-path による `clip-up`、`clip-down`、`clip-left`、`clip-right`、`clip-circle`。
+- **メモリ使用量の削減**：`once` 要素はアニメーション開始後に自動でレジストリから削除されます（パララックス/`onProgress` が必要な要素を除く）。`WeakSet` で記憶されるため、`init()`/`observe()` で再生されることはありません。従来の挙動は `createScrollAnimate({ autoUnregister: false })`。
+- **正しい `exports` マップ**：Node ESM は `dist/index.mjs`、CommonJS は `dist/index.js` に解決され、それぞれ対応する型定義付き。従来の `main`/`module`/`unpkg` と `dist/*` のディープインポートも引き続き利用可能。
+
+## v1.2.0 の新機能
+
+- **一度だけ実行 (Once)**：アニメーション実行後に監視を自動停止し、リソースを節約。
+- **オフセット (Offset)**：要素がビューポートに入ってから何ピクセル後にアニメーションを開始するかを指定可能。
+- **新しいプリセット**：`shimmer`（シマー）、`pulse`（パルス）、`swing`（スイング）を追加。
+- **多言語サポート**：中国語と日本語のドキュメントを追加。
+
+## 主な設定
+
+| オプション | 型 | デフォルト | 説明 |
+|--------|------|---------|-------------|
+| `animation` | `string` \| `string[]` | `'fade-in-up'` | プリセット名またはプリセットの配列 |
+| `duration` | `number` | `600` | アニメーションの長さ (ms) |
+| `delay` | `number` | `0` | アニメーションの遅延 (ms) |
+| `once` | `boolean` | `true` | 一度だけ実行するかどうか |
+| `offset` | `number` | `0` | アニメーションを開始するビューポートのオフセット (px) |
+| `parallax` | `object` | `{}` | パララックス効果の設定 |
+| `stagger` | `number` | `0` | 同じバッチで表示される兄弟要素ごとの追加遅延 (ms) |
+| `onProgress` | `(el, progress) => void` | – | スクロール進捗のコールバック (0–1) |
+| `progressMode` | `'ratio'` \| `'scroll'` | `'ratio'` | 進捗の計算方法：表示比率または本当のスクロール進捗 |
+
+## ライセンス
+
+このプロジェクトは MIT ライセンスの下でライセンスされています - 詳細は [LICENSE](LICENSE) ファイルを参照してください。