schema-components 2.1.0 → 3.0.0

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:
@@ -130,8 +165,8 @@ import { SchemaComponent } from "schema-components/react/SchemaComponent";
 // JSON Schema object
 <SchemaComponent schema={{ type: "object", properties: { name: { type: "string" } } }} value={data} />
 
-// OpenAPI document + ref
-<SchemaComponent schema={openApiSpec} ref="#/components/schemas/User" value={data} />
+// OpenAPI document + schemaRef
+<SchemaComponent schema={openApiSpec} schemaRef="#/components/schemas/User" value={data} />
 ```
 
 ### Props
@@ -143,7 +178,7 @@ import { SchemaComponent } from "schema-components/react/SchemaComponent";
 | `onChange` | `(value: unknown) => void` | Callback when value changes |
 | `readOnly` | `boolean` | Force read-only presentation |
 | `writeOnly` | `boolean` | Force write-only (blank inputs) |
-| `ref` | `string` | JSON Pointer into OpenAPI document |
+| `schemaRef` | `string` | JSON Pointer into OpenAPI document |
 | `fields` | `InferFields<T>` | Type-safe per-field overrides |
 | `widgets` | `WidgetMap` | Instance-scoped widget overrides |
 | `validate` | `boolean` | Enable Zod validation on change |
@@ -222,7 +257,7 @@ const jsonSchema = {
   }}
 />
 
-// OpenAPI as const + ref — full autocomplete
+// OpenAPI as const + schemaRef — full autocomplete
 const spec = {
   openapi: "3.1.0",
   components: {
@@ -241,9 +276,9 @@ const spec = {
 
 <SchemaComponent
   schema={spec}
-  ref="#/components/schemas/User"
+  schemaRef="#/components/schemas/User"
   fields={{
-    id: { readOnly: true },              // ✓ inferred through ref
+    id: { readOnly: true },              // ✓ inferred through schemaRef
   }}
 />
 ```

package/dist/{SchemaComponent-B__6-5-E.d.mts → SchemaComponent-CRgCVDhz.d.mts}

@@ -66,7 +66,7 @@ declare function __clearGlobalWidgets(): void;
  *
  * @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.
    *
@@ -78,8 +78,16 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    * — the static rejection surfaces the same failure at compile time.
    */
   schema: RejectUnrepresentableZod<T>;
-  /** For OpenAPI: a ref string like "#/components/schemas/User" or "/users/post". */
-  ref?: Ref;
+  /**
+   * For OpenAPI / JSON Schema documents: a `$ref` string pointing at
+   * the sub-schema to render — e.g. `"#/components/schemas/User"` or
+   * `"/users/post"`.
+   *
+   * Named `schemaRef` (not `ref`) so the prop survives the React /
+   * `preact/compat` `createElement` boundary, which strips the
+   * reserved `ref` name from the vnode prop bag.
+   */
+  schemaRef?: SchemaRef;
   /**
    * Which side of every transform / pipe / codec to render.
    *
@@ -103,8 +111,8 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
   io?: Mode;
   /**
    * Current value to render. Typed against
-   * `InferSchemaValue<T, Ref, Mode>` so the prop tracks the schema's
-   * inferred shape for the chosen `io` direction.
+   * `InferSchemaValue<T, SchemaRef, Mode>` so the prop tracks the
+   * schema's inferred shape for the chosen `io` direction.
    *
    * Falls back to `unknown` when the schema's value type cannot be
    * statically inferred (runtime `Record<string, unknown>` JSON
@@ -119,7 +127,7 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    * <SchemaComponent schema={userSchema} value={user} readOnly />
    * ```
    */
-  value?: InferSchemaValue<T, Ref, Mode>;
+  value?: InferSchemaValue<T, SchemaRef, Mode>;
   /**
    * Called when the value changes (editable fields). The parameter
    * shares the same shape as {@link SchemaComponentProps.value} so
@@ -129,7 +137,7 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    * Falls back to `unknown` for schemas whose value type cannot be
    * statically inferred — see {@link SchemaComponentProps.value}.
    */
