@cognitap/radiant 0.0.91 → 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 (129) hide show
  1. package/CHANGELOG.md +11 -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/Table/Table.d.ts +6 -2
  83. package/dist/library/components/Table/Table.d.ts.map +1 -1
  84. package/dist/library/components/Table/Table.js +10 -4
  85. package/dist/library/components/Table/Table.js.map +1 -1
  86. package/dist/library/index.d.ts +1 -1
  87. package/dist/library/index.d.ts.map +1 -1
  88. package/dist/library/presentation.d.ts +3 -0
  89. package/dist/library/presentation.d.ts.map +1 -1
  90. package/dist/library/styles.css +1 -1
  91. package/dist/library/themes/components.d.ts +6 -0
  92. package/dist/library/themes/components.d.ts.map +1 -1
  93. package/dist/library/themes/components.js +6 -0
  94. package/dist/library/themes/components.js.map +1 -1
  95. package/dist/library/themes/tokens.d.ts +4 -0
  96. package/dist/library/themes/tokens.d.ts.map +1 -1
  97. package/dist/library/themes/tokens.js +3 -0
  98. package/dist/library/themes/tokens.js.map +1 -1
  99. package/docs/accessibility.md +6 -0
  100. package/docs/architecture.md +13 -1
  101. package/docs/theming.md +13 -0
  102. package/package.json +17 -5
  103. package/src/a2ui/A2uiPlaceholder.tsx +64 -0
  104. package/src/a2ui/A2uiSurface.tsx +790 -0
  105. package/src/a2ui/accessibility.ts +145 -0
  106. package/src/a2ui/accessibilityRules.ts +106 -0
  107. package/src/a2ui/catalog.json +317 -0
  108. package/src/a2ui/catalogGenerator.ts +717 -0
  109. package/src/a2ui/coerce.ts +379 -0
  110. package/src/a2ui/entries.tsx +519 -0
  111. package/src/a2ui/fixtures.ts +402 -0
  112. package/src/a2ui/index.ts +50 -0
  113. package/src/a2ui/protocolErrors.ts +63 -0
  114. package/src/a2ui/registry.ts +221 -0
  115. package/src/a2ui/sanitize.ts +51 -0
  116. package/src/a2ui/surfaceRuntime.ts +317 -0
  117. package/src/catalog/actions.ts +108 -0
  118. package/src/catalog/coerce.ts +447 -0
  119. package/src/catalog/index.ts +67 -0
  120. package/src/catalog/radiantCatalog.ts +949 -0
  121. package/src/catalog/types.ts +159 -0
  122. package/src/catalog/validate.ts +454 -0
  123. package/src/components/Card/Card.tsx +35 -19
  124. package/src/components/Table/Table.tsx +16 -3
  125. package/src/index.ts +1 -1
  126. package/src/presentation.ts +3 -0
  127. package/src/themes/baseline.css +3 -0
  128. package/src/themes/components.ts +6 -0
  129. package/src/themes/tokens.ts +7 -0
