diff --git a/.cursor/plans/interact_readme_implementation_0bc18dd8.plan.md b/.cursor/plans/interact_readme_implementation_0bc18dd8.plan.md index bf0ddd18..dd29f10a 100644 --- a/.cursor/plans/interact_readme_implementation_0bc18dd8.plan.md +++ b/.cursor/plans/interact_readme_implementation_0bc18dd8.plan.md @@ -60,13 +60,13 @@ Sourced from `package.json` description. No emoji. 6-7 concise bullet points: -- **Config-driven**: Define trigger-to-effect bindings in JSON — no imperative event wiring -- **Web-native**: Built on WAAPI, ViewTimeline, and IntersectionObserver — no custom runtime -- **Three entry points**: Web Components, React, Vanilla JS — same config shape across all -- **AI-ready**: JSON configs are machine-readable — LLMs can generate and validate them -- **Preset ecosystem**: Plug in `@wix/motion-presets` for 80+ ready-made effects -- **Pre-rendered CSS**: `generate(config)` emits complete CSS for the whole config — `@keyframes`, `view-timeline`, transitions, FOUC rules — so animations run natively before JS loads (SSR / build-time friendly) -- **Accessible**: Built-in `activate` (keyboard) and `interest` (focus) trigger variants +- **Declerative** — 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. +- **Accessible** — Built-in `activate` (click + keyboard) and `interest` (hover + focus) trigger variants ### 4. Install diff --git a/packages/interact/README.md b/packages/interact/README.md index eee85dec..4338ab0f 100644 --- a/packages/interact/README.md +++ b/packages/interact/README.md @@ -1,383 +1,385 @@ # @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. +Declarative, configuration-driven interaction library — web-native, AI-ready, and framework-agnostic. -## Features +[![npm version](https://img.shields.io/npm/v/@wix/interact.svg)](https://www.npmjs.com/package/@wix/interact) +[![bundle size](https://img.shields.io/bundlephobia/minzip/@wix/interact)](https://bundlephobia.com/package/@wix/interact) +[![license](https://img.shields.io/npm/l/@wix/interact.svg)](https://github.com/wix/interact/blob/master/LICENSE) +[![downloads](https://img.shields.io/npm/dm/@wix/interact.svg)](https://www.npmjs.com/package/@wix/interact) -- 🎯 **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 +## Why Interact? -## Installation +- **Declerative** — 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. +- **Accessible** — Built-in `activate` (click + keyboard) and `interest` (hover + focus) trigger variants + +## Install ```bash npm install @wix/interact ``` +### Use pre-made presets + +```bash +npm install @wix/motion-presets +``` + +`@wix/motion-presets` is optional but recommended — it provides the `namedEffect` library used in most examples below. + ## Quick Start -### Using Custom Elements +### Using Web Components (recommended) -#### 1. Basic Setup +**Web Components** — wrap the target element with ``: -```typescript -import { Interact } from '@wix/interact/web'; +```ts +import { Interact, generate, type InteractConfig } from '@wix/interact/web'; +import * as presets from '@wix/motion-presets'; // optional -// Define your interaction configuration -const config = { +Interact.registerEffects(presets); // optional + +const config: InteractConfig = { interactions: [ { + key: 'hero', trigger: 'viewEnter', - key: '#my-element', - effects: [ - { - effectId: 'fade-in', - }, - ], + effects: [{ effectId: 'hero-in' }], }, ], effects: { - 'fade-in': { - duration: 1000, - keyframeEffect: { - name: 'fade', - keyframes: { opacity: [0, 1] }, - }, + 'hero-in': { + duration: 800, + easing: 'ease-out', + namedEffect: { type: 'FadeIn' }, // requires motion-presets + triggerType: 'once', }, }, }; -// Initialize the interact instance -const interact = Interact.create(config); +// render styles - e.g. for SSR +const interactCSS = generate(config, false); + +// run on client - e.g. on pagereveal event +const instance = Interact.create(config); ``` -#### 2. HTML Setup +In `` add: ```html - - -
This will fade in when it enters the viewport!
+ +``` + +In the `` add: + +```html + +
Hello, animated world!
 ``` ### Using React -#### 1. Basic Setup +A complete React example: register presets, generate CSS, mount the component, clean up on unmount. + +```tsx +import { useEffect } from 'react'; +import { Interact, Interaction, generate } from '@wix/interact/react'; +import * as presets from '@wix/motion-presets'; // optional -```typescript -import { Interact } from '@wix/interact/react'; +Interact.registerEffects(presets); // optional -// Define your interaction configuration const config = { interactions: [ { + key: 'hero', trigger: 'viewEnter', - key: '#my-element', - effects: [ - { - effectId: 'fade-in', - }, - ], + effects: [{ effectId: 'hero-in' }], }, ], effects: { - 'fade-in': { - duration: 1000, - keyframeEffect: { - name: 'fade', - keyframes: { opacity: [0, 1] }, - }, + 'hero-in': { + duration: 800, + easing: 'ease-out', + namedEffect: { type: 'FadeIn' }, // requires motion-presets + triggerType: 'once', }, }, }; -// Initialize the interact instance -const interact = Interact.create(config); -``` +export function App () { + const interactCSS = generate(config, false); + // rest of App logic ... -#### 2. HTML Setup + useEffect(() => { + const instance = Interact.create(config); + return () => instance.destroy(); + }, []); -```tsx -import { Interaction } from '@wix/interact/react'; + return ( + // can go to + + // ... + + // ... + ) +} -function MyComponent() { +// in components/Hero.jsx +export function Hero() { return ( - + Hello, animated world! ); } ``` -### Vanilla usage +### Using vaniall JS - no handling for DOM changes -#### 1. Basic Setup +**Vanilla JS** — bind elements after they exist in the DOM: -```typescript +```ts import { Interact, add } from '@wix/interact'; -// Define your interaction configuration -const config = { - interactions: [ - { - trigger: 'viewEnter', - key: '#my-element', - effects: [ - { - effectId: 'fade-in', - }, - ], - }, - ], - effects: { - 'fade-in': { - duration: 1000, - keyframeEffect: { - name: 'fade', - keyframes: { opacity: [0, 1] }, - }, - }, - }, -}; - -// add element -add(document.querySelector('[data-interact-key="my-element"]'), 'my-element'); - -// Initialize the interact instance -const interact = Interact.create(config); -``` - -#### 2. HTML Setup +const instance = Interact.create(config); -```html -
