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

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

<!-- 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

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

Zoom-In

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

Parallax

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

Timeline

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

Sticky Fade

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

Sticky Steps

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

---

HTML Data Attributes

Auto-Initialization

The system automatically initializes animations based on HTML attributes:

<!-- 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:

<!-- 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:

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

After:

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:

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

After:

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 →