@cognitap/radiant 0.0.4 → 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.
- package/CHANGELOG.md +44 -0
- package/README.md +17 -0
- package/dist/library/Button.d.ts +3 -1
- package/dist/library/Button.d.ts.map +1 -1
- package/dist/library/Button.js +43 -2
- package/dist/library/Button.js.map +1 -1
- package/dist/library/Card.d.ts.map +1 -1
- package/dist/library/Card.js +8 -6
- package/dist/library/Card.js.map +1 -1
- package/dist/library/Checkbox.js +2 -2
- package/dist/library/Checkbox.js.map +1 -1
- package/dist/library/Collapsible.d.ts +2 -1
- package/dist/library/Collapsible.d.ts.map +1 -1
- package/dist/library/Collapsible.js +10 -6
- package/dist/library/Collapsible.js.map +1 -1
- package/dist/library/Dialog.d.ts +2 -1
- package/dist/library/Dialog.d.ts.map +1 -1
- package/dist/library/Dialog.js +13 -8
- package/dist/library/Dialog.js.map +1 -1
- package/dist/library/Field.js +4 -4
- package/dist/library/Field.js.map +1 -1
- package/dist/library/Input.d.ts.map +1 -1
- package/dist/library/Input.js +4 -3
- package/dist/library/Input.js.map +1 -1
- package/dist/library/Link.d.ts.map +1 -1
- package/dist/library/Link.js +0 -1
- package/dist/library/Link.js.map +1 -1
- package/dist/library/RadioGroup.js +2 -2
- package/dist/library/RadioGroup.js.map +1 -1
- package/dist/library/ThemeScope.d.ts.map +1 -1
- package/dist/library/ThemeScope.js +11 -10
- package/dist/library/ThemeScope.js.map +1 -1
- package/dist/library/actionStyles.js +2 -2
- package/dist/library/actionStyles.js.map +1 -1
- package/dist/library/cn.d.ts +2 -1
- package/dist/library/cn.d.ts.map +1 -1
- package/dist/library/cn.js +22 -1
- package/dist/library/cn.js.map +1 -1
- package/dist/library/index.d.ts +5 -1
- package/dist/library/index.d.ts.map +1 -1
- package/dist/library/index.js +2 -0
- package/dist/library/index.js.map +1 -1
- package/dist/library/motion/MotionLink.d.ts +7 -0
- package/dist/library/motion/MotionLink.d.ts.map +1 -0
- package/dist/library/motion/MotionLink.js +45 -0
- package/dist/library/motion/MotionLink.js.map +1 -0
- package/dist/library/motion/browser.d.ts +5 -0
- package/dist/library/motion/browser.d.ts.map +1 -0
- package/dist/library/motion/browser.js +35 -0
- package/dist/library/motion/browser.js.map +1 -0
- package/dist/library/motion/config.d.ts +26 -0
- package/dist/library/motion/config.d.ts.map +1 -0
- package/dist/library/motion/config.js +58 -0
- package/dist/library/motion/config.js.map +1 -0
- package/dist/library/motion/context.d.ts +2 -0
- package/dist/library/motion/context.d.ts.map +1 -0
- package/dist/library/motion/context.js +5 -0
- package/dist/library/motion/context.js.map +1 -0
- package/dist/library/motion/drag.d.ts +20 -0
- package/dist/library/motion/drag.d.ts.map +1 -0
- package/dist/library/motion/drag.js +138 -0
- package/dist/library/motion/drag.js.map +1 -0
- package/dist/library/motion/dragBrowser.d.ts +4 -0
- package/dist/library/motion/dragBrowser.d.ts.map +1 -0
- package/dist/library/motion/dragBrowser.js +156 -0
- package/dist/library/motion/dragBrowser.js.map +1 -0
- package/dist/library/motion/follow.d.ts +9 -0
- package/dist/library/motion/follow.d.ts.map +1 -0
- package/dist/library/motion/follow.js +26 -0
- package/dist/library/motion/follow.js.map +1 -0
- package/dist/library/motion/host.d.ts +27 -0
- package/dist/library/motion/host.d.ts.map +1 -0
- package/dist/library/motion/host.js +62 -0
- package/dist/library/motion/host.js.map +1 -0
- package/dist/library/motion/index.d.ts +16 -0
- package/dist/library/motion/index.d.ts.map +1 -0
- package/dist/library/motion/index.js +9 -0
- package/dist/library/motion/index.js.map +1 -0
- package/dist/library/motion/layout.d.ts +20 -0
- package/dist/library/motion/layout.d.ts.map +1 -0
- package/dist/library/motion/layout.js +67 -0
- package/dist/library/motion/layout.js.map +1 -0
- package/dist/library/motion/layoutDom.d.ts +17 -0
- package/dist/library/motion/layoutDom.d.ts.map +1 -0
- package/dist/library/motion/layoutDom.js +272 -0
- package/dist/library/motion/layoutDom.js.map +1 -0
- package/dist/library/motion/press.d.ts +5 -0
- package/dist/library/motion/press.d.ts.map +1 -0
- package/dist/library/motion/press.js +72 -0
- package/dist/library/motion/press.js.map +1 -0
- package/dist/library/motion/pressPolicy.d.ts +5 -0
- package/dist/library/motion/pressPolicy.d.ts.map +1 -0
- package/dist/library/motion/pressPolicy.js +8 -0
- package/dist/library/motion/pressPolicy.js.map +1 -0
- package/dist/library/motion/react.d.ts +35 -0
- package/dist/library/motion/react.d.ts.map +1 -0
- package/dist/library/motion/react.js +224 -0
- package/dist/library/motion/react.js.map +1 -0
- package/dist/library/motion/runtime.d.ts +22 -0
- package/dist/library/motion/runtime.d.ts.map +1 -0
- package/dist/library/motion/runtime.js +117 -0
- package/dist/library/motion/runtime.js.map +1 -0
- package/dist/library/motion/transitions.d.ts +5 -0
- package/dist/library/motion/transitions.d.ts.map +1 -0
- package/dist/library/motion/transitions.js +211 -0
- package/dist/library/motion/transitions.js.map +1 -0
- package/dist/library/styles.css +1 -1
- package/dist/library/themes/defineTheme.d.ts +3 -0
- package/dist/library/themes/defineTheme.d.ts.map +1 -1
- package/dist/library/themes/defineTheme.js +9 -3
- package/dist/library/themes/defineTheme.js.map +1 -1
- package/dist/library/themes/index.d.ts +1 -1
- package/dist/library/themes/index.d.ts.map +1 -1
- package/dist/library/themes/index.js.map +1 -1
- package/dist/library/themes/themeDocument.d.ts.map +1 -1
- package/dist/library/themes/themeDocument.js +39 -8
- package/dist/library/themes/themeDocument.js.map +1 -1
- package/dist/library/themes/themeDocumentTypes.d.ts +16 -1
- package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -1
- package/dist/library/themes/themeDocumentTypes.js.map +1 -1
- package/dist/library/themes/tokens.d.ts +7 -0
- package/dist/library/themes/tokens.d.ts.map +1 -1
- package/dist/library/themes/tokens.js +99 -0
- package/dist/library/themes/tokens.js.map +1 -1
- package/dist/library/typography/index.d.ts +72 -0
- package/dist/library/typography/index.d.ts.map +1 -0
- package/dist/library/typography/index.js +160 -0
- package/dist/library/typography/index.js.map +1 -0
- package/dist/library/typography/types.d.ts +78 -0
- package/dist/library/typography/types.d.ts.map +1 -0
- package/dist/library/typography/types.js +2 -0
- package/dist/library/typography/types.js.map +1 -0
- package/docs/motion.md +434 -0
- package/docs/system.md +33 -0
- package/docs/theming.md +204 -0
- package/package.json +20 -4
- package/src/Button.tsx +49 -1
- package/src/Card.tsx +8 -6
- package/src/Checkbox.tsx +2 -2
- package/src/Collapsible.tsx +18 -5
- package/src/Dialog.tsx +18 -7
- package/src/Field.tsx +4 -4
- package/src/Input.tsx +4 -3
- package/src/Link.tsx +0 -1
- package/src/RadioGroup.tsx +2 -2
- package/src/ThemeScope.tsx +22 -18
- package/src/actionStyles.ts +2 -2
- package/src/cn.ts +25 -1
- package/src/index.ts +12 -0
- package/src/motion/MotionLink.tsx +64 -0
- package/src/motion/browser.ts +45 -0
- package/src/motion/config.ts +79 -0
- package/src/motion/context.ts +4 -0
- package/src/motion/drag.ts +151 -0
- package/src/motion/dragBrowser.ts +159 -0
- package/src/motion/follow.ts +28 -0
- package/src/motion/host.ts +88 -0
- package/src/motion/index.ts +28 -0
- package/src/motion/layout.ts +78 -0
- package/src/motion/layoutDom.ts +293 -0
- package/src/motion/press.ts +77 -0
- package/src/motion/pressPolicy.ts +12 -0
- package/src/motion/react.ts +272 -0
- package/src/motion/runtime.ts +122 -0
- package/src/motion/transitions.ts +206 -0
- package/src/styles.css +1 -0
- package/src/themes/baseline.css +131 -0
- package/src/themes/defineTheme.ts +15 -3
- package/src/themes/index.ts +2 -0
- package/src/themes/themeDocument.ts +47 -9
- package/src/themes/themeDocumentTypes.ts +24 -5
- package/src/themes/tokens.ts +137 -0
- package/src/typography/index.ts +199 -0
- package/src/typography/types.ts +92 -0
- package/src/typography.css +336 -0
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
|
@@ -54,6 +54,13 @@ For public workshop editing, use the versioned `ThemeDocument` authoring API.
|
|
|
54
54
|
Its token sections compile through `defineTheme` into the same `ThemeScope`
|
|
55
55
|
contract. Section imports preserve unrelated settings and deliberate component
|
|
56
56
|
exceptions. See [portable documents and import semantics](theming.md#portable-workshop-documents). The pure
|
|
57
|
+
`generateTypography` interface and `typography.typesetting` recipe supply opt-in
|
|
58
|
+
font assignments, 16 text styles and independent prose/UI rhythms through the
|
|
59
|
+
same compiler. Use the semantic HTML hooks and local container documented under
|
|
60
|
+
[responsive typography](theming.md#responsive-typography); production component text consumes the shared UI roles. Control sizes retain
|
|
61
|
+
their font-size/geometry metrics, and inline links inherit their surrounding text.
|
|
62
|
+
The baseline UI roles bridge the legacy typography leaves; recipes and explicit
|
|
63
|
+
role values take ownership when supplied. The pure
|
|
57
64
|
`generateColorWall` interface supplies calibrated sRGB palette metadata through
|
|
58
65
|
`@cognitap/radiant/color`; see [color-wall inputs and output](theming.md#generate-a-color-wall). Use
|
|
59
66
|
`colorCalibrationPresets` for independent wall/ramp treatments (Classic, Balanced,
|
|
@@ -229,3 +236,29 @@ Check relevant keyboard/form/ref behavior and actual appearance in both modes;
|
|
|
229
236
|
automated accessibility results do not establish complete visual or assistive
|
|
230
237
|
technology readiness. Historical design decisions and acceptance sketches remain
|
|
231
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.
|