schema-components 1.28.2 → 2.0.0

package/dist/openapi/resolve.mjs

@@ -3,9 +3,9 @@ import "../core/limits.mjs";
 import { emitDiagnostic } from "../core/diagnostics.mjs";
 import { isPrototypePollutingKey } from "../core/uri.mjs";
 import { detectOpenApiVersion } from "../core/version.mjs";
-import { o as normaliseOpenApiSchemas, r as documentContainsKeyword } from "../normalise-Db1xaxgx.mjs";
+import { o as normaliseOpenApiSchemas, r as documentContainsKeyword } from "../normalise-DB-Xtjmn.mjs";
 import { resolveRefChain } from "../core/refChain.mjs";
-import { getParameters, getRequestBody, getResponses, listAllOperations, parseOpenApiDocument } from "./parser.mjs";
+import { extractParameters, extractRequestBody, extractResponses, listAllOperations, parseOpenApiDocument } from "./parser.mjs";
 //#region src/openapi/resolve.ts
 /**
 * OpenAPI document resolution and caching.
@@ -24,7 +24,7 @@ const docCache = /* @__PURE__ */ new WeakMap();
 * keywords (`nullable`, `discriminator`, `example`), OpenAPI 3.1.x
 * `discriminator`, and Swagger 2.0 documents are all converted to
 * canonical Draft 2020-12 form. The parser and downstream extractors
-* (`getRequestBody`, `getResponses`, etc.) then observe schemas in the
+* (`extractRequestBody`, `extractResponses`, etc.) then observe schemas in the
 * same form `<SchemaComponent>` does, keeping the OpenAPI components on
 * the same pipeline as the top-level adapter.
 *
@@ -314,16 +314,20 @@ function extractPathItemInfo(pathItem) {
 	};
 }
 /**
-* Resolve an operation against an already-parsed document. Throws if
-* the operation is not found.
+* Resolve an operation from an OpenAPI document by path and method.
+* Throws if the operation is not found.
 *
-* Used by callers that have already obtained a parsed document via
-* {@link getParsed} — most importantly the React components, which
-* supply `diagnostics` to `getParsed` and must avoid re-running the
-* normalisation pipeline (every re-run would emit each diagnostic
-* again into the sink).
+* Accepts either a raw document (parsed lazily via {@link getParsed}'s
+* WeakMap cache) or an already-parsed {@link OpenApiDocument}. Callers
+* that have a parsed document at hand can pass it directly to avoid
+* an extra cache lookup; everyone else trusts the cache.
+*
+* `diagnostics` is forwarded to {@link getParsed} so normalisation
+* events surface to the caller's sink exactly once per `(doc, sink)`
+* pair, no matter how many times this function is called.
 */
