@wix/interact 1.66.0

package/README.md

@@ -0,0 +1,258 @@
+# @wix/interact
+
+A powerful, declarative interaction library for creating engaging web animations and effects. Built on top of `@wix/motion`, it provides a configuration-driven approach to adding triggers, animations, and state transitions to web applications.
+
+## Features
+
+- 🎯 **Declarative Configuration** - Define complex interactions through simple JSON configuration
+- 🎨 **Rich Animation Support** - Integration with `@wix/motion` for high-performance animations  
+- 🖱️ **Multiple Trigger Types** - Support for hover, click, scroll, viewport, and custom triggers
+- 📱 **Responsive Conditions** - Media query and container-based conditional interactions
+- 🔧 **Custom Elements** - Web Components API for easy framework integration
+- ⚡ **Performance Optimized** - Efficient event handling and animation management
+- 🧩 **Framework Agnostic** - Works with React, vanilla JS, and other frameworks
+
+## Installation
+
+```bash
+npm install @wix/interact
+```
+
+## Quick Start
+
+### 1. Basic Setup
+
+```typescript
+import { Interact } from '@wix/interact';
+
+// Define your interaction configuration
+const config = {
+  interactions: [
+    {
+      trigger: 'viewEnter',
+      source: '#my-element',
+      effects: [
+        {
+          effectId: 'fade-in',
+        }
+      ]
+    }
+  ],
+  effects: {
+    'fade-in': {
+      duration: 1000,
+      keyframeEffect: {
+        opacity: [0, 1]
+      }
+    }
+  }
+};
+
+// Initialize the interact instance
+const interact = Interact.create(config);
+```
+
+### 2. HTML Setup
+
+```html
+<!-- Wrap your target element with wix-interact-element -->
+<wix-interact-element data-wix-path="#my-element">
+  <div>This will fade in when it enters the viewport!</div>
+</wix-interact-element>
+```
+
+### 3. Framework Integration
+
+#### React
+```tsx
+import React from 'react';
+
+function MyComponent() {
+  return (
+    <wix-interact-element data-wix-path="#my-element">
+      <div className="animated-content">
+        Hello, animated world!
+      </div>
+    </wix-interact-element>
+  );
+}
+```
+
+## Core Concepts
+
+### Triggers
+Define when interactions should occur:
+- `viewEnter` - When element enters viewport
+- `click` - On element click
+- `hover` - On element hover
+- `viewProgress` - Based on scroll progress
+- `pointerMove` - On pointer/mouse movement
+- `pageVisible` - When page becomes visible
+- `animationEnd` - When another animation completes
+
+### Effects
+Define what should happen:
+- **Time-based animations** - Duration-based effects with easing
+- **Scroll-driven animations** - Progress-based effects tied to scroll
+- **Pointer-driven animations** - Progress-based effects linked to pointer possition
+- **CSS transitions** - Style property transitions
+- **Custom effects** - Integration with `@wix/motion`
+
+### Configuration Structure
+```typescript
+{
+  interactions: [    // Define trigger → effect relationships
+    {
+      trigger: 'viewEnter',
+      source: '#source-element',
+      effects: [{ effectId: 'my-effect' }]
+    }
+  ],
+  effects: {         // Define reusable effect definitions
+    'my-effect': {
+      duration: 1000,
+      keyframeEffect: { opacity: [0, 1] }
+    }
+  },
+  conditions: {      // Define conditional logic
+    'mobile-only': {
+      type: 'media',
+      predicate: '(max-width: 768px)'
+    }
+  }
+}
+```
+
+## API Reference
+
+### Interact Class
+
+#### Static Methods
+```typescript
+// Create a new instance with configuration
+Interact.create(config: InteractConfig): Interact
+
+// Get instance that handles a specific path
+Interact.getInstance(path: string): Interact | undefined
+
+// Get cached element by path
+Interact.getElement(path: string): IWixInteractElement | undefined
+```
+
+### Standalone Functions
+```typescript
+// Add interactions to an element
+add(element: IWixInteractElement, path: string): boolean
+
+// Remove all interactions from an element
+remove(path: string): void
+```
+
+## Examples
+
+### Entrance Animation
+```typescript
+{
+  interactions: [{
+    trigger: 'viewEnter',
+    source: '#hero',
+    effects: [{ effectId: 'slide-up' }]
+  }],
+  effects: {
+    'slide-up': {
+      duration: 800,
+      easing: 'ease-out',
+      keyframeEffect: {
+        transform: ['translateY(50px)', 'translateY(0)'],
+        opacity: [0, 1]
+      }
+    }
+  }
+}
+```
+
+### Click Interaction
+```typescript
+{
+  interactions: [{
+    trigger: 'click',
+    source: '#button',
+    effects: [{ effectId: 'bounce' }]
+  }],
+  effects: {
+    'bounce': {
+      duration: 600,
+      namedEffect: 'bounce'
+    }
+  }
+}
+```
+
+### Responsive Interactions
+```typescript
+{
+  interactions: [{
+    trigger: 'hover',
+    source: '#card',
+    conditions: ['desktop-only'],
+    effects: [{ effectId: 'lift' }]
+  }],
+  conditions: {
+    'desktop-only': {
+      type: 'media',
+      predicate: '(min-width: 1024px)'
+    }
+  },
+  effects: {
+    'lift': {
+      duration: 200,
+      keyframeEffect: {
+        transform: ['translateY(0)', 'translateY(-8px)'],
+        boxShadow: ['0 2px 4px rgba(0,0,0,0.1)', '0 8px 16px rgba(0,0,0,0.15)']
+      }
+    }
+  }
+}
+```
+
+## Documentation
+
+- [Full API Documentation](docs/api/README.md)
+- [Guides and Tutorials](docs/guides/README.md)
+- [Examples and Patterns](docs/examples/README.md)
+- [Integration Guides](docs/integration/README.md)
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Run tests
+yarn test
+
+# Run playground
+yarn playground
+
+# Build package
+yarn build
+```
+
+## Browser Support
+
+- ✅ Modern browsers with Web Components support
+- ⚠️ If using setting styles via JS in `transition` or `transitionProerties` - which use `adoptedStyleSheets`, browser support is: Chrome 73+, Firefox 101+, Safari 16.4+, Edge 79+
+
+## Related Packages
+
+- [`@wix/motion`](../motion/README.md) - Core animation engine
+- [`fizban`](https://github.com/wix-incubator/fizban) - For polyfilling scroll-driven animations
+- [`kuliso`](https://github.com/wix-incubator/kuliso) - For polyfilling pointer-driven animations
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this package.
+
+## License
+
+UNLICENSED - Internal Wix package

package/dist/cjs/WixInteractElement.js

@@ -0,0 +1,103 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+exports.__esModule = true;
+exports.WIX_INTERACT_EFFECT_DATA_ATTR = void 0;
+exports.getWixInteractElement = getWixInteractElement;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _interact = require("./interact");
+const WIX_INTERACT_EFFECT_DATA_ATTR = exports.WIX_INTERACT_EFFECT_DATA_ATTR = 'wixInteractEffect';
+function getWixInteractElement() {
+  let checkedForLegacyStateSyntax = false;
+  let isLegacyStateSyntax = false;
+  return class WixInteractElement extends HTMLElement {
+    constructor() {
+      super();
+      (0, _defineProperty2.default)(this, "_internals", void 0);
+      (0, _defineProperty2.default)(this, "connected", void 0);
+      (0, _defineProperty2.default)(this, "sheet", void 0);
+      this.connected = false;
+      this.sheet = null;
+      if (this.attachInternals) {
+        this._internals = this.attachInternals();
+        if (!checkedForLegacyStateSyntax) {
+          checkedForLegacyStateSyntax = true;
+          try {
+            this._internals.states.add('test');
+            this._internals.states.delete('test');
+          } catch (e) {
+            isLegacyStateSyntax = true;
+          }
+        }
+      } else {
+        checkedForLegacyStateSyntax = true; // custom states not supported - skip syntax check
+        this._internals = null;
+      }
+    }
+    connectedCallback() {
+      this.connect();
+    }
+    disconnectedCallback() {
+      const path = this.dataset.wixPath;
+      if (path) {
+        (0, _interact.remove)(path);
+      }
+      if (this.sheet) {
+        const index = document.adoptedStyleSheets.indexOf(this.sheet);
+        document.adoptedStyleSheets.splice(index, 1);
+      }
+      this.connected = false;
+    }
+    connect(path) {
+      if (this.connected) {
+        return;
+      }
+      path = path || this.dataset.wixPath;
+      if (!path) {
+        console.warn('WixInteractElement: No path provided');
+        return;
+      }
+      if (this.firstElementChild) {
+        this.connected = (0, _interact.add)(this, path);
+      } else {
+        console.warn('WixInteractElement: No child element found');
+      }
+    }
+    renderStyle(cssText) {
+      const sheet = new CSSStyleSheet();
+      this.sheet = sheet;
+      sheet.replace(cssText);
+      document.adoptedStyleSheets.push(sheet);
+    }
+    toggleEffect(effectId, method) {
+      if (isLegacyStateSyntax) {
+        effectId = `--${effectId}`;
+      }
+      if (this._internals) {
+        if (method === 'toggle') {
+          this._internals.states.has(effectId) ? this._internals.states.delete(effectId) : this._internals.states.add(effectId);
+        } else if (method === 'add') {
+          this._internals.states.add(effectId);
+        } else if (method === 'remove') {
+          this._internals.states.delete(effectId);
+        } else if (method === 'clear') {
+          this._internals.states.clear();
+        }
+      } else {
+        var _this$dataset$WIX_INT;
+        const currentEffects = new Set(((_this$dataset$WIX_INT = this.dataset[WIX_INTERACT_EFFECT_DATA_ATTR]) == null ? void 0 : _this$dataset$WIX_INT.split(' ')) || []);
+        if (method === 'toggle') {
+          currentEffects.has(effectId) ? currentEffects.delete(effectId) : currentEffects.add(effectId);
+        } else if (method === 'add') {
+          currentEffects.add(effectId);
+        } else if (method === 'remove') {
+          currentEffects.delete(effectId);
+        } else if (method === 'clear') {
+          currentEffects.clear();
+        }
+        this.dataset[WIX_INTERACT_EFFECT_DATA_ATTR] = Array.from(currentEffects).join(' ');
+      }
+    }
+  };
+}
+//# sourceMappingURL=WixInteractElement.js.map

package/dist/cjs/WixInteractElement.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_interact","require","WIX_INTERACT_EFFECT_DATA_ATTR","exports","getWixInteractElement","checkedForLegacyStateSyntax","isLegacyStateSyntax","WixInteractElement","HTMLElement","constructor","_defineProperty2","default","connected","sheet","attachInternals","_internals","states","add","delete","e","connectedCallback","connect","disconnectedCallback","path","dataset","wixPath","remove","index","document","adoptedStyleSheets","indexOf","splice","console","warn","firstElementChild","renderStyle","cssText","CSSStyleSheet","replace","push","toggleEffect","effectId","method","has","clear","_this$dataset$WIX_INT","currentEffects","Set","split","Array","from","join"],"sources":["../../src/WixInteractElement.ts"],"sourcesContent":["import type { StateParams } from './types';\nimport { add, remove } from './interact';\n\nexport const WIX_INTERACT_EFFECT_DATA_ATTR = 'wixInteractEffect';\n\nexport function getWixInteractElement() {\n  let checkedForLegacyStateSyntax = false;\n  let isLegacyStateSyntax = false;\n\n  return class WixInteractElement extends HTMLElement {\n    _internals: (ElementInternals & { states: Set<string> }) | null;\n    connected: boolean;\n    sheet: CSSStyleSheet | null;\n\n    constructor() {\n      super();\n\n      this.connected = false;\n      this.sheet = null;\n\n      if (this.attachInternals) {\n        this._internals = this.attachInternals() as ElementInternals & {\n          states: Set<string>;\n        };\n\n        if (!checkedForLegacyStateSyntax) {\n          checkedForLegacyStateSyntax = true;\n\n          try {\n            this._internals.states.add('test');\n            this._internals.states.delete('test');\n          } catch (e) {\n            isLegacyStateSyntax = true;\n          }\n        }\n      } else {\n        checkedForLegacyStateSyntax = true; // custom states not supported - skip syntax check\n        this._internals = null;\n      }\n    }\n    connectedCallback() {\n      this.connect();\n    }\n\n    disconnectedCallback() {\n      const path = this.dataset.wixPath;\n\n      if (path) {\n        remove(path);\n      }\n\n      if (this.sheet) {\n        const index = document.adoptedStyleSheets.indexOf(this.sheet);\n        document.adoptedStyleSheets.splice(index, 1);\n      }\n\n      this.connected = false;\n    }\n\n    connect(path?: string) {\n      if (this.connected) {\n        return;\n      }\n\n      path = path || this.dataset.wixPath;\n\n      if (!path) {\n        console.warn('WixInteractElement: No path provided');\n        return;\n      }\n\n      if (this.firstElementChild) {\n        this.connected = add(this, path);\n      } else {\n        console.warn('WixInteractElement: No child element found');\n      }\n    }\n\n    renderStyle(cssText: string) {\n      const sheet = new CSSStyleSheet();\n      this.sheet = sheet;\n\n      sheet.replace(cssText);\n\n      document.adoptedStyleSheets.push(sheet);\n    }\n\n    toggleEffect(effectId: string, method: StateParams['method']) {\n      if (isLegacyStateSyntax) {\n        effectId = `--${effectId}`;\n      }\n\n      if (this._internals) {\n        if (method === 'toggle') {\n          this._internals.states.has(effectId)\n            ? this._internals.states.delete(effectId)\n            : this._internals.states.add(effectId);\n        } else if (method === 'add') {\n          this._internals.states.add(effectId);\n        } else if (method === 'remove') {\n          this._internals.states.delete(effectId);\n        } else if (method === 'clear') {\n          this._internals.states.clear();\n        }\n      } else {\n        const currentEffects = new Set(\n          this.dataset[WIX_INTERACT_EFFECT_DATA_ATTR]?.split(' ') || [],\n        );\n\n        if (method === 'toggle') {\n          currentEffects.has(effectId)\n            ? currentEffects.delete(effectId)\n            : currentEffects.add(effectId);\n        } else if (method === 'add') {\n          currentEffects.add(effectId);\n        } else if (method === 'remove') {\n          currentEffects.delete(effectId);\n        } else if (method === 'clear') {\n          currentEffects.clear();\n        }\n\n        this.dataset[WIX_INTERACT_EFFECT_DATA_ATTR] =\n          Array.from(currentEffects).join(' ');\n      }\n    }\n  };\n}\n"],"mappings":"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","ignoreList":[]}