@wix/interact 1.92.0 → 2.0.0-rc.2

package/docs/advanced/README.md

@@ -0,0 +1,164 @@
+# Advanced Topics
+
+Deep-dive technical documentation for power users, contributors, and developers who want to extend `@wix/interact`.
+
+## Architecture & Design
+
+### System Architecture
+- [**Architecture Overview**](architecture.md) - High-level system design
+  - [Core Components](architecture.md#components) - Main classes and modules
+  - [Data Flow](architecture.md#data-flow) - How interactions are processed
+  - [Event System](architecture.md#events) - Event handling architecture
+  - [Memory Management](architecture.md#memory) - Lifecycle and cleanup
+
+### Design Decisions
+- [**Design Philosophy**](design-decisions.md) - Why we built it this way
+  - [Configuration-driven Approach](design-decisions.md#config-driven) - Declarative vs imperative
+  - [Custom Elements Choice](design-decisions.md#custom-elements) - Web standards adoption
+  - [Motion Integration](design-decisions.md#motion) - Why @wix/motion
+  - [Performance Priorities](design-decisions.md#performance) - Optimization strategies
+
+## Extending the System
+
+### Custom Triggers
+- [**Creating Custom Triggers**](custom-triggers.md) - Build your own trigger types
+  - [Trigger Handler Interface](custom-triggers.md#interface) - Required implementation
+  - [Event Registration](custom-triggers.md#events) - DOM event handling
+  - [Cleanup Management](custom-triggers.md#cleanup) - Memory and event cleanup
+  - [Parameter Validation](custom-triggers.md#validation) - Type-safe parameters
+  - [Testing Custom Triggers](custom-triggers.md#testing) - Testing strategies
+
+### Custom Effects
+- [**Creating Custom Effects**](custom-effects.md) - Extend animation capabilities
+  - [Effect Interface](custom-effects.md#interface) - Effect implementation
+  - [Motion Integration](custom-effects.md#motion) - Using @wix/motion APIs
+  - [CSS Generation](custom-effects.md#css) - Dynamic CSS creation
+  - [State Management](custom-effects.md#state) - Effect state handling
+
+### Plugin System
+- [**Plugin Architecture**](plugins.md) - Extensible plugin system
+  - [Plugin Interface](plugins.md#interface) - Plugin development
+  - [Lifecycle Hooks](plugins.md#hooks) - Plugin integration points
+  - [Configuration Extensions](plugins.md#config) - Extending configuration
+  - [Plugin Registry](plugins.md#registry) - Plugin management
+
+## Performance Deep Dive
+
+### Optimization Strategies
+- [**Performance Optimization**](performance-optimization.md) - Advanced performance techniques
+  - [GPU Acceleration](performance-optimization.md#gpu) - Hardware acceleration
+  - [Batching Operations](performance-optimization.md#batching) - Efficient DOM updates
+  - [Event Debouncing](performance-optimization.md#debouncing) - Event optimization
+  - [Memory Pooling](performance-optimization.md#pooling) - Object reuse strategies
+
+### Profiling and Analysis
+- [**Performance Profiling**](performance-profiling.md) - Measuring and analyzing performance
+  - [Browser DevTools](performance-profiling.md#devtools) - Built-in profiling tools
+  - [Custom Metrics](performance-profiling.md#metrics) - Application-specific measurements
+  - [Automated Testing](performance-profiling.md#automation) - CI/CD performance testing
+  - [Real-world Monitoring](performance-profiling.md#monitoring) - Production monitoring
+
+### Optimization Patterns
+- [**Animation Patterns**](optimization-patterns.md) - Performant animation techniques
+  - [Transform-based Animations](optimization-patterns.md#transforms) - GPU-friendly animations
+  - [Composite Layers](optimization-patterns.md#compositing) - Layer management
+  - [Frame Rate Optimization](optimization-patterns.md#framerate) - 60fps techniques
+  - [Mobile Optimization](optimization-patterns.md#mobile) - Touch device considerations
+
+## Browser Compatibility
+
+### Polyfills and Fallbacks
+- [**Browser Support**](browser-support.md) - Comprehensive compatibility guide
+  - [Required Polyfills](browser-support.md#polyfills) - Essential polyfills
+  - [Feature Detection](browser-support.md#detection) - Runtime capability checking
+  - [Graceful Degradation](browser-support.md#degradation) - Fallback strategies
+  - [Progressive Enhancement](browser-support.md#enhancement) - Feature layering
+
+### Platform-Specific Issues
+- [**Platform Considerations**](platform-issues.md) - Platform-specific challenges
+  - [iOS Safari](platform-issues.md#ios) - iOS-specific issues and workarounds
+  - [Android Chrome](platform-issues.md#android) - Android considerations
+  - [Desktop Browsers](platform-issues.md#desktop) - Desktop-specific optimizations
+  - [Accessibility Tools](platform-issues.md#accessibility) - Screen reader compatibility
+
+## Debugging and Troubleshooting
+
+### Advanced Debugging
+- [**Deep Debugging**](debugging.md) - Advanced debugging techniques
+  - [Animation Inspector](debugging.md#inspector) - Browser animation tools
+  - [Custom Logging](debugging.md#logging) - Debug output strategies
+  - [State Inspection](debugging.md#state) - Runtime state debugging
+  - [Performance Debugging](debugging.md#performance) - Performance issue diagnosis
+
+### Common Issues
+- [**Troubleshooting Guide**](troubleshooting.md) - Solving complex problems
+  - [Memory Leaks](troubleshooting.md#memory-leaks) - Identifying and fixing leaks
+  - [Performance Issues](troubleshooting.md#performance) - Performance problem solving
+  - [Browser Quirks](troubleshooting.md#quirks) - Browser-specific issues
+  - [Configuration Errors](troubleshooting.md#config) - Common configuration mistakes
+
+## Security Considerations
+
+### Security Best Practices
+- [**Security Guide**](security.md) - Security considerations for interactions
+  - [XSS Prevention](security.md#xss) - Cross-site scripting prevention
+  - [Content Security Policy](security.md#csp) - CSP compatibility
+  - [User Input Validation](security.md#validation) - Safe configuration handling
+  - [Third-party Integration](security.md#third-party) - External library safety
+
+## Contributing
+
+### Development Setup
+- [**Contributing Guide**](contributing.md) - How to contribute to the project
+  - [Development Environment](contributing.md#environment) - Local setup
+  - [Code Standards](contributing.md#standards) - Coding conventions
+  - [Testing Requirements](contributing.md#testing) - Test coverage expectations
+  - [Documentation Standards](contributing.md#docs) - Documentation guidelines
+
+### Release Process
+- [**Release Management**](release-process.md) - How releases are managed
+  - [Versioning Strategy](release-process.md#versioning) - Semantic versioning
+  - [Change Management](release-process.md#changes) - Breaking change policies
+  - [Testing Pipeline](release-process.md#testing) - Pre-release testing
+  - [Documentation Updates](release-process.md#docs) - Documentation maintenance
+
+## Experimental Features
+
+### Upcoming Features
+- [**Experimental APIs**](experimental.md) - Preview of future features
+  - [WebGL Integration](experimental.md#webgl) - 3D animation support
+  - [AI-driven Animations](experimental.md#ai) - Machine learning integration
+  - [Voice/Gesture Triggers](experimental.md#voice-gesture) - Alternative input methods
+
+### Feature Flags
+- [**Feature Flags**](feature-flags.md) - Experimental feature control
+  - [Enabling Features](feature-flags.md#enabling) - How to enable experimental features
+  - [Stability Warnings](feature-flags.md#stability) - Usage considerations
+  - [Feedback Process](feature-flags.md#feedback) - How to provide feedback
+
+## Technical Specifications
+
+### API Contracts
+- [**API Specifications**](api-specs.md) - Detailed API contracts
+  - [Type Definitions](api-specs.md#types) - Complete TypeScript definitions
+  - [Interface Contracts](api-specs.md#contracts) - Implementation requirements
+  - [Error Handling](api-specs.md#errors) - Error codes and handling
+  - [Backwards Compatibility](api-specs.md#compatibility) - API stability guarantees
+
+### Internal APIs
+- [**Internal Documentation**](internal-apis.md) - Internal implementation details
+  - [Private Methods](internal-apis.md#private) - Internal method documentation
+  - [State Management](internal-apis.md#state) - Internal state handling
+  - [Cache Management](internal-apis.md#cache) - Internal caching strategies
+  - [Event Dispatching](internal-apis.md#events) - Internal event system
+
+## Research and Background
+
+### Industry Best Practices
+- [**Industry Analysis**](industry.md) - How we compare to industry standards
+  - [Competitive Analysis](industry.md#competition) - Comparison with other libraries
+  - [Best Practices](industry.md#practices) - Industry-standard practices
+  - [Performance Benchmarks](industry.md#benchmarks) - Performance comparisons
+  - [Standards Compliance](industry.md#compliance) - Web standards adherence
+
+This advanced documentation is intended for developers who need deep technical understanding of the `@wix/interact` system. For general usage, start with the [Getting Started Guide](../guides/getting-started.md) or [Examples](../examples/README.md).

package/docs/api/README.md

@@ -0,0 +1,157 @@
+# API Reference
+
+Complete reference documentation for all public APIs in `@wix/interact`.
+
+## Core API
+
+### Classes
+
+- [**Interact**](interact-class.md) - Main interaction manager class
+  - [Static methods](interact-class.md#static-methods): `create()`, `getInstance()`, `getElement()`, `setElement()`
+  - [Instance methods](interact-class.md#instance-methods): `init()`, `has()`, `clearInteractionStateForKey()`
+  - [Properties](interact-class.md#properties): `dataCache`, `addedInteractions`
+  - [Error handling](interact-class.md#error-handling) and [best practices](interact-class.md#best-practices)
+
+### Functions
+
+- [**add(element, path)**](functions.md#add) - Add interactions to an element
+  - [Usage examples](functions.md#examples) and [behavior details](functions.md#behavior-details)
+  - [Error handling](functions.md#error-handling) and [performance considerations](functions.md#performance-considerations)
+- [**remove(path)**](functions.md#remove) - Remove interactions from an element
+  - [Cleanup behavior](functions.md#behavior-details) and [advanced usage](functions.md#advanced-usage)
+- [**generate(config)**](functions.md#generate) - Generate CSS for hiding elements with entrance animations
+  - [SSR usage](functions.md#server-side-rendering-ssr) and [React integration](functions.md#with-react)
+  - [HTML setup](functions.md#html-setup) and [accessibility](functions.md#accessibility)
+- [**addListItems(root, key, listContainer, elements)**](functions.md#addlistitems) - Add interactions to new list items
+  - [Manual list management](functions.md#manual-list-item-addition) and [batch operations](functions.md#batch-adding-items)
+- [**removeListItems(elements)**](functions.md#removelistitems) - Remove interactions from list items
+  - [Cleanup workflows](functions.md#complete-removal-workflow) and [performance tips](functions.md#performance-considerations)
+
+### Custom Elements
+
+- [**interact-element**](interact-element.md) - Custom element for wrapping interactive content
+  - [Interface](interact-element.md#element-interface) and [lifecycle methods](interact-element.md#methods)
+  - [Framework integration](interact-element.md#framework-integration) (React, Vue, Angular)
+  - [State management](interact-element.md#state-management) and [browser support](interact-element.md#browser-support)
+  - [List management with watchChildList](interact-element.md#list-management-with-watchchildlist)
+
+### Element Selection
+
+- [**Element Selection Priority**](element-selection.md) - Understanding how elements are selected
+  - [Selection priority order](element-selection.md#selection-priority-overview) with flowchart
+  - [Common patterns](element-selection.md#common-patterns) and [troubleshooting](element-selection.md#troubleshooting)
+  - [listContainer vs selector](element-selection.md#scenario-4-listcontainer--selector)
+
+## Type Definitions
+
+### Configuration Types
+
+- [**InteractConfig**](types.md#interactconfig) - Main configuration object
+- [**Interaction**](types.md#interaction) - Individual interaction definition
+- [**Effect**](types.md#effect) - Effect definition and parameters
+- [**Condition**](types.md#condition) - Conditional interaction logic
+
+### Trigger Types
+
+- [**TriggerType**](types.md#triggertype) - Union of all supported triggers
+- [**ViewEnterParams**](types.md#viewenterparams) - Viewport entry configuration
+- [**StateParams**](types.md#stateparams) - State transition parameters  
+- [**PointerMoveParams**](types.md#pointermoveparams) - Pointer movement configuration
+- [**AnimationEndParams**](types.md#animationendparams) - Animation completion triggers
+
+### Effect Types
+
+- [**TimeEffect**](types.md#timeeffect) - Time-based animations with examples
+- [**ScrubEffect**](types.md#scrubeffect) - Progress-based animations with named ranges
+- [**TransitionEffect**](types.md#transitioneffect) - CSS transition effects
+- [**EffectRef**](types.md#effectref) - Effect reference by ID
+
+### Advanced Types
+
+- [**IInteractElement**](types.md#iwixinteractelement) - Custom element interface
+- [**InteractCache**](types.md#interactcache) - Internal cache structure
+- [**EffectProperty**](types.md#effectproperty) - Animation content types
+- [**TypeScript patterns**](types.md#typescript-usage-patterns) - Type guards and generic constraints
+
+## Quick Reference
+
+### Essential Imports
+```typescript
+import { 
+  Interact,           // Main class
+  add, remove,        // Standalone functions
+  generate,           // CSS generation for entrance animations
+  InteractConfig,     // Configuration type
+  IInteractElement // Custom element interface
+} from '@wix/interact';
+```
+
+### Basic Pattern
+```typescript
+// 1. Create configuration
+const config: InteractConfig = {
+  interactions: [{ /* ... */ }],
+  effects: { /* ... */ }
+};
+
+// 2. Initialize
+const interact = Interact.create(config);
+
+// 3. HTML usage
+// <interact-element data-interact-key="#element">
+//   <div>Content</div>
+// </interact-element>
+```
+
+### Type Hierarchy
+
+```
+InteractConfig
+├── interactions: Interaction[]
+│   ├── trigger: TriggerType
+│   ├── key: string
+│   ├── selector?: string
+│   ├── listContainer?: string
+│   ├── params?: TriggerParams  
+│   ├── conditions?: string[]
+│   └── effects: (Effect | EffectRef)[]
+├── effects?: Record<string, Effect>
+│   ├── TimeEffect (duration-based)
+│   ├── ScrubEffect (progress-based)
+│   └── TransitionEffect (CSS transitions)
+└── conditions?: Record<string, Condition>
+    ├── Media queries
+    └── Container queries
+```
+
+## Integration with @wix/motion
+
+The `@wix/interact` package provides a declarative layer on top of `@wix/motion`. Effect definitions can include:
+
+- `keyframeEffect` - Raw keyframe animations
+- `namedEffect` - Pre-built animation effects from @wix/motion
+- `customEffect` - Custom animation functions with full control
+
+**Example Integration:**
+```typescript
+{
+  effects: {
+    'slide-in': {
+      duration: 800,
+      keyframeEffect: {
+        name: 'slide-in',
+        keyframes: [
+          { opacity: 0, transform: 'translateY(50px)' },
+          { opacity: 1, transform: 'translateY(0)' }
+        ]
+      }
+    },
+    'bounce': {
+      duration: 600,
+      namedEffect: 'bounce' // Pre-built from @wix/motion
+    }
+  }
+}
+```
+
+See the [Effects Guide](../guides/effects.md) for detailed information on animation integration and [Examples](../examples/README.md) for practical usage patterns.