@erosnicolau/animated-text/README.md

Advanced React animated text component with comprehensive animation effects

# @erosnicolau/animated-text

Advanced React animated text component with comprehensive animation effects and performance optimization.

## Features

- 🎨 **5 Animation Types** - Block, phrase, word, typewriter, and word-typewriter animations
- 🚀 **Performance Optimized** - FPS monitoring with automatic degradation
- 🔧 **Highly Configurable** - Extensive customization options for timing, effects, and styling
- 📱 **Responsive** - Automatic font scaling and mobile-optimized animations
- ♿ **Accessible** - Respects `prefers-reduced-motion` with graceful fallbacks
- 🎯 **TypeScript** - Full type safety with comprehensive interfaces
- 🌐 **i18n Ready** - Built for multilingual applications with phrase-based styling
- 🎬 **Group Coordination** - Synchronize multiple animated text elements

## Installation

```bash
npm install @erosnicolau/animated-text
```

## Quick Start

```tsx
import AnimatedText from '@erosnicolau/animated-text'

function MyComponent() {
  return <AnimatedText content="Hello, World!" animation="word" wordEffect={['fadeIn', 'slide-up']} />
}
```

## Animation Types

### 1. Block Animation

Animates the entire text block as one unit.

```tsx
<AnimatedText
  content="Welcome to our website"
  animation="block"
  blockEffect={['fadeIn', 'slide-up']}
  blockDuration={800}
/>
```

### 2. Phrase Animation

Animates phrases separated by "|" character with individual styling.

```tsx
<AnimatedText
  content="First phrase | Second phrase | Third phrase"
  animation="phrases"
  phraseStyles={[
    { phrase: 1, effect: ['fadeIn', 'slide-up'], className: 'text-blue-600' },
    { phrase: 2, effect: ['fadeIn', 'slide-up'], delayBefore: 300, className: 'text-green-600' },
    { phrase: 3, effect: ['fadeIn', 'slide-up'], delayBefore: 600, className: 'text-purple-600' }
  ]}
/>
```

### 3. Word Animation

Animates each word sequentially.

```tsx
<AnimatedText
  content="Each word appears individually"
  animation="word"
  wordEffect={['fadeIn', 'scale']}
  wordSpacing={200}
/>
```

### 4. Typewriter Animation

Animates each letter individually for a classic typewriter effect.

```tsx
<AnimatedText
  content="Letter by letter animation"
  animation="typewriter"
  typewriterEffect={['fadeIn']}
  typewriterDelay={50}
/>
```

### 5. Word-Typewriter Animation

Hybrid animation: letters appear individually with longer pauses between words for natural reading flow.

```tsx
<AnimatedText
  content="Natural reading flow with pauses"
  animation="word-typewriter"
  wordTypewriterEffect={['fadeIn']}
  wordTypewriterLetterDelay={40}
  wordTypewriterWordDelay={300}
/>
```

## Effects System

The component supports composable effects that can be combined for sophisticated animations:

### Simple Effects

- **Opacity**: `fade`, `fadeIn`, `fadeOut`
- **Movement**: `slide-up`, `slide-down`, `slide-left`, `slide-right`
- **Scale**: `scale`, `scaleX`, `scaleY`
- **Rotation**: `rotate`, `rotateX`, `rotateY`
- **Filters**: `blur`, `brightness`, `contrast`

### Advanced Object Effects

For precise control, use object notation with custom values:

```tsx
<AnimatedText
  content="Advanced effects"
  animation="block"
  blockEffect={[
    'fadeIn',
    { type: 'slide', x: 0, y: -30 },
    { type: 'scale', from: 0.5, to: 1 },
    { type: 'rotate', from: 15, to: 0 },
    { type: 'fontSize', from: '12px', to: '48px' },
    { type: 'letterSpacing', from: '8px', to: '2px' },
    { type: 'textShadow', from: 'none', to: '0 0 20px #8b5cf6' },
    { type: 'color', from: '#8b5cf6', to: '#1e40af' }
  ]}
  blockDuration={3000}
/>
```

### Typography Effects

- **Font**: `fontSize`, `fontWeight`, `letterSpacing`, `lineHeight`
- **Color**: `color`, `textShadow`
- **Spacing**: `margin`, `padding`, `width`, `height`

### Visual Effects

