schema-components 0.0.0 → 1.1.0

package/dist/openapi/components.mjs

@@ -0,0 +1,223 @@
+import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import { normaliseSchema } from "../core/adapter.mjs";
+import { SchemaNormalisationError } from "../core/errors.mjs";
+import { walk } from "../core/walker.mjs";
+import { getParameters, getRequestBody, getResponses, listOperations, parseOpenApiDocument } from "./parser.mjs";
+import { renderField } from "../react/SchemaComponent.mjs";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/openapi/components.tsx
+const docCache = /* @__PURE__ */ new WeakMap();
+function getParsed(doc) {
+	const cached = docCache.get(doc);
+	if (cached !== void 0) return cached;
+	const parsed = parseOpenApiDocument(doc);
+	docCache.set(doc, parsed);
+	return parsed;
+}
+function noop() {}
+function toDoc(value) {
+	return isObject(value) ? value : {};
+}
+function renderSchema(schema, rootDocument, options) {
+	let jsonSchema;
+	let rootMeta;
+	try {
+		const normalised = normaliseSchema(schema);
+		jsonSchema = normalised.jsonSchema;
+		rootMeta = normalised.rootMeta;
+	} catch (err) {
+		throw new SchemaNormalisationError(err instanceof Error ? err.message : "Failed to normalise schema", schema, "unknown");
+	}
+	const componentMeta = {};
+	if (options.readOnly === true) componentMeta.readOnly = true;
+	if (options.meta !== void 0) for (const [k, v] of Object.entries(options.meta)) componentMeta[k] = v;
+	const walkOpts = {
+		componentMeta,
+		rootMeta,
+		fieldOverrides: toRecordOrUndefined(options.fields),
+		rootDocument
+	};
+	const tree = walk(jsonSchema, walkOpts);
+	const renderChild = (childTree, childValue, childOnChange) => renderField(childTree, childValue, childOnChange, void 0, renderChild);
+	return renderField(tree, options.value, options.onChange ?? noop, void 0, renderChild);
+}
+function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields }) {
+	const parsed = getParsed(toDoc(doc));
+	const rootDoc = toDoc(doc);
+	const operation = listOperations(parsed).find((op) => op.path === path && op.method === method);
+	if (operation === void 0) throw new SchemaNormalisationError(`Operation not found: ${method.toUpperCase()} ${path}`, doc, "openapi-invalid");
+	const params = getParameters(parsed, path, method);
+	const requestBody = getRequestBody(parsed, path, method);
+	const responses = getResponses(parsed, path, method);
+	return /* @__PURE__ */ jsxs("section", {
+		"data-operation": `${method.toUpperCase()} ${path}`,
+		children: [
+			/* @__PURE__ */ jsx(OperationHeader, { operation }),
+			params.length > 0 && /* @__PURE__ */ jsxs("section", {
+				"data-parameters": true,
+				children: [/* @__PURE__ */ jsx("h4", { children: "Parameters" }), /* @__PURE__ */ jsx(ParameterList, {
+					parameters: params,
+					rootDoc,
+					meta
+				})]
+			}),
+			requestBody?.schema !== void 0 && /* @__PURE__ */ jsxs("section", {
+				"data-request-body": true,
+				children: [
+					/* @__PURE__ */ jsxs("h4", { children: ["Request Body", requestBody.required && /* @__PURE__ */ jsx("span", {
+						"data-required": true,
+						children: "*"
+					})] }),
+					requestBody.description && /* @__PURE__ */ jsx("p", { children: requestBody.description }),
+					requestBody.contentTypes.length > 0 && /* @__PURE__ */ jsx("span", {
+						"data-content-type": true,
+						children: requestBody.contentTypes[0]
+					}),
+					renderSchema(requestBody.schema, rootDoc, {
+						value: requestBodyValue,
+						onChange: onRequestBodyChange,
+						fields: requestBodyFields,
+						meta
+					})
+				]
+			}),
+			responses.length > 0 && /* @__PURE__ */ jsxs("section", {
+				"data-responses": true,
+				children: [/* @__PURE__ */ jsx("h4", { children: "Responses" }), responses.map((response) => /* @__PURE__ */ jsx(ResponseCard, {
+					response,
+					rootDoc,
+					value: responseValue,
+					meta
+				}, response.statusCode))]
+			})
+		]
+	});
+}
+function ApiParameters({ schema: doc, path, method, meta, overrides }) {
+	const parsed = getParsed(toDoc(doc));
+	const rootDoc = toDoc(doc);
+	const params = getParameters(parsed, path, method);
+	if (params.length === 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		"data-parameters": true,
+		children: [/* @__PURE__ */ jsx("h4", { children: "Parameters" }), /* @__PURE__ */ jsx(ParameterList, {
+			parameters: params,
+			rootDoc,
+			overrides,
+			meta
+		})]
+	});
+}
+function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields }) {
+	const parsed = getParsed(toDoc(doc));
+	const rootDoc = toDoc(doc);
+	const requestBody = getRequestBody(parsed, path, method);
+	if (requestBody?.schema === void 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		"data-request-body": true,
+		children: [
+			/* @__PURE__ */ jsxs("h4", { children: ["Request Body", requestBody.required && /* @__PURE__ */ jsx("span", {
+				"data-required": true,
+				children: "*"
+			})] }),
+			requestBody.description && /* @__PURE__ */ jsx("p", { children: requestBody.description }),
+			requestBody.contentTypes.length > 0 && /* @__PURE__ */ jsx("span", {
+				"data-content-type": true,
+				children: requestBody.contentTypes[0]
+			}),
+			renderSchema(requestBody.schema, rootDoc, {
+				value,
+				onChange,
+				fields,
+				meta
+			})
+		]
+	});
+}
+function ApiResponse({ schema: doc, path, method, status, value, meta, fields }) {
+	const parsed = getParsed(toDoc(doc));
+	const rootDoc = toDoc(doc);
+	const response = getResponses(parsed, path, method).find((r) => r.statusCode === status);
+	if (response === void 0) throw new SchemaNormalisationError(`Response not found: ${status}`, doc, "openapi-invalid");
+	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
+		"data-status": status,
+		children: [
+			/* @__PURE__ */ jsx("h4", { children: status }),
+			response.description && /* @__PURE__ */ jsx("p", { children: response.description }),
+			/* @__PURE__ */ jsx("p", { children: /* @__PURE__ */ jsx("em", { children: "No schema" }) })
+		]
+	});
+	return /* @__PURE__ */ jsx(ResponseCard, {
+		response,
+		rootDoc,
+		value,
+		fields,
+		meta
+	});
+}
+function OperationHeader({ operation }) {
+	return /* @__PURE__ */ jsxs("header", { children: [
+		/* @__PURE__ */ jsxs("h3", { children: [
+			operation.method.toUpperCase(),
+			" ",
+			operation.path
+		] }),
+		operation.summary && /* @__PURE__ */ jsx("p", { children: operation.summary }),
+		operation.deprecated && /* @__PURE__ */ jsx("span", {
+			"data-deprecated": true,
+			children: "Deprecated"
+		})
+	] });
+}
+function ParameterList({ parameters, rootDoc, overrides, meta }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: parameters.map((param) => /* @__PURE__ */ jsxs("div", {
+		"data-parameter": param.name,
+		children: [
+			/* @__PURE__ */ jsxs("label", { children: [param.name, param.required && /* @__PURE__ */ jsx("span", {
+				"data-required": true,
+				children: "*"
+			})] }),
+			param.description && /* @__PURE__ */ jsx("span", {
+				"data-description": true,
+				children: param.description
+			}),
+			renderSchema(param.schema ?? { type: "string" }, rootDoc, { meta: buildParamMeta(param, overrides, meta) })
+		]
+	}, param.name)) });
+}
+function ResponseCard({ response, rootDoc, value, fields, meta }) {
+	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
+		"data-status": response.statusCode,
+		children: [
+			/* @__PURE__ */ jsx("h5", { children: response.statusCode }),
+			response.description && /* @__PURE__ */ jsx("p", { children: response.description }),
+			/* @__PURE__ */ jsx("p", { children: /* @__PURE__ */ jsx("em", { children: "No schema" }) })
+		]
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		"data-status": response.statusCode,
+		children: [
+			/* @__PURE__ */ jsx("h5", { children: response.statusCode }),
+			response.description && /* @__PURE__ */ jsx("p", { children: response.description }),
+			renderSchema(response.schema, rootDoc, {
+				value,
+				fields,
+				meta: {
+					readOnly: true,
+					...meta
+				}
+			})
+		]
+	});
+}
+function buildParamMeta(param, overrides, meta) {
+	const result = {};
+	if (param.description !== void 0) result.description = param.description;
+	if (param.deprecated) result.deprecated = true;
+	const override = toRecordOrUndefined(toRecordOrUndefined(overrides)?.[param.name]);
+	if (override !== void 0) for (const [k, v] of Object.entries(override)) result[k] = v;
+	if (meta !== void 0) for (const [k, v] of Object.entries(meta)) result[k] = v;
+	return Object.keys(result).length > 0 ? result : void 0;
+}
+//#endregion
+export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse };

