@wix/interact 2.0.4 → 2.1.0

package/docs/guides/sequences.md

@@ -0,0 +1,421 @@
+# Sequences & Staggering
+
+Sequences let you coordinate multiple effects as a single timeline with staggered delay offsets. Built on the `@wix/motion` `Sequence` class, they provide easing-driven timing distribution across effects — ideal for list entrances, multi-element orchestrations, and any pattern requiring coordinated animation timing.
+
+## What is a Sequence?
+
+A Sequence groups multiple effects and applies calculated delay offsets to each one, so they play back in a staggered pattern. The stagger timing is shaped by an easing function, producing natural-feeling cascades rather than uniform delays.
+
+```
+offset[i] = easing(i / last) * last * offsetMs
+```
+
+For example, with 5 effects and `offset: 200`:
+
+| Easing    | Computed delays       | Feel                     |
+| --------- | --------------------- | ------------------------ |
+| `linear`  | 0, 200, 400, 600, 800 | Even spacing             |
+| `quadIn`  | 0, 50, 200, 450, 800  | Slow start, then rapid   |
+| `sineOut` | 0, 306, 565, 739, 800 | Fast start, then gradual |
+
+## Config Structure
+
+Sequences can be defined at two levels:
+
+### Reusable Sequences (`InteractConfig.sequences`)
+
+Define named sequences in the top-level `sequences` map, then reference them by ID from any interaction:
+
+```typescript
+const config: InteractConfig = {
+  sequences: {
+    'card-stagger': {
+      offset: 150,
+      offsetEasing: 'quadIn',
+      effects: [{ effectId: 'fade-up' }],
+    },
+  },
+  interactions: [
+    {
+      key: 'cards',
+      trigger: 'viewEnter',
+      listContainer: '.card-grid',
+      sequences: [{ sequenceId: 'card-stagger' }],
+    },
+  ],
+  effects: {
+    'fade-up': {
+      duration: 600,
+      easing: 'ease-out',
+      keyframeEffect: {
+        name: 'fade-up',
+        keyframes: [
+          { opacity: 0, transform: 'translateY(20px)' },
+          { opacity: 1, transform: 'translateY(0)' },
+        ],
+      },
+    },
+  },
+};
+```
+
+### Inline Sequences (`Interaction.sequences`)
+
+Define sequences directly on an interaction:
+
+```typescript
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'items',
+      trigger: 'viewEnter',
+      listContainer: '.item-list',
+      sequences: [
+        {
+          offset: 100,
+          offsetEasing: 'sineOut',
+          effects: [
+            {
+              duration: 500,
+              keyframeEffect: {
+                name: 'slide-in',
+                keyframes: [
+                  { opacity: 0, transform: 'translateX(-30px)' },
+                  { opacity: 1, transform: 'translateX(0)' },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  effects: {},
+};
+```
+
+### Combining Effects and Sequences
+
+An interaction can have both `effects` and `sequences`:
+
+```typescript
+{
+  key: 'hero',
+  trigger: 'viewEnter',
+  effects: [{ effectId: 'background-fade' }],
+  sequences: [{
+    offset: 200,
+    effects: [
+      { key: 'hero-title', effectId: 'slide-down' },
+      { key: 'hero-subtitle', effectId: 'fade-in' },
+    ],
+  }],
+}
+```
+
+## Types Reference
+
+### `SequenceOptionsConfig`
+
+Shared options for sequence timing and identity:
+
+```typescript
+type SequenceOptionsConfig = {
+  delay?: number; // Base delay (ms). Default: 0
+  offset?: number; // Stagger interval (ms). Default: 0
+  offsetEasing?: string | ((p: number) => number); // Easing for offset distribution
+  sequenceId?: string; // ID for reusable sequence reference
+  conditions?: string[]; // Media query condition IDs
+};
+```
+
+### `SequenceConfig`
+
+Inline sequence definition (extends `SequenceOptionsConfig`):
+
+```typescript
+type SequenceConfig = SequenceOptionsConfig & {
+  effects: (Effect | EffectRef)[];
+};
+```
+
+### `SequenceConfigRef`
+
+Reference to a reusable sequence with optional overrides:
+
+```typescript
+type SequenceConfigRef = {
+  sequenceId: string;
+  delay?: number;
+  offset?: number;
+  offsetEasing?: string | ((p: number) => number);
+  conditions?: string[];
+};
+```
+
+Overrides in the ref merge on top of the referenced sequence's values.
+
+## Cross-Element Sequences
+
+Effects within a sequence can target different elements using the `key` property:
+
+```typescript
+{
+  key: 'trigger-element',
+  trigger: 'click',
+  params: { type: 'alternate' },
+  sequences: [{
+    offset: 150,
+    offsetEasing: 'sineOut',
+    effects: [
+      { key: 'heading', effectId: 'slide-down' },
+      { key: 'body-text', effectId: 'fade-in' },
+      { key: 'hero-image', effectId: 'scale-in' },
+    ],
+  }],
+}
+```
+
+Cross-element sequences are resolved at add-time. When a sequence effect targets a `key` different from the source interaction, Interact waits for both elements to be registered before creating the Sequence. The effects are processed via `addEffectsForTarget()` when the target controller connects.
+
+## Sequences with `listContainer`
+
+The most common use case: staggering list item animations.
+
+### Initial Load
+
+When the source element connects, all existing list items are gathered and a Sequence is created with one `AnimationGroup` per item:
+
+```typescript
+{
+  key: 'product-grid',
+  trigger: 'viewEnter',
+  listContainer: '.products',
+  params: { type: 'once' },
+  sequences: [{
+    offset: 80,
+    offsetEasing: 'quadIn',
+    effects: [{
+      key: 'product-grid',
+      listContainer: '.products',
+      effectId: 'card-entrance',
+    }],
+  }],
+}
+```
+
+### Dynamic Additions (`addListItems`)
+
+When new items are appended to the DOM (detected by MutationObserver), `addListItems` is called. For sequences, this calls `Interact.addToSequence()` with `IndexedGroup` entries at the correct indices, triggering automatic offset recalculation across the entire Sequence.
+
+Each `addListItems` invocation uses a unique cache key to manage its Sequence independently.
+
+### Dynamic Removals (`removeListItems`)
+
+When items are removed from the DOM, `removeListItems` automatically calls `Interact.removeFromSequences(elements)`. This:
+
+1. Looks up associated Sequences via the `elementSequenceMap` WeakMap (O(1) per element)
+2. Calls `sequence.removeGroups()` to cancel and remove the matching groups
+3. Recalculates offsets for remaining groups
+4. Cleans up the element from the map
+
+No manual cleanup is needed — MutationObserver handles it automatically.
+
+## Conditions on Sequences
+
+### Sequence-Level Conditions
+
+Gate an entire sequence with media query conditions:
+
+```typescript
+{
+  key: 'hero',
+  trigger: 'viewEnter',
+  sequences: [{
+    conditions: ['desktop-only'],
+    offset: 200,
+    effects: [
+      { key: 'hero-title', effectId: 'slide-down' },
+      { key: 'hero-body', effectId: 'fade-in' },
+    ],
+  }],
+}
+```
+
+When the condition doesn't match, the entire sequence is skipped. Interact sets up `matchMedia` listeners so the sequence is added/removed dynamically when the condition changes.
+
+### Effect-Level Conditions
+
+Individual effects within a sequence can have their own conditions:
+
+```typescript
+sequences: [
+  {
+    offset: 150,
+    effects: [
+      { effectId: 'base-entrance' },
+      { effectId: 'fancy-entrance', conditions: ['desktop-only'] },
+    ],
+  },
+];
+```
+
+When an effect-level condition doesn't match, that effect is excluded from the Sequence's animation groups, and offsets are calculated for the remaining effects only.
+
+## Sequence Caching
+
+Interact caches Sequences to avoid recreating them:
+
+- **`Interact.sequenceCache`** (`Map<string, Sequence>`) — maps cache keys to Sequence instances
+- **`Interact.elementSequenceMap`** (`WeakMap<HTMLElement, Set<Sequence>>`) — maps elements to their Sequences for efficient removal
+
+Cache keys are derived from the interaction key, sequence index, and context. Cleanup happens automatically:
+
+- `Interact.destroy()` clears both `sequenceCache` and `elementSequenceMap`
+- `clearInteractionStateForKey()` removes cache entries by key prefix
+- Element removal cleans up `elementSequenceMap` entries via the WeakMap
+
+## Examples
+
+### Staggered Card Grid Entrance
+
+```typescript
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'cards',
+      trigger: 'viewEnter',
+      listContainer: '.card-grid',
+      params: { type: 'once', threshold: 0.1 },
+      sequences: [
+        {
+          offset: 80,
+          offsetEasing: 'quadIn',
+          effects: [
+            {
+              key: 'cards',
+              listContainer: '.card-grid',
+              effectId: 'card-entrance',
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  effects: {
+    'card-entrance': {
+      duration: 600,
+      easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
+      keyframeEffect: {
+        name: 'card-entrance',
+        keyframes: [
+          { opacity: 0, transform: 'translateY(40px) scale(0.95)' },
+          { opacity: 1, transform: 'translateY(0) scale(1)' },
+        ],
+      },
+    },
+  },
+};
+```
+
+### Click-Triggered Multi-Element Orchestration
+
+```typescript
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'reveal-btn',
+      trigger: 'click',
+      params: { type: 'alternate' },
+      sequences: [
+        {
+          offset: 150,
+          offsetEasing: 'sineOut',
+          effects: [
+            { key: 'section-heading', effectId: 'slide-down' },
+            { key: 'section-body', effectId: 'fade-in' },
+            { key: 'section-image', effectId: 'scale-in' },
+          ],
+        },
+      ],
+    },
+  ],
+  effects: {
+    'slide-down': {
+      duration: 400,
+      keyframeEffect: {
+        name: 'slide-down',
+        keyframes: [
+          { transform: 'translateY(-20px)', opacity: 0 },
+          { transform: 'translateY(0)', opacity: 1 },
+        ],
+      },
+    },
+    'fade-in': {
+      duration: 500,
+      keyframeEffect: {
+        name: 'fade-in',
+        keyframes: [{ opacity: 0 }, { opacity: 1 }],
+      },
+    },
+    'scale-in': {
+      duration: 600,
+      keyframeEffect: {
+        name: 'scale-in',
+        keyframes: [
+          { transform: 'scale(0.9)', opacity: 0 },
+          { transform: 'scale(1)', opacity: 1 },
+        ],
+      },
+    },
+  },
+};
+```
+
+### Sequence with Media-Query Conditions
+
+```typescript
+const config: InteractConfig = {
+  conditions: {
+    'desktop-only': { type: 'media', predicate: '(min-width: 1024px)' },
+    'no-reduced-motion': { type: 'media', predicate: '(prefers-reduced-motion: no-preference)' },
+  },
+  interactions: [
+    {
+      key: 'features',
+      trigger: 'viewEnter',
+      listContainer: '.feature-list',
+      conditions: ['no-reduced-motion'],
+      sequences: [
+        {
+          conditions: ['desktop-only'],
+          offset: 120,
+          offsetEasing: 'quadIn',
+          effects: [{ effectId: 'feature-entrance' }],
+        },
+      ],
+    },
+  ],
+  effects: {
+    'feature-entrance': {
+      duration: 700,
+      easing: 'ease-out',
+      keyframeEffect: {
+        name: 'feature-entrance',
+        keyframes: [
+          { opacity: 0, transform: 'translateY(30px)' },
+          { opacity: 1, transform: 'translateY(0)' },
+        ],
+      },
+    },
+  },
+};
+```
+
+## See Also
+
+- [Lists and Dynamic Content](./lists-and-dynamic-content.md) — `listContainer`, `addListItems`, mutation tracking
+- [Conditions and Media Queries](./conditions-and-media-queries.md) — conditional interactions
+- [Effects and Animations](./effects-and-animations.md) — effect types and properties
+- [Interact Class API](../api/interact-class.md) — `getSequence()`, `addToSequence()`, `removeFromSequences()`
+- [Type Definitions](../api/types.md) — `SequenceConfig`, `SequenceConfigRef`, `SequenceOptionsConfig`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/interact",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "A powerful, declarative interaction library for creating engaging web apps.",
   "license": "MIT",
   "main": "dist/cjs/index.js",
