@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.
Files changed (234) hide show
  1. package/CHANGELOG.md +68 -368
  2. package/README.md +41 -1006
  3. package/RELEASE_POLICY.md +3 -3
  4. package/dist/library/Accordion.d.ts +3 -0
  5. package/dist/library/Accordion.d.ts.map +1 -1
  6. package/dist/library/Accordion.js +1 -1
  7. package/dist/library/Accordion.js.map +1 -1
  8. package/dist/library/Button.d.ts +8 -1
  9. package/dist/library/Button.d.ts.map +1 -1
  10. package/dist/library/Button.js +44 -2
  11. package/dist/library/Button.js.map +1 -1
  12. package/dist/library/Card.d.ts +2 -0
  13. package/dist/library/Card.d.ts.map +1 -1
  14. package/dist/library/Card.js +1 -1
  15. package/dist/library/Card.js.map +1 -1
  16. package/dist/library/Checkbox.d.ts +5 -0
  17. package/dist/library/Checkbox.d.ts.map +1 -1
  18. package/dist/library/Checkbox.js +3 -2
  19. package/dist/library/Checkbox.js.map +1 -1
  20. package/dist/library/Collapsible.d.ts +6 -1
  21. package/dist/library/Collapsible.d.ts.map +1 -1
  22. package/dist/library/Collapsible.js +24 -3
  23. package/dist/library/Collapsible.js.map +1 -1
  24. package/dist/library/Dialog.d.ts +5 -1
  25. package/dist/library/Dialog.d.ts.map +1 -1
  26. package/dist/library/Dialog.js +5 -2
  27. package/dist/library/Dialog.js.map +1 -1
  28. package/dist/library/Field.d.ts +8 -0
  29. package/dist/library/Field.d.ts.map +1 -1
  30. package/dist/library/Field.js +2 -0
  31. package/dist/library/Field.js.map +1 -1
  32. package/dist/library/Input.d.ts +3 -0
  33. package/dist/library/Input.d.ts.map +1 -1
  34. package/dist/library/Input.js +1 -0
  35. package/dist/library/Input.js.map +1 -1
  36. package/dist/library/Link.d.ts +5 -0
  37. package/dist/library/Link.d.ts.map +1 -1
  38. package/dist/library/Link.js.map +1 -1
  39. package/dist/library/RadioGroup.d.ts +8 -0
  40. package/dist/library/RadioGroup.d.ts.map +1 -1
  41. package/dist/library/RadioGroup.js +4 -2
  42. package/dist/library/RadioGroup.js.map +1 -1
  43. package/dist/library/ThemeScope.d.ts.map +1 -1
  44. package/dist/library/ThemeScope.js +10 -9
  45. package/dist/library/ThemeScope.js.map +1 -1
  46. package/dist/library/examples/expressive.d.ts +4 -0
  47. package/dist/library/examples/expressive.d.ts.map +1 -0
  48. package/dist/library/{themes → examples}/expressive.js +4 -3
  49. package/dist/library/examples/expressive.js.map +1 -0
  50. package/dist/library/examples/glass.d.ts +4 -0
  51. package/dist/library/examples/glass.d.ts.map +1 -0
  52. package/dist/library/{themes → examples}/glass.js +4 -3
  53. package/dist/library/examples/glass.js.map +1 -0
  54. package/dist/library/examples/index.d.ts +13 -0
  55. package/dist/library/examples/index.d.ts.map +1 -0
  56. package/dist/library/examples/index.js +32 -0
  57. package/dist/library/examples/index.js.map +1 -0
  58. package/dist/library/examples/jelly.d.ts +4 -0
  59. package/dist/library/examples/jelly.d.ts.map +1 -0
  60. package/dist/library/{themes → examples}/jelly.js +4 -3
  61. package/dist/library/examples/jelly.js.map +1 -0
  62. package/dist/library/examples/preset-values.d.ts.map +1 -0
  63. package/dist/library/examples/preset-values.js.map +1 -0
  64. package/dist/library/examples/radiant.d.ts +4 -0
  65. package/dist/library/examples/radiant.d.ts.map +1 -0
  66. package/dist/library/{themes → examples}/radiant.js +4 -3
  67. package/dist/library/examples/radiant.js.map +1 -0
  68. package/dist/library/examples/sharp-3d.d.ts +4 -0
  69. package/dist/library/examples/sharp-3d.d.ts.map +1 -0
  70. package/dist/library/{themes → examples}/sharp-3d.js +4 -3
  71. package/dist/library/examples/sharp-3d.js.map +1 -0
  72. package/dist/library/examples/soft-squircle.d.ts +4 -0
  73. package/dist/library/examples/soft-squircle.d.ts.map +1 -0
  74. package/dist/library/{themes → examples}/soft-squircle.js +4 -3
  75. package/dist/library/examples/soft-squircle.js.map +1 -0
  76. package/dist/library/examples/ticket.d.ts +4 -0
  77. package/dist/library/examples/ticket.d.ts.map +1 -0
  78. package/dist/library/{themes → examples}/ticket.js +4 -3
  79. package/dist/library/examples/ticket.js.map +1 -0
  80. package/dist/library/index.d.ts +4 -2
  81. package/dist/library/index.d.ts.map +1 -1
  82. package/dist/library/index.js +2 -1
  83. package/dist/library/index.js.map +1 -1
  84. package/dist/library/motion/MotionLink.d.ts +8 -0
  85. package/dist/library/motion/MotionLink.d.ts.map +1 -0
  86. package/dist/library/motion/MotionLink.js +44 -0
  87. package/dist/library/motion/MotionLink.js.map +1 -0
  88. package/dist/library/motion/browser.d.ts +5 -0
  89. package/dist/library/motion/browser.d.ts.map +1 -0
  90. package/dist/library/motion/browser.js +35 -0
  91. package/dist/library/motion/browser.js.map +1 -0
  92. package/dist/library/motion/config.d.ts +26 -0
  93. package/dist/library/motion/config.d.ts.map +1 -0
  94. package/dist/library/motion/config.js +58 -0
  95. package/dist/library/motion/config.js.map +1 -0
  96. package/dist/library/motion/context.d.ts +2 -0
  97. package/dist/library/motion/context.d.ts.map +1 -0
  98. package/dist/library/motion/context.js +5 -0
  99. package/dist/library/motion/context.js.map +1 -0
  100. package/dist/library/motion/drag.d.ts +20 -0
  101. package/dist/library/motion/drag.d.ts.map +1 -0
  102. package/dist/library/motion/drag.js +138 -0
  103. package/dist/library/motion/drag.js.map +1 -0
  104. package/dist/library/motion/dragBrowser.d.ts +4 -0
  105. package/dist/library/motion/dragBrowser.d.ts.map +1 -0
  106. package/dist/library/motion/dragBrowser.js +156 -0
  107. package/dist/library/motion/dragBrowser.js.map +1 -0
  108. package/dist/library/motion/follow.d.ts +9 -0
  109. package/dist/library/motion/follow.d.ts.map +1 -0
  110. package/dist/library/motion/follow.js +26 -0
  111. package/dist/library/motion/follow.js.map +1 -0
  112. package/dist/library/motion/host.d.ts +30 -0
  113. package/dist/library/motion/host.d.ts.map +1 -0
  114. package/dist/library/motion/host.js +70 -0
  115. package/dist/library/motion/host.js.map +1 -0
  116. package/dist/library/motion/index.d.ts +16 -0
  117. package/dist/library/motion/index.d.ts.map +1 -0
  118. package/dist/library/motion/index.js +9 -0
  119. package/dist/library/motion/index.js.map +1 -0
  120. package/dist/library/motion/layout.d.ts +20 -0
  121. package/dist/library/motion/layout.d.ts.map +1 -0
  122. package/dist/library/motion/layout.js +67 -0
  123. package/dist/library/motion/layout.js.map +1 -0
  124. package/dist/library/motion/layoutDom.d.ts +17 -0
  125. package/dist/library/motion/layoutDom.d.ts.map +1 -0
  126. package/dist/library/motion/layoutDom.js +272 -0
  127. package/dist/library/motion/layoutDom.js.map +1 -0
  128. package/dist/library/motion/press.d.ts +5 -0
  129. package/dist/library/motion/press.d.ts.map +1 -0
  130. package/dist/library/motion/press.js +99 -0
  131. package/dist/library/motion/press.js.map +1 -0
  132. package/dist/library/motion/pressPolicy.d.ts +5 -0
  133. package/dist/library/motion/pressPolicy.d.ts.map +1 -0
  134. package/dist/library/motion/pressPolicy.js +8 -0
  135. package/dist/library/motion/pressPolicy.js.map +1 -0
  136. package/dist/library/motion/react.d.ts +35 -0
  137. package/dist/library/motion/react.d.ts.map +1 -0
  138. package/dist/library/motion/react.js +224 -0
  139. package/dist/library/motion/react.js.map +1 -0
  140. package/dist/library/motion/runtime.d.ts +22 -0
  141. package/dist/library/motion/runtime.d.ts.map +1 -0
  142. package/dist/library/motion/runtime.js +117 -0
  143. package/dist/library/motion/runtime.js.map +1 -0
  144. package/dist/library/motion/transitions.d.ts +5 -0
  145. package/dist/library/motion/transitions.d.ts.map +1 -0
  146. package/dist/library/motion/transitions.js +244 -0
  147. package/dist/library/motion/transitions.js.map +1 -0
  148. package/dist/library/styles.css +1 -1
  149. package/dist/library/themes/defineTheme.d.ts +3 -0
  150. package/dist/library/themes/defineTheme.d.ts.map +1 -1
  151. package/dist/library/themes/defineTheme.js +4 -2
  152. package/dist/library/themes/defineTheme.js.map +1 -1
  153. package/dist/library/themes/index.d.ts +2 -12
  154. package/dist/library/themes/index.d.ts.map +1 -1
  155. package/dist/library/themes/index.js +1 -19
  156. package/dist/library/themes/index.js.map +1 -1
  157. package/dist/library/themes/themeDocument.d.ts.map +1 -1
  158. package/dist/library/themes/themeDocument.js +11 -5
  159. package/dist/library/themes/themeDocument.js.map +1 -1
  160. package/dist/library/themes/themeDocumentTypes.d.ts +5 -1
  161. package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -1
  162. package/dist/library/themes/themeDocumentTypes.js.map +1 -1
  163. package/docs/accessibility.md +76 -142
  164. package/docs/architecture.md +197 -0
  165. package/docs/motion.md +153 -0
  166. package/docs/theming.md +275 -882
  167. package/package.json +22 -7
  168. package/src/Accordion.tsx +4 -1
  169. package/src/Button.tsx +55 -1
  170. package/src/Card.tsx +3 -1
  171. package/src/Checkbox.tsx +7 -2
  172. package/src/Collapsible.tsx +38 -2
  173. package/src/Dialog.tsx +13 -1
  174. package/src/Field.tsx +8 -0
  175. package/src/Input.tsx +3 -0
  176. package/src/Link.tsx +5 -0
  177. package/src/RadioGroup.tsx +10 -2
  178. package/src/ThemeScope.tsx +21 -17
  179. package/src/{themes → examples}/expressive.ts +5 -3
  180. package/src/{themes → examples}/glass.ts +5 -3
  181. package/src/examples/index.ts +35 -0
  182. package/src/{themes → examples}/jelly.ts +5 -3
  183. package/src/{themes → examples}/radiant.ts +5 -3
  184. package/src/{themes → examples}/sharp-3d.ts +5 -3
  185. package/src/{themes → examples}/soft-squircle.ts +5 -3
  186. package/src/{themes → examples}/ticket.ts +5 -3
  187. package/src/index.ts +10 -13
  188. package/src/motion/MotionLink.tsx +69 -0
  189. package/src/motion/browser.ts +45 -0
  190. package/src/motion/config.ts +79 -0
  191. package/src/motion/context.ts +4 -0
  192. package/src/motion/drag.ts +151 -0
  193. package/src/motion/dragBrowser.ts +159 -0
  194. package/src/motion/follow.ts +28 -0
  195. package/src/motion/host.ts +96 -0
  196. package/src/motion/index.ts +28 -0
  197. package/src/motion/layout.ts +78 -0
  198. package/src/motion/layoutDom.ts +293 -0
  199. package/src/motion/press.ts +97 -0
  200. package/src/motion/pressPolicy.ts +14 -0
  201. package/src/motion/react.ts +272 -0
  202. package/src/motion/runtime.ts +122 -0
  203. package/src/motion/transitions.ts +237 -0
  204. package/src/themes/defineTheme.ts +10 -2
  205. package/src/themes/index.ts +2 -22
  206. package/src/themes/themeDocument.ts +14 -6
  207. package/src/themes/themeDocumentTypes.ts +12 -5
  208. package/dist/library/themes/expressive.d.ts +0 -2
  209. package/dist/library/themes/expressive.d.ts.map +0 -1
  210. package/dist/library/themes/expressive.js.map +0 -1
  211. package/dist/library/themes/glass.d.ts +0 -2
  212. package/dist/library/themes/glass.d.ts.map +0 -1
  213. package/dist/library/themes/glass.js.map +0 -1
  214. package/dist/library/themes/jelly.d.ts +0 -2
  215. package/dist/library/themes/jelly.d.ts.map +0 -1
  216. package/dist/library/themes/jelly.js.map +0 -1
  217. package/dist/library/themes/preset-values.d.ts.map +0 -1
  218. package/dist/library/themes/preset-values.js.map +0 -1
  219. package/dist/library/themes/radiant.d.ts +0 -2
  220. package/dist/library/themes/radiant.d.ts.map +0 -1
  221. package/dist/library/themes/radiant.js.map +0 -1
  222. package/dist/library/themes/sharp-3d.d.ts +0 -2
  223. package/dist/library/themes/sharp-3d.d.ts.map +0 -1
  224. package/dist/library/themes/sharp-3d.js.map +0 -1
  225. package/dist/library/themes/soft-squircle.d.ts +0 -2
  226. package/dist/library/themes/soft-squircle.d.ts.map +0 -1
  227. package/dist/library/themes/soft-squircle.js.map +0 -1
  228. package/dist/library/themes/ticket.d.ts +0 -2
  229. package/dist/library/themes/ticket.d.ts.map +0 -1
  230. package/dist/library/themes/ticket.js.map +0 -1
  231. package/docs/system.md +0 -238
  232. /package/dist/library/{themes → examples}/preset-values.d.ts +0 -0
  233. /package/dist/library/{themes → examples}/preset-values.js +0 -0
  234. /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.