# Interactive Guide System

An interactive, step-by-step guide that helps users understand and utilize the animation features in Linchpin Blocks. Uses WordPress's native `Guide` component for consistent UI.

> **📚 For complete user documentation, see [Animation Controls](./ANIMATION-CONTROLS.md)**

## Overview

The Animation Guide Modal provides a comprehensive walkthrough of all animation features including:
- Animate In (entrance animations)
- Animate Out (exit animations)
- Pinning (sticky scroll effects)
- Scroll Scrubbing & Triggers
- Snap & Advanced Features

## Features

### Multi-Step Walkthrough
- **7 comprehensive steps** covering all animation features
- **Progress indicators** showing current position in the guide
- **Next/Previous navigation** for easy step traversal
- **Finish button** on the last step to complete the guide

### Smart Auto-Display
The guide automatically appears when users:
1. First enable "Animate In" animation
2. First enable "Animate Out" animation  
3. First enable "Pin" functionality

The guide will **only show once per session** for users who haven't dismissed it permanently.

### User Controls
- **Animation Guide Panel**: A separate panel that appears in Inspector Controls when animation features are enabled
- **Show Animation Guide Button**: Click to open the interactive guide
- **Don't Show Again**: Checkbox on the final step to permanently dismiss auto-display
- **Close Button**: Available on every step to exit the guide
- **Persistent Access**: Users can always reopen the guide via the Animation Guide panel, even after dismissing

## Implementation

### Component Structure
Follows the same pattern as the Animation Block Guide:

```
src/animation-controls/components/guide/
├── index.js                  # Main guide component using WordPress Guide
├── step-wrapper.js           # Consistent wrapper for all steps
└── steps/
    ├── welcome.js           # Step 1: Welcome
    ├── animate-in.js        # Step 2: Animate In
    ├── animate-out.js       # Step 3: Animate Out
    ├── pinning.js           # Step 4: Pinning
    ├── scrub-trigger.js     # Step 5: Scroll Scrubbing
    ├── advanced.js          # Step 6: Advanced Features
    └── getting-started.js   # Step 7: Getting Started
```

### Integration
The guide is filtered into blocks with animation support via:
```
src/animation-controls/filters/wrapper-guide.js
src/animation-controls/components/animation-guide-control.js  # Wrapper component
src/animation-controls/components/more-menu/index.js          # Menu item
```

This follows the same pattern as the Animation Block Guide for visual consistency.

### Guide State Management
The guide uses the existing block guides system in:
```
src/block-guides.js
```

Guide ID: `linchpin-blocks/animation-features`

## Usage

### For Users

1. **Automatic Display**:
   - The guide appears automatically when you first enable any animation feature
   - It will not show again in the same session even if you close it
   - You can permanently dismiss it on the last step

2. **Manual Access**:
   - Find the "Animation Guide" panel in the Inspector Controls (block settings sidebar)
   - Click "Show Animation Guide" button
   - The guide will open at step 1
   - Navigate through all steps at your own pace

3. **Permanent Dismissal**:
   - Complete all steps to the final page
   - Check "Don't show this guide automatically again"
   - Click "Finish"
   - The guide won't auto-display again, but you can still access it via the Animation Guide panel

### For Developers

#### Opening the Guide Programmatically
```javascript
setIsGuideOpen(true);
```

#### Checking Guide Status
```javascript
if (window.linchpinBlocksGuides?.utils?.isGuideDismissed) {
    const isDismissed = window.linchpinBlocksGuides.utils.isGuideDismissed(
        'linchpin-blocks/animation-features'
    );
}
```

#### Dismissing Permanently
```javascript
if (window.linchpinBlocksGuides?.utils?.dismissGuide) {
    window.linchpinBlocksGuides.utils.dismissGuide(
        'linchpin-blocks/animation-features'
    );
}
```

## Guide Content Structure

### Step 1: Welcome
Introduction to animation controls and GSAP/ScrollTrigger

### Step 2: Animate In
- Entrance animations
- Preset animation types
- Duration, delay, easing
- Child animations with stagger
- Scroll scrubbing

### Step 3: Animate Out
- Exit animations
- Independent configuration
- ScrollTrigger integration
- Combination with Animate In

### Step 4: Pinning
- Sticky scroll effects
- Pin types (Fixed vs Transform)
- Pin spacing and advanced options
- Combining with scrubbing

### Step 5: Scroll Scrubbing & Triggers
- What is scrubbing
- Start/End positions
- Scrub smoothness
- Traditional vs scrubbed animations

### Step 6: Snap & Advanced
- Scroll snapping (Mandatory vs Proximity)
- Child animations
- Copy/Paste settings
- Preview functionality

### Step 7: Getting Started
- Quick start guide (5 steps)
- Resources and documentation
- Reminder about Help button access

## Styling

Custom styles are defined in:
```
src/animation-controls/editor-styles.scss
```

Key style features:
- Progress indicator bars
- Scrollable content area with custom scrollbar
- Properly styled lists and code blocks
- Responsive layout
- Clear visual hierarchy

## API Integration

The guide integrates with the WordPress REST API through the block guides system:

### Endpoints Used
- `GET /linchpin-blocks/v1/block-guides/status` - Check guide dismissal status
- `POST /linchpin-blocks/v1/block-guides/dismiss` - Permanently dismiss guide

### Nonce Verification
All API calls use the WordPress nonce system:
```javascript
headers: {
    'X-WP-Nonce': window.linchpinBlocksGuides.apiNonce,
}
```

## Best Practices

### For Content Updates
- Keep each step focused on a single topic
- Use clear, concise language
- Include examples and tips
- Maintain consistent formatting
- Test all links and code examples

### For Styling
- Follow WordPress design patterns
- Ensure readability on all screen sizes
- Use consistent spacing and typography
- Maintain accessibility standards

### For Functionality
- Test auto-display triggers
- Verify dismissal persists across sessions
- Ensure Help button always works
- Test all navigation controls

## Future Enhancements

Potential improvements:
- [ ] Add interactive demos within steps
- [ ] Include video tutorials
- [ ] Add tooltips for specific UI elements
- [ ] Create a quick reference card
- [ ] Add search functionality for guide content
- [ ] Track which steps users spend most time on
- [ ] Add keyboard navigation shortcuts

## Troubleshooting

### Guide Doesn't Auto-Display
1. Check if `window.linchpinBlocksGuides` is loaded
2. Verify API endpoints are accessible
3. Check browser console for errors
4. Clear WordPress transients/cache

### Dismissal Not Persisting
1. Verify nonce is valid
2. Check API endpoint permissions
3. Ensure user has proper capabilities
4. Check database for user meta storage

### Styling Issues
1. Clear asset cache
2. Rebuild JavaScript/CSS
3. Check for conflicting styles
4. Verify SCSS compilation

## Related Files

- **Guide Component**: `src/animation-controls/components/guide/index.js`
- **Step Wrapper**: `src/animation-controls/components/guide/step-wrapper.js`
- **Individual Steps**: `src/animation-controls/components/guide/steps/*.js`
- **Control Wrapper**: `src/animation-controls/components/animation-guide-control.js`
- **Menu Item**: `src/animation-controls/components/more-menu/index.js`
- **Filter Integration**: `src/animation-controls/filters/wrapper-guide.js`
- **Guide System**: `src/block-guides.js`
- **API Controller**: `includes/Controller/REST/Block_Guides.php` (backend)

## Support

For issues or questions about the animation guide:
1. Check this documentation
2. Review the inline code comments
3. Test in a clean WordPress environment
4. Check WordPress and browser console for errors