package/dist/openapi/parser.d.mts

@@ -0,0 +1,45 @@
+import { l as JsonObject } from "../types-BU0ETFHk.mjs";
+
+//#region src/openapi/parser.d.ts
+interface OpenApiDocument {
+  doc: JsonObject;
+  schemas: Map<string, JsonObject>;
+}
+interface OperationInfo {
+  path: string;
+  method: string;
+  operationId: string | undefined;
+  summary: string | undefined;
+  description: string | undefined;
+  deprecated: boolean;
+  operation: JsonObject;
+}
+type ParameterLocation = "query" | "path" | "header" | "cookie";
+interface ParameterInfo {
+  name: string;
+  location: ParameterLocation;
+  required: boolean;
+  deprecated: boolean;
+  description: string | undefined;
+  schema: JsonObject | undefined;
+}
+interface ResponseInfo {
+  statusCode: string;
+  description: string | undefined;
+  contentTypes: string[];
+  schema: JsonObject | undefined;
+}
+interface RequestBodyInfo {
+  required: boolean;
+  description: string | undefined;
+  contentTypes: string[];
+  schema: JsonObject | undefined;
+}
+declare function parseOpenApiDocument(doc: JsonObject): OpenApiDocument;
+declare function getSchema(parsed: OpenApiDocument, ref: string): JsonObject | undefined;
+declare function listOperations(parsed: OpenApiDocument): OperationInfo[];
+declare function getParameters(parsed: OpenApiDocument, path: string, method: string): ParameterInfo[];
+declare function getRequestBody(parsed: OpenApiDocument, path: string, method: string): RequestBodyInfo | undefined;
+declare function getResponses(parsed: OpenApiDocument, path: string, method: string): ResponseInfo[];
+//#endregion
+export { OpenApiDocument, OperationInfo, ParameterInfo, ParameterLocation, RequestBodyInfo, ResponseInfo, getParameters, getRequestBody, getResponses, getSchema, listOperations, parseOpenApiDocument };

