schema-components 1.28.2 → 1.29.0

package/dist/core/walkBuilders.d.mts

@@ -1,11 +1,21 @@
-import { A as UnknownField, D as StringField, b as NumberField, c as FieldBase, j as WalkedField, o as Editability, p as FileField, r as BooleanField, v as NullField, w as SchemaMeta } from "../types-BTB73MB8.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
-import { t as ExternalResolver } from "../ref-TdeMfaV_.mjs";
+import { A as UnknownField, D as StringField, b as NumberField, c as FieldBase, j as WalkedField, o as Editability, p as FileField, r as BooleanField, v as NullField, w as SchemaMeta } from "../types-C2Ay1FEh.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-ByEzkjrA.mjs";
+import { t as ExternalResolver } from "../ref-CPh8rKQ3.mjs";
 
 //#region src/core/walkBuilders.d.ts
+/** Read a key from a JSON object, returning the value when it is a string and `undefined` otherwise. */
 declare function getString(obj: Record<string, unknown>, key: string): string | undefined;
+/** Read a key from a JSON object, returning the value when it is an array and `undefined` otherwise. */
 declare function getArray(obj: Record<string, unknown>, key: string): unknown[] | undefined;
+/** Read a key from a JSON object, returning the value when it is a plain object and `undefined` otherwise. */
 declare function getObject(obj: Record<string, unknown>, key: string): Record<string, unknown> | undefined;
