@wix/interact 1.93.0 → 2.0.0-rc.4

package/docs/guides/custom-elements.md

@@ -0,0 +1,327 @@
+# Custom Elements
+
+The `<interact-element>` custom element is the foundation of `@wix/interact`. This guide explains how it works, when to use it, and how to integrate it effectively into your applications.
+
+## What is interact-element?
+
+`<interact-element>` is a custom HTML element that serves as a bridge between your HTML content and the `@wix/interact` system. It:
+
+- **Wraps your interactive content** to enable trigger detection
+- **Manages element state** using CSS custom states
+- **Handles lifecycle events** for adding/removing interactions
+- **Provides a unique identifier** via `data-interact-key`
+
+## Basic Usage
+
+### HTML Structure
+```html
+<interact-element data-interact-key="my-button">
+    <button id="my-button">Click me</button>
+</interact-element>
+```
+
+### React/JSX Usage
+```tsx
+import React from 'react';
+
+function InteractiveButton() {
+    return (
+        <interact-element data-interact-key="my-button">
+            <button id="my-button">Click me</button>
+        </interact-element>
+    );
+}
+```
+
+### Key Requirements
+1. **Unique `data-interact-key`** - Must match your interaction `key` property
+2. **Child element** - The custom element must contain at least one child
+
+## The data-interact-key Attribute
+
+The `data-interact-key` attribute is crucial - it connects your HTML to your interaction configuration.
+
+### Matching Keys
+The key must match your interaction's key property:
+
+```typescript
+// Configuration
+{
+    key: 'my-button',  // This key...
+    trigger: 'hover',
+    effects: [/* ... */]
+}
+```
+
+```html
+<!-- Must match this key -->
+<interact-element data-interact-key="my-button">
+    <button id="my-button">Hover me</button>
+</interact-element>
+```
+
+## Element Lifecycle
+
+When `<interact-element>` connects to the DOM:
+
+1. **Custom element registration** - Registers the element class if not already done
+2. **Key validation** - Checks for valid `data-interact-key`
+3. **Child validation** - Ensures at least one child element exists
+4. **Interaction activation** - Calls `add()` to enable interactions when connected to DOM
+5. **Automatic cleanup** - Calls `remove()` to clean up interactions when disconnected from DOM
+
+## State Management
+
+### CSS Custom States
+`<interact-element>` uses modern CSS custom states for effect management:
+
+```css
+/* Target elements in specific states */
+interact-element:state(hover-active) .my-element {
+    transform: scale(1.1);
+    transition: transform 0.2s ease;
+}
+
+interact-element:state(clicked) .my-element {
+    background-color: #blue;
+}
+```
+
+### Legacy Browser Support
+For browsers without custom state support, falls back to CSS classes:
+
+```css
+/* Legacy fallback */
+interact-element.--hover-active .my-element {
+    transform: scale(1.1);
+}
+```
+
+### State Toggle Methods
+The element provides methods to manage states:
+
+1. `add`: adds a state named by `effectId`
+2. `remove`: removes a state named by `effectId`
+3. `toggle`: toggles a state named by `effectId`
+4. `clear`: removes all states
+
+## Integration Patterns
+
+### React Integration
+
+TBD
+
+### Vue Integration
+```vue
+<template>
+    <interact-element :data-interact-key="`${elementId}`">
+        <div :id="elementId" class="interactive-element">
+            <slot />
+        </div>
+    </interact-element>
+</template>
+
+<script>
+import { Interact } from '@wix/interact';
+
+export default {
+    props: ['elementId'],
+    mounted() {
+        const config = {
+            interactions: [
+                {
+                    key: this.elementId,
+                    trigger: 'hover',
+                    effects: [
+                        {
+                            key: this.elementId,
+                            namedEffect: {
+                              type: 'FadeIn'
+                            },
+                            duration: 300
+                        }
+                    ]
+                }
+            ]
+        };
+        
+        Interact.create(config);
+    }
+};
+</script>
+```
+
+### Vanilla JavaScript
+```javascript
+// Create element programmatically
+function createInteractiveElement(id, content) {
+    const wixElement = document.createElement('interact-element');
+    wixElement.dataset.wixPath = id;
+    
+    const childElement = document.createElement('div');
+    childElement.id = id;
+    childElement.innerHTML = content;
+    
+    wixElement.appendChild(childElement);
+    
+    return wixElement;
+}
+
+// Usage
+const interactive = createInteractiveElement('my-element', 'Interactive content');
+document.body.appendChild(interactive);
+```
+
+## Advanced Usage
+
+### Multiple Children
+You can have multiple children, but only the first one is used for interaction targeting:
+
+```html
+<interact-element data-interact-key="main-target">
+    <div id="main-target">Primary interactive element</div>
+    <div>Supporting content (not interactive)</div>
+    <span>Additional content</span>
+</interact-element>
+```
+
+### Nested interact-elements
+Nesting is supported for complex interactions:
+
+```html
+<interact-element data-interact-key="outer-container">
+    <div id="outer-container">
+        <interact-element data-interact-key="inner-button">
+            <button id="inner-button">Nested interactive button</button>
+        </interact-element>
+        <p>Other content in outer container</p>
+    </div>
+</interact-element>
+```
+
+### Dynamic Key Updates
+You can change the key dynamically:
+
+```javascript
+const element = document.querySelector('interact-element');
+
+// Remove old interactions
+if (element.dataset.wixPath) {
+    remove(element.dataset.wixPath);
+}
+
+// Update key
+element.dataset.wixPath = 'new-target';
+
+// Reconnect with new key
+element.connect('new-target');
+```
+
+## Styling interact-element
+
+### Default Display
+The custom element has minimal default styling:
+
+```css
+interact-element {
+    display: contents; /* Doesn't affect layout */
+}
+```
+
+### Custom Styling
+You can style the element wrapper if needed:
+
+```css
+/* Make wrapper a block container */
+interact-element.card-wrapper {
+    display: block;
+    padding: 1rem;
+    border-radius: 8px;
+}
+
+/* Style based on state */
+interact-element:state(hover-active) {
+    background-color: rgba(0, 0, 0, 0.05);
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### "No key provided" Warning
+```html
+<!-- Wrong - missing data-interact-key -->
+<interact-element>
+    <div>Content</div>
+</interact-element>
+
+<!-- Correct -->
+<interact-element data-interact-key="my-element">
+    <div id="my-element">Content</div>
+</interact-element>
+```
+
+#### "No child element found" Warning
+```html
+<!-- Wrong - empty element -->
+<interact-element data-interact-key="my-element"></interact-element>
+
+<!-- Correct -->
+<interact-element data-interact-key="my-element">
+    <div id="my-element">Content</div>
+</interact-element>
+```
+
+### Debugging Tips
+
+#### Check Element Registration
+```javascript
+// Verify custom element is registered
+console.log('interact-element registered:', 
+    customElements.get('interact-element') !== undefined);
+```
+
+#### Inspect Element State
+```javascript
+const element = document.querySelector('interact-element');
+console.log('Connected:', element.connected);
+console.log('Key:', element.dataset.wixPath);
+console.log('Has child:', element.firstElementChild !== null);
+```
+
+#### Monitor State Changes
+```javascript
+const element = document.querySelector('interact-element');
+if (element._internals) {
+    console.log('Current states:', Array.from(element._internals.states));
+}
+```
+
+## Performance Considerations
+
+### Element Creation
+- Custom elements are lightweight but avoid creating thousands
+- Use the `selector` property to target elements inside a single custom element component
+- Consider using event delegation for dynamic content
+
+### Memory Management
+- Elements automatically clean up when removed from DOM
+- For SPA routing, ensure proper cleanup during navigation
+- Use `remove()` explicitly if needed for manual cleanup
+
+## Browser Support
+
+### Modern Browsers
+- Adopted style sheets for dynamic CSS
+
+## Best Practices
+
+TBD
+
+## Next Steps
+
+Now that you understand custom elements:
+- **[State Management](./state-management.md)** - Learn about CSS states vs data attributes
+- **[Conditions and Media Queries](./conditions-and-media-queries.md)** - Create responsive interactions
+- **[Understanding Triggers](./understanding-triggers.md)** - Master trigger types and behaviors