anime-ts/README.md

A lightweight and flexible JS/TS animation library that provides smooth animation with precise control. Features include customizable durations, timing functions, delays, and lifecycle hooks. Perfect for creating performant web animations with minimal ove

## 🎨 Animation Controller By JS/TS

A lightweight and powerful TypeScript library for creating smooth, controlled CSS transitions with minimal overhead.  
Perfect for pure JS/TS, React, Next.js projects, and other libraries and frameworks.

### ✨ Features

-  🚀 **Lightweight & Fast**: Pure TypeScript implementation with zero dependencies
-  🎯 **Type-Safe**: Full TypeScript support for better development experience
-  ⚛️ **Framework-Agnostic**: Use in React, Vanilla JS, or any environment
-  🎮 **Fine Control**: Precise lifecycle hooks for transitions (start, run, end, cancel)
-  ⚡ **Performance Focused**: Uses native CSS transitions
-  🛠️ **Flexible API**: Simple yet powerful
-  🎭 **Multiple Properties**: Animate multiple CSS properties simultaneously
-  ⏱️ **Timing Control**: Supports numeric duration, easing, and delay

---

### 📦 Installation

```bash
npm install anime-ts
# or
yarn add anime-ts
# or
pnpm add anime-ts
```

---

### 🚀 Quick Start

```ts
import { An } from 'anime-ts';

// Animate opacity and transform
An(
   '#myElement',
   {
      opacity: '0',
      transform: 'translateY(20px)',
   },
   {
      time: 0.5, // duration in seconds
      ease: 'ease-out',
      delay: 0, // delay in seconds
   }
);
```

#### Using individual timings per property:

```ts
An(
   '#myElement',
   {
      opacity: {
         from: '1',
         to: '0.5',
         delay: 1, // in seconds
      },
      transform: {
         from: 'translateY(0)',
         to: 'translateY(20px)',
         time: 0.8,
         ease: 'ease-in-out',
         delay: 0.2,
      },
   },
   {
      time: 0.5,
      delay: 0,
   }
);
```

---

### 📖 API Reference

#### Constructor

```ts
An(
  target: string | HTMLElement,
  attributes: AttributeT,
  detail?: {
    time?: number;  // default time in seconds
    ease?: string;  // default easing function
    delay?: number;  // default delay in seconds
  }
)
```

---

### 🔧 Attribute Syntax

Each attribute can be:

1. A string value (target value):

   ```ts
   {
      opacity: '0';
   }
   ```

2. Or an object with detailed settings:
   ```ts
   {
     opacity: {
        from: '1',
        to: '0',
        time: 0.5,     // in seconds
        ease: 'ease-in',
        delay: 0.3     // in seconds
     }
   }
   ```

---

### 🔁 Lifecycle Hooks

```ts
const animation = An('#myElement', { opacity: '0.5' });

animation.onRun = () => console.log('Running...');
animation.onStart = () => console.log('Started');
animation.onCancel = () => console.log('Cancelled');
animation.onEnd = () => console.log('Completed');
```

---

### ⏹️ Stop Animation

```ts
animation.stop();
```

---

### 🎭 More Examples

```ts
An(
   '#box',
   {
      width: {
         from: '100px',
         to: '300px',
         time: 1,
         ease: 'ease-in-out',
      },
      background: {
         from: '#ff0000',
         to: '#00ff00',
         time: 1.5,
      },
   },
   {
      time: 0.8,
      ease: 'ease-out',
      delay: 0,
   }
);
```

---

### 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, open an issue to discuss first.

---

### 📄 License

MIT License – see the [LICENSE.md](LICENSE.md) for details.

---

Made with ❤️ in TypeScript