+/**
+ * Options accepted by `walk`. Use to inject meta overrides, field-level
+ * overrides, the root document for cross-document `$ref` resolution, a
+ * diagnostics sink, and an external `$ref` resolver.
+ *
+ * @group Walkers
+ */
 interface WalkOptions {
   componentMeta?: SchemaMeta | undefined;
   rootMeta?: SchemaMeta | undefined;
@@ -18,9 +28,34 @@ interface WalkOptions {
   /** Sync resolver for external $ref URIs. */
   externalResolver?: ExternalResolver;
 }
+/**
+ * Extract recognised meta keywords (`readOnly`, `writeOnly`,
+ * `description`, `title`, `deprecated`, `default`, `component`,
+ * `example`, `examples`) from a JSON Schema node into the `SchemaMeta`
+ * shape consumed by the walker.
+ */
 declare function extractMetaFromJson(schema: Record<string, unknown>): SchemaMeta;
+/**
+ * Project the meta-style keys (`readOnly`, `writeOnly`, `description`,
+ * `title`, `deprecated`, `component`, `visible`, `order`) out of a
+ * field override object into a `SchemaMeta`. Returns `undefined` when
+ * the override has no meta fields so the walker can short-circuit.
+ */
 declare function extractSchemaMetaFields(overrides: Record<string, unknown> | undefined): SchemaMeta | undefined;
+/**
+ * Pluck the nested override at `key` from a parent field override map.
+ * Returns `undefined` when no override is present or when the entry is
+ * not a non-array object.
+ */
 declare function extractChildOverride(overrides: Record<string, unknown> | undefined, key: string): Record<string, unknown> | undefined;
+/**
+ * Mutable context threaded through every recursive walk step. Carries
+ * the merged metadata, field overrides, document root, nullability /
+ * optionality flags, `$ref` cache, diagnostics sink, and per-document
+ * `$ref` depth bound that `walkBuilders` and the walker itself share.
+ *
+ * @group Walkers
+ */
 interface WalkContext {
   componentMeta: SchemaMeta | undefined;
   rootMeta: SchemaMeta | undefined;
@@ -46,11 +81,17 @@ interface WalkContext {
 declare function buildBase(schema: Record<string, unknown>, ctx: WalkContext): FieldBase & {
   editability: Editability;
 };
+/** Build a walked `StringField` from a JSON Schema node. */
 declare function buildStringField(schema: Record<string, unknown>, ctx: WalkContext): StringField;
+/** Build a walked `NumberField` from a JSON Schema node. */
 declare function buildNumberField(schema: Record<string, unknown>, ctx: WalkContext): NumberField;
+/** Build a walked `BooleanField` from a JSON Schema node. */
 declare function buildBooleanField(schema: Record<string, unknown>, ctx: WalkContext): BooleanField;
+/** Build a walked `NullField` from a JSON Schema node. */
 declare function buildNullField(schema: Record<string, unknown>, ctx: WalkContext): NullField;
+/** Build a walked `UnknownField` (permissive open-shape) from a JSON Schema node. */
 declare function buildUnknownField(schema: Record<string, unknown>, ctx: WalkContext): UnknownField;
+/** Build a walked `FileField` from a JSON Schema node carrying `contentMediaType`. */
 declare function buildFileField(schema: Record<string, unknown>, ctx: WalkContext): FileField;
 /**
  * Walk a map of sub-schemas (patternProperties, dependentSchemas, $defs).
@@ -69,6 +110,10 @@ declare function walkDependentRequiredMap(map: Record<string, unknown>): Record<
  * Used to strip composition keywords before walking the base schema.
  */
 declare function withoutKeys(schema: Record<string, unknown>, keys: string[]): Record<string, unknown>;
+/**
+ * Type guard for a JSON primitive: string, number, boolean, or null.
+ * Used to short-circuit walk-time decisions about leaf values.
+ */
 declare function isPrimitive(value: unknown): value is string | number | boolean | null;
 /**
  * Convert any JSON-shaped value to a display string suitable for

package/dist/core/walkBuilders.mjs

@@ -2,14 +2,17 @@ import { isObject } from "./guards.mjs";
 import { extractFileConstraints, extractNumberConstraints, extractStringConstraints } from "./constraints.mjs";
 import { resolveEditability } from "./types.mjs";
 //#region src/core/walkBuilders.ts
+/** Read a key from a JSON object, returning the value when it is a string and `undefined` otherwise. */
 function getString(obj, key) {
 	const value = obj[key];
 	return typeof value === "string" ? value : void 0;
 }
+/** Read a key from a JSON object, returning the value when it is an array and `undefined` otherwise. */
 function getArray(obj, key) {
 	const value = obj[key];
 	return Array.isArray(value) ? value : void 0;
 }
+/** Read a key from a JSON object, returning the value when it is a plain object and `undefined` otherwise. */
 function getObject(obj, key) {
 	const value = obj[key];
 	return isObject(value) ? value : void 0;
@@ -25,6 +28,12 @@ const META_KEYWORDS = new Set([
 	"example",
 	"examples"
 ]);
+/**
+* Extract recognised meta keywords (`readOnly`, `writeOnly`,
+* `description`, `title`, `deprecated`, `default`, `component`,
+* `example`, `examples`) from a JSON Schema node into the `SchemaMeta`
+* shape consumed by the walker.
+*/
 function extractMetaFromJson(schema) {
 	const meta = {};
 	for (const [key, value] of Object.entries(schema)) if (META_KEYWORDS.has(key)) meta[key] = value;
@@ -40,12 +49,23 @@ const OVERRIDE_META_KEYS = new Set([
 	"visible",
 	"order"
 ]);
+/**
+* Project the meta-style keys (`readOnly`, `writeOnly`, `description`,
+* `title`, `deprecated`, `component`, `visible`, `order`) out of a
+* field override object into a `SchemaMeta`. Returns `undefined` when
+* the override has no meta fields so the walker can short-circuit.
+*/
 function extractSchemaMetaFields(overrides) {
 	if (overrides === void 0) return void 0;
 	const meta = {};
 	for (const key of Object.keys(overrides)) if (OVERRIDE_META_KEYS.has(key)) meta[key] = overrides[key];
 	return Object.keys(meta).length > 0 ? meta : void 0;
 }
+/**
+* Pluck the nested override at `key` from a parent field override map.
+* Returns `undefined` when no override is present or when the entry is
+* not a non-array object.
+*/
 function extractChildOverride(overrides, key) {
 	if (overrides === void 0) return void 0;
 	const child = overrides[key];
@@ -77,6 +97,7 @@ function buildBase(schema, ctx) {
 		...examples !== void 0 ? { examples } : {}
 	};
 }
+/** Build a walked `StringField` from a JSON Schema node. */
 function buildStringField(schema, ctx) {
 	return {
 		...buildBase(schema, ctx),
@@ -84,6 +105,7 @@ function buildStringField(schema, ctx) {
 		constraints: extractStringConstraints(schema, ctx.diagnostics, ctx.pointer)
 	};
 }
+/** Build a walked `NumberField` from a JSON Schema node. */
 function buildNumberField(schema, ctx) {
 	return {
 		...buildBase(schema, ctx),
@@ -91,6 +113,7 @@ function buildNumberField(schema, ctx) {
 		constraints: extractNumberConstraints(schema)
 	};
 }
+/** Build a walked `BooleanField` from a JSON Schema node. */
 function buildBooleanField(schema, ctx) {
 	return {
 		...buildBase(schema, ctx),
@@ -98,6 +121,7 @@ function buildBooleanField(schema, ctx) {
 		constraints: {}
 	};
 }
+/** Build a walked `NullField` from a JSON Schema node. */
 function buildNullField(schema, ctx) {
 	return {
 		...buildBase(schema, ctx),
@@ -105,6 +129,7 @@ function buildNullField(schema, ctx) {
 		constraints: {}
 	};
 }
+/** Build a walked `UnknownField` (permissive open-shape) from a JSON Schema node. */
 function buildUnknownField(schema, ctx) {
 	return {
 		...buildBase(schema, ctx),
@@ -112,6 +137,7 @@ function buildUnknownField(schema, ctx) {
 		constraints: {}
 	};
 }
+/** Build a walked `FileField` from a JSON Schema node carrying `contentMediaType`. */
 function buildFileField(schema, ctx) {
 	return {
 		...buildBase(schema, ctx),
@@ -148,6 +174,10 @@ function withoutKeys(schema, keys) {
 	for (const [key, value] of Object.entries(schema)) if (!keys.includes(key)) result[key] = value;
 	return result;
 }
+/**
+* Type guard for a JSON primitive: string, number, boolean, or null.
+* Used to short-circuit walk-time decisions about leaf values.
+*/
 function isPrimitive(value) {
 	return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null;
 }

package/dist/core/walker.d.mts

@@ -1,7 +1,20 @@
-import { j as WalkedField } from "../types-BTB73MB8.mjs";
+import { j as WalkedField } from "../types-C2Ay1FEh.mjs";
 import { WalkOptions } from "./walkBuilders.mjs";
 
 //#region src/core/walker.d.ts
+/**
+ * Walk a normalised JSON Schema and produce a {@link WalkedField} tree
+ * that drives every rendering pipeline in schema-components (React,
+ * HTML, streaming HTML).
+ *
+ * Reads standard Draft 2020-12 keywords only — no Zod internals. Handles
+ * `$ref` resolution, `allOf` merging, `nullable` detection from
+ * `anyOf`, and discriminated-union detection from `oneOf` + `const`.
+ * Pass `rootDocument` so cross-document refs resolve correctly and
+ * `diagnostics` to receive per-keyword warnings.
+ *
+ * @group Walkers
+ */
 declare function walk(schema: unknown, options?: WalkOptions): WalkedField;
 //#endregion
 export { walk };

package/dist/core/walker.mjs

@@ -90,6 +90,19 @@ function applyStrictestUnevaluated(merged, branches) {
 	if (strictestProps !== void 0) merged.unevaluatedProperties = strictestProps;
 	if (strictestItems !== void 0) merged.unevaluatedItems = strictestItems;
 }
+/**
+* Walk a normalised JSON Schema and produce a {@link WalkedField} tree
+* that drives every rendering pipeline in schema-components (React,
+* HTML, streaming HTML).
+*
+* Reads standard Draft 2020-12 keywords only — no Zod internals. Handles
+* `$ref` resolution, `allOf` merging, `nullable` detection from
+* `anyOf`, and discriminated-union detection from `oneOf` + `const`.
+* Pass `rootDocument` so cross-document refs resolve correctly and
+* `diagnostics` to receive per-keyword warnings.
+*
+* @group Walkers
+*/
 function walk(schema, options = {}) {
 	const { componentMeta, rootMeta, fieldOverrides, rootDocument, diagnostics, externalResolver } = options;
 	if (typeof schema === "boolean") return walkBooleanSchema(schema);

package/dist/{diagnostics-Cbwak-ZX.d.mts → diagnostics-ByEzkjrA.d.mts}

@@ -15,10 +15,14 @@
 /**
  * Machine-readable codes identifying each class of diagnostic.
  * Stable across releases — consumers can pattern-match on these.
+ *
+ * @group Diagnostics
  */
 type DiagnosticCode = "allof-conflict" | "assumed-draft" | "bare-exclusive-bound" | "conditional-fallback" | "cross-schema-relative-ref-unsupported" | "cyclic-header-ref" | "cyclic-link-ref" | "cyclic-parameter-ref" | "cyclic-path-item-ref" | "dependencies-conflict" | "dependent-required-invalid" | "depth-exceeded" | "discriminator-inconsistent" | "divisible-by-conflict" | "doc-not-object" | "dropped-swagger-feature" | "header-ref-too-deep" | "duplicate-body-parameter" | "duplicate-operation-id" | "dynamic-ref-degraded" | "enum-value-filtered" | "external-ref" | "invalid-const" | "invalid-id-fragment" | "keyword-out-of-draft" | "link-ref-too-deep" | "legacy-dependencies-split" | "legacy-dependencies-split-2019" | "non-json-media-type-fallback" | "parameter-missing-schema" | "parameter-ref-too-deep" | "path-item-ref-too-deep" | "path-webhook-name-collision" | "pattern-invalid" | "prototype-polluting-property" | "recursive-anchor-collision" | "relative-ref-resolved" | "required-non-string" | "schema-allof-incompatible" | "swagger-collection-format-dropped" | "swagger-cyclic-parameter-ref" | "swagger-invalid-file-parameter" | "swagger-malformed-oauth-flow" | "swagger-missing-consumes" | "swagger-missing-host" | "type-mismatch" | "type-negation-fallback" | "unknown-format" | "unknown-json-schema-dialect" | "unknown-keyword" | "unknown-openapi-version" | "unknown-parameter-location" | "unknown-security-scheme-type" | "unresolved-ref" | "unsupported-type" | "zod-codec-nested-output-only" | "zod-codec-output-only" | "zod-preprocess-output-only" | "zod-promise-nested-unwrap";
 /**
  * A single diagnostic emitted during schema processing.
+ *
+ * @group Diagnostics
  */
 interface Diagnostic {
   /** Machine-readable code for programmatic handling. */
@@ -32,10 +36,14 @@ interface Diagnostic {
 }
 /**
  * Callback that receives each diagnostic as it is emitted.
+ *
+ * @group Diagnostics
  */
 type DiagnosticSink = (d: Diagnostic) => void;
 /**
  * Diagnostics configuration threaded through the processing pipeline.
+ *
+ * @group Diagnostics
  */
 interface DiagnosticsOptions {
   /**

package/dist/{errors-DQSIK4n1.d.mts → errors-D8JndRwI.d.mts}

@@ -1,14 +1,17 @@
-import { T as SchemaType } from "./types-BTB73MB8.mjs";
+import { T as SchemaType } from "./types-C2Ay1FEh.mjs";
 
 //#region src/core/errors.d.ts
 /**
- * Base class for all schema-components errors.
- * Catch this to handle any library error uniformly.
+ * Base class for every schema-components error. Catch this to handle
+ * any library error uniformly.
  *
- * Forwards the optional `cause` to the native ES2022 `Error` constructor so
- * `error.cause` is wired up by the runtime and rendered correctly by
- * `util.inspect` ("Caused by: ..."). Subclasses that need a typed `cause`
- * field still get it via the platform's own `Error.cause` getter.
+ * Forwards the optional `cause` to the native ES2022 `Error` constructor
+ * so `error.cause` is wired up by the runtime and rendered correctly by
+ * `util.inspect` ("Caused by: ..."). Subclasses that need a typed
+ * `cause` field still get it via the platform's own `Error.cause`
+ * getter.
+ *
+ * @group Errors
  */
 declare class SchemaError extends Error {
   /** The schema input that caused the error. */
@@ -19,7 +22,12 @@ declare class SchemaError extends Error {
  * 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.
+ * JSON Schema, missing OpenAPI ref, unsupported ref format,
+ * unrepresentable Zod types, conversion bugs, cycles, and duplicate
+ * ids. The `kind` field carries the precise classification — see the
+ * union declaration below.
+ *
+ * @group Errors
  */
 declare class SchemaNormalisationError extends SchemaError {
   readonly kind: "invalid-zod" | "unsupported-schema" | "zod3-unsupported" | "zod-transform-unsupported" | "zod-type-unrepresentable" | "zod-conversion-failed" | "zod-conversion-bug" | "zod-cycle-detected" | "zod-duplicate-id" | "invalid-json-schema" | "openapi-missing-ref" | "openapi-invalid" | "unknown";
@@ -31,9 +39,10 @@ declare class SchemaNormalisationError extends SchemaError {
   constructor(message: string, schema: unknown, kind: SchemaNormalisationError["kind"], zodType?: string, cause?: unknown);
 }
 /**
- * A theme adapter's render function threw during rendering.
+ * A theme adapter's render function threw during rendering. The
+ * original error is preserved on `cause`.
  *
- * The `cause` is the original error from the render function.
+ * @group Errors
  */
 declare class SchemaRenderError extends SchemaError {
   /**
@@ -45,10 +54,11 @@ declare class SchemaRenderError extends SchemaError {
   constructor(message: string, schema: unknown, schemaType: SchemaType, cause: unknown);
 }
 /**
- * A field path couldn't be resolved against the walked schema tree.
+ * A field path could not be resolved against the walked schema tree.
+ * Produced by `<SchemaField>` when the `path` prop does not match any
+ * field in the schema.
  *
- * This is produced by `<SchemaField>` when the `path` prop doesn't
- * match any field in the schema.
+ * @group Errors
  */
 declare class SchemaFieldError extends SchemaError {
   /** The unresolvable dot-separated path. */

package/dist/html/a11y.d.mts

@@ -1,5 +1,5 @@
-import { j as WalkedField } from "../types-BTB73MB8.mjs";
-import { t as AllConstraints } from "../renderer-Ul9taFYp.mjs";
+import { j as WalkedField } from "../types-C2Ay1FEh.mjs";
+import { t as AllConstraints } from "../renderer-OaOz-n6-.mjs";
 import { HtmlAttributes, HtmlNode } from "./html.mjs";
 
 //#region src/html/a11y.d.ts

package/dist/html/html.d.mts

@@ -65,6 +65,7 @@ type AttrValue = string | number | boolean | undefined;
  * arbitrary `data-*` and `aria-*` keys are allowed via index signature.
  */
 type HtmlAttributes = Record<string, AttrValue>;
+/** HTML5 void-element tag names — self-closing, must not carry children. */
 declare const VOID_ELEMENTS: Set<string>;
 /**
  * Build an HTML element node.
@@ -103,7 +104,17 @@ declare function raw(html: string): HtmlRaw;
  * @returns HTML string
  */
 declare function serialize(node: HtmlNode): string;
+/**
+ * Serialise a single {@link HtmlElement} to a string, taking care of
+ * void-element self-closing, attribute serialisation, and recursive
+ * child rendering. Use {@link serialize} for arbitrary nodes.
+ */
 declare function serializeElement(el: HtmlElement): string;
+/**
+ * Serialise an attribute map to the `key="value"` form used inside an
+ * opening tag. `false` / `undefined` values are omitted; `true` renders
+ * as a boolean attribute (just the name).
+ */
 declare function serializeAttributes(attrs: HtmlAttributes): string;
 /**
  * Serialise an HTML node to chunks, yielded at natural element boundaries.

package/dist/html/html.mjs

@@ -1,4 +1,5 @@
 //#region src/html/html.ts
+/** HTML5 void-element tag names — self-closing, must not carry children. */
 const VOID_ELEMENTS = new Set([
 	"area",
 	"base",
@@ -80,6 +81,11 @@ function serialize(node) {
 	if (node.tag === "") return node.children.map((child) => serialize(child)).join("");
 	return serializeElement(node);
 }
+/**
+* Serialise a single {@link HtmlElement} to a string, taking care of
+* void-element self-closing, attribute serialisation, and recursive
+* child rendering. Use {@link serialize} for arbitrary nodes.
+*/
 function serializeElement(el) {
 	const attrs = serializeAttributes(el.attributes);
 	if (VOID_ELEMENTS.has(el.tag)) return `<${el.tag}${attrs}>`;
@@ -87,6 +93,11 @@ function serializeElement(el) {
 	const inner = el.children.map((child) => serialize(child)).join("");
 	return `<${el.tag}${attrs}>${inner}</${el.tag}>`;
 }
+/**
+* Serialise an attribute map to the `key="value"` form used inside an
+* opening tag. `false` / `undefined` values are omitted; `true` renders
+* as a boolean attribute (just the name).
+*/
 function serializeAttributes(attrs) {
 	const parts = [];
 	for (const [key, value] of Object.entries(attrs)) {

package/dist/html/renderToHtml.d.mts

@@ -1,14 +1,22 @@
-import { w as SchemaMeta } from "../types-BTB73MB8.mjs";
-import { o as HtmlResolver } from "../renderer-Ul9taFYp.mjs";
+import { w as SchemaMeta } from "../types-C2Ay1FEh.mjs";
+import { o as HtmlResolver } from "../renderer-OaOz-n6-.mjs";
 
 //#region src/html/renderToHtml.d.ts
 /**
- * Build the recursion-cap sentinel element. The label is interpolated
- * via `h()` + `serialize` so any HTML in `meta.description` (which is
+ * Build the recursion-cap sentinel element used when the renderer
+ * encounters circular schema references. The label is interpolated via
+ * `h()` + `serialize` so any HTML in `meta.description` (which is
  * schema-author content but can equally be sourced from user-supplied
  * JSON Schema input) is escaped — never interpolated into raw markup.
+ *
+ * @group HTML
  */
 declare function recursionSentinelHtml(label: string): string;
+/**
+ * Options accepted by {@link renderToHtml}.
+ *
+ * @group HTML
+ */
 interface RenderToHtmlOptions {
   /** The data value to render. */
   value?: unknown;
@@ -28,11 +36,23 @@ interface RenderToHtmlOptions {
   resolver?: HtmlResolver;
 }
 /**
- * Render a schema to an HTML string.
+ * Render a schema to a semantic HTML string.
+ *
+ * Framework-agnostic alternative to the React rendering pipeline.
+ * Shares the same normalise → walk → render pipeline, but emits
+ * escaped HTML with `sc-` prefixed classes rather than ReactNodes.
+ * Pass `resolver` to plug in a custom HTML renderer.
  *
+ * @group HTML
  * @param schema - Zod schema, JSON Schema, or OpenAPI document
  * @param options - Value, overrides, and resolver options
  * @returns Semantic HTML string with `sc-` prefixed classes
+ * @example
+ * ```tsx
+ * import { renderToHtml } from "schema-components/html/renderToHtml";
+ *
+ * const html = renderToHtml(userSchema, { value: user, readOnly: true });
+ * ```
  */
 declare function renderToHtml(schema: unknown, options?: RenderToHtmlOptions): string;
 //#endregion

package/dist/html/renderToHtml.mjs

@@ -27,20 +27,35 @@ import { defaultHtmlResolver } from "./renderers.mjs";
 *   });
 */
 /**
-* Build the recursion-cap sentinel element. The label is interpolated
-* via `h()` + `serialize` so any HTML in `meta.description` (which is
+* Build the recursion-cap sentinel element used when the renderer
+* encounters circular schema references. The label is interpolated via
+* `h()` + `serialize` so any HTML in `meta.description` (which is
 * schema-author content but can equally be sourced from user-supplied
 * JSON Schema input) is escaped — never interpolated into raw markup.
+*
+* @group HTML
 */
 function recursionSentinelHtml(label) {
 	return serialize(h("fieldset", { class: "sc-recursive" }, h("em", {}, `↻ ${label} (recursive)`)));
 }
 /**
-* Render a schema to an HTML string.
+* Render a schema to a semantic HTML string.
+*
+* Framework-agnostic alternative to the React rendering pipeline.
+* Shares the same normalise → walk → render pipeline, but emits
+* escaped HTML with `sc-` prefixed classes rather than ReactNodes.
+* Pass `resolver` to plug in a custom HTML renderer.
 *
+* @group HTML
 * @param schema - Zod schema, JSON Schema, or OpenAPI document
 * @param options - Value, overrides, and resolver options
 * @returns Semantic HTML string with `sc-` prefixed classes
+* @example
+* ```tsx
+* import { renderToHtml } from "schema-components/html/renderToHtml";
+*
+* const html = renderToHtml(userSchema, { value: user, readOnly: true });
+* ```
 */
 function renderToHtml(schema, options = {}) {
 	const mergedMeta = { ...options.meta };

package/dist/html/renderToHtmlStream.d.mts

@@ -1,7 +1,14 @@
-import { w as SchemaMeta } from "../types-BTB73MB8.mjs";
-import { o as HtmlResolver } from "../renderer-Ul9taFYp.mjs";
+import { w as SchemaMeta } from "../types-C2Ay1FEh.mjs";
+import { o as HtmlResolver } from "../renderer-OaOz-n6-.mjs";
 
 //#region src/html/renderToHtmlStream.d.ts
+/**
+ * Options accepted by the streaming HTML renderers
+ * ({@link renderToHtmlChunks}, {@link renderToHtmlStream},
+ * {@link renderToHtmlReadable}).
+ *
+ * @group HTML
+ */
 interface StreamRenderOptions {
   /** The data value to render. */
   value?: unknown;
@@ -21,19 +28,44 @@ interface StreamRenderOptions {
   resolver?: HtmlResolver;
 }
 /**
- * Render a schema as an iterable of HTML string chunks.
- * Each chunk is a self-contained HTML fragment.
+ * Render a schema as a synchronous iterable of HTML string chunks. Each
+ * chunk is a self-contained HTML fragment, ready to write to a stream
+ * or concatenate into a single string. Use when the host can flush
+ * output incrementally but does not need cooperative scheduling.
+ *
+ * @group HTML
+ * @example
+ * ```tsx
+ * import { renderToHtmlChunks } from "schema-components/html/renderToHtmlStream";
+ *
+ * for (const chunk of renderToHtmlChunks(userSchema, { value: user })) {
+ *   response.write(chunk);
+ * }
+ * ```
  */
 declare function renderToHtmlChunks(schema: unknown, options?: StreamRenderOptions): Iterable<string>;
 /**
- * Render a schema as an async iterable of HTML string chunks.
- * Yields `undefined` between chunks to allow the event loop to process
- * other tasks (cooperative scheduling).
+ * Render a schema as an async iterable of HTML string chunks. Yields
+ * back to the event loop between chunks via a microtask so other tasks
+ * (queued I/O, timers) can run between fragments.
+ *
+ * @group HTML
  */
 declare function renderToHtmlStream(schema: unknown, options?: StreamRenderOptions): AsyncIterable<string>;
 /**
- * Render a schema as a web `ReadableStream<string>`.
- * Uses the async rendering pipeline internally.
+ * Render a schema as a web `ReadableStream<string>` so it can be piped
+ * into a `Response` body. Pulls chunks lazily from the synchronous
+ * chunk iterator under the hood.
+ *
+ * @group HTML
+ * @example
+ * ```tsx
+ * import { renderToHtmlReadable } from "schema-components/html/renderToHtmlStream";
+ *
+ * return new Response(renderToHtmlReadable(userSchema, { value: user }), {
+ *   headers: { "content-type": "text/html" },
+ * });
+ * ```
  */
 declare function renderToHtmlReadable(schema: unknown, options?: StreamRenderOptions): ReadableStream<string>;
 //#endregion

package/dist/html/renderToHtmlStream.mjs

@@ -19,17 +19,31 @@ import { streamField } from "./streamRenderers.mjs";
 * - `renderToHtmlReadable(schema, options)` → web `ReadableStream<string>`
 */
 /**
-* Render a schema as an iterable of HTML string chunks.
-* Each chunk is a self-contained HTML fragment.
+* Render a schema as a synchronous iterable of HTML string chunks. Each
+* chunk is a self-contained HTML fragment, ready to write to a stream
+* or concatenate into a single string. Use when the host can flush
+* output incrementally but does not need cooperative scheduling.
+*
+* @group HTML
+* @example
+* ```tsx
+* import { renderToHtmlChunks } from "schema-components/html/renderToHtmlStream";
+*
+* for (const chunk of renderToHtmlChunks(userSchema, { value: user })) {
+*   response.write(chunk);
+* }
+* ```
 */
 function renderToHtmlChunks(schema, options = {}) {
 	const { tree, resolver } = prepareTree(schema, options);
 	return streamField(tree, options.value ?? tree.defaultValue, mergeHtmlResolvers(resolver, defaultHtmlResolver), "", resolver);
 }
 /**
-* Render a schema as an async iterable of HTML string chunks.
-* Yields `undefined` between chunks to allow the event loop to process
-* other tasks (cooperative scheduling).
+* Render a schema as an async iterable of HTML string chunks. Yields
+* back to the event loop between chunks via a microtask so other tasks
+* (queued I/O, timers) can run between fragments.
+*
+* @group HTML
 */
 async function* renderToHtmlStream(schema, options = {}) {
 	const { tree, resolver } = prepareTree(schema, options);
@@ -41,8 +55,19 @@ async function* renderToHtmlStream(schema, options = {}) {
 	}
 }
 /**
-* Render a schema as a web `ReadableStream<string>`.
-* Uses the async rendering pipeline internally.
+* Render a schema as a web `ReadableStream<string>` so it can be piped
+* into a `Response` body. Pulls chunks lazily from the synchronous
+* chunk iterator under the hood.
+*
+* @group HTML
+* @example
+* ```tsx
+* import { renderToHtmlReadable } from "schema-components/html/renderToHtmlStream";
+*
+* return new Response(renderToHtmlReadable(userSchema, { value: user }), {
+*   headers: { "content-type": "text/html" },
+* });
+* ```
 */
 function renderToHtmlReadable(schema, options = {}) {
 	const { tree, resolver } = prepareTree(schema, options);

package/dist/html/renderers.d.mts

@@ -1,5 +1,5 @@
 import { dateInputType } from "../core/formats.mjs";
-import { o as HtmlResolver } from "../renderer-Ul9taFYp.mjs";
+import { o as HtmlResolver } from "../renderer-OaOz-n6-.mjs";
 import { matchUnionOption } from "../core/unionMatch.mjs";
 
 //#region src/html/renderers.d.ts
@@ -34,6 +34,12 @@ declare function panelId(path: string): string;
  * `panelId` above — see its comment.
  */
 declare function tabId(path: string, i: number): string;
+/**
+ * Default HTML resolver used by `renderToHtml` and the streaming
+ * renderers when the consumer does not pass a custom resolver. Maps
+ * every `WalkedField` variant to a semantic HTML renderer built on the
+ * `h()` element builder.
+ */
 declare const defaultHtmlResolver: HtmlResolver;
 //#endregion
 export { dateInputType, defaultHtmlResolver, fieldId, matchUnionOption, panelId, tabId };

package/dist/html/renderers.mjs

@@ -428,6 +428,12 @@ function renderNeverHtml(props) {
 		...ariaReadonlyAttrs()
 	}, h("em", {}, "never matches")));
 }
+/**
+* Default HTML resolver used by `renderToHtml` and the streaming
+* renderers when the consumer does not pass a custom resolver. Maps
+* every `WalkedField` variant to a semantic HTML renderer built on the
+* `h()` element builder.
+*/
 const defaultHtmlResolver = {
 	string: renderStringHtml,
 	number: renderNumberHtml,