Hello, animated world!
+add(document.querySelector('#hero'), 'hero'); ``` -## Core Concepts - -### Triggers +## Entry Points -Define when interactions should occur: +| Import | Use When | +| --------------------- | ----------------------------------------------------------- | +| `@wix/interact` | Vanilla JS — manual element binding via `add()`/`remove()`. | +| `@wix/interact/web` | Web Components — `` custom element. | +| `@wix/interact/react` | React — `` component with lifecycle. | -- `viewEnter` - When element enters viewport -- `click` - On element click -- `hover` - On element hover -- `viewProgress` - Scroll-driven animations based on progress of element in viewport -- `pointerMove` - On pointer/mouse movement over an element or viewport -- `animationEnd` - When another animation completes +All three entry points export the same `Interact` class, `generate()` function, and types. -### Effects +## How It Works -Define what should happen: +``` +Config ─┬─► Interact.create() ─► Trigger Observers ─► Effect Engine ─► Animation (via @wix/motion) + └─► generate() ────────► CSS (@keyframes, view-timeline, animations, transitions) ─► +``` -- **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 position -- **CSS transitions** - Style property transitions -- **Custom effects** - Integration with `@wix/motion` +`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 -### Configuration Structure +The `InteractConfig` shape: -```typescript -{ - interactions: [ // Define trigger → effect relationships - { - trigger: 'viewEnter', - key: 'source-element', - effects: [{ effectId: 'my-effect' }] - } - ], - effects: { // Define reusable effect definitions - 'my-effect': { - duration: 1000, - keyframeEffect: { - name: 'fade', - keyframes: { opacity: [0, 1] } - } - } - }, - conditions: { // Define conditional logic - 'mobile-only': { - type: 'media', - predicate: '(max-width: 768px)' - } - } -} +```ts +type InteractConfig = { + interactions: Interaction[]; // trigger → effect bindings + effects: Record; // reusable effect definitions + sequences?: Record; // staggered multi-effect timelines + conditions?: Record; // media / selector gates +}; ``` -## Basic API Reference +## Triggers -### Interact Class +| Trigger | Fires On | Params | +| -------------- | -------------------------------------------- | --------------------------------------- | +| `viewEnter` | Element enters viewport | `threshold?`, `inset?` | +| `viewProgress` | While element scrolls through viewport | (use `rangeStart`/`rangeEnd` on effect) | +| `hover` | Pointer enters/leaves element | — | +| `click` | Element is clicked | — | +| `activate` | Click + keyboard (a11y variant of `click`) | — | +| `interest` | Hover + focus (a11y variant of `hover`) | — | +| `pointerMove` | While pointer moves over element or viewport | `hitArea?`, `axis?` | +| `animationEnd` | Another effect completes | `effectId` | -#### Static Methods +## Effects -```typescript -// Create a new instance with configuration -Interact.create(config: InteractConfig): Interact -``` - -### Standalone Functions - -```typescript -// Add interactions to an element -add(element: IInteractElement, key: string): boolean +| Effect Type | Use For | +| ------------------------------------- | -------------------------------------------------------------------------- | +| `keyframeEffect` | Inline keyframes — self-contained, no preset needed. | +| `namedEffect` | Registered presets from `@wix/motion-presets` (e.g. `{ type: 'FadeIn' }`). | +| `customEffect` | Programmatic `(element, progress) => void` callback. | +| `transition` / `transitionProperties` | CSS state changes driven by `stateAction` (`add`/`remove`/`toggle`). | -// Remove all interactions from an element -remove(key: string): void -``` +## Recipes -## Examples +Each example is a complete `InteractConfig` — pass it to `Interact.create(config)`. -### Entrance Animation +### Entrance animation -```typescript +```ts { interactions: [{ - trigger: 'viewEnter', key: 'hero', - effects: [{ effectId: 'slide-up' }] + trigger: 'viewEnter', + effects: [{ effectId: 'float-in' }], }], effects: { - 'slide-up': { + 'float-in': { duration: 800, easing: 'ease-out', - keyframeEffect: { - name: 'slide-up', - keyframes: { - transform: ['translateY(20px)', 'translateY(0)'], - opacity: [0, 1] - } - } - } - } + namedEffect: { type: 'FloatIn', direction: 'bottom', distance: '60px' }, + }, + }, } ``` -### Click Interaction +### Click effect -```typescript +```ts { interactions: [{ + key: 'cta', trigger: 'click', - key: 'button', - effects: [{ effectId: 'bounce' }] + effects: [{ effectId: 'pulse' }], }], effects: { - 'bounce': { - duration: 600, - namedEffect: { - type: 'Bounce' - } - } - } + 'pulse': { + duration: 300, + keyframeEffect: { + name: 'pulse', + keyframes: { transform: ['scale(1)', 'scale(1.08)', 'scale(1)'] }, + }, + triggerType: 'repeat', + }, + }, } ``` -### Scroll-driven Animation +### Scroll-driven parallax -```typescript +```ts { interactions: [{ + key: 'card', trigger: 'viewProgress', - key: 'parallax-card', - effects: [{ effectId: 'parallax-scroll' }] + effects: [{ effectId: 'parallax' }], }], effects: { - 'parallax-scroll': { + 'parallax': { keyframeEffect: { - name: 'parallax-1', + name: 'parallax', keyframes: [ - { transform: 'translateY(200px)' }, - { transform: 'translateY(-200px)' } - ] + { transform: 'translateY(-120px)' }, + { transform: 'translateY(120px)' }, + ], }, rangeStart: { name: 'cover', offset: { value: 0, unit: 'percentage' } }, rangeEnd: { name: 'cover', offset: { value: 100, unit: 'percentage' } }, fill: 'both', - easing: 'linear' - } - } + easing: 'linear', + }, + }, } ``` -### Responsive Interactions +### Hover toggle (CSS transition) -```typescript +```ts { interactions: [{ - trigger: 'hover', key: 'card', - conditions: ['desktop-only'], - effects: [{ effectId: 'lift' }] + trigger: 'hover', + effects: [{ effectId: 'lift', stateAction: 'toggle' }], }], - conditions: { - 'desktop-only': { - type: 'media', - predicate: '(min-width: 1024px)' - } - }, effects: { 'lift': { - duration: 200, - keyframeEffect: { - name: 'lift', - keyframes: { - transform: ['translateY(0)', 'translateY(-8px)'], - boxShadow: ['0 2px 4px rgb(0 0 0 / 0.1)', '0 8px 16px rgb(0 0 0 / 0.15)'] - } - } - } - } + transition: { + duration: 200, + easing: 'ease-out', + styleProperties: [ + { name: 'transform', value: 'scale(1.08)' }, + { name: 'box-shadow', value: '0 8px 16px rgb(0 0 0 / 0.15)' }, + ], + }, + }, + }, } ``` -## Documentation +### Pointer-tracking custom effect -- [Full API Documentation](https://wix.github.io/interact/docs/api) -- [Guides and Tutorials](https://wix.github.io/interact/docs/guides) -- [Examples and Patterns](https://wix.github.io/interact/docs/examples) -- [Integration Guides](https://wix.github.io/interact/docs/integration) +```ts +{ + interactions: [{ + key: 'spotlight', + trigger: 'pointerMove', + params: { hitArea: 'root' }, + effects: [{ effectId: 'follow' }], + }], + effects: { + 'follow': { + customEffect: (element, progress) => { + (element as HTMLElement).style.setProperty('--x', `${progress.x * 100}%`); + (element as HTMLElement).style.setProperty('--y', `${progress.y * 100}%`); + }, + }, + }, +} +``` -## AI Support +## Common Pitfalls -- [Full-flow, lean rules](https://wix.github.io/interact/rules/full-lean.md) -- [Rules for integration](https://wix.github.io/interact/rules/integration.md) -- [Rules for view entrance interactions](https://wix.github.io/interact/rules/viewenter.md) -- [Rules for click interactions](https://wix.github.io/interact/rules/click.md) -- [Rules for hover interactions](https://wix.github.io/interact/rules/click.md) -- [Rules for scroll interactions](https://wix.github.io/interact/rules/viewprogress.md) -- [Rules for pointer-move interactions](https://wix.github.io/interact/rules/pointermove.md) +- **`overflow: hidden` breaks `viewProgress`** — Use `overflow: clip` on all ancestors between the source and the scroll container. +- **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. Animate a child via `selector` instead. +- **`registerEffects()` must run before `Interact.create()`** when using `namedEffect`. +- **FOUC prevention requires both** — `generate(config)` injected 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. -## Development +## AI & Agent Support -```bash -# Install dependencies -yarn install +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. -# Run tests -yarn test +**Rules files** ship with the package under [`rules/`](https://github.com/wix/interact/tree/master/packages/interact/rules) — point your agent at them: -# Run playground -yarn playground +- [`rules/full-lean.md`](https://wix.github.io/interact/rules/full-lean.md) — complete config spec, pitfalls, and constraints +- [`rules/integration.md`](https://wix.github.io/interact/rules/integration.md) — integration entry points, lifecycle, style generation +- [`rules/viewenter.md`](https://wix.github.io/interact/rules/viewenter.md) — viewport entrance triggers (scroll-triggered animations) +- [`rules/viewprogress.md`](https://wix.github.io/interact/rules/viewprogress.md) — scroll-driven animations +- [`rules/click.md`](https://wix.github.io/interact/rules/click.md) — click and activate triggers +- [`rules/hover.md`](https://wix.github.io/interact/rules/hover.md) — hover and interest triggers +- [`rules/pointermove.md`](https://wix.github.io/interact/rules/pointermove.md) — pointer-driven animations -# Build package -yarn build -``` +**Generation constraints** for agents producing configs: + +- Do not invent `namedEffect` types — use only registered presets. +- Do not attach DOM event listeners manually — use triggers. +- Do not use `overflow: hidden` on scroll-tracked ancestors — use `overflow: clip`. +- Always pre-render CSS with `generate(config)` and inject into ``. +- Always call `Interact.registerEffects(presets)` before `generate()` and `Interact.create()` when using `namedEffect`. ## 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+ +- 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. ## Related Packages -- [`@wix/motion`](../motion/README.md) - Core animation engine -- [`fizban`](https://github.com/wix/fizban) - For polyfilling scroll-driven animations -- [`kuliso`](https://github.com/wix/kuliso) - For polyfilling pointer-driven animations +- [`@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). + +## 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 ## License diff --git a/readme-spec-1.md b/readme-spec-1.md deleted file mode 100644 index a51a8ce0..00000000 --- a/readme-spec-1.md +++ /dev/null @@ -1,97 +0,0 @@ -# README Research - -**Current Repo Takeaways** The rewrite should cover [root README.md](http:///Users/Yehonatand/dev/interact/README.md:1), [packages/interact/README.md](http:///Users/Yehonatand/dev/interact/packages/interact/README.md:1), [packages/motion/README.md](http:///Users/Yehonatand/dev/interact/packages/motion/README.md:1), and add a missing package README for `packages/motion-presets/`. - -Important cleanup: `@wix/motion` should be presented as the low-level engine, not as the preset catalog. Presets now belong in `@wix/motion-presets`. Also, the Motion README says `UNLICENSED`, while package metadata says `MIT`. - -**Strong GitHub References** - -| Category | References | What To Borrow | -| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | -| Animation engines | [Motion](https://github.com/motiondivision/motion), [GSAP](https://github.com/greensock/GSAP), [Anime.js](https://github.com/juliangarnier/anime), [react-spring](https://github.com/pmndrs/react-spring), [Popmotion](https://github.com/Popmotion/popmotion) | crisp positioning, tiny first example, “why this engine,” platform/API split | -| Declarative interaction | [AOS](https://github.com/michalsnik/aos), [VueUse Motion](https://github.com/vueuse/motion), [use-gesture](https://github.com/pmndrs/use-gesture), [interact.js](https://github.com/taye/interact.js), [AutoAnimate](https://github.com/formkit/auto-animate) | config defaults, trigger tables, recipe/caveat sections, clear scope boundaries | -| Presets/catalogs | [Motion Primitives](https://github.com/ibelick/motion-primitives), [Magic UI](https://github.com/magicuidesign/magicui), [Rive Web](https://github.com/rive-app/rive-wasm), [Lottie Web](https://github.com/airbnb/lottie-web) | catalog navigation, designer/developer workflow, examples, performance notes | -| LLM/generative UI | [Vercel AI SDK](https://github.com/vercel/ai), [Tambo](https://github.com/tambo-ai/tambo), [json-render](https://github.com/vercel-labs/json-render), [OpenUI](https://github.com/thesysdev/openui), [Google A2UI](https://github.com/google/A2UI), [AG-UI](https://github.com/ag-ui-protocol/ag-ui) | schema-first explanations, component maps, guardrails, “for agents” setup | -| Agent docs/tooling | [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk), [Magic UI MCP](https://github.com/magicuidesign/mcp), [OpenAI Agents JS](https://github.com/openai/openai-agents-js) | runnable examples, concepts first, tool/resource tables, agent-specific instructions | - -**Reusable Section Strategy** - -| Section | Goal | -| :------------------------------- | :----------------------------------------------------------------------------------------- | -| One-line identity | Say exactly what the package is, who it is for, and what problem it solves. | -| Package/entry-point matrix | Help developers and agents choose the right import. | -| Install \+ first working example | One copy-paste path that works without needing the whole docs site. | -| Mental model | Define stable nouns: trigger, effect, preset, sequence, condition, scene, scrub. | -| API surface table | Small, scannable table of exported functions/classes and when to use each. | -| Recipes | 3-5 common tasks, each linked to docs: entrance, hover/click, scroll, pointer, state/list. | -| Caveats | Browser support, reduced motion, layout pitfalls, preset registration, DOM binding. | -| Agent/LLM support | Link rules files, show canonical config shape, list “do not guess” constraints. | -| Development | Repo commands only where relevant; package READMEs should stay user-facing first. | - -**Root README Strategy** - -Make the root README the map of the ecosystem, not a full API guide. - -Suggested sections: - -1. `# Wix Interact` or `# Wix Motion & Interact` -2. Short monorepo promise: web-native animation and declarative interaction libraries. -3. Package matrix: `@wix/motion`, `@wix/interact`, `@wix/motion-presets`. -4. “Which package should I use?” decision table. -5. Minimal combined example: `@wix/interact` \+ `@wix/motion-presets`. -6. Architecture diagram showing Motion underneath Interact and Presets. -7. Docs/rules links, including agent-facing rules. -8. Development setup: `nvm use`, `yarn install`, `yarn build`, `yarn test`, docs/demo commands. -9. Contributing/license. - -**@wix/motion README Strategy** - -Position it as the engine. - -Suggested sections: - -1. What it is: low-level WAAPI/CSS animation toolkit. -2. When to use Motion directly vs Interact. -3. Install. -4. Quickstart with `getWebAnimation`. -5. Scroll/pointer-driven example with `getScrubScene`. -6. Core concepts: time animations, scrub animations, named effects, custom effects, sequences. -7. API table: `getWebAnimation`, `getCSSAnimation`, `getScrubScene`, `prepareAnimation`, `getSequence`, `registerEffects`. -8. Using presets via `@wix/motion-presets`. -9. Performance/browser/reduced-motion notes. -10. Agent notes: prefer Motion for custom low-level animation generation. - -**@wix/interact README Strategy** - -Position it as the declarative runtime. - -Suggested sections: - -1. What it is: JSON/config-driven trigger-to-effect binding. -2. Entry-point table: `@wix/interact`, `/react`, `/web`. -3. Install, with optional `@wix/motion-presets`. -4. One canonical quickstart for React, then links for Web Components and vanilla. -5. Mental model: element keys \-\> triggers \-\> effects/sequences \-\> conditions. -6. Trigger table: `viewEnter`, `viewProgress`, `hover`, `click`, `pointerMove`, `animationEnd`, etc. -7. Effect table: keyframes, named presets, CSS transitions/state, custom effects. -8. Recipes: entrance, hover, scroll progress, pointer tracking, list items. -9. Common pitfalls from [full-lean rules](http:///Users/Yehonatand/dev/interact/packages/interact/rules/full-lean.md:1). -10. AI support: stable config shape, rules links, “register presets before create,” “do not manually attach listeners.” - -**@wix/motion-presets README Strategy** - -Add this README. It should be a catalog gateway. - -Suggested sections: - -1. What it is: ready-made named effects for Motion/Interact. -2. Install. -3. Register all presets and selective registration examples. -4. Category matrix: entrance, ongoing, scroll, mouse, background-scroll. -5. “Choose by intent” table: reveal, attention, parallax, pointer, background media. -6. Small examples for Interact and Motion. -7. Link to preset reference docs/rules. -8. Parameter conventions: direction, distance units, range offsets, reduced motion. -9. Agent support: link [presets-main.md](http:///Users/Yehonatand/dev/interact/packages/motion-presets/rules/presets/presets-main.md:1), say to rely on defaults when unsure. - -One extra note: reconcile preset counts before publishing. Local source currently suggests category counts that do not perfectly match one rules file, especially mouse presets. diff --git a/readme-spec-2.md b/readme-spec-2.md deleted file mode 100644 index b16afd99..00000000 --- a/readme-spec-2.md +++ /dev/null @@ -1,175 +0,0 @@ -# README Research - -## Research Findings & README Content Strategy - -### Tier 1 — Direct Competitors / Closest Analogues - -| Repository | Stars | Why It's Relevant | -| :------------------------------------------------------------------------- | :---- | :------------------------------------------------------------------------------------------------------- | -| [**Motion**](https://github.com/motiondivision/motion) (fka Framer Motion) | 31.8k | Closest competitor — animation library, monorepo, multi-platform (React/JS/Vue), also built on WAAPI | -| [**GSAP**](https://github.com/greensock/GSAP) | 24.6k | Gold standard animation library README — rich docs, clear hierarchy, plugin ecosystem | -| [**react-spring**](https://github.com/pmndrs/react-spring) | 29k | Cross-platform spring-physics animation — excellent concise README with social proof | -| [**Lenis**](https://github.com/darkroomengineering/lenis) | 13.5k | Scroll library — the most comprehensive API reference README I found; excellent for developer experience | -| [**Theatre.js**](https://github.com/theatre-js/theatre) | 12k | Motion design monorepo — visual \+ programmatic API, great "use cases" section with GIFs | -| [**AutoAnimate**](https://github.com/formkit/auto-animate) | 13.8k | Zero-config animation — extremely concise, visual-first README | - -### Tier 2 — Declarative/Config-Driven & Generative UI - -| Repository | Stars | Why It's Relevant | -| :---------------------------------------------------------------------- | :---- | :------------------------------------------------------------------------------------------------------------------------------------ | -| [**json-render**](https://github.com/vercel-labs/json-render) | 14k | Declarative JSON-driven UI framework — excellent monorepo package table, catalog pattern similar to Interact's config-driven approach | -| [**OpenAI Agents SDK**](https://github.com/openai/openai-agents-python) | — | Best-in-class "core concepts" numbered list with linked docs; good model for AI Support section | - ---- - -### Section Anatomy: What the Best READMEs Do - -I identified **14 recurring section patterns** across these projects. Here's what each achieves: - -| \# | Section | Goal | Best Example | -| :-- | :-------------------------------- | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------- | -| 1 | **Hero Banner / Logo** | Visual identity, instant recognition | Motion, react-spring, Lenis, Theatre.js | -| 2 | **One-Line Description** | Instant "what is this?" comprehension | Motion: _"An open source animation library for React and JavaScript"_ | -| 3 | **Badges** | Trust signals (npm version, downloads, build status, bundle size) | Lenis (npm, downloads, size), AutoAnimate | -| 4 | **Why X? / Value Proposition** | Answer "why should I use this over alternatives?" | Motion: bullet list of differentiators. GSAP: narrative paragraph | -| 5 | **Install** | Immediate actionability — copy-paste-ready | All of them — typically first code block | -| 6 | **Quick Start** | "Hello world" in \<30 seconds | Motion: 3-line code per platform. Your Interact README already does this well | -| 7 | **Core Concepts** | Mental model for the library's architecture | OpenAI Agents SDK: numbered list with linked docs. Interact's current README does this | -| 8 | **Packages / Ecosystem Table** | Monorepo navigation \+ scope clarity | json-render: comprehensive table. Lenis: linked sub-packages | -| 9 | **API Reference (inline)** | Key APIs surfaced without leaving the README | Lenis: full Settings/Properties/Methods/Events tables | -| 10 | **Examples / Demos** | "See it in action" — live links, GIFs, CodeSandbox | Theatre.js: animated GIFs. Motion: 330+ examples link | -| 11 | **Framework Integration** | Shows flexibility and reduces "will it work with my stack?" anxiety | Motion: React/JS/Vue tabs. Interact already has this | -| 12 | **AI Support / LLM-Friendliness** | Machine-readable guidance for coding agents | Interact's current README has this — unique differentiator\! | -| 13 | **Browser Support** | Compatibility clarity | Lenis: limitations section. GSAP: broad compatibility claims | -| 14 | **Contributing / License** | Community invitation \+ legal clarity | Universal pattern | - ---- - -### Content Strategy Per File - -#### 1\. Root README (`/README.md`) - -**Current state:** Generic monorepo boilerplate. Doesn't convey what the project _is_ or _why_ it matters. - -**Recommended sections:** - -| Section | Content Description | -| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Hero** | Logo/banner image \+ tagline: _"Web-native animation & interaction libraries — declarative, AI-ready, framework-agnostic."_ | -| **Badges** | npm versions for all 3 packages, MIT license, CI status, bundle sizes | -| **What is Interact?** | 2-3 sentence elevator pitch explaining the project vision: declarative, config-driven animations built on native browser APIs (WAAPI, ViewTimeline, pointer tracking). Emphasize: zero dependencies on external animation engines, everything runs on the platform. | -| **Packages** | Table with columns: Package, npm name, Description, Links (README, npm, docs). List `@wix/motion`, `@wix/interact`, `@wix/motion-presets`. Include the dependency graph from AGENTS.md as a small diagram. | -| **Quick Start** | Minimal "pick your path" section — 3 short code snippets showing the most common entry point for each package (similar to how Motion shows React/JS/Vue). | -| **Live Demo / Website** | Link to `https://wix.github.io/interact/` with a screenshot or GIF of the examples page | -| **Documentation** | Links to docs site, API reference, guides, examples gallery | -| **AI Support** | Brief section noting the project ships with LLM/agent integration rules. Link to the rules files. Mention the `llms.txt`\-style resources. This is a unique differentiator — lean into it. | -| **Development** | Condensed: `nvm use && yarn install && yarn build && yarn test`. Link to CONTRIBUTING.md for details. | -| **Contributing** | Short invitation \+ link to CONTRIBUTING.md | -| **License** | MIT | - -**Key principle:** The root README is a _landing page_ and _navigation hub_. It should not duplicate package-level detail. It answers: "What is this monorepo? What's in it? Where do I go next?" - -**Best references:** json-render (package table), Motion (platform tabs), Lenis (clean hierarchy) - ---- - -#### 2\. `@wix/motion` README (`packages/motion/README.md`) - -**Current state:** Decent but has issues — claims "82+ presets" which belongs to motion-presets, has emojis in section headers (inconsistent style), mentions GSAP/Framer Motion compatibility (questionable), says "UNLICENSED" but package.json says MIT. - -**Recommended sections:** - -| Section | Content Description | -| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Title \+ One-Liner** | `@wix/motion` — _"Low-level, web-first animation toolkit. WAAPI, scroll-driven, and pointer-tracking animations with zero dependencies."_ (Use the package.json description) | -| **Badges** | npm version, bundle size (bundlephobia), license | -| **Why Motion?** | 4-5 bullet points: built on native WAAPI (no custom runtime), ViewTimeline for scroll, pointer-driven animations, fastdom for perf, dual rendering (WAAPI \+ CSS), TypeScript-first | -| **Install** | `npm install @wix/motion` | -| **Quick Start** | 2 examples: (1) Basic time-based animation with `getWebAnimation()`, (2) Scroll-driven with `getScrubScene()`. Keep them accurate to the actual API. | -| **Core APIs** | Brief table or list of the main exports: `getWebAnimation()`, `getScrubScene()`, `prepareAnimation()`, CSS integration. Link each to API docs. | -| **Animation Types** | Explain the 3 animation modes: time-based (WAAPI), scroll-driven (ViewTimeline), pointer-driven. Brief description \+ code snippet each. | -| **TypeScript** | Show the key interfaces — `TimeAnimationOptions`, `ScrubSceneOptions`. Developers love seeing the type signatures upfront. | -| **Performance** | Brief section on fastdom batching, why it matters, best practices | -| **Documentation** | Links to full API docs, category guides, preset reference | -| **Browser Support** | WAAPI support, ViewTimeline (with polyfill note via `fizban`), fallback strategy | -| **Related Packages** | `@wix/interact` (declarative layer on top), `@wix/motion-presets` (ready-made presets), `fizban` (scroll polyfill), `kuliso` (pointer polyfill) | -| **AI Support** | Link to rules for LLM/agent integration | -| **License** | MIT (fix the current "UNLICENSED" error) | - -**Best references:** Lenis (comprehensive API tables), GSAP (clear value prop narrative), Motion (concise per-platform examples) - ---- - -#### 3\. `@wix/interact` README (`packages/interact/README.md`) - -**Current state:** This is actually the strongest README already. Good structure, real code examples, covers all 3 entry points. Needs refinement, not a rewrite. - -**Recommended sections:** - -| Section | Content Description | -| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Title \+ One-Liner** | `@wix/interact` — _"Declarative, configuration-driven interaction library — web-native, AI-ready, and framework-agnostic."_ | -| **Badges** | npm version, bundle size, license | -| **Why Interact?** | Emphasize the unique value: JSON config drives everything, works with vanilla/React/Web Components, AI agents can generate configs. Compare briefly to imperative alternatives. | -| **Install** | `npm install @wix/interact` | -| **Quick Start** | Keep the 3 entry points (Custom Elements, React, Vanilla) but make them more concise — show just one trigger type in each, not all three with identical configs. | -| **How It Works** | A Mermaid diagram or ASCII flow showing: `Config → Interact.create() → Triggers → Effects → Animation`. This is the mental model section — the config structure is the key concept. | -| **Triggers** | Table of all trigger types with one-line descriptions. Keep what's there but tighten. | -| **Effects** | Table of effect types. | -| **Configuration Schema** | The annotated config structure — keep but add links to full schema docs | -| **Examples** | 3-4 focused examples: entrance, click, scroll-driven, responsive. Keep but slim down — the current README has too many full config blocks. Link to the examples gallery for more. | -| **Entry Points** | Table: `@wix/interact` (vanilla), `@wix/interact/react` (React), `@wix/interact/web` (Custom Elements). Brief description of when to use each. | -| **Documentation** | Links to docs, guides, API reference, examples | -| **AI Support** | This is Interact's killer feature for differentiation. Expand this section: explain that configs are JSON-serializable and LLM-friendly, link to all rule files, mention that AI agents can generate complete interaction configs. Consider linking to `llms.txt` or Context7 integration. | -| **Browser Support** | Keep current content | -| **Related Packages** | `@wix/motion`, `@wix/motion-presets`, `fizban`, `kuliso` | -| **License** | MIT | - -**Best references:** json-render (config-driven framework with similar catalog/registry pattern), OpenAI Agents SDK (core concepts list), Motion (multi-platform quick start) - ---- - -#### 4\. `@wix/motion-presets` README (`packages/motion-presets/README.md`) — **NEW** - -**Current state:** Does not exist. Needs to be created. - -**Recommended sections:** - -| Section | Content Description | -| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Title \+ One-Liner** | `@wix/motion-presets` — _"Ready-made animation presets for `@wix/motion` — entrance, scroll, pointer, loop, and background effects."_ | -| **Badges** | npm version, bundle size, license | -| **What's Included** | Summary: X presets across 5 categories. Brief bullet list of categories with counts. | -| **Install** | `npm install @wix/motion-presets` | -| **Quick Start** | Show `registerEffects()` usage — how to import and register presets, then use them by name | -| **Preset Categories** | 5 subsections, one per category (Entrance, Ongoing, Scroll, Mouse, Background Scroll). Each has: description, preset list (names only — like a menu), link to detailed docs. Move the category content from the current Motion README here where it belongs. | -| **Usage with `@wix/interact`** | Show how presets are consumed via Interact's `namedEffect` in config. This bridges the two packages. | -| **Usage with `@wix/motion`** | Show direct usage with `getWebAnimation()` and `getScrubScene()` | -| **Creating Custom Presets** | Brief guide or link to docs on the preset structure/interface | -| **Full Preset Reference** | Link to docs with every preset's parameters and visual preview | -| **Related Packages** | `@wix/motion` (required peer), `@wix/interact` (declarative layer) | -| **License** | MIT | - -**Best references:** The current Motion README's "Animation Categories" section (move it here), GSAP (plugin ecosystem presentation) - ---- - -### Cross-Cutting Recommendations - -1. **Kill the emojis in headers.** The current Motion README uses emoji headers. None of the top-tier libraries (Motion, GSAP, Lenis) do this. Use clean markdown headers. - -2. **Add badges to all packages.** npm version, bundle size (bundlephobia), license badge, and CI status. This is universal across all well-maintained OSS. - -3. **AI Support is your differentiator — make it prominent.** No other animation library has a dedicated AI/LLM section. Interact's existing `AI Support` section with rule links is ahead of the curve. Expand it in the Interact README and reference it from root. - -4. **Use a consistent structure.** All 3 package READMEs should follow the same template: Title \+ one-liner → badges → why/value prop → install → quick start → core concepts → API overview → docs links → related → license. - -5. **Add visual assets.** Theatre.js and AutoAnimate demonstrate that GIFs/screenshots dramatically increase engagement. Consider adding: - - A hero GIF for the root README showing the examples page - - Small inline GIFs for each animation category in motion-presets - -6. **Keep API reference minimal in READMEs.** Lenis is an outlier with its full API tables in the README. For your project, link to the docs site — the README should be a "menu" not the "full meal." - -7. **llms.txt consideration.** Given the AI-ready positioning, consider adding an `llms.txt` file at the root that describes the project in a structured format for AI agents. Reference it from the root README. This aligns with the emerging GitHub convention. - -8. **Fix factual errors.** The current Motion README says "UNLICENSED" but package.json says MIT. It also claims features (82+ presets, GSAP compatibility) that belong to other packages or aren't accurate.