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/docs/guides/getting-started.md ADDED Viewed

@@ -0,0 +1,379 @@
+# Getting Started
+Welcome to `@wix/interact`! This guide will help you create your first interaction in under 4 minutes.
+## What is @wix/interact?
+`@wix/interact` is a powerful library that lets you create interactive animations and effects triggered by user actions like clicking, hovering, or scrolling. It integrates seamlessly with `@wix/motion` to provide smooth, performant animations.
+## Core Concepts
+Before we dive in, let's understand the three main concepts:
+1. **Triggers** - User actions that start an interaction (click, hover, scroll, etc.)
+2. **Effects** - The visual changes that happen (animations, transitions, style changes)
+3. **Elements** - The HTML elements that participate in the interaction
+## Installation
+```bash
+npm install @wix/interact
+```
+## Package Entry Points
+`@wix/interact` provides three entry points for different use cases:
+| Entry Point | Use Case | Key Exports |
+|-------------|----------|-------------|
+| `@wix/interact/react` | React applications | `Interaction`, `createInteractRef`, `Interact` |
+| `@wix/interact/web` | Web Components | `Interact`, `defineInteractElement`, `add`, `remove` |
+| `@wix/interact` | Vanilla JS | `Interact`, `add`, `remove` |
+Choose the entry point that matches your framework:
+```typescript
+// For React applications
+import { Interact, Interaction } from '@wix/interact/react';
+// For native Web Components
+import { Interact } from '@wix/interact/web';
+// For vaniall JavaScript
+import { Interact, add, remove } from '@wix/interact';
+```
+---
+## Your First Interaction (React)
+If you're using React, here's the quickest way to get started using the `Interaction` component:
+### Step 1: Create the Configuration
+```tsx
+import React, { useEffect } from 'react';
+import { Interact, Interaction, InteractConfig } from '@wix/interact/react';
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'my-image',            // What element triggers the interaction
+      trigger: 'hover',           // What user action starts it
+      effects: [
+        {
+          keyframeEffect: {
+            name: 'scale',
+            keyframes: [
+              { scale: 2 }
+            ]
+          },
+          duration: 300,          // Animation duration in milliseconds
+          easing: 'ease-out'      // Animation timing
+        }
+      ]
+    }
+  ],
+  effects: {}
+};
+```
+### Step 2: Create the Component
+```tsx
+function App() {
+  useEffect(() => {
+    const instance = Interact.create(config);
+    return () => instance.destroy();
+  }, []);
+  return (
+    <Interaction tagName="div" interactKey="my-image" className="image-container">
+      <img src="logo.png" alt="Logo" />
+    </Interaction>
+  );
+}
+export default App;
+```
+That's it! The image will now scale up when you hover over it.
+---
+## Your First Interaction (Vanilla JavaScript)
+For vanilla JavaScript or non-React frameworks, use the `interact-element` custom element:
+### Step 1: Basic HTML Structure
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>My First Interaction</title>
+</head>
+<body>
+    <interact-element data-interact-key="my-image">
+        <img id="my-image" src="logo.png" alt="Logo" />
+    </interact-element>
+    <script type="module" src="./main.js"></script>
+</body>
+</html>
+```
+**Key points:**
+- Wrap your element in `<interact-element>`
+- Use `data-interact-key` to identify the element (must be unique)
+- The key in your interaction config should be a unique string that matches the value of `data-interact-key` for that element
+### Step 2: Configure the Interaction
+```javascript
+// main.js
+import { Interact } from '@wix/interact/web';
+// Create the interaction configuration
+const config = {
+    interactions: [
+        {
+            key: 'my-image',            // What element triggers the interaction
+            trigger: 'hover',           // What user action starts it
+            effects: [
+                {
+                    keyframeEffect: {
+                        name: 'scale',
+                        keyframes: [
+                            { scale: 2 }
+                        ]
+                    },
+                    duration: 300,          // Animation duration in milliseconds
+                    easing: 'ease-out'      // Animation timing
+                }
+            ]
+        }
+    ],
+    effects: {}
+};
+// Initialize the interaction
+Interact.create(config);
+```
+---
+## Understanding the Configuration
+Let's break down what each part does:
+### The `interactions` Array
+This contains all your interactions. Each interaction defines:
+- **key**: Which element triggers the interaction
+- **trigger**: What user action starts it
+- **effects**: What animations happen
+### The `effects` Object
+Define reusable effects that can be referenced by `effectId`:
+```typescript
+const config = {
+  effects: {
+    'fade-in': {
+      duration: 1000,
+      keyframeEffect: {
+        name: 'fade-in',
+        keyframes: [
+          { opacity: 0 },
+          { opacity: 1 }
+        ]
+      }
+    }
+  },
+  interactions: [
+    {
+      key: 'hero',
+      trigger: 'viewEnter',
+      effects: [{ effectId: 'fade-in' }]  // Reference the effect
+    }
+  ]
+};
+```
+### Effect Properties
+Each effect defines:
+- **key**: Which element gets animated (if missing it defaults to source)
+- **keyframeEffect**: An object containing a `keyframes` property that maps to an array of keyframe objects, and a `name` containing a unique name for that effect
+- **duration**: How long the animation takes
+- **easing**: The animation timing curve
+---
+## Common Patterns
+### Hover with Scale and Rotation
+```javascript
+{
+    key: 'my-element',
+    trigger: 'hover',
+    effects: [
+        {
+            key: 'my-element',
+            keyframeEffect: {
+                name: 'twist',
+                keyframes: [
+                    { transform: 'scale(1) rotate(0deg)' },
+                    { transform: 'scale(1.1) rotate(5deg)' }
+                ]
+            },
+            duration: 200,
+            easing: 'ease-out'
+        }
+    ]
+}
+```
+### Click to Toggle State
+```javascript
+{
+    key: 'my-button',
+    trigger: 'click',
+    params: { method: 'toggle' },
+    effects: [
+        {
+            key: 'my-content',
+            effectId: 'expand',
+        }
+    ]
+}
+```
+### Entrance Animation on Viewport Entry
+```javascript
+{
+    key: 'my-element',
+    trigger: 'viewEnter',
+    effects: [
+        {
+            key: 'my-element',
+            namedEffect: 'FadeIn',
+            duration: 800,
+            easing: 'ease-out'
+        }
+    ]
+}
+```
+> **Tip**: To prevent a flash of content before entrance animations start, use the `generate()` function to create CSS that hides elements until their animation triggers. See [Entrance Animations](../examples/entrance-animations.md#preventing-flash-of-unstyled-content-fouc) for details.
+---
+## React vs Web Components
+| Approach | When to Use |
+|----------|-------------|
+| **React (`Interaction` component)** | React applications, automatic cleanup |
+| **Web Components (`interact-element`)** | Framework-agnostic projects, declerative creation and automatic DOM-changes handling |
+| **Mini** | Framework-agnostic projects, if no need for dynamic DOM changes or integrating with other frameworks |
+### React Example (Recommended for React)
+```tsx
+import { Interact, Interaction } from '@wix/interact/react';
+function Card() {
+  useEffect(() => {
+    Interact.create(config);
+    return () => Interact.destroy();
+  }, []);
+  return (
+    <Interaction tagName="article" interactKey="card" className="card">
+      <h2>Card Title</h2>
+      <p>Card content here</p>
+    </Interaction>
+  );
+}
+```
+### Web Component Example (Framework-agnostic)
+```html
+<interact-element data-interact-key="card">
+  <article class="card">
+    <h2>Card Title</h2>
+    <p>Card content here</p>
+  </article>
+</interact-element>
+```
+```typescript
+import { Interact } from '@wix/interact/web';
+Interact.create(config);
+```
+---
+## TypeScript Support
+Both entry points provide full TypeScript support:
+```typescript
+import { Interact, InteractConfig, Interaction } from '@wix/interact/react';
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'hero',
+      trigger: 'viewEnter',  // TypeScript validates trigger types
+      effects: [
+        {
+          duration: 1000,
+          keyframeEffect: {
+            name: 'fade',
+            keyframes: [{ opacity: 0 }, { opacity: 1 }]
+          }
+        }
+      ]
+    }
+  ],
+  effects: {}
+};
+// Full type inference
+const instance = Interact.create(config);
+```
+---
+## Cleanup
+Always clean up interactions when components unmount or pages change:
+### React
+```tsx
+useEffect(() => {
+  const instance = Interact.create(config);
+  return () => instance.destroy();
+}, []);
+```
+### Vanilla JavaScript
+```javascript
+// On page unload or SPA navigation
+window.addEventListener('beforeunload', () => {
+  Interact.destroy();
+});
+```
+---
+## Next Steps
+Congratulations! You've created your first interaction. Here's what to explore next:
+1. **[Understanding Triggers](./understanding-triggers.md)** - Learn about all 7 trigger types
+2. **[Effects and Animations](./effects-and-animations.md)** - Discover more animation options
+3. **[Custom Elements](./custom-elements.md)** - Understand how `<interact-element>` works
+4. **[React Integration](../integration/react.md)** - Deep dive into React components and hooks
+5. **[Configuration Structure](./configuration-structure.md)** - Organize complex interactions