package/dist/openapi/parser.mjs

@@ -0,0 +1,159 @@
+import { getProperty, isObject } from "../core/guards.mjs";
+//#region src/openapi/parser.ts
+function getString(value, key) {
+	const result = isObject(value) ? value[key] : void 0;
+	return typeof result === "string" ? result : void 0;
+}
+function toParameterLocation(value) {
+	if (value === "query" || value === "path" || value === "header" || value === "cookie") return value;
+	return "query";
+}
+function parseOpenApiDocument(doc) {
+	const schemas = /* @__PURE__ */ new Map();
+	const componentSchemas = getProperty(getProperty(doc, "components"), "schemas");
+	if (isObject(componentSchemas)) {
+		for (const [name, schema] of Object.entries(componentSchemas)) if (isObject(schema)) schemas.set(`#/components/schemas/${name}`, schema);
+	}
+	return {
+		doc,
+		schemas
+	};
+}
+function getSchema(parsed, ref) {
+	const cached = parsed.schemas.get(ref);
+	if (cached !== void 0) return cached;
+	const resolved = resolveRefInDoc(parsed.doc, ref);
+	if (resolved !== void 0) {
+		parsed.schemas.set(ref, resolved);
+		return resolved;
+	}
+}
+const METHODS = [
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete"
+];
+function listOperations(parsed) {
+	const operations = [];
+	const paths = getProperty(parsed.doc, "paths");
+	if (!isObject(paths)) return operations;
+	for (const [path, pathItem] of Object.entries(paths)) {
+		if (!isObject(pathItem)) continue;
+		for (const method of METHODS) {
+			const operation = getProperty(pathItem, method);
+			if (!isObject(operation)) continue;
+			operations.push({
+				path,
+				method,
+				operationId: getString(operation, "operationId"),
+				summary: getString(operation, "summary"),
+				description: getString(operation, "description"),
+				deprecated: getProperty(operation, "deprecated") === true,
+				operation
+			});
+		}
+	}
+	return operations;
+}
+function getParameters(parsed, path, method) {
+	const pathItem = getProperty(getProperty(parsed.doc, "paths"), path);
+	if (!isObject(pathItem)) return [];
+	const operation = getProperty(pathItem, method);
+	if (!isObject(operation)) return [];
+	const pathParams = extractParameterList(getProperty(pathItem, "parameters"));
+	const opParams = extractParameterList(getProperty(operation, "parameters"));
+	const map = /* @__PURE__ */ new Map();
+	for (const param of pathParams) map.set(`${param.name}:${param.location}`, param);
+	for (const param of opParams) map.set(`${param.name}:${param.location}`, param);
+	return [...map.values()];
+}
+function extractParameterList(parameters) {
+	if (!Array.isArray(parameters)) return [];
+	const result = [];
+	for (const param of parameters) {
+		if (!isObject(param)) continue;
+		const name = getProperty(param, "name");
+		const location = getProperty(param, "in");
+		if (typeof name !== "string" || typeof location !== "string") continue;
+		const resolved = resolveParam(param);
+		const schema = getProperty(resolved, "schema");
+		result.push({
+			name,
+			location: toParameterLocation(location),
+			required: getProperty(resolved, "required") === true,
+			deprecated: getProperty(resolved, "deprecated") === true,
+			description: getString(resolved, "description"),
+			schema: isObject(schema) ? schema : void 0
+		});
+	}
+	return result;
+}
+function resolveParam(param) {
+	const ref = getProperty(param, "$ref");
+	if (typeof ref === "string" && ref.startsWith("#/")) {
+		const resolved = resolveRefInDoc(param, ref);
+		if (resolved !== void 0) return resolved;
+	}
+	return param;
+}
+function getRequestBody(parsed, path, method) {
+	const requestBody = getProperty(getProperty(getProperty(getProperty(parsed.doc, "paths"), path), method), "requestBody");
+	if (!isObject(requestBody)) return void 0;
+	const content = getProperty(requestBody, "content");
+	if (!isObject(content)) return {
+		required: getProperty(requestBody, "required") === true,
+		description: getString(requestBody, "description"),
+		contentTypes: [],
+		schema: void 0
+	};
+	const contentTypes = Object.keys(content);
+	const schema = extractSchemaFromContent(content);
+	return {
+		required: getProperty(requestBody, "required") === true,
+		description: getString(requestBody, "description"),
+		contentTypes,
+		schema
+	};
+}
+function getResponses(parsed, path, method) {
+	const responses = getProperty(getProperty(getProperty(getProperty(parsed.doc, "paths"), path), method), "responses");
+	if (!isObject(responses)) return [];
+	const result = [];
+	for (const [statusCode, response] of Object.entries(responses)) {
+		if (!isObject(response)) continue;
+		const content = getProperty(response, "content");
+		const contentTypes = isObject(content) ? Object.keys(content) : [];
+		const schema = isObject(content) ? extractSchemaFromContent(content) : void 0;
+		result.push({
+			statusCode,
+			description: getString(response, "description"),
+			contentTypes,
+			schema
+		});
+	}
+	return result;
+}
+function extractSchemaFromContent(content) {
+	const jsonSchema = getProperty(getProperty(content, "application/json"), "schema");
+	if (isObject(jsonSchema)) return jsonSchema;
+	for (const mediaType of Object.values(content)) {
+		if (!isObject(mediaType)) continue;
+		const schema = getProperty(mediaType, "schema");
+		if (isObject(schema)) return schema;
+	}
+}
+function resolveRefInDoc(doc, ref) {
+	if (!ref.startsWith("#/")) return void 0;
+	const parts = ref.slice(2).split("/");
+	let current = doc;
+	for (const part of parts) {
+		if (!isObject(current)) return void 0;
+		const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
+		current = current[decoded];
+	}
+	return isObject(current) ? current : void 0;
+}
+//#endregion
+export { getParameters, getRequestBody, getResponses, getSchema, listOperations, parseOpenApiDocument };