@@ -0,0 +1,159 @@
1
+ export const CATALOG_SPACING = ['tight', 'normal', 'airy'] as const
2
+ export type CatalogSpacing = (typeof CATALOG_SPACING)[number]
3
+
4
+ export const CATALOG_TONES = ['accent', 'neutral', 'warning', 'danger'] as const
5
+ export type CatalogTone = (typeof CATALOG_TONES)[number]
6
+
7
+ export const CATALOG_VARIANTS = ['solid', 'soft', 'outline', 'ghost'] as const
8
+ export type CatalogVariant = (typeof CATALOG_VARIANTS)[number]
9
+
10
+ export const CATALOG_CONTROL_SIZES = ['small', 'medium', 'large'] as const
11
+ export type CatalogControlSize = (typeof CATALOG_CONTROL_SIZES)[number]
12
+
13
+ export const CATALOG_ORIENTATIONS = ['horizontal', 'vertical'] as const
14
+ export type CatalogOrientation = (typeof CATALOG_ORIENTATIONS)[number]
15
+
16
+ export const CATALOG_ALIGNMENTS = ['start', 'center', 'end', 'stretch'] as const
17
+ export type CatalogAlignment = (typeof CATALOG_ALIGNMENTS)[number]
18
+
19
+ export const CATALOG_JUSTIFY = [
20
+ 'start',
21
+ 'center',
22
+ 'end',
23
+ 'between',
24
+ 'around',
25
+ 'evenly',
26
+ 'stretch'
27
+ ] as const
28
+ export type CatalogJustify = (typeof CATALOG_JUSTIFY)[number]
29
+
30
+ export const CHOICE_PRESENTATIONS = ['list', 'segmented', 'chips', 'cards', 'dropdown'] as const
31
+ export type ChoicePresentation = (typeof CHOICE_PRESENTATIONS)[number]
32
+
33
+ export const CATALOG_ANNOUNCEMENTS = ['off', 'polite', 'assertive'] as const
34
+ export type CatalogAnnouncement = (typeof CATALOG_ANNOUNCEMENTS)[number]
35
+
36
+ export const CATALOG_CATEGORIES = [
37
+ 'content',
38
+ 'media',
39
+ 'layout',
40
+ 'action',
41
+ 'input',
42
+ 'feedback',
43
+ 'data'
44
+ ] as const
45
+ export type CatalogCategory = (typeof CATALOG_CATEGORIES)[number]
46
+
47
+ export type CatalogJsonPrimitive = string | number | boolean | null
48
+ export type CatalogJsonSchemaType =
49
+ | 'string'
50
+ | 'number'
51
+ | 'integer'
52
+ | 'boolean'
53
+ | 'object'
54
+ | 'array'
55
+ | 'null'
56
+
57
+ export type CatalogJsonSchema = {
58
+ readonly type?: CatalogJsonSchemaType | readonly CatalogJsonSchemaType[]
59
+ readonly description?: string
60
+ readonly enum?: readonly CatalogJsonPrimitive[]
61
+ readonly const?: CatalogJsonPrimitive
62
+ readonly default?: unknown
63
+ readonly properties?: Readonly<Record<string, CatalogJsonSchema>>
64
+ readonly required?: readonly string[]
65
+ readonly additionalProperties?: boolean | CatalogJsonSchema
66
+ readonly items?: CatalogJsonSchema
67
+ readonly minItems?: number
68
+ readonly maxItems?: number
69
+ readonly minimum?: number
70
+ readonly maximum?: number
71
+ readonly exclusiveMinimum?: number
72
+ readonly minLength?: number
73
+ readonly maxLength?: number
74
+ readonly format?: string
75
+ readonly oneOf?: readonly CatalogJsonSchema[]
76
+ readonly anyOf?: readonly CatalogJsonSchema[]
77
+ readonly $ref?: string
78
+ readonly $defs?: Readonly<Record<string, CatalogJsonSchema>>
79
+ }
80
+
81
+ export type CatalogObjectSchema = CatalogJsonSchema & {
82
+ readonly type: 'object'
83
+ readonly properties: Readonly<Record<string, CatalogJsonSchema>>
84
+ readonly required?: readonly string[]
85
+ readonly additionalProperties: false
86
+ }
87
+
88
+ export type CatalogSlotCardinality = 'single' | 'many'
89
+
90
+ export type CatalogSlotConstraint = {
91
+ readonly description: string
92
+ readonly cardinality: CatalogSlotCardinality
93
+ readonly required?: boolean
94
+ readonly templated?: boolean
95
+ readonly allowedCategories?: readonly CatalogCategory[]
96
+ readonly allowedEntries?: readonly string[]
97
+ readonly childProps?: Readonly<Record<string, CatalogJsonSchema>>
98
+ }
99
+
100
+ export type CatalogBindingValueType = 'string' | 'number' | 'boolean' | 'string[]' | 'object[]'
101
+ export type CatalogBindingDirection = 'read' | 'two-way'
102
+
103
+ export type CatalogStateBinding = {
104
+ readonly description: string
105
+ readonly valueType: CatalogBindingValueType
106
+ readonly direction: CatalogBindingDirection
107
+ readonly validatable?: boolean
108
+ }
109
+
110
+ export type CatalogActionScope = 'outbound' | 'client'
111
+
112
+ export type CatalogActionShape = {
113
+ readonly description: string
114
+ readonly scope: CatalogActionScope
115
+ readonly payloadSchema?: CatalogJsonSchema
116
+ }
117
+
118
+ export type CatalogEntryGuidance = {
119
+ readonly whenToUse: string
120
+ readonly whenNotToUse: string
121
+ readonly examples?: readonly string[]
122
+ }
123
+
124
+ export type CatalogEntryInvocation = 'render' | 'action'
125
+
126
+ export type CatalogEntry = {
127
+ readonly name: string
128
+ readonly category: CatalogCategory
129
+ readonly description: string
130
+ readonly propsSchema: CatalogObjectSchema
131
+ readonly slots: Readonly<Record<string, CatalogSlotConstraint>>
132
+ readonly bindings: Readonly<Record<string, CatalogStateBinding>>
133
+ readonly actions: Readonly<Record<string, CatalogActionShape>>
134
+ readonly invocation?: CatalogEntryInvocation
135
+ readonly guidance?: CatalogEntryGuidance
136
+ }
137
+
138
+ export type Catalog = {
139
+ readonly id: string
140
+ readonly version: string
141
+ readonly description: string
142
+ readonly extends?: string
143
+ readonly entries: Readonly<Record<string, CatalogEntry>>
144
+ }
145
+
146
+ export type CatalogInput = {
147
+ readonly id: string
148
+ readonly version: string
149
+ readonly description: string
150
+ readonly extends?: string
151
+ readonly entries: Readonly<Record<string, CatalogEntry>>
152
+ }
153
+
154
+ export type CatalogExtension = {
155
+ readonly id: string
156
+ readonly version: string
157
+ readonly description?: string
158
+ readonly entries: Readonly<Record<string, CatalogEntry>>
159
+ }
@@ -0,0 +1,454 @@
1
+ import {
2
+ CATALOG_CATEGORIES,
3
+ type Catalog,
4
+ type CatalogActionShape,
5
+ type CatalogCategory,
6
+ type CatalogEntry,
7
+ type CatalogExtension,
8
+ type CatalogInput,
9
+ type CatalogJsonSchema,
10
+ type CatalogSlotConstraint,
11
+ type CatalogStateBinding
12
+ } from './types.js'
13
+
14
+ const ENTRY_NAME_PATTERN = /^[A-Z][A-Za-z0-9]*$/
15
+ const VALID_CATEGORIES = new Set<string>(CATALOG_CATEGORIES)
16
+ const VALID_BINDING_TYPES = new Set(['string', 'number', 'boolean', 'string[]', 'object[]'])
17
+ const VALID_BINDING_DIRECTIONS = new Set(['read', 'two-way'])
18
+ const VALID_ACTION_SCOPES = new Set(['outbound', 'client'])
19
+ const VALID_SLOT_CARDINALITIES = new Set(['single', 'many'])
20
+ const VALID_INVOCATIONS = new Set(['render', 'action'])
21
+
22
+ const EXACT_FORBIDDEN_PROPS = new Set([
23
+ 'classname',
24
+ 'class',
25
+ 'style',
26
+ 'render',
27
+ 'as',
28
+ 'aschild',
29
+ 'ref',
30
+ 'parts',
31
+ 'key',
32
+ 'role',
33
+ 'tabindex',
34
+ 'dangerouslysetinnerhtml',
35
+ 'innerhtml'
36
+ ])
37
+
38
+ // Lowercase DOM handler attributes such as `onclick`; camelCase handlers match /^on[A-Z]/.
39
+ const DOM_EVENT_NAMES = new Set([
40
+ 'abort',
41
+ 'beforeinput',
42
+ 'blur',
43
+ 'change',
44
+ 'click',
45
+ 'contextmenu',
46
+ 'copy',
47
+ 'cut',
48
+ 'dblclick',
49
+ 'drag',
50
+ 'dragend',
51
+ 'dragenter',
52
+ 'dragleave',
53
+ 'dragover',
54
+ 'dragstart',
55
+ 'drop',
56
+ 'error',
57
+ 'focus',
58
+ 'focusin',
59
+ 'focusout',
60
+ 'input',
61
+ 'invalid',
62
+ 'keydown',
63
+ 'keypress',
64
+ 'keyup',
65
+ 'load',
66
+ 'mousedown',
67
+ 'mouseenter',
68
+ 'mouseleave',
69
+ 'mousemove',
70
+ 'mouseout',
71
+ 'mouseover',
72
+ 'mouseup',
73
+ 'paste',
74
+ 'pointerdown',
75
+ 'pointerenter',
76
+ 'pointerleave',
77
+ 'pointermove',
78
+ 'pointerup',
79
+ 'reset',
80
+ 'scroll',
81
+ 'select',
82
+ 'submit',
83
+ 'toggle',
84
+ 'touchend',
85
+ 'touchmove',
86
+ 'touchstart',
87
+ 'wheel'
88
+ ])
89
+
90
+ /**
91
+ * Returns true when a prop name leaks host styling, React rendering escape hatches,
92
+ * DOM event handlers, or raw ARIA attributes into the model-facing contract.
93
+ */
94
+ export function isForbiddenCatalogProp(name: string): boolean {
95
+ const lower = name.toLowerCase()
96
+ if (EXACT_FORBIDDEN_PROPS.has(lower)) return true
97
+ if (lower.startsWith('aria-') || /^aria[A-Z]/.test(name)) return true
98
+ if (lower.startsWith('data-')) return true
99
+ if (/^on[A-Z]/.test(name)) return true
100
+ if (lower.startsWith('on') && DOM_EVENT_NAMES.has(lower.slice(2))) return true
101
+ return false
102
+ }
103
+
104
+ /**
105
+ * Recursively scans a JSON Schema for forbidden model-facing prop names.
106
+ */
107
+ export function findForbiddenPropsInSchema(
108
+ schema: CatalogJsonSchema | undefined,
109
+ path = 'props'
110
+ ): readonly string[] {
111
+ if (!schema || typeof schema !== 'object') return []
112
+ const violations: string[] = []
113
+ if (schema.properties) {
114
+ for (const [key, propSchema] of Object.entries(schema.properties)) {
115
+ const propPath = `${path}.${key}`
116
+ if (isForbiddenCatalogProp(key)) violations.push(propPath)
117
+ violations.push(...findForbiddenPropsInSchema(propSchema, propPath))
118
+ }
119
+ }
120
+ if (schema.items) {
121
+ violations.push(...findForbiddenPropsInSchema(schema.items, `${path}[]`))
122
+ }
123
+ if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
124
+ violations.push(...findForbiddenPropsInSchema(schema.additionalProperties, `${path}.*`))
125
+ }
126
+ if (schema.oneOf) {
127
+ for (let i = 0; i < schema.oneOf.length; i++) {
128
+ violations.push(...findForbiddenPropsInSchema(schema.oneOf[i], `${path}.oneOf[${i}]`))
129
+ }
130
+ }
131
+ if (schema.anyOf) {
132
+ for (let i = 0; i < schema.anyOf.length; i++) {
133
+ violations.push(...findForbiddenPropsInSchema(schema.anyOf[i], `${path}.anyOf[${i}]`))
134
+ }
135
+ }
136
+ if (schema.$defs) {
137
+ for (const [defName, defSchema] of Object.entries(schema.$defs)) {
138
+ violations.push(...findForbiddenPropsInSchema(defSchema, `${path}.$defs.${defName}`))
139
+ }
140
+ }
141
+ return violations
142
+ }
143
+
144
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
145
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false
146
+ const proto = Object.getPrototypeOf(value)
147
+ return proto === Object.prototype || proto === null
148
+ }
149
+
150
+ function validateSlot(
151
+ entryName: string,
152
+ slotName: string,
153
+ slot: CatalogSlotConstraint,
154
+ violations: string[]
155
+ ): void {
156
+ const prefix = `${entryName}.slots.${slotName}`
157
+ if (!isPlainObject(slot)) {
158
+ violations.push(`${prefix} must be an object.`)
159
+ return
160
+ }
161
+ if (typeof slot.description !== 'string' || !slot.description.trim()) {
162
+ violations.push(`${prefix}.description must be a non-empty string.`)
163
+ }
164
+ if (!VALID_SLOT_CARDINALITIES.has(slot.cardinality)) {
165
+ violations.push(`${prefix}.cardinality must be "single" or "many".`)
166
+ }
167
+ if (slot.allowedCategories) {
168
+ for (const category of slot.allowedCategories) {
169
+ if (!VALID_CATEGORIES.has(category)) {
170
+ violations.push(`${prefix}.allowedCategories contains unknown category "${category}".`)
171
+ }
172
+ }
173
+ }
174
+ if (slot.childProps) {
175
+ for (const [propName, propSchema] of Object.entries(slot.childProps)) {
176
+ if (isForbiddenCatalogProp(propName)) {
177
+ violations.push(`${prefix}.childProps.${propName} is a forbidden catalog prop.`)
178
+ }
179
+ for (const nested of findForbiddenPropsInSchema(
180
+ propSchema,
181
+ `${prefix}.childProps.${propName}`
182
+ )) {
183
+ violations.push(`${nested} is a forbidden catalog prop.`)
184
+ }
185
+ }
186
+ }
187
+ }
188
+
189
+ function validateBinding(
190
+ entryName: string,
191
+ bindingName: string,
192
+ binding: CatalogStateBinding,
193
+ violations: string[]
194
+ ): void {
195
+ const prefix = `${entryName}.bindings.${bindingName}`
196
+ if (!isPlainObject(binding)) {
197
+ violations.push(`${prefix} must be an object.`)
198
+ return
199
+ }
200
+ if (isForbiddenCatalogProp(bindingName)) {
201
+ violations.push(`${prefix} uses a forbidden prop name.`)
202
+ }
203
+ if (typeof binding.description !== 'string' || !binding.description.trim()) {
204
+ violations.push(`${prefix}.description must be a non-empty string.`)
205
+ }
206
+ if (!VALID_BINDING_TYPES.has(binding.valueType)) {
207
+ violations.push(`${prefix}.valueType "${String(binding.valueType)}" is unsupported.`)
208
+ }
209
+ if (!VALID_BINDING_DIRECTIONS.has(binding.direction)) {
210
+ violations.push(`${prefix}.direction must be "read" or "two-way".`)
211
+ }
212
+ }
213
+
214
+ function validateAction(
215
+ entryName: string,
216
+ actionName: string,
217
+ action: CatalogActionShape,
218
+ violations: string[]
219
+ ): void {
220
+ const prefix = `${entryName}.actions.${actionName}`
221
+ if (!isPlainObject(action)) {
222
+ violations.push(`${prefix} must be an object.`)
223
+ return
224
+ }
225
+ if (typeof action.description !== 'string' || !action.description.trim()) {
226
+ violations.push(`${prefix}.description must be a non-empty string.`)
227
+ }
228
+ if (!VALID_ACTION_SCOPES.has(action.scope)) {
229
+ violations.push(`${prefix}.scope must be "outbound" or "client".`)
230
+ }
231
+ if (action.payloadSchema) {
232
+ for (const bad of findForbiddenPropsInSchema(action.payloadSchema, `${prefix}.payloadSchema`)) {
233
+ violations.push(`${bad} is a forbidden catalog prop.`)
234
+ }
235
+ }
236
+ }
237
+
238
+ /**
239
+ * Validates a single canonical catalog entry and returns a list of violations.
240
+ */
241
+ export function validateCatalogEntry(entry: CatalogEntry, key?: string): readonly string[] {
242
+ const violations: string[] = []
243
+ if (!isPlainObject(entry)) {
244
+ return [`Entry "${key ?? '(unnamed)'}" must be a plain object.`]
245
+ }
246
+ const label = typeof entry.name === 'string' && entry.name ? entry.name : (key ?? '(unnamed)')
247
+ if (typeof entry.name !== 'string' || !ENTRY_NAME_PATTERN.test(entry.name)) {
248
+ violations.push(`${label}: entry name must be PascalCase.`)
249
+ }
250
+ if (key !== undefined && entry.name !== key) {
251
+ violations.push(`${label}: entry key "${key}" must match entry.name "${entry.name}".`)
252
+ }
253
+ if (!VALID_CATEGORIES.has(entry.category as CatalogCategory)) {
254
+ violations.push(`${label}: unknown category "${String(entry.category)}".`)
255
+ }
256
+ if (typeof entry.description !== 'string' || !entry.description.trim()) {
257
+ violations.push(`${label}: description must be a non-empty string.`)
258
+ }
259
+ if (entry.invocation !== undefined && !VALID_INVOCATIONS.has(entry.invocation)) {
260
+ violations.push(`${label}: invocation must be "render" or "action".`)
261
+ }
262
+ if (!isPlainObject(entry.propsSchema)) {
263
+ violations.push(`${label}: propsSchema must be an object schema.`)
264
+ } else {
265
+ if (entry.propsSchema.type !== 'object') {
266
+ violations.push(`${label}: propsSchema.type must be "object".`)
267
+ }
268
+ if (entry.propsSchema.additionalProperties !== false) {
269
+ violations.push(`${label}: propsSchema.additionalProperties must be false.`)
270
+ }
271
+ if (!isPlainObject(entry.propsSchema.properties)) {
272
+ violations.push(`${label}: propsSchema.properties must be an object.`)
273
+ } else {
274
+ for (const bad of findForbiddenPropsInSchema(entry.propsSchema, `${label}.props`)) {
275
+ violations.push(`${bad} is a forbidden catalog prop.`)
276
+ }
277
+ if (entry.propsSchema.required) {
278
+ for (const requiredProp of entry.propsSchema.required) {
279
+ if (!Object.hasOwn(entry.propsSchema.properties, requiredProp)) {
280
+ violations.push(
281
+ `${label}: required prop "${requiredProp}" is missing from propsSchema.properties.`
282
+ )
283
+ }
284
+ }
285
+ }
286
+ }
287
+ }
288
+ if (!isPlainObject(entry.slots)) {
289
+ violations.push(`${label}: slots must be an object.`)
290
+ } else {
291
+ for (const [slotName, slot] of Object.entries(entry.slots)) {
292
+ validateSlot(label, slotName, slot, violations)
293
+ if (
294
+ isPlainObject(entry.propsSchema?.properties) &&
295
+ Object.hasOwn(entry.propsSchema.properties, slotName)
296
+ ) {
297
+ violations.push(`${label}: slot "${slotName}" collides with a prop of the same name.`)
298
+ }
299
+ if (isPlainObject(entry.bindings) && Object.hasOwn(entry.bindings, slotName)) {
300
+ violations.push(`${label}: slot "${slotName}" collides with a binding of the same name.`)
301
+ }
302
+ }
303
+ }
304
+ if (!isPlainObject(entry.bindings)) {
305
+ violations.push(`${label}: bindings must be an object.`)
306
+ } else {
307
+ for (const [bindingName, binding] of Object.entries(entry.bindings)) {
308
+ validateBinding(label, bindingName, binding, violations)
309
+ }
310
+ }
311
+ if (!isPlainObject(entry.actions)) {
312
+ violations.push(`${label}: actions must be an object.`)
313
+ } else {
314
+ for (const [actionName, action] of Object.entries(entry.actions)) {
315
+ validateAction(label, actionName, action, violations)
316
+ for (const [kind, names] of [
317
+ ['prop', entry.propsSchema?.properties],
318
+ ['slot', entry.slots],
319
+ ['binding', entry.bindings]
320
+ ] as const) {
321
+ if (isPlainObject(names) && Object.hasOwn(names, actionName)) {
322
+ violations.push(
323
+ `${label}: action "${actionName}" collides with a ${kind} of the same name.`
324
+ )
325
+ }
326
+ }
327
+ }
328
+ }
329
+ if (entry.guidance !== undefined) {
330
+ if (!isPlainObject(entry.guidance)) {
331
+ violations.push(`${label}: guidance must be an object.`)
332
+ } else {
333
+ if (typeof entry.guidance.whenToUse !== 'string' || !entry.guidance.whenToUse.trim()) {
334
+ violations.push(`${label}: guidance.whenToUse must be a non-empty string.`)
335
+ }
336
+ if (typeof entry.guidance.whenNotToUse !== 'string' || !entry.guidance.whenNotToUse.trim()) {
337
+ violations.push(`${label}: guidance.whenNotToUse must be a non-empty string.`)
338
+ }
339
+ }
340
+ }
341
+ return violations
342
+ }
343
+
344
+ /**
345
+ * Validates an entire canonical catalog and returns all contract violations.
346
+ */
347
+ export function validateCatalog(catalog: Catalog): readonly string[] {
348
+ const violations: string[] = []
349
+ if (!isPlainObject(catalog)) {
350
+ return ['Catalog must be a plain object.']
351
+ }
352
+ if (typeof catalog.id !== 'string' || !catalog.id.trim()) {
353
+ violations.push('Catalog id must be a non-empty string.')
354
+ }
355
+ if (typeof catalog.version !== 'string' || !catalog.version.trim()) {
356
+ violations.push('Catalog version must be a non-empty string.')
357
+ }
358
+ if (typeof catalog.description !== 'string' || !catalog.description.trim()) {
359
+ violations.push('Catalog description must be a non-empty string.')
360
+ }
361
+ if (!isPlainObject(catalog.entries)) {
362
+ violations.push('Catalog entries must be an object.')
363
+ } else {
364
+ const names = Object.keys(catalog.entries)
365
+ if (names.length === 0) {
366
+ violations.push('Catalog must define at least one entry.')
367
+ }
368
+ for (const [key, entry] of Object.entries(catalog.entries)) {
369
+ violations.push(...validateCatalogEntry(entry, key))
370
+ }
371
+ for (const [key, entry] of Object.entries(catalog.entries)) {
372
+ if (!isPlainObject(entry) || !isPlainObject(entry.slots)) continue
373
+ for (const [slotName, slot] of Object.entries(entry.slots)) {
374
+ if (!slot.allowedEntries) continue
375
+ for (const allowed of slot.allowedEntries) {
376
+ if (!Object.hasOwn(catalog.entries, allowed)) {
377
+ violations.push(
378
+ `${key}.slots.${slotName}.allowedEntries references unknown entry "${allowed}".`
379
+ )
380
+ }
381
+ }
382
+ }
383
+ }
384
+ }
385
+ return violations
386
+ }
387
+
388
+ /**
389
+ * Throws a TypeError when the catalog violates any canonical contract rule.
390
+ */
391
+ export function assertValidCatalog(catalog: Catalog): void {
392
+ const violations = validateCatalog(catalog)
393
+ if (violations.length > 0) {
394
+ throw new TypeError(`Invalid Radiant catalog:\n- ${violations.join('\n- ')}`)
395
+ }
396
+ }
397
+
398
+ function freezeDeep<T>(value: T): T {
399
+ if (!value || typeof value !== 'object') return value
400
+ if (Object.isFrozen(value)) return value
401
+ if (Array.isArray(value)) {
402
+ for (const item of value) freezeDeep(item)
403
+ } else {
404
+ for (const item of Object.values(value as Record<string, unknown>)) freezeDeep(item)
405
+ }
406
+ return Object.freeze(value)
407
+ }
408
+
409
+ function clonePlain<T>(value: T): T {
410
+ return structuredClone(value)
411
+ }
412
+
413
+ /**
414
+ * Validates and freezes a canonical catalog definition.
415
+ */
416
+ export function defineCatalog(input: CatalogInput): Catalog {
417
+ const catalog = clonePlain(input) as Catalog
418
+ assertValidCatalog(catalog)
419
+ return freezeDeep(catalog)
420
+ }
421
+
422
+ /**
423
+ * Extends a base catalog with application entries without allowing name shadowing.
424
+ */
425
+ export function extendCatalog(base: Catalog, extension: CatalogExtension): Catalog {
426
+ assertValidCatalog(base)
427
+ if (!isPlainObject(extension)) {
428
+ throw new TypeError('Catalog extension must be a plain object.')
429
+ }
430
+ if (!isPlainObject(extension.entries) || Object.keys(extension.entries).length === 0) {
431
+ throw new TypeError('Catalog extension must provide at least one entry.')
432
+ }
433
+ const collisions: string[] = []
434
+ for (const key of Object.keys(extension.entries)) {
435
+ if (Object.hasOwn(base.entries, key)) collisions.push(key)
436
+ }
437
+ if (collisions.length > 0) {
438
+ throw new TypeError(
439
+ `Catalog extension cannot shadow base entries: ${collisions.sort().join(', ')}.`
440
+ )
441
+ }
442
+ const merged: Catalog = {
443
+ id: extension.id,
444
+ version: extension.version,
445
+ description: extension.description ?? base.description,
446
+ extends: base.id,
447
+ entries: {
448
+ ...clonePlain(base.entries),
449
+ ...clonePlain(extension.entries)
450
+ }
451
+ }
452
+ assertValidCatalog(merged)
453
+ return freezeDeep(merged)
454
+ }
@@ -4,26 +4,39 @@ import { cva } from 'class-variance-authority'
4
4
  import { cn } from 'cn'
