schema-components 2.1.0 → 2.1.1

package/README.md

@@ -117,6 +117,41 @@ For yarn, use the `resolutions` field with the same value.
 
 The test suite is parametrised with a `unit-preact` Vitest project that runs the same files under `preact/compat` aliasing. Run it via `pnpm test:preact` from the repo root, or directly with `pnpm exec vitest run --project=unit-preact` from `packages/core`. A small set of tests (the ones bound to the three known limitations above) fail intentionally; the remaining ~99% pass under both runtimes and establish the cross-runtime regression boundary.
 
+### Vue support
+
+Vue 3.5+ is supported as an optional peer dependency. The Vue adapter ships as **source** under `schema-components/vue/*` — the `.vue` Single File Components are not pre-compiled into the published tarball. Consumers need a Vite or webpack toolchain with `@vitejs/plugin-vue` (or equivalent) to compile the SFCs at their own build step.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+    plugins: [vue()],
+});
+```
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import SchemaComponent from "schema-components/vue/SchemaComponent.vue";
+import { z } from "zod";
+
+const userSchema = z.object({
+    name: z.string(),
+    email: z.email(),
+});
+
+const user = ref({ name: "Ada", email: "ada@example.com" });
+</script>
+
+<template>
+    <SchemaComponent :schema="userSchema" v-model="user" />
+</template>
+```
+
+The `./vue/*` export subpath resolves to the source tree (`src/vue/*.ts`) and `./vue/*.vue` resolves to the `.vue` SFCs under `src/vue/`. The same pattern is used by the Svelte adapter — both rely on the consumer's bundler to handle the framework-specific compilation step.
+
 ## `SchemaComponent`
 
 The single entry point. Accepts Zod schemas, JSON Schema objects, or OpenAPI documents:

package/dist/core/renderField.mjs

@@ -6,13 +6,14 @@ import { SchemaRenderError } from "./errors.mjs";
 *
 * Centralises the dispatch loop shared by the React `SchemaComponent` /
 * `SchemaView` renderers, the synchronous HTML renderer in
-* `renderToHtml`, and (in the future) Vue / Solid / Svelte / Lit
-* adapters. The dispatcher is intentionally framework-agnostic: it
-* neither imports React nor produces HTML strings directly. Each
-* adapter supplies a small {@link DispatchConfig} describing how to
-* build per-field props, how to handle a successful or absent resolver
-* lookup, and (optionally) how to handle widget overrides and the
-* recursion-depth cap.
+* `renderToHtml`, the streaming HTML renderer in `streamRenderers.ts`
+* (for its leaf path — see "Streaming integration" below), and (in
+* the future) Vue / Solid / Svelte / Lit adapters. The dispatcher is
+* intentionally framework-agnostic: it neither imports React nor
+* produces HTML strings directly. Each adapter supplies a small
+* {@link DispatchConfig} describing how to build per-field props, how
+* to handle a successful or absent resolver lookup, and (optionally)
+* how to handle widget overrides and the recursion-depth cap.
 *
 * The dispatch order is fixed and matches the historic React-side
 * behaviour so the React, HTML, and future adapters all observe the
@@ -32,6 +33,39 @@ import { SchemaRenderError } from "./errors.mjs";
 * The helpers that find render functions, merge resolvers, and build
 * the per-field props live in {@link "./renderer.ts"} and are reused
 * here — `core/renderField.ts` is purely the dispatch shell.
