schema-components 0.0.0 → 1.0.0

package/dist/react/SchemaComponent.mjs

@@ -0,0 +1,283 @@
+import { isObject, toRecord } from "../core/guards.mjs";
+import { normaliseSchema } from "../core/adapter.mjs";
+import { SchemaFieldError, SchemaNormalisationError, SchemaRenderError } from "../core/errors.mjs";
+import { getRenderFunction, mergeResolvers } from "../core/renderer.mjs";
+import { walk } from "../core/walker.mjs";
+import { headlessResolver } from "./headless.mjs";
+import { z } from "zod";
+import { createContext, isValidElement, useCallback, useContext, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/SchemaComponent.tsx
+/**
+* <SchemaComponent> — renders UI from Zod, JSON Schema, or OpenAPI schemas.
+*
+* Auto-detects the input format, normalises to JSON Schema via the adapter,
+* walks the JSON Schema tree, and delegates rendering to the
+* ComponentResolver (theme adapter). Falls back to headless HTML.
+*
+* 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>>
+* - Runtime schemas → Record<string, FieldOverride> (no autocomplete)
+*/
+const UserResolverContext = createContext(void 0);
+function SchemaProvider({ resolver, children }) {
+	return /* @__PURE__ */ jsx(UserResolverContext.Provider, {
+		value: resolver,
+		children
+	});
+}
+const widgetRegistry = /* @__PURE__ */ new Map();
+function registerWidget(name, render) {
+	widgetRegistry.set(name, render);
+}
+function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, fields, meta: componentMeta, readOnly, writeOnly, description }) {
+	const userResolver = useContext(UserResolverContext);
+	const mergedMeta = useMemo(() => {
+		const merged = { ...componentMeta };
+		if (readOnly === true) merged.readOnly = true;
+		if (writeOnly === true) merged.writeOnly = true;
+		if (description !== void 0) merged.description = description;
+		return merged;
+	}, [
+		componentMeta,
+		readOnly,
+		writeOnly,
+		description
+	]);
+	let jsonSchema;
+	let zodSchema;
+	let rootMeta;
+	let rootDocument;
+	try {
+		const normalised = normaliseSchema(schemaInput, refInput);
+		jsonSchema = normalised.jsonSchema;
+		zodSchema = normalised.zodSchema;
+		rootMeta = normalised.rootMeta;
+		rootDocument = normalised.rootDocument;
+	} catch (err) {
+		const error = new SchemaNormalisationError(err instanceof Error ? err.message : "Failed to normalise schema", schemaInput, detectNormalisationKind(err));
+		if (onError !== void 0) {
+			onError(error);
+			return null;
+		}
+		throw error;
+	}
+	const handleChange = useCallback((nextValue) => {
+		if (validate) runValidation(zodSchema, jsonSchema, nextValue, onValidationError);
+		onChange?.(nextValue);
+	}, [
+		validate,
+		zodSchema,
+		jsonSchema,
+		onChange,
+		onValidationError
+	]);
+	const tree = walk(jsonSchema, {
+		componentMeta: mergedMeta,
+		rootMeta,
+		fieldOverrides: fields,
+		rootDocument
+	});
+	const renderChild = (childTree, childValue, childOnChange) => {
+		return renderField(childTree, childValue, childOnChange, userResolver, renderChild);
+	};
+	return renderField(tree, value, handleChange, userResolver, renderChild);
+}
+function runValidation(zodSchema, jsonSchema, value, onError) {
+	if (zodSchema !== void 0 && isObject(zodSchema)) {
+		const safeParseFn = zodSchema.safeParse;
+		if (isCallable(safeParseFn)) {
+			const result = safeParseFn(value);
+			if (isObject(result) && "success" in result && result.success !== true) {
+				onError?.(result.error);
+				return;
+			}
+			return;
+		}
+	}
+	const parsed = z.fromJSONSchema(jsonSchema);
+	if (isObject(parsed)) {
+		const safeParseFn = parsed.safeParse;
+		if (isCallable(safeParseFn)) {
+			const result = safeParseFn(value);
+			if (isObject(result) && "success" in result && result.success !== true) onError?.(result.error);
+		}
+	}
+}
+function renderField(tree, value, onChange, userResolver, renderChild) {
+	const componentHint = tree.meta.component;
+	if (typeof componentHint === "string") {
+		const widget = widgetRegistry.get(componentHint);
+		if (widget !== void 0) {
+			const result = widget(buildRenderProps(tree, value, onChange, renderChild));
+			if (result !== void 0 && result !== null) {
+				if (isValidElement(result)) return result;
+				if (typeof result === "string" || typeof result === "number") return result;
+				return null;
+			}
+		}
+	}
+	const resolver = userResolver !== void 0 ? mergeResolvers(userResolver, headlessResolver) : headlessResolver;
+	const renderFn = getRenderFunction(tree.type, resolver);
+	if (renderFn !== void 0) {
+		let result;
+		try {
+			result = renderFn(buildRenderProps(tree, value, onChange, renderChild));
+		} catch (err) {
+			throw new SchemaRenderError(err instanceof Error ? err.message : `Render function threw for type "${tree.type}"`, tree, tree.type, err);
+		}
+		if (result !== void 0 && result !== null) {
+			if (isValidElement(result)) return result;
+			if (typeof result === "string" || typeof result === "number") return result;
+		}
+	}
+	if (value === void 0 || value === null) return /* @__PURE__ */ jsx("span", { children: "—" });
+	return /* @__PURE__ */ jsx("span", { children: typeof value === "string" ? value : JSON.stringify(value) });
+}
+function buildRenderProps(tree, value, onChange, renderChild) {
+	const props = {
+		value,
+		onChange,
+		readOnly: tree.editability === "presentation",
+		writeOnly: tree.editability === "input",
+		meta: tree.meta,
+		constraints: tree.constraints,
+		path: "",
+		tree,
+		renderChild
+	};
+	if (tree.enumValues !== void 0) props.enumValues = tree.enumValues;
+	if (tree.element !== void 0) props.element = tree.element;
+	if (tree.fields !== void 0) props.fields = tree.fields;
+	if (tree.options !== void 0) props.options = tree.options;
+	if (tree.discriminator !== void 0) props.discriminator = tree.discriminator;
+	if (tree.keyType !== void 0) props.keyType = tree.keyType;
+	if (tree.valueType !== void 0) props.valueType = tree.valueType;
+	return props;
+}
+function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange, meta: fieldMeta, validate, onValidationError }) {
+	const userResolver = useContext(UserResolverContext);
+	let jsonSchema;
+	let zodSchema;
+	let rootMeta;
+	let rootDocument;
+	try {
+		const normalised = normaliseSchema(schemaInput, refInput);
+		jsonSchema = normalised.jsonSchema;
+		zodSchema = normalised.zodSchema;
+		rootMeta = normalised.rootMeta;
+		rootDocument = normalised.rootDocument;
+	} catch (err) {
+		throw new SchemaNormalisationError(err instanceof Error ? err.message : "Failed to normalise schema", schemaInput, detectNormalisationKind(err));
+	}
+	const fieldTree = resolvePath(walk(jsonSchema, {
+		componentMeta: fieldMeta,
+		rootMeta,
+		rootDocument
+	}), path);
+	if (fieldTree === void 0) throw new SchemaFieldError(`Field not found: ${path}`, schemaInput, path);
+	const fieldValue = resolveValue(value, path);
+	const handleChange = useCallback((nextFieldValue) => {
+		if (validate) {
+			const newRootValue = setNestedValue(value, path, nextFieldValue);
+			runValidation(zodSchema, jsonSchema, newRootValue, onValidationError);
+		}
+		const newRootValue = setNestedValue(value, path, nextFieldValue);
+		onChange?.(newRootValue);
+	}, [
+		validate,
+		zodSchema,
+		jsonSchema,
+		value,
+		path,
+		onChange,
+		onValidationError
+	]);
+	const renderChild = (childTree, childValue, childOnChange) => {
+		return renderField(childTree, childValue, childOnChange, userResolver, renderChild);
+	};
+	return renderField(fieldTree, fieldValue, handleChange, userResolver, renderChild);
+}
+function resolvePath(tree, path) {
+	if (path.length === 0) return tree;
+	const parts = path.split(".");
+	let current = tree;
+	for (const part of parts) {
+		if (current === void 0) return void 0;
+		const bracketMatch = /^(.+)\[(\d+)\]$/.exec(part);
+		if (bracketMatch?.[1] !== void 0 && bracketMatch[2] !== void 0) {
+			const arrayField = bracketMatch[1];
+			if (current.fields !== void 0) current = current.fields[arrayField];
+			if (current?.element !== void 0) current = current.element;
+			continue;
+		}
+		if (current.fields !== void 0) current = current.fields[part];
+		else if (current.element !== void 0) current = current.element;
+		else return;
+	}
+	return current;
+}
+function resolveValue(root, path) {
+	if (path.length === 0) return root;
+	const parts = path.split(".");
+	let current = root;
+	for (const part of parts) {
+		if (typeof current !== "object" || current === null) return void 0;
+		const bracketMatch = /^(.+)\[(\d+)\]$/.exec(part);
+		if (bracketMatch?.[1] !== void 0 && bracketMatch[2] !== void 0) {
+			const key = bracketMatch[1];
+			const index = Number(bracketMatch[2]);
+			const arr = toRecord(current)[key];
+			if (Array.isArray(arr)) current = arr[index];
+			else return;
+		} else current = toRecord(current)[part];
+	}
+	return current;
+}
+function setNestedValue(root, path, leafValue) {
+	if (path.length === 0) return leafValue;
+	const parts = path.split(".");
+	const result = isObject(root) ? { ...toRecord(root) } : {};
+	let current = result;
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (part === void 0) break;
+		const isLast = i === parts.length - 1;
+		const bracketMatch = /^(.+)\[(\d+)\]$/.exec(part);
+		if (bracketMatch?.[1] !== void 0 && bracketMatch[2] !== void 0) {
+			const key = bracketMatch[1];
+			const index = Number(bracketMatch[2]);
+			const existing = current[key];
+			const arr = Array.isArray(existing) ? existing.slice() : [];
+			if (isLast) arr[index] = leafValue;
+			current[key] = arr;
+			const nextCurrent = arr[index];
+			if (nextCurrent !== void 0 && isObject(nextCurrent)) current = toRecord(nextCurrent);
+		} else if (isLast) current[part] = leafValue;
+		else {
+			const existing = current[part];
+			const next = isObject(existing) ? { ...toRecord(existing) } : {};
+			current[part] = next;
+			current = next;
+		}
+	}
+	return result;
+}
+function isCallable(value) {
+	return typeof value === "function";
+}
+function detectNormalisationKind(err) {
+	if (err instanceof Error) {
+		const msg = err.message;
+		if (msg.includes("Zod 3")) return "zod3-unsupported";
+		if (msg.includes("Invalid Zod 4")) return "invalid-zod";
+		if (msg.includes("OpenAPI ref not found")) return "openapi-missing-ref";
+		if (msg.includes("OpenAPI")) return "openapi-invalid";
+		if (msg.includes("JSON Schema")) return "invalid-json-schema";
+	}
+	return "unknown";
+}
+//#endregion
+export { SchemaComponent, SchemaField, SchemaProvider, registerWidget, renderField };

