@wix/interact 2.0.0-rc.8 → 2.0.1

package/docs/api/interaction-controller.md

@@ -25,16 +25,14 @@ const controller = Interact.getController('my-element');
 
 ```typescript
 interface IInteractionController {
-  // Properties
   element: HTMLElement;
   key: string | undefined;
   connected: boolean;
   sheet: CSSStyleSheet | null;
-  _observers: WeakMap<HTMLElement, MutationObserver>;
+  useFirstChild: boolean;
 
-  // Methods
   connect(key?: string): void;
-  disconnect(): void;
+  disconnect(options?: { removeFromCache?: boolean }): void;
   update(): void;
   toggleEffect(
     effectId: string,
@@ -45,7 +43,6 @@ interface IInteractionController {
   getActiveEffects(): string[];
   renderStyle(cssRules: string[]): void;
   watchChildList(listContainer: string): void;
-  _childListChangeHandler(listContainer: string, entries: MutationRecord[]): void;
 }
 ```
 
@@ -106,9 +103,9 @@ if (controller?.sheet) {
 }
 ```
 
-### `_observers: WeakMap<HTMLElement, MutationObserver>`
+### `useFirstChild: boolean`
 
-Internal storage for mutation observers watching list containers.
+When `true`, the interaction target is the first child (e.g. with `<interact-element>`). Set via constructor options.
 
 ## Methods
 
@@ -143,32 +140,28 @@ if (controller && !controller.connected) {
 4. Calls internal `add()` function to set up interactions
 5. Sets `connected = true` on success
 
-### `disconnect()`
+### `disconnect(options?)`
 
-Disconnects the controller from the interaction system, cleaning up all resources.
+Disconnects the controller and cleans up resources.
 
 **Signature:**
 
 ```typescript
-disconnect(): void
+disconnect(options?: { removeFromCache?: boolean }): void
 ```
 
+**Parameters:** `options.removeFromCache` - When `true`, removes the controller from `Interact.controllerCache` (e.g. when calling `remove(key)`).
+
 **Example:**
 
 ```typescript
 const controller = Interact.getController('my-element');
 if (controller?.connected) {
-  controller.disconnect();
-  console.log('Controller disconnected');
+  controller.disconnect({ removeFromCache: true });
 }
 ```
 
-**Behavior:**
-
-1. Calls internal `remove()` to clean up interactions
-2. Removes adopted stylesheet from document
-3. Clears all mutation observers
-4. Sets `connected = false`
+**Behavior:** Calls internal `remove()`, removes adopted stylesheet, clears observers, sets `connected = false`.
 
 ### `update()`
 
@@ -351,16 +344,6 @@ if (controller) {
 4. Automatically calls `addListItems` for added nodes
 5. Automatically calls `removeListItems` for removed nodes
 
-### `_childListChangeHandler(listContainer, entries)`
-
-Internal handler for mutation observer callbacks. You typically don't call this directly.
-
-**Signature:**
-
-```typescript
-_childListChangeHandler(listContainer: string, entries: MutationRecord[]): void
-```
-
 ## Usage Patterns
 
 ### Accessing Controllers
@@ -377,34 +360,15 @@ Interact.controllerCache.forEach((controller, key) => {
 });
 ```
 
-### Programmatic State Management
+### State and lists
 
 ```typescript
-const controller = Interact.getController('accordion');
-if (controller) {
-  // Check current state
-  const isExpanded = controller.getActiveEffects().includes('expanded');
-
-  // Toggle based on current state
-  controller.toggleEffect('expanded', isExpanded ? 'remove' : 'add');
-}
-```
+// Toggle effect by current state
+const c = Interact.getController('accordion');
+c?.toggleEffect('expanded', c.getActiveEffects().includes('expanded') ? 'remove' : 'add');
 
-### Dynamic List Management
-
-```typescript
-const controller = Interact.getController('todo-list');
-if (controller) {
-  // Watch for list changes
-  controller.watchChildList('.todo-items');
-
-  // Add new item - interactions apply automatically
-  const todoItems = controller.element.querySelector('.todo-items');
-  const newTodo = document.createElement('div');
-  newTodo.className = 'todo-item';
-  newTodo.textContent = 'New task';
-  todoItems?.appendChild(newTodo);
-}
+// Watch list container; new children get interactions automatically
+Interact.getController('list-key')?.watchChildList('.items');
 ```
 
 ### Refreshing Interactions
@@ -449,7 +413,7 @@ const controller = Interact.getController('my-element');
 // Safe operations - won't throw
 controller?.toggleEffect('effect', 'add');
 controller?.connect(); // Safe if already connected
