react-ui-animate/README.md

React library for gestures and animation

# React UI Animate

[![npm version](https://badge.fury.io/js/react-ui-animate.svg)](https://badge.fury.io/js/react-ui-animate)

> Create smooth animations and interactive gestures in React applications effortlessly.

### Install

You can install `react-ui-animate` via `npm` or `yarn`:

```sh
npm install react-ui-animate
```

```sh
yarn add react-ui-animate
```

---

## Getting Started

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

Use `useValue` to initialize and update an animated value.

```tsx
import React from 'react';
import {
  animate,
  useValue,
  withSpring,
  withTiming,
  withSequence,
} from 'react-ui-animate';

export const UseValue: React.FC = () => {
  const [width, setWidth] = useValue(100);

  return (
    <>
      <button
        onClick={() => {
          setWidth(withSequence([withTiming(100), withSpring(0)]));
        }}
      >
        SEQUENCE (100 → 0)
      </button>
      <button
        onClick={() => {
          setWidth(withSpring(200));
        }}
      >
        SPRING (→ 200)
      </button>
      <button
        onClick={() => {
          setWidth(400);
        }}
      >
        IMMEDIATE (→ 400)
      </button>

      <animate.div
        style={{
          width,
          height: 100,
          backgroundColor: 'red',
          left: 0,
          top: 0,
        }}
      />
    </>
  );
};
```

### 2. useMount

Use `useMount` to animate component mount and unmount transitions.

```tsx
import React from 'react';
import {
  animate,
  useMount,
  withDecay,
  withSequence,
  withSpring,
  withTiming,
} 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 });

  return (
    <>
      {mounted(
        (animation, isMounted) =>
          isMounted && (
            <animate.div
              style={{
                width: 100,
                height: 100,
                backgroundColor: 'teal',
                opacity: animation,
              }}
            />
          )
      )}

      <button onClick={() => setOpen((prev) => !prev)}>ANIMATE ME</button>
    </>
  );
};
```

### 3. Interpolation

Interpolate values for complex mappings like color transitions or movement.

```tsx
import React, { useLayoutEffect, useState } from 'react';
import { animate, useValue, withSpring } from 'react-ui-animate';

export const Interpolation: React.FC = () => {
  const [open, setOpen] = useState(false);
  const [x, setX] = useValue(0);

  useLayoutEffect(() => {
    setX(withSpring(open ? 500 : 0));
  }, [open, setX]);

  return (
    <>
      <animate.div
        style={{
          width: 100,
          height: 100,
          backgroundColor: x.to([0, 500], ['red', 'blue']),
          translateX: x,
        }}
      />

      <button onClick={() => setOpen((p) => !p)}>ANIMATE ME</button>
    </>
  );
};
```

---

## API Overview

- **`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.

## Gestures

`react-ui-animate` also provides hooks for handling gestures:

- `useDrag`
- `useMove`
- `useScroll`
- `useWheel`

**Example: `useDrag`**

```tsx
import React from 'react';
import { useValue, animate, useDrag, withSpring } from 'react-ui-animate';

export const Draggable: React.FC = () => {
  const ref = useRef(null);
  const [translateX, setTranslateX] = useValue(0);

  useDrag(ref, ({ down, movement }) => {
    setTranslateX(down ? movement.x : withSpring(0));
  });

  return (
    <animate.div
      ref={ref}
      style={{
        width: 100,
        height: 100,
        backgroundColor: '#3399ff',
        translateX,
      }}
    />
  );
};
```

## Documentation

For detailed documentation and examples, visit the official [react-ui-animate documentation](https://react-ui-animate.js.org/).

## License

This library is licensed under the MIT License.