@wix/interact 2.0.0-rc.2 → 2.0.0-rc.5

package/rules/Integration.md

@@ -6,31 +6,86 @@ This document outlines the rules and best practices for generating code that int
 
 `@wix/interact` is a library for creating interactive animations and effects triggered by user actions (click, hover, scroll, etc.). It works by binding **Triggers** and **Effects** to specific **Elements**.
 
-## 2. Core Components
+## 2. Integrations
 
-### `<interact-element>`
-The custom element wrapper is **required** for any element that triggers an interaction or recieves an effect.
+### `web` :: using Custom Elements
+
+#### 1. Basic Setup
+
+**Usage:**
+
+```typescript
+import { Interact } from '@wix/interact/web';
+
+// Define your interaction configuration
+const config = {
+  interactions: [
+    // ...
+  ],
+  effects: {
+    // ...
+  }
+};
+
+// Initialize the interact instance
+const interact = Interact.create(config);
+```
+
+#### 2. HTML Setup
 
 **Rules:**
-- MUST have a `data-interact-key` attribute that is unique within the scope.
+- MUST have a `data-interact-key` attribute with a value that is unique within the scope.
 - MUST contain at least one child element.
-- **Usage:**
-  ```html
-  <interact-element data-interact-key="my-button">
-      <button>Click Me</button>
-  </interact-element>
-  ```
 
-### `Interact.create(config)`
-The entry point for initializing interactions.
+**Usage:**
+```html
+<!-- Wrap your target element with interact-element -->
+<interact-element data-interact-key="my-element">
+  <div>This will fade in when it enters the viewport!</div>
+</interact-element>
+```
+
+### `react` :: using React
+
+#### 1. Basic Setup
+
+**Usage:**
+```typescript
+import { Interact } from '@wix/interact/react';
+
+// Define your interaction configuration
+const config = {
+  interactions: [
+    // ...
+  ],
+  effects: {
+    // ...
+  }
+};
+
+// Initialize the interact instance
+const interact = Interact.create(config);
+```
+
+#### 2. HTML Setup
 
 **Rules:**
-- MUST be called at least once with the full configuration, or per page for single-page apps.
-- **Usage:**
-  ```javascript
-  import { Interact } from '@wix/interact';
-  Interact.create(config);
-  ```
+- MUST replace the element itself with the `<Interaction/>` component.
+- MUST set the `tagName` prop with the tag of the replaced element.
+- MUST set the `interactKey` prop to a unique string within the scope.
+
+**Usage:**
+```tsx
+import { Interaction } from '@wix/interact/react';
+
+function MyComponent() {
+  return (
+    <Interaction tagName="div" interactKey="my-element" className="animated-content">
+      Hello, animated world!
+    </Interaction>
+  );
+}
+```
 
 ## 3. Configuration Schema
 