-controller?.disconnect(); // Safe if already disconnected
+controller?.disconnect({}); // Safe if already disconnected
 
 // Check connection status
 if (!controller?.connected) {

package/docs/api/types.md

@@ -161,16 +161,14 @@ Interface for the controller that manages interactions on an element. This is th
 
 ```typescript
 interface IInteractionController {
-  // Properties
   element: HTMLElement;
   key: string | undefined;
   connected: boolean;
   sheet: CSSStyleSheet | null;
-  _observers: WeakMap<HTMLElement, MutationObserver>;
+  useFirstChild: boolean;
 
-  // Methods
   connect(key?: string): void;
-  disconnect(): void;
+  disconnect(options?: { removeFromCache?: boolean }): void;
   update(): void;
   toggleEffect(
     effectId: string,
@@ -181,7 +179,6 @@ interface IInteractionController {
   getActiveEffects(): string[];
   renderStyle(cssRules: string[]): void;
   watchChildList(listContainer: string): void;
-  _childListChangeHandler(listContainer: string, entries: MutationRecord[]): void;
 }
 ```
 
@@ -189,14 +186,14 @@ interface IInteractionController {
 
 - `element` - The DOM element this controller manages
 - `key` - The unique identifier for this element's interactions
-- `connected` - Whether the controller is currently connected to the interaction system
+- `connected` - Whether the controller is currently connected
 - `sheet` - The adopted stylesheet for dynamic CSS rules
-- `_observers` - Internal storage for mutation observers
+- `useFirstChild` - When true, interaction target is the first child (e.g. custom elements)
 
 **Methods:**
 
 - `connect(key?)` - Connects the controller to the interaction system
-- `disconnect()` - Disconnects and cleans up all resources
+- `disconnect(options?)` - Disconnects and cleans up; `removeFromCache: true` removes from `Interact.controllerCache`
 - `update()` - Disconnects and reconnects (refreshes interactions)
 - `toggleEffect()` - Toggles a CSS state effect on the element
 - `getActiveEffects()` - Returns array of currently active effect IDs
@@ -232,7 +229,7 @@ interface IInteractElement extends HTMLElement {
   connectedCallback(): void;
   disconnectedCallback(): void;
   connect(key?: string): void;
-  disconnect(): void;
+  disconnect(options?: { removeFromCache?: boolean }): void;
   toggleEffect(effectId: string, method: StateParams['method'], item?: HTMLElement | null): void;
   getActiveEffects(): string[];
 }
@@ -362,19 +359,18 @@ type ViewEnterParams = {
   type?: ViewEnterType;
   threshold?: number;
   inset?: string;
+  useSafeViewEnter?: boolean;
 };
 
-type ViewEnterType = 'once' | 'repeat' | 'alternate';
+type ViewEnterType = 'once' | 'repeat' | 'alternate' | 'state';
 ```
 
 **Properties:**
 
-- `type` - How the trigger behaves on repeated intersections
-  - `'once'` - Trigger only the first time (default)
-  - `'repeat'` - Trigger every time element enters viewport
-  - `'alternate'` - Alternate between enter/exit effects
+- `type` - How the trigger behaves: `'once'` (default), `'repeat'`, `'alternate'`, `'state'` (play on enter, pause on exit)
 - `threshold` - Percentage of element that must be visible (0-1)
 - `inset` - CSS-style inset to shrink the root intersection area
+- `useSafeViewEnter` - When true, handles elements taller than viewport
 
 **Examples:**
 
@@ -438,22 +434,25 @@ const hoverState: StateParams = {
 Parameters for pointer/mouse movement triggers.
 
 ```typescript
+type PointerMoveAxis = 'x' | 'y';
+
 type PointerMoveParams = {
   hitArea?: 'root' | 'self';
+  axis?: PointerMoveAxis;
 };
 ```
 
 **Properties:**
 
-- `hitArea` - Defines the area that responds to pointer movement
-  - `'self'` - Only the source element (default)
-  - `'root'` - The entire viewport/root container
+- `hitArea` - `'self'` (default) or `'root'` (viewport)
+- `axis` - `'x'` or `'y'` (default `'y'`) for scrub direction
 
 **Example:**
 
 ```typescript
 const pointerParams: PointerMoveParams = {
-  hitArea: 'root', // Track mouse across entire page
+  hitArea: 'self',
+  axis: 'y',
 };
 ```
 
@@ -605,8 +604,8 @@ type ScrubEffect = {
 // Parallax background
 const parallaxEffect: ScrubEffect = {
   easing: 'linear',
-  rangeStart: { name: 'contain', offset: { value: 0, type: 'percentage' } },
-  rangeEnd: { name: 'contain', offset: { value: 100, type: 'percentage' } },
+  rangeStart: { name: 'contain', offset: { value: 0, unit: 'percentage' } },
+  rangeEnd: { name: 'contain', offset: { value: 100, unit: 'percentage' } },
   keyframeEffect: {
     name: 'parallax',
     keyframes: [{ transform: 'translateY(0)' }, { transform: 'translateY(-50px)' }],
@@ -750,8 +749,8 @@ type EffectProperty =
 **Types:**
 
 - `keyframeEffect` - Raw keyframe animation definition
-- `namedEffect` - Pre-built animation from `@wix/motion`
-- `customEffect` - Custom animation function
+- `namedEffect` - Pre-built animations from `@wix/motion-presets`
+- `customEffect` - Function `(element: Element, progress: number) => void` for custom scrub/behavior
 
 **Examples:**
 
@@ -769,18 +768,13 @@ const keyframeEffect = {
 
 // Named effect
 const namedEffect = {
-  namedEffect: {
-    type: 'SlideIn',
-  }, // Pre-built animation
+  namedEffect: { type: 'SlideIn' },
 };
 
-// Custom effect
+// Custom effect (signature: element, progress)
 const customEffect = {
-  customEffect: (element: HTMLElement) => {
-    // Custom animation logic
-    return element.animate([{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }], {
-      duration: 1000,
-    });
+  customEffect: (element: Element, progress: number) => {
+    (element as HTMLElement).style.opacity = String(progress);
   },
 };
 ```
@@ -793,17 +787,15 @@ Defines conditional logic for interactions.
 
 ```typescript
 type Condition = {
-  type: 'media' | 'container';
+  type: 'media' | 'container' | 'selector';
   predicate?: string;
 };
 ```
 
 **Properties:**
 
-- `type` - Type of condition check
-  - `'media'` - Media query condition
-  - `'container'` - Container query condition
-- `predicate` - The query string to evaluate
+- `type` - `'media'` (media query), `'container'` (container query), or `'selector'`
+- `predicate` - The query string or selector to evaluate
 
 **Examples:**
 
@@ -831,31 +823,7 @@ const wideContainer: Condition = {
 };
 ```
 
-## Handler Types
-
-### `InteractionHandlerModule`
-
-Interface for trigger handler modules.
-
-```typescript
-type InteractionHandlerModule<T extends TriggerType> = {
-  registerOptionsGetter?: (getter: () => any) => void;
-  add: (
-    source: HTMLElement,
-    target: HTMLElement,
-    effect: Effect,
-    options: InteractionParamsTypes[T],
-    interactOptions: InteractOptions,
-  ) => void;
-  remove: (element: HTMLElement) => void;
-};
-```
-
-**Properties:**
-
-- `registerOptionsGetter` - Optional function to register global options getter
-- `add` - Function to add a handler for this trigger type
-- `remove` - Function to remove all handlers from an element
+## Trigger parameter types
 
 ### `InteractionParamsTypes`
 
@@ -865,6 +833,8 @@ Map of trigger types to their parameter types.
 type InteractionParamsTypes = {
   hover: StateParams | PointerTriggerParams;
   click: StateParams | PointerTriggerParams;
+  interest: StateParams | PointerTriggerParams;
+  activate: StateParams | PointerTriggerParams;
   viewEnter: ViewEnterParams;
   pageVisible: ViewEnterParams;
   animationEnd: AnimationEndParams;
@@ -873,27 +843,6 @@ type InteractionParamsTypes = {
 };
 ```
 
-## Cache and Internal Types
-
-### `InteractCache`
-
-Internal cache structure for parsed configuration.
-
-```typescript
-type InteractCache = {
-  effects: { [effectId: string]: Effect };
-  conditions: { [conditionId: string]: Condition };
-  interactions: {
-    [key: string]: {
-      triggers: Interaction[];
-      effects: Record<string, (InteractionTrigger & { effect: Effect | EffectRef })[]>;
-      interactionIds: Set<string>;
-      selectors: Set<string>;
-    };
-  };
-};
-```
-
 ### `TriggerParams`
 
 Union type of all trigger parameter types.
@@ -907,68 +856,6 @@ type TriggerParams =
   | AnimationEndParams;
 ```
 
-## Utility Types
-
-### `HandlerObject`
-
-Internal type for event handler management.
-
-```typescript
-type HandlerObject = {
-  source: HTMLElement;
-  target: HTMLElement;
-  cleanup: () => void;
-  handler?: () => void;
-};
-
-type HandlerObjectMap = WeakMap<HTMLElement, Set<HandlerObject>>;
-```
-
-### Configuration Builders
-
-```typescript
-// Type-safe configuration builder
-class InteractConfigBuilder {
-  private config: Partial<InteractConfig> = { interactions: [], effects: {} };
-
-  addInteraction(interaction: Interaction): this {
-    this.config.interactions!.push(interaction);
-    return this;
-  }
-
-  addEffect(id: string, effect: Effect): this {
-    this.config.effects![id] = effect;
-    return this;
-  }
-
-  addCondition(id: string, condition: Condition): this {
-    if (!this.config.conditions) this.config.conditions = {};
-    this.config.conditions[id] = condition;
-    return this;
-  }
-
-  build(): InteractConfig {
-    return this.config as InteractConfig;
-  }
-}
-
-// Usage
-const config = new InteractConfigBuilder()
-  .addEffect('fade', {
-    duration: 1000,
-    keyframeEffect: {
-      name: 'fade',
-      keyframes: [{ opacity: 0 }, { opacity: 1 }],
-    },
-  })
-  .addInteraction({
-    trigger: 'viewEnter',
-    key: 'hero',
-    effects: [{ effectId: 'fade' }],
-  })
-  .build();
-```
-
 ## See Also
 
 - [Interact Class](interact-class.md) - Main API class

package/docs/guides/effects-and-animations.md

@@ -108,8 +108,8 @@ Scrub effects are progress-based animations that respond to scroll position or p
     },
     // No duration - controlled by scroll/pointer progress
     easing: 'linear',
-    rangeStart: { name: 'cover', offset: { type: 'percentage', value: 0 } },
-    rangeEnd: { name: 'cover', offset: { type: 'percentage', value: 100 } }
+    rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
+    rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } }
 }
 ```
 
@@ -127,8 +127,8 @@ Control when the animation starts and stops:
             { opacity: '0' }
         ]
     },
