@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
@@ -0,0 +1,375 @@
1
+ import type { SharedTokens } from '../themes/tokens.js'
2
+ import { freezeTree } from '../themes/tokens.js'
3
+ import { parseThemeDocument } from '../themes/themeDocument.js'
4
+ import type { ThemeColorSection, ThemePalette } from '../themes/themeDocumentTypes.js'
5
+ import type { ColorWall } from './generateColorWall.js'
6
+ import { colorFamilies } from './colorFamilies.js'
7
+ import { hueDifference, measureHex } from './oklch.js'
8
+
9
+ export type WorkingPaletteRole =
10
+ | 'primary'
11
+ | 'support'
12
+ | 'neutral'
13
+ | 'success'
14
+ | 'warning'
15
+ | 'danger'
16
+ type Mode = 'light' | 'dark'
17
+ type Colors = Readonly<SharedTokens['color']>
18
+ export type PaletteModeColors = Colors & { readonly canvas: string }
19
+ export interface ColorPaletteOptions {
20
+ readonly version?: 1
21
+ /** Existing wall palette IDs; originals and swatches are never rewritten. */
22
+ readonly working?: Readonly<Partial<Record<WorkingPaletteRole, string>>>
23
+ /** Explicit opaque sRGB overrides are retained, even when contrast fails. */
24
+ readonly modes?: {
25
+ readonly light?: Partial<PaletteModeColors>
26
+ readonly dark?: Partial<PaletteModeColors>
27
+ }
28
+ }
29
+ export interface PaletteColorPair {
30
+ readonly background: string
31
+ readonly foreground: string
32
+ }
33
+ export interface PaletteContrastCheck {
34
+ readonly mode: Mode
35
+ readonly foregroundRole: string
36
+ readonly backgroundRole: string
37
+ readonly foreground: string
38
+ readonly background: string
39
+ readonly ratio: number
40
+ /** null marks an inactive-control exception, not a passing contrast requirement. */
41
+ readonly minimum: 3 | 4.5 | null
42
+ readonly pass: boolean | null
43
+ readonly message: string
44
+ }
45
+ export interface ColorPalette {
46
+ readonly version: 1
47
+ readonly working: Readonly<
48
+ Record<
49
+ WorkingPaletteRole,
50
+ {
51
+ readonly paletteId: string
52
+ readonly light: PaletteColorPair
53
+ readonly dark: PaletteColorPair
54
+ }
55
+ >
56
+ >
57
+ readonly color: ThemeColorSection & {
58
+ readonly modes: { readonly light: Colors; readonly dark: Colors }
59
+ }
60
+ readonly surface: {
61
+ readonly modes: {
62
+ readonly light: { readonly canvas: string }
63
+ readonly dark: { readonly canvas: string }
64
+ }
65
+ }
66
+ readonly checks: readonly PaletteContrastCheck[]
67
+ readonly pass: boolean
68
+ }
69
+ const workingRoles = ['primary', 'support', 'neutral', 'success', 'warning', 'danger'] as const
70
+ const colorRoles = [
71
+ 'surface',
72
+ 'foreground',
73
+ 'mutedForeground',
74
+ 'border',
75
+ 'placeholder',
76
+ 'disabledBackground',
77
+ 'disabledBorder',
78
+ 'invalid',
79
+ 'focus',
80
+ 'accent',
81
+ 'accentForeground',
82
+ 'neutral',
83
+ 'neutralForeground',
84
+ 'warning',
85
+ 'warningForeground',
86
+ 'danger',
87
+ 'dangerForeground'
88
+ ] as const
89
+ const modes = ['light', 'dark'] as const
90
+ const hex = /^#[0-9a-f]{6}$/i
91
+ function object(value: unknown, path: string): asserts value is object {
92
+ if (!value || typeof value !== 'object' || Array.isArray(value))
93
+ throw new TypeError(`${path} must be an object.`)
94
+ }
95
+ function keys(value: object, allowed: readonly string[], path: string) {
96
+ for (const key of Object.keys(value))
97
+ if (!allowed.includes(key)) throw new TypeError(`Unknown ${path}.${key}.`)
98
+ }
99
+ function opaque(value: unknown, path: string): asserts value is string {
100
+ if (typeof value !== 'string' || !hex.test(value))
101
+ throw new TypeError(`${path} must be an opaque six-digit sRGB hex color.`)
102
+ }
103
+ function luminance(value: string) {
104
+ const [r, g, b] = [1, 3, 5]
105
+ .map(i => parseInt(value.slice(i, i + 2), 16) / 255)
106
+ .map(n => (n <= 0.04045 ? n / 12.92 : ((n + 0.055) / 1.055) ** 2.4))
107
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b
108
+ }
109
+ function contrast(a: string, b: string) {
110
+ const x = luminance(a),
111
+ y = luminance(b)
112
+ return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05)
113
+ }
114
+ const swatches = (palette: ThemePalette) => palette.swatches.map(s => s.value)
115
+ function choose(
116
+ values: readonly string[],
117
+ backgrounds: readonly string[],
118
+ minimum: number,
119
+ target: number
120
+ ): string {
121
+ const score = (value: string) => Math.min(...backgrounds.map(bg => contrast(value, bg)))
122
+ const valid = values.filter(value => score(value) >= minimum)
123
+ return valid.length
124
+ ? valid.reduce((a, b) =>
125
+ Math.abs(measureHex(a).L - target) <= Math.abs(measureHex(b).L - target) ? a : b
126
+ )
127
+ : values.reduce((a, b) => (score(a) >= score(b) ? a : b))
128
+ }
129
+ function pair(
130
+ values: readonly string[],
131
+ inks: readonly string[],
132
+ backgrounds: readonly string[],
133
+ target: number,
134
+ boundary: boolean,
135
+ fixedBackground?: string,
136
+ fixedForeground?: string,
137
+ source?: ReturnType<typeof measureHex>
138
+ ): PaletteColorPair {
139
+ const candidates = fixedBackground === undefined ? values : [fixedBackground]
140
+ const foregrounds = fixedForeground === undefined ? inks : [fixedForeground]
141
+ const ink = (background: string) =>
142
+ foregrounds.reduce((a, b) => (contrast(a, background) >= contrast(b, background) ? a : b))
143
+ const acceptable = candidates.filter(
144
+ bg =>
145
+ contrast(ink(bg), bg) >= 4.5 &&
146
+ (!boundary || backgrounds.every(surface => contrast(bg, surface) >= 3))
147
+ )
148
+ const pool = acceptable.length ? acceptable : candidates
149
+ // Perceptual distance includes both lightness and the chromatic axes. A caller's
150
+ // explicit working-family choice still bounds the candidate pool.
151
+ const distance = (value: string) => {
152
+ const color = measureHex(value)
153
+ if (!source) return Math.abs(color.L - target)
154
+ const radians = Math.PI / 180
155
+ return Math.hypot(
156
+ color.L - source.L,
157
+ color.C * Math.cos(color.h * radians) - source.C * Math.cos(source.h * radians),
158
+ color.C * Math.sin(color.h * radians) - source.C * Math.sin(source.h * radians)
159
+ )
160
+ }
161
+ const background = pool.reduce((a, b) => (distance(a) <= distance(b) ? a : b))
162
+ return { background, foreground: ink(background) }
163
+ }
164
+
165
+ /** Recommend a six-family working set and audit actual opaque semantic pairs. */
166
+ export function recommendColorPalette(
167
+ wall: ColorWall,
168
+ options: ColorPaletteOptions = {}
169
+ ): ColorPalette {
170
+ object(wall, 'colorWall')
171
+ object(wall.color, 'colorWall.color')
172
+ object(wall.input, 'colorWall.input')
173
+ if (wall.input.version !== 1) throw new TypeError('colorWall.input.version must be 1.')
174
+ if (wall.color.brand?.gamut !== 'srgb')
175
+ throw new TypeError('colorWall.color.brand.gamut must be srgb for semantic mapping version 1.')
176
+ const parsed = parseThemeDocument({
177
+ kind: 'radiant-theme-sections',
178
+ version: 1,
179
+ sections: { color: wall.color }
180
+ })
181
+ const color = parsed.sections.color!
182
+ if (!color.brand || !color.palettes?.length)
183
+ throw new TypeError('colorWall.color requires an original brand and populated palettes.')
184
+ opaque(color.brand.value, 'colorWall.color.brand.value')
185
+ for (const palette of color.palettes) {
186
+ const stops = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
187
+ if (
188
+ palette.swatches.length !== stops.length ||
189
+ palette.swatches.some((s, i) => s.stop !== stops[i])
190
+ )
191
+ throw new TypeError(
192
+ `colorWall.${palette.id} must contain the eleven ordered generator stops (50–950).`
193
+ )
194
+ for (const swatch of palette.swatches)
195
+ opaque(swatch.value, `colorWall.${palette.id}.${swatch.stop}`)
196
+ }
197
+ object(options, 'colorPalette')
198
+ keys(options, ['version', 'working', 'modes'], 'colorPalette')
199
+ if (options.version !== undefined && options.version !== 1)
200
+ throw new TypeError('Unsupported colorPalette.version; expected 1.')
201
+ if (options.working !== undefined) {
202
+ object(options.working, 'colorPalette.working')
203
+ keys(options.working, workingRoles, 'colorPalette.working')
204
+ for (const [role, id] of Object.entries(options.working))
205
+ if (id !== undefined && typeof id !== 'string')
206
+ throw new TypeError(`colorPalette.working.${role} must be a palette ID.`)
207
+ }
208
+ if (options.modes !== undefined) {
209
+ object(options.modes, 'colorPalette.modes')
210
+ keys(options.modes, modes, 'colorPalette.modes')
211
+ }
212
+ for (const mode of modes)
213
+ if (options.modes?.[mode] !== undefined) {
214
+ object(options.modes[mode], `colorPalette.modes.${mode}`)
215
+ keys(options.modes[mode], [...colorRoles, 'canvas'], `colorPalette.modes.${mode}`)
216
+ for (const [key, value] of Object.entries(options.modes[mode]))
217
+ if (value !== undefined) opaque(value, `colorPalette.modes.${mode}.${key}`)
218
+ }
219
+ function palette(id: string): ThemePalette {
220
+ const found = color.palettes!.find(p => p.id === id)
221
+ if (!found)
222
+ throw new TypeError(
223
+ `Unknown working palette ID: ${String(id)}. Choose one of: ${color.palettes!.map(p => p.id).join(', ')}.`
224
+ )
225
+ return found
226
+ }
227
+ const primary = palette(options.working?.primary ?? 'brand')
228
+ if (!Number.isFinite(wall.input.neutralHue) || !Number.isFinite(wall.input.hueAlignment))
229
+ throw new TypeError('colorWall.input must contain finite neutralHue and hueAlignment controls.')
230
+ const source = measureHex(color.brand.value)
231
+ const sourceHue = source.C < 0.02 ? wall.input.neutralHue : source.h
232
+ const nearest = colorFamilies.reduce((a, b) =>
233
+ Math.abs(hueDifference(sourceHue, a[1])) < Math.abs(hueDifference(sourceHue, b[1])) ? a : b
234
+ )
235
+ const rotation = hueDifference(sourceHue, nearest[1]) * wall.input.hueAlignment
236
+ function hueOf(p: ThemePalette) {
237
+ const sample = measureHex(p.swatches[Math.floor(p.swatches.length / 2)].value)
238
+ const nominal = colorFamilies.find(([name]) => name.toLowerCase() === p.id)
239
+ return sample.C >= 0.02 ? sample.h : nominal ? nominal[1] + rotation : sourceHue
240
+ }
241
+ const hue = hueOf(primary)
242
+ const supporting = color.palettes.filter(
243
+ p => p.id !== 'brand' && p.id !== 'neutral' && p.id !== primary.id
244
+ )
245
+ if (!supporting.length) throw new TypeError('colorWall requires supporting hue families.')
246
+ const support = supporting.reduce((a, b) => {
247
+ return Math.abs(hueDifference(hueOf(a), hue + 150)) <=
248
+ Math.abs(hueDifference(hueOf(b), hue + 150))
249
+ ? a
250
+ : b
251
+ })
252
+ const selected = {
253
+ primary: primary.id,
254
+ support: support.id,
255
+ neutral: 'neutral',
256
+ success: 'emerald',
257
+ warning: 'amber',
258
+ danger: 'red',
259
+ ...Object.fromEntries(
260
+ Object.entries(options.working ?? {}).filter(([, value]) => value !== undefined)
261
+ )
262
+ }
263
+ for (const id of Object.values(selected)) palette(id)
264
+ const working = {} as Record<
265
+ WorkingPaletteRole,
266
+ { paletteId: string; light: PaletteColorPair; dark: PaletteColorPair }
267
+ >
268
+ for (const role of workingRoles)
269
+ working[role] = {
270
+ paletteId: selected[role],
271
+ light: { background: '', foreground: '' },
272
+ dark: { background: '', foreground: '' }
273
+ }
274
+ const mapped = {} as Record<Mode, SharedTokens['color']>
275
+ const canvases = {} as Record<Mode, { canvas: string }>
276
+ const checks: PaletteContrastCheck[] = []
277
+ for (const mode of modes) {
278
+ const light = mode === 'light',
279
+ override = options.modes?.[mode] ?? {}
280
+ const neutrals = swatches(palette(selected.neutral))
281
+ const canvas = override.canvas ?? neutrals[light ? 0 : neutrals.length - 1]
282
+ const surface = override.surface ?? neutrals[light ? 1 : neutrals.length - 2]
283
+ const backgrounds = [canvas, surface]
284
+ const inks = [...neutrals, '#000000', '#FFFFFF']
285
+ const foreground = override.foreground ?? choose(inks, backgrounds, 7, light ? 0.21 : 0.985)
286
+ const muted = override.mutedForeground ?? choose(inks, backgrounds, 4.5, light ? 0.48 : 0.75)
287
+ const fills: Record<WorkingPaletteRole, [string | undefined, string | undefined]> = {
288
+ primary: [override.accent, override.accentForeground],
289
+ neutral: [override.neutral, override.neutralForeground],
290
+ warning: [override.warning, override.warningForeground],
291
+ danger: [override.danger, override.dangerForeground],
292
+ support: [undefined, undefined],
293
+ success: [undefined, undefined]
294
+ }
295
+ for (const role of workingRoles) {
296
+ working[role][mode] = pair(
297
+ swatches(palette(selected[role])),
298
+ inks,
299
+ backgrounds,
300
+ role === 'neutral' ? (light ? 0.93 : 0.43) : light ? 0.62 : 0.75,
301
+ role === 'primary',
302
+ ...fills[role],
303
+ role === 'primary' ? source : undefined
304
+ )
305
+ }
306
+ const colors: SharedTokens['color'] = {
307
+ surface,
308
+ foreground,
309
+ mutedForeground: muted,
310
+ placeholder: override.placeholder ?? muted,
311
+ border: override.border ?? choose(neutrals, backgrounds, 3, light ? 0.65 : 0.6),
312
+ focus: override.focus ?? choose(swatches(primary), backgrounds, 3, light ? 0.55 : 0.75),
313
+ invalid:
314
+ override.invalid ??
315
+ choose(swatches(palette(selected.danger)), backgrounds, 4.5, light ? 0.5 : 0.75),
316
+ disabledBackground: override.disabledBackground ?? neutrals[light ? 2 : neutrals.length - 3],
317
+ disabledBorder: override.disabledBorder ?? neutrals[light ? 3 : neutrals.length - 4],
318
+ accent: working.primary[mode].background,
319
+ accentForeground: working.primary[mode].foreground,
320
+ neutral: working.neutral[mode].background,
321
+ neutralForeground: working.neutral[mode].foreground,
322
+ warning: working.warning[mode].background,
323
+ warningForeground: working.warning[mode].foreground,
324
+ danger: working.danger[mode].background,
325
+ dangerForeground: working.danger[mode].foreground
326
+ }
327
+ mapped[mode] = colors
328
+ canvases[mode] = { canvas }
329
+ const values: Record<string, string> = {
330
+ ...colors,
331
+ canvas,
332
+ support: working.support[mode].background,
333
+ supportForeground: working.support[mode].foreground,
334
+ success: working.success[mode].background,
335
+ successForeground: working.success[mode].foreground
336
+ }
337
+ function check(fg: string, bg: string, minimum: 3 | 4.5 | null) {
338
+ const ratio = contrast(values[fg], values[bg]),
339
+ pass = minimum === null ? null : ratio >= minimum
340
+ checks.push({
341
+ mode,
342
+ foregroundRole: fg,
343
+ backgroundRole: bg,
344
+ foreground: values[fg],
345
+ background: values[bg],
346
+ ratio,
347
+ minimum,
348
+ pass,
349
+ message:
350
+ minimum === null
351
+ ? 'Inactive controls are exempt from minimum contrast; this token-pair ratio excludes component opacity/effects.'
352
+ : pass
353
+ ? ''
354
+ : `${fg} is ${ratio.toFixed(3)}:1 against ${bg}; requires ${minimum}:1 without rounding. Select another ${fg} shade or adjust ${bg}, then recheck the complete mode. The original brand and wall remain unchanged.`
355
+ })
356
+ }
357
+ for (const background of ['canvas', 'surface']) {
358
+ for (const foreground of ['foreground', 'mutedForeground', 'placeholder', 'invalid'])
359
+ check(foreground, background, 4.5)
360
+ for (const foreground of ['border', 'focus', 'accent']) check(foreground, background, 3)
361
+ }
362
+ for (const tone of ['accent', 'neutral', 'warning', 'danger', 'support', 'success'])
363
+ check(tone + 'Foreground', tone, 4.5)
364
+ check('mutedForeground', 'disabledBackground', null)
365
+ check('disabledBorder', 'surface', null)
366
+ }
367
+ return freezeTree({
368
+ version: 1 as const,
369
+ working,
370
+ color: { ...color, modes: mapped },
371
+ surface: { modes: canvases },
372
+ checks,
373
+ pass: checks.every(c => c.pass !== false)
374
+ })
375
+ }
@@ -0,0 +1,19 @@
1
+ import { cva } from 'class-variance-authority'
2
+
3
+ // Interactive boundaries need more contrast than passive surface dividers.
4
+ // Keep the derivation private so every control follows the same semantic palette.
5
+ export const controlBorderClass =
6
+ '[--_rad-control-border:color-mix(in_oklch,var(--rad-color-border,oklch(0.885_0.005_286))_55%,var(--rad-color-foreground,oklch(0.21_0.006_286)))]'
7
+ export const controlMetrics = cva('', {
8
+ variants: {
9
+ controlSize: {
10
+ small:
11
+ '[--_rad-control-height:var(--rad-control-small-height,2rem)] [--_rad-control-padding:var(--rad-control-small-padding-inline,0.75rem)] [--_rad-control-font-size:var(--rad-control-small-font-size,0.8125rem)] [--_rad-control-indicator-size:var(--rad-control-small-indicator-size,1rem)]',
12
+ medium:
13
+ '[--_rad-control-height:var(--rad-control-medium-height,2.5rem)] [--_rad-control-padding:var(--rad-control-medium-padding-inline,1rem)] [--_rad-control-font-size:var(--rad-control-medium-font-size,0.875rem)] [--_rad-control-indicator-size:var(--rad-control-medium-indicator-size,1.125rem)]',
14
+ large:
15
+ '[--_rad-control-height:var(--rad-control-large-height,3rem)] [--_rad-control-padding:var(--rad-control-large-padding-inline,1.375rem)] [--_rad-control-font-size:var(--rad-control-large-font-size,0.9375rem)] [--_rad-control-indicator-size:var(--rad-control-large-indicator-size,1.25rem)]'
16
+ }
17
+ },
18
+ defaultVariants: { controlSize: 'medium' }
19
+ })
package/src/index.ts CHANGED
@@ -1,2 +1,131 @@
1
1
  export { Button } from './Button.js'