5
5
  import { joinIds } from '../../internal/ids.js'
6
6
  import type { ThemeStyle } from '../../themes/defineTheme.js'
7
+ import type { Spacing } from '../../presentation.js'
7
8
 
8
9
  const colorMotionClass =
9
10
  'transition-colors duration-[var(--rad-motion-color-duration,150ms)] motion-reduce:transition-none'
10
11
 
11
- const cardVariants = cva([
12
- colorMotionClass,
13
- 'font-[family-name:var(--rad-typography-roles-ui-body-family,system-ui,sans-serif)] tracking-[var(--rad-typography-roles-ui-body-letter-spacing,-0.011em)] text-[length:var(--rad-typography-roles-ui-body-size,0.875rem)] font-[number:var(--rad-typography-roles-ui-body-weight,400)] leading-[var(--rad-typography-roles-ui-body-line-height,1.5)]',
14
- 'box-border grid w-full min-w-0 gap-[var(--rad-card-gap,var(--rad-surface-gap,1rem))] text-start antialiased',
15
- 'rounded-[var(--rad-card-radius,var(--rad-surface-radius,0.75rem))]',
16
- '[corner-shape:var(--rad-card-corner-shape,var(--rad-surface-corner-shape,round))]',
17
- '[border-width:var(--rad-card-border-width,var(--rad-surface-border-width,1px))]',
18
- '[border-style:var(--rad-card-border-style,var(--rad-surface-border-style,solid))]',
19
- '[border-color:var(--rad-card-border-color,var(--rad-color-border,oklch(0.885_0.005_286)))]',
20
- 'bg-[var(--rad-card-background,var(--rad-color-surface,oklch(1_0_0)))]',
21
- '[color:var(--rad-card-color,var(--rad-color-foreground,oklch(0.21_0.006_286)))]',
22
- 'p-[var(--rad-card-padding,var(--rad-surface-padding,1.5rem))]',
23
- '[box-shadow:var(--rad-card-shadow,var(--rad-surface-shadow,0_1px_2px_0_rgb(0_0_0/0.06)))]',
24
- '[backdrop-filter:var(--rad-surface-backdrop-filter,none)]',
25
- 'forced-colors:border-[CanvasText] forced-colors:bg-[Canvas] forced-colors:text-[CanvasText] forced-colors:shadow-none'
26
- ])
12
+ const cardVariants = cva(
13
+ [
14
+ colorMotionClass,
15
+ 'font-[family-name:var(--rad-typography-roles-ui-body-family,system-ui,sans-serif)] tracking-[var(--rad-typography-roles-ui-body-letter-spacing,-0.011em)] text-[length:var(--rad-typography-roles-ui-body-size,0.875rem)] font-[number:var(--rad-typography-roles-ui-body-weight,400)] leading-[var(--rad-typography-roles-ui-body-line-height,1.5)]',
16
+ 'box-border grid w-full min-w-0 gap-[var(--rad-card-gap,var(--rad-surface-gap,1rem))] text-start antialiased',
17
+ 'rounded-[var(--rad-card-radius,var(--rad-surface-radius,0.75rem))]',
18
+ '[corner-shape:var(--rad-card-corner-shape,var(--rad-surface-corner-shape,round))]',
19
+ '[border-width:var(--rad-card-border-width,var(--rad-surface-border-width,1px))]',
20
+ '[border-style:var(--rad-card-border-style,var(--rad-surface-border-style,solid))]',
21
+ '[border-color:var(--rad-card-border-color,var(--rad-color-border,oklch(0.885_0.005_286)))]',
22
+ 'bg-[var(--rad-card-background,var(--rad-color-surface,oklch(1_0_0)))]',
23
+ '[color:var(--rad-card-color,var(--rad-color-foreground,oklch(0.21_0.006_286)))]',
24
+ '[box-shadow:var(--rad-card-shadow,var(--rad-surface-shadow,0_1px_2px_0_rgb(0_0_0/0.06)))]',
25
+ '[backdrop-filter:var(--rad-surface-backdrop-filter,none)]',
26
+ 'forced-colors:border-[CanvasText] forced-colors:bg-[Canvas] forced-colors:text-[CanvasText] forced-colors:shadow-none'
27
+ ],
28
+ {
29
+ variants: {
30
+ padding: {
31
+ tight:
32
+ 'p-[var(--rad-card-padding-tight,calc(var(--rad-card-padding,var(--rad-surface-padding,1.5rem))*2/3))]',
33
+ normal: 'p-[var(--rad-card-padding,var(--rad-surface-padding,1.5rem))]',
34
+ airy: 'p-[var(--rad-card-padding-airy,calc(var(--rad-card-padding,var(--rad-surface-padding,1.5rem))*4/3))]'
35
+ }
36
+ },
37
+ defaultVariants: { padding: 'normal' }
38
+ }
39
+ )
27
40
 
