@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.
- package/README.md +10 -0
- package/dist/catalog.js +1 -1
- package/dist/catalog.js.map +1 -1
- package/dist/manifest.js +4 -4
- package/dist/manifest.js.map +1 -1
- package/dist/scripts/manifest-types.d.ts +5 -2
- 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,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.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# JS API
|
|
2
|
+
|
|
3
|
+
Orchestrate the [`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). 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.
|
|
4
|
+
|
|
5
|
+
<!-- prettier-ignore-start -->
|
|
6
|
+
```html {1}
|
|
7
|
+
<ul data-component="MotionSequence" data-option-stagger="0.1" data-option-autoplay>
|
|
8
|
+
<li data-component="Motion" data-option-initial='{ "opacity": 0, "y": 16 }' data-option-animate='{ "opacity": 1, "y": 0 }'>One</li>
|
|
9
|
+
<li data-component="Motion" data-option-initial='{ "opacity": 0, "y": 16 }' data-option-animate='{ "opacity": 1, "y": 0 }'>Two</li>
|
|
10
|
+
</ul>
|
|
11
|
+
```
|
|
12
|
+
<!-- prettier-ignore-end -->
|
|
13
|
+
|
|
14
|
+
## Options
|
|
15
|
+
|
|
16
|
+
`MotionSequence` extends [`Motion`](../Motion/index.md), so it also accepts every `Motion` option — `initial`, `animate`, `transition` and `autoplay` among them — and inherits the whole playback surface (`play()`, `reverse()`, `pause()`, `seek()`, `stop()`, `cancel()`, `complete()`) and the `motion-*` events.
|
|
17
|
+
|
|
18
|
+
### `stagger`
|
|
19
|
+
|
|
20
|
+
- Type: `number`
|
|
21
|
+
- Default: `0`
|
|
22
|
+
|
|
23
|
+
Spreads the segments automatically: each child starts `stagger` seconds after the previous one. Without it, segments run one after another (Motion's default).
|
|
24
|
+
|
|
25
|
+
### `at` (on the children)
|
|
26
|
+
|
|
27
|
+
- Type: `string`
|
|
28
|
+
- Default: `''`
|
|
29
|
+
|
|
30
|
+
A child's explicit position in the sequence, taking precedence over `stagger`: a time in seconds (`"2"`), a relative offset (`"-0.2"`), or `"<"` for "with the previous segment". See Motion's [sequencing options](https://motion.dev/docs/animate#timeline-sequencing).
|
|
31
|
+
|
|
32
|
+
## Notes
|
|
33
|
+
|
|
34
|
+
- The sequence element's own `transition` option is passed as the sequence-level options (e.g. a shared `duration` or `repeat`).
|
|
35
|
+
- Children without `animate` keyframes are skipped.
|
|
36
|
+
- Sequences need the full `motion` entry: `motion/mini`'s `animate()` does not support them. See [providing the Motion dependency](../Motion/js-api.md#providing-the-motion-dependency).
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# Examples
|
|
2
|
+
|
|
3
|
+
## Animated state change
|
|
4
|
+
|
|
5
|
+
[`MotionView`](js-api.md) wraps DOM updates in Motion's `animateView()`, as a drop-in alternative to [`ViewTransition`](https://ui-v2.studiometa.dev/reference/items/ViewTransition/): toggling swaps the `enterTo`/`leaveTo` classes inside a view transition, and the spring `transition` with the `layout` morph animates the card between its two states — no `::view-transition-*` CSS needed. Where view transitions are unavailable, the classes still swap, only without animation.
|
|
6
|
+
|
|
7
|
+
```twig
|
|
8
|
+
<div class="grid gap-4 justify-items-start">
|
|
9
|
+
<div
|
|
10
|
+
data-component="MotionView"
|
|
11
|
+
data-option-enter-to="w-72 p-8 rounded-3xl bg-emerald-400 dark:bg-emerald-600"
|
|
12
|
+
data-option-leave-to="w-40 p-4 rounded bg-blue-400 dark:bg-blue-600"
|
|
13
|
+
data-option-transition='{ "type": "spring", "bounce": 0.3 }'
|
|
14
|
+
data-option-layout
|
|
15
|
+
class="w-40 p-4 rounded bg-blue-400 dark:bg-blue-600 text-white font-bold">
|
|
16
|
+
One card, two states
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
<button
|
|
20
|
+
type="button"
|
|
21
|
+
data-component="Action"
|
|
22
|
+
data-on:click="MotionView->target.toggle()"
|
|
23
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
24
|
+
Toggle
|
|
25
|
+
</button>
|
|
26
|
+
</div>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
31
|
+
import { Action } from '@studiometa/ui';
|
|
32
|
+
import { MotionView } from '@studiometa/ui-motion';
|
|
33
|
+
|
|
34
|
+
registerComponents(Action, MotionView);
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Zero-wiring exit animation for `data-bind:if`
|
|
38
|
+
|
|
39
|
+
[Ambient wiring](js-api.md#ambient-wiring) in action: the `MotionView` has no wiring attribute at all — it wraps the `js-toolkit:dom:update` event that [`data-bind:if`](https://ui-v2.studiometa.dev/reference/items/DataBind/js-api#conditional-rendering-with-data-bind-if) announces before changing the DOM, so the template content animates in **and out**, even though the removed nodes are already gone when the exit plays. The `layout` option morphs the container's size with a spring. Because the event bubbles, the `MotionView` only needs to sit just outside the `<template>` instead of around the whole widget: the morph then hugs the panel region alone and leaves the checkbox above it out of the transition.
|
|
40
|
+
|
|
41
|
+
```twig
|
|
42
|
+
<div
|
|
43
|
+
data-component="DataScope"
|
|
44
|
+
data-option-group="ambient-panel"
|
|
45
|
+
class="grid gap-4 rounded ring p-4 max-w-sm">
|
|
46
|
+
<label class="flex items-center gap-2">
|
|
47
|
+
<input type="checkbox" name="details" data-component="DataModel" />
|
|
48
|
+
<span>Show the details</span>
|
|
49
|
+
</label>
|
|
50
|
+
{# The MotionView sits just outside the template, not around the whole
|
|
51
|
+
widget: the `js-toolkit:dom:update` event that `data-bind:if` announces before
|
|
52
|
+
changing the DOM bubbles up to it, so the insertion AND the removal play
|
|
53
|
+
as one spring view transition — and the `layout` morph hugs the panel
|
|
54
|
+
region only, leaving the checkbox above it untouched. #}
|
|
55
|
+
<div
|
|
56
|
+
data-component="MotionView"
|
|
57
|
+
data-option-transition='{ "type": "spring", "bounce": 0.2 }'
|
|
58
|
+
data-option-layout>
|
|
59
|
+
<template data-component="DataBind" data-option-key="details" data-bind:if>
|
|
60
|
+
<p class="p-4 rounded bg-emerald-400/20 ring ring-emerald-400">
|
|
61
|
+
I was inserted inside a view transition — and I animate out too, even
|
|
62
|
+
though my nodes are already gone when the exit plays.
|
|
63
|
+
</p>
|
|
64
|
+
</template>
|
|
65
|
+
</div>
|
|
66
|
+
</div>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```js
|
|
70
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
71
|
+
import { DataBind, DataModel, DataScope } from '@studiometa/ui';
|
|
72
|
+
import { MotionView } from '@studiometa/ui-motion';
|
|
73
|
+
|
|
74
|
+
registerComponents(DataScope, DataBind, DataModel, MotionView);
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Ambient view transitions in a `Dialog`
|
|
78
|
+
|
|
79
|
+
The same containment story with [`Dialog`](https://ui-v2.studiometa.dev/reference/items/Dialog/): nested inside it, a `MotionView` listens for the dialog's [extendable `open`/`close` events](https://ui-v2.studiometa.dev/reference/items/Dialog/js-api#extending-the-lifecycle-with-waituntil) by itself, with no wiring attribute at all. Two instances share it here, the backdrop fading and the box springing in, because the extension is additive: every registration on the event is awaited, so any number of them can animate one host without ever knowing about each other. The exit plays in full — the dialog stays painted until both have settled.
|
|
80
|
+
|
|
81
|
+
```twig
|
|
82
|
+
<button
|
|
83
|
+
type="button"
|
|
84
|
+
data-component="Action"
|
|
85
|
+
data-on:click="Dialog(#ambient-modal)->target.open()"
|
|
86
|
+
class="px-4 py-2 rounded bg-blue-600 text-white font-semibold">
|
|
87
|
+
Open dialog
|
|
88
|
+
</button>
|
|
89
|
+
|
|
90
|
+
{# Two MotionView instances, zero wiring attributes: the backdrop and the box
|
|
91
|
+
both live inside the Dialog and both listen for its extendable `open`/`close`
|
|
92
|
+
events on the document. Each registers with `detail.waitUntil()`, so the
|
|
93
|
+
dialog awaits both before it hides. #}
|
|
94
|
+
<dialog
|
|
95
|
+
id="ambient-modal"
|
|
96
|
+
data-component="Action Dialog"
|
|
97
|
+
data-on:cancel.prevent="Dialog.close()"
|
|
98
|
+
class="fixed inset-0 m-0 p-0 w-full h-full max-w-none max-h-none bg-transparent overflow-y-auto">
|
|
99
|
+
<div
|
|
100
|
+
data-component="Action MotionView"
|
|
101
|
+
data-on:click="Dialog(#ambient-modal)->target.close()"
|
|
102
|
+
data-option-view-transition-name="ambient-modal-backdrop"
|
|
103
|
+
data-option-transition='{ "duration": 0.3 }'
|
|
104
|
+
data-option-enter-to="opacity-100"
|
|
105
|
+
data-option-leave-to="opacity-0"
|
|
106
|
+
class="fixed inset-0 bg-black/50 opacity-0"></div>
|
|
107
|
+
|
|
108
|
+
<div
|
|
109
|
+
class="pointer-events-none relative flex min-h-full items-center justify-center p-4">
|
|
110
|
+
<div
|
|
111
|
+
data-component="MotionView"
|
|
112
|
+
data-option-view-transition-name="ambient-modal-box"
|
|
113
|
+
data-option-transition='{ "type": "spring", "bounce": 0.3 }'
|
|
114
|
+
data-option-enter-to="opacity-100 translate-y-0 scale-100"
|
|
115
|
+
data-option-leave-to="opacity-0 translate-y-8 scale-95"
|
|
116
|
+
class="pointer-events-auto relative w-full max-w-lg p-8 rounded-lg bg-white text-black shadow-2xl opacity-0 translate-y-8 scale-95">
|
|
117
|
+
<h2 class="text-xl font-bold mb-3">Ambient view transitions</h2>
|
|
118
|
+
<p class="mb-6 text-black/60">
|
|
119
|
+
No <code>data-on:open</code>, no <code>data-on:close</code>: the
|
|
120
|
+
<code>MotionView</code> heard the dialog's lifecycle because it lives inside
|
|
121
|
+
it, and swaps its state classes inside a spring view transition.
|
|
122
|
+
</p>
|
|
123
|
+
<button
|
|
124
|
+
type="button"
|
|
125
|
+
data-component="Action"
|
|
126
|
+
data-on:click="Dialog(#ambient-modal)->target.close()"
|
|
127
|
+
class="px-4 py-2 rounded bg-gray-900 text-white">
|
|
128
|
+
Close
|
|
129
|
+
</button>
|
|
130
|
+
</div>
|
|
131
|
+
</div>
|
|
132
|
+
</dialog>
|
|
133
|
+
|
|
134
|
+
<style>
|
|
135
|
+
dialog::backdrop { background: transparent; }
|
|
136
|
+
|
|
137
|
+
/* Chromium quirk: a view-transition layer on top-layer content can paint
|
|
138
|
+
behind the page snapshot mid-transition; lifting the groups fixes it. Both
|
|
139
|
+
groups are ordered explicitly so the backdrop stays under the box. */
|
|
140
|
+
::view-transition-group(ambient-modal-backdrop) { z-index: 1; }
|
|
141
|
+
::view-transition-group(ambient-modal-box) { z-index: 2; }
|
|
142
|
+
</style>
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
```js
|
|
146
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
147
|
+
import { Action, Dialog } from '@studiometa/ui';
|
|
148
|
+
import { MotionView } from '@studiometa/ui-motion';
|
|
149
|
+
|
|
150
|
+
registerComponents(Action, Dialog, MotionView);
|
|
151
|
+
```
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# MotionView
|
|
2
|
+
|
|
3
|
+
The `MotionView` component wraps DOM updates in Motion's [`animateView()`](https://motion.dev/docs/animate-view) so the change plays as a view transition. It is a drop-in alternative to the [`ViewTransition`](https://ui-v2.studiometa.dev/reference/items/ViewTransition/) component — same `enter()`/`leave()`/`toggle()` methods, `state` property, events and `viewTransitionName`/`enterTo`/`leaveTo` options — but the animation is declared with Motion keyframes and transitions (including springs) instead of the `::view-transition-*` CSS pseudo-elements.
|
|
4
|
+
|
|
5
|
+
Containment is the wiring: with the [`auto` option](js-api.md#auto) (on by default), a mounted `MotionView` wraps any DOM update announced inside its subtree — by [`Fetch`](https://ui-v2.studiometa.dev/reference/items/Fetch/) or [`DataBind`](https://ui-v2.studiometa.dev/reference/items/DataBind/)'s `data-bind:if` — and joins the extendable open/close lifecycle of a containing host such as [`Dialog`](https://ui-v2.studiometa.dev/reference/items/Dialog/), with zero wiring attributes on either side. See [ambient wiring](js-api.md#ambient-wiring).
|
|
6
|
+
|
|
7
|
+
`MotionView` needs its own `registerComponent()` call — see [installation](../Motion/index.md#installation). It is part of `@studiometa/ui-motion`, alongside [`Motion`](../Motion/index.md), [`MotionScrollTimeline`](../MotionScrollTimeline/index.md) and [`MotionSequence`](../MotionSequence/index.md).
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
Option values are parsed as JSON, so object keys must be quoted:
|
|
12
|
+
|
|
13
|
+
<!-- prettier-ignore-start -->
|
|
14
|
+
```html {2,3}
|
|
15
|
+
<div
|
|
16
|
+
data-component="MotionView"
|
|
17
|
+
data-option-enter-to="is-open"
|
|
18
|
+
data-option-transition='{ "type": "spring", "bounce": 0.3 }'>
|
|
19
|
+
…
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
<button data-component="Action" data-on:click="MotionView->target.toggle()">Toggle</button>
|
|
23
|
+
```
|
|
24
|
+
<!-- prettier-ignore-end -->
|
|
25
|
+
|
|
26
|
+
See the [examples](examples.md) for live demos of the ambient integrations, and the [JavaScript API](js-api.md) for the full list of options, methods and events.
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# JS API
|
|
2
|
+
|
|
3
|
+
Wrap DOM updates in Motion's [`animateView()`](https://motion.dev/docs/animate-view) so the change plays as a view transition. A drop-in alternative to the [`ViewTransition`](https://ui-v2.studiometa.dev/reference/items/ViewTransition/) component — same `enter()`/`leave()`/`toggle()` methods, `state` property, events and `viewTransitionName`/`enterTo`/`leaveTo` options — but the animation is declared with Motion keyframes and transitions (including springs) instead of the `::view-transition-*` CSS pseudo-elements.
|
|
4
|
+
|
|
5
|
+
<!-- prettier-ignore-start -->
|
|
6
|
+
```html {2,3}
|
|
7
|
+
<div
|
|
8
|
+
data-component="MotionView"
|
|
9
|
+
data-option-enter-to="is-open"
|
|
10
|
+
data-option-transition='{ "type": "spring", "bounce": 0.3 }'>
|
|
11
|
+
…
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
<button data-component="Action" data-on:click="MotionView->target.toggle()">Toggle</button>
|
|
15
|
+
```
|
|
16
|
+
<!-- prettier-ignore-end -->
|
|
17
|
+
|
|
18
|
+
## Options
|
|
19
|
+
|
|
20
|
+
Object options are parsed as JSON: quote the keys (`data-option-new='{ "opacity": [0, 1] }'`).
|
|
21
|
+
|
|
22
|
+
### `viewTransitionName`
|
|
23
|
+
|
|
24
|
+
- Type: `string`
|
|
25
|
+
- Default: `''`
|
|
26
|
+
|
|
27
|
+
Assigned as the element's [`view-transition-name`](https://developer.mozilla.org/en-US/docs/Web/CSS/view-transition-name) on mount, exactly like `ViewTransition`. Optional with `MotionView`: `animateView()` names the subjects it animates automatically.
|
|
28
|
+
|
|
29
|
+
### `enterTo`
|
|
30
|
+
|
|
31
|
+
- Type: `string`
|
|
32
|
+
- Default: `''`
|
|
33
|
+
|
|
34
|
+
Classes describing the shown state. Added on `enter`, removed on `leave`.
|
|
35
|
+
|
|
36
|
+
### `leaveTo`
|
|
37
|
+
|
|
38
|
+
- Type: `string`
|
|
39
|
+
- Default: `''`
|
|
40
|
+
|
|
41
|
+
Classes describing the hidden state. Added on `leave`, removed on `enter`. Usually also the element's initial class so it starts hidden.
|
|
42
|
+
|
|
43
|
+
### `transition`
|
|
44
|
+
|
|
45
|
+
- Type: `ViewTransitionOptions`
|
|
46
|
+
- Default: `{}`
|
|
47
|
+
|
|
48
|
+
The root [`animateView()` options](https://motion.dev/docs/animate-view): a default transition (`duration`, `ease`, `type: "spring"`, …) for every layer of the view transition.
|
|
49
|
+
|
|
50
|
+
### `add`
|
|
51
|
+
|
|
52
|
+
- Type: `string`
|
|
53
|
+
- Default: `''`
|
|
54
|
+
|
|
55
|
+
A selector resolved within the component's element: every matched element becomes an animated subject of the transition. When empty, the element itself is the subject.
|
|
56
|
+
|
|
57
|
+
### `new`, `old`, `enter`, `exit`
|
|
58
|
+
|
|
59
|
+
- Type: `DOMKeyframesDefinition`
|
|
60
|
+
- Default: `{}`
|
|
61
|
+
|
|
62
|
+
Per-layer keyframes applied to each subject, mapping to the builder's [`new()`/`old()`/`enter()`/`exit()` methods](https://motion.dev/docs/animate-view): `new` and `old` animate the new and old views whether the element persists or not, while `enter` and `exit` only fire for a pure newcomer or leaver.
|
|
63
|
+
|
|
64
|
+
### `layout`
|
|
65
|
+
|
|
66
|
+
- Type: `boolean`
|
|
67
|
+
- Default: `false`
|
|
68
|
+
|
|
69
|
+
Enable the layout morph on each subject (the builder's `layout()`), so position and size changes animate smoothly.
|
|
70
|
+
|
|
71
|
+
### `auto`
|
|
72
|
+
|
|
73
|
+
- Type: `boolean`
|
|
74
|
+
- Default: `true`
|
|
75
|
+
|
|
76
|
+
Enable [ambient wiring](#ambient-wiring): the component wraps any DOM update announced inside its subtree and joins the lifecycle of a containing `Dialog`. Opt out with `data-option-no-auto`.
|
|
77
|
+
|
|
78
|
+
## Properties
|
|
79
|
+
|
|
80
|
+
### `state`
|
|
81
|
+
|
|
82
|
+
- Type: `'entering' | 'leaving' | null`
|
|
83
|
+
|
|
84
|
+
The current state of the transition: `'entering'` while entering, `'leaving'` while leaving, or `null` before any transition has run. `toggle()` reads it to decide which direction to run.
|
|
85
|
+
|
|
86
|
+
### `target`
|
|
87
|
+
|
|
88
|
+
- Type: `HTMLElement`
|
|
89
|
+
|
|
90
|
+
The element the `view-transition-name` and the enter and leave classes are applied to — the component's root element.
|
|
91
|
+
|
|
92
|
+
## Events
|
|
93
|
+
|
|
94
|
+
The same events as [`ViewTransition`](https://ui-v2.studiometa.dev/reference/items/ViewTransition/js-api#events), in the same order: `enter`, `enter-start`, `enter-end` around the enter transition and `leave`, `leave-start`, `leave-end` around the leave transition.
|
|
95
|
+
|
|
96
|
+
## Methods
|
|
97
|
+
|
|
98
|
+
| Method | Description |
|
|
99
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
100
|
+
| `enter()` | Swap `leaveTo` for `enterTo` inside a view transition. Resolves once the animation settles. |
|
|
101
|
+
| `leave()` | Swap `enterTo` for `leaveTo` inside a view transition. Resolves once the animation settles. |
|
|
102
|
+
| `toggle()` | Toggle between enter and leave, entering first. |
|
|
103
|
+
| `update(mutate)` | The underlying primitive: run any DOM mutation as a view transition configured by the options. Never rejects. |
|
|
104
|
+
|
|
105
|
+
## Ambient wiring
|
|
106
|
+
|
|
107
|
+
Containment is the wiring: with the `auto` option (on by default), a mounted `MotionView` listens for the bubbling `js-toolkit:dom:update` event that mutating components — [`Fetch`](https://ui-v2.studiometa.dev/reference/items/Fetch/), [`DataBind`](https://ui-v2.studiometa.dev/reference/items/DataBind/)'s `data-bind:if` — announce before changing the DOM, and runs the announced change through `update()` so it plays as a view transition. Nesting the mutators inside the component is enough, with zero wiring attributes on either side:
|
|
108
|
+
|
|
109
|
+
<!-- prettier-ignore-start -->
|
|
110
|
+
```html {1}
|
|
111
|
+
<div data-component="MotionView" data-option-transition='{ "type": "spring", "bounce": 0.2 }'>
|
|
112
|
+
<form action="/search" data-component="Fetch">
|
|
113
|
+
<input type="search" name="q" />
|
|
114
|
+
</form>
|
|
115
|
+
|
|
116
|
+
<template data-component="DataBind" data-option-key="expanded" data-bind:if>
|
|
117
|
+
<p>…</p>
|
|
118
|
+
</template>
|
|
119
|
+
</div>
|
|
120
|
+
```
|
|
121
|
+
<!-- prettier-ignore-end -->
|
|
122
|
+
|
|
123
|
+
A `MotionView` also joins the lifecycle of an ancestor that emits **extendable** `open` and `close` events — those built with the toolkit's [`emitExtendable()`](https://js-toolkit-v4.studiometa.dev/api/dom/emitExtendable.html), whose `detail` carries a `waitUntil()` function. [`Dialog`](https://ui-v2.studiometa.dev/reference/items/Dialog/js-api#events) emits exactly those, so nesting a `MotionView` inside a dialog is enough: it registers `enter()` on `open` and `leave()` on `close`, and the dialog stays painted until the animation settles.
|
|
124
|
+
|
|
125
|
+
It registers a **function**, not itself: `emitExtendable()` duck-types an object registration on the name of the event, and a transition component has no `open()`/`close()` to offer. See [extending the lifecycle](https://ui-v2.studiometa.dev/reference/items/Dialog/js-api#extending-the-lifecycle-with-waituntil).
|
|
126
|
+
|
|
127
|
+
Only a **containing** ancestor counts. The event is heard on the document, and the component checks that its emitter contains the root element, so a dialog elsewhere on the page animates nothing here.
|
|
128
|
+
|
|
129
|
+
Opt out with `data-option-no-auto`. Explicit wiring through [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) remains for cross-subtree topologies, where the mutator and the animated subtree are not nested:
|
|
130
|
+
|
|
131
|
+
<!-- prettier-ignore-start -->
|
|
132
|
+
```html {4}
|
|
133
|
+
<form
|
|
134
|
+
action="/search"
|
|
135
|
+
data-component="Fetch Action"
|
|
136
|
+
data-on:js-toolkit:dom:update="MotionView(#list)->event.detail.wrap(target)">
|
|
137
|
+
<input type="search" name="q" />
|
|
138
|
+
</form>
|
|
139
|
+
|
|
140
|
+
<ul id="list" data-component="MotionView">
|
|
141
|
+
…
|
|
142
|
+
</ul>
|
|
143
|
+
```
|
|
144
|
+
<!-- prettier-ignore-end -->
|
|
145
|
+
|
|
146
|
+
## Notes
|
|
147
|
+
|
|
148
|
+
- The mutation is never lost: in browsers without the View Transitions API — or when the animation rejects — the update still applies, only without animation.
|
|
149
|
+
- `animateView()` is not part of `motion/mini`: when the [provided module](../Motion/js-api.md#providing-the-motion-dependency) lacks it, the component warns and applies updates directly.
|