2
- export type { ButtonProps } from './Button.js'
2
+ export { Link } from './Link.js'
3
+ export type { LinkProps, LinkRenderProps, LinkVariant } from './Link.js'
4
+ export { Field, useField } from './Field.js'
5
+ export type { FieldControlProps, FieldLayout, FieldProps, FieldState } from './Field.js'
6
+ export { Input } from './Input.js'
7
+ export type { InputProps } from './Input.js'
8
+ export { Checkbox } from './Checkbox.js'
9
+ export type { CheckboxProps } from './Checkbox.js'
10
+ export { Radio, RadioGroup } from './RadioGroup.js'
11
+ export type { RadioGroupProps, RadioProps } from './RadioGroup.js'
12
+ export {
13
+ Dialog,
14
+ DialogClose,
15
+ DialogContent,
16
+ DialogDescription,
17
+ DialogTitle,
18
+ DialogTrigger,
19
+ useDialog
20
+ } from './Dialog.js'
21
+ export type {
22
+ DialogCloseProps,
23
+ DialogContentProps,
24
+ DialogDescriptionProps,
25
+ DialogProps,
26
+ DialogRenderProps,
27
+ DialogState,
28
+ DialogTitleProps,
29
+ DialogTriggerProps
30
+ } from './Dialog.js'
31
+ export {
32
+ Collapsible,
33
+ CollapsibleContent,
34
+ CollapsibleTrigger,
35
+ useCollapsible
36
+ } from './Collapsible.js'
37
+ export type {
38
+ CollapsibleContentProps,
39
+ CollapsibleProps,
40
+ CollapsibleState,
41
+ CollapsibleTriggerProps
42
+ } from './Collapsible.js'
43
+ export {
44
+ Accordion,
45
+ AccordionContent,
46
+ AccordionItem,
47
+ AccordionTrigger,
48
+ useAccordion
49
+ } from './Accordion.js'
50
+ export type {
51
+ AccordionContentProps,
52
+ AccordionHeadingLevel,
53
+ AccordionItemProps,
54
+ AccordionProps,
55
+ AccordionState,
56
+ AccordionTriggerProps,
57
+ AccordionValue
58
+ } from './Accordion.js'
59
+ export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from './Card.js'
60
+ export type {
61
+ CardContentProps,
62
+ CardDescriptionProps,
63
+ CardFooterProps,
64
+ CardHeaderProps,
65
+ CardHeadingLevel,
66
+ CardProps,
67
+ CardTitleProps
68
+ } from './Card.js'
69
+ export {
70
+ defineTheme,
71
+ updateThemeAppearance,
72
+ themes,
73
+ radiant,
74
+ defaultTheme,
75
+ soft,
76
+ expressive,
77
+ glass,
78
+ sharp,
79
+ jelly,
80
+ ticket
81
+ } from './themes/index.js'
82
+ export type {
83
+ SharedTokens,
84
+ ThemeAppearanceSettings,
85
+ ThemeGeometrySettings,
86
+ Theme,
87
+ ThemeComponentOverrides,
88
+ ThemeDefinition,
89
+ ThemeLayer,
90
+ ThemeMode,
91
+ ThemeStyle,
92
+ ThemeTokens
93
+ } from './themes/index.js'
94
+ export { ThemeScope } from './ThemeScope.js'
95
+ export type { ThemeScopeProps } from './ThemeScope.js'
96
+ export type { ButtonProps, ButtonRenderProps, ButtonVariant } from './Button.js'
97
+ export type { ControlSize, Tone } from './presentation.js'
98
+
99
+ export {
100
+ defineThemeDocument,
101
+ parseThemeDocument,
102
+ compileThemeDocument,
103
+ updateThemeDocument,
104
+ exportThemeSections,
105
+ themeDocumentFromDefinition
106
+ } from './themes/index.js'
107
+ export type {
108
+ ThemeDocument,
109
+ ThemeSectionExport,
110
+ ThemeSections,
111
+ ThemeSectionName,
112
+ ThemeSection,
113
+ ThemeColorSection,
114
+ ThemeColorStop,
115
+ ThemeBrandSource,
116
+ ThemePalette,
117
+ ThemeTypographySection,
118
+ ThemeFontMetadata
119
+ } from './themes/index.js'
120
+
121
+ export { generateColorWall, colorCalibrationPresets } from './color/index.js'
122
+ export type { ColorWall, ColorWallInput, ColorCalibrationPreset } from './color/index.js'
123
+ export { recommendColorPalette } from './color/index.js'
124
+ export type {
125
+ ColorPalette,
126
+ ColorPaletteOptions,
127
+ PaletteModeColors,
128
+ PaletteColorPair,
129
+ PaletteContrastCheck,
130
+ WorkingPaletteRole
131
+ } from './color/index.js'
@@ -0,0 +1,17 @@
1
+ type CancellableEvent = { defaultPrevented: boolean; preventDefault(): void }
2
+
3
+ /** Activation guards precede the consumer, who can cancel the library action. */
4
+ export function composeAction<Event extends CancellableEvent>(
5
+ consumer: ((event: Event) => void) | undefined,
6
+ action: ((event: Event) => void) | undefined,
7
+ blocked?: (event: Event) => boolean
8
+ ) {
9
+ return (event: Event) => {
10
+ if (blocked?.(event)) {
11
+ event.preventDefault()
12
+ return
13
+ }
14
+ consumer?.(event)
15
+ if (!event.defaultPrevented) action?.(event)
16
+ }
17
+ }
@@ -0,0 +1,5 @@
1
+ /** Preserve owned relationships first, then append each external ID once. */
2
+ export function joinIds(...parts: Array<string | undefined>) {
3
+ const ids = new Set(parts.flatMap(part => part?.split(/\s+/) ?? []).filter(Boolean))
4
+ return ids.size > 0 ? [...ids].join(' ') : undefined
5
+ }
@@ -0,0 +1,20 @@
1
+ export type Selection = string | null | string[]
2
+
3
+ export function isItemOpen(value: Selection, item: string) {
4
+ return Array.isArray(value) ? value.includes(item) : value === item
5
+ }
6
+
7
+ export function sameSelection(left: Selection, right: Selection) {
8
+ if (Array.isArray(left) && Array.isArray(right)) {
9
+ return left.length === right.length && left.every((item, index) => item === right[index])
10
+ }
11
+ return left === right
12
+ }
13
+
14
+ export function nextSelection(current: Selection, item: string, open: boolean): Selection {
15
+ if (Array.isArray(current)) {
16
+ if (open) return current.includes(item) ? current : [...current, item]
17
+ return current.filter(value => value !== item)
18
+ }
19
+ return open ? item : current === item ? null : current
20
+ }
@@ -0,0 +1,12 @@
1
+ import type { VariantProps } from 'class-variance-authority'
2
+ import type { actionVariants } from './actionStyles.js'
3
+ import type { ThemeStyle } from './themes/defineTheme.js'
4
+
5
+ type ActionPresentation = VariantProps<typeof actionVariants>
6
+
7
+ export type ButtonVariant = NonNullable<ActionPresentation['variant']>
8
+ export type Tone = NonNullable<ActionPresentation['tone']>
9
+ export type ControlSize = 'small' | 'medium' | 'large'
10
+
11
+ export type PartStyle = { className?: string; style?: ThemeStyle }
12
+ export type ControlParts = { wrapper?: PartStyle; label?: PartStyle; indicator?: PartStyle }
@@ -0,0 +1,32 @@
1
+ 'use client'
2
+
3
+ import { useMemo, type Ref, type RefCallback } from 'react'
4
+
5
+ /** Compose library and caller refs without discarding React callback cleanup. */
6
+ export function useComposedRefs<Node>(
7
+ libraryRef: Ref<Node> | undefined,
8
+ callerRef: Ref<Node> | undefined
9
+ ): RefCallback<Node> {
10
+ return useMemo(
11
+ () => node => {
12
+ const cleanups = [libraryRef, callerRef].map(ref => {
13
+ if (typeof ref === 'function') {
14
+ const cleanup = ref(node)
15
+ return typeof cleanup === 'function'
16
+ ? cleanup
17
+ : () => {
18
+ ref(null)
19
+ }
20
+ }
21
+ if (ref) ref.current = node
22
+ return () => {
23
+ if (ref) ref.current = null
24
+ }
25
+ })
26
+ return () => {
27
+ for (const cleanup of cleanups) cleanup()
28
+ }
29
+ },
30
+ [libraryRef, callerRef]
31
+ )
32
+ }
@@ -0,0 +1,50 @@
1
+ 'use client'
2
+
3
+ import { useRef, useState } from 'react'
4
+
5
+ type StateOptions<Value> = {
6
+ name: string
7
+ value: Value | undefined
8
+ defaultValue: Value | undefined
9
+ initialValue: Value
10
+ onChange?: (value: Value) => void
11
+ equal?: (left: Value, right: Value) => boolean
12
+ }
13
+
14
+ /** One owner per mount. Native observations are separate from change requests. */
15
+ export function useControllableState<Value>({
16
+ name,
17
+ value,
18
+ defaultValue,
19
+ initialValue,
20
+ onChange,
21
+ equal = Object.is
22
+ }: StateOptions<Value>) {
23
+ const [controlled] = useState(value !== undefined)
24
+ const [uncontrolled, setUncontrolled] = useState(() =>
25
+ defaultValue !== undefined ? defaultValue : initialValue
26
+ )
27
+ if (controlled !== (value !== undefined)) {
28
+ throw new TypeError(
29
+ `${name} cannot switch between controlled and uncontrolled state. Remount with a new key.`
30
+ )
31
+ }
32
+ if (value !== undefined && defaultValue !== undefined) {
33
+ throw new TypeError(`${name} accepts a controlled value or a default, not both.`)
34
+ }
35
+ const current = value !== undefined ? value : uncontrolled
36
+ const accepted = useRef(current)
37
+ const request = (update: Value | ((current: Value) => Value)) => {
38
+ const previous = controlled ? current : accepted.current
39
+ const next =
40
+ typeof update === 'function' ? (update as (current: Value) => Value)(previous) : update
41
+ if (equal(previous, next)) return
42
+ if (!controlled) {
43
+ // Deduplicate accepted requests in the same event before React commits.
44
+ accepted.current = next
45
+ setUncontrolled(next)
46
+ }
47
+ onChange?.(next)
48
+ }
49
+ return { value: current, request, controlled }
50
+ }