28
41
  const cardHeaderVariants = cva([
29
42
  'grid min-w-0 gap-[var(--rad-card-header-gap,var(--rad-spacing-header-gap,0.375rem))]'
@@ -61,7 +74,10 @@ type CardPartProps<Host extends 'div' | 'h2' | 'p'> = Omit<ComponentProps<Host>,
61
74
  }
62
75
 
63
76
  /** Passive div host. Compose native actions, form state and dedicated motion wrappers explicitly. */
64
- export type CardProps = CardPartProps<'div'>
77
+ export type CardProps = CardPartProps<'div'> & {
78
+ /** Step of the card padding scale; `normal` keeps `--rad-card-padding`. */
79
+ padding?: Spacing
80
+ }
65
81
 
66
82
  export type CardHeaderProps = CardPartProps<'div'>
67
83
 
@@ -76,11 +92,11 @@ export type CardContentProps = CardPartProps<'div'>
76
92
 
77
93
  export type CardFooterProps = CardPartProps<'div'>
78
94
 
79
- export function Card({ className, ...props }: CardProps) {
95
+ export function Card({ padding, className, ...props }: CardProps) {
80
96
  return (
81
97
  <div
82
98
  {...props}
83
- className={cn(cardVariants(), className)}
99
+ className={cn(cardVariants({ padding }), className)}
84
100
  data-slot={joinIds('card', props['data-slot'])}
85
101
  />
86
102
  )