@json-render/svelte 0.6.1

package/dist/renderer.test.js

@@ -0,0 +1,168 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/svelte";
+import RendererWithProvider from "./RendererWithProvider.test.svelte";
+import TestContainer from "./TestContainer.svelte";
+import TestText from "./TestText.svelte";
+import TestButton from "./TestButton.svelte";
+import { defineRegistry } from "./renderer.js";
+describe("Renderer", () => {
+    afterEach(() => {
+        cleanup();
+    });
+    const { registry } = defineRegistry(null, {
+        components: {
+            Container: TestContainer,
+            Text: TestText,
+            Button: TestButton,
+        },
+    });
+    function mountRenderer(spec, options = {}) {
+        return render(RendererWithProvider, {
+            props: {
+                spec,
+                registry,
+                loading: options.loading ?? false,
+                initialState: spec?.state ?? {},
+            },
+        });
+    }
+    it("renders nothing for null spec", () => {
+        const { container } = mountRenderer(null);
+        // Should have no content rendered from Renderer
+        expect(container.querySelector(".test-container")).toBeNull();
+        expect(container.querySelector(".test-text")).toBeNull();
+    });
+    it("renders nothing for spec with empty root", () => {
+        const spec = { root: "", elements: {} };
+        const { container } = mountRenderer(spec);
+        expect(container.querySelector(".test-container")).toBeNull();
+    });
+    it("renders a single element", () => {
+        const spec = {
+            root: "text1",
+            elements: {
+                text1: {
+                    type: "Text",
+                    props: { text: "Hello World" },
+                    children: [],
+                },
+            },
+        };
+        const { container } = mountRenderer(spec);
+        const textEl = container.querySelector(".test-text");
+        expect(textEl).not.toBeNull();
+        expect(textEl?.textContent).toBe("Hello World");
+    });
+    it("renders nested elements", () => {
+        const spec = {
+            root: "container",
+            elements: {
+                container: {
+                    type: "Container",
+                    props: { title: "My Container" },
+                    children: ["text1", "text2"],
+                },
+                text1: {
+                    type: "Text",
+                    props: { text: "First" },
+                    children: [],
+                },
+                text2: {
+                    type: "Text",
+                    props: { text: "Second" },
+                    children: [],
+                },
+            },
+        };
+        const { container } = mountRenderer(spec);
+        const containerEl = container.querySelector(".test-container");
+        expect(containerEl).not.toBeNull();
+        expect(containerEl?.querySelector("h2")?.textContent).toBe("My Container");
+        const texts = container.querySelectorAll(".test-text");
+        expect(texts).toHaveLength(2);
+        expect(texts[0]?.textContent).toBe("First");
+        expect(texts[1]?.textContent).toBe("Second");
+    });
+    it("renders deeply nested elements", () => {
+        const spec = {
+            root: "outer",
+            elements: {
+                outer: {
+                    type: "Container",
+                    props: { title: "Outer" },
+                    children: ["inner"],
+                },
+                inner: {
+                    type: "Container",
+                    props: { title: "Inner" },
+                    children: ["text"],
+                },
+                text: {
+                    type: "Text",
+                    props: { text: "Deep text" },
+                    children: [],
+                },
+            },
+        };
+        const { container } = mountRenderer(spec);
+        const containers = container.querySelectorAll(".test-container");
+        expect(containers).toHaveLength(2);
+        const text = container.querySelector(".test-text");
+        expect(text?.textContent).toBe("Deep text");
+    });
+    it("passes loading prop to components", () => {
+        const spec = {
+            root: "container",
+            elements: {
+                container: {
+                    type: "Container",
+                    props: {},
+                    children: [],
+                },
+            },
+        };
+        const { container } = mountRenderer(spec, { loading: true });
+        const containerEl = container.querySelector(".test-container");
+        expect(containerEl?.getAttribute("data-loading")).toBe("true");
+    });
+    it("renders nothing for unknown component types without fallback", () => {
+        const spec = {
+            root: "unknown",
+            elements: {
+                unknown: {
+                    type: "UnknownType",
+                    props: {},
+                    children: [],
+                },
+            },
+        };
+        const { container } = mountRenderer(spec);
+        // No elements should be rendered for unknown type
+        expect(container.querySelector(".test-container")).toBeNull();
+        expect(container.querySelector(".test-text")).toBeNull();
+    });
+    it("skips missing child elements gracefully", () => {
+        const spec = {
+            root: "container",
+            elements: {
+                container: {
+                    type: "Container",
+                    props: { title: "Parent" },
+                    children: ["existing", "missing"],
+                },
+                existing: {
+                    type: "Text",
+                    props: { text: "I exist" },
+                    children: [],
+                },
+                // "missing" element is not defined
+            },
+        };
+        const { container } = mountRenderer(spec);
+        const containerEl = container.querySelector(".test-container");
+        expect(containerEl).not.toBeNull();
+        const texts = container.querySelectorAll(".test-text");
+        expect(texts).toHaveLength(1);
+        expect(texts[0]?.textContent).toBe("I exist");
+    });
+});