@@ -60,7 +115,7 @@ type InteractConfig = {
 ### Element Selection Hierarchy
 1. **`listContainer`**: If present, selects a container to target its immediate children as list items.
 2. **`selector`**: Matches elements within the root, or within each list item.
-3. **Fallback**: If neither is provided, targets the **first child** of `<interact-element>`.
+3. **Fallback**: If neither is provided, targets the **first child** of `<interact-element>` in `web` or the root element in `react`.
 
 ## 4. Generating Critical CSS for Entrance Animations
 
@@ -69,13 +124,11 @@ Generates critical CSS styles that prevent flash-of-unstyled-content (FOUC) for
 
 **Rules:**
 - MUST be called server-side or at build time to generate static CSS.
-- The generated CSS hides the first child of elements marked with `data-interact-initial="true"` until their entrance animation completes.
-- Only affects users who have not requested reduced motion (`prefers-reduced-motion: no-preference`).
-- The `<interact-element>` MUST have `data-interact-initial="true"` attribute to be affected by the generated CSS.
+- MUST set `data-interact-initial="true"` on elements that have an entrance effect.
 
 **Usage:**
 ```javascript
-import { generate } from '@wix/interact';
+import { generate } from '@wix/interact/web';
 
 const config = {/*...*/};
 
@@ -102,25 +155,20 @@ const html = `
 ```
 
 **When to Use:**
-- For elements that have a `viewEnter` trigger with `type: 'once'`  and an effect on same element
+- For elements with an entrance efffect that is triggered a with `viewEnter`
 - To prevent elements from being visible before their entrance animation plays
 - For server-side rendering (SSR) or static site generation (SSG) scenarios
 
-**Important Notes:**
-- The attribute `data-motion-enter="done"` is automatically set by the runtime when the entrance animation completes
-- Users with `prefers-reduced-motion: reduce` will see elements immediately (no hiding)
-- The CSS resets transform properties to prevent any inherited transforms from affecting the hidden state
-
 ## 5. Triggers & Behaviors
 
-| Trigger | Description | Key Parameters |
-| :--- | :--- | :--- |
-| `hover` | Mouse enter/leave | `type`: 'once', 'alternate', 'repeat', 'state' for animations, or `method`: 'add', 'remove', 'toggle', 'clear' for states |
-| `click` | Mouse click | `type`: 'once', 'alternate', 'repeat', 'state' for animations, or `method`: 'add', 'remove', 'toggle', 'clear' for states |
-| `viewEnter` | Element enters viewport | `type`: 'once', 'alternate', 'repeat', 'state'; `threshold` (0-1) |
-| `viewProgress` | Scroll progress inside viewport | (No specific params, uses effect ranges) |
-| `pointerMove` | Mouse movement | `hitArea`: 'self' (default) or 'root' |
-| `animationEnd` | Chaining animations | `effectId`: ID of the previous effect |
+| Trigger | Description | Key Parameters | Rules File |
+| :--- | :--- | :--- | :--- |
+| `hover` | Mouse enter/leave | `type`: 'once', 'alternate', 'repeat', 'state' for animations, or `method`: 'add', 'remove', 'toggle', 'clear' for states | `./hover.md` |
+| `click` | Mouse click | `type`: 'once', 'alternate', 'repeat', 'state' for animations, or `method`: 'add', 'remove', 'toggle', 'clear' for states | `./click.md` |
+| `viewEnter` | Element enters viewport | `type`: 'once', 'alternate', 'repeat', 'state'; `threshold` (0-1) | `./viewEnter.md` |
+| `viewProgress` | Scroll-driven using ViewTimeline | (No specific params, uses effect ranges) | `./viewprogress.md` |
+| `pointerMove` | Mouse movement | `hitArea`: 'self' (default) or 'root' | `./pointermove.md` |
+| `animationEnd` | Chaining animations | `effectId`: ID of the previous effect | -- |
 
 ## 6. Effects & Animations
 
@@ -170,7 +218,8 @@ Used with `viewProgress`, linked to scroll progress while element is inside view
 {
   keyframeEffect: { ... },
   rangeStart: { name: 'cover', offset: { value: 0, type: 'percentage' } },
-  rangeEnd: { name: 'cover', offset: { value: 100, type: 'percentage' } }
+  rangeEnd: { name: 'cover', offset: { value: 100, type: 'percentage' } },
+  fill: 'both'
 }
 ```
 
@@ -252,4 +301,3 @@ const config = {
   }]
 };
 ```
-

package/rules/full-lean.md

@@ -4,8 +4,21 @@
 - Call `Interact.create(config)` once to initialize.
 - Create the full configuration up‑front and pass it in a single `create` call to avoid unintended overrides; subsequent calls replace the previous config.
 
+**For web (Custom Elements):**
 ```ts
