@xmachines/json-render-solid 0.21.0-xm.1 → 0.21.0-xm.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -0
- package/dist/{chunk-ZTWTJIEL.mjs → chunk-4IHHL4OE.mjs} +3 -1
- package/dist/chunk-4IHHL4OE.mjs.map +1 -0
- package/dist/index.d.mts +26 -2
- package/dist/index.d.ts +26 -2
- package/dist/index.js +267 -172
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +280 -187
- package/dist/index.mjs.map +1 -1
- package/dist/schema.d.mts +10 -0
- package/dist/schema.d.ts +10 -0
- package/dist/schema.js +2 -0
- package/dist/schema.js.map +1 -1
- package/dist/schema.mjs +1 -1
- package/package.json +2 -2
- package/dist/chunk-ZTWTJIEL.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -128,11 +128,42 @@ interface UIElement {
|
|
|
128
128
|
type: string;
|
|
129
129
|
props: Record<string, unknown>;
|
|
130
130
|
children?: string[];
|
|
131
|
+
slots?: Record<string, string[]>; // Named slots mapped to child keys
|
|
131
132
|
visible?: VisibilityCondition;
|
|
132
133
|
watch?: Record<string, ActionBinding | ActionBinding[]>;
|
|
133
134
|
}
|
|
134
135
|
```
|
|
135
136
|
|
|
137
|
+
## Named Slots
|
|
138
|
+
|
|
139
|
+
Use `children` for the default slot. Use the element's top-level `slots` object for the other slot names that the catalog declares:
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"type": "Layout",
|
|
144
|
+
"props": {},
|
|
145
|
+
"children": ["main"],
|
|
146
|
+
"slots": {
|
|
147
|
+
"header": ["heading"],
|
|
148
|
+
"footer": ["actions"]
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
A registry component receives `slots`, a record of the rendered content for each named slot:
|
|
154
|
+
|
|
155
|
+
```tsx
|
|
156
|
+
Layout: (ctx) => (
|
|
157
|
+
<div>
|
|
158
|
+
<header>{ctx.slots?.header}</header>
|
|
159
|
+
<main>{ctx.children}</main>
|
|
160
|
+
<footer>{ctx.slots?.footer}</footer>
|
|
161
|
+
</div>
|
|
162
|
+
),
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Each key of `slots` is a getter, like `children`, so a slot renders only when the component reads it. Keep default content in `children`: the renderer warns about a `default` entry in `slots` and ignores it. It also warns about a slot name that the catalog does not declare, and it still renders that slot.
|
|
166
|
+
|
|
136
167
|
## Providers
|
|
137
168
|
|
|
138
169
|
| Provider | Purpose |
|
|
@@ -15,6 +15,7 @@ var schema = defineSchema(
|
|
|
15
15
|
props: s.propsOf("catalog.components"),
|
|
16
16
|
/** Child element keys (flat reference) */
|
|
17
17
|
children: s.array(s.string()),
|
|
18
|
+
slots: { ...s.record(s.array(s.string())), ...s.optional() },
|
|
18
19
|
/** Visibility condition */
|
|
19
20
|
visible: { ...s.any(), ...s.optional() },
|
|
20
21
|
/** Repeat children from a state array */
|
|
@@ -68,6 +69,7 @@ var schema = defineSchema(
|
|
|
68
69
|
"CRITICAL INTEGRITY CHECK: Before outputting ANY element that references children, you MUST have already output (or will output) each child as its own element. If an element has children: ['a', 'b'], then elements 'a' and 'b' MUST exist. A missing child element causes that entire branch of the UI to be invisible.",
|
|
69
70
|
"SELF-CHECK: After generating all elements, mentally walk the tree from root. Every key in every children array must resolve to a defined element. If you find a gap, output the missing element immediately.",
|
|
70
71
|
'REQUIRED FIELDS: Every element MUST include a "children" array. Leaf elements (text, badges, inputs, images) use an empty array: "children": []. Omitting "children" fails validation.',
|
|
72
|
+
'NAMED SLOTS: Use "children" for the default slot. For other slots declared by the component, use a top-level "slots" object that maps each slot name to child element keys, for example {"slots":{"header":["heading"],"footer":["actions"]}}. Never use "slots.default". Every referenced key must exist.',
|
|
71
73
|
// Field placement
|
|
72
74
|
'CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/tab","eq":"home"},"children":[...]}.',
|
|
73
75
|
'CRITICAL: The "on" field goes on the ELEMENT object, NOT inside "props". Use on.press, on.change, on.submit etc. NEVER put action/actionParams inside props.',
|
|
@@ -87,4 +89,4 @@ export {
|
|
|
87
89
|
schema,
|
|
88
90
|
elementTreeSchema
|
|
89
91
|
};
|
|
90
|
-
//# sourceMappingURL=chunk-
|
|
92
|
+
//# sourceMappingURL=chunk-4IHHL4OE.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/schema.ts"],"sourcesContent":["import { defineSchema } from \"@xmachines/json-render-core\";\n\n/**\n * The schema for @xmachines/json-render-solid\n *\n * Defines:\n * - Spec: A flat tree of elements with keys, types, props, and children references\n * - Catalog: Components with props schemas, and optional actions\n */\nexport const schema = defineSchema(\n (s) => ({\n // What the AI-generated SPEC looks like\n spec: s.object({\n /** Root element key */\n root: s.string(),\n /** Flat map of elements by key */\n elements: s.record(\n s.object({\n /** Component type from catalog */\n type: s.ref(\"catalog.components\"),\n /** Component props */\n props: s.propsOf(\"catalog.components\"),\n /** Child element keys (flat reference) */\n children: s.array(s.string()),\n slots: { ...s.record(s.array(s.string())), ...s.optional() },\n /** Visibility condition */\n visible: { ...s.any(), ...s.optional() },\n /** Repeat children from a state array */\n repeat: { ...s.any(), ...s.optional() },\n }),\n ),\n }),\n\n // What the CATALOG must provide\n catalog: s.object({\n /** Component definitions */\n components: s.map({\n /** Zod schema for component props */\n props: s.zod(),\n /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */\n slots: s.array(s.string()),\n /** Description for AI generation hints */\n description: s.string(),\n /** Example prop values used in prompt examples (auto-generated from Zod schema if omitted) */\n example: s.any(),\n }),\n /** Action definitions (optional) */\n actions: s.map({\n /** Zod schema for action params */\n params: s.zod(),\n /** Description for AI generation hints */\n description: s.string(),\n }),\n }),\n }),\n {\n builtInActions: [\n {\n name: \"setState\",\n description:\n \"Update a value in the state model at the given statePath. Params: { statePath: string, value: any }\",\n },\n {\n name: \"pushState\",\n description:\n 'Append an item to an array in state. Params: { statePath: string, value: any, clearStatePath?: string }. Value can contain {\"$state\":\"/path\"} refs and \"$id\" for auto IDs.',\n },\n {\n name: \"removeState\",\n description:\n \"Remove an item from an array in state by index. Params: { statePath: string, index: number }\",\n },\n {\n name: \"validateForm\",\n description:\n \"Validate all registered form fields and write the result to state. Params: { statePath?: string }. Defaults to /formValidation. Result: { valid: boolean, errors: Record<string, string[]> }.\",\n },\n ],\n defaultRules: [\n // Element integrity\n \"CRITICAL INTEGRITY CHECK: Before outputting ANY element that references children, you MUST have already output (or will output) each child as its own element. If an element has children: ['a', 'b'], then elements 'a' and 'b' MUST exist. A missing child element causes that entire branch of the UI to be invisible.\",\n \"SELF-CHECK: After generating all elements, mentally walk the tree from root. Every key in every children array must resolve to a defined element. If you find a gap, output the missing element immediately.\",\n 'REQUIRED FIELDS: Every element MUST include a \"children\" array. Leaf elements (text, badges, inputs, images) use an empty array: \"children\": []. Omitting \"children\" fails validation.',\n 'NAMED SLOTS: Use \"children\" for the default slot. For other slots declared by the component, use a top-level \"slots\" object that maps each slot name to child element keys, for example {\"slots\":{\"header\":[\"heading\"],\"footer\":[\"actions\"]}}. Never use \"slots.default\". Every referenced key must exist.',\n\n // Field placement\n 'CRITICAL: The \"visible\" field goes on the ELEMENT object, NOT inside \"props\". Correct: {\"type\":\"<ComponentName>\",\"props\":{},\"visible\":{\"$state\":\"/tab\",\"eq\":\"home\"},\"children\":[...]}.',\n 'CRITICAL: The \"on\" field goes on the ELEMENT object, NOT inside \"props\". Use on.press, on.change, on.submit etc. NEVER put action/actionParams inside props.',\n\n // State and data\n \"When the user asks for a UI that displays data (e.g. blog posts, products, users), ALWAYS include a state field with realistic sample data. The state field is a top-level field on the spec (sibling of root/elements).\",\n 'When building repeating content backed by a state array (e.g. posts, products, items), use the \"repeat\" field on a container element. Example: { \"type\": \"<ContainerComponent>\", \"props\": {}, \"repeat\": { \"statePath\": \"/posts\", \"key\": \"id\" }, \"children\": [\"post-card\"] }. For a nested list stored on the enclosing item, use \"repeat\": { \"statePath\": { \"$item\": \"comments\" }, \"key\": \"id\" }. The $item statePath form is valid only inside another repeat. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { \"$item\": \"field\" } to read a field from the current item, and { \"$index\": true } for the current array index. For two-way binding to an item field use { \"$bindItem\": \"completed\" }. Do NOT hardcode individual elements for each array item.',\n\n // Design quality\n \"Design with visual hierarchy: use container components to group content, heading components for section titles, proper spacing, and status indicators. ONLY use components from the AVAILABLE COMPONENTS list.\",\n \"For data-rich UIs, use multi-column layout components if available. For forms and single-column content, use vertical layout components. ONLY use components from the AVAILABLE COMPONENTS list.\",\n \"Always include realistic, professional-looking sample data. For blogs include 3-4 posts with varied titles, authors, dates, categories. For products include names, prices, images. Never leave data empty.\",\n ],\n },\n);\n\n/**\n * Type for the Solid schema\n */\nexport type SolidSchema = typeof schema;\n\n/**\n * Infer the spec type from a catalog\n */\nexport type SolidSpec<TCatalog> = typeof schema extends {\n createCatalog: (catalog: TCatalog) => { _specType: infer S };\n}\n ? S\n : never;\n\n// Backward compatibility aliases\n/** @deprecated Use `schema` instead */\nexport const elementTreeSchema = schema;\n/** @deprecated Use `SolidSchema` instead */\nexport type ElementTreeSchema = SolidSchema;\n/** @deprecated Use `SolidSpec` instead */\nexport type ElementTreeSpec<T> = SolidSpec<T>;\n"],"mappings":";AAAA,SAAS,oBAAoB;AAStB,IAAM,SAAS;AAAA,EACpB,CAAC,OAAO;AAAA;AAAA,IAEN,MAAM,EAAE,OAAO;AAAA;AAAA,MAEb,MAAM,EAAE,OAAO;AAAA;AAAA,MAEf,UAAU,EAAE;AAAA,QACV,EAAE,OAAO;AAAA;AAAA,UAEP,MAAM,EAAE,IAAI,oBAAoB;AAAA;AAAA,UAEhC,OAAO,EAAE,QAAQ,oBAAoB;AAAA;AAAA,UAErC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC;AAAA,UAC5B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,SAAS,EAAE;AAAA;AAAA,UAE3D,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,GAAG,EAAE,SAAS,EAAE;AAAA;AAAA,UAEvC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAG,GAAG,EAAE,SAAS,EAAE;AAAA,QACxC,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAAA;AAAA,IAGD,SAAS,EAAE,OAAO;AAAA;AAAA,MAEhB,YAAY,EAAE,IAAI;AAAA;AAAA,QAEhB,OAAO,EAAE,IAAI;AAAA;AAAA,QAEb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC;AAAA;AAAA,QAEzB,aAAa,EAAE,OAAO;AAAA;AAAA,QAEtB,SAAS,EAAE,IAAI;AAAA,MACjB,CAAC;AAAA;AAAA,MAED,SAAS,EAAE,IAAI;AAAA;AAAA,QAEb,QAAQ,EAAE,IAAI;AAAA;AAAA,QAEd,aAAa,EAAE,OAAO;AAAA,MACxB,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AAAA,EACA;AAAA,IACE,gBAAgB;AAAA,MACd;AAAA,QACE,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,IACF;AAAA,IACA,cAAc;AAAA;AAAA,MAEZ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA;AAAA,MAGA;AAAA,MACA;AAAA;AAAA,MAGA;AAAA,MACA;AAAA;AAAA,MAGA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAkBO,IAAM,oBAAoB;","names":[]}
|
package/dist/index.d.mts
CHANGED
|
@@ -10,6 +10,12 @@ interface StateContextValue {
|
|
|
10
10
|
set: (path: string, value: unknown) => void;
|
|
11
11
|
update: (updates: Record<string, unknown>) => void;
|
|
12
12
|
getSnapshot: () => StateModel;
|
|
13
|
+
/**
|
|
14
|
+
* Hear the paths that `set` and `update` of this context write. The watch
|
|
15
|
+
* of the renderer reads the reactive state and does not use it, because a
|
|
16
|
+
* write from the store or to a parent path emits no change here. It stays
|
|
17
|
+
* for hosts that use it.
|
|
18
|
+
*/
|
|
13
19
|
subscribeChanges: (listener: (changes: Array<{
|
|
14
20
|
path: string;
|
|
15
21
|
value: unknown;
|
|
@@ -39,7 +45,8 @@ declare function useIsVisible(condition: VisibilityCondition | undefined): boole
|
|
|
39
45
|
|
|
40
46
|
interface PendingConfirmation {
|
|
41
47
|
action: ResolvedAction;
|
|
42
|
-
handler
|
|
48
|
+
/** The handler of the host, or undefined for a built-in action. */
|
|
49
|
+
handler: ActionHandler | undefined;
|
|
43
50
|
resolve: () => void;
|
|
44
51
|
reject: () => void;
|
|
45
52
|
}
|
|
@@ -111,6 +118,13 @@ interface RepeatScopeValue {
|
|
|
111
118
|
basePath: string;
|
|
112
119
|
}
|
|
113
120
|
declare function RepeatScopeProvider(props: ParentProps<RepeatScopeValue>): solid_js.JSX.Element;
|
|
121
|
+
/**
|
|
122
|
+
* The repeat scope of the row that renders now, or `null` outside a repeat.
|
|
123
|
+
*
|
|
124
|
+
* Read `item`, `index` and `basePath` in a tracked place: the JSX, a memo or
|
|
125
|
+
* an effect. A row stays mounted across a write to its own item, so a copy
|
|
126
|
+
* that the component makes when it is set up keeps the item of then.
|
|
127
|
+
*/
|
|
114
128
|
declare function useRepeatScope(): RepeatScopeValue | null;
|
|
115
129
|
|
|
116
130
|
/**
|
|
@@ -151,6 +165,11 @@ interface EventHandle {
|
|
|
151
165
|
interface BaseComponentProps<P = Record<string, unknown>> {
|
|
152
166
|
props: P;
|
|
153
167
|
children?: JSX.Element;
|
|
168
|
+
/**
|
|
169
|
+
* Rendered content for each named slot of the element (`element.slots`).
|
|
170
|
+
* A slot renders only when the component reads its key, like `children`.
|
|
171
|
+
*/
|
|
172
|
+
slots?: Record<string, JSX.Element>;
|
|
154
173
|
/** Simple event emitter (shorthand). Fires the event and returns void. */
|
|
155
174
|
emit: (event: string) => void;
|
|
156
175
|
/** Get an event handle with metadata. Use when you need shouldPreventDefault or bound checks. */
|
|
@@ -226,6 +245,11 @@ interface ComponentRenderProps<P = Record<string, unknown>> {
|
|
|
226
245
|
element: UIElement<string, P>;
|
|
227
246
|
/** Rendered children */
|
|
228
247
|
children?: JSX.Element;
|
|
248
|
+
/**
|
|
249
|
+
* Rendered content for each named slot of the element (`element.slots`).
|
|
250
|
+
* Each key is a getter, so a slot renders only when the component reads it.
|
|
251
|
+
*/
|
|
252
|
+
slots?: Record<string, JSX.Element>;
|
|
229
253
|
/** Emit a named event. The renderer resolves the event to action binding(s) from the element's `on` field. Always provided by the renderer. */
|
|
230
254
|
emit: (event: string) => void;
|
|
231
255
|
/** Get an event handle with metadata (shouldPreventDefault, bound). Use when you need to inspect event bindings. */
|
|
@@ -355,7 +379,7 @@ type DefineRegistryOptions<C extends Catalog> = {
|
|
|
355
379
|
* });
|
|
356
380
|
* ```
|
|
357
381
|
*/
|
|
358
|
-
declare function defineRegistry<C extends Catalog>(
|
|
382
|
+
declare function defineRegistry<C extends Catalog>(catalog: C, options: DefineRegistryOptions<C>): DefineRegistryResult;
|
|
359
383
|
/**
|
|
360
384
|
* Props for renderers created with createRenderer
|
|
361
385
|
*/
|
package/dist/index.d.ts
CHANGED
|
@@ -10,6 +10,12 @@ interface StateContextValue {
|
|
|
10
10
|
set: (path: string, value: unknown) => void;
|
|
11
11
|
update: (updates: Record<string, unknown>) => void;
|
|
12
12
|
getSnapshot: () => StateModel;
|
|
13
|
+
/**
|
|
14
|
+
* Hear the paths that `set` and `update` of this context write. The watch
|
|
15
|
+
* of the renderer reads the reactive state and does not use it, because a
|
|
16
|
+
* write from the store or to a parent path emits no change here. It stays
|
|
17
|
+
* for hosts that use it.
|
|
18
|
+
*/
|
|
13
19
|
subscribeChanges: (listener: (changes: Array<{
|
|
14
20
|
path: string;
|
|
15
21
|
value: unknown;
|
|
@@ -39,7 +45,8 @@ declare function useIsVisible(condition: VisibilityCondition | undefined): boole
|
|
|
39
45
|
|
|
40
46
|
interface PendingConfirmation {
|
|
41
47
|
action: ResolvedAction;
|
|
42
|
-
handler
|
|
48
|
+
/** The handler of the host, or undefined for a built-in action. */
|
|
49
|
+
handler: ActionHandler | undefined;
|
|
43
50
|
resolve: () => void;
|
|
44
51
|
reject: () => void;
|
|
45
52
|
}
|
|
@@ -111,6 +118,13 @@ interface RepeatScopeValue {
|
|
|
111
118
|
basePath: string;
|
|
112
119
|
}
|
|
113
120
|
declare function RepeatScopeProvider(props: ParentProps<RepeatScopeValue>): solid_js.JSX.Element;
|
|
121
|
+
/**
|
|
122
|
+
* The repeat scope of the row that renders now, or `null` outside a repeat.
|
|
123
|
+
*
|
|
124
|
+
* Read `item`, `index` and `basePath` in a tracked place: the JSX, a memo or
|
|
125
|
+
* an effect. A row stays mounted across a write to its own item, so a copy
|
|
126
|
+
* that the component makes when it is set up keeps the item of then.
|
|
127
|
+
*/
|
|
114
128
|
declare function useRepeatScope(): RepeatScopeValue | null;
|
|
115
129
|
|
|
116
130
|
/**
|
|
@@ -151,6 +165,11 @@ interface EventHandle {
|
|
|
151
165
|
interface BaseComponentProps<P = Record<string, unknown>> {
|
|
152
166
|
props: P;
|
|
153
167
|
children?: JSX.Element;
|
|
168
|
+
/**
|
|
169
|
+
* Rendered content for each named slot of the element (`element.slots`).
|
|
170
|
+
* A slot renders only when the component reads its key, like `children`.
|
|
171
|
+
*/
|
|
172
|
+
slots?: Record<string, JSX.Element>;
|
|
154
173
|
/** Simple event emitter (shorthand). Fires the event and returns void. */
|
|
155
174
|
emit: (event: string) => void;
|
|
156
175
|
/** Get an event handle with metadata. Use when you need shouldPreventDefault or bound checks. */
|
|
@@ -226,6 +245,11 @@ interface ComponentRenderProps<P = Record<string, unknown>> {
|
|
|
226
245
|
element: UIElement<string, P>;
|
|
227
246
|
/** Rendered children */
|
|
228
247
|
children?: JSX.Element;
|
|
248
|
+
/**
|
|
249
|
+
* Rendered content for each named slot of the element (`element.slots`).
|
|
250
|
+
* Each key is a getter, so a slot renders only when the component reads it.
|
|
251
|
+
*/
|
|
252
|
+
slots?: Record<string, JSX.Element>;
|
|
229
253
|
/** Emit a named event. The renderer resolves the event to action binding(s) from the element's `on` field. Always provided by the renderer. */
|
|
230
254
|
emit: (event: string) => void;
|
|
231
255
|
/** Get an event handle with metadata (shouldPreventDefault, bound). Use when you need to inspect event bindings. */
|
|
@@ -355,7 +379,7 @@ type DefineRegistryOptions<C extends Catalog> = {
|
|
|
355
379
|
* });
|
|
356
380
|
* ```
|
|
357
381
|
*/
|
|
358
|
-
declare function defineRegistry<C extends Catalog>(
|
|
382
|
+
declare function defineRegistry<C extends Catalog>(catalog: C, options: DefineRegistryOptions<C>): DefineRegistryResult;
|
|
359
383
|
/**
|
|
360
384
|
* Props for renderers created with createRenderer
|
|
361
385
|
*/
|