# Animation Controls - Complete Documentation

This is the comprehensive documentation for the Linchpin Blocks animation controls system, covering all features, implementation details, and user guides.

## 📚 Table of Contents

1. [Overview & Features](#overview--features)
2. [User Guide](#user-guide)
3. [Animation Types & Controls](#animation-types--controls)
4. [Advanced Features](#advanced-features)
5. [Interactive Guide System](#interactive-guide-system)
6. [Frontend Implementation](#frontend-implementation)
7. [Developer Documentation](#developer-documentation)
8. [Performance & Accessibility](#performance--accessibility)

---

## Overview & Features

### **What is Animation Controls?**

The Animation Controls system provides comprehensive GSAP animation capabilities for WordPress blocks, including:

- **13+ Animation Types**: Fade, Slide, Scale, Rotate, Reveal, Zoom, Custom
- **ScrollTrigger Integration**: Complete ScrollTrigger support with pinning and snapping
- **Child Animation System**: 5 patterns for animating child elements
- **Preset Management**: Save, load, and share animation configurations
- **Copy/Paste Functionality**: Transfer settings between blocks
- **Interactive Guide**: 7-step walkthrough for new users
- **Performance Optimized**: Lazy loading, GPU acceleration, accessibility support

### **Supported Blocks**
- `core/group` - Group blocks
- `core/row` - Row blocks  
- `core/columns` - Column blocks
- `core/stack` - Stack blocks
- `core/grid` - Grid blocks
- `core/cover` - Cover blocks
- `core/column` - Individual columns

---

## User Guide

### **Getting Started**

1. **Select a supported block** in the WordPress editor
2. **Open the block settings sidebar** (Inspector Controls)
3. **Find the "Block Animation" panel** - it will auto-open when animations are enabled
4. **Configure your animations** using the three main tabs:
   - **Animate In**: Entrance animations and ScrollTrigger settings
   - **Animate Out**: Exit animations and toggle actions
   - **Pin**: Pinning and snap settings

### **Basic Animation Setup**

#### **Animate In (Entrance Animations)**
1. **Enable Animation**: Toggle the "Enable Animation" switch
2. **Choose Animation Type**: Select from 13+ preset types or Custom
3. **Set Timing**: Configure duration, delay, and easing
4. **ScrollTrigger Options**: Enable scrubbing and set trigger positions
5. **Child Animations**: Enable to animate child elements individually

#### **Animate Out (Exit Animations)**
1. **Enable Animate Out**: Toggle the "Enable Animate Out" switch
2. **Choose Out Animation Type**: Select from 13+ exit animation types
3. **Set Out Timing**: Configure duration, delay, and easing
4. **Set Offset**: Define when out animation should start
5. **Child Out Animations**: Enable to animate children when exiting

#### **Pin Controls (Sticky Effects)**
1. **Enable Pinning**: Toggle the "Enable Pinning" switch
2. **Choose Pin Type**: Fixed (performance) or Transform (nested elements)
3. **Configure Pin Options**: Spacing, anticipate pin, reparent settings
4. **Advanced Options**: Custom containers, spacer classes
5. **Snap Settings**: Configure scroll snapping behavior

### **Visual Indicators**

When animations are enabled, you'll see:
- **Blue Play Button**: On animated blocks (click to preview)
- **Animation Badges**: In/Out animation type indicators
- **Magenta Pin Icon**: On pinned blocks
- **Child Indicators**: Shows linked child animations

### **Smart Panel Behavior**
- **Auto-Open**: Panel opens when animations are enabled
- **Dynamic Title**: Shows current animation status
- **Intelligent Tabs**: Auto-selects relevant tab
- **Visual Feedback**: Green status indicators, animation summaries

---

## Animation Types & Controls

### **Animation Types**

#### **Entrance Animations (Animate In)**
1. **Fade In** - Simple opacity transition
2. **Slide In Up/Down/Left/Right** - Movement with opacity
3. **Scale In** - Scale and opacity transition
4. **Rotate In** - Rotation with opacity
5. **Reveal Left/Right** - Column-based reveals
6. **Reveal Inward/Outward** - Alternating column reveals
7. **Zoom In** - Center-based scale reveal
8. **Custom** - User-defined transform values

#### **Exit Animations (Animate Out)**
1. **Fade Out** - Simple opacity transition
2. **Slide Out Up/Down/Left/Right** - Movement with opacity
3. **Scale Out** - Scale and opacity transition
4. **Rotate Out** - Rotation with opacity
5. **Reveal Out Left/Right** - Column-based reveals
6. **Reveal Outward/Inward** - Alternating column reveals
7. **Zoom Out** - Center-based scale reveal
8. **Custom** - User-defined transform values

### **Timing & Easing Controls**

#### **Duration & Delay**
- **Duration**: 0.1-10 seconds with 0.1 step precision
- **Delay**: 0-5 seconds with 0.1 step precision
- **Stagger**: Delay between child element animations
- **Out Timing**: Independent timing for exit animations

#### **Easing Functions**
- **Power Easing**: Power1-4 with In/Out/InOut variants
- **Back Easing**: Overshoot effects with In/Out/InOut
- **Elastic Easing**: Bouncy effects with In/Out/InOut
- **Bounce Easing**: Bounce effects with In/Out/InOut
- **Linear**: No easing (none option)

### **Custom Transform Controls**

When "Custom" animation type is selected:
- **Position (X/Y)**: Horizontal and vertical positioning
- **Scale**: Size transformation (0.1-5x)
- **Rotation**: Rotation in degrees (-360 to 360)
- **Opacity**: Transparency (0-1)
- **From/To Values**: Initial and target states
- **Out From/To Values**: Exit animation states

---

## Advanced Features

### **ScrollTrigger Integration**

#### **Trigger Configuration**
- **Start Position**: Define when animation begins (e.g., "top 80%")
- **End Position**: Define when animation ends (e.g., "bottom 20%")
- **Scrub Animation**: Link animation progress to scroll position
- **Scrub Smoothness**: Control scrubbing responsiveness (0.1-5)
- **Auto Refresh**: Automatically refresh on layout changes

#### **Toggle Actions**
- **Enter Actions**: What happens when entering trigger zone
- **Leave Actions**: What happens when leaving trigger zone
- **Enter Back Actions**: What happens when re-entering from above
- **Leave Back Actions**: What happens when re-leaving from below

### **Child Animation System**

#### **Animation Patterns**
1. **Staggered** - One after another with delay
2. **All At Once** - Simultaneous animation
3. **Sequential** - Same as staggered
4. **Alternating** - Every other element
5. **Random** - Random order animation

#### **Child Animation Controls**
- **Animate Children**: Enable child element animation
- **Child Animation Type**: Independent animation type for children
- **Child Animation Pattern**: How children are animated
- **Child Delay**: Delay between each child animation
- **Reverse Child Order**: Animate from last to first
- **Child Out Animations**: Separate exit animations for children

### **Pin & Snap Features**

#### **Pin Settings**
- **Pin Enable/Disable**: Master pin control
- **Pin Type**: Fixed (performance) vs Transform (nested elements)
- **Pin Spacing**: Control content flow around pinned elements
- **Anticipate Pin**: Prevent visual jumps
- **Pin Reparent**: Handle overflow issues
- **Custom Containers**: Pin within specific containers
- **Pin Spacer Classes**: Custom CSS for spacer elements

#### **Snap Settings**
- **Snap Type**: None, Mandatory, or Proximity
- **Snap Duration**: Animation duration for snap (0.1-5s)
- **Snap Delay**: Delay before snap starts (0-2s)
- **Snap Ease**: Easing function for snap animation
- **Directional Snap**: Only snap in trigger direction

### **Preset Management**

#### **Save Presets**
- **Preset Naming**: Custom names for saved presets
- **Complete Settings**: Saves all animation attributes
- **REST API Integration**: Server-side preset storage
- **User-Specific**: Presets tied to user accounts

#### **Load Presets**
- **Preset Selection**: Dropdown of saved presets
- **Preview Modal**: See preset details before applying
- **Settings Summary**: Visual breakdown of preset settings
- **Apply Functionality**: One-click preset application
- **Delete Presets**: Remove unwanted presets

### **Copy/Paste Functionality**

#### **Copy Settings**
- **JSON Export**: Complete animation settings as JSON
- **Clipboard Integration**: One-click copy to clipboard
- **Validation**: Only copies when animations are enabled
- **Success Feedback**: Confirmation notifications

#### **Paste Settings**
- **JSON Import**: Paste animation settings from JSON
- **Modal Interface**: User-friendly paste interface
- **Error Handling**: Validation and error messages
- **Success Feedback**: Confirmation of successful application

---

## Interactive Guide System

### **7-Step Walkthrough**

The system includes an interactive guide that automatically appears for first-time users:

1. **Welcome**: Introduction to animation controls
2. **Animate In**: Entrance animation features
3. **Animate Out**: Exit animation features
4. **Pinning**: Sticky scroll effects
5. **Scroll Scrubbing**: Scroll-linked animations
6. **Advanced Features**: Snap and advanced options
7. **Getting Started**: Quick start guide

### **Guide Features**
- **Smart Auto-Display**: Shows when first enabling animations
- **Session Management**: Only shows once per session
- **Permanent Dismissal**: Option to never show again
- **Manual Access**: Always available via More Tools menu
- **Card-Based Layout**: Visual, engaging content with hover effects

### **Accessing the Guide**
- **Automatic**: Shows when first enabling any animation feature
- **Manual**: Click three dots (⋮) in editor toolbar → "Show Animation Features Guide"
- **Persistent**: Available even after permanent dismissal

---

## Frontend Implementation

### **How It Works**

#### **Block Rendering (PHP)**
When blocks are rendered on the frontend, animation data is injected as HTML attributes:

```html
<div class="wp-block-group" 
     data-animation-enabled="true"
     data-animation-type="slideInUp" 
     data-animation-duration="1"
     data-animation-delay="0.5"
     data-animation-ease="power2.out">
  <!-- Block content -->
</div>
```

#### **Animation Execution (JavaScript)**
The frontend script handles animation execution:

1. **Waits for GSAP library** to be available
2. **Registers ScrollTrigger plugin** if needed
3. **Finds all animated elements** via data attributes
4. **Initializes animations** for each element

#### **Animation Types**
- **In-View Animations**: Uses Intersection Observer API
- **Scroll-Based Animations**: Uses GSAP ScrollTrigger plugin
- **Child Animations**: Supports all 5 animation patterns
- **Pin & Snap**: Complete ScrollTrigger pinning and snapping

### **Performance Optimizations**
- **Lazy Loading**: Assets only load when needed
- **GPU Acceleration**: Hardware-accelerated animations
- **Efficient Triggers**: Optimized ScrollTrigger usage
- **Memory Management**: Proper cleanup and disposal

### **Browser Support**
- **Modern Browsers**: Chrome, Firefox, Safari, Edge
- **Mobile Support**: iOS and Android browsers
- **Progressive Enhancement**: Works without JavaScript
- **Accessibility**: Respects user motion preferences

---

## Developer Documentation

### **Extending Supported Blocks**

Add animation support to custom blocks:

```javascript
import { addFilter } from '@wordpress/hooks';

addFilter(
    'linchpin.animationControls.supportedBlocks',
    'my-plugin/add-animation-blocks',
    (blocks) => {
        return [
            ...blocks,
            'my-plugin/custom-block',
            'core/image',
            'core/heading'
        ];
    }
);
```

### **Animation Type Filtering**

Control which animation types are available:

```php
add_filter( 'linchpin_blocks_enabled_animation_types', function( $enabled_types, $all_defaults ) {
    return [
        'fadeIn',
        'fadeOut',
        'slideInUp',
        'slideInDown',
    ];
}, 10, 2 );
```

### **Technical Architecture**

#### **Modular Design**
- **Component-Based**: Reusable React components
- **Utility Functions**: Shared animation logic
- **Hook System**: Custom hooks for common functionality
- **Filter Integration**: WordPress filter system

#### **Code Organization**
- **Separation of Concerns**: Clear responsibility boundaries
- **Maintainability**: Easy to modify and extend
- **Testability**: Individual components can be tested
- **Documentation**: Comprehensive inline documentation

#### **WordPress Integration**
- **Block Editor**: Native block editor integration
- **REST API**: Server-side preset management
- **User Meta**: Persistent user preferences
- **Asset Management**: Efficient script and style loading

---

## Performance & Accessibility

### **Performance Optimizations**
- **Lazy Loading**: Assets only load when needed
- **GPU Acceleration**: Hardware-accelerated animations
- **Efficient Triggers**: Optimized ScrollTrigger usage
- **Memory Management**: Proper cleanup and disposal

### **Accessibility Features**
- **Reduced Motion**: Respects `prefers-reduced-motion`
- **Keyboard Navigation**: Full keyboard support
- **Screen Reader**: Proper ARIA labels and descriptions
- **Focus Management**: Clear focus indicators

### **Browser Compatibility**
- **Modern Browsers**: Chrome, Firefox, Safari, Edge
- **Mobile Support**: iOS and Android browsers
- **Progressive Enhancement**: Works without JavaScript
- **Fallback Support**: Graceful degradation

---

## Troubleshooting

### **Common Issues**

#### **Animations not running:**
1. Check if GSAP is loaded: `console.log(window.gsap)`
2. Verify data attributes in HTML
3. Check browser console for errors
4. Ensure blocks have animation enabled in editor

#### **ScrollTrigger animations not working:**
1. Verify ScrollTrigger plugin is loaded
2. Check start/end position values
3. Ensure trigger element exists
4. Test without scrub first

#### **Performance issues:**
1. Reduce number of animated elements
2. Use simpler animations
3. Check for conflicting CSS animations
4. Test on lower-end devices

### **Debugging Tools**
- **ScrollTrigger Markers**: Enable in development
- **Browser DevTools**: Inspect data attributes and performance
- **Console Warnings**: Check for missing dependencies
- **Network Tab**: Verify asset loading

---

## Future Enhancements

### **Planned Features**
- **Animation Templates**: Pre-built animation combinations
- **Batch Operations**: Apply settings to multiple blocks
- **Animation Library**: Curated animation collections
- **Advanced Easing**: Custom easing function editor
- **Animation Timeline**: Visual timeline editor
- **Performance Analytics**: Animation performance metrics

### **Extensibility**
- **Plugin API**: Third-party animation extensions
- **Custom Presets**: User-defined preset categories
- **Animation Events**: JavaScript events for animations
- **Advanced Triggers**: Custom trigger conditions

---

This comprehensive documentation covers all aspects of the Linchpin Blocks animation controls system, providing both users and developers with complete information about available functionality.