@studiometa/ui-motion 2.0.0-alpha.1 → 2.0.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -80,6 +80,16 @@ Once provided, `@studiometa/ui-motion` never imports `motion` by specifier — i
80
80
 
81
81
  Heads up to [ui.studiometa.dev](https://ui.studiometa.dev/reference/items/Motion/) for the full documentation.
82
82
 
83
+ ## Agent skills
84
+
85
+ The package ships the `studiometa-ui-motion` [agent skill](https://agentskills.io). The skill teaches coding agents how to use the package, and it matches the installed version. Link the skills of your dependencies into your project with the [`skills` CLI](https://github.com/vercel-labs/skills):
86
+
87
+ ```bash
88
+ npx skills experimental_sync
89
+ ```
90
+
91
+ The command links each skill from `node_modules` into the agent folders (`.agents/skills/`, `.claude/skills/`…). When you update the package, the linked skill updates too. The command also links the `studiometa-js-toolkit` skill when your version of `@studiometa/js-toolkit` ships it.
92
+
83
93
  ## Contributing
84
94
 
85
95
  Please read the [contribution docs](https://ui.studiometa.dev/guide/contributing/).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@studiometa/ui-motion",
3
- "version": "2.0.0-alpha.1",
3
+ "version": "2.0.0-alpha.3",
4
4
  "description": "Vanilla js-toolkit components to animate elements declaratively with Motion",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -59,7 +59,8 @@
59
59
  }
60
60
  },
61
61
  "scripts": {
62
- "build": "node scripts/build.js"
62
+ "build": "node scripts/build.js && npm run build:skills",
63
+ "build:skills": "node ../../scripts/build-skills.ts"
63
64
  },
64
65
  "repository": {
65
66
  "type": "git",
@@ -89,7 +90,11 @@
89
90
  },
90
91
  "files": [
91
92
  "dist",
93
+ "skills",
92
94
  "README.md",
93
95
  "LICENSE.md"
96
+ ],
97
+ "skills": [
98
+ "npm:@studiometa/js-toolkit"
94
99
  ]
95
100
  }
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: studiometa-ui-motion
3
+ description: Animate elements declaratively with @studiometa/ui-motion v2 — Motion, MotionSequence, MotionScrollTimeline and MotionView components powered by motion.dev on @studiometa/js-toolkit v4. Use when code imports @studiometa/ui-motion, when markup uses data-component="Motion" or another Motion* component, or when a page needs keyframe, spring, gesture, sequence or scroll-driven animations.
4
+ ---
5
+
6
+ # @studiometa/ui-motion
7
+
8
+ `@studiometa/ui-motion` wraps [Motion](https://motion.dev) in components that you configure from HTML. Options are Motion keyframes and transitions written as JSON.
9
+
10
+ This skill matches the installed package version. Read the references in this folder before the online docs.
11
+
12
+ ## References
13
+
14
+ - [references/index.md](references/index.md): the items of the package.
15
+ - `references/items/Motion/`: one animation with its playback API and gestures.
16
+ - `references/items/MotionSequence/`: several `Motion` children on one timeline (`at` positions or `stagger`).
17
+ - `references/items/MotionScrollTimeline/`: animations bound to the scroll progress of a wrapper.
18
+ - `references/items/MotionView/`: DOM updates animated with Motion `animateView()`, an alternative to the `ViewTransition` component of `@studiometa/ui`.
19
+
20
+ ## Install and register
21
+
22
+ ```bash
23
+ npm install @studiometa/ui-motion motion
24
+ ```
25
+
26
+ ```js
27
+ import { registerComponent } from '@studiometa/js-toolkit';
28
+ import { Motion } from '@studiometa/ui-motion';
29
+
30
+ registerComponent(Motion);
31
+ ```
32
+
33
+ ```html
34
+ <div
35
+ data-component="Motion"
36
+ data-option-initial='{ "opacity": 0, "y": 24 }'
37
+ data-option-animate='{ "opacity": 1, "y": 0 }'
38
+ data-option-transition='{ "type": "spring", "bounce": 0.3 }'
39
+ data-option-autoplay>
40
+ Hello world!
41
+ </div>
42
+ ```
43
+
44
+ ## Rules
45
+
46
+ - Option values are JSON: quote all object keys and use single quotes around the attribute.
47
+ - Only use options that Motion supports. Read the item `js-api.md`: do not add options from other animation libraries.
48
+ - `initial` sets the start state on mount. `animate` plays only with `data-option-autoplay` or when a method starts it.
49
+ - Drive the playback with `Action`: `data-on:click="Motion->target.play()"`. The methods are `play()`, `pause()`, `reverse()`, `seek(progress)`, `stop()`, `cancel()`, `complete()` and `animate(keyframes, options)`.
50
+ - `hover`, `press` and `inView` options apply keyframes while the state holds, then revert.
51
+ - The component emits bubbling `motion-play`, `motion-pause`, `motion-complete`, `motion-cancel` and `motion-stop` events.
52
+ - In a `MotionSequence`, leave `autoplay` off on the children and set it on the sequence.
53
+
54
+ ## Loading motion
55
+
56
+ `motion` loads with a dynamic `import()` when the first animation is built. To use another entry (for example `motion/mini`), inject it once before the components mount:
57
+
58
+ ```js
59
+ import { animate } from 'motion/mini';
60
+ import { provideMotion } from '@studiometa/ui-motion';
61
+
62
+ provideMotion({ animate });
63
+ ```
64
+
65
+ ## Related skills
66
+
67
+ - `studiometa-ui`: `Action`, `Transition`, `ViewTransition` and the shared markup rules.
68
+ - `studiometa-js-toolkit`: the `Base` class and the component lifecycle.
@@ -0,0 +1,10 @@
1
+ # @studiometa/ui-motion reference
2
+
3
+ Each item folder holds `index.md` (usage), `js-api.md` or `twig-api.md` (API) and `examples.md` when the docs have them.
4
+
5
+ | Item | Kind | Summary |
6
+ | --- | --- | --- |
7
+ | [Motion](items/Motion/index.md) | component | Animate elements declaratively with Motion and drive the playback from interactions. |
8
+ | [MotionScrollTimeline](items/MotionScrollTimeline/index.md) | component | Drive the Motion children of an element with its scroll progress. |
9
+ | [MotionSequence](items/MotionSequence/index.md) | component | Compose Motion children into a single staggered animation timeline. |
10
+ | [MotionView](items/MotionView/index.md) | component | Play DOM updates as view transitions declared with Motion keyframes. |
@@ -0,0 +1,380 @@
1
+ # Examples
2
+
3
+ ## Action-driven playback
4
+
5
+ Autoplay is off by default, so the card only moves when asked to. The buttons are [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) components targeting the `Motion` instance with the arrow syntax, the hover pattern combines `play()` and `reverse()` for a symmetric in/out animation, and the last button runs a one-off spin with `animate()` — clicking Play afterwards returns to the animation declared by the options.
6
+
7
+ ```twig
8
+ <div class="grid gap-4 justify-items-start">
9
+ <div
10
+ data-component="Motion"
11
+ data-option-animate='{ "x": 160, "rotate": 10 }'
12
+ data-option-transition='{ "type": "spring", "bounce": 0.4 }'
13
+ class="px-6 py-4 rounded-lg bg-blue-400 dark:bg-blue-600 text-white font-bold">
14
+ Drive me!
15
+ </div>
16
+
17
+ <div class="flex gap-2">
18
+ <button
19
+ type="button"
20
+ data-component="Action"
21
+ data-on:click="Motion->target.play()"
22
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
23
+ Play
24
+ </button>
25
+ <button
26
+ type="button"
27
+ data-component="Action"
28
+ data-on:click="Motion->target.reverse()"
29
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
30
+ Reverse
31
+ </button>
32
+ <button
33
+ type="button"
34
+ data-component="Action"
35
+ data-on:mouseenter="Motion->target.play()"
36
+ data-on:mouseleave="Motion->target.reverse()"
37
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
38
+ Hover me
39
+ </button>
40
+ <button
41
+ type="button"
42
+ data-component="Action"
43
+ data-on:click="Motion->target.animate({ rotate: 360, x: 0 }, { duration: 1 })"
44
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
45
+ Spin back
46
+ </button>
47
+ </div>
48
+ </div>
49
+ ```
50
+
51
+ ```js
52
+ import { registerComponents } from '@studiometa/js-toolkit';
53
+ import { Action } from '@studiometa/ui';
54
+ import { Motion } from '@studiometa/ui-motion';
55
+
56
+ registerComponents(Action, Motion);
57
+ ```
58
+
59
+ ## Full playback control
60
+
61
+ Every playback method on one animation: `play()`, `pause()`, `reverse()`, `stop()`, `cancel()` and `complete()`, plus a range input scrubbing through the animation with `seek()`. Stop commits the styles the element reached, while cancel reverts it to its pre-animation styles.
62
+
63
+ ```twig
64
+ <div class="grid gap-4 justify-items-start">
65
+ <div
66
+ data-component="Motion"
67
+ data-option-animate='{ "x": 200, "rotate": 180 }'
68
+ data-option-transition='{ "duration": 2, "ease": "easeInOut" }'
69
+ class="size-16 rounded-lg bg-blue-400 dark:bg-blue-600"></div>
70
+
71
+ <div class="flex flex-wrap gap-2">
72
+ <button
73
+ type="button"
74
+ data-component="Action"
75
+ data-on:click="Motion->target.play()"
76
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
77
+ Play
78
+ </button>
79
+ <button
80
+ type="button"
81
+ data-component="Action"
82
+ data-on:click="Motion->target.pause()"
83
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
84
+ Pause
85
+ </button>
86
+ <button
87
+ type="button"
88
+ data-component="Action"
89
+ data-on:click="Motion->target.reverse()"
90
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
91
+ Reverse
92
+ </button>
93
+ <button
94
+ type="button"
95
+ data-component="Action"
96
+ data-on:click="Motion->target.stop()"
97
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
98
+ Stop
99
+ </button>
100
+ <button
101
+ type="button"
102
+ data-component="Action"
103
+ data-on:click="Motion->target.cancel()"
104
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
105
+ Cancel
106
+ </button>
107
+ <button
108
+ type="button"
109
+ data-component="Action"
110
+ data-on:click="Motion->target.complete()"
111
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
112
+ Complete
113
+ </button>
114
+ </div>
115
+
116
+ <label class="flex items-center gap-2">
117
+ Seek<input
118
+ type="range"
119
+ min="0"
120
+ max="100"
121
+ value="0"
122
+ data-component="Action"
123
+ data-on:input="Motion->target.seek(event.target.valueAsNumber / 100)" />
124
+ </label>
125
+ </div>
126
+ ```
127
+
128
+ ```js
129
+ import { registerComponents } from '@studiometa/js-toolkit';
130
+ import { Action } from '@studiometa/ui';
131
+ import { Motion } from '@studiometa/ui-motion';
132
+
133
+ registerComponents(Action, Motion);
134
+ ```
135
+
136
+ ## Reacting to events with `DataBind`
137
+
138
+ The `motion-*` events bubble, so a single routing [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) on an ancestor catches all five of them and forwards a label to a [`DataBind`](https://ui-v2.studiometa.dev/reference/items/DataBind/) in a separate subtree — the status text never shares an element with the animation.
139
+
140
+ ```twig
141
+ <div
142
+ data-component="Action"
143
+ data-on:motion-play="DataBind->target.set('playing')"
144
+ data-on:motion-pause="DataBind->target.set('paused')"
145
+ data-on:motion-complete="DataBind->target.set('complete')"
146
+ data-on:motion-stop="DataBind->target.set('stopped')"
147
+ data-on:motion-cancel="DataBind->target.set('cancelled')"
148
+ class="grid gap-4 justify-items-start">
149
+ <div
150
+ data-component="Motion"
151
+ data-option-animate='{ "x": 160 }'
152
+ data-option-transition='{ "duration": 1.5 }'
153
+ class="px-6 py-4 rounded-lg bg-blue-400 dark:bg-blue-600 text-white font-bold">
154
+ Watch my status
155
+ </div>
156
+
157
+ <div class="flex flex-wrap gap-2">
158
+ <button
159
+ type="button"
160
+ data-component="Action"
161
+ data-on:click="Motion->target.play()"
162
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
163
+ Play
164
+ </button>
165
+ <button
166
+ type="button"
167
+ data-component="Action"
168
+ data-on:click="Motion->target.pause()"
169
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
170
+ Pause
171
+ </button>
172
+ <button
173
+ type="button"
174
+ data-component="Action"
175
+ data-on:click="Motion->target.stop()"
176
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
177
+ Stop
178
+ </button>
179
+ <button
180
+ type="button"
181
+ data-component="Action"
182
+ data-on:click="Motion->target.cancel()"
183
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
184
+ Cancel
185
+ </button>
186
+ </div>
187
+
188
+ <p>
189
+ Status: <strong data-component="DataBind">idle</strong>
190
+ </p>
191
+ </div>
192
+ ```
193
+
194
+ ```js
195
+ import { registerComponents } from '@studiometa/js-toolkit';
196
+ import { Action, DataBind } from '@studiometa/ui';
197
+ import { Motion } from '@studiometa/ui-motion';
198
+
199
+ registerComponents(Action, DataBind, Motion);
200
+ ```
201
+
202
+ ## Gestures
203
+
204
+ The `hover`, `press` and `inView` options apply keyframes while their state holds, through Motion's own gesture functions: hover filters out touch emulation, press responds to pointer and keyboard alike, and in-view uses a real `IntersectionObserver`. When the state ends, a new animation plays forward to the base values of the properties the gesture touched — the base values are read from the element itself, so there is nothing to declare.
205
+
206
+ ```twig
207
+ <div class="grid gap-4 justify-items-start">
208
+ <div
209
+ data-component="Motion"
210
+ data-option-hover='{ "scale": 1.1, "rotate": -2 }'
211
+ data-option-transition='{ "type": "spring", "bounce": 0.5 }'
212
+ class="px-6 py-4 rounded-lg bg-blue-400 dark:bg-blue-600 text-white font-bold">
213
+ Hover me
214
+ </div>
215
+
216
+ <button
217
+ type="button"
218
+ data-component="Motion"
219
+ data-option-press='{ "scale": 0.9 }'
220
+ data-option-transition='{ "type": "spring", "bounce": 0.5 }'
221
+ class="px-6 py-4 rounded-lg bg-zinc-200 dark:bg-zinc-800 font-bold">
222
+ Press me (pointer or keyboard)
223
+ </button>
224
+
225
+ <p class="pt-[80vh] text-current/60">
226
+ Scroll down for the in-view reveal ↓
227
+ </p>
228
+
229
+ <div
230
+ data-component="Motion"
231
+ data-option-initial='{ "opacity": 0, "y": 32 }'
232
+ data-option-in-view='{ "opacity": 1, "y": 0 }'
233
+ data-option-in-view-amount="0.5"
234
+ data-option-transition='{ "type": "spring", "bounce": 0.3 }'
235
+ class="px-6 py-4 rounded-lg bg-emerald-400 dark:bg-emerald-600 text-white font-bold">
236
+ I reveal in view, and return when I leave
237
+ </div>
238
+
239
+ <div class="h-[40vh]"></div>
240
+ </div>
241
+ ```
242
+
243
+ ```js
244
+ import { registerComponents } from '@studiometa/js-toolkit';
245
+ import { Motion } from '@studiometa/ui-motion';
246
+
247
+ registerComponents(Motion);
248
+ ```
249
+
250
+ ## Spring entrance and exit for a `Dialog`
251
+
252
+ The [`Dialog`](https://ui-v2.studiometa.dev/reference/items/Dialog/) component handles the top layer, focus and scroll lock, and both its lifecycle events bubble, so an [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) can route them: the `open` event plays a spring entrance on the `Motion` box and the `close` event plays it in reverse — physics a CSS transition cannot express. Every closing interaction (button, backdrop, <kbd>Esc</kbd>) just calls `Dialog.close()`.
253
+
254
+ A `Motion` is not one of the dialog's [transition children](https://ui-v2.studiometa.dev/reference/items/Dialog/js-api#what-the-dialog-waits-for), so the exit would be cut off when the native dialog hides. Handing each animation to [`event.detail.waitUntil()`](https://ui-v2.studiometa.dev/reference/items/Dialog/js-api#extending-the-lifecycle-with-waituntil) is what makes the dialog wait for it.
255
+
256
+ **Guard the `detail`**
257
+
258
+ A `<dialog>` fires its own native `close` event once hidden, which carries no `detail` and shares the name. `event.detail?.waitUntil(…)` skips it — and skips the animation call with it, since an optional chain does not evaluate its arguments.
259
+
260
+ ```twig
261
+ <button
262
+ type="button"
263
+ data-component="Action"
264
+ data-on:click="Dialog(#motion-modal)->target.open()"
265
+ class="px-4 py-2 rounded bg-blue-600 text-white font-semibold">
266
+ Open dialog
267
+ </button>
268
+
269
+ {# The <dialog> host carries NO display utility, so its native open/closed
270
+ display (block / none) is preserved. The `open` event plays the box's spring
271
+ entrance and the `close` event plays it in reverse; registering each with
272
+ `detail.waitUntil()` makes the dialog await it, so the exit plays in full
273
+ before the native dialog hides.
274
+
275
+ The `?.` is not decoration: <dialog> fires its own native `close` event once
276
+ hidden, with no detail. The optional chain skips it — and skips the
277
+ `reverse()` call with it. #}
278
+ <dialog
279
+ id="motion-modal"
280
+ data-component="Action Dialog"
281
+ data-on:open="Motion(#motion-modal-box)->event.detail?.waitUntil(target.play())"
282
+ data-on:close="Motion(#motion-modal-box)->event.detail?.waitUntil(target.reverse())"
283
+ data-on:cancel.prevent="Dialog.close()"
284
+ class="fixed inset-0 m-0 p-0 w-full h-full max-w-none max-h-none bg-transparent overflow-y-auto">
285
+ <div
286
+ data-component="Action"
287
+ data-on:click="Dialog(#motion-modal)->target.close()"
288
+ class="fixed inset-0 bg-black/50"></div>
289
+
290
+ <div
291
+ class="pointer-events-none relative flex min-h-full items-center justify-center p-4">
292
+ <div
293
+ id="motion-modal-box"
294
+ data-component="Motion"
295
+ data-option-initial='{ "opacity": 0, "scale": 0.8, "y": 40 }'
296
+ data-option-animate='{ "opacity": 1, "scale": 1, "y": 0 }'
297
+ data-option-transition='{ "type": "spring", "bounce": 0.4 }'
298
+ class="pointer-events-auto relative w-full max-w-lg p-8 rounded-lg bg-white text-black shadow-2xl">
299
+ <h2 class="text-xl font-bold mb-3">Spring entrance and exit</h2>
300
+ <p class="mb-6 text-black/60">
301
+ The <code>Dialog</code> handles the top layer, focus and scroll lock; the
302
+ <code>Motion</code> box springs in on its <code>open</code> event and springs
303
+ back out before the dialog closes, which it waits for — physics a CSS transition
304
+ cannot express.
305
+ </p>
306
+ <button
307
+ type="button"
308
+ data-component="Action"
309
+ data-on:click="Dialog(#motion-modal)->target.close()"
310
+ class="px-4 py-2 rounded bg-gray-900 text-white">
311
+ Close
312
+ </button>
313
+ </div>
314
+ </div>
315
+ </dialog>
316
+
317
+ <style>
318
+ dialog::backdrop { background: transparent; }
319
+ </style>
320
+ ```
321
+
322
+ ```js
323
+ import { registerComponents } from '@studiometa/js-toolkit';
324
+ import { Action, Dialog } from '@studiometa/ui';
325
+ import { Motion } from '@studiometa/ui-motion';
326
+
327
+ registerComponents(Action, Dialog, Motion);
328
+ ```
329
+
330
+ ## Scrubbing with `TimerProgress`
331
+
332
+ A single element carries `Action`, `Motion` and [`TimerProgress`](https://ui-v2.studiometa.dev/reference/items/Timer/): the timer emits a `0 → 1` ratio on every frame, and the co-located `Action` hands it to `Motion.seek()`. The effect folds the ratio into a `0 → 1 → 0` triangle wave (`1 - Math.abs(2 * ratio - 1)`), so one timer cycle yoyos the animation out and back — a looping, pausable, restartable timeline without a line of custom JavaScript. For a plain forward loop, pass the ratio through unchanged; Motion can also yoyo on its own with `data-option-transition='{ "repeat": 10, "repeatType": "reverse" }'`, without any timer.
333
+
334
+ ```twig
335
+ <div class="grid gap-4 justify-items-start">
336
+ {# One element carries the whole engine: `TimerProgress` emits a 0 → 1 ratio
337
+ on every frame, and the co-located `Action` folds it into a 0 → 1 → 0
338
+ triangle wave before handing it to `Motion.seek()` — one 8s timer cycle
339
+ yoyos the animation out and back. #}
340
+ <div
341
+ data-component="Action Motion TimerProgress"
342
+ data-option-delay="8"
343
+ data-option-repeat
344
+ data-option-animate='{ "x": 200, "rotate": 360, "borderRadius": "50%" }'
345
+ data-on:timer-progress="Motion.seek(1 - Math.abs(2 * event.detail.ratio - 1))"
346
+ class="size-16 rounded-lg bg-blue-400 dark:bg-blue-600"></div>
347
+
348
+ <div class="flex flex-wrap gap-2">
349
+ <button
350
+ type="button"
351
+ data-component="Action"
352
+ data-on:click="TimerProgress->target.pause()"
353
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
354
+ Pause
355
+ </button>
356
+ <button
357
+ type="button"
358
+ data-component="Action"
359
+ data-on:click="TimerProgress->target.resume()"
360
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
361
+ Resume
362
+ </button>
363
+ <button
364
+ type="button"
365
+ data-component="Action"
366
+ data-on:click="TimerProgress->target.restart()"
367
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
368
+ Restart
369
+ </button>
370
+ </div>
371
+ </div>
372
+ ```
373
+
374
+ ```js
375
+ import { registerComponents } from '@studiometa/js-toolkit';
376
+ import { Action, TimerProgress } from '@studiometa/ui';
377
+ import { Motion } from '@studiometa/ui-motion';
378
+
379
+ registerComponents(Action, TimerProgress, Motion);
380
+ ```
@@ -0,0 +1,83 @@
1
+ # Motion
2
+
3
+ The `Motion` component animates its root element declaratively with the [Motion](https://motion.dev) library. Describe the animation with the `initial`, `animate` and `transition` options: the `initial` styles are applied on mount, then the `animate` keyframes play on demand — or automatically when autoplay is enabled with `data-option-autoplay`.
4
+
5
+ The component is a thin, headless playback surface exposing imperative methods that an [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) can call from any interaction: `play()` and `reverse()` always drive the animation declared by the options, while `animate()` runs a one-off to arbitrary keyframes. All its events bubble, so an ancestor `Action` can catch and route them; use the `.stop` event modifier to contain them in nested setups.
6
+
7
+ The `motion` peer dependency is resolved with a lazy `import()` the first time an animation is built, so it stays out of your main bundle until needed. See [providing the Motion dependency](js-api.md#providing-the-motion-dependency) to inject a specific build such as `motion/mini`.
8
+
9
+ `Motion` is the playback primitive of `@studiometa/ui-motion`, which also ships [`MotionScrollTimeline`](../MotionScrollTimeline/index.md) to drive a group of `Motion` children with the scroll, [`MotionSequence`](../MotionSequence/index.md) to compose them into one staggered timeline, and [`MotionView`](../MotionView/index.md) to play DOM updates as view transitions.
10
+
11
+ ## Installation
12
+
13
+ `Motion` ships in the separate `@studiometa/ui-motion` package, with [`motion`](https://motion.dev) as a peer dependency:
14
+
15
+ ```bash
16
+ npm install @studiometa/ui-motion motion
17
+ ```
18
+
19
+ Importing a module only defines the class: no component registers itself. Register the ones a page uses, or reach for the package's lazy [manifest](https://ui-v2.studiometa.dev/guide/autoloading/):
20
+
21
+ ```js
22
+ import { registerComponents } from '@studiometa/js-toolkit';
23
+ import { Motion } from '@studiometa/ui-motion';
24
+ import { Action } from '@studiometa/ui';
25
+
26
+ registerComponents(Motion, Action);
27
+ ```
28
+
29
+ ## Usage
30
+
31
+ Option values are parsed as JSON, so object keys must be quoted. The animation below plays once on mount, which a preview finishes booting before you look at it — hence the replay button, which calls `play()` to restart it:
32
+
33
+ ```twig
34
+ {# The animation plays once, on mount. A preview boots before you look at it,
35
+ so the story pairs it with a replay button: `play()` restarts the animation
36
+ from the `initial` styles, which the component folds into the keyframes as
37
+ the starting point. #}
38
+ <div class="grid justify-items-start gap-4">
39
+ <div
40
+ id="basic-box"
41
+ data-component="Motion"
42
+ data-option-initial='{ "opacity": 0, "y": 24, "scale": 0.9 }'
43
+ data-option-animate='{ "opacity": 1, "y": 0, "scale": 1 }'
44
+ data-option-transition='{ "type": "spring", "bounce": 0.3, "duration": 0.8 }'
45
+ data-option-autoplay
46
+ class="rounded-lg bg-blue-400 px-6 py-4 font-bold text-white dark:bg-blue-600">
47
+ Hello, I animate on mount!
48
+ </div>
49
+
50
+ <button
51
+ type="button"
52
+ data-component="Action"
53
+ data-on:click="Motion(#basic-box)->target.play()"
54
+ class="rounded bg-zinc-200 px-4 py-2 dark:bg-zinc-800">
55
+ Replay
56
+ </button>
57
+ </div>
58
+ ```
59
+
60
+ ```js
61
+ import { registerComponents } from '@studiometa/js-toolkit';
62
+ import { Action } from '@studiometa/ui';
63
+ import { Motion } from '@studiometa/ui-motion';
64
+
65
+ registerComponents(Action, Motion);
66
+ ```
67
+
68
+ ## Driving the animation with `Action`
69
+
70
+ Autoplay is off by default, so the playback is yours to control from any interaction — see the [examples](examples.md) for a complete demo:
71
+
72
+ <!-- prettier-ignore-start -->
73
+ ```html
74
+ <div
75
+ data-component="Motion"
76
+ data-option-animate='{ "x": 100 }'>
77
+ …
78
+ </div>
79
+
80
+ <button data-component="Action" data-on:click="Motion->target.play()">Play</button>
81
+ <button data-component="Action" data-on:click="Motion->target.reverse()">Reverse</button>
82
+ ```
83
+ <!-- prettier-ignore-end -->