Rules rewrite WIP

packages/interact/rules/click.md

@@ -17,14 +17,14 @@ These rules help generate click-based interactions using the `@wix/interact` lib
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'click',
     params: {
         type: 'alternate'
     },
     effects: [
         {
-            key: '[TARGET_IDENTIFIER]',
+            key: '[TARGET_KEY]',
             [EFFECT_TYPE]: [EFFECT_DEFINITION],
             fill: 'both',
             reversed: [INITIAL_REVERSED_BOOL],
@@ -38,8 +38,8 @@ These rules help generate click-based interactions using the `@wix/interact` lib
 
 **Variables**:
 
-- `[SOURCE_IDENTIFIER]`: Unique identifier for clickable element (e.g., 'menu-button', 'accordion-header'). Should equal the value of the data-interact-key attribute on the wrapping interact-element.
-- `[TARGET_IDENTIFIER]`: Unique identifier for animated element (can be same as trigger or different). Should equal the value of the data-interact-key attribute on the wrapping interact-element.
+- `[SOURCE_KEY]`: Unique identifier for clickable element. Should equal the value of the `data-interact-key` attribute on the wrapping `<interact-element>`.
+- `[TARGET_KEY]`: Unique identifier for animated element (can be same as `[SOURCE_KEY]` for self-targeting, or different for cross-targeting).
 - `[EFFECT_TYPE]`: Either `namedEffect` or `keyframeEffect`
 - `[EFFECT_DEFINITION]`: Named effect object (e.g., { type: 'SlideIn', ...params }, { type: 'FadeIn', ...params }) or keyframe object (e.g., { name: 'custom-fade', keyframes: [{ opacity: 0 }, { opacity: 1 }] }, { name: 'custom-slide', keyframes: [{ transform: 'translateX(-100%)' }, { transform: 'translateX(0)' }] })
 - `[INITIAL_REVERSED_BOOL]`: Optional boolean value indicating whether the first toggle should play the reversed animation.
@@ -118,14 +118,14 @@ These rules help generate click-based interactions using the `@wix/interact` lib
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'click',
     params: {
         type: 'state'
     },
     effects: [
         {
-            key: '[TARGET_IDENTIFIER]',
+            key: '[TARGET_KEY]',
             [EFFECT_TYPE]: [EFFECT_DEFINITION],
             fill: 'both',
             reversed: [INITIAL_REVERSED_BOOL],
@@ -212,14 +212,14 @@ These rules help generate click-based interactions using the `@wix/interact` lib
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'click',
     params: {
         type: 'repeat'
     },
     effects: [
         {
-            key: '[TARGET_IDENTIFIER]',
+            key: '[TARGET_KEY]',
             [EFFECT_TYPE]: [EFFECT_DEFINITION],
             duration: [DURATION_MS],
             easing: '[EASING_FUNCTION]',
@@ -304,14 +304,14 @@ These rules help generate click-based interactions using the `@wix/interact` lib
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'click',
     params: {
-        method: 'toggle'
+        method: 'toggle'  // also: 'add', 'remove', 'clear' — see full-lean.md StateParams
     },
     effects: [
         {
-            key: '[TARGET_IDENTIFIER]',
+            key: '[TARGET_KEY]',
             transition: {
                 duration: [DURATION_MS],
                 delay: [DELAY_MS],
@@ -501,27 +501,12 @@ Using effectId for sequential animations:
 
 ## Best Practices for Click Interactions
 
-### Performance Guidelines
+### Timing and Pattern Guidelines
 
 1. **Keep click animations short** (100-500ms) for immediate feedback
-2. **Use `transform` and `opacity`** for smooth animations
-3. **Avoid animating layout properties** like width/height in clicks
-4. **Consider using `will-change`** for complex click animations
-
-### User Experience Guidelines
-
-1. **Provide immediate visual feedback** (within 100ms)
 2. **Use alternate pattern** for toggle states
 3. **Use repeat pattern** for confirmation actions
 4. **Use state pattern** for media controls
-5. **Ensure click targets are accessible** (minimum 44px touch target)
-
-### Accessibility Considerations
-
-1. **Respect `prefers-reduced-motion`** setting
-2. **Provide alternative interaction methods** (keyboard support)
-3. **Ensure sufficient color contrast** during transitions
-4. **Don't rely solely on animation** to convey state changes
 
 ### Common Use Cases by Pattern
 
@@ -555,7 +540,3 @@ Using effectId for sequential animations:
 - Color changes
 - Simple state toggles
 - CSS custom property updates
-
----
-
-These rules provide comprehensive coverage for click trigger interactions in `@wix/interact`, supporting the four main behavior patterns and two primary effect types as outlined in the development plan.

packages/interact/rules/full-lean.md

@@ -30,6 +30,25 @@ const config: InteractConfig = {
 Interact.create(config);
 ```
 
+### Using `namedEffect` presets (`registerEffects`)
+
+Before using `namedEffect`, you must register the presets with the `Interact` instance. Without this, `namedEffect` types will not resolve.
+
+```ts
+import { Interact } from '@wix/interact/web'; // or /react
+import * as presets from '@wix/motion-presets';
+
+Interact.registerEffects(presets);
+Interact.create(config);
+```
+
+Or register only what you need:
+
+```ts
+import { FadeIn, ParallaxScroll } from '@wix/motion-presets';
+Interact.registerEffects({ FadeIn, ParallaxScroll });
+```
+
 - Without Node/build tools: add a `<script type="module">` and import from the CDN.
 
 ```html
@@ -363,7 +382,7 @@ The config remains the same for both integrations—only the HTML/JSX setup diff
      - `transitionDelay?`: number
      - `transitionEasing?`: `ScrubTransitionEasing`
      - One of `keyframeEffect | namedEffect | customEffect` (see above)
-     - For mouse-effects driven by the `pointerMove` trigger, do NOT use `keyframeEffect` (pointer progress is two‑dimensional and cannot be mapped to linear keyframes). Use `namedEffect` mouse presets instead, or `customEffect` for custom‑made animations.
+     - For mouse-effects driven by the `pointerMove` trigger, avoid `keyframeEffect` unless using `params: { axis: 'x' | 'y' }` to map a single pointer axis to linear 0–1 progress. For 2D effects, use `namedEffect` mouse presets or `customEffect` instead.
      - For scroll `namedEffect` presets (e.g., `*Scroll`) used with a `viewProgress` trigger, include `range: 'in' | 'out' | 'continuous'` in the `namedEffect` options; prefer `'continuous'` for simplicity.
      - RangeOffset (used by `rangeStart`/`rangeEnd`):
        - Type: `{ name: 'entry' | 'exit' | 'contain' | 'cover' | 'entry-crossing' | 'exit-crossing'; offset: LengthPercentage }`
@@ -396,11 +415,14 @@ The config remains the same for both integrations—only the HTML/JSX setup diff
 
 - **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`
+  - Short list of common preset names:
+    - Entrance: `FadeIn`, `BounceIn`, `SlideIn`, `FlipIn`, `ArcIn`
+    - Ongoing: `Pulse`, `Spin`, `Wiggle`, `Bounce`
+    - Scroll: `ParallaxScroll`, `FadeScroll`, `RevealScroll`, `TiltScroll` — for `viewProgress`, `namedEffect` options MUST include `range: 'in' | 'out' | 'continuous'`; prefer `'continuous'`
+    - Mouse: `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse` — for `pointerMove`; prefer over `keyframeEffect` for 2D pointer effects
 - **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.
+  - When used with `pointerMove`, requires `params: { axis: 'x' | 'y' }` to select which pointer coordinate maps to linear progress. Without `axis`, pointer progress is two-dimensional and cannot drive keyframe animations. For 2D pointer effects, use `namedEffect` or `customEffect`.
 - **customEffect (Last resort)**: Use only when you must perform DOM manipulation or produce randomized/non-deterministic visuals that cannot be expressed as keyframes or presets.
   - Structure: `customEffect: (element: Element, progress: any) => void`