@wix/interact 2.0.4 → 2.1.0

package/rules/hover.md

@@ -484,6 +484,80 @@ This document contains rules for generating hover trigger interactions in `@wix/
 }
 ```
 
+## Rule 6: Hover with Sequence (Staggered Multi-Target)
+
+**Purpose**: Hover interactions that stagger animations across multiple targets using a sequence instead of manual delays.
+
+**When to Apply**:
+
+- When hovering a container should stagger-animate its children
+- For list item hover effects with coordinated timing
+- When you want easing-controlled stagger on hover
+
+**Pattern**:
+
+```typescript
+{
+    key: '[SOURCE_KEY]',
+    trigger: 'hover',
+    params: {
+        type: 'repeat'
+    },
+    sequences: [
+        {
+            offset: [OFFSET_MS],
+            offsetEasing: '[OFFSET_EASING]',
+            effects: [
+                {
+                    effectId: '[EFFECT_ID]',
+                    listContainer: '[LIST_CONTAINER_SELECTOR]'
+                }
+            ]
+        }
+    ]
+}
+```
+
+**Example - Hover Card Grid Stagger**:
+
+```typescript
+{
+    key: 'card-grid',
+    trigger: 'hover',
+    params: { type: 'repeat' },
+    sequences: [
+        {
+            offset: 80,
+            offsetEasing: 'sineOut',
+            effects: [
+                {
+                    effectId: 'item-pop',
+                    listContainer: '.card-grid-items'
+                }
+            ]
+        }
+    ]
+}
+```
+
+```typescript
+effects: {
+    'item-pop': {
+        duration: 400,
+        easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+        keyframeEffect: {
+            name: 'item-pop',
+            keyframes: [
+                { transform: 'translateY(16px) scale(0.95)', opacity: 0 },
+                { transform: 'translateY(0) scale(1)', opacity: 1 }
+            ]
+        }
+    }
+}
+```
+
+---
+
 ## Best Practices for Hover Rules
 
 ### Timing and Pattern Guidelines

package/rules/integration.md

@@ -100,6 +100,7 @@ The `InteractConfig` object defines the behavior.
 type InteractConfig = {
   interactions: Interaction[]; // Required: Array of interaction definitions
   effects?: Record<string, Effect>; // Optional: Reusable named effects
+  sequences?: Record<string, SequenceConfig>; // Optional: Reusable sequence definitions
   conditions?: Record<string, Condition>; // Optional: Reusable conditions (media queries)
 };
 ```
@@ -115,7 +116,8 @@ type InteractConfig = {
   listItemSelector?: '.item',      // Optional: CSS selector for items within listContainer
   params?: { ... },                // Trigger-specific parameters
   conditions?: ['cond-id'],        // Array of condition IDs
-  effects: [ ... ]                 // Array of effects to apply
+  effects?: [ ... ],               // Array of effects to apply
+  sequences?: [ ... ]              // Array of sequences (coordinated staggered effects)
 }
 ```
 
@@ -183,6 +185,38 @@ const html = `
 | `pointerMove`  | Mouse movement                                  | `hitArea`: 'self' (default) or 'root'; `axis`: 'x' or 'y' for keyframeEffect                                              | `./pointermove.md`  |
 | `animationEnd` | Chaining animations                             | `effectId`: ID of the previous effect                                                                                     | --                  |
 
+## 5b. Sequences (Coordinated Stagger)
+
+Sequences group multiple effects into a coordinated timeline with staggered timing. Instead of setting `delay` on each effect manually, define `offset` (ms between items) and `offsetEasing` (how offset is distributed).
+
+### Sequence Config
+
+```typescript
+{
+  offset: 100,            // ms between consecutive effects
+  offsetEasing: 'quadIn', // easing for stagger distribution (linear, quadIn, sineOut, etc.)
+  delay: 0,               // base delay before the sequence starts
+  effects: [              // effects in the sequence, applied in order
+    { effectId: 'card-entrance', listContainer: '.card-grid' },
+  ],
+}
+```
+
+Effects in a sequence can target different elements via `key`, use `listContainer` to target list children, or reference the effects registry via `effectId`.
+
+Reusable sequences can be defined in `InteractConfig.sequences` and referenced by `sequenceId`:
+
+```typescript
+{
+  sequences: {
+    'stagger-entrance': { offset: 80, offsetEasing: 'quadIn', effects: [{ effectId: 'fade-up', listContainer: '.items' }] },
+  },
+  interactions: [
+    { key: 'section', trigger: 'viewEnter', params: { type: 'once' }, sequences: [{ sequenceId: 'stagger-entrance' }] },
+  ],
+}
+```
+
 ## 6. Named Effects & `registerEffects`
 
 To use `namedEffect` presets from `@wix/motion-presets`, register them before calling `Interact.create`. For full effect type syntax (`keyframeEffect`, `customEffect`, `TransitionEffect`, `ScrubEffect`), see `full-lean.md`.
@@ -272,6 +306,41 @@ const config = {
 };
 ```
 
