npm - @wix/interact - Versions diffs - 1.92.0 → 2.0.0-rc.2 - Mend

@wix/interact 1.92.0 → 2.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (179) hide show

package/dist/cjs/index.js +2 -23
package/dist/cjs/index.js.map +1 -1
package/dist/cjs/react.js +15 -0
package/dist/cjs/react.js.map +1 -0
package/dist/cjs/web.js +2 -0
package/dist/cjs/web.js.map +1 -0
package/dist/es/index.js +8 -0
package/dist/es/index.js.map +1 -0
package/dist/es/react.js +650 -0
package/dist/es/react.js.map +1 -0
package/dist/es/web.js +56 -0
package/dist/es/web.js.map +1 -0
package/dist/index-C8QxOkui.mjs +7940 -0
package/dist/index-C8QxOkui.mjs.map +1 -0
package/dist/index-DEPRHaUt.js +18 -0
package/dist/index-DEPRHaUt.js.map +1 -0
package/dist/tsconfig.build.tsbuildinfo +1 -0
package/dist/types/core/Interact.d.ts +17 -7
package/dist/types/core/Interact.d.ts.map +1 -0
package/dist/types/core/InteractionController.d.ts +19 -0
package/dist/types/core/InteractionController.d.ts.map +1 -0
package/dist/types/core/add.d.ts +4 -3
package/dist/types/core/add.d.ts.map +1 -0
package/dist/types/core/css.d.ts +3 -0
package/dist/types/core/css.d.ts.map +1 -0
package/dist/types/core/remove.d.ts +3 -1
package/dist/types/core/remove.d.ts.map +1 -0
package/dist/types/core/utilities.d.ts +1 -0
package/dist/types/core/utilities.d.ts.map +1 -0
package/dist/types/dom/api.d.ts +3 -0
package/dist/types/dom/api.d.ts.map +1 -0
package/dist/types/handlers/animationEnd.d.ts +3 -2
package/dist/types/handlers/animationEnd.d.ts.map +1 -0
package/dist/types/handlers/click.d.ts +3 -2
package/dist/types/handlers/click.d.ts.map +1 -0
package/dist/types/handlers/hover.d.ts +3 -2
package/dist/types/handlers/hover.d.ts.map +1 -0
package/dist/types/handlers/index.d.ts +1 -0
package/dist/types/handlers/index.d.ts.map +1 -0
package/dist/types/handlers/pointerMove.d.ts +3 -2
package/dist/types/handlers/pointerMove.d.ts.map +1 -0
package/dist/types/handlers/utilities.d.ts +1 -0
package/dist/types/handlers/utilities.d.ts.map +1 -0
package/dist/types/handlers/viewEnter.d.ts +3 -2
package/dist/types/handlers/viewEnter.d.ts.map +1 -0
package/dist/types/handlers/viewProgress.d.ts +4 -3
package/dist/types/handlers/viewProgress.d.ts.map +1 -0
package/dist/types/index.d.ts +3 -2
package/dist/types/index.d.ts.map +1 -0
package/dist/types/react/Interaction.d.ts +10 -0
package/dist/types/react/Interaction.d.ts.map +1 -0
package/dist/types/react/index.d.ts +8 -0
package/dist/types/react/index.d.ts.map +1 -0
package/dist/types/react/interactRef.d.ts +3 -0
package/dist/types/react/interactRef.d.ts.map +1 -0
package/dist/types/types.d.ts +25 -10
package/dist/types/types.d.ts.map +1 -0
package/dist/types/utils.d.ts +4 -2
package/dist/types/utils.d.ts.map +1 -0
package/dist/types/{InteractElement.d.ts → web/InteractElement.d.ts} +115 -77
package/dist/types/web/InteractElement.d.ts.map +1 -0
package/dist/types/web/defineInteractElement.d.ts +2 -0
package/dist/types/web/defineInteractElement.d.ts.map +1 -0
package/dist/types/web/index.d.ts +6 -0
package/dist/types/web/index.d.ts.map +1 -0
package/docs/README.md +211 -0
package/docs/advanced/README.md +164 -0
package/docs/api/README.md +157 -0
package/docs/api/element-selection.md +607 -0
package/docs/api/functions.md +638 -0
package/docs/api/interact-class.md +663 -0
package/docs/api/interact-element.md +565 -0
package/docs/api/interaction-controller.md +450 -0
package/docs/api/types.md +957 -0
package/docs/examples/README.md +212 -0
package/docs/examples/click-interactions.md +977 -0
package/docs/examples/entrance-animations.md +935 -0
package/docs/examples/hover-effects.md +930 -0
package/docs/examples/list-patterns.md +737 -0
package/docs/guides/README.md +49 -0
package/docs/guides/conditions-and-media-queries.md +1068 -0
package/docs/guides/configuration-structure.md +726 -0
package/docs/guides/custom-elements.md +327 -0
package/docs/guides/effects-and-animations.md +634 -0
package/docs/guides/getting-started.md +379 -0
package/docs/guides/lists-and-dynamic-content.md +713 -0
package/docs/guides/state-management.md +747 -0
package/docs/guides/understanding-triggers.md +690 -0
package/docs/integration/README.md +264 -0
package/docs/integration/react.md +605 -0
package/package.json +73 -56
package/rules/Integration.md +255 -0
package/rules/click-rules.md +533 -0
package/rules/full-lean.md +346 -0
package/rules/hover-rules.md +593 -0
package/rules/pointermove-rules.md +1341 -0
package/rules/scroll-list-rules.md +900 -0
package/rules/viewenter-rules.md +1015 -0
package/rules/viewprogress-rules.md +1044 -0
package/dist/cjs/InteractElement.js +0 -162
package/dist/cjs/InteractElement.js.map +0 -1
package/dist/cjs/__tests__/interact.spec.js +0 -1930
package/dist/cjs/__tests__/interact.spec.js.map +0 -1
package/dist/cjs/__tests__/viewEnter.spec.js +0 -207
package/dist/cjs/__tests__/viewEnter.spec.js.map +0 -1
package/dist/cjs/core/Interact.js +0 -257
package/dist/cjs/core/Interact.js.map +0 -1
package/dist/cjs/core/add.js +0 -246
package/dist/cjs/core/add.js.map +0 -1
package/dist/cjs/core/remove.js +0 -35
package/dist/cjs/core/remove.js.map +0 -1
package/dist/cjs/core/utilities.js +0 -16
package/dist/cjs/core/utilities.js.map +0 -1
package/dist/cjs/external-types.d.js +0 -2
package/dist/cjs/external-types.d.js.map +0 -1
package/dist/cjs/handlers/animationEnd.js +0 -33
package/dist/cjs/handlers/animationEnd.js.map +0 -1
package/dist/cjs/handlers/click.js +0 -116
package/dist/cjs/handlers/click.js.map +0 -1
package/dist/cjs/handlers/hover.js +0 -141
package/dist/cjs/handlers/hover.js.map +0 -1
package/dist/cjs/handlers/index.js +0 -32
package/dist/cjs/handlers/index.js.map +0 -1
package/dist/cjs/handlers/pointerMove.js +0 -49
package/dist/cjs/handlers/pointerMove.js.map +0 -1
package/dist/cjs/handlers/utilities.js +0 -49
package/dist/cjs/handlers/utilities.js.map +0 -1
package/dist/cjs/handlers/viewEnter.js +0 -127
package/dist/cjs/handlers/viewEnter.js.map +0 -1
package/dist/cjs/handlers/viewProgress.js +0 -65
package/dist/cjs/handlers/viewProgress.js.map +0 -1
package/dist/cjs/test-types.d.js +0 -2
package/dist/cjs/test-types.d.js.map +0 -1
package/dist/cjs/types.js +0 -2
package/dist/cjs/types.js.map +0 -1
package/dist/cjs/utils.js +0 -68
package/dist/cjs/utils.js.map +0 -1
package/dist/esm/InteractElement.js +0 -156
package/dist/esm/InteractElement.js.map +0 -1
package/dist/esm/__tests__/interact.spec.js +0 -1937
package/dist/esm/__tests__/interact.spec.js.map +0 -1
package/dist/esm/__tests__/viewEnter.spec.js +0 -210
package/dist/esm/__tests__/viewEnter.spec.js.map +0 -1
package/dist/esm/core/Interact.js +0 -251
package/dist/esm/core/Interact.js.map +0 -1
package/dist/esm/core/add.js +0 -241
package/dist/esm/core/add.js.map +0 -1
package/dist/esm/core/remove.js +0 -30
package/dist/esm/core/remove.js.map +0 -1
package/dist/esm/core/utilities.js +0 -14
package/dist/esm/core/utilities.js.map +0 -1
package/dist/esm/external-types.d.js +0 -2
package/dist/esm/external-types.d.js.map +0 -1
package/dist/esm/handlers/animationEnd.js +0 -29
package/dist/esm/handlers/animationEnd.js.map +0 -1
package/dist/esm/handlers/click.js +0 -116
package/dist/esm/handlers/click.js.map +0 -1
package/dist/esm/handlers/hover.js +0 -141
package/dist/esm/handlers/hover.js.map +0 -1
package/dist/esm/handlers/index.js +0 -27
package/dist/esm/handlers/index.js.map +0 -1
package/dist/esm/handlers/pointerMove.js +0 -48
package/dist/esm/handlers/pointerMove.js.map +0 -1
package/dist/esm/handlers/utilities.js +0 -43
package/dist/esm/handlers/utilities.js.map +0 -1
package/dist/esm/handlers/viewEnter.js +0 -129
package/dist/esm/handlers/viewEnter.js.map +0 -1
package/dist/esm/handlers/viewProgress.js +0 -61
package/dist/esm/handlers/viewProgress.js.map +0 -1
package/dist/esm/index.js +0 -5
package/dist/esm/index.js.map +0 -1
package/dist/esm/test-types.d.js +0 -2
package/dist/esm/test-types.d.js.map +0 -1
package/dist/esm/types.js +0 -2
package/dist/esm/types.js.map +0 -1
package/dist/esm/utils.js +0 -63
package/dist/esm/utils.js.map +0 -1
package/dist/types/__tests__/interact.spec.d.ts +0 -1
package/dist/types/__tests__/viewEnter.spec.d.ts +0 -0

