@cognitap/radiant 0.0.77 → 0.0.79

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 (307) hide show
  1. package/CHANGELOG.md +36 -2
  2. package/README.md +6 -3
  3. package/RELEASE_POLICY.md +8 -19
  4. package/dist/library/charts/Charts.d.ts.map +1 -1
  5. package/dist/library/charts/Charts.js +6 -2
  6. package/dist/library/charts/Charts.js.map +1 -1
  7. package/dist/library/components/Accordion/Accordion.js +1 -1
  8. package/dist/library/components/Accordion/Accordion.js.map +1 -1
  9. package/dist/library/components/Alert/Alert.js +1 -1
  10. package/dist/library/components/Alert/Alert.js.map +1 -1
  11. package/dist/library/components/AppShell/AppShell.d.ts.map +1 -1
  12. package/dist/library/components/AppShell/AppShell.js +7 -6
  13. package/dist/library/components/AppShell/AppShell.js.map +1 -1
  14. package/dist/library/components/AspectRatio/AspectRatio.js +1 -1
  15. package/dist/library/components/AspectRatio/AspectRatio.js.map +1 -1
  16. package/dist/library/components/Avatar/Avatar.js +1 -1
  17. package/dist/library/components/Avatar/Avatar.js.map +1 -1
  18. package/dist/library/components/Badge/Badge.js +1 -1
  19. package/dist/library/components/Badge/Badge.js.map +1 -1
  20. package/dist/library/components/Breadcrumb/Breadcrumb.d.ts +2 -1
  21. package/dist/library/components/Breadcrumb/Breadcrumb.d.ts.map +1 -1
  22. package/dist/library/components/Breadcrumb/Breadcrumb.js +5 -10
  23. package/dist/library/components/Breadcrumb/Breadcrumb.js.map +1 -1
  24. package/dist/library/components/Button/Button.js +1 -1
  25. package/dist/library/components/Button/Button.js.map +1 -1
  26. package/dist/library/components/ButtonGroup/ButtonGroup.js +1 -1
  27. package/dist/library/components/ButtonGroup/ButtonGroup.js.map +1 -1
  28. package/dist/library/components/Card/Card.js +1 -1
  29. package/dist/library/components/Card/Card.js.map +1 -1
  30. package/dist/library/components/Carousel/Carousel.d.ts.map +1 -1
  31. package/dist/library/components/Carousel/Carousel.js +11 -9
  32. package/dist/library/components/Carousel/Carousel.js.map +1 -1
  33. package/dist/library/components/Checkbox/Checkbox.d.ts +3 -1
  34. package/dist/library/components/Checkbox/Checkbox.d.ts.map +1 -1
  35. package/dist/library/components/Checkbox/Checkbox.js +8 -8
  36. package/dist/library/components/Checkbox/Checkbox.js.map +1 -1
  37. package/dist/library/components/CheckboxGroup/CheckboxGroup.js +1 -1
  38. package/dist/library/components/CheckboxGroup/CheckboxGroup.js.map +1 -1
  39. package/dist/library/components/CodeBlock/CodeBlock.js +3 -3
  40. package/dist/library/components/CodeBlock/CodeBlock.js.map +1 -1
  41. package/dist/library/components/Collapsible/Collapsible.d.ts.map +1 -1
  42. package/dist/library/components/Collapsible/Collapsible.js +4 -6
  43. package/dist/library/components/Collapsible/Collapsible.js.map +1 -1
  44. package/dist/library/components/Combobox/Combobox.d.ts +9 -1
  45. package/dist/library/components/Combobox/Combobox.d.ts.map +1 -1
  46. package/dist/library/components/Combobox/Combobox.js +14 -13
  47. package/dist/library/components/Combobox/Combobox.js.map +1 -1
  48. package/dist/library/components/Combobox/comboboxStyles.d.ts.map +1 -1
  49. package/dist/library/components/Combobox/comboboxStyles.js +5 -2
  50. package/dist/library/components/Combobox/comboboxStyles.js.map +1 -1
  51. package/dist/library/components/Command/Command.d.ts +1 -4
  52. package/dist/library/components/Command/Command.d.ts.map +1 -1
  53. package/dist/library/components/Command/Command.js +3 -9
  54. package/dist/library/components/Command/Command.js.map +1 -1
  55. package/dist/library/components/ContextMenu/ContextMenu.d.ts.map +1 -1
  56. package/dist/library/components/ContextMenu/ContextMenu.js +3 -2
  57. package/dist/library/components/ContextMenu/ContextMenu.js.map +1 -1
  58. package/dist/library/components/Dialog/Dialog.d.ts +3 -0
  59. package/dist/library/components/Dialog/Dialog.d.ts.map +1 -1
  60. package/dist/library/components/Dialog/Dialog.js +9 -10
  61. package/dist/library/components/Dialog/Dialog.js.map +1 -1
  62. package/dist/library/components/Drawer/Drawer.js +1 -1
  63. package/dist/library/components/Drawer/Drawer.js.map +1 -1
  64. package/dist/library/components/EmptyState/EmptyState.js +1 -1
  65. package/dist/library/components/EmptyState/EmptyState.js.map +1 -1
  66. package/dist/library/components/Field/Field.js +1 -1
  67. package/dist/library/components/Field/Field.js.map +1 -1
  68. package/dist/library/components/Fieldset/Fieldset.d.ts +1 -1
  69. package/dist/library/components/Fieldset/Fieldset.d.ts.map +1 -1
  70. package/dist/library/components/Fieldset/Fieldset.js +3 -3
  71. package/dist/library/components/Fieldset/Fieldset.js.map +1 -1
  72. package/dist/library/components/FileInput/FileInput.d.ts +3 -1
  73. package/dist/library/components/FileInput/FileInput.d.ts.map +1 -1
  74. package/dist/library/components/FileInput/FileInput.js +6 -4
  75. package/dist/library/components/FileInput/FileInput.js.map +1 -1
  76. package/dist/library/components/Form/Form.d.ts.map +1 -1
  77. package/dist/library/components/Form/Form.js +16 -11
  78. package/dist/library/components/Form/Form.js.map +1 -1
  79. package/dist/library/components/HoverCard/HoverCard.d.ts +1 -0
  80. package/dist/library/components/HoverCard/HoverCard.d.ts.map +1 -1
  81. package/dist/library/components/HoverCard/HoverCard.js +2 -1
  82. package/dist/library/components/HoverCard/HoverCard.js.map +1 -1
  83. package/dist/library/components/InlineCode/InlineCode.js +1 -1
  84. package/dist/library/components/InlineCode/InlineCode.js.map +1 -1
  85. package/dist/library/components/Input/Input.d.ts +3 -1
  86. package/dist/library/components/Input/Input.d.ts.map +1 -1
  87. package/dist/library/components/Input/Input.js +7 -12
  88. package/dist/library/components/Input/Input.js.map +1 -1
  89. package/dist/library/components/InputGroup/InputGroup.d.ts.map +1 -1
  90. package/dist/library/components/InputGroup/InputGroup.js +3 -2
  91. package/dist/library/components/InputGroup/InputGroup.js.map +1 -1
  92. package/dist/library/components/Kbd/Kbd.js +1 -1
  93. package/dist/library/components/Kbd/Kbd.js.map +1 -1
  94. package/dist/library/components/Link/Link.d.ts +4 -2
  95. package/dist/library/components/Link/Link.d.ts.map +1 -1
  96. package/dist/library/components/Link/Link.js +7 -4
  97. package/dist/library/components/Link/Link.js.map +1 -1
  98. package/dist/library/components/Menu/Menu.d.ts +13 -3
  99. package/dist/library/components/Menu/Menu.d.ts.map +1 -1
  100. package/dist/library/components/Menu/Menu.js +24 -9
  101. package/dist/library/components/Menu/Menu.js.map +1 -1
  102. package/dist/library/components/Menubar/Menubar.d.ts.map +1 -1
  103. package/dist/library/components/Menubar/Menubar.js +2 -2
  104. package/dist/library/components/Menubar/Menubar.js.map +1 -1
  105. package/dist/library/components/Meter/Meter.js +1 -1
  106. package/dist/library/components/Meter/Meter.js.map +1 -1
  107. package/dist/library/components/NativeSelect/NativeSelect.d.ts.map +1 -1
  108. package/dist/library/components/NativeSelect/NativeSelect.js +3 -2
  109. package/dist/library/components/NativeSelect/NativeSelect.js.map +1 -1
  110. package/dist/library/components/NavLink/NavLink.d.ts.map +1 -1
  111. package/dist/library/components/NavLink/NavLink.js +6 -4
  112. package/dist/library/components/NavLink/NavLink.js.map +1 -1
  113. package/dist/library/components/NavigationMenu/NavigationMenu.d.ts +1 -1
  114. package/dist/library/components/NavigationMenu/NavigationMenu.d.ts.map +1 -1
  115. package/dist/library/components/NavigationMenu/NavigationMenu.js +11 -4
  116. package/dist/library/components/NavigationMenu/NavigationMenu.js.map +1 -1
  117. package/dist/library/components/NumberField/NumberField.d.ts.map +1 -1
  118. package/dist/library/components/NumberField/NumberField.js +2 -2
  119. package/dist/library/components/NumberField/NumberField.js.map +1 -1
  120. package/dist/library/components/OTPField/OTPField.d.ts.map +1 -1
  121. package/dist/library/components/OTPField/OTPField.js +3 -2
  122. package/dist/library/components/OTPField/OTPField.js.map +1 -1
  123. package/dist/library/components/Pagination/Pagination.d.ts +2 -1
  124. package/dist/library/components/Pagination/Pagination.d.ts.map +1 -1
  125. package/dist/library/components/Pagination/Pagination.js +5 -7
  126. package/dist/library/components/Pagination/Pagination.js.map +1 -1
  127. package/dist/library/components/PasswordInput/PasswordInput.js +1 -1
  128. package/dist/library/components/PasswordInput/PasswordInput.js.map +1 -1
  129. package/dist/library/components/Popover/Popover.d.ts.map +1 -1
  130. package/dist/library/components/Popover/Popover.js +5 -3
  131. package/dist/library/components/Popover/Popover.js.map +1 -1
  132. package/dist/library/components/Progress/Progress.js +1 -1
  133. package/dist/library/components/Progress/Progress.js.map +1 -1
  134. package/dist/library/components/RadioGroup/RadioGroup.d.ts +4 -2
  135. package/dist/library/components/RadioGroup/RadioGroup.d.ts.map +1 -1
  136. package/dist/library/components/RadioGroup/RadioGroup.js +10 -11
  137. package/dist/library/components/RadioGroup/RadioGroup.js.map +1 -1
  138. package/dist/library/components/Resizable/Resizable.d.ts.map +1 -1
  139. package/dist/library/components/Resizable/Resizable.js +3 -2
  140. package/dist/library/components/Resizable/Resizable.js.map +1 -1
  141. package/dist/library/components/ScrollArea/ScrollArea.d.ts.map +1 -1
  142. package/dist/library/components/ScrollArea/ScrollArea.js +3 -2
  143. package/dist/library/components/ScrollArea/ScrollArea.js.map +1 -1
  144. package/dist/library/components/Select/Select.d.ts +7 -0
  145. package/dist/library/components/Select/Select.d.ts.map +1 -1
  146. package/dist/library/components/Select/Select.js +12 -11
  147. package/dist/library/components/Select/Select.js.map +1 -1
  148. package/dist/library/components/Select/selectStyles.d.ts.map +1 -1
  149. package/dist/library/components/Select/selectStyles.js +3 -1
  150. package/dist/library/components/Select/selectStyles.js.map +1 -1
  151. package/dist/library/components/Separator/Separator.js +1 -1
  152. package/dist/library/components/Separator/Separator.js.map +1 -1
  153. package/dist/library/components/Skeleton/Skeleton.js +1 -1
  154. package/dist/library/components/Skeleton/Skeleton.js.map +1 -1
  155. package/dist/library/components/Slider/Slider.d.ts +3 -1
  156. package/dist/library/components/Slider/Slider.d.ts.map +1 -1
  157. package/dist/library/components/Slider/Slider.js +7 -9
  158. package/dist/library/components/Slider/Slider.js.map +1 -1
  159. package/dist/library/components/Spinner/Spinner.js +1 -1
  160. package/dist/library/components/Spinner/Spinner.js.map +1 -1
  161. package/dist/library/components/Switch/Switch.d.ts +3 -1
  162. package/dist/library/components/Switch/Switch.d.ts.map +1 -1
  163. package/dist/library/components/Switch/Switch.js +7 -8
  164. package/dist/library/components/Switch/Switch.js.map +1 -1
  165. package/dist/library/components/Table/Table.d.ts.map +1 -1
  166. package/dist/library/components/Table/Table.js +3 -2
  167. package/dist/library/components/Table/Table.js.map +1 -1
  168. package/dist/library/components/Tabs/Tabs.d.ts.map +1 -1
  169. package/dist/library/components/Tabs/Tabs.js +9 -7
  170. package/dist/library/components/Tabs/Tabs.js.map +1 -1
  171. package/dist/library/components/Tag/Tag.js +1 -1
  172. package/dist/library/components/Tag/Tag.js.map +1 -1
  173. package/dist/library/components/TagsInput/TagsInput.d.ts +3 -1
  174. package/dist/library/components/TagsInput/TagsInput.d.ts.map +1 -1
  175. package/dist/library/components/TagsInput/TagsInput.js +9 -6
  176. package/dist/library/components/TagsInput/TagsInput.js.map +1 -1
  177. package/dist/library/components/Textarea/Textarea.d.ts +3 -1
  178. package/dist/library/components/Textarea/Textarea.d.ts.map +1 -1
  179. package/dist/library/components/Textarea/Textarea.js +7 -8
  180. package/dist/library/components/Textarea/Textarea.js.map +1 -1
  181. package/dist/library/components/ThemeScope/ThemeScope.js +1 -1
  182. package/dist/library/components/ThemeScope/ThemeScope.js.map +1 -1
  183. package/dist/library/components/Toast/Toast.d.ts +2 -1
  184. package/dist/library/components/Toast/Toast.d.ts.map +1 -1
  185. package/dist/library/components/Toast/Toast.js +22 -9
  186. package/dist/library/components/Toast/Toast.js.map +1 -1
  187. package/dist/library/components/ToggleGroup/ToggleGroup.js +3 -1
  188. package/dist/library/components/ToggleGroup/ToggleGroup.js.map +1 -1
  189. package/dist/library/components/Toolbar/Toolbar.js +1 -1
  190. package/dist/library/components/Toolbar/Toolbar.js.map +1 -1
  191. package/dist/library/components/Tooltip/Tooltip.d.ts +1 -0
  192. package/dist/library/components/Tooltip/Tooltip.d.ts.map +1 -1
  193. package/dist/library/components/Tooltip/Tooltip.js +2 -2
  194. package/dist/library/components/Tooltip/Tooltip.js.map +1 -1
  195. package/dist/library/components/shared/actionStyles.d.ts.map +1 -1
  196. package/dist/library/components/shared/actionStyles.js +3 -1
  197. package/dist/library/components/shared/actionStyles.js.map +1 -1
  198. package/dist/library/components/shared/focusStyles.d.ts +13 -0
  199. package/dist/library/components/shared/focusStyles.d.ts.map +1 -0
  200. package/dist/library/components/shared/focusStyles.js +17 -0
  201. package/dist/library/components/shared/focusStyles.js.map +1 -0
  202. package/dist/library/index.d.ts +1 -1
  203. package/dist/library/index.d.ts.map +1 -1
  204. package/dist/library/index.js.map +1 -1
  205. package/dist/library/motion/MotionLink.js +1 -1
  206. package/dist/library/motion/MotionLink.js.map +1 -1
  207. package/dist/library/react/useComboboxPopup.d.ts.map +1 -1
  208. package/dist/library/react/useComboboxPopup.js +45 -6
  209. package/dist/library/react/useComboboxPopup.js.map +1 -1
  210. package/dist/library/react/useRovingFocus.d.ts.map +1 -1
  211. package/dist/library/react/useRovingFocus.js +76 -11
  212. package/dist/library/react/useRovingFocus.js.map +1 -1
  213. package/dist/library/react/useToastTimer.d.ts.map +1 -1
  214. package/dist/library/react/useToastTimer.js +29 -10
  215. package/dist/library/react/useToastTimer.js.map +1 -1
  216. package/dist/library/styles.css +1 -1
  217. package/dist/library/themes/components.d.ts +12 -0
  218. package/dist/library/themes/components.d.ts.map +1 -1
  219. package/dist/library/themes/components.js +15 -3
  220. package/dist/library/themes/components.js.map +1 -1
  221. package/docs/accessibility.md +23 -111
  222. package/docs/architecture.md +48 -228
  223. package/docs/motion.md +65 -130
  224. package/docs/theming.md +51 -422
  225. package/package.json +21 -13
  226. package/src/charts/Charts.tsx +6 -3
  227. package/src/components/Accordion/Accordion.tsx +1 -1
  228. package/src/components/Alert/Alert.tsx +1 -1
  229. package/src/components/AppShell/AppShell.tsx +10 -6
  230. package/src/components/AspectRatio/AspectRatio.tsx +1 -1
  231. package/src/components/Avatar/Avatar.tsx +1 -1
  232. package/src/components/Badge/Badge.tsx +1 -1
  233. package/src/components/Breadcrumb/Breadcrumb.tsx +6 -10
  234. package/src/components/Button/Button.tsx +1 -1
  235. package/src/components/ButtonGroup/ButtonGroup.tsx +1 -1
  236. package/src/components/Card/Card.tsx +1 -1
  237. package/src/components/Carousel/Carousel.tsx +14 -9
  238. package/src/components/Checkbox/Checkbox.tsx +10 -7
  239. package/src/components/CheckboxGroup/CheckboxGroup.tsx +1 -1
  240. package/src/components/CodeBlock/CodeBlock.tsx +3 -3
  241. package/src/components/Collapsible/Collapsible.tsx +4 -6
  242. package/src/components/Combobox/Combobox.tsx +72 -16
  243. package/src/components/Combobox/comboboxStyles.ts +5 -2
  244. package/src/components/Command/Command.tsx +3 -10
  245. package/src/components/ContextMenu/ContextMenu.tsx +3 -5
  246. package/src/components/Dialog/Dialog.tsx +30 -14
  247. package/src/components/Drawer/Drawer.tsx +1 -1
  248. package/src/components/EmptyState/EmptyState.tsx +1 -1
  249. package/src/components/Field/Field.tsx +1 -1
  250. package/src/components/Fieldset/Fieldset.tsx +4 -4
  251. package/src/components/FileInput/FileInput.tsx +9 -3
  252. package/src/components/Form/Form.tsx +14 -10
  253. package/src/components/HoverCard/HoverCard.tsx +6 -2
  254. package/src/components/InlineCode/InlineCode.tsx +1 -1
  255. package/src/components/Input/Input.tsx +14 -13
  256. package/src/components/InputGroup/InputGroup.tsx +5 -3
  257. package/src/components/Kbd/Kbd.tsx +1 -1
  258. package/src/components/Link/Link.tsx +10 -4
  259. package/src/components/Menu/Menu.tsx +52 -10
  260. package/src/components/Menubar/Menubar.tsx +2 -1
  261. package/src/components/Meter/Meter.tsx +1 -1
  262. package/src/components/NativeSelect/NativeSelect.tsx +4 -2
  263. package/src/components/NavLink/NavLink.tsx +9 -6
  264. package/src/components/NavigationMenu/NavigationMenu.tsx +15 -12
  265. package/src/components/NumberField/NumberField.tsx +2 -1
  266. package/src/components/OTPField/OTPField.tsx +5 -2
  267. package/src/components/Pagination/Pagination.tsx +6 -8
  268. package/src/components/PasswordInput/PasswordInput.tsx +1 -1
  269. package/src/components/Popover/Popover.tsx +5 -2
  270. package/src/components/Progress/Progress.tsx +1 -1
  271. package/src/components/RadioGroup/RadioGroup.tsx +14 -8
  272. package/src/components/Resizable/Resizable.tsx +5 -3
  273. package/src/components/ScrollArea/ScrollArea.tsx +3 -2
  274. package/src/components/Select/Select.tsx +28 -14
  275. package/src/components/Select/selectStyles.ts +3 -1
  276. package/src/components/Separator/Separator.tsx +1 -1
  277. package/src/components/Skeleton/Skeleton.tsx +1 -1
  278. package/src/components/Slider/Slider.tsx +9 -8
  279. package/src/components/Spinner/Spinner.tsx +1 -1
  280. package/src/components/Switch/Switch.tsx +9 -7
  281. package/src/components/Table/Table.tsx +4 -2
  282. package/src/components/Tabs/Tabs.tsx +9 -8
  283. package/src/components/Tag/Tag.tsx +1 -1
  284. package/src/components/TagsInput/TagsInput.tsx +11 -4
  285. package/src/components/Textarea/Textarea.tsx +9 -7
  286. package/src/components/ThemeScope/ThemeScope.tsx +1 -1
  287. package/src/components/Toast/Toast.tsx +27 -12
  288. package/src/components/ToggleGroup/ToggleGroup.tsx +3 -1
  289. package/src/components/Toolbar/Toolbar.tsx +1 -1
  290. package/src/components/Tooltip/Tooltip.tsx +3 -2
  291. package/src/components/shared/actionStyles.ts +3 -1
  292. package/src/components/shared/focusStyles.ts +28 -0
  293. package/src/css.d.ts +2 -0
  294. package/src/index.ts +1 -0
  295. package/src/motion/MotionLink.tsx +1 -1
  296. package/src/react/useComboboxPopup.ts +38 -6
  297. package/src/react/useRovingFocus.ts +73 -8
  298. package/src/react/useToastTimer.ts +25 -10
  299. package/src/styles.d.ts +1 -0
  300. package/src/themes/baseline.css +1 -1
  301. package/src/themes/components.ts +15 -3
  302. package/src/typography.css +17 -12
  303. package/dist/library/cn.d.ts +0 -3
  304. package/dist/library/cn.d.ts.map +0 -1
  305. package/dist/library/cn.js +0 -370
  306. package/dist/library/cn.js.map +0 -1
  307. package/src/cn.ts +0 -372
