@json-render/vue 0.20.0 → 0.21.1

package/README.md

@@ -26,6 +26,7 @@ export const catalog = defineCatalog(schema, {
         title: z.string(),
         description: z.string().nullable(),
       }),
+      slots: ["default", "header", "footer"],
       description: "A card container",
     },
     Button: {
@@ -53,7 +54,7 @@ export const catalog = defineCatalog(schema, {
 
 ### 2. Define Component Implementations
 
-Components are written using Vue's `h()` render function. `children` is a `VNode | VNode[]` — pass it directly to your container element.
+Components are written using Vue's `h()` render function. The `slots` context uses Vue's native slot functions, so render a region with `slots.header?.()`. For convenience and React parity, `children` contains the already-rendered result of `slots.default?.()`.
 
 `defineRegistry` conditionally requires the `actions` field only when the catalog declares actions. Catalogs with `actions: {}` can omit it entirely.
 
@@ -64,11 +65,12 @@ import { catalog } from "./catalog";
 
 export const { registry } = defineRegistry(catalog, {
   components: {
-    Card: ({ props, children }) =>
+    Card: ({ props, slots }) =>
       h("div", { class: "card" }, [
-        h("h3", null, props.title),
+        h("header", null, slots.header?.() ?? h("h3", null, props.title)),
         props.description ? h("p", null, props.description) : null,
-        children,
+        slots.default?.(),
+        h("footer", null, slots.footer?.()),
       ]),
     Button: ({ props, emit }) =>
       h("button", { onClick: () => emit("press") }, props.label),
@@ -131,6 +133,7 @@ interface UIElement {
   type: string;                          // Component name from catalog
   props: Record<string, unknown>;        // Component props
   children?: string[];                   // Keys of child elements
+  slots?: Record<string, string[]>;      // Named slots mapped to child keys
   visible?: VisibilityCondition;         // Visibility condition
 }
 ```
@@ -163,6 +166,35 @@ Example spec:
 }
 ```
 
+### Named Slots
+
+Use `children` for the default slot and the element's top-level `slots` object for other slot names declared by the catalog:
+
+```typescript
+Layout: ({ children, slots }) =>
+  h("div", null, [
+    h("header", null, slots.header?.()),
+    h("main", null, children),
+    h("footer", null, slots.footer?.()),
+  ]),
+```
+
+The corresponding spec maps element keys to each region:
+
+```json
+{
+  "type": "Layout",
+  "props": {},
+  "children": ["main-content"],
+  "slots": {
+    "header": ["page-heading"],
+    "footer": ["page-actions"]
+  }
+}
+```
+
+Registry components receive Vue-native slot functions and render them with `slots.header?.()`, `slots.footer?.()`, and so on. `slots.default?.()` renders the spec's `children`; `children` is an alias for that rendered result. In the JSON spec, keep default content in `children` rather than adding a `default` entry to `slots`.
+
 ## Providers
 
 ### StateProvider
@@ -366,11 +398,12 @@ The `setState`, `pushState`, `removeState`, and `validateForm` actions are built
 When using `defineRegistry`, components receive these props via their render function:
 
 ```typescript
-import type { VNode } from "vue";
+import type { Slots, VNode } from "vue";
 
 interface ComponentContext<P> {
   props: P;                          // Typed props from the catalog (expressions resolved)
   children?: VNode | VNode[];        // Rendered children (for container components)
+  slots: Slots;                      // Vue-native slot functions
   emit: (event: string) => void;     // Emit a named event (always defined)
   on: (event: string) => EventHandle; // Get event handle with metadata
   loading?: boolean;                 // Whether the parent is loading

package/dist/{chunk-F4CKBTOP.mjs → chunk-34A2QV2X.mjs}

@@ -15,6 +15,8 @@ var schema = defineSchema(
           props: s.propsOf("catalog.components"),
           /** Child element keys (flat reference) */
           children: s.array(s.string()),
+          /** Named slots mapped to child element keys */
+          slots: { ...s.record(s.array(s.string())), ...s.optional() },
           /** Visibility condition */
           visible: { ...s.any(), ...s.optional() },
           /** Repeat children from a state array */
@@ -68,6 +70,7 @@ var schema = defineSchema(
       "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.",
       "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.",
       'REQUIRED FIELDS: Every element MUST include a "children" array. Leaf elements (text, badges, inputs, images) use an empty array: "children": []. Omitting "children" fails validation.',
+      '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.',
       // Field placement
       'CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/tab","eq":"home"},"children":[...]}.',
       '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.',
@@ -85,4 +88,4 @@ var schema = defineSchema(
 export {
   schema
 };
-//# sourceMappingURL=chunk-F4CKBTOP.mjs.map
+//# sourceMappingURL=chunk-34A2QV2X.mjs.map

package/dist/chunk-34A2QV2X.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"sourcesContent":["import { defineSchema } from \"@json-render/core\";\n\n/**\n * The schema for @json-render/vue\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          /** Named slots mapped to child element keys */\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 Vue schema\n */\nexport type VueSchema = typeof schema;\n\n/**\n * Infer the spec type from a catalog\n */\nexport type VueSpec<TCatalog> = typeof schema extends {\n  createCatalog: (catalog: TCatalog) => { _specType: infer S };\n}\n  ? S\n  : never;\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;AAAA,UAE5B,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;","names":[]}

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as vue from 'vue';
-import { PropType, ShallowRef, ComputedRef, VNode, Ref, Component } from 'vue';
+import { PropType, ShallowRef, ComputedRef, VNode, Slots, Ref, Component } from 'vue';
 import { StateStore, StateModel, VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, ActionBinding, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, Catalog, InferCatalogComponents, InferComponentProps, InferCatalogActions, InferActionParams, Spec, FlatElement, SchemaDefinition, ComputedFunction, DirectiveDefinition, UIElement } from '@json-render/core';
 export { ComputedFunction, Spec, StateModel, StateStore, createStateStore } from '@json-render/core';
 export { VueSchema, VueSpec, schema } from './schema.mjs';
@@ -384,6 +384,8 @@ interface BaseComponentProps<P = Record<string, unknown>> {
     props: P;
     /** Rendered children (from the default slot) */
     children?: VNode | VNode[];
+    /** Vue-native slot functions, including the default slot */
+    slots: Slots;
     /** Simple event emitter (shorthand). Fires the event and returns void. */
     emit: (event: string) => void;
     /** Get an event handle with metadata. Use when you need shouldPreventDefault or bound checks. */
@@ -849,7 +851,7 @@ type DefineRegistryOptions<C extends Catalog> = {
  * });
  * ```
  */
-declare function defineRegistry<C extends Catalog>(_catalog: C, options: DefineRegistryOptions<C>): DefineRegistryResult;
+declare function defineRegistry<C extends Catalog>(catalog: C, options: DefineRegistryOptions<C>): DefineRegistryResult;
 /**
  * Props for renderers created with createRenderer
  */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as vue from 'vue';
-import { PropType, ShallowRef, ComputedRef, VNode, Ref, Component } from 'vue';
+import { PropType, ShallowRef, ComputedRef, VNode, Slots, Ref, Component } from 'vue';
 import { StateStore, StateModel, VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, ActionBinding, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, Catalog, InferCatalogComponents, InferComponentProps, InferCatalogActions, InferActionParams, Spec, FlatElement, SchemaDefinition, ComputedFunction, DirectiveDefinition, UIElement } from '@json-render/core';
 export { ComputedFunction, Spec, StateModel, StateStore, createStateStore } from '@json-render/core';
 export { VueSchema, VueSpec, schema } from './schema.js';
@@ -384,6 +384,8 @@ interface BaseComponentProps<P = Record<string, unknown>> {
     props: P;
     /** Rendered children (from the default slot) */
     children?: VNode | VNode[];
+    /** Vue-native slot functions, including the default slot */
+    slots: Slots;
     /** Simple event emitter (shorthand). Fires the event and returns void. */
     emit: (event: string) => void;
     /** Get an event handle with metadata. Use when you need shouldPreventDefault or bound checks. */
@@ -849,7 +851,7 @@ type DefineRegistryOptions<C extends Catalog> = {
  * });
  * ```
  */
-declare function defineRegistry<C extends Catalog>(_catalog: C, options: DefineRegistryOptions<C>): DefineRegistryResult;
+declare function defineRegistry<C extends Catalog>(catalog: C, options: DefineRegistryOptions<C>): DefineRegistryResult;
 /**
  * Props for renderers created with createRenderer
  */

package/dist/index.js

@@ -783,6 +783,8 @@ var schema = (0, import_core5.defineSchema)(
           props: s.propsOf("catalog.components"),
           /** Child element keys (flat reference) */
           children: s.array(s.string()),
+          /** Named slots mapped to child element keys */
+          slots: { ...s.record(s.array(s.string())), ...s.optional() },
           /** Visibility condition */
           visible: { ...s.any(), ...s.optional() },
           /** Repeat children from a state array */
@@ -836,6 +838,7 @@ var schema = (0, import_core5.defineSchema)(
       "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.",
       "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.",
       'REQUIRED FIELDS: Every element MUST include a "children" array. Leaf elements (text, badges, inputs, images) use an empty array: "children": []. Omitting "children" fails validation.',
+      '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.',
       // Field placement
       'CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/tab","eq":"home"},"children":[...]}.',
       '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.',
@@ -1333,6 +1336,7 @@ function useChatUI({
 // src/renderer.ts
 var import_vue7 = require("vue");
 var import_core7 = require("@json-render/core");
+var registryMetadata = /* @__PURE__ */ new WeakMap();
 var EMPTY_FUNCTIONS = {};
 var FUNCTIONS_KEY = /* @__PURE__ */ Symbol("json-render:functions");
 var FunctionsProvider = (0, import_vue7.defineComponent)({
@@ -1557,18 +1561,28 @@ var ElementRenderer = (0, import_vue7.defineComponent)({
         );
         return null;
       }
-      const childrenVNodes = resolvedElement.repeat ? (0, import_vue7.h)(RepeatChildren, {
-        element: resolvedElement,
-        spec: props.spec,
-        registry: props.registry,
-        loading: props.loading,
-        fallback: props.fallback
-      }) : resolvedElement.children?.map((childKey) => {
+      const metadata = registryMetadata.get(props.registry)?.[resolvedElement.type];
+      if (resolvedElement.slots && metadata?.slots) {
+        const availableSlots = new Set(metadata.slots);
+        for (const slotName of Object.keys(resolvedElement.slots)) {
+          if (slotName === "default") {
+            console.warn(
+              `[json-render] Component "${resolvedElement.type}" uses slots.default. Use "children" for default slot content.`
+            );
+          } else if (!availableSlots.has(slotName)) {
+            console.warn(
+              `[json-render] Unknown slot "${slotName}" on component "${resolvedElement.type}". Available slots: ${metadata.slots.join(", ")}`
+            );
+          }
+        }
+      }
+      const renderChildKeys = (childKeys, slotName) => childKeys.map((childKey) => {
         const childElement = props.spec.elements[childKey];
         if (!childElement) {
           if (!props.loading) {
+            const location = slotName ? `in slot "${slotName}" of "${resolvedElement.type}"` : `as child of "${resolvedElement.type}"`;
             console.warn(
-              `[json-render] Missing element "${childKey}" referenced as child of "${resolvedElement.type}". This element will not render.`
+              `[json-render] Missing element "${childKey}" referenced ${location}. This element will not render.`
             );
           }
           return null;
@@ -1582,7 +1596,20 @@ var ElementRenderer = (0, import_vue7.defineComponent)({
           loading: props.loading,
           fallback: props.fallback
         });
-      }).filter((n) => n !== null) ?? void 0;
+      }).filter((node) => node !== null);
+      const childrenVNodes = resolvedElement.repeat ? (0, import_vue7.h)(RepeatChildren, {
+        element: resolvedElement,
+        spec: props.spec,
+        registry: props.registry,
+        loading: props.loading,
+        fallback: props.fallback
+      }) : resolvedElement.children ? renderChildKeys(resolvedElement.children) : void 0;
+      const namedSlots = resolvedElement.slots ? Object.fromEntries(
+        Object.entries(resolvedElement.slots).filter(([slotName]) => slotName !== "default").map(([slotName, childKeys]) => [
+          slotName,
+          () => renderChildKeys(childKeys, slotName)
+        ])
+      ) : {};
       const componentVNode = (0, import_vue7.h)(
         Component,
         {
@@ -1592,7 +1619,7 @@ var ElementRenderer = (0, import_vue7.defineComponent)({
           bindings: elementBindings,
           loading: props.loading
         },
-        { default: () => childrenVNodes }
+        { default: () => childrenVNodes, ...namedSlots }
       );
       const tagged = devtoolsActive.value && props.elementKey ? (0, import_vue7.h)(
         "span",
@@ -1821,7 +1848,7 @@ var JSONUIProvider = (0, import_vue7.defineComponent)({
     );
   }
 });
-function defineRegistry(_catalog, options) {
+function defineRegistry(catalog, options) {
   const registry = {};
   if (options.components) {
     for (const [name, componentFn] of Object.entries(options.components)) {
@@ -1853,6 +1880,7 @@ function defineRegistry(_catalog, options) {
           return () => componentFn({
             props: registryProps.element.props,
             children: slots.default?.(),
+            slots,
             emit: registryProps.emit,
             on: registryProps.on,
             bindings: registryProps.bindings,
@@ -1862,6 +1890,10 @@ function defineRegistry(_catalog, options) {
       });
     }
   }
+  const catalogComponents = catalog.data?.components;
+  if (catalogComponents) {
+    registryMetadata.set(registry, catalogComponents);
+  }
   const actionMap = options.actions ? Object.entries(options.actions) : [];
   const handlers = (getSetState, getState) => {
     const result = {};
@@ -1888,6 +1920,10 @@ function defineRegistry(_catalog, options) {
 }
 function createRenderer(catalog, components) {
   const registry = components;
+  const catalogComponents = catalog.data.components;
+  if (catalogComponents) {
+    registryMetadata.set(registry, catalogComponents);
+  }
   return (0, import_vue7.defineComponent)({
     name: "CatalogRenderer",
     props: {