-    rangeStart: { name: 'cover', offset: { type: 'percentage', value: 30 } },  // Start at 30% scroll
-    rangeEnd: { name: 'cover', offset: { type: 'percentage', value: 80 } }     // End at 80% scroll
+    rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 30 } },  // Start at 30% scroll
+    rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 80 } }     // End at 80% scroll
 }
 ```
 
@@ -153,8 +153,8 @@ TBD
                     { transform: 'translateY(-150px)' }
                 ]
             },
-            rangeStart: { name: 'cover', offset: { type: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { type: 'percentage', value: 100 } }
+            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
+            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } }
         },
         // Text fades out faster
         {
@@ -166,8 +166,8 @@ TBD
                     { opacity: '0', transform: 'translateY(-50px)' }
                 ]
             },
-            rangeStart: { name: 'cover', offset: { type: 'percentage', value: 20 } },
-            rangeEnd: { name: 'cover', offset: { type: 'percentage', value: 60 } }
+            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 20 } },
+            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 60 } }
         }
     ]
 }
@@ -450,7 +450,7 @@ Avoid animating:
 ### Named Effects vs Keyframes
 
 ```typescript
-// Preferred - optimized by @wix/motion
+// Preferred - optimized; from @wix/motion-presets
 {
     namedEffect: {
         type: 'FadeIn'

package/docs/guides/understanding-triggers.md

@@ -302,6 +302,7 @@ The `viewEnter` trigger uses Intersection Observer to detect when elements enter
 - **`once`** (recommended): Triggers only when element first enters viewport
 - **`repeat`**: Triggers every time element enters viewport
 - **`alternate`**: Plays forward on enter, reverses on exit
+- **`state`**: Plays on enter, pauses on exit
 
 ### Real-World Example: Staggered Card Animation
 
@@ -393,8 +394,8 @@ The `viewProgress` trigger creates scroll-driven animations as elements move thr
                     { filter: 'grayscale(100%)' }
                 ]
             },
