react-animate-z 2.3.0 → 3.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Delpi.Kye
+Copyright (c) 2026 Delpi.Kye
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,50 +1,43 @@
-# 📦 react-animate-z
 
-<div align="center">
-  <b>✨ Simple React animation components built with styled-components</b>.
-  <br />
-  <br />
-  <a href="https://www.npmjs.com/package/react-animate-z">react-animate-z</a>
-  <br />
-  <br />
-  <b><a href="https://codesandbox.io/p/devbox/lively-night-lrjs4s">LIVE EXAMPLE</a></b>
-</div>
+# 🎞️ react-animate-z
 
-<br />
+[![NPM](https://img.shields.io/npm/v/react-animate-z.svg)](https://www.npmjs.com/package/react-animate-z) ![Downloads](https://img.shields.io/npm/dt/react-animate-z.svg)
 
-[![NPM](https://img.shields.io/npm/v/react-animate-z.svg)](https://www.npmjs.com/package/react-animate-z)
-[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
-![Downloads](https://img.shields.io/npm/dt/react-animate-z.svg)
+<a href="https://codesandbox.io/p/devbox/lively-night-lrjs4s" target="_blank">LIVE EXAMPLE</a>
 
-A React + styled-components based animation library with more than
-**180+ pre-built animations**.
 
-## 🚀 Features
+A lightweight, UX-first animation library for React.
 
-✅ Easy-to-use animation wrapper for any element
+**react-animate-z** provides a clean imperative + declarative API to orchestrate animations
 
-✅ Fully typed with TypeScript
+---
+
+## ✨ Why react-animate-z
 
-✅ Customizable duration, delay, iteration, timing, direction, fillMode
+- 🚀 180+ prebuilt animations
+- 🧠 Semantic UX states (loading / success / error)
+- ⛓️ Timeline API (sequence, parallel, wait)
+- 🎯 Ref-based animation (no wrapper required)
+- 🎲 Random & playful animation hooks
+- ♿ Reduced-motion safe
+- 🧩 Fully typed with TypeScript
 
-✅ Typewriter-style text animation with blinking cursor
+---
 
-## 🚀 Installation
+## 📦 Installation
 
 ```bash
 npm install react-animate-z
-
 # or
-
 yarn add react-animate-z
 ```
 
-## 🎬 Usage
+---
+
+## 🚀 Basic Usage (Declarative)
 
 ```tsx
-import React from "react";
 import Animate from "react-animate-z";
-import { animGroups, animNames } from "react-animate-z";
 
 export default function App() {
   return (
@@ -55,342 +48,259 @@ export default function App() {
 }
 ```
 
+## 🎛️ Animation Catalog
+```ts
+import { animNames, animGroups } from "react-animate-z";
+
+console.log(animNames);   // all animation names
+console.log(animGroups); // grouped by category
+
+```
+
+---
+
+## 🔧 `Animate` Props
+
+| Prop        | Type                   | Default     | Description         |
+|-------------|------------------------|-------------|---------------------|
+| `type`      | `AnimateType`          | `blurIn`    | Animation name      |
+| `duration`  | `string \| number`     | preset map  | `'1s'` or `1000`    |
+| `timing`    | `TimingKey`            | `ease`      | CSS timing function |
+| `delay`     | `string \| number`     | `0s`        | Delay before start  |
+| `iteration` | `number \| "infinite"` | `1`         | Repeat count        |
+| `direction` | `string`               | `normal`    | Animation direction |
+| `fillMode`  | `string`               | `forwards`  | CSS fill-mode       |
+| `tagName`   | `string`               | `div`       | Rendered HTML tag   |
+
+---
+
+## 🎯 Ref-based Animation (Imperative)
+
 ```tsx
-// 1. Get all animation names
-import { animGroups, animNames } from "react-animate-z";
+import { useAnimate } from "react-animate-z";
 
-// 2. Get animation groups
-console.log(animNames);
-console.log(animGroups);
+function Box() {
+  const { ref, play } = useAnimate<HTMLDivElement>();
+
+  return (
+    <div ref={ref} onClick={() => play("pulse")}>
+      Click me
+    </div>
+  );
+}
 ```
 
-## 🔧 Props
+---
+
+## ⛓️ Timeline API
+
+Compose animations as clear motion flows, not nested callbacks.
+
+```tsx
+import { useAnimate } from "react-animate-z";
+import { useEffect } from "react";
+
+function Example() {
+  const { ref, sequence } = useAnimate<HTMLDivElement>();
+
+  useEffect(() => {
+    sequence()
+      .animate("fadeInFromBottom")
+      .wait(300)
+      .animate("pulse");
+  }, []);
+
+  return <div ref={ref}>Hello</div>;
+}
+```
+
+---
+
+## 🧠 Semantic Recipes (State-driven UX)
+
+```tsx
+import { useRecipe } from "react-animate-z";
+
+function SaveButton() {
+  const anim = useRecipe();
+
+  return (
+    <button
+      ref={anim.ref}
+      onClick={async () => {
+        anim.loading();
+        await save();
+        anim.success();
+      }}
+    >
+      Save
+    </button>
+  );
+}
+```
+
+Available presets:
+- loading()
+- success()
+- error()
+- idle()
+
+---
+
+## 🔁 <AnimateOn /> — Trigger by State Change
 
-Prop Type Default Description
+```ts
+import { AnimateOn } from "react-animate-z";
 
-| Prop        | Type                   | Default                      | Description                                                                              |
-| ----------- | ---------------------- | -----------------------------| ---------------------------------------------------------------------------------------- |
-| `type`      | `AnimateType`          | `'blurIn'`                   | Animation name (ví dụ: `'blurIn'`, `'bounce'`, `'fadeOut'`, ...)                         |
-| `duration`  | `string \| number`     | `'defaultDurationMap'`       | Duration of the animation (can be in seconds `'1s'` or milliseconds `1000`)              |
-| `timing`    | `TimingKey`            | `'ease'`                     | Timing function (e.g., `'ease'`, `'linear'`, `'ease-in'`, `'ease-out'`)                  |
-| `delay`     | `string \| number`     | `'0s'`                       | Delay before the animation starts                                                        |
-| `iteration` | `number \| "infinite"` | `1`                          | Repeat count of the animation                                                            |
-| `direction` | `string`               | `'normal'`                   | Animation direction (`'normal'`, `'alternate'`, `'reverse'`, etc.)                       |
-| `fillMode`  | `string`               | `'forwards'`                 | How styles are applied after animation (`'forwards'`, `'backwards'`, `'both'`, `'none'`) |
-| `tagName`   | `string`               | `'div'`                      | Custom HTML tag to render                                                                |
+<AnimateOn when={status} value="success" anim={["fadeIn", "pulse"]}>
+  <div>Done!</div>
+</AnimateOn>
+
+```
 
 ---
 
-#### Chain Animation
+## 🧩 AnimateGroup – Staggered Children
+
+```tsx
+import { AnimateGroup } from "react-animate-z";
+
+<AnimateGroup type="fadeInUp" stagger={160}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</AnimateGroup>
+
+```
+
+---
 
-An string-arry of animation names is used to wrap the animations you want to chain.
+## ⌨️ Typing Animation
 
-```js
-import React, { useState } from "react";
+```tsx
 import { AnimateTyping } from "react-animate-z";
 
-const AnimationsForChaining = [
-  "swing",
-  "flipSlowDown",
-  "fadeOutToBottom",
+<AnimateTyping
+  dataText={[
+    "Hello World",
+    "React Animate Z",
+    "Built for UX",
+  ]}
+/>
+```
+
+---
+
+## 🎲 Random & Playful Motion
+
+```ts
+import { useRandomAnimateNoRepeat } from "react-animate-z";
+
+const play = useRandomAnimateNoRepeat(run, [
+  "shakeMix",
+  "pulse",
+  "flash",
   "jelly",
-];
+]);
+
+<button onClick={() => play()}>Surprise me</button>
+
+```
+
+---
 
-const AnimationChain: React.FC = () => {
-  // const [animationIndex, setAnimationIndex] = useState(0);
-  // const [animationType, setAnimationType] = useState(AnimationsForChaining[0]);
+## 🪄 AnimatePresence (Enter / Exit)
+
+`AnimatePresence` animates mount / unmount using enter / exit animation pairs,
+similar to Framer Motion but lighter, CSS-based, and no styled-components dependency.
+
+#### ✅ Use case
+- Modal
+- Drawer / Sidebar
+- Toast / Snackbar
+- Tooltip
+- Dropdown
+- Conditional UI
+---
 
-  // const handleChainAnimation = () => {
-  //   const nextIndex = (animationIndex + 1) % AnimationsForChaining.length;
-  //   setAnimationIndex(nextIndex);
-  //   setAnimationType(AnimationsForChaining[nextIndex]);
-  // };
+#### 📌 Basic usage
 
+```tsx
+import { AnimatePresence } from "react-animate-z";
+
+function Example({ open }: { open: boolean }) {
   return (
-    <>
-      <AnimateTyping
-        heading="Hello,"
-        dataText={["I am Delpi", "I build animations", "I love coding!"]}
-        cursorColor="red"
-      />
-
-      <AnimateTyping dataText="Only once" />
-
-      <AnimateTyping
-        heading="Fast typing:"
-        dataText={["speed x2", "super fast!"]}
-        typingSpeed={50}
-        deletingSpeed={20}
-        pauseTime={1000}
-      />
-    </>
+    <AnimatePresence
+      show={open}
+      enter="fadeIn"
+      exit="fadeOut"
+      duration={300}
+    >
+      <div>Hello</div>
+    </AnimatePresence>
   );
-};
+}
+
+```
+---
 
-export default AnimationChain;
+#### 🔥 Example: Modal
+
+```tsx
+<AnimatePresence
+  show={open}
+  enter="zoomIn"
+  exit="fadeOut"
+  duration={250}
+>
+  <div className="modal" />
+</AnimatePresence>
 ```
 
 ---
 
-## 🎨 Available Animations
-
-#### 🎾 Bounce
-
-- bounce
-- bounceIn
-- bounceOut
-- bounceElastic
-- bounceSmall
-- bounceRotate
-- bounceJelly
-
-#### ✨ Text / Glow Effects
-
-- effect3D
-- neonGlow
-- retro3D
-- emboss
-- fireGlow
-- iceGlow
-- shine
-
-#### 🌫 Blur
-
-- blurIn
-- blurInZoom
-- blurInScale
-- blurInUp
-- blurInRotate
-- blurOut
-- blurOutZoom
-- blurOutScale
-- blurOutDown
-- blurOutRotate
-
-#### ⚡ Flash
-
-- flash
-- flashIrregular
-- flashFast
-- flashSlow
-- flashPulse
-
-#### 🎈 Float
-
-- float
-- floatSway
-- floatHorizontal
-- floatCircular
-- floatWiggle
-
-#### 💡 Glow
-
-- glow
-- glowTextFlicker
-- glowRainbow
-- glowBreathing
-- glowGlitch
-
-#### 🍮 Jelly
-
-- jelly
-- jellyX
-- jellyY
-- jellyIn
-- jellyOut
-
-#### 🌑 Shadow / Spin / Swing / Orbit
-
-- shadow
-- shadowText
-- shadowPulse
-- shadowNeon
-- spin
-- spin3D
-- spinX
-- spinBounce
-- swing
-- swingPivot
-- swingX
-- swingY
-- orbit
-- orbitEllipse
-
-#### 💓 Pulse
-
-- pulse
-- pulseInOut
-- pulseFade
-- pulseFast
-- pulseColor
-
-#### 🌫 Fade
-
-- fadeIn
-- fadeOut
-- fadeInFromLeft
-- fadeInFromRight
-- fadeInFromTop
-- fadeInFromBottom
-- fadeOutToLeft
-- fadeOutToRight
-- fadeOutToTop
-- fadeOutToBottom
-- fadeInZoom
-- fadeOutZoom
-- fadeInRotate
-- fadeOutRotate
-- fadeInSkew
-- fadeOutSkew
-- fadeInFlipX
-- fadeOutFlipX
-- fadeInFlipY
-- fadeOutFlipY
-- fadeInPerspective
-- fadeOutPerspective
-
-#### 🤯 Squeeze / Shake
-
-- squeezeMix
-- squeezeHorizontal
-- squeezeVertical
-- squeezeDiagonal
-- squeezePulse
-- squeezeBounce
-- squeezeElastic
-- squeezeFlash
-- shakeMix
-- shakeHorizontal
-- shakeVertical
-- shakeDiagonal
-- shakeQuick
-- shakeRotate
-- shakeSkew
-- shakeBounce
-- shakeCrazy
-- squeezeThenShakeX
-- shakeYThenSqueeze
-- squeezeShakeCrazy
-
-#### 📥 Slide
-
-- slideInFromLeft
-- slideInFromRight
-- slideOutToLeft
-- slideOutToRight
-- slideInFromTop
-- slideInFromBottom
-- slideOutToTop
-- slideOutToBottom
-- slideInFromLeftOvershoot
-- slideInFromRightOvershoot
-- slideOutToLeftOvershoot
-- slideOutToRightOvershoot
-- slideInFromTopOvershoot
-- slideInFromBottomOvershoot
-- slideOutToTopOvershoot
-- slideOutToBottomOvershoot
-
-#### 🔄 Flip
-
-- flip
-- flipIn
-- flipOut
-- flipSlowDown
-- flipToLeft
-- flipToRight
-- flipFromTop
-- flipToTop
-- flipToBottom
-- flipFromBottom
-- flipFromLeftToCenter
-- flipFromRightToCenter
-- flipRich
-- flipToTopRich
-- flipToBottomRich
-- flipToTopLeftRich
-- flipToRightRich
-- flipFromTopRich
-- flipFromBottomRich
-- flipFromLeftToCenterRich
-- flipFromRightToCenterRich
-
-#### 📂 Fold / Unfold
-
-- fold
-- foldDeep
-- unfold
-- unfoldDeep
-
-#### 🪝 Hang On
-
-- hangOnLeft
-- hangOnRight
-- hangOnTop
-- hangOnBottom
-- hangOnLeftSwing
-- hangOnRightSwing
-- hangOnTopSwing
-- hangOnBottomSwing
-- hangOnOscillate
-- hangOnDrop
-
-#### 🔍 Zoom
-
-- zoomIn
-- zoomOut
-- zoomInFromLeft
-- zoomInFromRight
-- zoomInFromTop
-- zoomInFromBottom
-- zoomOutToLeft
-- zoomOutToRight
-- zoomOutToTop
-- zoomOutToBottom
-
-#### 🌀 Rotate
-
-- rotateCW
-- rotateACW
-- rotateSlowDown
-- rotateX
-- rotateY
-- rotateFromLeft
-- rotateFromRight
-- rotateToLeft
-- rotateToRight
-- rotateFromTop
-- rotateFromBottom
-- rotateToTop
-- rotateToBottom
-
-#### 🎉 Fun / Attention
-
-- heartBeat
-- tada
-- hinge
-- lightSpeedInLeft
-- lightSpeedOutRight
-- popIn
-- popOut
-- popBounceIn
-- popBounceOut
-- popUpIn
-- popUpOut
-- popRotateIn
-- popRotateOut
-- popBlurIn
-- popBlurOut
-- popLeftIn
-- popLeftOut
-- popRightIn
-- popRightOut
-- rubberBand
-- jello
-- wobble
-- rollIn
-- jackInTheBox
+
+#### 🧠 Behavior timeline
+
+```bash
+show = false
+  └─ nothing rendered
+
+show = true
+  └─ mount
+      └─ enter animation
+
+show = false
+  └─ exit animation
+      └─ wait(duration)
+          └─ unmount
+```
+
+- Declarative intent, not keyframes
+- Timeline-based composition
+- Ref-first, framework-agnostic core
+- Safe defaults for accessibility
+
+---
+
+## 🧩 Additional APIs
+
+#### Components
+- AnimateHost: Low-level animation context host, used for coordinating multiple animated elements.
+- WrapperAnimate: Conditional animation wrapper without breaking DOM structure.
+- TypingText: Lightweight typing animation for inline text (simpler than AnimateTyping).
+
+#### Hooks
+- useAnimateController: Imperative control over animation lifecycle (play, stop, reset).
+- useAnimateSequence: Timeline logic as a hook for reusable animation flows.
+- useRandomAnimateNoRepeat: Random animation helper with no immediate repetition.
+- useRecipe: Semantic, state-driven animation (loading, success, error).
+
+> These APIs are intended for advanced or compositional use cases.
+> Most applications only need <Animate /> and useAnimate().
+
+---
 
 ## 📜 License
 
-MIT © Delpi
+MIT