@luna-park/plugin-motion 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# 🪄 Motion plugin for Luna Park
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Animate any element of your app** (entrances, hover effects, scroll reveals, looping details) from a single **Motion** panel in the inspector, without writing a line of animation code.
+
+Powered by [anime.js](https://animejs.com), and what you see in the editor preview is exactly what runs once deployed.
+
+## ✨ What you get
+
+| | |
+|---|---|
+| 🎬 **17 ready-made presets** | Enter, emphasis and ambient animations, one click away. |
+| 🎛️ **Custom from/to** | Animate opacity, position, scale, rotation and blur between your own values. |
+| 🎯 **7 triggers** | On mount, when visible, synced with scroll, on hover, on press, on focus, or driven by a state. |
+| 🌊 **Stagger** | Cascade the animation over children, over sibling elements (lists!), from the first, last, center or at random. |
+| 🔤 **Split text** | Animate a text letter by letter, word by word, or line by line. |
+| ♿ **Reduced motion** | Respects the visitor's `prefers-reduced-motion` setting out of the box. |
+
+## 🚀 Getting started
+
+1. In Luna Park, open **Library → Install Plugins**, search for **Motion** and install it.
+2. Select an element and open the **Motion** panel in the inspector.
+3. Pick a **trigger**, an **animation** and an **easing**. Hit **Replay** (↺) in the panel header to watch it again.
+
+## 🎬 Presets
+
+| Category | Presets | Typical use |
+|---|---|---|
+| **Enter** | `fade`, `slide-up`, `slide-down`, `slide-left`, `slide-right`, `zoom`, `blur` | Make an element appear (on mount, when scrolled into view…). |
+| **Emphasis** | `grow`, `shrink`, `lift`, `tilt` | Small feedback on interaction, best with hover, press, focus or state. |
+| **Ambient** | `pulse`, `float`, `spin`, `shake`, `blink`, `wiggle` | Loop forever to draw attention. |
+| **Custom** | `custom` | Animate from your **From** values to your **To** values (`opacity`, `x`, `y`, `scale`, `rotate`, `blur`). |
+
+## 🎯 Triggers
+
+| Trigger | Behavior |
+|---|---|
+| **On mount** | Plays as soon as the element appears. |
+| **When visible** | Plays once, the first time the element scrolls into view. |
+| **Synced with scroll** | Progress follows the scroll position while the element crosses the viewport. |
+| **On hover** | Plays when the pointer enters, rewinds when it leaves. |
+| **On press** | Plays while the element is pressed, rewinds on release. |
+| **On focus** | Plays when the element (or one of its children) gets focus, rewinds when it loses it. |
+| **From a state** | Bind **State** to a boolean: `true` plays the animation, `false` rewinds it. The initial value is applied without animating. |
+
+## 🎛️ Options
+
+| Option | What it does |
+|---|---|
+| **Duration** / **Delay** | In milliseconds. Duration falls back to the plugin default. |
+| **Easing** | `linear`, `outQuad`, `outCubic`, `outExpo`, `inOutSine`, `outBack`, `outElastic`, `outBounce`. |
+| **Loops** | Number of repetitions, `-1` for infinite. Ambient presets loop by default. |
+| **Alternate** | Play back and forth instead of restarting each loop. |
+| **Stagger** | Delay between each animated item, in milliseconds. |
+| **Stagger from** | Where the cascade starts: `first`, `center`, `last` or `random`. |
+| **Split text** | Split the element's text into `chars`, `words` or `lines` and animate each piece (with a 30 ms stagger by default). |
+
+> [!TIP]
+> **Stagger** adapts to what you put it on:
+> - On a **single element**, its children are animated one after the other. Children added later are animated too.
+> - On **repeated siblings** sharing the same motion (e.g. a list rendered from an array), the siblings cascade together. With **When visible**, they are revealed in order as they come into view.
+
+## ⚙️ Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Default duration (ms)** | `600` | Used by every animation without its own duration. |
+| **Default easing** | `outExpo` | Used by every animation without its own easing (ambient presets have their own). |
+| **Reduced motion** | `reduce` | With `reduce`, visitors who prefer reduced motion get instant transitions, no delays, and no looping or scroll-synced animations. Use `ignore` to always play everything. |
+
+## 📦 In your deployed app
+
+When you build your project:
+
+- **Runtime**: the plugin and `animejs` are added to your frontend dependencies automatically.
+- **Directive**: animated elements use the `v-motion` directive from `@luna-park/plugin-motion/runtime`.
+- **Configuration**: the plugin settings are applied when the app starts.
+
+## 🛠️ Development
+
+```bash
+pnpm install
+pnpm build      # build the plugin
+pnpm dev        # rebuild on change
+pnpm preview    # serve it to the Luna Park editor (http://127.0.0.1:2084)
+```
+
+The package ships two entries:
+
+- `@luna-park/plugin-motion`: the editor plugin (settings and Motion panel).
+- `@luna-park/plugin-motion/runtime`: the browser runtime used by the generated app (`vMotion`, `configureMotion`, `replayMotion`, `presets`).
+
+---
+
+Made with 💙 by [Luna Park](https://luna-park.app).