schema-components 0.0.0 → 1.1.0

package/dist/core/adapter.mjs

@@ -0,0 +1,140 @@
+import { getProperty, hasProperty, isObject } from "./guards.mjs";
+import { z } from "zod";
+//#region src/core/adapter.ts
+/**
+* Schema adapter — normalises all inputs to JSON Schema.
+*
+* - Zod 4 schemas → converted via z.toJSONSchema()
+* - Zod 3 schemas → error (not yet supported)
+* - JSON Schema objects → passed through
+* - OpenAPI documents → schemas extracted and passed through
+*
+* The adapter preserves the original Zod schema for validation.
+* All narrowing uses type guards — no type assertions.
+*/
+const schemaCache = /* @__PURE__ */ new WeakMap();
+function detectSchemaKind(input) {
+	if (hasProperty(input, "_zod")) return "zod4";
+	if (hasProperty(input, "_def") && !hasProperty(input, "_zod")) return "zod3";
+	if (hasProperty(input, "openapi")) return "openapi";
+	return "jsonSchema";
+}
+/**
+* Wraps z.toJSONSchema() for a runtime-validated Zod schema.
+*
+* The _zod guard in normaliseZod4 has confirmed this is a valid Zod schema,
+* but TypeScript cannot represent "has _zod.def" as the $ZodType parameter
+* that z.toJSONSchema expects. This is the library boundary equivalent of
+* object → Record<string, unknown> — the type mismatch is genuinely unavoidable.
+*/
+function callToJsonSchema(schema) {
+	return z.toJSONSchema(schema);
+}
+function normaliseSchema(input, ref) {
+	if (ref === void 0 && isObject(input)) {
+		const cached = schemaCache.get(input);
+		if (cached !== void 0) return cached;
+	}
+	const kind = detectSchemaKind(input);
+	let result;
+	switch (kind) {
+		case "zod4":
+			result = normaliseZod4(input);
+			break;
+		case "zod3":
+			result = normaliseZod3();
+			break;
+		case "openapi":
+			if (!isObject(input)) throw new Error("Invalid OpenAPI document");
+			result = normaliseOpenApi(input, ref);
+			break;
+		case "jsonSchema":
+			if (!isObject(input)) throw new Error("Invalid JSON Schema");
+			result = normaliseJsonSchema(input);
+			break;
+	}
+	if (ref === void 0 && isObject(input)) schemaCache.set(input, result);
+	return result;
+}
+function normaliseZod4(input) {
+	const zod = getProperty(input, "_zod");
+	if (!isObject(zod)) throw new Error("Invalid Zod 4 schema: missing _zod property");
+	if (!("def" in zod)) throw new Error("Invalid Zod 4 schema: missing _zod.def");
+	const jsonSchema = callToJsonSchema(input);
+	if (!isObject(jsonSchema)) throw new Error("z.toJSONSchema() did not produce an object");
+	return {
+		jsonSchema,
+		zodSchema: input,
+		rootMeta: extractRootMetaFromJson(jsonSchema),
+		rootDocument: jsonSchema
+	};
+}
+function normaliseJsonSchema(jsonSchema) {
+	return {
+		jsonSchema,
+		rootMeta: extractRootMetaFromJson(jsonSchema),
+		rootDocument: jsonSchema
+	};
+}
+function normaliseZod3() {
+	throw new Error("Zod 3 schemas are not yet supported. Convert to Zod 4 or provide JSON Schema directly.");
+}
+function normaliseOpenApi(doc, ref) {
+	const resolved = resolveOpenApiRef(doc, ref);
+	return {
+		jsonSchema: resolved,
+		rootMeta: extractRootMetaFromJson(resolved),
+		rootDocument: doc
+	};
+}
+function resolveOpenApiRef(doc, ref) {
+	if (ref === void 0) {
+		const schemas = getProperty(getProperty(doc, "components"), "schemas");
+		if (!isObject(schemas)) throw new Error("OpenAPI document has no components/schemas and no ref was provided.");
+		const firstKey = Object.keys(schemas)[0];
+		if (firstKey === void 0) throw new Error("OpenAPI document has empty components/schemas.");
+		const first = schemas[firstKey];
+		if (!isObject(first)) throw new Error("Schema is not an object.");
+		return first;
+	}
+	if (ref.startsWith("#/components/schemas/")) {
+		const name = ref.slice(21);
+		const schemas = getProperty(getProperty(doc, "components"), "schemas");
+		if (!isObject(schemas)) throw new Error(`OpenAPI ref not found: ${ref}`);
+		const resolved = schemas[name];
+		if (!isObject(resolved)) throw new Error(`OpenAPI ref not found: ${ref}`);
+		return resolved;
+	}
+	const pathMatch = /^\/(.+)\/(get|post|put|patch|delete)$/.exec(ref);
+	if (pathMatch?.[1] !== void 0 && pathMatch[2] !== void 0) {
+		const pathStr = pathMatch[1];
+		const method = pathMatch[2];
+		const paths = getProperty(doc, "paths");
+		if (!isObject(paths)) throw new Error("OpenAPI document has no paths.");
+		const pathObj = paths[`/${pathStr}`];
+		if (!isObject(pathObj)) throw new Error(`Path not found: /${pathStr}`);
+		const operation = pathObj[method];
+		if (!isObject(operation)) throw new Error(`Method ${method} not found on /${pathStr}`);
+		const requestBody = getProperty(operation, "requestBody");
+		if (!isObject(requestBody)) throw new Error(`No requestBody for ${ref}`);
+		const content = getProperty(requestBody, "content");
+		if (!isObject(content)) throw new Error(`No content for ${ref}`);
+		const json = getProperty(content, "application/json");
+		if (!isObject(json)) throw new Error(`No application/json for ${ref}`);
+		const schema = getProperty(json, "schema");
+		if (!isObject(schema)) throw new Error(`Could not resolve request body schema for ${ref}`);
+		return schema;
+	}
+	throw new Error(`Unsupported OpenAPI ref format: ${ref}`);
+}
+function extractRootMetaFromJson(jsonSchema) {
+	const meta = {};
+	if (jsonSchema.readOnly === true) meta.readOnly = true;
+	if (jsonSchema.writeOnly === true) meta.writeOnly = true;
+	if (typeof jsonSchema.description === "string") meta.description = jsonSchema.description;
+	if (typeof jsonSchema.title === "string") meta.title = jsonSchema.title;
+	if (typeof jsonSchema.deprecated === "boolean") meta.deprecated = jsonSchema.deprecated;
+	return Object.keys(meta).length > 0 ? meta : void 0;
+}
+//#endregion
+export { detectSchemaKind, normaliseSchema };

