@cognitap/radiant 0.0.90 → 0.0.92

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 (169) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/library/a2ui/A2uiPlaceholder.d.ts +14 -0
  3. package/dist/library/a2ui/A2uiPlaceholder.d.ts.map +1 -0
  4. package/dist/library/a2ui/A2uiPlaceholder.js +44 -0
  5. package/dist/library/a2ui/A2uiPlaceholder.js.map +1 -0
  6. package/dist/library/a2ui/A2uiSurface.d.ts +33 -0
  7. package/dist/library/a2ui/A2uiSurface.d.ts.map +1 -0
  8. package/dist/library/a2ui/A2uiSurface.js +542 -0
  9. package/dist/library/a2ui/A2uiSurface.js.map +1 -0
  10. package/dist/library/a2ui/accessibility.d.ts +31 -0
  11. package/dist/library/a2ui/accessibility.d.ts.map +1 -0
  12. package/dist/library/a2ui/accessibility.js +108 -0
  13. package/dist/library/a2ui/accessibility.js.map +1 -0
  14. package/dist/library/a2ui/accessibilityRules.d.ts +28 -0
  15. package/dist/library/a2ui/accessibilityRules.d.ts.map +1 -0
  16. package/dist/library/a2ui/accessibilityRules.js +73 -0
  17. package/dist/library/a2ui/accessibilityRules.js.map +1 -0
  18. package/dist/library/a2ui/catalogGenerator.d.ts +29 -0
  19. package/dist/library/a2ui/catalogGenerator.d.ts.map +1 -0
  20. package/dist/library/a2ui/catalogGenerator.js +578 -0
  21. package/dist/library/a2ui/catalogGenerator.js.map +1 -0
  22. package/dist/library/a2ui/coerce.d.ts +16 -0
  23. package/dist/library/a2ui/coerce.d.ts.map +1 -0
  24. package/dist/library/a2ui/coerce.js +254 -0
  25. package/dist/library/a2ui/coerce.js.map +1 -0
  26. package/dist/library/a2ui/entries.d.ts +6 -0
  27. package/dist/library/a2ui/entries.d.ts.map +1 -0
  28. package/dist/library/a2ui/entries.js +277 -0
  29. package/dist/library/a2ui/entries.js.map +1 -0
  30. package/dist/library/a2ui/fixtures.d.ts +38 -0
  31. package/dist/library/a2ui/fixtures.d.ts.map +1 -0
  32. package/dist/library/a2ui/fixtures.js +389 -0
  33. package/dist/library/a2ui/fixtures.js.map +1 -0
  34. package/dist/library/a2ui/index.d.ts +17 -0
  35. package/dist/library/a2ui/index.d.ts.map +1 -0
  36. package/dist/library/a2ui/index.js +9 -0
  37. package/dist/library/a2ui/index.js.map +1 -0
  38. package/dist/library/a2ui/protocolErrors.d.ts +13 -0
  39. package/dist/library/a2ui/protocolErrors.d.ts.map +1 -0
  40. package/dist/library/a2ui/protocolErrors.js +48 -0
  41. package/dist/library/a2ui/protocolErrors.js.map +1 -0
  42. package/dist/library/a2ui/registry.d.ts +58 -0
  43. package/dist/library/a2ui/registry.d.ts.map +1 -0
  44. package/dist/library/a2ui/registry.js +128 -0
  45. package/dist/library/a2ui/registry.js.map +1 -0
  46. package/dist/library/a2ui/sanitize.d.ts +7 -0
  47. package/dist/library/a2ui/sanitize.d.ts.map +1 -0
  48. package/dist/library/a2ui/sanitize.js +54 -0
  49. package/dist/library/a2ui/sanitize.js.map +1 -0
  50. package/dist/library/a2ui/surfaceRuntime.d.ts +34 -0
  51. package/dist/library/a2ui/surfaceRuntime.d.ts.map +1 -0
  52. package/dist/library/a2ui/surfaceRuntime.js +284 -0
  53. package/dist/library/a2ui/surfaceRuntime.js.map +1 -0
  54. package/dist/library/catalog/actions.d.ts +40 -0
  55. package/dist/library/catalog/actions.d.ts.map +1 -0
  56. package/dist/library/catalog/actions.js +70 -0
  57. package/dist/library/catalog/actions.js.map +1 -0
  58. package/dist/library/catalog/coerce.d.ts +70 -0
  59. package/dist/library/catalog/coerce.d.ts.map +1 -0
  60. package/dist/library/catalog/coerce.js +332 -0
  61. package/dist/library/catalog/coerce.js.map +1 -0
  62. package/dist/library/catalog/index.d.ts +9 -0
  63. package/dist/library/catalog/index.d.ts.map +1 -0
  64. package/dist/library/catalog/index.js +6 -0
  65. package/dist/library/catalog/index.js.map +1 -0
  66. package/dist/library/catalog/radiantCatalog.d.ts +9 -0
  67. package/dist/library/catalog/radiantCatalog.d.ts.map +1 -0
  68. package/dist/library/catalog/radiantCatalog.js +902 -0
  69. package/dist/library/catalog/radiantCatalog.js.map +1 -0
  70. package/dist/library/catalog/types.d.ts +113 -0
  71. package/dist/library/catalog/types.d.ts.map +1 -0
  72. package/dist/library/catalog/types.js +27 -0
  73. package/dist/library/catalog/types.js.map +1 -0
  74. package/dist/library/catalog/validate.d.ts +31 -0
  75. package/dist/library/catalog/validate.d.ts.map +1 -0
  76. package/dist/library/catalog/validate.js +420 -0
  77. package/dist/library/catalog/validate.js.map +1 -0
  78. package/dist/library/components/Card/Card.d.ts +6 -2
  79. package/dist/library/components/Card/Card.d.ts.map +1 -1
  80. package/dist/library/components/Card/Card.js +12 -4
  81. package/dist/library/components/Card/Card.js.map +1 -1
  82. package/dist/library/components/Checkbox/Checkbox.d.ts.map +1 -1
  83. package/dist/library/components/Checkbox/Checkbox.js +2 -2
  84. package/dist/library/components/Checkbox/Checkbox.js.map +1 -1
  85. package/dist/library/components/Collapsible/Collapsible.js +1 -1
  86. package/dist/library/components/Collapsible/Collapsible.js.map +1 -1
  87. package/dist/library/components/InputGroup/InputGroup.js +1 -1
  88. package/dist/library/components/InputGroup/InputGroup.js.map +1 -1
  89. package/dist/library/components/NavLink/NavLink.d.ts.map +1 -1
  90. package/dist/library/components/NavLink/NavLink.js +1 -1
  91. package/dist/library/components/NavLink/NavLink.js.map +1 -1
  92. package/dist/library/components/RadioGroup/RadioGroup.d.ts.map +1 -1
  93. package/dist/library/components/RadioGroup/RadioGroup.js +3 -3
  94. package/dist/library/components/RadioGroup/RadioGroup.js.map +1 -1
  95. package/dist/library/components/ScrollArea/ScrollArea.d.ts.map +1 -1
  96. package/dist/library/components/ScrollArea/ScrollArea.js +4 -1
  97. package/dist/library/components/ScrollArea/ScrollArea.js.map +1 -1
  98. package/dist/library/components/Switch/Switch.d.ts.map +1 -1
  99. package/dist/library/components/Switch/Switch.js +2 -2
  100. package/dist/library/components/Switch/Switch.js.map +1 -1
  101. package/dist/library/components/Table/Table.d.ts +6 -2
  102. package/dist/library/components/Table/Table.d.ts.map +1 -1
  103. package/dist/library/components/Table/Table.js +10 -4
  104. package/dist/library/components/Table/Table.js.map +1 -1
  105. package/dist/library/components/TagsInput/TagsInput.d.ts.map +1 -1
  106. package/dist/library/components/TagsInput/TagsInput.js +1 -1
  107. package/dist/library/components/TagsInput/TagsInput.js.map +1 -1
  108. package/dist/library/components/TimeInput/TimeInput.d.ts.map +1 -1
  109. package/dist/library/components/TimeInput/TimeInput.js +28 -20
  110. package/dist/library/components/TimeInput/TimeInput.js.map +1 -1
  111. package/dist/library/components/Toast/Toast.js +1 -1
  112. package/dist/library/components/Toast/Toast.js.map +1 -1
  113. package/dist/library/components/ToggleGroup/ToggleGroup.js +1 -1
  114. package/dist/library/components/ToggleGroup/ToggleGroup.js.map +1 -1
  115. package/dist/library/index.d.ts +1 -1
  116. package/dist/library/index.d.ts.map +1 -1
  117. package/dist/library/presentation.d.ts +3 -0
  118. package/dist/library/presentation.d.ts.map +1 -1
  119. package/dist/library/styles.css +1 -1
  120. package/dist/library/themes/components.d.ts +6 -0
  121. package/dist/library/themes/components.d.ts.map +1 -1
  122. package/dist/library/themes/components.js +6 -0
  123. package/dist/library/themes/components.js.map +1 -1
  124. package/dist/library/themes/tokens.d.ts +4 -0
  125. package/dist/library/themes/tokens.d.ts.map +1 -1
  126. package/dist/library/themes/tokens.js +3 -0
  127. package/dist/library/themes/tokens.js.map +1 -1
  128. package/docs/accessibility.md +6 -0
  129. package/docs/architecture.md +20 -1
  130. package/docs/theming.md +13 -0
  131. package/package.json +17 -5
  132. package/src/a2ui/A2uiPlaceholder.tsx +64 -0
  133. package/src/a2ui/A2uiSurface.tsx +790 -0
  134. package/src/a2ui/accessibility.ts +145 -0
  135. package/src/a2ui/accessibilityRules.ts +106 -0
  136. package/src/a2ui/catalog.json +317 -0
  137. package/src/a2ui/catalogGenerator.ts +717 -0
  138. package/src/a2ui/coerce.ts +379 -0
  139. package/src/a2ui/entries.tsx +519 -0
  140. package/src/a2ui/fixtures.ts +402 -0
  141. package/src/a2ui/index.ts +50 -0
  142. package/src/a2ui/protocolErrors.ts +63 -0
  143. package/src/a2ui/registry.ts +221 -0
  144. package/src/a2ui/sanitize.ts +51 -0
  145. package/src/a2ui/surfaceRuntime.ts +317 -0
  146. package/src/catalog/actions.ts +108 -0
  147. package/src/catalog/coerce.ts +447 -0
  148. package/src/catalog/index.ts +67 -0
  149. package/src/catalog/radiantCatalog.ts +949 -0
  150. package/src/catalog/types.ts +159 -0
  151. package/src/catalog/validate.ts +454 -0
  152. package/src/components/Card/Card.tsx +35 -19
  153. package/src/components/Checkbox/Checkbox.tsx +2 -0
  154. package/src/components/Collapsible/Collapsible.tsx +1 -1
  155. package/src/components/InputGroup/InputGroup.tsx +2 -2
  156. package/src/components/NavLink/NavLink.tsx +1 -6
  157. package/src/components/RadioGroup/RadioGroup.tsx +3 -0
  158. package/src/components/ScrollArea/ScrollArea.tsx +5 -1
  159. package/src/components/Switch/Switch.tsx +2 -0
  160. package/src/components/Table/Table.tsx +16 -3
  161. package/src/components/TagsInput/TagsInput.tsx +1 -0
  162. package/src/components/TimeInput/TimeInput.tsx +100 -75
  163. package/src/components/Toast/Toast.tsx +1 -1
  164. package/src/components/ToggleGroup/ToggleGroup.tsx +1 -1
  165. package/src/index.ts +1 -1
  166. package/src/presentation.ts +3 -0
  167. package/src/themes/baseline.css +3 -0
  168. package/src/themes/components.ts +6 -0
  169. package/src/themes/tokens.ts +7 -0