- **Borders**: `borderColor`, `borderWidth`, `borderRadius`
- **Shadows**: `textShadow`, `boxShadow`
- **Background**: `backgroundColor`, `backdropFilter`

### Effect Categories by Complexity

#### Basic (String Effects)

```tsx
wordEffect={['fadeIn', 'slide-up', 'scale']}
```

#### Advanced (Object Effects)

```tsx
blockEffect={[
  'fadeIn',
  { type: 'fontSize', from: '16px', to: '32px' },
  { type: 'color', from: '#000', to: '#ff6b6b' }
]}
```

#### Ultimate (8+ Effect Combinations)

```tsx
blockEffect={[
  'fadeIn',
  { type: 'slide', x: 0, y: -30 },
  { type: 'scale', from: 0.5, to: 1 },
  { type: 'rotate', from: 15, to: 0 },
  { type: 'fontSize', from: '12px', to: '48px' },
  { type: 'letterSpacing', from: '8px', to: '2px' },
  { type: 'textShadow', from: 'none', to: '0 0 20px #8b5cf6' },
  { type: 'color', from: '#8b5cf6', to: '#1e40af' }
]}
```

## Performance Features

### FPS Monitoring

Automatic performance monitoring with graceful degradation:

```tsx
import { getFPSMetrics, updateFPSThreshold } from '@erosnicolau/animated-text'

// Monitor performance
const metrics = getFPSMetrics()
console.log(`Current FPS: ${metrics.currentFPS}`)

// Adjust performance threshold
updateFPSThreshold(30) // Switch to simplified animations below 30 FPS
```

### Virtualization

Features intersection observer-based virtualization for performance optimization with large amounts of text.

## Group Coordination

Coordinate multiple animated text elements:

```tsx
import { AnimatedTextGroup } from '@erosnicolau/animated-text'

function Showcase() {
  return (
    <AnimatedTextGroup coordinationMode="sequential" staggerDelay={300}>
      <AnimatedText content="First text" animation="word" />
      <AnimatedText content="Second text" animation="block" />
      <AnimatedText content="Third text" animation="typewriter" />
    </AnimatedTextGroup>
  )
}
```

### Coordination Modes

- `parallel` - All animations start simultaneously
- `sequential` - Animations start one after another
- `cascade` - Overlapping start times with stagger delay
- `wave` - Wave-like propagation effect

## Internationalization

Built for multilingual applications:

```tsx
<AnimatedText
  content="Bună ziua | Salut | Welcome"
  animation="phrases"
  phraseStyles={[{ className: 'text-blue-600' }, { className: 'text-green-600' }, { className: 'text-purple-600' }]}
/>
```

## Font Scaling System

### 3-Level Priority Font System

The component uses a sophisticated 3-level priority system for font sizing:

#### Level 1: Explicit className (Highest Priority)

When you provide explicit font classes in `className`, they take full precedence:

```tsx
<AnimatedText
  content="Custom sizing"
  className="text-2xl md:text-3xl lg:text-4xl"
  // fontPreset and fontScale are ignored
/>
```

#### Level 2: Font Presets (Medium Priority)

Use predefined responsive font combinations:

```tsx
<AnimatedText
  content="Preset sizing"
  fontPreset="hero" // 'hero', 'section', 'subsection', 'body'
  // Only applies when no explicit font classes in className
/>
```

**Available Presets:**

- `hero`: Large display text (text-4xl md:text-5xl lg:text-6xl)
- `section`: Section headings (text-3xl md:text-4xl lg:text-5xl) - **default**
- `subsection`: Subsection headings (text-2xl md:text-3xl lg:text-4xl)
- `body`: Body text (text-lg md:text-xl lg:text-2xl)

#### Level 3: Font Scaling (Lowest Priority)

Proportionally scale any preset:

```tsx
<AnimatedText
  content="Scaled preset"
  fontPreset="section"
  fontScale={1.2} // 20% larger than section preset
/>

<AnimatedText
  content="Smaller version"
  fontPreset="hero"
  fontScale={0.8} // 20% smaller than hero preset
/>
```

### Semantic Elements

Control the HTML element used:

```tsx
<AnimatedText
  content="Page Title"
  as="h1" // h1, h2, h3, h4, h5, h6, p, div, span
  fontPreset="hero"
/>
```

## Advanced Props

### AnimatedTextProps

