@cognitap/radiant 0.0.6 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (196) hide show
  1. package/CHANGELOG.md +82 -395
  2. package/README.md +41 -1014
  3. package/RELEASE_POLICY.md +3 -3
  4. package/dist/library/Accordion.d.ts +3 -0
  5. package/dist/library/Accordion.d.ts.map +1 -1
  6. package/dist/library/Accordion.js +1 -1
  7. package/dist/library/Accordion.js.map +1 -1
  8. package/dist/library/Button.d.ts +5 -0
  9. package/dist/library/Button.d.ts.map +1 -1
  10. package/dist/library/Button.js +8 -7
  11. package/dist/library/Button.js.map +1 -1
  12. package/dist/library/Card.d.ts +2 -0
  13. package/dist/library/Card.d.ts.map +1 -1
  14. package/dist/library/Card.js +1 -1
  15. package/dist/library/Card.js.map +1 -1
  16. package/dist/library/Checkbox.d.ts +5 -0
  17. package/dist/library/Checkbox.d.ts.map +1 -1
  18. package/dist/library/Checkbox.js +3 -2
  19. package/dist/library/Checkbox.js.map +1 -1
  20. package/dist/library/Collapsible.d.ts +4 -0
  21. package/dist/library/Collapsible.d.ts.map +1 -1
  22. package/dist/library/Collapsible.js +22 -4
  23. package/dist/library/Collapsible.js.map +1 -1
  24. package/dist/library/Dialog.d.ts +3 -0
  25. package/dist/library/Dialog.d.ts.map +1 -1
  26. package/dist/library/Dialog.js.map +1 -1
  27. package/dist/library/Field.d.ts +8 -0
  28. package/dist/library/Field.d.ts.map +1 -1
  29. package/dist/library/Field.js +2 -0
  30. package/dist/library/Field.js.map +1 -1
  31. package/dist/library/Input.d.ts +3 -0
  32. package/dist/library/Input.d.ts.map +1 -1
  33. package/dist/library/Input.js +1 -0
  34. package/dist/library/Input.js.map +1 -1
  35. package/dist/library/Link.d.ts +5 -0
  36. package/dist/library/Link.d.ts.map +1 -1
  37. package/dist/library/Link.js.map +1 -1
  38. package/dist/library/RadioGroup.d.ts +8 -0
  39. package/dist/library/RadioGroup.d.ts.map +1 -1
  40. package/dist/library/RadioGroup.js +4 -2
  41. package/dist/library/RadioGroup.js.map +1 -1
  42. package/dist/library/Select.d.ts +87 -0
  43. package/dist/library/Select.d.ts.map +1 -0
  44. package/dist/library/Select.js +454 -0
  45. package/dist/library/Select.js.map +1 -0
  46. package/dist/library/cn.d.ts.map +1 -1
  47. package/dist/library/cn.js +20 -3
  48. package/dist/library/cn.js.map +1 -1
  49. package/dist/library/examples/expressive.d.ts +4 -0
  50. package/dist/library/examples/expressive.d.ts.map +1 -0
  51. package/dist/library/{themes → examples}/expressive.js +4 -3
  52. package/dist/library/examples/expressive.js.map +1 -0
  53. package/dist/library/examples/glass.d.ts +4 -0
  54. package/dist/library/examples/glass.d.ts.map +1 -0
  55. package/dist/library/{themes → examples}/glass.js +9 -3
  56. package/dist/library/examples/glass.js.map +1 -0
  57. package/dist/library/examples/index.d.ts +13 -0
  58. package/dist/library/examples/index.d.ts.map +1 -0
  59. package/dist/library/examples/index.js +32 -0
  60. package/dist/library/examples/index.js.map +1 -0
  61. package/dist/library/examples/jelly.d.ts +4 -0
  62. package/dist/library/examples/jelly.d.ts.map +1 -0
  63. package/dist/library/{themes → examples}/jelly.js +4 -3
  64. package/dist/library/examples/jelly.js.map +1 -0
  65. package/dist/library/examples/preset-values.d.ts.map +1 -0
  66. package/dist/library/examples/preset-values.js.map +1 -0
  67. package/dist/library/examples/radiant.d.ts +4 -0
  68. package/dist/library/examples/radiant.d.ts.map +1 -0
  69. package/dist/library/{themes → examples}/radiant.js +4 -3
  70. package/dist/library/examples/radiant.js.map +1 -0
  71. package/dist/library/examples/sharp-3d.d.ts +4 -0
  72. package/dist/library/examples/sharp-3d.d.ts.map +1 -0
  73. package/dist/library/{themes → examples}/sharp-3d.js +4 -3
  74. package/dist/library/examples/sharp-3d.js.map +1 -0
  75. package/dist/library/examples/soft-squircle.d.ts +4 -0
  76. package/dist/library/examples/soft-squircle.d.ts.map +1 -0
  77. package/dist/library/{themes → examples}/soft-squircle.js +4 -3
  78. package/dist/library/examples/soft-squircle.js.map +1 -0
  79. package/dist/library/examples/ticket.d.ts +4 -0
  80. package/dist/library/examples/ticket.d.ts.map +1 -0
  81. package/dist/library/{themes → examples}/ticket.js +4 -3
  82. package/dist/library/examples/ticket.js.map +1 -0
  83. package/dist/library/index.d.ts +3 -1
  84. package/dist/library/index.d.ts.map +1 -1
  85. package/dist/library/index.js +2 -1
  86. package/dist/library/index.js.map +1 -1
  87. package/dist/library/internal/select.d.ts +37 -0
  88. package/dist/library/internal/select.d.ts.map +1 -0
  89. package/dist/library/internal/select.js +42 -0
  90. package/dist/library/internal/select.js.map +1 -0
  91. package/dist/library/motion/MotionLink.d.ts +1 -0
  92. package/dist/library/motion/MotionLink.d.ts.map +1 -1
  93. package/dist/library/motion/MotionLink.js +9 -10
  94. package/dist/library/motion/MotionLink.js.map +1 -1
  95. package/dist/library/motion/host.d.ts +7 -3
  96. package/dist/library/motion/host.d.ts.map +1 -1
  97. package/dist/library/motion/host.js +13 -5
  98. package/dist/library/motion/host.js.map +1 -1
  99. package/dist/library/motion/popup.d.ts +5 -0
  100. package/dist/library/motion/popup.d.ts.map +1 -0
  101. package/dist/library/motion/popup.js +60 -0
  102. package/dist/library/motion/popup.js.map +1 -0
  103. package/dist/library/motion/press.d.ts.map +1 -1
  104. package/dist/library/motion/press.js +41 -14
  105. package/dist/library/motion/press.js.map +1 -1
  106. package/dist/library/motion/pressPolicy.d.ts.map +1 -1
  107. package/dist/library/motion/pressPolicy.js +2 -2
  108. package/dist/library/motion/pressPolicy.js.map +1 -1
  109. package/dist/library/motion/react.d.ts.map +1 -1
  110. package/dist/library/motion/react.js +3 -1
  111. package/dist/library/motion/react.js.map +1 -1
  112. package/dist/library/motion/transitions.d.ts.map +1 -1
  113. package/dist/library/motion/transitions.js +48 -15
  114. package/dist/library/motion/transitions.js.map +1 -1
  115. package/dist/library/react/useControllableState.d.ts +1 -0
  116. package/dist/library/react/useControllableState.d.ts.map +1 -1
  117. package/dist/library/react/useControllableState.js +8 -1
  118. package/dist/library/react/useControllableState.js.map +1 -1
  119. package/dist/library/selectStyles.d.ts +4 -0
  120. package/dist/library/selectStyles.d.ts.map +1 -0
  121. package/dist/library/selectStyles.js +32 -0
  122. package/dist/library/selectStyles.js.map +1 -0
  123. package/dist/library/styles.css +1 -1
  124. package/dist/library/themes/components.d.ts +24 -0
  125. package/dist/library/themes/components.d.ts.map +1 -1
  126. package/dist/library/themes/components.js +24 -0
  127. package/dist/library/themes/components.js.map +1 -1
  128. package/dist/library/themes/index.d.ts +1 -11
  129. package/dist/library/themes/index.d.ts.map +1 -1
  130. package/dist/library/themes/index.js +1 -19
  131. package/dist/library/themes/index.js.map +1 -1
  132. package/docs/accessibility.md +76 -142
  133. package/docs/architecture.md +208 -0
  134. package/docs/motion.md +115 -396
  135. package/docs/theming.md +275 -882
  136. package/package.json +9 -5
  137. package/src/Accordion.tsx +4 -1
  138. package/src/Button.tsx +13 -7
  139. package/src/Card.tsx +3 -1
  140. package/src/Checkbox.tsx +7 -2
  141. package/src/Collapsible.tsx +28 -4
  142. package/src/Dialog.tsx +3 -0
  143. package/src/Field.tsx +8 -0
  144. package/src/Input.tsx +3 -0
  145. package/src/Link.tsx +5 -0
  146. package/src/RadioGroup.tsx +10 -2
  147. package/src/Select.tsx +781 -0
  148. package/src/cn.ts +20 -3
  149. package/src/{themes → examples}/expressive.ts +5 -3
  150. package/src/{themes → examples}/glass.ts +10 -3
  151. package/src/examples/index.ts +35 -0
  152. package/src/{themes → examples}/jelly.ts +5 -3
  153. package/src/{themes → examples}/radiant.ts +5 -3
  154. package/src/{themes → examples}/sharp-3d.ts +5 -3
  155. package/src/{themes → examples}/soft-squircle.ts +5 -3
  156. package/src/{themes → examples}/ticket.ts +5 -3
  157. package/src/index.ts +28 -13
  158. package/src/internal/select.ts +80 -0
  159. package/src/motion/MotionLink.tsx +16 -11
  160. package/src/motion/host.ts +16 -7
  161. package/src/motion/popup.ts +55 -0
  162. package/src/motion/press.ts +32 -12
  163. package/src/motion/pressPolicy.ts +4 -2
  164. package/src/motion/react.ts +3 -1
  165. package/src/motion/transitions.ts +45 -14
  166. package/src/react/useControllableState.ts +7 -1
  167. package/src/selectStyles.ts +34 -0
  168. package/src/themes/components.ts +24 -0
  169. package/src/themes/index.ts +1 -22
  170. package/dist/library/themes/expressive.d.ts +0 -2
  171. package/dist/library/themes/expressive.d.ts.map +0 -1
  172. package/dist/library/themes/expressive.js.map +0 -1
  173. package/dist/library/themes/glass.d.ts +0 -2
  174. package/dist/library/themes/glass.d.ts.map +0 -1
  175. package/dist/library/themes/glass.js.map +0 -1
  176. package/dist/library/themes/jelly.d.ts +0 -2
  177. package/dist/library/themes/jelly.d.ts.map +0 -1
  178. package/dist/library/themes/jelly.js.map +0 -1
  179. package/dist/library/themes/preset-values.d.ts.map +0 -1
  180. package/dist/library/themes/preset-values.js.map +0 -1
  181. package/dist/library/themes/radiant.d.ts +0 -2
  182. package/dist/library/themes/radiant.d.ts.map +0 -1
  183. package/dist/library/themes/radiant.js.map +0 -1
  184. package/dist/library/themes/sharp-3d.d.ts +0 -2
  185. package/dist/library/themes/sharp-3d.d.ts.map +0 -1
  186. package/dist/library/themes/sharp-3d.js.map +0 -1
  187. package/dist/library/themes/soft-squircle.d.ts +0 -2
  188. package/dist/library/themes/soft-squircle.d.ts.map +0 -1
  189. package/dist/library/themes/soft-squircle.js.map +0 -1
  190. package/dist/library/themes/ticket.d.ts +0 -2
  191. package/dist/library/themes/ticket.d.ts.map +0 -1
  192. package/dist/library/themes/ticket.js.map +0 -1
  193. package/docs/system.md +0 -264
  194. /package/dist/library/{themes → examples}/preset-values.d.ts +0 -0
  195. /package/dist/library/{themes → examples}/preset-values.js +0 -0
  196. /package/src/{themes → examples}/preset-values.ts +0 -0
