michaelschiemer/docs/modules/animation-system.md

# Animation System Module

**Unified Animation System for Scroll-Based Animations**

The Animation System Module consolidates all scroll animation modules into a single, unified system with backward compatibility.

---

## Features

- **Fade-In Animations** - Elements fade in when scrolling into view
- **Zoom-In Animations** - Elements zoom in when scrolling into view
- **Parallax Effects** - Parallax scrolling effects
- **Scroll Timeline** - Step-based scroll animations
- **Sticky Fade** - Fade effects on sticky elements
- **Sticky Steps** - Step-based animations on sticky elements
- **IntersectionObserver Support** - Efficient scroll detection
- **Backward Compatibility** - Works with existing HTML attributes

---

## Quick Start

### Basic Usage

```javascript
import { AnimationSystem } from './modules/animation-system/index.js';

// Create animation system
const system = AnimationSystem.create({
    enabled: true,
    useIntersectionObserver: true
});

// Register animation
system.registerAnimation(element, {
    type: 'fade-in',
    offset: 0.85,
    delay: 0.1,
    once: true
});
```

### Module System Integration

```html
<!-- Enable global animation system -->
<script type="module">
    import { init } from './modules/animation-system/index.js';
    
    init({
        enabled: true,
        useIntersectionObserver: true
    });
</script>

<!-- Use data attributes (auto-initialized) -->
<div class="fade-in-on-scroll" data-offset="0.85" data-delay="0.1">
    Content that fades in
</div>

<div data-parallax data-speed="0.5">
    Parallax content
</div>
```

---

## API Reference

### AnimationSystem.create(config)

Create a new AnimationSystem instance.

**Parameters**:
- `config.enabled` - Enable animations (default: true)
- `config.useIntersectionObserver` - Use IntersectionObserver (default: true)
- `config.throttleDelay` - Throttle delay for scroll handler (default: 16ms)

### system.registerAnimation(element, config)

Register an animation for an element.

**Parameters**:
- `element` - HTMLElement
- `config.type` - Animation type
- `config.offset` - Trigger offset (0-1)
- `config.delay` - Animation delay
- `config.once` - Trigger only once
- `config.speed` - Parallax speed
- `config.steps` - Number of steps
- `config.triggerPoint` - Trigger point (0-1)

---

## Animation Types

### Fade-In

```javascript
system.registerAnimation(element, {
    type: 'fade-in',
    offset: 0.85,
    delay: 0.1,
    once: true
});
```

### Zoom-In

```javascript
system.registerAnimation(element, {
    type: 'zoom-in',
    offset: 0.85,
    delay: 0.1
});
```

### Parallax

```javascript
system.registerAnimation(element, {
    type: 'parallax',
    speed: 0.5
});
```

### Timeline

```javascript
system.registerAnimation(element, {
    type: 'timeline',
    steps: 5,
    triggerPoint: 0.4
});
```

### Sticky Fade

```javascript
system.registerAnimation(element, {
    type: 'sticky-fade',
    fadeStart: 0,
    fadeEnd: 1
});
```

### Sticky Steps

```javascript
system.registerAnimation(element, {
    type: 'sticky-steps',
    steps: 3
});
```

---

## HTML Data Attributes

### Auto-Initialization

The system automatically initializes animations based on HTML attributes:

```html
<!-- Fade in -->
<div class="fade-in-on-scroll" data-offset="0.85" data-delay="0.1">
    Content
</div>

<!-- Parallax -->
<div data-parallax data-speed="0.5">
    Parallax content
</div>

<!-- Timeline -->
<div data-scroll-timeline data-scroll-steps="5">
    Timeline content
</div>

<!-- Sticky fade -->
<div data-sticky-fade data-fade-start="0" data-fade-end="1">
    Sticky content
</div>
```

---

## Backward Compatibility

The system maintains backward compatibility with old modules:

```html
<!-- Old scrollfx classes still work -->
<div class="fade-in-on-scroll">Content</div>
<div class="zoom-in">Content</div>

<!-- Old parallax attributes still work -->
<div class="parallax" data-speed="0.5">Content</div>

<!-- Old scroll-timeline attributes still work -->
<div data-scroll-step="0">Content</div>
```

---

## Migration Guide

### From scrollfx

**Before**:
```javascript
import { createTrigger } from './modules/scrollfx/index.js';
createTrigger({ element: '.fade-in', offset: 0.85 });
```

**After**:
```javascript
import { AnimationSystem } from './modules/animation-system/index.js';
const system = AnimationSystem.create();
document.querySelectorAll('.fade-in').forEach(el => {
    system.registerAnimation(el, { type: 'fade-in', offset: 0.85 });
});
```

### From parallax

**Before**:
```javascript
import { init } from './modules/parallax/index.js';
init({ selector: '.parallax' });
```

**After**:
```javascript
import { AnimationSystem } from './modules/animation-system/index.js';
const system = AnimationSystem.create();
document.querySelectorAll('.parallax').forEach(el => {
    system.registerAnimation(el, { type: 'parallax', speed: 0.5 });
});
```

---

## Best Practices

1. **Use IntersectionObserver** - More efficient than scroll listeners
2. **Set Appropriate Offsets** - Balance visibility with performance
3. **Use Once for Performance** - Set `once: true` for elements that don't need to re-animate
4. **Throttle Updates** - Use appropriate throttle delays
5. **Clean Up** - Remove animations when elements are removed

---

## Browser Support

- **Chrome/Edge**: 90+
- **Firefox**: 88+
- **Safari**: 14+
- **Mobile**: iOS 14+, Android Chrome 90+

**Required Features**:
- ES2020 JavaScript
- IntersectionObserver (for efficient detection)
- requestAnimationFrame (for smooth animations)

---

**Next**: Continue with remaining modules →