-import { Interact } from '@wix/interact';
+import { Interact } from '@wix/interact/web';
+import type { InteractConfig } from '@wix/interact';
+
+const config: InteractConfig = {
+  // config-props
+};
+
+Interact.create(config);
+```
+
+**For React:**
+```ts
+import { Interact } from '@wix/interact/react';
 import type { InteractConfig } from '@wix/interact';
 
 const config: InteractConfig = {
@@ -19,7 +32,7 @@ Interact.create(config);
 
 ```html
 <script type="module">
-  import { Interact } from 'https://esm.sh/@wix/interact@1.86.0';
+  import { Interact } from 'https://esm.sh/@wix/interact@2.0.0-rc.4';
 
   const config = {
     // config-props
@@ -38,7 +51,7 @@ Interact.create(config);
 
 **Usage:**
 ```javascript
-import { generate } from '@wix/interact';
+import { generate } from '@wix/interact/web';
 
 const config = {/*...*/};
 
@@ -82,7 +95,7 @@ This configuration declares what user/system triggers occur on which source elem
 - **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.
 - **Conditions**: Conditions act as guards. If any condition on an interaction or effect evaluates to false, the corresponding trigger/effect WILL NOT be applied.
-- **Custom element usage**: Do NOT add observers/listeners manually. Wrap the DOM subtree with `<interact-element>` and set `data-interact-key` to the element key; use that same key in your config (`Interaction.key`/`Effect.key`). The runtime binds triggers/effects via this attribute.
+- **Element binding**: Do NOT add observers/listeners manually. For web, wrap the DOM subtree with `<interact-element>` and set `data-interact-key` to the element key. For React, use the `<Interaction>` component with `interactKey` prop. Use the same key in your config (`Interaction.key`/`Effect.key`). The runtime binds triggers/effects via this attribute.
 
 ### Structure
 - **effects: Record<string, Effect>**
@@ -171,9 +184,13 @@ This configuration declares what user/system triggers occur on which source elem
     - **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.
 
-### Working with `<interact-element>`
-- Wrap the interactive DOM subtree with the custom element and set `data-interact-key` to a stable key. Reference that same key from your config via `Interaction.key` (and optionally `Effect.key`). No observers/listeners or manual DOM querying are needed—the runtime binds triggers and effects by this attribute.
-- If an effect targets an element that is not the interaction’s source, you MUST also wrap that target element’s subtree with its own `<interact-element>` and set `data-interact-key` to the target’s key (the value used in `Effect.key` or the referenced registry Effect’s `key`). This is required so the runtime can locate and apply effects to non-source targets.
+### Working with elements
+
+#### Web: `<interact-element>` custom element
+- Wrap the interactive DOM subtree with the custom element and set `data-interact-key` to a stable key. Reference that same key from your config via `Interaction.key` (and optionally `Effect.key`). No observers/listeners or manual DOM querying are needed—the runtime binds triggers and effects via this attribute.
+- If an effect targets an element that is not the interaction's source, you MUST also wrap that target element's subtree with its own `<interact-element>` and set `data-interact-key` to the target's key (the value used in `Effect.key` or the referenced registry Effect's `key`). This is required so the runtime can locate and apply effects to non-source targets.
+- MUST have a `data-interact-key` attribute with a value that is unique within the scope.
+- MUST contain at least one child element.
 
 ```html
 <interact-element data-interact-key="my-button">
@@ -229,6 +246,45 @@ const config: InteractConfig = {
 };
 ```
 
+#### React: `<Interaction>` component
+- MUST replace the element itself with the `<Interaction/>` component.
+- MUST set the `tagName` prop with the tag of the replaced element.
+- MUST set the `interactKey` prop to a unique string within the scope.
+
+```tsx
+import { Interaction } from '@wix/interact/react';
+
+function MyComponent() {
+  return (
+    <Interaction tagName="button" interactKey="my-button" className="btn">
+      Click me
+    </Interaction>
+  );
+}
+```
+
+For a different target element:
+
+```tsx
+import { Interaction } from '@wix/interact/react';
+
+function MyComponent() {
+  return (
+    <>
+      <Interaction tagName="button" interactKey="my-button" className="btn">
+        Click me
+      </Interaction>
+
+      <Interaction tagName="span" interactKey="my-badge" className="badge">
+        Badge
+      </Interaction>
+    </>
+  );
+}
+```
+
+The config remains the same for both integrations—only the HTML/JSX setup differs.
+
 ### Effect rules (applies to both registry-defined Effect and inline Effect within interactions)
 - Common fields (`EffectBase`):
   - **key?: string**

package/rules/{viewprogress-rules.md → viewprogress.md}

@@ -1,6 +1,6 @@
 # ViewProgress Trigger Rules for @wix/interact
 
