feat(vue): support named slots (#323)

Recreate the Vue named slots implementation from #322 and add regression coverage for raw registries, lazy slots, diagnostics, loading, repeat scope, and prompt output.

Co-authored-by: wotnak <wotnak@pm.me>

Author: Railly

apps/web/app/(main)/docs/api/vue/page.mdx

@@ -95,7 +95,7 @@ store.set("/count", 1);
 
 ## defineRegistry
 
-Create a type-safe component registry from a catalog. Components receive `props`, `children`, `emit`, `on`, and `loading` with catalog-inferred types.
+Create a type-safe component registry from a catalog. Components receive `props`, `children`, `slots`, `emit`, `on`, and `loading` with catalog-inferred types.
 
 When the catalog declares actions, the `actions` field is required. When the catalog has no actions (e.g. `actions: {}`), the field is optional. When passing stubs, any `async () => {}` is sufficient.
 
@@ -105,8 +105,12 @@ import { defineRegistry } from "@json-render/vue";
 
 const { registry } = defineRegistry(catalog, {
   components: {
-    Card: ({ props, children }) =>
-      h("div", { class: "card" }, [h("h3", null, props.title), children]),
+    Layout: ({ slots }) =>
+      h("div", { class: "layout" }, [
+        h("header", null, slots.header?.()),
+        h("main", null, slots.default?.()),
+        h("footer", null, slots.footer?.()),
+      ]),
     Button: ({ props, emit }) =>
       h("button", { onClick: () => emit("press") }, props.label),
   },
@@ -136,11 +140,12 @@ const { registry } = defineRegistry(catalog, {
 ### Component Props (via defineRegistry)
 
 ```typescript
-import type { VNode } from "vue";
+import type { Slots, VNode } from "vue";
 
 interface ComponentContext<P> {
   props: P;                          // Typed props from catalog
   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;
@@ -154,6 +159,22 @@ interface EventHandle {
 }
 ```
 
+Use `children` for the default slot. For other slots declared by the catalog, add a top-level `slots` map to the spec element:
+
+```json
+{
+  "type": "Layout",
+  "props": {},
+  "children": ["main-content"],
+  "slots": {
+    "header": ["page-heading"],
+    "footer": ["page-actions"]
+  }
+}
+```
+
+The component renders these regions with Vue's native slot functions: `slots.header?.()`, `slots.footer?.()`, and so on. `slots.default?.()` renders the spec's `children`; `children` is a convenience alias for that rendered result. In the JSON spec, keep default content in `children` rather than adding a `default` entry to `slots`.
+
 Use `emit("press")` for simple event firing. Use `on("click")` when you need metadata like `shouldPreventDefault`:
 
 ```typescript

apps/web/app/(main)/docs/specs/page.mdx

@@ -206,7 +206,7 @@ Each element in the map has a consistent shape:
 - `type` — Component type from your catalog
 - `props` — Component properties
 - `children` — Array of child element keys
-- `slots`: Optional map of named slots to child element keys. Use `children` for the default slot. Named slot rendering is currently supported by `@json-render/react`.
+- `slots`: Optional map of named slots to child element keys. Use `children` for the default slot. Named slot rendering is supported by `@json-render/react` and `@json-render/vue`.
 
 ### Dynamic Data
 

packages/vue/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

packages/vue/src/catalog-types.ts

@@ -1,4 +1,4 @@
-import type { VNode } from "vue";
+import type { Slots, VNode } from "vue";
 import type {
   Catalog,
   InferCatalogComponents,
@@ -59,6 +59,8 @@ export 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. */

packages/vue/src/hooks.test.ts

@@ -128,6 +128,31 @@ describe("buildSpecFromParts", () => {
     ];
     expect(buildSpecFromParts(parts)).toBeNull();
   });
+
+  it("preserves named slots in nested spec parts", () => {
+    const spec = buildSpecFromParts([
+      {
+        type: SPEC_DATA_PART_TYPE,
+        data: {
+          type: "nested",
+          spec: {
+            type: "Layout",
+            props: {},
+            slots: {
+              header: [
+                { type: "Heading", props: { text: "Header" }, children: [] },
+              ],
+            },
+          },
+        },
+      },
+    ]);
+
+    expect(spec).not.toBeNull();
+    const root = spec!.elements[spec!.root]!;
+    expect(root.slots?.header).toHaveLength(1);
+    expect(spec!.elements[root.slots!.header![0]!]!.type).toBe("Heading");
+  });
 });
 
 // ---------------------------------------------------------------------------