+### Staggered List Entrance (Sequence)
+
+```typescript
+const config = {
+  interactions: [
+    {
+      key: 'card-grid',
+      trigger: 'viewEnter',
+      params: { type: 'once', threshold: 0.3 },
+      sequences: [
+        {
+          offset: 100,
+          offsetEasing: 'quadIn',
+          effects: [{ effectId: 'card-entrance', listContainer: '.card-grid' }],
+        },
+      ],
+    },
+  ],
+  effects: {
+    'card-entrance': {
+      duration: 500,
+      easing: 'ease-out',
+      keyframeEffect: {
+        name: 'card-fade-up',
+        keyframes: [
+          { transform: 'translateY(40px)', opacity: 0 },
+          { transform: 'translateY(0)', opacity: 1 },
+        ],
+      },
+      fill: 'both',
+    },
+  },
+};
+```
+
 ### Interactive Toggle (Click)
 
 ```typescript

package/rules/viewenter.md

@@ -527,9 +527,9 @@ Same as Rule 2
 
 ---
 
-## Rule 6: Staggered Entrance Animations
+## Rule 6: Staggered Entrance Animations (Sequences)
 
-**Use Case**: Sequential entrance animations where multiple elements animate with delays (e.g., card grids, list items, team member cards, feature sections)
+**Use Case**: Sequential entrance animations where multiple elements animate with staggered timing (e.g., card grids, list items, team member cards, feature sections)
 
 **When to Apply**:
 
@@ -538,196 +538,126 @@ Same as Rule 2
 - When animating lists, grids, or collections
 - For progressive content revelation
 
-**Pattern**:
+**Preferred approach: use `sequences`** on the interaction instead of manually setting `delay` on individual effects. Sequences automatically calculate stagger delays using `offset` and `offsetEasing`.
+
+**Pattern (with `listContainer`)**:
 
 ```typescript
-[
-  {
-    key: '[ELEMENT_1_SELECTOR]',
-    trigger: 'viewEnter',
-    params: {
-      type: 'once',
-      threshold: [SHARED_THRESHOLD],
-      inset: '[SHARED_INSET]',
-    },
-    effects: [
-      {
-        [EFFECT_TYPE]: [SHARED_EFFECT_DEFINITION],
-        duration: [SHARED_DURATION],
-        easing: '[SHARED_EASING]',
-        delay: [DELAY_1],
-      },
-    ],
-  },
-  {
-    key: '[ELEMENT_2_SELECTOR]',
+{
+    key: '[CONTAINER_KEY]',
     trigger: 'viewEnter',
     params: {
-      type: 'once',
-      threshold: [SHARED_THRESHOLD],
-      inset: '[SHARED_INSET]',
+        type: '[BEHAVIOR_TYPE]',
+        threshold: [VISIBILITY_THRESHOLD]
     },
-    effects: [
-      {
-        [EFFECT_TYPE]: [SHARED_EFFECT_DEFINITION],
-        duration: [SHARED_DURATION],
-        easing: '[SHARED_EASING]',
-        delay: [DELAY_2],
-      },
-    ],
-  },
-  // ... additional elements with increasing delays
-];
+    sequences: [
+        {
+            offset: [OFFSET_MS],
+            offsetEasing: '[OFFSET_EASING]',
+            effects: [
+                {
+                    effectId: '[EFFECT_ID]',
+                    listContainer: '[LIST_CONTAINER_SELECTOR]'
+                }
+            ]
+        }
+    ]
+}
 ```
 
 **Variables**:
 
-- `[ELEMENT_N_KEY]`: Unique identifier for each individual element in sequence
-- `[DELAY_N]`: Progressive delay values (e.g., 0, 100, 200, 300ms)
-- `[SHARED_*]`: Common values used across all elements in the sequence
+- `[CONTAINER_KEY]`: Unique identifier for the container element
+- `[OFFSET_MS]`: Stagger offset in ms between consecutive items (e.g., 80, 100, 120)
+- `[OFFSET_EASING]`: How the offset is distributed — `'linear'` (equal spacing), `'quadIn'` (accelerating), `'sineOut'` (decelerating), etc.
+- `[LIST_CONTAINER_SELECTOR]`: CSS selector for the list container whose children become sequence items
 - Other variables same as Rule 1
 
-**Example - Card Grid Stagger**:
+**Example - Card Grid Stagger (listContainer)**:
 
 ```typescript