package/dist/schema.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The schema for @json-render/svelte
+ *
+ * Defines:
+ * - Spec: A flat tree of elements with keys, types, props, and children references
+ * - Catalog: Components with props schemas, and optional actions
+ */
+export declare const schema: import("@json-render/core").Schema<{
+    spec: import("@json-render/core").SchemaType<"object", {
+        /** Root element key */
+        root: import("@json-render/core").SchemaType<"string", unknown>;
+        /** Flat map of elements by key */
+        elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
+            /** Component type from catalog */
+            type: import("@json-render/core").SchemaType<"ref", string>;
+            /** Component props */
+            props: import("@json-render/core").SchemaType<"propsOf", string>;
+            /** Child element keys (flat reference) */
+            children: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
+            /** Visibility condition */
+            visible: import("@json-render/core").SchemaType<"any", unknown>;
+        }>>;
+    }>;
+    catalog: import("@json-render/core").SchemaType<"object", {
+        /** Component definitions */
+        components: import("@json-render/core").SchemaType<"map", {
+            /** Zod schema for component props */
+            props: import("@json-render/core").SchemaType<"zod", unknown>;
+            /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */
+            slots: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
+            /** Description for AI generation hints */
+            description: import("@json-render/core").SchemaType<"string", unknown>;
+            /** Example prop values used in prompt examples (auto-generated from Zod schema if omitted) */
+            example: import("@json-render/core").SchemaType<"any", unknown>;
+        }>;
+        /** Action definitions (optional) */
+        actions: import("@json-render/core").SchemaType<"map", {
+            /** Zod schema for action params */
+            params: import("@json-render/core").SchemaType<"zod", unknown>;
+            /** Description for AI generation hints */
+            description: import("@json-render/core").SchemaType<"string", unknown>;
+        }>;
+    }>;
+}>;
+/**
+ * Type for the Svelte schema
+ */
+export type SvelteSchema = typeof schema;
+/**
+ * Infer the spec type from a catalog
+ */
+export type SvelteSpec<TCatalog> = typeof schema extends {
+    createCatalog: (catalog: TCatalog) => {
+        _specType: infer S;
+    };
+} ? S : never;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,MAAM;;QAIb,uBAAuB;;QAEvB,kCAAkC;;YAG9B,kCAAkC;;YAElC,sBAAsB;;YAEtB,0CAA0C;;YAE1C,2BAA2B;;;;;QAQ/B,4BAA4B;;YAE1B,qCAAqC;;YAErC,uGAAuG;;YAEvG,0CAA0C;;YAE1C,8FAA8F;;;QAGhG,oCAAoC;;YAElC,mCAAmC;;YAEnC,0CAA0C;;;;EA+CjD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,MAAM,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,QAAQ,IAAI,OAAO,MAAM,SAAS;IACvD,aAAa,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK;QAAE,SAAS,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CAC9D,GACG,CAAC,GACD,KAAK,CAAC"}

package/dist/schema.js

