@wix/interact 2.0.3 → 2.1.0

package/rules/scroll-list.md

@@ -1,17 +1,12 @@
 # Scroll List Animation Rules for @wix/interact
 
-These rules help generate scroll-driven list animations using the `@wix/interact` library. List animations encompass sticky containers, sticky items, and their content animations, providing comprehensive patterns for modern scroll-driven list interactions including parallax effects, staggered reveals, and progressive content disclosure.
+Scroll-driven list animations using `@wix/interact`. Sticky hierarchy: **container** → **items** → **content**. Use `key` for container/item; use `selector` for content within an item.
 
 ## Rule 1: Sticky Container List Animations with Named Effects
 
-**Use Case**: Animations applied to list containers that are sticky-positioned within their wrapper, using pre-built named effects for smooth scroll-driven transformations (e.g., horizontal sliding galleries, parallax backgrounds, container reveals)
+**Use Case**: Sticky list containers with named effects (horizontal galleries, parallax backgrounds). Use `contain` range—animations run while the element is stuck in position.
 
-**When to Apply**:
-
-- For sticky container horizontal sliding during scroll
-- When creating parallax container effects
-- For container-level background transformations
-- When using pre-built motion effects for container animations
+**When to Apply**: Sticky container sliding, parallax, background transformations.
 
 **Pattern**:
 
