@cognitap/radiant 0.0.78 → 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 (222) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +6 -3
  3. package/RELEASE_POLICY.md +8 -19
  4. package/dist/library/charts/Charts.js +1 -1
  5. package/dist/library/charts/Charts.js.map +1 -1
  6. package/dist/library/components/Accordion/Accordion.js +1 -1
  7. package/dist/library/components/Accordion/Accordion.js.map +1 -1
  8. package/dist/library/components/Alert/Alert.js +1 -1
  9. package/dist/library/components/Alert/Alert.js.map +1 -1
  10. package/dist/library/components/AppShell/AppShell.js +1 -1
  11. package/dist/library/components/AppShell/AppShell.js.map +1 -1
  12. package/dist/library/components/AspectRatio/AspectRatio.js +1 -1
  13. package/dist/library/components/AspectRatio/AspectRatio.js.map +1 -1
  14. package/dist/library/components/Avatar/Avatar.js +1 -1
  15. package/dist/library/components/Avatar/Avatar.js.map +1 -1
  16. package/dist/library/components/Badge/Badge.js +1 -1
  17. package/dist/library/components/Badge/Badge.js.map +1 -1
  18. package/dist/library/components/Breadcrumb/Breadcrumb.js +1 -1
  19. package/dist/library/components/Breadcrumb/Breadcrumb.js.map +1 -1
  20. package/dist/library/components/Button/Button.js +1 -1
  21. package/dist/library/components/Button/Button.js.map +1 -1
  22. package/dist/library/components/ButtonGroup/ButtonGroup.js +1 -1
  23. package/dist/library/components/ButtonGroup/ButtonGroup.js.map +1 -1
  24. package/dist/library/components/Card/Card.js +1 -1
  25. package/dist/library/components/Card/Card.js.map +1 -1
  26. package/dist/library/components/Carousel/Carousel.js +6 -6
  27. package/dist/library/components/Carousel/Carousel.js.map +1 -1
  28. package/dist/library/components/Checkbox/Checkbox.js +1 -1
  29. package/dist/library/components/Checkbox/Checkbox.js.map +1 -1
  30. package/dist/library/components/CheckboxGroup/CheckboxGroup.js +1 -1
  31. package/dist/library/components/CheckboxGroup/CheckboxGroup.js.map +1 -1
  32. package/dist/library/components/CodeBlock/CodeBlock.js +1 -1
  33. package/dist/library/components/CodeBlock/CodeBlock.js.map +1 -1
  34. package/dist/library/components/Collapsible/Collapsible.js +1 -1
  35. package/dist/library/components/Collapsible/Collapsible.js.map +1 -1
  36. package/dist/library/components/Combobox/Combobox.js +1 -1
  37. package/dist/library/components/Combobox/Combobox.js.map +1 -1
  38. package/dist/library/components/Command/Command.js +1 -1
  39. package/dist/library/components/Command/Command.js.map +1 -1
  40. package/dist/library/components/ContextMenu/ContextMenu.js +1 -1
  41. package/dist/library/components/ContextMenu/ContextMenu.js.map +1 -1
  42. package/dist/library/components/Dialog/Dialog.js +1 -1
  43. package/dist/library/components/Dialog/Dialog.js.map +1 -1
  44. package/dist/library/components/Drawer/Drawer.js +1 -1
  45. package/dist/library/components/Drawer/Drawer.js.map +1 -1
  46. package/dist/library/components/EmptyState/EmptyState.js +1 -1
  47. package/dist/library/components/EmptyState/EmptyState.js.map +1 -1
  48. package/dist/library/components/Field/Field.js +1 -1
  49. package/dist/library/components/Field/Field.js.map +1 -1
  50. package/dist/library/components/Fieldset/Fieldset.js +1 -1
  51. package/dist/library/components/Fieldset/Fieldset.js.map +1 -1
  52. package/dist/library/components/FileInput/FileInput.js +1 -1
  53. package/dist/library/components/FileInput/FileInput.js.map +1 -1
  54. package/dist/library/components/Form/Form.js +4 -4
  55. package/dist/library/components/Form/Form.js.map +1 -1
  56. package/dist/library/components/HoverCard/HoverCard.js +1 -1
  57. package/dist/library/components/HoverCard/HoverCard.js.map +1 -1
  58. package/dist/library/components/InlineCode/InlineCode.js +1 -1
  59. package/dist/library/components/InlineCode/InlineCode.js.map +1 -1
  60. package/dist/library/components/Input/Input.js +1 -1
  61. package/dist/library/components/Input/Input.js.map +1 -1
  62. package/dist/library/components/InputGroup/InputGroup.js +1 -1
  63. package/dist/library/components/InputGroup/InputGroup.js.map +1 -1
  64. package/dist/library/components/Kbd/Kbd.js +1 -1
  65. package/dist/library/components/Kbd/Kbd.js.map +1 -1
  66. package/dist/library/components/Link/Link.js +1 -1
  67. package/dist/library/components/Link/Link.js.map +1 -1
  68. package/dist/library/components/Menu/Menu.js +1 -1
  69. package/dist/library/components/Menu/Menu.js.map +1 -1
  70. package/dist/library/components/Menubar/Menubar.js +1 -1
  71. package/dist/library/components/Menubar/Menubar.js.map +1 -1
  72. package/dist/library/components/Meter/Meter.js +1 -1
  73. package/dist/library/components/Meter/Meter.js.map +1 -1
  74. package/dist/library/components/NativeSelect/NativeSelect.js +1 -1
  75. package/dist/library/components/NativeSelect/NativeSelect.js.map +1 -1
  76. package/dist/library/components/NavLink/NavLink.js +1 -1
  77. package/dist/library/components/NavLink/NavLink.js.map +1 -1
  78. package/dist/library/components/NavigationMenu/NavigationMenu.js +1 -1
  79. package/dist/library/components/NavigationMenu/NavigationMenu.js.map +1 -1
  80. package/dist/library/components/NumberField/NumberField.js +1 -1
  81. package/dist/library/components/NumberField/NumberField.js.map +1 -1
  82. package/dist/library/components/OTPField/OTPField.js +1 -1
  83. package/dist/library/components/OTPField/OTPField.js.map +1 -1
  84. package/dist/library/components/Pagination/Pagination.js +1 -1
  85. package/dist/library/components/Pagination/Pagination.js.map +1 -1
  86. package/dist/library/components/PasswordInput/PasswordInput.js +1 -1
  87. package/dist/library/components/PasswordInput/PasswordInput.js.map +1 -1
  88. package/dist/library/components/Popover/Popover.js +1 -1
  89. package/dist/library/components/Popover/Popover.js.map +1 -1
  90. package/dist/library/components/Progress/Progress.js +1 -1
  91. package/dist/library/components/Progress/Progress.js.map +1 -1
  92. package/dist/library/components/RadioGroup/RadioGroup.js +1 -1
  93. package/dist/library/components/RadioGroup/RadioGroup.js.map +1 -1
  94. package/dist/library/components/Resizable/Resizable.js +1 -1
  95. package/dist/library/components/Resizable/Resizable.js.map +1 -1
  96. package/dist/library/components/ScrollArea/ScrollArea.js +1 -1
  97. package/dist/library/components/ScrollArea/ScrollArea.js.map +1 -1
  98. package/dist/library/components/Select/Select.js +1 -1
  99. package/dist/library/components/Select/Select.js.map +1 -1
  100. package/dist/library/components/Separator/Separator.js +1 -1
  101. package/dist/library/components/Separator/Separator.js.map +1 -1
  102. package/dist/library/components/Skeleton/Skeleton.js +1 -1
  103. package/dist/library/components/Skeleton/Skeleton.js.map +1 -1
  104. package/dist/library/components/Slider/Slider.js +1 -1
  105. package/dist/library/components/Slider/Slider.js.map +1 -1
  106. package/dist/library/components/Spinner/Spinner.js +1 -1
  107. package/dist/library/components/Spinner/Spinner.js.map +1 -1
  108. package/dist/library/components/Switch/Switch.js +1 -1
  109. package/dist/library/components/Switch/Switch.js.map +1 -1
  110. package/dist/library/components/Table/Table.js +1 -1
  111. package/dist/library/components/Table/Table.js.map +1 -1
  112. package/dist/library/components/Tabs/Tabs.js +1 -1
  113. package/dist/library/components/Tabs/Tabs.js.map +1 -1
  114. package/dist/library/components/Tag/Tag.js +1 -1
  115. package/dist/library/components/Tag/Tag.js.map +1 -1
  116. package/dist/library/components/TagsInput/TagsInput.js +1 -1
  117. package/dist/library/components/TagsInput/TagsInput.js.map +1 -1
  118. package/dist/library/components/Textarea/Textarea.js +1 -1
  119. package/dist/library/components/Textarea/Textarea.js.map +1 -1
  120. package/dist/library/components/ThemeScope/ThemeScope.js +1 -1
  121. package/dist/library/components/ThemeScope/ThemeScope.js.map +1 -1
  122. package/dist/library/components/Toast/Toast.js +1 -1
  123. package/dist/library/components/Toast/Toast.js.map +1 -1
  124. package/dist/library/components/ToggleGroup/ToggleGroup.js +3 -1
  125. package/dist/library/components/ToggleGroup/ToggleGroup.js.map +1 -1
  126. package/dist/library/components/Toolbar/Toolbar.js +1 -1
  127. package/dist/library/components/Toolbar/Toolbar.js.map +1 -1
  128. package/dist/library/components/Tooltip/Tooltip.js +1 -1
  129. package/dist/library/components/Tooltip/Tooltip.js.map +1 -1
  130. package/dist/library/motion/MotionLink.js +1 -1
  131. package/dist/library/motion/MotionLink.js.map +1 -1
  132. package/dist/library/react/useComboboxPopup.d.ts.map +1 -1
  133. package/dist/library/react/useComboboxPopup.js +45 -6
  134. package/dist/library/react/useComboboxPopup.js.map +1 -1
  135. package/dist/library/react/useRovingFocus.d.ts.map +1 -1
  136. package/dist/library/react/useRovingFocus.js +76 -11
  137. package/dist/library/react/useRovingFocus.js.map +1 -1
  138. package/dist/library/react/useToastTimer.d.ts.map +1 -1
  139. package/dist/library/react/useToastTimer.js +28 -9
  140. package/dist/library/react/useToastTimer.js.map +1 -1
  141. package/dist/library/styles.css +1 -1
  142. package/docs/accessibility.md +23 -111
  143. package/docs/architecture.md +48 -242
  144. package/docs/motion.md +65 -130
  145. package/docs/theming.md +51 -427
  146. package/package.json +21 -13
  147. package/src/charts/Charts.tsx +1 -1
  148. package/src/components/Accordion/Accordion.tsx +1 -1
  149. package/src/components/Alert/Alert.tsx +1 -1
  150. package/src/components/AppShell/AppShell.tsx +1 -1
  151. package/src/components/AspectRatio/AspectRatio.tsx +1 -1
  152. package/src/components/Avatar/Avatar.tsx +1 -1
  153. package/src/components/Badge/Badge.tsx +1 -1
  154. package/src/components/Breadcrumb/Breadcrumb.tsx +1 -1
  155. package/src/components/Button/Button.tsx +1 -1
  156. package/src/components/ButtonGroup/ButtonGroup.tsx +1 -1
  157. package/src/components/Card/Card.tsx +1 -1
  158. package/src/components/Carousel/Carousel.tsx +6 -6
  159. package/src/components/Checkbox/Checkbox.tsx +1 -1
  160. package/src/components/CheckboxGroup/CheckboxGroup.tsx +1 -1
  161. package/src/components/CodeBlock/CodeBlock.tsx +1 -1
  162. package/src/components/Collapsible/Collapsible.tsx +1 -1
  163. package/src/components/Combobox/Combobox.tsx +1 -1
  164. package/src/components/Command/Command.tsx +1 -1
  165. package/src/components/ContextMenu/ContextMenu.tsx +1 -1
  166. package/src/components/Dialog/Dialog.tsx +1 -1
  167. package/src/components/Drawer/Drawer.tsx +1 -1
  168. package/src/components/EmptyState/EmptyState.tsx +1 -1
  169. package/src/components/Field/Field.tsx +1 -1
  170. package/src/components/Fieldset/Fieldset.tsx +1 -1
  171. package/src/components/FileInput/FileInput.tsx +1 -1
  172. package/src/components/Form/Form.tsx +4 -4
  173. package/src/components/HoverCard/HoverCard.tsx +1 -1
  174. package/src/components/InlineCode/InlineCode.tsx +1 -1
  175. package/src/components/Input/Input.tsx +1 -1
  176. package/src/components/InputGroup/InputGroup.tsx +1 -1
  177. package/src/components/Kbd/Kbd.tsx +1 -1
  178. package/src/components/Link/Link.tsx +1 -1
  179. package/src/components/Menu/Menu.tsx +1 -1
  180. package/src/components/Menubar/Menubar.tsx +1 -1
  181. package/src/components/Meter/Meter.tsx +1 -1
  182. package/src/components/NativeSelect/NativeSelect.tsx +1 -1
  183. package/src/components/NavLink/NavLink.tsx +1 -1
  184. package/src/components/NavigationMenu/NavigationMenu.tsx +1 -1
  185. package/src/components/NumberField/NumberField.tsx +1 -1
  186. package/src/components/OTPField/OTPField.tsx +1 -1
  187. package/src/components/Pagination/Pagination.tsx +1 -1
  188. package/src/components/PasswordInput/PasswordInput.tsx +1 -1
  189. package/src/components/Popover/Popover.tsx +1 -1
  190. package/src/components/Progress/Progress.tsx +1 -1
  191. package/src/components/RadioGroup/RadioGroup.tsx +1 -1
  192. package/src/components/Resizable/Resizable.tsx +1 -1
  193. package/src/components/ScrollArea/ScrollArea.tsx +1 -1
  194. package/src/components/Select/Select.tsx +1 -1
  195. package/src/components/Separator/Separator.tsx +1 -1
  196. package/src/components/Skeleton/Skeleton.tsx +1 -1
  197. package/src/components/Slider/Slider.tsx +1 -1
  198. package/src/components/Spinner/Spinner.tsx +1 -1
  199. package/src/components/Switch/Switch.tsx +1 -1
  200. package/src/components/Table/Table.tsx +1 -1
  201. package/src/components/Tabs/Tabs.tsx +1 -1
  202. package/src/components/Tag/Tag.tsx +1 -1
  203. package/src/components/TagsInput/TagsInput.tsx +1 -1
  204. package/src/components/Textarea/Textarea.tsx +1 -1
  205. package/src/components/ThemeScope/ThemeScope.tsx +1 -1
  206. package/src/components/Toast/Toast.tsx +1 -1
  207. package/src/components/ToggleGroup/ToggleGroup.tsx +3 -1
  208. package/src/components/Toolbar/Toolbar.tsx +1 -1
  209. package/src/components/Tooltip/Tooltip.tsx +1 -1
  210. package/src/css.d.ts +2 -0
  211. package/src/motion/MotionLink.tsx +1 -1
  212. package/src/react/useComboboxPopup.ts +38 -6
  213. package/src/react/useRovingFocus.ts +73 -8
  214. package/src/react/useToastTimer.ts +24 -9
  215. package/src/styles.d.ts +1 -0
  216. package/src/themes/baseline.css +1 -1
  217. package/src/typography.css +17 -12
  218. package/dist/library/cn.d.ts +0 -3
  219. package/dist/library/cn.d.ts.map +0 -1
  220. package/dist/library/cn.js +0 -370
  221. package/dist/library/cn.js.map +0 -1
  222. package/src/cn.ts +0 -372