package/dist/core/errors.d.mts

@@ -0,0 +1,2 @@
+import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-DIKI2C78.mjs";
+export { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError };

package/dist/core/errors.mjs

@@ -0,0 +1,74 @@
+//#region src/core/errors.ts
+/**
+* Structured error types for schema-components.
+*
+* Every error produced by the library is one of these three types:
+*
+* - SchemaNormalisationError — the adapter failed to convert the input
+*   to JSON Schema (invalid Zod, bad OpenAPI ref, malformed schema)
+* - SchemaRenderError — a theme adapter's render function threw
+* - SchemaFieldError — a field path couldn't be resolved
+*
+* All extend `SchemaError` so consumers can catch the base class.
+*/
+/**
+* Base class for all schema-components errors.
+* Catch this to handle any library error uniformly.
+*/
+var SchemaError = class extends Error {
+	/** The schema input that caused the error. */
+	schema;
+	constructor(message, schema) {
+		super(message);
+		this.name = "SchemaError";
+		this.schema = schema;
+	}
+};
+/**
+* The adapter failed to convert the input schema to JSON Schema.
+*
+* Causes: invalid Zod schema, Zod 3 schema (unsupported), malformed
+* JSON Schema, missing OpenAPI ref, unsupported ref format.
+*/
+var SchemaNormalisationError = class extends SchemaError {
+	kind;
+	constructor(message, schema, kind) {
+		super(message, schema);
+		this.name = "SchemaNormalisationError";
+		this.kind = kind;
+	}
+};
+/**
+* A theme adapter's render function threw during rendering.
+*
+* The `cause` is the original error from the render function.
+*/
+var SchemaRenderError = class extends SchemaError {
+	/** The schema type being rendered when the error occurred. */
+	schemaType;
+	/** The original error from the render function. */
+	cause;
+	constructor(message, schema, schemaType, cause) {
+		super(message, schema);
+		this.name = "SchemaRenderError";
+		this.schemaType = schemaType;
+		this.cause = cause;
+	}
+};
+/**
+* A field path couldn't be resolved against the walked schema tree.
+*
+* This is produced by `<SchemaField>` when the `path` prop doesn't
+* match any field in the schema.
+*/
+var SchemaFieldError = class extends SchemaError {
+	/** The unresolvable dot-separated path. */
+	path;
+	constructor(message, schema, path) {
+		super(message, schema);
+		this.name = "SchemaFieldError";
+		this.path = path;
+	}
+};
+//#endregion
+export { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError };

package/dist/core/guards.d.mts

@@ -0,0 +1,44 @@
+//#region src/core/guards.d.ts
+/**
+ * Shared type guards and safe property access.
+ *
+ * Every module in schema-components needs `isObject` and `getProperty`.
+ * Defining them once eliminates the six re-implementations that existed
+ * across core, react, openapi, html, and themes.
+ *
+ * The `object → Record<string, unknown>` conversion (`toRecord`) is
+ * the one place where a cast is genuinely unavoidable — TypeScript's
+ * `object` type has no index signature. See AGENTS.md: "object →
+ * Record<string, unknown>".
+ */
+/**
+ * Narrows `unknown` to a non-null, non-array object.
+ * This is the most fundamental narrowing in the library — every module
+ * that reads JSON Schema or OpenAPI objects uses this.
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Safe property access on unknown values. Returns `undefined` if the
+ * value is not an object or the key doesn't exist.
+ */
+declare function getProperty(value: unknown, key: string): unknown;
+/**
+ * Check if a value is an object with a specific own-property.
+ */
+declare function hasProperty(value: unknown, key: string): boolean;
+/**
+ * Convert a known `object` to `Record<string, unknown>` by iterating
+ * `Object.entries`. This avoids the cast that TypeScript's `object`
+ * type (no index signature) otherwise forces.
+ *
+ * Only use this when you already know `value` is an `object` — it does
+ * not perform a type guard.
+ */
+declare function toRecord(value: object): Record<string, unknown>;
+/**
+ * Convert `unknown` to `Record<string, unknown> | undefined`.
+ * Returns `undefined` for non-objects, null, and arrays.
+ */
+declare function toRecordOrUndefined(value: unknown): Record<string, unknown> | undefined;
+//#endregion
+export { getProperty, hasProperty, isObject, toRecord, toRecordOrUndefined };

package/dist/core/guards.mjs

