use-scroll-animate 1.2.0 → 1.5.0

package/dist/types/types.d.ts

@@ -1,123 +1,153 @@
-/**
- * use-scroll-animate - Core Type Definitions
- * A lightweight, high-performance scroll animation library
- */
-/** Built-in animation presets */
-export 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';
-/** Easing function types */
-export type EasingType = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | string;
-/** Keyframe definition for custom animations */
-export interface AnimationKeyframe {
-    [property: string]: string | number;
-}
-/** Custom animation definition */
-export interface CustomAnimation {
-    from: AnimationKeyframe;
-    to: AnimationKeyframe;
-}
-/** Parallax configuration */
-export 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 */
-export 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;
-}
-/** Global configuration for ScrollAnimate instance */
-export 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;
-}
-/** Registered element entry */
-export interface AnimatedElement {
-    element: Element;
-    options: Required<AnimateOptions>;
-    observer: IntersectionObserver;
-    animated: boolean;
-    progressObserver?: IntersectionObserver;
-}
-/** ScrollAnimate public API */
-export 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 Type Definitions
+ * A lightweight, high-performance scroll animation library
+ */
+/** Built-in animation presets */
+export 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.
+ */
+export type ProgressMode = 'ratio' | 'scroll';
+/** Easing function types */
+export 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 */
+export interface AnimationKeyframe {
+    [property: string]: string | number;
+}
+/** Custom animation definition */
+export interface CustomAnimation {
+    from: AnimationKeyframe;
+    to: AnimationKeyframe;
+}
+/** Parallax configuration */
+export 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 */
+export 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;
+    /**
+     * 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 */
+export 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 */
+export interface AnimatedElement {
+    element: Element;
+    options: Required<AnimateOptions>;
+    observer: IntersectionObserver;
+    animated: boolean;
+    progressObserver?: IntersectionObserver;
+}
+/** ScrollAnimate public API */
+export 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;
+    /**
+     * 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) */
+    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;
+}

package/dist/types/vue.d.ts

@@ -1,18 +1,28 @@
-/**
- * use-scroll-animate - Vue 3 Integration
- * Provides useScrollAnimate composable for Vue 3 applications.
- */
-import type { AnimateOptions } from './types';
-export 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;
-        };
-    };
-};
+/**
+ * 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.
+ */
+import type { AnimateOptions } from './types';
+import { type StaggerOptions } from './stagger';
+export 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;
+        };
+    };
+};

package/package.json

@@ -1,35 +1,81 @@
-{
-  "name": "use-scroll-animate",
-  "version": "1.2.0",
-  "description": "A lightweight, high-performance, dependency-free scroll animation library for modern web.",
-  "main": "dist/index.js",
-  "module": "dist/index.esm.js",
-  "browser": "dist/index.umd.js",
-  "types": "dist/types/index.d.ts",
-  "scripts": {
-    "build": "rollup -c",
-    "dev": "rollup -c -w",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [
-    "scroll",
-    "animation",
-    "intersection-observer",
-    "lightweight",
-    "vanilla-js",
-    "typescript",
-    "frontend",
-    "ui"
-  ],
-  "author": "",
-  "license": "MIT",
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^29.0.2",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-terser": "^1.0.0",
-    "@rollup/plugin-typescript": "^12.3.0",
-    "rollup": "^4.60.0",
-    "tslib": "^2.8.1",
-    "typescript": "^6.0.2"
-  }
-}
+{
+  "name": "use-scroll-animate",
+  "version": "1.5.0",
+  "description": "A lightweight, high-performance, dependency-free scroll animation library for modern web.",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "unpkg": "dist/index.umd.js",
+  "jsdelivr": "dist/index.umd.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README_zh.md",
+    "README_ja.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "typecheck": "tsc --noEmit -p .",
+    "test": "vitest run",
+    "check:exports": "node scripts/check-exports.mjs",
+    "lint:package": "publint && attw --pack . --profile node16",
+    "size": "node scripts/size.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run check:exports"
+  },
+  "keywords": [
+    "scroll",
+    "animation",
+    "intersection-observer",
+    "lightweight",
+    "vanilla-js",
+    "typescript",
+    "frontend",
+    "ui",
+    "scroll-progress",
+    "stagger",
+    "timeline"
+  ],
+  "author": "HarrisonCN",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HarrisonCN/use-scroll-animate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HarrisonCN/use-scroll-animate/issues"
+  },
+  "homepage": "https://github.com/HarrisonCN/use-scroll-animate#readme",
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "jsdom": "^26.1.0",
+    "publint": "^0.3.25",
+    "rollup": "^4.60.0",
+    "rollup-plugin-dts": "^6.5.1",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.2",
+    "vitest": "^3.2.7"
+  }
+}

