# Text Stylizer

![npm Version](https://img.shields.io/npm/v/text-stylizer)
![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
![Tests](https://img.shields.io/badge/tests-passing-brightgreen)
![Bundle Size](https://img.shields.io/bundlephobia/minzip/text-stylizer)
![License](https://img.shields.io/npm/l/text-stylizer)

A powerful TypeScript library for creating dynamic text effects and animations. Perfect for adding engaging text effects to your web applications with minimal effort and maximum flexibility.

## ✨ Features

- 🎨 **Rich Effects Collection**: Wave, Gradient, Neon, Bounce, Typewriter, Fire, Glitch, and more
- 🎯 **Type Safe**: Full TypeScript support with comprehensive type definitions
- ⚡ **Performance Optimized**: CSS-based animations for smooth performance
- 🎮 **Customizable**: Extensive options for fine-tuning effects
- 🧩 **Extensible**: Easy-to-use API for creating custom effects
- 📱 **Cross-Browser**: Works in all modern browsers
- 🔄 **Effect Chaining**: Combine multiple effects seamlessly
- 🎪 **Live Preview**: Built-in demo component for React

## 📦 Installation

```bash
npm install text-stylizer
```

## 🚀 Quick Start

```typescript
import { TextStylizer, WaveEffect } from 'text-stylizer';

// Create a new instance of TextStylizer
const stylizer = new TextStylizer();

// Register the wave effect before using it
stylizer.registerEffect(WaveEffect);

// Now you can use the wave effect
const result = stylizer.applyEffect('wave', 'Hello World', {
  amplitude: 10,
  frequency: 0.1
});

console.log(result);
```

## 🎨 Available Effects

### Wave Effect
Creates a smooth wave animation through text.
```typescript
stylizer.applyEffect('wave', text, {
  amplitude: 10,    // Wave height in pixels
  frequency: 0.1,   // Wave frequency
  speed: 1         // Animation speed
});
```

### Gradient Effect
Applies a flowing color gradient through text.
```typescript
stylizer.applyEffect('gradient', text, {
  colors: ['#ff0000', '#00ff00', '#0000ff'],  // At least 2 colors
  speed: 1                                     // Flow speed
});
```

### Neon Effect
Creates a glowing neon light effect.
```typescript
stylizer.applyEffect('neon', text, {
  colors: ['#ff00ff'],  // Primary color
  blur: 2,              // Blur amount
  intensity: 1.5        // Glow intensity
});
```

### Bounce Effect
Makes text characters bounce playfully.
```typescript
stylizer.applyEffect('bounce', text, {
  height: 20,      // Bounce height
  speed: 1,        // Animation speed
  stagger: 0.1     // Delay between characters
});
```

### Typewriter Effect
Simulates typewriter-style text appearance.
```typescript
stylizer.applyEffect('typewriter', text, {
  speed: 1,           // Typing speed
  cursor: true,       // Show cursor
  cursorChar: '|'     // Custom cursor character
});
```

### Fire Effect
Creates a fiery animation effect.
```typescript
stylizer.applyEffect('fire', text, {
  colors: ['#ff0000', '#ff6600', '#ffcc00'],  // Flame colors
  speed: 1,                                    // Animation speed
  intensity: 1.5                               // Flame intensity
});
```

### Glitch Effect
Applies a digital glitch effect.
```typescript
stylizer.applyEffect('glitch', text, {
  intensity: 1,    // Glitch intensity
  speed: 1,        // Animation speed
  colors: ['#ff0000', '#00ff00', '#0000ff']  // Glitch colors
});
```

### Sparkle Effect
Adds a sparkling animation to text.
```typescript
stylizer.applyEffect('sparkle', text, {
  colors: ['#FFD700'],  // Sparkle color
  intensity: 1,         // Sparkle intensity
  speed: 1              // Animation speed
});
```

## 🛠️ Advanced Usage

### Chaining Effects
```typescript
const result = stylizer.chainEffects('Hello World', [
  { name: 'wave', options: { amplitude: 10 } },
  { name: 'neon', options: { intensity: 1.5 } },
  { name: 'sparkle', options: { speed: 1.2 } }
]);

// Add both HTML and CSS to your document
document.body.innerHTML += result.html;
document.head.innerHTML += `<style>${result.css}</style>`;
```

### Custom Effects
```typescript
import { TextEffect, StyleOptions } from 'text-stylizer';

const CustomEffect: TextEffect = {
  name: 'custom',
  defaultOptions: {
    speed: 1
  },
  keyframes: {
    '0%': 'transform: scale(1)',
    '50%': 'transform: scale(1.5)',
    '100%': 'transform: scale(1)'
  },
  apply(text: string, options: StyleOptions = {}) {
    // Implementation
    return `<span style="...">${text}</span>`;
  }
};

stylizer.registerEffect(CustomEffect);
```

## 🎮 Configuration Options

### Global Options
```typescript
const stylizer = new TextStylizer({
  fontSize: '16px',
  fontFamily: 'Arial, sans-serif',
  speed: 1,
  intensity: 1
});
```

### Style Options
```typescript
interface StyleOptions {
  // Animation options
  amplitude?: number;
  frequency?: number;
  speed?: number;
  intensity?: number;
  duration?: number;
  delay?: number;
  
  // Text styling
  bold?: boolean;
  italic?: boolean;
  fontSize?: string;
  fontFamily?: string;
  letterSpacing?: string;
  
  // Effect-specific options
  colors?: string[];
  blur?: number;
  height?: number;
  stagger?: number;
  cursor?: boolean;
  cursorChar?: string;
}
```

## 🧪 Testing

```bash
# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run specific test suite
npm test -- effects.test.ts
```

## 📈 Performance Tips

1. Use CSS animations over JavaScript animations
2. Limit the number of simultaneous animations
3. Use `will-change` property for better performance
4. Consider using `requestAnimationFrame` for complex animations
5. Enable hardware acceleration when appropriate

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -am 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup
```bash
# Clone the repository
git clone https://github.com/OrenGrinker/textStylizer.git

# Install dependencies
npm install

# Start development
npm run dev

# Build the project
npm run build
```

## 📝 License

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

## 💬 Support

- Issues: [GitHub Issues](https://github.com/OrenGrinker/textStylizer/issues)