@@ -1,123 +1,35 @@
1
1
  # Accessibility
2
2
 
3
- What to check by hand, on which browsers and screen readers, and how to record
4
- it. Automated tests are described in [testing](testing.md). The reference is
5
- [WCAG 2.2 A/AA](https://www.w3.org/TR/WCAG22/). Component checks are evidence
6
- toward it, but conformance applies to whole pages, so this is not a
7
- certification.
3
+ What automation covers, what to check by hand, and who owns what. Radiant targets [WCAG 2.2 A/AA](https://www.w3.org/TR/WCAG22/).
8
4
 
9
- ## Targets
5
+ ## Automated checks
10
6
 
11
- | Target | Input / AT | Status |
12
- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
13
- | Pinned Playwright Chromium on the local macOS host | Automated browser input and axe; no AT | Version-complete environment captured |
14
- | Pinned Playwright Chromium on Linux CI | Same automated suite; no AT | Each new run records its own environment and JUnit report; inspect that run's artifacts |
15
- | Windows + Firefox | Keyboard and NVDA | **Not run**; browser, OS and NVDA versions unrecorded |
16
- | macOS + Safari | Keyboard and VoiceOver | **Not run**; installed OS availability is not a test result |
17
- | iOS + Safari on a physical iPhone/iPad | Touch exploration and VoiceOver; external keyboard when claimed | **Not run**; device, OS/build, Safari and AT configuration unrecorded |
18
- | Android + Chrome on a physical device | Touch exploration and TalkBack; external keyboard when claimed | **Not run**; device, OS/build, Chrome and TalkBack versions unrecorded |
19
- | Desktop Chrome / Edge on supported Windows/macOS; Firefox and Safari on their supported desktop OS | Keyboard, zoom, visual rendering; real Windows contrast themes where applicable | **Not run as a version-complete manual matrix** |
7
+ | Command | Checks |
8
+ | ------------------- | ------------------------------------------ |
9
+ | `pnpm test:browser` | axe on every story in Playwright Chromium |
10
+ | `pnpm test:package` | Token contrast across every exported theme |
20
11
 
21
- A row marked **Not run** is a gap, not a failure. Record exact versions when you
22
- test; "latest" is not a version. Playwright WebKit does not stand in for Safari
23
- with VoiceOver, and a desktop engine does not stand in for a mobile browser.
12
+ Automation does not cover screen readers, real browser zoom, OS forced colors, or contrast over translucent surfaces such as Glass. Playwright WebKit is not Safari with VoiceOver, and browser media emulation is not OS reduced motion or forced colors.
24
13
 
25
- ## Prepare a run
14
+ ## Manual targets
26
15
 
27
- 1. Use a fixed commit with matching JavaScript and CSS. Note the CSS route,
28
- reset, overrides and fonts.
29
- 2. Open the [canonical examples](architecture.md#examples-and-type-fixtures).
30
- Cover native and TanStack forms, standalone, Card and Dialog placement, and
31
- both default and `render` actions.
32
- 3. Pick the theme and mode in the Storybook toolbar. Add `embed=true` to the
33
- iframe URL so plays do not interfere. See
34
- [Storybook](storybook.md#verification).
35
- 4. Record each preset and mode you test. Never write "all themes" from a sample.
36
- 5. Record OS, browser and screen reader versions and settings first: zoom,
37
- viewport, text scaling, reduced motion and contrast settings.
16
+ | Platform | Setup |
17
+ | -------- | --------------------------------------------------------------------- |
18
+ | Windows | Firefox + NVDA, and Windows contrast themes (`forced-colors: active`) |
19
+ | macOS | Safari + VoiceOver |
20
+ | iOS | Safari + VoiceOver on a physical device |
21
+ | Android | Chrome + TalkBack on a physical device |
38
22
 
39
- ## Scenarios
23
+ ## Manual checks
40
24
 
41
- Run keyboard cases with the screen reader off, then on. Record what is conveyed
42
- (names, roles, states), not exact wording.
25
+ Open Storybook (`pnpm storybook`) and check the affected stories in each theme and mode.
43
26
 
44
- | ID | Action and expected observation |
45
- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46
- | K1 — actions | Tab/Shift+Tab through Button, Link and Dialog actions, including default/custom hosts. Enter/Space activate buttons; Enter follows a link, while Space keeps native anchor behavior. Pending/disabled actions retain their documented guards/cues. Press, move away, then release to check cancellation. Visible text is included in the accessible name. |
47
- | K2 — forms | Read Field labels/help/required/error text and RadioGroup legend/options. Exercise text entry, checkbox checked/unchecked/mixed state, radio arrows/Space and disabled options. Submit invalid then valid data; hear the error relationship and saved/reset result. Reset restores the right owner and clears stale feedback in native and TanStack recipes. |
48
- | K3 — Dialog | Open through default Trigger and a compatible replacement. Confirm name/description, appropriate initial focus, keyboard focus containment, background inertness, a reachable visible close action, Escape and focus restoration. Repeat with long content and a narrow viewport. Check nonmodal behavior separately; a modal's standard exit makes its contained Tab cycle legitimate. |
49
- | K4 — disclosures | Enter/Space toggle native summary; expanded state and meaningful heading/order reach AT. Closed content is excluded from reading/focus navigation while remaining mounted. Check nested Collapsible and single/multiple Accordion, disabled sections and independent instances. Keep native summary behavior rather than inventing button or roving-focus rules. |
50
- | K5 — composition | Complete Recipes → Workspace: open the profile Dialog, correct an error, save/reset, open Privacy/Data retention and follow its Link. Check Card's reading order/heading and contained actions without adding a focus stop to its passive wrapper. Test reused forms and actual navigation/form data, not only a rendered role. |
51
- | V1 — palette and state | For every claimed theme/mode, inspect rest/hover/press/focus, invalid/required, pending, selected/mixed and disabled states. Measure rendered text, outlines and state indicators against adjacent/composited backgrounds, especially Glass gradients. Record sizes, ratios and any criterion exception; keep non-color cues. |
52
- | V2 — resizing | Test native browser zoom at 200% text resize and a 1280 CSS px viewport at 400% zoom (320 CSS px effective width), plus actual narrow viewports. Apply the text-spacing overrides below together. Check clipping, two-axis scrolling, modal scrolling, sticky/overlay focus obstruction and portrait/landscape. A resized viewport alone is not browser-zoom evidence. |
53
- | V3 — preferences | Enable real OS reduced motion and, on Windows, contrast themes/forced colors. Verify visible focus, selected/disabled/mixed marks, pending feedback and readable controls after decorative paint disappears. Label browser-emulated media checks as emulation; they do not establish real OS or AT behavior. |
54
- | T1 — mobile AT | On iOS/Android, explore by touch and swipe reading order, use heading/link/form navigation, activate with double-tap, edit and dismiss the on-screen keyboard, select options and submit/correct/reset the form. Open/close Dialog and verify touch/reading containment and restoration. Ensure collapsed/disabled/background items are treated appropriately. Measure the real label/control hit area and spacing, not only its glyph. |
27
+ - **Keyboard and screen reader.** Tab through actions, fields, disclosures, and dialogs, first with the screen reader off and then on. Check names, roles, and states (`disabled`, `aria-busy`, `aria-invalid`, `aria-expanded`, checked, mixed), error and description announcements, modal focus containment, Escape, and focus restoration.
28
+ - **Contrast.** Check rest, hover, press, focus, invalid, pending, selected, and disabled states against their real backgrounds, especially Glass gradients. Normal text needs 4.5:1. Large text, control boundaries, state indicators, and focus outlines need 3:1 against adjacent colors. Keep non-color cues.
29
+ - **Zoom and spacing.** Check 200% text resize and 400% browser zoom at a 1280 px viewport (320 px effective width), and WCAG text spacing (line height 1.5, paragraph spacing 2 em, letter spacing 0.12 em, word spacing 0.16 em). Look for clipped text, two-axis scrolling, and sticky or overlay elements hiding focus.
30
+ - **Pointer.** Targets need 24 × 24 px, or 24 px between target centers. Releasing outside a control cancels activation.
31
+ - **OS preferences.** With reduced motion on, springs and CSS lift or shift stop while state changes stay immediate. With Windows contrast themes on, focus outlines, selection marks, and boundaries stay visible once decorative backgrounds are stripped.
55
32
 
56
- Native radio entry with no option checked differs between browsers; record it
57
- rather than forcing the [APG radio](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
58
- model. Use the [APG modal dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
59
- guidance for initial focus and restoration.
33
+ ## Ownership
60
34
 
61
- ### Screen reader pairs
62
-
63
- | Pair | Procedure and primary reference |
64
- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
65
- | NVDA + Firefox / Windows | Record NVDA's installed version and browse/focus settings. Use `NVDA+Space` to switch browse/focus modes; Tab/Shift+Tab also exercise native focus. Browse with heading/link/form/button/checkbox/radio commands and test actual input in focus mode. Capture the relevant Speech Viewer output alongside focus observations. [NVDA browse mode](https://download.nvaccess.org/documentation/userGuide.html#BrowseMode), [Speech Viewer](https://download.nvaccess.org/documentation/userGuide.html#SpeechViewer). |
66
- | VoiceOver + Safari / macOS | Record Safari, OS/build, VoiceOver modifier and Safari/macOS keyboard navigation settings. Use `VO+Left/Right` to read, `VO+Space` to activate, and `VO+Shift+Down/Up` to enter/exit groups; use the rotor for headings/links/forms. Test plain Tab order as a separate observation. [Apple VoiceOver guide](https://support.apple.com/guide/voiceover/vo4be8816d70/mac), [rotor](https://support.apple.com/guide/voiceover/mchlp2719/mac). |
67
- | VoiceOver + Safari / iOS | Record device, iOS build, Safari context and VoiceOver settings. Touch explores; swipe Right/Left moves next/previous; double-tap activates. Use the rotor's headings/links/form-control categories and check the on-screen keyboard and modal boundaries. [Apple gestures](https://support.apple.com/guide/iphone/iph3e2e2281/ios), [Safari](https://support.apple.com/guide/iphone/iphe4ee74be8/ios). |
68
- | TalkBack + Chrome / Android | Record Android/build, device, Chrome and installed TalkBack version/settings. Touch explores; swipe Right/Left moves next/previous; double-tap activates; two-finger swipe scrolls. Use reading controls for headings/links/controls, accounting for customised gestures. [Google Chrome guidance](https://support.google.com/accessibility/android/answer/2633135?hl=en), [TalkBack gestures](https://support.google.com/accessibility/android/answer/6151827?hl=en). |
69
-
70
- ## WCAG criteria
71
-
72
- These are the criteria to assess for each scenario, not passed results.
73
-
74
- | Scenario / requirement area | Relevant A/AA criteria and evidence |
75
- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
76
- | K1–K5, T1: semantics and content | [1.1.1 A](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html), [1.3.1 A](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html), [1.3.2 A](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html), [2.4.4 A](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html), [2.4.6 AA](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html), [2.5.3 A](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html), [3.3.2 A](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html), [4.1.2 A](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html): capture reading order, accessible names, grouping, roles/states and meaningful instructions. |
77
- | K1–K5: keyboard and focus | [2.1.1 A](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html), [2.1.2 A](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html), [2.4.3 A](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html), [2.4.7 AA](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html), [2.4.11 AA](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html): record the key sequence, focus order, visible indicator, exit and overlay/scroll behavior. |
78
- | K2/K5: input, errors and feedback | [1.3.5 AA](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html), [3.2.1 A](https://www.w3.org/WAI/WCAG22/Understanding/on-focus.html), [3.2.2 A](https://www.w3.org/WAI/WCAG22/Understanding/on-input.html), [3.3.1 A](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html), [3.3.3 AA](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html), [4.1.3 AA](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html): record purpose metadata where applicable, context changes, error/correction text and actual status announcements without focus theft. Opening a dialog is not itself a status message. |
79
- | V1: visual information | [1.4.1 A](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html), [1.4.3 AA](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html), [1.4.11 AA](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html): record non-color cues and measured contrast on actual backgrounds. Normal text needs 4.5:1; large text needs 3:1; required control/state visual information needs 3:1 against adjacent colors. |
80
- | V2/T1: adaptable layout | [1.3.4 AA](https://www.w3.org/WAI/WCAG22/Understanding/orientation.html), [1.4.4 AA](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html), [1.4.10 AA](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html), [1.4.12 AA](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html): retain content/function at the tested zoom, effective width, spacing and orientation; record any applicable exceptions. |
81
- | K1/T1: pointer and targets | [2.5.2 A](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html), [2.5.8 AA](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html): record cancellation behavior and measured target/spacing, or the precise exception used. |
82
- | Additional hover/focus content | [1.4.13 AA](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html): if extra content appears, check dismissal, hoverability and persistence; an ordinary paint-only hover effect is not extra content. |
83
-
84
- Easy to get wrong:
85
-
86
- - **Focus:** 2.4.7 and 2.4.11 are AA. The two-pixel perimeter rule (2.4.13) is
87
- AAA.
88
- - **Targets:** 2.5.8 needs 24×24 CSS px unless an exception applies. For the
89
- spacing exception, a 24px circle centered on each small target must not touch
90
- another target or circle. Styled native controls are not exempt by default.
91
- - **Contrast:** large text is 18pt, or 14pt bold. Disabled controls are exempt,
92
- but record their legibility anyway.
93
- - **Text spacing:** apply line height 1.5×, paragraph spacing 2×, letter spacing
94
- 0.12× and word spacing 0.16× the font size together.
95
- - **Preferences:** emulated reduced motion or forced colors is not an OS result.
96
-
97
- ## Record results
98
-
99
- Put the results in the pull request with a link to the CI run and commit. Use
100
- this structure for each run:
101
-
102
- ```text
103
- Record ID, date/time, tester and method (manual / automated / emulated)
104
- Source revision + dirty changes, package integrity/fixture, CSS/reset/fonts
105
- OS/version/build, device, browser/version, AT/version (or bundled OS build)
106
- AT mode/verbosity/custom gestures, keyboard/zoom/scaling/viewport/orientation
107
- Preset/mode and state; scenario IDs; applicable WCAG criteria or N/A reason
108
- Steps + expected outcome + observed outcome / actual announcement / ratio / geometry
109
- Result per case: pass / fail / not-run / incomplete / not-applicable (with reason)
110
- JUnit/log/capture/transcript links; defect issue + affected combinations
111
- Retest revision and result; remaining untested combinations/criterion gaps
112
- ```
113
-
114
- A failure gets an issue listing the affected combinations; link the fix and
115
- the retest. An inconclusive axe result stays incomplete until reviewed. Never
116
- turn a missing result into a pass.
117
-
118
- ## What the application owns
119
-
120
- Radiant supplies native semantics, relationships and functional styles. The
121
- application supplies meaningful names, headings and content, form instructions
122
- and errors, initial focus, navigation, and its own colors and overrides. It must
123
- test its own pages and tasks; a passing library matrix does not cover them.
35
+ Radiant provides native elements, ARIA relationships, keyboard behavior, and theme tokens. Applications own accessible names, heading hierarchy, form instructions and error messages, landmarks, and any custom colors or style overrides.
@@ -1,274 +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. 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
- ## Presentation
67
-
68
- Actions take three independent props:
69
-
70
- | Prop | Values | Default |
71
- | ------------- | ------------------------------------------------------------------------- | ------------------------------------ |
72
- | `variant` | `solid`, `soft`, `outline`, `ghost`; Link also accepts `inline`, `subtle` | Button `solid`; Link `inline` |
73
- | `tone` | `accent`, `neutral`, `warning`, `danger` | Actions `accent`; feedback `neutral` |
74
- | `controlSize` | `small`, `medium`, `large` | `medium` |
75
-
76
- A variant picks the treatment and a tone picks the palette. Input, Textarea, Checkbox, Switch, Slider,
77
- Radio, RadioGroup, Combobox and Tabs share `controlSize` but have no variants. Native meanings
78
- win: `Input.size` stays a character count, and a checkbox `value` stays its
79
- submitted data. Radius is a theme decision, not a prop.
80
-
81
- Button defaults to `type="button"`. `pending` blocks activation but keeps focus
82
- and the accessible name. Button's optional `pressed` state is independent of press motion.
83
- Link is always an anchor and has no fake `disabled`.
84
-
85
- ## Themes
86
-
87
- A theme is one typed `defineTheme({ id, name, tokens, components, modes })`
88
- definition. Values resolve as **component override → shared token → neutral
89
- baseline**, and never fall back through another family's override. Shared tokens reach every family; overrides stay local.
90
-
91
- The core entry ships only the neutral baseline, `defaultTheme`. Styled presets
92
- are examples at `@cognitap/radiant/examples`, and Storybook, the docs and the
93
- theme workshop all read that one copy.
94
-
95
- `ThemeScope` is a plain `div` that applies a theme to its subtree. It does not
96
- touch the document or persist anything. Without `theme` or `mode` it inherits.
97
- A named theme starts fresh from the library defaults, so a nested `default`
98
- really resets an outer theme. `mode` (`light`, `dark` or `system`) is
99
- independent of the theme, and `system` uses CSS media queries so server markup
100
- stays stable. Token names, CSS variables, scopes and presets are in
101
- [theming](theming.md).
102
-
103
- ## Hosts and targeting
104
-
105
- Root `className`, `style`, native props and `ref` always reach the documented
106
- host, never a wrapper:
107
-
108
- | Family or part | Host |
109
- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
110
- | Charts / ChartDataTable | `figure` / Table's `table` |
111
- | Carousel / CarouselViewport / CarouselIndicators | `section` / native scroll `div` / `div` |
112
- | Form / FormField / FormError | `form` / Field's host / Alert's `div` |
113
- | AppShell / AppShellHeader / AppShellMain / Sidebar | `div` / `header` / `main` / `nav` |
114
- | AppShellSkipLink / SidebarLabel / SidebarContent | Link's `a` / `span` / `div` |
115
- | AspectRatio, Toolbar, ToggleGroup, ButtonGroup, InputGroup, InputGroupAddon, Alert, Tabs, TabsList | `div` |
116
- | Resizable, ResizablePanel, CodeBlock, CodeBlockHeader, EmptyState, EmptyStateActions, TabsContent | `div` |
117
- | Toast / ToastViewport / ToastProvider | Alert's `div` / `section` / None |
118
- | ScrollArea / CodeBlockViewport | Native `div` scroll viewport / ScrollArea's `div` |
119
- | CodeBlockContent / InlineCode / Kbd and KbdGroup | `pre` / `code` / `kbd` |
120
- | Avatar, Badge, Skeleton, EmptyStateIcon, TooltipContent | `span` |
121
- | Tag | Badge's `span`; its removal part styles the actual Button |
122
- | Separator / MenuSeparator and ResizableHandle | `hr` / Separator's `hr` |
123
- | Meter / Progress / Spinner | Native `meter` / `progress` / `svg` |
124
- | Table / TableContainer / other Table parts | `table` / `section` / their native table element |
125
- | Button / Link / NavLink | `button` / `a`, including through `render` |
126
- | Breadcrumb, Pagination, NavigationMenu | `nav` |
127
- | BreadcrumbList and PaginationList / NavigationMenuList / their Items | `ol` / `ul` / `li` |
128
- | BreadcrumbLink, PaginationLink, PaginationPrevious, PaginationNext, NavigationMenuLink | Link's `a` |
129
- | BreadcrumbPage, BreadcrumbSeparator, PaginationEllipsis, PaginationUnavailable | `span` |
130
- | NavigationMenuContent / NavigationMenuViewport | `div` |
131
- | Field | `div` in control layout; `fieldset` in group layout |
132
- | RadioGroup, CheckboxGroup, Fieldset | Field's `fieldset` |
133
- | Input, InputGroupInput, PasswordInput, FileInput, NumberField, OTPField, TagsInput, Checkbox, Switch, Slider, Radio | Native `input` |
134
- | Textarea, InputGroupTextarea / NativeSelect | Native `textarea` / native `select` |
135
- | Select, Combobox, Autocomplete, MultiSelect / their Portals | None; state / portal |
136
- | Popover, HoverCard, Tooltip, Menu, ContextMenu, MenuSub / their Portals | None; state / portal |
137
- | Menubar / MenubarMenu / MenubarPortal | `div` / None / None |
138
- | ContextMenuTrigger / ContextMenuContent | Named native `div` / Menu content `div` |
139
- | HoverCardTrigger / HoverCardContent | Link's `a` / Popover's `div` |
140
- | PopoverContent, MenuContent, MenuSubContent, MenuGroup, MenuLabel, MenuRadioGroup | `div` |
141
- | SelectContent, SelectViewport, SelectItem | `div` |
142
- | ComboboxInput / AutocompleteInput / CommandInput | Native `input` |
143
- | ComboboxContent / ComboboxItem / AutocompleteContent / AutocompleteItem / CommandList / CommandItem | `div` |
144
- | PopoverTrigger, PopoverClose, TooltipTrigger, SelectTrigger, TabsTrigger, ToggleGroupItem, SidebarTrigger | Button's `button` |
145
- | MenuTrigger, MenubarTrigger, MenuItem, MenuCheckboxItem, MenuRadioItem, MenuSubTrigger | Button's `button` |
146
- | ComboboxTrigger, ComboboxClear, AutocompleteTrigger, AutocompleteClear, NavigationMenuTrigger | Button's `button` |
147
- | Carousel controls, PaginationButton, CodeBlockCopy, ToastAction, ToastClose | Button's `button` |
148
- | Dialog, AlertDialog, Drawer and Command actions | Button's `button` |
149
- | Dialog / AlertDialog / Drawer / Command | None; state owners |
150
- | Dialog, AlertDialog, Drawer and Command Content / Title / Description | `dialog` / `h2` / `p` |
151
- | Collapsible / NavLinkGroup | `details` |
152
- | CollapsibleTrigger / NavLinkGroupTrigger | `summary` |
153
- | CollapsibleContent / NavLinkGroupContent | `div` |
154
- | Accordion / AccordionItem / AccordionTrigger / AccordionContent | `div` / `details` / `summary` / `div` |
155
- | Card / CardHeader / CardContent / CardFooter | `div` |
156
- | CardTitle, AlertTitle, ToastTitle, EmptyStateTitle | Heading chosen by `level` |
157
- | CardDescription, AlertDescription, ToastDescription, EmptyStateDescription | `p` |
158
-
159
- MultiSelect parts keep Combobox hosts and add `multi-select-*` identities. TagsInput
160
- styles its wrapper, tags, removal buttons and error message through `parts`.
161
-
162
- Internal parts take `className` and `style` through a `parts` map. Field has
163
- `label`, `description`, `error` and `required`. Checkbox, Switch and Radio have
164
- `wrapper`, `label` and `indicator`, and RadioGroup and CheckboxGroup add `options`. These hooks
165
- cannot replace IDs, ARIA, handlers or refs. Caller classes merge after the
166
- defaults and caller `style` wins. Identity and presentation data attributes
167
- 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.
168
27
 
169
- `data-slot` is a space-separated set, so select with `[data-slot~="button"]`.
170
- Hosts keep their base identity first, then caller tokens:
171
- `button dialog-trigger`, `field radio-group`, `collapsible accordion-item`.
172
- 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`.
173
29
 
174
- Style real state: native `:disabled`, `:checked` and `open`, plus `aria-busy`
175
- for pending. Field and RadioGroup set `data-invalid`, `data-disabled` and
176
- `data-required`. Disclosures, triggers and DialogContent set `data-state="open|closed"`.
177
- Actions set `data-variant`, `data-tone` and `data-control-size`. Switch uses
178
- `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.
179
31
 
180
- ## State and forms
32
+ ## Hosts, parts, and styling
181
33
 
182
- Each state axis has one owner for the life of a mount. Pass `value`, `checked`
183
- or `open` to control it, or `default*` to set an initial value. Passing both, or switching owner during
184
- a mount, throws; remount with a new `key` instead. A controlled callback is a request, and the consumer
185
- 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.
186
39
 
187
- | Family | State | Callback | Empty |
188
- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------ | ---------------------- |
189
- | Input, Textarea, NativeSelect, PasswordInput, OTPField | `value` / `defaultValue` | Native `onChange`, `onBlur` | `''` |
190
- | Checkbox, Switch, standalone Radio | `checked` / `defaultChecked` | Native `onChange`, `onBlur` | `false` |
191
- | Slider | `value` / `defaultValue` | `onValueChange(number)` or native `onChange`, `onBlur` | Native midpoint |
192
- | RadioGroup | `value` / `defaultValue` | `onValueChange(string)` or native `onChange` | `null` |
193
- | NumberField | `value` / `defaultValue` | `onValueChange(number \| null)` | `null` |
194
- | Select, MenuRadioGroup; Combobox, ToggleGroup and Accordion single | `value` / `defaultValue` | `onValueChange(string \| null)` | `null` |
195
- | Menubar and NavigationMenu open item | `value` / `defaultValue` | `onValueChange(string \| null)` | `null` |
196
- | MultiSelect, Combobox, ToggleGroup and Accordion multiple, CheckboxGroup, TagsInput | `value` / `defaultValue` | `onValueChange(string[])` | `[]` |
197
- | Autocomplete text | `value` / `defaultValue` | `onValueChange(string)` | `''` |
198
- | Carousel current slide | `value` / `defaultValue` | `onValueChange(string \| null)` | First item |
199
- | Tabs | `value` / `defaultValue` | `onValueChange(string)` | Initial value required |
200
- | Resizable panel sizes | `value` / `defaultValue` | `onValueChange(number[])` | Initial value required |
201
- | Combobox, MultiSelect, Command search | `query` / `defaultQuery` | `onQueryChange(string)` | `''` |
202
- | Button toggle | `pressed` / `defaultPressed` | `onPressedChange(boolean)` | `false` |
203
- | MenuCheckboxItem | `checked` / `defaultChecked` | `onCheckedChange(boolean)` | `false` |
204
- | Dialog, AlertDialog, Drawer, Command, Collapsible, Toast, Tooltip | `open` / `defaultOpen` | `onOpenChange(boolean)` | `false` |
205
- | Popover, HoverCard, Menu, ContextMenu, Select, Combobox, Autocomplete, MultiSelect | `open` / `defaultOpen` | `onOpenChange(boolean)` | `false` |
206
- | AppShell | `collapsed` / `defaultCollapsed`; mobile `open` / `defaultOpen` | `onCollapsedChange(boolean)`; `onOpenChange(boolean)` | `false` |
207
- | Drawer | `snapPoint` / `defaultSnapPoint` | `onSnapPointChange(number)` | Largest snap point |
208
- | Form | `errors` / `defaultErrors` | `onErrorsChange(FormErrors)` | `{}` |
40
+ ## State
209
41
 
210
- RadioGroup owns its options' `name`, generating one when none is given, and selection. Use one of `onValueChange`
211
- or `onChange` to write state, not both. `''` is a valid option value, and `null`
212
- 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.
213
43
 
214
- Field owns IDs and label, help and error relationships. Set a control's ID with
215
- Field's `controlId`. Radiant controls read Field context. A native control uses
216
- `children(controlProps)` and forwards those props. Disabled and required only
217
- add up: a child cannot re-enable or un-require what its Field set.
44
+ `onXChange(next)` receives the next value only.
218
45
 
219
- The consumer owns validation, touched and dirty state, error text, submission
220
- and persistence. Native reset restores uncontrolled inputs. A controlled adapter
221
- resets its own values. Reset never changes pressed buttons, ToggleGroup, Dialog, Tabs or disclosure state. TanStack Form is an optional example adapter.
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>`.
222
48
 
223
- Select takes one `items` registry for SSR labels, native options and typeahead.
224
- Rich labels supply `textValue`. The focused option and committed value are
225
- distinct; activation commits, Escape dismisses and restores trigger focus.
226
- Native reset silently restores uncontrolled selection. Controlled resets stay
227
- with the owner. User selections emit form change; prop syncs do not.
49
+ ## Events
228
50
 
229
- Carousel uses native scroll snap and Button controls; opt-in autoplay pauses for interaction, visibility and reduced motion.
230
- Form coordinates native validation and asynchronous submission without storing values. FormField composes Field; FormError composes Alert.
231
- A nameless validating control names its FormField with `data-form-name`.
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.
232
52
 
233
- ## Replacement and events
53
+ ## Forms
234
54
 
235
- Button, Link and the Dialog actions accept `render(resolvedProps)`. Forward all
236
- props, the ref and the children to one compatible `button` or `a`. There is no
237
- `as` or `asChild`. Forwarding keeps the contract intact. Field's `children(controlProps)` adapts relationships and does not
238
- 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)`.
239
56
 
240
- For cancellable actions, disabled and pending guards run first, then the
241
- consumer handler, then the state request if `defaultPrevented` is false. Native
242
- change, toggle and blur are observations and cannot veto anything. Library and
243
- caller refs get the same host, and callback-ref cleanup functions are honored.
244
- Exported hooks read and request their owner's state and return `null` outside it:
245
- `useAccordion`, `useAlertDialog`, `useAppShell` (alias `useSidebar`), `useCarousel`,
246
- `useCollapsible`, `useCombobox`, `useContextMenu`, `useDialog`, `useDrawer`, `useField`,
247
- `useForm`, `useHoverCard`, `useMenu`, `useMenubar`, `useMultiSelect`, `useNavigationMenu`,
248
- `usePopover`, `useResizable`, `useSelect`, `useTabs`, `useToast`, `useToggleGroup` and `useTooltip`. Parts that need a root throw when misplaced. Lifecycle,
249
- SSR and hydration details are in [React bindings](react-bindings.md).
57
+ Custom controls submit through a native form element:
250
58
 
251
- ## 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 |
252
67
 
253
- 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.
254
69
 
255
- - Native controls and labels stay operable, with names and descriptions connected.
256
- - Focus, invalid, disabled and pending cues stay visible.
257
- - Closed dialog and details content stays hidden. Dialog keeps its bounds,
258
- scrolling and modal focus, and `details` keeps a direct-child `summary`.
259
- - Decorative indicators stay hidden from assistive technology.
260
- - Reduced-motion and forced-colors modes still work.
70
+ ## Customization limits
261
71
 
262
- 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.
263
73
 
264
- ## Examples and type fixtures
74
+ Custom styling and rendering must keep:
265
75
 
266
- The canonical live examples are Storybook stories:
267
- [Input](../src/components/Input/Input.stories.tsx), [Form](../src/components/Form/Form.stories.tsx)
268
- (native validation, server recovery and optional TanStack values) and
269
- [Recipes → Workspace → Settings](../src/recipes/Workspace.stories.tsx) (all ten
270
- 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.
271
79
 
272
- `docs/contracts/*.ts(x)` are compile-only fixtures. `pnpm typecheck:contracts`
273
- checks that they type-check and that contradictory props, such as `value` with
274
- `defaultValue`, are rejected.
80
+ When a contract changes, update the component's stories and the compile checks in [tests/package](../tests/package).