@wix/interact 2.0.0-rc.8 → 2.0.1

package/rules/click.md

@@ -61,8 +61,7 @@ These rules help generate click-based interactions using the `@wix/interact` lib
             key: 'mobile-nav',
             namedEffect: {
                 type: 'SlideIn',
-                direction: 'left',
-                power: 'medium'
+                direction: 'left'
             },
             fill: 'both',
             reversed: true,
@@ -119,14 +118,14 @@ These rules help generate click-based interactions using the `@wix/interact` lib
 
 ```typescript
 {
-    source: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_IDENTIFIER]',
     trigger: 'click',
     params: {
         type: 'state'
     },
     effects: [
         {
-            target: '[TARGET_IDENTIFIER]',
+            key: '[TARGET_IDENTIFIER]',
             [EFFECT_TYPE]: [EFFECT_DEFINITION],
             fill: 'both',
             reversed: [INITIAL_REVERSED_BOOL],
@@ -277,8 +276,7 @@ These rules help generate click-based interactions using the `@wix/interact` lib
             key: 'success-badge',
             namedEffect: {
                 type: 'BounceIn',
-                direction: 'center',
-                power: 'medium'
+                direction: 'center'
             },
             duration: 600,
             easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
@@ -309,7 +307,7 @@ These rules help generate click-based interactions using the `@wix/interact` lib
     key: '[SOURCE_IDENTIFIER]',
     trigger: 'click',
     params: {
-        type: 'alternate'
+        method: 'toggle'
     },
     effects: [
         {
@@ -342,7 +340,7 @@ These rules help generate click-based interactions using the `@wix/interact` lib
     key: 'theme-switcher',
     trigger: 'click',
     params: {
-        type: 'alternate'
+        method: 'toggle'
     },
     effects: [
         {
@@ -370,7 +368,7 @@ These rules help generate click-based interactions using the `@wix/interact` lib
     key: 'style-toggle',
     trigger: 'click',
     params: {
-        type: 'alternate'
+        method: 'toggle'
     },
     effects: [
         {
@@ -397,7 +395,7 @@ These rules help generate click-based interactions using the `@wix/interact` lib
     key: 'interactive-card',
     trigger: 'click',
     params: {
-        type: 'alternate'
+        method: 'toggle'
     },
     effects: [
         {

package/rules/full-lean.md

@@ -34,7 +34,7 @@ Interact.create(config);
 
 ```html
 <script type="module">
