my-animation-lib/README.md

A powerful animation library combining Three.js, GSAP, custom scroll triggers, and advanced effects with MathUtils integration

# 🎨 My Animation Library

> A powerful, feature-rich animation library combining Three.js, GSAP, and advanced mathematical utilities for creating stunning web animations and effects.

[![npm version](https://badge.fury.io/js/my-animation-lib.svg)](https://badge.fury.io/js/my-animation-lib)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Bundle Size](https://img.shields.io/bundlephobia/min/my-animation-lib)](https://bundlephobia.com/result?p=my-animation-lib)

## ✨ Features

- 🚀 **High-Performance Animation Engine** - Built on GSAP for smooth, optimized animations
- 🎯 **Advanced Math Utilities** - Comprehensive mathematical functions for natural animations
- 🌊 **Rich Effect Library** - 20+ pre-built effects and animations
- 📱 **Responsive & Touch-Friendly** - Works seamlessly across all devices
- 🎨 **Three.js Integration** - WebGL-powered 3D animations and effects
- 📜 **Smart Scroll Triggers** - Automatic animation triggering on scroll
- 🧮 **Easing Functions** - 30+ easing functions for smooth transitions
- 🎭 **Particle Systems** - Dynamic particle effects and simulations
- 🔄 **Spring Physics** - Realistic spring-based animations
- 🎪 **Morphing & Path Animations** - Smooth shape and path interpolations

## 🚀 Quick Start

### Installation

```bash
npm install my-animation-lib
```

### CDN Usage

```html
<script src="https://unpkg.com/my-animation-lib@1.0.0/dist/index.umd.js"></script>
```

### Basic Usage

```javascript
import { AnimationEngine, MathUtils } from 'my-animation-lib';

// Initialize the engine
const engine = new AnimationEngine();

// Create a spring animation
const element = document.getElementById('myElement');
engine.createSpringAnimation(element, {
    targetValue: 100,
    stiffness: 0.1,
    damping: 0.8
});
```

## 🎭 Effects Library

### 🌊 Wave Effects

#### `createAdvancedWaveEffect(element, options)`
Creates sophisticated wave animations with customizable parameters.

```javascript
engine.createAdvancedWaveEffect(element, {
    amplitude: 50,        // Wave height
    frequency: 2,         // Wave frequency
    duration: 3,          // Animation duration
    easing: 'sine',       // Easing function
    direction: 'horizontal' // Wave direction
});
```

**Options:**
- `amplitude` (number): Wave height in pixels
- `frequency` (number): Number of wave cycles
- `duration` (number): Animation duration in seconds
- `easing` (string): Easing function name
- `direction` (string): 'horizontal' or 'vertical'

### 🎲 Noise Animations

#### `createNoiseAnimation(element, options)`
Generates organic, random movement using Perlin noise.

```javascript
engine.createNoiseAnimation(element, {
    intensity: 30,        // Movement intensity
    speed: 0.5,          // Animation speed
    duration: 5,          // Total duration
    seed: 12345          // Random seed for consistency
});
```

**Options:**
- `intensity` (number): Maximum movement distance
- `speed` (number): Animation speed multiplier
- `duration` (number): Total animation duration
- `seed` (number): Random seed for reproducible results

### 🦘 Spring Animations

#### `createSpringAnimation(element, options)`
Creates realistic spring physics animations.

```javascript
engine.createSpringAnimation(element, {
    targetValue: 150,     // Target position
    stiffness: 0.1,       // Spring stiffness (0-1)
    damping: 0.8,         // Damping factor (0-1)
    mass: 1.0,            // Mass of the object
    restThreshold: 0.01   // Rest threshold
});
```

**Options:**
- `targetValue` (number): Target position/value
- `stiffness` (number): Spring stiffness (0-1)
- `damping` (number): Damping factor (0-1)
- `mass` (number): Mass of the animated object
- `restThreshold` (number): Threshold to stop animation

### ✨ Particle Systems

#### `createParticleSystem(container, options)`
Generates dynamic particle effects with customizable properties.

```javascript
engine.createParticleSystem(container, {
    particleCount: 100,   // Number of particles
    colors: ['#ff6b6b', '#4ecdc4', '#45b7d1'],
    size: { min: 2, max: 8 },
    speed: 0.5,           // Movement speed
    life: 3000,           // Particle lifetime in ms
    gravity: 0.1,         // Gravity effect
    wind: { x: 0.5, y: 0 }
});
```

**Options:**
- `particleCount` (number): Number of particles to generate
- `colors` (array): Array of hex colors for particles
- `size` (object): Min/max particle sizes
- `speed` (number): Movement speed multiplier
- `life` (number): Particle lifetime in milliseconds
- `gravity` (number): Gravity effect strength
- `wind` (object): Wind effect direction and strength

### 🎨 Color Transitions

#### `createColorTransition(element, startColor, endColor, options)`
Smoothly interpolates between two colors.

```javascript
engine.createColorTransition(element, '#ff0000', '#00ff00', {
    duration: 2,          // Transition duration
    easing: 'sine',       // Easing function
    loop: true,           // Loop the transition
    yoyo: true            // Reverse direction
});
```

**Options:**
- `duration` (number): Transition duration in seconds
- `easing` (string): Easing function name
- `loop` (boolean): Whether to loop the transition
- `yoyo` (boolean): Whether to reverse direction

### 🛤️ Path Animations

#### `createMorphingPath(element, pathPoints, options)`
Animates elements along smooth Catmull-Rom spline paths.

```javascript
const pathPoints = [
    { x: 0, y: 0 },
    { x: 100, y: 50 },
    { x: 200, y: 0 },
    { x: 300, y: 100 }
];

engine.createMorphingPath(element, pathPoints, {
    duration: 5,          // Animation duration
    easing: 'sine',       // Easing function
    loop: true,           // Loop the path
    autoRotate: true      // Auto-rotate along path
});
```

**Options:**
- `duration` (number): Animation duration in seconds
- `easing` (string): Easing function name
- `loop` (boolean): Whether to loop the path
- `autoRotate` (boolean): Auto-rotate element along path

### 🔄 Shape Morphing

#### `createMorphingShape(element, shapes, options)`
Smoothly interpolates between different shape definitions.

```javascript
const shapes = [
    'circle(50% at 50% 50%)',
    'polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)',
    'ellipse(25% 40% at 50% 50%)'
];

engine.createMorphingShape(element, shapes, {
    duration: 3,          // Morphing duration
    easing: 'sine',       // Easing function
    loop: true,           // Loop the morphing
    steps: 10             // Number of interpolation steps
});
```

**Options:**
- `duration` (number): Morphing duration in seconds
- `easing` (string): Easing function name
- `loop` (boolean): Whether to loop the morphing
- `steps` (number): Number of interpolation steps

## 🧮 MathUtils Functions

### Basic Math Functions

```javascript
import { MathUtils } from 'my-animation-lib';

// Clamp value between min and max
MathUtils.clamp(5, 0, 10);        // Returns 5

// Linear interpolation
MathUtils.lerp(0, 100, 0.5);      // Returns 50

// Map value from one range to another
MathUtils.map(25, 0, 100, 0, 1); // Returns 0.25

// Random number between min and max
MathUtils.random(1, 10);          // Returns random number

// Distance between two points
MathUtils.distance(0, 0, 3, 4);   // Returns 5
```

### Easing Functions

```javascript
// Bounce effect
MathUtils.bounce(0.5);             // Returns bounce value

// Elastic effect
MathUtils.elastic(0.5);            // Returns elastic value

// Back effect
MathUtils.back(0.5);               // Returns back value

// Smooth step
MathUtils.smoothstep(0.3);         // Returns smoothstep value
```

### Advanced Math Functions

```javascript
// Fibonacci sequence
MathUtils.fibonacci(10);           // Returns 55

// Factorial
MathUtils.factorial(5);            // Returns 120

// Prime number check
MathUtils.isPrime(17);             // Returns true

// Greatest common divisor
MathUtils.gcd(48, 18);             // Returns 6

// Least common multiple
MathUtils.lcm(12, 18);             // Returns 36
```

## 🎯 Easing Functions

### Standard Easing

```javascript
import { Easing } from 'my-animation-lib';

// Linear
Easing.linear(t);

// Quadratic
Easing.easeInQuad(t);
Easing.easeOutQuad(t);
Easing.easeInOutQuad(t);

// Cubic
Easing.easeInCubic(t);
Easing.easeOutCubic(t);
Easing.easeInOutCubic(t);

// Bounce
Easing.easeInBounce(t);
Easing.easeOutBounce(t);
Easing.easeInOutBounce(t);

// Elastic
Easing.easeInElastic(t);
Easing.easeOutElastic(t);
Easing.easeInOutElastic(t);
```

### Custom Easing

```javascript
// Custom easing function
Easing.custom(t, [0.25, 0.46, 0.45, 0.94]);

// Bezier curve
Easing.bezier(t, 0.25, 0.46, 0.45, 0.94);
```

## 🎮 Advanced Usage

### Custom Animation Timeline

```javascript
const engine = new AnimationEngine();
const timeline = engine.createTimeline();

timeline
    .add(engine.createSpringAnimation(element1, { targetValue: 100 }))
    .add(engine.createWaveEffect(element2, { amplitude: 50 }), '-=0.5')
    .add(engine.createParticleSystem(container, { particleCount: 200 }));

timeline.play();
```

### Scroll-Triggered Animations

```javascript
const engine = new AnimationEngine({ enableScrollTrigger: true });

engine.createScrollAnimation(element, {
    trigger: '.trigger-element',
    start: 'top center',
    end: 'bottom center',
    animation: engine.createSpringAnimation(element, { targetValue: 200 })
});
```

### Three.js Integration

```javascript
const engine = new AnimationEngine({ enableThreeJS: true });

const scene = engine.threeJSManager.createScene();
const cube = engine.threeJSManager.createCube();

engine.createThreeJSAnimation(cube, {
    rotation: { x: Math.PI * 2, y: Math.PI * 2 },
    duration: 3,
    easing: 'elastic'
});
```

## 📱 Components

### HiTechScroller

```javascript
import { HiTechScroller } from 'my-animation-lib';

const scroller = new HiTechScroller({
    container: '.scroll-container',
    speed: 1.5,
    smoothness: 0.1
});
```

### ScrollTrigger

```javascript
import { ScrollTrigger } from 'my-animation-lib';

const trigger = new ScrollTrigger({
    trigger: '.element',
    start: 'top center',
    end: 'bottom center',
    onEnter: () => console.log('Element entered viewport'),
    onLeave: () => console.log('Element left viewport')
});
```

## 🔧 Configuration

### AnimationEngine Options

```javascript
const engine = new AnimationEngine({
    enableThreeJS: true,           // Enable Three.js features
    enableScrollTrigger: true,     // Enable scroll triggers
    defaultDuration: 1,            // Default animation duration
    defaultEasing: 'sine',         // Default easing function
    performanceMode: 'high'        // Performance optimization level
});
```

### Performance Modes

- `'high'`: Maximum performance, minimal features
- `'balanced'`: Balanced performance and features (default)
- `'quality'`: Maximum quality, reduced performance

## 📦 Build & Development

### Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview build
npm run preview
```

### Build Outputs

- `dist/index.js` - CommonJS bundle
- `dist/index.esm.js` - ES Modules bundle
- `dist/index.umd.js` - Universal bundle (CDN ready)

## 🌟 Examples

Check out the comprehensive examples in the `examples/` directory:

- `test-package.html` - Complete package test and demo
- `math-utils-integration.html` - MathUtils integration examples

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [GSAP](https://greensock.com/gsap/) - The animation powerhouse
- [Three.js](https://threejs.org/) - 3D graphics library
- [Perlin Noise](https://en.wikipedia.org/wiki/Perlin_noise) - Natural randomness algorithm

## 📞 Support

- 📧 Email: your-email@example.com
- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/my-animation-lib/issues)
- 📖 Documentation: [Full Documentation](docs/)
- 💬 Discord: [Join our community](https://discord.gg/your-server)

---

Made with ❤️ by [Your Name]