@cognitap/radiant 0.0.5 → 0.0.6

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.
Files changed (127) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +8 -0
  3. package/dist/library/Button.d.ts +3 -1
  4. package/dist/library/Button.d.ts.map +1 -1
  5. package/dist/library/Button.js +43 -2
  6. package/dist/library/Button.js.map +1 -1
  7. package/dist/library/Collapsible.d.ts +2 -1
  8. package/dist/library/Collapsible.d.ts.map +1 -1
  9. package/dist/library/Collapsible.js +5 -2
  10. package/dist/library/Collapsible.js.map +1 -1
  11. package/dist/library/Dialog.d.ts +2 -1
  12. package/dist/library/Dialog.d.ts.map +1 -1
  13. package/dist/library/Dialog.js +5 -2
  14. package/dist/library/Dialog.js.map +1 -1
  15. package/dist/library/ThemeScope.d.ts.map +1 -1
  16. package/dist/library/ThemeScope.js +10 -9
  17. package/dist/library/ThemeScope.js.map +1 -1
  18. package/dist/library/index.d.ts +3 -1
  19. package/dist/library/index.d.ts.map +1 -1
  20. package/dist/library/index.js +1 -0
  21. package/dist/library/index.js.map +1 -1
  22. package/dist/library/motion/MotionLink.d.ts +7 -0
  23. package/dist/library/motion/MotionLink.d.ts.map +1 -0
  24. package/dist/library/motion/MotionLink.js +45 -0
  25. package/dist/library/motion/MotionLink.js.map +1 -0
  26. package/dist/library/motion/browser.d.ts +5 -0
  27. package/dist/library/motion/browser.d.ts.map +1 -0
  28. package/dist/library/motion/browser.js +35 -0
  29. package/dist/library/motion/browser.js.map +1 -0
  30. package/dist/library/motion/config.d.ts +26 -0
  31. package/dist/library/motion/config.d.ts.map +1 -0
  32. package/dist/library/motion/config.js +58 -0
  33. package/dist/library/motion/config.js.map +1 -0
  34. package/dist/library/motion/context.d.ts +2 -0
  35. package/dist/library/motion/context.d.ts.map +1 -0
  36. package/dist/library/motion/context.js +5 -0
  37. package/dist/library/motion/context.js.map +1 -0
  38. package/dist/library/motion/drag.d.ts +20 -0
  39. package/dist/library/motion/drag.d.ts.map +1 -0
  40. package/dist/library/motion/drag.js +138 -0
  41. package/dist/library/motion/drag.js.map +1 -0
  42. package/dist/library/motion/dragBrowser.d.ts +4 -0
  43. package/dist/library/motion/dragBrowser.d.ts.map +1 -0
  44. package/dist/library/motion/dragBrowser.js +156 -0
  45. package/dist/library/motion/dragBrowser.js.map +1 -0
  46. package/dist/library/motion/follow.d.ts +9 -0
  47. package/dist/library/motion/follow.d.ts.map +1 -0
  48. package/dist/library/motion/follow.js +26 -0
  49. package/dist/library/motion/follow.js.map +1 -0
  50. package/dist/library/motion/host.d.ts +27 -0
  51. package/dist/library/motion/host.d.ts.map +1 -0
  52. package/dist/library/motion/host.js +62 -0
  53. package/dist/library/motion/host.js.map +1 -0
  54. package/dist/library/motion/index.d.ts +16 -0
  55. package/dist/library/motion/index.d.ts.map +1 -0
  56. package/dist/library/motion/index.js +9 -0
  57. package/dist/library/motion/index.js.map +1 -0
  58. package/dist/library/motion/layout.d.ts +20 -0
  59. package/dist/library/motion/layout.d.ts.map +1 -0
  60. package/dist/library/motion/layout.js +67 -0
  61. package/dist/library/motion/layout.js.map +1 -0
  62. package/dist/library/motion/layoutDom.d.ts +17 -0
  63. package/dist/library/motion/layoutDom.d.ts.map +1 -0
  64. package/dist/library/motion/layoutDom.js +272 -0
  65. package/dist/library/motion/layoutDom.js.map +1 -0
  66. package/dist/library/motion/press.d.ts +5 -0
  67. package/dist/library/motion/press.d.ts.map +1 -0
  68. package/dist/library/motion/press.js +72 -0
  69. package/dist/library/motion/press.js.map +1 -0
  70. package/dist/library/motion/pressPolicy.d.ts +5 -0
  71. package/dist/library/motion/pressPolicy.d.ts.map +1 -0
  72. package/dist/library/motion/pressPolicy.js +8 -0
  73. package/dist/library/motion/pressPolicy.js.map +1 -0
  74. package/dist/library/motion/react.d.ts +35 -0
  75. package/dist/library/motion/react.d.ts.map +1 -0
  76. package/dist/library/motion/react.js +224 -0
  77. package/dist/library/motion/react.js.map +1 -0
  78. package/dist/library/motion/runtime.d.ts +22 -0
  79. package/dist/library/motion/runtime.d.ts.map +1 -0
  80. package/dist/library/motion/runtime.js +117 -0
  81. package/dist/library/motion/runtime.js.map +1 -0
  82. package/dist/library/motion/transitions.d.ts +5 -0
  83. package/dist/library/motion/transitions.d.ts.map +1 -0
  84. package/dist/library/motion/transitions.js +211 -0
  85. package/dist/library/motion/transitions.js.map +1 -0
  86. package/dist/library/styles.css +1 -1
  87. package/dist/library/themes/defineTheme.d.ts +3 -0
  88. package/dist/library/themes/defineTheme.d.ts.map +1 -1
  89. package/dist/library/themes/defineTheme.js +4 -2
  90. package/dist/library/themes/defineTheme.js.map +1 -1
  91. package/dist/library/themes/index.d.ts +1 -1
  92. package/dist/library/themes/index.d.ts.map +1 -1
  93. package/dist/library/themes/index.js.map +1 -1
  94. package/dist/library/themes/themeDocument.d.ts.map +1 -1
  95. package/dist/library/themes/themeDocument.js +11 -5
  96. package/dist/library/themes/themeDocument.js.map +1 -1
  97. package/dist/library/themes/themeDocumentTypes.d.ts +5 -1
  98. package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -1
  99. package/dist/library/themes/themeDocumentTypes.js.map +1 -1
  100. package/docs/motion.md +434 -0
  101. package/docs/system.md +26 -0
  102. package/package.json +14 -3
  103. package/src/Button.tsx +49 -1
  104. package/src/Collapsible.tsx +13 -1
  105. package/src/Dialog.tsx +10 -1
  106. package/src/ThemeScope.tsx +21 -17
  107. package/src/index.ts +9 -0
  108. package/src/motion/MotionLink.tsx +64 -0
  109. package/src/motion/browser.ts +45 -0
  110. package/src/motion/config.ts +79 -0
  111. package/src/motion/context.ts +4 -0
  112. package/src/motion/drag.ts +151 -0
  113. package/src/motion/dragBrowser.ts +159 -0
  114. package/src/motion/follow.ts +28 -0
  115. package/src/motion/host.ts +88 -0
  116. package/src/motion/index.ts +28 -0
  117. package/src/motion/layout.ts +78 -0
  118. package/src/motion/layoutDom.ts +293 -0
  119. package/src/motion/press.ts +77 -0
  120. package/src/motion/pressPolicy.ts +12 -0
  121. package/src/motion/react.ts +272 -0
  122. package/src/motion/runtime.ts +122 -0
  123. package/src/motion/transitions.ts +206 -0
  124. package/src/themes/defineTheme.ts +10 -2
  125. package/src/themes/index.ts +1 -0
  126. package/src/themes/themeDocument.ts +14 -6
  127. package/src/themes/themeDocumentTypes.ts +12 -5
