@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 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
@@ -1,7 +1,7 @@
1
1
  /** The autoload catalog for every declarative `@studiometa/ui-motion` component. */
2
2
  const catalog = {
3
3
  packageName: "@studiometa/ui-motion",
4
- strategy: "visible",
4
+ strategy: "eager",
5
5
  components: [
6
6
  {
7
7
  token: "Motion",
@@ -1 +1 @@
1
- {"version":3,"file":"catalog.js","names":[],"sources":["../src/catalog.ts"],"sourcesContent":["import type { ComponentCatalog, CuratedComponentMetadata } 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.\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: 'visible',\n components,\n abstractExports: [],\n};\n"],"mappings":";AAaA,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"}
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: "visible",
4
+ mountStrategy: "eager",
5
5
  load: () => import("./Motion.js").then(({ Motion }) => Motion)
6
6
  },
7
7
  MotionScrollTimeline: {
8
- mountStrategy: "visible",
8
+ mountStrategy: "eager",
9
9
  load: () => import("./MotionScrollTimeline.js").then(({ MotionScrollTimeline }) => MotionScrollTimeline)
10
10
  },
11
11
  MotionSequence: {
12
- mountStrategy: "visible",
12
+ mountStrategy: "eager",
13
13
  load: () => import("./MotionSequence.js").then(({ MotionSequence }) => MotionSequence)
14
14
  },
15
15
  MotionView: {
16
- mountStrategy: "visible",
16
+ mountStrategy: "eager",
17
17
  load: () => import("./MotionView.js").then(({ MotionView }) => MotionView)
18
18
  }
19
19
  };
@@ -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: 'visible',\n load: () => import('./Motion.js').then(({ Motion }) => Motion),\n },\n MotionScrollTimeline: {\n mountStrategy: 'visible',\n load: () =>\n import('./MotionScrollTimeline.js').then(({ MotionScrollTimeline }) => MotionScrollTimeline),\n },\n MotionSequence: {\n mountStrategy: 'visible',\n load: () => import('./MotionSequence.js').then(({ MotionSequence }) => MotionSequence),\n },\n MotionView: {\n mountStrategy: 'visible',\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"}
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
- * they share, and the abstract exports that are intentionally excluded from the manifest.
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.0",
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
+ ```