@@ -34,13 +29,7 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 }
 ```
 
-**Variables**:
-
-- `[CONTAINER_KEY]`: Unique identifier for sticky list container
-- `[CONTAINER_NAMED_EFFECT]`: Container-level scroll effects ('BgParallax', 'PanScroll', 'MoveScroll', 'ParallaxScroll') or background effects ('BgPan', 'BgZoom', 'BgFade', 'BgReveal')
-- `[START_PERCENTAGE]`: Start point in contain range (typically 0)
-- `[END_PERCENTAGE]`: End point in contain range (typically 100)
-- `[UNIQUE_EFFECT_ID]`: Optional unique identifier
+**Variables**: `[CONTAINER_KEY]`, `[CONTAINER_NAMED_EFFECT]` ('BgParallax', 'PanScroll', 'MoveScroll', 'ParallaxScroll', 'BgPan', 'BgZoom', 'BgFade', 'BgReveal'), `[START_PERCENTAGE]`/`[END_PERCENTAGE]` (typically 0/100), `[UNIQUE_EFFECT_ID]`.
 
 **Example - Horizontal Sliding Gallery Container**:
 
@@ -88,14 +77,9 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 ## Rule 2: Sticky Item List Animations with Named Effects
 
-**Use Case**: Animations on individual list items that are sticky-positioned within the container, using named effects for entrance/exit animations as items enter sticky positioning (e.g., progressive item reveals, item transformation sequences)
+**Use Case**: Individual sticky list items with named effects for entrance/exit (progressive reveals, item transformations).
 
-**When to Apply**:
-
-- For item entrance/exit animations during sticky phases
-- When creating progressive item reveals
-- For individual item transformations
-- When using pre-built item-level effects
+**When to Apply**: Item entrance/exit during sticky phases, progressive item reveals.
 
 **Pattern**:
 
@@ -120,14 +104,13 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 **Variables**:
 
-- `[ITEM_KEY]`: Unique identifier for individual list items
-- `[ITEM_NAMED_EFFECT]`: Item-level scroll effects from @wix/motion-presets scroll animations:
+- `[ITEM_KEY]`: Individual list item identifier
+- `[ITEM_NAMED_EFFECT]`: Item-level scroll effects from @wix/motion-presets:
   - **Reveal/Fade**: 'FadeScroll', 'BlurScroll', 'RevealScroll', 'ShapeScroll', 'ShuttersScroll'
   - **Movement**: 'MoveScroll', 'SlideScroll', 'PanScroll', 'SkewPanScroll'
   - **Scale**: 'GrowScroll', 'ShrinkScroll', 'StretchScroll'
   - **Rotation**: 'SpinScroll', 'FlipScroll', 'TiltScroll', 'TurnScroll'
   - **3D**: 'ArcScroll', 'Spin3dScroll'
-- `[RANGE_TYPE]`: 'entry' for entrance, 'exit' for exit, 'contain' for during sticky, 'cover' for full scroll range
 - `[START_PERCENTAGE]`: Range start percentage (0-100)
 - `[END_PERCENTAGE]`: Range end percentage (0-100)
 - `[EASING_FUNCTION]`: Timing function
@@ -179,14 +162,9 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 ## Rule 3: Sticky Item List Content Animations with Named Effects
 
-**Use Case**: Animations on content within sticky list items, using named effects with each individual item being the viewProgress trigger (e.g., text reveals within cards, image animations within items, progressive content disclosure)
-
-**When to Apply**:
+**Use Case**: Content within sticky items; each item is the viewProgress trigger (text reveals in cards, image animations, progressive disclosure). Use `key` for the item, `selector` for content within.
 
-- For content animations within sticky items
-- When creating staggered content reveals
-- For text/image animations inside list items
-- When coordinating multiple content elements
+**When to Apply**: Content within sticky items, staggered content reveals, text/image animations inside list items.
 
 **Pattern**:
 
@@ -211,15 +189,13 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 **Variables**:
 
-- `[ITEM_CONTAINER_KEY]`: Unique identifier for the containing list item
-- `[CONTENT_KEY]`: Unique identifier for content within the item (or use `selector` for CSS selector)
+- `[ITEM_CONTAINER_KEY]` / `[CONTENT_KEY]`: Item and content identifiers. Use `selector` (e.g. `selector: '.content-text'`) for content within the item.
 - `[CONTENT_NAMED_EFFECT]`: Content-level scroll effects from @wix/motion-presets:
   - **Opacity/Visibility**: 'FadeScroll', 'BlurScroll'
   - **Reveal**: 'RevealScroll', 'ShapeScroll', 'ShuttersScroll'
   - **3D Transforms**: 'TiltScroll', 'FlipScroll', 'ArcScroll', 'TurnScroll', 'Spin3dScroll'
   - **Movement**: 'MoveScroll', 'SlideScroll'
   - **Scale**: 'GrowScroll', 'ShrinkScroll'
-- Other variables same as Rule 2
 
 **Example - Staggered Text Content Reveal**:
 
@@ -269,7 +245,7 @@ These rules help generate scroll-driven list animations using the `@wix/interact
     effects: [
         {
             key: 'product-card',
-            selector: ' .hero-image',
+            selector: '.hero-image',
             namedEffect: {
                 type: 'RevealScroll'
             },
@@ -286,14 +262,9 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 ## Rule 4: List Container Keyframe Animations
 
-**Use Case**: Custom scroll-driven container animations using keyframe effects for precise control over sticky container behaviors (e.g., multi-property container transformations, responsive container animations, complex background effects)
+**Use Case**: Custom container keyframe effects for sticky containers (multi-property transforms, complex backgrounds).
 
-**When to Apply**:
-
-- For custom container effects not available in named effects
-- When combining multiple CSS properties in container animations
-- For responsive container behaviors
-- When creating unique container visual effects
+**When to Apply**: Custom container effects not available in named effects.
 
 **Pattern**:
 
@@ -322,13 +293,7 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 }
 ```
 
-**Variables**:
-
-- `[CONTAINER_KEY]`: Unique identifier for list container
-- `[UNIQUE_KEYFRAME_EFFECT_NAME]`: unique name for the CSS keyframe effect (can equal `[UNIQUE_EFFECT_ID]` if provided)
-- `[CSS_PROPERTY_N]`: CSS property names ('transform', 'filter', 'opacity', 'backgroundColor')
-- `[START/MID/END_VALUE_N]`: Keyframe values for each property
-- Other variables same as Rule 1
+**Variables**: `[CONTAINER_KEY]`, `[UNIQUE_KEYFRAME_EFFECT_NAME]` (or `[UNIQUE_EFFECT_ID]`). Other variables same as Rule 1.
 
 **Example - Multi-Property Container Animation**:
 
@@ -387,14 +352,9 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 ## Rule 5: List Item Keyframe Entrance/Exit Animations
 
-**Use Case**: Custom entrance and exit animations for list items using keyframe effects for precise control over item reveals and dismissals (e.g., complex item entrances, item position flow, responsive item animations)
-
-**When to Apply**:
+**Use Case**: Custom keyframe entrance/exit for list items (complex reveals, dismissals).
 
-- For complex item entrance effects beyond named effects
-- When creating unique item position flows
-- For multi-stage item animations
-- When coordinating item wrapper with content animations
+**When to Apply**: Complex item entrance effects beyond named effects, coordinating item wrapper with content animations.
 
 **Pattern**:
 
@@ -423,12 +383,7 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 }
 ```
 
-**Variables**:
-
-- `[ITEM_KEY]`: Unique identifier for individual list items
-- `[RANGE_TYPE]`: 'entry', 'exit', or 'contain' depending on animation phase
-- `[EASING_FUNCTION]`: Easing function to use
-- Other variables same as Rule 4
+**Variables**: `[ITEM_KEY]`, `[EASING_FUNCTION]`. Other variables same as Rule 4.
 
 **Example - Complex Item Entrance**:
 
@@ -488,13 +443,9 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 ## Rule 6: Staggered List Animations with Custom Timing
 
-**Use Case**: Coordinated animations across multiple list items with each individual item used as the viewProgress trigger and custom timing patterns (e.g., wave animations, linear stagger, exponential stagger, reverse stagger)
+**Use Case**: Coordinated animations across list items; each item is the viewProgress trigger. Shared `effectId` in effects registry.
 
-**When to Apply**:
-
-- For creating wave-like animation propagation
-- When implementing linear or exponential stagger patterns
-- For reverse-order animations (exit effects)
+**When to Apply**: Wave-like propagation, linear/exponential stagger, reverse-order exit effects. Uses shared `effectId` in the effects registry so each item references the same effect.
 
 **Pattern**:
 
@@ -589,33 +540,9 @@ These rules help generate scroll-driven list animations using the `@wix/interact
         }
     },
     interactions: [
-        {
-            key: 'feature-1',
-            trigger: 'viewProgress',
-            effects: [
-                {
-                    effectId: 'feature-entrance'
-                }
-            ]
-        },
-        {
-            key: 'feature-2',
-            trigger: 'viewProgress',
-            effects: [
-                {
-                    effectId: 'feature-entrance'
-                }
-            ]
-        },
-        {
-            key: 'feature-3',
-            trigger: 'viewProgress',
-            effects: [
-                {
-                    effectId: 'feature-entrance'
-                }
-            ]
-        },
+        { key: 'feature-1', trigger: 'viewProgress', effects: [{ effectId: 'feature-entrance' }] },
+        { key: 'feature-2', trigger: 'viewProgress', effects: [{ effectId: 'feature-entrance' }] },
+        { key: 'feature-3', trigger: 'viewProgress', effects: [{ effectId: 'feature-entrance' }] },
     ]
 }
 ```
@@ -624,14 +551,9 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 ## Rule 7: Dynamic Content Animations with Custom Effects
 
-**Use Case**: JavaScript-powered list animations with custom effects for complex interactions that require calculations or dynamic content updates (e.g., scroll counters, progress tracking, data visualization, dynamic text updates)
+**Use Case**: Per-item dynamic content via `customEffect` (counters, progress tracking, data visualization, dynamic text).
 
-**When to Apply**:
-
-- For animations requiring complex calculations
-- When integrating with data visualization
-- For dynamic content updates based on scroll
-- When creating interactive scroll-driven counters
+**When to Apply**: Scroll-driven counters, progress tracking, data visualization, dynamic text updates in list contexts.
 
 **Pattern**:
 
@@ -657,13 +579,7 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 }
 ```
 
-**Variables**:
-
-- `[LIST_CONTAINER_KEY]`: Unique identifier for list or section containing dynamic content
-- `[DYNAMIC_CONTENT_KEY]`: Unique identifier for elements that will be dynamically updated
-- `[CUSTOM_CALCULATION_LOGIC]`: JavaScript calculations based on progress
-- `[DYNAMIC_CONTENT_UPDATE]`: Code to update element content
-- `[VISUAL_PROPERTY_UPDATES]`: Code to update visual properties
+**Variables**: `[LIST_CONTAINER_KEY]` / `[DYNAMIC_CONTENT_KEY]` identify the list and target elements. The `customEffect` receives `(element, progress)` where progress is 0–1.
 
 **Example - Scroll-Driven Counter in List**:
 
@@ -714,39 +630,24 @@ These rules help generate scroll-driven list animations using the `@wix/interact
                 const items = element.closest('interact-element')?.querySelectorAll('.task-item') || [];
                 const totalItems = items.length;
                 const elementIndex = Array.from(items).indexOf(element);
