@wix/interact 1.93.0 → 2.0.0-rc.4

package/package.json

@@ -1,73 +1,90 @@
 {
   "name": "@wix/interact",
-  "version": "1.93.0",
-  "author": {
-    "name": "wow!Team",
-    "email": "wow-dev@wix.com"
-  },
-  "license": "UNLICENSED",
+  "version": "2.0.0-rc.4",
+  "description": "A powerful, declarative interaction library for creating engaging web apps.",
+  "license": "MIT",
   "main": "dist/cjs/index.js",
-  "module": "dist/esm/index.js",
-  "sideEffects": false,
+  "module": "dist/es/index.js",
   "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/es/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./react": {
+      "types": "./dist/types/react/index.d.ts",
+      "import": "./dist/es/react.js",
+      "require": "./dist/cjs/react.js"
+    },
+    "./web": {
+      "types": "./dist/types/web/index.d.ts",
+      "import": "./dist/es/web.js",
+      "require": "./dist/cjs/web.js"
+    }
+  },
   "files": [
-    "dist/cjs",
-    "dist/esm",
-    "dist/types"
+    "dist",
+    "rules",
+    "docs"
   ],
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  },
+  "sideEffects": false,
   "scripts": {
-    "build": "yoshi-library build",
-    "start": "yoshi-library start",
-    "test": "yoshi-library test",
-    "test:coverage": "yoshi-library test --coverage",
-    "playground": "yarn workspace @wix/interact-playground dev",
-    "lint": "yoshi-library lint"
+    "dev": "vite dev --open",
+    "build": "rimraf dist && vite build && npm run build:types",
+    "build:types": "tsc -p tsconfig.build.json",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage"
   },
-  "lint-staged": {
-    "*.{js,ts}": "yarn lint"
+  "keywords": [
+    "animation",
+    "javascript",
+    "css",
+    "waapi"
+  ],
+  "author": {
+    "name": "wow!Team",
+    "email": "wow-dev@wix.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wix-incubator/interact"
+  },
+  "bugs": {
+    "url": "https://github.com/wix-incubator/interact/issues"
   },
   "dependencies": {
-    "@babel/runtime": "^7.26.0",
-    "@wix/motion": "1.656.0",
+    "@wix/motion": "^1.0.0",
     "fastdom": "^1.0.12",
-    "fizban": "^0.7.0",
+    "fizban": "^0.7.2",
     "kuliso": "^0.4.13"
   },
-  "devDependencies": {
-    "@types/jest": "^27.5.2",
-    "@types/node": "^16.18.123",
-    "@wix/eslint-config-yoshi": "^6.163.0",
-    "@wix/jest-yoshi-preset": "^6.163.0",
-    "@wix/yoshi-flow-library": "^6.163.0",
-    "ts-jest": "^29.2.5",
-    "typescript": "~4.9.5"
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   },
-  "jest": {
-    "preset": "@wix/jest-yoshi-preset"
-  },
-  "yoshiFlowLibrary": {
-    "buildEsmWithBabel": true
-  },
-  "eslintConfig": {
-    "extends": "@wix/eslint-config-yoshi"
-  },
-  "wix": {
-    "artifact": {
-      "groupId": "com.wixpress.wow",
-      "artifactId": "interact"
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
     },
-    "validations": {
-      "postDependenciesBuild": [
-        "lint"
-      ]
+    "react-dom": {
+      "optional": true
     }
   },
-  "wallaby": {
-    "autoDetect": true
-  },
-  "falconPackageHash": "6b4071ff75035af06326865108012e422c9f4adbbfed6828d778e157"
-}
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.2",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "@vitest/coverage-v8": "^4.0.14",
+    "jsdom": "^24.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.2",
+    "vitest": "^4.0.14"
+  }
+}

package/rules/Integration.md

