react-ui-animate 5.2.0 → 5.3.0-next.1

package/README.md

@@ -4,9 +4,7 @@
 
 > Create smooth animations and interactive gestures in React applications effortlessly.
 
-### Install
-
-You can install `react-ui-animate` via `npm` or `yarn`:
+## Installation
 
 ```sh
 npm install react-ui-animate
@@ -18,49 +16,157 @@ yarn add react-ui-animate
 
 ---
 
-## Getting Started
+## Quick Start
+
+The `react-ui-animate` library provides a declarative way to add animations and gestures to your React components. Here's a simple example:
+
+```tsx
+import { animate, withSpring } from 'react-ui-animate';
+
+function App() {
+  return (
+    <animate.div
+      style={{
+        width: 100,
+        height: 100,
+        backgroundColor: 'blue',
+        scale: 0.5,
+        opacity: 0,
+      }}
+      animate={{
+        scale: withSpring(1),
+        opacity: withSpring(1),
+      }}
+    />
+  );
+}
+```
 
-The `react-ui-animate` library provides a straightforward way to add animations and gestures to your React components. Below are some common use cases.
+---
 
-### 1. useValue
+## Core Concepts
 
-Use `useValue` to initialize and update an animated value.
+### 1. Animate Component
+
+The `animate` object provides animated versions of all HTML elements. Use `animate.div`, `animate.button`, `animate.span`, etc., just like regular React elements.
+
+#### Basic Animation
+
+Use the `animate` prop to define animations that run when the component mounts or when the prop changes:
 
 ```tsx
-import React from 'react';
-import {
-  animate,
-  useValue,
-  withSpring,
-  withTiming,
-  withSequence,
-} from 'react-ui-animate';
+import { animate, withSpring, withTiming } from 'react-ui-animate';
+
+<animate.div
+  style={{
+    width: 100,
+    height: 100,
+    backgroundColor: 'red',
+    translateX: 0,
+  }}
+  animate={{
+    translateX: withSpring(200),
+    backgroundColor: withTiming('blue', { duration: 500 }),
+  }}
+/>
+```
+
+#### Exit Animations with Presence
 
-export const UseValue: React.FC = () => {
+Wrap components in `Presence` to enable exit animations when they're removed:
+
+```tsx
+import { Presence, animate, withSpring, withTiming } from 'react-ui-animate';
+
+function Modal({ isOpen, onClose }) {
+  return (
+    <Presence>
+      {isOpen && (
+        <animate.div
+          key="modal"
+          style={{
+            opacity: 0,
+            scale: 0.8,
+          }}
+          animate={{
+            opacity: withTiming(1),
+            scale: withSpring(1),
+          }}
+          exit={{
+            opacity: withTiming(0),
+            scale: withSpring(0.8),
+          }}
+        >
+          Modal Content
+        </animate.div>
+      )}
+    </Presence>
+  );
+}
+```
+
+#### State-Based Animations
+
+React to user interactions with `hover`, `press`, `focus`, and `view` props:
+
+```tsx
+<animate.button
+  style={{
+    scale: 1,
+    backgroundColor: '#3399ff',
+  }}
+  hover={{
+    scale: withSpring(1.05),
+    backgroundColor: withTiming('#4da6ff'),
+  }}
+  press={{
+    scale: withSpring(0.95),
+  }}
+>
+  Hover Me
+</animate.button>
+```
+
+**View Animations** - Animate when elements enter the viewport:
+
+```tsx
+<animate.div
+  style={{
+    opacity: 0,
+    translateY: 50,
+  }}
+  view={{
+    opacity: withTiming(1),
+    translateY: withSpring(0),
+  }}
+  viewOptions={{ threshold: 0.3, once: true }}
+>
+  This animates when scrolled into view
+</animate.div>
+```
+
+### 2. useValue Hook
+
+Create and control animated values programmatically:
+
+```tsx
+import { useValue, animate, withSpring, withSequence, withTiming } from 'react-ui-animate';
+
+function AnimatedBox() {
   const [width, setWidth] = useValue(100);
+  const [x, setX] = useValue(0);
 
   return (
     <>
-      <button
-        onClick={() => {
-          setWidth(withSequence([withTiming(100), withSpring(0)]));
-        }}
-      >
-        SEQUENCE (100 → 0)
-      </button>
-      <button
-        onClick={() => {
-          setWidth(withSpring(200));
-        }}
-      >
-        SPRING (→ 200)
+      <button onClick={() => setWidth(withSpring(200))}>
+        Expand
       </button>
-      <button
-        onClick={() => {
-          setWidth(400);
-        }}
-      >
-        IMMEDIATE (→ 400)
+      <button onClick={() => setX(withSequence([
+        withTiming(100, { duration: 300 }),
+        withTiming(200, { duration: 300 }),
+        withTiming(0, { duration: 300 }),
+      ]))}>
+        Sequence
       </button>
 
       <animate.div
@@ -68,119 +174,235 @@ export const UseValue: React.FC = () => {
           width,
           height: 100,
           backgroundColor: 'red',
-          left: 0,
-          top: 0,
+          translateX: x,
         }}
       />
     </>
   );
