@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.
- package/CHANGELOG.md +11 -0
- package/README.md +6 -3
- package/RELEASE_POLICY.md +8 -19
- package/dist/library/charts/Charts.js +1 -1
- package/dist/library/charts/Charts.js.map +1 -1
- package/dist/library/components/Accordion/Accordion.js +1 -1
- package/dist/library/components/Accordion/Accordion.js.map +1 -1
- package/dist/library/components/Alert/Alert.js +1 -1
- package/dist/library/components/Alert/Alert.js.map +1 -1
- package/dist/library/components/AppShell/AppShell.js +1 -1
- package/dist/library/components/AppShell/AppShell.js.map +1 -1
- package/dist/library/components/AspectRatio/AspectRatio.js +1 -1
- package/dist/library/components/AspectRatio/AspectRatio.js.map +1 -1
- package/dist/library/components/Avatar/Avatar.js +1 -1
- package/dist/library/components/Avatar/Avatar.js.map +1 -1
- package/dist/library/components/Badge/Badge.js +1 -1
- package/dist/library/components/Badge/Badge.js.map +1 -1
- package/dist/library/components/Breadcrumb/Breadcrumb.js +1 -1
- package/dist/library/components/Breadcrumb/Breadcrumb.js.map +1 -1
- package/dist/library/components/Button/Button.js +1 -1
- package/dist/library/components/Button/Button.js.map +1 -1
- package/dist/library/components/ButtonGroup/ButtonGroup.js +1 -1
- package/dist/library/components/ButtonGroup/ButtonGroup.js.map +1 -1
- package/dist/library/components/Card/Card.js +1 -1
- package/dist/library/components/Card/Card.js.map +1 -1
- package/dist/library/components/Carousel/Carousel.js +6 -6
- package/dist/library/components/Carousel/Carousel.js.map +1 -1
- package/dist/library/components/Checkbox/Checkbox.js +1 -1
- package/dist/library/components/Checkbox/Checkbox.js.map +1 -1
- package/dist/library/components/CheckboxGroup/CheckboxGroup.js +1 -1
- package/dist/library/components/CheckboxGroup/CheckboxGroup.js.map +1 -1
- package/dist/library/components/CodeBlock/CodeBlock.js +1 -1
- package/dist/library/components/CodeBlock/CodeBlock.js.map +1 -1
- package/dist/library/components/Collapsible/Collapsible.js +1 -1
- package/dist/library/components/Collapsible/Collapsible.js.map +1 -1
- package/dist/library/components/Combobox/Combobox.js +1 -1
- package/dist/library/components/Combobox/Combobox.js.map +1 -1
- package/dist/library/components/Command/Command.js +1 -1
- package/dist/library/components/Command/Command.js.map +1 -1
- package/dist/library/components/ContextMenu/ContextMenu.js +1 -1
- package/dist/library/components/ContextMenu/ContextMenu.js.map +1 -1
- package/dist/library/components/Dialog/Dialog.js +1 -1
- package/dist/library/components/Dialog/Dialog.js.map +1 -1
- package/dist/library/components/Drawer/Drawer.js +1 -1
- package/dist/library/components/Drawer/Drawer.js.map +1 -1
- package/dist/library/components/EmptyState/EmptyState.js +1 -1
- package/dist/library/components/EmptyState/EmptyState.js.map +1 -1
- package/dist/library/components/Field/Field.js +1 -1
- package/dist/library/components/Field/Field.js.map +1 -1
- package/dist/library/components/Fieldset/Fieldset.js +1 -1
- package/dist/library/components/Fieldset/Fieldset.js.map +1 -1
- package/dist/library/components/FileInput/FileInput.js +1 -1
- package/dist/library/components/FileInput/FileInput.js.map +1 -1
- package/dist/library/components/Form/Form.js +4 -4
- package/dist/library/components/Form/Form.js.map +1 -1
- package/dist/library/components/HoverCard/HoverCard.js +1 -1
- package/dist/library/components/HoverCard/HoverCard.js.map +1 -1
- package/dist/library/components/InlineCode/InlineCode.js +1 -1
- package/dist/library/components/InlineCode/InlineCode.js.map +1 -1
- package/dist/library/components/Input/Input.js +1 -1
- package/dist/library/components/Input/Input.js.map +1 -1
- package/dist/library/components/InputGroup/InputGroup.js +1 -1
- package/dist/library/components/InputGroup/InputGroup.js.map +1 -1
- package/dist/library/components/Kbd/Kbd.js +1 -1
- package/dist/library/components/Kbd/Kbd.js.map +1 -1
- package/dist/library/components/Link/Link.js +1 -1
- package/dist/library/components/Link/Link.js.map +1 -1
- package/dist/library/components/Menu/Menu.js +1 -1
- package/dist/library/components/Menu/Menu.js.map +1 -1
- package/dist/library/components/Menubar/Menubar.js +1 -1
- package/dist/library/components/Menubar/Menubar.js.map +1 -1
- package/dist/library/components/Meter/Meter.js +1 -1
- package/dist/library/components/Meter/Meter.js.map +1 -1
- package/dist/library/components/NativeSelect/NativeSelect.js +1 -1
- package/dist/library/components/NativeSelect/NativeSelect.js.map +1 -1
- package/dist/library/components/NavLink/NavLink.js +1 -1
- package/dist/library/components/NavLink/NavLink.js.map +1 -1
- package/dist/library/components/NavigationMenu/NavigationMenu.js +1 -1
- package/dist/library/components/NavigationMenu/NavigationMenu.js.map +1 -1
- package/dist/library/components/NumberField/NumberField.js +1 -1
- package/dist/library/components/NumberField/NumberField.js.map +1 -1
- package/dist/library/components/OTPField/OTPField.js +1 -1
- package/dist/library/components/OTPField/OTPField.js.map +1 -1
- package/dist/library/components/Pagination/Pagination.js +1 -1
- package/dist/library/components/Pagination/Pagination.js.map +1 -1
- package/dist/library/components/PasswordInput/PasswordInput.js +1 -1
- package/dist/library/components/PasswordInput/PasswordInput.js.map +1 -1
- package/dist/library/components/Popover/Popover.js +1 -1
- package/dist/library/components/Popover/Popover.js.map +1 -1
- package/dist/library/components/Progress/Progress.js +1 -1
- package/dist/library/components/Progress/Progress.js.map +1 -1
- package/dist/library/components/RadioGroup/RadioGroup.js +1 -1
- package/dist/library/components/RadioGroup/RadioGroup.js.map +1 -1
- package/dist/library/components/Resizable/Resizable.js +1 -1
- package/dist/library/components/Resizable/Resizable.js.map +1 -1
- package/dist/library/components/ScrollArea/ScrollArea.js +1 -1
- package/dist/library/components/ScrollArea/ScrollArea.js.map +1 -1
- package/dist/library/components/Select/Select.js +1 -1
- package/dist/library/components/Select/Select.js.map +1 -1
- package/dist/library/components/Separator/Separator.js +1 -1
- package/dist/library/components/Separator/Separator.js.map +1 -1
- package/dist/library/components/Skeleton/Skeleton.js +1 -1
- package/dist/library/components/Skeleton/Skeleton.js.map +1 -1
- package/dist/library/components/Slider/Slider.js +1 -1
- package/dist/library/components/Slider/Slider.js.map +1 -1
- package/dist/library/components/Spinner/Spinner.js +1 -1
- package/dist/library/components/Spinner/Spinner.js.map +1 -1
- package/dist/library/components/Switch/Switch.js +1 -1
- package/dist/library/components/Switch/Switch.js.map +1 -1
- package/dist/library/components/Table/Table.js +1 -1
- package/dist/library/components/Table/Table.js.map +1 -1
- package/dist/library/components/Tabs/Tabs.js +1 -1
- package/dist/library/components/Tabs/Tabs.js.map +1 -1
- package/dist/library/components/Tag/Tag.js +1 -1
- package/dist/library/components/Tag/Tag.js.map +1 -1
- package/dist/library/components/TagsInput/TagsInput.js +1 -1
- package/dist/library/components/TagsInput/TagsInput.js.map +1 -1
- package/dist/library/components/Textarea/Textarea.js +1 -1
- package/dist/library/components/Textarea/Textarea.js.map +1 -1
- package/dist/library/components/ThemeScope/ThemeScope.js +1 -1
- package/dist/library/components/ThemeScope/ThemeScope.js.map +1 -1
- package/dist/library/components/Toast/Toast.js +1 -1
- package/dist/library/components/Toast/Toast.js.map +1 -1
- package/dist/library/components/ToggleGroup/ToggleGroup.js +3 -1
- package/dist/library/components/ToggleGroup/ToggleGroup.js.map +1 -1
- package/dist/library/components/Toolbar/Toolbar.js +1 -1
- package/dist/library/components/Toolbar/Toolbar.js.map +1 -1
- package/dist/library/components/Tooltip/Tooltip.js +1 -1
- package/dist/library/components/Tooltip/Tooltip.js.map +1 -1
- package/dist/library/motion/MotionLink.js +1 -1
- package/dist/library/motion/MotionLink.js.map +1 -1
- package/dist/library/react/useComboboxPopup.d.ts.map +1 -1
- package/dist/library/react/useComboboxPopup.js +45 -6
- package/dist/library/react/useComboboxPopup.js.map +1 -1
- package/dist/library/react/useRovingFocus.d.ts.map +1 -1
- package/dist/library/react/useRovingFocus.js +76 -11
- package/dist/library/react/useRovingFocus.js.map +1 -1
- package/dist/library/react/useToastTimer.d.ts.map +1 -1
- package/dist/library/react/useToastTimer.js +28 -9
- package/dist/library/react/useToastTimer.js.map +1 -1
- package/dist/library/styles.css +1 -1
- package/docs/accessibility.md +23 -111
- package/docs/architecture.md +48 -242
- package/docs/motion.md +65 -130
- package/docs/theming.md +51 -427
- package/package.json +21 -13
- package/src/charts/Charts.tsx +1 -1
- package/src/components/Accordion/Accordion.tsx +1 -1
- package/src/components/Alert/Alert.tsx +1 -1
- package/src/components/AppShell/AppShell.tsx +1 -1
- package/src/components/AspectRatio/AspectRatio.tsx +1 -1
- package/src/components/Avatar/Avatar.tsx +1 -1
- package/src/components/Badge/Badge.tsx +1 -1
- package/src/components/Breadcrumb/Breadcrumb.tsx +1 -1
- package/src/components/Button/Button.tsx +1 -1
- package/src/components/ButtonGroup/ButtonGroup.tsx +1 -1
- package/src/components/Card/Card.tsx +1 -1
- package/src/components/Carousel/Carousel.tsx +6 -6
- package/src/components/Checkbox/Checkbox.tsx +1 -1
- package/src/components/CheckboxGroup/CheckboxGroup.tsx +1 -1
- package/src/components/CodeBlock/CodeBlock.tsx +1 -1
- package/src/components/Collapsible/Collapsible.tsx +1 -1
- package/src/components/Combobox/Combobox.tsx +1 -1
- package/src/components/Command/Command.tsx +1 -1
- package/src/components/ContextMenu/ContextMenu.tsx +1 -1
- package/src/components/Dialog/Dialog.tsx +1 -1
- package/src/components/Drawer/Drawer.tsx +1 -1
- package/src/components/EmptyState/EmptyState.tsx +1 -1
- package/src/components/Field/Field.tsx +1 -1
- package/src/components/Fieldset/Fieldset.tsx +1 -1
- package/src/components/FileInput/FileInput.tsx +1 -1
- package/src/components/Form/Form.tsx +4 -4
- package/src/components/HoverCard/HoverCard.tsx +1 -1
- package/src/components/InlineCode/InlineCode.tsx +1 -1
- package/src/components/Input/Input.tsx +1 -1
- package/src/components/InputGroup/InputGroup.tsx +1 -1
- package/src/components/Kbd/Kbd.tsx +1 -1
- package/src/components/Link/Link.tsx +1 -1
- package/src/components/Menu/Menu.tsx +1 -1
- package/src/components/Menubar/Menubar.tsx +1 -1
- package/src/components/Meter/Meter.tsx +1 -1
- package/src/components/NativeSelect/NativeSelect.tsx +1 -1
- package/src/components/NavLink/NavLink.tsx +1 -1
- package/src/components/NavigationMenu/NavigationMenu.tsx +1 -1
- package/src/components/NumberField/NumberField.tsx +1 -1
- package/src/components/OTPField/OTPField.tsx +1 -1
- package/src/components/Pagination/Pagination.tsx +1 -1
- package/src/components/PasswordInput/PasswordInput.tsx +1 -1
- package/src/components/Popover/Popover.tsx +1 -1
- package/src/components/Progress/Progress.tsx +1 -1
- package/src/components/RadioGroup/RadioGroup.tsx +1 -1
- package/src/components/Resizable/Resizable.tsx +1 -1
- package/src/components/ScrollArea/ScrollArea.tsx +1 -1
- package/src/components/Select/Select.tsx +1 -1
- package/src/components/Separator/Separator.tsx +1 -1
- package/src/components/Skeleton/Skeleton.tsx +1 -1
- package/src/components/Slider/Slider.tsx +1 -1
- package/src/components/Spinner/Spinner.tsx +1 -1
- package/src/components/Switch/Switch.tsx +1 -1
- package/src/components/Table/Table.tsx +1 -1
- package/src/components/Tabs/Tabs.tsx +1 -1
- package/src/components/Tag/Tag.tsx +1 -1
- package/src/components/TagsInput/TagsInput.tsx +1 -1
- package/src/components/Textarea/Textarea.tsx +1 -1
- package/src/components/ThemeScope/ThemeScope.tsx +1 -1
- package/src/components/Toast/Toast.tsx +1 -1
- package/src/components/ToggleGroup/ToggleGroup.tsx +3 -1
- package/src/components/Toolbar/Toolbar.tsx +1 -1
- package/src/components/Tooltip/Tooltip.tsx +1 -1
- package/src/css.d.ts +2 -0
- package/src/motion/MotionLink.tsx +1 -1
- package/src/react/useComboboxPopup.ts +38 -6
- package/src/react/useRovingFocus.ts +73 -8
- package/src/react/useToastTimer.ts +24 -9
- package/src/styles.d.ts +1 -0
- package/src/themes/baseline.css +1 -1
- package/src/typography.css +17 -12
- package/dist/library/cn.d.ts +0 -3
- package/dist/library/cn.d.ts.map +0 -1
- package/dist/library/cn.js +0 -370
- package/dist/library/cn.js.map +0 -1
- package/src/cn.ts +0 -372
package/docs/accessibility.md
CHANGED
|
@@ -1,123 +1,35 @@
|
|
|
1
1
|
# Accessibility
|
|
2
2
|
|
|
3
|
-
What to check by hand,
|
|
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
|
-
##
|
|
5
|
+
## Automated checks
|
|
10
6
|
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
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
|
-
|
|
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
|
-
##
|
|
14
|
+
## Manual targets
|
|
26
15
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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
|
-
##
|
|
23
|
+
## Manual checks
|
|
40
24
|
|
|
41
|
-
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
package/docs/architecture.md
CHANGED
|
@@ -1,274 +1,80 @@
|
|
|
1
1
|
# Architecture
|
|
2
2
|
|
|
3
|
-
Radiant
|
|
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
|
-
|
|
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
|
-
##
|
|
7
|
+
## Package entries
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
- `@cognitap/radiant`: components
|
|
10
|
+
- `@cognitap/radiant/charts`: charts
|
|
11
|
+
- `@cognitap/radiant/examples`: theme presets
|
|
12
12
|
|
|
13
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
-
##
|
|
32
|
+
## Hosts, parts, and styling
|
|
181
33
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
220
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
53
|
+
## Forms
|
|
234
54
|
|
|
235
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
74
|
+
Custom styling and rendering must keep:
|
|
265
75
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
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
|
-
|
|
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).
|