package/dist/react/SchemaErrorBoundary.d.mts

@@ -0,0 +1,26 @@
+import { Component, ReactNode } from "react";
+
+//#region src/react/SchemaErrorBoundary.d.ts
+interface SchemaErrorBoundaryProps {
+  /** Called with the caught error. Returns fallback ReactNode to render. */
+  fallback: (error: Error, reset: () => void) => ReactNode;
+  children: ReactNode;
+}
+interface ErrorBoundaryState {
+  error: Error | undefined;
+}
+/**
+ * React error boundary that catches schema rendering errors.
+ *
+ * Provides a `reset` callback that clears the error state, allowing
+ * the children to re-render (e.g. after fixing a bad schema prop).
+ */
+declare class SchemaErrorBoundary extends Component<SchemaErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState;
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+  componentDidCatch(error: Error): void;
+  reset: () => void;
+  render(): ReactNode;
+}
+//#endregion
+export { SchemaErrorBoundary, SchemaErrorBoundaryProps };

package/dist/react/SchemaErrorBoundary.mjs

@@ -0,0 +1,47 @@
+import { SchemaError } from "../core/errors.mjs";
+import { Component } from "react";
+//#region src/react/SchemaErrorBoundary.tsx
+/**
+* React error boundary for schema-components.
+*
+* Catches render errors from `<SchemaComponent>`, theme adapters, and
+* any child components. Without this boundary, a throwing render function
+* crashes the entire React tree.
+*
+* Usage:
+*   import { SchemaErrorBoundary } from "schema-components/react/SchemaErrorBoundary";
+*
+*   <SchemaErrorBoundary fallback={(error) => <p>{error.message}</p>}>
+*     <SchemaComponent schema={userSchema} value={user} />
+*   </SchemaErrorBoundary>
+*
+* The boundary catches `SchemaRenderError` from theme adapters and any
+* other errors thrown during rendering. It does NOT catch:
+* - Event handler errors (onChange, etc.)
+* - Async errors
+* - Errors in server-side rendering
+*/
+/**
+* React error boundary that catches schema rendering errors.
+*
+* Provides a `reset` callback that clears the error state, allowing
+* the children to re-render (e.g. after fixing a bad schema prop).
+*/
+var SchemaErrorBoundary = class extends Component {
+	state = { error: void 0 };
+	static getDerivedStateFromError(error) {
+		return { error };
+	}
+	componentDidCatch(error) {
+		if (!(error instanceof SchemaError)) console.error("[schema-components] Unhandled render error:", error);
+	}
+	reset = () => {
+		this.setState({ error: void 0 });
+	};
+	render() {
+		if (this.state.error !== void 0) return this.props.fallback(this.state.error, this.reset);
+		return this.props.children;
+	}
+};
+//#endregion
+export { SchemaErrorBoundary };