-};
+}
 ```
 
-### 2. useMount
+**Interpolation** - Map values to different ranges:
 
-Use `useMount` to animate component mount and unmount transitions.
+```tsx
+const [progress, setProgress] = useValue(0);
+
+<animate.div
+  style={{
+    backgroundColor: progress.to([0, 1], ['red', 'blue']),
+    translateX: progress.to([0, 1], [0, 500]),
+  }}
+/>
+```
+
+**Controls** - Control animations programmatically:
+
+```tsx
+const [value, setValue, controls] = useValue(0);
+
+// Start animation
+setValue(withSpring(100));
+
+// Control playback
+controls.pause();
+controls.resume();
+controls.cancel();
+controls.reset();
+```
+
+### 3. Animation Descriptors
+
+Animation descriptors define how animations behave. They can be used with both `animate` components and `useValue`.
+
+#### withSpring
+
+Creates physics-based spring animations:
+
+```tsx
+withSpring(100, {
+  stiffness: 100,  // Spring stiffness (default: 100)
+  damping: 15,    // Spring damping (default: 15)
+  mass: 1,        // Spring mass (default: 1)
+})
+```
+
+#### withTiming
+
+Creates time-based animations with easing:
+
+```tsx
+withTiming(100, {
+  duration: 500,           // Duration in milliseconds
+  easing: Easing.easeInOut, // Easing function
+})
+```
+
+#### withDecay
+
+Creates momentum-based decay animations:
+
+```tsx
+withDecay({
+  velocity: 100,  // Initial velocity
+  clamp: [0, 500], // Optional: clamp values
+})
+```
+
+#### withSequence
+
+Runs animations one after another:
+
+```tsx
+withSequence([
+  withTiming(100, { duration: 300 }),
+  withTiming(200, { duration: 300 }),
+  withSpring(0, { stiffness: 200 }),
+])
+```
+
+#### withLoop
+
+Repeats animations:
+
+```tsx
+withLoop(
+  withSequence([
+    withTiming(90, { duration: 500 }),
+    withTiming(180, { duration: 500 }),
+    withTiming(360, { duration: 500 }),
+  ]),
+  3  // Number of iterations (0 = infinite)
+)
+```
+
+#### withDelay
+
+Adds delay to animations (typically used inside `withSequence`):
+
+```tsx
+withSequence([
+  withDelay(500),
+  withTiming(1, { duration: 500 }),
+])
+```
+
+### 4. Animation Recipes
+
+Pre-built animation recipes for common use cases:
 
 ```tsx
-import React from 'react';
 import {
   animate,
-  useMount,
-  withDecay,
-  withSequence,
-  withSpring,
-  withTiming,
+  fadeIn,
+  slideInUp,
+  scaleIn,
+  bounceIn,
+  hoverScale,
+  pressScale,
 } from 'react-ui-animate';
 
