@wix/interact 2.0.0-rc.7 → 2.0.0

package/docs/api/functions.md

@@ -8,15 +8,15 @@ The `@wix/interact` package exports standalone functions for managing interactio
 import { add, remove, generate } from '@wix/interact';
 ```
 
-> **Note**: The `add` and `remove` functions are available from both `@wix/interact/web` and `@wix/interact/react` entry points. The `generate` function is only available from the main `@wix/interact` entry point.
+> **Note**: `add`, `remove`, and `generate` are available from all entry points: `@wix/interact`, `@wix/interact/web`, and `@wix/interact/react`.
 
 ## Functions Overview
 
-| Function     | Purpose                                                   | Parameters        | Returns  |
-| ------------ | --------------------------------------------------------- | ----------------- | -------- |
-| `add()`      | Add interactions to an element                            | `element`, `key?` | `void`   |
-| `remove()`   | Remove interactions from an element                       | `key`             | `void`   |
-| `generate()` | Generate CSS for hiding elements with entrance animations | `config`          | `string` |
+| Function     | Purpose                                                   | Parameters                 | Returns  |
+| ------------ | --------------------------------------------------------- | -------------------------- | -------- |
+| `add()`      | Add interactions to an element                            | `element`, `key?`          | `void`   |
+| `remove()`   | Remove interactions from an element                       | `key`                      | `void`   |
+| `generate()` | Generate CSS for hiding elements with entrance animations | `config`, `useFirstChild?` | `string` |
 
 ---
 
@@ -196,40 +196,39 @@ console.log('Interactions removed for hero');
 
 ---
 
-## `generate(config)`
+## `generate(config, useFirstChild?)`
 
-Generates CSS styles needed to hide elements that have entrance animations with a `viewEnter` trigger. This prevents a flash of unstyled content (FOUC) where elements briefly appear before their entrance animation starts.
+Generates CSS styles needed to hide elements that have entrance animations with a `viewEnter` trigger and `type: 'once'`. This prevents a flash of unstyled content (FOUC) where elements briefly appear before their entrance animation starts.
 
 ### Signature
 
 ```typescript