-  onChange?: (value: InferSchemaValue<T, Ref, Mode>) => void;
+  onChange?: (value: InferSchemaValue<T, SchemaRef, Mode>) => void;
   /** Run schema.safeParse() on change and surface errors via onValidationError. */
   validate?: boolean;
   /** Called with the ZodError when validation fails. */
@@ -141,7 +149,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. */
@@ -183,7 +191,7 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
  * <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>): ReactNode;
+declare function SchemaComponent<T = unknown, SchemaRef extends string | undefined = undefined, Mode extends SchemaIoSide = "output">(props: SchemaComponentProps<T, SchemaRef, Mode>): ReactNode;
 /**
  * Append a child path suffix to a parent path. When the suffix is omitted
  * (e.g. transparent wrappers like union options), the parent path is
@@ -229,7 +237,7 @@ 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)> {
   /**
    * Dot-separated path to the field (e.g. "address.city").
    * When the schema is a Zod schema or typed `as const`, only valid
@@ -241,8 +249,12 @@ interface SchemaFieldProps<T = unknown, Ref extends string | undefined = undefin
    * unrepresentable-Zod rejection as {@link SchemaComponentProps.schema}.
    */
   schema: RejectUnrepresentableZod<T>;
-  /** For OpenAPI: a ref string. */
-  ref?: Ref;
+  /**
+   * For OpenAPI / JSON Schema documents: a `$ref` string. Named
+   * `schemaRef` (not `ref`) to avoid the React / `preact/compat`
+   * reserved prop name. See {@link SchemaComponentProps.schemaRef}.
+   */
+  schemaRef?: SchemaRef;
   /** Current value of the field at the given path. */
   value?: unknown;
   /** Called with the updated root value when this field changes. */
@@ -263,15 +275,15 @@ 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)>({
+declare function SchemaField<T = unknown, SchemaRef extends string | undefined = undefined, P extends string = PathOfType<InferSchemaType<T>> | (string extends PathOfType<InferSchemaType<T>> ? string : never)>({
   path,
   schema: schemaInput,
-  ref: refInput,
+  schemaRef: schemaRefInput,
   value,
   onChange,
   meta: fieldMeta,
   validate,
   onValidationError
-}: SchemaFieldProps<T, Ref, P>): ReactNode;
+}: SchemaFieldProps<T, SchemaRef, P>): ReactNode;
 //#endregion
 export { SchemaProvider as a, registerWidget as c, SchemaFieldProps as i, renderField as l, SchemaComponentProps as n, __clearGlobalWidgets as o, SchemaField as r, joinPath as s, SchemaComponent as t, sanitisePrefix as u };

package/dist/{SchemaComponent-BxzzsHsK.mjs → SchemaComponent-Cga5oJfP.mjs}