-export const UseMount: React.FC = () => {
-  const [open, setOpen] = React.useState(true);
-  const mounted = useMount(open, { from: 0, enter: 1, exit: 0 });
+// Enter animations
+<animate.div animate={fadeIn}>Fades in</animate.div>
+<animate.div animate={slideInUp}>Slides up</animate.div>
+<animate.div animate={scaleIn}>Scales in</animate.div>
+<animate.div animate={bounceIn}>Bounces in</animate.div>
 
-  return (
-    <>
-      {mounted(
-        (animation, isMounted) =>
-          isMounted && (
-            <animate.div
-              style={{
-                width: 100,
-                height: 100,
-                backgroundColor: 'teal',
-                opacity: animation,
-              }}
-            />
-          )
-      )}
+// State animations
+<animate.button hover={hoverScale} press={pressScale}>
+  Interactive Button
+</animate.button>
 
-      <button onClick={() => setOpen((prev) => !prev)}>ANIMATE ME</button>
-    </>
-  );
-};
+// Exit animations
+<animate.div exit={exitFade}>Fades out</animate.div>
 ```
 
-### 3. Interpolation
+**Available Recipes:**
 
-Interpolate values for complex mappings like color transitions or movement.
+- **Fade**: `fadeIn`, `fadeOut`, `fadeInUp`, `fadeInDown`, `fadeInLeft`, `fadeInRight`
+- **Slide**: `slideInUp`, `slideInDown`, `slideInLeft`, `slideInRight`, `slideOutUp`, `slideOutDown`, `slideOutLeft`, `slideOutRight`
+- **Scale**: `scaleIn`, `scaleOut`, `scaleUp`, `scaleDown`
+- **Bounce**: `bounceIn`, `bounceOut`
+- **Rotate**: `rotateIn`, `rotateOut`, `spin`
+- **Zoom**: `zoomIn`, `zoomOut`
+- **Flip**: `flipX`, `flipY`
+- **Combined**: `slideFadeIn`, `slideFadeOut`, `scaleFadeIn`, `scaleFadeOut`
+- **Hover**: `hoverScale`, `hoverLift`, `hoverGlow`
+- **Press**: `pressScale`, `pressDown`
+- **Exit**: `exitFade`, `exitSlideUp`, `exitSlideDown`, `exitScale`
 
-```tsx
-import React, { useLayoutEffect, useState } from 'react';
-import { animate, useValue, withSpring } from 'react-ui-animate';
+### 5. Presence Component
 