| Prop          | Type            | Default   | Description                    |
| ------------- | --------------- | --------- | ------------------------------ |
| `content`     | `string`        | -         | Text content (required)        |
| `animation`   | `AnimationType` | `'block'` | Animation type                 |
| `allowHtml`   | `boolean`       | `false`   | Enable HTML parsing            |
| `startDelay`  | `number`        | `300`     | Initial delay before animation |
| `itemSpacing` | `number`        | `600`     | Default spacing between items  |

### Block Animation Props

| Prop            | Type               | Default                  | Description              |
| --------------- | ------------------ | ------------------------ | ------------------------ |
| `blockEffect`   | `ComposableEffect` | `['fadeIn', 'slide-up']` | Block animation effects  |
| `blockDuration` | `number`           | `600`                    | Block animation duration |
| `blockEasing`   | `AnimationEasing`  | `'ease-out'`             | Block animation easing   |

### Word Animation Props

| Prop           | Type               | Default      | Description            |
| -------------- | ------------------ | ------------ | ---------------------- |
| `wordEffect`   | `ComposableEffect` | `['fadeIn']` | Word animation effects |
| `wordDuration` | `number`           | `400`        | Duration per word      |
| `wordSpacing`  | `number`           | `200`        | Time between words     |
| `wordEasing`   | `AnimationEasing`  | `'ease-out'` | Word animation easing  |

### Typewriter Animation Props

| Prop                 | Type               | Default      | Description              |
| -------------------- | ------------------ | ------------ | ------------------------ |
| `typewriterEffect`   | `ComposableEffect` | `['fadeIn']` | Letter animation effects |
| `typewriterDuration` | `number`           | `200`        | Duration per letter      |
| `typewriterDelay`    | `number`           | `50`         | Time between letters     |
| `typewriterEasing`   | `AnimationEasing`  | `'ease-out'` | Letter animation easing  |

### Word-Typewriter Animation Props

| Prop                        | Type               | Default      | Description                   |
| --------------------------- | ------------------ | ------------ | ----------------------------- |
| `wordTypewriterEffect`      | `ComposableEffect` | `['fadeIn']` | Letter animation effects      |
| `wordTypewriterDuration`    | `number`           | `150`        | Duration per letter           |
| `wordTypewriterLetterDelay` | `number`           | `50`         | Time between letters          |
| `wordTypewriterWordDelay`   | `number`           | `400`        | Time delay at word boundaries |
| `wordTypewriterEasing`      | `AnimationEasing`  | `'ease-out'` | Letter animation easing       |

### Phrase Animation Props

| Prop           | Type            | Default | Description                          |
| -------------- | --------------- | ------- | ------------------------------------ |
| `phraseStyles` | `PhraseStyle[]` | `[]`    | Individual phrase styling and timing |

## Demo

The package includes a comprehensive demo showcasing all features:

```tsx
import { AnimatedTextDemo } from '@erosnicolau/animated-text/demo'

function App() {
  return <AnimatedTextDemo />
}
```

### Demo Sections Available

- **Animation Types**: All 5 animation modes with live examples
- **Composable Effects**: Mix and match effect combinations
- **Ultimate Effects**: 8+ effect combinations showing maximum capabilities
- **Font Effects**: fontSize, fontWeight, letterSpacing, lineHeight animations
- **Visual Effects**: Colors, shadows, borders, backgrounds
- **Layout Effects**: Width, height, margin, padding animations
- **Typography Showcases**: Real-world text animation scenarios
- **Group Animations**: Coordinated multi-element animations
- **Creative Demos**: Artistic, cinematic, gaming, and agency-style presentations
- **Static Styling**: Non-animated styling options
- **Border Effects**: Comprehensive border animation examples

## CSS Import

Don't forget to import the CSS file:

```tsx
import '@erosnicolau/animated-text/dist/AnimatedText.css'
```

## TypeScript Support

Full TypeScript support with exported types:

```tsx
import type { AnimatedTextProps, AnimationEffect, ComposableEffect, FPSMetrics } from '@erosnicolau/animated-text'
```

## Performance Recommendations

1. **Monitor FPS** in production with `getFPSMetrics()`
2. **Limit concurrent animations** (< 10 simultaneously)
3. **Prefer `transform` and `opacity`** effects for best performance
4. **Test on mobile devices** for performance validation

## License

MIT License - see package.json for details.

## Contributing

This package is part of the Eros Nicolau portfolio project. For bugs or feature requests, please open an issue.

---

**Made with ❤️ by Eros Nicolau**