-            rangeStart: { name: 'exit', offset: { type: 'percentage', value: 0 } },
-            rangeEnd: { name: 'exit', offset: { type: 'percentage', value: 100 } }
+            rangeStart: { name: 'exit', offset: { unit: 'percentage', value: 0 } },
+            rangeEnd: { name: 'exit', offset: { unit: 'percentage', value: 100 } }
         },
         {
             key: 'foreground-text',
@@ -405,8 +406,8 @@ The `viewProgress` trigger creates scroll-driven animations as elements move thr
                     { opacity: '0', transform: 'scale(0.8)' }
                 ]
             },
-            rangeStart: { name: 'exit', offset: { type: 'percentage', value: 0 } },
-            rangeEnd: { name: 'exit', offset: { type: 'percentage', value: 100 } }
+            rangeStart: { name: 'exit', offset: { unit: 'percentage', value: 0 } },
+            rangeEnd: { name: 'exit', offset: { unit: 'percentage', value: 100 } }
         }
     ]
 }
@@ -428,14 +429,14 @@ The `viewProgress` trigger creates scroll-driven animations as elements move thr
                     { transform: 'scaleX(1)' }
                 ]
             },
-            rangeStart: { name: 'cover', offset: { type: 'percentage', value: 0 } },
-            rangeEnd: { name: 'cover', offset: { type: 'percentage', value: 100 } }
+            rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
+            rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } }
         }
     ]
 }
 ```
 
-## 8. PointerMove Trigger
+## 7. PointerMove Trigger
 
 The `pointerMove` trigger creates mouse-following effects and 3D interactions.
 
@@ -467,7 +468,8 @@ The `pointerMove` trigger creates mouse-following effects and 3D interactions.
     key: 'card-section',
     trigger: 'pointerMove',
     params: {
-        hitArea: 'self'  // 'self' | 'root'
+        hitArea: 'self',  // 'self' | 'root'
+        axis: 'y'         // 'x' | 'y' – scrub axis (default 'y')
     },
     effects: [
         {
@@ -508,7 +510,7 @@ The `pointerMove` trigger creates mouse-following effects and 3D interactions.
 }
 ```
 
