@cognitap/radiant 0.0.5 → 0.0.7
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 +68 -368
- package/README.md +41 -1006
- 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 +8 -1
- package/dist/library/Button.d.ts.map +1 -1
- package/dist/library/Button.js +44 -2
- 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 +6 -1
- package/dist/library/Collapsible.d.ts.map +1 -1
- package/dist/library/Collapsible.js +24 -3
- package/dist/library/Collapsible.js.map +1 -1
- package/dist/library/Dialog.d.ts +5 -1
- package/dist/library/Dialog.d.ts.map +1 -1
- package/dist/library/Dialog.js +5 -2
- 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/ThemeScope.d.ts.map +1 -1
- package/dist/library/ThemeScope.js +10 -9
- package/dist/library/ThemeScope.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 +4 -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 +4 -2
- 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/motion/MotionLink.d.ts +8 -0
- package/dist/library/motion/MotionLink.d.ts.map +1 -0
- package/dist/library/motion/MotionLink.js +44 -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 +30 -0
- package/dist/library/motion/host.d.ts.map +1 -0
- package/dist/library/motion/host.js +70 -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 +99 -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 +244 -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 +4 -2
- package/dist/library/themes/defineTheme.js.map +1 -1
- package/dist/library/themes/index.d.ts +2 -12
- 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/dist/library/themes/themeDocument.d.ts.map +1 -1
- package/dist/library/themes/themeDocument.js +11 -5
- package/dist/library/themes/themeDocument.js.map +1 -1
- package/dist/library/themes/themeDocumentTypes.d.ts +5 -1
- package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -1
- package/dist/library/themes/themeDocumentTypes.js.map +1 -1
- package/docs/accessibility.md +76 -142
- package/docs/architecture.md +197 -0
- package/docs/motion.md +153 -0
- package/docs/theming.md +275 -882
- package/package.json +22 -7
- package/src/Accordion.tsx +4 -1
- package/src/Button.tsx +55 -1
- package/src/Card.tsx +3 -1
- package/src/Checkbox.tsx +7 -2
- package/src/Collapsible.tsx +38 -2
- package/src/Dialog.tsx +13 -1
- 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/ThemeScope.tsx +21 -17
- package/src/{themes → examples}/expressive.ts +5 -3
- package/src/{themes → examples}/glass.ts +5 -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 +10 -13
- package/src/motion/MotionLink.tsx +69 -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 +96 -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 +97 -0
- package/src/motion/pressPolicy.ts +14 -0
- package/src/motion/react.ts +272 -0
- package/src/motion/runtime.ts +122 -0
- package/src/motion/transitions.ts +237 -0
- package/src/themes/defineTheme.ts +10 -2
- package/src/themes/index.ts +2 -22
- package/src/themes/themeDocument.ts +14 -6
- package/src/themes/themeDocumentTypes.ts +12 -5
- 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 -238
- /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
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
How Radiant's ten families fit together and why. Props are on the
|
|
4
|
+
[docs site](https://github.com/cognitap/radiant-docs); themes are in [theming](theming.md); springs are in
|
|
5
|
+
[motion](motion.md).
|
|
6
|
+
|
|
7
|
+
The families are Button, Link, Field, Input, Checkbox, RadioGroup (with Radio),
|
|
8
|
+
Dialog, Collapsible, Accordion and Card. All ship in one package,
|
|
9
|
+
`@cognitap/radiant`. Deep imports are unsupported.
|
|
10
|
+
|
|
11
|
+
## Native first
|
|
12
|
+
|
|
13
|
+
Each piece of behavior has one owner:
|
|
14
|
+
|
|
15
|
+
| Responsibility | Owner |
|
|
16
|
+
| ------------------------------------------------------ | ----------------------------------------------- |
|
|
17
|
+
| Activation, radio grouping, disclosure, modal dialog | The native element |
|
|
18
|
+
| Selection rules, ID merging and other reusable policy | Private modules in `src/internal/`, no React |
|
|
19
|
+
| Rendering, context, state hooks, event and ref wiring | React bindings in `src/react/` and family roots |
|
|
20
|
+
| Appearance | Shared tokens and component overrides |
|
|
21
|
+
| Content, validation, routing, fetching and persistence | The consumer |
|
|
22
|
+
|
|
23
|
+
Why: the browser already gets keyboard, focus and form behavior right.
|
|
24
|
+
Radiant wraps native elements and has no headless-library dependency.
|
|
25
|
+
|
|
26
|
+
Import rules:
|
|
27
|
+
|
|
28
|
+
1. `internal` never imports React, a binding, a family or app code.
|
|
29
|
+
2. `react` imports `internal` and React, never a family.
|
|
30
|
+
3. Families compose other families explicitly (Accordion uses Collapsible,
|
|
31
|
+
RadioGroup uses Field, Dialog actions use Button). The graph stays acyclic.
|
|
32
|
+
4. Nothing touches `window`, `document` or the DOM at import time. Effects use
|
|
33
|
+
the owning document and clean up on unmount.
|
|
34
|
+
5. Server markup matches the first client render. For example, a native dialog
|
|
35
|
+
opens in an effect, not during render.
|
|
36
|
+
|
|
37
|
+
Extract a shared module only when a policy really repeats.
|
|
38
|
+
|
|
39
|
+
## Composition
|
|
40
|
+
|
|
41
|
+
Use Button for actions and Link for navigation, even when a Link looks like a
|
|
42
|
+
button. Field owns label, help and error relationships. Card groups content.
|
|
43
|
+
Dialog owns open state. Collapsible owns one disclosure, and Accordion composes
|
|
44
|
+
Collapsible for a set of them.
|
|
45
|
+
|
|
46
|
+
Composed families reuse the real thing: DialogTrigger and DialogClose are
|
|
47
|
+
Buttons, RadioGroup is a Field, and an Accordion item is a Collapsible, so
|
|
48
|
+
theme, keyboard behavior and relationships travel together.
|
|
49
|
+
|
|
50
|
+
## Presentation
|
|
51
|
+
|
|
52
|
+
Actions take three independent props:
|
|
53
|
+
|
|
54
|
+
| Prop | Values | Default |
|
|
55
|
+
| ------------- | ------------------------------------------------------------------------- | ----------------------------- |
|
|
56
|
+
| `variant` | `solid`, `soft`, `outline`, `ghost`; Link also accepts `inline`, `subtle` | Button `solid`; Link `inline` |
|
|
57
|
+
| `tone` | `accent`, `neutral`, `warning`, `danger` | `accent` |
|
|
58
|
+
| `controlSize` | `small`, `medium`, `large` | `medium` |
|
|
59
|
+
|
|
60
|
+
A variant picks the treatment and a tone picks the palette. Input, Checkbox,
|
|
61
|
+
Radio and RadioGroup share `controlSize` but have no variants. Native meanings
|
|
62
|
+
win: `Input.size` stays a character count, and a checkbox `value` stays its
|
|
63
|
+
submitted data. Radius is a theme decision, not a prop.
|
|
64
|
+
|
|
65
|
+
Button defaults to `type="button"`. `pending` blocks activation but keeps focus
|
|
66
|
+
and the accessible name. Link is always an anchor and has no fake `disabled`.
|
|
67
|
+
|
|
68
|
+
## Themes
|
|
69
|
+
|
|
70
|
+
A theme is one typed `defineTheme({ id, name, tokens, components, modes })`
|
|
71
|
+
definition. Values resolve as **component override → shared token → neutral
|
|
72
|
+
baseline**, and never fall back through another family's override. Why: a
|
|
73
|
+
change to shared tokens should reach every family, and an exception should stay
|
|
74
|
+
local. A Button-only font does not become body text.
|
|
75
|
+
|
|
76
|
+
The core entry ships only the neutral baseline, `defaultTheme`. Styled presets
|
|
77
|
+
are examples at `@cognitap/radiant/examples`, and Storybook, the docs and the
|
|
78
|
+
theme workshop all read that one copy. Why: a preset is a starting point to copy
|
|
79
|
+
or edit, not a contract the library has to keep stable.
|
|
80
|
+
|
|
81
|
+
`ThemeScope` is a plain `div` that applies a theme to its subtree. It does not
|
|
82
|
+
touch the document or persist anything. Without `theme` or `mode` it inherits.
|
|
83
|
+
A named theme starts fresh from the library defaults, so a nested `default`
|
|
84
|
+
really resets an outer theme. `mode` (`light`, `dark` or `system`) is
|
|
85
|
+
independent of the theme, and `system` uses CSS media queries so server markup
|
|
86
|
+
stays stable. Token names, CSS variables, scopes and presets are in
|
|
87
|
+
[theming](theming.md).
|
|
88
|
+
|
|
89
|
+
## Hosts and targeting
|
|
90
|
+
|
|
91
|
+
Root `className`, `style`, native props and `ref` always reach the documented
|
|
92
|
+
host, never a wrapper:
|
|
93
|
+
|
|
94
|
+
| Family or part | Host |
|
|
95
|
+
| --------------------------------------------------------------- | --------------------------------------------------- |
|
|
96
|
+
| Button / Link | `button` / `a`, including through `render` |
|
|
97
|
+
| Field | `div` in control layout; `fieldset` in group layout |
|
|
98
|
+
| Input / Checkbox / Radio | Native `input` |
|
|
99
|
+
| RadioGroup | Field's `fieldset` |
|
|
100
|
+
| Dialog | None; it only owns state |
|
|
101
|
+
| DialogTrigger / DialogClose | Button's `button` |
|
|
102
|
+
| DialogContent / DialogTitle / DialogDescription | `dialog` / `h2` / `p` |
|
|
103
|
+
| Collapsible / CollapsibleTrigger / CollapsibleContent | `details` / `summary` / `div` |
|
|
104
|
+
| Accordion / AccordionItem / AccordionTrigger / AccordionContent | `div` / `details` / `summary` / `div` |
|
|
105
|
+
| Card / CardHeader / CardContent / CardFooter | `div` |
|
|
106
|
+
| CardTitle / CardDescription | Heading chosen by `level` / `p` |
|
|
107
|
+
|
|
108
|
+
Internal parts take `className` and `style` through a `parts` map. Field has
|
|
109
|
+
`label`, `description`, `error` and `required`. Checkbox and Radio have
|
|
110
|
+
`wrapper`, `label` and `indicator`, and RadioGroup adds `options`. These hooks
|
|
111
|
+
cannot replace IDs, ARIA, handlers or refs. Caller classes merge after the
|
|
112
|
+
defaults and caller `style` wins. Identity and presentation data attributes
|
|
113
|
+
cannot be overridden.
|
|
114
|
+
|
|
115
|
+
`data-slot` is a space-separated set, so select with `~=`, as in
|
|
116
|
+
`[data-slot~="button"]`. Composed parts keep their base identity:
|
|
117
|
+
`button dialog-trigger`, `field radio-group`, `collapsible accordion-item`.
|
|
118
|
+
Why: styling written for Button still reaches a DialogTrigger.
|
|
119
|
+
|
|
120
|
+
Style real state: native `:disabled`, `:checked` and `open`, plus `aria-busy`
|
|
121
|
+
for pending. Field and RadioGroup set `data-invalid`, `data-disabled` and
|
|
122
|
+
`data-required`. Disclosures and DialogContent set `data-state="open|closed"`.
|
|
123
|
+
Actions set `data-variant`, `data-tone` and `data-control-size`.
|
|
124
|
+
|
|
125
|
+
## State and forms
|
|
126
|
+
|
|
127
|
+
Each state axis has one owner for the life of a mount. Pass `value`, `checked`
|
|
128
|
+
or `open` to control it, or `default*` to set an initial value. Passing both, or switching owner during
|
|
129
|
+
a mount, throws; remount with a new `key` instead. A controlled callback is a request, and the consumer
|
|
130
|
+
may refuse it. No-op requests and prop syncs fire no callback.
|
|
131
|
+
|
|
132
|
+
| Family | State | Callback | Empty |
|
|
133
|
+
| -------------------------- | ---------------------------- | -------------------------------------------- | ------- |
|
|
134
|
+
| Input | `value` / `defaultValue` | Native `onChange`, `onBlur` | `''` |
|
|
135
|
+
| Checkbox, standalone Radio | `checked` / `defaultChecked` | Native `onChange`, `onBlur` | `false` |
|
|
136
|
+
| RadioGroup | `value` / `defaultValue` | `onValueChange(string)` or native `onChange` | `null` |
|
|
137
|
+
| Dialog, Collapsible | `open` / `defaultOpen` | `onOpenChange(boolean)` | `false` |
|
|
138
|
+
| Accordion single | `value` / `defaultValue` | `onValueChange(string \| null)` | `null` |
|
|
139
|
+
| Accordion multiple | `value` / `defaultValue` | `onValueChange(string[])` | `[]` |
|
|
140
|
+
|
|
141
|
+
RadioGroup owns its options' `name` and selection. Use one of `onValueChange`
|
|
142
|
+
or `onChange` to write state, not both. `''` is a valid option value, and `null`
|
|
143
|
+
clears the group.
|
|
144
|
+
|
|
145
|
+
Field owns IDs and label, help and error relationships. Set a control's ID with
|
|
146
|
+
Field's `controlId`. Radiant controls read Field context. A native control uses
|
|
147
|
+
`children(controlProps)` and forwards those props. Disabled and required only
|
|
148
|
+
add up: a child cannot re-enable or un-require what its Field set.
|
|
149
|
+
|
|
150
|
+
The consumer owns validation, touched and dirty state, error text, submission
|
|
151
|
+
and persistence. Native reset restores uncontrolled inputs. A controlled adapter
|
|
152
|
+
resets its own values. Reset never changes Dialog or disclosure state. Why: form
|
|
153
|
+
libraries differ, and Radiant should fit any of them without a hidden form
|
|
154
|
+
store. TanStack Form is an optional example adapter, not a dependency.
|
|
155
|
+
|
|
156
|
+
## Replacement and events
|
|
157
|
+
|
|
158
|
+
Button, Link and the Dialog actions accept `render(resolvedProps)`. Forward all
|
|
159
|
+
props, the ref and the children to one compatible `button` or `a`. There is no
|
|
160
|
+
`as` or `asChild`. Why: one convention, and the resolved props already carry
|
|
161
|
+
presentation, relationships and guards, so an adapter cannot drop them by
|
|
162
|
+
accident. Field's `children(controlProps)` adapts relationships and does not
|
|
163
|
+
replace Field's host.
|
|
164
|
+
|
|
165
|
+
For cancellable actions, disabled and pending guards run first, then the
|
|
166
|
+
consumer handler, then the state request if `defaultPrevented` is false. Native
|
|
167
|
+
change, toggle and blur are observations and cannot veto anything. Library and
|
|
168
|
+
caller refs get the same host, and callback-ref cleanup functions are honored.
|
|
169
|
+
`useField`, `useDialog`, `useCollapsible` and `useAccordion` read and request
|
|
170
|
+
state, and return `null` outside their owner. Parts that need a root throw when misplaced. Lifecycle,
|
|
171
|
+
SSR and hydration details are in [React bindings](react-bindings.md).
|
|
172
|
+
|
|
173
|
+
## What customization must keep
|
|
174
|
+
|
|
175
|
+
Restyling or replacing a host is fine as long as these keep working:
|
|
176
|
+
|
|
177
|
+
- Native controls and labels stay operable, with names and descriptions connected.
|
|
178
|
+
- Focus, invalid, disabled and pending cues stay visible.
|
|
179
|
+
- Closed dialog and details content stays hidden. Dialog keeps its bounds,
|
|
180
|
+
scrolling and modal focus, and `details` keeps a direct-child `summary`.
|
|
181
|
+
- Decorative indicators stay hidden from assistive technology.
|
|
182
|
+
- Reduced-motion and forced-colors modes still work.
|
|
183
|
+
|
|
184
|
+
Passing the type check alone does not prove any of this. See
|
|
185
|
+
[accessibility](accessibility.md) for what to check by hand.
|
|
186
|
+
|
|
187
|
+
## Examples and type fixtures
|
|
188
|
+
|
|
189
|
+
The canonical live examples are Storybook stories:
|
|
190
|
+
[Input](../src/Input.stories.tsx), [Recipes → Forms](../src/Form.stories.tsx)
|
|
191
|
+
(one form, plain or in a Card or Dialog, optionally with TanStack) and
|
|
192
|
+
[Recipes → Workspace → Settings](../src/Workspace.stories.tsx) (all ten
|
|
193
|
+
families). Change a contract and its example together.
|
|
194
|
+
|
|
195
|
+
`docs/contracts/*.ts(x)` are compile-only fixtures. `pnpm typecheck:contracts`
|
|
196
|
+
checks that they type-check and that contradictory props, such as `value` with
|
|
197
|
+
`defaultValue`, are rejected.
|
package/docs/motion.md
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Motion
|
|
2
|
+
|
|
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
|
+
The root package carries only configuration and types. Import
|
|
6
|
+
`@cognitap/radiant/motion` or `/motion/react` to use the runtime.
|
|
7
|
+
|
|
8
|
+
## Theme profiles
|
|
9
|
+
|
|
10
|
+
```tsx
|
|
11
|
+
const theme = defineTheme({
|
|
12
|
+
id: 'brand',
|
|
13
|
+
name: 'Brand',
|
|
14
|
+
motion: {
|
|
15
|
+
spring: { stiffness: 320, damping: 30, mass: 1 },
|
|
16
|
+
interactions: { press: { stiffness: 400, damping: 34 } }
|
|
17
|
+
}
|
|
18
|
+
})
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
| Field | Rule |
|
|
22
|
+
| --------------------- | ----------------------------------------------------------------------------------- |
|
|
23
|
+
| `spring` | Default 320 / 30 / 1. Stiffness and damping in (0, 10000], mass in (0, 100] |
|
|
24
|
+
| `interactions.<name>` | `press`, `disclosure`, `dialog`, `follow`, `drag`, `layout`; each inherits `spring` |
|
|
25
|
+
| `mode` | `system` (default) or `off` |
|
|
26
|
+
|
|
27
|
+
The system reduced-motion setting always wins. A nested ThemeScope inherits its
|
|
28
|
+
theme's profile, and switching light or dark mode does not change it. Theme
|
|
29
|
+
documents store it at `sections.motion.profile`. The CSS duration and easing
|
|
30
|
+
tokens still drive ordinary CSS transitions.
|
|
31
|
+
|
|
32
|
+
## Component motion
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
import { MotionProvider, MotionLink } from '@cognitap/radiant/motion/react'
|
|
36
|
+
|
|
37
|
+
;<MotionProvider>
|
|
38
|
+
<Button>Save</Button>
|
|
39
|
+
<Button motion="off">No spring</Button>
|
|
40
|
+
<MotionLink
|
|
41
|
+
variant="solid"
|
|
42
|
+
href="/account"
|
|
43
|
+
>
|
|
44
|
+
Account
|
|
45
|
+
</MotionLink>
|
|
46
|
+
</MotionProvider>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`MotionProvider` adds no DOM. Inside it:
|
|
50
|
+
|
|
51
|
+
- Button, DialogTrigger and DialogClose compress on press, using
|
|
52
|
+
`--rad-button-press-scale` (default 0.97, range 0.5–1). Use `MotionLink` for
|
|
53
|
+
action-shaped links; plain Link stays server-renderable. Only the active
|
|
54
|
+
pointer or key releases its press.
|
|
55
|
+
- Collapsible and Accordion animate natural height, including replacement and
|
|
56
|
+
resized content. Closed content is inert immediately. Before hydration,
|
|
57
|
+
native details controls visibility. Neither scales its children.
|
|
58
|
+
- Dialog springs open and closes natively immediately. An inert copy finishes
|
|
59
|
+
exit, bounded to 500 descendants and two seconds. Nested dialogs, media,
|
|
60
|
+
canvas, embeds and custom elements (including customized built-ins) skip it.
|
|
61
|
+
|
|
62
|
+
Set `motion="off"` on Button, MotionLink, Collapsible 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
|
|
108
|
+
|
|
109
|
+
```tsx
|
|
110
|
+
<div
|
|
111
|
+
ref={root}
|
|
112
|
+
className="grid grid-cols-2 gap-4"
|
|
113
|
+
>
|
|
114
|
+
{items.map(item => (
|
|
115
|
+
<div
|
|
116
|
+
key={item.id}
|
|
117
|
+
data-rad-layout-slot=""
|
|
118
|
+
className="flow-root"
|
|
119
|
+
>
|
|
120
|
+
<div data-rad-layout-part="">
|
|
121
|
+
<Card>{item.title}</Card>
|
|
122
|
+
</div>
|
|
123
|
+
</div>
|
|
124
|
+
))}
|
|
125
|
+
</div>
|
|
126
|
+
```
|
|
127
|
+
|
|
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.
|
|
131
|
+
|
|
132
|
+
The [Card dashboard](../.storybook/examples/CardExamples.tsx) preserves styles and focus.
|
|
133
|
+
|
|
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.
|
|
140
|
+
|
|
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.
|
|
143
|
+
|
|
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.
|
|
149
|
+
|
|
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.
|