package/README.md CHANGED
@@ -1,1039 +1,66 @@
1
1
  # Radiant
2
2
 
3
- React interaction components and presentation primitives, published as
4
- [`@cognitap/radiant`](https://www.npmjs.com/package/@cognitap/radiant) under the
5
- [MIT license](LICENSE). Radiant is experimental during 0.x. The current source
6
- combines ten families through shared themes, native controls and composed actions
7
- and surfaces.
3
+ React components built on native HTML elements, with shared themes. Published
4
+ as [`@cognitap/radiant`](https://www.npmjs.com/package/@cognitap/radiant) under
5
+ the [MIT license](LICENSE). Radiant is experimental during 0.x.
8
6
 
9
- Start with the [Radiant system guide](docs/system.md) for setup, theme/mode rules,
10
- public anatomy, state ownership and canonical form/Dialog/Card examples. This
11
- README is the detailed component reference. It describes the current source;
12
- changes under [Unreleased](CHANGELOG.md#unreleased) need a release before npm
13
- consumers can use them. Check your installed version's release notes.
7
+ It has eleven families: Button, Link, Field, Input, Select, Checkbox, RadioGroup,
8
+ Dialog, Collapsible, Accordion and Card.
14
9
 
15
- ## Usage
10
+ ## Install
16
11
 
17
12
  ```sh
18
13
  pnpm add --save-exact @cognitap/radiant
19
14
  ```
20
15
 
21
- Import the stylesheet once in your application. It needs no Tailwind and only
22
- styles Radiant components:
16
+ React 19.3+ is a peer dependency. Import the stylesheet once. It needs no
17
+ Tailwind and styles only Radiant components:
23
18
 
24
19
  ```tsx
25
20
  import '@cognitap/radiant/styles.css'
26
- import { Field, Input } from '@cognitap/radiant'
27
-
28
- ;<Field label="Email">
29
- <Input
30
- name="email"
31
- type="email"
32
- autoComplete="email"
33
- />
34
- </Field>
35
- ```
36
-
37
- All components share a neutral light/dark baseline: control dimensions,
38
- typography, surfaces, focus, and motion. Follow the
39
- [system guide](docs/system.md#set-up-styles-and-themes) to choose or author a
40
- theme, or the [canonical recipes](docs/system.md#reuse-the-canonical-examples)
41
- to compose controls into a form, Card or Dialog.
42
-
43
- For a global reset (Tailwind Preflight), also import `@cognitap/radiant/reset.css`
44
- before `styles.css`. React 19.3+ is a peer dependency.
45
-
46
- ## Component reference
47
-
48
- ### Button
49
-
50
- `Button` takes native button props, including `ref`, `aria-*` and form attributes,
51
- and defaults to `type="button"`. Give every button an accessible name through its
52
- text, `aria-label`, or `aria-labelledby`. The type does not reject a nameless
53
- button. Use a link for navigation.
54
-
55
- ```tsx
56
- import { Button } from '@cognitap/radiant'
57
-
58
- <Button variant="solid" tone="danger" controlSize="small">Delete</Button>
59
- <Button variant="outline" tone="neutral" className="rounded-full">Next</Button>
60
- <Button iconOnly aria-label="Close"><CloseIcon /></Button>
61
- ```
62
-
63
- | Prop | Values | Default |
64
- | ------------- | ------------------------------------------------------ | -------- |
65
- | `variant` | `solid`, `soft`, `outline`, `ghost` | `solid` |
66
- | `tone` | `accent`, `neutral`, `warning`, `danger` | `accent` |
67
- | `controlSize` | `small`, `medium`, `large` | `medium` |
68
- | `iconOnly` | Squares the button at its size. Pass `aria-label`. | `false` |
69
- | `fullWidth` | Fills the container width. | `false` |
70
- | `pending` | Shows a spinner over the label and ignores activation. | `false` |
71
- | `render` | Forward resolved props to one custom button host. | — |
72
-
73
- The style prop is `variant`, because `type` stays the native attribute. An omitted
74
- `type` is `button` even when `formAction` is set. Pass `type="submit"` to submit.
75
- While `pending` is set, the label stays in place, a spinner covers it, and
76
- activation does not run. It does not set `disabled`, so focus stays. Reduced
77
- motion keeps the label and hides the spinner. Child SVGs are sized to the button.
78
-
79
- Button owns host replacement through `render(resolvedNativeProps)`. The public
80
- `ButtonRenderProps` type includes merged classes, caller styles, the real button
81
- ref, guarded activation, computed presentation attributes and resolved children
82
- (label and pending indicator). Forward these to one native/custom button:
83
-
84
- ```tsx
85
- <Button
86
- variant="outline"
87
- render={props => <button {...props}>{props.children}</button>}
88
- >
89
- Save draft
90
- </Button>
91
- ```
92
-
93
- Return one compatible element. Null, text, arrays, fragments and direct native
94
- hosts other than buttons fail clearly. Custom components must forward every
95
- resolved prop/ref/child to their button. Preserve resolved children and handlers
96
- so pending presentation and activation guards survive. Set presentation on the
97
- owning Button; resolved props already contain its styling and children.
98
- Dialog actions inherit this same Button interface and compose Button in both
99
- the default and replacement paths.
100
-
101
- ### Link
102
-
103
- `Link` is for navigation: a real anchor with `href`, `target`, `download`, and
104
- native click semantics untouched, so modified clicks and keyboard activation
105
- behave normally. Use inline decoration for running text, subtle decoration that
106
- underlines on hover, or the same solid/soft/outline/ghost treatments as Button. Tone always
107
- selects a palette; controlSize selects dimensions for action-shaped links.
108
- Inline and subtle links inherit the surrounding text size.
109
-
110
- ```tsx
111
- import { Link } from '@cognitap/radiant'
112
-
113
- <p>Read the <Link href="/guide">guide</Link> first.</p>
114
- <Link href="/settings" variant="subtle">Settings</Link>
115
- <Link href="/deletion" variant="solid" tone="danger" controlSize="small">Review deletion</Link>
116
- <Link href="https://example.com" external>Example</Link>
117
- ```
118
-
119
- | Prop | Values | Default |
120
- | ------------- | ------------------------------------------------------------------ | -------- |
121
- | `variant` | `inline`, `subtle`, `solid`, `soft`, `outline`, `ghost` | `inline` |
122
- | `tone` | `accent`, `neutral`, `warning`, `danger` | `accent` |
123
- | `controlSize` | `small`, `medium`, `large` (action dimensions) | `medium` |
124
- | `external` | Adds `target="_blank"` and `rel="noopener noreferrer"` when unset. | `false` |
125
- | `render` | Replace the anchor element; see below. | — |
126
-
127
- Links paint from `--rad-link-color` and `--rad-link-hover-color` (falling back to
128
- readable ink derived from the selected tone and shared foreground) and from the
129
- shared focus variables, so a theme styles links and buttons together. `defineTheme({ components: { link: { ... } } })` sets typed Link overrides:
130
- `color`, `hoverColor`, `underlineOffset`, `decorationThickness`,
131
- `decorationThicknessHover`, `colorDuration`, and `focusColor`, `focusWidth`,
132
- `focusOffset`, `focusStyle`.
133
-
134
- Routers stay outside the core. Pass `render` to hand the anchor props —
135
- `href`, `className`, `children`, and every native attribute — to your router's
136
- own link component:
137
-
138
- ```tsx
139
- <Link
140
- href="/docs"
141
- render={props => <RouterLink {...props} />}
142
- />
143
- ```
144
-
145
- The adapter must forward `href`, `className`, and `children`, and keep native
146
- anchor semantics. When `render` is absent, `Link` renders a plain `<a>`.
147
- Adapt router-specific destination props inside your adapter, and forward native
148
- attributes and the ref to its final anchor.
149
-
150
- `LinkRenderProps` includes the native anchor `ref` (object or callback, including
151
- React's cleanup return), handlers, style, accessibility attributes and resolved
152
- presentation. Forward that ref to the same anchor; Link adds no ref wrapper or
153
- activation handler. Caller classes merge after defaults and caller style wins.
154
- Identity and presentation attributes are protected: `data-slot="link"`,
155
- `data-variant`, `data-tone` and `data-control-size` reflect the actual props.
156
-
157
- A router adapter calls the supplied `onClick` once before its own navigation,
158
- and honours `event.defaultPrevented`. It only intercepts the navigation its
159
- router owns: modified/middle clicks, a different target, downloads and external
160
- URLs must retain browser behaviour. Native click/Enter navigates; Space keeps
161
- anchor behaviour. Links never acquire Button's disabled, pending or form-submit
162
- semantics. `external` supplies `_blank` and `noopener noreferrer` only when the
163
- corresponding attributes are omitted; explicit `target` and `rel` win.
164
-
165
- **Breaking replacement contract:** `render` must return one anchor element or
166
- one router component that forwards all resolved props/ref to an anchor. Null,
167
- text, arrays, fragments and other direct native hosts now throw a descriptive
168
- error; the return type is `ReactElement`. Link cannot inspect a router
169
- component's implementation, so preserving the anchor remains the adapter's
170
- responsibility. Migrate a fragment/wrapper by returning the router element
171
- directly and placing surrounding layout outside Link.
172
-
173
- ### Action API migration (breaking)
174
-
175
- Button, Link, DialogTrigger and DialogClose share `variant`, `tone` and
176
- `controlSize`. `soft` is a quiet filled treatment in any tone. Unfilled and soft
177
- actions mix tone colour toward the shared foreground to retain readable ink in
178
- light and dark; solid uses the selected palette's foreground pair. Neutral
179
- soft, outline and ghost preserve the previous neutral treatments. Theme action
180
- effects, including Glass and Sharp 3D, apply to both Button and action-shaped Link.
181
-
182
- | Previous API | Replacement |
183
- | ----------------------------------------------- | --------------------------------------------------------------------------------------- |
184
- | Button `variant="primary"` | `variant="solid" tone="accent"` (the defaults) |
185
- | Button `variant="secondary"` | `variant="soft" tone="neutral"` |
186
- | Button `variant="warning"` / `"destructive"` | `variant="solid" tone="warning"` / `"danger"` |
187
- | Button `variant="outline"` / `"ghost"` | Same variant, add `tone="neutral"` to retain the previous palette |
188
- | Link `variant="button" tone={oldButtonVariant}` | Use the matching variant/tone pair above directly |
189
- | `size="small" / "default" / "large"` | `controlSize="small" / "medium" / "large"` |
190
- | `radius="full"` | `className="rounded-full"`, or a local `ThemeStyle`/`components.button.radius` override |
191
- | `ButtonSize` / `ButtonRadius` types | `ControlSize`; radius is a CSS/theme decision |
192
- | `[data-size]` | `[data-control-size]`; presentation also exposes `data-variant` and `data-tone` |
193
-
194
- The exported `ButtonVariant` and `LinkVariant` types use the new treatments;
195
- `Tone` and `ControlSize` are shared public types. The old props/values/types are
196
- removed during the experimental 0.x series. Native Input's numeric `size`,
197
- Button form attributes, accessible names and pending behaviour remain available.
198
- Link remains an anchor with native navigation. Button owns `render` for custom
199
- button hosts; Dialog actions inherit it and receive fully resolved Button
200
- presentation, including pending markup.
201
-
202
- ### Field
203
-
204
- `Field` is the form anatomy: it connects a label, an optional description, and
205
- an optional error to one control, or captions a group. It does not validate and
206
- it does not read form state. The consumer owns the error. Pass the message when
207
- the value is invalid and clear it when the value recovers. An empty message
208
- removes the invalid state.
209
-
210
- ```tsx
211
- import { Field, Input } from '@cognitap/radiant'
212
-
213
- ;<Field
214
- label="Email"
215
- description="Work address"
216
- error={error}
217
- required
218
- >
219
- <Input
220
- name="email"
221
- type="email"
222
- autoComplete="email"
223
- />
224
- </Field>
225
- ```
226
-
227
- Radiant controls read `useField()` and connect themselves. For a native or
228
- custom control, explicitly forward `children(controlProps)` to its input,
229
- textarea or select. Field leaves ordinary children untouched. The callback
230
- supplies the owned `id`, `required`, `disabled`, `aria-invalid`, `aria-required`
231
- and `aria-describedby` relationships:
232
-
233
- ```tsx
234
- <Field
235
- label="Email"
236
- error={error}
237
- >
238
- {control => (
239
- <input
240
- {...control}
241
- name="email"
242
- />
243
- )}
244
- </Field>
245
- ```
246
-
247
- `useField()` returns `null` outside a Field. Inside a group, `controlProps` is
248
- `null`: the group element owns the description, and each control keeps its own
249
- label.
250
-
251
- | Prop | Role | Default |
252
- | ------------------- | ----------------------------------------------------------------------------- | --------- |
253
- | `label` | Accessible name. A `<label>` for one control, a `<legend>` for a group. | — |
254
- | `description` | Help text, included in `aria-describedby` while present. | — |
255
- | `error` | Error message. Presence marks the field invalid and announces it as an alert. | — |
256
- | `layout` | `control` or `group` (`<fieldset>`). | `control` |
257
- | `controlId` | Owned control ID in control layout; omit to generate a stable ID. | generated |
258
- | `parts` | `className`/`style` hooks for `label`, `description`, `error` and `required`. | — |
259
- | `required` | Sets the control's `required` and `aria-required`. The marker is visual. | `false` |
260
- | `disabled` | Disables the control, or the whole `<fieldset>` for a group. | `false` |
261
- | `requiredIndicator` | Replaceable visual marker, hidden from assistive tech. `null` hides it. | `*` |
262
-
263
- Group anatomy is a `<fieldset>` and `<legend>`, so a disabled group disables
264
- its descendants natively. A radio group uses `RadioGroup`, which is this
265
- fieldset of native radios, and does not add `role="radiogroup"`. Required and
266
- invalid on a group are relationships on the fieldset, not on each control.
267
-
268
- Set a custom control ID through `Field controlId`, rather than overriding its
269
- child's ID. Otherwise IDs come from `useId()`, so server markup and hydration
270
- agree. Radiant controls append external `aria-describedby` IDs to the owned
271
- description/error IDs. Native adapters must preserve the callback's relationships
272
- when adding their own descriptions. The label, description, error and required
273
- marker are all consumer content.
274
-
275
- Control layout accepts native div props and a div ref. Group layout accepts
276
- native fieldset props, including `form`, `name`, and a fieldset ref; its children
277
- are ordinary nodes. `className` and `style` target that root. Use
278
- `parts={{ description: { style: { fontStyle: 'italic' } } }}` to style a text
279
- part. These hooks accept only styling: Field keeps each part's ID, label
280
- association, alert role and hidden required marker.
281
-
282
- `components.field` in `defineTheme` maps typed keys to `--rad-field-*` variables: `gap`, `labelColor`,
283
- `labelSize`, `labelWeight`, `descriptionColor`, `descriptionSize`, `errorColor`,
284
- `errorSize`, `requiredColor`, and `disabledOpacity`. The root sets
285
- `data-slot="field"`, `data-layout`, `data-invalid`, `data-disabled`, and
286
- `data-required`. Parts set `data-slot` to `field-label`, `field-description`,
287
- `field-error`, and `field-required`. Style a control from the field, for
288
- example `[data-slot~="field"][data-invalid] input`.
289
-
290
- A native `<form>` leaves the control uncontrolled: give it a `name`, and on
291
- submit pass the message back through `error`. Text controls follow the value
292
- contract documented on Input.
293
-
294
- ### Form styling targets
295
-
296
- `className`, `style`, native props and `ref` reach the same host. Convenience
297
- labels do not redirect input props to a wrapper. Use `parts` for the named
298
- internal elements; each hook accepts only `className` and `style`.
299
-
300
- | Component / part | Host / identity tokens | Styling hook |
301
- | -------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
302
- | Field control / group root | `div` / `fieldset`: `field` | Root `className` / `style` |
303
- | RadioGroup root | Field's `fieldset`: `field radio-group` | Root `className` / `style` |
304
- | Field / RadioGroup label | `label` / `legend`: `field-label` | `parts.label` |
305
- | Help / error / required marker | `field-description` / `field-error` / `field-required` | `parts.description` / `parts.error` / `parts.required` |
306
- | RadioGroup options | `div`: `radio-group-options` | `parts.options` |
307
- | Input / Checkbox / Radio control | Native `input`: `input` / `checkbox` / `radio` | Root `className` / `style` |
308
- | Checkbox / Radio wrapper | Outer `label` when labelled, otherwise control `span`: `checkbox-wrapper` / `radio-wrapper` | `parts.wrapper` |
309
- | Checkbox / Radio label text | `span`: `checkbox-label` / `radio-label` (only when labelled) | `parts.label` |
310
- | Checkbox / Radio indicator | Check/mixed SVGs: `checkbox-indicator`; dot `span`: `radio-indicator` | `parts.indicator` |
311
-
312
- Identities are whitespace-separated tokens. Select parts with
313
- `[data-slot~="radio-group"]` and `[data-slot~="radio-group-options"]`. This
314
- replaces the old `[data-slot="radio-group"]` options selector. Composed roots
315
- retain their base identity, including when extra tokens are supplied.
316
-
317
- Part hooks leave owned IDs, label associations, ARIA, events and refs intact.
318
- Checkbox's indicator hook styles both its check and mixed-state glyphs; the
319
- control's state still determines which is visible. Local styles on a control or
320
- part affect that subtree. The Customisation stories show neighbouring controls
321
- without those overrides.
322
-
323
- ### Form recipes
324
-
325
- Storybook's **Recipes → Forms → Native / TanStack** shows the same profile
326
- form with two value owners. The **placement** control reuses either form
327
- standalone, inside Card, or inside Dialog. Both inherit the toolbar's theme and
328
- mode. The [live source](.storybook/examples/ProfileForm.tsx) shares field anatomy,
329
- validation rules and Button actions; each adapter makes ownership explicit.
330
-
331
- | Responsibility | Native recipe | TanStack recipe |
332
- | -------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
333
- | Values | `defaultValue` / `defaultChecked`; read `FormData` on submit | Controlled `value` / `checked`; forward native changes to `handleChange` |
334
- | Blur | The recipe marks email touched and validates | `handleBlur`; group blur ignores focus moves between its options |
335
- | Validation | The recipe validates on blur, change once touched, and submit | Validators run on change/blur/submit; format errors and reveal them once touched |
336
- | Reset | Browser restores defaults; the recipe clears its error/touched state | Prevent the native reset and call `form.reset()` to reset values and metadata together |
337
- | Submission | Read named native inputs; unchecked and disabled controls are omitted | `handleSubmit()` delivers the library's values after validation |
338
-
339
- Both use `noValidate` so the recipe can show the agreed errors through Field,
340
- while inputs retain their native types, required/disabled state and form data.
341
- Checkbox maps its boolean through `checked`; its `value="yes"` remains submitted
342
- data. RadioGroup writes through one selection callback. Card and Dialog reuse
343
- the form without nested forms or per-surface styling overrides. Saving a valid
344
- Dialog form closes it and restores trigger focus; reset leaves the Dialog open.
345
-
346
- TanStack is an optional development/example dependency. Neither the recipes nor
347
- the integration are exported by the library. The ownership decisions are in
348
- [the system guide](docs/system.md#state-and-forms).
349
-
350
- ### Input
351
-
352
- `Input` is a native `<input>` with the text-field metrics. It keeps every
353
- native attribute, including `name`, `type`, `autoComplete`, `placeholder`,
354
- `size` (the character width), `defaultValue`, `value`, `onChange`, `onBlur`,
355
- and `ref`. Inside a single-control Field it takes the field id, required,
356
- disabled, and description relationships. Inside a group it keeps its own
357
- identity, because the fieldset owns the description.
358
-
359
- ```tsx
360
- import { Field, Input } from '@cognitap/radiant'
361
-
362
- ;<Field
363
- label="Email"
364
- description="Work address"
365
- error={error}
366
- required
367
- >
368
- <Input
369
- name="email"
370
- type="email"
371
- autoComplete="email"
372
- defaultValue="ada@example.com"
373
- />
374
- </Field>
375
- ```
376
-
377
- | Mode | How the value moves | Reset |
378
- | ------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
379
- | Uncontrolled | Omit `value`. `defaultValue` is the initial value. Read it from `FormData` or the ref. | `form.reset()` restores `defaultValue`. |
380
- | Controlled | Pass `value` and update it from `onChange`. | The browser reset does not change React state. Reset the state, or call the form library's reset. |
381
-
382
- `onChange` and `onBlur` are the native events. Radiant does not store the value
383
- and does not validate on blur. The native `size` attribute stays the character
384
- width. `controlSize="small" | "medium" | "large"` selects shared height,
385
- padding and font metrics, independently of native `size`. The default is
386
- `medium`; explicit `--rad-input-height`, padding and font overrides still win.
387
- Choose `value` or `defaultValue` for text inputs, and keep that owner for the
388
- mounted lifetime. Mixed owners or changing modes throw; use a new key to
389
- remount. Controlled text uses `''` for empty, never `null`. File, checkbox and
390
- radio Input types retain their native type-specific value behavior.
391
-
392
- Field's owned control ID, required state and active error cannot be erased by
393
- conflicting child props. Descriptions append external IDs once. Disabled Field
394
- owners propagate through nested Fields; a child `disabled={false}` cannot
395
- re-enable them. Native fieldsets retain the platform's first-legend exception
396
- for arbitrary native content.
397
-
398
- `components.input` in `defineTheme` accepts `height`, `padding`, `fontFamily`, `fontSize`, `fontWeight`,
399
- `color`, `background`, `borderWidth`, `borderStyle`, `borderColor`, `radius`,
400
- `cornerShape`, `shadow`, `placeholder`, `invalidBorder`, `disabledBackground`,
401
- `focusColor`, `focusWidth`, `focusOffset`, and `focusStyle`. An invalid field
402
- uses the destructive border. The element sets `data-slot="input"`.
403
-
404
- The [form recipes](#form-recipes) show controlled Input, Checkbox and RadioGroup
405
- with optional TanStack state, validation and reset ownership.
406
-
407
- Checkbox, radio, and file inputs are separate families. `type` still accepts
408
- any native value. Use `RadioGroup` for a mutually exclusive choice.
409
-
410
- ### Checkbox
411
-
412
- `Checkbox` is a native checkbox. `type` is always `checkbox`. The visible box
413
- is drawn on that input, so keyboard activation, form submission, reset, and
414
- label clicks stay the platform's.
415
-
416
- ```tsx
417
- import { Checkbox, Field } from '@cognitap/radiant'
418
-
419
- ;<Checkbox label="Email" name="channels" value="email" defaultChecked />
420
-
421
- <Field label="Notifications" layout="group" description="Choose any">
422
- <Checkbox label="Email" name="channels" value="email" />
423
- <Checkbox label="SMS" name="channels" value="sms" />
424
- </Field>
425
- ```
426
-
427
- | Mode | How the check moves | Reset |
428
- | ------------ | ------------------------------------------------------ | -------------------------------------------- |
429
- | Uncontrolled | Omit `checked`. `defaultChecked` is the initial check. | `form.reset()` restores `defaultChecked`. |
430
- | Controlled | Pass `checked` and update it from `onChange`. | A browser reset does not change React state. |
431
-
432
- `indeterminate` is the mixed state. It is a visual mark for a partial
433
- selection, applied to the DOM property after mount. It is not a third submitted
434
- value and not an HTML attribute. The form submits `checked`. A checked box
435
- submits its `value`, or `on` when `value` is omitted. An unchecked box submits
436
- nothing.
437
-
438
- Checkbox and standalone Radio choose `checked` or `defaultChecked`, with one
439
- owner per mount. Mixed owners or switching modes throw. Native default/reset
440
- behavior stays with React and the browser. A controlled checkbox or radio
441
- preserves its current check during browser reset, including after a change.
442
- The consumer recomputes `indeterminate` after reset when it derives from other
443
- selections.
444
-
445
- `controlSize` uses the same small/medium/large vocabulary and defaults to
446
- medium. It selects the shared indicator and label font metrics. Explicit
447
- Checkbox/Radio size and label overrides still win; decorative marks follow
448
- the actual input dimensions.
449
-
450
- `label` wraps the input, so the text toggles it. Inside a single-control Field
451
- the field id wins, and that label is the accessible name. Inside a group, each
452
- checkbox keeps the `label` beside it and the fieldset keeps the caption. Pass
453
- one name for the option, not both.
454
- An ordinary Field group leaves each checkbox's native requirement independent:
455
- a group marker does not require every box. The consumer validates rules such
456
- as “choose at least one”. RadioGroup uses native radio validity for its one
457
- required choice.
458
-
459
- `className` merges onto the input. Replacing `appearance-none` puts the native
460
- glyph back; the input stays in the tab order and in the form. The check and
461
- dash are decorative and do not receive clicks.
462
-
463
- `components.checkbox` in `defineTheme` accepts `size`, `radius`, `cornerShape`, `borderWidth`,
464
- `borderStyle`, `borderColor`, `background`, `checkedBackground`,
465
- `checkedBorder`, `mark`, `invalidBorder`, `gap`, `labelColor`, `labelSize`,
466
- `disabledBorder`, `disabledBackground`, `focusColor`, `focusWidth`,
467
- `focusOffset`, and `focusStyle`. The input sets `data-slot="checkbox"`.
468
-
469
- ### RadioGroup
470
-
471
- `RadioGroup` is a Field group: a `<fieldset>` and `<legend>` of native radios.
472
- The group owns `name`. Each `Radio` owns its `value` and `label`. The visible
473
- disk is drawn on the input, so arrow keys, focus entry, focus exit, form
474
- submission, reset, and label clicks stay the platform's. Tab lands on the
475
- selected radio, or the first enabled radio when none is selected, and the next
476
- Tab leaves the group. Arrow keys move among enabled radios that share the name
477
- and skip a disabled choice. The group does not set `role="radiogroup"`, and
478
- it does not put `aria-invalid` or `aria-required` on the radios. The fieldset
479
- owns its description and invalid state; `aria-required` is not supported on a
480
- fieldset. A required group sets each radio's native `required`
481
- attribute, and an invalid group paints the disks from the field's invalid
482
- state.
483
-
484
- ```tsx
485
- import { Radio, RadioGroup } from '@cognitap/radiant'
486
-
487
- ;<RadioGroup
488
- label="Plan"
489
- name="plan"
490
- defaultValue="pro"
491
- description="Billed monthly"
492
- >
493
- <Radio
494
- label="Free"
495
- value="free"
496
- />
497
- <Radio
498
- label="Pro"
499
- value="pro"
500
- />
501
- <Radio
502
- label="Retired"
503
- value="retired"
504
- disabled
505
- />
506
- <Radio
507
- label="Team"
508
- value="team"
509
- />
510
- </RadioGroup>
511
- ```
512
-
513
- | Mode | How the selection moves | Reset |
514
- | ------------ | ------------------------------------------------------------------- | ----------------------------------------------- |
515
- | Uncontrolled | Omit `value`. The initial `defaultValue` checks its matching radio. | `form.reset()` restores that initial selection. |
516
- | Controlled | Pass `value` and update it from `onValueChange` or `onChange`. | A browser reset does not change React state. |
517
-
518
- The checked radio submits `name=value`. When none is checked, the group submits
519
- nothing. `onChange` is the selected radio's change event, and `onValueChange`
520
- receives its value. React does not deliver a radio change through the
521
- fieldset, so the group listens on each radio. Inside the group, the group name
522
- and selection win, so a `checked` or `name` on `Radio` does not split the
523
- group. Conflicting option names or supplied `checked`/`defaultChecked` throw;
524
- put selection ownership on RadioGroup. Outside a group, `Radio` is an ordinary radio: pass `name` and
525
- `defaultChecked` or `checked`.
526
-
527
- Use `value={null}` to clear a controlled group. `value=""` selects a real
528
- option whose value is the empty string. Never pass both `value` and
529
- `defaultValue`, or switch modes during a mount. Group defaults are initial
530
- snapshots; changing them does not replace a user's selection or reset baseline.
531
- User selection notifies once; prop updates, reset and clearing do not emit a
532
- selection callback. A controlled owner may decline a selection, and native
533
- checked state reconciles to its unchanged prop.
534
-
535
- Group `controlSize` supplies the default size for its Radio options. An option
536
- may select its own `controlSize`. Group required state cannot be removed by an
537
- option's `required={false}`.
538
-
539
- `label` wraps the input. Pass one name for the option, not a Field label as
540
- well. A disabled group disables every choice through the fieldset. A disabled
541
- choice stays visible and is skipped by the arrow keys.
542
-
543
- `className` merges onto the input. Replacing `appearance-none` puts the native
544
- glyph back; the input stays in the tab order and in the form. The dot is
545
- decorative and does not receive clicks.
546
-
547
- The disk stays a circle. `--rad-radio-radius` defaults to `999px` and
548
- `--rad-radio-corner-shape` defaults to `unset`, so shared squircle or scoop
549
- control shapes do not pinch it. Checked fill follows `--rad-color-accent`.
550
-
551
- `components.radio` in `defineTheme` accepts `size`, `radius`, `cornerShape`, `borderWidth`,
552
- `borderStyle`, `borderColor`, `background`, `checkedBackground`,
553
- `checkedBorder`, `mark`, `invalidBorder`, `labelGap`, `labelColor`,
554
- `labelSize`, `disabledBorder`, `disabledBackground`, `focusColor`,
555
- `focusWidth`, `focusOffset`, and `focusStyle`. Root and part identities and
556
- styling hooks are listed in [Form styling targets](#form-styling-targets).
557
-
558
- ### Dialog
559
-
560
- `Dialog` is the open-state owner and renders no DOM wrapper. `DialogContent`
561
- renders the native `<dialog>`. It stays in the document that rendered it, so
562
- an ancestor form still owns the fields inside. There is no portal. A modal
563
- dialog calls `showModal()`, which gives it the browser's top layer, inert
564
- background, focus containment, and focus restoration. `modal={false}` calls
565
- `show()` instead, for a dialog that leaves the rest of the page active.
566
-
567
- ```tsx
568
- import {
569
- Dialog,
570
- DialogClose,
571
- DialogContent,
572
- DialogDescription,
573
- DialogTitle,
574
- DialogTrigger
575
- } from '@cognitap/radiant'
576
-
577
- ;<Dialog>
578
- <DialogTrigger>Edit profile</DialogTrigger>
579
- <DialogContent>
580
- <DialogTitle>Edit profile</DialogTitle>
581
- <DialogDescription>This name is visible to your team.</DialogDescription>
582
- <DialogClose>Close</DialogClose>
583
- </DialogContent>
584
- </Dialog>
585
- ```
586
-
587
- | Mode | How it opens and closes | After a browser close |
588
- | ------------ | ---------------------------------------------- | ----------------------------------------------- |
589
- | Uncontrolled | Omit `open`. `defaultOpen` opens after mount. | React follows the browser. |
590
- | Controlled | Pass `open` and update it from `onOpenChange`. | If `open` stays `true`, the dialog opens again. |
591
-
592
- Dialog, Collapsible and Accordion keep one state owner for a mount. Omit the
593
- controlled prop when using its initial default; do not supply both. To change
594
- ownership or Accordion type, remount with a new key. No-op requests, prop
595
- synchronisation and native restoration do not emit semantic change callbacks.
596
-
597
- `showModal()` and `close()` run after mount. Server markup never includes the
598
- `open` attribute, including when `defaultOpen` is set, so hydration matches.
599
- The file is marked `'use client'` because those DOM methods cannot be
600
- represented in HTML. `showModal()` puts the dialog in the top layer and makes
601
- the rest of the document inert. It does not lock document scrolling, and this
602
- component does not set `overflow: hidden` on the body. The panel scrolls its
603
- own overflow. Closed content stays mounted and hidden by the user agent. A
604
- field inside a closed dialog is still in an ancestor form.
605
-
606
- `DialogTrigger` and `DialogClose` compose `Button` by default, accepting its
607
- `variant`, `tone`, `controlSize`, `iconOnly`, `fullWidth`, and `pending` props.
608
- They inherit Button's typography, theme effects, hover, press, focus, and pending
609
- presentation. `DialogTrigger` adds `aria-haspopup="dialog"`, `aria-expanded`, and
610
- `aria-controls` pointing at the dialog; `DialogClose` requests close. Native
611
- disabled and pending guards run before the consumer click handler. A consumer
612
- can prevent the open/close request with `event.preventDefault()`.
613
-
614
- Dialog actions inherit Button's `render(resolvedNativeProps)` interface. Both
615
- default and custom paths compose Button; Button resolves and validates the host.
616
- The callback returns one button or a component that forwards
617
- to one button. It receives merged Button classes, caller styles, the real ref,
618
- resolved children (including pending presentation), protected relationships and
619
- guarded activation. Forward all props and children without wrapping another
620
- Button or composing the handler again. Null, text, arrays, fragments and direct
621
- native hosts other than buttons are rejected; custom components must preserve
622
- the button host themselves.
623
-
624
- ```tsx
625
- <DialogClose
626
- variant="outline"
627
- tone="neutral"
628
- render={props => <button {...props}>{props.children}</button>}
629
- >
630
- Cancel
631
- </DialogClose>
632
- ```
633
-
634
- **Replacement migration:** callbacks previously owned their presentation. Move
635
- `render={props => <Button {...props} variant="outline" />}` to `variant="outline"`
636
- on the Dialog action and forward the resolved props to a native/custom button.
637
- Use caller `className`/`style` on the action for local overrides. Retain resolved
638
- children so the pending label and decorative indicator remain consistent.
639
- Button preserves its base identity when composition adds slot tokens; Dialog
640
- protects the exact `button dialog-trigger` / `button dialog-close` token sets.
641
- Resolved presentation attributes cannot be replaced with caller data attributes.
642
-
643
- Ordinary actions should set presentation props directly on `DialogTrigger` or
644
- `DialogClose`. A `<form method="dialog">` inside the
645
- dialog also closes it, and the `close` event updates React. `closeOnBackdrop`
646
- and `closeOnEscape` default to true and apply to modal dialogs. Escape is the
647
- browser's cancel event. A backdrop click is a click on the dialog whose point
648
- lies outside its border box, so a click on the padding does not close it.
649
-
650
- `DialogTitle` names the dialog through `aria-labelledby`. Include it. The title
651
- is an `h2`. `DialogDescription` fills `aria-describedby`. The ids come from
652
- context, so the parts can be reordered. Omitting the description leaves
653
- `aria-describedby` pointing at a missing id. Pass `aria-label` on
654
- `DialogContent` when the dialog has no title; the labelled-by relationship is
655
- then left to the consumer.
656
-
657
- External `aria-describedby` IDs are deduplicated and appended to the owned
658
- DialogDescription ID. Changing `modal` on an open Dialog switches the same
659
- native host between `showModal()` and `show()` without requesting a state change.
660
-
661
- | Part | DOM, styling and ref target | Identity |
662
- | --------------------------- | --------------------------------------------- | ----------------------------------------------- |
663
- | Dialog | State owner; DOM props belong to its parts | No host |
664
- | DialogContent | Native `dialog` panel, including `::backdrop` | `dialog` |
665
- | DialogTitle | `h2`, with its owned label ID | `dialog-title` |
666
- | DialogDescription | `p`, with its owned description ID | `dialog-description` |
667
- | DialogTrigger / DialogClose | Button's native `button` host | `button dialog-trigger` / `button dialog-close` |
668
-
669
- Each DOM part accepts `className`, `style`, native props and the ref for that
670
- same host. Content, title and description styles accept local theme variables.
671
- Computed identities and IDs stay owned. Content's `data-state="open" | "closed"`
672
- reflects the React state owner, just like Trigger's `aria-expanded`; native
673
- `open`/`:modal` remain authoritative for the browser layer. Even untyped caller
674
- props cannot supply Content's `open` attribute. Server markup stays closed and
675
- hydration opens it after mount.
676
-
677
- The open panel keeps a viewport margin of 1rem, a maximum height of
678
- `min(40rem, 100dvh - 2rem)`, and its own scrolling/overscroll containment.
679
- Set `style={{ '--rad-dialog-width': '24rem' }}` to choose a local width while
680
- retaining the viewport bound. Caller classes merge after defaults; match the
681
- `open:` prefix for open-only layout, such as `open:p-0`. Preserve visibility,
682
- viewport bounds and scrolling when replacing functional styles.
683
-
684
- Surface, typography, border and focus settings fall back to shared theme roles.
685
- Panel/title/description color transitions use `motion.colorDuration` and turn
686
- off under reduced motion. Native opening, dismissal and cleanup keep their
687
- existing timing. Backdrop background and the panel's `backdropFilter` remain
688
- independent settings, including Glass's blur correction.
689
-
690
- Focus is the platform's. An `autoFocus` control inside the dialog takes initial
691
- focus. Otherwise the browser focuses the first focusable control inside.
692
- Shift+Tab from that control wraps to the last control. Tab from the last
693
- control can land on the document body for one stop; the next Tab returns to
694
- the first control, and background controls stay unfocused. Closing restores
695
- the element that was focused when the dialog opened. A second dialog opened
696
- with `showModal()` stacks on the first, and Escape closes the top one. `close`
697
- and `cancel` bubble, and a parent ignores an event that started on a nested
698
- dialog. `useDialog()` lets another control open the same dialog. It returns
699
- `null` outside `Dialog`.
700
-
701
- `className` merges onto the part it is passed to. The panel uses shared surface
702
- radius and corner shape, so a scoop or squircle theme shapes the surface.
703
- `components.dialog` in `defineTheme` accepts `width`, `padding`, `gap`, `radius`, `cornerShape`,
704
- `background`, `color`, `borderWidth`, `borderStyle`, `borderColor`, `shadow`,
705
- `backdrop`, `backdropFilter`, `titleSize`, `titleWeight`, `descriptionColor`, `descriptionSize`,
706
- `focusColor`, `focusWidth`, `focusOffset`, and `focusStyle`. The dialog sets
707
- `data-slot="dialog"`. The action identities are `button dialog-trigger` and
708
- `button dialog-close`; use membership selectors such as
709
- `[data-slot~="dialog-trigger"]`. Title and description retain `dialog-title`
710
- and `dialog-description`.
711
-
712
- ### Collapsible
713
-
714
- `Collapsible` is a native `<details>` element. `CollapsibleTrigger` is its
715
- `<summary>`. The browser toggles it with a click, Space, or Enter, and keeps
716
- focus on the summary. There is no separate open attribute to invent: `open` is
717
- the disclosure's open state. Closed content stays in the document and is hidden
718
- by the user agent, so a field inside a closed disclosure is still part of an
719
- ancestor form.
720
-
721
- ```tsx
722
- import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@cognitap/radiant'
723
-
724
- ;<Collapsible>
725
- <CollapsibleTrigger>Shipping</CollapsibleTrigger>
726
- <CollapsibleContent>Ships in two days.</CollapsibleContent>
727
- </Collapsible>
728
- ```
729
-
730
- | Mode | How it opens | After the browser toggles |
731
- | ------------ | --------------------------------------------------- | --------------------------------------------------- |
732
- | Uncontrolled | Omit `open`. `defaultOpen` is in the server markup. | React follows the summary. |
733
- | Controlled | Pass `open` and update it from `onOpenChange`. | If `open` stays unchanged, the disclosure does too. |
734
-
735
- `defaultOpen` is the `open` attribute on the server, so hydration matches.
736
- The file is marked `'use client'` because the summary changes the DOM open
737
- state and React state has to follow it. Parts can be reordered; the summary
738
- still toggles every other child. `name` is the native exclusive group: opening
739
- one disclosure closes another with the same name. A nested disclosure does not
740
- toggle its parent.
741
-
742
- The summary's text is its accessible name. Do not put a button or link inside
743
- the summary. The marker is decorative. `useCollapsible()` reads the open state
744
- and can request a change. It returns `null` outside `Collapsible`.
745
-
746
- The panel height and the marker use shared disclosure motion timing. `prefers-reduced-motion`
747
- removes those transitions, so the state change is instant. `data-state` is
748
- `open` or `closed`.
749
-
750
- `className` merges onto the part it is passed to. The surface inherits the
751
- shared surface radius and corner shape. `components.collapsible` in `defineTheme` accepts `radius`,
752
- `cornerShape`, `background`, `color`, `borderWidth`, `borderStyle`,
753
- `borderColor`, `padding`, `gap`, `contentColor`, `contentSize`, `duration`,
754
- `focusColor`, `focusWidth`, `focusOffset`, and `focusStyle`. The disclosure
755
- sets `data-slot="collapsible"`. The summary and content set
756
- `collapsible-trigger` and `collapsible-content`. Root, summary and content accept
757
- native props/refs and typed local theme styles on those exact hosts. Their
758
- owned `data-state` follows the open-state owner; a caller `data-slot` adds tokens
759
- without replacing the owned identity. Use token selectors (`[data-slot~="collapsible"]`)
760
- when targeting composed disclosures. Color transitions use shared color motion
761
- and also stop under reduced motion. Keep the native closed-content visibility,
762
- direct-child summary and details-content overflow/height rules when overriding
763
- functional CSS. Closed fields stay mounted and remain successful form controls.
764
-
765
- ### Accordion
766
-
767
- `Accordion` is a group of `Collapsible` sections. Each trigger is that
768
- section's `<summary>`, and each panel is its content. The accordion chooses
769
- which sections are open. The summary still toggles, and `open` is still the
770
- disclosure's open state.
771
-
772
- ```tsx
773
- import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@cognitap/radiant'
774
-
775
- ;<Accordion defaultValue="shipping">
776
- <AccordionItem value="shipping">
777
- <AccordionTrigger>Shipping</AccordionTrigger>
778
- <AccordionContent>Ships in two days.</AccordionContent>
779
- </AccordionItem>
780
- <AccordionItem value="returns">
781
- <AccordionTrigger>Returns</AccordionTrigger>
782
- <AccordionContent>Returns are free for 30 days.</AccordionContent>
783
- </AccordionItem>
784
- </Accordion>
785
- ```
786
-
787
- | Mode | What stays open |
788
- | ---------- | ----------------------------------------------------- |
789
- | `single` | One section. Opening another closes the previous one. |
790
- | `multiple` | Each section, on its own. |
791
-
792
- `single` is the default. Omit `value` and pass `defaultValue` for an
793
- uncontrolled group. Pass `value` and update it from `onValueChange` for a
794
- controlled group. If `value` does not change, the open sections do not change
795
- either. Sections do not share a `name`: the accordion passes `open` to each
796
- section, so a controlled value can restore the disclosure without fighting
797
- the browser's exclusive group. Closed content stays mounted, so a field
798
- inside a closed section is still part of an ancestor form.
799
-
800
- The trigger label is a level-3 heading inside the summary. Set `level` to
801
- another heading level, or `level={null}` for text with no heading. The summary
802
- has to stay a direct child of `<details>`, so the heading cannot wrap the
803
- summary. Do not put a button or link inside the trigger. The marker is
804
- decorative. `useAccordion()` reads the value and can open or close a section.
805
- It returns `null` outside `Accordion`.
806
-
807
- Tab moves between summaries and into open content. Space and Enter toggle the
808
- focused summary and leave focus there. ArrowDown leaves focus on the summary.
809
- A disabled summary is removed from the tab order and does not toggle. A nested
810
- disclosure does not change the accordion selection.
811
-
812
- `className` merges onto the part it is passed to. Section surface, radius,
813
- and motion come from `Collapsible`; set `components.collapsible` in the scoped
814
- theme and the variables inherit. `components.accordion.gap` maps to `--rad-accordion-gap`,
815
- the space between sections. The group sets `data-slot="accordion"` and
816
- `data-type="single"` or `"multiple"`. Part props, styles and refs target the same native hosts as Collapsible:
817
-
818
- | Part | Host | Owned identity tokens |
819
- | ---------------- | --------- | --------------------------------------- |
820
- | Accordion | `div` | `accordion` |
821
- | AccordionItem | `details` | `collapsible accordion-item` |
822
- | AccordionTrigger | `summary` | `collapsible-trigger accordion-trigger` |
823
- | AccordionContent | `div` | `collapsible-content accordion-content` |
824
-
825
- Use `[data-slot~="accordion-trigger"]` (and token selectors for the underlying
826
- Collapsible identities). Caller tokens are additive and deduplicated. Item,
827
- trigger and content expose the item's owned `data-state`; content IDs remain
828
- owned. Content must belong to an AccordionItem. The item ignores native `name`
829
- even for JavaScript callers, so browser exclusive grouping cannot compete with
830
- Accordion's selection owner. Local theme variables can be passed directly to
831
- any part's `style`. Choose `value` or `defaultValue`, and `open` or `defaultOpen`
832
- for standalone Collapsible; mixed owners are rejected by types and runtime.
833
-
834
- ### Card
835
-
836
- `Card` is a grouped surface. It renders a `<div>`. It is not a button, a link,
837
- or a region. Put a `Button` or a `Link` inside it when the card needs an
838
- action. Those controls keep their own keyboard behavior. The card itself is
839
- not in the tab order.
840
-
841
- ```tsx
842
- import {
843
- Button,
844
- Card,
845
- CardContent,
846
- CardDescription,
847
- CardFooter,
848
- CardHeader,
849
- CardTitle,
850
- Link
851
- } from '@cognitap/radiant'
852
-
853
- ;<Card>
854
- <CardHeader>
855
- <CardTitle>Shipping</CardTitle>
856
- <CardDescription>Leaves the studio tomorrow.</CardDescription>
857
- </CardHeader>
858
- <CardContent>Ships in two days.</CardContent>
859
- <CardFooter>
860
- <Button type="button">Track</Button>
861
- <Link href="/orders/1">Details</Link>
862
- </CardFooter>
863
- </Card>
864
- ```
865
-
866
- The title is a level-2 heading. Set `level` when the page outline needs a
867
- different one. The description is a paragraph. Header, content, footer, and
868
- title can be omitted or reordered. The consumer owns the words.
869
-
870
- To name a region, wrap the card in a `<section>` and point
871
- `aria-labelledby` at the title's `id`. The card does not add that role.
872
-
873
- `className` merges onto the part it is passed to. The surface inherits the
874
- shared surface radius and corner shape. `components.card` in `defineTheme` accepts `radius`, `cornerShape`,
875
- `background`, `color`, `borderWidth`, `borderStyle`, `borderColor`,
876
- `padding`, `gap`, `headerGap`, `footerGap`, `shadow`, `titleSize`,
877
- `titleWeight`, `descriptionColor`, and `descriptionSize`. The card sets
878
- `data-slot="card"`. The header, title, description, content, and footer set
879
- `card-header`, `card-title`, `card-description`, `card-content`, and
880
- `card-footer`. Each part accepts typed local theme variables and native props/refs
881
- on its own host. Caller `data-slot` tokens are additive and deduplicated; owned
882
- identities remain present. Use token selectors such as `[data-slot~="card-title"]`.
883
-
884
- | Part | Native host / ref target |
885
- | ----------------------------------------- | --------------------------------------------- |
886
- | Card, CardHeader, CardContent, CardFooter | `div` / `HTMLDivElement` |
887
- | CardTitle | `h1`–`h6` from `level` / `HTMLHeadingElement` |
888
- | CardDescription | `p` / `HTMLParagraphElement` |
889
-
890
- Root/title/description color transitions follow shared color motion and stop
891
- under reduced motion. Local overrides retain the shared fallbacks on other
892
- parts: for example, `style={{ '--rad-card-padding': '1.25rem' }}` changes root
893
- padding and `style={{ '--rad-card-title-size': '1.25rem' }}` targets a title.
894
- Caller classes merge after defaults. Preserve the grid layout, content wrapping
895
- and footer wrapping when changing functional CSS; keep actions as Button/Link
896
- children rather than making the surface itself interactive.
897
-
898
- Card → Composition reuses the canonical native profile form under the global
899
- Storybook theme. Recipes → Forms also offers the TanStack owner and Dialog
900
- placement; these share the same fields and actions rather than separate demos.
901
-
902
- ### Theming
903
-
904
- Use `defineTheme` for shared semantic tokens and deliberate `components`
905
- exceptions; apply its result with `ThemeScope`. Theme and light/dark/system mode
906
- are independent. The [system guide](docs/system.md#set-up-styles-and-themes)
907
- explains scopes, precedence, fonts and local styling; the
908
- [theming reference](docs/theming.md) contains the canonical authoring example,
909
- complete token defaults and preset reference.
910
-
911
- Migrating older code? Follow the
912
- [theme migration steps](docs/theming.md#migration-from-button-centred-themes)
913
- and [action migration table](#action-api-migration-breaking). Family theme
914
- helpers/types, `Theme.style`, `Theme.surface`, `radiantTheme` and old CSS aliases
915
- are removed. Use `ThemeComponentOverrides` for reusable configuration and
916
- `ThemeStyle` for local `--rad-*` styles.
21
+ import { Button, Field, Input } from '@cognitap/radiant'
22
+
23
+ export function Signup() {
24
+ return (
25
+ <form>
26
+ <Field label="Email">
27
+ <Input
28
+ name="email"
29
+ type="email"
30
+ autoComplete="email"
31
+ />
32
+ </Field>
33
+ <Button type="submit">Sign up</Button>
34
+ </form>
35
+ )
36
+ }
37
+ ```
38
+
39
+ For a global reset, also import `@cognitap/radiant/reset.css` before
40
+ `styles.css`.
917
41
 
918
42
  ### With Tailwind
919
43
 
920
- For opt-in prose and reusable text styles, see
921
- [responsive typography](docs/theming.md#responsive-typography).
922
- Existing components consume the shared UI roles, while control sizes and explicit
923
- component exceptions retain their metrics. See [component mapping and migration](docs/theming.md#component-roles-and-earlier-themes).
924
-
925
- The pure
926
- `@cognitap/radiant/typography` entry resolves font-aware starting points through
927
- the existing theme compiler; applications still own font loading.
928
-
929
44
  Applications on Tailwind 4.3.3+ can import the source entry instead of
930
45
  `styles.css`, so their own build generates Radiant's utilities. Use one route,
931
- not both, or the utilities are duplicated:
46
+ not both:
932
47
 
933
48
  ```css
934
49
  @import 'tailwindcss';
935
50
  @import '@cognitap/radiant/tailwind.css';
936
51
  ```
937
52
 
938
- To skip Preflight, replace `@import 'tailwindcss'` with
939
- [Tailwind's separate imports](https://tailwindcss.com/docs/preflight#disabling-preflight).
940
-
941
- ```css
942
- @layer theme, base, components, utilities;
943
- @import 'tailwindcss/theme.css' layer(theme);
944
- @import 'tailwindcss/utilities.css' layer(utilities);
945
- @import '@cognitap/radiant/tailwind.css';
946
- ```
947
-
948
- Keep application source discovery enabled so caller utilities are generated;
949
- using `source(none)` requires explicitly registering your application's sources.
950
- Utilities passed in `className` replace matching defaults, including `hover:` and
951
- `disabled:` variants: `<Button className="rounded-full hover:bg-red-500">`.
952
-
953
- ## Development
954
-
955
- The [system guide](docs/system.md) defines the current ten-family consumer
956
- contract and canonical sources. [GLOSSARY.md](GLOSSARY.md) defines the shared
957
- vocabulary. The [harmonisation design record](docs/contracts/README.md) and
958
- [migration inventory](docs/contracts/migration.md) preserve the original decisions
959
- and compile-only acceptance sketches. `pnpm typecheck:contracts` checks those
960
- sketches' type consistency; runtime and browser checks establish behavior.
961
-
962
- The [React binding reference](docs/react-bindings.md) details the implemented
963
- ref, event, ID, state ownership and mounted lifecycle conventions and their
964
- private consumers.
965
-
966
- Use the Node.js version in `.nvmrc`. Any recent pnpm switches itself to the version
967
- pinned in `package.json`:
968
-
969
- ```sh
970
- nvm install && nvm use
971
- npm install --global pnpm
972
- pnpm install --frozen-lockfile
973
- pnpm exec playwright install chromium
974
- pnpm storybook
975
- ```
976
-
977
- Storybook runs at [localhost:6006](http://localhost:6006) and needs no Cognitap
978
- checkout. Choose **Theme** and **Mode** in its toolbar; the selection applies
979
- across component stories and Docs. Defaults are Radiant and System.
980
- See the [Storybook guide](docs/storybook.md) for the shared story
981
- structure and verification workflow.
982
-
983
- | Command | Purpose |
984
- | ------------------------- | ----------------------------------------------------------------------------------- |
985
- | `pnpm storybook` | Develop components in Storybook. |
986
- | `pnpm build` | Build JavaScript, declarations, and CSS into `dist/library`. |
987
- | `pnpm watch` | Rebuild on change, except `reset.css` (run `pnpm build` first). |
988
- | `pnpm build:storybook` | Build static Storybook into `dist/storybook`. |
989
- | `pnpm lint` | Run Oxlint, including accessibility rules. |
990
- | `pnpm format` | Format with Oxfmt (`format:check` to check only). |
991
- | `pnpm typecheck` | Check TypeScript. |
992
- | `pnpm test` | Run style tests and verify the packed, installed package. |
993
- | `pnpm test:package` | Verify the packed, installed package only. |
994
- | `pnpm test:browser` | Run Storybook plays and axe in every theme/mode, plus native browser scenarios. |
995
- | `pnpm test:browser:smoke` | Run every story in Radiant Light/Dark plus native browser scenarios. |
996
- | `pnpm check:ci` | Run source checks, runtime/package tests, builds, and representative browser tests. |
997
- | `pnpm check` | Run the full theme, installed styling/composition, and browser audit. |
998
- | `pnpm release:prepare` | Pack and verify a release candidate, then dry-run publishing. |
999
-
1000
- Package verification installs the archive with npm, so it needs network access.
1001
- A Husky pre-commit hook formats staged files with Oxfmt.
1002
- [CI](.github/workflows/ci.yml) runs `pnpm check:ci` for pull requests and pushes
1003
- to `main`. Run `pnpm check` for the exhaustive audit, locally or with the manual
1004
- workflow's **full** input.
1005
- See [verification conventions](docs/testing.md) for focused browser runs,
1006
- failure artifacts, and the evidence required by migration issues.
1007
-
1008
- Modules must stay free of import-time side effects, and client-dependent modules
1009
- need their own `use client` directive. Add `*.stories.tsx` next to each component,
1010
- like `src/Button.stories.tsx`. Storybook's Accessibility panel runs axe checks on
1011
- every story, but automated checks cover only part of WCAG, so still test keyboard,
1012
- focus, and screen reader behavior by hand.
1013
-
1014
- ## Live development in Cognitap
1015
-
1016
- With this checkout at `../radiant` and its dependencies installed, `pnpm dev` in
1017
- Cognitap builds and watches it, points both apps at it, and starts this Storybook.
1018
- Cognitap's installed package, manifests, and lockfile stay untouched. See
1019
- [Cognitap's guide](https://github.com/cognitap/cognitap#live-radiant-development)
1020
- for other checkouts and type checking.
1021
-
1022
- ## Further reading
1023
-
1024
- - [Browser/accessibility matrix](docs/accessibility.md): support targets, manual checks, WCAG evidence and unverified combinations
1025
- - [System guide](docs/system.md): the current ten-family theming, composition and customisation contract
1026
- - [Theming reference](docs/theming.md): token defaults, presets, fonts and migration steps
1027
- - [Storybook inspection](docs/storybook.md): global Theme/Mode controls and canonical live recipes
1028
- - [Release policy](RELEASE_POLICY.md): versioning, compatibility, and the release workflow
1029
- - [Changelog](CHANGELOG.md): consumer-facing changes per release
1030
- - [CONTRIBUTING.md](CONTRIBUTING.md): maintainer workflow and bug reports
1031
- - [AGENTS.md](AGENTS.md): component and styling conventions
53
+ Keep source discovery on so your own utilities are generated. Utilities you pass
54
+ in `className` replace the matching defaults, including `hover:` and
55
+ `disabled:` variants.
1032
56
 
1033
- ### Spring runtime (unreleased)
57
+ ## Documentation
1034
58
 
1035
- Configure serializable `defineTheme({motion: ...})` profiles and opt into
1036
- `@cognitap/radiant/motion` or `/motion/react`. See the [runtime and migration
1037
- guide](docs/motion.md) for physical values, native bindings, live reduced motion,
1038
- cleanup and the accepted Radiant layout boundary. Existing component animations
1039
- are unchanged until their individual integrations.
59
+ - [Docs site](https://radiant-docs.pages.dev): a guide and live example for each component
60
+ - [Architecture](docs/architecture.md): how the families fit together and why
61
+ - [Theming](docs/theming.md): tokens, presets, fonts and modes
62
+ - [Motion](docs/motion.md): opt-in spring animation
63
+ - [Accessibility](docs/accessibility.md): support targets and manual checks
64
+ - [Glossary](GLOSSARY.md): shared vocabulary
65
+ - [Changelog](CHANGELOG.md): what changed in each release, including unreleased work
66
+ - [Contributing](CONTRIBUTING.md): setup, commands and how changes get merged