-These rules help generate scroll-driven interactions using the `@wix/interact` library. ViewProgress triggers create scroll-based animations that update continuously as elements move through the viewport, perfect for parallax effects, progress indicators, and scroll-responsive content.
+These rules help generate scroll-driven interactions using the `@wix/interact` library. `viewProgress` triggers create scroll-based animations that update continuously as elements move through the viewport, leveraging native CSS ViewTimelines.
 
 ## Rule 1: Range-Based Parallax/Continuous Animation Control with Named Effects
 
@@ -12,7 +12,7 @@ These rules help generate scroll-driven interactions using the `@wix/interact` l
 - For continuous scroll-driven decorative animations
 - When using pre-built motion effects for scroll interactions
 
-**Pattern**:
+**KeyframeEffect Pattern**:
 ```typescript
 {
     key: '[SOURCE_SELECTOR]',
@@ -20,12 +20,14 @@ These rules help generate scroll-driven interactions using the `@wix/interact` l
     effects: [
         {
             key: '[TARGET_SELECTOR]',
-            namedEffect: {
-              type: '[NAMED_EFFECT]',
+            keyframeEffect: {
+              name: '[EFFECT_NAME]',
+              keyframes: [EFFECT_KEYFRAMES]
             },
             rangeStart: { name: '[RANGE_NAME]', offset: { type: 'percentage', value: [START_PERCENTAGE] } },
             rangeEnd: { name: '[RANGE_NAME]', offset: { type: 'percentage', value: [END_PERCENTAGE] } },
             easing: '[EASING_FUNCTION]',
+            fill: 'both',
             effectId: '[UNIQUE_EFFECT_ID]'
         }
     ]
@@ -35,48 +37,50 @@ These rules help generate scroll-driven interactions using the `@wix/interact` l
 **Variables**:
 - `[SOURCE_SELECTOR]`: Unique identifier for element that tracks scroll progress
 - `[TARGET_SELECTOR]`: Unique identifier for element to animate (can be same as source or different)
-- `[NAMED_EFFECT]`: Pre-built scroll effect name from @wix/motion (e.g., 'ParallaxScroll', 'MoveScroll', 'FadeScroll', 'RevealScroll', 'GrowScroll', 'SlideScroll', 'SpinScroll', 'PanScroll', 'BlurScroll', 'ArcScroll', 'FlipScroll', 'Spin3dScroll', 'TiltScroll', 'TurnScroll', 'ShapeScroll', 'ShuttersScroll', 'ShrinkScroll', 'SkewPanScroll', 'StretchScroll')
+- `[EFFECT_NAME]`: Optional unique name for the effec
+- `[EFFECT_KEYFRAMES]`: Keyframes for the effect
 - `[RANGE_NAME]`: 'cover', 'contain', 'entry', 'exit', 'entry-crossing', or 'exit-crossing'
 - `[START_PERCENTAGE]`: Start point as percentage (0-100)
 - `[END_PERCENTAGE]`: End point as percentage (0-100)
 - `[EASING_FUNCTION]`: Timing function (typically 'linear' for smooth scroll effects)
 - `[UNIQUE_EFFECT_ID]`: Optional unique identifier
 
-**Example - Background Parallax**:
+**NamedEffect Pattern**:
 ```typescript
 {
-    key: 'hero-section',
+    key: '[SOURCE_SELECTOR]',
     trigger: 'viewProgress',
     effects: [
         {
-            key: 'hero-background',
+            key: '[TARGET_SELECTOR]',
             namedEffect: {
-                type: 'ParallaxScroll'
+              type: '[NAMED_EFFECT]'
             },
-            rangeStart: { name: 'cover', offset: { type: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { type: 'percentage', value: 100 } },
-            easing: 'linear'
+            rangeStart: { name: '[RANGE_NAME]', offset: { type: 'percentage', value: [START_PERCENTAGE] } },
+            rangeEnd: { name: '[RANGE_NAME]', offset: { type: 'percentage', value: [END_PERCENTAGE] } },
+            easing: '[EASING_FUNCTION]',
+            effectId: '[UNIQUE_EFFECT_ID]'
         }
     ]
 }
 ```
+- `[NAMED_EFFECT]`: Pre-built scroll effect name from @wix/motion (e.g., 'ParallaxScroll', 'MoveScroll', 'FadeScroll', 'RevealScroll', 'GrowScroll', 'SlideScroll', 'SpinScroll', 'PanScroll', 'BlurScroll', 'ArcScroll', 'FlipScroll', 'Spin3dScroll', 'TiltScroll', 'TurnScroll', 'ShapeScroll', 'ShuttersScroll', 'ShrinkScroll', 'SkewPanScroll', 'StretchScroll')
+
 
-**Example - Floating Element Scroll Response**:
+**Example - Background Parallax**:
 ```typescript
 {
-    key: 'content-section',
+    key: 'hero-section',
     trigger: 'viewProgress',
     effects: [
         {
-            key: 'floating-decoration',
+            key: 'hero-background',
             namedEffect: {
-                type: 'MoveScroll',
-                angle: 45  // 45-degree angle movement
+                type: 'ParallaxScroll'
             },
-            rangeStart: { name: 'entry', offset: { type: 'percentage', value: 0 } },
-            rangeEnd: { name: 'exit', offset: { type: 'percentage', value: 100 } },
-            easing: 'linear',
-            effectId: 'decoration-float'
+            rangeStart: { name: 'cover', offset: { type: 'percentage', value: 0 } },
+            rangeEnd: { name: 'cover', offset: { type: 'percentage', value: 100 } },
+            easing: 'linear'
         }
     ]
 }
@@ -180,13 +184,14 @@ These rules help generate scroll-driven interactions using the `@wix/interact` l
     effects: [
         {
             key: '[TARGET_SELECTOR]',
-            namedEffect: {
-                type: '[EXIT_EFFECT]',
-                range: 'out'
+            keyframeEffect: {
+                name: '[EFFECT_NAME]',
+                keyframes: [EFFECT_KEYFRAMES]
             },
             rangeStart: { name: 'exit', offset: { type: 'percentage', value: [EXIT_START] } },
             rangeEnd: { name: 'exit', offset: { type: 'percentage', value: [EXIT_END] } },
             easing: '[EASING_FUNCTION]',
+            fill: 'both',
             effectId: '[UNIQUE_EFFECT_ID]'
         }
     ]
@@ -194,10 +199,9 @@ These rules help generate scroll-driven interactions using the `@wix/interact` l
 ```
 
 **Variables**:
-- `[EXIT_EFFECT]`: Named exit effect (e.g., 'FadeScroll', 'SlideScroll', 'GrowScroll', 'ShrinkScroll')
 - `[EXIT_START]`: Exit animation start percentage (typically 0-30)
 - `[EXIT_END]`: Exit animation end percentage (typically 70-100)
-- Other variables same as Rule 1
+- `[EFFECT_KEYFRAMES]`: 
 
 **Example - Content Fade Out on Exit**:
 ```typescript
@@ -207,35 +211,16 @@ These rules help generate scroll-driven interactions using the `@wix/interact` l
     effects: [
         {
             key: 'hero-text',
-            namedEffect: {
-                type: 'FadeScroll',
-                range: 'out'
+            keyframeEffect: {
+                name: 'fade-out'
+                keyframes: [{
+                    opacity: 0
+                }]
             },
             rangeStart: { name: 'exit', offset: { type: 'percentage', value: 0 } },
-            rangeEnd: { name: 'exit', offset: { type: 'percentage', value: 50 } },
-            easing: 'ease-in'
-        }
-    ]
-}
-```
-
-**Example - Navigation Hide on Scroll Out**:
-```typescript
-{
-    key: 'main-content',
-    trigger: 'viewProgress',
-    effects: [
-        {
-            key: 'floating-nav',
-            namedEffect: {
-                type: 'SlideScroll',
-                direction: 'top',
-                range: 'out'
-            },
-            rangeStart: { name: 'exit', offset: { type: 'percentage', value: 20 } },
-            rangeEnd: { name: 'exit', offset: { type: 'percentage', value: 80 } },
-            easing: 'ease-in-out',
-            effectId: 'nav-hide'
+            rangeEnd: { name: 'exit', offset: { type: 'percentage', value: 100 } },
+            easing: 'ease-in',
+            fill: 'both'
         }
     ]
 }