package/rules/full-lean.md ADDED Viewed

@@ -0,0 +1,346 @@
+### Basic usage (quick start)
+- Import the runtime and create it with a config defining the interactions.
+- 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.
+```ts
+import { Interact } from '@wix/interact';
+import type { InteractConfig } from '@wix/interact';
+const config: InteractConfig = {
+  // config-props
+};
+Interact.create(config);
+```
+- Without Node/build tools: add a `<script type="module">` and import from the CDN.
+```html
+<script type="module">
+  import { Interact } from 'https://esm.sh/@wix/interact@1.86.0';
+  const config = {
+    // config-props
+  };
+  Interact.create(config);
+</script>
+```
+### Preventing FOUC for entrance animations
+- 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.
+- Do NOT use for `hover` or `click` interactions.
+**Usage:**
+```javascript
+import { generate } from '@wix/interact';
+const config = {/*...*/};
+// Generate CSS at build time or on server
+const css = generate(config);
+// Include in your HTML template
+const html = `
+<!DOCTYPE html>
+<html>
+<head>
+    <style>${css}</style>
+</head>
+<body>
+    <interact-element data-interact-key="hero" data-interact-initial="true">
+        <section class="hero">
+            <h1>Welcome to Our Site</h1>
+            <p>This content fades in smoothly without flash</p>
+        </section>
+    </interact-element>
+    <script type="module" src="./main.js"></script>
+</body>
+</html>
+`;
+```
+### General guidelines (avoiding common pitfalls)
+- Missing required fields or invalid references SHOULD be treated as no-ops for the offending interaction/effect while leaving the rest of the config functional.
+- Params with incorrect types or shapes (especially for `namedEffect` preset options) can produce console errors. If you do not know the expected type/structure for a param, omit it and rely on defaults rather than guessing.
+- Using `overflow: hidden` or `overflow: auto` can break viewProgress animations. Prefer `overflow: clip` for clipping semantics while preserving normal ViewTimeline.
+- When animating with perspective, prefer `transform: perspective(...)` inside keyframes/presets. Reserve the static CSS `perspective` property for the specific case where multiple children of the same container must share the same viewpoint (`perspective-origin`).
+- Stacking contexts and `viewProgress` (ViewTimeline): Creating a new stacking context on the target or any of its ancestors can prevent or freeze ViewTimeline sampling in some engines and setups. Avoid stacking‑context‑creating styles on the observed subtree (target and ancestors), including `transform`, `filter`, `perspective`, `opacity < 1`, `mix-blend-mode`, `isolation: isolate`, aggressive `will-change`, and `contain: paint/layout/size`. If needed for visuals, wrap the content and apply these styles to an inner child so the element that owns the timeline remains “flat”. Also avoid turning the scroll container into a stacking context; if you need clipping, prefer `overflow: clip` and avoid `transform` on the container. Typical symptoms are `viewProgress` not running, jumping 0→1, or never reaching anchors—remove or relocate the offending styles.
+### InteractConfig – Rules for authoring interactions (AI-agent oriented)
+This configuration declares what user/system triggers occur on which source element(s), and which visual effects should be applied to which target element(s). It is composed of three top-level sections: `effects`, `conditions`, and `interactions`.
+### Global rules
+- **Required/Optional**: You MUST provide an `interactions` array. You SHOULD provide an `effects` registry when you want to reference reusable effects by id. `conditions` are OPTIONAL.
+- **Cross-references**: All cross-references (by id) MUST point to existing entries (e.g., an `EffectRef.effectId` MUST exist in `effects`).
+- **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.
+### Structure
+- **effects: Record<string, Effect>**
+  - **Purpose**: A registry of reusable, named effect definitions that can be referenced from interactions via `EffectRef`.
+  - **Key (string)**: The effect id. MUST be unique across the registry.
+  - **Value (Effect)**: A full effect definition. See Effect rules below.
+- **conditions?: Record<string, Condition>**
+  - **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'`
+      - `'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.
+    - **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[]**
+  - **Purpose**: Declarative mapping from a source element and trigger to one or more target effects.
+  - Each `Interaction` contains:
+    - **key: string**
+      - REQUIRED. The source element path. The trigger attaches to this element.
+    - **listContainer?: string**
+      - OPTIONAL. A CSS selector for a list container context. When present, the trigger is scoped to items within this list.
+    - **listItemSelector?: string**
+      - OPTIONAL. A CSS selector used to select items within `listContainer`.
+    - **trigger: TriggerType**
+      - REQUIRED. One of:
+        - `'hover' | 'click'`: Pointer interactions.
+        - `'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`
+          - `StateParams.method`: `'add' | 'remove' | 'toggle' | 'clear'`
+          - `PointerTriggerParams.type?`: `'once' | 'repeat' | 'alternate' | 'state'`
+          - Usage:
+            - When the effect is a `TransitionEffect`, use `StateParams.method` to control the state toggle invoked on interaction:
+              - `'toggle'` (default): Hover — adds on enter and removes on leave. Click — toggles on each click.
+              - `'add'`: Apply the state on the event; hover leave will NOT auto‑remove.
+              - `'remove'`: Remove the state on the event.
+              - `'clear'`: Clear/reset the effect’s state for the element (or list item when list context is used).
+              - With lists (`listContainer`/`listItemSelector`), the state is set on the matching item only.
+            - When the effect is a time animation (`namedEffect`/`keyframeEffect`), use `PointerTriggerParams.type`:
+              - `'alternate'` (default): Hover — play on enter, reverse on leave. Click — alternate play/reverse on successive clicks.
+              - `'repeat'`: Restart from progress 0 on each event; on hover leave the animation is canceled.
+              - `'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'`
+          - `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.
+            - `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`.
+        - animationEnd: `AnimationEndParams`
+          - `effectId`: string of the effect to wait for completion
+          - Usage: Fire when the specified effect (by `effectId`) on the source element finishes, useful for chaining sequences.
+        - pointerMove: `PointerMoveParams`
+          - `hitArea?`: `'root' | 'self'` (default `'self'`)
+          - 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`.
+          - When using `customEffect` with `pointerMove`, the progress parameter is an object:
+            - ```typescript
+              type Progress = {
+                x: number;      // 0-1: horizontal position (0 = left edge, 1 = right edge)
+                y: number;      // 0-1: vertical position (0 = top edge, 1 = bottom edge)
+                v?: {           // Velocity (optional)
+                  x: number;    // Horizontal velocity
+                  y: number;    // Vertical velocity
+                };
+                active?: boolean; // Whether mouse is currently in the hit area
+              };
+              ```
+    - **conditions?: string[]**
+      - OPTIONAL. Array of condition ids that MUST all pass for this trigger to be active.
+    - **selector?: string**
+      - OPTIONAL. Additional CSS selector to refine the source element's descendants when attaching/observing the trigger (e.g., delegate a click to a child button).
+    - **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.
+```html
+<interact-element data-interact-key="my-button">
+  <button id="my-button">Click me</button>
+</interact-element>
+```
+```ts
+import type { InteractConfig } from '@wix/interact';
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'my-button', // matches data-interact-key
+      trigger: 'hover',
+      effects: [
+        {
+          // key omitted -> targets the source element ('my-button')
+          // effect props go here (e.g., transition | keyframeEffect | namedEffect | customEffect)
+        },
+      ],
+    },
+  ],
+};
+```
+For a different target element:
+```html
+<interact-element data-interact-key="my-button">
+  <button id="my-button">Click me</button>
+</interact-element>
+<interact-element data-interact-key="my-badge">
+  <span id="my-badge">Badge</span>
+</interact-element>
+```
+```ts
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'my-button',
+      trigger: 'click',
+      effects: [
+        {
+          key: 'my-badge', // target is different than source
+          // effect props (e.g., transition | keyframeEffect | namedEffect)
+        },
+      ],
+    },
+  ],
+};
+```
+### Effect rules (applies to both registry-defined Effect and inline Effect within interactions)
+- Common fields (`EffectBase`):
+  - **key?: string**
+    - OPTIONAL. Target element path. If omitted, resolution follows TARGET CASCADE:
+      1) `Effect.key` (if provided)
+      2) If Effect is an `EffectRef`: lookup registry by `effectId` and use that registry Effect’s `key`
+      3) Fallback to the `Interaction.key` (i.e., source acts as target)
+  - **listContainer?: string, listItemSelector?: string**
+    - OPTIONAL. If provided, MUST match the interaction's list context when both exist.
+  - **conditions?: string[]**
+    - OPTIONAL. All conditions MUST pass for the effect to run (in addition to interaction conditions).
+  - **selector?: string**
+    - OPTIONAL. Additional CSS selector to refine the target element's descendants.
+  - **effectId?: string**
+    - For `EffectRef` this field is REQUIRED and MUST reference an entry in `effects`.
+- Composition and fill usage
+  - **composite** (similar to CSS `animation-composition` / WAAPI `composite`):
+    - Controls how this effect combines with other effects targeting the same element/property.
+    - `'replace'` (default): this effect fully replaces prior values for overlapping properties.
+    - `'add'`: this effect adds to the underlying value where the property supports additive composition (e.g., transforms, filters, opacity).
+    - `'accumulate'`: values build up across iterations/repeats where supported.
+    - Note: If a property is not additive, the runtime will treat `'add'`/`'accumulate'` like `'replace'`.
+  - **fill** (like CSS `animation-fill-mode`):
+    - `'none'`: styles are only applied while the effect is actively running/in-range.
+    - `'forwards'`: the effect’s end state is retained after completion (or last sampled value for scrub).
+    - `'backwards'`: the start state applies before the effect begins (or before `rangeStart` for scrub/during `delay` for time effects).
+    - `'both'`: combines `'backwards'` and `'forwards'`.
+    - For scroll-driven animations (`viewProgress`), prefer `fill: 'both'` to preserve start/end states around the active range and avoid flicker on rapid scroll.
+- Types of `Effect` (exactly one MUST be provided via discriminated fields):
+  1) **TimeEffect** (discrete animation over time)
+     - `duration`: number (REQUIRED)
+     - `easing?`: string (CSS/WAAPI easing)
+     - `iterations?`: number (>=1 or Infinity)
+     - `alternate?`: boolean (direction alternation)
+     - `fill?`: `'none' | 'forwards' | 'backwards' | 'both'`
+     - `composite?`: `'replace' | 'add' | 'accumulate'`
+     - `reversed?`: boolean
+     - `delay?`: number (ms)
+     - One of:
+       - `keyframeEffect`: `{ name: string; keyframes: Keyframe[] }`
+       - `namedEffect`: `NamedEffect` (from `@wix/motion`)
+       - `customEffect`: `(element: Element, progress: any) => void`
+  2) **ScrubEffect** (animation driven by scroll/progress)
+     - `easing?`: string
+     - `iterations?`: number (NOT Infinity)
+     - `alternate?`: boolean
+     - `fill?`: `'none' | 'forwards' | 'backwards' | 'both'`
+     - `composite?`: `'replace' | 'add' | 'accumulate'`
+     - `reversed?`: boolean
+     - `rangeStart`: `RangeOffset`
+     - `rangeEnd`: `RangeOffset`
+     - `centeredToTarget?`: boolean // If `true` centers the coordinate range at the target element, otherwise uses source element
+     - `transitionDuration?`: number (ms for smoothing on progress jumps)
+     - `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 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 }`
+       - name?: Optional logical anchor derived from ViewTimeline concepts.
+         - 'entry': Leading edge of the target crosses into the view/container.
+         - 'exit': Trailing edge of the target crosses out of the view/container.
+         - 'contain': Interval where the target is fully within the view/container.
+         - 'cover': Interval where the view/container is fully covered by the target.
+         - 'entry-crossing': The moment the target's center crosses the entry boundary.
+         - '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' }`
+         - 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' } }`
+  3) **TransitionEffect** (CSS transition-style state toggles)
+     - `key?`: string (target override; see TARGET CASCADE)
+     - `effectId?`: string (when used as a reference identity)
+     - One of:
+       - `transition?`: `{ duration?: number; delay?: number; easing?: string; styleProperties: { name: string; value: string }[] }`
+         - Applies a single transition options block to all listed style properties.
+       - `transitionProperties?`: `Array<{ name: string; value: string; duration?: number; delay?: number; easing?: string }>`
+         - Allows per-property transition options. If both `transition` and `transitionProperties` are provided, the system SHOULD apply both with per-property entries taking precedence for overlapping properties.
+### 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`
+  - **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.
+  - **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`
+### Target resolution and list context
+- When applying an effect, the system resolves the final target as:
+  `Effect.key -> registry Effect.key (for EffectRef) -> Interaction.key`.
+- If a `listContainer` is present on the interaction, the selector resolution may be widened to include list items (optionally filtered by `listItemSelector`), and then further refined by any provided `selector`.
+### Reduced motion
+- The runtime MAY force reduced motion globally. Authors SHOULD keep effects resilient to reduced motion by avoiding reliance on specific durations or continuous motion.
+- Use `conditions` to provide responsive and accessible behavior:
+  - Define media conditions such as `'(prefers-reduced-motion: reduce)'` and breakpoint queries, and attach them to interactions/effects to disable, simplify, or swap animations when appropriate.
+  - Provide alternative reduced‑motion variants (e.g., shorter durations, fewer transforms, no perpetual motion/parallax/3D), and select them via `conditions` or effect references so that users who prefer reduced motion get a gentler experience.