use-scroll-animate 1.2.0 → 1.4.0

package/README_zh.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_ja.md)
-
-</div>
-
-## 为什么选择 `use-scroll-animate`？
-
-在 2025 年，性能至关重要。传统的滚动动画库通常捆绑了沉重的依赖，依赖过时的滚动事件监听器，或者强制你使用特定的框架。
-
-`use-scroll-animate` 的设计初衷截然不同：
-- ⚡ **零依赖**：纯原生 JS/TypeScript 编写。
-- 🚀 **高性能**：由 `IntersectionObserver` 和原生 `Web Animations API` 驱动。无滚动事件监听，无布局抖动。
-- 🪶 **极轻量**：Gzip 后仅约 2.9KB。
-- 🧩 **框架无关**：完美支持原生 JS、React、Vue、Svelte 等。内置一流的 React Hooks 和 Vue Composables。
-- ♿ **无障碍**：原生支持 `prefers-reduced-motion`。
-
-## 安装
-
-```bash
-npm install use-scroll-animate
-```
-
-## 快速上手 (原生 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` 的设计初衷截然不同：
+- ⚡ **零依赖**：纯原生 JS/TypeScript 编写。
+- 🚀 **高性能**：由 `IntersectionObserver` 和原生 `Web Animations API` 驱动。默认不监听滚动事件（可选的滚动进度模式仅在被追踪元素可见时使用一个 passive、rAF 节流的监听器），无布局抖动。
+- 🪶 **极轻量**：Gzip 后核心约 4.8KB（含 `sequence`、`staggerChildren` 与 React/Vue 辅助在内全部约 6.1KB）。
+- 🧩 **框架无关**：完美支持原生 JS、React、Vue、Svelte 等。内置一流的 React Hooks 和 Vue Composables。
+- ♿ **无障碍**：原生支持 `prefers-reduced-motion`。
+
+## 安装
+
+```bash
+npm install use-scroll-animate
+```
+
+## 快速上手 (原生 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()`（原生）与 `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) 文件。

package/dist/index.d.mts

