@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 +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
|
@@ -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>"<"</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.
|