schema-components 2.1.1 → 3.0.1

package/README.md

@@ -165,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
@@ -178,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 |
@@ -257,7 +257,7 @@ const jsonSchema = {
   }}
 />
 
-// OpenAPI as const + ref — full autocomplete
+// OpenAPI as const + schemaRef — full autocomplete
 const spec = {
   openapi: "3.1.0",
   components: {
@@ -276,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/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);

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.1",
+    "version": "3.0.1",
     "description": "React components that render UI from Zod schemas, JSON Schema, and OpenAPI documents",
     "type": "module",
     "exports": {

package/src/svelte/SchemaComponent.svelte

@@ -41,7 +41,7 @@
     constraint Vue, Solid, and React impose on shared mutable
     state and is documented in the package README.
 -->
-<script lang="ts" generics="T = unknown, Ref extends string | undefined = undefined">
+<script lang="ts" generics="T = unknown, SchemaRef extends string | undefined = undefined">
     import { z } from "zod";
     import { walk } from "../core/walker.ts";
     import type { WalkOptions } from "../core/walkBuilders.ts";
@@ -78,13 +78,13 @@
         /** Zod 4, JSON Schema, or OpenAPI document. */
         schema: T;
         /** OpenAPI ref string, e.g. "#/components/schemas/User". */
-        ref?: Ref;
+        schemaRef?: SchemaRef;
         /** Direction (`"output"` / `"input"`) for codec / transform schemas. */
         io?: SchemaIoSide;
         /** Current value to render. */
-        value?: InferSchemaValue<T, Ref, "output">;
+        value?: InferSchemaValue<T, SchemaRef, "output">;
         /** Called when the value changes. */
-        onChange?: (value: InferSchemaValue<T, Ref, "output">) => void;
+        onChange?: (value: InferSchemaValue<T, SchemaRef, "output">) => void;
         /** Run `safeParse` / `safeEncode` on change. */
         validate?: boolean;
         /** Called with the ZodError on validation failure. */
@@ -96,7 +96,7 @@
         /** When true, any diagnostic becomes a thrown error. */
         strict?: boolean;
         /** Per-field meta overrides. */
-        fields?: InferFields<T, Ref>;
+        fields?: InferFields<T, SchemaRef>;
         /** Meta overrides applied to the root schema. */
         meta?: SchemaMeta;
         /** Convenience: sets readOnly on all fields. */
@@ -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)
     );
 
     /**
@@ -234,7 +234,7 @@
             // contravariant assignment cannot be proven by
             // TypeScript and is the same pattern used in
             // `react/SchemaComponent.tsx`.
-            onChange(nextValue as InferSchemaValue<T, Ref, "output">);
+            onChange(nextValue as InferSchemaValue<T, SchemaRef, "output">);
         }
     }
 

package/src/svelte/SchemaField.svelte

@@ -7,7 +7,7 @@
     fields inside bespoke layouts when `<SchemaComponent>` would
     render too much.
 -->
-<script lang="ts" generics="T = unknown, Ref extends string | undefined = undefined">
+<script lang="ts" generics="T = unknown, SchemaRef extends string | undefined = undefined">
     import { walk } from "../core/walker.ts";
     import type { WalkOptions } from "../core/walkBuilders.ts";
     import {
@@ -40,7 +40,7 @@
         /** The schema to extract the field from. */
         schema: T;
         /** OpenAPI ref string. */
-        ref?: Ref;
+        schemaRef?: SchemaRef;
         /** 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

@@ -20,7 +20,7 @@
       - No global widget lookup — Svelte SSR mustn't read
         module-level mutable state.
 -->
-<script lang="ts" generics="T = unknown, Ref extends string | undefined = undefined">
+<script lang="ts" generics="T = unknown, SchemaRef extends string | undefined = undefined">
     import { walk } from "../core/walker.ts";
     import type { WalkOptions } from "../core/walkBuilders.ts";
     import {
@@ -51,10 +51,10 @@
 
     interface Props {
         schema: T;
-        ref?: Ref;
+        schemaRef?: SchemaRef;
         io?: SchemaIoSide;
-        value?: InferredValue<T, Ref, undefined, "output">;
-        fields?: InferFields<T, Ref>;
+        value?: InferredValue<T, SchemaRef, undefined, "output">;
+        fields?: InferFields<T, SchemaRef>;
         meta?: SchemaMeta;
         description?: string;
         /** Theme resolver — Svelte SSR has no context fallthrough, pass explicitly. */