+*
+* # Streaming integration (design choice B)
+*
+* The streaming HTML renderer (`html/streamRenderers.ts` +
+* `html/renderToHtmlStream.ts`) consumes this dispatcher for leaf
+* field types — `string`, `number`, `boolean`, `enum`, `literal`,
+* `file`, `unknown` — and for variants without a dedicated streaming
+* generator (`null`, `tuple`, `conditional`, `negation`, `never`).
+* Container types (`object`, `array`, `record`, `union`,
+* `discriminatedUnion`) keep bespoke generator implementations
+* because the dispatcher's single-output contract cannot express the
+* "yield opening tag → recurse into children → yield closing tag"
+* chunk-boundary semantics that streaming depends on.
+*
+* We deliberately chose this approach (the Phase 1 agent's "option
+* B" — leaves dispatch through the shared loop, containers keep their
+* own iteration) over the alternative of building a generator-output
+* mode into the dispatcher itself. Approach B preserves the existing
+* chunk boundaries byte-for-byte while still eliminating the duplicate
+* resolver-lookup logic that previously lived in `renderLeaf`. A
+* generator-aware dispatcher would require either a parallel "stream
+* resolver" shape or a unified return type wide enough to cover both
+* single-output and iterable cases — neither of which is justified by
+* the small amount of dispatch logic the leaf path needs.
+*
+* The streaming `streamField` function performs its own depth check
+* before invoking the dispatcher for leaf paths. The check appears
+* textually in both places (streamField and this dispatcher) but at
+* runtime fires exactly once per recursion step: streamField's guard
+* filters the streaming path, and the dispatcher's guard remains in
+* place for the sync HTML and React callers that do not pre-filter
+* depth themselves. See `html/streamRenderers.ts` for the matching
+* commentary.
 */
 /**
 * Framework-agnostic dispatch loop shared by the React, HTML, and

package/dist/html/streamRenderers.d.mts

@@ -19,10 +19,19 @@ declare function yieldClose(el: HtmlElement): string;
 /**
  * Render a leaf {@link WalkedField} entirely as a single HTML chunk.
  * Used inside the streaming generators when descent into containers is
- * complete. Falls back to a `<span>`-wrapped value when no renderer is
- * registered for the field type.
+ * complete.
+ *
+ * Delegates to the framework-agnostic {@link dispatchRenderField}
+ * dispatcher so resolver lookup, the (unused) widget step, error
+ * wrapping, and the unresolved-type fallback share one implementation
+ * with the sync HTML renderer and the React adapter.
+ *
+ * @param depth - Current recursion depth — defaults to `0` so the
+ *   public signature stays additive. Callers inside the streaming
+ *   pipeline thread the live `currentDepth` so the dispatcher's
+ *   internal depth check is consistent with the streamField gate.
  */
-declare function renderLeaf(tree: WalkedField, value: unknown, mergedResolver: HtmlResolver, path: string): string;
+declare function renderLeaf(tree: WalkedField, value: unknown, mergedResolver: HtmlResolver, path: string, depth?: number): string;
 /**
  * Drain {@link streamField} into a single string. Used when a streamed
  * sub-tree needs to be embedded inside a non-streaming chunk (e.g. as

package/dist/html/streamRenderers.mjs

@@ -3,6 +3,7 @@ import "../core/limits.mjs";
 import { emitDiagnostic } from "../core/diagnostics.mjs";
 import { SC_CLASSES } from "../core/cssClasses.mjs";
 import { panelIdFor, tabIdFor } from "../core/idPath.mjs";
+import { dispatchRenderField } from "../core/renderField.mjs";
 import { getHtmlRenderFn } from "../core/renderer.mjs";
 import { matchUnionOption, resolveDiscriminatedActive } from "../core/unionMatch.mjs";
 import { VOID_ELEMENTS, h, raw, serialize, serializeAttributes } from "./html.mjs";
@@ -29,14 +30,15 @@ function yieldClose(el) {
 	return `</${el.tag}>`;
 }
 /**
-* Render a leaf {@link WalkedField} entirely as a single HTML chunk.
-* Used inside the streaming generators when descent into containers is
-* complete. Falls back to a `<span>`-wrapped value when no renderer is
-* registered for the field type.
+* Build the per-leaf {@link HtmlRenderProps} bundle handed to resolver
+* render functions and (in future) to widget renderers. The streaming
+* pipeline never recurses through `renderChild` for leaves — container
+* recursion happens through the streamField generators — so the
+* supplied `renderChild` is the constant `() => ""` stub matching the
+* historic streaming-leaf shape.
 */