-
-                // Calculate staggered progress for each item
                 const itemStartProgress = elementIndex / totalItems;
                 const itemEndProgress = (elementIndex + 1) / totalItems;
+                let itemProgress = progress > itemStartProgress
+                    ? Math.min(1, (progress - itemStartProgress) / (itemEndProgress - itemStartProgress))
+                    : 0;
 
-                // Calculate individual item progress
-                let itemProgress = 0;
-                if (progress > itemStartProgress) {
-                    itemProgress = Math.min(1, (progress - itemStartProgress) / (itemEndProgress - itemStartProgress));
-                }
-
-                // Update visual state
                 const checkbox = element.querySelector('.task-checkbox');
                 const taskText = element.querySelector('.task-text');
-
                 if (itemProgress > 0.5) {
                     element.classList.add('active');
                     checkbox.style.transform = `scale(${0.8 + itemProgress * 0.4})`;
                     checkbox.style.opacity = itemProgress;
                 }
-
                 if (itemProgress > 0.8) {
                     element.classList.add('completed');
                     taskText.style.textDecoration = 'line-through';
                     taskText.style.opacity = '0.7';
                 }
-
-                // Update overall progress indicator
-                const progressIndicator = document.querySelector('#overall-progress');
-                if (progressIndicator && elementIndex === 0) {
-                    progressIndicator.style.width = `${progress * 100}%`;
-                    progressIndicator.textContent = `${Math.floor(progress * 100)}% Complete`;
-                }
             },
             rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
             rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
