@wix/interact 2.1.3 → 2.2.0

package/rules/viewprogress.md

@@ -1,378 +1,144 @@
 # ViewProgress Trigger Rules for @wix/interact
 
-## Core Concept
+These rules help generate scroll-driven interactions using `@wix/interact`. ViewProgress triggers create animations that update continuously as elements move through the viewport, leveraging native CSS ViewTimelines where supported, and using a polyfill library where unsupported. Use when animation progress should be tied to the element's scroll position.
 
-`viewProgress` triggers create scroll-driven animations that update continuously as elements move through the viewport, leveraging native CSS ViewTimelines. Use when animation progress should be tied to the element's scroll position.
+> **CRITICAL:** You MUST replace all usage of `overflow: hidden` with `overflow: clip` on every element between the trigger source element and the scroll container. `overflow: hidden` creates a new scroll context that breaks the ViewTimeline; `overflow: clip` clips overflow visually without affecting scroll ancestry. If using Tailwind, replace all `overflow-hidden` classes with `overflow-clip`.
 
-## Config Template
+**Offset semantics:** The `offset` inside `rangeStart`/`rangeEnd` is an object `{ unit: 'percentage', value: NUMBER }` where value is 0–100. For absolute lengths use `{ unit: 'px', value: NUMBER }` (or other CSS length units). Positive values move the effective range boundary forward along the scroll axis.
 