-function resolveOperationFromParsed(parsed, path, method, diagnostics) {
+function resolveOperation(doc, path, method, diagnostics) {
+	const parsed = ensureParsed(doc, diagnostics);
 	const pathItemNode = lookupPathItemNode(parsed, path, diagnostics);
 	const operation = listAllOperations(parsed).find((op) => op.path === path && op.method === method);
 	if (operation === void 0) throw new Error(`Operation not found: ${method.toUpperCase()} ${path}`);
@@ -331,79 +335,81 @@ function resolveOperationFromParsed(parsed, path, method, diagnostics) {
 	return {
 		operation,
 		pathItem: extractPathItemInfo(pathItemNode),
-		parameters: getParameters(parsed, path, method),
-		requestBody: getRequestBody(parsed, path, method),
-		responses: getResponses(parsed, path, method)
+		parameters: extractParameters(parsed, path, method),
+		requestBody: extractRequestBody(parsed, path, method),
+		responses: extractResponses(parsed, path, method)
 	};
 }
 /**
-* Resolve an operation from an OpenAPI document by path and method.
-* Throws if the operation is not found.
-*
-* `diagnostics` is forwarded to {@link getParsed} so normalisation
-* events surface to the caller's sink.
+* Coerce the first argument of every `resolveX` function — either a
+* raw OpenAPI document or an already-parsed {@link OpenApiDocument} —
+* into a parsed view. Distinguishes the two by the presence of the
+* `schemas` map on the parsed shape; falls through to {@link getParsed}
+* for raw documents (which itself short-circuits on a WeakMap cache).
 */
-function resolveOperation(doc, path, method, diagnostics) {
-	return resolveOperationFromParsed(getParsed(doc, diagnostics), path, method, diagnostics);
+function ensureParsed(doc, diagnostics) {
+	if (isParsedDocument(doc)) {
+		const cached = docCache.get(doc.doc);
+		if (cached !== void 0 && (diagnostics?.diagnostics !== void 0 || diagnostics?.strict === true)) replayCapturedDiagnostics(cached, diagnostics);
+		return doc;
+	}
+	return getParsed(doc, diagnostics);
 }
 /**
-* Resolve parameters against an already-parsed document. See
-* {@link resolveOperationFromParsed} for the rationale.
+* Decide whether `value` is an already-parsed {@link OpenApiDocument}.
+* The parsed shape carries a `schemas` Map alongside the raw `doc`
+* object; a raw OpenAPI document has neither — its keys are
+* `openapi`/`swagger`, `info`, `paths`, etc.
 */
-function resolveParametersFromParsed(parsed, path, method) {
-	return getParameters(parsed, path, method);
+function isParsedDocument(value) {
+	return isObject(value.doc) && value.schemas instanceof Map;
 }
 /**
-* Resolve parameters for an operation. Returns empty array if none.
+* Resolve parameters for an operation. Returns an empty array if none.
 *
-* `diagnostics` is forwarded to {@link getParsed} so normalisation
-* events surface to the caller's sink.
+* Accepts either a raw document or an already-parsed
+* {@link OpenApiDocument}. `diagnostics` is forwarded to
+* {@link getParsed} so normalisation events surface to the caller's
+* sink.
 */
 function resolveParameters(doc, path, method, diagnostics) {
-	return resolveParametersFromParsed(getParsed(doc, diagnostics), path, method);
+	return extractParameters(ensureParsed(doc, diagnostics), path, method);
 }
 /**
-* Resolve a request body against an already-parsed document. See
-* {@link resolveOperationFromParsed} for the rationale.
-*/
-function resolveRequestBodyFromParsed(parsed, path, method) {
-	return getRequestBody(parsed, path, method);
-}
-/**
-* Resolve request body for an operation. Returns undefined if none.
+* Resolve the request body for an operation. Returns `undefined` if
+* the operation declares no request body.
 *
-* `diagnostics` is forwarded to {@link getParsed} so normalisation
-* events surface to the caller's sink.
+* Accepts either a raw document or an already-parsed
+* {@link OpenApiDocument}. `diagnostics` is forwarded to
+* {@link getParsed} so normalisation events surface to the caller's
+* sink.
 */
 function resolveRequestBody(doc, path, method, diagnostics) {
-	return resolveRequestBodyFromParsed(getParsed(doc, diagnostics), path, method);
-}
-/**
-* Resolve a specific response against an already-parsed document. See
-* {@link resolveOperationFromParsed} for the rationale.
-*/
-function resolveResponseFromParsed(parsed, path, method, statusCode) {
-	const response = getResponses(parsed, path, method).find((r) => r.statusCode === statusCode);
-	if (response === void 0) throw new Error(`Response not found: ${statusCode}`);
-	return response;
+	return extractRequestBody(ensureParsed(doc, diagnostics), path, method);
 }
 /**
 * Resolve a specific response by status code. Throws if not found.
 *
-* `diagnostics` is forwarded to {@link getParsed} so normalisation
-* events surface to the caller's sink.
+* Accepts either a raw document or an already-parsed
+* {@link OpenApiDocument}. `diagnostics` is forwarded to
+* {@link getParsed} so normalisation events surface to the caller's
+* sink.
 */
 function resolveResponse(doc, path, method, statusCode, diagnostics) {
-	return resolveResponseFromParsed(getParsed(doc, diagnostics), path, method, statusCode);
+	const response = extractResponses(ensureParsed(doc, diagnostics), path, method).find((r) => r.statusCode === statusCode);
+	if (response === void 0) throw new Error(`Response not found: ${statusCode}`);
+	return response;
 }
 /**
 * Resolve all responses for an operation.
 *
-* `diagnostics` is forwarded to {@link getParsed} so normalisation
-* events surface to the caller's sink.
+* Accepts either a raw document or an already-parsed
+* {@link OpenApiDocument}. `diagnostics` is forwarded to
+* {@link getParsed} so normalisation events surface to the caller's
+* sink.
 */
 function resolveResponses(doc, path, method, diagnostics) {
-	return getResponses(getParsed(doc, diagnostics), path, method);
+	return extractResponses(ensureParsed(doc, diagnostics), path, method);
 }
 //#endregion
-export { getParsed, resolveOperation, resolveOperationFromParsed, resolveParameters, resolveParametersFromParsed, resolveRequestBody, resolveRequestBodyFromParsed, resolveResponse, resolveResponseFromParsed, resolveResponses, toDoc };
+export { getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, resolveResponses, toDoc };

package/dist/react/SchemaComponent.d.mts

@@ -1,25 +1,36 @@
-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 { FromJSONSchema, FromJSONSchemaMode, IsSwagger2Doc, PathOfType, RejectUnrepresentableZod, ResolveOpenAPIRef, TypeAtPath, __SchemaInferenceFellBack } from "../core/typeInference.mjs";
+import { j as WalkedField, w as SchemaMeta } from "../types-BrYbjC7_.mjs";
+import { t as Diagnostic } from "../diagnostics-BTrm3O6J.mjs";
+import { SchemaIoSide } from "../core/adapter.mjs";
+import { ComponentResolver, RenderProps, WidgetMap } from "../core/renderer.mjs";
+import { t as SchemaError } from "../errors-Dki7tji4.mjs";
+import { FromJSONSchema, PathOfType, RejectUnrepresentableZod } from "../core/typeInference.mjs";
+import { a as InferredValue, i as InferredOutputValue, n as InferSchemaValue, r as InferredInputValue, t as InferFields } from "../inferValue-PPXWJpbN.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
 /**
- * Widget map — maps component hints (from `.meta({ component })`) to render
- * functions. Scoped at three levels:
+ * Provide a theme resolver and scoped widgets to every `<SchemaComponent>`
+ * and `<SchemaView>` rendered inside the subtree.
  *
- * 1. **Per-instance** — `widgets` prop on `<SchemaComponent>`
- * 2. **Context-scoped** — `widgets` prop on `<SchemaProvider>`
- * 3. **Global** — `registerWidget()` (app-wide defaults)
+ * 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.
  *
- * Resolution order: instance → context → global → resolver → headless.
+ * @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>
+ * ```
  */
-type WidgetMap = ReadonlyMap<string, (props: RenderProps) => unknown>;
 declare function SchemaProvider({
   resolver,
   widgets,
@@ -37,65 +48,25 @@ declare function SchemaProvider({
  * or `<SchemaProvider>` instead.
  */
 declare function registerWidget(name: string, render: (props: RenderProps) => unknown): void;
-type InferFields<T, Ref extends string | undefined> = IsSwagger2Doc<T> extends true ? __SchemaInferenceFellBack : 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>;
 /**
- * Infer the data type carried by the schema input.
- *
- * Mirrors {@link InferFields}'s dispatch order: Zod schema → `z.infer`,
- * OpenAPI doc + ref → `ResolveOpenAPIRef`, plain JSON Schema object →
- * `FromJSONSchema`, everything else → `unknown`. The `Mode` parameter
- * is plumbed through to `FromJSONSchema` / `ResolveOpenAPIRef` so
- * `readOnly` / `writeOnly` keywords participate in the inferred
- * object shape — `"output"` for the rendered value, `"input"` for the
- * `onChange` argument.
+ * Clear every globally registered widget. Intended for test isolation —
+ * `registerWidget` writes to module-level state and that state otherwise
+ * leaks across test cases, making the test suite order-dependent. Tests
+ * should call this from an `afterEach` hook.
  *
- * When the schema's value type cannot be statically determined (e.g.
- * a runtime `Record<string, unknown>` JSON Schema, or an OpenAPI doc
- * without a ref), the result falls back to `unknown` so callers can
- * still supply arbitrary values.
+ * @internal
  */
-type InferSchemaValue<T, Ref extends string | undefined, Mode extends FromJSONSchemaMode> = IsSwagger2Doc<T> extends true ? __SchemaInferenceFellBack : T extends z.ZodType ? Mode extends "input" ? z.input<T> : z.output<T> : T extends {
-  openapi: unknown;
-} ? Ref extends string ? ResolveOpenAPIRef<T & Record<string, unknown>, Ref, [], Mode> : unknown : T extends object ? FromJSONSchema<T, Record<string, never>, [], Mode> | (unknown extends FromJSONSchema<T> ? unknown : never) extends infer V ? V : unknown : unknown;
+declare function __clearGlobalWidgets(): void;
 /**
- * Narrow an inferred value type to the sub-shape at `P`, or return
- * the original value type when `P` is `undefined` (no path supplied).
- */
-type NarrowAtPath<V, P extends string | undefined> = P extends string ? TypeAtPath<V, P> : V;
-/**
- * Public alias mapping a schema input to the rendered value type.
+ * Props accepted by {@link SchemaComponent}.
  *
- * Picks the OUTPUT side (server → client) of every transform / pipe /
- * codec. For an `<SchemaComponent io="output">` or `<SchemaView
- * io="output">` (both defaults), this is the inferred shape of
- * `value` and the parameter of `onChange`.
- */
-type InferredOutputValue<T, Ref extends string | undefined = undefined, P extends string | undefined = undefined> = NarrowAtPath<InferSchemaValue<T, Ref, "output">, P>;
-/**
- * Companion to {@link InferredOutputValue} for `"input"`-mode shapes.
+ * 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.
  *
- * Picks the INPUT side (client → server) of every transform / pipe /
- * codec. Surfaces as the inferred shape of `value` / `onChange` when
- * a consumer renders `<SchemaComponent io="input">`. For JSON Schema
- * inputs with `readOnly`/`writeOnly` annotations, the INPUT mode
- * omits properties marked `readOnly: true`.
+ * @group Components
  */
-type InferredInputValue<T, Ref extends string | undefined = undefined, P extends string | undefined = undefined> = NarrowAtPath<InferSchemaValue<T, Ref, "input">, P>;
-/**
- * Resolve the schema-driven value type for either I/O direction.
- *
- * Thin convenience over {@link InferredOutputValue} /
- * {@link InferredInputValue} so consumers that decide between the
- * two at the type level (e.g. a generic wrapper component) can pass
- * the chosen direction as a type argument rather than branch on it
- * with conditional types. Falls back to `unknown` when the schema's
- * value type cannot be statically inferred, identical to the
- * 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>;
-interface SchemaComponentProps<T = unknown, Ref extends string | undefined = undefined, P extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> {
+interface SchemaComponentProps<T = unknown, Ref extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> {
   /**
    * Zod schema, JSON Schema object, or OpenAPI document.
    *
@@ -109,21 +80,6 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
   schema: RejectUnrepresentableZod<T>;
   /** For OpenAPI: a ref string like "#/components/schemas/User" or "/users/post". */
   ref?: Ref;
-  /**
-   * Optional dot-separated path used purely for type narrowing.
-   * When the schema is typed, the path is restricted to the valid
-   * dot-paths reachable through the schema's inferred value.
-   *
-   * RUNTIME CAVEAT: this prop is currently type-level only. The
-   * render pipeline still operates on the root schema; sub-path
-   * value resolution is provided by the dedicated `<SchemaField>`
-   * component, which already implements `resolvePath` /
-   * `setNestedValue`. The `path` prop here documents intent at the
-   * type level (and prepares the API surface) so consumers can
-   * declare narrow typed wrappers without runtime regressions. Use
-   * `<SchemaField>` when a sub-path render is required at runtime.
-   */
-  path?: P;
   /**
    * Which side of every transform / pipe / codec to render.
    *
@@ -148,9 +104,7 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
   /**
    * Current value to render. Typed against `InferSchemaValue<T,
    * Ref, Mode>` so the prop tracks the schema's inferred shape for
-   * the chosen `io` direction. Narrowed further by `P` when a
-   * `path` is supplied (currently type-level only — see the JSDoc
-   * on {@link SchemaComponentProps.path}).
+   * the chosen `io` direction.
    *
    * Falls back to `unknown` when the schema's value type cannot be
    * statically inferred (runtime `Record<string, unknown>` JSON
@@ -165,7 +119,7 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    * <SchemaComponent schema={userSchema} value={user} readOnly />
    * ```
    */
-  value?: NarrowAtPath<InferSchemaValue<T, Ref, Mode>, P>;
+  value?: InferSchemaValue<T, Ref, Mode>;
   /**
    * Called when the value changes (editable fields). The parameter
    * shares the same shape as {@link SchemaComponentProps.value} so
@@ -175,7 +129,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: NarrowAtPath<InferSchemaValue<T, Ref, Mode>, P>) => void;
+  onChange?: (value: InferSchemaValue<T, Ref, Mode>) => void;
   /** Run schema.safeParse() on change and surface errors via onValidationError. */
   validate?: boolean;
   /** Called with the ZodError when validation fails. */
@@ -206,7 +160,30 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    */
   idPrefix?: string;
 }
-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;
+/**
+ * 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, Mode extends SchemaIoSide = "output">(props: SchemaComponentProps<T, Ref, 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
@@ -225,11 +202,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 +246,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,
@@ -265,4 +267,4 @@ declare function SchemaField<T = unknown, Ref extends string | undefined = undef
   onValidationError
 }: SchemaFieldProps<T, Ref, P>): ReactNode;
 //#endregion
-export { InferredInputValue, InferredOutputValue, InferredValue, SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, WidgetMap, joinPath, registerWidget, renderField, sanitisePrefix };
+export { type InferFields, type InferredInputValue, type InferredOutputValue, type InferredValue, SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, __clearGlobalWidgets, joinPath, registerWidget, renderField, sanitisePrefix };

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,40 @@ const globalWidgets = /* @__PURE__ */ new Map();
 function registerWidget(name, render) {
 	globalWidgets.set(name, render);
 }
+/**
+* Clear every globally registered widget. Intended for test isolation —
+* `registerWidget` writes to module-level state and that state otherwise
+* leaks across test cases, making the test suite order-dependent. Tests
+* should call this from an `afterEach` hook.
+*
+* @internal
+*/
+function __clearGlobalWidgets() {
+	globalWidgets.clear();
+}
+/**
+* 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 +275,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 +317,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);
@@ -344,4 +416,4 @@ function isCallable(value) {
 	return typeof value === "function";
 }
 //#endregion
-export { SchemaComponent, SchemaField, SchemaProvider, joinPath, registerWidget, renderField, sanitisePrefix };
+export { SchemaComponent, SchemaField, SchemaProvider, __clearGlobalWidgets, joinPath, registerWidget, renderField, sanitisePrefix };

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;

package/dist/react/SchemaErrorBoundary.mjs

@@ -23,10 +23,22 @@ import { Component } from "react";
 * - Errors in server-side rendering
 */
 /**
-* 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>
+* ```
 */
 var SchemaErrorBoundary = class extends Component {
 	state = { error: void 0 };