-function renderLeaf(tree, value, mergedResolver, path) {
-	const renderFn = getHtmlRenderFn(tree.type, mergedResolver);
-	if (renderFn !== void 0) return renderFn({
+function buildLeafProps(tree, value, path) {
+	const props = {
 		value,
 		readOnly: tree.editability === "presentation",
 		writeOnly: tree.editability === "input",
@@ -45,11 +47,55 @@ function renderLeaf(tree, value, mergedResolver, path) {
 		path,
 		tree,
 		renderChild: () => ""
-	});
+	};
+	if (tree.examples !== void 0) props.examples = tree.examples;
+	return props;
+}
+/**
+* Build the streaming-friendly placeholder a {@link dispatchRenderField}
+* fallback emits when no resolver handled the leaf type. The sync HTML
+* dispatcher throws in this position — streaming must keep producing
+* output, so the streaming adapter renders the same `<span>` shape
+* `renderLeaf` historically produced for unresolved types.
+*/
+function leafFallbackHtml(value) {
 	if (value === void 0 || value === null) return serialize(h("span", { class: SC_CLASSES.valueEmpty }, "—"));
 	return serialize(h("span", { class: SC_CLASSES.value }, typeof value === "string" ? value : JSON.stringify(value)));
 }
 /**
+* Render a leaf {@link WalkedField} entirely as a single HTML chunk.
+* Used inside the streaming generators when descent into containers is
+* complete.
+*
+* Delegates to the framework-agnostic {@link dispatchRenderField}
+* dispatcher so resolver lookup, the (unused) widget step, error
+* wrapping, and the unresolved-type fallback share one implementation
+* with the sync HTML renderer and the React adapter.
+*
+* @param depth - Current recursion depth — defaults to `0` so the
+*   public signature stays additive. Callers inside the streaming
+*   pipeline thread the live `currentDepth` so the dispatcher's
+*   internal depth check is consistent with the streamField gate.
+*/
+function renderLeaf(tree, value, mergedResolver, path, depth = 0) {
+	return dispatchRenderField({
+		tree,
+		value,
+		path,
+		depth,
+		resolver: mergedResolver,
+		config: {
+			buildProps: (fieldTree, fieldPath) => buildLeafProps(fieldTree, value, fieldPath),
+			lookupRenderFn: (type, htmlResolver) => getHtmlRenderFn(type, htmlResolver),
+			recursionSentinel: (fieldTree) => {
+				return recursionSentinelHtml(typeof fieldTree.meta.description === "string" ? fieldTree.meta.description : "schema");
+			},
+			fallback: (_fieldTree, fieldValue) => leafFallbackHtml(fieldValue),
+			coerceResult: (result) => typeof result === "string" ? result : void 0
+		}
+	});
+}
+/**
 * Drain {@link streamField} into a single string. Used when a streamed
 * sub-tree needs to be embedded inside a non-streaming chunk (e.g. as
 * children of a parent element).
@@ -87,7 +133,7 @@ function* streamField(tree, value, mergedResolver, path, rawResolver, currentDep
 	const effectiveValue = value ?? tree.defaultValue;
 	const type = tree.type;
 	if (type === "string" || type === "number" || type === "boolean" || type === "enum" || type === "literal" || type === "file" || type === "unknown") {
-		yield renderLeaf(tree, effectiveValue, mergedResolver, path);
+		yield renderLeaf(tree, effectiveValue, mergedResolver, path, currentDepth);
 		return;
 	}
 	if (type === "union") {
@@ -110,7 +156,7 @@ function* streamField(tree, value, mergedResolver, path, rawResolver, currentDep
 		yield* streamRecord(tree, value, mergedResolver, path, rawResolver, currentDepth, diagnostics);
 		return;
 	}
-	yield renderLeaf(tree, value, mergedResolver, path);
+	yield renderLeaf(tree, value, mergedResolver, path, currentDepth);
 }
 function* streamObject(tree, value, mergedResolver, path, rawResolver, currentDepth, diagnostics) {
 	if (tree.type !== "object") return;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "schema-components",
-    "version": "2.1.0",
+    "version": "2.1.1",
     "description": "React components that render UI from Zod schemas, JSON Schema, and OpenAPI documents",
     "type": "module",
     "exports": {
@@ -29,9 +29,10 @@
             "types": "./dist/themes/*.d.mts",
             "import": "./dist/themes/*.mjs"
         },
+        "./vue/*.vue": "./src/vue/*.vue",
         "./vue/*": {
-            "types": "./dist/vue/*.d.mts",
-            "import": "./dist/vue/*.mjs"
+            "types": "./src/vue/*.ts",
+            "import": "./src/vue/*.ts"
         },
         "./svelte/*.svelte": "./src/svelte/*.svelte",
         "./svelte/renderers/*.svelte": "./src/svelte/renderers/*.svelte",
@@ -52,6 +53,7 @@
     "files": [
         "dist",
         "src/svelte",
+        "src/vue",
         "LICENSE",
         "README.md",
         "CHANGELOG.md"

package/src/vue/SchemaComponent.vue

@@ -0,0 +1,274 @@
+<script setup lang="ts">
+/**
+ * `<SchemaComponent>` — Vue counterpart of the React `<SchemaComponent>`.
+ *
+ * Auto-detects the input format, normalises to JSON Schema via the
+ * adapter, walks the JSON Schema tree, and delegates per-field
+ * rendering to the {@link VueComponentResolver} supplied via
+ * `<SchemaProvider>` — falling back to the headless renderer when no
+ * provider is present.
+ *
+ * `onChange` semantics: the component accepts BOTH a `v-model`
+ * binding (Vue-idiomatic — `modelValue` prop +
+ * `update:modelValue` emit) and an explicit `onChange` callback prop
+ * (matching the React adapter). It also emits a `change` event for
+ * Vue authors who prefer event listeners. All three surfaces fire
+ * together so consumers may use whichever idiom suits them.
+ *
+ * @group Components
+ */
+import { computed, h, toRaw, type VNode } from "vue";
+import { walk } from "../core/walker.ts";
+import type { WalkOptions } from "../core/walkBuilders.ts";
+import { normaliseSchema } from "../core/adapter.ts";
+import type { SchemaMeta, WalkedField } from "../core/types.ts";
+import type { Diagnostic, DiagnosticsOptions } from "../core/diagnostics.ts";
+import { SchemaNormalisationError } from "../core/errors.ts";
+import { toRecordOrUndefined } from "../core/guards.ts";
+import { VueResolverContext, VueWidgetsContext } from "./contexts.ts";
+import { vueRenderField } from "./renderField.ts";
+import { deriveIdPrefix, joinPath } from "./idPrefix.ts";
+import type {
+    VueComponentResolver,
+    VueRenderProps,
+    VueWidgetMap,
+} from "./types.ts";
+import { VNodeHost } from "./VNodeHost.ts";
+
+const props = withDefaults(
+    defineProps<{
+        /** Zod schema, JSON Schema object, or OpenAPI document. */
+        schema: unknown;
+        /** For OpenAPI: a ref string like `#/components/schemas/User`. */
+        refPath?: string;
+        /** v-model binding for the current value. */
+        modelValue?: unknown;
+        /**
+         * Explicit `onChange` callback — wired in parallel with
+         * `update:modelValue` so consumers may use either surface.
+         */
+        onChange?: (value: unknown) => void;
+        /** Convenience: sets `readOnly` on all fields. */
+        readOnly?: boolean;
+        /** Convenience: sets `writeOnly` on all fields. */
+        writeOnly?: boolean;
+        /** Convenience: sets `description` on the root. */
+        description?: string;
+        /** Meta overrides applied to the root schema. */
+        meta?: SchemaMeta;
+        /** Per-field meta overrides — nested object mirroring schema shape. */
+        fields?: Record<string, unknown>;
+        /** Theme resolver. Overrides the context resolver when supplied. */
+        resolver?: VueComponentResolver;
+        /** Instance-scoped widgets — override context and global widgets. */
+        widgets?: VueWidgetMap;
+        /** Deterministic id prefix. Defaults to a per-instance `useId()` value. */
+        idPrefix?: string;
+        /** Called with each diagnostic emitted during schema processing. */
+        onDiagnostic?: (diagnostic: Diagnostic) => void;
+        /** When `true`, any diagnostic becomes a thrown error. */
+        strict?: boolean;
+        /** Called when schema normalisation fails. */
+        onError?: (error: SchemaNormalisationError) => void;
+    }>(),
+    {
+        refPath: undefined,
+        modelValue: undefined,
+        onChange: undefined,
+        readOnly: false,
+        writeOnly: false,
+        description: undefined,
+        meta: () => ({}),
+        fields: undefined,
+        resolver: undefined,
+        widgets: undefined,
+        idPrefix: undefined,
+        onDiagnostic: undefined,
+        strict: false,
+        onError: undefined,
+    }
+);
+
+const emit = defineEmits<{
+    "update:modelValue": [value: unknown];
+    change: [value: unknown];
+}>();
+
+// Consume the resolver and widget contexts. Both ports return
+// `undefined` when no provider is mounted in scope — the dispatcher
+// then falls through to the headless resolver.
+const contextResolver = VueResolverContext.consume();
+const contextWidgets = VueWidgetsContext.consume();
+
+const rootPath = computed(() => deriveIdPrefix(props.idPrefix));
+
+const mergedMeta = computed<SchemaMeta>(() => {
+    const merged: SchemaMeta = { ...props.meta };
+    if (props.readOnly) merged.readOnly = true;
+    if (props.writeOnly) merged.writeOnly = true;
+    if (props.description !== undefined) merged.description = props.description;
+    return merged;
+});
+
+const diagnostics = computed<DiagnosticsOptions | undefined>(() => {
+    if (props.onDiagnostic === undefined && !props.strict) return undefined;
+    const opts: DiagnosticsOptions = {};
+    if (props.onDiagnostic !== undefined) opts.diagnostics = props.onDiagnostic;
+    if (props.strict) opts.strict = true;
+    return opts;
+});
+
+interface Normalised {
+    jsonSchema: Record<string, unknown>;
+    rootMeta: SchemaMeta | undefined;
+    rootDocument: Record<string, unknown>;
+    error?: SchemaNormalisationError;
+}
+
+const normalised = computed<Normalised>(() => {
+    try {
+        const opts =
+            diagnostics.value !== undefined
+                ? { diagnostics: diagnostics.value }
+                : undefined;
+        // Vue wraps every reactive prop in a Proxy. Zod 4 schemas
+        // carry non-configurable internal data members (`_zod`) that
+        // the default reactivity proxy cannot mirror — accessing them
+        // through the proxy throws. `toRaw` recovers the original
+        // object before passing it into `normaliseSchema`, which does
+        // not need (and should not see) Vue's reactivity layer. The
+        // same fix is applied to `props.modelValue` further down for
+        // consistency with the React adapter, which receives raw
+        // values directly.
+        const rawSchema = toRaw(props.schema);
+        const result = normaliseSchema(rawSchema, props.refPath, opts);
+        return {
+            jsonSchema: result.jsonSchema,
+            rootMeta: result.rootMeta,
+            rootDocument: result.rootDocument,
+        };
+    } catch (err) {
+        const error =
+            err instanceof SchemaNormalisationError
+                ? err
+                : new SchemaNormalisationError(
+                      err instanceof Error
+                          ? err.message
+                          : "Failed to normalise schema",
+                      toRaw(props.schema),
+                      "unknown"
+                  );
+        return {
+            jsonSchema: {},
+            rootMeta: undefined,
+            rootDocument: {},
+            error,
+        };
+    }
+});
+
+const tree = computed<WalkedField | undefined>(() => {
+    const n = normalised.value;
+    if (n.error !== undefined) return undefined;
+    const walkOptions: WalkOptions = {
+        componentMeta: mergedMeta.value,
+        rootDocument: n.rootDocument,
+    };
+    if (n.rootMeta !== undefined) walkOptions.rootMeta = n.rootMeta;
+    const fieldsRecord = toRecordOrUndefined(props.fields);
+    if (fieldsRecord !== undefined) walkOptions.fieldOverrides = fieldsRecord;
+    if (diagnostics.value !== undefined)
+        walkOptions.diagnostics = diagnostics.value;
+    return walk(n.jsonSchema, walkOptions);
+});
+
+const effectiveValue = computed<unknown>(() => {
+    if (props.modelValue !== undefined) return props.modelValue;
+    return tree.value?.defaultValue;
+});
+
+function handleChange(next: unknown): void {
+    emit("update:modelValue", next);
+    // Vue auto-wires any `onChange="…"` template attribute as a
+    // `change` event listener (the same `on<Event>` convention React
+    // uses for synthetic events). To avoid invoking the same handler
+    // twice — once via `emit("change", …)` and once via
+    // `props.onChange(…)` — we emit the event when no explicit prop
+    // handler was supplied, and call the prop directly otherwise.
+    // Both paths are observable to consumers but never overlap.
+    if (props.onChange !== undefined) {
+        props.onChange(next);
+    } else {
+        emit("change", next);
+    }
+}
+
+/**
+ * Build the recursive `renderChild` closure. Each invocation increments
+ * the depth counter so the dispatcher's `MAX_RENDER_DEPTH` cap fires
+ * on truly recursive structures rather than on shallow trees.
+ */
+function makeRenderChild(
+    currentDepth: number,
+    parentPath: string
+): VueRenderProps["renderChild"] {
+    return (
+        childTree: WalkedField,
+        childValue: unknown,
+        childOnChange: (v: unknown) => void,
+        pathSuffix?: string
+    ) => {
+        const childPath = joinPath(parentPath, pathSuffix);
+        return vueRenderField(
+            childTree,
+            childValue,
+            childOnChange,
+            props.resolver ?? contextResolver,
+            makeRenderChild(currentDepth + 1, childPath),
+            childPath,
+            props.widgets,
+            contextWidgets,
+            currentDepth + 1
+        );
+    };
+}
+
+/**
+ * Reactive root VNode. Recomputed whenever any reactive dependency
+ * (props, contexts, tree) changes. The template renders it via
+ * `<component :is="rootVNode">` — Vue accepts a VNode object as the
+ * target of `:is`, which lets us drive the render from a render
+ * function while keeping the SFC `<template>` block as the single
+ * mount point.
+ */
+const rootVNode = computed<VNode>(() => {
+    const t = tree.value;
+    if (t === undefined) {
+        const err = normalised.value.error;
+        if (err !== undefined) {
+            if (props.onError !== undefined) {
+                props.onError(err);
+                return h("span", { style: { display: "none" } });
+            }
+            throw err;
+        }
+        return h("span", { style: { display: "none" } });
+    }
+    const renderChild = makeRenderChild(0, rootPath.value);
+    return vueRenderField(
+        t,
+        effectiveValue.value,
+        handleChange,
+        props.resolver ?? contextResolver,
+        renderChild,
+        rootPath.value,
+        props.widgets,
+        contextWidgets,
+        0
+    );
+});
+</script>
+
+<template>
+    <VNodeHost :node="rootVNode" />
+</template>

package/src/vue/SchemaErrorBoundary.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+/**
+ * `<SchemaErrorBoundary>` — Vue counterpart of the React
+ * `SchemaErrorBoundary`.
+ *
+ * Uses Vue 3's `onErrorCaptured` lifecycle hook
+ * (https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured)
+ * to catch render-time errors thrown by any descendant — including
+ * the dispatcher-wrapped `SchemaRenderError` from theme adapters that
+ * throw inside their render function. Returning `false` from
+ * `onErrorCaptured` halts further propagation up the component tree.
+ *
+ * The fallback slot is invoked with the captured error and a `reset`
+ * callback. Calling `reset()` clears the captured error so the
+ * children re-render (e.g. after fixing a bad schema prop).
+ *
+ * Like the React boundary, this captures render-time and lifecycle
+ * errors but NOT errors thrown from event handlers (Vue routes those
+ * through a separate `errorHandler` on the app instance) or async
+ * code that escapes the component tree.
+ *
+ * @group Components
+ */
+import { onErrorCaptured, ref } from "vue";
+
+const captured = ref<Error | undefined>(undefined);
+
+defineSlots<{
+    /**
+     * Default slot — rendered when no error has been captured.
+     */
+    default(): unknown;
+    /**
+     * Fallback slot — invoked with the captured error and a `reset`
+     * callback. Use it to render an error UI; call `reset` to clear
+     * the captured state and let the children re-render.
+     */
+    fallback(props: { error: Error; reset: () => void }): unknown;
+}>();
+
+onErrorCaptured((err) => {
+    captured.value =
+        err instanceof Error ? err : new Error("Unknown render error");
+    return false;
+});
+
+function reset(): void {
+    captured.value = undefined;
+}
+</script>
+
+<template>
+    <slot
+        v-if="captured !== undefined"
+        name="fallback"
+        :error="captured"
+        :reset="reset"
+    />
+    <slot v-else />
+</template>