schema-components 1.28.2 → 1.29.0

package/dist/openapi/parser.d.mts

@@ -1,11 +1,22 @@
-import { m as JsonObject } from "../types-BTB73MB8.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
+import { m as JsonObject } from "../types-C2Ay1FEh.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-ByEzkjrA.mjs";
 
 //#region src/openapi/parser.d.ts
+/**
+ * Parsed OpenAPI document: the raw root JSON plus a cache of resolved
+ * `#/components/schemas/*` (or Swagger 2.0 `#/definitions/*`) entries.
+ * Produced by {@link parseOpenApiDocument} and consumed by every other
+ * parser/resolver helper in this module.
+ */
 interface OpenApiDocument {
   doc: JsonObject;
   schemas: Map<string, JsonObject>;
 }
+/**
+ * Lightweight summary of an OpenAPI operation: its location, identity,
+ * description fields, deprecation flag, and the underlying Operation
+ * Object. Returned by {@link listOperations} / {@link listAllOperations}.
+ */
 interface OperationInfo {
   path: string;
   method: string;
@@ -15,7 +26,12 @@ interface OperationInfo {
   deprecated: boolean;
   operation: JsonObject;
 }
+/** Canonical four-value OpenAPI parameter `in` location. */
 type ParameterLocation = "query" | "path" | "header" | "cookie";
+/**
+ * Parsed view of an OpenAPI Parameter Object — name, location,
+ * required flag, deprecation flag, description, and resolved schema.
+ */
 interface ParameterInfo {
   name: string;
   location: ParameterLocation;
@@ -24,6 +40,10 @@ interface ParameterInfo {
   description: string | undefined;
   schema: JsonObject | undefined;
 }
+/**
+ * Parsed view of an OpenAPI Response Object — status code, description,
+ * declared content types, response schema, and resolved headers.
+ */
 interface ResponseInfo {
   statusCode: string;
   description: string | undefined;
@@ -31,16 +51,29 @@ interface ResponseInfo {
   schema: JsonObject | undefined;
   headers: Map<string, HeaderInfo>;
 }
+/**
+ * Parsed view of an OpenAPI Request Body Object — required flag,
+ * description, declared content types, and the request body schema.
+ */
 interface RequestBodyInfo {
   required: boolean;
   description: string | undefined;
   contentTypes: string[];
   schema: JsonObject | undefined;
 }
+/**
+ * A single entry in an OpenAPI Security Requirement Object — the name
+ * of a security scheme paired with its list of required scopes.
+ */
 interface SecurityRequirement {
   name: string;
   scopes: string[];
 }
+/**
+ * Parsed view of an OpenAPI Security Scheme Object covering every
+ * field defined for `apiKey`, `http`, `oauth2`, `openIdConnect`, and
+ * `mutualTLS` schemes.
+ */
 interface SecurityScheme {
   type: string | undefined;
   description: string | undefined;
@@ -51,6 +84,10 @@ interface SecurityScheme {
   flows: JsonObject | undefined;
   openIdConnectUrl: string | undefined;
 }
+/**
+ * Parsed view of an OpenAPI Header Object — name, description, required
+ * and deprecated flags, and resolved schema.
+ */
 interface HeaderInfo {
   name: string;
   description: string | undefined;
@@ -58,14 +95,23 @@ interface HeaderInfo {
   deprecated: boolean;
   schema: JsonObject | undefined;
 }
+/**
+ * Parsed view of a single OpenAPI 3.1 webhook entry: its name and the
+ * operations declared on its Path Item Object.
+ */
 interface WebhookInfo {
   name: string;
   operations: OperationInfo[];
 }
+/** Parsed view of an OpenAPI External Documentation Object. */
 interface ExternalDocs {
   url: string;
   description: string | undefined;
 }
+/**
+ * Parsed view of an OpenAPI XML Object — controls how a schema field
+ * is serialised in an XML payload.
+ */
 interface XmlInfo {
   name: string | undefined;
   namespace: string | undefined;
@@ -73,10 +119,19 @@ interface XmlInfo {
   attribute: boolean;
   wrapped: boolean;
 }
+/**
+ * Parsed view of a single OpenAPI Callback Object: its name and the
+ * operations declared on every callback path.
+ */
 interface CallbackInfo {
   name: string;
   operations: OperationInfo[];
 }
+/**
+ * Parsed view of an OpenAPI Link Object — name, target operation
+ * (`operationId` or `operationRef`), description, parameter mappings,
+ * and the optional request body expression.
+ */
 interface LinkInfo {
   name: string;
   operationId: string | undefined;
@@ -85,15 +140,67 @@ interface LinkInfo {
   parameters: Map<string, string>;
   requestBody: string | undefined;
 }
+/**
+ * Build an {@link OpenApiDocument} from a raw OpenAPI JSON object.
+ *
+ * Eagerly indexes the document's `#/components/schemas/*` entries and
+ * lazily caches any other `$ref` lookup on first request. Used by
+ * every other helper in this module as the single entry point for
+ * structured access to an OpenAPI document.
+ */
 declare function parseOpenApiDocument(doc: JsonObject): OpenApiDocument;
+/**
+ * Resolve a `$ref` string against a parsed OpenAPI document. Returns
+ * the cached entry for `#/components/schemas/*` refs (or the lazily
+ * resolved value for arbitrary fragment refs), or `undefined` when the
+ * ref cannot be resolved.
+ */
 declare function getSchema(parsed: OpenApiDocument, ref: string): JsonObject | undefined;
+/**
+ * List every operation declared under the document's `paths` map.
+ * Follows Path Item `$ref` chains internally; cycles and over-deep
+ * chains surface as diagnostics when a sink is supplied.
+ */
 declare function listOperations(parsed: OpenApiDocument, diagnostics?: DiagnosticsOptions, seenIds?: Map<string, string>): OperationInfo[];
+/**
+ * Resolve the parameters of a single operation, merging path-level
+ * parameters with operation-level overrides and following any
+ * Parameter Object `$ref` chains.
+ */
 declare function getParameters(parsed: OpenApiDocument, path: string, method: string, diagnostics?: DiagnosticsOptions): ParameterInfo[];
+/**
+ * Resolve the request body of a single operation, including its
+ * declared content types and schema. Returns `undefined` when the
+ * operation declares no request body.
+ */
 declare function getRequestBody(parsed: OpenApiDocument, path: string, method: string): RequestBodyInfo | undefined;
+/**
+ * Resolve the responses of a single operation, returning one
+ * {@link ResponseInfo} per declared status code (including class
+ * wildcards and `default`).
+ */
 declare function getResponses(parsed: OpenApiDocument, path: string, method: string, diagnostics?: DiagnosticsOptions): ResponseInfo[];
+/**
+ * Resolve the effective security requirements for a single operation.
+ * Operation-level requirements override the document-level defaults
+ * when present.
+ */
 declare function getSecurityRequirements(parsed: OpenApiDocument, path: string, method: string): SecurityRequirement[];
+/**
+ * Read the document's `components.securitySchemes` map as a map of
+ * scheme names to {@link SecurityScheme} entries.
+ */
 declare function getSecuritySchemes(parsed: OpenApiDocument): Map<string, SecurityScheme>;
+/**
+ * Resolve the headers of a single OpenAPI Response Object as a map of
+ * header name to {@link HeaderInfo}. Follows Header Object `$ref`
+ * chains via the optional document root.
+ */
 declare function getResponseHeaders(response: JsonObject, doc?: JsonObject, diagnostics?: DiagnosticsOptions): Map<string, HeaderInfo>;
+/**
+ * List every OpenAPI 3.1 webhook declared under the document's
+ * `webhooks` map, each with its name and resolved operations.
+ */
 declare function listWebhooks(parsed: OpenApiDocument, diagnostics?: DiagnosticsOptions, seenIds?: Map<string, string>): WebhookInfo[];
 /**
  * Enumerate every operation in the document — both the `paths` map and
@@ -104,9 +211,29 @@ declare function listWebhooks(parsed: OpenApiDocument, diagnostics?: Diagnostics
  * grouping should call `listWebhooks` directly.
  */
 declare function listAllOperations(parsed: OpenApiDocument, diagnostics?: DiagnosticsOptions): OperationInfo[];
+/**
+ * Read the optional `externalDocs` field on an OpenAPI object
+ * (document, operation, tag, schema, ...) into an {@link ExternalDocs}
+ * record. Returns `undefined` when absent or malformed.
+ */
 declare function getExternalDocs(obj: JsonObject): ExternalDocs | undefined;
+/**
+ * Read the optional `xml` keyword on a JSON Schema object into an
+ * {@link XmlInfo} record describing how the field is serialised in an
+ * XML payload. Returns `undefined` when absent or malformed.
+ */
 declare function getXmlInfo(schema: JsonObject): XmlInfo | undefined;
+/**
+ * List the OpenAPI callback definitions declared on a single
+ * operation. Each entry carries the callback name and the operations
+ * declared on its Path Item Object.
+ */
 declare function listCallbacks(parsed: OpenApiDocument, path: string, method: string, diagnostics?: DiagnosticsOptions): CallbackInfo[];
+/**
+ * List the OpenAPI link definitions declared on a specific response of
+ * a single operation, returning each link's parsed
+ * {@link LinkInfo} entry.
+ */
 declare function getLinks(parsed: OpenApiDocument, path: string, method: string, statusCode: string, diagnostics?: DiagnosticsOptions): LinkInfo[];
 //#endregion
 export { CallbackInfo, ExternalDocs, HeaderInfo, LinkInfo, OpenApiDocument, OperationInfo, ParameterInfo, ParameterLocation, RequestBodyInfo, ResponseInfo, SecurityRequirement, SecurityScheme, WebhookInfo, XmlInfo, getExternalDocs, getLinks, getParameters, getRequestBody, getResponseHeaders, getResponses, getSchema, getSecurityRequirements, getSecuritySchemes, getXmlInfo, listAllOperations, listCallbacks, listOperations, listWebhooks, parseOpenApiDocument };

package/dist/openapi/parser.mjs

@@ -33,6 +33,14 @@ function toParameterLocation(value, parameterName, pointer, diagnostics) {
 		}
 	});
 }
+/**
+* Build an {@link OpenApiDocument} from a raw OpenAPI JSON object.
+*
+* Eagerly indexes the document's `#/components/schemas/*` entries and
+* lazily caches any other `$ref` lookup on first request. Used by
+* every other helper in this module as the single entry point for
+* structured access to an OpenAPI document.
+*/
 function parseOpenApiDocument(doc) {
 	const schemas = /* @__PURE__ */ new Map();
 	const componentSchemas = getProperty(getProperty(doc, "components"), "schemas");
@@ -44,6 +52,12 @@ function parseOpenApiDocument(doc) {
 		schemas
 	};
 }
+/**
+* Resolve a `$ref` string against a parsed OpenAPI document. Returns
+* the cached entry for `#/components/schemas/*` refs (or the lazily
+* resolved value for arbitrary fragment refs), or `undefined` when the
+* ref cannot be resolved.
+*/
 function getSchema(parsed, ref) {
 	const cached = parsed.schemas.get(ref);
 	if (cached !== void 0) return cached;
@@ -125,6 +139,11 @@ function recordOperationId(operationId, location, pointer, seenIds, diagnostics)
 	}
 	seenIds.set(operationId, location);
 }
+/**
+* List every operation declared under the document's `paths` map.
+* Follows Path Item `$ref` chains internally; cycles and over-deep
+* chains surface as diagnostics when a sink is supplied.
+*/
 function listOperations(parsed, diagnostics, seenIds = /* @__PURE__ */ new Map()) {
 	const operations = [];
 	const paths = getProperty(parsed.doc, "paths");
@@ -150,6 +169,11 @@ function listOperations(parsed, diagnostics, seenIds = /* @__PURE__ */ new Map()
 	}
 	return operations;
 }
+/**
+* Resolve the parameters of a single operation, merging path-level
+* parameters with operation-level overrides and following any
+* Parameter Object `$ref` chains.
+*/
 function getParameters(parsed, path, method, diagnostics) {
 	const pathItem = lookupPathItem(parsed, path);
 	if (pathItem === void 0) return [];
@@ -246,6 +270,11 @@ function resolveParam(doc, param, diagnostics) {
 function jsonPointerEscape(segment) {
 	return segment.replace(/~/g, "~0").replace(/\//g, "~1");
 }
+/**
+* Resolve the request body of a single operation, including its
+* declared content types and schema. Returns `undefined` when the
+* operation declares no request body.
+*/
 function getRequestBody(parsed, path, method) {
 	const requestBodyRaw = getProperty(getProperty(lookupPathItem(parsed, path), method), "requestBody");
 	if (!isObject(requestBodyRaw)) return void 0;
@@ -267,6 +296,11 @@ function getRequestBody(parsed, path, method) {
 		schema
 	};
 }
+/**
+* Resolve the responses of a single operation, returning one
+* {@link ResponseInfo} per declared status code (including class
+* wildcards and `default`).
+*/
 function getResponses(parsed, path, method, diagnostics) {
 	const responses = getProperty(getProperty(lookupPathItem(parsed, path), method), "responses");
 	if (!isObject(responses)) return [];
@@ -409,6 +443,11 @@ function resolveRefInDoc(doc, ref) {
 	}
 	return isObject(current) ? current : void 0;
 }
+/**
+* Resolve the effective security requirements for a single operation.
+* Operation-level requirements override the document-level defaults
+* when present.
+*/
 function getSecurityRequirements(parsed, path, method) {
 	const opSecurity = getProperty(getProperty(lookupPathItem(parsed, path), method), "security");
 	const globalSecurity = getProperty(parsed.doc, "security");
@@ -423,6 +462,10 @@ function getSecurityRequirements(parsed, path, method) {
 	}
 	return result;
 }
+/**
+* Read the document's `components.securitySchemes` map as a map of
+* scheme names to {@link SecurityScheme} entries.
+*/
 function getSecuritySchemes(parsed) {
 	const result = /* @__PURE__ */ new Map();
 	const securitySchemes = getProperty(getProperty(parsed.doc, "components"), "securitySchemes");
@@ -443,6 +486,11 @@ function getSecuritySchemes(parsed) {
 	}
 	return result;
 }
+/**
+* Resolve the headers of a single OpenAPI Response Object as a map of
+* header name to {@link HeaderInfo}. Follows Header Object `$ref`
+* chains via the optional document root.
+*/
 function getResponseHeaders(response, doc, diagnostics) {
 	const result = /* @__PURE__ */ new Map();
 	const headers = getProperty(response, "headers");
@@ -461,6 +509,10 @@ function getResponseHeaders(response, doc, diagnostics) {
 	}
 	return result;
 }
+/**
+* List every OpenAPI 3.1 webhook declared under the document's
+* `webhooks` map, each with its name and resolved operations.
+*/
 function listWebhooks(parsed, diagnostics, seenIds = /* @__PURE__ */ new Map()) {
 	const result = [];
 	const webhooks = getProperty(parsed.doc, "webhooks");
@@ -505,6 +557,11 @@ function listAllOperations(parsed, diagnostics) {
 	const webhookOps = listWebhooks(parsed, diagnostics, seenIds).flatMap((w) => w.operations);
 	return [...pathOps, ...webhookOps];
 }
+/**
+* Read the optional `externalDocs` field on an OpenAPI object
+* (document, operation, tag, schema, ...) into an {@link ExternalDocs}
+* record. Returns `undefined` when absent or malformed.
+*/
 function getExternalDocs(obj) {
 	const docs = getProperty(obj, "externalDocs");
 	if (!isObject(docs)) return void 0;
@@ -515,6 +572,11 @@ function getExternalDocs(obj) {
 		description: getString(docs, "description")
 	};
 }
+/**
+* Read the optional `xml` keyword on a JSON Schema object into an
+* {@link XmlInfo} record describing how the field is serialised in an
+* XML payload. Returns `undefined` when absent or malformed.
+*/
 function getXmlInfo(schema) {
 	const xml = getProperty(schema, "xml");
 	if (!isObject(xml)) return void 0;
@@ -526,6 +588,11 @@ function getXmlInfo(schema) {
 		wrapped: getProperty(xml, "wrapped") === true
 	};
 }
+/**
+* List the OpenAPI callback definitions declared on a single
+* operation. Each entry carries the callback name and the operations
+* declared on its Path Item Object.
+*/
 function listCallbacks(parsed, path, method, diagnostics) {
 	const operation = getProperty(lookupPathItem(parsed, path), method);
 	if (!isObject(operation)) return [];
@@ -559,6 +626,11 @@ function listCallbacks(parsed, path, method, diagnostics) {
 	}
 	return result;
 }
+/**
+* List the OpenAPI link definitions declared on a specific response of
+* a single operation, returning each link's parsed
+* {@link LinkInfo} entry.
+*/
 function getLinks(parsed, path, method, statusCode, diagnostics) {
 	const response = getProperty(getProperty(getProperty(lookupPathItem(parsed, path), method), "responses"), statusCode);
 	if (!isObject(response)) return [];

package/dist/openapi/resolve.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-ByEzkjrA.mjs";
 import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequestBody } from "./parser.mjs";
 
 //#region src/openapi/resolve.d.ts
@@ -58,6 +58,12 @@ interface PathItemInfo {
   summary: string | undefined;
   description: string | undefined;
 }
+/**
+ * Aggregate view of a single OpenAPI operation: the operation itself,
+ * its Path Item Object context, merged parameters, request body, and
+ * responses. Produced by {@link resolveOperation} /
+ * {@link resolveOperationFromParsed} for rendering and inspection.
+ */
 interface ResolvedOperation {
   operation: OperationInfo;
   pathItem: PathItemInfo;

package/dist/react/SchemaComponent.d.mts

@@ -1,12 +1,12 @@
-import { d as FieldOverrides, j as WalkedField, u as FieldOverride, w as SchemaMeta } from "../types-BTB73MB8.mjs";
-import { t as Diagnostic } from "../diagnostics-Cbwak-ZX.mjs";
-import { i as SchemaIoSide } from "../adapter-DqlAnZ_w.mjs";
-import { t as SchemaError } from "../errors-DQSIK4n1.mjs";
-import { l as RenderProps, r as ComponentResolver } from "../renderer-Ul9taFYp.mjs";
+import { d as FieldOverrides, j as WalkedField, u as FieldOverride, w as SchemaMeta } from "../types-C2Ay1FEh.mjs";
+import { t as Diagnostic } from "../diagnostics-ByEzkjrA.mjs";
+import { i as SchemaIoSide } from "../adapter-DcWi4XXn.mjs";
+import { t as SchemaError } from "../errors-D8JndRwI.mjs";
+import { l as RenderProps, r as ComponentResolver } from "../renderer-OaOz-n6-.mjs";
 import { FromJSONSchema, FromJSONSchemaMode, IsSwagger2Doc, PathOfType, RejectUnrepresentableZod, ResolveOpenAPIRef, TypeAtPath, __SchemaInferenceFellBack } from "../core/typeInference.mjs";
 import { z } from "zod";
-import { ReactNode } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { ReactNode } from "react";
 
 //#region src/react/SchemaComponent.d.ts
 /**
@@ -20,6 +20,27 @@ import * as _$react_jsx_runtime0 from "react/jsx-runtime";
  * Resolution order: instance → context → global → resolver → headless.
  */
 type WidgetMap = ReadonlyMap<string, (props: RenderProps) => unknown>;
+/**
+ * Provide a theme resolver and scoped widgets to every `<SchemaComponent>`
+ * and `<SchemaView>` rendered inside the subtree.
+ *
+ * Wrap an application (or a region of it) with `<SchemaProvider>` so a
+ * single theme — typically one of the bundled adapters
+ * (`shadcnResolver`, `muiResolver`, `mantineResolver`, `radixResolver`)
+ * or a custom one — drives every schema render. Without a provider,
+ * schema-components fall back to the headless HTML renderer.
+ *
+ * @group Components
+ * @example
+ * ```tsx
+ * import { SchemaProvider } from "schema-components/react/SchemaComponent";
+ * import { shadcnResolver } from "schema-components/themes/shadcn";
+ *
+ * <SchemaProvider resolver={shadcnResolver}>
+ *   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+ * </SchemaProvider>
+ * ```
+ */
 declare function SchemaProvider({
   resolver,
   widgets,
@@ -95,6 +116,15 @@ type InferredInputValue<T, Ref extends string | undefined = undefined, P extends
  * underlying helpers.
  */
 type InferredValue<T, Ref extends string | undefined = undefined, P extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> = NarrowAtPath<InferSchemaValue<T, Ref, Mode>, P>;
+/**
+ * Props accepted by {@link SchemaComponent}.
+ *
+ * The generic parameters carry the inferred schema shape through to
+ * `value`, `onChange`, and `fields` so a typed `schema` prop drives
+ * typed props on the rest of the component.
+ *
+ * @group Components
+ */
 interface SchemaComponentProps<T = unknown, Ref extends string | undefined = undefined, P extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> {
   /**
    * Zod schema, JSON Schema object, or OpenAPI document.
@@ -206,6 +236,29 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    */
   idPrefix?: string;
 }
+/**
+ * Render an editable (or read-only) UI from a Zod schema, JSON Schema, or
+ * OpenAPI document.
+ *
+ * Auto-detects the input format, normalises to JSON Schema via the
+ * adapter, walks the JSON Schema tree, and delegates per-field rendering
+ * to the {@link ComponentResolver} supplied via {@link SchemaProvider} —
+ * falling back to a headless HTML renderer when no provider is present.
+ *
+ * Pass `readOnly` to render a presentational view instead of inputs, or
+ * wrap with `<SchemaProvider resolver={…}>` to swap the theme.
+ *
+ * @group Components
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { SchemaComponent } from "schema-components/react/SchemaComponent";
+ *
+ * const userSchema = z.object({ name: z.string(), email: z.email() });
+ *
+ * <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+ * ```
+ */
 declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined, P extends string | undefined = undefined, Mode extends SchemaIoSide = "output">(props: SchemaComponentProps<T, Ref, P, Mode>): ReactNode;
 /**
  * Append a child path suffix to a parent path. When the suffix is omitted
@@ -225,11 +278,26 @@ declare function joinPath(parent: string, suffix: string | undefined): string;
  * with a single hyphen and trim leading/trailing hyphens.
  */
 declare function sanitisePrefix(value: string): string;
+/**
+ * Render a single walked field through the resolved widget /
+ * resolver / headless pipeline. Used internally by
+ * {@link SchemaComponent} and {@link SchemaField}, exported so other
+ * React-side components (e.g. the OpenAPI renderers) can dispatch
+ * into the same fallback chain.
+ */
 declare function renderField(tree: WalkedField, value: unknown, onChange: (v: unknown) => void, userResolver: ComponentResolver | undefined, renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void, pathSuffix?: string) => ReactNode, path: string, instanceWidgets?: WidgetMap, contextWidgets?: WidgetMap, depth?: number): 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;
+/**
+ * Props accepted by {@link SchemaField}. The generic `P` constrains
+ * `path` to dot-paths reachable through the schema's inferred value
+ * type — typed schemas get autocomplete; runtime schemas fall back to
+ * `string`.
+ *
+ * @group Components
+ */
 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").
@@ -254,6 +322,16 @@ interface SchemaFieldProps<T = unknown, Ref extends string | undefined = undefin
   validate?: boolean;
   onValidationError?: (error: unknown) => void;
 }
+/**
+ * Render a single field from a schema by dot-separated `path`.
+ *
+ * Walks the full schema tree and resolves the field at the supplied
+ * `path`, then renders only that field through the same resolver
+ * pipeline as {@link SchemaComponent}. Useful for embedding individual
+ * fields inside bespoke layouts.
+ *
+ * @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)>({
   path,
   schema: schemaInput,

package/dist/react/SchemaComponent.mjs

@@ -8,8 +8,8 @@ import { walk } from "../core/walker.mjs";
 import { headlessResolver } from "./headless.mjs";
 import { resolvePath, resolveValue, setNestedValue } from "./fieldPath.mjs";
 import { z } from "zod";
-import { createContext, isValidElement, useCallback, useContext, useId, useMemo } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { createContext, isValidElement, useCallback, useContext, useId, useMemo } from "react";
 //#region src/react/SchemaComponent.tsx
 /**
 * <SchemaComponent> — renders UI from Zod, JSON Schema, or OpenAPI schemas.
@@ -26,6 +26,27 @@ import { jsx, jsxs } from "react/jsx-runtime";
 */
 const UserResolverContext = createContext(void 0);
 const WidgetsContext = createContext(void 0);
+/**
+* Provide a theme resolver and scoped widgets to every `<SchemaComponent>`
+* and `<SchemaView>` rendered inside the subtree.
+*
+* Wrap an application (or a region of it) with `<SchemaProvider>` so a
+* single theme — typically one of the bundled adapters
+* (`shadcnResolver`, `muiResolver`, `mantineResolver`, `radixResolver`)
+* or a custom one — drives every schema render. Without a provider,
+* schema-components fall back to the headless HTML renderer.
+*
+* @group Components
+* @example
+* ```tsx
+* import { SchemaProvider } from "schema-components/react/SchemaComponent";
+* import { shadcnResolver } from "schema-components/themes/shadcn";
+*
+* <SchemaProvider resolver={shadcnResolver}>
+*   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+* </SchemaProvider>
+* ```
+*/
 function SchemaProvider({ resolver, widgets, children }) {
 	return /* @__PURE__ */ jsx(UserResolverContext.Provider, {
 		value: resolver,
@@ -47,6 +68,29 @@ const globalWidgets = /* @__PURE__ */ new Map();
 function registerWidget(name, render) {
 	globalWidgets.set(name, render);
 }
+/**
+* Render an editable (or read-only) UI from a Zod schema, JSON Schema, or
+* OpenAPI document.
+*
+* Auto-detects the input format, normalises to JSON Schema via the
+* adapter, walks the JSON Schema tree, and delegates per-field rendering
+* to the {@link ComponentResolver} supplied via {@link SchemaProvider} —
+* falling back to a headless HTML renderer when no provider is present.
+*
+* Pass `readOnly` to render a presentational view instead of inputs, or
+* wrap with `<SchemaProvider resolver={…}>` to swap the theme.
+*
+* @group Components
+* @example
+* ```tsx
+* import { z } from "zod";
+* import { SchemaComponent } from "schema-components/react/SchemaComponent";
+*
+* const userSchema = z.object({ name: z.string(), email: z.email() });
+*
+* <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+* ```
+*/
 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 userResolver = useContext(UserResolverContext);
@@ -220,6 +264,13 @@ function runValidation(zodSchema, jsonSchema, value, io, onDiagnostic) {
 		}
 	}
 }
+/**
+* Render a single walked field through the resolved widget /
+* resolver / headless pipeline. Used internally by
+* {@link SchemaComponent} and {@link SchemaField}, exported so other
+* React-side components (e.g. the OpenAPI renderers) can dispatch
+* into the same fallback chain.
+*/
 function renderField(tree, value, onChange, userResolver, renderChild, path, instanceWidgets, contextWidgets, depth = 0) {
 	if (path.length === 0) throw new Error("renderField requires a non-empty path. Pass the root path (derived from `idPrefix` or `useId()`) for the root field, and use renderChild's pathSuffix to derive child paths.");
 	if (depth >= 10) return /* @__PURE__ */ jsx("fieldset", { children: /* @__PURE__ */ jsxs("em", { children: [
@@ -255,6 +306,16 @@ function renderField(tree, value, onChange, userResolver, renderChild, path, ins
 	if (value === void 0 || value === null) return /* @__PURE__ */ jsx("span", { children: "—" });
 	return /* @__PURE__ */ jsx("span", { children: typeof value === "string" ? value : JSON.stringify(value) });
 }
+/**
+* Render a single field from a schema by dot-separated `path`.
+*
+* Walks the full schema tree and resolves the field at the supplied
+* `path`, then renders only that field through the same resolver
+* pipeline as {@link SchemaComponent}. Useful for embedding individual
+* fields inside bespoke layouts.
+*
+* @group Components
+*/
 function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange, meta: fieldMeta, validate, onValidationError }) {
 	const userResolver = useContext(UserResolverContext);
 	const contextWidgets = useContext(WidgetsContext);

package/dist/react/SchemaErrorBoundary.d.mts

@@ -1,6 +1,11 @@
 import { Component, ReactNode } from "react";
 
 //#region src/react/SchemaErrorBoundary.d.ts
+/**
+ * Props accepted by {@link SchemaErrorBoundary}.
+ *
+ * @group Components
+ */
 interface SchemaErrorBoundaryProps {
   /** Called with the caught error. Returns fallback ReactNode to render. */
   fallback: (error: Error, reset: () => void) => ReactNode;
@@ -10,10 +15,22 @@ interface ErrorBoundaryState {
   error: Error | undefined;
 }
 /**
- * React error boundary that catches schema rendering errors.
+ * React error boundary that catches rendering errors from
+ * `SchemaComponent`, theme adapters, and any descendant.
  *
  * Provides a `reset` callback that clears the error state, allowing
  * the children to re-render (e.g. after fixing a bad schema prop).
+ * Does not catch errors thrown from event handlers, async work, or
+ * server-side rendering — those paths must be handled by the host
+ * application.
+ *
+ * @group Components
+ * @example
+ * ```tsx
+ * <SchemaErrorBoundary fallback={(error) => <p>{error.message}</p>}>
+ *   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+ * </SchemaErrorBoundary>
+ * ```
  */
 declare class SchemaErrorBoundary extends Component<SchemaErrorBoundaryProps, ErrorBoundaryState> {
   state: ErrorBoundaryState;