-[
-  {
-    key: 'card-1',
-    trigger: 'viewEnter',
-    params: {
-      type: 'once',
-      threshold: 0.3,
-    },
-    effects: [
-      {
-        namedEffect: {
-          type: 'SlideIn',
-          direction: 'bottom',
-        },
-        duration: 600,
-        easing: 'ease-out',
-        fill: 'backwards',
-        delay: 0,
-      },
-    ],
-  },
-  {
-    key: 'card-2',
-    trigger: 'viewEnter',
-    params: {
-      type: 'once',
-      threshold: 0.3,
-    },
-    effects: [
-      {
-        namedEffect: {
-          type: 'SlideIn',
-          direction: 'bottom',
-        },
-        duration: 600,
-        easing: 'ease-out',
-        fill: 'backwards',
-        delay: 150,
-      },
-    ],
-  },
-  {
-    key: 'card-3',
+{
+    key: 'card-grid-container',
     trigger: 'viewEnter',
     params: {
-      type: 'once',
-      threshold: 0.3,
+        type: 'once',
+        threshold: 0.3
     },
-    effects: [
-      {
-        namedEffect: {
-          type: 'SlideIn',
-          direction: 'bottom',
-        },
-        duration: 600,
-        easing: 'ease-out',
-        fill: 'backwards',
-        delay: 300,
-      },
-    ],
-  },
-];
+    sequences: [
+        {
+            offset: 100,
+            offsetEasing: 'quadIn',
+            effects: [
+                {
+                    effectId: 'card-entrance',
+                    listContainer: '.card-grid'
+                }
+            ]
+        }
+    ]
+}
 ```
 
-**Example - Feature List Cascade**:
+With effect in the registry:
 
 ```typescript
-[
-  {
-    key: 'feature-item:nth-child(1)',
-    trigger: 'viewEnter',
-    params: {
-      type: 'once',
-      threshold: 0.4,
-    },
-    effects: [
-      {
+effects: {
+    'card-entrance': {
+        duration: 500,
+        easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
         keyframeEffect: {
-          name: 'item-kf-1',
-          keyframes: [
-            { opacity: '0', transform: 'translateX(-30px)' },
-            { opacity: '1', transform: 'translateX(0)' },
-          ],
+            name: 'card-fade-up',
+            keyframes: [
+                { transform: 'translateY(40px)', opacity: 0 },
+                { transform: 'translateY(0)', opacity: 1 }
+            ]
         },
-        duration: 500,
-        easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
-        fill: 'backwards',
-        delay: 0,
-      },
-    ],
-  },
-  {
-    key: 'feature-item:nth-child(2)',
+        fill: 'both'
+    }
+}
+```
+
+**Example - Feature List Cascade (per-key effects)**:
+
+When items have individual keys rather than a shared container, list each as a separate effect in the sequence:
+
+```typescript
+{
+    key: 'features-section',
     trigger: 'viewEnter',
     params: {
-      type: 'once',
-      threshold: 0.4,
+        type: 'once',
+        threshold: 0.4
     },
-    effects: [
-      {
-        keyframeEffect: {
-          name: 'item-kf-2',
-          keyframes: [
-            { opacity: '0', transform: 'translateX(-30px)' },
-            { opacity: '1', transform: 'translateX(0)' },
-          ],
-        },
+    sequences: [
+        {
+            offset: 100,
+            offsetEasing: 'linear',
+            effects: [
+                { effectId: 'feature-slide', key: 'feature-1' },
+                { effectId: 'feature-slide', key: 'feature-2' },
+                { effectId: 'feature-slide', key: 'feature-3' }
+            ]
+        }
+    ]
+}
+```
+
+```typescript
+effects: {
+    'feature-slide': {
         duration: 500,
         easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
-        fill: 'backwards',
-        delay: 100,
-      },
-    ],
-  },
-  {
-    key: 'feature-item:nth-child(3)',
-    trigger: 'viewEnter',
-    params: {
-      type: 'once',
-      threshold: 0.4,
-    },
-    effects: [
-      {
         keyframeEffect: {
-          name: 'item-kf-3',
-          keyframes: [
-            { opacity: '0', transform: 'translateX(-30px)' },
-            { opacity: '1', transform: 'translateX(0)' },
-          ],
+            name: 'feature-slide-in',
+            keyframes: [
+                { opacity: '0', transform: 'translateX(-30px)' },
+                { opacity: '1', transform: 'translateX(0)' }
+            ]
         },
-        duration: 500,
-        easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
-        fill: 'backwards',
-        delay: 200,
-      },
-    ],
-  },
-];
+        fill: 'backwards'
+    }
+}
 ```
 
 ---