@studiometa/ui-motion 2.0.0-alpha.1 → 2.0.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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.