@@ -0,0 +1,255 @@
+# @wix/interact Integration Rules
+
+This document outlines the rules and best practices for generating code that integrates `@wix/interact` into a webpage.
+
+## 1. Overview
+
+`@wix/interact` is a library for creating interactive animations and effects triggered by user actions (click, hover, scroll, etc.). It works by binding **Triggers** and **Effects** to specific **Elements**.
+
+## 2. Core Components
+
+### `<interact-element>`
+The custom element wrapper is **required** for any element that triggers an interaction or recieves an effect.
+
+**Rules:**
+- MUST have a `data-interact-key` attribute that is unique within the scope.
+- MUST contain at least one child element.
+- **Usage:**
+  ```html
+  <interact-element data-interact-key="my-button">
+      <button>Click Me</button>
+  </interact-element>
+  ```
+
+### `Interact.create(config)`
+The entry point for initializing interactions.
+
+**Rules:**
+- MUST be called at least once with the full configuration, or per page for single-page apps.
+- **Usage:**
+  ```javascript
+  import { Interact } from '@wix/interact';
+  Interact.create(config);
+  ```
+
+## 3. Configuration Schema
+
+The `InteractConfig` object defines the behavior.
+
+```typescript
+type InteractConfig = {
+  interactions: Interaction[];          // Required: Array of interaction definitions
+  effects?: Record<string, Effect>;     // Optional: Reusable named effects
+  conditions?: Record<string, Condition>; // Optional: Reusable conditions (media queries)
+};
+```
+
+### Interaction Definition
+```typescript
+{
+  key: 'element-key',       // Matches data-interact-key
+  trigger: 'trigger-type',  // e.g., 'hover', 'click'
+  selector?: '.child-cls',  // Optional: Targets specific child inside the interact-element
+  listContainer?: '.list',  // Optional: A selector for the element containing a list, for interactions on lists
+  params?: { ... },         // Trigger-specific parameters
+  conditions?: ['cond-id'], // Array of condition IDs
+  effects: [ ... ]          // Array of effects to apply
+}
+```
+
+### Element Selection Hierarchy
+1. **`listContainer`**: If present, selects a container to target its immediate children as list items.
+2. **`selector`**: Matches elements within the root, or within each list item.
+3. **Fallback**: If neither is provided, targets the **first child** of `<interact-element>`.
+
+## 4. Generating Critical CSS for Entrance Animations
+
+### `generate(config)`
+Generates critical CSS styles that prevent flash-of-unstyled-content (FOUC) for elements with `viewEnter` entrance animations.
+
+**Rules:**
+- MUST be called server-side or at build time to generate static CSS.
+- The generated CSS hides the first child of elements marked with `data-interact-initial="true"` until their entrance animation completes.
+- Only affects users who have not requested reduced motion (`prefers-reduced-motion: no-preference`).
+- The `<interact-element>` MUST have `data-interact-initial="true"` attribute to be affected by the generated CSS.
+
+**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">
+            ...
+        </section>
+    </interact-element>
+    <script type="module" src="./main.js"></script>
+</body>
+</html>
+`;
+```
+
+**When to Use:**
+- For elements that have a `viewEnter` trigger with `type: 'once'`  and an effect on same element
+- To prevent elements from being visible before their entrance animation plays
+- For server-side rendering (SSR) or static site generation (SSG) scenarios
+
+**Important Notes:**
+- The attribute `data-motion-enter="done"` is automatically set by the runtime when the entrance animation completes
+- Users with `prefers-reduced-motion: reduce` will see elements immediately (no hiding)
+- The CSS resets transform properties to prevent any inherited transforms from affecting the hidden state
+
+## 5. Triggers & Behaviors
+
+| Trigger | Description | Key Parameters |
+| :--- | :--- | :--- |
+| `hover` | Mouse enter/leave | `type`: 'once', 'alternate', 'repeat', 'state' for animations, or `method`: 'add', 'remove', 'toggle', 'clear' for states |
+| `click` | Mouse click | `type`: 'once', 'alternate', 'repeat', 'state' for animations, or `method`: 'add', 'remove', 'toggle', 'clear' for states |
+| `viewEnter` | Element enters viewport | `type`: 'once', 'alternate', 'repeat', 'state'; `threshold` (0-1) |
+| `viewProgress` | Scroll progress inside viewport | (No specific params, uses effect ranges) |
+| `pointerMove` | Mouse movement | `hitArea`: 'self' (default) or 'root' |
+| `animationEnd` | Chaining animations | `effectId`: ID of the previous effect |
+
+## 6. Effects & Animations
+
+Effects define *what* happens. They can be inline or referenced by ID.
+
+### Effect Types
+
+#### 1. Named Effects (Pre-built)
+Use Motion effect presets for consistency.
+```typescript
+{
+  namedEffect: { type: 'FadeIn' },
+  duration: 800,
+  easing: 'ease-out'
+}
+```
+
+#### 2. Keyframe Effects (Custom)
+Define explicit Web Animations API-like keyframes.
+```typescript
+{
+  keyframeEffect: {
+    name: 'custom-slide',
+    keyframes: [
+      { transform: 'translateY(20px)', opacity: 0 },
+      { transform: 'translateY(0)', opacity: 1 }
+    ]
+  },
+  duration: 500
+}
+```
+
+#### 3. Transition Effects
+Smoothly transition CSS properties.
+```typescript
+{
+  transition: {
+    duration: 300,
+    styleProperties: [{ name: 'backgroundColor', value: 'red' }]
+  }
+}
+```
+
+#### 4. Scroll Effects
+Used with `viewProgress`, linked to scroll progress while element is inside viewport.
+```typescript
+{
+  keyframeEffect: { ... },
+  rangeStart: { name: 'cover', offset: { value: 0, type: 'percentage' } },
+  rangeEnd: { name: 'cover', offset: { value: 100, type: 'percentage' } }
+}
+```
+
+#### 5. Mouse Effects
+Used with `pointerMove`, linked to mouse progress while moving over an element.
+```typescript
+{
+  namedEffect: { type: 'Track3DMouse' },
+  centeredToTarget: true
+}
+```
+
+### Targeting
+- **Self**: Omit `key` in the effect to target the trigger element. If using `selector` for trigger, also specify it again for the effect target.
+- **Cross-Targeting**: Specify a different `key` and/or `selector` in the effect to animate a different element.
+
+## 7. Examples
+
+### Basic Hover (Scale)
+```typescript
+const config = {
+  effects: {
+    scaleUp: {
+      transitionProperties: [
+        {
+          name: 'transform',
+          value: 'scale(1.1)',
+          duration: 300,
+          delay: 100,
+          easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)'
+        }
+      ]
+    }
+  },
+  interactions: [{
+    key: 'btn',
+    trigger: 'hover',
+    effects: [{
+      effectId: 'scaleUp'
+    }]
+  }]
+};
+```
+
+### Viewport Entrance
+```typescript
+const config = {
+  interactions: [{
+    key: 'hero',
+    trigger: 'viewEnter',
+    params: { type: 'once', threshold: 0.2 },
+    effects: [{
+      namedEffect: { type: 'FadeIn' },
+      duration: 800
+    }]
+  }]
+};
+```
+
+### Interactive Toggle (Click)
+```typescript
+const config = {
+  interactions: [{
+    key: 'menu-btn',
+    trigger: 'click',
+    params: { type: 'alternate' },
+    effects: [{
+      key: 'menu-content',
+      effectId: 'menu-open', // Creates state 'menu-open'
+      keyframeEffect: {
+        name: 'slide',
+        keyframes: [
+          { transform: 'translateX(-100%)' },
+          { transform: 'translateX(0)' }
+        ]
+      },
+      duration: 300
+    }]
+  }]
+};
+```
+