@@ -0,0 +1,58 @@
+//#region src/core/guards.ts
+/**
+* Shared type guards and safe property access.
+*
+* Every module in schema-components needs `isObject` and `getProperty`.
+* Defining them once eliminates the six re-implementations that existed
+* across core, react, openapi, html, and themes.
+*
+* The `object → Record<string, unknown>` conversion (`toRecord`) is
+* the one place where a cast is genuinely unavoidable — TypeScript's
+* `object` type has no index signature. See AGENTS.md: "object →
+* Record<string, unknown>".
+*/
+/**
+* Narrows `unknown` to a non-null, non-array object.
+* This is the most fundamental narrowing in the library — every module
+* that reads JSON Schema or OpenAPI objects uses this.
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Safe property access on unknown values. Returns `undefined` if the
+* value is not an object or the key doesn't exist.
+*/
+function getProperty(value, key) {
+	if (!isObject(value)) return void 0;
+	return value[key];
+}
+/**
+* Check if a value is an object with a specific own-property.
+*/
+function hasProperty(value, key) {
+	return isObject(value) && key in value;
+}
+/**
+* Convert a known `object` to `Record<string, unknown>` by iterating
+* `Object.entries`. This avoids the cast that TypeScript's `object`
+* type (no index signature) otherwise forces.
+*
+* Only use this when you already know `value` is an `object` — it does
+* not perform a type guard.
+*/
+function toRecord(value) {
+	const record = {};
+	for (const [key, val] of Object.entries(value)) record[key] = val;
+	return record;
+}
+/**
+* Convert `unknown` to `Record<string, unknown> | undefined`.
+* Returns `undefined` for non-objects, null, and arrays.
+*/
+function toRecordOrUndefined(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	return toRecord(value);
+}
+//#endregion
+export { getProperty, hasProperty, isObject, toRecord, toRecordOrUndefined };

package/dist/core/renderer.d.mts