-function generate(config: InteractConfig): string;
+function generate(config: InteractConfig, useFirstChild?: boolean): string;
 ```
 
 ### Parameters
 
-**`config: InteractConfig`**
+**`config: InteractConfig`** - The interaction configuration; used to find `viewEnter`/`once` interactions and build selectors.
 
-- The interaction configuration object
-- Used to determine which elements need initial hiding styles
+**`useFirstChild?: boolean`** - When `true`, targets the first child of each key (e.g. for `<interact-element>`). Default `false`.
 
 ### Returns
 
-**`string`** - A CSS string that can be injected into a `<style>` tag or stylesheet
+**`string`** - A CSS string to inject into a `<style>` tag or stylesheet.
 
 ### Generated CSS
 
 The function generates CSS that:
 
-1. **Respects reduced motion preferences**: Wrapped in `@media (prefers-reduced-motion: no-preference)` to ensure accessibility
-2. **Targets first child of elements with `data-interact-initial="true"`**: Only affects elements explicitly marked for entrance animations
-3. **Excludes completed animations**: Uses `:not([data-interact-enter="done"])` to show elements after their animation completes
+1. **Respects reduced motion**: Wrapped in `@media (prefers-reduced-motion: no-preference)`.
+2. **Targets elements by key**: Selectors use `[data-interact-key="..."]` for each interaction key that has a `viewEnter`/`once` entrance.
+3. **Excludes completed animations**: Uses `:not([data-interact-enter])` so elements are shown after the animation runs.
 
-**For the `web` integration (with custom elements)**:
+**With `useFirstChild: false` (vanilla/React, element is the target)**:
 
 ```css
 @media (prefers-reduced-motion: no-preference) {
-  [data-interact-initial='true'] > :first-child:not([data-interact-enter='done']) {
+  [data-interact-key='hero']:not([data-interact-enter]) {
     visibility: hidden;
     transform: none;
     translate: none;
@@ -239,11 +238,11 @@ The function generates CSS that:
 }
 ```
 
-**For other integrations (without custom elements)**:
+**With `useFirstChild: true` (e.g. custom elements, first child is the target)**:
 
 ```css
 @media (prefers-reduced-motion: no-preference) {
-  [data-interact-initial='true']:not([data-interact-enter='done']) {
+  [data-interact-key='hero'] > :first-child:not([data-interact-enter]) {
     visibility: hidden;
     transform: none;
     translate: none;
@@ -283,8 +282,8 @@ const config = {
   effects: {},
 };
 
-// Generate the CSS
-const css = generate(config);
+// Generate the CSS (pass true when using custom elements so first child is targeted)
+const css = generate(config, false);
 
 // Inject into page
 const styleElement = document.createElement('style');
@@ -328,21 +327,7 @@ const html = `
 
 ### HTML Setup
 
-For the generated CSS to work, the `<interact-element>` must have the `data-interact-initial="true"` attribute:
-
-```html
-<interact-element data-interact-key="hero" data-interact-initial="true">
-  <!-- First child will be hidden until viewEnter animation completes -->
-  <section class="hero">
-    <h1>Welcome</h1>
-  </section>
-</interact-element>
-
-<!-- Without the attribute, element is visible immediately -->
-<interact-element data-interact-key="footer">
-  <footer>Footer content</footer>
-</interact-element>
-```
+Elements must have `data-interact-key` matching the interaction key in your config. When using `<interact-element>`, use `generate(config, true)` so the first child is targeted. With the React `Interaction` component, use `initial={true}` to set `data-interact-initial="true"` for FOUC prevention; the generated CSS still selects by `data-interact-key`.
 
 ---
 

package/docs/api/interact-class.md

@@ -5,7 +5,7 @@ The `Interact` class is the main entry point for managing interactions in your a
 ## Import
 
 ```typescript
-// Web entry point with automatic custom-eleemnt registration
+// Web entry point with automatic custom-element registration
 import { Interact } from '@wix/interact/web';
 
 // React entry point
@@ -20,19 +20,23 @@ import { Interact } from '@wix/interact';
 ```typescript
 class Interact {
   // Static methods
-  static create(config: InteractConfig): Interact
-  static getInstance(key: string): Interact | undefined
-  static destroy(): void
-  static setup(options: { forceReducedMotion?: boolean, ... }): void
-  static registerEffects(effects: Record<string, NamedEffect>): void
-  static getController(key: string): IInteractController | undefined
-
+  static create(config: InteractConfig, options?: { useCutsomElement?: boolean }): Interact;
+  static getInstance(key: string): Interact | undefined;
+  static destroy(): void;
+  static setup(options: {
+    scrollOptionsGetter?: () => Partial<scrollConfig>;
+    pointerOptionsGetter?: () => Partial<PointerConfig>;
+    viewEnter?: Partial<ViewEnterParams>;
+    allowA11yTriggers?: boolean;
+  }): void;
+  static registerEffects(effects: Record<string, NamedEffect>): void;
+  static getController(key: string | undefined): IInteractionController | undefined;
 
   // Instance methods
-  init(config: InteractConfig): void
-  destroy(): void
-  has(key: string): boolean
-  get(key: string): CachedInteractionData | undefined
+  init(config: InteractConfig, options?: { useCutsomElement?: boolean }): void;
+  destroy(): void;
+  has(key: string): boolean;
+  get(key: string): InteractCache['interactions'][string] | undefined;
 }
 ```
 
@@ -125,22 +129,29 @@ Configures global settings for the Interact system.
 
 **Parameters:**
 
-- `options: { forceReducedMotion?: boolean, viewEnter?: object, viewProgress?: object, pointerMove?: object, allowA11yTriggers?: boolean}`
+- `options.scrollOptionsGetter` - Optional callback returning default partial scroll config for `viewProgress` trigger
+- `options.pointerOptionsGetter` - Optional callback returning default partial pointer config for `pointerMove` trigger
+- `options.viewEnter` - Optional default partial `ViewEnterParams` (e.g. `threshold`, `inset`, `useSafeViewEnter`)
+- `options.allowA11yTriggers` - When `true`, `click` and `hover` triggers also respond to keyboard (Enter/Space) and focus
+
+To force reduced motion globally, set `Interact.forceReducedMotion = true` (static property, not via `setup`).
 
 **Example:**
 
 ```typescript
-// Force reduced motion globally
+// Configure viewEnter defaults
 Interact.setup({
-  forceReducedMotion: true,
+  viewEnter: { threshold: 0.5 },
 });
 
-// Configure trigger-specific options
+// Provide scroll/pointer options via getters
 Interact.setup({
-  viewEnter: { threshold: 0.5 },
-  viewProgress: {
-    /* scroll options */
-  },
+  scrollOptionsGetter: () => ({
+    /* scroll config */
+  }),
+  pointerOptionsGetter: () => ({
+    /* pointer config */
+  }),
 });
 
 // Enable accessibility for click and hover triggers

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

@@ -124,7 +124,7 @@ type Interaction = {
 
 - `key` - Unique identifier for the custom element that triggers the interaction
 - `trigger` - Type of trigger event
-- `selector` - Optional CSS selector to target an element within the custom element or within each list item if combined with `listContainer`
+- `selector` - Optional CSS selector to target elements. When `listContainer` is also specified, uses `querySelectorAll` within the container to find matching elements as list items. Without `listContainer`, uses `querySelectorAll` within the root element. For dynamically added list items, uses `querySelector` within each item.
 - `listContainer` - Optional selector for list container when targeting list items
 - `params` - Optional parameters for the trigger
 - `conditions` - Optional array of condition IDs to evaluate
@@ -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',
 };
 ```
 
@@ -516,7 +515,7 @@ type Fill = 'none' | 'forwards' | 'backwards' | 'both';
 **Properties:**
 
 - `key` - unique identifier for targeting a custom element (optional, defaults to source key from the `Interaction`)
-- `selector` - CSS selector for targeting an element inside the custom element or each list item if combined with `listContainer` (optional, defaults to `firstElementChild`)
+- `selector` - CSS selector for targeting elements inside the custom element (uses `querySelectorAll`) or each list item if combined with `listContainer` (optional, defaults to `firstElementChild`)
 - `listContainer` - CSS selector for list container when targeting list items (optional)
 - `duration` - Animation duration in milliseconds (required)
 - `easing` - Easing function name or custom cubic-bezier
@@ -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