@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
package/README.md
CHANGED
|
@@ -80,6 +80,16 @@ Once provided, `@studiometa/ui-motion` never imports `motion` by specifier — i
|
|
|
80
80
|
|
|
81
81
|
Heads up to [ui.studiometa.dev](https://ui.studiometa.dev/reference/items/Motion/) for the full documentation.
|
|
82
82
|
|
|
83
|
+
## Agent skills
|
|
84
|
+
|
|
85
|
+
The package ships the `studiometa-ui-motion` [agent skill](https://agentskills.io). The skill teaches coding agents how to use the package, and it matches the installed version. Link the skills of your dependencies into your project with the [`skills` CLI](https://github.com/vercel-labs/skills):
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
npx skills experimental_sync
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The command links each skill from `node_modules` into the agent folders (`.agents/skills/`, `.claude/skills/`…). When you update the package, the linked skill updates too. The command also links the `studiometa-js-toolkit` skill when your version of `@studiometa/js-toolkit` ships it.
|
|
92
|
+
|
|
83
93
|
## Contributing
|
|
84
94
|
|
|
85
95
|
Please read the [contribution docs](https://ui.studiometa.dev/guide/contributing/).
|
package/dist/catalog.js
CHANGED
package/dist/catalog.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"catalog.js","names":[],"sources":["../src/catalog.ts"],"sourcesContent":["import type {
|
|
1
|
+
{"version":3,"file":"catalog.js","names":[],"sources":["../src/catalog.ts"],"sourcesContent":["import type {\n ComponentCatalog,\n CuratedComponentMetadata,\n} from '../../../scripts/manifest-types.js';\n\n// Motion is external (import-map resolved) and never bundled, so the component\n// declares neither a CDN-served stylesheet nor a bundled integration chunk —\n// consumers load the Motion JavaScript from the source their import map points at.\n//\n// Every component is `eager`: it mounts because its element is on the page,\n// which is also the strategy its class declares by default, so the manifest\n// and the class agree for every element. A viewport strategy fails each of\n// them:\n//\n// - `Motion` applies its `initial` styles on mount, so they must be in place\n// before the element is first seen, or the final state flashes. A `Motion`\n// inside a closed `<dialog>` must also exist before the dialog opens, for an\n// `Action` that plays it. Viewport-driven playback is its `inView` option.\n// - `MotionScrollTimeline` links its `Motion` children once, when it mounts,\n// and a child deep in a tall timeline is far below the viewport then.\n// `MotionSequence` builds its animation from its children the same way.\n// - `MotionView` changes its element's visibility: its `leaveTo` class often\n// starts it out not rendered, and it must already listen when a containing\n// `Dialog` opens or a descendant announces a DOM update.\n//\n// `MotionView` imports the Motion library only on its first `update()`; the\n// other components import it on mount.\nconst components: readonly CuratedComponentMetadata[] = [\n { token: 'Motion', group: 'motion' },\n { token: 'MotionScrollTimeline', group: 'motion', children: ['Motion'] },\n { token: 'MotionSequence', group: 'motion', children: ['Motion'] },\n { token: 'MotionView', group: 'motion' },\n];\n\n/** The autoload catalog for every declarative `@studiometa/ui-motion` component. */\nexport const catalog: ComponentCatalog = {\n packageName: '@studiometa/ui-motion',\n strategy: 'eager',\n components,\n abstractExports: [],\n};\n"],"mappings":";AAmCA,MAAa,UAA4B;CACvC,aAAa;CACb,UAAU;CACV,YAXsD;EACtD;GAAE,OAAO;GAAU,OAAO;GAAU;EACpC;GAAE,OAAO;GAAwB,OAAO;GAAU,UAAU,CAAC,SAAS;GAAE;EACxE;GAAE,OAAO;GAAkB,OAAO;GAAU,UAAU,CAAC,SAAS;GAAE;EAClE;GAAE,OAAO;GAAc,OAAO;GAAU;EACzC;CAOC,iBAAiB,EAAE;CACpB"}
|
package/dist/manifest.js
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
//#region src/manifest.ts
|
|
2
2
|
const manifest = {
|
|
3
3
|
Motion: {
|
|
4
|
-
mountStrategy: "
|
|
4
|
+
mountStrategy: "eager",
|
|
5
5
|
load: () => import("./Motion.js").then(({ Motion }) => Motion)
|
|
6
6
|
},
|
|
7
7
|
MotionScrollTimeline: {
|
|
8
|
-
mountStrategy: "
|
|
8
|
+
mountStrategy: "eager",
|
|
9
9
|
load: () => import("./MotionScrollTimeline.js").then(({ MotionScrollTimeline }) => MotionScrollTimeline)
|
|
10
10
|
},
|
|
11
11
|
MotionSequence: {
|
|
12
|
-
mountStrategy: "
|
|
12
|
+
mountStrategy: "eager",
|
|
13
13
|
load: () => import("./MotionSequence.js").then(({ MotionSequence }) => MotionSequence)
|
|
14
14
|
},
|
|
15
15
|
MotionView: {
|
|
16
|
-
mountStrategy: "
|
|
16
|
+
mountStrategy: "eager",
|
|
17
17
|
load: () => import("./MotionView.js").then(({ MotionView }) => MotionView)
|
|
18
18
|
}
|
|
19
19
|
};
|
package/dist/manifest.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"manifest.js","names":[],"sources":["../src/manifest.ts"],"sourcesContent":["// This file is generated by scripts/generate-manifests.ts. Do not edit.\nimport type { ComponentManifest } from '@studiometa/js-toolkit';\n\nexport const manifest: ComponentManifest = {\n Motion: {\n mountStrategy: '
|
|
1
|
+
{"version":3,"file":"manifest.js","names":[],"sources":["../src/manifest.ts"],"sourcesContent":["// This file is generated by scripts/generate-manifests.ts. Do not edit.\nimport type { ComponentManifest } from '@studiometa/js-toolkit';\n\nexport const manifest: ComponentManifest = {\n Motion: {\n mountStrategy: 'eager',\n load: () => import('./Motion.js').then(({ Motion }) => Motion),\n },\n MotionScrollTimeline: {\n mountStrategy: 'eager',\n load: () =>\n import('./MotionScrollTimeline.js').then(({ MotionScrollTimeline }) => MotionScrollTimeline),\n },\n MotionSequence: {\n mountStrategy: 'eager',\n load: () => import('./MotionSequence.js').then(({ MotionSequence }) => MotionSequence),\n },\n MotionView: {\n mountStrategy: 'eager',\n load: () => import('./MotionView.js').then(({ MotionView }) => MotionView),\n },\n};\n"],"mappings":";AAGA,MAAa,WAA8B;CACzC,QAAQ;EACN,eAAe;EACf,YAAY,OAAO,eAAe,MAAM,EAAE,aAAa,OAAO;EAC/D;CACD,sBAAsB;EACpB,eAAe;EACf,YACE,OAAO,6BAA6B,MAAM,EAAE,2BAA2B,qBAAqB;EAC/F;CACD,gBAAgB;EACd,eAAe;EACf,YAAY,OAAO,uBAAuB,MAAM,EAAE,qBAAqB,eAAe;EACvF;CACD,YAAY;EACV,eAAe;EACf,YAAY,OAAO,mBAAmB,MAAM,EAAE,iBAAiB,WAAW;EAC3E;CACF"}
|
|
@@ -11,7 +11,8 @@ import { MountStrategy } from "@studiometa/js-toolkit";
|
|
|
11
11
|
*/
|
|
12
12
|
/**
|
|
13
13
|
* Curated authoring metadata for a single component, consumed by the manifest generator. The
|
|
14
|
-
* `subpath` and `exportName` default to the `token` when omitted
|
|
14
|
+
* `subpath` and `exportName` default to the `token` when omitted, and `strategy` defaults to the
|
|
15
|
+
* one the catalog declares for the whole package.
|
|
15
16
|
*/
|
|
16
17
|
interface CuratedComponentMetadata {
|
|
17
18
|
token: string;
|
|
@@ -21,10 +22,12 @@ interface CuratedComponentMetadata {
|
|
|
21
22
|
integrations?: readonly string[];
|
|
22
23
|
subpath?: string;
|
|
23
24
|
exportName?: string;
|
|
25
|
+
strategy?: MountStrategy;
|
|
24
26
|
}
|
|
25
27
|
/**
|
|
26
28
|
* The authoring catalog for a component package: the list of its components, the default strategy
|
|
27
|
-
*
|
|
29
|
+
* a component inherits when it declares none of its own, and the abstract exports that are
|
|
30
|
+
* intentionally excluded from the manifest.
|
|
28
31
|
*/
|
|
29
32
|
interface ComponentCatalog {
|
|
30
33
|
packageName: string;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@studiometa/ui-motion",
|
|
3
|
-
"version": "2.0.0-alpha.
|
|
3
|
+
"version": "2.0.0-alpha.2",
|
|
4
4
|
"description": "Vanilla js-toolkit components to animate elements declaratively with Motion",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
@@ -59,7 +59,8 @@
|
|
|
59
59
|
}
|
|
60
60
|
},
|
|
61
61
|
"scripts": {
|
|
62
|
-
"build": "node scripts/build.js"
|
|
62
|
+
"build": "node scripts/build.js && npm run build:skills",
|
|
63
|
+
"build:skills": "node ../../scripts/build-skills.ts"
|
|
63
64
|
},
|
|
64
65
|
"repository": {
|
|
65
66
|
"type": "git",
|
|
@@ -89,7 +90,11 @@
|
|
|
89
90
|
},
|
|
90
91
|
"files": [
|
|
91
92
|
"dist",
|
|
93
|
+
"skills",
|
|
92
94
|
"README.md",
|
|
93
95
|
"LICENSE.md"
|
|
96
|
+
],
|
|
97
|
+
"skills": [
|
|
98
|
+
"npm:@studiometa/js-toolkit"
|
|
94
99
|
]
|
|
95
100
|
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: studiometa-ui-motion
|
|
3
|
+
description: Animate elements declaratively with @studiometa/ui-motion v2 — Motion, MotionSequence, MotionScrollTimeline and MotionView components powered by motion.dev on @studiometa/js-toolkit v4. Use when code imports @studiometa/ui-motion, when markup uses data-component="Motion" or another Motion* component, or when a page needs keyframe, spring, gesture, sequence or scroll-driven animations.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @studiometa/ui-motion
|
|
7
|
+
|
|
8
|
+
`@studiometa/ui-motion` wraps [Motion](https://motion.dev) in components that you configure from HTML. Options are Motion keyframes and transitions written as JSON.
|
|
9
|
+
|
|
10
|
+
This skill matches the installed package version. Read the references in this folder before the online docs.
|
|
11
|
+
|
|
12
|
+
## References
|
|
13
|
+
|
|
14
|
+
- [references/index.md](references/index.md): the items of the package.
|
|
15
|
+
- `references/items/Motion/`: one animation with its playback API and gestures.
|
|
16
|
+
- `references/items/MotionSequence/`: several `Motion` children on one timeline (`at` positions or `stagger`).
|
|
17
|
+
- `references/items/MotionScrollTimeline/`: animations bound to the scroll progress of a wrapper.
|
|
18
|
+
- `references/items/MotionView/`: DOM updates animated with Motion `animateView()`, an alternative to the `ViewTransition` component of `@studiometa/ui`.
|
|
19
|
+
|
|
20
|
+
## Install and register
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install @studiometa/ui-motion motion
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
```js
|
|
27
|
+
import { registerComponent } from '@studiometa/js-toolkit';
|
|
28
|
+
import { Motion } from '@studiometa/ui-motion';
|
|
29
|
+
|
|
30
|
+
registerComponent(Motion);
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```html
|
|
34
|
+
<div
|
|
35
|
+
data-component="Motion"
|
|
36
|
+
data-option-initial='{ "opacity": 0, "y": 24 }'
|
|
37
|
+
data-option-animate='{ "opacity": 1, "y": 0 }'
|
|
38
|
+
data-option-transition='{ "type": "spring", "bounce": 0.3 }'
|
|
39
|
+
data-option-autoplay>
|
|
40
|
+
Hello world!
|
|
41
|
+
</div>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Rules
|
|
45
|
+
|
|
46
|
+
- Option values are JSON: quote all object keys and use single quotes around the attribute.
|
|
47
|
+
- Only use options that Motion supports. Read the item `js-api.md`: do not add options from other animation libraries.
|
|
48
|
+
- `initial` sets the start state on mount. `animate` plays only with `data-option-autoplay` or when a method starts it.
|
|
49
|
+
- Drive the playback with `Action`: `data-on:click="Motion->target.play()"`. The methods are `play()`, `pause()`, `reverse()`, `seek(progress)`, `stop()`, `cancel()`, `complete()` and `animate(keyframes, options)`.
|
|
50
|
+
- `hover`, `press` and `inView` options apply keyframes while the state holds, then revert.
|
|
51
|
+
- The component emits bubbling `motion-play`, `motion-pause`, `motion-complete`, `motion-cancel` and `motion-stop` events.
|
|
52
|
+
- In a `MotionSequence`, leave `autoplay` off on the children and set it on the sequence.
|
|
53
|
+
|
|
54
|
+
## Loading motion
|
|
55
|
+
|
|
56
|
+
`motion` loads with a dynamic `import()` when the first animation is built. To use another entry (for example `motion/mini`), inject it once before the components mount:
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
import { animate } from 'motion/mini';
|
|
60
|
+
import { provideMotion } from '@studiometa/ui-motion';
|
|
61
|
+
|
|
62
|
+
provideMotion({ animate });
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Related skills
|
|
66
|
+
|
|
67
|
+
- `studiometa-ui`: `Action`, `Transition`, `ViewTransition` and the shared markup rules.
|
|
68
|
+
- `studiometa-js-toolkit`: the `Base` class and the component lifecycle.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# @studiometa/ui-motion reference
|
|
2
|
+
|
|
3
|
+
Each item folder holds `index.md` (usage), `js-api.md` or `twig-api.md` (API) and `examples.md` when the docs have them.
|
|
4
|
+
|
|
5
|
+
| Item | Kind | Summary |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| [Motion](items/Motion/index.md) | component | Animate elements declaratively with Motion and drive the playback from interactions. |
|
|
8
|
+
| [MotionScrollTimeline](items/MotionScrollTimeline/index.md) | component | Drive the Motion children of an element with its scroll progress. |
|
|
9
|
+
| [MotionSequence](items/MotionSequence/index.md) | component | Compose Motion children into a single staggered animation timeline. |
|
|
10
|
+
| [MotionView](items/MotionView/index.md) | component | Play DOM updates as view transitions declared with Motion keyframes. |
|
|
@@ -0,0 +1,380 @@
|
|
|
1
|
+
# Examples
|
|
2
|
+
|
|
3
|
+
## Action-driven playback
|
|
4
|
+
|
|
5
|
+
Autoplay is off by default, so the card only moves when asked to. The buttons are [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) components targeting the `Motion` instance with the arrow syntax, the hover pattern combines `play()` and `reverse()` for a symmetric in/out animation, and the last button runs a one-off spin with `animate()` — clicking Play afterwards returns to the animation declared by the options.
|
|
6
|
+
|
|
7
|
+
```twig
|
|
8
|
+
<div class="grid gap-4 justify-items-start">
|
|
9
|
+
<div
|
|
10
|
+
data-component="Motion"
|
|
11
|
+
data-option-animate='{ "x": 160, "rotate": 10 }'
|
|
12
|
+
data-option-transition='{ "type": "spring", "bounce": 0.4 }'
|
|
13
|
+
class="px-6 py-4 rounded-lg bg-blue-400 dark:bg-blue-600 text-white font-bold">
|
|
14
|
+
Drive me!
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+
<div class="flex gap-2">
|
|
18
|
+
<button
|
|
19
|
+
type="button"
|
|
20
|
+
data-component="Action"
|
|
21
|
+
data-on:click="Motion->target.play()"
|
|
22
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
23
|
+
Play
|
|
24
|
+
</button>
|
|
25
|
+
<button
|
|
26
|
+
type="button"
|
|
27
|
+
data-component="Action"
|
|
28
|
+
data-on:click="Motion->target.reverse()"
|
|
29
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
30
|
+
Reverse
|
|
31
|
+
</button>
|
|
32
|
+
<button
|
|
33
|
+
type="button"
|
|
34
|
+
data-component="Action"
|
|
35
|
+
data-on:mouseenter="Motion->target.play()"
|
|
36
|
+
data-on:mouseleave="Motion->target.reverse()"
|
|
37
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
38
|
+
Hover me
|
|
39
|
+
</button>
|
|
40
|
+
<button
|
|
41
|
+
type="button"
|
|
42
|
+
data-component="Action"
|
|
43
|
+
data-on:click="Motion->target.animate({ rotate: 360, x: 0 }, { duration: 1 })"
|
|
44
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
45
|
+
Spin back
|
|
46
|
+
</button>
|
|
47
|
+
</div>
|
|
48
|
+
</div>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```js
|
|
52
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
53
|
+
import { Action } from '@studiometa/ui';
|
|
54
|
+
import { Motion } from '@studiometa/ui-motion';
|
|
55
|
+
|
|
56
|
+
registerComponents(Action, Motion);
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Full playback control
|
|
60
|
+
|
|
61
|
+
Every playback method on one animation: `play()`, `pause()`, `reverse()`, `stop()`, `cancel()` and `complete()`, plus a range input scrubbing through the animation with `seek()`. Stop commits the styles the element reached, while cancel reverts it to its pre-animation styles.
|
|
62
|
+
|
|
63
|
+
```twig
|
|
64
|
+
<div class="grid gap-4 justify-items-start">
|
|
65
|
+
<div
|
|
66
|
+
data-component="Motion"
|
|
67
|
+
data-option-animate='{ "x": 200, "rotate": 180 }'
|
|
68
|
+
data-option-transition='{ "duration": 2, "ease": "easeInOut" }'
|
|
69
|
+
class="size-16 rounded-lg bg-blue-400 dark:bg-blue-600"></div>
|
|
70
|
+
|
|
71
|
+
<div class="flex flex-wrap gap-2">
|
|
72
|
+
<button
|
|
73
|
+
type="button"
|
|
74
|
+
data-component="Action"
|
|
75
|
+
data-on:click="Motion->target.play()"
|
|
76
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
77
|
+
Play
|
|
78
|
+
</button>
|
|
79
|
+
<button
|
|
80
|
+
type="button"
|
|
81
|
+
data-component="Action"
|
|
82
|
+
data-on:click="Motion->target.pause()"
|
|
83
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
84
|
+
Pause
|
|
85
|
+
</button>
|
|
86
|
+
<button
|
|
87
|
+
type="button"
|
|
88
|
+
data-component="Action"
|
|
89
|
+
data-on:click="Motion->target.reverse()"
|
|
90
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
91
|
+
Reverse
|
|
92
|
+
</button>
|
|
93
|
+
<button
|
|
94
|
+
type="button"
|
|
95
|
+
data-component="Action"
|
|
96
|
+
data-on:click="Motion->target.stop()"
|
|
97
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
98
|
+
Stop
|
|
99
|
+
</button>
|
|
100
|
+
<button
|
|
101
|
+
type="button"
|
|
102
|
+
data-component="Action"
|
|
103
|
+
data-on:click="Motion->target.cancel()"
|
|
104
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
105
|
+
Cancel
|
|
106
|
+
</button>
|
|
107
|
+
<button
|
|
108
|
+
type="button"
|
|
109
|
+
data-component="Action"
|
|
110
|
+
data-on:click="Motion->target.complete()"
|
|
111
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
112
|
+
Complete
|
|
113
|
+
</button>
|
|
114
|
+
</div>
|
|
115
|
+
|
|
116
|
+
<label class="flex items-center gap-2">
|
|
117
|
+
Seek<input
|
|
118
|
+
type="range"
|
|
119
|
+
min="0"
|
|
120
|
+
max="100"
|
|
121
|
+
value="0"
|
|
122
|
+
data-component="Action"
|
|
123
|
+
data-on:input="Motion->target.seek(event.target.valueAsNumber / 100)" />
|
|
124
|
+
</label>
|
|
125
|
+
</div>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
```js
|
|
129
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
130
|
+
import { Action } from '@studiometa/ui';
|
|
131
|
+
import { Motion } from '@studiometa/ui-motion';
|
|
132
|
+
|
|
133
|
+
registerComponents(Action, Motion);
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Reacting to events with `DataBind`
|
|
137
|
+
|
|
138
|
+
The `motion-*` events bubble, so a single routing [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) on an ancestor catches all five of them and forwards a label to a [`DataBind`](https://ui-v2.studiometa.dev/reference/items/DataBind/) in a separate subtree — the status text never shares an element with the animation.
|
|
139
|
+
|
|
140
|
+
```twig
|
|
141
|
+
<div
|
|
142
|
+
data-component="Action"
|
|
143
|
+
data-on:motion-play="DataBind->target.set('playing')"
|
|
144
|
+
data-on:motion-pause="DataBind->target.set('paused')"
|
|
145
|
+
data-on:motion-complete="DataBind->target.set('complete')"
|
|
146
|
+
data-on:motion-stop="DataBind->target.set('stopped')"
|
|
147
|
+
data-on:motion-cancel="DataBind->target.set('cancelled')"
|
|
148
|
+
class="grid gap-4 justify-items-start">
|
|
149
|
+
<div
|
|
150
|
+
data-component="Motion"
|
|
151
|
+
data-option-animate='{ "x": 160 }'
|
|
152
|
+
data-option-transition='{ "duration": 1.5 }'
|
|
153
|
+
class="px-6 py-4 rounded-lg bg-blue-400 dark:bg-blue-600 text-white font-bold">
|
|
154
|
+
Watch my status
|
|
155
|
+
</div>
|
|
156
|
+
|
|
157
|
+
<div class="flex flex-wrap gap-2">
|
|
158
|
+
<button
|
|
159
|
+
type="button"
|
|
160
|
+
data-component="Action"
|
|
161
|
+
data-on:click="Motion->target.play()"
|
|
162
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
163
|
+
Play
|
|
164
|
+
</button>
|
|
165
|
+
<button
|
|
166
|
+
type="button"
|
|
167
|
+
data-component="Action"
|
|
168
|
+
data-on:click="Motion->target.pause()"
|
|
169
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
170
|
+
Pause
|
|
171
|
+
</button>
|
|
172
|
+
<button
|
|
173
|
+
type="button"
|
|
174
|
+
data-component="Action"
|
|
175
|
+
data-on:click="Motion->target.stop()"
|
|
176
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
177
|
+
Stop
|
|
178
|
+
</button>
|
|
179
|
+
<button
|
|
180
|
+
type="button"
|
|
181
|
+
data-component="Action"
|
|
182
|
+
data-on:click="Motion->target.cancel()"
|
|
183
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
184
|
+
Cancel
|
|
185
|
+
</button>
|
|
186
|
+
</div>
|
|
187
|
+
|
|
188
|
+
<p>
|
|
189
|
+
Status: <strong data-component="DataBind">idle</strong>
|
|
190
|
+
</p>
|
|
191
|
+
</div>
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
```js
|
|
195
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
196
|
+
import { Action, DataBind } from '@studiometa/ui';
|
|
197
|
+
import { Motion } from '@studiometa/ui-motion';
|
|
198
|
+
|
|
199
|
+
registerComponents(Action, DataBind, Motion);
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Gestures
|
|
203
|
+
|
|
204
|
+
The `hover`, `press` and `inView` options apply keyframes while their state holds, through Motion's own gesture functions: hover filters out touch emulation, press responds to pointer and keyboard alike, and in-view uses a real `IntersectionObserver`. When the state ends, a new animation plays forward to the base values of the properties the gesture touched — the base values are read from the element itself, so there is nothing to declare.
|
|
205
|
+
|
|
206
|
+
```twig
|
|
207
|
+
<div class="grid gap-4 justify-items-start">
|
|
208
|
+
<div
|
|
209
|
+
data-component="Motion"
|
|
210
|
+
data-option-hover='{ "scale": 1.1, "rotate": -2 }'
|
|
211
|
+
data-option-transition='{ "type": "spring", "bounce": 0.5 }'
|
|
212
|
+
class="px-6 py-4 rounded-lg bg-blue-400 dark:bg-blue-600 text-white font-bold">
|
|
213
|
+
Hover me
|
|
214
|
+
</div>
|
|
215
|
+
|
|
216
|
+
<button
|
|
217
|
+
type="button"
|
|
218
|
+
data-component="Motion"
|
|
219
|
+
data-option-press='{ "scale": 0.9 }'
|
|
220
|
+
data-option-transition='{ "type": "spring", "bounce": 0.5 }'
|
|
221
|
+
class="px-6 py-4 rounded-lg bg-zinc-200 dark:bg-zinc-800 font-bold">
|
|
222
|
+
Press me (pointer or keyboard)
|
|
223
|
+
</button>
|
|
224
|
+
|
|
225
|
+
<p class="pt-[80vh] text-current/60">
|
|
226
|
+
Scroll down for the in-view reveal ↓
|
|
227
|
+
</p>
|
|
228
|
+
|
|
229
|
+
<div
|
|
230
|
+
data-component="Motion"
|
|
231
|
+
data-option-initial='{ "opacity": 0, "y": 32 }'
|
|
232
|
+
data-option-in-view='{ "opacity": 1, "y": 0 }'
|
|
233
|
+
data-option-in-view-amount="0.5"
|
|
234
|
+
data-option-transition='{ "type": "spring", "bounce": 0.3 }'
|
|
235
|
+
class="px-6 py-4 rounded-lg bg-emerald-400 dark:bg-emerald-600 text-white font-bold">
|
|
236
|
+
I reveal in view, and return when I leave
|
|
237
|
+
</div>
|
|
238
|
+
|
|
239
|
+
<div class="h-[40vh]"></div>
|
|
240
|
+
</div>
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
```js
|
|
244
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
245
|
+
import { Motion } from '@studiometa/ui-motion';
|
|
246
|
+
|
|
247
|
+
registerComponents(Motion);
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## Spring entrance and exit for a `Dialog`
|
|
251
|
+
|
|
252
|
+
The [`Dialog`](https://ui-v2.studiometa.dev/reference/items/Dialog/) component handles the top layer, focus and scroll lock, and both its lifecycle events bubble, so an [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) can route them: the `open` event plays a spring entrance on the `Motion` box and the `close` event plays it in reverse — physics a CSS transition cannot express. Every closing interaction (button, backdrop, <kbd>Esc</kbd>) just calls `Dialog.close()`.
|
|
253
|
+
|
|
254
|
+
A `Motion` is not one of the dialog's [transition children](https://ui-v2.studiometa.dev/reference/items/Dialog/js-api#what-the-dialog-waits-for), so the exit would be cut off when the native dialog hides. Handing each animation to [`event.detail.waitUntil()`](https://ui-v2.studiometa.dev/reference/items/Dialog/js-api#extending-the-lifecycle-with-waituntil) is what makes the dialog wait for it.
|
|
255
|
+
|
|
256
|
+
**Guard the `detail`**
|
|
257
|
+
|
|
258
|
+
A `<dialog>` fires its own native `close` event once hidden, which carries no `detail` and shares the name. `event.detail?.waitUntil(…)` skips it — and skips the animation call with it, since an optional chain does not evaluate its arguments.
|
|
259
|
+
|
|
260
|
+
```twig
|
|
261
|
+
<button
|
|
262
|
+
type="button"
|
|
263
|
+
data-component="Action"
|
|
264
|
+
data-on:click="Dialog(#motion-modal)->target.open()"
|
|
265
|
+
class="px-4 py-2 rounded bg-blue-600 text-white font-semibold">
|
|
266
|
+
Open dialog
|
|
267
|
+
</button>
|
|
268
|
+
|
|
269
|
+
{# The <dialog> host carries NO display utility, so its native open/closed
|
|
270
|
+
display (block / none) is preserved. The `open` event plays the box's spring
|
|
271
|
+
entrance and the `close` event plays it in reverse; registering each with
|
|
272
|
+
`detail.waitUntil()` makes the dialog await it, so the exit plays in full
|
|
273
|
+
before the native dialog hides.
|
|
274
|
+
|
|
275
|
+
The `?.` is not decoration: <dialog> fires its own native `close` event once
|
|
276
|
+
hidden, with no detail. The optional chain skips it — and skips the
|
|
277
|
+
`reverse()` call with it. #}
|
|
278
|
+
<dialog
|
|
279
|
+
id="motion-modal"
|
|
280
|
+
data-component="Action Dialog"
|
|
281
|
+
data-on:open="Motion(#motion-modal-box)->event.detail?.waitUntil(target.play())"
|
|
282
|
+
data-on:close="Motion(#motion-modal-box)->event.detail?.waitUntil(target.reverse())"
|
|
283
|
+
data-on:cancel.prevent="Dialog.close()"
|
|
284
|
+
class="fixed inset-0 m-0 p-0 w-full h-full max-w-none max-h-none bg-transparent overflow-y-auto">
|
|
285
|
+
<div
|
|
286
|
+
data-component="Action"
|
|
287
|
+
data-on:click="Dialog(#motion-modal)->target.close()"
|
|
288
|
+
class="fixed inset-0 bg-black/50"></div>
|
|
289
|
+
|
|
290
|
+
<div
|
|
291
|
+
class="pointer-events-none relative flex min-h-full items-center justify-center p-4">
|
|
292
|
+
<div
|
|
293
|
+
id="motion-modal-box"
|
|
294
|
+
data-component="Motion"
|
|
295
|
+
data-option-initial='{ "opacity": 0, "scale": 0.8, "y": 40 }'
|
|
296
|
+
data-option-animate='{ "opacity": 1, "scale": 1, "y": 0 }'
|
|
297
|
+
data-option-transition='{ "type": "spring", "bounce": 0.4 }'
|
|
298
|
+
class="pointer-events-auto relative w-full max-w-lg p-8 rounded-lg bg-white text-black shadow-2xl">
|
|
299
|
+
<h2 class="text-xl font-bold mb-3">Spring entrance and exit</h2>
|
|
300
|
+
<p class="mb-6 text-black/60">
|
|
301
|
+
The <code>Dialog</code> handles the top layer, focus and scroll lock; the
|
|
302
|
+
<code>Motion</code> box springs in on its <code>open</code> event and springs
|
|
303
|
+
back out before the dialog closes, which it waits for — physics a CSS transition
|
|
304
|
+
cannot express.
|
|
305
|
+
</p>
|
|
306
|
+
<button
|
|
307
|
+
type="button"
|
|
308
|
+
data-component="Action"
|
|
309
|
+
data-on:click="Dialog(#motion-modal)->target.close()"
|
|
310
|
+
class="px-4 py-2 rounded bg-gray-900 text-white">
|
|
311
|
+
Close
|
|
312
|
+
</button>
|
|
313
|
+
</div>
|
|
314
|
+
</div>
|
|
315
|
+
</dialog>
|
|
316
|
+
|
|
317
|
+
<style>
|
|
318
|
+
dialog::backdrop { background: transparent; }
|
|
319
|
+
</style>
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
```js
|
|
323
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
324
|
+
import { Action, Dialog } from '@studiometa/ui';
|
|
325
|
+
import { Motion } from '@studiometa/ui-motion';
|
|
326
|
+
|
|
327
|
+
registerComponents(Action, Dialog, Motion);
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
## Scrubbing with `TimerProgress`
|
|
331
|
+
|
|
332
|
+
A single element carries `Action`, `Motion` and [`TimerProgress`](https://ui-v2.studiometa.dev/reference/items/Timer/): the timer emits a `0 → 1` ratio on every frame, and the co-located `Action` hands it to `Motion.seek()`. The effect folds the ratio into a `0 → 1 → 0` triangle wave (`1 - Math.abs(2 * ratio - 1)`), so one timer cycle yoyos the animation out and back — a looping, pausable, restartable timeline without a line of custom JavaScript. For a plain forward loop, pass the ratio through unchanged; Motion can also yoyo on its own with `data-option-transition='{ "repeat": 10, "repeatType": "reverse" }'`, without any timer.
|
|
333
|
+
|
|
334
|
+
```twig
|
|
335
|
+
<div class="grid gap-4 justify-items-start">
|
|
336
|
+
{# One element carries the whole engine: `TimerProgress` emits a 0 → 1 ratio
|
|
337
|
+
on every frame, and the co-located `Action` folds it into a 0 → 1 → 0
|
|
338
|
+
triangle wave before handing it to `Motion.seek()` — one 8s timer cycle
|
|
339
|
+
yoyos the animation out and back. #}
|
|
340
|
+
<div
|
|
341
|
+
data-component="Action Motion TimerProgress"
|
|
342
|
+
data-option-delay="8"
|
|
343
|
+
data-option-repeat
|
|
344
|
+
data-option-animate='{ "x": 200, "rotate": 360, "borderRadius": "50%" }'
|
|
345
|
+
data-on:timer-progress="Motion.seek(1 - Math.abs(2 * event.detail.ratio - 1))"
|
|
346
|
+
class="size-16 rounded-lg bg-blue-400 dark:bg-blue-600"></div>
|
|
347
|
+
|
|
348
|
+
<div class="flex flex-wrap gap-2">
|
|
349
|
+
<button
|
|
350
|
+
type="button"
|
|
351
|
+
data-component="Action"
|
|
352
|
+
data-on:click="TimerProgress->target.pause()"
|
|
353
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
354
|
+
Pause
|
|
355
|
+
</button>
|
|
356
|
+
<button
|
|
357
|
+
type="button"
|
|
358
|
+
data-component="Action"
|
|
359
|
+
data-on:click="TimerProgress->target.resume()"
|
|
360
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
361
|
+
Resume
|
|
362
|
+
</button>
|
|
363
|
+
<button
|
|
364
|
+
type="button"
|
|
365
|
+
data-component="Action"
|
|
366
|
+
data-on:click="TimerProgress->target.restart()"
|
|
367
|
+
class="px-4 py-2 rounded bg-zinc-200 dark:bg-zinc-800">
|
|
368
|
+
Restart
|
|
369
|
+
</button>
|
|
370
|
+
</div>
|
|
371
|
+
</div>
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
```js
|
|
375
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
376
|
+
import { Action, TimerProgress } from '@studiometa/ui';
|
|
377
|
+
import { Motion } from '@studiometa/ui-motion';
|
|
378
|
+
|
|
379
|
+
registerComponents(Action, TimerProgress, Motion);
|
|
380
|
+
```
|