@@ -763,108 +664,73 @@ These rules help generate scroll-driven list animations using the `@wix/interact
 
 ### Multi-Layer List Coordination
 
-Coordinating container, items, and content simultaneously:
+Container, items, and content: use `cover` for background/foreground layers (full scroll range), `contain` for the sticky container layer (while stuck).
 
 ```typescript
 {
     key: 'complex-list-section',
     trigger: 'viewProgress',
     effects: [
-        // Background layer
-        {
-            key: 'list-background',
-            keyframeEffect: {
-                name: 'background-parallax',
-                keyframes: [
-                    { transform: 'scale(1.1) translateY(0)', filter: 'blur(0)' },
-                    { transform: 'scale(1) translateY(-50px)', filter: 'blur(2px)' }
-                ]
-            },
-            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
-            easing: 'linear',
-            fill: 'both'
-        },
-        // Container layer
-        {
-            key: 'list-container',
-            keyframeEffect: {
-                name: 'container-slide',
-                keyframes: [
-                    { transform: 'translateX(0)' },
-                    { transform: 'translateX(-50%)' }
-                ]
-            },
-            rangeStart: { name: 'contain', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'contain', offset: { unit: 'percentage', value: 100 } },
-            easing: 'linear',
-            fill: 'both'
-        },
-        // Foreground decorations
-        {
-            key: 'list-decorations',
-            keyframeEffect: {
-                name: 'decorations-parallax',
-                keyframes: [
-                    { transform: 'translateY(0)', opacity: '0.8' },
-                    { transform: 'translateY(-100px)', opacity: '1' }
-                ]
-            },
-            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
-            easing: 'linear',
-            fill: 'both'
-        }
+        { key: 'list-background', keyframeEffect: { name: 'bg-parallax', keyframes: [{ transform: 'scale(1.1)' }, { transform: 'scale(1) translateY(-50px)' }] }, rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } }, rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } }, easing: 'linear', fill: 'both' },
+        { key: 'list-container', keyframeEffect: { name: 'container-slide', keyframes: [{ transform: 'translateX(0)' }, { transform: 'translateX(-50%)' }] }, rangeStart: { name: 'contain', offset: { unit: 'percentage', value: 0 } }, rangeEnd: { name: 'contain', offset: { unit: 'percentage', value: 100 } }, easing: 'linear', fill: 'both' }
     ]
 }
 ```
 
 ### Responsive List Animations
 
-Adaptive patterns based on screen size and device capabilities:
+Condition IDs are user-defined strings declared in the top-level `conditions` map. Define separate interactions for the same `key` with different conditions and effects.
 
 ```typescript