-export const Interpolation: React.FC = () => {
-  const [open, setOpen] = useState(false);
-  const [x, setX] = useValue(0);
+`Presence` manages mount and unmount animations for components:
 
-  useLayoutEffect(() => {
-    setX(withSpring(open ? 500 : 0));
-  }, [open, setX]);
+```tsx
+import { Presence, animate, withSpring } from 'react-ui-animate';
 
-  return (
-    <>
-      <animate.div
-        style={{
-          width: 100,
-          height: 100,
-          backgroundColor: x.to([0, 500], ['red', 'blue']),
-          translateX: x,
-        }}
-      />
+function List() {
+  const [items, setItems] = useState(['Item 1', 'Item 2']);
 
-      <button onClick={() => setOpen((p) => !p)}>ANIMATE ME</button>
-    </>
+  return (
+    <Presence mode="sync" onExitComplete={() => console.log('All exited')}>
+      {items.map((item) => (
+        <animate.div
+          key={item}
+          animate={{ opacity: withSpring(1) }}
+          exit={{ opacity: withSpring(0) }}
+        >
+          {item}
+        </animate.div>
+      ))}
+    </Presence>
   );
-};
+}
 ```
 
----
+**Presence Props:**
 
-## API Overview
+- `mode`: `'sync'` (default) | `'wait'` | `'popLayout'`
+  - `sync`: Exiting and entering animate simultaneously
+  - `wait`: Exiting complete before entering start
+  - `popLayout`: Exiting removed from layout immediately
+- `initial`: Skip enter animation on initial mount (default: `true`)
+- `onExitComplete`: Callback when all exits complete
 
-- **`useValue(initial)`**: Initializes an animated value.
-- **`animate`**: JSX wrapper for animatable elements (`animate.div`, `animate.span`, etc.).
-- **Modifiers**: `withSpring`, `withTiming`, `withDecay`, `withSequence` — functions to define animation behavior.
-- **`useMount(state, config)`**: Manages mount/unmount transitions. `config` includes `from`, `enter`, and `exit` values.
+**Presence Hooks:**
+
+```tsx
+import { usePresence, useIsPresent } from 'react-ui-animate';
+
+function AnimatedItem() {
+  const [isPresent, onExitComplete] = usePresence();
+  const isPresent2 = useIsPresent(); // Simple boolean check
+
+  // Use isPresent to conditionally render or animate
+  return isPresent ? <div>Content</div> : null;
+}
+```
 
-## Gestures
+### 6. Gestures
 
-`react-ui-animate` also provides hooks for handling gestures:
+React to user gestures with built-in hooks:
 
-- `useDrag`
-- `useMove`
-- `useScroll`
-- `useWheel`
+#### useDrag
 
-**Example: `useDrag`**
+Handle drag gestures:
 
 ```tsx
-import React from 'react';
 import { useValue, animate, useDrag, withSpring } from 'react-ui-animate';
 
-export const Draggable: React.FC = () => {
+function Draggable() {
   const ref = useRef(null);
-  const [translateX, setTranslateX] = useValue(0);
+  const [x, setX] = useValue(0);
+  const [y, setY] = useValue(0);
 
   useDrag(ref, ({ down, movement }) => {
-    setTranslateX(down ? movement.x : withSpring(0));
+    if (down) {
+      setX(movement.x);
+      setY(movement.y);
+    } else {
+      setX(withSpring(0));
+      setY(withSpring(0));
+    }
   });
 
   return (
@@ -189,18 +411,333 @@ export const Draggable: React.FC = () => {
       style={{
         width: 100,
         height: 100,
-        backgroundColor: '#3399ff',
-        translateX,
+        backgroundColor: 'blue',
+        translateX: x,
+        translateY: y,
       }}
     />
   );
-};
+}
+```
+
+#### useMove
+
+Track pointer movement:
+
+```tsx
+import { useMove } from 'react-ui-animate';
+
+useMove(ref, ({ movement }) => {
+  console.log('Moving:', movement.x, movement.y);
+});
+```
+
+#### useScroll
+
+React to scroll events:
+
+```tsx
+import { useScroll } from 'react-ui-animate';
+
+useScroll(ref, ({ scroll }) => {
+  console.log('Scrolled:', scroll.x, scroll.y);
+});
+```
+
+#### useWheel
+
+Handle wheel events:
+
+```tsx
+import { useWheel } from 'react-ui-animate';
+
+useWheel(ref, ({ delta }) => {
+  console.log('Wheel delta:', delta.x, delta.y);
+});
+```
+
+#### useScrollProgress
+
+Track scroll progress:
+
+```tsx
+import { useScrollProgress } from 'react-ui-animate';
+
+const progress = useScrollProgress(ref, {
+  start: 0,      // Start tracking at 0% scroll
+  end: 100,      // End tracking at 100% scroll
+  axis: 'y',    // 'x' or 'y'
+});
+```
+
+### 7. Utilities
+
+#### makeAnimated
+
+Create custom animated components:
+
+```tsx
+import { makeAnimated } from 'react-ui-animate';
+
+const AnimatedButton = makeAnimated('button');
+const AnimatedSection = makeAnimated('section');
+
+<AnimatedButton animate={{ scale: withSpring(1.1) }}>
+  Custom Button
+</AnimatedButton>
+```
+
+#### to (Interpolation)
+
+Map values between ranges:
+
+```tsx
+import { to } from 'react-ui-animate';
+
+const interpolate = to([0, 100], [0, 500]);
+interpolate(50); // Returns 250
+
+// Color interpolation
+const colorInterpolate = to([0, 1], ['red', 'blue']);
+colorInterpolate(0.5); // Returns interpolated color
+```
+
+#### combine
+
+Combine multiple animated values:
+
+```tsx
+import { combine, useValue } from 'react-ui-animate';
+
+const [x, setX] = useValue(0);
+const [y, setY] = useValue(0);
+const combined = combine(x, y, (x, y) => x + y);
+```
+
+### 8. Additional Hooks
+
+#### useInView
+
+Detect when elements enter the viewport:
+
+```tsx
+import { useInView } from 'react-ui-animate';
+
+const ref = useRef(null);
+const isInView = useInView(ref, {
+  threshold: 0.5,
+  once: true,
+});
+```
+
+#### useOutsideClick
+
+Detect clicks outside an element:
+
+```tsx
+import { useOutsideClick } from 'react-ui-animate';
+
+const ref = useRef(null);
+useOutsideClick(ref, () => {
+  console.log('Clicked outside!');
+});
+```
+
+---
+
+## Complete Examples
+
+### Modal with Exit Animation
+
+```tsx
+import { useState, useRef } from 'react';
+import {
+  Presence,
+  animate,
+  useOutsideClick,
+  withSpring,
+  withTiming,
+} from 'react-ui-animate';
+
+function Modal({ isOpen, onClose }) {
+  const ref = useRef(null);
+  useOutsideClick(ref, onClose);
+
+  return (
+    <Presence>
+      {isOpen && (
+        <>
+          {/* Backdrop */}
+          <animate.div
+            key="backdrop"
+            style={{
+              position: 'fixed',
+              inset: 0,
+              backgroundColor: 'rgba(0,0,0,0)',
+              opacity: 0,
+            }}
+            animate={{
+              backgroundColor: withTiming('rgba(0,0,0,0.5)'),
+              opacity: withTiming(1),
+            }}
+            exit={{
+              backgroundColor: withTiming('rgba(0,0,0,0)'),
+              opacity: withTiming(0),
+            }}
+          />
+
+          {/* Modal */}
+          <animate.div
+            key="modal"
+            ref={ref}
+            style={{
+              position: 'fixed',
+              inset: 0,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              scale: 0.8,
+              opacity: 0,
+            }}
+            animate={{
+              scale: withSpring(1),
+              opacity: withSpring(1),
+            }}
+            exit={{
+              scale: withSpring(0.8),
+              opacity: withSpring(0),
+            }}
+          >
+            <div style={{ backgroundColor: 'white', padding: 20 }}>
+              Modal Content
+            </div>
+          </animate.div>
+        </>
+      )}
+    </Presence>
+  );
+}
+```
+
+### Scroll-Triggered Animations
+
+```tsx
+import { animate, withSpring, withTiming } from 'react-ui-animate';
+
+function FeatureCard({ title, description }) {
+  return (
+    <animate.div
+      style={{
+        opacity: 0,
+        translateY: 50,
+        scale: 0.9,
+      }}
+      view={{
+        opacity: withTiming(1, { duration: 600 }),
+        translateY: withSpring(0),
+        scale: withSpring(1),
+      }}
+      viewOptions={{ threshold: 0.3, once: true }}
+    >
+      <h3>{title}</h3>
+      <p>{description}</p>
+    </animate.div>
+  );
+}
+```
+
+### Interactive Button
+
+```tsx
+import { animate, withSpring, hoverScale, pressScale } from 'react-ui-animate';
+
+<animate.button
+  style={{
+    padding: '12px 24px',
+    backgroundColor: '#3399ff',
+    color: 'white',
+    border: 'none',
+    borderRadius: 8,
+    cursor: 'pointer',
+  }}
+  hover={hoverScale}
+  press={pressScale}
+>
+  Click Me
+</animate.button>
 ```
 
+---
+
+## API Reference
+
+### Animation Descriptors
+
+| Descriptor | Description | Options |
+|------------|-------------|---------|
+| `withSpring(to, options?)` | Physics-based spring | `stiffness`, `damping`, `mass`, `from`, callbacks |
+| `withTiming(to, options?)` | Time-based animation | `duration`, `easing`, `from`, callbacks |
+| `withDecay(options)` | Momentum decay | `velocity`, `clamp`, callbacks |
+| `withSequence(animations)` | Run sequentially | `animations` array, callbacks |
+| `withLoop(animation, iterations)` | Repeat animation | `iterations` (0 = infinite), callbacks |
+| `withDelay(ms)` | Add delay | `delay` in milliseconds |
+
+### Animate Component Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `animate` | `AnimateProp` | Animations on mount/update |
+| `exit` | `AnimateProp` | Animations on unmount (requires `Presence`) |
+| `hover` | `AnimateProp` | Animations on hover |
+| `press` | `AnimateProp` | Animations on press (mousedown/touchstart) |
+| `focus` | `AnimateProp` | Animations on focus |
+| `view` | `AnimateProp` | Animations when entering viewport |
+| `viewOptions` | `UseInViewOptions` | IntersectionObserver options |
+
+### Callbacks
+
+All descriptors support optional callbacks:
+
+```tsx
+withSpring(100, {
+  onStart: () => console.log('Started'),
+  onChange: (value) => console.log('Value:', value),
+  onComplete: () => console.log('Completed'),
+})
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript support is included. All components, hooks, and utilities are fully typed.
+
+---
+
+## Performance
+
+- Animations run on the GPU when possible
+- Automatic batching of style updates
+- Optimized re-renders
+- Tree-shakeable exports
+
+---
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+---
+
 ## Documentation
 
-For detailed documentation and examples, visit the official [react-ui-animate documentation](https://react-ui-animate.js.org/).
+For detailed documentation and more examples, visit the [official documentation](https://react-ui-animate.js.org/).
+
+---
 
 ## License
 
-This library is licensed under the MIT License.
+MIT © [Dipesh Rai](https://github.com/dipeshrai123)