@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.
Files changed (230) hide show
  1. package/CHANGELOG.md +357 -0
  2. package/README.md +944 -29
  3. package/dist/library/Accordion.d.ts +56 -0
  4. package/dist/library/Accordion.d.ts.map +1 -0
  5. package/dist/library/Accordion.js +89 -0
  6. package/dist/library/Accordion.js.map +1 -0
  7. package/dist/library/Button.d.ts +25 -3
  8. package/dist/library/Button.d.ts.map +1 -1
  9. package/dist/library/Button.js +31 -3
  10. package/dist/library/Button.js.map +1 -1
  11. package/dist/library/Card.d.ts +31 -0
  12. package/dist/library/Card.d.ts.map +1 -0
  13. package/dist/library/Card.js +69 -0
  14. package/dist/library/Card.js.map +1 -0
  15. package/dist/library/Checkbox.d.ts +13 -0
  16. package/dist/library/Checkbox.d.ts.map +1 -0
  17. package/dist/library/Checkbox.js +77 -0
  18. package/dist/library/Checkbox.js.map +1 -0
  19. package/dist/library/Collapsible.d.ts +32 -0
  20. package/dist/library/Collapsible.d.ts.map +1 -0
  21. package/dist/library/Collapsible.js +99 -0
  22. package/dist/library/Collapsible.js.map +1 -0
  23. package/dist/library/Dialog.d.ts +50 -0
  24. package/dist/library/Dialog.d.ts.map +1 -0
  25. package/dist/library/Dialog.js +215 -0
  26. package/dist/library/Dialog.js.map +1 -0
  27. package/dist/library/Field.d.ts +68 -0
  28. package/dist/library/Field.d.ts.map +1 -0
  29. package/dist/library/Field.js +114 -0
  30. package/dist/library/Field.js.map +1 -0
  31. package/dist/library/Input.d.ts +10 -0
  32. package/dist/library/Input.d.ts.map +1 -0
  33. package/dist/library/Input.js +51 -0
  34. package/dist/library/Input.js.map +1 -0
  35. package/dist/library/Link.d.ts +27 -0
  36. package/dist/library/Link.d.ts.map +1 -0
  37. package/dist/library/Link.js +50 -0
  38. package/dist/library/Link.js.map +1 -0
  39. package/dist/library/RadioGroup.d.ts +27 -0
  40. package/dist/library/RadioGroup.d.ts.map +1 -0
  41. package/dist/library/RadioGroup.js +103 -0
  42. package/dist/library/RadioGroup.js.map +1 -0
  43. package/dist/library/ThemeScope.d.ts +10 -0
  44. package/dist/library/ThemeScope.d.ts.map +1 -0
  45. package/dist/library/ThemeScope.js +41 -0
  46. package/dist/library/ThemeScope.js.map +1 -0
  47. package/dist/library/actionStyles.d.ts +11 -0
  48. package/dist/library/actionStyles.d.ts.map +1 -0
  49. package/dist/library/actionStyles.js +75 -0
  50. package/dist/library/actionStyles.js.map +1 -0
  51. package/dist/library/cn.d.ts +1 -2
  52. package/dist/library/cn.d.ts.map +1 -1
  53. package/dist/library/cn.js +1 -8
  54. package/dist/library/cn.js.map +1 -1
  55. package/dist/library/color/colorFamilies.d.ts +3 -0
  56. package/dist/library/color/colorFamilies.d.ts.map +1 -0
  57. package/dist/library/color/colorFamilies.js +20 -0
  58. package/dist/library/color/colorFamilies.js.map +1 -0
  59. package/dist/library/color/generateColorWall.d.ts +54 -0
  60. package/dist/library/color/generateColorWall.d.ts.map +1 -0
  61. package/dist/library/color/generateColorWall.js +231 -0
  62. package/dist/library/color/generateColorWall.js.map +1 -0
  63. package/dist/library/color/index.d.ts +5 -0
  64. package/dist/library/color/index.d.ts.map +1 -0
  65. package/dist/library/color/index.js +3 -0
  66. package/dist/library/color/index.js.map +1 -0
  67. package/dist/library/color/oklch.d.ts +17 -0
  68. package/dist/library/color/oklch.d.ts.map +1 -0
  69. package/dist/library/color/oklch.js +79 -0
  70. package/dist/library/color/oklch.js.map +1 -0
  71. package/dist/library/color/recommendColorPalette.d.ts +65 -0
  72. package/dist/library/color/recommendColorPalette.d.ts.map +1 -0
  73. package/dist/library/color/recommendColorPalette.js +263 -0
  74. package/dist/library/color/recommendColorPalette.js.map +1 -0
  75. package/dist/library/controlStyles.d.ts +5 -0
  76. package/dist/library/controlStyles.d.ts.map +1 -0
  77. package/dist/library/controlStyles.js +15 -0
  78. package/dist/library/controlStyles.js.map +1 -0
  79. package/dist/library/index.d.ts +30 -1
  80. package/dist/library/index.d.ts.map +1 -1
  81. package/dist/library/index.js +14 -0
  82. package/dist/library/index.js.map +1 -1
  83. package/dist/library/internal/events.d.ts +8 -0
  84. package/dist/library/internal/events.d.ts.map +1 -0
  85. package/dist/library/internal/events.js +13 -0
  86. package/dist/library/internal/events.js.map +1 -0
  87. package/dist/library/internal/ids.d.ts +3 -0
  88. package/dist/library/internal/ids.d.ts.map +1 -0
  89. package/dist/library/internal/ids.js +6 -0
  90. package/dist/library/internal/ids.js.map +1 -0
  91. package/dist/library/internal/selection.d.ts +5 -0
  92. package/dist/library/internal/selection.d.ts.map +1 -0
  93. package/dist/library/internal/selection.js +18 -0
  94. package/dist/library/internal/selection.js.map +1 -0
  95. package/dist/library/presentation.d.ts +18 -0
  96. package/dist/library/presentation.d.ts.map +1 -0
  97. package/dist/library/presentation.js +2 -0
  98. package/dist/library/presentation.js.map +1 -0
  99. package/dist/library/react/useComposedRefs.d.ts +4 -0
  100. package/dist/library/react/useComposedRefs.d.ts.map +1 -0
  101. package/dist/library/react/useComposedRefs.js +28 -0
  102. package/dist/library/react/useComposedRefs.js.map +1 -0
  103. package/dist/library/react/useControllableState.d.ts +16 -0
  104. package/dist/library/react/useControllableState.d.ts.map +1 -0
  105. package/dist/library/react/useControllableState.js +29 -0
  106. package/dist/library/react/useControllableState.js.map +1 -0
  107. package/dist/library/react/useNativeOwner.d.ts +17 -0
  108. package/dist/library/react/useNativeOwner.d.ts.map +1 -0
  109. package/dist/library/react/useNativeOwner.js +17 -0
  110. package/dist/library/react/useNativeOwner.js.map +1 -0
  111. package/dist/library/reset.css +1 -0
  112. package/dist/library/styles.css +2 -1
  113. package/dist/library/themes/components.d.ts +217 -0
  114. package/dist/library/themes/components.d.ts.map +1 -0
  115. package/dist/library/themes/components.js +229 -0
  116. package/dist/library/themes/components.js.map +1 -0
  117. package/dist/library/themes/default.d.ts +2 -0
  118. package/dist/library/themes/default.d.ts.map +1 -0
  119. package/dist/library/themes/default.js +4 -0
  120. package/dist/library/themes/default.js.map +1 -0
  121. package/dist/library/themes/defineTheme.d.ts +33 -0
  122. package/dist/library/themes/defineTheme.d.ts.map +1 -0
  123. package/dist/library/themes/defineTheme.js +98 -0
  124. package/dist/library/themes/defineTheme.js.map +1 -0
  125. package/dist/library/themes/expressive.d.ts +2 -0
  126. package/dist/library/themes/expressive.d.ts.map +1 -0
  127. package/dist/library/themes/expressive.js +132 -0
  128. package/dist/library/themes/expressive.js.map +1 -0
  129. package/dist/library/themes/glass.d.ts +2 -0
  130. package/dist/library/themes/glass.d.ts.map +1 -0
  131. package/dist/library/themes/glass.js +132 -0
  132. package/dist/library/themes/glass.js.map +1 -0
  133. package/dist/library/themes/index.d.ts +18 -0
  134. package/dist/library/themes/index.d.ts.map +1 -0
  135. package/dist/library/themes/index.js +23 -0
  136. package/dist/library/themes/index.js.map +1 -0
  137. package/dist/library/themes/jelly.d.ts +2 -0
  138. package/dist/library/themes/jelly.d.ts.map +1 -0
  139. package/dist/library/themes/jelly.js +130 -0
  140. package/dist/library/themes/jelly.js.map +1 -0
  141. package/dist/library/themes/preset-values.d.ts +4 -0
  142. package/dist/library/themes/preset-values.d.ts.map +1 -0
  143. package/dist/library/themes/preset-values.js +5 -0
  144. package/dist/library/themes/preset-values.js.map +1 -0
  145. package/dist/library/themes/radiant.d.ts +2 -0
  146. package/dist/library/themes/radiant.d.ts.map +1 -0
  147. package/dist/library/themes/radiant.js +129 -0
  148. package/dist/library/themes/radiant.js.map +1 -0
  149. package/dist/library/themes/sharp-3d.d.ts +2 -0
  150. package/dist/library/themes/sharp-3d.d.ts.map +1 -0
  151. package/dist/library/themes/sharp-3d.js +142 -0
  152. package/dist/library/themes/sharp-3d.js.map +1 -0
  153. package/dist/library/themes/soft-squircle.d.ts +2 -0
  154. package/dist/library/themes/soft-squircle.d.ts.map +1 -0
  155. package/dist/library/themes/soft-squircle.js +131 -0
  156. package/dist/library/themes/soft-squircle.js.map +1 -0
  157. package/dist/library/themes/themeDocument.d.ts +16 -0
  158. package/dist/library/themes/themeDocument.d.ts.map +1 -0
  159. package/dist/library/themes/themeDocument.js +307 -0
  160. package/dist/library/themes/themeDocument.js.map +1 -0
  161. package/dist/library/themes/themeDocumentTypes.d.ts +69 -0
  162. package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -0
  163. package/dist/library/themes/themeDocumentTypes.js +2 -0
  164. package/dist/library/themes/themeDocumentTypes.js.map +1 -0
  165. package/dist/library/themes/ticket.d.ts +2 -0
  166. package/dist/library/themes/ticket.d.ts.map +1 -0
  167. package/dist/library/themes/ticket.js +141 -0
  168. package/dist/library/themes/ticket.js.map +1 -0
  169. package/dist/library/themes/tokens.d.ts +100 -0
  170. package/dist/library/themes/tokens.d.ts.map +1 -0
  171. package/dist/library/themes/tokens.js +171 -0
  172. package/dist/library/themes/tokens.js.map +1 -0
  173. package/dist/library/themes/types.d.ts +2 -0
  174. package/dist/library/themes/types.d.ts.map +1 -0
  175. package/dist/library/themes/types.js +2 -0
  176. package/dist/library/themes/types.js.map +1 -0
  177. package/dist/library/themes/updateThemeAppearance.d.ts +29 -0
  178. package/dist/library/themes/updateThemeAppearance.d.ts.map +1 -0
  179. package/dist/library/themes/updateThemeAppearance.js +138 -0
  180. package/dist/library/themes/updateThemeAppearance.js.map +1 -0
  181. package/docs/accessibility.md +189 -0
  182. package/docs/system.md +231 -0
  183. package/docs/theming.md +804 -0
  184. package/package.json +34 -10
  185. package/src/Accordion.tsx +235 -0
  186. package/src/Button.tsx +95 -15
  187. package/src/Card.tsx +143 -0
  188. package/src/Checkbox.tsx +189 -0
  189. package/src/Collapsible.tsx +193 -0
  190. package/src/Dialog.tsx +333 -0
  191. package/src/Field.tsx +293 -0
  192. package/src/Input.tsx +82 -0
  193. package/src/Link.tsx +95 -0
  194. package/src/RadioGroup.tsx +255 -0
  195. package/src/ThemeScope.tsx +64 -0
  196. package/src/actionStyles.ts +90 -0
  197. package/src/cn.ts +1 -10
  198. package/src/color/colorFamilies.ts +19 -0
  199. package/src/color/generateColorWall.ts +358 -0
  200. package/src/color/index.ts +11 -0
  201. package/src/color/oklch.ts +95 -0
  202. package/src/color/recommendColorPalette.ts +375 -0
  203. package/src/controlStyles.ts +19 -0
  204. package/src/index.ts +130 -1
  205. package/src/internal/events.ts +17 -0
  206. package/src/internal/ids.ts +5 -0
  207. package/src/internal/selection.ts +20 -0
  208. package/src/presentation.ts +12 -0
  209. package/src/react/useComposedRefs.ts +32 -0
  210. package/src/react/useControllableState.ts +50 -0
  211. package/src/react/useNativeOwner.ts +33 -0
  212. package/src/styles.css +2 -14
  213. package/src/themes/baseline.css +116 -0
  214. package/src/themes/components.ts +249 -0
  215. package/src/themes/default.ts +4 -0
  216. package/src/themes/defineTheme.ts +145 -0
  217. package/src/themes/expressive.ts +132 -0
  218. package/src/themes/glass.ts +135 -0
  219. package/src/themes/index.ts +57 -0
  220. package/src/themes/jelly.ts +130 -0
  221. package/src/themes/preset-values.ts +5 -0
  222. package/src/themes/radiant.ts +129 -0
  223. package/src/themes/sharp-3d.ts +142 -0
  224. package/src/themes/soft-squircle.ts +131 -0
  225. package/src/themes/themeDocument.ts +340 -0
  226. package/src/themes/themeDocumentTypes.ts +76 -0
  227. package/src/themes/ticket.ts +141 -0
  228. package/src/themes/tokens.ts +262 -0
  229. package/src/themes/types.ts +10 -0
  230. 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).