diff --git a/.cursor/plans/llms-txt_web_presence_c57a751b.plan.md b/.cursor/plans/llms-txt_web_presence_c57a751b.plan.md index a3e98315..4cba6d63 100644 --- a/.cursor/plans/llms-txt_web_presence_c57a751b.plan.md +++ b/.cursor/plans/llms-txt_web_presence_c57a751b.plan.md @@ -7,19 +7,19 @@ todos: status: completed - id: workflow content: Update `.github/workflows/interactdocs.yml` -- run generation script and copy outputs to `_site/` - status: pending + status: completed - id: npm-ship content: Add `llms.txt` to `packages/interact/package.json` files array, add `.gitignore` entries for generated files - status: pending + status: completed - id: canonical-url content: Add canonical URL HTML comment to top of `full-lean.md` - status: pending + status: completed - id: root-script content: Add `generate:llms` script to root `package.json` - status: pending + status: completed - id: verify content: Run generation script locally and verify both outputs are correct - status: pending + status: completed isProject: false --- diff --git a/.cursor/plans/motionpresets_readme_implementation_5114f617.plan.md b/.cursor/plans/motionpresets_readme_implementation_5114f617.plan.md index 8dd500c8..cee18be3 100644 --- a/.cursor/plans/motionpresets_readme_implementation_5114f617.plan.md +++ b/.cursor/plans/motionpresets_readme_implementation_5114f617.plan.md @@ -1,15 +1,42 @@ --- name: MotionPresets README Implementation -overview: Create a new README.md for the @wix/motion-presets package, positioned as a catalog gateway that summarizes all 73 presets across 5 categories, shows registration and usage patterns with both @wix/motion and @wix/interact, and links to detailed reference docs and agent rules. +overview: Create a new README.md for the @wix/motion-presets package, positioned as a catalog gateway that summarizes all 62 presets across 4 categories, shows registration and usage patterns with both @wix/motion and @wix/interact, and links to detailed reference docs and agent rules. DVD and background-scroll presets are excluded — not production ready. todos: - id: write-readme content: Write the new packages/motion-presets/README.md following the 13-section structure above - status: pending + status: completed - id: verify-examples content: Verify code examples compile against actual API signatures (registerEffects from @wix/motion, namedEffect shape, getScrubScene trigger options) - status: pending + status: completed - id: verify-preset-counts content: Cross-check final preset name lists in the README against src/library/*/index.ts barrel files to ensure accuracy + status: completed + - id: fix-dvd-export + content: Fix missing barrel export — add DVD to packages/motion-presets/src/library/ongoing/index.ts (the preset is fully implemented and documented but was accidentally omitted from the barrel) + status: cancelled + - id: exclude-non-production + content: 'DVD and all background-scroll presets confirmed not production ready — removed from all docs and rules, DVD removed from barrel export, NOT PRODUCTION READY comment added to each source file' + status: completed + - id: phase2-rules-audit + content: '[Phase 2] After the README is complete, audit rules/presets/ files for any discrepancies surfaced during README preparation and update them to match verified ground truth' + status: completed + - id: phase2-mouse-rules + content: '[Phase 2] Add BounceMouse and SpinMouse entries to mouse-presets.md (currently only 9 of 11 user-facing mouse presets are documented there)' + status: completed + - id: phase2-npm-publish + content: "[Phase 2] Add 'rules' and 'docs' to packages/motion-presets/package.json files array once rule files are verified — consistent with @wix/interact npm publishing pattern" + status: pending + - id: phase3-extend-script + content: '[Phase 3] Extend scripts/generate-llms.mjs to also read packages/motion-presets/rules/presets/ and include those files in both llms.txt and llms-full.txt' + status: pending + - id: phase3-docs-section + content: '[Phase 3] Add presets-main.md under the ## Docs section of llms.txt (below full-lean.md and integration.md)' + status: pending + - id: phase3-presets-section + content: '[Phase 3] Add a new ## Presets section to llms.txt containing the 4 category rule files (entrance, scroll, ongoing, mouse)' + status: pending + - id: phase3-verify + content: '[Phase 3] Re-run scripts/generate-llms.mjs and verify both outputs are correct' status: pending isProject: false --- @@ -18,17 +45,20 @@ isProject: false ## Context -[`packages/motion-presets/`](packages/motion-presets/) has no `README.md`. Both research specs ([readme-spec-1.md](readme-spec-1.md), [readme-spec-2.md](readme-spec-2.md)) call for creating one, positioning it as a **catalog gateway** -- the entry point for discovering and using ready-made animation presets. +`[packages/motion-presets/](packages/motion-presets/)` has no `README.md`. Both research specs ([readme-spec-1.md](readme-spec-1.md), [readme-spec-2.md](readme-spec-2.md)) call for creating one, positioning it as a **catalog gateway** -- the entry point for discovering and using ready-made animation presets. -The package exports **73 presets** across 5 categories (verified from source and rules): +The package exports **62 presets** across 4 categories: - **Entrance** (19): FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn - **Scroll** (19): ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll -- **Ongoing** (14): Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle -- **Mouse** (9): AiryMouse, BlobMouse, BlurMouse, ScaleMouse, SkewMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse -- **Background Scroll** (12): BgCloseUp, BgFade, BgFadeBack, BgFake3D, BgPan, BgParallax, BgPullBack, BgReveal, BgRotate, BgSkew, BgZoom, ImageParallax +- **Ongoing** (13): Bounce, Breathe, Cross, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle _(`DVD` is implemented but **not production ready** — excluded from barrel exports and all documentation)_ +- **Mouse** (11): AiryMouse, BlobMouse, BlurMouse, BounceMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse _(`CustomMouse` is excluded — it is internal infrastructure used to implement `customEffect` for the `pointerMove` trigger, not a user-facing preset)_ -Key architectural note: `registerEffects()` lives in **`@wix/motion`**, not this package. This package exports preset modules that you pass _into_ `registerEffects()`. +> **Excluded (not production ready):** DVD (ongoing) and all 12 background-scroll presets (BgCloseUp, BgFade, BgFadeBack, BgFake3D, BgPan, BgParallax, BgPullBack, BgReveal, BgRotate, BgSkew, BgZoom, ImageParallax). Each source file carries a `NOT PRODUCTION READY` comment. DVD is also removed from the barrel export. + +Key architectural note: `registerEffects()` lives in `**@wix/motion`\**, not this package. This package exports preset modules that you pass *into\* `registerEffects()`. + +> **SSOT:** This README and the rules files will eventually be migrated to generated templates under `context/` in Phase 3 of the [SSOT restructure plan](https://github.com/wix/interact/pull/210/changes#diff-a68c779a9afdb459ce4130f6f8d9fa811df80d04b64ef7c7a6232051048a6ecb). Write it as a static file for now. ## Proposed Section Structure @@ -61,7 +91,7 @@ Show the critical first step: importing presets and registering them with `regis - **Register all** -- import all category exports and register at once - **Selective registration** -- import only the categories/presets you need (for bundle size) -Based on actual source: `src/index.ts` exports 5 namespace re-exports (`entrance`, `ongoing`, `scroll`, `mouse`, `backgroundScroll`). +Based on actual source: `src/index.ts` exports 5 namespace re-exports (`entrance`, `ongoing`, `scroll`, `mouse`, `backgroundScroll`). Note: `backgroundScroll` remains re-exported at the module level for internal use but is excluded from all public documentation. ### 5. Usage with @wix/interact @@ -83,19 +113,20 @@ This is the catalog. For each category: - Full preset list (names only, as a comma-separated line) - Link to detailed reference docs -Categories: **Entrance**, **Scroll**, **Ongoing**, **Mouse**, **Background Scroll** +Categories: **Entrance**, **Scroll**, **Ongoing**, **Mouse** (Background Scroll excluded — not production ready) -Source for preset lists: +Source strategy (layered): -- Entrance, Scroll, Ongoing, Mouse: from [`rules/presets/presets-main.md`](packages/motion-presets/rules/presets/presets-main.md) -- Background Scroll: from [`src/library/backgroundScroll/index.ts`](packages/motion-presets/src/library/backgroundScroll/index.ts) +- **Which presets exist**: barrel exports (`src/library/*/index.ts`) are ground truth — not the rules files. +- **Param names, types, defaults**: TypeScript source files. When code and rules conflict on structured data, the code wins. +- **Verbal descriptions, atmosphere tables, selection guidance**: `[presets-main.md](packages/motion-presets/rules/presets/presets-main.md)` and the category rule files. This prose has no equivalent in the code — use it as-is, and log any structural mismatches found for Phase 2 correction. ### 8. Choosing a Preset Brief guidance section: - "Choose by intent" table mapping intents (reveal, attention, parallax, pointer tracking, background media) to recommended categories and example presets -- Link to the full "Selection by Atmosphere" guide in [`presets-main.md`](packages/motion-presets/rules/presets/presets-main.md) +- Link to the full "Selection by Atmosphere" guide in `[presets-main.md](packages/motion-presets/rules/presets/presets-main.md)` ### 9. Parameter Conventions @@ -114,11 +145,23 @@ Concise section noting: - Reduced-motion fallback table (subset) - Link to full accessibility guidance in `presets-main.md` -### 11. AI / Agent Support +### 11. AI & Agent Support + +Match the pattern used in the other package READMEs: list rule files with one-line descriptions, then generation constraints. + +**Rules files** ship with the package under `[rules/presets/](packages/motion-presets/rules/presets/)`: + +- `[presets-main.md](packages/motion-presets/rules/presets/presets-main.md)` — overview, parameter standards, atmosphere guide, accessibility +- `[entrance-presets.md](packages/motion-presets/rules/presets/entrance-presets.md)` — entrance preset parameters +- `[scroll-presets.md](packages/motion-presets/rules/presets/scroll-presets.md)` — scroll preset parameters +- `[ongoing-presets.md](packages/motion-presets/rules/presets/ongoing-presets.md)` — ongoing preset parameters +- `[mouse-presets.md](packages/motion-presets/rules/presets/mouse-presets.md)` — mouse preset parameters -- Link to [`rules/presets/presets-main.md`](packages/motion-presets/rules/presets/presets-main.md) and per-category rule files -- Note: rely on preset defaults when unsure -- Note: presets are JSON-serializable config objects +**Generation constraints** for agents: + +- Use only the registered preset names listed in this README as `namedEffect.type` values — do not invent types. +- When uncertain about a preset's parameters, omit them — the defaults will apply. +- Presets are JSON-serializable config objects. ### 12. Related Packages @@ -127,7 +170,7 @@ Concise section noting: ### 13. License -MIT (from [`package.json`](packages/motion-presets/package.json)). +MIT (from `[package.json](packages/motion-presets/package.json)`). ## Style Guidelines (from Specs) @@ -139,4 +182,77 @@ MIT (from [`package.json`](packages/motion-presets/package.json)). ## Discrepancy Notes -The existing [`docs/presets/README.md`](packages/motion-presets/docs/presets/README.md) claims "82+ presets", "16 ongoing", and "12 mouse" -- these counts are inaccurate vs. the source and rules. The new README will use verified counts (73 total: 19 entrance + 19 scroll + 14 ongoing + 9 mouse + 12 background-scroll). This discrepancy should be noted but fixing the docs README is out of scope for this task. +**Docs README:** The existing `[docs/presets/README.md](packages/motion-presets/docs/presets/README.md)` claims "82+ presets", "16 ongoing", and "12 mouse" — these counts are inaccurate. The Background Scroll section was removed from `docs/presets/README.md` as part of the not-production-ready exclusion work. Remaining count inaccuracies ("82+", "16 ongoing", "12 mouse") are pre-existing and out of scope. + +**Ground-truth counts (current):** 62 total: 19 entrance + 19 scroll + 13 ongoing + 11 mouse. DVD and all 12 background-scroll presets are excluded as not production ready. + +**Known param discrepancies (resolved during verify-examples):** + +- `ParallaxScroll`: the param is `parallaxFactor` (not `speed`) — critical, would break integrations. +- `ArcIn`: default direction is `'right'` (not `'bottom'`). +- `Pulse`: intensity default is `0` (not `1.0`). +- Angle convention: `0° = right` — `presets-main.md` documents this correctly; `_template.md` may differ. Code is authoritative. +- `TurnScroll.rotation` and `ParallaxScroll.range`: typed in source but unused at runtime — do not document them as functional parameters. + +## Phase 2: Fix Rules Files + +After the README is complete, the research done during preparation will have surfaced discrepancies between source code and `rules/presets/`. Phase 2 corrects those files. + +**Known items to address (seed list — extend with anything found during Phase 1):** + +- `mouse-presets.md`: Add BounceMouse and SpinMouse entries (see `phase2-mouse-rules` todo). ✅ Done. +- `presets-main.md`: Update mouse count from 9 to 11; update ongoing count and total to reflect exclusions. ✅ Done (ongoing 13, total 62). +- Any param name / default mismatches found during the `verify-examples` step. +- Add `"rules"` and `"docs"` to `packages/motion-presets/package.json` `"files"` array (see `phase2-npm-publish` todo) — currently only `dist` is shipped; adding rules enables local agent access via `node_modules/@wix/motion-presets/rules/`. + +Phase 2 is a separate task. Do not attempt it during README preparation. + +## Phase 3: Extend llms.txt and llms-full.txt + +Once Phase 2 is complete and the rules files are accurate, incorporate the preset rules into the existing `llms.txt` / `llms-full.txt` generation. There is no separate llms.txt for `@wix/motion-presets` — the one docs site (`wix.github.io/interact`) is the canonical home for all packages in this monorepo, and the two packages are always installed together. + +### What to change in `scripts/generate-llms.mjs` + +The script currently only reads `packages/interact/rules/`. It needs to: + +1. Also read `packages/motion-presets/rules/presets/` and load those 5 files. +2. Route `presets-main.md` into the `## Docs` section (below `full-lean.md` and `integration.md`), using a display title like `"Presets Reference"`. +3. Route the 4 category files (`entrance-presets.md`, `scroll-presets.md`, `ongoing-presets.md`, `mouse-presets.md`) into a new `**## Presets`\*\* section inserted between `## Docs` and `## Optional`. +4. Include all 5 preset files in the `llms-full.txt` concatenation (after the interact files). + +### Resulting `llms.txt` structure + +```markdown +# @wix/interact + +> ... + +- Install: ... + +## Docs + +- [Full Reference](...full-lean.md): ... +- [Integration Guide](...integration.md): ... +- [Presets Reference](...presets-main.md): ... ← new + +## Presets + +- [Entrance Presets](...entrance-presets.md): ... ← new +- [Scroll Presets](...scroll-presets.md): ... ← new +- [Ongoing Presets](...ongoing-presets.md): ... ← new +- [Mouse Presets](...mouse-presets.md): ... ← new + +## Optional + +- [Click Trigger Rules...](...click.md): ... +- ... +- [All rules in one file](...llms-full.txt): ... +``` + +### Size impact + +Current `llms-full.txt`: ~2,141 lines. The 5 preset files add ~1,614 lines, bringing the total to ~3,755 lines — well within modern context window limits. + +### Timing + +Do this after Phase 2 (so the rules files being added are already accurate). The [llms-txt plan](.cursor/plans/llms-txt_web_presence_c57a751b.plan.md) is fully complete — the generation script, workflow deployment, and npm packaging are all in place. Phase 3 only needs to extend the existing script. diff --git a/apps/playground/src/components/inspector/pg-named-effect-picker.ts b/apps/playground/src/components/inspector/pg-named-effect-picker.ts index 88c304dc..0dc0dfeb 100644 --- a/apps/playground/src/components/inspector/pg-named-effect-picker.ts +++ b/apps/playground/src/components/inspector/pg-named-effect-picker.ts @@ -24,7 +24,7 @@ interface OptionDef { min?: number; max?: number; step?: number; - defaultValue?: string | number | boolean | { value: number; type: string }; + defaultValue?: string | number | boolean | { value: number; unit: string }; units?: string[]; } @@ -42,7 +42,7 @@ const PRESET_OPTIONS: Record = { name: 'depth', label: 'Depth', type: 'unit-value', - defaultValue: { value: 200, type: 'px' }, + defaultValue: { value: 200, unit: 'px' }, step: 10, }, { @@ -97,7 +97,7 @@ const PRESET_OPTIONS: Record = { name: 'depth', label: 'Depth', type: 'unit-value', - defaultValue: { value: 300, type: 'px' }, + defaultValue: { value: 300, unit: 'px' }, step: 10, }, { @@ -142,7 +142,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 120, type: 'percentage' }, + defaultValue: { value: 120, unit: 'percentage' }, step: 10, }, ], @@ -221,7 +221,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 100, type: 'percentage' }, + defaultValue: { value: 100, unit: 'percentage' }, step: 10, }, ], @@ -313,7 +313,7 @@ const PRESET_OPTIONS: Record = { name: 'depth', label: 'Depth', type: 'unit-value', - defaultValue: { value: 200, type: 'px' }, + defaultValue: { value: 200, unit: 'px' }, step: 10, }, { @@ -377,7 +377,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 25, type: 'px' }, + defaultValue: { value: 25, unit: 'px' }, step: 5, }, { @@ -713,7 +713,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 400, type: 'px' }, + defaultValue: { value: 400, unit: 'px' }, step: 10, }, ], @@ -729,7 +729,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 400, type: 'px' }, + defaultValue: { value: 400, unit: 'px' }, step: 10, }, { name: 'startFromOffScreen', label: 'Start Off-Screen', type: 'boolean', defaultValue: true }, @@ -939,7 +939,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 200, type: 'px' }, + defaultValue: { value: 200, unit: 'px' }, step: 10, }, { @@ -959,7 +959,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 200, type: 'px' }, + defaultValue: { value: 200, unit: 'px' }, step: 10, }, { @@ -978,7 +978,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 80, type: 'px' }, + defaultValue: { value: 80, unit: 'px' }, step: 10, }, { @@ -1016,7 +1016,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 80, type: 'px' }, + defaultValue: { value: 80, unit: 'px' }, step: 10, }, { name: 'scale', label: 'Scale', type: 'number', min: 0, max: 5, step: 0.1, defaultValue: 1.4 }, @@ -1028,7 +1028,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 200, type: 'px' }, + defaultValue: { value: 200, unit: 'px' }, step: 10, }, { @@ -1097,7 +1097,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 200, type: 'px' }, + defaultValue: { value: 200, unit: 'px' }, step: 10, }, { @@ -1126,7 +1126,7 @@ const PRESET_OPTIONS: Record = { name: 'distance', label: 'Distance', type: 'unit-value', - defaultValue: { value: 200, type: 'px' }, + defaultValue: { value: 200, unit: 'px' }, step: 10, }, { name: 'axis', label: 'Axis', type: 'select', options: MOUSE_AXIS, defaultValue: 'both' }, @@ -1309,11 +1309,11 @@ export class PgNamedEffectPicker extends BaseComponent { if (def.type === 'unit-value') { const current = this._currentOptions[def.name] as - | { value?: number; type?: string } + | { value?: number; unit?: string } | undefined; - const defaults = def.defaultValue as { value: number; type: string } | undefined; + const defaults = def.defaultValue as { value: number; unit: string } | undefined; const numVal = current?.value ?? defaults?.value ?? 0; - const unitVal = current?.type ?? defaults?.type ?? 'px'; + const unitVal = current?.unit ?? defaults?.unit ?? 'px'; const units = def.units ?? UNIT_OPTIONS; const unitOpts = units .map( @@ -1421,16 +1421,16 @@ export class PgNamedEffectPicker extends BaseComponent { const handler = () => { const presetDefs = PRESET_OPTIONS[this._currentPreset]; const def = presetDefs?.find((d) => d.name === optName); - const defaults = def?.defaultValue as { value: number; type: string } | undefined; - const current = (this._currentOptions[optName] as { value?: number; type?: string }) ?? {}; + const defaults = def?.defaultValue as { value: number; unit: string } | undefined; + const current = (this._currentOptions[optName] as { value?: number; unit?: string }) ?? {}; const merged = { value: current.value ?? defaults?.value ?? 0, - type: current.type ?? defaults?.type ?? 'px', + unit: current.unit ?? defaults?.unit ?? 'px', }; if (part === 'value') { merged.value = parseFloat((el as HTMLInputElement).value) || 0; } else { - merged.type = (el as HTMLSelectElement).value; + merged.unit = (el as HTMLSelectElement).value; } this._currentOptions[optName] = merged; this._emitChange(); diff --git a/apps/website/assets/examples/basic/scroll.html b/apps/website/assets/examples/basic/scroll.html index 74da94a9..79aed195 100644 --- a/apps/website/assets/examples/basic/scroll.html +++ b/apps/website/assets/examples/basic/scroll.html @@ -80,8 +80,8 @@ import { Interact } from '../../lib/interact/es/web.js'; const r = { - rangeStart: { name: 'cover', offset: { value: 0, type: 'percentage' } }, - rangeEnd: { name: 'cover', offset: { value: 100, type: 'percentage' } }, + rangeStart: { name: 'cover', offset: { value: 0, unit: 'percentage' } }, + rangeEnd: { name: 'cover', offset: { value: 100, unit: 'percentage' } }, }; Interact.create({ diff --git a/packages/motion-presets/README.md b/packages/motion-presets/README.md new file mode 100644 index 00000000..b8dbbea0 --- /dev/null +++ b/packages/motion-presets/README.md @@ -0,0 +1,267 @@ + + +# @wix/motion-presets + +Ready-made animation presets for @wix/motion — entrance, scroll, pointer, loop, and background effects. + +[![npm version](https://img.shields.io/npm/v/@wix/motion-presets.svg)](https://www.npmjs.com/package/@wix/motion-presets) +[![bundle size](https://img.shields.io/bundlephobia/minzip/@wix/motion-presets)](https://bundlephobia.com/package/@wix/motion-presets) +[![license](https://img.shields.io/npm/l/@wix/motion-presets.svg)](https://github.com/wix/interact/blob/master/LICENSE) + +## What's Included + +62 ready-made animation presets across 4 categories: + +| Category | Count | Description | +| --------------------- | ----- | ---------------------------------------------- | +| [Entrance](#entrance) | 19 | Play once when an element enters the viewport | +| [Scroll](#scroll) | 19 | Progress tied to the element's scroll position | +| [Ongoing](#ongoing) | 13 | Continuous looping animations | +| [Mouse](#mouse) | 11 | Real-time response to cursor position | + +## Install + +```bash +npm install @wix/motion-presets +``` + +`@wix/motion` is included as a dependency — no separate install needed. + +## Quick Start — Registration + +Presets are passive modules. Register them with `registerEffects()` from `@wix/motion` before calling `getWebAnimation()`, `getScrubScene()`, or `generate()`. + +### Register all presets + +```typescript +import { registerEffects } from '@wix/motion'; +import * as presets from '@wix/motion-presets'; + +registerEffects(presets); +``` + +### Register selectively + +Import only the presets you use to keep your bundle smaller: + +```typescript +import { registerEffects } from '@wix/motion'; +import { FadeIn, SlideIn, ParallaxScroll } from '@wix/motion-presets'; + +registerEffects({ FadeIn, SlideIn, ParallaxScroll }); +``` + +## Usage with @wix/interact + +Pass a `namedEffect` to any effect in an [`@wix/interact`](https://github.com/wix/interact/tree/master/packages/interact) config. Call `registerEffects()` before `generate()` and `Interact.create()`. + +```typescript +import { Interact, generate } from '@wix/interact/web'; +import * as presets from '@wix/motion-presets'; + +Interact.registerEffects(presets); + +const config = { + interactions: [ + { + key: 'hero', + trigger: 'viewEnter', + effects: [{ effectId: 'fade-in' }], + }, + ], + effects: { + 'fade-in': { + duration: 800, + easing: 'ease-out', + namedEffect: { type: 'FadeIn' }, + triggerType: 'once', + }, + }, +}; + +const css = generate(config, true); +const instance = Interact.create(config); +``` + +## Usage with @wix/motion + +### Time-based entrance + +```typescript +import { getWebAnimation, registerEffects } from '@wix/motion'; +import * as presets from '@wix/motion-presets'; + +registerEffects(presets); + +const animation = getWebAnimation(document.getElementById('hero'), { + namedEffect: { type: 'FadeIn' }, + duration: 800, + easing: 'ease-out', +}); + +animation.play(); +``` + +### Scroll-driven + +```typescript +import { getScrubScene, registerEffects } from '@wix/motion'; +import * as presets from '@wix/motion-presets'; + +registerEffects(presets); + +const scrollRoot = document.getElementById('scroll-root')!; + +const scenes = getScrubScene( + document.getElementById('card'), + { + namedEffect: { type: 'FadeScroll' }, + startOffset: { name: 'cover', offset: { value: 0, unit: 'percentage' } }, + endOffset: { name: 'cover', offset: { value: 100, unit: 'percentage' } }, + fill: 'both', + easing: 'linear', + }, + { trigger: 'view-progress', element: scrollRoot }, +); +``` + +## Preset Categories + +### Entrance + +Animations optimized for when an element enters the viewport. Used with the `viewEnter` trigger (intersection observer), but can be wired to any trigger. + +**Presets (19):** ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FadeIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn + +→ [Entrance Preset Reference](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/entrance-presets.md) + +### Scroll + +Animations driven by an element's scroll progress through the viewport via ViewTimeline. Used with the `viewProgress` trigger. + +**Presets (19):** ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll + +→ [Scroll Preset Reference](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/scroll-presets.md) + +### Ongoing + +Continuous looping animations that run indefinitely until stopped. Used with any trigger — typically `viewEnter` or `hover`. + +**Presets (13):** Bounce, Breathe, Cross, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle + +→ [Ongoing Preset Reference](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/ongoing-presets.md) + +### Mouse + +Animations driven by pointer position in real time. Transform values respond to the cursor's `(x, y)` coordinates. Used with the `pointerMove` trigger. + +> Mouse presets may behave differently on touch devices. + +**Presets (11):** AiryMouse, BlobMouse, BlurMouse, BounceMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse + +→ [Mouse Preset Reference](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/mouse-presets.md) + +## Choosing a Preset + +| Intent | Category | Example Presets | +| ---------------------------- | -------- | -------------------------------------- | +| Reveal content on scroll | Entrance | FadeIn, SlideIn, FloatIn | +| Animate through the viewport | Scroll | FadeScroll, ParallaxScroll, MoveScroll | +| Draw continuous attention | Ongoing | Pulse, Breathe, Wiggle | +| Respond to cursor position | Mouse | TrackMouse, Tilt3DMouse, BlurMouse | + +For selection by tone and atmosphere (playful, elegant, bold, soft, dramatic, modern, etc.), see the [Selection by Atmosphere](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/presets-main.md#selection-by-atmosphere) guide. + +## Parameter Conventions + +### `direction` + +The `direction` parameter accepts different value sets depending on the preset: + +| Values | Example Presets | +| ---------------------------------------- | ----------------------------------------------------------------------- | +| `'top' \| 'right' \| 'bottom' \| 'left'` | SlideIn, FloatIn, FlipIn, FoldIn | +| `'horizontal' \| 'vertical'` | WinkIn, ArcScroll, FlipScroll, Flip | +| `'clockwise' \| 'counter-clockwise'` | SpinIn, SpinScroll, Spin | +| `0–360` (degrees, number) | GlideIn, ExpandIn, MoveScroll | +| Corner values | TurnIn (`'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`) | + +**Angle convention:** `0° = right (east)`, angles increase counter-clockwise. + +### Distance units + +Prefer the `{ value, unit }` object notation: + +```typescript +namedEffect: { + type: 'GlideIn', + distance: { value: 120, unit: 'px' }, +} +``` + +Supported units: `px`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax`, `percentage`. + +### `iterationDelay` (ongoing only) + +Adds an idle pause between loop cycles. Set on the `namedEffect`: + +```typescript +namedEffect: { type: 'Bounce', iterationDelay: 1000 } // 1 s pause after each cycle +``` + +Available on all ongoing presets. + +For full parameter standards and the coordinate system reference, see [Parameter Standards](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/presets-main.md#parameter-standards) in `presets-main.md`. + +## Accessibility + +Interact's `conditions` system lets you define media-query gates. Define a condition for `(prefers-reduced-motion: reduce)` and attach it to interactions or effects that use high-risk presets — when the query matches, those effects are skipped or replaced with safer alternatives. + +See [Accessibility](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/presets-main.md#accessibility) in `presets-main.md` for full guidance and LLM principles. + +### Preset risk levels + +| Risk | Presets | +| ---------- | --------------------------------------------------------------------------------------------------------------------- | +| High | SpinIn, Spin, BounceIn, Bounce, ArcIn, ArcScroll, FlipIn, FlipScroll, Spin3dScroll, Tilt3DMouse, Flash, Jello, Wiggle | +| Medium | TurnIn, ParallaxScroll (at high speed values) | +| Low / safe | FadeIn, FadeScroll, BlurIn, BlurScroll, Pulse, Breathe | + +### Reduced-motion fallbacks (subset) + +| Original | Fallback | +| --------------------- | ------------------------- | +| BounceIn, SpinIn | FadeIn | +| ArcIn, FlipIn, TurnIn | FadeIn | +| Spin, Bounce, Wiggle | Stop or subtle Pulse | +| Flash | Reduce frequency (<3/sec) | +| ParallaxScroll | Static position | +| All mouse presets | Static state | + +## AI & Agent Support + +**Rules files** ship with the package under [`rules/presets/`](https://github.com/wix/interact/tree/master/packages/motion-presets/rules/presets) — point your agent at them: + +| File | Contents | +| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | +| [`presets-main.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/presets-main.md) | Overview, parameter standards, atmosphere guide, accessibility | +| [`entrance-presets.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/entrance-presets.md) | Entrance preset parameters and defaults | +| [`scroll-presets.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/scroll-presets.md) | Scroll preset parameters and defaults | +| [`ongoing-presets.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/ongoing-presets.md) | Ongoing preset parameters and defaults | +| [`mouse-presets.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/mouse-presets.md) | Mouse preset parameters and defaults | + +**Generation constraints** for agents: + +- Use only the preset names listed in this README as `namedEffect.type` values — do not invent types. +- When uncertain about a preset's parameters, omit them — the defaults will apply. +- Always call `registerEffects()` before `generate()` and `Interact.create()` (or before `getWebAnimation()`/`getScrubScene()`) when using `namedEffect`. +- Presets are JSON-serializable config objects. + +## Related Packages + +- [`@wix/motion`](https://github.com/wix/interact/tree/master/packages/motion) — the animation engine; provides `registerEffects()`, `getWebAnimation()`, and `getScrubScene()` +- [`@wix/interact`](https://github.com/wix/interact/tree/master/packages/interact) — declarative interaction layer; the recommended way to use presets in production + +## License + +[MIT](https://github.com/wix/interact/blob/master/LICENSE) diff --git a/packages/motion-presets/docs/presets/README.md b/packages/motion-presets/docs/presets/README.md index 683878b4..46bad520 100644 --- a/packages/motion-presets/docs/presets/README.md +++ b/packages/motion-presets/docs/presets/README.md @@ -28,12 +28,6 @@ Interactive pointer-driven effects. **Featured Presets**: [TrackMouse](mouse/track-mouse.md) • [Tilt3DMouse](mouse/tilt-3d-mouse.md) • [ScaleMouse](mouse/scale-mouse.md) • [BlurMouse](mouse/blur-mouse.md) -### 🖼️ [Background Scroll Animations](background-scroll/) (12 presets) - -Specialized effects for background media elements. - -**Featured Presets**: [BgParallax](background-scroll/bg-parallax.md) • [BgZoom](background-scroll/bg-zoom.md) • [BgFade](background-scroll/bg-fade.md) • [BgFake3D](background-scroll/bg-fake-3d.md) - ## 🔍 Quick Reference ### By Complexity diff --git a/packages/motion-presets/docs/presets/background-scroll/README.md b/packages/motion-presets/docs/presets/background-scroll/README.md index 099ee02d..2db91bf7 100644 --- a/packages/motion-presets/docs/presets/background-scroll/README.md +++ b/packages/motion-presets/docs/presets/background-scroll/README.md @@ -1,3 +1,5 @@ +> **NOT PRODUCTION READY** — Background-scroll presets are experimental and not available in production builds. Do not use them in production code or reference them in user-facing documentation. + # Background Scroll Animations Specialized effects designed for background media elements and hero sections. Perfect for creating immersive backgrounds, parallax landscapes, and cinematic scroll experiences. diff --git a/packages/motion-presets/docs/presets/ongoing/README.md b/packages/motion-presets/docs/presets/ongoing/README.md index 41ac663e..3848fe1d 100644 --- a/packages/motion-presets/docs/presets/ongoing/README.md +++ b/packages/motion-presets/docs/presets/ongoing/README.md @@ -2,7 +2,7 @@ Time-based looping animations designed to create continuous movement and draw user attention. Perfect for call-to-action emphasis, loading states, and ambient motion. -## Complete Preset List (16 presets) +## Complete Preset List (15 presets) ### 💓 Rhythmic Scaling @@ -42,13 +42,6 @@ Time-based looping animations designed to create continuous movement and draw us | --------------------- | ---------- | ----------------------- | | **[Flash](flash.md)** | Simple | Opacity blinking effect | -### 🎪 Special Effects (Experimental) - -| Animation | Complexity | Description | Status | -| --------------------- | ---------- | ------------------------- | ----------- | -| **[Blink](blink.md)** | Complex | Random blinking teleport | ⚠️ Disabled | -| **[DVD](dvd.md)** | Medium | Bouncing corner-to-corner | ⚠️ Disabled | - _Note: Experimental animations are currently disabled in production but available in development environments._ ## Quick Reference @@ -90,10 +83,6 @@ _Note: Experimental animations are currently disabled in production but availabl - Breathe, Flash, Cross -#### Experimental - -- Blink, DVD (disabled in production) - ### By Performance #### Lightweight (GPU Optimized) diff --git a/packages/motion-presets/rules/presets/entrance-presets.md b/packages/motion-presets/rules/presets/entrance-presets.md index 49517cf1..18bffda6 100644 --- a/packages/motion-presets/rules/presets/entrance-presets.md +++ b/packages/motion-presets/rules/presets/entrance-presets.md @@ -195,7 +195,7 @@ Parameters: - `distance`: UnitLengthPercentage | 'top' | 'right' | 'bottom' | 'left' — travel distance or edge keyword (default: `{ value: 100, unit: 'percentage' }`) ```typescript -{ type: 'GlideIn', direction: 270, distance: { value: 200, type: 'px' } } +{ type: 'GlideIn', direction: 270, distance: { value: 200, unit: 'px' } } ``` --- diff --git a/packages/motion-presets/rules/presets/mouse-presets.md b/packages/motion-presets/rules/presets/mouse-presets.md index 865b40de..e6e15ae5 100644 --- a/packages/motion-presets/rules/presets/mouse-presets.md +++ b/packages/motion-presets/rules/presets/mouse-presets.md @@ -1,6 +1,6 @@ --- name: mouse-presets -description: Full parameter reference for mouse motion presets. Read when configuring AiryMouse, BlobMouse, BlurMouse, ScaleMouse, SkewMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, or TrackMouse pointer-driven animations. +description: Full parameter reference for mouse motion presets. Read when configuring AiryMouse, BlobMouse, BlurMouse, BounceMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, or TrackMouse pointer-driven animations. --- # Mouse Presets @@ -15,8 +15,10 @@ Mouse presets drive element transforms in real-time based on pointer position. T - [AiryMouse](#airymouse) - [BlobMouse](#blobmouse) - [BlurMouse](#blurmouse) +- [BounceMouse](#bouncemouse) - [ScaleMouse](#scalemouse) - [SkewMouse](#skewmouse) +- [SpinMouse](#spinmouse) - [SwivelMouse](#swivelmouse) - [Tilt3DMouse](#tilt3dmouse) - [Track3DMouse](#track3dmouse) @@ -51,7 +53,7 @@ Parameters: - `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) ```typescript -{ type: 'AiryMouse', angle: 50, distance: { value: 150, type: 'px' } } +{ type: 'AiryMouse', angle: 50, distance: { value: 150, unit: 'px' } } ``` --- @@ -67,7 +69,7 @@ Parameters: - `scale`: number — max scale at edges (default: `1.4`) ```typescript -{ type: 'BlobMouse', scale: 2, distance: { value: 100, type: 'px' } } +{ type: 'BlobMouse', scale: 2, distance: { value: 100, unit: 'px' } } ``` --- @@ -91,6 +93,22 @@ Parameters: --- +### BounceMouse + +Visual: Element follows the cursor like TrackMouse but with elastic easing — the element snaps to the cursor position with a springy bounce rather than following linearly. + +Parameters: + +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 80, unit: 'px' }`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) + +```typescript +{ type: 'BounceMouse', distance: { value: 120, unit: 'px' } } +``` + +--- + ### ScaleMouse Visual: Element translates and scales uniformly following the cursor. @@ -125,6 +143,21 @@ Parameters: --- +### SpinMouse + +Visual: Element rotates in response to cursor direction — the rotation angle is derived from the angle between the element's center and the cursor position, so the element always "points toward" the cursor. + +Parameters: + +- `inverted`: boolean (default: `false`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) + +```typescript +{ type: 'SpinMouse', axis: 'horizontal' } +``` + +--- + ### SwivelMouse Visual: Element tilts in 3D around a chosen pivot axis following the cursor. @@ -171,7 +204,7 @@ Parameters: - `perspective`: number — 3D perspective in px (default: `800`) ```typescript -{ type: 'Track3DMouse', angle: 15, distance: { value: 100, type: 'px' } } +{ type: 'Track3DMouse', angle: 15, distance: { value: 100, unit: 'px' } } ``` --- @@ -187,7 +220,7 @@ Parameters: - `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) ```typescript -{ type: 'TrackMouse', distance: { value: 100, type: 'px' }, axis: 'vertical' } +{ type: 'TrackMouse', distance: { value: 100, unit: 'px' }, axis: 'vertical' } ``` --- @@ -201,6 +234,7 @@ Tested values for different intensity levels. When a user asks for "soft", "subt | AiryMouse | angle | 10° | 50° | 85° | | BlobMouse | scale | 1.2 | 1.6 | 2.4 | | BlurMouse | angle, scale | 0°, 1 | 25°, 0.7 | 65°, 0.25 | +| BounceMouse | distance | 40px | 80px | 200px | | ScaleMouse (down) | scale | 0.85 | 0.5 | 0 | | ScaleMouse (up) | scale | 1.2 | 1.6 | 2.4 | | SkewMouse | angle | 10° | 20° | 45° | diff --git a/packages/motion-presets/rules/presets/ongoing-presets.md b/packages/motion-presets/rules/presets/ongoing-presets.md index b6ab8288..3219ba03 100644 --- a/packages/motion-presets/rules/presets/ongoing-presets.md +++ b/packages/motion-presets/rules/presets/ongoing-presets.md @@ -1,6 +1,6 @@ --- name: ongoing-presets -description: Full parameter reference for ongoing motion presets. Read when configuring Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, or Wiggle continuous loop animations. +description: Full parameter reference for ongoing motion presets. Read when configuring Bounce, Breathe, Cross, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, or Wiggle continuous loop animations. --- # Ongoing Presets @@ -12,7 +12,6 @@ Ongoing presets run as continuous, looping animations. They repeat indefinitely - [Bounce](#bounce) - [Breathe](#breathe) - [Cross](#cross) -- [DVD](#dvd) - [Flash](#flash) - [Flip](#flip) - [Fold](#fold) @@ -54,7 +53,7 @@ Parameters: - `iterationDelay`: number — idle time in ms after each iteration cycle (default: `0`) ```typescript -{ type: 'Breathe', direction: 'horizontal', distance: { value: 15, type: 'px' } } +{ type: 'Breathe', direction: 'horizontal', distance: { value: 15, unit: 'px' } } ``` --- @@ -74,20 +73,6 @@ Parameters: --- -### DVD - -Visual: Element bounces diagonally off the viewport edges like a DVD screensaver logo. No configurable parameters — uses viewport dimensions to calculate bounce paths. - -Parameters: None. - -```typescript -{ - type: 'DVD'; -} -``` - ---- - ### Flash Visual: Element blinks by rapidly cycling opacity from visible to invisible and back. diff --git a/packages/motion-presets/rules/presets/presets-main.md b/packages/motion-presets/rules/presets/presets-main.md index 3f2c1541..b962afdb 100644 --- a/packages/motion-presets/rules/presets/presets-main.md +++ b/packages/motion-presets/rules/presets/presets-main.md @@ -71,7 +71,7 @@ These are set on the effect configuration level, not on the preset itself: **Ongoing-specific preset parameter:** -- `iterationDelay`: Idle time in ms appended after each active iteration cycle. Available on all ongoing presets except DVD. This compresses the active animation keyframes into a fraction of the total iteration duration, creating a pause between repetitions. Set on the `namedEffect`, not on the animation options. +- `iterationDelay`: Idle time in ms appended after each active iteration cycle. Available on all ongoing presets. This compresses the active animation keyframes into a fraction of the total iteration duration, creating a pause between repetitions. Set on the `namedEffect`, not on the animation options. **Scroll-specific animation options:** @@ -94,11 +94,11 @@ The `direction` parameter accepts different values depending on the preset: | Axis | 'horizontal', 'vertical' | WinkIn, ArcScroll, FlipScroll, Flip | | Axis + center | 'horizontal', 'vertical', 'center' | Breathe | | Rotation | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | -| Angle (number) | 0–360 (0° = right, 90° = top, 180° = left, 270° = bottom) | GlideIn, ExpandIn, MoveScroll | +| Angle (number) | 0–360 (0° = right, 90° = top, 180° = left, 270° = bottom) | GlideIn, ExpandIn | ### Using Units -Interact supports both a CSSUnitValue-style object (e.g., `distance: { value: 120, type: 'px' }`, mapped to the internal type `UnitLengthPercentage`) and flat string values (e.g., `distance: '120px'`). +Interact supports both a CSSUnitValue-style object (e.g., `distance: { value: 120, unit: 'px' }`, mapped to the internal type `UnitLengthPercentage`) and flat string values (e.g., `distance: '120px'`). Prefer the object notation. Be consistent within a configuration — use one format, not both. @@ -116,9 +116,9 @@ Prefer the object notation. Be consistent within a configuration — use one for Supported unit types: `px`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax`, `percentage` ```typescript -distance: { value: 120, type: 'px' } // pixels -distance: { value: 50, type: 'percentage' } // percentage -distance: { value: 10, type: 'vh' } // viewport height +distance: { value: 120, unit: 'px' } // pixels +distance: { value: 50, unit: 'percentage' } // percentage +distance: { value: 10, unit: 'vh' } // viewport height ``` ### CSS Custom Properties @@ -141,15 +141,15 @@ ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll → [Full scroll preset reference](./scroll-presets.md) -### Ongoing (14 presets) +### Ongoing (13 presets) -Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle +Bounce, Breathe, Cross, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle → [Full ongoing preset reference](./ongoing-presets.md) -### Mouse (9 presets) +### Mouse (11 presets) -AiryMouse, BlobMouse, BlurMouse, ScaleMouse, SkewMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse +AiryMouse, BlobMouse, BlurMouse, BounceMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse → [Full mouse preset reference](./mouse-presets.md) @@ -165,7 +165,6 @@ Keywords: playful, fun, quirky, whimsical, lighthearted, bouncy, cheerful, cute, | Wiggle | loop | Wiggle | | Jello | loop | Jello | | Poke | loop | Poke | -| DVD | loop | DVD | | Cross | loop | Cross | | Spin | entrance | SpinIn | | Spin | scroll | SpinScroll | @@ -175,6 +174,7 @@ Keywords: playful, fun, quirky, whimsical, lighthearted, bouncy, cheerful, cute, | Flip | loop | Flip | | Bounce | entrance | BounceIn | | Bounce | loop | Bounce | +| Bounce | mouse | BounceMouse | | Swing | loop | Swing | | Blob | mouse | BlobMouse | | Rubber | loop | Rubber | @@ -279,6 +279,7 @@ Keywords: modern, tech, immersive, dimensional, spatial, 3d, depth, layered, inn | Track 3D | mouse | Track3DMouse | | Track | mouse | TrackMouse | | Skew | mouse | SkewMouse | +| Spin | mouse | SpinMouse | | 3D spin | scroll | Spin3dScroll | | Parallax | scroll | ParallaxScroll | | Resize | mouse | ScaleMouse | @@ -300,6 +301,7 @@ Keywords: creative, artistic, experimental, unconventional, edgy, distorted, uni | Shape | entrance | ShapeIn | | Shape | scroll | ShapeScroll | | Blob | mouse | BlobMouse | +| Spin | mouse | SpinMouse | | Cross | loop | Cross | | Stretch | scroll | StretchScroll | | Rubber | loop | Rubber | @@ -332,8 +334,8 @@ Keywords: clean, structured, organized, directional, purposeful, direct, simple, | ---------- | -------------- | ------- | ----------- | | FadeIn | FadeScroll | Flash | - | | ArcIn | ArcScroll | - | - | -| SpinIn | SpinScroll | Spin | - | -| BounceIn | - | Bounce | - | +| SpinIn | SpinScroll | Spin | SpinMouse | +| BounceIn | - | Bounce | BounceMouse | | TiltIn | TiltScroll | - | Tilt3DMouse | | FlipIn | FlipScroll | Flip | - | | FoldIn | - | Fold | - | @@ -363,7 +365,7 @@ If the host handles accessibility globally (e.g., disabling all animations on `( - Spinning: SpinIn, Spin, SpinScroll, Spin3dScroll - Bouncing: BounceIn, Bounce - 3D rotations: ArcIn, FlipIn, ArcScroll, FlipScroll, Tilt3DMouse -- Continuous motion: Flash, DVD, Jello, Wiggle +- Continuous motion: Flash, Jello, Wiggle **Medium risk** (strong motion, may affect some users): diff --git a/packages/motion-presets/rules/presets/scroll-presets.md b/packages/motion-presets/rules/presets/scroll-presets.md index 17c133ca..5f3fcf1b 100644 --- a/packages/motion-presets/rules/presets/scroll-presets.md +++ b/packages/motion-presets/rules/presets/scroll-presets.md @@ -135,7 +135,7 @@ Parameters: - `distance`: UnitLengthPercentage — travel distance (default: `{ value: 400, unit: 'px' }`) ```typescript -{ type: 'MoveScroll', angle: 90, distance: { value: 200, type: 'px' } } +{ type: 'MoveScroll', angle: 90, distance: { value: 200, unit: 'px' } } ``` --- @@ -164,7 +164,6 @@ Visual: Element moves at a different speed than the scroll, creating a depth ill Parameters: - `parallaxFactor`: number — speed multiplier relative to scroll (default: `0.5`) -- `range`: 'in' | 'out' | 'continuous' ```typescript { type: 'ParallaxScroll', parallaxFactor: 0.8 } diff --git a/packages/motion-presets/src/library/backgroundScroll/BgCloseUp.ts b/packages/motion-presets/src/library/backgroundScroll/BgCloseUp.ts index b1683ec0..24686020 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgCloseUp.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgCloseUp.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgCloseUp, DomApi, diff --git a/packages/motion-presets/src/library/backgroundScroll/BgFade.ts b/packages/motion-presets/src/library/backgroundScroll/BgFade.ts index 4c33bdf0..f6a98fec 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgFade.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgFade.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgFade, DomApi, diff --git a/packages/motion-presets/src/library/backgroundScroll/BgFadeBack.ts b/packages/motion-presets/src/library/backgroundScroll/BgFadeBack.ts index 9d9e27d2..ab1b3790 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgFadeBack.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgFadeBack.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgFadeBack, DomApi, diff --git a/packages/motion-presets/src/library/backgroundScroll/BgFake3D.ts b/packages/motion-presets/src/library/backgroundScroll/BgFake3D.ts index 08e73f4c..0ab0512d 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgFake3D.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgFake3D.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgFake3D, RangeOffset, diff --git a/packages/motion-presets/src/library/backgroundScroll/BgPan.ts b/packages/motion-presets/src/library/backgroundScroll/BgPan.ts index 7f5597d5..bc61ab71 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgPan.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgPan.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgPan, DomApi, diff --git a/packages/motion-presets/src/library/backgroundScroll/BgParallax.ts b/packages/motion-presets/src/library/backgroundScroll/BgParallax.ts index fca89556..b2bd0603 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgParallax.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgParallax.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgParallax, RangeOffset, diff --git a/packages/motion-presets/src/library/backgroundScroll/BgPullBack.ts b/packages/motion-presets/src/library/backgroundScroll/BgPullBack.ts index b272af4d..ad0f30d8 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgPullBack.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgPullBack.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgPullBack, DomApi, diff --git a/packages/motion-presets/src/library/backgroundScroll/BgReveal.ts b/packages/motion-presets/src/library/backgroundScroll/BgReveal.ts index 9a5defa0..075a6b7d 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgReveal.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgReveal.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { ScrubAnimationOptions, DomApi } from '../../types'; import { measureCompHeight } from './utils'; diff --git a/packages/motion-presets/src/library/backgroundScroll/BgRotate.ts b/packages/motion-presets/src/library/backgroundScroll/BgRotate.ts index 2497fdbb..9dee23b1 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgRotate.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgRotate.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgRotate, RangeOffset, ScrubAnimationOptions } from '../../types'; import { toKeyframeValue } from '../../utils'; diff --git a/packages/motion-presets/src/library/backgroundScroll/BgSkew.ts b/packages/motion-presets/src/library/backgroundScroll/BgSkew.ts index 0b73a838..a01f56d3 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgSkew.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgSkew.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { BgSkew, DomApi, diff --git a/packages/motion-presets/src/library/backgroundScroll/BgZoom.ts b/packages/motion-presets/src/library/backgroundScroll/BgZoom.ts index 308575ea..7a4ac7bd 100644 --- a/packages/motion-presets/src/library/backgroundScroll/BgZoom.ts +++ b/packages/motion-presets/src/library/backgroundScroll/BgZoom.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { AnimationData, BgZoom, diff --git a/packages/motion-presets/src/library/backgroundScroll/ImageParallax.ts b/packages/motion-presets/src/library/backgroundScroll/ImageParallax.ts index 8c03336d..2c78105c 100644 --- a/packages/motion-presets/src/library/backgroundScroll/ImageParallax.ts +++ b/packages/motion-presets/src/library/backgroundScroll/ImageParallax.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. import type { DomApi, ImageParallax, diff --git a/packages/motion-presets/src/library/backgroundScroll/index.ts b/packages/motion-presets/src/library/backgroundScroll/index.ts index c9e5f273..f5a1f5c8 100644 --- a/packages/motion-presets/src/library/backgroundScroll/index.ts +++ b/packages/motion-presets/src/library/backgroundScroll/index.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — background-scroll presets are experimental and excluded from public documentation. export * as BgCloseUp from './BgCloseUp'; export * as BgFade from './BgFade'; export * as BgFadeBack from './BgFadeBack'; diff --git a/packages/motion-presets/src/library/ongoing/DVD.ts b/packages/motion-presets/src/library/ongoing/DVD.ts index 27af8ec6..ceeb8739 100644 --- a/packages/motion-presets/src/library/ongoing/DVD.ts +++ b/packages/motion-presets/src/library/ongoing/DVD.ts @@ -1,3 +1,4 @@ +// NOT PRODUCTION READY — this preset is experimental and excluded from public documentation and exports. import type { TimeAnimationOptions, DomApi } from '../../types'; import { getElementOffset } from '../../utils'; diff --git a/packages/motion/docs/categories/ongoing-animations.md b/packages/motion/docs/categories/ongoing-animations.md index 45a9a29d..c0f26f00 100644 --- a/packages/motion/docs/categories/ongoing-animations.md +++ b/packages/motion/docs/categories/ongoing-animations.md @@ -54,8 +54,6 @@ Opacity, visibility, and special visual transitions. | **Fold** | Rotation | Complex | 4-way | 3D folding animation | | **Jello** | Dynamic | Medium | - | Gelatinous wobble effect | | **Cross** | Movement | Complex | 8-way | Multi-directional crossing | -| **Blink** | Visual | Complex | - | Random blinking teleport\* | -| **DVD** | Movement | Medium | - | Bouncing corner-to-corner\* | \*Currently disabled in production @@ -274,21 +272,6 @@ Many animations support directional parameters: // Quick opacity flash effect ``` -#### Blink\* (Experimental) - -**Best for**: Glitch effects, teleportation, magical elements - -```typescript -{ - type: 'Blink', - scale: 0.5, // Size variation - distance: { value: 100, unit: 'px' } // Jump distance -} -// Random position jumping with opacity flashes -``` - -\*Note: Currently disabled in production - ## Timing and Control ### Recommended Durations