package/CONTRIBUTING.md

@@ -1,76 +0,0 @@
-# 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/examples/react/App.tsx

@@ -1,61 +0,0 @@
-/**
- * use-scroll-animate — React Example
- *
- * This example demonstrates how to use the useScrollAnimate and useScrollStagger
- * hooks in a React application.
- */
-
-import React from 'react';
-import { createReactHooks } from 'use-scroll-animate';
-
-const { useScrollAnimate, useScrollStagger } = createReactHooks(React);
-
-const features = [
-  { title: 'Zero Dependencies', desc: 'No lodash, no jQuery, no bloat.' },
-  { title: 'TypeScript First', desc: 'Full type safety and IntelliSense.' },
-  { title: 'Framework Agnostic', desc: 'Works with React, Vue, Svelte, and more.' },
-  { title: 'Accessible', desc: 'Respects prefers-reduced-motion.' },
-];
-
-export default function App() {
-  const heroTitleRef = useScrollAnimate({ animation: 'fade-in-down', duration: 1000 });
-  const heroSubRef = useScrollAnimate({ animation: 'fade-in-up', delay: 300 });
-  const featuresRef = useScrollStagger({ animation: 'fade-in-up', stagger: 120 });
-  const ctaRef = useScrollAnimate({ animation: 'zoom-in', easing: 'spring' });
-
-  return (
-    <main style={{ fontFamily: 'system-ui, sans-serif', background: '#0a0a0a', color: '#fff', minHeight: '100vh' }}>
-      {/* Hero Section */}
-      <section style={{ height: '100vh', display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', textAlign: 'center', padding: '2rem' }}>
-        <h1 ref={heroTitleRef} style={{ fontSize: 'clamp(2rem, 6vw, 5rem)', fontWeight: 800 }}>
-          use-scroll-animate
-        </h1>
-        <p ref={heroSubRef} style={{ fontSize: '1.2rem', color: '#aaa', marginTop: '1rem' }}>
-          Lightweight. Dependency-free. Blazing fast.
-        </p>
-      </section>
-
-      {/* Features Section */}
-      <section style={{ maxWidth: 900, margin: '0 auto', padding: '6rem 2rem' }}>
-        <ul ref={featuresRef} style={{ listStyle: 'none', padding: 0, display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', gap: '1.5rem' }}>
-          {features.map((f) => (
-            <li key={f.title} style={{ background: '#1a1a1a', border: '1px solid #333', borderRadius: 12, padding: '1.5rem' }}>
-              <h3 style={{ marginBottom: '0.5rem' }}>{f.title}</h3>
-              <p style={{ color: '#aaa', lineHeight: 1.6 }}>{f.desc}</p>
-            </li>
-          ))}
-        </ul>
-      </section>
-
-      {/* CTA Section */}
-      <section style={{ textAlign: 'center', padding: '6rem 2rem' }}>
-        <div ref={ctaRef} style={{ display: 'inline-block', background: 'linear-gradient(135deg, #6366f1, #8b5cf6)', borderRadius: 16, padding: '3rem 4rem' }}>
-          <h2 style={{ fontSize: '2rem', marginBottom: '1rem' }}>Get Started Today</h2>
-          <code style={{ background: 'rgba(0,0,0,0.3)', padding: '0.5rem 1rem', borderRadius: 8, fontSize: '1rem' }}>
-            npm install use-scroll-animate
-          </code>
-        </div>
-      </section>
-    </main>
-  );
-}