-// Desktop version with complex effects
 {
-    key: 'responsive-list',
-    trigger: 'viewProgress',
-    conditions: ['desktop-only', 'prefers-motion'],
-    effects: [
+    conditions: {
+        'desktop-only':   { type: 'media', predicate: '(min-width: 768px)' },
+        'prefers-motion': { type: 'media', predicate: '(prefers-reduced-motion: no-preference)' },
+        'mobile-only':    { type: 'media', predicate: '(max-width: 767px)' },
+    },
+    interactions: [
         {
             key: 'list-item',
-            keyframeEffect: {
-                name: 'list-item-complex',
-                keyframes: [
-                    { transform: 'translateY(-20px) rotateY(5deg)', boxShadow: '0 20px 40px rgb(0 0 0 / 0.15)' },
-                    { transform: 'translateY(0) rotateY(0deg)', boxShadow: '0 0 0 rgb(0 0 0 / 0)' }
-                ]
-            },
-            rangeStart: { name: 'entry', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'entry', offset: { unit: 'percentage', value: 80 } },
-            easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
-            fill: 'both'
-        }
-    ]
-},
-// Mobile version with simplified effects
-{
-    key: 'responsive-list',
-    trigger: 'viewProgress',
-    conditions: ['mobile-only'],
-    effects: [
+            trigger: 'viewProgress',
+            conditions: ['desktop-only', 'prefers-motion'],
+            effects: [
+                {
+                    key: 'list-item',
+                    keyframeEffect: {
+                        name: 'item-complex',
+                        keyframes: [
+                            { opacity: '0', transform: 'translateY(-20px) rotateY(5deg)' },
+                            { opacity: '1', transform: 'translateY(0) rotateY(0deg)' }
+                        ]
+                    },
+                    rangeStart: { name: 'entry', offset: { unit: 'percentage', value: 0 } },
+                    rangeEnd: { name: 'entry', offset: { unit: 'percentage', value: 80 } },
+                    easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
+                    fill: 'both'
+                }
+            ]
+        },
+        // Simplified fallback for mobile or reduced-motion users
         {
             key: 'list-item',
-            keyframeEffect: {
-                name: 'list-item-simple',
-                keyframes: [
-                    { opacity: '0', transform: 'translateY(30px)' },
-                    { opacity: '1', transform: 'translateY(0)' }
-                ]
-            },
-            rangeStart: { name: 'entry', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'entry', offset: { unit: 'percentage', value: 60 } },
-            easing: 'ease-out',
-            fill: 'both'
+            trigger: 'viewProgress',
+            conditions: ['mobile-only'],
+            effects: [
+                {
+                    key: 'list-item',
+                    keyframeEffect: {
+                        name: 'item-simple',
+                        keyframes: [
+                            { opacity: '0', transform: 'translateY(30px)' },
+                            { opacity: '1', transform: 'translateY(0)' }
+                        ]
+                    },
+                    rangeStart: { name: 'entry', offset: { unit: 'percentage', value: 0 } },
+                    rangeEnd: { name: 'entry', offset: { unit: 'percentage', value: 60 } },
+                    easing: 'ease-out',
+                    fill: 'both'
+                }
+            ]
         }
     ]
 }
