@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.
@@ -0,0 +1,230 @@
1
+ # JS API
2
+
3
+ Animate the component's root element with [Motion](https://motion.dev).
4
+
5
+ ## Options
6
+
7
+ Object options are parsed as JSON: quote the keys (`data-option-animate='{ "x": 100 }'`). The available keyframes and transition settings are Motion's own — see the [`animate()` documentation](https://motion.dev/docs/animate) for the full vocabulary.
8
+
9
+ ### `initial`
10
+
11
+ - Type: `DOMKeyframesDefinition`
12
+ - Default: `{}`
13
+
14
+ Styles applied to the element on mount, before anything plays. Use it to define the starting state of an enter animation without a flash of the final state. It doubles as the starting point of the [`animate`](#animate) keyframes, so the declared animation always plays from here — however many times it runs.
15
+
16
+ <!-- prettier-ignore-start -->
17
+ ```html {3}
18
+ <div
19
+ data-component="Motion"
20
+ data-option-initial='{ "opacity": 0, "y": 24 }'
21
+ data-option-animate='{ "opacity": 1, "y": 0 }'>
22
+ …
23
+ </div>
24
+ ```
25
+ <!-- prettier-ignore-end -->
26
+
27
+ ### `animate`
28
+
29
+ - Type: `DOMKeyframesDefinition`
30
+ - Default: `{}`
31
+
32
+ The target keyframes of the animation. They play on mount when [`autoplay`](#autoplay) is enabled.
33
+
34
+ Each property the [`initial`](#initial) option also describes starts from that style, so the declared animation replays identically for as long as the options stand — declare the starting state once, in `initial`:
35
+
36
+ <!-- prettier-ignore-start -->
37
+ ```html {3,4}
38
+ <div
39
+ data-component="Motion"
40
+ data-option-initial='{ "opacity": 0, "y": 24 }'
41
+ data-option-animate='{ "opacity": 1, "y": 0 }'
42
+ data-option-autoplay>
43
+ …
44
+ </div>
45
+ ```
46
+ <!-- prettier-ignore-end -->
47
+
48
+ A property `initial` says nothing about animates from whatever the element currently shows, which is what a one-off transition to a new state wants. To pin a starting point without painting it on mount, write that property as a `[from, to]` array (`{ "opacity": [0.2, 1] }`) — an explicit array is never overridden.
49
+
50
+ ### `transition`
51
+
52
+ - Type: `AnimationOptions`
53
+ - Default: `{}`
54
+
55
+ Motion's animation options: `duration`, `delay`, `ease`, `type` (`"tween"`, `"spring"`, `"inertia"`), `repeat`, spring physics, etc.
56
+
57
+ <!-- prettier-ignore-start -->
58
+ ```html {4}
59
+ <div
60
+ data-component="Motion"
61
+ data-option-animate='{ "scale": 1 }'
62
+ data-option-transition='{ "type": "spring", "bounce": 0.3 }'>
63
+ …
64
+ </div>
65
+ ```
66
+ <!-- prettier-ignore-end -->
67
+
68
+ ### `autoplay`
69
+
70
+ - Type: `boolean`
71
+ - Default: `false`
72
+
73
+ Whether the `animate` keyframes play automatically on mount. Enable it with the `data-option-autoplay` attribute; without it, playback waits for an explicit `play()`.
74
+
75
+ <!-- prettier-ignore-start -->
76
+ ```html {4}
77
+ <div
78
+ data-component="Motion"
79
+ data-option-animate='{ "x": 100 }'
80
+ data-option-autoplay>
81
+ …
82
+ </div>
83
+ ```
84
+ <!-- prettier-ignore-end -->
85
+
86
+ ### `at`
87
+
88
+ - Type: `string`
89
+ - Default: `''`
90
+
91
+ Only meaningful inside a [`MotionSequence`](../MotionSequence/index.md): this component's explicit position in the parent sequence, taking precedence over the sequence's `stagger`. A time in seconds (`"2"`), a relative offset (`"-0.2"`), or `"<"` for "with the previous segment". Ignored when the component animates on its own. See [`at` on the children](../MotionSequence/js-api.md#at-on-the-children).
92
+
93
+ ### `hover`
94
+
95
+ - Type: `DOMKeyframesDefinition`
96
+ - Default: `{}`
97
+
98
+ Keyframes applied while the element is hovered, through Motion's [`hover()`](https://motion.dev/docs/hover) — real hover only, touch emulation is filtered out. When the hover ends, a new animation plays **forward** to the base values of the properties the gesture touched, with the same [`transition`](#transition) — the same return Motion for React performs when it deactivates a `whileHover` variant. The base value of each property is read from the element once, the first time a gesture touches it, so the return never plays the easing or spring curve backward and never depends on a gesture animation still being around.
99
+
100
+ <!-- prettier-ignore-start -->
101
+ ```html {3}
102
+ <div
103
+ data-component="Motion"
104
+ data-option-hover='{ "scale": 1.1 }'>
105
+ …
106
+ </div>
107
+ ```
108
+ <!-- prettier-ignore-end -->
109
+
110
+ ### `press`
111
+
112
+ - Type: `DOMKeyframesDefinition`
113
+ - Default: `{}`
114
+
115
+ Keyframes applied while the element is pressed, through Motion's [`press()`](https://motion.dev/docs/press) — pointer and keyboard alike, so the state is accessible for free. Returns to the base values like `hover` when the press ends.
116
+
117
+ ### `inView`
118
+
119
+ - Type: `DOMKeyframesDefinition`
120
+ - Default: `{}`
121
+
122
+ Keyframes applied when the element enters the viewport, through Motion's [`inView()`](https://motion.dev/docs/inview). Returns to the base values when the element leaves, unless [`once`](#once) is set. Declaring [`initial`](#initial) is the way to choose those base values: it is applied on mount, so it is what the element holds when the first reveal reads it.
123
+
124
+ <!-- prettier-ignore-start -->
125
+ ```html {3,4}
126
+ <div
127
+ data-component="Motion"
128
+ data-option-initial='{ "opacity": 0, "y": 24 }'
129
+ data-option-in-view='{ "opacity": 1, "y": 0 }'
130
+ data-option-once>
131
+ …
132
+ </div>
133
+ ```
134
+ <!-- prettier-ignore-end -->
135
+
136
+ ### `inViewMargin`
137
+
138
+ - Type: `string`
139
+ - Default: `''`
140
+
141
+ The viewport margin for the `inView` detection, in CSS margin syntax (e.g. `"-100px"` to trigger 100px inside the viewport).
142
+
143
+ ### `inViewAmount`
144
+
145
+ - Type: `'some' | 'all' | number`
146
+ - Default: `'some'`
147
+
148
+ How much of the element must be visible to trigger `inView`: `"some"`, `"all"`, or a `0`–`1` proportion.
149
+
150
+ ### `once`
151
+
152
+ - Type: `boolean`
153
+ - Default: `false`
154
+
155
+ When set, the `inView` keyframes play once and the reached styles persist — the element is no longer watched.
156
+
157
+ **Gesture animations are transient**
158
+
159
+ The gesture options animate alongside the declared animation: they never become the [current animation](#methods) and emit no lifecycle events — and neither does the animation returning to the base values. Like `scroll()`, the gesture functions are not part of `motion/mini` — a gesture option warns and is skipped when the [provided module](#providing-the-motion-dependency) lacks its function.
160
+
161
+ ## Events
162
+
163
+ All events are dispatched as bubbling `CustomEvent`s on the component's element, so they can be listened to with [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/)'s `data-on:<event>` attribute — either on the same element or on an ancestor. Use the `.stop` modifier to contain them.
164
+
165
+ | Event | Fired when |
166
+ | ----------------- | -------------------------------------------------------------------------- |
167
+ | `motion-play` | a playback starts (`autoplay`, `play()`, `reverse()` or `animate()`). |
168
+ | `motion-pause` | the current animation is paused. |
169
+ | `motion-complete` | the current animation finishes. |
170
+ | `motion-stop` | the current animation is stopped, keeping the styles it reached. |
171
+ | `motion-cancel` | the current animation is cancelled, reverting to the pre-animation styles. |
172
+
173
+ <!-- prettier-ignore-start -->
174
+ ```html {4}
175
+ <div
176
+ data-component="Action Motion"
177
+ data-option-animate='{ "opacity": 1 }'
178
+ data-on:motion-complete="console.log('done')">
179
+ …
180
+ </div>
181
+ ```
182
+ <!-- prettier-ignore-end -->
183
+
184
+ ## Methods
185
+
186
+ The component holds a single current animation. `play()` and `reverse()` always drive the animation declared by the options — recreating it when an imperative `animate()` call superseded it — while `pause()`, `seek()`, `stop()`, `cancel()` and `complete()` act on whichever animation is current. `play()`, `reverse()` and `animate()` return a promise that resolves when the animation settles and never rejects.
187
+
188
+ | Method | Description |
189
+ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
190
+ | `play()` | Play the declared animation forward, creating it on first play. Restarts a finished animation. |
191
+ | `reverse()` | Play the declared animation backward. When nothing has played yet, it starts from its end. |
192
+ | `pause()` | Pause the current animation in place. |
193
+ | `seek(progress)` | Jump to a progress between `0` and `1`, creating the declared animation paused when nothing has played yet. |
194
+ | `animate(keyframes, options)` | Run a one-off animation to arbitrary keyframes; options are merged over `transition`. `play()` returns to the declared animation. |
195
+ | `stop()` | Stop the current animation and commit the styles reached. The next `play()` creates a fresh animation. |
196
+ | `cancel()` | Cancel the current animation and revert to the pre-animation styles. The next `play()` creates a fresh animation. |
197
+ | `complete()` | Jump the current animation to its end state. |
198
+
199
+ Methods are callable from an `Action` effect — on the same element or through the target syntax:
200
+
201
+ <!-- prettier-ignore-start -->
202
+ ```html {2,3}
203
+ <div data-component="Action" data-on:mouseenter="Motion(#logo)->target.play()"
204
+ data-on:mouseleave="Motion(#logo)->target.reverse()">
205
+ <div id="logo" data-component="Motion" data-option-animate='{ "scale": 1.2 }'>…</div>
206
+ </div>
207
+ ```
208
+ <!-- prettier-ignore-end -->
209
+
210
+ ## Getters
211
+
212
+ | Getter | Description |
213
+ | ---------- | ---------------------------------------------------------- |
214
+ | `controls` | The current Motion playback controls, or `null` when idle. |
215
+ | `time` | The current playback time in seconds. |
216
+ | `duration` | The current animation duration in seconds. |
217
+ | `progress` | The current playback progress, from `0` to `1`. |
218
+
219
+ ## Providing the Motion dependency
220
+
221
+ By default the component resolves `motion` with a lazy `import()` the first time an animation is built. To control which build is used — a specific version, the smaller `motion/mini` entry, or a module served from an import map or a CDN — inject it once with `provideMotion()` before the components mount:
222
+
223
+ ```js
224
+ import { animate } from 'motion/mini';
225
+ import { provideMotion } from '@studiometa/ui-motion';
226
+
227
+ provideMotion({ animate });
228
+ ```
229
+
230
+ Once provided, `@studiometa/ui-motion` never imports `motion` by specifier — it uses the instance you handed it. The injected value must satisfy the `MotionModule` type: the subset of the `motion` module the components consume. `resolveMotion()` is also exported to trigger (and await) resolution yourself, for example to preload the module.
@@ -0,0 +1,160 @@
1
+ # Examples
2
+
3
+ ## Scroll-driven timeline
4
+
5
+ [`MotionScrollTimeline`](js-api.md) separates the timeline from the animations: the tall section defines the scroll range, and every `Motion` inside it is driven by that progress through Motion's `scroll()` — hardware-accelerated where the browser supports `ScrollTimeline`. Keyframe arrays give each child a multi-step track across the same range, and registering the timeline is enough: it mounts its `Motion` children itself.
6
+
7
+ ```twig
8
+ <p class="py-8 text-center text-current/60">
9
+ Scroll down ↓
10
+ </p>
11
+
12
+ <section data-component="MotionScrollTimeline" class="relative h-[300vh]">
13
+ <div
14
+ class="sticky top-0 flex h-screen flex-col items-center justify-center gap-6 overflow-hidden">
15
+ <h2
16
+ data-component="Motion"
17
+ data-option-animate='{ "opacity": [0, 1, 1, 0], "y": [80, 0, 0, -80] }'
18
+ class="text-3xl font-bold">
19
+ Driven by scroll
20
+ </h2>
21
+ <div
22
+ data-component="Motion"
23
+ data-option-animate='{ "rotate": [0, 360], "scale": [0.5, 1.5], "borderRadius": ["10%", "50%"] }'
24
+ class="size-24 bg-blue-400 dark:bg-blue-600"></div>
25
+ </div>
26
+ </section>
27
+
28
+ <p class="py-8 text-center text-current/60">
29
+ Done ↑
30
+ </p>
31
+ ```
32
+
33
+ ```js
34
+ import { registerComponents } from '@studiometa/js-toolkit';
35
+ import { MotionScrollTimeline } from '@studiometa/ui-motion';
36
+
37
+ registerComponents(MotionScrollTimeline);
38
+ ```
39
+
40
+ ## Reading progress bar
41
+
42
+ The timeline element is the article, and the [`offset`](js-api.md#offset) maps progress `0` to its top reaching the top of the viewport and progress `1` to its bottom reaching the bottom — the reading range, rather than the default entering-and-leaving range. The sticky bar holds a single `Motion` child scrubbed from `scaleX: 0` to `scaleX: 1`, which is the cheap way to draw a progress indicator: the browser animates a transform instead of a width, anchored to the left edge by `origin-left`.
43
+
44
+ ```twig
45
+ {# The article itself is the timeline, and the `offset` maps progress 0 to its
46
+ top reaching the top of the viewport and progress 1 to its bottom reaching
47
+ the bottom — the reading range. The single Motion child inside the sticky
48
+ bar is scrubbed by that progress, so its scaleX track reads as the share of
49
+ the article already scrolled. #}
50
+ <section
51
+ data-component="MotionScrollTimeline"
52
+ data-option-offset='["start start", "end end"]'
53
+ class="relative">
54
+ <div class="sticky top-0 h-1.5 bg-zinc-200 dark:bg-zinc-800">
55
+ <div
56
+ data-component="Motion"
57
+ data-option-animate='{ "scaleX": [0, 1] }'
58
+ class="h-full origin-left bg-blue-500 dark:bg-blue-400"></div>
59
+ </div>
60
+
61
+ <article class="mx-auto max-w-xl px-6 py-16 flex flex-col gap-6">
62
+ <h2 class="text-3xl font-bold">Reading progress</h2>
63
+ <p>
64
+ Scroll this article: the bar above sticks to the top of the section and
65
+ fills from left to right as the content goes by. Nothing listens to the
66
+ scroll event — the timeline binds the bar to the scroll position once, on
67
+ mount.
68
+ </p>
69
+ <p>
70
+ The bar is a plain <code>Motion</code> child. It declares a single
71
+ <code>scaleX</code> track from 0 to 1, keeps its
72
+ <code>autoplay</code> off, and the timeline takes over its playback: the animation
73
+ never runs on its own clock, it is scrubbed.
74
+ </p>
75
+ <p>
76
+ Scaling is the cheap way to draw a progress bar: the browser animates a
77
+ transform instead of a width, and the
78
+ <code>origin-left</code> class anchors the growth to the left edge.
79
+ </p>
80
+ <p>
81
+ The default <code>offset</code> would start the bar as soon as the section enters
82
+ the viewport from the bottom, so the bar would already be part-filled on the
83
+ first paint. The
84
+ <code>["start start", "end end"]</code> range instead follows the section's
85
+ own scroll, which is what a reader expects from a progress indicator.
86
+ </p>
87
+ <p>
88
+ Any number of children can share the same timeline. A second
89
+ <code>Motion</code> could fade a "back to top" button in over the last part
90
+ of the range, without a single line of JavaScript.
91
+ </p>
92
+ <p>
93
+ Where the browser supports <code>ScrollTimeline</code>, the link is
94
+ hardware-accelerated and runs off the main thread; elsewhere Motion falls
95
+ back to a scroll listener with the same result.
96
+ </p>
97
+ <p>
98
+ The link is released when the timeline is destroyed, so a section that
99
+ leaves the page leaves nothing behind.
100
+ </p>
101
+ </article>
102
+ </section>
103
+ ```
104
+
105
+ ```js
106
+ import { registerComponents } from '@studiometa/js-toolkit';
107
+ import { MotionScrollTimeline } from '@studiometa/ui-motion';
108
+
109
+ registerComponents(MotionScrollTimeline);
110
+ ```
111
+
112
+ ## Parallax layers
113
+
114
+ One timeline, one scroll range, three `Motion` children: only the travelled distance changes. The far disc moves 80 pixels, the card 180 and the badge 300 over the same progress, and the speed difference alone reads as depth. The timeline scrubs every child with the same progress, so depth is authored entirely in the keyframes — there is no per-layer speed or offset option to set.
115
+
116
+ ```twig
117
+ <p class="py-8 text-center text-current/60">
118
+ Scroll down ↓
119
+ </p>
120
+
121
+ {# One timeline, one scroll range, three Motion children: only the travelled
122
+ distance differs. The far layer moves the least and the near one the most,
123
+ so the speed difference alone reads as depth — no per-layer wiring, the
124
+ timeline scrubs them all with the same progress. #}
125
+ <section data-component="MotionScrollTimeline" class="relative h-[250vh]">
126
+ <div
127
+ class="sticky top-0 grid h-screen grid-cols-1 grid-rows-1 place-items-center overflow-hidden">
128
+ <div
129
+ data-component="Motion"
130
+ data-option-animate='{ "y": [80, -80] }'
131
+ class="col-start-1 row-start-1 size-72 rounded-full bg-blue-400/30 dark:bg-blue-600/30"></div>
132
+ <div
133
+ data-component="Motion"
134
+ data-option-animate='{ "y": [180, -180] }'
135
+ class="col-start-1 row-start-1 w-64 rounded-lg bg-white p-6 text-black shadow-2xl dark:bg-zinc-100">
136
+ <h2 class="text-xl font-bold">Parallax layers</h2>
137
+ <p class="mt-2 text-black/60">
138
+ Same range, three speeds.
139
+ </p>
140
+ </div>
141
+ <div
142
+ data-component="Motion"
143
+ data-option-animate='{ "y": [300, -300] }'
144
+ class="col-start-1 row-start-1 mt-56 ml-56 rounded-full bg-emerald-400 px-4 py-2 font-bold text-white dark:bg-emerald-600">
145
+ Closest
146
+ </div>
147
+ </div>
148
+ </section>
149
+
150
+ <p class="py-8 text-center text-current/60">
151
+ Done ↑
152
+ </p>
153
+ ```
154
+
155
+ ```js
156
+ import { registerComponents } from '@studiometa/js-toolkit';
157
+ import { MotionScrollTimeline } from '@studiometa/ui-motion';
158
+
159
+ registerComponents(MotionScrollTimeline);
160
+ ```
@@ -0,0 +1,25 @@
1
+ # MotionScrollTimeline
2
+
3
+ The `MotionScrollTimeline` component is the scroll driver for a group of animations: the element's traversal of the viewport defines the timeline, and every [`Motion`](../Motion/index.md) child it contains is bound to that progress with Motion's [`scroll()`](https://motion.dev/docs/scroll) — hardware-accelerated where the browser supports `ScrollTimeline`.
4
+
5
+ The children declare their keyframes as usual (arrays give multi-step tracks) and keep their whole playback surface; leave their `autoplay` off (its default) so they do not play before the scroll link takes over. Registering the timeline is enough: it declares `Motion` in `config.components`, so `registerComponent(MotionScrollTimeline)` registers both. See [installation](../Motion/index.md#installation).
6
+
7
+ `MotionScrollTimeline` is part of `@studiometa/ui-motion`, alongside [`Motion`](../Motion/index.md), [`MotionSequence`](../MotionSequence/index.md) and [`MotionView`](../MotionView/index.md).
8
+
9
+ ## Usage
10
+
11
+ <!-- prettier-ignore-start -->
12
+ ```html {2,6}
13
+ <section
14
+ data-component="MotionScrollTimeline"
15
+ class="h-[300vh]">
16
+ <div
17
+ data-component="Motion"
18
+ data-option-animate='{ "opacity": [0, 1, 0], "y": [80, 0, -80] }'>
19
+ …
20
+ </div>
21
+ </section>
22
+ ```
23
+ <!-- prettier-ignore-end -->
24
+
25
+ See the [examples](examples.md) for a live demo, and the [JavaScript API](js-api.md) for the full list of options.
@@ -0,0 +1,58 @@
1
+ # JS API
2
+
3
+ The scroll driver for a group of animations: the element's traversal of the viewport defines the timeline, and every [`Motion`](../Motion/index.md) child it contains is bound to that progress with Motion's [`scroll()`](https://motion.dev/docs/scroll) — hardware-accelerated where the browser supports `ScrollTimeline`. The children declare their keyframes as usual (arrays give multi-step tracks) and keep their whole playback surface; leave their `autoplay` off (its default) so they do not play before the scroll link takes over.
4
+
5
+ <!-- prettier-ignore-start -->
6
+ ```html {2,6}
7
+ <section
8
+ data-component="MotionScrollTimeline"
9
+ class="h-[300vh]">
10
+ <div
11
+ data-component="Motion"
12
+ data-option-animate='{ "opacity": [0, 1, 0], "y": [80, 0, -80] }'>
13
+ …
14
+ </div>
15
+ </section>
16
+ ```
17
+ <!-- prettier-ignore-end -->
18
+
19
+ ## Options
20
+
21
+ ### `offset`
22
+
23
+ - Type: `string[]`
24
+ - Default: `["start end", "end start"]`
25
+
26
+ The scroll range, in Motion's [offset syntax](https://motion.dev/docs/scroll#offset): each entry pairs a point of the timeline element with a point of the viewport. The default maps progress `0` to the element entering the viewport and `1` to it leaving.
27
+
28
+ ### `axis`
29
+
30
+ - Type: `'x' | 'y'`
31
+ - Default: `'y'`
32
+
33
+ The scroll axis driving the timeline.
34
+
35
+ ### `trackContentSize`
36
+
37
+ - Type: `boolean`
38
+ - Default: `false`
39
+
40
+ Watch the scroll container for content size changes, through Motion's own [`trackContentSize`](https://motion.dev/docs/scroll) option. The scroll range is measured once and re-measured on resize, so content that grows or shrinks **after** mount without resizing anything — lazy-loaded images landing, a filtered list dropping rows, an accordion opening — leaves the timeline mapped to a range the page no longer has. Turn this on there.
41
+
42
+ It is not free: Motion compares the container's `scrollWidth` and `scrollHeight` on **every frame** for as long as the timeline lives, and each change costs a re-measure. Leave it off when the content settles before the first scroll.
43
+
44
+ <!-- prettier-ignore-start -->
45
+ ```html {3}
46
+ <section
47
+ data-component="MotionScrollTimeline"
48
+ data-option-track-content-size>
49
+ …
50
+ </section>
51
+ ```
52
+ <!-- prettier-ignore-end -->
53
+
54
+ ## Notes
55
+
56
+ - `scroll()` is not part of `motion/mini`: when the [provided module](../Motion/js-api.md#providing-the-motion-dependency) lacks it, the timeline warns and leaves its children untouched.
57
+ - Each child gets its own `scroll()` link, released when the timeline is destroyed.
58
+ - `trackContentSize` only changes the JavaScript path: where the browser drives the timeline natively with `ScrollTimeline` or `ViewTimeline`, it reads the live scroll range on its own.
@@ -0,0 +1,143 @@
1
+ # Examples
2
+
3
+ ## Staggered sequence
4
+
5
+ [`MotionSequence`](js-api.md) composes its `Motion` children into one timeline: the `stagger` option spreads the first three items, the finale positions itself with `data-option-at="+0.2"`, and one `Action` target plays or reverses the entire choreography — a single animation under the hood.
6
+
7
+ ```twig
8
+ <div class="grid gap-4 justify-items-start">
9
+ <ul
10
+ data-component="MotionSequence"
11
+ data-option-stagger="0.15"
12
+ class="grid gap-2 list-none p-0">
13
+ <li
14
+ data-component="Motion"
15
+ data-option-initial='{ "opacity": 0, "x": -32 }'
16
+ data-option-animate='{ "opacity": 1, "x": 0 }'
17
+ class="px-4 py-2 rounded bg-blue-400 dark:bg-blue-600 text-white font-bold">
18
+ One
19
+ </li>
20
+ <li
21
+ data-component="Motion"
22
+ data-option-initial='{ "opacity": 0, "x": -32 }'
23
+ data-option-animate='{ "opacity": 1, "x": 0 }'
24
+ class="px-4 py-2 rounded bg-blue-400 dark:bg-blue-600 text-white font-bold">
25
+ Two
26
+ </li>
27
+ <li
28
+ data-component="Motion"
29
+ data-option-initial='{ "opacity": 0, "x": -32 }'
30
+ data-option-animate='{ "opacity": 1, "x": 0 }'
31
+ class="px-4 py-2 rounded bg-blue-400 dark:bg-blue-600 text-white font-bold">
32
+ Three
33
+ </li>
34
+ <li
35
+ data-component="Motion"
36
+ data-option-initial='{ "opacity": 0, "scale": 0 }'
37
+ data-option-animate='{ "opacity": 1, "scale": 1 }'
38
+ data-option-transition='{ "type": "spring", "bounce": 0.5 }'
39
+ data-option-at="+0.2"
40
+ class="px-4 py-2 rounded bg-emerald-400 dark:bg-emerald-600 text-white font-bold">
41
+ Finale, 0.2s later
42
+ </li>
43
+ </ul>
44
+
45
+ <div class="flex gap-2">
46
+ <button
47
+ type="button"
48
+ data-component="Action"
49
+ data-on:click="MotionSequence->target.play()"
50
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
51
+ Play
52
+ </button>
53
+ <button
54
+ type="button"
55
+ data-component="Action"
56
+ data-on:click="MotionSequence->target.reverse()"
57
+ class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
58
+ Reverse
59
+ </button>
60
+ </div>
61
+ </div>
62
+ ```
63
+
64
+ ```js
65
+ import { registerComponents } from '@studiometa/js-toolkit';
66
+ import { Action } from '@studiometa/ui';
67
+ import { MotionSequence } from '@studiometa/ui-motion';
68
+
69
+ registerComponents(Action, MotionSequence);
70
+ ```
71
+
72
+ ## Hero intro on mount
73
+
74
+ A badge, a heading, a paragraph and a button entering as one choreography: `data-option-autoplay` goes on the sequence, never on the children, because the sequence owns their playback. The three positioning modes are mixed in one timeline — the badge and the heading follow one another in DOM order, the paragraph starts _with_ the heading through [`data-option-at="<"`](js-api.md#at-on-the-children), and the button overlaps the end of the paragraph with the relative offset `data-option-at="-0.2"`. Each child keeps its own `initial`/`animate` keyframes and its own spring. A mount animation is over before a reader reaches the preview, so the replay button restarts the whole choreography with a single `play()` on the sequence.
75
+
76
+ ```twig
77
+ {# One choreography, played on mount: `data-option-autoplay` belongs to the
78
+ sequence, never to the children — the sequence owns their playback. The
79
+ badge and the heading follow one another in DOM order, the paragraph joins
80
+ the heading with `data-option-at="<"`, and the button overlaps the end of
81
+ the paragraph with the relative offset `data-option-at="-0.2"`. The replay
82
+ button below drives the whole timeline with a single `play()`. #}
83
+ <div
84
+ id="hero-sequence"
85
+ data-component="MotionSequence"
86
+ data-option-autoplay
87
+ class="grid max-w-xl justify-items-start gap-4 rounded-lg p-8 ring">
88
+ <span
89
+ data-component="Motion"
90
+ data-option-initial='{ "opacity": 0, "scale": 0.8 }'
91
+ data-option-animate='{ "opacity": 1, "scale": 1 }'
92
+ data-option-transition='{ "type": "spring", "bounce": 0.5 }'
93
+ class="rounded-full bg-emerald-400/20 px-3 py-1 text-sm font-bold text-emerald-700 ring ring-emerald-400 dark:text-emerald-300">
94
+ New
95
+ </span>
96
+
97
+ <h2
98
+ data-component="Motion"
99
+ data-option-initial='{ "opacity": 0, "y": 24 }'
100
+ data-option-animate='{ "opacity": 1, "y": 0 }'
101
+ data-option-transition='{ "type": "spring", "bounce": 0.2 }'
102
+ class="text-3xl font-bold">
103
+ Animate the whole hero as one timeline
104
+ </h2>
105
+
106
+ <p
107
+ data-component="Motion"
108
+ data-option-initial='{ "opacity": 0, "y": 16 }'
109
+ data-option-animate='{ "opacity": 1, "y": 0 }'
110
+ data-option-at="<"
111
+ class="text-current/70">
112
+ This paragraph starts with the heading, not after it: <code>"&lt;"</code>
113
+ positions a segment at the start of the previous one.
114
+ </p>
115
+
116
+ <button
117
+ type="button"
118
+ data-component="Motion"
119
+ data-option-initial='{ "opacity": 0, "y": 12, "scale": 0.9 }'
120
+ data-option-animate='{ "opacity": 1, "y": 0, "scale": 1 }'
121
+ data-option-transition='{ "type": "spring", "bounce": 0.4 }'
122
+ data-option-at="-0.2"
123
+ class="rounded bg-blue-600 px-4 py-2 font-semibold text-white">
124
+ Get started
125
+ </button>
126
+ </div>
127
+
128
+ <button
129
+ type="button"
130
+ data-component="Action"
131
+ data-on:click="MotionSequence(#hero-sequence)->target.play()"
132
+ class="mt-4 rounded bg-zinc-200 px-4 py-2 dark:bg-zinc-800">
133
+ Replay the sequence
134
+ </button>
135
+ ```
136
+
137
+ ```js
138
+ import { registerComponents } from '@studiometa/js-toolkit';
139
+ import { Action } from '@studiometa/ui';
140
+ import { MotionSequence } from '@studiometa/ui-motion';
141
+
142
+ registerComponents(Action, MotionSequence);
143
+ ```
@@ -0,0 +1,20 @@
1
+ # MotionSequence
2
+
3
+ The `MotionSequence` component orchestrates its [`Motion`](../Motion/index.md) children as one animation sequence: each child declares its keyframes as usual, and the sequence composes them — in DOM order — into a single timeline with Motion's [sequencing](https://motion.dev/docs/animate#timeline-sequencing).
4
+
5
+ The whole playback surface applies to the sequence: an [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) can `play()`, `reverse()` or `seek()` the entire choreography, and a [`MotionScrollTimeline`](../MotionScrollTimeline/index.md) can scrub it. The sequence owns the children's playback — leave their `autoplay` off (its default) and enable it on the sequence itself with `data-option-autoplay` to play on mount.
6
+
7
+ `MotionSequence` declares `Motion` in `config.components`, so `registerComponent(MotionSequence)` registers both — see [installation](../Motion/index.md#installation). It is part of `@studiometa/ui-motion`, alongside [`Motion`](../Motion/index.md), [`MotionScrollTimeline`](../MotionScrollTimeline/index.md) and [`MotionView`](../MotionView/index.md).
8
+
9
+ ## Usage
10
+
11
+ <!-- prettier-ignore-start -->
12
+ ```html {1}
13
+ <ul data-component="MotionSequence" data-option-stagger="0.1" data-option-autoplay>
14
+ <li data-component="Motion" data-option-initial='{ "opacity": 0, "y": 16 }' data-option-animate='{ "opacity": 1, "y": 0 }'>One</li>
15
+ <li data-component="Motion" data-option-initial='{ "opacity": 0, "y": 16 }' data-option-animate='{ "opacity": 1, "y": 0 }'>Two</li>
16
+ </ul>
17
+ ```
18
+ <!-- prettier-ignore-end -->
19
+
20
+ See the [examples](examples.md) for a live demo, and the [JavaScript API](js-api.md) for the full list of options.