@studiometa/ui-motion 2.0.0-alpha.0 → 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.
@@ -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 -->
@@ -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.