@@ -0,0 +1,2 @@
+import { A as mergeResolvers, C as HtmlResolver, D as getHtmlRenderFn, E as RenderProps, O as getRenderFunction, S as HtmlRenderProps, T as RenderFunction, b as ComponentResolver, j as typeToKey, k as mergeHtmlResolvers, w as RESOLVER_KEYS, x as HtmlRenderFunction, y as BaseFieldProps } from "../types-BU0ETFHk.mjs";
+export { BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/core/renderer.mjs

@@ -0,0 +1,71 @@
+//#region src/core/renderer.ts
+const RESOLVER_KEYS = [
+	"string",
+	"number",
+	"boolean",
+	"enum",
+	"object",
+	"array",
+	"record",
+	"union",
+	"literal",
+	"file",
+	"unknown"
+];
+/**
+* Map a schema type to the resolver key that handles it.
+* `discriminatedUnion` → `union`. Unknown types → `unknown`.
+*/
+function typeToKey(type) {
+	switch (type) {
+		case "string":
+		case "number":
+		case "boolean":
+		case "enum":
+		case "object":
+		case "array":
+		case "record":
+		case "union":
+		case "literal":
+		case "file":
+		case "unknown": return type;
+		case "discriminatedUnion": return "union";
+		default: return "unknown";
+	}
+}
+/**
+* Look up the render function for a schema type in a ComponentResolver.
+*/
+function getRenderFunction(type, resolver) {
+	return resolver[typeToKey(type)];
+}
+/**
+* Look up the render function for a schema type in an HtmlResolver.
+*/
+function getHtmlRenderFn(type, resolver) {
+	return resolver[typeToKey(type)];
+}
+/**
+* Merge two ComponentResolvers — user values take priority, fallback fills gaps.
+*/
+function mergeResolvers(user, fallback) {
+	const merged = {};
+	for (const key of RESOLVER_KEYS) {
+		const fn = user[key] ?? fallback[key];
+		if (fn !== void 0) merged[key] = fn;
+	}
+	return merged;
+}
+/**
+* Merge two HtmlResolvers — user values take priority, fallback fills gaps.
+*/
+function mergeHtmlResolvers(user, fallback) {
+	const merged = {};
+	for (const key of RESOLVER_KEYS) {
+		const fn = user[key] ?? fallback[key];
+		if (fn !== void 0) merged[key] = fn;
+	}
+	return merged;
+}
+//#endregion
+export { RESOLVER_KEYS, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/core/types.d.mts

@@ -0,0 +1,3 @@
+import { C as HtmlResolver, E as RenderProps, S as HtmlRenderProps, T as RenderFunction, _ as WalkedField, a as FromJSONSchema, b as ComponentResolver, c as InferResponseFields, d as OpenAPIResponseType, f as PathOfType, g as TypeAtPath, h as SchemaType, i as FieldOverrides, l as JsonObject, m as SchemaMeta, n as FieldConstraints, o as InferParameterOverrides, p as ResolveOpenAPIRef, r as FieldOverride, s as InferRequestBodyFields, t as Editability, u as OpenAPIRequestBodyType, v as resolveEditability, x as HtmlRenderFunction, y as BaseFieldProps } from "../types-BU0ETFHk.mjs";
+import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-DIKI2C78.mjs";
+export { BaseFieldProps, ComponentResolver, Editability, FieldConstraints, FieldOverride, FieldOverrides, FromJSONSchema, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, InferParameterOverrides, InferRequestBodyFields, InferResponseFields, JsonObject, OpenAPIRequestBodyType, OpenAPIResponseType, PathOfType, RenderFunction, RenderProps, ResolveOpenAPIRef, SchemaError, SchemaFieldError, SchemaMeta, SchemaNormalisationError, SchemaRenderError, SchemaType, TypeAtPath, WalkedField, resolveEditability };

package/dist/core/types.mjs

@@ -0,0 +1,40 @@
+import { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError } from "./errors.mjs";
+//#region src/core/types.ts
+/**
+* Resolved editability state for a single field.
+*
+* Priority (highest wins):
+* 1. Property-level readOnly → presentation
+* 2. Property-level writeOnly → input
+* 3. Component-level readOnly → presentation
+* 4. Component-level writeOnly → input
+* 5. Schema root readOnly → presentation
+* 6. Schema root writeOnly → input
+* 7. Neither → editable
+*/
+function resolveEditability(propertyMeta, componentMeta, rootMeta) {
+	if (propertyMeta !== void 0 && "readOnly" in propertyMeta) {
+		if (propertyMeta.readOnly) return "presentation";
+	}
+	if (propertyMeta !== void 0 && "writeOnly" in propertyMeta) {
+		if (propertyMeta.writeOnly) return "input";
+	}
+	if (propertyMeta !== void 0 && ("readOnly" in propertyMeta || "writeOnly" in propertyMeta)) return "editable";
+	if (componentMeta !== void 0 && "readOnly" in componentMeta) {
+		if (componentMeta.readOnly) return "presentation";
+	}
+	if (componentMeta !== void 0 && "writeOnly" in componentMeta) {
+		if (componentMeta.writeOnly) return "input";
+	}
+	if (componentMeta !== void 0 && ("readOnly" in componentMeta || "writeOnly" in componentMeta)) return "editable";
+	if (rootMeta !== void 0 && "readOnly" in rootMeta) {
+		if (rootMeta.readOnly) return "presentation";
+	}
+	if (rootMeta !== void 0 && "writeOnly" in rootMeta) {
+		if (rootMeta.writeOnly) return "input";
+	}
+	if (rootMeta !== void 0 && ("readOnly" in rootMeta || "writeOnly" in rootMeta)) return "editable";
+	return "editable";
+}
+//#endregion
+export { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError, resolveEditability };

package/dist/core/walker.d.mts

@@ -0,0 +1,14 @@
+import { _ as WalkedField, m as SchemaMeta } from "../types-BU0ETFHk.mjs";
+
+//#region src/core/walker.d.ts
+interface WalkOptions {
+  componentMeta?: SchemaMeta | undefined;
+  rootMeta?: SchemaMeta | undefined;
+  /** Nested field overrides — same shape as the schema. */
+  fieldOverrides?: Record<string, unknown> | undefined;
+  /** The root document for $ref resolution. */
+  rootDocument?: Record<string, unknown> | undefined;
+}
+declare function walk(schema: unknown, options?: WalkOptions): WalkedField;
+//#endregion
+export { WalkOptions, walk };