@@ -0,0 +1,81 @@
+import { defineSchema } from "@json-render/core";
+/**
+ * The schema for @json-render/svelte
+ *
+ * Defines:
+ * - Spec: A flat tree of elements with keys, types, props, and children references
+ * - Catalog: Components with props schemas, and optional actions
+ */
+export const schema = defineSchema((s) => ({
+    // What the AI-generated SPEC looks like
+    spec: s.object({
+        /** Root element key */
+        root: s.string(),
+        /** Flat map of elements by key */
+        elements: s.record(s.object({
+            /** Component type from catalog */
+            type: s.ref("catalog.components"),
+            /** Component props */
+            props: s.propsOf("catalog.components"),
+            /** Child element keys (flat reference) */
+            children: s.array(s.string()),
+            /** Visibility condition */
+            visible: s.any(),
+        })),
+    }),
+    // What the CATALOG must provide
+    catalog: s.object({
+        /** Component definitions */
+        components: s.map({
+            /** Zod schema for component props */
+            props: s.zod(),
+            /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */
+            slots: s.array(s.string()),
+            /** Description for AI generation hints */
+            description: s.string(),
+            /** Example prop values used in prompt examples (auto-generated from Zod schema if omitted) */
+            example: s.any(),
+        }),
+        /** Action definitions (optional) */
+        actions: s.map({
+            /** Zod schema for action params */
+            params: s.zod(),
+            /** Description for AI generation hints */
+            description: s.string(),
+        }),
+    }),
+}), {
+    builtInActions: [
+        {
+            name: "setState",
+            description: "Update a value in the state model at the given statePath. Params: { statePath: string, value: any }",
+        },
+        {
+            name: "pushState",
+            description: '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.',
+        },
+        {
+            name: "removeState",
+            description: "Remove an item from an array in state by index. Params: { statePath: string, index: number }",
+        },
+        {
+            name: "validateForm",
+            description: "Validate all registered form fields and write the result to state. Params: { statePath?: string }. Defaults to /formValidation. Result: { valid: boolean, errors: Record<string, string[]> }.",
+        },
+    ],
+    defaultRules: [
+        // Element integrity
+        "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.",
+        // 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.',
+        // State and data
+        "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).",
+        '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"] }. 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.',
+        // Design quality
+        "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.",
+        "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.",
+        "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.",
+    ],
+});

package/dist/streaming.svelte.d.ts

@@ -0,0 +1,75 @@
+import type { Spec } from "@json-render/core";
+/**
+ * Token usage metadata from AI generation
+ */
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * UI Stream state
+ */
+export interface UIStreamState {
+    spec: Spec | null;
+    isStreaming: boolean;
+    error: Error | null;
+    usage: TokenUsage | null;
+    rawLines: string[];
+}
+/**
+ * UI Stream return type
+ */
+export interface UIStreamReturn {
+    readonly spec: Spec | null;
+    readonly isStreaming: boolean;
+    readonly error: Error | null;
+    readonly usage: TokenUsage | null;
+    readonly rawLines: string[];
+    send: (prompt: string, context?: Record<string, unknown>) => Promise<void>;
+    clear: () => void;
+}
+/**
+ * Options for createUIStream
+ */
+export interface UIStreamOptions {
+    api: string;
+    onComplete?: (spec: Spec) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a streaming UI generator using Svelte 5 $state
+ */
+export declare function createUIStream({ api, onComplete, onError, }: UIStreamOptions): UIStreamReturn;
+/**
+ * Chat message type
+ */
+export interface ChatMessage {
+    id: string;
+    role: "user" | "assistant";
+    text: string;
+    spec: Spec | null;
+}
+/**
+ * Chat UI options
+ */
+export interface ChatUIOptions {
+    api: string;
+    onComplete?: (message: ChatMessage) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Chat UI return type
+ */
+export interface ChatUIReturn {
+    readonly messages: ChatMessage[];
+    readonly isStreaming: boolean;
+    readonly error: Error | null;
+    send: (text: string) => Promise<void>;
+    clear: () => void;
+}
+/**
+ * Create a chat UI with streaming support
+ */
+export declare function createChatUI({ api, onComplete, onError, }: ChatUIOptions): ChatUIReturn;
+//# sourceMappingURL=streaming.svelte.d.ts.map

package/dist/streaming.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.svelte.d.ts","sourceRoot":"","sources":["../src/streaming.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAa,MAAM,mBAAmB,CAAC;AASzD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAClC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AA4JD;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAC7B,GAAG,EACH,UAAU,EACV,OAAO,GACR,EAAE,eAAe,GAAG,cAAc,CA+HlC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAcD;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAC3B,GAAG,EACH,UAAU,EACV,OAAO,GACR,EAAE,aAAa,GAAG,YAAY,CA8I9B"}