@@ -1,260 +1,80 @@
1
1
  # Architecture
2
2
 
3
- Radiant's sixty-four families. See [props](https://github.com/cognitap/radiant-docs), [themes](theming.md) and [motion](motion.md).
3
+ Radiant wraps native HTML in React components. The browser provides behavior: button activation, radio grouping, modal focus. Radiant adds composition, state, and styling. Applications provide content and logic.
4
4
 
5
- The families are Charts, Carousel, Form, AppShell (with Sidebar), NavigationMenu, Resizable, NumberField, CodeBlock (with InlineCode), EmptyState, Command, Autocomplete, NavLink, PasswordInput, FileInput, Meter, NativeSelect, InputGroup, Kbd, Button, ButtonGroup, ToggleGroup, Toolbar, Link, Field, Fieldset, Input, OTPField, Textarea, Select, Combobox, MultiSelect, TagsInput, Checkbox, CheckboxGroup, AspectRatio, ScrollArea, Switch, Slider, RadioGroup (with Radio),
6
- Dialog, AlertDialog, Drawer, Popover, HoverCard, Tooltip, Menu, ContextMenu, Menubar, Alert, Toast, Progress, Spinner, Skeleton, Separator, Badge, Tag, Avatar, Breadcrumb, Pagination, Table, Collapsible, Accordion, Tabs and Card. All ship in
7
- `@cognitap/radiant`. Charts uses the explicit `@cognitap/radiant/charts` entry; arbitrary deep imports are unsupported.
5
+ Component APIs live in the [component guides](https://github.com/cognitap/radiant-docs). Cross-family topics live in [theming](theming.md), [motion](motion.md), and [accessibility](accessibility.md).
8
6
 
9
- ## Native first
7
+ ## Package entries
10
8
 
11
- Behavior owners:
9
+ - `@cognitap/radiant`: components
10
+ - `@cognitap/radiant/charts`: charts
11
+ - `@cognitap/radiant/examples`: theme presets
12
12
 
13
- | Responsibility | Owner |
14
- | ------------------------------------------------------ | ----------------------------------------------- |
15
- | Activation, radio grouping, disclosure, modal dialog | The native element |
16
- | Selection rules, ID merging and other reusable policy | Private modules in `src/internal/`, no React |
17
- | Rendering, context, state hooks, event and ref wiring | React bindings in `src/react/` and family roots |
18
- | Appearance | Shared tokens and component overrides |
19
- | Content, validation, routing, fetching and persistence | The consumer |
13
+ [package.json](../package.json) lists every import path, including CSS and motion.
20
14
 
21
- Browsers own keyboard, focus and form semantics.
22
- Radiant has no headless-library dependency. Select owns its themed listbox and
23
- item focus, while a visually hidden native select supplies form semantics.
24
- Select, Combobox and Popover use the local top layer, preserving theme and modal ancestry.
25
- Combobox keeps DOM focus on its native input and submits the committed key through
26
- native form controls. Search text never becomes a selection. Autocomplete reuses the listbox but submits its native text, including off-list values. Applications own async
27
- requests, cancellation and selected labels; results never trigger selection.
28
- Command combines Dialog with an inline Combobox listbox for explicit actions; applications register shortcuts.
29
- MultiSelect composes Combobox with `type="multiple"`. TagsInput commits free text; both
30
- submit repeated named values. Their nameless JSON carrier emits accepted array changes.
31
- NumberField edits localized text and submits one raw numeric form value.
32
- Resizable composes Separator for adjacent panel sizing; applications persist layouts.
33
- Charts use SVG through an optional entry; pure geometry stays separate from React, reusing Tooltip, Button, Table and palette modes.
34
- AppShell places native landmarks around one Sidebar subtree, reusing Drawer for mobile navigation and optional spring layout.
35
- NavigationMenu composes Button and Link with one shared spring viewport, preserving navigation semantics.
36
- Tag composes Badge and Button for removal.
37
- OTPField keeps one native Input for editing, autofill and forms; its character slots are decorative.
38
- InputGroup shares a boundary around real Input or Textarea controls and their addons.
15
+ ## Module rules
39
16
 
40
- Import rules:
17
+ - `src/internal/` is framework-free logic: selection rules, event guards. `src/react/` wraps it in hooks and imports only React and `src/internal/`. Families may depend on each other without cycles.
18
+ - Do not read browser globals during module initialization or server rendering. In effects, use the host's `ownerDocument` and `defaultView` so iframes work, and clean up on unmount.
19
+ - Server markup must equal the first client render. `Dialog` opens in an effect. `Collapsible` syncs `<details open>` on mount.
20
+ - Add `"use client"` to modules that use state, context, refs, or effects. Other modules stay static and may render client families, as `Pagination` renders `Button`. `Card`, `Link`, themes, and examples import nothing marked `"use client"`; they share styles through modules such as `src/components/shared/actionStyles.ts`.
41
21
 
42
- 1. `internal` never imports React, a binding, a family or app code.
43
- 2. `react` imports `internal` and React, never a family.
44
- 3. Families compose other families explicitly (Accordion uses Collapsible,
45
- RadioGroup uses Field, Dialog actions use Button). The graph stays acyclic.
46
- 4. Nothing touches `window`, `document` or the DOM at import time. Effects use
47
- the owning document and clean up on unmount.
48
- 5. Server markup matches the first client render; dialogs open in effects.
49
-
50
- Extract shared policy only when it repeats.
22
+ [tests/architecture.test.mjs](../tests/architecture.test.mjs) enforces the import, cycle, `"use client"`, and browser-global rules. [tests/browser](../tests/browser) hydrates server markup.
51
23
 
52
24
  ## Composition
53
25
 
54
- Use Button for actions and Link for navigation, even when a Link looks like a
55
- button. Field owns label, help and error relationships. Card groups content.
56
- Dialog owns open state. Toast composes Alert and Button with a local FIFO queue and pausable timing. Collapsible owns one disclosure, and Accordion composes
57
- Collapsible for a set of them.
58
-
59
- Drawer composes Dialog with a dedicated Button drag handle. Snap fractions size an internal
60
- scroll viewport; the native dialog remains the host. Its optional spring adapter
61
- animates entry and snapping without delaying native close or focus.
62
-
63
- AlertDialog specializes Dialog's native lifecycle, surface tokens and motion for
64
- urgent decisions. Its modal content retains Dialog identities and adds alert-dialog tokens.
65
-
66
- Composition preserves theme, keyboard behavior and relationships.
67
-
68
- ## Presentation
69
-
70
- Actions take three independent props:
71
-
72
- | Prop | Values | Default |
73
- | ------------- | ------------------------------------------------------------------------- | ------------------------------------ |
74
- | `variant` | `solid`, `soft`, `outline`, `ghost`; Link also accepts `inline`, `subtle` | Button `solid`; Link `inline` |
75
- | `tone` | `accent`, `neutral`, `warning`, `danger` | Actions `accent`; feedback `neutral` |
76
- | `controlSize` | `small`, `medium`, `large` | `medium` |
77
-
78
- A variant picks the treatment and a tone picks the palette. Input, Textarea, Checkbox, Switch, Slider,
79
- Radio, RadioGroup, Combobox and Tabs share `controlSize` but have no variants. Native meanings
80
- win: `Input.size` stays a character count, and a checkbox `value` stays its
81
- submitted data. Radius is a theme decision, not a prop.
82
-
83
- Button defaults to `type="button"`. `pending` blocks activation but keeps focus
84
- and the accessible name. Button's optional `pressed` state is independent of press motion.
85
- Link is always an anchor and has no fake `disabled`.
86
-
87
- ## Themes
88
-
89
- A theme is one typed `defineTheme({ id, name, tokens, components, modes })`
90
- definition. Values resolve as **component override → shared token → neutral
91
- baseline**, and never fall back through another family's override. Shared tokens reach every family; overrides stay local.
92
-
93
- The core entry ships only the neutral baseline, `defaultTheme`. Styled presets
94
- are examples at `@cognitap/radiant/examples`, and Storybook, the docs and the
95
- theme workshop all read that one copy. Presets are starting points.
96
-
97
- `ThemeScope` is a plain `div` that applies a theme to its subtree. It does not
98
- touch the document or persist anything. Without `theme` or `mode` it inherits.
99
- A named theme starts fresh from the library defaults, so a nested `default`
100
- really resets an outer theme. `mode` (`light`, `dark` or `system`) is
101
- independent of the theme, and `system` uses CSS media queries so server markup
102
- stays stable. Token names, CSS variables, scopes and presets are in
103
- [theming](theming.md).
104
-
105
- ## Hosts and targeting
106
-
107
- Root `className`, `style`, native props and `ref` always reach the documented
108
- host, never a wrapper:
109
-
110
- | Family or part | Host |
111
- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
112
- | Charts / ChartDataTable | figure / Table table |
113
- | Carousel / CarouselViewport / Carousel controls | section / native scroll div / Button button |
114
- | Form / FormField / FormError | form / Field host / Alert div |
115
- | AppShell / AppShellHeader / AppShellMain / Sidebar | div / header / main / nav |
116
- | AppShellSkipLink / SidebarTrigger / SidebarLabel / SidebarContent | Link's a / Button's button / span / div |
117
- | AspectRatio | `div` |
118
- | Toolbar | `div` |
119
- | ToggleGroup / ToggleGroupItem | `div` / Button's `button` |
120
- | ScrollArea | Native `div` scroll viewport |
121
- | Skeleton | `span` |
122
- | Meter | Native meter |
123
- | Progress / Spinner | `progress` / `svg` |
124
- | Button / Link / NavLink | `button` / `a`, including through `render` |
125
- | Field | `div` in control layout; `fieldset` in group layout |
126
- | Input / PasswordInput / FileInput / NumberField / Checkbox / Switch / Slider / Radio | Native `input` |
127
- | Textarea | Native `textarea` |
128
- | NativeSelect | Native select |
129
- | Select / SelectPortal / Combobox / ComboboxPortal / Autocomplete / AutocompletePortal | None; state / portal |
130
- | Popover, HoverCard, Tooltip, Menu, ContextMenu, MenuSub / their Portals | None; state / portal |
131
- | Menubar / MenubarMenu / MenubarPortal | div / None / None |
132
- | ContextMenuTrigger / ContextMenuContent | Named native div / Menu content div |
133
- | HoverCardTrigger / HoverCardContent | Link's `a` / Popover's `div` |
134
- | MenuTrigger / MenuItem / MenuCheckboxItem / MenuRadioItem / MenuSubTrigger | Button's button |
135
- | MenuContent / MenuSubContent / MenuGroup / MenuLabel / MenuRadioGroup | div |
136
- | MenuSeparator | Separator's hr |
137
- | PopoverTrigger / PopoverClose / PopoverContent | Button's `button` / Button's `button` / `div` |
138
- | SelectTrigger / SelectContent / SelectViewport / SelectItem | Button's `button` / `div` / `div` / `div` |
139
- | ComboboxInput / AutocompleteInput / CommandInput | Native `input` |
140
- | ComboboxContent / ComboboxItem / AutocompleteContent / AutocompleteItem / CommandList / CommandItem | `div` |
141
- | ComboboxTrigger / ComboboxClear / AutocompleteTrigger / AutocompleteClear | Button's `button` |
142
- | Tabs / TabsList / TabsContent | `div` |
143
- | TabsTrigger | Button's `button` |
144
- | RadioGroup | Field's `fieldset` |
145
- | Dialog / AlertDialog / Drawer / Command | None; state owners |
146
- | Dialog actions / AlertDialog actions / Command actions | Button's `button` |
147
- | Dialog, AlertDialog, Drawer and Command Content / Title / Description | `dialog` / `h2` / `p` |
148
- | Collapsible / NavLinkGroup | `details` |
149
- | CollapsibleTrigger / NavLinkGroupTrigger | `summary` |
150
- | CollapsibleContent / NavLinkGroupContent | `div` |
151
- | Accordion / AccordionItem / AccordionTrigger / AccordionContent | `div` / `details` / `summary` / `div` |
152
- | Card / CardHeader / CardContent / CardFooter | `div` |
153
- | CardTitle and AlertTitle / CardDescription and AlertDescription | Heading chosen by `level` / `p` |
154
-
155
- MultiSelect parts retain Combobox hosts and add `multi-select-*`. TagsInput props/ref
156
- reach Input; wrapper, tag, removal and message styles use named parts. Tag props/ref
157
- reach Badge’s span; its removal part styles the actual Button.
158
-
159
- Internal parts take `className` and `style` through a `parts` map. Field has
160
- `label`, `description`, `error` and `required`. Checkbox, Switch and Radio have
161
- `wrapper`, `label` and `indicator`, and RadioGroup and CheckboxGroup add `options`. These hooks
162
- cannot replace IDs, ARIA, handlers or refs. Caller classes merge after the
163
- defaults and caller `style` wins. Identity and presentation data attributes
164
- cannot be overridden.
26
+ Each native element or behavior has one base family. Higher-level components compose that family instead of rendering raw elements or duplicating its state, keyboard, and focus logic.
165
27
 
166
- `data-slot` is a space-separated set, so select with `~=`, as in
167
- `[data-slot~="button"]`. Composed parts keep their base identity:
168
- `button dialog-trigger`, `field radio-group`, `collapsible accordion-item`.
169
- Why: styling written for Button still reaches a DialogTrigger.
28
+ `Button` owns `<button>` actions and `Link` owns `<a>` navigation, even when a link looks like a button. Triggers, close buttons, and action items in other families build on `Button`, and navigation items build on `Link`.
170
29
 
171
- Style real state: native `:disabled`, `:checked` and `open`, plus `aria-busy`
172
- for pending. Field and RadioGroup set `data-invalid`, `data-disabled` and
173
- `data-required`. Disclosures and DialogContent set `data-state="open|closed"`.
174
- Actions set `data-variant`, `data-tone` and `data-control-size`. Switch uses
175
- `data-dragging` during a provisional pointer gesture; `:checked` stays committed.
30
+ `Collapsible` owns `<details>` disclosures, `Dialog` owns modal `<dialog>` state and focus containment, and `Popover` owns the anchored popups of `Menu`, `ContextMenu`, `Menubar`, and `HoverCard`. `Select`, `Combobox`, and `Tooltip` render their own. All of these popups render inside the trigger's container with `popover="manual"`, so they enter the top layer and stay inside their theme and modal subtree.
176
31
 
177
- ## State and forms
32
+ ## Hosts, parts, and styling
178
33
 
179
- Each state axis has one owner for the life of a mount. Pass `value`, `checked`
180
- or `open` to control it, or `default*` to set an initial value. Passing both, or switching owner during
181
- a mount, throws; remount with a new `key` instead. A controlled callback is a request, and the consumer
182
- may refuse it. No-op requests and prop syncs fire no callback.
34
+ - Root `className`, `style`, `ref`, and native props go to the documented host element. State-only roots such as `Dialog` render no element; their named parts (`Trigger`, `Content`) do.
35
+ - `parts` styles inner elements such as `label` or `indicator`. Caller classes merge after Radiant's, and caller inline styles win. Radiant owns IDs, ARIA, events, refs, and state attributes.
36
+ - A composed host lists every slot: `data-slot="button dialog-trigger"`. Match one slot with `[data-slot~="button"]`.
37
+ - Style state with native selectors (`:disabled`, `:checked`, `[open]`), `aria-busy` for pending, and documented `data-state` values. Boolean attributes such as `data-selected` are present when true and absent otherwise.
38
+ - Actions take `variant` (appearance), `tone` (intent), and `controlSize` (scale). All controls share `controlSize`. Native props keep their native meaning: `Input.size` is a character width. Radius comes from the theme.
183
39
 
184
- | Family | State | Callback | Empty |
185
- | ---------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | ---------------------- |
186
- | Input, Textarea, NativeSelect | `value` / `defaultValue` | Native `onChange`, `onBlur` | `''` |
187
- | ToggleGroup single / multiple | `value` / `defaultValue` | `onValueChange(string \| null)` / `onValueChange(string[])` | `null` / `[]` |
188
- | Button toggle | `pressed` / `defaultPressed` | `onPressedChange(boolean)` | `false` |
189
- | Checkbox, Switch, standalone Radio | `checked` / `defaultChecked` | Native `onChange`, `onBlur` | `false` |
190
- | Slider | `value` / `defaultValue` | Native `onChange`, `onBlur` | Native midpoint |
191
- | RadioGroup | `value` / `defaultValue` | `onValueChange(string)` or native `onChange` | `null` |
192
- | Select | `value` / `defaultValue` | `onValueChange(string \| null)` | `null` |
193
- | Combobox | `value` / `defaultValue`; `query` / `defaultQuery` | `onValueChange(string \| null)`; `onQueryChange(string)` | `null`; `''` |
194
- | Tabs | `value` / `defaultValue` | `onValueChange(string)` | Initial value required |
195
- | Dialog, AlertDialog, Drawer, Collapsible | `open` / `defaultOpen` | `onOpenChange(boolean)` | `false` |
196
- | Popover | `open` / `defaultOpen` | `onOpenChange(boolean)` | `false` |
197
- | Accordion single | `value` / `defaultValue` | `onValueChange(string \| null)` | `null` |
198
- | Accordion multiple | `value` / `defaultValue` | `onValueChange(string[])` | `[]` |
40
+ ## State
199
41
 
200
- RadioGroup owns its options' `name`, generating one when none is given, and selection. Use one of `onValueChange`
201
- or `onChange` to write state, not both. `''` is a valid option value, and `null`
202
- clears the group.
42
+ Each state value has one owner for the life of a mount. Pass `x` to control it or `defaultX` to seed it. Passing both, or switching between them, throws. Remount with a new `key` to change owner.
203
43
 
204
- Field owns IDs and label, help and error relationships. Set a control's ID with
205
- Field's `controlId`. Radiant controls read Field context. A native control uses
206
- `children(controlProps)` and forwards those props. Disabled and required only
207
- add up: a child cannot re-enable or un-require what its Field set.
44
+ `onXChange(next)` receives the next value only.
208
45
 
209
- The consumer owns validation, touched and dirty state, error text, submission
210
- and persistence. Native reset restores uncontrolled inputs. A controlled adapter
211
- resets its own values. Reset never changes pressed buttons, ToggleGroup, Dialog, Tabs or disclosure state. Radiant has no form store. TanStack Form is an optional example adapter, not a dependency.
46
+ - Uncontrolled: Radiant applies the change, then calls the handler.
47
+ - Controlled: the handler is a request. If the application declines a disclosure toggle, Radiant restores `<details open>`.
212
48
 
213
- Select takes one `items` registry for SSR labels, native options and typeahead.
214
- Rich labels supply `textValue`. The focused option and committed value are
215
- distinct; activation commits, Escape dismisses and restores trigger focus.
216
- Native reset silently restores uncontrolled selection. Controlled resets stay
217
- with the owner. User selections emit form change; prop syncs do not.
49
+ ## Events
218
50
 
219
- Carousel uses native scroll snap and Button controls; opt-in autoplay pauses for interaction, visibility and reduced motion.
220
- Form coordinates native validation and asynchronous submission without storing values. FormField composes Field; FormError composes Alert.
51
+ For click and keydown, `composeAction` checks disabled and pending first, then calls the caller's handler, then the library action. `preventDefault()` in the caller's handler cancels the library action. Native `change`, `toggle`, and `blur` report what has already happened and cannot be cancelled.
221
52
 
222
- ## Replacement and events
53
+ ## Forms
223
54
 
224
- Button, Link and the Dialog actions accept `render(resolvedProps)`. Forward all
225
- props, the ref and the children to one compatible `button` or `a`. There is no
226
- `as` or `asChild`. Forwarding keeps the contract intact. Field's `children(controlProps)` adapts relationships and does not
227
- replace Field's host.
55
+ `Field` provides label and description IDs, passes `disabled` and `required` down, and renders a `<fieldset>` for control groups. Radiant controls read it from context. Plain HTML controls receive `children(controlProps)`.
228
56
 
229
- For cancellable actions, disabled and pending guards run first, then the
230
- consumer handler, then the state request if `defaultPrevented` is false. Native
231
- change, toggle and blur are observations and cannot veto anything. Library and
232
- caller refs get the same host, and callback-ref cleanup functions are honored.
233
- `useToggleGroup`, `useField`, `useDialog`, `usePopover`, `useTooltip`, `useMenu`, `useCombobox`, `useTabs`, `useCollapsible` and `useAccordion` read and request
234
- state, and return `null` outside their owner. Parts that need a root throw when misplaced. Lifecycle,
235
- SSR and hydration details are in [React bindings](react-bindings.md).
57
+ Custom controls submit through a native form element:
236
58
 
237
- ## What customization must keep
59
+ | Component | Submitted value |
60
+ | -------------------------- | ------------------------------------------------- |
61
+ | `Select` | Selected value, from a visually hidden `<select>` |
62
+ | `Combobox` | Committed key, from a hidden input |
63
+ | `Autocomplete` | Input text, including text not in the list |
64
+ | `MultiSelect`, `TagsInput` | One named value per item |
65
+ | `NumberField` | Raw number, separate from the localized display |
66
+ | `OTPField` | Whole code, from one input |
238
67
 
239
- Restyling or replacing a host is fine as long as these keep working:
68
+ `Form` runs native validation and async submission. The application owns values, rules, messages, and persistence. Reset restores uncontrolled controls, clears form errors, and aborts a pending submission. Widget state such as the active tab is not form state and survives reset.
240
69
 
241
- - Native controls and labels stay operable, with names and descriptions connected.
242
- - Focus, invalid, disabled and pending cues stay visible.
243
- - Closed dialog and details content stays hidden. Dialog keeps its bounds,
244
- scrolling and modal focus, and `details` keeps a direct-child `summary`.
245
- - Decorative indicators stay hidden from assistive technology.
246
- - Reduced-motion and forced-colors modes still work.
70
+ ## Customization limits
247
71
 
248
- Verify these behaviors manually: [accessibility](accessibility.md).
72
+ `render(props)` on button and link parts must return a `<button>` or `<a>`, or a component that forwards to one, with all props, the ref, and the children.
249
73
 
250
- ## Examples and type fixtures
74
+ Custom styling and rendering must keep:
251
75
 
252
- The canonical live examples are Storybook stories:
253
- [Input](../src/components/Input/Input.stories.tsx), [Form](../src/components/Form/Form.stories.tsx)
254
- (native validation, server recovery and optional TanStack values) and
255
- [Recipes → Workspace → Settings](../src/recipes/Workspace.stories.tsx) (all ten
256
- families). Change a contract and its example together.
76
+ - Connected labels and descriptions, and visible focus, invalid, disabled, and pending states.
77
+ - Closed dialog and disclosure content hidden, focus contained in modal dialogs, and `<summary>` as a direct child of `<details>`.
78
+ - `aria-hidden` on decorative indicators, and support for reduced motion and forced colors.
257
79
 
258
- `docs/contracts/*.ts(x)` are compile-only fixtures. `pnpm typecheck:contracts`
259
- checks that they type-check and that contradictory props, such as `value` with
260
- `defaultValue`, are rejected.
80
+ When a contract changes, update the component's stories and the compile checks in [tests/package](../tests/package).
package/docs/motion.md CHANGED
@@ -1,10 +1,12 @@
1
1
  # Motion
2
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
- Import `@cognitap/radiant/motion` or `/motion/react` for the runtime.
3
+ Opt-in springs for Radiant components and your own elements. Functions are in `@cognitap/radiant/motion`. Hooks and components are in `@cognitap/radiant/motion/react`. Both wrap Motion's `springValue`. See [ADR 0001](adr/0001-spring-engine-boundaries.md).
6
4
 
7
- ## Theme profiles
5
+ `prefers-reduced-motion: reduce` disables spring animation. Duration and easing tokens still apply to CSS transitions.
6
+
7
+ ## Theme profile
8
+
9
+ A theme sets springs under `motion`:
8
10
 
9
11
  ```tsx
10
12
  const theme = defineTheme({
@@ -17,137 +19,70 @@ const theme = defineTheme({
17
19
  })
18
20
  ```
19
21
 
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` |
22
+ | Field | Rule |
23
+ | --------------------- | -------------------------------------------------------------------------------------- |
24
+ | `spring` | Default `320` / `30` / `1`. Stiffness and damping in `(0, 10000]`, mass in `(0, 100]` |
25
+ | `interactions.<name>` | `press`, `disclosure`, `dialog`, `follow`, `drag`, or `layout`; each inherits `spring` |
26
+ | `mode` | `system` (default) or `off` |
25
27
 
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.
28
+ `ThemeScope` keeps the profile across light and dark. Theme documents store it at `sections.motion.profile`.
30
29
 
31
30
  ## Component motion
32
31
 
33
- ```tsx
34
- import { MotionProvider, MotionLink } from '@cognitap/radiant/motion/react'
35
-
36
- ;<MotionProvider>
37
- <Button>Save</Button>
38
- <Button motion="off">No spring</Button>
39
- <MotionLink
40
- variant="solid"
41
- href="/account"
42
- >
43
- Account
44
- </MotionLink>
45
- </MotionProvider>
46
- ```
47
-
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/components/Link/Link.stories.tsx) and [Button](../src/components/Button/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
32
+ Wrap a subtree in `MotionProvider`. It adds no DOM.
108
33
 
109
34
  ```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>
35
+ import { Button } from '@cognitap/radiant'
36
+ import { MotionLink, MotionProvider } from '@cognitap/radiant/motion/react'
37
+
38
+ export function AccountActions() {
39
+ return (
40
+ <MotionProvider>
41
+ <Button>Save</Button>
42
+ <Button motion="off">No spring</Button>
43
+ <MotionLink
44
+ variant="solid"
45
+ href="/account"
46
+ >
47
+ Account
48
+ </MotionLink>
49
+ </MotionProvider>
50
+ )
51
+ }
126
52
  ```
127
53
 
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.
54
+ Examples:
55
+
56
+ | Component | Motion |
57
+ | ---------------------------------------- | --------------------------------------------------------------------------------- |
58
+ | `Button`, `DialogTrigger`, `DialogClose` | Compress on press to `--rad-button-press-scale` (default `0.97`, range `0.5`–`1`) |
59
+ | `MotionLink` | Press scale on button-styled links. `Link` stays server-renderable |
60
+ | `Collapsible`, `Accordion` | Animate height. Closed content is inert immediately |
61
+ | `Dialog` | Springs open. The `<dialog>` closes immediately. An inert clone finishes the exit |
62
+ | `Select` | Fade the popup in. Close immediately |
63
+
64
+ The exit clone is skipped when the dialog has more than 500 descendants, or when it contains a nested dialog, media, a canvas, an embed, or a custom element. The clone stops after 2 seconds.
65
+
66
+ Pass `motion="off"` on `Button`, `MotionLink`, `Collapsible`, `SelectContent`, or `DialogContent`. A caller `scale-*` class, inline `scale`, or scale transition also disables press scaling.
67
+
68
+ ## Spring API
69
+
70
+ | API | Entry | Purpose |
71
+ | ---------------------------------------------- | --------------- | ------------------------------------------------------------------------------- |
72
+ | `createSpring(initial, options)` | `/motion` | `to`, `jump`, `stop`, `get`, `getVelocity`, `subscribe`, `configure`, `destroy` |
73
+ | `bindSpringStyle(el, spring, prop)` | `/motion` | `scale`, `opacity`, `width`, `height`, `translateX`, `translateY` |
74
+ | `useSpring`, `useSpringStyle` | `/motion/react` | Theme profile and reduced motion |
75
+ | `useReducedMotion` | `/motion/react` | `prefers-reduced-motion` |
76
+ | `useSpringFollow(target)` | `/motion/react` | Follow a number or `SpringSource` (`{ get, subscribe }`) |
77
+ | `bindSpringSource(spring, source)` | `/motion` | `useSpringFollow` outside React |
78
+ | `useSpringDrag(ref, initial, opts)` | `/motion/react` | One-axis pointer and keyboard drag, with bounds and snap points |
79
+ | `createSpringDrag`, `bindSpringDrag` | `/motion` | Drag controller and element binding |
80
+ | `useSpringLayout(ref)` | `/motion/react` | Reorder and resize a flex or grid group |
81
+ | `bindSpringLayout(root)`, `createLayoutSpring` | `/motion` | Layout binding and a 4-axis spring |
82
+
83
+ - Values are finite numbers in one unit. Convert percentages, colors, and CSS variables first.
84
+ - `to(next)` keeps position and velocity. `configure` applies at rest.
85
+ - When motion is off or reduced, `to` jumps to `reducedValue ?? target`.
86
+ - `bindSpringStyle` writes its CSS property and restores the previous inline value on cleanup.
87
+ - Hooks do not write animation frames to React state.
88
+ - `useSpringLayout` measures each direct child marked `data-rad-layout-slot`. That child has one first-child `data-rad-layout-part`, no padding or border, and stays in normal flow.