package/docs/motion.md ADDED
@@ -0,0 +1,434 @@
1
+ # Spring motion runtime
2
+
3
+ Radiant uses Motion 14.7.1 physics with a Radiant-owned layout adapter, as recorded
4
+ in the [accepted engine decision](adr/0001-spring-engine-boundaries.md). These APIs
5
+ are experimental in 0.x. Opt-in bindings cover native Button, disclosure/Dialog,
6
+ drag/snap, changing-target values and measured layout groups. Importing numeric
7
+ interfaces alone does not enable native component motion.
8
+
9
+ ## Theme configuration
10
+
11
+ ```tsx
12
+ import {defineTheme, ThemeScope} from '@cognitap/radiant'
13
+
14
+ const theme = defineTheme({
15
+ id: 'brand', name: 'Brand',
16
+ motion: {
17
+ mode: 'system',
18
+ spring: {stiffness: 320, damping: 30, mass: 1},
19
+ interactions: {press: {stiffness: 400, damping: 34}}
20
+ }
21
+ })
22
+
23
+ <ThemeScope theme={theme}>{children}</ThemeScope>
24
+ ```
25
+
26
+ Profiles are validated, immutable, JSON-serializable data. Omitted values resolve
27
+ to a restrained spring (320/30/1); named interactions are `press`, `disclosure`,
28
+ `dialog`, `follow`, `drag` and `layout`. Each interaction inherits the common spring
29
+ and accepts individual overrides. Stiffness/damping must be positive and at most
30
+ 10,000; mass must be positive and at most 100. Zero damping is excluded so every
31
+ accepted spring can settle. `mode: 'off'` disables spatial motion. System reduced
32
+ motion always wins; there is no forced-animation override.
33
+
34
+ A nested ThemeScope inherits its selected theme's profile. A new named theme
35
+ resets it; changing light/dark mode does not change physical behavior. Theme
36
+ profiles are available provider-free using the default profile. Theme documents
37
+ retain authoring data at `sections.motion.profile`, independently of legacy
38
+ `sections.motion.values` CSS tokens. Compilation and selective section export
39
+ preserve the profile; the public workshop/handoff UI is DEV-178/179.
40
+
41
+ ## Numeric and browser interfaces
42
+
43
+ ```ts
44
+ import { createSpring, bindSpringStyle } from '@cognitap/radiant/motion'
45
+
46
+ const position = createSpring(0, {
47
+ parameters: theme.motion.interactions.follow,
48
+ enabled: !matchMedia('(prefers-reduced-motion: reduce)').matches
49
+ })
50
+ const unbind = bindSpringStyle(element, position, 'translateX')
51
+ position.to(160)
52
+ position.to(40) // preserve the in-flight position and momentum
53
+ // On preference change: position.configure({enabled: false})
54
+ // On disposal: unbind(); position.destroy()
55
+ ```
56
+
57
+ `createSpring` is framework-neutral and does not read browser preferences or own
58
+ DOM. Its owner supplies and updates `enabled`; React bindings do this automatically.
59
+ `get`, `getVelocity` (units/second), `isAnimating`, `subscribe`, `to`, `jump`,
60
+ `stop`, `configure` and idempotent `destroy` form its supported interface.
61
+ Subscriptions run outside React; disposal removes subscriptions and frame work.
62
+ `stop()` freezes the current presentation and discards the old goal. `jump()` sets
63
+ a new goal immediately with zero velocity. Destroyed controllers ignore further
64
+ writes and never resume. Unsubscribe before discarding a standalone subscriber.
65
+
66
+ All values must be finite numbers in one consistent coordinate/unit system.
67
+ There is no mixed-unit, percentage, auto-size, color, CSS-variable or arbitrary
68
+ transform-string interpolation. Resolve those to numeric values before animating.
69
+ A running follower retains its physics until it rests: `configure({parameters})`
70
+ queues the latest physics, avoiding a velocity reset on profile changes. Target
71
+ changes continue immediately with the current physics. At rest the pending physics
72
+ is applied. Explicit off cancels and snaps to the latest goal, or to `reducedValue`
73
+ (e.g. neutral scale 1). Re-enabling never replays an old gesture or animation;
74
+ a later `to()` starts new work. An explicitly supplied `reducedValue: undefined`
75
+ clears a neutral override.
76
+
77
+ `bindSpringStyle` reserves one property until cleanup. Supported properties:
78
+ `scale`, `opacity`, `width`, `height`, `translateX`, `translateY`. Width/height are
79
+ pixels; translation is pixels in one axis and reserves the entire individual
80
+ `translate` property. Scale is unitless. Opacity clamps to [0,1]; dimensions and
81
+ scale clamp to nonnegative presentation while the numeric spring can overshoot.
82
+ The caller must not simultaneously animate/write the reserved property or apply
83
+ a CSS transition to it. The binding leaves `transform`, rotate, refs, children,
84
+ state and all event handlers untouched. Cleanup restores the prior inline value
85
+ and priority unless a caller has reclaimed it since the last spring write.
86
+ A dedicated motion part is required when the caller already owns that property.
87
+
88
+ `createLayoutSpring(bounds, options)` retains independent upstream springs for
89
+ local-pixel `{x, y, width, height}`. Measurements must share a stable coordinate
90
+ space; dimensions must be nonnegative. Off snaps all axes to the latest measured
91
+ bounds. Subscribers observe per-axis updates, not one atomic frame callback.
92
+ This is the layout adapter's numeric foundation. The grouped browser and React
93
+ interfaces described under [layout resize and reorder](#layout-resize-and-reorder)
94
+ own natural-flow measurement, scheduling and presentation.
95
+
96
+ ## React lifecycle
97
+
98
+ ```tsx
99
+ import { useRef } from 'react'
100
+ import { Button } from '@cognitap/radiant'
101
+ import { useSpringStyle } from '@cognitap/radiant/motion/react'
102
+
103
+ function Example() {
104
+ const ref = useRef<HTMLButtonElement>(null)
105
+ const scale = useSpringStyle(ref, 'scale', 1, 'press', 1)
106
+ return (
107
+ <Button
108
+ ref={ref}
109
+ style={{ '--rad-button-press-scale': '1' }}
110
+ onPointerDown={event => {
111
+ if (!event.defaultPrevented) scale.to(0.96)
112
+ }}
113
+ onPointerUp={() => scale.to(1)}
114
+ onPointerCancel={() => scale.to(1)}
115
+ onPointerLeave={() => scale.to(1)}
116
+ onBlur={() => scale.to(1)}
117
+ >
118
+ Save
119
+ </Button>
120
+ )
121
+ }
122
+ ```
123
+
124
+ This illustrates the interface, not the finished Button policy. The canonical
125
+ [System/Motion story](../src/Motion.stories.tsx) includes keyboard handling.
126
+ Consumers keep native activation, cancellation/disabled guards and semantic state
127
+ with the host. A replacement `render` must forward the resolved native ref and
128
+ props as usual. There is no wrapper or event interception in these hooks.
129
+
130
+ `useSpring(initial, interaction?, reducedValue?)` supplies a stable controller;
131
+ `useSpringStyle(ref, property, initial, interaction?, reducedValue?)` also binds the
132
+ real host. `initial` is mount-only. Replaced render hosts rebind after commit.
133
+ `useReducedMotion` live-subscribes to the system preference, removing listeners
134
+ when the last owner unmounts. SSR/hydration uses a conservative reduced snapshot;
135
+ there is no animation or browser access during server rendering, and no required
136
+ movement to reveal useful content. Effects create/dispose owned springs, including
137
+ StrictMode replay; frame updates do not set React state. Use the framework-neutral
138
+ controller for explicit manual lifecycle ownership instead of manually destroying
139
+ a hook-owned controller while its component remains mounted.
140
+
141
+ ## Loading and migration
142
+
143
+ The root export carries configuration and types only; it does not import Motion
144
+ physics or React projection. Opt in synchronously through `/motion` or
145
+ `/motion/react`. There is no runtime download, first-input race or lazy global
146
+ engine singleton. The consumer's bundler can place the opt-in import in its own
147
+ route/chunk. Rich gesture integration will have an explicit heavier boundary;
148
+ Motion React projection is excluded from the retained-momentum layout path.
149
+
150
+ Existing duration/easing tokens continue to control existing CSS transitions.
151
+ There is no reliable conversion from a CSS bounce curve to physical spring
152
+ parameters. Add `motion` to the theme, opt into these runtime bindings and disable
153
+ competing CSS presentation on the reserved property; migrate each built-in family
154
+ in its issue. Color fades may continue to use CSS durations. No tokens are removed
155
+ or renamed here. JavaScript and CSS still need matching package versions.
156
+
157
+ ## Native action springs
158
+
159
+ ```tsx
160
+ import { Button } from '@cognitap/radiant'
161
+ import { MotionProvider, MotionLink } from '@cognitap/radiant/motion/react'
162
+
163
+ ;<MotionProvider>
164
+ <Button type="submit">Save</Button>
165
+ <Button motion="off">Immediate spatial feedback</Button>
166
+ <MotionLink
167
+ variant="solid"
168
+ href="/account"
169
+ >
170
+ Account
171
+ </MotionLink>
172
+ </MotionProvider>
173
+ ```
174
+
175
+ MotionProvider adds no DOM wrapper. Within it, real Button hosts and composed
176
+ DialogTrigger/DialogClose actions use the theme's press spring for compression
177
+ and release, including re-press during rebound. The pressed scale comes from
178
+ `--rad-button-press-scale` (default .97, supported .5–1). MotionLink is an opt-in
179
+ client adapter for action-shaped Link; ordinary Link keeps its server contract.
180
+ Inline/subtle links do not compress, and Space keeps native anchor scrolling.
181
+
182
+ Native clicks/submission/navigation are never synthesized or delayed. Consumer
183
+ handlers run first; cancelling press input prevents compression. Pointer/touch,
184
+ Enter/Space, repeat, outside release, pointer cancellation, lost capture, blur,
185
+ disabled fieldsets and pending changes retain their native meanings. Off and
186
+ system reduced-motion cancel to neutral. The adapter reserves individual scale,
187
+ leaves caller transform intact, and removes scale from CSS transitions. Recognized
188
+ caller scale utilities or inline scale/scale transitions retain ownership and opt
189
+ out of the spring. For arbitrary external scale styles, set `motion="off"` and
190
+ keep one owner. Cleanup restores prior presentation and removes listeners.
191
+
192
+ See [System/Motion → ButtonPress](../src/Motion.stories.tsx) for the canonical
193
+ interactive proof. The public workshop composes these production APIs in DEV-178.
194
+
195
+ ## Disclosure and Dialog transitions
196
+
197
+ The same MotionProvider enables native Collapsible/Accordion height springs and
198
+ Dialog entry/exit presentation. `Collapsible motion="off"` and
199
+ `DialogContent motion="off"` opt out locally; theme off and live system reduced
200
+ motion snap immediately. Native open state, callbacks, Escape cancellation,
201
+ modal/top-layer behavior and focus restoration keep their existing owners.
202
+
203
+ Disclosure animates the `::details-content` height using a reserved internal CSS
204
+ variable. Real children keep natural size and are measured with ResizeObserver;
205
+ there is no child/border scaling. Closed content can finish a visual collapse,
206
+ but is inert and ARIA-hidden immediately. Authored inert/hidden values are restored
207
+ on opening/disposal. Custom layouts whose direct content margins/positioning do
208
+ not fit this measurement should opt out. Browsers without `::details-content`
209
+ visibility support retain native immediate collapse as progressive fallback.
210
+
211
+ Dialog closes natively immediately. For safe ordinary HTML content, an inert,
212
+ ARIA-hidden presentation `div` can finish a spring exit outside the top layer.
213
+ It carries no IDs, form names, autofocus or event handlers; form controls are
214
+ disabled, and pointer events pass through. It is removed at rest, reduced motion,
215
+ reopen or disposal. Reopening reuses the current spring state and cancels the copy.
216
+ Caller transform remains intact; authored scale/scale transitions retain ownership.
217
+
218
+ Nested native dialogs, custom elements, scripts/styles, embedded documents,
219
+ canvas and media use immediate visual exit: cloning those could trigger behavior
220
+ or fail to reproduce their content. The visual copy is not a retained modal or
221
+ interactive surface. Exotic containing blocks/positioning and live content during
222
+ exit are outside this snapshot contract; use local off when they need a different
223
+ presentation. See System/Motion → Transitions and the native browser proof.
224
+
225
+ ## Drag, release and snap
226
+
227
+ ```tsx
228
+ import { useRef } from 'react'
229
+ import { Button } from '@cognitap/radiant'
230
+ import { useSpringDrag } from '@cognitap/radiant/motion/react'
231
+
232
+ function Handle() {
233
+ const ref = useRef<HTMLButtonElement>(null)
234
+ const drag = useSpringDrag(ref, 0, { min: 0, max: 160, snapPoints: [0, 80, 160] })
235
+ return (
236
+ <>
237
+ <Button
238
+ ref={ref}
239
+ className="transition-colors"
240
+ >
241
+ Drag or use arrow keys
242
+ </Button>
243
+ <Button onClick={() => drag.step('first')}>Start</Button>
244
+ <Button onClick={() => drag.step('last')}>End</Button>
245
+ </>
246
+ )
247
+ }
248
+ ```
249
+
250
+ The hook reserves the handle's individual translate, keeps transform untouched,
251
+ and owns its binding/controller cleanup. It exposes `get`, `getVelocity`,
252
+ `subscribe`, `isAnimating`, `to`, `cancel` and `step`. Use a dedicated handle
253
+ without competing translate/transform animation. Initial position is mount-only;
254
+ changing bounds/snap points/theme updates the existing controller. Replacing a
255
+ host rebinds it; it does not replace the native host/ref or create a wrapper.
256
+
257
+ The framework-neutral `createSpringDrag(initial, options)` additionally exposes
258
+ `begin`, `move(position, time)`, `release(time)`, `jump`, `stop`, `configure` and
259
+ `destroy`. Bounds are finite pixels with min < max. Snap points are detached,
260
+ sorted, deduplicated and must be nonempty/in bounds; omitted points mean the two
261
+ bounds. `bindSpringDrag(element, controller, axis?)` supplies native browser input
262
+ and presentation; dispose the binding and then its owned controller separately.
263
+ The axis is x by default, or y. Geometry conversion/reordering is DEV-177.
264
+
265
+ Direct manipulation jumps to bounded pointer positions. Release uses signed
266
+ velocity from fresh monotonic samples (milliseconds; zero after 80ms inactivity,
267
+ clamped to ±3000px/s). It projects 180ms ahead and selects the nearest bounded
268
+ snap point; ties choose the lower point. Motion receives the actual signed release
269
+ velocity through its public value API. `createSpring.to(target, velocity?)` also
270
+ supports an explicitly seeded velocity in units/second. Ordinary target changes
271
+ still retain the running follower's momentum; explicit velocity starts a new
272
+ trajectory at the current position. No solver, sampled bounce curve or website-only
273
+ physics engine is added.
274
+
275
+ Bounds hard-clamp presentation and direct input, while upstream physics can
276
+ overshoot internally. This is not a collision/bounce or free 2D drag engine.
277
+ Re-grab freezes the current presentation; cancellation returns to the last
278
+ committed goal with zero release velocity. Escape cancels an active drag; arrows
279
+ select adjacent points, Home/End choose extremes. Native focus and tap/Enter/Space
280
+ click remain native; a completed drag suppresses its following click once.
281
+ Consumer prevention/propagation runs before the document-bubble gesture handlers.
282
+ Disabled/pending and lost capture/blur cancel the gesture. Horizontal handles use
283
+ pan-y and vertical handles pan-x when no inline touch-action is authored, retaining
284
+ perpendicular native scrolling; caller touch-action values remain owned by the
285
+ caller. Off/reduced motion preserves useful direct manipulation and snaps release
286
+ or keyboard goals immediately, rather than disabling functional controls.
287
+
288
+ See System/Motion → DragSnap for a real handle, explicit native button alternatives,
289
+ range target and position readout. The public editor composes these APIs in DEV-178.
290
+
291
+ ## Following changing targets
292
+
293
+ ```tsx
294
+ import { useEffect, useRef } from 'react'
295
+ import { bindSpringStyle } from '@cognitap/radiant/motion'
296
+ import { useSpringFollow } from '@cognitap/radiant/motion/react'
297
+
298
+ function Follower({ target }: { target: number }) {
299
+ const ref = useRef<HTMLDivElement>(null)
300
+ const spring = useSpringFollow(target)
301
+ useEffect(() => {
302
+ if (ref.current) return bindSpringStyle(ref.current, spring, 'translateX')
303
+ }, [spring])
304
+ return (
305
+ <div
306
+ ref={ref}
307
+ aria-hidden="true"
308
+ />
309
+ )
310
+ }
311
+ ```
312
+
313
+ `useSpringFollow(target, interaction?, reducedValue?)` accepts either a finite numeric
314
+ prop or a `SpringSource` with synchronous `get()` and `subscribe(listener)` methods.
315
+ A source notifies with its latest numeric destination; it must offer a server-safe
316
+ snapshot when used during SSR. The hook reads props after commit and external
317
+ notifications directly, without storing each animated frame in React state. Source
318
+ replacement detaches the old subscription and retargets the same spring. Target
319
+ changes preserve current position and momentum; theme parameter changes wait until
320
+ rest. Off/reduced motion follows the latest destination immediately, or uses the
321
+ explicit neutral value. Initial server markup is unchanged by the binding.
322
+
323
+ For manual ownership, `bindSpringSource(spring, source)` subscribes an existing
324
+ controller and reads the current snapshot. Its idempotent cleanup only detaches
325
+ the source: the last destination can finish. Call `spring.stop()` after detaching
326
+ to freeze presentation, or `destroy()` to dispose an owned controller. Calling
327
+ `stop()` while still bound freezes only until the next source notification. Never
328
+ bind a source to itself or create cyclic follower chains. One binding owns targets
329
+ at a time; the binding never owns or destroys its source. Numeric units, property
330
+ ownership and parameter rules are the same as `createSpring`.
331
+
332
+ System/Motion → FollowingValues offers pointer, native range and moving-target
333
+ controls with a visible destination, follower and numeric readout. This is a
334
+ library development proof; the public workshop remains DEV-178.
335
+
336
+ ## Layout resize and reorder
337
+
338
+ ```tsx
339
+ import { useRef } from 'react'
340
+ import { Card, CardTitle } from '@cognitap/radiant'
341
+ import { useSpringLayout } from '@cognitap/radiant/motion/react'
342
+
343
+ function Cards({ items }: { items: { id: string; title: string }[] }) {
344
+ const root = useRef<HTMLDivElement>(null)
345
+ useSpringLayout(root)
346
+ return (
347
+ <div
348
+ ref={root}
349
+ className="grid grid-cols-2 gap-4"
350
+ >
351
+ {items.map(item => (
352
+ <div
353
+ key={item.id}
354
+ data-rad-layout-slot=""
355
+ className="flow-root"
356
+ >
357
+ <Card data-rad-layout-part="">
358
+ <CardTitle>{item.title}</CardTitle>
359
+ </Card>
360
+ </div>
361
+ ))}
362
+ </div>
363
+ )
364
+ }
365
+ ```
366
+
367
+ The root owns a group of **direct-child** `data-rad-layout-slot` wrappers. Each
368
+ slot has one first-child `data-rad-layout-part` containing the actual content.
369
+ Keep keys and the slot/part DOM identities stable during reorder; replacement
370
+ starts a new item at its natural bounds. New and removed items appear/disappear
371
+ immediately; this interface does not provide enter/exit presence or drag sorting.
372
+ Native semantic elements stay inside the motion part or, for passive Card, can
373
+ be the part itself. A part can have padding, borders, backgrounds and a grid/flex
374
+ content layout. Children, text and borders are never scaled or cloned.
375
+
376
+ `useSpringLayout(ref)` measures the group in a layout effect after each commit,
377
+ before paint. It supplies `measure()`, `get(slot)`, `getVelocity(slot)` and
378
+ `isAnimating()`. Snapshots use local pixel `{x,y,width,height}` bounds and velocities
379
+ in pixels/second, or undefined for an unregistered/disposed slot. Theme `layout`
380
+ physics, system reduced motion and lifetime remain hook-owned. The stable handle
381
+ survives root replacement; SSR does not measure or alter markup. No animated
382
+ frame is stored in React state. See System/Motion → LayoutResizeReorder for a
383
+ responsive Card grid with reorder, width and dynamic-content controls.
384
+
385
+ For manual ownership, `bindSpringLayout(root, options?)` measures a mounted browser
386
+ root and returns the same inspection/measurement interface plus `configure` and
387
+ idempotent `destroy`. Supply `enabled` from your live reduced-motion policy, as
388
+ with `createSpring`. Options use the same physical parameter rules; scalar
389
+ `reducedValue` is rejected. Destroy removes observers, listeners, pending adapter
390
+ frames and springs, and restores inline properties still owned by the binding.
391
+
392
+ Every measurement releases **all** slot reservations/projections before reading
393
+ natural layout, then retargets one persistent upstream spring per coordinate axis.
394
+ Slots reserve their final natural width/height while their motion parts render the
395
+ current position and physical width/height. Text reflows at the animated width;
396
+ height does not scale or implicitly clip content. The group restores normal flow
397
+ at rest. Off/reduced motion snaps to the natural layout immediately. Profile
398
+ parameter changes take effect at rest without replacing in-flight momentum.
399
+
400
+ Root/slot ResizeObservers, subtree content/class/open/hidden/style mutations,
401
+ resource loads, viewport resize and font completion schedule a grouped measurement.
402
+ Imperative callers can call `measure()` synchronously after a transaction to avoid
403
+ a frame before mutation-observer work. Style writes on the reserved slot/part are
404
+ ignored by the mutation observer to avoid observing the animation itself: call
405
+ `measure()` explicitly after changing their author-owned styles. React commits do
406
+ this automatically. Scrolling the root or an outer scroller preserves local
407
+ coordinates; scrolling is not a new motion target. Native overflow clipping and
408
+ scrollbar ownership remain with the application.
409
+
410
+ Geometry requirements:
411
+
412
+ - Use dedicated, normal-flow, unpadded, borderless slots. Slots can carry grid/flex
413
+ placement and margins; use `flow-root` to avoid collapsed content margins.
414
+ Parts must have zero outer margin and fill their slot naturally. Put decoration
415
+ and padding on the part or content. Keep one part as the slot's only element.
416
+ - Reserve slot position/width/height/box-sizing/flex and part position/insets/width/
417
+ height/box-sizing/translate for the binding. No competing transitions, transforms
418
+ or individual translate/rotate/scale on these wrappers; transformed native
419
+ controls **inside** a part keep their own presentation. Insets must start at
420
+ their normal-flow defaults. Unsupported wrapper geometry is rejected rather
421
+ than silently projecting distorted measurements.
422
+ - The coordinate plane must be unscaled/unrotated, with no CSS zoom/perspective on
423
+ the root/ancestors. Common ancestor translation is supported. Fixed/sticky or
424
+ absolute slots, cross-root shared-element morphing, nested independently animated
425
+ layout groups and arbitrary transformed coordinate systems are outside this
426
+ contract. Ordinary nested content, native modal top layers and internal scrollers
427
+ retain their owners. Scroll-position/sticky pinning is not synthesized.
428
+ - Layout motion never delays semantic changes, takes focus, moves DOM or duplicates
429
+ native controls. DOM reorder is still the application's operation; if it removes
430
+ or moves the focused host, apply the application's intended focus policy. Keep
431
+ overflow visible when focus outlines or content must extend beyond animated bounds.
432
+
433
+ The public workshop and theme handoff remain DEV-178/179; this ships the reusable
434
+ library interface and its development proof, without publishing a package.
package/docs/system.md CHANGED
@@ -236,3 +236,29 @@ Check relevant keyboard/form/ref behavior and actual appearance in both modes;
236
236
  automated accessibility results do not establish complete visual or assistive
237
237
  technology readiness. Historical design decisions and acceptance sketches remain
238
238
  in the [harmonisation record](https://github.com/cognitap/radiant/blob/main/docs/contracts/README.md).
239
+
240
+ ## Spring runtime
241
+
242
+ Themes can carry serializable physical motion profiles separately from CSS
243
+ duration/easing tokens. Opt-in numeric and React lifecycle interfaces live in
244
+ `@cognitap/radiant/motion` and `/motion/react`; ordinary root imports carry no
245
+ physics engine. See the [motion runtime contract](motion.md) and canonical
246
+ [System/Motion binding](../src/Motion.stories.tsx). Built-in family integration
247
+ follows separately; native state, event composition and refs keep their owners.
248
+
249
+ Opt into native Button and composed Dialog action springs with the wrapper-free
250
+ `MotionProvider` from `/motion/react`. `Button motion="off"` suppresses its spatial
251
+ feedback. The optional `MotionLink` adapter gives action-shaped anchors spring
252
+ compression while ordinary Link stays server-renderable. See [native action
253
+ springs](motion.md#native-action-springs) for event and style ownership.
254
+
255
+ MotionProvider also enables native disclosure height and Dialog presentation.
256
+ Native close and focus restoration stay immediate; a bounded inert visual copy
257
+ may finish Dialog exit. See [native transition ownership](motion.md#disclosure-and-dialog-transitions).
258
+
259
+ Use `useSpringFollow` for committed numeric targets or subscribed sources. For
260
+ resize/reorder, `useSpringLayout` measures direct-child layout slots containing
261
+ dedicated motion parts; actual native content stays in place and text reflows
262
+ without scaling. See [layout geometry and ownership](motion.md#layout-resize-and-reorder)
263
+ before composing the wrappers. Both opt-in interfaces use theme profiles and
264
+ live reduced motion. Their canonical interactive proofs remain in System/Motion.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cognitap/radiant",
3
- "version": "0.0.5",
3
+ "version": "0.0.6",
4
4
  "description": "React interaction components and presentation primitives",
5
5
  "homepage": "https://github.com/cognitap/radiant#readme",
6
6
  "bugs": {
@@ -16,6 +16,7 @@
16
16
  "CHANGELOG.md",
17
17
  "RELEASE_POLICY.md",
18
18
  "docs/system.md",
19
+ "docs/motion.md",
19
20
  "docs/accessibility.md",
20
21
  "docs/theming.md",
21
22
  "dist/library",
@@ -46,6 +47,14 @@
46
47
  "./typography": {
47
48
  "types": "./dist/library/typography/index.d.ts",
48
49
  "default": "./dist/library/typography/index.js"
50
+ },
51
+ "./motion": {
52
+ "types": "./dist/library/motion/index.d.ts",
53
+ "default": "./dist/library/motion/index.js"
54
+ },
55
+ "./motion/react": {
56
+ "types": "./dist/library/motion/react.d.ts",
57
+ "default": "./dist/library/motion/react.js"
49
58
  }
50
59
  },
51
60
  "publishConfig": {
@@ -55,7 +64,8 @@
55
64
  },
56
65
  "dependencies": {
57
66
  "class-variance-authority": "0.7.1",
58
- "cn": "0.4.0"
67
+ "cn": "0.4.0",
68
+ "motion": "14.7.1"
59
69
  },
60
70
  "devDependencies": {
61
71
  "@storybook/addon-a11y": "10.6.1",
@@ -116,7 +126,8 @@
116
126
  "lint": "oxlint --deny-warnings",
117
127
  "format": "oxfmt",
118
128
  "format:check": "oxfmt --check",
119
- "check:source": "pnpm theme:check && pnpm format:check && pnpm lint && pnpm typecheck",
129
+ "check:source": "pnpm theme:check && pnpm format:check && pnpm lint && pnpm typecheck && pnpm docs:check",
130
+ "docs:check": "node scripts/check-docs.mjs",
120
131
  "check:ci": "pnpm check:source && pnpm test && pnpm build:storybook && pnpm test:browser:smoke",
121
132
  "check": "pnpm check:source && pnpm test --styles --compositions && pnpm build:storybook && pnpm test:browser",
122
133
  "test:compositions": "pnpm build && node scripts/verify-package.mjs --compositions",
package/src/Button.tsx CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  import type { ComponentProps, ReactElement } from 'react'
4
4
  import { Fragment, isValidElement } from 'react'
5
+ import { callerOwnsPress, springPressClass, offPressClass } from './motion/pressPolicy.js'
6
+ import { usePressHost } from './motion/host.js'
5
7
  import { actionVariants } from './actionStyles.js'
6
8
  import type { ButtonVariant, ControlSize, Tone } from './presentation.js'
7
9
  import { cn } from './cn.js'
@@ -31,10 +33,14 @@ export type ButtonProps = Omit<ComponentProps<'button'>, 'style'> & {
31
33
  iconOnly?: boolean
32
34
  fullWidth?: boolean
33
35
  pending?: boolean
36
+ /** Requires MotionProvider. Off also suppresses legacy spatial transitions. */
37
+ motion?: 'inherit' | 'off'
34
38
  }
35
39
 
36
40
  export function Button({
37
41
  render,
42
+ motion = 'inherit',
43
+ ref,
38
44
  type = 'button',
39
45
  variant = 'solid',
40
46
  tone = 'accent',
@@ -47,15 +53,56 @@ export function Button({
47
53
  children,
48
54
  ...props
49
55
  }: ButtonProps) {
56
+ const callerOwnsScale = callerOwnsPress(props.style, className)
57
+ const press = usePressHost(ref, motion === 'off' || callerOwnsScale)
58
+ const spatial = (press.active || motion === 'off') && !callerOwnsScale
50
59
  const buttonProps: ButtonRenderProps = {
51
60
  ...props,
61
+ ref: press.active ? press.ref : ref,
62
+ onPointerDown: event => {
63
+ props.onPointerDown?.(event)
64
+ if (!pending && !event.defaultPrevented) press.press(event.nativeEvent)
65
+ },
66
+ onPointerUp: event => {
67
+ props.onPointerUp?.(event)
68
+ press.release()
69
+ },
70
+ onPointerCancel: event => {
71
+ props.onPointerCancel?.(event)
72
+ press.release()
73
+ },
74
+ onPointerLeave: event => {
75
+ props.onPointerLeave?.(event)
76
+ press.release()
77
+ },
78
+ onLostPointerCapture: event => {
79
+ props.onLostPointerCapture?.(event)
80
+ press.release()
81
+ },
82
+ onBlur: event => {
83
+ props.onBlur?.(event)
84
+ press.release()
85
+ },
86
+ onKeyDown: event => {
87
+ props.onKeyDown?.(event)
88
+ if (!pending && !event.defaultPrevented) press.press(event.nativeEvent)
89
+ },
90
+ onKeyUp: event => {
91
+ props.onKeyUp?.(event)
92
+ press.release()
93
+ },
52
94
  type,
53
95
  'aria-busy': pending || props['aria-busy'],
54
96
  'data-slot': joinIds('button', props['data-slot']) ?? 'button',
55
97
  'data-variant': variant,
56
98
  'data-tone': tone,
57
99
  'data-control-size': controlSize,
58
- className: cn(actionVariants({ variant, tone, controlSize, iconOnly, fullWidth }), className),
100
+ className: cn(
101
+ actionVariants({ variant, tone, controlSize, iconOnly, fullWidth }),
102
+ spatial && springPressClass,
103
+ motion === 'off' && !callerOwnsScale && offPressClass,
104
+ className
105
+ ),
59
106
  onClick: composeAction(
60
107
  onClick,
61
108
  undefined,
@@ -76,6 +123,7 @@ export function Button({
76
123
  )
77
124
  }
78
125
  if (!render) return <button {...buttonProps}>{buttonProps.children}</button>
126
+ // oxlint-disable-next-line react/refs -- The render contract forwards refs; it does not read ref.current.
79
127
  const element = render(buttonProps)
80
128
  if (
81
129
  !isValidElement(element) ||
@@ -3,6 +3,7 @@
3
3
  import type { ComponentProps, ToggleEvent } from 'react'
4
4
  import { createContext, useContext, useId } from 'react'
5
5
  import { cva } from 'class-variance-authority'
6
+ import { useTransitionHost } from './motion/host.js'
6
7
  import { cn } from './cn.js'
7
8
  import { joinIds } from './internal/ids.js'
8
9
  import type { ThemeStyle } from './themes/defineTheme.js'
@@ -67,6 +68,7 @@ const collapsibleContentVariants = cva([
67
68
  export type CollapsibleProps = Omit<ComponentProps<'details'>, 'open' | 'onToggle' | 'style'> &
68
69
  ({ open: boolean; defaultOpen?: never } | { open?: undefined; defaultOpen?: boolean }) & {
69
70
  style?: ThemeStyle
71
+ motion?: 'inherit' | 'off'
70
72
  'data-slot'?: string
71
73
  onOpenChange?: (open: boolean) => void
72
74
  onToggle?: (event: ToggleEvent<HTMLDetailsElement>) => void
@@ -103,12 +105,15 @@ function useCollapsibleContext() {
103
105
  export function Collapsible({
104
106
  open,
105
107
  defaultOpen,
108
+ motion = 'inherit',
109
+ ref,
106
110
  onOpenChange,
107
111
  onToggle,
108
112
  className,
109
113
  children,
110
114
  ...props
111
115
  }: CollapsibleProps) {
116
+ const transition = useTransitionHost<HTMLDetailsElement>('disclosure', ref, motion === 'off')
112
117
  const contentId = useId()
113
118
  const {
114
119
  value: isOpen,
@@ -126,7 +131,14 @@ export function Collapsible({
126
131
  <CollapsibleContext.Provider value={{ open: isOpen, contentId, setOpen }}>
127
132
  <details
128
133
  {...props}
129
- className={cn(collapsibleVariants(), className)}
134
+ ref={transition.active ? transition.ref : ref}
135
+ className={cn(
136
+ collapsibleVariants(),
137
+ transition.active &&
138
+ '[&::details-content]:[content-visibility:visible] [&::details-content]:transition-none [&:not([open])::details-content]:h-[var(--_rad-spring-details-height,0px)] open:[&::details-content]:h-[var(--_rad-spring-details-height,auto)]',
139
+ motion === 'off' && '[&::details-content]:transition-none',
140
+ className
141
+ )}
130
142
  data-slot={joinIds('collapsible', props['data-slot'])}
131
143
  data-state={isOpen ? 'open' : 'closed'}
132
144
  open={isOpen}