@@ -0,0 +1,302 @@
+/**
+ * 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';
+/** 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;
+}
+/** Global configuration for ScrollAnimate instance */
+interface ScrollAnimateConfig {
+    /** Default animation preset (default: 'fade-in-up') */
+    defaultAnimation?: AnimationPreset | AnimationPreset[] | CustomAnimation;
+    /** Default duration in ms (default: 600) */
+    defaultDuration?: number;
+    /** Default delay in ms (default: 0) */
+    defaultDelay?: number;
+    /** Default easing (default: 'ease') */
+    defaultEasing?: EasingType;
+    /** Default threshold (default: 0.1) */
+    defaultThreshold?: number | number[];
+    /** Default root margin (default: '0px') */
+    defaultRootMargin?: string;
+    /** Whether animations replay by default (default: false) */
+    defaultRepeat?: boolean;
+    /** Default once setting (default: true) */
+    defaultOnce?: boolean;
+    /** Default offset in pixels (default: 0) */
+    defaultOffset?: number;
+    /** CSS class added before animation (default: 'sa-hidden') */
+    hiddenClass?: string;
+    /** CSS class added when element is visible (default: 'sa-visible') */
+    visibleClass?: string;
+    /** Whether to use CSS class-based animation instead of Web Animations API */
+    useClassNames?: boolean;
+    /** Disable all animations (useful for reduced-motion preference) */
+    disabled?: boolean;
+    /** Custom IntersectionObserver root element */
+    root?: Element | null;
+    /**
+     * Drop `once` elements from the registry as soon as their entrance animation
+     * has been triggered (unless they still need parallax/onProgress), so they can
+     * be garbage-collected. They are remembered in a WeakSet, so `init()`/`observe()`
+     * never re-hide or replay them. (default: true)
+     */
+    autoUnregister?: boolean;
+}
+/** Registered element entry */
+interface AnimatedElement {
+    element: Element;
+    options: Required<AnimateOptions>;
+    observer: IntersectionObserver;
+    animated: boolean;
+    progressObserver?: IntersectionObserver;
+}
+/** ScrollAnimate public API */
+interface ScrollAnimateInstance {
+    /** Observe a single element or CSS selector */
+    observe(target: string | Element | NodeList | Element[], options?: AnimateOptions): void;
+    /** Stop observing a single element or CSS selector */
+    unobserve(target: string | Element | NodeList | Element[]): void;
+    /** Observe all elements matching the data-sa attribute */
+    init(rootElement?: Element | Document): void;
+    /** Destroy the instance and clean up all observers */
+    destroy(): void;
+    /** Refresh all observers (useful after DOM changes) */
+    refresh(): void;
+    /** Manually trigger animation on an element */
+    animate(target: string | Element, options?: AnimateOptions): void;
+    /** Get all currently observed elements */
+    getObservedElements(): AnimatedElement[];
+    /** Update global configuration */
+    configure(config: Partial<ScrollAnimateConfig>): void;
+}
+
+/**
+ * use-scroll-animate - Core Implementation
+ * Uses IntersectionObserver + Web Animations API for zero-dependency,
+ * high-performance scroll-triggered animations.
+ */
+
+/**
+ * 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.
+ * Works for elements taller than the viewport. Returns 0 without a DOM.
+ */
+declare function getScrollProgress(el: Element, root?: Element | null): number;
+declare function createScrollAnimate(userConfig?: ScrollAnimateConfig): ScrollAnimateInstance;
+
+/**
+ * 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;
+}
+/**
+ * Animate the children of `container` with a stagger once it enters the
+ * viewport. Returns a cleanup function. SSR-safe (no-op without a DOM).
+ *
+ * @example
+ * const stop = staggerChildren(document.querySelector('ul'), { stagger: 60, observeChildren: true });
+ */
+declare function staggerChildren(container: Element | null | undefined, options?: StaggerOptions, instance?: ScrollAnimateInstance): () => void;
+
+/**
+ * use-scroll-animate - Sequence / timeline helper
+ * Chain animations on several targets, one after another (or overlapping).
+ */
+
+interface SequenceStep extends AnimateOptions {
+    /** Selector, Element, NodeList or Element[] to animate in this step */
+    target: string | Element | NodeList | Element[];
+    /** Pause (ms) after the previous step ends before this one starts. Negative values overlap. (default: 0) */
+    gap?: number;
+    /** Absolute start time (ms) on the timeline; overrides `gap` */
+    at?: number;
+}
+interface SequenceOptions extends AnimateOptions {
+    /** Play automatically (once) when this element/selector enters the viewport */
+    trigger?: string | Element;
+    /** Instance whose global config (easing, classes, `disabled`) is used */
+    instance?: ScrollAnimateInstance;
+}
+interface SequenceController {
+    /** Play (or replay) the timeline. Resolves when every step has completed, or on `cancel()`. */
+    play(): Promise<void>;
+    /** Stop the trigger and running animations; elements are left visible. */
+    cancel(): void;
+    /** Total duration of the timeline in ms (computed for the current DOM). */
+    duration(): number;
+}
+/**
+ * Build a timeline of animations.
+ *
+ * @example
+ * sequence([
+ *   { target: '.title', animation: 'fade-in-up' },
+ *   { target: '.subtitle', animation: 'blur-in', gap: -300 },   // overlap by 300ms
+ *   { target: '.card', animation: 'scale-up', stagger: 80 },
+ * ], { trigger: '.hero' });
+ */
+declare function sequence(steps: SequenceStep[], options?: SequenceOptions): SequenceController;
+
+/**
+ * use-scroll-animate - Animation Presets
+ * Defines keyframes for all built-in animation presets
+ */
+
+type KeyframeMap = {
+    from: Record<string, string | number>;
+    to: Record<string, string | number>;
+};
+declare const PRESETS: Record<AnimationPreset, KeyframeMap>;
+declare function resolvePreset(animation: AnimationPreset | AnimationPreset[] | CustomAnimation): KeyframeMap;
+/** Easing to CSS cubic-bezier mapping */
+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.
+ *
+ * @example
+ * ```js
+ * import ScrollAnimate from 'use-scroll-animate';
+ *
+ * // Auto-initialize all elements with data-sa attribute
+ * ScrollAnimate.init();
+ *
+ * // Or manually observe elements
+ * ScrollAnimate.observe('.my-element', { animation: 'fade-in-up' });
+ * ```
+ */
+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 };