@cognitap/radiant 0.0.2 → 0.0.4
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 +357 -0
- package/README.md +944 -29
- package/dist/library/Accordion.d.ts +56 -0
- package/dist/library/Accordion.d.ts.map +1 -0
- package/dist/library/Accordion.js +89 -0
- package/dist/library/Accordion.js.map +1 -0
- package/dist/library/Button.d.ts +25 -3
- package/dist/library/Button.d.ts.map +1 -1
- package/dist/library/Button.js +31 -3
- package/dist/library/Button.js.map +1 -1
- package/dist/library/Card.d.ts +31 -0
- package/dist/library/Card.d.ts.map +1 -0
- package/dist/library/Card.js +69 -0
- package/dist/library/Card.js.map +1 -0
- package/dist/library/Checkbox.d.ts +13 -0
- package/dist/library/Checkbox.d.ts.map +1 -0
- package/dist/library/Checkbox.js +77 -0
- package/dist/library/Checkbox.js.map +1 -0
- package/dist/library/Collapsible.d.ts +32 -0
- package/dist/library/Collapsible.d.ts.map +1 -0
- package/dist/library/Collapsible.js +99 -0
- package/dist/library/Collapsible.js.map +1 -0
- package/dist/library/Dialog.d.ts +50 -0
- package/dist/library/Dialog.d.ts.map +1 -0
- package/dist/library/Dialog.js +215 -0
- package/dist/library/Dialog.js.map +1 -0
- package/dist/library/Field.d.ts +68 -0
- package/dist/library/Field.d.ts.map +1 -0
- package/dist/library/Field.js +114 -0
- package/dist/library/Field.js.map +1 -0
- package/dist/library/Input.d.ts +10 -0
- package/dist/library/Input.d.ts.map +1 -0
- package/dist/library/Input.js +51 -0
- package/dist/library/Input.js.map +1 -0
- package/dist/library/Link.d.ts +27 -0
- package/dist/library/Link.d.ts.map +1 -0
- package/dist/library/Link.js +50 -0
- package/dist/library/Link.js.map +1 -0
- package/dist/library/RadioGroup.d.ts +27 -0
- package/dist/library/RadioGroup.d.ts.map +1 -0
- package/dist/library/RadioGroup.js +103 -0
- package/dist/library/RadioGroup.js.map +1 -0
- package/dist/library/ThemeScope.d.ts +10 -0
- package/dist/library/ThemeScope.d.ts.map +1 -0
- package/dist/library/ThemeScope.js +41 -0
- package/dist/library/ThemeScope.js.map +1 -0
- package/dist/library/actionStyles.d.ts +11 -0
- package/dist/library/actionStyles.d.ts.map +1 -0
- package/dist/library/actionStyles.js +75 -0
- package/dist/library/actionStyles.js.map +1 -0
- package/dist/library/cn.d.ts +1 -2
- package/dist/library/cn.d.ts.map +1 -1
- package/dist/library/cn.js +1 -8
- package/dist/library/cn.js.map +1 -1
- package/dist/library/color/colorFamilies.d.ts +3 -0
- package/dist/library/color/colorFamilies.d.ts.map +1 -0
- package/dist/library/color/colorFamilies.js +20 -0
- package/dist/library/color/colorFamilies.js.map +1 -0
- package/dist/library/color/generateColorWall.d.ts +54 -0
- package/dist/library/color/generateColorWall.d.ts.map +1 -0
- package/dist/library/color/generateColorWall.js +231 -0
- package/dist/library/color/generateColorWall.js.map +1 -0
- package/dist/library/color/index.d.ts +5 -0
- package/dist/library/color/index.d.ts.map +1 -0
- package/dist/library/color/index.js +3 -0
- package/dist/library/color/index.js.map +1 -0
- package/dist/library/color/oklch.d.ts +17 -0
- package/dist/library/color/oklch.d.ts.map +1 -0
- package/dist/library/color/oklch.js +79 -0
- package/dist/library/color/oklch.js.map +1 -0
- package/dist/library/color/recommendColorPalette.d.ts +65 -0
- package/dist/library/color/recommendColorPalette.d.ts.map +1 -0
- package/dist/library/color/recommendColorPalette.js +263 -0
- package/dist/library/color/recommendColorPalette.js.map +1 -0
- package/dist/library/controlStyles.d.ts +5 -0
- package/dist/library/controlStyles.d.ts.map +1 -0
- package/dist/library/controlStyles.js +15 -0
- package/dist/library/controlStyles.js.map +1 -0
- package/dist/library/index.d.ts +30 -1
- package/dist/library/index.d.ts.map +1 -1
- package/dist/library/index.js +14 -0
- package/dist/library/index.js.map +1 -1
- package/dist/library/internal/events.d.ts +8 -0
- package/dist/library/internal/events.d.ts.map +1 -0
- package/dist/library/internal/events.js +13 -0
- package/dist/library/internal/events.js.map +1 -0
- package/dist/library/internal/ids.d.ts +3 -0
- package/dist/library/internal/ids.d.ts.map +1 -0
- package/dist/library/internal/ids.js +6 -0
- package/dist/library/internal/ids.js.map +1 -0
- package/dist/library/internal/selection.d.ts +5 -0
- package/dist/library/internal/selection.d.ts.map +1 -0
- package/dist/library/internal/selection.js +18 -0
- package/dist/library/internal/selection.js.map +1 -0
- package/dist/library/presentation.d.ts +18 -0
- package/dist/library/presentation.d.ts.map +1 -0
- package/dist/library/presentation.js +2 -0
- package/dist/library/presentation.js.map +1 -0
- package/dist/library/react/useComposedRefs.d.ts +4 -0
- package/dist/library/react/useComposedRefs.d.ts.map +1 -0
- package/dist/library/react/useComposedRefs.js +28 -0
- package/dist/library/react/useComposedRefs.js.map +1 -0
- package/dist/library/react/useControllableState.d.ts +16 -0
- package/dist/library/react/useControllableState.d.ts.map +1 -0
- package/dist/library/react/useControllableState.js +29 -0
- package/dist/library/react/useControllableState.js.map +1 -0
- package/dist/library/react/useNativeOwner.d.ts +17 -0
- package/dist/library/react/useNativeOwner.d.ts.map +1 -0
- package/dist/library/react/useNativeOwner.js +17 -0
- package/dist/library/react/useNativeOwner.js.map +1 -0
- package/dist/library/reset.css +1 -0
- package/dist/library/styles.css +2 -1
- package/dist/library/themes/components.d.ts +217 -0
- package/dist/library/themes/components.d.ts.map +1 -0
- package/dist/library/themes/components.js +229 -0
- package/dist/library/themes/components.js.map +1 -0
- package/dist/library/themes/default.d.ts +2 -0
- package/dist/library/themes/default.d.ts.map +1 -0
- package/dist/library/themes/default.js +4 -0
- package/dist/library/themes/default.js.map +1 -0
- package/dist/library/themes/defineTheme.d.ts +33 -0
- package/dist/library/themes/defineTheme.d.ts.map +1 -0
- package/dist/library/themes/defineTheme.js +98 -0
- package/dist/library/themes/defineTheme.js.map +1 -0
- package/dist/library/themes/expressive.d.ts +2 -0
- package/dist/library/themes/expressive.d.ts.map +1 -0
- package/dist/library/themes/expressive.js +132 -0
- package/dist/library/themes/expressive.js.map +1 -0
- package/dist/library/themes/glass.d.ts +2 -0
- package/dist/library/themes/glass.d.ts.map +1 -0
- package/dist/library/themes/glass.js +132 -0
- package/dist/library/themes/glass.js.map +1 -0
- package/dist/library/themes/index.d.ts +18 -0
- package/dist/library/themes/index.d.ts.map +1 -0
- package/dist/library/themes/index.js +23 -0
- package/dist/library/themes/index.js.map +1 -0
- package/dist/library/themes/jelly.d.ts +2 -0
- package/dist/library/themes/jelly.d.ts.map +1 -0
- package/dist/library/themes/jelly.js +130 -0
- package/dist/library/themes/jelly.js.map +1 -0
- package/dist/library/themes/preset-values.d.ts +4 -0
- package/dist/library/themes/preset-values.d.ts.map +1 -0
- package/dist/library/themes/preset-values.js +5 -0
- package/dist/library/themes/preset-values.js.map +1 -0
- package/dist/library/themes/radiant.d.ts +2 -0
- package/dist/library/themes/radiant.d.ts.map +1 -0
- package/dist/library/themes/radiant.js +129 -0
- package/dist/library/themes/radiant.js.map +1 -0
- package/dist/library/themes/sharp-3d.d.ts +2 -0
- package/dist/library/themes/sharp-3d.d.ts.map +1 -0
- package/dist/library/themes/sharp-3d.js +142 -0
- package/dist/library/themes/sharp-3d.js.map +1 -0
- package/dist/library/themes/soft-squircle.d.ts +2 -0
- package/dist/library/themes/soft-squircle.d.ts.map +1 -0
- package/dist/library/themes/soft-squircle.js +131 -0
- package/dist/library/themes/soft-squircle.js.map +1 -0
- package/dist/library/themes/themeDocument.d.ts +16 -0
- package/dist/library/themes/themeDocument.d.ts.map +1 -0
- package/dist/library/themes/themeDocument.js +307 -0
- package/dist/library/themes/themeDocument.js.map +1 -0
- package/dist/library/themes/themeDocumentTypes.d.ts +69 -0
- package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -0
- package/dist/library/themes/themeDocumentTypes.js +2 -0
- package/dist/library/themes/themeDocumentTypes.js.map +1 -0
- package/dist/library/themes/ticket.d.ts +2 -0
- package/dist/library/themes/ticket.d.ts.map +1 -0
- package/dist/library/themes/ticket.js +141 -0
- package/dist/library/themes/ticket.js.map +1 -0
- package/dist/library/themes/tokens.d.ts +100 -0
- package/dist/library/themes/tokens.d.ts.map +1 -0
- package/dist/library/themes/tokens.js +171 -0
- package/dist/library/themes/tokens.js.map +1 -0
- package/dist/library/themes/types.d.ts +2 -0
- package/dist/library/themes/types.d.ts.map +1 -0
- package/dist/library/themes/types.js +2 -0
- package/dist/library/themes/types.js.map +1 -0
- package/dist/library/themes/updateThemeAppearance.d.ts +29 -0
- package/dist/library/themes/updateThemeAppearance.d.ts.map +1 -0
- package/dist/library/themes/updateThemeAppearance.js +138 -0
- package/dist/library/themes/updateThemeAppearance.js.map +1 -0
- package/docs/accessibility.md +189 -0
- package/docs/system.md +231 -0
- package/docs/theming.md +804 -0
- package/package.json +34 -10
- package/src/Accordion.tsx +235 -0
- package/src/Button.tsx +95 -15
- package/src/Card.tsx +143 -0
- package/src/Checkbox.tsx +189 -0
- package/src/Collapsible.tsx +193 -0
- package/src/Dialog.tsx +333 -0
- package/src/Field.tsx +293 -0
- package/src/Input.tsx +82 -0
- package/src/Link.tsx +95 -0
- package/src/RadioGroup.tsx +255 -0
- package/src/ThemeScope.tsx +64 -0
- package/src/actionStyles.ts +90 -0
- package/src/cn.ts +1 -10
- package/src/color/colorFamilies.ts +19 -0
- package/src/color/generateColorWall.ts +358 -0
- package/src/color/index.ts +11 -0
- package/src/color/oklch.ts +95 -0
- package/src/color/recommendColorPalette.ts +375 -0
- package/src/controlStyles.ts +19 -0
- package/src/index.ts +130 -1
- package/src/internal/events.ts +17 -0
- package/src/internal/ids.ts +5 -0
- package/src/internal/selection.ts +20 -0
- package/src/presentation.ts +12 -0
- package/src/react/useComposedRefs.ts +32 -0
- package/src/react/useControllableState.ts +50 -0
- package/src/react/useNativeOwner.ts +33 -0
- package/src/styles.css +2 -14
- package/src/themes/baseline.css +116 -0
- package/src/themes/components.ts +249 -0
- package/src/themes/default.ts +4 -0
- package/src/themes/defineTheme.ts +145 -0
- package/src/themes/expressive.ts +132 -0
- package/src/themes/glass.ts +135 -0
- package/src/themes/index.ts +57 -0
- package/src/themes/jelly.ts +130 -0
- package/src/themes/preset-values.ts +5 -0
- package/src/themes/radiant.ts +129 -0
- package/src/themes/sharp-3d.ts +142 -0
- package/src/themes/soft-squircle.ts +131 -0
- package/src/themes/themeDocument.ts +340 -0
- package/src/themes/themeDocumentTypes.ts +76 -0
- package/src/themes/ticket.ts +141 -0
- package/src/themes/tokens.ts +262 -0
- package/src/themes/types.ts +10 -0
- package/src/themes/updateThemeAppearance.ts +172 -0
package/README.md
CHANGED
|
@@ -2,13 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
React interaction components and presentation primitives, published as
|
|
4
4
|
[`@cognitap/radiant`](https://www.npmjs.com/package/@cognitap/radiant) under the
|
|
5
|
-
[MIT license](LICENSE). Radiant is experimental
|
|
6
|
-
|
|
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.
|
|
8
|
+
|
|
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
14
|
|
|
8
15
|
## Usage
|
|
9
16
|
|
|
10
17
|
```sh
|
|
11
|
-
pnpm add --save-exact @cognitap/radiant
|
|
18
|
+
pnpm add --save-exact @cognitap/radiant
|
|
12
19
|
```
|
|
13
20
|
|
|
14
21
|
Import the stylesheet once in your application. It needs no Tailwind and only
|
|
@@ -16,25 +23,897 @@ styles Radiant components:
|
|
|
16
23
|
|
|
17
24
|
```tsx
|
|
18
25
|
import '@cognitap/radiant/styles.css'
|
|
19
|
-
import {
|
|
26
|
+
import { Field, Input } from '@cognitap/radiant'
|
|
20
27
|
|
|
21
|
-
|
|
22
|
-
<
|
|
23
|
-
|
|
28
|
+
;<Field label="Email">
|
|
29
|
+
<Input
|
|
30
|
+
name="email"
|
|
31
|
+
type="email"
|
|
32
|
+
autoComplete="email"
|
|
33
|
+
/>
|
|
34
|
+
</Field>
|
|
24
35
|
```
|
|
25
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
|
+
|
|
26
43
|
For a global reset (Tailwind Preflight), also import `@cognitap/radiant/reset.css`
|
|
27
44
|
before `styles.css`. React 19.3+ is a peer dependency.
|
|
28
45
|
|
|
46
|
+
## Component reference
|
|
47
|
+
|
|
48
|
+
### Button
|
|
49
|
+
|
|
29
50
|
`Button` takes native button props, including `ref`, `aria-*` and form attributes,
|
|
30
51
|
and defaults to `type="button"`. Give every button an accessible name through its
|
|
31
|
-
text
|
|
32
|
-
|
|
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.
|
|
33
449
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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.
|
|
38
917
|
|
|
39
918
|
### With Tailwind
|
|
40
919
|
|
|
@@ -49,11 +928,32 @@ not both, or the utilities are duplicated:
|
|
|
49
928
|
|
|
50
929
|
To skip Preflight, replace `@import 'tailwindcss'` with
|
|
51
930
|
[Tailwind's separate imports](https://tailwindcss.com/docs/preflight#disabling-preflight).
|
|
931
|
+
|
|
932
|
+
```css
|
|
933
|
+
@layer theme, base, components, utilities;
|
|
934
|
+
@import 'tailwindcss/theme.css' layer(theme);
|
|
935
|
+
@import 'tailwindcss/utilities.css' layer(utilities);
|
|
936
|
+
@import '@cognitap/radiant/tailwind.css';
|
|
937
|
+
```
|
|
938
|
+
|
|
939
|
+
Keep application source discovery enabled so caller utilities are generated;
|
|
940
|
+
using `source(none)` requires explicitly registering your application's sources.
|
|
52
941
|
Utilities passed in `className` replace matching defaults, including `hover:` and
|
|
53
942
|
`disabled:` variants: `<Button className="rounded-full hover:bg-red-500">`.
|
|
54
943
|
|
|
55
944
|
## Development
|
|
56
945
|
|
|
946
|
+
The [system guide](docs/system.md) defines the current ten-family consumer
|
|
947
|
+
contract and canonical sources. [GLOSSARY.md](GLOSSARY.md) defines the shared
|
|
948
|
+
vocabulary. The [harmonisation design record](docs/contracts/README.md) and
|
|
949
|
+
[migration inventory](docs/contracts/migration.md) preserve the original decisions
|
|
950
|
+
and compile-only acceptance sketches. `pnpm typecheck:contracts` checks those
|
|
951
|
+
sketches' type consistency; runtime and browser checks establish behavior.
|
|
952
|
+
|
|
953
|
+
The [React binding reference](docs/react-bindings.md) details the implemented
|
|
954
|
+
ref, event, ID, state ownership and mounted lifecycle conventions and their
|
|
955
|
+
private consumers.
|
|
956
|
+
|
|
57
957
|
Use the Node.js version in `.nvmrc`. Any recent pnpm switches itself to the version
|
|
58
958
|
pinned in `package.json`:
|
|
59
959
|
|
|
@@ -61,29 +961,40 @@ pinned in `package.json`:
|
|
|
61
961
|
nvm install && nvm use
|
|
62
962
|
npm install --global pnpm
|
|
63
963
|
pnpm install --frozen-lockfile
|
|
964
|
+
pnpm exec playwright install chromium
|
|
64
965
|
pnpm storybook
|
|
65
966
|
```
|
|
66
967
|
|
|
67
968
|
Storybook runs at [localhost:6006](http://localhost:6006) and needs no Cognitap
|
|
68
|
-
checkout.
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
| `pnpm
|
|
76
|
-
| `pnpm
|
|
77
|
-
| `pnpm
|
|
78
|
-
| `pnpm
|
|
79
|
-
| `pnpm
|
|
80
|
-
| `pnpm
|
|
81
|
-
| `pnpm
|
|
82
|
-
| `pnpm
|
|
969
|
+
checkout. Choose **Theme** and **Mode** in its toolbar; the selection applies
|
|
970
|
+
across component stories and Docs. Defaults are Radiant and System.
|
|
971
|
+
See the [Storybook guide](docs/storybook.md) for the shared story
|
|
972
|
+
structure and verification workflow.
|
|
973
|
+
|
|
974
|
+
| Command | Purpose |
|
|
975
|
+
| ------------------------- | ----------------------------------------------------------------------------------- |
|
|
976
|
+
| `pnpm storybook` | Develop components in Storybook. |
|
|
977
|
+
| `pnpm build` | Build JavaScript, declarations, and CSS into `dist/library`. |
|
|
978
|
+
| `pnpm watch` | Rebuild on change, except `reset.css` (run `pnpm build` first). |
|
|
979
|
+
| `pnpm build:storybook` | Build static Storybook into `dist/storybook`. |
|
|
980
|
+
| `pnpm lint` | Run Oxlint, including accessibility rules. |
|
|
981
|
+
| `pnpm format` | Format with Oxfmt (`format:check` to check only). |
|
|
982
|
+
| `pnpm typecheck` | Check TypeScript. |
|
|
983
|
+
| `pnpm test` | Run style tests and verify the packed, installed package. |
|
|
984
|
+
| `pnpm test:package` | Verify the packed, installed package only. |
|
|
985
|
+
| `pnpm test:browser` | Run Storybook plays and axe in every theme/mode, plus native browser scenarios. |
|
|
986
|
+
| `pnpm test:browser:smoke` | Run every story in Radiant Light/Dark plus native browser scenarios. |
|
|
987
|
+
| `pnpm check:ci` | Run source checks, runtime/package tests, builds, and representative browser tests. |
|
|
988
|
+
| `pnpm check` | Run the full theme, installed styling/composition, and browser audit. |
|
|
989
|
+
| `pnpm release:prepare` | Pack and verify a release candidate, then dry-run publishing. |
|
|
83
990
|
|
|
84
991
|
Package verification installs the archive with npm, so it needs network access.
|
|
85
992
|
A Husky pre-commit hook formats staged files with Oxfmt.
|
|
86
|
-
[CI](.github/workflows/ci.yml) runs `pnpm check
|
|
993
|
+
[CI](.github/workflows/ci.yml) runs `pnpm check:ci` for pull requests and pushes
|
|
994
|
+
to `main`. Run `pnpm check` for the exhaustive audit, locally or with the manual
|
|
995
|
+
workflow's **full** input.
|
|
996
|
+
See [verification conventions](docs/testing.md) for focused browser runs,
|
|
997
|
+
failure artifacts, and the evidence required by migration issues.
|
|
87
998
|
|
|
88
999
|
Modules must stay free of import-time side effects, and client-dependent modules
|
|
89
1000
|
need their own `use client` directive. Add `*.stories.tsx` next to each component,
|
|
@@ -101,6 +1012,10 @@ for other checkouts and type checking.
|
|
|
101
1012
|
|
|
102
1013
|
## Further reading
|
|
103
1014
|
|
|
1015
|
+
- [Browser/accessibility matrix](docs/accessibility.md): support targets, manual checks, WCAG evidence and unverified combinations
|
|
1016
|
+
- [System guide](docs/system.md): the current ten-family theming, composition and customisation contract
|
|
1017
|
+
- [Theming reference](docs/theming.md): token defaults, presets, fonts and migration steps
|
|
1018
|
+
- [Storybook inspection](docs/storybook.md): global Theme/Mode controls and canonical live recipes
|
|
104
1019
|
- [Release policy](RELEASE_POLICY.md): versioning, compatibility, and the release workflow
|
|
105
1020
|
- [Changelog](CHANGELOG.md): consumer-facing changes per release
|
|
106
1021
|
- [CONTRIBUTING.md](CONTRIBUTING.md): maintainer workflow and bug reports
|