schema-components 2.1.0 → 3.0.0

package/dist/solid/SchemaComponent.d.mts

@@ -42,17 +42,17 @@ declare function SchemaProvider(props: {
  *
  * @group Components
  */
-interface SchemaComponentProps<T = unknown, Ref extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> {
+interface SchemaComponentProps<T = unknown, SchemaRef extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> {
   /** Zod schema, JSON Schema object, or OpenAPI document. */
   schema: RejectUnrepresentableZod<T>;
   /** For OpenAPI: a ref string like `"#/components/schemas/User"`. */
-  ref?: Ref;
+  schemaRef?: SchemaRef;
   /** Which side of every transform / pipe / codec to render. */
   io?: Mode;
   /** Current value to render — typed against the schema's inferred shape. */
-  value?: InferSchemaValue<T, Ref, Mode>;
+  value?: InferSchemaValue<T, SchemaRef, Mode>;
   /** Called when the value changes; receives the next value. */
-  onChange?: (value: InferSchemaValue<T, Ref, Mode>) => void;
+  onChange?: (value: InferSchemaValue<T, SchemaRef, Mode>) => void;
   /** Run `safeParse` / `safeEncode` on change and route errors. */
   validate?: boolean;
   /** Called with the validation error when validation fails. */
@@ -64,7 +64,7 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
   /** When true, any diagnostic becomes a thrown error. */
   strict?: boolean;
   /** Per-field meta overrides — nested object mirroring schema shape. */
-  fields?: InferFields<T, Ref>;
+  fields?: InferFields<T, SchemaRef>;
   /** Meta overrides applied to the root schema. */
   meta?: SchemaMeta;
   /** Convenience: sets readOnly on all fields. */
@@ -131,6 +131,6 @@ declare function renderField(tree: WalkedField, value: unknown, onChange: (v: un
  * <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
  * ```
  */
-declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined, Mode extends SchemaIoSide = "output">(props: SchemaComponentProps<T, Ref, Mode>): JSX.Element;
+declare function SchemaComponent<T = unknown, SchemaRef extends string | undefined = undefined, Mode extends SchemaIoSide = "output">(props: SchemaComponentProps<T, SchemaRef, Mode>): JSX.Element;
 //#endregion
 export { type InferFields, type InferredInputValue, type InferredOutputValue, type InferredValue, SchemaComponent, SchemaComponentProps, SchemaProvider, joinPath, renderField, sanitisePrefix };

package/dist/solid/SchemaComponent.mjs

@@ -232,7 +232,7 @@ function SchemaComponent(props) {
 		const onDiagnostic = rest.onDiagnostic;
 		const strict = rest.strict;
 		const io = rest.io;
-		const refInput = rest.ref;
+		const refInput = rest.schemaRef;
 		const onError = rest.onError;
 		const idPrefix = rest.idPrefix;
 		const mergedMeta = { ...componentMeta };

package/dist/solid/SchemaField.d.mts

@@ -16,10 +16,10 @@ type InferSchemaType<T> = T extends z.ZodType ? z.infer<T> : T extends object ?
  *
  * @group Components
  */
-interface SchemaFieldProps<T = unknown, Ref extends string | undefined = undefined, P extends string = PathOfType<InferSchemaType<T>> | (string extends PathOfType<InferSchemaType<T>> ? string : never)> {
+interface SchemaFieldProps<T = unknown, SchemaRef extends string | undefined = undefined, P extends string = PathOfType<InferSchemaType<T>> | (string extends PathOfType<InferSchemaType<T>> ? string : never)> {
   path: P;
   schema: RejectUnrepresentableZod<T>;
-  ref?: Ref;
+  schemaRef?: SchemaRef;
   value?: unknown;
   onChange?: (value: unknown) => void;
   meta?: SchemaMeta;
@@ -35,6 +35,6 @@ interface SchemaFieldProps<T = unknown, Ref extends string | undefined = undefin
  *
  * @group Components
  */
-declare function SchemaField<T = unknown, Ref extends string | undefined = undefined, P extends string = PathOfType<InferSchemaType<T>> | (string extends PathOfType<InferSchemaType<T>> ? string : never)>(props: SchemaFieldProps<T, Ref, P>): JSX.Element;
+declare function SchemaField<T = unknown, SchemaRef extends string | undefined = undefined, P extends string = PathOfType<InferSchemaType<T>> | (string extends PathOfType<InferSchemaType<T>> ? string : never)>(props: SchemaFieldProps<T, SchemaRef, P>): JSX.Element;
 //#endregion
 export { SchemaField, SchemaFieldProps };

package/dist/solid/SchemaField.mjs

@@ -40,7 +40,7 @@ function SchemaField(props) {
 	let rootMeta;
 	let rootDocument;
 	try {
-		const normalised = normaliseSchema(props.schema, props.ref);
+		const normalised = normaliseSchema(props.schema, props.schemaRef);
 		jsonSchema = normalised.jsonSchema;
 		zodSchema = normalised.zodSchema;
 		rootMeta = normalised.rootMeta;

package/dist/solid/SchemaView.d.mts

@@ -17,12 +17,12 @@ import { JSX } from "solid-js";
  *
  * @group Components
  */
-interface SchemaViewProps<T = unknown, Ref extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> {
+interface SchemaViewProps<T = unknown, SchemaRef extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> {
   schema: RejectUnrepresentableZod<T>;
-  ref?: Ref;
+  schemaRef?: SchemaRef;
   io?: Mode;
-  value?: InferredValue<T, Ref, undefined, Mode>;
-  fields?: InferFields<T, Ref>;
+  value?: InferredValue<T, SchemaRef, undefined, Mode>;
+  fields?: InferFields<T, SchemaRef>;
   meta?: SchemaMeta;
   description?: string;
   /** Theme resolver. Falls back to the headless resolver if omitted. */
@@ -49,6 +49,6 @@ interface SchemaViewProps<T = unknown, Ref extends string | undefined = undefine
  * }
  * ```
  */
-declare function SchemaView<T = unknown, Ref extends string | undefined = undefined, Mode extends SchemaIoSide = "output">(props: SchemaViewProps<T, Ref, Mode>): JSX.Element;
+declare function SchemaView<T = unknown, SchemaRef extends string | undefined = undefined, Mode extends SchemaIoSide = "output">(props: SchemaViewProps<T, SchemaRef, Mode>): JSX.Element;
 //#endregion
 export { SchemaView, SchemaViewProps };

package/dist/solid/SchemaView.mjs

@@ -66,7 +66,7 @@ function SchemaView(props) {
 			...diagnostics !== void 0 ? { diagnostics } : {},
 			...props.io !== void 0 ? { io: props.io } : {}
 		} : void 0;
-		const normalised = normaliseSchema(props.schema, props.ref, normaliseOptions);
+		const normalised = normaliseSchema(props.schema, props.schemaRef, normaliseOptions);
 		jsonSchema = normalised.jsonSchema;
 		rootMeta = normalised.rootMeta;
 		rootDocument = normalised.rootDocument;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "schema-components",
-    "version": "2.1.0",
+    "version": "3.0.0",
     "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/svelte/SchemaComponent.svelte

@@ -78,7 +78,7 @@
         /** Zod 4, JSON Schema, or OpenAPI document. */
         schema: T;
         /** OpenAPI ref string, e.g. "#/components/schemas/User". */
-        ref?: Ref;
+        schemaRef?: Ref;
         /** Direction (`"output"` / `"input"`) for codec / transform schemas. */
         io?: SchemaIoSide;
         /** Current value to render. */
@@ -119,7 +119,7 @@
 
     const {
         schema,
-        ref,
+        schemaRef,
         io,
         value,
         onChange,
@@ -176,7 +176,7 @@
     }
 
     const normalisedResult = $derived<NormalisedShape | SchemaError>(
-        normaliseSafely(schema, ref, io, diagnostics)
+        normaliseSafely(schema, schemaRef, io, diagnostics)
     );
 
     /**

package/src/svelte/SchemaField.svelte

@@ -40,7 +40,7 @@
         /** The schema to extract the field from. */
         schema: T;
         /** OpenAPI ref string. */
-        ref?: Ref;
+        schemaRef?: Ref;
         /** Direction (`"output"` / `"input"`) for codec / transform schemas. */
         io?: SchemaIoSide;
         /** Current value of the root schema. */
@@ -59,7 +59,7 @@
     const {
         path,
         schema,
-        ref,
+        schemaRef,
         io,
         value,
         onChange,
@@ -80,7 +80,7 @@
     }
 
     const normalisedResult = $derived<NormalisedShape>(
-        normaliseOrThrow(schema, ref, io)
+        normaliseOrThrow(schema, schemaRef, io)
     );
 
     const walkOptions = $derived<WalkOptions>({

package/src/svelte/SchemaView.svelte

@@ -51,7 +51,7 @@
 
     interface Props {
         schema: T;
-        ref?: Ref;
+        schemaRef?: Ref;
         io?: SchemaIoSide;
         value?: InferredValue<T, Ref, undefined, "output">;
         fields?: InferFields<T, Ref>;
@@ -68,7 +68,7 @@
 
     const {
         schema,
-        ref,
+        schemaRef,
         io,
         value,
         fields,
@@ -113,7 +113,7 @@
     }
 
     const normalisedResult = $derived<NormalisedShape>(
-        normaliseOrThrow(schema, ref, io, diagnostics)
+        normaliseOrThrow(schema, schemaRef, io, diagnostics)
     );
 
     const fieldsRecord = $derived(toRecordOrUndefined(fields));

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`. */
+        schemaRef?: 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;
+    }>(),
+    {
+        schemaRef: 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.schemaRef, 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>