@cognitap/radiant 0.0.6 → 0.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +68 -385
- package/README.md +41 -1014
- package/RELEASE_POLICY.md +3 -3
- package/dist/library/Accordion.d.ts +3 -0
- package/dist/library/Accordion.d.ts.map +1 -1
- package/dist/library/Accordion.js +1 -1
- package/dist/library/Accordion.js.map +1 -1
- package/dist/library/Button.d.ts +5 -0
- package/dist/library/Button.d.ts.map +1 -1
- package/dist/library/Button.js +8 -7
- package/dist/library/Button.js.map +1 -1
- package/dist/library/Card.d.ts +2 -0
- package/dist/library/Card.d.ts.map +1 -1
- package/dist/library/Card.js +1 -1
- package/dist/library/Card.js.map +1 -1
- package/dist/library/Checkbox.d.ts +5 -0
- package/dist/library/Checkbox.d.ts.map +1 -1
- package/dist/library/Checkbox.js +3 -2
- package/dist/library/Checkbox.js.map +1 -1
- package/dist/library/Collapsible.d.ts +4 -0
- package/dist/library/Collapsible.d.ts.map +1 -1
- package/dist/library/Collapsible.js +22 -4
- package/dist/library/Collapsible.js.map +1 -1
- package/dist/library/Dialog.d.ts +3 -0
- package/dist/library/Dialog.d.ts.map +1 -1
- package/dist/library/Dialog.js.map +1 -1
- package/dist/library/Field.d.ts +8 -0
- package/dist/library/Field.d.ts.map +1 -1
- package/dist/library/Field.js +2 -0
- package/dist/library/Field.js.map +1 -1
- package/dist/library/Input.d.ts +3 -0
- package/dist/library/Input.d.ts.map +1 -1
- package/dist/library/Input.js +1 -0
- package/dist/library/Input.js.map +1 -1
- package/dist/library/Link.d.ts +5 -0
- package/dist/library/Link.d.ts.map +1 -1
- package/dist/library/Link.js.map +1 -1
- package/dist/library/RadioGroup.d.ts +8 -0
- package/dist/library/RadioGroup.d.ts.map +1 -1
- package/dist/library/RadioGroup.js +4 -2
- package/dist/library/RadioGroup.js.map +1 -1
- package/dist/library/examples/expressive.d.ts +4 -0
- package/dist/library/examples/expressive.d.ts.map +1 -0
- package/dist/library/{themes → examples}/expressive.js +4 -3
- package/dist/library/examples/expressive.js.map +1 -0
- package/dist/library/examples/glass.d.ts +4 -0
- package/dist/library/examples/glass.d.ts.map +1 -0
- package/dist/library/{themes → examples}/glass.js +4 -3
- package/dist/library/examples/glass.js.map +1 -0
- package/dist/library/examples/index.d.ts +13 -0
- package/dist/library/examples/index.d.ts.map +1 -0
- package/dist/library/examples/index.js +32 -0
- package/dist/library/examples/index.js.map +1 -0
- package/dist/library/examples/jelly.d.ts +4 -0
- package/dist/library/examples/jelly.d.ts.map +1 -0
- package/dist/library/{themes → examples}/jelly.js +4 -3
- package/dist/library/examples/jelly.js.map +1 -0
- package/dist/library/examples/preset-values.d.ts.map +1 -0
- package/dist/library/examples/preset-values.js.map +1 -0
- package/dist/library/examples/radiant.d.ts +4 -0
- package/dist/library/examples/radiant.d.ts.map +1 -0
- package/dist/library/{themes → examples}/radiant.js +4 -3
- package/dist/library/examples/radiant.js.map +1 -0
- package/dist/library/examples/sharp-3d.d.ts +4 -0
- package/dist/library/examples/sharp-3d.d.ts.map +1 -0
- package/dist/library/{themes → examples}/sharp-3d.js +4 -3
- package/dist/library/examples/sharp-3d.js.map +1 -0
- package/dist/library/examples/soft-squircle.d.ts +4 -0
- package/dist/library/examples/soft-squircle.d.ts.map +1 -0
- package/dist/library/{themes → examples}/soft-squircle.js +4 -3
- package/dist/library/examples/soft-squircle.js.map +1 -0
- package/dist/library/examples/ticket.d.ts +4 -0
- package/dist/library/examples/ticket.d.ts.map +1 -0
- package/dist/library/{themes → examples}/ticket.js +4 -3
- package/dist/library/examples/ticket.js.map +1 -0
- package/dist/library/index.d.ts +1 -1
- package/dist/library/index.d.ts.map +1 -1
- package/dist/library/index.js +1 -1
- package/dist/library/index.js.map +1 -1
- package/dist/library/motion/MotionLink.d.ts +1 -0
- package/dist/library/motion/MotionLink.d.ts.map +1 -1
- package/dist/library/motion/MotionLink.js +9 -10
- package/dist/library/motion/MotionLink.js.map +1 -1
- package/dist/library/motion/host.d.ts +5 -2
- package/dist/library/motion/host.d.ts.map +1 -1
- package/dist/library/motion/host.js +13 -5
- package/dist/library/motion/host.js.map +1 -1
- package/dist/library/motion/press.d.ts.map +1 -1
- package/dist/library/motion/press.js +41 -14
- package/dist/library/motion/press.js.map +1 -1
- package/dist/library/motion/pressPolicy.d.ts.map +1 -1
- package/dist/library/motion/pressPolicy.js +2 -2
- package/dist/library/motion/pressPolicy.js.map +1 -1
- package/dist/library/motion/transitions.d.ts.map +1 -1
- package/dist/library/motion/transitions.js +48 -15
- package/dist/library/motion/transitions.js.map +1 -1
- package/dist/library/styles.css +1 -1
- package/dist/library/themes/index.d.ts +1 -11
- package/dist/library/themes/index.d.ts.map +1 -1
- package/dist/library/themes/index.js +1 -19
- package/dist/library/themes/index.js.map +1 -1
- package/docs/accessibility.md +76 -142
- package/docs/architecture.md +197 -0
- package/docs/motion.md +115 -396
- package/docs/theming.md +275 -882
- package/package.json +9 -5
- package/src/Accordion.tsx +4 -1
- package/src/Button.tsx +13 -7
- package/src/Card.tsx +3 -1
- package/src/Checkbox.tsx +7 -2
- package/src/Collapsible.tsx +28 -4
- package/src/Dialog.tsx +3 -0
- package/src/Field.tsx +8 -0
- package/src/Input.tsx +3 -0
- package/src/Link.tsx +5 -0
- package/src/RadioGroup.tsx +10 -2
- package/src/{themes → examples}/expressive.ts +5 -3
- package/src/{themes → examples}/glass.ts +5 -3
- package/src/examples/index.ts +35 -0
- package/src/{themes → examples}/jelly.ts +5 -3
- package/src/{themes → examples}/radiant.ts +5 -3
- package/src/{themes → examples}/sharp-3d.ts +5 -3
- package/src/{themes → examples}/soft-squircle.ts +5 -3
- package/src/{themes → examples}/ticket.ts +5 -3
- package/src/index.ts +1 -13
- package/src/motion/MotionLink.tsx +16 -11
- package/src/motion/host.ts +14 -6
- package/src/motion/press.ts +32 -12
- package/src/motion/pressPolicy.ts +4 -2
- package/src/motion/transitions.ts +45 -14
- package/src/themes/index.ts +1 -22
- package/dist/library/themes/expressive.d.ts +0 -2
- package/dist/library/themes/expressive.d.ts.map +0 -1
- package/dist/library/themes/expressive.js.map +0 -1
- package/dist/library/themes/glass.d.ts +0 -2
- package/dist/library/themes/glass.d.ts.map +0 -1
- package/dist/library/themes/glass.js.map +0 -1
- package/dist/library/themes/jelly.d.ts +0 -2
- package/dist/library/themes/jelly.d.ts.map +0 -1
- package/dist/library/themes/jelly.js.map +0 -1
- package/dist/library/themes/preset-values.d.ts.map +0 -1
- package/dist/library/themes/preset-values.js.map +0 -1
- package/dist/library/themes/radiant.d.ts +0 -2
- package/dist/library/themes/radiant.d.ts.map +0 -1
- package/dist/library/themes/radiant.js.map +0 -1
- package/dist/library/themes/sharp-3d.d.ts +0 -2
- package/dist/library/themes/sharp-3d.d.ts.map +0 -1
- package/dist/library/themes/sharp-3d.js.map +0 -1
- package/dist/library/themes/soft-squircle.d.ts +0 -2
- package/dist/library/themes/soft-squircle.d.ts.map +0 -1
- package/dist/library/themes/soft-squircle.js.map +0 -1
- package/dist/library/themes/ticket.d.ts +0 -2
- package/dist/library/themes/ticket.d.ts.map +0 -1
- package/dist/library/themes/ticket.js.map +0 -1
- package/docs/system.md +0 -264
- /package/dist/library/{themes → examples}/preset-values.d.ts +0 -0
- /package/dist/library/{themes → examples}/preset-values.js +0 -0
- /package/src/{themes → examples}/preset-values.ts +0 -0
package/docs/accessibility.md
CHANGED
|
@@ -1,73 +1,45 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
revision, working-tree changes, CSS route (compiled or Tailwind), optional
|
|
44
|
-
reset, custom overrides and font loading. Installed-consumer evidence must
|
|
45
|
-
also identify its package version/archive integrity and fixture revision.
|
|
46
|
-
2. Open the [canonical stories and assembled recipes](system.md#reuse-the-canonical-examples).
|
|
47
|
-
Inspect native and TanStack form owners, standalone/Card/Dialog placement,
|
|
48
|
-
and both default and replacement action paths. Use default Radiant parts in
|
|
49
|
-
the ordinary path so an adapter cannot hide a broken composition.
|
|
50
|
-
3. Use the global Theme/Mode selectors. Disable autoplay for manual interactions
|
|
51
|
-
with `embed=true`; wait for the story scope, fonts and mode to settle. Check
|
|
52
|
-
Canvas and Docs when changing preview integration. See
|
|
53
|
-
[Storybook inspection](https://github.com/cognitap/radiant/blob/main/docs/storybook.md#verification).
|
|
54
|
-
4. Record each tested preset/mode rather than writing "all themes" from a sample.
|
|
55
|
-
The visual target is every preset in explicit light/dark, relevant states,
|
|
56
|
-
and System preference switching. For each claimed browser/AT combination,
|
|
57
|
-
execute the applicable scenarios below; record sampled combinations and leave
|
|
58
|
-
the rest unverified. Recheck a defect's affected combinations after its fix.
|
|
59
|
-
5. Capture OS/browser/AT versions and settings before acting. Include locale,
|
|
60
|
-
browser zoom, viewport, orientation, OS text/display scaling, keyboard access
|
|
61
|
-
and screen-reader mode/verbosity/gesture customisations. Record OS reduced
|
|
62
|
-
motion/contrast settings separately from browser emulation.
|
|
63
|
-
|
|
64
|
-
## Manual scenarios
|
|
65
|
-
|
|
66
|
-
Run desktop keyboard cases with the screen reader off, then with it on.
|
|
67
|
-
Observe browser focus and the screen reader's reading cursor separately.
|
|
68
|
-
Record conveyed names/roles/states and actual announcements; exact speech wording
|
|
69
|
-
can vary by settings. The platform instructions below are operating guidance,
|
|
70
|
-
not results for Radiant.
|
|
1
|
+
# Accessibility
|
|
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.
|
|
8
|
+
|
|
9
|
+
## Targets
|
|
10
|
+
|
|
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** |
|
|
20
|
+
|
|
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.
|
|
24
|
+
|
|
25
|
+
## Prepare a run
|
|
26
|
+
|
|
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.
|
|
38
|
+
|
|
39
|
+
## Scenarios
|
|
40
|
+
|
|
41
|
+
Run keyboard cases with the screen reader off, then on. Record what is conveyed
|
|
42
|
+
(names, roles, states), not exact wording.
|
|
71
43
|
|
|
72
44
|
| ID | Action and expected observation |
|
|
73
45
|
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -81,14 +53,12 @@ not results for Radiant.
|
|
|
81
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. |
|
|
82
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. |
|
|
83
55
|
|
|
84
|
-
Native radio
|
|
85
|
-
|
|
86
|
-
model. [APG
|
|
87
|
-
|
|
88
|
-
for content-dependent initial focus and restoration. APG is informative guidance;
|
|
89
|
-
its examples do not certify a library's browser/AT compatibility.
|
|
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.
|
|
90
60
|
|
|
91
|
-
###
|
|
61
|
+
### Screen reader pairs
|
|
92
62
|
|
|
93
63
|
| Pair | Procedure and primary reference |
|
|
94
64
|
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -97,11 +67,9 @@ its examples do not certify a library's browser/AT compatibility.
|
|
|
97
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). |
|
|
98
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). |
|
|
99
69
|
|
|
100
|
-
## WCAG
|
|
70
|
+
## WCAG criteria
|
|
101
71
|
|
|
102
|
-
These are
|
|
103
|
-
records applicability and an observed outcome for the criteria it covers. Follow
|
|
104
|
-
the linked definitions/exception rules; the list is not a complete product audit.
|
|
72
|
+
These are the criteria to assess for each scenario, not passed results.
|
|
105
73
|
|
|
106
74
|
| Scenario / requirement area | Relevant A/AA criteria and evidence |
|
|
107
75
|
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -113,50 +81,23 @@ the linked definitions/exception rules; the list is not a complete product audit
|
|
|
113
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. |
|
|
114
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. |
|
|
115
83
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- **Focus:** 2.4.7 and 2.4.11 are AA.
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
letter spacing 0.12×font size and word spacing 0.16×font size together, with
|
|
134
|
-
applicable language/script exceptions. These are resilience tests, not required
|
|
135
|
-
default typography settings.
|
|
136
|
-
- **Preferences:** forced-colors and reduced-motion checks are part of Radiant's
|
|
137
|
-
functional CSS target. An emulated preference or a `motion-reduce` class proves
|
|
138
|
-
neither an OS/AT result nor complete WCAG conformance.
|
|
139
|
-
|
|
140
|
-
## Record and retain evidence
|
|
141
|
-
|
|
142
|
-
`pnpm test:browser` first writes `output/browser/environment.json` from the
|
|
143
|
-
installed Chromium and host OS, then runs the existing tests. Preflight clears
|
|
144
|
-
prior environment/JUnit files first so an interrupted run cannot reuse an old
|
|
145
|
-
pass. Preserve an old run before starting the next. The receipt contains
|
|
146
|
-
exact browser/Node/Playwright/Vitest versions, OS/build details, revision, dirty
|
|
147
|
-
flag and CI run link. AT is explicitly `not-run`. It is environment metadata,
|
|
148
|
-
not a passing test result: pair it with the completed `junit.xml`, actual project/
|
|
149
|
-
case selection, logs and manual evidence. A failed or interrupted suite does not
|
|
150
|
-
inherit a prior pass from the receipt. The current command runs Chromium only.
|
|
151
|
-
|
|
152
|
-
CI uploads these files as **browser-results** with a 14-day retention period.
|
|
153
|
-
Before they expire, retain the version/result summary and relevant captures in a
|
|
154
|
-
reviewed `docs/verification/YYYY-MM-DD-<scope>.md` record or durable issue/PR
|
|
155
|
-
attachments. Link the exact CI run and commit; keep older records immutable and
|
|
156
|
-
append a new verification when code, browser/AT, OS, theme or adapter changes.
|
|
157
|
-
A preview/run of the environment recorder alone has no test-result status.
|
|
158
|
-
|
|
159
|
-
Use this structure for each actual manual or automated run:
|
|
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:
|
|
160
101
|
|
|
161
102
|
```text
|
|
162
103
|
Record ID, date/time, tester and method (manual / automated / emulated)
|
|
@@ -170,20 +111,13 @@ JUnit/log/capture/transcript links; defect issue + affected combinations
|
|
|
170
111
|
Retest revision and result; remaining untested combinations/criterion gaps
|
|
171
112
|
```
|
|
172
113
|
|
|
173
|
-
A failure gets
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
errors, appropriate initial focus, sensible navigation, validation/persistence,
|
|
184
|
-
font assets and theme/adapter choices. They must verify their rendered colors,
|
|
185
|
-
content, responsive layouts, complete tasks and any overrides/host replacements.
|
|
186
|
-
Page language/titles, consistent navigation, authentication, data-entry/error
|
|
187
|
-
prevention and other page/process criteria also need product-level applicability
|
|
188
|
-
and evidence. Neither a passing library matrix nor a paid certificate replaces
|
|
189
|
-
that evaluation. Follow the [system guide](system.md) when composing the controls.
|
|
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.
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
How Radiant's ten families fit together and why. Props are on the
|
|
4
|
+
[docs site](https://github.com/cognitap/radiant-docs); themes are in [theming](theming.md); springs are in
|
|
5
|
+
[motion](motion.md).
|
|
6
|
+
|
|
7
|
+
The families are Button, Link, Field, Input, Checkbox, RadioGroup (with Radio),
|
|
8
|
+
Dialog, Collapsible, Accordion and Card. All ship in one package,
|
|
9
|
+
`@cognitap/radiant`. Deep imports are unsupported.
|
|
10
|
+
|
|
11
|
+
## Native first
|
|
12
|
+
|
|
13
|
+
Each piece of behavior has one owner:
|
|
14
|
+
|
|
15
|
+
| Responsibility | Owner |
|
|
16
|
+
| ------------------------------------------------------ | ----------------------------------------------- |
|
|
17
|
+
| Activation, radio grouping, disclosure, modal dialog | The native element |
|
|
18
|
+
| Selection rules, ID merging and other reusable policy | Private modules in `src/internal/`, no React |
|
|
19
|
+
| Rendering, context, state hooks, event and ref wiring | React bindings in `src/react/` and family roots |
|
|
20
|
+
| Appearance | Shared tokens and component overrides |
|
|
21
|
+
| Content, validation, routing, fetching and persistence | The consumer |
|
|
22
|
+
|
|
23
|
+
Why: the browser already gets keyboard, focus and form behavior right.
|
|
24
|
+
Radiant wraps native elements and has no headless-library dependency.
|
|
25
|
+
|
|
26
|
+
Import rules:
|
|
27
|
+
|
|
28
|
+
1. `internal` never imports React, a binding, a family or app code.
|
|
29
|
+
2. `react` imports `internal` and React, never a family.
|
|
30
|
+
3. Families compose other families explicitly (Accordion uses Collapsible,
|
|
31
|
+
RadioGroup uses Field, Dialog actions use Button). The graph stays acyclic.
|
|
32
|
+
4. Nothing touches `window`, `document` or the DOM at import time. Effects use
|
|
33
|
+
the owning document and clean up on unmount.
|
|
34
|
+
5. Server markup matches the first client render. For example, a native dialog
|
|
35
|
+
opens in an effect, not during render.
|
|
36
|
+
|
|
37
|
+
Extract a shared module only when a policy really repeats.
|
|
38
|
+
|
|
39
|
+
## Composition
|
|
40
|
+
|
|
41
|
+
Use Button for actions and Link for navigation, even when a Link looks like a
|
|
42
|
+
button. Field owns label, help and error relationships. Card groups content.
|
|
43
|
+
Dialog owns open state. Collapsible owns one disclosure, and Accordion composes
|
|
44
|
+
Collapsible for a set of them.
|
|
45
|
+
|
|
46
|
+
Composed families reuse the real thing: DialogTrigger and DialogClose are
|
|
47
|
+
Buttons, RadioGroup is a Field, and an Accordion item is a Collapsible, so
|
|
48
|
+
theme, keyboard behavior and relationships travel together.
|
|
49
|
+
|
|
50
|
+
## Presentation
|
|
51
|
+
|
|
52
|
+
Actions take three independent props:
|
|
53
|
+
|
|
54
|
+
| Prop | Values | Default |
|
|
55
|
+
| ------------- | ------------------------------------------------------------------------- | ----------------------------- |
|
|
56
|
+
| `variant` | `solid`, `soft`, `outline`, `ghost`; Link also accepts `inline`, `subtle` | Button `solid`; Link `inline` |
|
|
57
|
+
| `tone` | `accent`, `neutral`, `warning`, `danger` | `accent` |
|
|
58
|
+
| `controlSize` | `small`, `medium`, `large` | `medium` |
|
|
59
|
+
|
|
60
|
+
A variant picks the treatment and a tone picks the palette. Input, Checkbox,
|
|
61
|
+
Radio and RadioGroup share `controlSize` but have no variants. Native meanings
|
|
62
|
+
win: `Input.size` stays a character count, and a checkbox `value` stays its
|
|
63
|
+
submitted data. Radius is a theme decision, not a prop.
|
|
64
|
+
|
|
65
|
+
Button defaults to `type="button"`. `pending` blocks activation but keeps focus
|
|
66
|
+
and the accessible name. Link is always an anchor and has no fake `disabled`.
|
|
67
|
+
|
|
68
|
+
## Themes
|
|
69
|
+
|
|
70
|
+
A theme is one typed `defineTheme({ id, name, tokens, components, modes })`
|
|
71
|
+
definition. Values resolve as **component override → shared token → neutral
|
|
72
|
+
baseline**, and never fall back through another family's override. Why: a
|
|
73
|
+
change to shared tokens should reach every family, and an exception should stay
|
|
74
|
+
local. A Button-only font does not become body text.
|
|
75
|
+
|
|
76
|
+
The core entry ships only the neutral baseline, `defaultTheme`. Styled presets
|
|
77
|
+
are examples at `@cognitap/radiant/examples`, and Storybook, the docs and the
|
|
78
|
+
theme workshop all read that one copy. Why: a preset is a starting point to copy
|
|
79
|
+
or edit, not a contract the library has to keep stable.
|
|
80
|
+
|
|
81
|
+
`ThemeScope` is a plain `div` that applies a theme to its subtree. It does not
|
|
82
|
+
touch the document or persist anything. Without `theme` or `mode` it inherits.
|
|
83
|
+
A named theme starts fresh from the library defaults, so a nested `default`
|
|
84
|
+
really resets an outer theme. `mode` (`light`, `dark` or `system`) is
|
|
85
|
+
independent of the theme, and `system` uses CSS media queries so server markup
|
|
86
|
+
stays stable. Token names, CSS variables, scopes and presets are in
|
|
87
|
+
[theming](theming.md).
|
|
88
|
+
|
|
89
|
+
## Hosts and targeting
|
|
90
|
+
|
|
91
|
+
Root `className`, `style`, native props and `ref` always reach the documented
|
|
92
|
+
host, never a wrapper:
|
|
93
|
+
|
|
94
|
+
| Family or part | Host |
|
|
95
|
+
| --------------------------------------------------------------- | --------------------------------------------------- |
|
|
96
|
+
| Button / Link | `button` / `a`, including through `render` |
|
|
97
|
+
| Field | `div` in control layout; `fieldset` in group layout |
|
|
98
|
+
| Input / Checkbox / Radio | Native `input` |
|
|
99
|
+
| RadioGroup | Field's `fieldset` |
|
|
100
|
+
| Dialog | None; it only owns state |
|
|
101
|
+
| DialogTrigger / DialogClose | Button's `button` |
|
|
102
|
+
| DialogContent / DialogTitle / DialogDescription | `dialog` / `h2` / `p` |
|
|
103
|
+
| Collapsible / CollapsibleTrigger / CollapsibleContent | `details` / `summary` / `div` |
|
|
104
|
+
| Accordion / AccordionItem / AccordionTrigger / AccordionContent | `div` / `details` / `summary` / `div` |
|
|
105
|
+
| Card / CardHeader / CardContent / CardFooter | `div` |
|
|
106
|
+
| CardTitle / CardDescription | Heading chosen by `level` / `p` |
|
|
107
|
+
|
|
108
|
+
Internal parts take `className` and `style` through a `parts` map. Field has
|
|
109
|
+
`label`, `description`, `error` and `required`. Checkbox and Radio have
|
|
110
|
+
`wrapper`, `label` and `indicator`, and RadioGroup adds `options`. These hooks
|
|
111
|
+
cannot replace IDs, ARIA, handlers or refs. Caller classes merge after the
|
|
112
|
+
defaults and caller `style` wins. Identity and presentation data attributes
|
|
113
|
+
cannot be overridden.
|
|
114
|
+
|
|
115
|
+
`data-slot` is a space-separated set, so select with `~=`, as in
|
|
116
|
+
`[data-slot~="button"]`. Composed parts keep their base identity:
|
|
117
|
+
`button dialog-trigger`, `field radio-group`, `collapsible accordion-item`.
|
|
118
|
+
Why: styling written for Button still reaches a DialogTrigger.
|
|
119
|
+
|
|
120
|
+
Style real state: native `:disabled`, `:checked` and `open`, plus `aria-busy`
|
|
121
|
+
for pending. Field and RadioGroup set `data-invalid`, `data-disabled` and
|
|
122
|
+
`data-required`. Disclosures and DialogContent set `data-state="open|closed"`.
|
|
123
|
+
Actions set `data-variant`, `data-tone` and `data-control-size`.
|
|
124
|
+
|
|
125
|
+
## State and forms
|
|
126
|
+
|
|
127
|
+
Each state axis has one owner for the life of a mount. Pass `value`, `checked`
|
|
128
|
+
or `open` to control it, or `default*` to set an initial value. Passing both, or switching owner during
|
|
129
|
+
a mount, throws; remount with a new `key` instead. A controlled callback is a request, and the consumer
|
|
130
|
+
may refuse it. No-op requests and prop syncs fire no callback.
|
|
131
|
+
|
|
132
|
+
| Family | State | Callback | Empty |
|
|
133
|
+
| -------------------------- | ---------------------------- | -------------------------------------------- | ------- |
|
|
134
|
+
| Input | `value` / `defaultValue` | Native `onChange`, `onBlur` | `''` |
|
|
135
|
+
| Checkbox, standalone Radio | `checked` / `defaultChecked` | Native `onChange`, `onBlur` | `false` |
|
|
136
|
+
| RadioGroup | `value` / `defaultValue` | `onValueChange(string)` or native `onChange` | `null` |
|
|
137
|
+
| Dialog, Collapsible | `open` / `defaultOpen` | `onOpenChange(boolean)` | `false` |
|
|
138
|
+
| Accordion single | `value` / `defaultValue` | `onValueChange(string \| null)` | `null` |
|
|
139
|
+
| Accordion multiple | `value` / `defaultValue` | `onValueChange(string[])` | `[]` |
|
|
140
|
+
|
|
141
|
+
RadioGroup owns its options' `name` and selection. Use one of `onValueChange`
|
|
142
|
+
or `onChange` to write state, not both. `''` is a valid option value, and `null`
|
|
143
|
+
clears the group.
|
|
144
|
+
|
|
145
|
+
Field owns IDs and label, help and error relationships. Set a control's ID with
|
|
146
|
+
Field's `controlId`. Radiant controls read Field context. A native control uses
|
|
147
|
+
`children(controlProps)` and forwards those props. Disabled and required only
|
|
148
|
+
add up: a child cannot re-enable or un-require what its Field set.
|
|
149
|
+
|
|
150
|
+
The consumer owns validation, touched and dirty state, error text, submission
|
|
151
|
+
and persistence. Native reset restores uncontrolled inputs. A controlled adapter
|
|
152
|
+
resets its own values. Reset never changes Dialog or disclosure state. Why: form
|
|
153
|
+
libraries differ, and Radiant should fit any of them without a hidden form
|
|
154
|
+
store. TanStack Form is an optional example adapter, not a dependency.
|
|
155
|
+
|
|
156
|
+
## Replacement and events
|
|
157
|
+
|
|
158
|
+
Button, Link and the Dialog actions accept `render(resolvedProps)`. Forward all
|
|
159
|
+
props, the ref and the children to one compatible `button` or `a`. There is no
|
|
160
|
+
`as` or `asChild`. Why: one convention, and the resolved props already carry
|
|
161
|
+
presentation, relationships and guards, so an adapter cannot drop them by
|
|
162
|
+
accident. Field's `children(controlProps)` adapts relationships and does not
|
|
163
|
+
replace Field's host.
|
|
164
|
+
|
|
165
|
+
For cancellable actions, disabled and pending guards run first, then the
|
|
166
|
+
consumer handler, then the state request if `defaultPrevented` is false. Native
|
|
167
|
+
change, toggle and blur are observations and cannot veto anything. Library and
|
|
168
|
+
caller refs get the same host, and callback-ref cleanup functions are honored.
|
|
169
|
+
`useField`, `useDialog`, `useCollapsible` and `useAccordion` read and request
|
|
170
|
+
state, and return `null` outside their owner. Parts that need a root throw when misplaced. Lifecycle,
|
|
171
|
+
SSR and hydration details are in [React bindings](react-bindings.md).
|
|
172
|
+
|
|
173
|
+
## What customization must keep
|
|
174
|
+
|
|
175
|
+
Restyling or replacing a host is fine as long as these keep working:
|
|
176
|
+
|
|
177
|
+
- Native controls and labels stay operable, with names and descriptions connected.
|
|
178
|
+
- Focus, invalid, disabled and pending cues stay visible.
|
|
179
|
+
- Closed dialog and details content stays hidden. Dialog keeps its bounds,
|
|
180
|
+
scrolling and modal focus, and `details` keeps a direct-child `summary`.
|
|
181
|
+
- Decorative indicators stay hidden from assistive technology.
|
|
182
|
+
- Reduced-motion and forced-colors modes still work.
|
|
183
|
+
|
|
184
|
+
Passing the type check alone does not prove any of this. See
|
|
185
|
+
[accessibility](accessibility.md) for what to check by hand.
|
|
186
|
+
|
|
187
|
+
## Examples and type fixtures
|
|
188
|
+
|
|
189
|
+
The canonical live examples are Storybook stories:
|
|
190
|
+
[Input](../src/Input.stories.tsx), [Recipes → Forms](../src/Form.stories.tsx)
|
|
191
|
+
(one form, plain or in a Card or Dialog, optionally with TanStack) and
|
|
192
|
+
[Recipes → Workspace → Settings](../src/Workspace.stories.tsx) (all ten
|
|
193
|
+
families). Change a contract and its example together.
|
|
194
|
+
|
|
195
|
+
`docs/contracts/*.ts(x)` are compile-only fixtures. `pnpm typecheck:contracts`
|
|
196
|
+
checks that they type-check and that contradictory props, such as `value` with
|
|
197
|
+
`defaultValue`, are rejected.
|