@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/docs/system.md
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# Radiant system guide
|
|
2
|
+
|
|
3
|
+
Use this guide to theme, compose and customise the ten families in the current
|
|
4
|
+
source: Button, Link, Field, Input, Checkbox, RadioGroup (including Radio),
|
|
5
|
+
Dialog, Collapsible, Accordion and Card. Their public props and types are in the
|
|
6
|
+
[README](../README.md) and package declarations. Changes under
|
|
7
|
+
[Unreleased](../CHANGELOG.md#unreleased) require a release before npm consumers
|
|
8
|
+
can use them; keep JavaScript and CSS on the same version. Radiant remains
|
|
9
|
+
experimental during 0.x.
|
|
10
|
+
|
|
11
|
+
## Compose by responsibility
|
|
12
|
+
|
|
13
|
+
Use Button for actions and Link for navigation, including when a Link looks
|
|
14
|
+
like a button. Use Field for label/help/error relationships, and native controls
|
|
15
|
+
for values and selection. Card groups content; Dialog owns open state and its
|
|
16
|
+
native modal lifecycle; Collapsible owns a disclosure; Accordion composes
|
|
17
|
+
Collapsible for a selection of sections.
|
|
18
|
+
|
|
19
|
+
DialogTrigger and DialogClose compose Button in both default and replacement
|
|
20
|
+
paths. They accept Button's presentation and `render` interface. RadioGroup
|
|
21
|
+
composes Field. Action-shaped Link shares Button's presentation while retaining
|
|
22
|
+
an anchor. Reuse these families when assembling an interface so their theme,
|
|
23
|
+
keyboard behavior and relationships travel together.
|
|
24
|
+
|
|
25
|
+
Action presentation uses three independent choices:
|
|
26
|
+
|
|
27
|
+
| Prop | Values | Default |
|
|
28
|
+
| ------------- | ------------------------------------------------------------------------- | ----------------------------- |
|
|
29
|
+
| `variant` | `solid`, `soft`, `outline`, `ghost`; Link also accepts `inline`, `subtle` | Button `solid`; Link `inline` |
|
|
30
|
+
| `tone` | `accent`, `neutral`, `warning`, `danger` | `accent` |
|
|
31
|
+
| `controlSize` | `small`, `medium`, `large` | `medium` |
|
|
32
|
+
|
|
33
|
+
Input, Checkbox, Radio and RadioGroup share `controlSize`. Input's numeric native
|
|
34
|
+
`size` still measures character width. A variant selects treatment; a tone
|
|
35
|
+
selects its semantic palette.
|
|
36
|
+
|
|
37
|
+
## Set up styles and themes
|
|
38
|
+
|
|
39
|
+
Choose one CSS route: import `@cognitap/radiant/styles.css` once for compiled
|
|
40
|
+
styles, or import `@cognitap/radiant/tailwind.css` alongside your application's
|
|
41
|
+
Tailwind entry. The reset is a separate opt-in import. Compiled CSS supplies a
|
|
42
|
+
neutral light/dark baseline without a provider. Follow the
|
|
43
|
+
[setup examples](../README.md#usage) and [Tailwind route](../README.md#with-tailwind).
|
|
44
|
+
|
|
45
|
+
Author a theme with `defineTheme({ id, name, tokens, components, modes })`.
|
|
46
|
+
It validates typed partial definitions and resolves immutable light/dark maps.
|
|
47
|
+
Choose a built-in preset from the readonly `themes` registry by stable `id`, or
|
|
48
|
+
use its named export, such as `radiant`, `glass` or `defaultTheme`. Load preset
|
|
49
|
+
fonts in your application; choosing a theme never downloads a font. The
|
|
50
|
+
[theming reference](theming.md#define-and-apply-a-theme) owns the authoring
|
|
51
|
+
example, token defaults, preset IDs, font families/weights and migration steps.
|
|
52
|
+
|
|
53
|
+
For public workshop editing, use the versioned `ThemeDocument` authoring API.
|
|
54
|
+
Its token sections compile through `defineTheme` into the same `ThemeScope`
|
|
55
|
+
contract. Section imports preserve unrelated settings and deliberate component
|
|
56
|
+
exceptions. See [portable documents and import semantics](theming.md#portable-workshop-documents). The pure
|
|
57
|
+
`generateColorWall` interface supplies calibrated sRGB palette metadata through
|
|
58
|
+
`@cognitap/radiant/color`; see [color-wall inputs and output](theming.md#generate-a-color-wall). Use
|
|
59
|
+
`colorCalibrationPresets` for independent wall/ramp treatments (Classic, Balanced,
|
|
60
|
+
Expressive; Balanced by default), and `recommendColorPalette` to select a limited working set, map light/dark color and
|
|
61
|
+
canvas layers, and inspect named contrast pairs before compiling a theme.
|
|
62
|
+
Apply these together with bounded geometry using `updateThemeAppearance`; it
|
|
63
|
+
updates existing spacing, control and surface roles without removing authored
|
|
64
|
+
component exceptions. See [appearance settings](theming.md#apply-palette-spacing-and-surfaces-together).
|
|
65
|
+
|
|
66
|
+
| Token group | Shared responsibility |
|
|
67
|
+
| ------------ | ---------------------------------------------------------------------------------- |
|
|
68
|
+
| `color` | Surface, foreground, borders, focus, invalid/disabled colors and action tone pairs |
|
|
69
|
+
| `typography` | Body, label and heading font decisions |
|
|
70
|
+
| `control` | Small/medium/large metrics, control shape and borders |
|
|
71
|
+
| `surface` | Canvas background, panel shape, spacing, elevation and backdrop |
|
|
72
|
+
| `focus` | Outline width, offset and style |
|
|
73
|
+
| `motion` | Press/release, color and disclosure timing |
|
|
74
|
+
| `spacing` | Label, field, group, header and footer gaps |
|
|
75
|
+
| `state` | Disabled opacity |
|
|
76
|
+
|
|
77
|
+
Apply a theme with `ThemeScope`, a normal `div` whose props/ref target that
|
|
78
|
+
host. `mode` is independently `light`, `dark` or `system`; system follows the
|
|
79
|
+
browser preference through CSS. Omitted theme/mode inherit. An explicit named
|
|
80
|
+
theme starts afresh from library defaults, then common values, then its mode
|
|
81
|
+
layer. Nested `defaultTheme` resets inherited effects as well as colors.
|
|
82
|
+
|
|
83
|
+
Within a scope, precedence is **component override → shared role → neutral
|
|
84
|
+
baseline**. Promote a decision to `tokens` when it should affect several
|
|
85
|
+
families; put a deliberate exception in `components.<family>`. Button-only
|
|
86
|
+
fonts/effects stay action-local. `components.radioGroup.gap` spaces options;
|
|
87
|
+
`components.radio.labelGap` spaces an option's label. Passive surfaces use
|
|
88
|
+
surface roles, and Radio stays round by default.
|
|
89
|
+
|
|
90
|
+
Use `ThemeComponentOverrides` for reusable component configuration and
|
|
91
|
+
`ThemeStyle` for local `style` values. Public CSS variables follow their typed
|
|
92
|
+
paths: `tokens.control.radius` becomes `--rad-control-radius`, and
|
|
93
|
+
`components.input.radius` becomes `--rad-input-radius`. Local styles override
|
|
94
|
+
generated values on the same host; caller classes merge after defaults. Use the
|
|
95
|
+
Tailwind route to generate new utility classes supplied by your application.
|
|
96
|
+
|
|
97
|
+
A mode-only scope re-materialises its selected theme. Put token exceptions that
|
|
98
|
+
must survive it on a ThemeScope's inline `style` or in the theme definition;
|
|
99
|
+
intervening ordinary DOM/stylesheet overrides are not recovered automatically.
|
|
100
|
+
A new named theme clears inherited exceptions. See the precise
|
|
101
|
+
[scope and override rules](theming.md#scopes-mode-and-overrides).
|
|
102
|
+
|
|
103
|
+
## Find the actual styling and ref target
|
|
104
|
+
|
|
105
|
+
Root `className`, `style`, native attributes and `ref` reach the documented
|
|
106
|
+
host. A convenience label does not move input props to its wrapper.
|
|
107
|
+
|
|
108
|
+
| Public family / parts | Host and target |
|
|
109
|
+
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
110
|
+
| Button / Link | `button` / `a`, including through a compatible `render` adapter |
|
|
111
|
+
| Field | `div` in control layout; `fieldset` in group layout |
|
|
112
|
+
| Input / Checkbox / Radio | Native `input`; Checkbox/Radio wrapper, label and indicator use `parts` |
|
|
113
|
+
| RadioGroup | Field's `fieldset`; `parts.options` styles its internal option grid |
|
|
114
|
+
| Dialog | Logical state owner with no DOM/style/ref target |
|
|
115
|
+
| DialogTrigger / DialogClose | Button's `button` host |
|
|
116
|
+
| DialogContent / DialogTitle / DialogDescription | `dialog` / `h2` / `p` |
|
|
117
|
+
| Collapsible / CollapsibleTrigger / CollapsibleContent | `details` / `summary` / `div` |
|
|
118
|
+
| Accordion / AccordionItem / AccordionTrigger / AccordionContent | `div` / Collapsible `details` / `summary` / `div`; trigger `level` adds a heading without moving the ref |
|
|
119
|
+
| Card / CardHeader / CardContent / CardFooter | Passive `div` hosts |
|
|
120
|
+
| CardTitle / CardDescription | Heading selected by `level` / `p` |
|
|
121
|
+
|
|
122
|
+
Field exposes `parts.label`, `description`, `error` and `required`;
|
|
123
|
+
Checkbox/Radio expose `parts.wrapper`, `label` and `indicator`. RadioGroup adds
|
|
124
|
+
`parts.options` to Field's hooks. Each hook accepts only `className` and `style`.
|
|
125
|
+
Use the explicit compound parts for layout where a family provides them.
|
|
126
|
+
|
|
127
|
+
`data-slot` is a set of identity tokens. Select with membership, for example
|
|
128
|
+
`[data-slot~="dialog-trigger"]`. Composed identities retain their base:
|
|
129
|
+
`button dialog-trigger`, `button dialog-close`, `field radio-group`,
|
|
130
|
+
`collapsible accordion-item`, `collapsible-trigger accordion-trigger`, and
|
|
131
|
+
`collapsible-content accordion-content`. Caller identities are additive only
|
|
132
|
+
where the family's props support them; owned identities remain protected.
|
|
133
|
+
|
|
134
|
+
Style actual state: native `:disabled`, `:checked`, `:indeterminate` and `open`;
|
|
135
|
+
Button pending uses `aria-busy`; Field/RadioGroup expose presence-based
|
|
136
|
+
`data-invalid`, `data-disabled` and `data-required`. DialogContent and the
|
|
137
|
+
disclosure parts expose `data-state="open" | "closed"`. Actions expose
|
|
138
|
+
`data-variant`, `data-tone` and `data-control-size`; controls expose
|
|
139
|
+
`data-control-size` independently of native Input `size`. There is no universal
|
|
140
|
+
synthetic state attribute to substitute for native or ARIA state.
|
|
141
|
+
|
|
142
|
+
## State and forms
|
|
143
|
+
|
|
144
|
+
Keep one owner per state axis for a mount. Use `value`/`checked`/`open` for
|
|
145
|
+
controlled state and their `default*` counterparts for initial uncontrolled
|
|
146
|
+
state. Accordion uses `value`/`defaultValue` and a fixed single/multiple type.
|
|
147
|
+
Remount to change ownership or selection type. Controlled callbacks request a
|
|
148
|
+
change; the consumer decides whether to accept it. No-op requests and prop
|
|
149
|
+
synchronisation do not create another semantic change callback.
|
|
150
|
+
|
|
151
|
+
Text changes and blur retain native event meanings. RadioGroup owns its options'
|
|
152
|
+
name/selection; `value={null}` clears a controlled group and `""` remains a real
|
|
153
|
+
option value. Choose one state-writing callback, `onValueChange` or `onChange`.
|
|
154
|
+
Checkbox's `checked` is boolean state; its `value` is submitted data.
|
|
155
|
+
|
|
156
|
+
Field owns IDs, label/help/error relationships and inherited metadata. Give an
|
|
157
|
+
explicit control ID through Field's `controlId`. Radiant controls consume those
|
|
158
|
+
relationships; a native adapter uses `children(controlProps)` and forwards them
|
|
159
|
+
to its control. Owned error/disabled/required state cannot be erased by a child.
|
|
160
|
+
A plain Field group preserves native fieldset/first-legend behavior and does
|
|
161
|
+
not make every checkbox required. RadioGroup applies its requirement to the
|
|
162
|
+
mutually exclusive native choice.
|
|
163
|
+
|
|
164
|
+
The consumer owns validation rules/timing, touched/dirty state, error text,
|
|
165
|
+
submission and persistence. Native reset restores uncontrolled controls; a
|
|
166
|
+
controlled adapter resets its values and validation metadata together. Form
|
|
167
|
+
reset does not reset Dialog or disclosure state. Dialog retains its DOM form
|
|
168
|
+
association; compose one form without nesting forms. TanStack is an optional
|
|
169
|
+
reference adapter, outside the runtime dependency and public export surface.
|
|
170
|
+
|
|
171
|
+
For cancellable activation, guards run first, the consumer handler runs next,
|
|
172
|
+
and the library requests a change only when `defaultPrevented` is false.
|
|
173
|
+
Native change/toggle/blur are observations, not vetoable requests. Preserve one
|
|
174
|
+
handler chain and the real host ref, including callback-ref cleanup. Public
|
|
175
|
+
`useField`, `useDialog`, `useCollapsible` and `useAccordion` return null outside
|
|
176
|
+
their owner; required parts fail clearly when misplaced. The
|
|
177
|
+
[React binding reference](https://github.com/cognitap/radiant/blob/main/docs/react-bindings.md)
|
|
178
|
+
details lifecycle, reconciliation, SSR and hydration behavior.
|
|
179
|
+
|
|
180
|
+
## Preserve behavior when customising
|
|
181
|
+
|
|
182
|
+
Button, Link and Dialog actions support `render(resolvedNativeProps)`. Forward
|
|
183
|
+
all resolved props, ref and children to one compatible button or anchor;
|
|
184
|
+
presentation is already resolved. A router adapter keeps native modified-click,
|
|
185
|
+
target and download behavior. Preserve Button's resolved pending children and
|
|
186
|
+
guarded handler; passing them through another Button would wrap/style them
|
|
187
|
+
again. Field's control-prop callback adapts relationships rather than replacing
|
|
188
|
+
Field's host.
|
|
189
|
+
|
|
190
|
+
Keep native controls and labels operable, accessible names/description IDs
|
|
191
|
+
connected, and focus/invalid/disabled/pending cues visible. Closed Dialog/details
|
|
192
|
+
content stays mounted and hidden by the native/functional styles. Preserve
|
|
193
|
+
Dialog bounds, scrolling, top-layer modal focus behavior, and a direct-child
|
|
194
|
+
summary for details. Keep decorative indicators hidden from assistive technology.
|
|
195
|
+
Preserve reduced-motion alternatives and forced-colors readability when changing
|
|
196
|
+
paint, motion or hosts. A type-correct adapter alone does not prove these behaviors.
|
|
197
|
+
|
|
198
|
+
## Reuse the canonical examples
|
|
199
|
+
|
|
200
|
+
Use the global Storybook **Theme** and **Mode** controls in Canvas and Docs.
|
|
201
|
+
Ordinary stories inherit them; **System → Theming → Comparison** is the named
|
|
202
|
+
preset comparison. Follow the [Storybook inspection guide](https://github.com/cognitap/radiant/blob/main/docs/storybook.md).
|
|
203
|
+
|
|
204
|
+
| Need | Canonical live source |
|
|
205
|
+
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
206
|
+
| One labelled control and local override | [Input Default / Customisation](https://github.com/cognitap/radiant/blob/main/src/Input.stories.tsx) |
|
|
207
|
+
| Native form, optional TanStack owner, the same form in Card or Dialog | [ProfileExample](https://github.com/cognitap/radiant/blob/main/.storybook/examples/ProfileForm.tsx), exposed by [Recipes → Forms](https://github.com/cognitap/radiant/blob/main/src/Form.stories.tsx); choose its `placement` control |
|
|
208
|
+
| Assembled interface across all ten families | [WorkspaceSettings](https://github.com/cognitap/radiant/blob/main/.storybook/examples/WorkspaceSettings.tsx), exposed by [Recipes → Workspace → Settings](https://github.com/cognitap/radiant/blob/main/src/Workspace.stories.tsx) |
|
|
209
|
+
|
|
210
|
+
These are development examples using public Radiant names, not package exports.
|
|
211
|
+
Adapt the existing form's state owner and placement rather than copying a second
|
|
212
|
+
form or replacing its actions with bespoke styled hosts. Application imports
|
|
213
|
+
come from `@cognitap/radiant`; implementation deep imports are unsupported.
|
|
214
|
+
|
|
215
|
+
The installed composition checkpoint reuses these exact recipes with public
|
|
216
|
+
package imports. When copying TypeScript recipe sources into an application,
|
|
217
|
+
follow its local module-resolution rules: Cognitap's current Next/Turbopack
|
|
218
|
+
setup needs extensionless local TSX imports, whereas the NodeNext installed
|
|
219
|
+
fixture uses `.js` specifiers. This adaptation does not change Radiant's compiled
|
|
220
|
+
JavaScript imports. See the [checkpoint commands](https://github.com/cognitap/radiant/blob/main/docs/testing.md#evidence-and-readiness).
|
|
221
|
+
An older registry package cannot verify newer exported components; use a matching
|
|
222
|
+
build/archive checkpoint and keep the registry limitation explicit until release.
|
|
223
|
+
|
|
224
|
+
For a change to this contract, update its guide/reference and canonical example
|
|
225
|
+
together, then run the [verification gate](https://github.com/cognitap/radiant/blob/main/docs/testing.md).
|
|
226
|
+
Use the [browser/AT matrix](accessibility.md) for target combinations, manual
|
|
227
|
+
scenarios, exact-version evidence and unverified gaps.
|
|
228
|
+
Check relevant keyboard/form/ref behavior and actual appearance in both modes;
|
|
229
|
+
automated accessibility results do not establish complete visual or assistive
|
|
230
|
+
technology readiness. Historical design decisions and acceptance sketches remain
|
|
231
|
+
in the [harmonisation record](https://github.com/cognitap/radiant/blob/main/docs/contracts/README.md).
|