@cognitap/radiant 0.0.6 → 0.0.8
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 +82 -395
- package/README.md +41 -1014
- package/RELEASE_POLICY.md +3 -3
- package/dist/library/Accordion.d.ts +3 -0
- package/dist/library/Accordion.d.ts.map +1 -1
- package/dist/library/Accordion.js +1 -1
- package/dist/library/Accordion.js.map +1 -1
- package/dist/library/Button.d.ts +5 -0
- package/dist/library/Button.d.ts.map +1 -1
- package/dist/library/Button.js +8 -7
- package/dist/library/Button.js.map +1 -1
- package/dist/library/Card.d.ts +2 -0
- package/dist/library/Card.d.ts.map +1 -1
- package/dist/library/Card.js +1 -1
- package/dist/library/Card.js.map +1 -1
- package/dist/library/Checkbox.d.ts +5 -0
- package/dist/library/Checkbox.d.ts.map +1 -1
- package/dist/library/Checkbox.js +3 -2
- package/dist/library/Checkbox.js.map +1 -1
- package/dist/library/Collapsible.d.ts +4 -0
- package/dist/library/Collapsible.d.ts.map +1 -1
- package/dist/library/Collapsible.js +22 -4
- package/dist/library/Collapsible.js.map +1 -1
- package/dist/library/Dialog.d.ts +3 -0
- package/dist/library/Dialog.d.ts.map +1 -1
- package/dist/library/Dialog.js.map +1 -1
- package/dist/library/Field.d.ts +8 -0
- package/dist/library/Field.d.ts.map +1 -1
- package/dist/library/Field.js +2 -0
- package/dist/library/Field.js.map +1 -1
- package/dist/library/Input.d.ts +3 -0
- package/dist/library/Input.d.ts.map +1 -1
- package/dist/library/Input.js +1 -0
- package/dist/library/Input.js.map +1 -1
- package/dist/library/Link.d.ts +5 -0
- package/dist/library/Link.d.ts.map +1 -1
- package/dist/library/Link.js.map +1 -1
- package/dist/library/RadioGroup.d.ts +8 -0
- package/dist/library/RadioGroup.d.ts.map +1 -1
- package/dist/library/RadioGroup.js +4 -2
- package/dist/library/RadioGroup.js.map +1 -1
- package/dist/library/Select.d.ts +87 -0
- package/dist/library/Select.d.ts.map +1 -0
- package/dist/library/Select.js +454 -0
- package/dist/library/Select.js.map +1 -0
- package/dist/library/cn.d.ts.map +1 -1
- package/dist/library/cn.js +20 -3
- package/dist/library/cn.js.map +1 -1
- package/dist/library/examples/expressive.d.ts +4 -0
- package/dist/library/examples/expressive.d.ts.map +1 -0
- package/dist/library/{themes → examples}/expressive.js +4 -3
- package/dist/library/examples/expressive.js.map +1 -0
- package/dist/library/examples/glass.d.ts +4 -0
- package/dist/library/examples/glass.d.ts.map +1 -0
- package/dist/library/{themes → examples}/glass.js +9 -3
- package/dist/library/examples/glass.js.map +1 -0
- package/dist/library/examples/index.d.ts +13 -0
- package/dist/library/examples/index.d.ts.map +1 -0
- package/dist/library/examples/index.js +32 -0
- package/dist/library/examples/index.js.map +1 -0
- package/dist/library/examples/jelly.d.ts +4 -0
- package/dist/library/examples/jelly.d.ts.map +1 -0
- package/dist/library/{themes → examples}/jelly.js +4 -3
- package/dist/library/examples/jelly.js.map +1 -0
- package/dist/library/examples/preset-values.d.ts.map +1 -0
- package/dist/library/examples/preset-values.js.map +1 -0
- package/dist/library/examples/radiant.d.ts +4 -0
- package/dist/library/examples/radiant.d.ts.map +1 -0
- package/dist/library/{themes → examples}/radiant.js +4 -3
- package/dist/library/examples/radiant.js.map +1 -0
- package/dist/library/examples/sharp-3d.d.ts +4 -0
- package/dist/library/examples/sharp-3d.d.ts.map +1 -0
- package/dist/library/{themes → examples}/sharp-3d.js +4 -3
- package/dist/library/examples/sharp-3d.js.map +1 -0
- package/dist/library/examples/soft-squircle.d.ts +4 -0
- package/dist/library/examples/soft-squircle.d.ts.map +1 -0
- package/dist/library/{themes → examples}/soft-squircle.js +4 -3
- package/dist/library/examples/soft-squircle.js.map +1 -0
- package/dist/library/examples/ticket.d.ts +4 -0
- package/dist/library/examples/ticket.d.ts.map +1 -0
- package/dist/library/{themes → examples}/ticket.js +4 -3
- package/dist/library/examples/ticket.js.map +1 -0
- package/dist/library/index.d.ts +3 -1
- package/dist/library/index.d.ts.map +1 -1
- package/dist/library/index.js +2 -1
- package/dist/library/index.js.map +1 -1
- package/dist/library/internal/select.d.ts +37 -0
- package/dist/library/internal/select.d.ts.map +1 -0
- package/dist/library/internal/select.js +42 -0
- package/dist/library/internal/select.js.map +1 -0
- package/dist/library/motion/MotionLink.d.ts +1 -0
- package/dist/library/motion/MotionLink.d.ts.map +1 -1
- package/dist/library/motion/MotionLink.js +9 -10
- package/dist/library/motion/MotionLink.js.map +1 -1
- package/dist/library/motion/host.d.ts +7 -3
- package/dist/library/motion/host.d.ts.map +1 -1
- package/dist/library/motion/host.js +13 -5
- package/dist/library/motion/host.js.map +1 -1
- package/dist/library/motion/popup.d.ts +5 -0
- package/dist/library/motion/popup.d.ts.map +1 -0
- package/dist/library/motion/popup.js +60 -0
- package/dist/library/motion/popup.js.map +1 -0
- package/dist/library/motion/press.d.ts.map +1 -1
- package/dist/library/motion/press.js +41 -14
- package/dist/library/motion/press.js.map +1 -1
- package/dist/library/motion/pressPolicy.d.ts.map +1 -1
- package/dist/library/motion/pressPolicy.js +2 -2
- package/dist/library/motion/pressPolicy.js.map +1 -1
- package/dist/library/motion/react.d.ts.map +1 -1
- package/dist/library/motion/react.js +3 -1
- package/dist/library/motion/react.js.map +1 -1
- package/dist/library/motion/transitions.d.ts.map +1 -1
- package/dist/library/motion/transitions.js +48 -15
- package/dist/library/motion/transitions.js.map +1 -1
- package/dist/library/react/useControllableState.d.ts +1 -0
- package/dist/library/react/useControllableState.d.ts.map +1 -1
- package/dist/library/react/useControllableState.js +8 -1
- package/dist/library/react/useControllableState.js.map +1 -1
- package/dist/library/selectStyles.d.ts +4 -0
- package/dist/library/selectStyles.d.ts.map +1 -0
- package/dist/library/selectStyles.js +32 -0
- package/dist/library/selectStyles.js.map +1 -0
- package/dist/library/styles.css +1 -1
- package/dist/library/themes/components.d.ts +24 -0
- package/dist/library/themes/components.d.ts.map +1 -1
- package/dist/library/themes/components.js +24 -0
- package/dist/library/themes/components.js.map +1 -1
- package/dist/library/themes/index.d.ts +1 -11
- package/dist/library/themes/index.d.ts.map +1 -1
- package/dist/library/themes/index.js +1 -19
- package/dist/library/themes/index.js.map +1 -1
- package/docs/accessibility.md +76 -142
- package/docs/architecture.md +208 -0
- package/docs/motion.md +115 -396
- package/docs/theming.md +275 -882
- package/package.json +9 -5
- package/src/Accordion.tsx +4 -1
- package/src/Button.tsx +13 -7
- package/src/Card.tsx +3 -1
- package/src/Checkbox.tsx +7 -2
- package/src/Collapsible.tsx +28 -4
- package/src/Dialog.tsx +3 -0
- package/src/Field.tsx +8 -0
- package/src/Input.tsx +3 -0
- package/src/Link.tsx +5 -0
- package/src/RadioGroup.tsx +10 -2
- package/src/Select.tsx +781 -0
- package/src/cn.ts +20 -3
- package/src/{themes → examples}/expressive.ts +5 -3
- package/src/{themes → examples}/glass.ts +10 -3
- package/src/examples/index.ts +35 -0
- package/src/{themes → examples}/jelly.ts +5 -3
- package/src/{themes → examples}/radiant.ts +5 -3
- package/src/{themes → examples}/sharp-3d.ts +5 -3
- package/src/{themes → examples}/soft-squircle.ts +5 -3
- package/src/{themes → examples}/ticket.ts +5 -3
- package/src/index.ts +28 -13
- package/src/internal/select.ts +80 -0
- package/src/motion/MotionLink.tsx +16 -11
- package/src/motion/host.ts +16 -7
- package/src/motion/popup.ts +55 -0
- package/src/motion/press.ts +32 -12
- package/src/motion/pressPolicy.ts +4 -2
- package/src/motion/react.ts +3 -1
- package/src/motion/transitions.ts +45 -14
- package/src/react/useControllableState.ts +7 -1
- package/src/selectStyles.ts +34 -0
- package/src/themes/components.ts +24 -0
- package/src/themes/index.ts +1 -22
- package/dist/library/themes/expressive.d.ts +0 -2
- package/dist/library/themes/expressive.d.ts.map +0 -1
- package/dist/library/themes/expressive.js.map +0 -1
- package/dist/library/themes/glass.d.ts +0 -2
- package/dist/library/themes/glass.d.ts.map +0 -1
- package/dist/library/themes/glass.js.map +0 -1
- package/dist/library/themes/jelly.d.ts +0 -2
- package/dist/library/themes/jelly.d.ts.map +0 -1
- package/dist/library/themes/jelly.js.map +0 -1
- package/dist/library/themes/preset-values.d.ts.map +0 -1
- package/dist/library/themes/preset-values.js.map +0 -1
- package/dist/library/themes/radiant.d.ts +0 -2
- package/dist/library/themes/radiant.d.ts.map +0 -1
- package/dist/library/themes/radiant.js.map +0 -1
- package/dist/library/themes/sharp-3d.d.ts +0 -2
- package/dist/library/themes/sharp-3d.d.ts.map +0 -1
- package/dist/library/themes/sharp-3d.js.map +0 -1
- package/dist/library/themes/soft-squircle.d.ts +0 -2
- package/dist/library/themes/soft-squircle.d.ts.map +0 -1
- package/dist/library/themes/soft-squircle.js.map +0 -1
- package/dist/library/themes/ticket.d.ts +0 -2
- package/dist/library/themes/ticket.d.ts.map +0 -1
- package/dist/library/themes/ticket.js.map +0 -1
- package/docs/system.md +0 -264
- /package/dist/library/{themes → examples}/preset-values.d.ts +0 -0
- /package/dist/library/{themes → examples}/preset-values.js +0 -0
- /package/src/{themes → examples}/preset-values.ts +0 -0
package/docs/motion.md
CHANGED
|
@@ -1,168 +1,41 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Motion
|
|
2
2
|
|
|
3
|
-
Radiant
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
drag/snap, changing-target values and measured layout groups. Importing numeric
|
|
7
|
-
interfaces alone does not enable native component motion.
|
|
3
|
+
Radiant's spring motion is opt-in. It uses Motion's physics behind
|
|
4
|
+
Radiant-owned bindings; see the [engine decision](adr/0001-spring-engine-boundaries.md).
|
|
5
|
+
Import `@cognitap/radiant/motion` or `/motion/react` for the runtime.
|
|
8
6
|
|
|
9
|
-
## Theme
|
|
7
|
+
## Theme profiles
|
|
10
8
|
|
|
11
9
|
```tsx
|
|
12
|
-
import {defineTheme, ThemeScope} from '@cognitap/radiant'
|
|
13
|
-
|
|
14
10
|
const theme = defineTheme({
|
|
15
|
-
id: 'brand',
|
|
11
|
+
id: 'brand',
|
|
12
|
+
name: 'Brand',
|
|
16
13
|
motion: {
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
interactions: {press: {stiffness: 400, damping: 34}}
|
|
14
|
+
spring: { stiffness: 320, damping: 30, mass: 1 },
|
|
15
|
+
interactions: { press: { stiffness: 400, damping: 34 } }
|
|
20
16
|
}
|
|
21
17
|
})
|
|
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
18
|
```
|
|
123
19
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
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.
|
|
20
|
+
| Field | Rule |
|
|
21
|
+
| --------------------- | ----------------------------------------------------------------------------------- |
|
|
22
|
+
| `spring` | Default 320 / 30 / 1. Stiffness and damping in (0, 10000], mass in (0, 100] |
|
|
23
|
+
| `interactions.<name>` | `press`, `disclosure`, `dialog`, `follow`, `drag`, `layout`; each inherits `spring` |
|
|
24
|
+
| `mode` | `system` (default) or `off` |
|
|
140
25
|
|
|
141
|
-
|
|
26
|
+
Reduced motion always wins. ThemeScope inherits its
|
|
27
|
+
theme's profile, and switching light or dark mode does not change it. Theme
|
|
28
|
+
documents store it at `sections.motion.profile`. The CSS duration and easing
|
|
29
|
+
tokens still drive ordinary CSS transitions.
|
|
142
30
|
|
|
143
|
-
|
|
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
|
|
31
|
+
## Component motion
|
|
158
32
|
|
|
159
33
|
```tsx
|
|
160
|
-
import { Button } from '@cognitap/radiant'
|
|
161
34
|
import { MotionProvider, MotionLink } from '@cognitap/radiant/motion/react'
|
|
162
35
|
|
|
163
36
|
;<MotionProvider>
|
|
164
|
-
<Button
|
|
165
|
-
<Button motion="off">
|
|
37
|
+
<Button>Save</Button>
|
|
38
|
+
<Button motion="off">No spring</Button>
|
|
166
39
|
<MotionLink
|
|
167
40
|
variant="solid"
|
|
168
41
|
href="/account"
|
|
@@ -172,263 +45,109 @@ import { MotionProvider, MotionLink } from '@cognitap/radiant/motion/react'
|
|
|
172
45
|
</MotionProvider>
|
|
173
46
|
```
|
|
174
47
|
|
|
175
|
-
MotionProvider adds no DOM
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
`--rad-button-press-scale` (default .97,
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
motion
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
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
|
|
48
|
+
`MotionProvider` adds no DOM. Inside it:
|
|
49
|
+
|
|
50
|
+
- Button, DialogTrigger and DialogClose compress on press, using
|
|
51
|
+
`--rad-button-press-scale` (default 0.97, range 0.5–1). Use `MotionLink` for
|
|
52
|
+
action-shaped links; plain Link stays server-renderable. Only the active
|
|
53
|
+
pointer or key releases its press.
|
|
54
|
+
- Collapsible and Accordion animate natural height, including replacement and
|
|
55
|
+
resized content. Closed content is inert immediately. Before hydration,
|
|
56
|
+
native details controls visibility. Neither scales its children.
|
|
57
|
+
- Dialog springs open and closes natively immediately. An inert copy finishes
|
|
58
|
+
exit, bounded to 500 descendants and two seconds. Nested dialogs, media,
|
|
59
|
+
canvas, embeds and custom elements (including customized built-ins) skip it.
|
|
60
|
+
- Select reuses Button press and dialog springs for popup opacity. Closing is immediate.
|
|
61
|
+
|
|
62
|
+
Set `motion="off"` on Button, MotionLink, Collapsible, SelectContent or DialogContent.
|
|
63
|
+
Theme off and reduced motion suppress springs and CSS lift/shift. Pending and
|
|
64
|
+
disabled cancel a held press; re-enabling never replays it. Native activation,
|
|
65
|
+
focus and Escape stay immediate; `preventDefault` cancels compression.
|
|
66
|
+
Caller scale utilities and inline scale/scale transitions opt out. Other scale
|
|
67
|
+
styles need `motion="off"`. Explore [Link](../src/Link.stories.tsx) and [Button](../src/Button.stories.tsx).
|
|
68
|
+
|
|
69
|
+
## Hooks and functions
|
|
70
|
+
|
|
71
|
+
| API | Entry | Use |
|
|
72
|
+
| ---------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------- |
|
|
73
|
+
| `createSpring(initial, options)` | `/motion` | A numeric spring: `to`, `jump`, `stop`, `get`, `getVelocity`, `subscribe`, `configure`, `destroy` |
|
|
74
|
+
| `bindSpringStyle(el, spring, prop)` | `/motion` | Drive `scale`, `opacity`, `width`, `height`, `translateX` or `translateY` |
|
|
75
|
+
| `useSpring`, `useSpringStyle` | `/motion/react` | The same, owned by a component and the theme profile |
|
|
76
|
+
| `useReducedMotion` | `/motion/react` | The live system preference |
|
|
77
|
+
| `useSpringFollow(target)` | `/motion/react` | Follow a changing number or a `SpringSource` (`get`, `subscribe`) |
|
|
78
|
+
| `bindSpringSource(spring, source)` | `/motion` | The same, managed by hand |
|
|
79
|
+
| `useSpringDrag(ref, initial, opts)` | `/motion/react` | One-axis drag with bounds and snap points |
|
|
80
|
+
| `createSpringDrag`, `bindSpringDrag` | `/motion` | The same, managed by hand |
|
|
81
|
+
| `useSpringLayout(ref)` | `/motion/react` | Animate resize and reorder of a grid or flex group |
|
|
82
|
+
| `bindSpringLayout(root)`, `createLayoutSpring` | `/motion` | The same, managed by hand |
|
|
83
|
+
|
|
84
|
+
Hooks follow the theme profile and reduced motion for you. With the plain
|
|
85
|
+
functions, you pass `enabled` and call `destroy`.
|
|
86
|
+
|
|
87
|
+
Rules for every spring:
|
|
88
|
+
|
|
89
|
+
- Values are finite numbers in one unit. Convert percentages, colors and CSS
|
|
90
|
+
variables first.
|
|
91
|
+
- A new target keeps the current position and momentum. New physics apply once
|
|
92
|
+
the spring rests.
|
|
93
|
+
- With motion off or reduced, a spring jumps straight to its target, or to
|
|
94
|
+
`reducedValue` if you set one.
|
|
95
|
+
- A bound style property belongs to the spring until cleanup. Don't animate it
|
|
96
|
+
or give it a CSS transition elsewhere. Cleanup restores the previous value.
|
|
97
|
+
- Server rendering never animates, and hooks never store frames in React state.
|
|
98
|
+
|
|
99
|
+
## Drag
|
|
100
|
+
|
|
101
|
+
Release velocity comes from recent pointer samples. The handle settles on the
|
|
102
|
+
snap point nearest to where it would land 180ms ahead. Arrow keys move between
|
|
103
|
+
snap points, Home and End go to the ends, and Escape cancels. A finished drag
|
|
104
|
+
swallows the click that follows it. With reduced motion, dragging still works
|
|
105
|
+
and only the settling is instant.
|
|
106
|
+
|
|
107
|
+
## Layout
|
|
337
108
|
|
|
338
109
|
```tsx
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
const root = useRef<HTMLDivElement>(null)
|
|
345
|
-
useSpringLayout(root)
|
|
346
|
-
return (
|
|
110
|
+
<div
|
|
111
|
+
ref={root}
|
|
112
|
+
className="grid grid-cols-2 gap-4"
|
|
113
|
+
>
|
|
114
|
+
{items.map(item => (
|
|
347
115
|
<div
|
|
348
|
-
|
|
349
|
-
|
|
116
|
+
key={item.id}
|
|
117
|
+
data-rad-layout-slot=""
|
|
118
|
+
className="flow-root"
|
|
350
119
|
>
|
|
351
|
-
|
|
352
|
-
<
|
|
353
|
-
|
|
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
|
-
))}
|
|
120
|
+
<div data-rad-layout-part="">
|
|
121
|
+
<Card>{item.title}</Card>
|
|
122
|
+
</div>
|
|
362
123
|
</div>
|
|
363
|
-
)
|
|
364
|
-
|
|
124
|
+
))}
|
|
125
|
+
</div>
|
|
365
126
|
```
|
|
366
127
|
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
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.
|
|
128
|
+
Each direct child of the root is a slot with one part inside. Keep their keys
|
|
129
|
+
stable. Text reflows at the animated width; nothing is scaled or cloned. Items
|
|
130
|
+
that enter or leave appear at once.
|
|
391
131
|
|
|
392
|
-
|
|
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.
|
|
132
|
+
The [Card dashboard](../.storybook/examples/CardExamples.tsx) preserves styles and focus.
|
|
399
133
|
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
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.
|
|
134
|
+
- Slots carry no padding, border or positioning. Put decoration on the part,
|
|
135
|
+
which needs no outer margin.
|
|
136
|
+
- Don't transform, transition or position the slot or part yourself.
|
|
137
|
+
- The root and its ancestors must not be scaled, rotated or zoomed.
|
|
138
|
+
- Nested layout groups, sticky or fixed slots and shared-element morphs are not
|
|
139
|
+
supported.
|
|
409
140
|
|
|
410
|
-
|
|
141
|
+
React commits measure automatically. Call `measure()` after changing a slot's
|
|
142
|
+
or part's own styles. Moving focus during a reorder is the application's job.
|
|
411
143
|
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
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.
|
|
144
|
+
Wrap Fields in dedicated parts with stable slots, as in the
|
|
145
|
+
[Field example](../.storybook/examples/FieldExamples.tsx). Only surrounding space
|
|
146
|
+
moves; errors and relationships stay immediate. Keep validation and focus in the
|
|
147
|
+
consumer. The [Input editor](../.storybook/examples/InputExamples.tsx) springs a
|
|
148
|
+
separate focus cue, preserving the native ring, caret and caller styles.
|
|
432
149
|
|
|
433
|
-
The
|
|
434
|
-
|
|
150
|
+
The [Checkbox permissions example](../.storybook/examples/CheckboxExamples.tsx)
|
|
151
|
+
uses `useSpring` and `parts.indicator` for decorative entry feedback. Checked and
|
|
152
|
+
mixed semantics stay native. Disabled changes settle the glyph, and indicator
|
|
153
|
+
customization takes ownership. The local adapter keeps frame writes outside React.
|