-```typescript
-{
-    key: '[SOURCE_KEY]',
-    trigger: 'viewProgress',
-    conditions: ['[CONDITION_NAME]'],  // optional: e.g. 'prefers-motion', 'desktop-only'
-    effects: [
-        {
-            key: '[TARGET_KEY]',
-            // Effect block — use exactly one of: namedEffect | keyframeEffect | customEffect
-            namedEffect: { type: '[NAMED_EFFECT]', /* preset-specific options only if documented */ },  // OR
-            keyframeEffect: { name: '[EFFECT_NAME]', keyframes: [EFFECT_KEYFRAMES] },  // OR
-            customEffect: (element, progress) => { [CUSTOM_LOGIC] },
-            rangeStart: { name: '[RANGE_NAME]', offset: { unit: 'percentage', value: [START_PERCENTAGE] } },
-            rangeEnd: { name: '[RANGE_NAME]', offset: { unit: 'percentage', value: [END_PERCENTAGE] } },
-            easing: '[EASING_FUNCTION]',
-            fill: '[FILL_MODE]',
-            effectId: '[UNIQUE_EFFECT_ID]'
-        }
-    ]
-}
-```
-
-## Variable Key
-
-| Placeholder          | Valid Values / Notes                                                                                                                                                                                |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[SOURCE_KEY]`       | Unique identifier for element that tracks scroll progress                                                                                                                                           |
-| `[TARGET_KEY]`       | Unique identifier for element to animate (can equal source)                                                                                                                                         |
-| `[NAMED_EFFECT]`     | Preset from @wix/motion-presets (see Named Scroll Effects below). Some presets accept options (e.g. `direction`) — only use options you have documentation for; omit and rely on defaults otherwise |
-| `[EFFECT_NAME]`      | Unique name for keyframe effect                                                                                                                                                                     |
-| `[EFFECT_KEYFRAMES]` | Array of keyframe objects, e.g. `[{ opacity: '0' }, { opacity: '1' }]`                                                                                                                              |
-| `[CUSTOM_LOGIC]`     | JS: `progress` is 0–1 within range; mutate `element.style` or DOM                                                                                                                                   |
-| `[RANGE_NAME]`       | 'cover', 'contain', 'entry', 'exit', 'entry-crossing', 'exit-crossing'                                                                                                                              |
-| `[START_PERCENTAGE]` | 0–100                                                                                                                                                                                               |
-| `[END_PERCENTAGE]`   | 0–100                                                                                                                                                                                               |
-| `[EASING_FUNCTION]`  | 'linear', 'ease-in', 'ease-out', 'ease-in-out', or cubic-bezier string                                                                                                                              |
-| `[FILL_MODE]`        | 'both', 'backwards', 'forwards', 'none'                                                                                                                                                             |
-| `[UNIQUE_EFFECT_ID]` | Optional unique identifier                                                                                                                                                                          |
-| `[CONDITION_NAME]`   | User-defined condition ID declared in the top-level `conditions` map (e.g. `'prefers-motion'`, `'desktop-only'`)                                                                                    |
+## Table of Contents
 
-**Offset semantics:** Positive offset values move the effective range forward along the scroll axis. 0 = start of range, 100 = end.
+- [Rule 1: ViewProgress with keyframeEffect or namedEffect](#rule-1-viewprogress-with-keyframeeffect-or-namedeffect)
+- [Rule 2: ViewProgress with customEffect](#rule-2-viewprogress-with-customeffect)
+- [Rule 3: ViewProgress with Tall Wrapper + Sticky Container (contain range)](#rule-3-viewprogress-with-tall-wrapper--sticky-container-contain-range)
 
-## Effect Type Selection
+---
 
-| Scenario                                                      | Effect Type      | Notes                             |
-| ------------------------------------------------------------- | ---------------- | --------------------------------- |
-| Parallax, scroll-responsive decorations, floating elements    | `namedEffect`    | Use presets; fastest to implement |
-| Custom multi-property animations, brand-specific reveals      | `keyframeEffect` | Full control over CSS keyframes   |
-| Dynamic content (counters, text reveal, canvas, calculations) | `customEffect`   | JS callback; `progress` 0–1       |
+## Rule 1: ViewProgress with keyframeEffect or namedEffect
 
-## Range Reference
+**Use Case**: Scroll-driven CSS-based effects.
 
-| Intent                                  | rangeStart.name | rangeEnd.name | Typical Offsets        |
-| --------------------------------------- | --------------- | ------------- | ---------------------- |
-| Parallax / continuous while visible     | cover           | cover         | 0–100                  |
-| Entry animation (element entering view) | entry           | entry         | 0–30 start, 70–100 end |
-| Exit animation (element leaving view)   | exit            | exit          | 0–30 start, 70–100 end |
-| Cross-range (entry to exit)             | entry           | exit          | 0–100                  |
-| Contained phase                         | contain         | contain       | 0–100                  |
+**Multiple effects:** The `effects` array can contain multiple effects — all are driven by the same scroll progress. Use this to animate different targets or properties in sync with the same scroll position.
 
-## Named Scroll Effects
-
-From `@wix/motion-presets` scroll animations: ParallaxScroll, MoveScroll, FadeScroll, RevealScroll, GrowScroll, SlideScroll, SpinScroll, PanScroll, BlurScroll, ArcScroll, FlipScroll, Spin3dScroll, TiltScroll, TurnScroll, ShapeScroll, ShuttersScroll, ShrinkScroll, SkewPanScroll, StretchScroll.
-
-## Examples
-
-### Example 1: Named Effect (Parallax)
+### Template
 
 ```typescript
 {
-    key: 'hero-section',
+    key: '[SOURCE_KEY]',
     trigger: 'viewProgress',
     effects: [
         {
-            key: 'hero-background',
-            namedEffect: {
-                type: 'ParallaxScroll'
-            },
-            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
-            easing: 'linear'
-        }
-    ]
-}
-```
-
-### Example 2: Keyframe Effect (Custom Animation)
+            key: '[TARGET_KEY]',
+            // --- pick ONE of the two effect types ---
+            namedEffect: [NAMED_EFFECT_DEFINITION],
+            // OR
+            keyframeEffect: { name: '[EFFECT_NAME]', keyframes: [EFFECT_KEYFRAMES] },
 
-```typescript
-{
-    key: 'card-section',
-    trigger: 'viewProgress',
-    effects: [
-        {
-            key: 'product-card',
-            keyframeEffect: {
-                name: 'card-entrance',
-                keyframes: [
-                    { opacity: '0', transform: 'translateY(80px) scale(0.9)', filter: 'blur(5px)' },
-                    { opacity: '1', transform: 'translateY(0) scale(1)', filter: 'blur(0)' }
-                ]
-            },
-            rangeStart: { name: 'entry', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'entry', offset: { unit: 'percentage', value: 70 } },
-            easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
-            fill: 'both'
-        }
+            rangeStart: { name: '[RANGE_NAME]', offset: { unit: 'percentage', value: [START_PERCENTAGE] } },
+            rangeEnd: { name: '[RANGE_NAME]', offset: { unit: 'percentage', value: [END_PERCENTAGE] } },
+            easing: '[EASING_FUNCTION]', // usually 'linear'
+            fill: 'both',
+            effectId: '[UNIQUE_EFFECT_ID]'
+        },
+        // additional effects targeting other elements can be added here
     ]
 }
 ```
 
-### Example 3: Custom Effect (Dynamic Content)
+### Variables
 
-```typescript
-{
-    key: 'text-section',
-    trigger: 'viewProgress',
-    effects: [
-        {
-            key: 'animated-text',
-            customEffect: (element, progress) => {
-                const text = element.dataset.fullText || element.textContent;
-                const visibleLength = Math.floor(text.length * progress);
-                const visibleText = text.substring(0, visibleLength);
-                element.textContent = visibleText + (progress < 1 ? '|' : '');
+- `[SOURCE_KEY]` — identifier matching the element's key (`data-interact-key` for web, `interactKey` for React). The element whose scroll position drives the animation.
+- `[TARGET_KEY]` — identifier matching the element's key (`data-interact-key` for web, `interactKey` for React) on the element to animate (can be same as source or different).
+- `[NAMED_EFFECT_DEFINITION]` — object with properties of pre-built effect from `@wix/motion-presets`. **CRITICAL:** Scroll presets (`*Scroll`) MUST include `range: 'in' | 'out' | 'continuous'` in their options. `'in'` ends at the idle state, `'out'` starts from the idle state, `'continuous'` passes through it.
+- `[EFFECT_NAME]` — unique name for custom keyframe effect.
+- `[EFFECT_KEYFRAMES]` — array of keyframe objects defining CSS property values (e.g. `[{ opacity: 0 }, { opacity: 1 }]`). Property names in camelCase.
+- `[RANGE_NAME]` — scroll range name:
+  - `'cover'` — full visibility span from first pixel entering to last pixel leaving.
+  - `'entry'` — the phase while the element is entering the viewport.
+  - `'exit'` — the phase while the element is exiting the viewport.
+  - `'contain'` — while the element is fully contained in the viewport. Typically used with a `position: sticky` container.
+  - `'entry-crossing'` — from the element's leading edge entering to its leading edge reaching the opposite side.
+  - `'exit-crossing'` — from the element's trailing edge reaching the start to its trailing edge leaving.
+- `[START_PERCENTAGE]` — 0–100, starting point within the named range.
+- `[END_PERCENTAGE]` — 0–100, end point within the named range.
+- `[EASING_FUNCTION]` - CSS easing string or named easing from `@wix/motion`. Typically `'linear'` for scrolling effects.
+- `[UNIQUE_EFFECT_ID]` — optional identifier for referencing the effect externally.
 
-                element.style.opacity = Math.min(1, progress * 2);
-                element.style.transform = `translateY(${(1 - progress) * 30}px)`;
-            },
-            rangeStart: { name: 'entry', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'entry', offset: { unit: 'percentage', value: 80 } },
-            fill: 'both',
-            effectId: 'text-reveal'
-        }
-    ]
-}
-```
+---
 
-### Example 4: Multi-Range (Entry + Exit on the same element)
+## Rule 2: ViewProgress with customEffect
 
-Animating the same element in on scroll entry and out on scroll exit requires two separate effects within the same interaction — one scoped to the `entry` range, one to `exit`. This pattern is non-obvious because both effects share the same `key` but have different ranges.
+**Use Case**: Scroll-driven effects requiring JavaScript logic (e.g., changing SVG attributes, controlling WebGL/WebGPU effects).
+
+### Template
 
 ```typescript
 {
-    key: 'feature-card',
+    key: '[SOURCE_KEY]',
     trigger: 'viewProgress',
     effects: [
-        // Animate IN as element enters viewport
         {
-            key: 'feature-card',
-            keyframeEffect: {
-                name: 'card-in',
-                keyframes: [
-                    { opacity: '0', transform: 'translateY(40px)' },
-                    { 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'
+            key: '[TARGET_KEY]',
+            customEffect: [CUSTOM_EFFECT_CALLBACK],
+            rangeStart: { name: '[RANGE_NAME]', offset: { unit: 'percentage', value: [START_PERCENTAGE] } },
+            rangeEnd: { name: '[RANGE_NAME]', offset: { unit: 'percentage', value: [END_PERCENTAGE] } },
+            easing: `'[EASING_FUNCTION]'`, // usually 'linear'
+            fill: 'both',
+            effectId: '[UNIQUE_EFFECT_ID]'
         },
-        // Animate OUT as element exits viewport
-        {
-            key: 'feature-card',
-            keyframeEffect: {
-                name: 'card-out',
-                keyframes: [
-                    { opacity: '1', transform: 'translateY(0)' },
-                    { opacity: '0', transform: 'translateY(-40px)' }
-                ]
-            },
-            rangeStart: { name: 'exit', offset: { unit: 'percentage', value: 40 } },
-            rangeEnd: { name: 'exit', offset: { unit: 'percentage', value: 100 } },
-            easing: 'ease-in',
-            fill: 'both'
-        }
+        // additional effects targeting other elements can be added here
     ]
 }
 ```
 
-## Advanced Patterns
-
-### Multi-Range ViewProgress Effects
+### Variables
 
-Combining different ranges for complex scroll animations:
+- `[SOURCE_KEY]` / `[TARGET_KEY]` — same as Rule 1.
+- `[CUSTOM_EFFECT_CALLBACK]` — function with signature `(element: HTMLElement, progress: number) => void`. Called on each animation frame with `progress` from 0 to 1.
+- `[RANGE_NAME]` / `[START_PERCENTAGE]` / `[END_PERCENTAGE]` — same as Rule 1.
+- `[EASING_FUNCTION]` — CSS easing string or named easing from `@wix/motion`. Typically `'linear'` for scrolling effects.
+- `[UNIQUE_EFFECT_ID]` — optional identifier for referencing the effect externally.
 
-```typescript
-{
-    key: 'complex-section',
-    trigger: 'viewProgress',
-    effects: [
-        // Entry phase
-        {
-            key: 'section-content',
-            keyframeEffect: {
-                name: 'content-entrance',
-                keyframes: [
-                    { opacity: '0', transform: 'translateY(50px)' },
-                    { opacity: '1', transform: 'translateY(0)' }
-                ]
-            },
-            rangeStart: { name: 'entry', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'entry', offset: { unit: 'percentage', value: 50 } },
-            easing: 'ease-out',
-            fill: 'backwards'
-        },
-        // Cover phase
-        {
-            key: 'background-element',
-            keyframeEffect: {
-                name: 'background-parallax-hue',
-                keyframes: [
-                    { transform: 'translateY(0)', filter: 'hue-rotate(0deg)' },
-                    { transform: 'translateY(-100px)', filter: 'hue-rotate(180deg)' }
-                ]
-            },
-            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
-            easing: 'linear',
-            fill: 'both'
-        },
-        // Exit phase
-        {
-            key: 'section-content',
-            keyframeEffect: {
-                name: 'content-exit',
-                keyframes: [
-                    { opacity: '1', transform: 'scale(1)' },
-                    { opacity: '0', transform: 'scale(0.8)' }
-                ]
-            },
-            rangeStart: { name: 'exit', offset: { unit: 'percentage', value: 50 } },
-            rangeEnd: { name: 'exit', offset: { unit: 'percentage', value: 100 } },
-            easing: 'ease-in',
-            fill: 'forwards'
-        }
-    ]
-}
-```
+---
 
-### ViewProgress with Conditional Behavior
+## Rule 3: ViewProgress with Tall Wrapper + Sticky Container (contain range)
 
-Use interact `conditions` for responsive scroll animations and `prefers-reduced-motion`. Condition IDs are user-defined strings — they must be declared in the top-level `conditions` map before being referenced in an interaction.
+**Use Case**: Scroll-driven animations inside a sticky-positioned container, where the source element is a tall wrapper and the effect applies during the "stuck" phase using `position: sticky` to lock a container and `contain` range to animate only during the stuck phase. Good for heavy effects on large media elements or scrolly-telling effects.
 
-```typescript
-{
-    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: 'responsive-parallax',
-            trigger: 'viewProgress',
-            conditions: ['desktop-only', 'prefers-motion'],
-            effects: [
-                {
-                    key: 'parallax-bg',
-                    keyframeEffect: {
-                        name: 'parallax-bg',
-                        keyframes: [
-                            { transform: 'translateY(0)' },
-                            { transform: 'translateY(-300px)' }
-                        ]
-                    },
-                    rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
-                    rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
-                    easing: 'linear',
-                    fill: 'both'
-                }
-            ]
-        },
-        // Simplified fallback for mobile
-        {
-            key: 'responsive-parallax',
-            trigger: 'viewProgress',
-            conditions: ['mobile-only'],
-            effects: [
-                {
-                    key: 'parallax-bg',
-                    keyframeEffect: {
-                        name: 'fade-out-bg',
-                        keyframes: [
-                            { opacity: '1' },
-                            { opacity: '0.7' }
-                        ]
-                    },
-                    rangeStart: { name: 'exit', offset: { unit: 'percentage', value: 0 } },
-                    rangeEnd: { name: 'exit', offset: { unit: 'percentage', value: 100 } },
-                    easing: 'linear',
-                    fill: 'both'
-                }
-            ]
-        }
-    ]
-}
-```
+**Layout Structure**:
 
-### Multiple Element Coordination
+- **Tall wrapper** (`[TALL_WRAPPER_KEY]`): An element with enough height to create scroll distance (e.g., `height: 300vh`). This is the ViewTimeline source. The taller it is relative to the viewport, the longer the scroll distance and the more "duration" the animation has.
+- **Sticky container**: A direct child with `position: sticky; top: 0; height: 100vh` that stays fixed in the viewport while the wrapper scrolls past.
+- **Animated elements** (`[STICKY_CHILD_KEY]`): Children of the sticky container that receive the effects.
 
-Orchestrating multiple elements with viewProgress:
+### Template
 
 ```typescript
 {
-    key: 'orchestrated-section',
+    key: '[TALL_WRAPPER_KEY]',
     trigger: 'viewProgress',
     effects: [
         {
-            key: 'bg-layer-1',
-            keyframeEffect: {
-                name: 'layer-1-parallax',
-                keyframes: [
-                    { transform: 'translateY(0)' },
-                    { transform: 'translateY(-50px)' }
-                ]
-            },
-            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
-            easing: 'linear',
-            fill: 'both'
-        },
-        {
-            key: 'bg-layer-2',
-            keyframeEffect: {
-                name: 'layer-2-parallax',
-                keyframes: [
-                    { transform: 'translateY(0)' },
-                    { transform: 'translateY(-100px)' }
-                ]
-            },
-            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
-            easing: 'linear',
-            fill: 'both'
+            key: '[STICKY_CHILD_KEY]',
+            // Use keyframeEffect, namedEffect, or customEffect as in Rules 1–2
+            keyframeEffect: { name: '[EFFECT_NAME]', keyframes: [EFFECT_KEYFRAMES] },
+            rangeStart: { name: 'contain', offset: { unit: 'percentage', value: [START_PERCENTAGE] } },
+            rangeEnd: { name: 'contain', offset: { unit: 'percentage', value: [END_PERCENTAGE] } },
+            easing: '[EASING_FUNCTION]', // usually 'linear'
+            fill: 'both',
+            effectId: '[UNIQUE_EFFECT_ID]'
         },
-        {
-            key: 'fg-content',
-            keyframeEffect: {
-                name: 'layer-3-parallax',
-                keyframes: [
-                    { transform: 'translateY(0)' },
-                    { transform: 'translateY(-150px)' }
-                ]
-            },
-            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
-            easing: 'linear',
-            fill: 'both'
-        }
+        // additional effects targeting other elements can be added here
     ]
 }
 ```
 
-## Best Practices
-
-### Interact-Specific
-
-1. **Respect `prefers-reduced-motion`** via interact `conditions`: use `'prefers-motion'` so scroll animations run only when the user has not requested reduced motion.
-2. **Use `linear` easing** for most scroll effects; non-linear easing can feel jarring as scroll position changes.
-3. **Range configuration:** Verify source element remains visible throughout the scroll range. If the source is hidden or in a frozen stacking context, the ViewTimeline constraint may not update correctly.
-4. **Avoid overlapping ranges** on the same target to prevent conflicting animations.
-5. **Entry/exit timing:** Use 0–50% cover or 0–100% entry for entrances; 50–100% cover or 0–100% exit for exits. Start with broad ranges (0–100) then refine.
-6. **customEffect:** Use `element.closest('interact-element')` when querying related DOM within the callback; target elements must exist when the effect runs.
-
-### Troubleshooting
+### Variables
 
-- **Unexpected behavior:** Check range names match intent; verify source visibility; ensure target elements exist.
-- **Janky custom effects:** Simplify calculations; avoid layout-triggering reads in the callback.
+- `[TALL_WRAPPER_KEY]` — key for the tall outer element that defines the scroll distance — this is the ViewTimeline source.
+- `[STICKY_CHILD_KEY]` — key for the animated element inside the sticky container.
+- `[EFFECT_NAME]` / `[EFFECT_KEYFRAMES]` — same as Rule 1.
+- `[START_PERCENTAGE]` — 0–100, starting point within the `contain` range (the stuck phase).
+- `[END_PERCENTAGE]` — 0–100, end point within the `contain` range.
+- `[UNIQUE_EFFECT_ID]` — same as Rule 1.
+- `[EASING_FUNCTION]` — CSS easing string or named easing from `@wix/motion`. Typically `'linear'` for scrolling effects.