@@ -95,7 +95,7 @@ var SchemaField = class extends SchemaComponent {
 		let rootMeta;
 		let rootDocument;
 		try {
-			const normalised = normaliseSchema(this.schema, this.ref);
+			const normalised = normaliseSchema(this.schema, this.schemaRef);
 			jsonSchema = normalised.jsonSchema;
 			rootMeta = normalised.rootMeta;
 			rootDocument = normalised.rootDocument;
@@ -504,7 +504,7 @@ var SchemaComponent = class extends LitElement {
 		widgets: { attribute: false },
 		fields: { attribute: false },
 		meta: { attribute: false },
-		ref: { attribute: false },
+		schemaRef: { attribute: false },
 		io: { attribute: false },
 		idPrefix: { attribute: false },
 		onDiagnostic: { attribute: false },
@@ -533,7 +533,7 @@ var SchemaComponent = class extends LitElement {
 				...diagnosticsOptions !== void 0 ? { diagnostics: diagnosticsOptions } : {},
 				...this.io !== void 0 ? { io: this.io } : {}
 			} : void 0;
-			const normalised = normaliseSchema(this.schema, this.ref, normaliseOptions);
+			const normalised = normaliseSchema(this.schema, this.schemaRef, normaliseOptions);
 			jsonSchema = normalised.jsonSchema;
 			rootMeta = normalised.rootMeta;
 			rootDocument = normalised.rootDocument;

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/dist/lit/SchemaComponent.d.mts

@@ -66,7 +66,7 @@ declare class SchemaComponent extends LitElement {
     meta: {
       attribute: boolean;
     };
-    ref: {
+    schemaRef: {
       attribute: boolean;
     };
     io: {
@@ -94,7 +94,7 @@ declare class SchemaComponent extends LitElement {
    * values are seeded in the constructor.
    */
   schema: unknown;
-  ref: string | undefined;
+  schemaRef: string | undefined;
   io: SchemaIoSide | undefined;
   value: unknown;
   resolver: LitComponentResolver | undefined;

package/dist/lit/SchemaComponent.mjs

@@ -1,2 +1,2 @@
-import { t as SchemaComponent } from "../SchemaComponent-BxzzsHsK.mjs";
+import { t as SchemaComponent } from "../SchemaComponent-Cga5oJfP.mjs";
 export { SchemaComponent };

package/dist/lit/SchemaField.d.mts

@@ -37,7 +37,7 @@ declare class SchemaField extends SchemaComponent {
     meta: {
       attribute: boolean;
     };
-    ref: {
+    schemaRef: {
       attribute: boolean;
     };
     io: {

package/dist/lit/SchemaField.mjs

@@ -1,2 +1,2 @@
-import { o as SchemaField } from "../SchemaComponent-BxzzsHsK.mjs";
+import { o as SchemaField } from "../SchemaComponent-Cga5oJfP.mjs";
 export { SchemaField };

package/dist/lit/SchemaView.mjs

@@ -1,2 +1,2 @@
-import { s as SchemaView } from "../SchemaComponent-BxzzsHsK.mjs";
+import { s as SchemaView } from "../SchemaComponent-Cga5oJfP.mjs";
 export { SchemaView };

package/dist/lit/defaultResolver.mjs

@@ -1,2 +1,2 @@
-import { n as TYPE_TO_CANONICAL_TAG, r as createDefaultLitResolver } from "../SchemaComponent-BxzzsHsK.mjs";
+import { n as TYPE_TO_CANONICAL_TAG, r as createDefaultLitResolver } from "../SchemaComponent-Cga5oJfP.mjs";
 export { TYPE_TO_CANONICAL_TAG, createDefaultLitResolver };

package/dist/lit/registry.mjs

@@ -1,2 +1,2 @@
-import { a as registerSchemaComponents, i as BUILT_IN_ELEMENTS } from "../SchemaComponent-BxzzsHsK.mjs";
+import { a as registerSchemaComponents, i as BUILT_IN_ELEMENTS } from "../SchemaComponent-Cga5oJfP.mjs";
 export { BUILT_IN_ELEMENTS, registerSchemaComponents };

package/dist/preact/SchemaComponent.d.mts

@@ -1,3 +1,3 @@
 import { a as InferredValue, i as InferredOutputValue, r as InferredInputValue, t as InferFields } from "../inferValue-eAnh50EM.mjs";
-import { a as SchemaProvider, c as registerWidget, i as SchemaFieldProps, n as SchemaComponentProps, r as SchemaField, t as SchemaComponent } from "../SchemaComponent-B__6-5-E.mjs";
+import { a as SchemaProvider, c as registerWidget, i as SchemaFieldProps, n as SchemaComponentProps, r as SchemaField, t as SchemaComponent } from "../SchemaComponent-CRgCVDhz.mjs";
 export { type InferFields, type InferredInputValue, type InferredOutputValue, type InferredValue, SchemaComponent, type SchemaComponentProps, SchemaField, type SchemaFieldProps, SchemaProvider, registerWidget };

package/dist/react/SchemaComponent.d.mts

@@ -1,3 +1,3 @@
 import { a as InferredValue, i as InferredOutputValue, r as InferredInputValue, t as InferFields } from "../inferValue-eAnh50EM.mjs";
-import { a as SchemaProvider, c as registerWidget, i as SchemaFieldProps, l as renderField, n as SchemaComponentProps, o as __clearGlobalWidgets, r as SchemaField, s as joinPath, t as SchemaComponent, u as sanitisePrefix } from "../SchemaComponent-B__6-5-E.mjs";
+import { a as SchemaProvider, c as registerWidget, i as SchemaFieldProps, l as renderField, n as SchemaComponentProps, o as __clearGlobalWidgets, r as SchemaField, s as joinPath, t as SchemaComponent, u as sanitisePrefix } from "../SchemaComponent-CRgCVDhz.mjs";
 export { InferFields, InferredInputValue, InferredOutputValue, InferredValue, SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, __clearGlobalWidgets, joinPath, registerWidget, renderField, sanitisePrefix };

package/dist/react/SchemaComponent.mjs

@@ -21,7 +21,7 @@ import { createContext, isValidElement, useCallback, useContext, useId, useMemo
 * The `fields` prop type is inferred from the `schema` prop:
 * - Zod schemas → `FieldOverrides<z.infer<T>>` (full autocomplete)
 * - JSON Schema `as const` → `FieldOverrides<FromJSONSchema<T>>` (full autocomplete)
-* - OpenAPI `as const` + `ref` → `FieldOverrides<ResolveOpenAPIRef<T, Ref>>`
+* - OpenAPI `as const` + `schemaRef` → `FieldOverrides<ResolveOpenAPIRef<T, SchemaRef>>`
 * - Runtime schemas → `Record<string, FieldOverride>` (no autocomplete)
 */
 const UserResolverContext = createContext(void 0);
@@ -103,7 +103,7 @@ function __clearGlobalWidgets() {
 * ```
 */
 function SchemaComponent(props) {
-	const { schema: schemaInput, ref: refInput, io, value, onChange, validate, onValidationError, onError, onDiagnostic, strict, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets, idPrefix } = props;
+	const { schema: schemaInput, schemaRef: schemaRefInput, io, value, onChange, validate, onValidationError, onError, onDiagnostic, strict, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets, idPrefix } = props;
 	const userResolver = useContext(UserResolverContext);
 	const contextWidgets = useContext(WidgetsContext);
 	const generatedId = useId();
@@ -129,7 +129,7 @@ function SchemaComponent(props) {
 	let rootMeta;
 	let rootDocument;
 	try {
-		const normalised = normaliseSchema(schemaInput, refInput, diagnostics !== void 0 || io !== void 0 ? {
+		const normalised = normaliseSchema(schemaInput, schemaRefInput, diagnostics !== void 0 || io !== void 0 ? {
 			...diagnostics !== void 0 ? { diagnostics } : {},
 			...io !== void 0 ? { io } : {}
 		} : void 0);
@@ -336,7 +336,7 @@ function renderField(tree, value, onChange, userResolver, renderChild, path, ins
 *
 * @group Components
 */
-function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange, meta: fieldMeta, validate, onValidationError }) {
+function SchemaField({ path, schema: schemaInput, schemaRef: schemaRefInput, value, onChange, meta: fieldMeta, validate, onValidationError }) {
 	const userResolver = useContext(UserResolverContext);
 	const contextWidgets = useContext(WidgetsContext);
 	const generatedId = useId();
@@ -345,7 +345,7 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 	let rootMeta;
 	let rootDocument;
 	try {
-		const normalised = normaliseSchema(schemaInput, refInput);
+		const normalised = normaliseSchema(schemaInput, schemaRefInput);
 		jsonSchema = normalised.jsonSchema;
 		zodSchema = normalised.zodSchema;
 		rootMeta = normalised.rootMeta;
@@ -389,7 +389,7 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 * Walks the fields override tree and matches errors by path prefix.
 *
 * The runtime shape of `fields` is always `Record<string, FieldOverride>`
-* after `InferFields<T, Ref>` is erased — the typed variants
+* after `InferFields<T, SchemaRef>` is erased — the typed variants
 * (`FieldOverrides<U>`) and the loose `Record<string, FieldOverride>`
 * fallback share the same structural shape, so the dispatch logic only
 * needs the loose record. The previous parameter union

package/dist/react/SchemaView.d.mts

@@ -16,7 +16,7 @@ import { ReactNode } from "react";
  *
  * @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"> {
   /**
    * Zod schema, JSON Schema object, or OpenAPI document.
    *
@@ -25,8 +25,13 @@ interface SchemaViewProps<T = unknown, Ref extends string | undefined = undefine
    * {@link RejectUnrepresentableZod}.
    */
   schema: RejectUnrepresentableZod<T>;
-  /** For OpenAPI: a ref string like "#/components/schemas/User". */
-  ref?: Ref;
+  /**
+   * For OpenAPI / JSON Schema documents: a `$ref` string like
+   * `"#/components/schemas/User"`. Named `schemaRef` (not `ref`) to
+   * avoid the React / `preact/compat` reserved prop name. See
+   * {@link SchemaComponentProps.schemaRef}.
+   */
+  schemaRef?: SchemaRef;
   /**
    * Which side of every transform / pipe / codec to render. Mirrors
    * `<SchemaComponent io>`. Defaults to `"output"` — the inferred
@@ -39,18 +44,18 @@ interface SchemaViewProps<T = unknown, Ref extends string | undefined = undefine
   io?: Mode;
   /**
    * Current value to render. Typed against
-   * `InferSchemaValue<T, Ref, Mode>` so the prop tracks the schema's
-   * inferred shape for the chosen `io` direction. Falls back to
-   * `unknown` for runtime schemas where the value type cannot be
+   * `InferSchemaValue<T, SchemaRef, Mode>` so the prop tracks the
+   * schema's inferred shape for the chosen `io` direction. Falls back
+   * to `unknown` for runtime schemas where the value type cannot be
    * statically inferred.
    */
-  value?: InferredValue<T, Ref, undefined, Mode>;
+  value?: InferredValue<T, SchemaRef, undefined, Mode>;
   /**
    * Per-field meta overrides — nested object mirroring schema shape.
    * Typed against {@link InferFields} so a typed `schema` prop drives
    * autocomplete on the override map, matching `<SchemaComponent>`.
    */
-  fields?: InferFields<T, Ref>;
+  fields?: InferFields<T, SchemaRef>;
   /** Meta overrides applied to the root schema. */
   meta?: SchemaMeta;
   /** Convenience: sets description on the root. */
@@ -96,9 +101,9 @@ interface SchemaViewProps<T = unknown, Ref extends string | undefined = undefine
  * }
  * ```
  */
-declare function SchemaView<T = unknown, Ref extends string | undefined = undefined, Mode extends SchemaIoSide = "output">({
+declare function SchemaView<T = unknown, SchemaRef extends string | undefined = undefined, Mode extends SchemaIoSide = "output">({
   schema: schemaInput,
-  ref: refInput,
+  schemaRef: schemaRefInput,
   io,
   value,
   fields,
@@ -109,6 +114,6 @@ declare function SchemaView<T = unknown, Ref extends string | undefined = undefi
   onDiagnostic,
   strict,
   idPrefix
-}: SchemaViewProps<T, Ref, Mode>): ReactNode;
+}: SchemaViewProps<T, SchemaRef, Mode>): ReactNode;
 //#endregion
 export { SchemaView, SchemaViewProps };

package/dist/react/SchemaView.mjs

@@ -58,7 +58,7 @@ import { isValidElement, useId } from "react";
 * }
 * ```
 */
-function SchemaView({ schema: schemaInput, ref: refInput, io, value, fields, meta: componentMeta, description, resolver, widgets, onDiagnostic, strict, idPrefix }) {
+function SchemaView({ schema: schemaInput, schemaRef: schemaRefInput, io, value, fields, meta: componentMeta, description, resolver, widgets, onDiagnostic, strict, idPrefix }) {
 	const generatedId = useId();
 	const rootPath = idPrefix ?? sanitisePrefix(generatedId);
 	const mergedMeta = {
@@ -74,7 +74,7 @@ function SchemaView({ schema: schemaInput, ref: refInput, io, value, fields, met
 	let rootMeta;
 	let rootDocument;
 	try {
-		const normalised = normaliseSchema(schemaInput, refInput, diagnostics !== void 0 || io !== void 0 ? {
+		const normalised = normaliseSchema(schemaInput, schemaRefInput, diagnostics !== void 0 || io !== void 0 ? {
 			...diagnostics !== void 0 ? { diagnostics } : {},
 			...io !== void 0 ? { io } : {}
 		} : void 0);