-  import { Interact } from 'https://esm.sh/@wix/interact@2.0.0-rc.4';
+  import { Interact } from 'https://esm.sh/@wix/interact';
 
   const config = {
     // config-props
@@ -48,7 +48,7 @@ Interact.create(config);
 
 - Use `generate(config)` to create critical CSS that hides elements until their `viewEnter` entrance animation plays.
 - Add `data-interact-initial="true"` to the `<interact-element>` that should have its first child hidden initially.
-- Only use `data-interact-initial="true"` for `<interact-element>` with `viewEnter` trigger.
+- Only use `data-interact-initial="true"` for `<interact-element>` with `viewEnter` trigger and `type: 'once'`, where the source and target elements are the same.
 - Do NOT use for `hover` or `click` interactions.
 
 **Usage:**
@@ -115,9 +115,10 @@ This configuration declares what user/system triggers occur on which source elem
   - **Purpose**: Named predicates that gate interactions/effects by runtime context.
   - **Key (string)**: The condition id. MUST be unique across the registry.
   - **Value (Condition)**:
-    - **type**: `'media' | 'container'`
+    - **type**: `'media' | 'container' | 'selector'`
       - `'media'`: The predicate MUST be a valid CSS media query expression without the outer `@media` keyword (e.g., `'(min-width: 768px)'`).
       - `'container'`: The predicate SHOULD be a valid CSS container query condition string relative to the relevant container context.
+      - `'selector'`: The predicate is a CSS selector pattern. If it contains `&`, the `&` is replaced with the base element selector; otherwise the predicate is appended to the base selector. Used for conditional styling (e.g., `:nth-of-type(odd)`, `.active`).
     - **predicate?**: OPTIONAL textual predicate for the given type. If omitted, the condition is treated as always-true (i.e., a no-op guard).
 
 - **interactions: Interaction[]**
@@ -131,13 +132,13 @@ This configuration declares what user/system triggers occur on which source elem
       - OPTIONAL. A CSS selector used to select items within `listContainer`.
     - **trigger: TriggerType**
       - REQUIRED. One of:
-        - `'hover' | 'click'`: Pointer interactions.
+        - `'hover' | 'click' | 'activate' | 'interest'`: Pointer interactions (`activate` = click with keyboard Space/Enter; `interest` = hover with focus).
         - `'viewEnter' | 'pageVisible' | 'viewProgress'`: Viewport visibility/progress triggers.
         - `'animationEnd'`: Fires when a specific effect completes on the source element.
         - `'pointerMove'`: Continuous pointer motion over an area.
     - **params?: TriggerParams**
       - OPTIONAL. Parameter object that MUST match the trigger:
-        - hover/click: `StateParams | PointerTriggerParams`
+        - hover/click/activate/interest: `StateParams | PointerTriggerParams` (activate uses same params as click; interest uses same params as hover).
           - `StateParams.method`: `'add' | 'remove' | 'toggle' | 'clear'`
           - `PointerTriggerParams.type?`: `'once' | 'repeat' | 'alternate' | 'state'`
           - Usage:
@@ -153,13 +154,14 @@ This configuration declares what user/system triggers occur on which source elem
               - `'once'`: Play once and remove the listener (hover attaches only the enter listener; no leave).
               - `'state'`: Hover — play on enter if idle/paused, pause on leave if running. Click — toggle play/pause on successive clicks until finished.
         - viewEnter/pageVisible/viewProgress: `ViewEnterParams`
-          - `type?`: `'once' | 'repeat' | 'alternate'`
+          - `type?`: `'once' | 'repeat' | 'alternate' | 'state'`
           - `threshold?`: number in [0,1] describing intersection threshold
           - `inset?`: string CSS-style inset for rootMargin/observer geometry
           - Usage:
             - `'once'`: Play on first visibility and unobserve the element.
             - `'repeat'`: Play each time the element re‑enters visibility according to `threshold`/`inset`.
             - `'alternate'`: Triggers on re‑entries; if you need alternating direction, set it on the effect (e.g., `alternate: true`) rather than relying on the trigger.
+            - `'state'`: Play on entry, pause on exit (for looping/continuous animations).
             - `threshold`: Passed to `IntersectionObserver.threshold` — typical values are 0.1–0.6 for entrances.
             - `inset`: Applied as vertical `rootMargin` (`top/bottom`), e.g., `'-100px'` to trigger earlier/later; left/right remain 0.
             - Note: For `viewProgress`, `threshold` and `inset` are ignored; progress is driven by ViewTimeline/scroll scenes. Control the range via `ScrubEffect.rangeStart/rangeEnd` and `namedEffect.range`.
@@ -168,10 +170,11 @@ This configuration declares what user/system triggers occur on which source elem
           - Usage: Fire when the specified effect (by `effectId`) on the source element finishes, useful for chaining sequences.
         - pointerMove: `PointerMoveParams`
           - `hitArea?`: `'root' | 'self'` (default `'self'`)
+          - `axis?`: `'x' | 'y'` - when using `keyframeEffect` with `pointerMove`, selects which pointer coordinate maps to linear 0-1 progress; defaults to `'y'`. Ignored for `namedEffect` and `customEffect`.
           - Usage:
             - `'self'`: Track pointer within the source element’s bounds.
             - `'root'`: Track pointer anywhere in the viewport (document root).
-            - Only use with `ScrubEffect` mouse presets (`namedEffect`) or `customEffect` that consumes pointer progress; avoid `keyframeEffect` with `pointerMove`.
+            - Only use with `ScrubEffect` mouse presets (`namedEffect`) or `customEffect` that consumes pointer progress; avoid `keyframeEffect` with `pointerMove` unless mapping a single axis via `axis`.
           - When using `customEffect` with `pointerMove`, the progress parameter is an object:
             - ```typescript
               type Progress = {
@@ -343,7 +346,7 @@ The config remains the same for both integrations—only the HTML/JSX setup diff
      - `delay?`: number (ms)
      - One of:
        - `keyframeEffect`: `{ name: string; keyframes: Keyframe[] }`
-       - `namedEffect`: `NamedEffect` (from `@wix/motion`)
+       - `namedEffect`: `NamedEffect` (from `@wix/motion-presets`)
        - `customEffect`: `(element: Element, progress: any) => void`
 
   2. **ScrubEffect** (animation driven by scroll/progress)
@@ -373,12 +376,12 @@ The config remains the same for both integrations—only the HTML/JSX setup diff
          - 'exit-crossing': The moment the target's center crosses the exit boundary.
          - If omitted, the runtime chooses a context-appropriate anchor; specify explicitly for deterministic behavior.
        - offset: A `LengthPercentage` that shifts the anchor boundary.
-         - Explicit format: `{ value: number; type: 'percentage' | 'px' | 'em' | 'rem' | 'vh' | 'vw' | 'vmin' | 'vmax' }`
+         - Explicit format: `{ value: number; unit: 'percentage' | 'px' | 'em' | 'rem' | 'vh' | 'vw' | 'vmin' | 'vmax' }`
          - Percentages are interpreted along the relevant scroll axis relative to the observation area (e.g., viewport or container size).
          - Positive values move the anchor "forward" along the scroll direction; negative values move it "backward".
        - Examples:
-         - Start when the element is 20% inside the viewport: `rangeStart: { name: 'entry', offset: { value: 20, type: 'percentage' } }`
-         - End when the element is leaving: `rangeEnd: { name: 'exit', offset: { value: 0, type: 'percentage' } }`
+         - Start when the element is 20% inside the viewport: `rangeStart: { name: 'entry', offset: { value: 20, unit: 'percentage' } }`
+         - End when the element is leaving: `rangeEnd: { name: 'exit', offset: { value: 0, unit: 'percentage' } }`
 
   3. **TransitionEffect** (CSS transition-style state toggles)
      - `key?`: string (target override; see TARGET CASCADE)
@@ -391,15 +394,10 @@ The config remains the same for both integrations—only the HTML/JSX setup diff
 
 ### Authoring rules for animation payloads (`namedEffect`, `keyframeEffect`, `customEffect`):
 
-- **namedEffect (Preferred)**: Use first for best performance. These are pre-built presets from `@wix/motion` that are GPU-friendly and tuned.
-  - Structure: `namedEffect: { type: '<PresetName>', /* optional preset options like direction (bottom|top|left|right), power ('soft'|'medium'|'hard'), etc. do not use those without having proper documentation of which options exist and of what types. */ }`
-  - Short list of common preset names:
-    - Entrance: `FadeIn`, `BounceIn`, `SlideIn`, `FlipIn`, `ArcIn`
-    - Ongoing: `Pulse`, `Spin`, `Wiggle`, `Bounce`
-    - Scroll: `ParallaxScroll`, `FadeScroll`, `RevealScroll`, `TiltScroll`
-    - For scroll-effects used with the `viewProgress` trigger, the `namedEffect` options MUST include `range: 'in' | 'out' | 'continuous'`. Prefer `range: 'continuous'` for simplicity.
-    - Mouse: For `pointerMove` (mouse-effects), prefer `namedEffect` presets (e.g., `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse`); avoid `keyframeEffect` with `pointerMove` since progress is two‑dimensional.
-    - Mouse: `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse`
+- **namedEffect (Preferred)**: Use first for best performance. These are pre-built presets from `@wix/motion-presets` that are GPU-friendly and tuned.
+  - Structure: `namedEffect: { type: '<PresetName>', /* optional preset options like direction (bottom|top|left|right), etc. do not use those without having proper documentation of which options exist and of what types. */ }`
+  - Short list of common preset names: - Entrance: `FadeIn`, `BounceIn`, `SlideIn`, `F
+lipIn`, `ArcIn` - Ongoing: `Pulse`, `Spin`, `Wiggle`, `Bounce` - Scroll: `ParallaxScroll`, `FadeScroll`, `RevealScroll`, `TiltScroll` - For scroll-effects used with the `viewProgress` trigger, the `namedEffect` options MUST include `range: 'in' | 'out' | 'continuous'`. Prefer `range: 'continuous'` for simplicity. - Mouse: For `pointerMove` (mouse-effects), prefer `namedEffect` presets (e.g., `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse`); avoid `keyframeEffect` with `pointerMove` since progress is two‑dimensional. - Mouse: `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse`
 - **keyframeEffect (Default for custom animations)**: Prefer this when you need a custom-made animation.
   - Structure: `keyframeEffect: { name: string; keyframes: Keyframe[] }` (keyframes use standard CSS/WAAPI properties).
   - Not compatible with `pointerMove` (mouse-effects) because pointer progress is two‑dimensional; use `customEffect` for custom pointer‑driven animations.

package/rules/hover.md

@@ -95,7 +95,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
 
 ## Rule 2: Hover Enter/Leave Animations with Named Effects
 
-**Purpose**: Generate hover interactions using pre-built named effects from @wix/motion
+**Purpose**: Generate hover interactions using pre-built named effects from @wix/motion-presets
 
 **Pattern**:
 
@@ -125,7 +125,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
 **Variables**:
 
 - `[REVERSED_BOOL]`: Optional boolean value indicating whether the mouse enter animation is reversed (and mouse leave is forwards).
-- `[NAMED_EFFECT_TYPE]`: Name of the pre-built named effect from @wix/motion to use.
+- `[NAMED_EFFECT_TYPE]`: Name of the pre-built named effect from @wix/motion-presets to use.
 - `[EFFECT_PROPERTIES]`: Named effect specific properties (distance, angle, perspective, etc.)
 - Other variables same as Rule 1
 
@@ -159,8 +159,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
         {
             key: 'feature-card',
             namedEffect: {
-                type: 'Pulse',
-                power: 'soft'
+                type: 'Pulse'
             },
             fill: 'both',
             duration: 250,
@@ -181,8 +180,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
             key: 'button-icon',
             namedEffect: {
                 type: 'SpinIn',
-                direction: 'clockwise',
-                power: 'soft'
+                direction: 'clockwise'
             },
             fill: 'both',
             duration: 200,

package/rules/integration.md

@@ -169,20 +169,22 @@ const html = `
 
 **When to Use:**
 
-- For elements with an entrance efffect that is triggered a with `viewEnter`
+- For elements with an entrance effect that is triggered with `viewEnter`
 - To prevent elements from being visible before their entrance animation plays
 - For server-side rendering (SSR) or static site generation (SSG) scenarios
 
 ## 5. Triggers & Behaviors
 
-| 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                                                                                     | --                  |
+| 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`        |
+| `activate`     | Accessible click (click + keyboard Space/Enter) | Same as `click` with keyboard support                                                                                     | `./click.md`        |
+| `interest`     | Accessible hover (hover + focus)                | Same as `hover` with focus support                                                                                        | `./hover.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'; `axis`: 'x' or 'y' for keyframeEffect                                              | `./pointermove.md`  |
+| `animationEnd` | Chaining animations                             | `effectId`: ID of the previous effect                                                                                     | --                  |
 
 ## 6. Effects & Animations
 
@@ -190,9 +192,33 @@ Effects define _what_ happens. They can be inline or referenced by ID.
 
 ### Effect Types
 
-#### 1. Named Effects (Pre-built)
+#### 1. Named Effects (Pre-built effect library)>
 
-Use Motion effect presets for consistency.
+Use the @wix/motion-presets library for consistency.
+
+**Install:**
+
+```bash
+> npm install @wix/motion-presets
+```
+
+**Import and register:**
+
+```typescript
+import { Interact } from '@wix/interact/web';
+import * as presets from '@wix/motion-presets';
+
+Interact.registerEffects(presets);
+```
+
+**Or register only required presets:**
+
+```typescript
+import { Interact } from '@wix/interact/web';
+import { FadeIn, ParallaxScroll } from '@wix/motion-presets';
+
+Interact.registerEffects({ FadeIn, ParallaxScroll });
+```
 
 ```typescript
 {
@@ -239,8 +265,8 @@ Used with `viewProgress`, linked to scroll progress while element is inside view
 ```typescript
 {
   keyframeEffect: { ... },
-  rangeStart: { name: 'cover', offset: { value: 0, type: 'percentage' } },
-  rangeEnd: { name: 'cover', offset: { value: 100, type: 'percentage' } },
+  rangeStart: { name: 'cover', offset: { value: 0, unit: 'percentage' } },
+  rangeEnd: { name: 'cover', offset: { value: 100, unit: 'percentage' } },
   fill: 'both'
 }
 ```