@@ -0,0 +1,447 @@
1
+ import type { CatalogJsonPrimitive, CatalogJsonSchema } from './types.js'
2
+ import { isForbiddenCatalogProp } from './validate.js'
3
+
4
+ export type CatalogDiagnosticKind = 'coerced' | 'defaulted' | 'stripped' | 'fallback' | 'error'
5
+
6
+ export type CatalogDiagnostic = {
7
+ readonly kind: CatalogDiagnosticKind
8
+ readonly nodeId: string
9
+ readonly component: string
10
+ readonly prop: string
11
+ readonly received: unknown
12
+ readonly used: unknown
13
+ readonly reason: string
14
+ /** Stable machine-readable code for catalog and protocol errors, such as `UNKNOWN_COMPONENT_TYPE`. */
15
+ readonly code?: string
16
+ }
17
+
18
+ export type CatalogDiagnosticSummary = {
19
+ readonly total: number
20
+ readonly coercions: number
21
+ readonly defaults: number
22
+ readonly stripped: number
23
+ readonly fallbacks: number
24
+ readonly errors: number
25
+ readonly byComponent: Readonly<Record<string, number>>
26
+ readonly byProp: Readonly<Record<string, number>>
27
+ }
28
+
29
+ export type DiagnosticLogger = (
30
+ kind: CatalogDiagnosticKind,
31
+ prop: string,
32
+ received: unknown,
33
+ used: unknown,
34
+ reason: string
35
+ ) => void
36
+
37
+ export type CoerceSchemaPropsOptions = {
38
+ readonly nodeId: string
39
+ readonly component: string
40
+ readonly customPropCoercer?: (
41
+ value: unknown,
42
+ context: {
43
+ readonly nodeId: string
44
+ readonly prop: string
45
+ readonly propSchema: CatalogJsonSchema
46
+ readonly required: boolean
47
+ readonly rawProps: Readonly<Record<string, unknown>>
48
+ readonly log: DiagnosticLogger
49
+ }
50
+ ) => { readonly handled: boolean; readonly value?: unknown; readonly omit?: boolean }
51
+ }
52
+
53
+ export type CoercePropsResult = {
54
+ readonly props: Record<string, unknown>
55
+ readonly diagnostics: readonly CatalogDiagnostic[]
56
+ }
57
+
58
+ const FALLBACK_TEXT_KEYS = [
59
+ 'text',
60
+ 'label',
61
+ 'title',
62
+ 'heading',
63
+ 'description',
64
+ 'message',
65
+ 'placeholder',
66
+ 'value'
67
+ ] as const
68
+
69
+ // Drop the uncontrolled default prop when paired with its controlled counterpart.
70
+ const STATE_OWNERSHIP_PAIRS = [
71
+ ['value', 'defaultValue'],
72
+ ['checked', 'defaultChecked'],
73
+ ['open', 'defaultOpen']
74
+ ] as const
75
+
76
+ export const isPlainRecord = (v: unknown): v is Record<string, unknown> =>
77
+ Boolean(v) && typeof v === 'object' && !Array.isArray(v)
78
+
79
+ /** Creates a diagnostic logger bound to one node and component, shared by catalog and A2UI coercion. */
80
+ export function createDiagnosticLogger(
81
+ target: CatalogDiagnostic[],
82
+ nodeId: string,
83
+ component: string
84
+ ): DiagnosticLogger {
85
+ return (kind, prop, received, used, reason) => {
86
+ target.push({ kind, nodeId, component, prop, received, used, reason })
87
+ }
88
+ }
89
+
90
+ /** Turns a component ID (such as `display_name` or `emailField`) into a readable fallback label. */
91
+ export function humanizeNodeId(nodeId: string): string {
92
+ const spaced = nodeId
93
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
94
+ .replace(/[_-]+/g, ' ')
95
+ .replace(/\s+/g, ' ')
96
+ .trim()
97
+ return spaced && /[A-Za-z0-9]/.test(spaced)
98
+ ? spaced[0]!.toUpperCase() + spaced.slice(1).toLowerCase()
99
+ : 'Field'
100
+ }
101
+
102
+ /** Extracts readable fallback text from raw component props when a node must degrade gracefully. */
103
+ export function extractFallbackText(rawProps: Readonly<Record<string, unknown>>): string {
104
+ for (const key of FALLBACK_TEXT_KEYS) {
105
+ const v = rawProps[key]
106
+ if (typeof v === 'string' && v.trim()) return v.trim()
107
+ if (typeof v === 'number' || typeof v === 'boolean') return String(v)
108
+ }
109
+ return ''
110
+ }
111
+
112
+ /** Summarizes diagnostics into counts for host telemetry and per-run harness reports. */
113
+ export function summarizeCatalogDiagnostics(
114
+ diagnostics: readonly CatalogDiagnostic[]
115
+ ): CatalogDiagnosticSummary {
116
+ const counts = { coerced: 0, defaulted: 0, stripped: 0, fallback: 0, error: 0 }
117
+ const byComponent: Record<string, number> = {}
118
+ const byProp: Record<string, number> = {}
119
+ const increment = (map: Record<string, number>, key: string) => {
120
+ map[key] = (Object.hasOwn(map, key) ? map[key]! : 0) + 1
121
+ }
122
+ for (const d of diagnostics) {
123
+ counts[d.kind]++
124
+ increment(byComponent, d.component)
125
+ increment(byProp, `${d.component}.${d.prop}`)
126
+ }
127
+ return Object.freeze({
128
+ total: diagnostics.length,
129
+ coercions: counts.coerced,
130
+ defaults: counts.defaulted,
131
+ stripped: counts.stripped,
132
+ fallbacks: counts.fallback,
133
+ errors: counts.error,
134
+ byComponent: Object.freeze(byComponent),
135
+ byProp: Object.freeze(byProp)
136
+ })
137
+ }
138
+
139
+ export type FlattenedObjectSchema = {
140
+ readonly properties: Record<string, CatalogJsonSchema>
141
+ readonly required: Set<string>
142
+ readonly additionalProperties: boolean | CatalogJsonSchema | undefined
143
+ }
144
+
145
+ export function flattenObjectSchema(schema: Record<string, unknown>): FlattenedObjectSchema {
146
+ const properties: Record<string, CatalogJsonSchema> = {}
147
+ const required = new Set<string>()
148
+ let additionalProperties: boolean | CatalogJsonSchema | undefined
149
+ const visit = (node: Record<string, unknown>) => {
150
+ if (isPlainRecord(node.properties)) {
151
+ for (const [k, s] of Object.entries(node.properties)) {
152
+ if (isPlainRecord(s)) properties[k] = s as CatalogJsonSchema
153
+ }
154
+ }
155
+ if (Array.isArray(node.required)) {
156
+ for (const k of node.required) if (typeof k === 'string') required.add(k)
157
+ }
158
+ if (
159
+ typeof node.additionalProperties === 'boolean' ||
160
+ isPlainRecord(node.additionalProperties)
161
+ ) {
162
+ additionalProperties = node.additionalProperties as boolean | CatalogJsonSchema
163
+ }
164
+ if (Array.isArray(node.allOf)) for (const b of node.allOf) if (isPlainRecord(b)) visit(b)
165
+ }
166
+ visit(schema)
167
+ return { properties, required, additionalProperties }
168
+ }
169
+
170
+ type ValueContext = {
171
+ readonly nodeId: string
172
+ readonly rawProps: Readonly<Record<string, unknown>>
173
+ readonly log: DiagnosticLogger
174
+ }
175
+
176
+ const cloneDefault = <T>(v: T): T => (typeof v === 'object' && v !== null ? structuredClone(v) : v)
177
+ const nextAboveExclusiveMinimum = (min: number, isInteger: boolean) =>
178
+ isInteger ? Math.floor(min) + 1 : min + 1
179
+
180
+ function primaryType(s: CatalogJsonSchema): string | undefined {
181
+ if (typeof s.type === 'string') return s.type
182
+ if (Array.isArray(s.type)) return s.type.find(t => t !== 'null') ?? s.type[0]
183
+ if (s.const !== undefined) return typeof s.const
184
+ if (s.enum?.length) return typeof s.enum[0]
185
+ return s.properties ? 'object' : s.items ? 'array' : undefined
186
+ }
187
+
188
+ export function synthesizeSchemaFallback(
189
+ prop: string,
190
+ s: CatalogJsonSchema,
191
+ ctx: ValueContext,
192
+ idx?: number
193
+ ): unknown {
194
+ if (s.default !== undefined) return cloneDefault(s.default)
195
+ if (s.const !== undefined) return s.const
196
+ if (s.enum?.length) return s.enum[0]
197
+
198
+ const type = primaryType(s)
199
+ if (type === 'string') {
200
+ if (prop === 'label' && idx === undefined) {
201
+ const placeholder = ctx.rawProps.placeholder
202
+ return typeof placeholder === 'string' && placeholder.trim()
203
+ ? placeholder.trim()
204
+ : humanizeNodeId(ctx.nodeId)
205
+ }
206
+ if (typeof s.minLength === 'number' && s.minLength > 0) {
207
+ return idx !== undefined
208
+ ? prop === 'label'
209
+ ? `Option ${idx + 1}`
210
+ : `${prop}_${idx + 1}`
211
+ : humanizeNodeId(prop || ctx.nodeId)
212
+ }
213
+ return ''
214
+ }
215
+ if (type === 'number' || type === 'integer') {
216
+ if (typeof s.minimum === 'number') return s.minimum
217
+ return typeof s.exclusiveMinimum === 'number'
218
+ ? nextAboveExclusiveMinimum(s.exclusiveMinimum, type === 'integer')
219
+ : 0
220
+ }
221
+ if (type === 'boolean') return false
222
+ if (type === 'array') {
223
+ const count = typeof s.minItems === 'number' && s.minItems > 0 ? s.minItems : 0
224
+ return count > 0 && s.items
225
+ ? Array.from({ length: count }, (_, i) => synthesizeSchemaFallback(prop, s.items!, ctx, i))
226
+ : []
227
+ }
228
+ if (type === 'object') {
229
+ const { properties, required } = flattenObjectSchema(s as Record<string, unknown>)
230
+ const obj: Record<string, unknown> = {}
231
+ for (const k of required) {
232
+ const ps = Object.hasOwn(properties, k) ? properties[k] : undefined
233
+ const v = ps ? synthesizeSchemaFallback(k, ps, ctx, idx) : undefined
234
+ if (v !== undefined) obj[k] = v
235
+ }
236
+ return obj
237
+ }
238
+ return undefined
239
+ }
240
+
241
+ export function coerceSchemaValue(
242
+ received: unknown,
243
+ prop: string,
244
+ s: CatalogJsonSchema,
245
+ ctx: ValueContext,
246
+ idx?: number
247
+ ): unknown {
248
+ const report = (used: unknown, reason: string) => {
249
+ ctx.log('coerced', prop, received, used, reason)
250
+ return used
251
+ }
252
+ const fallback = () => synthesizeSchemaFallback(prop, s, ctx, idx)
253
+
254
+ if (s.const !== undefined) {
255
+ return received === s.const ? received : report(s.const, `Expected ${JSON.stringify(s.const)}.`)
256
+ }
257
+ if (s.enum?.length) {
258
+ if (s.enum.includes(received as CatalogJsonPrimitive)) return received
259
+ if (typeof received === 'string') {
260
+ const hit = s.enum.find(
261
+ c => typeof c === 'string' && c.toLowerCase() === received.trim().toLowerCase()
262
+ )
263
+ if (hit !== undefined) return report(hit, `Normalized enum to "${hit}".`)
264
+ }
265
+ return report(
266
+ s.default !== undefined ? cloneDefault(s.default) : s.enum[0],
267
+ 'Unknown enum value.'
268
+ )
269
+ }
270
+
271
+ const types = Array.isArray(s.type) ? s.type : s.type ? [s.type] : []
272
+ if (received === null && types.includes('null')) return null
273
+ const type = primaryType(s)
274
+
275
+ if (type === 'string') {
276
+ const next =
277
+ typeof received === 'string'
278
+ ? received
279
+ : typeof received === 'number' || typeof received === 'boolean'
280
+ ? (report(String(received), `Converted ${typeof received} to string.`) as string)
281
+ : undefined
282
+ if (next === undefined) return report(String(fallback() ?? ''), 'Expected string.')
283
+ return typeof s.minLength === 'number' && next.length < s.minLength
284
+ ? report(String(fallback() ?? ''), `Shorter than minLength ${s.minLength}.`)
285
+ : next
286
+ }
287
+
288
+ if (type === 'number' || type === 'integer') {
289
+ const fromStr =
290
+ typeof received === 'string' && received.trim() !== '' && Number.isFinite(Number(received))
291
+ const num =
292
+ typeof received === 'number' && Number.isFinite(received)
293
+ ? received
294
+ : fromStr
295
+ ? Number(received)
296
+ : undefined
297
+ if (num === undefined) return report(Number(fallback() ?? 0), `Expected ${type}.`)
298
+ let v = type === 'integer' ? Math.round(num) : num
299
+ if (typeof s.minimum === 'number' && v < s.minimum) v = s.minimum
300
+ if (typeof s.exclusiveMinimum === 'number' && v <= s.exclusiveMinimum) {
301
+ v = nextAboveExclusiveMinimum(s.exclusiveMinimum, type === 'integer')
302
+ }
303
+ if (typeof s.maximum === 'number' && v > s.maximum) v = s.maximum
304
+ return fromStr || v !== received
305
+ ? report(v, fromStr ? `Converted string to ${type}.` : `Clamped ${type}.`)
306
+ : v
307
+ }
308
+
309
+ if (type === 'boolean') {
310
+ if (typeof received === 'boolean') return received
311
+ return received === 'true' || received === 'false'
312
+ ? report(received === 'true', 'Parsed boolean.')
313
+ : report(Boolean(fallback()), 'Expected boolean.')
314
+ }
315
+
316
+ if (type === 'array') {
317
+ if (!Array.isArray(received)) return report(fallback(), 'Expected array.')
318
+ const next = s.items
319
+ ? received.map((item, i) => coerceSchemaValue(item, `${prop}[${i}]`, s.items!, ctx, i))
320
+ : [...received]
321
+ if (typeof s.minItems === 'number' && next.length < s.minItems && s.items) {
322
+ for (let i = next.length; i < s.minItems; i++) {
323
+ next.push(synthesizeSchemaFallback(prop, s.items, ctx, i))
324
+ }
325
+ return report(next, `Shorter than minItems ${s.minItems}.`)
326
+ }
327
+ return next
328
+ }
329
+
330
+ if (type === 'object') {
331
+ if (!isPlainRecord(received)) return report(fallback() ?? {}, 'Expected object.')
332
+ const nested = coerceObjectRecord(s, received, {
333
+ nodeId: ctx.nodeId,
334
+ component: prop,
335
+ checkMixedState: false,
336
+ strictAdditionalProperties: false
337
+ })
338
+ for (const d of nested.diagnostics)
339
+ ctx.log(d.kind, `${prop}.${d.prop}`, d.received, d.used, d.reason)
340
+ return nested.props
341
+ }
342
+
343
+ return received
344
+ }
345
+
346
+ function coerceObjectRecord(
347
+ schema: CatalogJsonSchema | Record<string, unknown>,
348
+ rawProps: Readonly<Record<string, unknown>>,
349
+ options: CoerceSchemaPropsOptions & {
350
+ readonly checkMixedState: boolean
351
+ readonly strictAdditionalProperties: boolean
352
+ }
353
+ ): CoercePropsResult {
354
+ const { nodeId, component, customPropCoercer } = options
355
+ const diagnostics: CatalogDiagnostic[] = []
356
+ const log = createDiagnosticLogger(diagnostics, nodeId, component)
357
+ const valueCtx: ValueContext = { nodeId, rawProps, log }
358
+ const { properties, required, additionalProperties } = flattenObjectSchema(
359
+ schema as Record<string, unknown>
360
+ )
361
+
362
+ const droppedMixed = new Set<string>()
363
+ if (options.checkMixedState) {
364
+ for (const [controlled, uncontrolled] of STATE_OWNERSHIP_PAIRS) {
365
+ if (rawProps[controlled] !== undefined && rawProps[uncontrolled] !== undefined) {
366
+ droppedMixed.add(uncontrolled)
367
+ log(
368
+ 'coerced',
369
+ uncontrolled,
370
+ rawProps[uncontrolled],
371
+ undefined,
372
+ `Mixed "${controlled}" and "${uncontrolled}".`
373
+ )
374
+ }
375
+ }
376
+ }
377
+
378
+ const coerced: Record<string, unknown> = {}
379
+ const applyCustom = (
380
+ prop: string,
381
+ val: unknown,
382
+ propSchema: CatalogJsonSchema,
383
+ isReq: boolean
384
+ ) => {
385
+ const hit = customPropCoercer?.(val, {
386
+ nodeId,
387
+ prop,
388
+ propSchema,
389
+ required: isReq,
390
+ rawProps,
391
+ log
392
+ })
393
+ if (!hit?.handled) return false
394
+ if (!hit.omit && hit.value !== undefined) coerced[prop] = hit.value
395
+ return true
396
+ }
397
+
398
+ for (const [k, v] of Object.entries(rawProps)) {
399
+ if (v === undefined || droppedMixed.has(k)) continue
400
+ if (isForbiddenCatalogProp(k)) {
401
+ log('stripped', k, v, undefined, 'Forbidden host prop.')
402
+ continue
403
+ }
404
+ const ps = Object.hasOwn(properties, k) ? properties[k] : undefined
405
+ if (!ps) {
406
+ if (
407
+ additionalProperties === true ||
408
+ (additionalProperties === undefined && !options.strictAdditionalProperties)
409
+ ) {
410
+ coerced[k] = v
411
+ } else if (isPlainRecord(additionalProperties)) {
412
+ coerced[k] = coerceSchemaValue(v, k, additionalProperties as CatalogJsonSchema, valueCtx)
413
+ } else {
414
+ log('stripped', k, v, undefined, 'Unknown prop.')
415
+ }
416
+ continue
417
+ }
418
+ if (!applyCustom(k, v, ps, required.has(k))) {
419
+ coerced[k] = coerceSchemaValue(v, k, ps, valueCtx)
420
+ }
421
+ }
422
+
423
+ for (const k of required) {
424
+ if (Object.hasOwn(coerced, k) && coerced[k] !== undefined) continue
425
+ const ps = Object.hasOwn(properties, k) ? properties[k] : undefined
426
+ if (!ps || applyCustom(k, undefined, ps, true)) continue
427
+ const fallback = synthesizeSchemaFallback(k, ps, valueCtx)
428
+ if (fallback !== undefined) {
429
+ coerced[k] = fallback
430
+ log('defaulted', k, rawProps[k], fallback, 'Missing required prop.')
431
+ }
432
+ }
433
+
434
+ return { props: coerced, diagnostics }
435
+ }
436
+
437
+ /** Validates and coerces raw model props against a JSON Schema object at the catalog boundary. */
438
+ export const coerceSchemaProps = (
439
+ schema: CatalogJsonSchema | Record<string, unknown>,
440
+ rawProps: Readonly<Record<string, unknown>>,
441
+ options: CoerceSchemaPropsOptions
442
+ ): CoercePropsResult =>
443
+ coerceObjectRecord(schema, rawProps, {
444
+ ...options,
445
+ checkMixedState: true,
446
+ strictAdditionalProperties: true
447
+ })
@@ -0,0 +1,67 @@
1
+ export {
2
+ CATALOG_SPACING,
3
+ CATALOG_TONES,
4
+ CATALOG_VARIANTS,
5
+ CATALOG_CONTROL_SIZES,
6
+ CATALOG_ORIENTATIONS,
7
+ CATALOG_ALIGNMENTS,
8
+ CATALOG_JUSTIFY,
9
+ CHOICE_PRESENTATIONS,
10
+ CATALOG_ANNOUNCEMENTS,
11
+ CATALOG_CATEGORIES
12
+ } from './types.js'
13
+ export type {
14
+ Catalog,
15
+ CatalogActionScope,
16
+ CatalogActionShape,
17
+ CatalogAlignment,
18
+ CatalogAnnouncement,
19
+ CatalogBindingDirection,
20
+ CatalogBindingValueType,
21
+ CatalogCategory,
22
+ CatalogControlSize,
23
+ CatalogEntry,
24
+ CatalogEntryGuidance,
25
+ CatalogEntryInvocation,
26
+ CatalogExtension,
27
+ CatalogInput,
28
+ CatalogJsonPrimitive,
29
+ CatalogJsonSchema,
30
+ CatalogJsonSchemaType,
31
+ CatalogJustify,
32
+ CatalogObjectSchema,
33
+ CatalogOrientation,
34
+ CatalogSlotCardinality,
35
+ CatalogSlotConstraint,
36
+ CatalogSpacing,
37
+ CatalogStateBinding,
38
+ CatalogTone,
39
+ CatalogVariant,
40
+ ChoicePresentation
41
+ } from './types.js'
42
+ export {
43
+ assertValidCatalog,
44
+ defineCatalog,
45
+ extendCatalog,
46
+ findForbiddenPropsInSchema,
47
+ isForbiddenCatalogProp,
48
+ validateCatalog,
49
+ validateCatalogEntry
50
+ } from './validate.js'
51
+ export { coerceSchemaProps, summarizeCatalogDiagnostics } from './coerce.js'
52
+ export type {
53
+ CatalogDiagnostic,
54
+ CatalogDiagnosticKind,
55
+ CatalogDiagnosticSummary,
56
+ CoercePropsResult,
57
+ CoerceSchemaPropsOptions
58
+ } from './coerce.js'
59
+ export { createCatalogActionEvent, snapshotSurfaceState } from './actions.js'
60
+ export type {
61
+ CatalogActionEvent,
62
+ CatalogActionEventInput,
63
+ CatalogActionHandler,
64
+ CatalogJsonValue,
65
+ CatalogSurfaceState
66
+ } from './actions.js'
67
+ export { RADIANT_CATALOG_ID, RADIANT_CATALOG_VERSION, radiantCatalog } from './radiantCatalog.js'