use-scroll-animate 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2025-03-25
+
+### Added
+
+- **Once Control**: New `once` option to automatically stop observing an element after its animation has triggered, saving system resources.
+- **Viewport Offset**: New `offset` option to specify how many pixels an element must enter the viewport before the animation starts.
+- **New Animation Presets**: Added `shimmer`, `pulse`, and `swing`.
+- **Multi-language Documentation**: Added Chinese (`README_zh.md`) and Japanese (`README_ja.md`) documentation.
+- **Fallback Support**: Added a fallback mechanism for browsers that do not support the Web Animations API.
+
+### Fixed
+
+- **Memory Leak**: Improved `IntersectionObserver` cleanup by using `disconnect()` instead of `unobserve()` in key areas.
+- **Stagger Bug**: Fixed an issue where `stagger` animation indices were incorrectly calculated when DOM elements were added dynamically.
+- **Type Safety**: Improved TypeScript definitions for better developer experience.
+
+### Changed
+
+- Updated `AnimateOptions` and `ScrollAnimateConfig` to include `once` and `offset`.
+- Refactored `IntersectionObserver` logic to handle offsets via `rootMargin`.
+
+## [1.1.0] - 2025-03-25
+
+### Added
+
+- **Multiple Animations**: Support for applying multiple animation presets simultaneously (e.g., `["fade-in-up", "zoom-in"]`).
+- **Parallax Effect**: New `parallax` option for creating scroll-driven parallax effects (`x`, `y`, `rotate`, `scale`, `speed`).
+- **Scroll Progress Listener**: New `onProgress` callback that provides real-time scroll progress (0 to 1) for an element.
+- **New Animation Presets**: Added `skew-in`, `scale-x`, `scale-y`.
+- **Threshold Array Support**: `threshold` option now accepts an array of numbers for more granular progress tracking.
+- **Improved React Hooks**: `useScrollAnimate` and `useScrollStagger` now fully support `parallax` and `onProgress`.
+- **Improved Vue Composables**: `useScrollAnimate` now fully supports `parallax` and `onProgress`.
+
+## [1.0.0] - 2025-03-25
+
+### Added
+
+- Initial release of `use-scroll-animate`.
+- 16 built-in animation presets: `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`.
+- Core `ScrollAnimate` singleton with `init()`, `observe()`, `unobserve()`, `animate()`, `destroy()`, `refresh()`, and `configure()` methods.
+- HTML `data-sa` attribute API for zero-JS usage.
+- React integration via `createReactHooks()` factory, providing `useScrollAnimate` and `useScrollStagger` hooks.
+- Vue 3 integration via `createVueComposables()` factory, providing `useScrollAnimate` composable.
+- Custom animation support via keyframe objects.
+- `spring` easing preset (`cubic-bezier(0.34, 1.56, 0.64, 1)`).
+- Stagger animation support for sibling elements.
+- `onStart`, `onComplete`, `onEnter`, `onLeave` lifecycle callbacks.
+- Full TypeScript support with comprehensive type definitions.
+- Automatic `prefers-reduced-motion` detection and respect.
+- Zero dependencies.
+- ~2.9KB gzipped UMD bundle.

package/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to use-scroll-animate
+
+First off, thank you for considering contributing to `use-scroll-animate`! It's people like you that make the open-source community such a great place to learn, inspire, and create.
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our Code of Conduct. Please treat everyone with respect and kindness.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check the issue tracker as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+
+* Use a clear and descriptive title for the issue to identify the problem.
+* Describe the exact steps which reproduce the problem in as many details as possible.
+* Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples.
+* Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
+* Explain which behavior you expected to see instead and why.
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When you are creating an enhancement suggestion, please include:
+
+* Use a clear and descriptive title for the issue to identify the suggestion.
+* Provide a step-by-step description of the suggested enhancement in as many details as possible.
+* Provide specific examples to demonstrate the steps.
+* Describe the current behavior and explain which behavior you expected to see instead and why.
+* Explain why this enhancement would be useful to most users.
+
+### Pull Requests
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code lints.
+6. Issue that pull request!
+
+## Development Setup
+
+1. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/use-scroll-animate.git
+   cd use-scroll-animate
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Start the development build watcher:
+   ```bash
+   npm run dev
+   ```
+
+4. Build the project:
+   ```bash
+   npm run build
+   ```
+
+## Commit Messages
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. Please ensure your commit messages adhere to this format:
+
+* `feat:` A new feature
+* `fix:` A bug fix
+* `docs:` Documentation only changes
+* `style:` Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+* `refactor:` A code change that neither fixes a bug nor adds a feature
+* `perf:` A code change that improves performance
+* `test:` Adding missing tests or correcting existing tests
+* `chore:` Changes to the build process or auxiliary tools and libraries such as documentation generation
+
+Thank you for your contribution!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+<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.

package/README_ja.md

@@ -0,0 +1,69 @@
+<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) ファイルを参照してください。

package/README_zh.md

@@ -0,0 +1,69 @@
+<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) 文件。