package/dist/react/SchemaComponent.d.mts

@@ -0,0 +1,96 @@
+import { E as RenderProps, _ as WalkedField, a as FromJSONSchema, b as ComponentResolver, f as PathOfType, i as FieldOverrides, m as SchemaMeta, p as ResolveOpenAPIRef, r as FieldOverride } from "../types-BU0ETFHk.mjs";
+import { t as SchemaError } from "../errors-DIKI2C78.mjs";
+import { z } from "zod";
+import { ReactNode } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/react/SchemaComponent.d.ts
+declare function SchemaProvider({
+  resolver,
+  children
+}: {
+  resolver: ComponentResolver;
+  children: ReactNode;
+}): _$react_jsx_runtime0.JSX.Element;
+declare function registerWidget(name: string, render: (props: RenderProps) => unknown): void;
+type InferFields<T, Ref extends string | undefined> = T extends z.ZodType ? FieldOverrides<z.infer<T>> : T extends {
+  openapi: unknown;
+} ? Ref extends string ? FieldOverrides<ResolveOpenAPIRef<T & Record<string, unknown>, Ref>> : Record<string, FieldOverride> : T extends object ? unknown extends FromJSONSchema<T> ? Record<string, FieldOverride> : FieldOverrides<FromJSONSchema<T>> : Record<string, FieldOverride>;
+interface SchemaComponentProps<T = unknown, Ref extends string | undefined = undefined> {
+  /** Zod schema, JSON Schema object, or OpenAPI document. */
+  schema: T;
+  /** For OpenAPI: a ref string like "#/components/schemas/User" or "/users/post". */
+  ref?: Ref;
+  /** Current value to render. */
+  value?: unknown;
+  /** Called when the value changes (editable fields). */
+  onChange?: (value: unknown) => void;
+  /** Run schema.safeParse() on change and surface errors via onValidationError. */
+  validate?: boolean;
+  /** Called with the ZodError when validation fails. */
+  onValidationError?: (error: unknown) => void;
+  /** Called when schema normalisation or rendering fails. */
+  onError?: (error: SchemaError) => void;
+  /** Per-field meta overrides — nested object mirroring schema shape. */
+  fields?: InferFields<T, Ref>;
+  /** Meta overrides applied to the root schema. */
+  meta?: SchemaMeta;
+  /** Convenience: sets readOnly on all fields. */
+  readOnly?: boolean;
+  /** Convenience: sets writeOnly on all fields. */
+  writeOnly?: boolean;
+  /** Convenience: sets description on the root. */
+  description?: string;
+}
+declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined>({
+  schema: schemaInput,
+  ref: refInput,
+  value,
+  onChange,
+  validate,
+  onValidationError,
+  onError,
+  fields,
+  meta: componentMeta,
+  readOnly,
+  writeOnly,
+  description
+}: SchemaComponentProps<T, Ref>): ReactNode;
+declare function renderField(tree: WalkedField, value: unknown, onChange: (v: unknown) => void, userResolver: ComponentResolver | undefined, renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void) => ReactNode): ReactNode;
+/**
+ * Infer the schema's output type for SchemaField path inference.
+ */
+type InferSchemaType<T> = T extends z.ZodType ? z.infer<T> : T extends object ? unknown extends FromJSONSchema<T> ? unknown : FromJSONSchema<T> : unknown;
+interface SchemaFieldProps<T = unknown, Ref 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
+   * paths are accepted. Falls back to `string` for runtime schemas.
+   */
+  path: P;
+  /** The schema to extract the field from. */
+  schema: T;
+  /** For OpenAPI: a ref string. */
+  ref?: Ref;
+  /** Current value of the field at the given path. */
+  value?: unknown;
+  /** Called with the updated root value when this field changes. */
+  onChange?: (value: unknown) => void;
+  /** Override meta for this specific field. */
+  meta?: SchemaMeta;
+  /** Run validation on change. */
+  validate?: boolean;
+  onValidationError?: (error: unknown) => void;
+}
+declare function SchemaField<T = unknown, Ref extends string | undefined = undefined, P extends string = string>({
+  path,
+  schema: schemaInput,
+  ref: refInput,
+  value,
+  onChange,
+  meta: fieldMeta,
+  validate,
+  onValidationError
+}: SchemaFieldProps<T, Ref, P>): ReactNode;
+//#endregion
+export { SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, registerWidget, renderField };