@@ -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

@@ -40,7 +40,7 @@ const props = withDefaults(
         /** Zod schema, JSON Schema object, or OpenAPI document. */
         schema: unknown;
         /** For OpenAPI: a ref string like `#/components/schemas/User`. */
-        refPath?: string;
+        schemaRef?: string;
         /** v-model binding for the current value. */
         modelValue?: unknown;
         /**
@@ -72,7 +72,7 @@ const props = withDefaults(
         onError?: (error: SchemaNormalisationError) => void;
     }>(),
     {
-        refPath: undefined,
+        schemaRef: undefined,
         modelValue: undefined,
         onChange: undefined,
         readOnly: false,
@@ -141,7 +141,7 @@ const normalised = computed<Normalised>(() => {
         // consistency with the React adapter, which receives raw
         // values directly.
         const rawSchema = toRaw(props.schema);
-        const result = normaliseSchema(rawSchema, props.refPath, opts);
+        const result = normaliseSchema(rawSchema, props.schemaRef, opts);
         return {
             jsonSchema: result.jsonSchema,
             rootMeta: result.rootMeta,

package/src/vue/SchemaField.vue

@@ -41,7 +41,7 @@ const props = withDefaults(
         /** The schema to extract the field from. */
         schema: unknown;
         /** For OpenAPI: a ref string. */
-        refPath?: string;
+        schemaRef?: string;
         /** Current value of the root object the field belongs to. */
         modelValue?: unknown;
         /** Explicit onChange callback. Wired alongside `update:modelValue`. */
@@ -52,7 +52,7 @@ const props = withDefaults(
         idPrefix?: string;
     }>(),
     {
-        refPath: undefined,
+        schemaRef: undefined,
         modelValue: undefined,
         onChange: undefined,
         meta: () => ({}),
@@ -80,7 +80,7 @@ const normalised = computed<Normalised>(() => {
         // Zod schemas carry non-configurable members that Vue's
         // default reactive Proxy cannot mirror.
         const rawSchema = toRaw(props.schema);
-        const result = normaliseSchema(rawSchema, props.refPath);
+        const result = normaliseSchema(rawSchema, props.schemaRef);
         return {
             jsonSchema: result.jsonSchema,
             rootMeta: result.rootMeta,

package/src/vue/SchemaView.vue

@@ -38,7 +38,7 @@ const props = withDefaults(
         /** Zod schema, JSON Schema object, or OpenAPI document. */
         schema: unknown;
         /** For OpenAPI: a ref string. */
-        refPath?: string;
+        schemaRef?: string;
         /** Current value to render. */
         value?: unknown;
         /** Meta overrides applied to the root schema. */
@@ -63,7 +63,7 @@ const props = withDefaults(
         strict?: boolean;
     }>(),
     {
-        refPath: undefined,
+        schemaRef: undefined,
         value: undefined,
         meta: () => ({}),
         description: undefined,
@@ -110,7 +110,7 @@ const normalised = computed<Normalised>(() => {
         // `_zod` data members that Vue's default Proxy cannot mirror).
         // See the matching comment in `SchemaComponent.vue`.
         const rawSchema = toRaw(props.schema);
-        const result = normaliseSchema(rawSchema, props.refPath, opts);
+        const result = normaliseSchema(rawSchema, props.schemaRef, opts);
         return {
             jsonSchema: result.jsonSchema,
             rootMeta: result.rootMeta,