diff --git a/README.md b/README.md index 4b94684d..744f795e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ + + # Wix Interact Web-native animation and interaction libraries — declarative, AI-ready, framework-agnostic. @@ -5,7 +7,7 @@ Web-native animation and interaction libraries — declarative, AI-ready, framew [![npm version](https://img.shields.io/npm/v/@wix/interact)](https://www.npmjs.com/package/@wix/interact) [![npm version](https://img.shields.io/npm/v/@wix/motion)](https://www.npmjs.com/package/@wix/motion) [![npm version](https://img.shields.io/npm/v/@wix/motion-presets)](https://www.npmjs.com/package/@wix/motion-presets) -[![license](https://img.shields.io/npm/l/@wix/interact)](LICENSE) +[![license](https://img.shields.io/npm/l/@wix/interact)](https://github.com/wix/interact/blob/master/LICENSE) [![bundle size](https://img.shields.io/bundlephobia/minzip/@wix/interact)](https://bundlephobia.com/package/@wix/interact) ## What is Interact? @@ -13,7 +15,7 @@ Web-native animation and interaction libraries — declarative, AI-ready, framew **Wix Interact** (`@wix/interact`) is a declarative interaction layer on top of **@wix/motion**. You describe _when_ something should animate and _what_ should happen in a JSON config — no manual event listeners, no imperative animation wiring. - **Config-driven** — bind triggers (`viewEnter`, `click`, `hover`, `viewProgress`, `pointerMove`, and more) to effects in one `InteractConfig` object -- **Built on native browser APIs** — Web Animations API, `ViewTimeline`, pointer tracking, and CSS; with an optional custom animation runtime via `@wix/motion` +- **Built on native browser APIs** — Web Animations API, `ViewTimeline`, pointer tracking, and CSS. - **Three entry points** — Web Components (`@wix/interact/web`), React (`@wix/interact/react`), and vanilla JS (`@wix/interact`) - **Ready-made presets** — entrance, scroll, pointer, loop, and micro-interactions from `@wix/motion-presets` - **SSR-friendly CSS** — `generate(config)` emits complete CSS for the whole config (keyframes, view-timeline, transitions, FOUC rules) so animations can be ready before JS runs @@ -22,11 +24,11 @@ Web-native animation and interaction libraries — declarative, AI-ready, framew ## Packages -| Package | Description | Links | -| --------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`@wix/interact`](https://github.com/wix/interact/blob/master/packages/interact/) | Declarative interaction layer (main package) | [README](https://github.com/wix/interact/blob/master/packages/interact/README.md) · [npm](https://www.npmjs.com/package/@wix/interact) | -| [`@wix/motion`](https://github.com/wix/interact/blob/master/packages/motion/) | Low-level animation engine | [README](https://github.com/wix/interact/blob/master/packages/motion/README.md) · [npm](https://www.npmjs.com/package/@wix/motion) | -| [`@wix/motion-presets`](https://github.com/wix/interact/blob/master/packages/motion-presets/) | Ready-made animation presets | [README](https://github.com/wix/interact/blob/master/packages/motion-presets/README.md) [npm](https://www.npmjs.com/package/@wix/motion-presets) | +| Package | Description | Links | +| -------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| [`@wix/interact`](https://github.com/wix/interact/blob/master/packages/interact/) | Declarative interaction layer (main package) | [README](https://github.com/wix/interact/blob/master/packages/interact/README.md) · [npm](https://www.npmjs.com/package/@wix/interact) | +| [`@wix/motion`](https://github.com/wix/interact/blob/master/packages/motion/) | Low-level animation engine | [README](https://github.com/wix/interact/blob/master/packages/motion/README.md) · [npm](https://www.npmjs.com/package/@wix/motion) | +| [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) | Ready-made animation presets | [npm](https://www.npmjs.com/package/@wix/motion-presets) | ``` @wix/motion ← @wix/interact (declarative layer) @@ -120,9 +122,10 @@ import { useEffect } from 'react'; import { Interact, Interaction } from '@wix/interact/react'; import * as presets from '@wix/motion-presets'; +Interact.registerEffects(presets); + function App() { useEffect(() => { - Interact.registerEffects(presets); const instance = Interact.create(config); return () => { @@ -187,7 +190,7 @@ const config: InteractConfig = { }; ``` -Inject the styles returned from `generate(config)` into `` for FOUC prevention. +FOUC prevention requires injecting the output of `generate(config)` into ``. ### Click effect @@ -229,7 +232,7 @@ const config: InteractConfig = { trigger: 'viewProgress', effects: [ { - namedEffect: { type: 'ParallaxScroll', speed: 0.5 }, + namedEffect: { type: 'ParallaxScroll', parallaxFactor: 0.5 }, rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } }, rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } }, easing: 'linear', @@ -333,6 +336,11 @@ type Interaction = { ## AI and Agent Support +AI agents can discover @wix/interact documentation through: + +- **[llms.txt](https://wix.github.io/interact/llms.txt)** — structured docs index ([llms.txt standard](https://llmstxt.org/)) +- **[llms-full.txt](https://wix.github.io/interact/llms-full.txt)** — all rules in a single file + ### Rules files **@wix/interact**: @@ -355,7 +363,7 @@ type Interaction = { - Do not invent `namedEffect` types — use only registered presets (see preset rules above) - Do not attach DOM event listeners manually — express behavior through `trigger` and config - For `viewProgress`, avoid `overflow: hidden` on ancestors; use `overflow: clip` instead -- Call `generate(config)` at build time or on the server and inject CSS into ``. For `viewEnter` + `triggerType: 'once'`, to prevent FOUC +- Call `generate(config)` at build time or on the server and inject CSS into `` - `effects` at the config top level is a reusable `Record` - `` should wrap exactly one child (the library targets `.firstElementChild` by default). diff --git a/packages/interact/README.md b/packages/interact/README.md index 4cc68c09..6473a009 100644 --- a/packages/interact/README.md +++ b/packages/interact/README.md @@ -1,3 +1,5 @@ + + # @wix/interact Declarative, configuration-driven interaction library — web-native, AI-ready, and framework-agnostic. @@ -9,12 +11,12 @@ Declarative, configuration-driven interaction library — web-native, AI-ready, ## Why Interact? -- **Declerative** — Define trigger-to-effect bindings in JSON; no imperative event wiring +- **Declarative** — Define trigger-to-effect bindings in JSON; no imperative event wiring - **Web-native** — Built on CSS, WAAPI, ViewTimeline, and DOM APIs; supports DOM management via Custom Elements - **Framework-agnostic** — Web Components and vanilla JS integrations; React integration included - **AI-ready** — JSON configs are machine-readable and provide guardrails; LLMs can generate and agents can validate them - **CSS generation** — `generate(config)` emits complete CSS for the whole config (`@keyframes`, `view-timeline`, transitions, FOUC rules) -- **Preset ecosystem** — Plug in [`@wix/motion-presets`](../motion-presets/README.md) for 80+ ready-made effects. +- **Preset ecosystem** — Plug in [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) for 75+ ready-made effects. - **Accessible** — Built-in `activate` (click + keyboard) and `interest` (hover + focus) trigger variants ## Install @@ -39,9 +41,9 @@ npm install @wix/motion-presets ```ts import { Interact, generate, type InteractConfig } from '@wix/interact/web'; -import * as presets from '@wix/motion-presets'; // optional +import * as presets from '@wix/motion-presets'; // required when using namedEffect -Interact.registerEffects(presets); // optional +Interact.registerEffects(presets); // required when using namedEffect const config: InteractConfig = { interactions: [ @@ -62,7 +64,7 @@ const config: InteractConfig = { }; // render styles - e.g. for SSR -const interactCSS = generate(config, false); +const interactCSS = generate(config, true); // run on client - e.g. on pagereveal event const instance = Interact.create(config); @@ -132,7 +134,7 @@ export function Hero() { } ``` -### Using vaniall JS - no handling for DOM changes +### Using Vanilla JS (you manage element lifecycle) **Vanilla JS** — bind elements after they exist in the DOM: @@ -167,14 +169,14 @@ Config ─┬─► Interact.create() ─► Trigger Observers ─► Effect Eng ``` `generate(config)` runs at build time or on the server to emit complete CSS for the entire config — maximizing offload of effect creation, binding, and running to the browser. -Interact also uses native effect triggering, i.e. `view-timeline`, as it becomes more widely supported +Interact also generates native `view-timeline` CSS declarations, so browsers that support it can drive scroll animations entirely without JS. The `InteractConfig` shape: ```ts type InteractConfig = { interactions: Interaction[]; // trigger → effect bindings - effects: ?Record; // reusable effect definitions + effects?: Record; // reusable effect definitions sequences?: Record; // staggered multi-effect timelines conditions?: Record; // media / selector gates }; @@ -314,8 +316,9 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf effects: { 'lift': { keyframeEffect: { + name: 'lift', keyframes: [ - { transform: 'transformY(-80px)', boxShadow: '0 8px 16px rgb(0 0 0 / 0.15)' }, + { transform: 'translateY(-80px)', boxShadow: '0 8px 16px rgb(0 0 0 / 0.15)' }, ], }, duration: 200, @@ -345,6 +348,7 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf effects: { 'follow-x': { keyframeEffect: { + name: 'follow-x', keyframes: [ { transform: 'rotateY(-45deg)' }, { transform: 'rotateY(0px)' }, @@ -356,6 +360,7 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf }, 'follow-y': { keyframeEffect: { + name: 'follow-y', keyframes: [ { transform: 'rotateX(45deg)' }, { transform: 'rotateX(0px)' }, @@ -397,7 +402,7 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf - **Same element as source and target with `viewEnter`** — Must use `triggerType: 'once'`. Other types cause re-entry loops. - **Hit-area shift on `hover` / `pointerMove`** — Animating size/position of the hovered element shifts the hit area and causes jitter. Instead, animate a child via `selector` or a different `key`. - **`registerEffects()` must run before `Interact.create()`/`generate()`** when using `namedEffect`. -- **FOUC prevention requires** — `generate(config)` injected into ``. +- **FOUC prevention** — requires injecting the output of `generate(config)` into ``. - **`generate(config, useFirstChild)`** — Pass `true` for `` (web), `false` for vanilla and React ``. - **`` must wrap exactly one child** — the library targets `:first-child` by default. @@ -405,6 +410,11 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf Interact's JSON-config surface is the differentiator: configs are serializable, schema-typed, and validate-able (guardrails) — no imperative DOM logic for an LLM to hallucinate. +AI agents can discover @wix/interact documentation through: + +- **[llms.txt](https://wix.github.io/interact/llms.txt)** — structured docs index ([llms.txt standard](https://llmstxt.org/)) +- **[llms-full.txt](https://wix.github.io/interact/llms-full.txt)** — all rules in a single file + **Rules files** ship with the package under [`rules/`](https://github.com/wix/interact/tree/master/packages/interact/rules) — point your agent at them: - [`rules/full-lean.md`](https://wix.github.io/interact/rules/full-lean.md) — complete config spec, pitfalls, and constraints @@ -427,23 +437,23 @@ Interact's JSON-config surface is the differentiator: configs are serializable, - Modern browsers with the Web Animations API (Baseline). - `adoptedStyleSheets` (used by `transition` / `transitionProperties`): Chrome 73+, Firefox 101+, Safari 16.4+, Edge 79+. -- ViewTimeline: Chrome 115+; polyfilled via [`fizban`](https://github.com/wix/fizban) elsewhere. +- ViewTimeline: Chrome 115+; polyfilled via [`fizban`](https://github.com/wix-incubator/fizban) elsewhere. ## Related Packages - [`@wix/motion`](https://github.com/wix/interact/tree/master/packages/motion) — low-level animation engine underneath Interact. - [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) — ready-made effect catalog (entrance, scroll, hover, pointer). -- [`fizban`](https://github.com/wix/fizban) — scroll-driven animation polyfill (bundled dependency). -- [`kuliso`](https://github.com/wix/kuliso) — pointer-driven animation polyfill (bundled dependency). +- [`fizban`](https://github.com/wix-incubator/fizban) — scroll-driven animation polyfill (bundled dependency). +- [`kuliso`](https://github.com/wix-incubator/kuliso) — pointer-driven animation polyfill (bundled dependency). ## Documentation -- [**Getting Started**](https://wix.github.io/interact/docs/guides/getting-started.md) -- [**API Reference**](https://wix.github.io/interact/docs/api/README.md) — `Interact` class, `InteractionController`, standalone functions, types -- [**Guides**](https://wix.github.io/interact/docs/guides/README.md) — triggers, effects, configuration, state, conditions, sequences -- [**Examples**](https://wix.github.io/interact/docs/examples/README.md) — entrance, click, hover, list patterns -- [**Web Components**](https://wix.github.io/interact/docs/guides/custom-elements.md) - integration via custom elements -- [**React Integration**](https://wix.github.io/interact/docs/integration/react.md) - React integration +- [**Getting Started**](https://wix.github.io/interact/docs/#/guides/getting-started) +- [**API Reference**](https://wix.github.io/interact/docs/#/api) — `Interact` class, `InteractionController`, standalone functions, types +- [**Guides**](https://wix.github.io/interact/docs/#/guides) — triggers, effects, configuration, state, conditions, sequences +- [**Examples**](https://wix.github.io/interact/docs/#/examples) — entrance, click, hover, list patterns +- [**Web Components**](https://wix.github.io/interact/docs/#/guides/custom-elements) — integration via custom elements +- [**React Integration**](https://wix.github.io/interact/docs/#/integration/react) — React integration ## License diff --git a/packages/interact/package.json b/packages/interact/package.json index 0d718233..73a7bb0f 100644 --- a/packages/interact/package.json +++ b/packages/interact/package.json @@ -6,6 +6,8 @@ "main": "dist/cjs/index.js", "module": "dist/es/index.js", "types": "dist/types/index.d.ts", + "llms": "https://wix.github.io/interact/llms.txt", + "llmsFull": "https://wix.github.io/interact/llms-full.txt", "exports": { ".": { "types": "./dist/types/index.d.ts", diff --git a/packages/motion/README.md b/packages/motion/README.md index 858c5df6..ed0dde55 100644 --- a/packages/motion/README.md +++ b/packages/motion/README.md @@ -1,182 +1,188 @@ -# Wix Motion +# @wix/motion -A comprehensive animation library featuring 82+ carefully crafted presets, designed for modern web applications, built on native browser technology. +Low-level, web-native animation engine — WAAPI, CSS, scroll-driven, and pointer-tracking animations with a single dependency. -## ✨ Features +[![npm version](https://img.shields.io/npm/v/@wix/motion.svg)](https://www.npmjs.com/package/@wix/motion) +[![bundle size](https://img.shields.io/bundlephobia/minzip/@wix/motion)](https://bundlephobia.com/package/@wix/motion) +[![license](https://img.shields.io/npm/l/@wix/motion.svg)](https://github.com/wix/interact/blob/master/LICENSE) -- **Web Platform First** - Built on native browser technology for smooth 60fps animations -- **82+ Animation Presets** - Professionally designed animations ready to use -- **5 Animation Categories** - Entrance, Ongoing, Scroll, Mouse, and Background Scroll effects -- **TypeScript Support** - Complete type definitions with IntelliSense support -- **Dual Rendering** - Both Web Animations API and CSS-based rendering -- **Scroll Integration** - Advanced scroll-driven animations with ViewTimeline API support -- **Mouse Parallax** - Interactive pointer-based animations -- **Performance Optimized** - Uses fastdom to minimize layout thrashing +## Why Motion? -## 🚀 Quick Start +- **Native-first** — Built directly on the Web Animations API and CSS Animations. +- **ViewTimeline** — First-class scroll-driven animations via the ViewTimeline API, with a scrub fallback when the API is unavailable. +- **Pointer-driven** — `pointer-move` animations map cursor `(x, y)` progress to effects, with optional transition smoothing. +- **Custom effects** — Plug in programmatic render callbacks — no preset registration required. +- **Dual rendering** — Choose CSS for declarative effects or WAAPI for fine-grained control, using the same options shape. +- **Performance** — `fastdom` batches DOM reads/writes; no `requestAnimationFrame` loop (except for customEffect callbacks). +- **Pluggable presets** — `registerEffects()` accepts any effect module. Use [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) or create your own. -### Installation +## Install ```bash npm install @wix/motion ``` -### Basic Usage +## Quick Start + +### Time-based animation (WAAPI) ```typescript import { getWebAnimation } from '@wix/motion'; -// Create a fade-in entrance animation -const animation = getWebAnimation(document.getElementById('myElement'), { - namedEffect: { type: 'FadeIn' }, - duration: 1000, - easing: 'easeOut', +const animation = getWebAnimation(document.getElementById('hero'), { + keyframeEffect: { + name: 'fade-up', + keyframes: [ + { opacity: 0, transform: 'translateY(20px)' }, + { opacity: 1, transform: 'translateY(0)' }, + ], + }, + duration: 600, + easing: 'ease-out', }); -// Play the animation -await animation.play(); +animation.play(); ``` -### Scroll-Driven Animation +### Scroll-driven (ViewTimeline) ```typescript -import { getScrubScene } from '@wix/motion'; +import { getWebAnimation } from '@wix/motion'; -// Create a scroll-driven parallax effect -const scene = getScrubScene( - document.getElementById('scrollElement'), +const scrollRoot = document.getElementById('scrollRoot')!; + +const animation = getWebAnimation( + document.getElementById('parallax'), { - namedEffect: { - type: 'ParallaxScroll', - speed: 0.5, + keyframeEffect: { + name: 'parallax', + keyframes: [{ transform: 'translateY(80px)' }, { transform: 'translateY(-80px)' }], }, + startOffset: { name: 'cover', offset: { value: 0, unit: 'percentage' } }, + endOffset: { name: 'cover', offset: { value: 100, unit: 'percentage' } }, }, - { trigger: 'view-progress', element: document.getElementById('viewport') }, + { trigger: 'view-progress', element: scrollRoot }, ); ``` -## 📚 Animation Categories - -### 🎭 Entrance Animations (24 presets) - -Perfect for element reveals and page transitions: - -- **FadeIn** - Simple opacity transition -- **ArcIn** - Curved motion with 3D rotation -- **BounceIn** - Spring-based entrance with bounce effect -- **SlideIn** - Directional slides from off-screen -- **FlipIn** - 3D flip transitions -- [See all entrance animations →](docs/categories/entrance-animations.md) - -### 🔄 Ongoing Animations (16 presets) - -Continuous looping animations for attention and delight: - -- **Pulse** - Rhythmic scaling effect -- **Breathe** - Organic scaling animation -- **Spin** - Smooth rotation loops -- **Wiggle** - Playful shake motions -- **Float** - Gentle floating movement -- [See all ongoing animations →](docs/categories/ongoing-animations.md) - -### 📜 Scroll Animations (19 presets) - -Scroll-synchronized effects that respond to viewport position: +### Scroll-driven (polyfill / custom scrubbing) -- **ParallaxScroll** - Classic parallax movement -- **FadeScroll** - Opacity changes on scroll -- **GrowScroll** - Scale transformations -- **RevealScroll** - Clip-path reveals -- **TiltScroll** - 3D perspective tilting -- [See all scroll animations →](docs/categories/scroll-animations.md) +```typescript +import { getScrubScene } from '@wix/motion'; -### 🖱️ Mouse Animations (12 presets) +const scrollRoot = document.getElementById('scrollRoot')!; -Interactive pointer-driven effects: +const scenes = getScrubScene( + document.getElementById('parallax'), + { + keyframeEffect: { + name: 'parallax', + keyframes: [{ transform: 'translateY(80px)' }, { transform: 'translateY(-80px)' }], + }, + startOffset: { name: 'cover', offset: { value: 0, unit: 'percentage' } }, + endOffset: { name: 'cover', offset: { value: 100, unit: 'percentage' } }, + }, + { trigger: 'view-progress', element: scrollRoot }, +); +// Drive each scene's `effect(scene, progress)` from your own scroll/IO listener +// when ViewTimeline is unavailable. +``` -- **TrackMouse** - Element follows cursor -- **Tilt3DMouse** - 3D tilt based on pointer position -- **ScaleMouse** - Dynamic scaling on hover -- **BlurMouse** - Motion blur effects -- [See all mouse animations →](docs/categories/mouse-animations.md) +Quickstart examples use `keyframeEffect` (inline keyframes) so they run without registering presets. -### 🖼️ Background Scroll Animations (12 presets) +## Animation Modes -Specialized effects for background media elements: +| Mode | Driver | API | +| -------------- | ----------------------------- | ---------------------------------------------- | +| Time-based | Duration + easing | `getWebAnimation()` / `getCSSAnimation()` | +| Scroll-driven | ViewTimeline / external scrub | `getScrubScene()` with `view-progress` trigger | +| Pointer-driven | Mouse / touch position | `getScrubScene()` with `pointer-move` trigger | -- **BgParallax** - Background parallax scrolling -- **BgZoom** - Dynamic background scaling -- **BgFade** - Background opacity transitions -- **BgRotate** - Background rotation effects -- [See all background animations →](docs/categories/background-scroll-animations.md) +## Core API -## 🛠️ Core APIs +| Function | Purpose | +| -------------------- | ----------------------------------------------------------- | +| `getWebAnimation()` | Create WAAPI-backed animations (time- or scroll-linked) | +| `getCSSAnimation()` | Generate CSS animation descriptors for stylesheet injection | +| `getScrubScene()` | Build scroll-polyfill or pointer-driven scrub scenes | +| `prepareAnimation()` | Pre-measure / mutate DOM via `fastdom` before animating | +| `getAnimation()` | Auto-select CSS (if present) or WAAPI path | +| `getSequence()` | Coordinate staggered groups with easing-based offsets | +| `registerEffects()` | Register named effect modules into the global registry | -### Animation Creation +See [`docs/api/`](https://github.com/wix/interact/blob/master/packages/motion/docs/api/README.md) for full signatures and options. -- `getWebAnimation()` - Create Web Animations API instances -- `getScrubScene()` - Generate scroll/pointer-driven scenes -- `prepareAnimation()` - Pre-calculate measurements for performance +## Custom Effects -### CSS Integration +Three ways to define what an animation does: -- CSS custom properties for dynamic values -- CSS Animation API for stylesheet-based animations -- Automatic vendor prefixing and fallbacks +1. **Inline keyframes** — pass `keyframeEffect: { name, keyframes }` directly. Zero registration. +2. **Custom callback** — pass `customEffect: (element, progress) => void` for full programmatic control per frame. +3. **Named presets** — pass `namedEffect: { type: '…', …params }` referencing effects you've registered via `registerEffects()` (use [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) or your own modules). -### TypeScript Support +## Sequences and Staggering -Complete type definitions for all animation options: +`getSequence()` plays multiple animations with staggered start times. Pass `offset` (ms between each start) and an optional `offsetEasing` to shape how the offsets are distributed across the sequence. ```typescript -interface TimeAnimationOptions { - namedEffect: EntranceAnimation | OngoingAnimation; - duration?: number; - easing?: string; - // ... more options -} -``` +import { getSequence } from '@wix/motion'; + +const sequence = getSequence( + { offset: 150, offsetEasing: 'quadIn' }, + Array.from(document.querySelectorAll('.card')).map((el) => ({ + target: el, + options: { + duration: 600, + easing: 'ease-out', + keyframeEffect: { + name: 'fade-up', + keyframes: [ + { opacity: 0, transform: 'translateY(20px)' }, + { opacity: 1, transform: 'translateY(0)' }, + ], + }, + }, + })), +); -## 📖 Documentation +sequence.play(); +``` -- **[Getting Started](docs/getting-started.md)** - Setup and first animation -- **[Core Concepts](docs/core-concepts.md)** - Understanding the animation system -- **[API Reference](docs/api/)** - Complete function documentation -- **[Category Guides](docs/categories/)** - Detailed category overviews -- **[Preset Reference](docs/presets/)** - Individual animation documentation -- **[Advanced Usage](docs/guides/)** - Performance tips and patterns +See [`docs/api/get-sequence.md`](https://github.com/wix/interact/blob/master/packages/motion/docs/api/get-sequence.md) for the full stagger model. -## 🎮 Interactive Playground +## ViewTimeline and Polyfills -Explore animations interactively in our Storybook playground: +Motion is built around progressive enhancement: -```bash -yarn start # Opens interactive documentation -``` +- **Native path** — when `window.ViewTimeline` is available, `getWebAnimation()` with a `view-progress` trigger returns a WAAPI animation linked to the scroll timeline. +- **Polyfill path** — `getScrubScene()` with `view-progress` returns `ScrubScrollScene[]` objects exposing `start`, `end`, `viewSource`, and `effect(scene, progress)`. Drive these from your own IntersectionObserver/scroll listener. If using `@wix/interact`, its bundled scroll polyfill - [`fizban`](https://github.com/wix-incubator/fizban) - handles this automatically. +- **Pointer smoothing** — `ScrubPointerScene` accepts `transitionDuration` and `transitionEasing` so pointer-tracking effects don't snap to the cursor. -## 🔧 Framework Integration +## Performance Notes -Works seamlessly with popular frameworks: +- `prepareAnimation()` runs `fastdom` measure/mutate phases before the animation starts, avoiding layout thrash. +- The CSS rendering path (`getCSSAnimation`) offloads work to the compositor thread. +- No `requestAnimationFrame` loop runs unless a `customEffect` callback is used. -- React/Vue/Angular components -- GSAP and Framer Motion compatibility -- CSS-in-JS libraries -- Server-side rendering support +## Browser Support -## 🌐 Browser Support +Modern evergreen browsers with Web Animations API support (Chrome, Edge, Firefox, Safari). The ViewTimeline API is used where available; pair `getScrubScene()` with an external driver for older browsers. -- **Modern browsers** with Web Animations API -- **Progressive enhancement** with CSS fallbacks -- **ViewTimeline API** for advanced scroll effects (with polyfill) +## Related Packages -## 🤝 Contributing +Motion is the engine layer. The other packages in this repo build on top of it: -This package is part of the Wix wow-libs monorepo. See [contributing guidelines](../../CONTRIBUTING.md) for development setup and contribution process. +- [`@wix/interact`](https://github.com/wix/interact/tree/master/packages/interact) — declarative, config-driven interaction layer built on Motion. +- [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) — ready-made effect catalog (entrance, ongoing, scroll, mouse, background-scroll). -## 📄 License +## Documentation -UNLICENSED - Internal Wix package +- [Getting Started](https://github.com/wix/interact/blob/master/packages/motion/docs/getting-started.md) +- [Core Concepts](https://github.com/wix/interact/blob/master/packages/motion/docs/core-concepts.md) +- [API Reference](https://github.com/wix/interact/blob/master/packages/motion/docs/api/README.md) +- [Category Guides](https://github.com/wix/interact/blob/master/packages/motion/docs/categories/README.md) +- [Advanced Patterns](https://github.com/wix/interact/blob/master/packages/motion/docs/guides/README.md) ---- +## License -**Built with ❤️ by the Wix wow!Team** +[MIT](https://github.com/wix/interact/blob/master/LICENSE)