@studiometa/ui-motion 0.0.1 → 1.11.0

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/LICENSE.md ADDED
@@ -0,0 +1,110 @@
1
+ # Functional Source License, Version 1.1, MIT Future License
2
+
3
+ ## Abbreviation
4
+
5
+ FSL-1.1-MIT
6
+
7
+ ## Notice
8
+
9
+ Copyright 2025 Studio Meta
10
+
11
+ ## Terms and Conditions
12
+
13
+ ### Licensor ("We")
14
+
15
+ The party offering the Software under these Terms and Conditions.
16
+
17
+ ### The Software
18
+
19
+ The "Software" is each version of the software that we make available under
20
+ these Terms and Conditions, as indicated by our inclusion of these Terms and
21
+ Conditions with the Software.
22
+
23
+ ### License Grant
24
+
25
+ Subject to your compliance with this License Grant and the Patents,
26
+ Redistribution and Trademark clauses below, we hereby grant you the right to
27
+ use, copy, modify, create derivative works, publicly perform, publicly display
28
+ and redistribute the Software for any Permitted Purpose identified below.
29
+
30
+ ### Permitted Purpose
31
+
32
+ A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
+ means making the Software available to others in a commercial product or
34
+ service that:
35
+
36
+ 1. substitutes for the Software;
37
+
38
+ 2. substitutes for any other product or service we offer using the Software
39
+ that exists as of the date we make the Software available; or
40
+
41
+ 3. offers the same or substantially similar functionality as the Software.
42
+
43
+ Permitted Purposes specifically include using the Software:
44
+
45
+ 1. for your internal use and access;
46
+
47
+ 2. for non-commercial education;
48
+
49
+ 3. for non-commercial research; and
50
+
51
+ 4. in connection with professional services that you provide to a licensee
52
+ using the Software in accordance with these Terms and Conditions.
53
+
54
+ ### Patents
55
+
56
+ To the extent your use for a Permitted Purpose would necessarily infringe our
57
+ patents, the license grant above includes a license under our patents. If you
58
+ make a claim against any party that the Software infringes or contributes to
59
+ the infringement of any patent, then your patent license to the Software ends
60
+ immediately.
61
+
62
+ ### Redistribution
63
+
64
+ The Terms and Conditions apply to all copies, modifications and derivatives of
65
+ the Software.
66
+
67
+ If you redistribute any copies, modifications or derivatives of the Software,
68
+ you must include a copy of or a link to these Terms and Conditions and not
69
+ remove any copyright notices provided in or with the Software.
70
+
71
+ ### Disclaimer
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
74
+ IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
75
+ PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
76
+
77
+ IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
+ SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
79
+ EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
+
81
+ ### Trademarks
82
+
83
+ Except for displaying the License Details and identifying us as the origin of
84
+ the Software, you have no right under these Terms and Conditions to use our
85
+ trademarks, trade names, service marks or product names.
86
+
87
+ ## Grant of Future License
88
+
89
+ We hereby irrevocably grant you an additional license to use the Software under
90
+ the MIT license that is effective on the second anniversary of the date we make
91
+ the Software available. On or after that date, you may use the Software under
92
+ the MIT license, in which case the following will apply:
93
+
94
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
95
+ this software and associated documentation files (the "Software"), to deal in
96
+ the Software without restriction, including without limitation the rights to
97
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
98
+ of the Software, and to permit persons to whom the Software is furnished to do
99
+ so, subject to the following conditions:
100
+
101
+ The above copyright notice and this permission notice shall be included in all
102
+ copies or substantial portions of the Software.
103
+
104
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
105
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
106
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
107
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
108
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
109
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
110
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,85 @@
1
+ # @studiometa/ui-motion
2
+
3
+ [![NPM Version](https://img.shields.io/npm/v/@studiometa/ui-motion.svg?style=flat&colorB=3e63dd&colorA=414853)](https://www.npmjs.com/package/@studiometa/ui-motion/)
4
+ [![Downloads](https://img.shields.io/npm/dm/@studiometa/ui-motion?style=flat&colorB=3e63dd&colorA=414853)](https://www.npmjs.com/package/@studiometa/ui-motion/)
5
+
6
+ > Vanilla [@studiometa/js-toolkit](https://github.com/studiometa/js-toolkit) components to animate elements declaratively with [Motion](https://motion.dev).
7
+
8
+ ## Installation
9
+
10
+ Install the package along with its `motion` peer dependency:
11
+
12
+ ```bash
13
+ npm install @studiometa/ui-motion motion
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ Register the component, then author the animation declaratively in your markup. Option values are parsed as JSON, so object keys must be quoted:
19
+
20
+ ```js
21
+ import { registerComponent } from '@studiometa/js-toolkit';
22
+ import { Motion } from '@studiometa/ui-motion';
23
+
24
+ registerComponent(Motion);
25
+ ```
26
+
27
+ ```html
28
+ <div
29
+ data-component="Motion"
30
+ data-option-initial='{ "opacity": 0, "y": 24 }'
31
+ data-option-animate='{ "opacity": 1, "y": 0 }'
32
+ data-option-transition='{ "type": "spring", "bounce": 0.3 }'
33
+ data-option-autoplay>
34
+ Hello world!
35
+ </div>
36
+ ```
37
+
38
+ The `initial` styles are applied on mount, then the `animate` keyframes play when playback on mount is enabled with `data-option-autoplay`. Without it, drive the animation from an [`Action`](https://ui.studiometa.dev/reference/items/Action/) instead:
39
+
40
+ ```html
41
+ <div data-component="Motion" data-option-animate='{ "x": 100 }'>...</div>
42
+
43
+ <button data-component="Action" data-on:click="Motion->target.play()">Play</button>
44
+ <button data-component="Action" data-on:click="Motion->target.reverse()">Reverse</button>
45
+ <button data-component="Action" data-on:click="Motion->target.animate({ rotate: 360 })">
46
+ Spin
47
+ </button>
48
+ ```
49
+
50
+ The playback API is `play()`, `pause()`, `reverse()`, `seek(progress)`, `stop()`, `cancel()`, `complete()` and `animate(keyframes, options)`. The component emits bubbling `motion-play`, `motion-pause`, `motion-complete`, `motion-cancel` and `motion-stop` events an ancestor `Action` can catch and route.
51
+
52
+ The `hover`, `press` and `inView` options apply keyframes while their state holds (through Motion's touch-filtered, keyboard-accessible gesture functions) and revert when it ends:
53
+
54
+ ```html
55
+ <div data-component="Motion" data-option-hover='{ "scale": 1.1 }'>Hover me</div>
56
+ ```
57
+
58
+ `MotionView` wraps DOM updates (its `enter()`/`leave()`/`toggle()` class swaps, or any mutation through `update()`) in Motion's `animateView()`, as a drop-in alternative to the `ViewTransition` component powered by Motion keyframes and springs instead of CSS pseudo-elements. `MotionSequence` composes its `Motion` children into one timeline (with per-child `at` positions or an automatic `stagger`), and the whole playback surface drives the sequence. For scroll-driven animations, wrap `Motion` components in a `MotionScrollTimeline`: the wrapper's traversal of the viewport defines the timeline and every child is bound to that progress with Motion's `scroll()`, hardware-accelerated where the browser supports `ScrollTimeline`:
59
+
60
+ ```html
61
+ <section data-component="MotionScrollTimeline" class="h-[300vh]">
62
+ <div data-component="Motion" data-option-animate='{ "opacity": [0, 1, 0] }'>...</div>
63
+ </section>
64
+ ```
65
+
66
+ ## Providing `motion`
67
+
68
+ By default the component resolves `motion` with a lazy `import()` the first time an animation is built, so the dependency stays out of your main bundle until it is needed. You never have to configure anything for the default to work — just keep `motion` installed.
69
+
70
+ When you need to control which `motion` the component uses — a specific version, the smaller `motion/mini` entry, or a module served from an import map or a CDN — inject your own instance once, before the components mount:
71
+
72
+ ```js
73
+ import { animate } from 'motion/mini';
74
+ import { provideMotion } from '@studiometa/ui-motion';
75
+
76
+ provideMotion({ animate });
77
+ ```
78
+
79
+ Once provided, `@studiometa/ui-motion` never imports `motion` by specifier — it uses the instance you handed it. `resolveMotion()` is also exported if you want to trigger (and await) resolution yourself, for example to preload the module.
80
+
81
+ Heads up to [ui.studiometa.dev](https://ui.studiometa.dev/reference/items/Motion/) for the full documentation.
82
+
83
+ ## Contributing
84
+
85
+ Please read the [contribution docs](https://ui.studiometa.dev/guide/contributing/).
@@ -0,0 +1,238 @@
1
+ import { MotionModule } from "./dependencies.js";
2
+ import { Base } from "@studiometa/js-toolkit/Base";
3
+ import { BaseConfig, BaseProps } from "@studiometa/js-toolkit";
4
+ import { AnimationOptions, AnimationPlaybackControlsWithThen, DOMKeyframesDefinition } from "motion";
5
+
6
+ //#region src/Motion.d.ts
7
+ interface MotionProps extends BaseProps {
8
+ $options: {
9
+ initial: DOMKeyframesDefinition;
10
+ animate: DOMKeyframesDefinition;
11
+ transition: AnimationOptions;
12
+ autoplay: boolean;
13
+ at: string;
14
+ hover: DOMKeyframesDefinition;
15
+ press: DOMKeyframesDefinition;
16
+ inView: DOMKeyframesDefinition;
17
+ inViewMargin: string;
18
+ inViewAmount: string;
19
+ once: boolean;
20
+ };
21
+ }
22
+ /**
23
+ * Motion class.
24
+ *
25
+ * Animate the component's root element declaratively with the
26
+ * [Motion](https://motion.dev) library. The `initial` styles are applied on
27
+ * mount, then the `animate` keyframes play when playback on mount is enabled
28
+ * with `data-option-autoplay`.
29
+ *
30
+ * The component holds a single current animation. `play()` and `reverse()`
31
+ * always drive the animation declared by the options — recreating it when an
32
+ * imperative {@link Motion.animate} call superseded it — while the other
33
+ * playback methods (`pause`, `seek`, `stop`, ...) act on whichever animation
34
+ * is current. An `Action` can control it from any interaction:
35
+ * `data-on:click="Motion->target.play()"`.
36
+ *
37
+ * Events bubble, so an ancestor `Action` can catch and route them; use the
38
+ * `.stop` event modifier to contain them in nested setups.
39
+ *
40
+ * @link https://ui.studiometa.dev/reference/items/Motion/
41
+ */
42
+ declare class Motion<T extends BaseProps = BaseProps> extends Base<MotionProps & T> {
43
+ /**
44
+ * Config.
45
+ */
46
+ static config: BaseConfig;
47
+ /**
48
+ * The current animation playback controls, or `null` when idle.
49
+ * @private
50
+ */
51
+ __controls: AnimationPlaybackControlsWithThen | null;
52
+ /**
53
+ * Monotonic token invalidating stale completion watchers whenever the
54
+ * current playback changes (new play, stop, cancel, destroy).
55
+ * @private
56
+ */
57
+ __completionToken: number;
58
+ /**
59
+ * The stop function of each gesture binding, released on destroy.
60
+ * @private
61
+ */
62
+ __gestureStops: VoidFunction[];
63
+ /**
64
+ * The base value of every property a gesture animated, captured the first
65
+ * time a gesture touched it — the values a gesture returns to when it ends.
66
+ * @private
67
+ */
68
+ __baseValues: Record<string, string | number>;
69
+ /**
70
+ * Whether the current animation was built from the `animate` and
71
+ * `transition` options, as opposed to an imperative `animate()` call.
72
+ * @private
73
+ */
74
+ __fromOptions: boolean;
75
+ /**
76
+ * The current animation playback controls, exposed for advanced use from
77
+ * `Action` effects (e.g. `Motion->target.controls.speed = 2`).
78
+ */
79
+ get controls(): AnimationPlaybackControlsWithThen | null;
80
+ /**
81
+ * The current playback time in seconds.
82
+ */
83
+ get time(): number;
84
+ /**
85
+ * The current animation duration in seconds.
86
+ */
87
+ get duration(): number;
88
+ /**
89
+ * The current playback progress, from 0 to 1.
90
+ */
91
+ get progress(): number;
92
+ /**
93
+ * Apply the `initial` styles, play the `animate` keyframes when `autoplay`
94
+ * is enabled, then bind the gesture options.
95
+ */
96
+ mounted(): Promise<void>;
97
+ /**
98
+ * Whether the options declare an animation to play — the gate for
99
+ * `autoplay`. Subclasses building their animation from another source
100
+ * (e.g. `MotionSequence` from its children) override this.
101
+ * @protected
102
+ */
103
+ get __hasDeclaredAnimation(): boolean;
104
+ /**
105
+ * Stop the current animation and release the gesture bindings on destroy,
106
+ * keeping the styles the animation reached.
107
+ */
108
+ destroyed(): void;
109
+ /**
110
+ * Play the animation declared by the `animate` and `transition` options
111
+ * forward, creating it on first play — or recreating it when an imperative
112
+ * `animate()` call superseded it. Restarts a finished animation. The
113
+ * returned promise resolves when the animation settles.
114
+ */
115
+ play(): Promise<void>;
116
+ /**
117
+ * Play the animation declared by the options backward. When nothing has
118
+ * played yet — or when an imperative `animate()` call superseded the
119
+ * declared animation — it is created at its end so it plays back to its
120
+ * starting styles. The returned promise resolves when the animation settles.
121
+ */
122
+ reverse(): Promise<void>;
123
+ /**
124
+ * Pause the current animation in place.
125
+ */
126
+ pause(): void;
127
+ /**
128
+ * Animate to the given keyframes, replacing the current animation. The
129
+ * options are merged over the `transition` option. The returned promise
130
+ * resolves when the animation settles.
131
+ */
132
+ animate(keyframes: DOMKeyframesDefinition, options?: AnimationOptions): Promise<void>;
133
+ /**
134
+ * Seek the current animation to the given progress (0 to 1), creating it
135
+ * paused when nothing has played yet.
136
+ */
137
+ seek(progress: number): Promise<void>;
138
+ /**
139
+ * Stop the current animation, committing the styles it reached. The next
140
+ * `play()` creates a fresh animation.
141
+ */
142
+ stop(): void;
143
+ /**
144
+ * Cancel the current animation, reverting the element to its pre-animation
145
+ * styles. The next `play()` creates a fresh animation.
146
+ */
147
+ cancel(): void;
148
+ /**
149
+ * Jump the current animation to its end state.
150
+ */
151
+ complete(): void;
152
+ /**
153
+ * Bind the `hover`, `press` and `inView` gesture options with Motion's own
154
+ * gesture functions (touch-filtered, keyboard-accessible press, real
155
+ * IntersectionObserver). Nothing binds when an option is empty, so idle
156
+ * elements pay nothing. Gesture animations are transient: they never become
157
+ * the current animation and emit no lifecycle events.
158
+ * @private
159
+ */
160
+ __bindGestures(motion: MotionModule): void;
161
+ /**
162
+ * Animate to a gesture state, alongside — not replacing — the current
163
+ * animation, capturing the base value of every property it touches first.
164
+ * @private
165
+ */
166
+ __startGesture(keyframes: DOMKeyframesDefinition): AnimationPlaybackControlsWithThen;
167
+ /**
168
+ * Capture the element's current value for every property a gesture is about
169
+ * to animate, once per property and never refreshed afterwards.
170
+ *
171
+ * The read mirrors Motion's own `VisualElement.readValueFromInstance()`: the
172
+ * parsed transform matrix for a transform property, the computed style
173
+ * otherwise — both through Motion's own readers, so the values come back in
174
+ * the shape its animations expect. Motion React hydrates the same snapshot
175
+ * (its `baseTarget`) the first time it reads a value and keeps it, which is
176
+ * what makes a return immune to a second gesture starting while the previous
177
+ * one is still returning.
178
+ *
179
+ * A property the readers cannot resolve is left out, so nothing is invented:
180
+ * the return animation simply does not touch it.
181
+ * @private
182
+ */
183
+ __captureBaseValues(keyframes: DOMKeyframesDefinition): void;
184
+ /**
185
+ * Return the element to its base values when a gesture ends, animating
186
+ * forward with the `transition` option — the gesture animation is never
187
+ * rewound.
188
+ *
189
+ * This is what Motion React does: ending a gesture deactivates its variant
190
+ * (`node.animationState.setActive("whileHover", false)`), which recomputes
191
+ * the target of every property the variant owned and animates to it. Playing
192
+ * the gesture animation backward instead would run its easing or spring
193
+ * curve in reverse — a different feel — and could never reach a base value
194
+ * the element did not hold when the gesture started.
195
+ * @private
196
+ */
197
+ __revertGesture(keyframes: DOMKeyframesDefinition): void;
198
+ /**
199
+ * Warn about a gesture option the resolved motion module cannot honor.
200
+ * @private
201
+ */
202
+ __warnMissingGesture(name: string): void;
203
+ /**
204
+ * Create the animation from the `animate` and `transition` options and make
205
+ * it the current one. Subclasses override this to build the current
206
+ * animation from another source.
207
+ * @protected
208
+ */
209
+ __createControls(): AnimationPlaybackControlsWithThen;
210
+ /**
211
+ * The keyframes of the declared animation, with the `initial` styles folded
212
+ * in as the starting point of every property they both describe.
213
+ *
214
+ * Motion reads a lone target value as "from wherever the element is now", so
215
+ * a settled animation would have nothing left to move on the next `play()`.
216
+ * Pairing each such value with its `initial` counterpart pins the start, and
217
+ * the animation replays identically for as long as the options stand. A
218
+ * property already written as a `[from, to]` array is left untouched, and so
219
+ * is one the `initial` styles say nothing about — there, animating from the
220
+ * current state is the point.
221
+ */
222
+ get keyframes(): DOMKeyframesDefinition;
223
+ /**
224
+ * Emit `motion-complete` when the given animation finishes, unless another
225
+ * playback superseded it in the meantime. The returned promise resolves when
226
+ * the animation settles and never rejects, so playback methods can safely
227
+ * hand it to callers that do not catch.
228
+ * @private
229
+ */
230
+ __watchCompletion(controls: AnimationPlaybackControlsWithThen): Promise<void>;
231
+ /**
232
+ * Dispatch a bubbling event so an ancestor `Action` can catch and route it.
233
+ * @private
234
+ */
235
+ __dispatch(name: string, ...detail: unknown[]): void;
236
+ }
237
+ //#endregion
238
+ export { Motion, Motion as default, MotionProps };