# Animation System Migration Guide

**Complete Migration Guide from Old Scroll Animation Modules to Unified Animation System**

This guide helps you migrate from the old scroll animation modules to the new unified Animation System.

---

## Overview

The Animation System consolidates 8 separate modules into one unified system:

- `scrollfx` → `AnimationSystem` (fade-in, zoom-in)
- `parallax` → `AnimationSystem` (parallax)
- `scroll-timeline` → `AnimationSystem` (timeline)
- `scroll-loop` → `AnimationSystem` (timeline with loop)
- `scroll-dependent` → `AnimationSystem` (dependent animations)
- `sticky-fade` → `AnimationSystem` (sticky-fade)
- `sticky-steps` → `AnimationSystem` (sticky-steps)
- `smooth-scroll` → Keep separate (different purpose)

---

## Migration Steps

### 1. Update Imports

**Before**:
```javascript
import { createTrigger } from './modules/scrollfx/index.js';
import { init as initParallax } from './modules/parallax/index.js';
```

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

### 2. Update Initialization

**Before**:
```javascript
createTrigger({ element: '.fade-in', offset: 0.85 });
initParallax({ selector: '.parallax' });
```

**After**:
```javascript
const system = AnimationSystem.create();
// Auto-initializes based on HTML attributes
// Or manually:
document.querySelectorAll('.fade-in').forEach(el => {
    system.registerAnimation(el, { type: 'fade-in', offset: 0.85 });
});
```

### 3. Update HTML Attributes

Most HTML attributes remain compatible, but you can use new unified attributes:

**Before**:
```html
<div class="fade-in-on-scroll" data-offset="0.85">Content</div>
<div class="parallax" data-speed="0.5">Content</div>
```

**After** (still works, or use new format):
```html
<div data-animate="fade-in" data-offset="0.85">Content</div>
<div data-parallax data-speed="0.5">Content</div>
```

---

## Module-Specific Migrations

### scrollfx → AnimationSystem

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

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

### parallax → AnimationSystem

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

**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
    });
});
```

### scroll-timeline → AnimationSystem

**Before**:
```javascript
import { init } from './modules/scroll-timeline/index.js';
init({ attribute: 'data-scroll-step', triggerPoint: 0.4 });
```

**After**:
```javascript
import { AnimationSystem } from './modules/animation-system/index.js';
const system = AnimationSystem.create();
document.querySelectorAll('[data-scroll-step]').forEach(el => {
    system.registerAnimation(el, {
        type: 'timeline',
        steps: parseInt(el.dataset.scrollSteps) || null,
        triggerPoint: 0.4
    });
});
```

---

## Backward Compatibility

The Animation System maintains backward compatibility with existing HTML:

- Old CSS classes still work: `.fade-in-on-scroll`, `.zoom-in`, `.parallax`
- Old data attributes still work: `data-parallax`, `data-scroll-step`, etc.
- Old module initialization still works (but deprecated)

---

## Breaking Changes

1. **Module Exports** - Old module exports are deprecated
2. **JavaScript API** - Some APIs have changed (see migration examples)
3. **Configuration** - Some config options have been renamed

---

## Testing Checklist

- [ ] All fade-in animations work
- [ ] All parallax effects work
- [ ] All timeline animations work
- [ ] All sticky animations work
- [ ] Performance is acceptable
- [ ] No console errors
- [ ] Backward compatibility maintained

---

## Support

For issues or questions, see the main [Animation System documentation](animation-system.md).