-## 9. AnimationEnd Trigger
+## 8. AnimationEnd Trigger
 
 The `animationEnd` trigger allows you to chain animations by waiting for a previous animation to complete.
 

package/docs/integration/react.md

@@ -64,13 +64,14 @@ The `Interaction` component is a wrapper that automatically manages interaction
 
 ### Props
 
-| Prop          | Type                          | Required | Description                                                      |
-| ------------- | ----------------------------- | -------- | ---------------------------------------------------------------- |
-| `tagName`     | `keyof JSX.IntrinsicElements` | Yes      | The HTML element to render (e.g., `'div'`, `'button'`, `'span'`) |
-| `interactKey` | `string`                      | Yes      | Unique identifier matching the interaction configuration         |
-| `children`    | `React.ReactNode`             | No       | Child elements to render                                         |
-| `ref`         | `React.Ref<any>`              | No       | Forwarded ref to the underlying DOM element                      |
-| `...rest`     | `JSX.IntrinsicElements[T]`    | No       | Any valid props for the specified `tagName`                      |
+| Prop          | Type                          | Required | Description                                                                                   |
+| ------------- | ----------------------------- | -------- | --------------------------------------------------------------------------------------------- |
+| `tagName`     | `keyof JSX.IntrinsicElements` | Yes      | The HTML element to render (e.g., `'div'`, `'button'`, `'span'`)                              |
+| `interactKey` | `string`                      | Yes      | Unique identifier matching the interaction configuration                                      |
+| `initial`     | `boolean`                     | No       | When `true`, sets `data-interact-initial="true"` for FOUC prevention with entrance animations |
+| `children`    | `React.ReactNode`             | No       | Child elements to render                                                                      |
+| `ref`         | `React.Ref<any>`              | No       | Forwarded ref to the underlying DOM element                                                   |
+| `...rest`     | `JSX.IntrinsicElements[T]`    | No       | Any valid props for the specified `tagName`                                                   |
 
 ### Basic Usage
 
@@ -385,12 +386,14 @@ import { Interact, Interaction, InteractConfig } from '@wix/interact/react';
 const config: InteractConfig = {
   effects: {
     expanded: {
-      transitionEffect: {
-        properties: ['max-height', 'padding'],
-        from: { maxHeight: '0px', padding: '0' },
-        to: { maxHeight: '200px', padding: '16px' },
+      transition: {
+        duration: 300,
+        easing: 'ease-out',
+        styleProperties: [
+          { name: 'max-height', value: '200px' },
+          { name: 'padding', value: '16px' },
+        ],
       },
-      duration: 300,
     },
   },
   interactions: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/interact",
-  "version": "2.0.0-rc.8",
+  "version": "2.0.1",
   "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-incubator/interact/issues"
   },
   "dependencies": {
-    "@wix/motion": "^2.0.0-rc.6",
+    "@wix/motion": "^2.0.0",
     "fastdom": "^1.0.12",
     "fizban": "^0.7.2",
     "kuliso": "^0.4.13"
@@ -86,6 +86,5 @@
     "typescript": "^5.9.3",
     "vite": "^7.2.2",
     "vitest": "^4.0.14"
-  },
-  "stableVersion": "2.0.0-rc.6"
+  }
 }