@@ -55,7 +55,7 @@
     "url": "https://github.com/wix/interact/issues"
   },
   "dependencies": {
-    "@wix/motion": "^2.0.1",
+    "@wix/motion": "^2.1.0",
     "fastdom": "^1.0.12",
     "fizban": "^0.7.2",
     "kuliso": "^0.4.13"

package/rules/click.md

@@ -416,11 +416,122 @@ These rules help generate click-based interactions using the `@wix/interact` lib
 
 ---
 
+## Rule 5: Click with Sequence (Staggered Multi-Element Orchestration)
+
+**Use Case**: Click-triggered coordinated animations across multiple elements with staggered timing (e.g., page section reveals, multi-element toggles, orchestrated content entrances)
+
+**When to Apply**:
+
+- When a click should animate multiple elements with staggered timing
+- For orchestrated content reveals (heading, body, image in sequence)
+- When you want easing-controlled stagger instead of manual delays
+- For toggle-able multi-element sequences
+
+**Pattern**:
+
+```typescript
+{
+    key: '[SOURCE_KEY]',
+    trigger: 'click',
+    params: {
+        type: 'alternate'
+    },
+    sequences: [
+        {
+            offset: [OFFSET_MS],
+            offsetEasing: '[OFFSET_EASING]',
+            effects: [
+                { effectId: '[EFFECT_ID_1]', key: '[TARGET_KEY_1]' },
+                { effectId: '[EFFECT_ID_2]', key: '[TARGET_KEY_2]' },
+                { effectId: '[EFFECT_ID_3]', key: '[TARGET_KEY_3]' }
+            ]
+        }
+    ]
+}
+```
+
+**Variables**:
+
+- `[OFFSET_MS]`: Stagger offset in ms between consecutive effects (typically 100-200ms)
+- `[OFFSET_EASING]`: Easing for stagger distribution — `'linear'`, `'quadIn'`, `'sineOut'`, etc.
+- `[EFFECT_ID_N]`: Effect id from the effects registry for each element
+- `[TARGET_KEY_N]`: Element key for each target
+- Other variables same as Rule 1
+
+**Example - Orchestrated Content Reveal**:
+
+```typescript
+{
+    key: 'reveal-button',
+    trigger: 'click',
+    params: {
+        type: 'alternate'
+    },
+    sequences: [
+        {
+            offset: 150,
+            offsetEasing: 'sineOut',
+            effects: [
+                { effectId: 'heading-entrance', key: 'content-heading' },
+                { effectId: 'body-entrance', key: 'content-body' },
+                { effectId: 'image-entrance', key: 'content-image' }
+            ]
+        }
+    ]
+}
+```
+
+```typescript
+effects: {
+    'heading-entrance': {
+        key: 'content-heading',
+        duration: 600,
+        easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+        keyframeEffect: {
+            name: 'heading-in',
+            keyframes: [
+                { transform: 'translateX(-40px)', opacity: 0 },
+                { transform: 'translateX(0)', opacity: 1 }
+            ]
+        },
+        fill: 'both'
+    },
+    'body-entrance': {
+        key: 'content-body',
+        duration: 500,
+        easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+        keyframeEffect: {
+            name: 'body-in',
+            keyframes: [
+                { transform: 'translateY(20px)', opacity: 0 },
+                { transform: 'translateY(0)', opacity: 1 }
+            ]
+        },
+        fill: 'both'
+    },
+    'image-entrance': {
+        key: 'content-image',
+        duration: 700,
+        easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+        keyframeEffect: {
+            name: 'image-in',
+            keyframes: [
+                { transform: 'scale(0.8) rotate(-5deg)', opacity: 0 },
+                { transform: 'scale(1) rotate(0deg)', opacity: 1 }
+            ]
+        },
+        fill: 'both'
+    }
+}
+```
+
+---
+
 ## Advanced Patterns and Combinations
 
 ### Multi-Target Click Effects
 
-When one click should animate multiple elements:
+When one click should animate multiple elements (without stagger, use `effects`; with stagger, prefer `sequences` above):
 
 ```typescript
 {

package/rules/full-lean.md

@@ -116,7 +116,7 @@ This configuration declares what user/system triggers occur on which source elem
 
 ### Global rules
 
-- **Required/Optional**: You MUST provide an `interactions` array. You SHOULD provide an `effects` registry when you want to reference reusable effects by id. `conditions` are OPTIONAL.
+- **Required/Optional**: You MUST provide an `interactions` array. You SHOULD provide an `effects` registry when you want to reference reusable effects by id. `conditions` and `sequences` are OPTIONAL.
 - **Cross-references**: All cross-references (by id) MUST point to existing entries (e.g., an `EffectRef.effectId` MUST exist in `effects`).
 - **Element keys**: All element keys (`key` fields) refer to the element path string (e.g., the value used in `data-interact-key`) and MUST be stable for the lifetime of the configuration.
 - **List context**: Where both a list container and list item selector are provided, they MUST describe the same list context across an interaction and its effects. Mismatched list contexts will be ignored by the system.
@@ -130,6 +130,11 @@ This configuration declares what user/system triggers occur on which source elem
   - **Key (string)**: The effect id. MUST be unique across the registry.
   - **Value (Effect)**: A full effect definition. See Effect rules below.
 
+- **sequences?: Record<string, SequenceConfig>**
+  - **Purpose**: A registry of reusable sequence definitions that can be referenced from interactions via `SequenceConfigRef`.
+  - **Key (string)**: The sequence id. MUST be unique across the registry.
+  - **Value (SequenceConfig)**: A full sequence definition. See Sequences section below.
+
 - **conditions?: Record<string, Condition>**
   - **Purpose**: Named predicates that gate interactions/effects by runtime context.
   - **Key (string)**: The condition id. MUST be unique across the registry.
@@ -214,8 +219,67 @@ This configuration declares what user/system triggers occur on which source elem
       - OPTIONAL. Additional CSS selector to refine element selection:
         - Without `listContainer`: Uses `querySelectorAll` to match all elements within the root element as separate items.
         - With `listContainer`: Uses `querySelectorAll` within the container to find matching elements as list items. For dynamically added list items, uses `querySelector` within each item to find a single matching element.
-    - **effects: Array<Effect | EffectRef>**
-      - REQUIRED. The effects to apply when the trigger fires. Ordering is significant: the first array entry is applied first. The system may reverse internal storage to preserve this application order.
+    - **effects?: Array<Effect | EffectRef>**
+      - The effects to apply when the trigger fires. Ordering is significant: the first array entry is applied first. The system may reverse internal storage to preserve this application order.
+      - At least one of `effects` or `sequences` MUST be provided.
+    - **sequences?: Array<SequenceConfig | SequenceConfigRef>**
+      - OPTIONAL. Sequences to play when the trigger fires. Each sequence coordinates multiple effects with staggered timing. See Sequences section below.
+
+### Sequences (coordinated multi-effect stagger)
+
+Sequences let you group multiple effects into a single coordinated timeline with staggered delays. Instead of manually setting `delay` on each effect, you define `offset` (ms between items) and `offsetEasing` (how that offset is distributed).
+
+**Prefer sequences over manual delay stagger** for any multi-element entrance or orchestration pattern.
+
+- **SequenceConfig** type:
+  - `effects: (Effect | EffectRef)[]` — REQUIRED. The effects in this sequence, applied in array order.
+  - `delay?: number` — Base delay (ms) before the entire sequence starts. Default `0`.
+  - `offset?: number` — Stagger offset (ms) between consecutive effects. Default `0`.
+  - `offsetEasing?: string | ((p: number) => number)` — Easing function for stagger distribution. Named easings: `'linear'`, `'quadIn'`, `'quadOut'`, `'sineOut'`, `'cubicIn'`, `'cubicOut'`, `'cubicInOut'`. Also accepts `'cubic-bezier(...)'` strings or a JS function `(p: number) => number`. Default `'linear'`.
+  - `sequenceId?: string` — Id for caching and referencing. Auto-generated if omitted.
+  - `conditions?: string[]` — Condition ids that MUST all pass for this sequence to be active.
+
+- **SequenceConfigRef** type (referencing a reusable sequence):
+  - `sequenceId: string` — REQUIRED. MUST match a key in `InteractConfig.sequences`.
+  - `delay?`, `offset?`, `offsetEasing?`, `conditions?` — OPTIONAL overrides merged on top of the referenced sequence.
+
+- Effects within a sequence follow the same rules as standalone effects. Each effect can:
+  - Target a different element via `key` (cross-element sequences).
+  - Use `listContainer` to target list children (each child becomes a separate effect in the sequence).
+  - Reference the effects registry via `effectId`.
+
+- A sequence is treated as a single animation unit by the trigger handler—it plays, reverses, and alternates as one.
+
+**Example — viewEnter staggered list using `listContainer`**:
+
+```typescript
+{
+  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': {
+      // ...
+    },
+  },
+}
+```
 
 ### Working with elements