@@ -874,73 +740,9 @@ Adaptive patterns based on screen size and device capabilities:
 
 ## Best Practices for List Scroll Animations
 
-### Performance Guidelines
-
-1. **Use hardware-accelerated properties**: `transform`, `opacity`, `filter` for smooth animations
-2. **Limit concurrent animations**: Avoid animating too many items simultaneously
-3. **Use position:sticky for scrolling effects**: Animate elements while they're stuck in position and not scrolling with the page
-4. **Consider `will-change` property**: When doing complex style animations inside custom effects that the browser can not predict automatically
-
-### Range Selection Guidelines
-
-1. **Container animations**: Use `contain` range for sticky container effects
-2. **Item entrance**: Use `entry` range (0-60%) for natural reveals
-3. **Item exit**: Use `exit` range (20-100%) for smooth dismissals
-4. **Content coordination**: Use same timeline with `cover`/`contain` range and staggered offsets, or use a different timeline per item with same range and offsets
-
-### User Experience Guidelines
-
-1. **Keep animations subtle**: Avoid overwhelming users with excessive motion
-2. **Maintain content readability**: Ensure text remains legible during animations
-3. **Provide reduced motion alternatives**: Respect `prefers-reduced-motion` setting
-
-### Accessibility Considerations
-
-1. **Respect motion preferences**: Include `prefers-motion` conditions
-2. **Provide keyboard navigation**: Ensure list remains navigable during animations
-3. **Maintain focus management**: Don't break focus states with animations
-4. **Ensure content accessibility**: Keep content accessible throughout animation states
-
-### Common Use Cases by Pattern
-
-**Sticky Container (Rule 1)**:
-
-- Horizontal scrolling galleries
-- Timeline navigation
-- Product showcase carousels
-- Feature comparison tables
-
-**Sticky Items (Rule 2)**:
-
-- Progressive story reveals
-- Step-by-step processes
-- Card-based layouts
-- Interactive portfolios
-
-**Content Animations (Rule 3)**:
-
-- Text reveals within cards
-- Image animations in galleries
-- Icon animations in feature lists
-- Progressive data visualization
-
-**Keyframe Effects (Rules 4-5)**:
-
-- Complex brand animations
-- Multi-property transformations
-- Responsive design adaptations
-- Advanced visual effects
-
-**Staggered Animations (Rule 6)**:
-
-- Team member introductions
-- Product grid reveals
-- Feature list presentations
-- Testimonial carousels
-
-**Dynamic Content (Rule 7)**:
+### List-Specific Guidelines
 
-- Statistics counters
-- Progress tracking
-- Data visualization
-- Interactive dashboards
+1. **Sticky hierarchy**: Container → items → content. Use `contain` range for sticky container effects (animations run while the element is stuck in position).
+2. **Content coordination**: Use same timeline with `cover`/`contain` range and staggered offsets, or use a different timeline per item with same range and offsets.
+3. **Use position:sticky**: Animate elements while they're stuck in position and not scrolling with the page.
+4. **@wix/interact conditions**: Include `prefers-motion` in conditions for reduced-motion users (e.g. `conditions: ['prefers-motion']`).