@studiometa/ui-motion 2.0.0-alpha.1 → 2.0.0-alpha.2
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 +10 -0
- package/package.json +7 -2
- package/skills/studiometa-ui-motion/SKILL.md +68 -0
- package/skills/studiometa-ui-motion/references/index.md +10 -0
- package/skills/studiometa-ui-motion/references/items/Motion/examples.md +380 -0
- package/skills/studiometa-ui-motion/references/items/Motion/index.md +83 -0
- package/skills/studiometa-ui-motion/references/items/Motion/js-api.md +230 -0
- package/skills/studiometa-ui-motion/references/items/MotionScrollTimeline/examples.md +160 -0
- package/skills/studiometa-ui-motion/references/items/MotionScrollTimeline/index.md +25 -0
- package/skills/studiometa-ui-motion/references/items/MotionScrollTimeline/js-api.md +58 -0
- package/skills/studiometa-ui-motion/references/items/MotionSequence/examples.md +143 -0
- package/skills/studiometa-ui-motion/references/items/MotionSequence/index.md +20 -0
- package/skills/studiometa-ui-motion/references/items/MotionSequence/js-api.md +36 -0
- package/skills/studiometa-ui-motion/references/items/MotionView/examples.md +151 -0
- package/skills/studiometa-ui-motion/references/items/MotionView/index.md +26 -0
- package/skills/studiometa-ui-motion/references/items/MotionView/js-api.md +149 -0
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.
|
|
3
|
+
"version": "2.0.0-alpha.2",
|
|
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 -->
|