@wix/interact 1.93.0 → 2.0.0-rc.4

package/docs/guides/understanding-triggers.md

@@ -0,0 +1,690 @@
+# Understanding Triggers
+
+Triggers are the heart of `@wix/interact` - they define when an interaction should start. This guide covers all 9 trigger types and how to use them effectively.
+
+## Overview of Trigger Types
+
+| Trigger | Description | Use Cases |
+|---------|-------------|-----------|
+| `hover` | Mouse enter/leave events | Button highlights, image overlays |
+| `click` | Mouse click events | Toggles, state changes, menus |
+| `interest` | Accessibility-friendly hover (focus events) 
+| `activate` | Accessibility-friendly click (keyboard Enter/Space) 
+| `viewEnter` | Element enters viewport | Entrance animations, lazy loading |
+| `pageVisible` | Page becomes visible | Loop animations, Auto-play videos |
+| `animationEnd` | Previous animation completes | Animation sequences, chaining |
+| `viewProgress` | Scroll progress through element | Parallax, progress bars |
+| `pointerMove` | Mouse movement over element | Interactive cards, 3D effects |
+
+## 1. Hover Trigger
+
+The `hover` trigger responds to mouse enter and leave events.
+
+### Basic Usage
+```typescript
+{
+    key: 'my-button',
+    trigger: 'hover',
+    effects: [
+        {
+            keyframeEffect: {
+                name: 'scale',
+                keyframes: [
+                    { scale: 2 }
+                ]
+            },
+            duration: 200
+        }
+    ]
+}
+```
+
+### Advanced Options
+```typescript
+{
+    key: 'my-card',
+    trigger: 'hover',
+    params: {
+        type: 'alternate'
+    },
+    effects: [
+        {
+            keyframeEffect: {
+                name: 'shadow',
+                keyframes: [
+                    { transform: 'scale(1)', boxShadow: 'none' },
+                    { transform: 'scale(1.05)', boxShadow: '0 10px 20px rgba(0,0,0,0.1)' }
+                ]
+            },
+            duration: 300,
+            easing: 'ease-out'
+        }
+    ]
+}
+```
+
+### Hover Behavior Types
+- **`alternate`** (default): Plays forward on enter, reverses on leave
+- **`repeat`**: Restarts animation each time
+- **`once`**: Only plays once, then stops
+- **`state`**: Pauses/resumes on hover
+
+### Real-World Example: Image Overlay
+```typescript
+{
+    key: 'image-card',
+    trigger: 'hover',
+    params: { type: 'alternate' },
+    effects: [
+        {
+            key: 'image-overlay',
+            keyframeEffect: {
+                name: 'slide-hover',
+                keyframes: [
+                    { opacity: '0', transform: 'translateY(20px)' },
+                    { opacity: '1', transform: 'translateY(0)' }
+                ]
+            },
+            duration: 250,
+            easing: 'ease-out'
+        }
+    ]
+}
+```
+
+## 2. Click Trigger
+
+The `click` trigger responds to mouse click events and supports multiple behavior modes.
+
+### Basic Usage
+```typescript
+{
+    key: 'toggle-button',
+    trigger: 'click',
+    effects: [
+        {
+            key: 'sidebar',
+            keyframeEffect: {
+                name: 'sidebar-toggle',
+                keyframes: [
+                    { transform: 'translateX(-100%)' },
+                    { transform: 'translateX(0)' }
+                ]
+            },
+            duration: 300
+        }
+    ]
+}
+```
+
+### Click Behavior Types
+```typescript
+{
+    key: 'accordion-header',
+    trigger: 'click',
+    params: {
+        type: 'alternate' 
+    },
+    effects: [
+        {
+            key: 'accordion-content',
+            keyframeEffect: {
+                name: 'accordion',
+                keyframes: [
+                    { clipPath: 'inset(0 0 100% 0)', translate: '0 -100%' },
+                    { clipPath: 'inset(0 0 0 0)', translate: '0 0' }
+                ]
+            },
+            duration: 400
+        }
+    ]
+}
+```
+
+- **`alternate`** (default): First click plays forward, subsequent click reverses
+- **`repeat`**: Each click restarts the animation
+- **`once`**: Only responds to the first click
+- **`state`**: First click plays, subsequent clicks pause/resume
+
+### Real-World Example: Menu Toggle
+```typescript
+{
+    key: 'menu-button',
+    trigger: 'click',
+    params: { type: 'alternate' },
+    effects: [
+        {
+            key: 'menu-icon',
+            keyframeEffect: {
+                name: 'spin',
+                keyframes: [
+                    { transform: 'rotate(0deg)' },
+                    { transform: 'rotate(45deg)' }
+                ]
+            },
+            duration: 200,
+            effectId: 'menu-icon-rotate'
+        },
+        {
+            key: 'mobile-menu',
+            keyframeEffect: {
+                name: 'slide',
+                keyframes: [
+                    { opacity: '0', transform: 'translateX(100%)' },
+                    { opacity: '1', transform: 'translateX(0)' }
+                ]
+            },
+            duration: 300,
+            delay: 100
+        }
+    ]
+}
+```
+
+## 3. Interest Trigger
+
+The `interest` trigger is an accessibility-friendly version of `hover` that responds to both mouse hover and keyboard focus events. This makes interactions accessible to keyboard users and screen reader users.
+
+### Basic Usage
+```typescript
+{
+    key: 'my-button',
+    trigger: 'interest',
+    effects: [
+        {
+            keyframeEffect: {
+                name: 'scale',
+                keyframes: [
+                    { scale: 2 }
+                ]
+            },
+            duration: 200
+        }
+    ]
+}
+```
+
+### How It Works
+- **Mouse users**: Triggers on `mouseenter` and `mouseleave` events (same as `hover`)
+- **Keyboard users**: Triggers on `focusin` and `focusout` events
+- Automatically sets `tabIndex={0}` on the element to make it keyboard-focusable
+
+## 4. Activate Trigger
+
+The `activate` trigger is an accessibility-friendly version of `click` that responds to both mouse clicks and keyboard activation (Enter/Space keys). This makes click interactions accessible to keyboard users.
+
+### Basic Usage
+```typescript
+{
+    key: 'toggle-button',
+    trigger: 'activate',
+    effects: [
+        {
+            key: 'sidebar',
+            keyframeEffect: {
+                name: 'sidebar-toggle',
+                keyframes: [
+                    { transform: 'translateX(-100%)' },
+                    { transform: 'translateX(0)' }
+                ]
+            },
+            duration: 300
+        }
+    ]
+}
+```
+
+### How It Works
+- **Mouse users**: Triggers on `click` events (same as `click`)
+- **Keyboard users**: Triggers on `keydown` events for Enter and Space keys
+- Automatically sets `tabIndex={0}` on the element to make it keyboard-focusable
+
+## 5. ViewEnter Trigger
+
+The `viewEnter` trigger uses Intersection Observer to detect when elements enter the viewport.
+
+### Basic Usage
+```typescript
+{
+    key: 'section-title',
+    trigger: 'viewEnter',
+    effects: [
+        {
+            key: 'section-title',
+            namedEffect: 'FadeIn',
+            duration: 800
+        }
+    ]
+}
+```
+
+### Advanced Configuration
+```typescript
+{
+    key: 'hero-image',
+    trigger: 'viewEnter',
+    params: {
+        type: 'once',        // 'once' | 'repeat' | 'alternate'
+        threshold: 0.5,      // 0-1, how much of element must be visible
+        inset: '-50px'        // Margin around viewport
+    },
+    effects: [
+        {
+            key: 'hero-image',
+            keyframeEffect: {
+                name: 'slide-in',
+                keyframes: [
+                    { opacity: '0', transform: 'translateY(50px)' },
+                    { opacity: '1', transform: 'translateY(0)' }
+                ]
+            },
+            duration: 1000,
+            easing: 'ease-out'
+        }
+    ]
+}
+```
+
+### ViewEnter Behavior Types
+- **`once`** (recommended): Triggers only when element first enters viewport
+- **`repeat`**: Triggers every time element enters viewport
+- **`alternate`**: Plays forward on enter, reverses on exit
+
+### Real-World Example: Staggered Card Animation
+```typescript
+// Configure multiple cards with delays
+const cardAnimations = [
+    {
+        key: 'card-1',
+        trigger: 'viewEnter',
+        params: { type: 'once', threshold: 0.3 },
+        effects: [{
+            key: 'card-1',
+            keyframeEffect: {
+                name: 'slide-up',
+                keyframes: [
+                    { opacity: '0', transform: 'translateY(30px)' },
+                    { opacity: '1', transform: 'translateY(0)' }
+                ]
+            },
+            duration: 600,
+            delay: 0,
+            easing: 'ease-out'
+        }]
+    },
+    {
+        key: 'card-2',
+        trigger: 'viewEnter',
+        params: { type: 'once', threshold: 0.3 },
+        effects: [{
+            key: 'card-2',
+            keyframeEffect: {
+                name: 'slide-up',
+                keyframes: [
+                    { opacity: '0', transform: 'translateY(30px)' },
+                    { opacity: '1', transform: 'translateY(0)' }
+                ]
+            },
+            duration: 600,
+            delay: 100,
+            easing: 'ease-out'
+        }]
+    }
+];
+```
+
+## 6. PageVisible Trigger
+
+TBD
+
+## 7. ViewProgress Trigger
+
+The `viewProgress` trigger creates scroll-driven animations as elements move through the viewport.
+
+### Basic Usage
+```typescript
+{
+    key: 'parallax-element',
+    trigger: 'viewProgress',
+    effects: [
+        {
+            key: 'parallax-element',
+            keyframeEffect: {
+                name: 'parallax',
+                keyframes: [
+                    { transform: 'translateY(0)' },
+                    { transform: 'translateY(-100px)' }
+                ]
+            }
+            // Note: viewProgress uses ranges, not duration
+        }
+    ]
+}
+```
+
+### Advanced Parallax Effect
+```typescript
+{
+    key: 'hero-section',
+    trigger: 'viewProgress',
+    effects: [
+        {
+            key: 'background-image',
+            keyframeEffect: {
+                name: 'grayscale',
+                keyframes: [
+                    { filter: 'grayscale(0)' },
+                    { filter: 'grayscale(100%)' }
+                ]
+            },
+            rangeStart: { name: 'exit', offset: { type: 'percentage', value: 0 } },
+            rangeEnd: { name: 'exit', offset: { type: 'percentage', value: 100 } }
+        },
+        {
+            key: 'foreground-text',
+            keyframeEffect: {
+                name: 'fade-zoom',
+                keyframes: [
+                    { opacity: '1', transform: 'scale(1)' },
+                    { opacity: '0', transform: 'scale(0.8)' }
+                ]
+            },
+            rangeStart: { name: 'exit', offset: { type: 'percentage', value: 0 } },
+            rangeEnd: { name: 'exit', offset: { type: 'percentage', value: 100 } }
+        }
+    ]
+}
+```
+
+### Real-World Example: Reading Progress Bar
+```typescript
+{
+    key: 'article-content',
+    trigger: 'viewProgress',
+    effects: [
+        {
+            key: 'progress-bar',
+            keyframeEffect: {
+                name: 'progress-animation',
+                keyframes: [
+                    { transform: 'scaleX(0)' },
+                    { transform: 'scaleX(1)' }
+                ]
+            },
+            rangeStart: { name: 'cover', offset: { type: 'percentage', value: 0 } },
+            rangeEnd: { name: 'cover', offset: { type: 'percentage', value: 100 } }
+        }
+    ]
+}
+```
+
+## 8. PointerMove Trigger
+
+The `pointerMove` trigger creates mouse-following effects and 3D interactions.
+
+### Basic Usage
+```typescript
+{
+    key: 'interactive-card',
+    trigger: 'pointerMove',
+    effects: [
+        {
+            key: 'interactive-card',
+            keyframeEffect: {
+                name: 'tilt-card',
+                keyframes: [
+                    { transform: 'perspective(800px) rotateX(40deg) rotateY(-40deg)' },
+                    { transform: 'perspective(800px) rotateX(-40deg) rotateY(40deg)' }
+                ]
+            }
+        }
+    ]
+}
+```
+
+### Advanced Configuration
+```typescript
+{
+    key: 'card-section',
+    trigger: 'pointerMove',
+    params: {
+        hitArea: 'self'  // 'self' | 'root'
+    },
+    effects: [
+        {
+            key: 'tilt-card',
+            keyframeEffect: {
+                name: 'tilt-card',
+                keyframes: [
+                    { transform: 'perspective(800px) rotateX(40deg) rotateY(-40deg)' },
+                    { transform: 'perspective(800px) rotateX(-40deg) rotateY(40deg)' }
+                ]
+            },
+            centeredToTarget: true // will place 50% point at center of animation target
+        }
+    ]
+}
+```
+
+### Real-World Example: 3D Product Card
+```typescript
+{
+    key: 'product-card',
+    trigger: 'pointerMove',
+    params: { hitArea: 'self' },
+    effects: [
+        {
+            key: 'tilt-card',
+            keyframeEffect: {
+                name: 'tilt-card',
+                keyframes: [
+                    { transform: 'perspective(800px) rotateX(40deg) rotateY(-40deg)' },
+                    { transform: 'perspective(800px) rotateX(-40deg) rotateY(40deg)' }
+                ]
+            },
+            centeredToTarget: true // will place 50% point at center of animation target
+        }
+    ]
+}
+```
+
+## 9. AnimationEnd Trigger
+
+The `animationEnd` trigger allows you to chain animations by waiting for a previous animation to complete.
+
+### Basic Usage
+```typescript
+// First animation
+{
+    key: 'sequence-start',
+    trigger: 'click',
+    effects: [
+        {
+            key: 'first-element',
+            namedEffect: {
+                type: 'FadeIn'
+            },
+            duration: 500,
+            effectId: 'fade-in-first'  // Required for chaining
+        }
+    ]
+},
+// Chained animation
+{
+    key: 'first-element',
+    trigger: 'animationEnd',
+    params: {
+        effectId: 'fade-in-first'  // Must match the effectId above
+    },
+    effects: [
+        {
+            key: 'second-element',
+            namedEffect: {
+                type: 'SlideIn'
+            },
+            duration: 500,
+            effectId: 'slide-in-second'
+        }
+    ]
+}
+```
+
+### Real-World Example: Loading Sequence
+```typescript
+const loadingSequence = [
+    {
+        key: 'app-logo',
+        trigger: 'viewEnter',
+        effects: [{
+            key: 'app-logo',
+            namedEffect: {
+                type: 'FadeIn'
+            },
+            duration: 800,
+            effectId: 'logo-appear'
+        }]
+    },
+    {
+        key: 'app-logo',
+        trigger: 'animationEnd',
+        params: { effectId: 'logo-appear' },
+        effects: [{
+            key: 'loading-text',
+            keyframeEffect: {
+                name: 'slide-up',
+                keyframes: [
+                    { opacity: '0', transform: 'translateY(20px)' },
+                    { opacity: '1', transform: 'translateY(0)' }
+                ]
+            },
+            duration: 600,
+            easing: 'ease-out',
+            effectId: 'text-appear'
+        }]
+    },
+    {
+        key: 'loading-text',
+        trigger: 'animationEnd',
+        params: { effectId: 'text-appear' },
+        effects: [{
+            key: 'main-content',
+            namedEffect: {
+                type: 'FadeIn'
+            },
+            duration: 1000
+        }]
+    }
+];
+```
+
+## Combining Triggers
+
+You can combine multiple triggers on the same element for complex interactions:
+
+```typescript
+{
+    interactions: [
+        // Entrance animation
+        {
+            key: 'interactive-card',
+            trigger: 'viewEnter',
+            params: { type: 'once' },
+            effects: [{
+                key: 'interactive-card',
+                namedEffect: {
+                    type: 'FadeIn'
+                },
+                duration: 800
+            }]
+        },
+        // Hover effect
+        {
+            key: 'interactive-card',
+            trigger: 'hover',
+            effects: [{
+                key: 'interactive-card',
+                keyframeEffect: {
+                    name: 'shadow',
+                    keyframes: [
+                        { transform: 'scale(1)', boxShadow: 'none' },
+                        { transform: 'scale(1.02)', boxShadow: '0 20px 40px rgba(0 0 0 / 0.1)' }
+                    ]
+                },
+                duration: 200,
+                easing: 'ease-out'
+            }]
+        },
+        // Click action
+        {
+            key: '#interactive-card',
+            trigger: 'click',
+            effects: [{
+                key: 'card-details',
+                keyframeEffect: {
+                    name: 'slide-down',
+                    keyframes: [
+                        { opacity: '0', transform: 'translateY(-20px)' },
+                        { opacity: '1', transform: 'translateY(0)' }
+                    ]
+                },
+                duration: 400,
+                easing: 'ease-out'
+            }]
+        }
+    ]
+}
+```
+
+## Best Practices
+
+### Performance
+1. **Prefer animating hardware-accelerated properties**, i.e. transforms, opacity, and filters
+2. **Avoid animating layout properties**, these are the most costly properties to animate
+3. **Avoid animating custom properties**, since changing them via animation causes a style recalculation
+
+### User Experience
+1. **Keep hover animations short** (200-300ms) for responsiveness
+2. **Use meaningful delays** in animation sequences
+3. **Provide visual feedback** for click interactions
+4. **Set appropriate thresholds** for `viewEnter` to avoid premature triggers
+
+### Accessibility
+1. **Respect `prefers-reduced-motion`** media query
+2. **Use `activate` instead of `click`** for keyboard accessibility
+3. **Use `interest` instead of `hover`** for keyboard accessibility
+4. **Ensure click targets are accessible** via keyboard
+5. **Don't rely solely on motion** for important information
+6. **Enable accessibility triggers globally** using `Interact.setup({ allowA11yTriggers: true })` to make `click` and `hover` triggers keyboard-accessible
+
+## Troubleshooting
+
+### Common Issues
+
+**Trigger not firing:**
+- Check element exists when `Interact.create()` is called
+- Verify `data-interact-key` matches your CSS selector
+- Ensure element is actually visible for viewport triggers
+
+**Animation not smooth:**
+- Use `transform` and `opacity` properties
+- Avoid animating layout properties like `width`/`height`
+- Check for conflicting CSS transitions
+
+**ViewEnter not triggering**
+- Since entrance animations use `IntersectionObserver`, if the source element is clipped out, e.g: by a parent's `overflow`, or `clip-path`, or if it's pushed out of the viewport it may never trigger.
+  To avoid this either **use a separate target element form the source element, or avoid transforms/clip-path/mask at 0% progress**
+
+**ViewEnter triggering multiple times**
+- From same reasons as above, **Use `once` for `viewEnter` triggers**, if the source element is also the target element, since it may re-trigger animations multiple times when animating.
+
+**ViewEnter triggering too early/late:**
+- Adjust `threshold` and `inset` parameters
+- Test on different screen sizes
+- Consider content loading delays
+
+## Next Steps
+
+Now that you understand all trigger types, explore:
+- **[Effects and Animations](./effects-and-animations.md)** - Learn about animation options
+- **[Configuration Structure](./configuration-structure.md)** - Organize complex interactions
+- **[State Management](./state-management.md)** - Advanced state handling techniques