package/dist/react/headless.d.mts

@@ -0,0 +1,13 @@
+import { b as ComponentResolver } from "../types-BU0ETFHk.mjs";
+import { ReactNode } from "react";
+
+//#region src/react/headless.d.ts
+declare function toReactNode(value: unknown): ReactNode;
+/**
+ * The headless resolver uses props.renderChild for recursive rendering.
+ * No factory function needed — the renderChild is always available
+ * on RenderProps.
+ */
+declare const headlessResolver: ComponentResolver;
+//#endregion
+export { headlessResolver, toReactNode };

package/dist/react/headless.mjs

@@ -0,0 +1,163 @@
+import { isObject } from "../core/guards.mjs";
+import { isValidElement } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/headless.tsx
+/**
+* React headless renderer — the default ComponentResolver implementation.
+*
+* Produces plain HTML elements for every schema type. Theme adapters
+* replace this by implementing ComponentResolver with their own components.
+*
+* This module imports React and lives in the react layer, not core,
+* because it produces ReactNode values.
+*/
+function toReactNode(value) {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	if (isValidElement(value)) return value;
+	return null;
+}
+function renderString(props) {
+	if (props.readOnly) {
+		const strValue = typeof props.value === "string" ? props.value : void 0;
+		if (strValue === void 0 || strValue.length === 0) return /* @__PURE__ */ jsx("span", { children: "—" });
+		const format = props.constraints.format;
+		if (format === "email") return /* @__PURE__ */ jsx("a", {
+			href: `mailto:${strValue}`,
+			children: strValue
+		});
+		if (format === "uri" || format === "url") return /* @__PURE__ */ jsx("a", {
+			href: strValue,
+			children: strValue
+		});
+		return /* @__PURE__ */ jsx("span", { children: strValue });
+	}
+	const strValue = typeof props.value === "string" ? props.value : "";
+	if (props.enumValues !== void 0 && props.enumValues.length > 0) return /* @__PURE__ */ jsxs("select", {
+		value: strValue,
+		onChange: (e) => {
+			props.onChange(e.target.value);
+		},
+		children: [/* @__PURE__ */ jsx("option", {
+			value: "",
+			children: "Select…"
+		}), props.enumValues.map((v) => /* @__PURE__ */ jsx("option", {
+			value: v,
+			children: v
+		}, v))]
+	});
+	return /* @__PURE__ */ jsx("input", {
+		type: props.constraints.format === "email" ? "email" : props.constraints.format === "uri" ? "url" : "text",
+		value: props.writeOnly ? "" : strValue,
+		onChange: (e) => {
+			props.onChange(e.target.value);
+		},
+		placeholder: typeof props.meta.description === "string" ? props.meta.description : void 0,
+		minLength: props.constraints.minLength,
+		maxLength: props.constraints.maxLength
+	});
+}
+function renderNumber(props) {
+	if (props.readOnly) {
+		if (typeof props.value !== "number") return /* @__PURE__ */ jsx("span", { children: "—" });
+		return /* @__PURE__ */ jsx("span", { children: props.value.toLocaleString() });
+	}
+	const numValue = typeof props.value === "number" ? props.value : "";
+	return /* @__PURE__ */ jsx("input", {
+		type: "number",
+		value: props.writeOnly ? "" : numValue,
+		onChange: (e) => {
+			props.onChange(Number(e.target.value));
+		},
+		min: props.constraints.minimum,
+		max: props.constraints.maximum
+	});
+}
+function renderBoolean(props) {
+	if (props.readOnly) {
+		if (typeof props.value !== "boolean") return /* @__PURE__ */ jsx("span", { children: "—" });
+		return /* @__PURE__ */ jsx("span", { children: props.value ? "Yes" : "No" });
+	}
+	return /* @__PURE__ */ jsx("input", {
+		type: "checkbox",
+		checked: props.value === true,
+		onChange: (e) => {
+			props.onChange(e.target.checked);
+		}
+	});
+}
+function renderEnum(props) {
+	const enumValue = typeof props.value === "string" ? props.value : "";
+	if (props.readOnly) return /* @__PURE__ */ jsx("span", { children: enumValue || "—" });
+	return /* @__PURE__ */ jsxs("select", {
+		value: props.writeOnly ? "" : enumValue,
+		onChange: (e) => {
+			props.onChange(e.target.value);
+		},
+		children: [/* @__PURE__ */ jsx("option", {
+			value: "",
+			children: "Select…"
+		}), props.enumValues?.map((v) => /* @__PURE__ */ jsx("option", {
+			value: v,
+			children: v
+		}, v))]
+	});
+}
+function renderObject(props) {
+	const obj = isObject(props.value) ? props.value : {};
+	const fields = props.fields;
+	if (fields === void 0) return null;
+	return /* @__PURE__ */ jsxs("fieldset", { children: [typeof props.meta.description === "string" && /* @__PURE__ */ jsx("legend", { children: props.meta.description }), Object.entries(fields).map(([key, field]) => {
+		const childValue = obj[key];
+		const childOnChange = (v) => {
+			const updated = {};
+			for (const [k, val] of Object.entries(obj)) updated[k] = val;
+			updated[key] = v;
+			props.onChange(updated);
+		};
+		return /* @__PURE__ */ jsxs("div", { children: [typeof field.meta.description === "string" && /* @__PURE__ */ jsx("label", { children: field.meta.description }), toReactNode(props.renderChild(field, childValue, childOnChange))] }, key);
+	})] });
+}
+function renderArray(props) {
+	const arr = Array.isArray(props.value) ? props.value : [];
+	const element = props.element;
+	if (element === void 0) return null;
+	return /* @__PURE__ */ jsx("div", { children: arr.map((item, i) => {
+		const childOnChange = (v) => {
+			const next = arr.slice();
+			next[i] = v;
+			props.onChange(next);
+		};
+		return /* @__PURE__ */ jsx("div", { children: toReactNode(props.renderChild(element, item, childOnChange)) }, String(i));
+	}) });
+}
+function renderUnknown(props) {
+	if (props.readOnly) {
+		if (props.value === void 0 || props.value === null) return /* @__PURE__ */ jsx("span", { children: "—" });
+		return /* @__PURE__ */ jsx("span", { children: typeof props.value === "string" ? props.value : JSON.stringify(props.value) });
+	}
+	const strValue = typeof props.value === "string" ? props.value : "";
+	return /* @__PURE__ */ jsx("input", {
+		type: "text",
+		value: props.writeOnly ? "" : strValue,
+		onChange: (e) => {
+			props.onChange(e.target.value);
+		}
+	});
+}
+/**
+* The headless resolver uses props.renderChild for recursive rendering.
+* No factory function needed — the renderChild is always available
+* on RenderProps.
+*/
+const headlessResolver = {
+	string: renderString,
+	number: renderNumber,
+	boolean: renderBoolean,
+	enum: renderEnum,
+	object: renderObject,
+	array: renderArray,
+	unknown: renderUnknown
+};
+//#endregion
+export { headlessResolver, toReactNode };

package/dist/themes/shadcn.d.mts

@@ -0,0 +1,6 @@
+import { b as ComponentResolver } from "../types-BU0ETFHk.mjs";
+
+//#region src/themes/shadcn.d.ts
+declare const shadcnResolver: ComponentResolver;
+//#endregion
+export { shadcnResolver };