schema-components 1.28.2 → 2.0.0

package/README.md

@@ -298,14 +298,20 @@ import { shadcnResolver } from "schema-components/themes/shadcn";
 ### MUI
 
 ```tsx
-import { registerMuiComponents } from "schema-components/themes/mui";
-import { shadcnResolver } from "schema-components/themes/shadcn";
-
-// Register MUI components at app startup
-registerMuiComponents();
+import { SchemaProvider } from "schema-components/react/SchemaComponent";
+import { createMuiResolver } from "schema-components/themes/mui";
+import TextField from "@mui/material/TextField";
+import Checkbox from "@mui/material/Checkbox";
+import Typography from "@mui/material/Typography";
+import Box from "@mui/material/Box";
+import MenuItem from "@mui/material/MenuItem";
+import FormControlLabel from "@mui/material/FormControlLabel";
+
+const muiResolver = createMuiResolver({
+  TextField, Checkbox, Typography, Box, MenuItem, FormControlLabel,
+});
 
-// Use via SchemaProvider
-<SchemaProvider resolver={shadcnResolver}>
+<SchemaProvider resolver={muiResolver}>
   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
 </SchemaProvider>
 ```
@@ -313,12 +319,17 @@ registerMuiComponents();
 ### Mantine
 
 ```tsx
-import { registerMantineComponents } from "schema-components/themes/mantine";
-import { shadcnResolver } from "schema-components/themes/shadcn";
+import { SchemaProvider } from "schema-components/react/SchemaComponent";
+import { createMantineResolver } from "schema-components/themes/mantine";
+import {
+  TextInput, NumberInput, Switch, Select, Fieldset, Text,
+} from "@mantine/core";
 
-registerMantineComponents();
+const mantineResolver = createMantineResolver({
+  TextInput, NumberInput, Switch, Select, Fieldset, Text,
+});
 
-<SchemaProvider resolver={shadcnResolver}>
+<SchemaProvider resolver={mantineResolver}>
   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
 </SchemaProvider>
 ```
@@ -326,12 +337,23 @@ registerMantineComponents();
 ### Radix Themes
 
 ```tsx
-import { registerRadixComponents } from "schema-components/themes/radix";
-import { shadcnResolver } from "schema-components/themes/shadcn";
-
-registerRadixComponents();
+import { SchemaProvider } from "schema-components/react/SchemaComponent";
+import { createRadixResolver } from "schema-components/themes/radix";
+import { Box, Checkbox, Flex, Select, Text, TextField } from "@radix-ui/themes";
+
+const radixResolver = createRadixResolver({
+  Box,
+  Checkbox,
+  Flex,
+  SelectRoot: Select.Root,
+  SelectTrigger: Select.Trigger,
+  SelectContent: Select.Content,
+  SelectItem: Select.Item,
+  Text,
+  TextField: TextField.Root,
+});
 
-<SchemaProvider resolver={shadcnResolver}>
+<SchemaProvider resolver={radixResolver}>
   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
 </SchemaProvider>
 ```

package/dist/core/adapter.d.mts

@@ -1,3 +1,213 @@
-import { m as JsonObject, w as SchemaMeta } from "../types-BTB73MB8.mjs";
-import { a as SchemaKind, c as extractRootMetaFromJson, i as SchemaIoSide, l as isCodecSchema, n as NormalisedSchema, o as __CLASSIFIER_RULES_FOR_TEST, r as SchemaInput, s as detectSchemaKind, t as NormaliseOptions, u as normaliseSchema } from "../adapter-DqlAnZ_w.mjs";
-export { JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaIoSide, SchemaKind, SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, extractRootMetaFromJson, isCodecSchema, normaliseSchema };
+import { m as JsonObject, w as SchemaMeta } from "../types-BrYbjC7_.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
+
+//#region src/core/adapter.d.ts
+/**
+ * Classification produced by {@link detectSchemaKind} when inspecting a
+ * runtime schema input.
+ *
+ * @group Adapter
+ */
+type SchemaKind = "zod4" | "zod3" | "jsonSchema" | "openapi" | "unsupported-schema-lib";
+/**
+ * Classify a runtime schema input by structural markers — Zod 4, Zod 3,
+ * OpenAPI document, plain JSON Schema, or an unsupported third-party
+ * schema library.
+ *
+ * - `zod4` — has a `_zod` marker (further validation that `_zod.def` is a
+ *   non-null object happens inside `normaliseZod4`).
+ * - `zod3` — has `_def` and no `_zod`. The `typeName` field is no longer
+ *   required: any `_def` without `_zod` is treated as a probable Zod 3
+ *   schema. Third-party libraries that expose `_def` without `_zod` are
+ *   nearly always Zod 3 forks; surfacing the migration message is the
+ *   correct response.
+ * - `openapi` — has `openapi` or `swagger` at the root.
+ * - `unsupported-schema-lib` — has `parse` and `safeParse` callables but
+ *   no `_zod` and no `_def` marker. This catches Standard Schema
+ *   implementations (valibot, arktype, etc.) that would otherwise flow
+ *   through as "malformed JSON Schema".
+ * - `jsonSchema` — fallback for anything that does not match the above.
+ *
+ * @group Adapter
+ */
+declare function detectSchemaKind(input: unknown): SchemaKind;
+/**
+ * Wraps z.toJSONSchema() for a runtime-validated Zod schema.
+ *
+ * The _zod guard in normaliseZod4 has confirmed this is a valid Zod schema,
+ * but TypeScript cannot represent "has _zod.def" as the $ZodType parameter
+ * that z.toJSONSchema expects. This is the library boundary equivalent of
+ * object → Record<string, unknown> — the type mismatch is genuinely unavoidable.
+ *
+ * # Options
+ *
+ * `z.toJSONSchema` is invoked with an explicit options object rather than
+ * Zod's defaults so the conversion contract is pinned and stable:
+ *
+ * - `target: "draft-2020-12"` — matches the walker's draft target.
+ * - `unrepresentable: "throw"` — keeps the unrepresentable-type rules in
+ *   the classifier table firing instead of silently emitting `{}`.
+ * - `cycles: "ref"` — converts cyclic graphs into $ref pairs rather than
+ *   throwing. Cycles in user schemas surface through the walker's $ref
+ *   resolution rather than the adapter.
+ * - `io` — selects which side of every transform / pipe / codec is
+ *   converted. Defaults to `"output"` (the OUTPUT side); pass `"input"`
+ *   to render the INPUT side instead. The input side is invisible to
+ *   the converted schema when `io: "output"` is in force, even though
+ *   `safeParse` on the same Zod schema consumes the input shape. For
+ *   transforms this divergence is fatal and the call throws via
+ *   `Transforms cannot be represented`; for `z.codec(...)` the call
+ *   succeeds but only the selected side is rendered. Consumers receive
+ *   a `zod-codec-output-only` diagnostic in the codec case so the
+ *   asymmetry is visible — see `screenPreConversion`.
+ *
+ * # Error classification
+ *
+ * Any exception thrown by z.toJSONSchema is classified into a
+ * SchemaNormalisationError so the caller does not have to re-parse error
+ * message strings. The classification covers:
+ *
+ * - Nested Zod 3 schemas inside a Zod 4 tree → zod3-unsupported.
+ *   Detected structurally (presence of `_def.typeName` markers anywhere
+ *   in the schema tree) so the check works across V8, JavaScriptCore,
+ *   and SpiderMonkey, none of which agree on the wording of
+ *   "Cannot read properties of undefined".
+ * - Transforms → zod-transform-unsupported. This also catches `z.codec(…)`
+ *   because Zod implements codecs as a pipe + transform internally, so
+ * they trip the same processor when round-tripping is forced. (Plain
+ *   `z.toJSONSchema(codec)` itself does NOT throw because Zod picks one
+ *   side of the codec; the static rejection in `typeInference.ts` is the
+ *   compile-time guard.)
+ * - Dynamic catch values whose handler throws → zod-type-unrepresentable
+ *   with zodType "dynamic-catch".
+ * - Unrepresentable types — bigint, date, map, set, symbol, function, custom,
+ *   undefined, void, NaN, and the literal-only forms `z.literal(undefined)`
+ *   ("undefined-literal") and `z.literal(<bigint>)` ("bigint-literal") →
+ *   zod-type-unrepresentable.
+ * - The catch-all "Non-representable type encountered: <type>" fallback Zod
+ *   emits for any new schema kind without a registered processor →
+ *   zod-type-unrepresentable with zodType set to the offending def.type.
+ * - Cycle detected (`cycles: "throw"`) → zod-cycle-detected.
+ * - Duplicate schema id → zod-duplicate-id.
+ * - "Unprocessed schema. This is a bug in Zod." → zod-conversion-bug.
+ * - "Error converting schema to JSON." → zod-conversion-failed (explicit
+ *   classification rather than the generic fallback so the contract test
+ *   protects the prefix from drift).
+ * - Anything else → zod-conversion-failed.
+ *
+ * The original error is preserved on each classified error via the `cause`
+ * field so consumers can still inspect the Zod stack trace.
+ */
+/**
+ * Direction of the Zod transform / pipe / codec that
+ * {@link normaliseSchema} should surface to the renderer.
+ *
+ * - `"output"` (default) — the server-facing side of every transform,
+ *   matching `z.toJSONSchema`'s default and the historic adapter
+ *   behaviour.
+ * - `"input"` — the client-facing side; flips a `z.codec(...)` chain
+ *   so consumers can render its input shape.
+ *
+ * @group Adapter
+ */
+type SchemaIoSide = "input" | "output";
+/**
+ * True when `value` is a Zod schema implemented as a codec
+ * (`z.codec(...)`). Detection looks for the `$ZodCodec` marker on the
+ * schema's `_zod.traits` Set — the same structural check used by Zod
+ * itself in `to-json-schema.ts`'s `isTransforming` helper.
+ *
+ * Promoted from a duplicated local helper in `react/SchemaComponent.tsx`
+ * so the validation boundary inside `runValidation` can branch on
+ * codec-vs-not-codec without re-implementing the trait check. The
+ * shared helper anchors a single source of truth for codec detection:
+ * any future change to Zod's trait naming flows through here, not
+ * through two parallel copies.
+ *
+ * Returns `false` for non-objects, plain JSON Schema inputs, OpenAPI
+ * documents, or Zod schemas of any other kind. This is structural
+ * rather than nominal — a Zod 4 codec produced by any path that ends
+ * up tagging `_zod.traits` with `$ZodCodec` is recognised, including
+ * schemas wrapped by user-defined helpers.
+ */
+declare function isCodecSchema(value: unknown): boolean;
+/**
+ * Exposed for unit testing — lets the contract test enumerate every rule's
+ * `prefix` value and assert mutual non-prefixing.
+ */
+declare const __CLASSIFIER_RULES_FOR_TEST: readonly {
+  readonly prefix: string;
+}[];
+/**
+ * Result of {@link normaliseSchema}. Carries the canonical Draft 2020-12
+ * JSON Schema the walker consumes, the optional original Zod schema
+ * (used for validation), and the resolved root document so cross-document
+ * `$ref`s can be dereferenced downstream.
+ *
+ * @group Adapter
+ */
+interface NormalisedSchema {
+  /** JSON Schema object — the authoritative schema for rendering. */
+  jsonSchema: JsonObject;
+  /** Original Zod schema, if input was Zod. Used for validation. */
+  zodSchema?: unknown;
+  /** Root-level metadata. */
+  rootMeta: SchemaMeta | undefined;
+  /** The root document for $ref resolution. */
+  rootDocument: JsonObject;
+}
+/**
+ * Options accepted by {@link normaliseSchema}.
+ *
+ * @group Adapter
+ */
+interface NormaliseOptions {
+  /** Diagnostics channel for surfacing silent fallbacks. */
+  diagnostics?: DiagnosticsOptions;
+  /**
+   * Side of every transform / pipe / codec to render. Defaults to
+   * `"output"`, matching `z.toJSONSchema`'s default and the
+   * historic behaviour of the adapter. Passing `"input"` flips the
+   * conversion so consumers rendering the input shape of a
+   * `z.codec(...)` chain receive that side instead of the output
+   * side. Only the Zod 4 branch consults this option — JSON Schema
+   * and OpenAPI inputs are already a single canonical shape.
+   */
+  io?: SchemaIoSide;
+}
+/**
+ * Normalise any supported schema input — Zod 4 schema, plain JSON
+ * Schema (any draft), Swagger 2.0, OpenAPI 3.0 or 3.1 document — into
+ * a canonical Draft 2020-12 {@link NormalisedSchema} the walker can
+ * consume.
+ *
+ * Dispatches on {@link detectSchemaKind}, applies the appropriate
+ * version normaliser, and returns the JSON Schema alongside the
+ * original Zod schema (for validation) and the resolved root document
+ * (for cross-document `$ref` resolution). Throws
+ * `SchemaNormalisationError` for unsupported inputs (Zod 3, valibot,
+ * arktype, codec or other unrepresentable Zod types).
+ *
+ * @group Adapter
+ */
+declare function normaliseSchema(input: unknown, ref?: string, options?: NormaliseOptions): NormalisedSchema;
+/**
+ * Surface root-level metadata from the JSON Schema into the `rootMeta`
+ * shape consumed by the walker. Pulls `readOnly`, `writeOnly`,
+ * `description`, `title`, `deprecated`, `examples`, and `default`
+ * directly from the schema root.
+ *
+ * `examples` is forwarded only when present as an array (per JSON Schema
+ * Draft 2020-12 — Draft 04's `example` singular is normalised upstream).
+ * `default` is forwarded for any value the schema declares (any JSON
+ * value, including `null` and `false`); the presence check uses `in`
+ * so a literal `false` or `null` default is preserved.
+ *
+ * `examples` and `default` ride on the `[key: string]: unknown` index
+ * signature of {@link SchemaMeta}. They are not declared as named fields
+ * on `SchemaMeta` because that type lives in `types.ts` and is shared
+ * with the walker; the index signature is the agreed extension point.
+ */
+declare function extractRootMetaFromJson(jsonSchema: JsonObject): SchemaMeta | undefined;
+//#endregion
+export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaIoSide, SchemaKind, type SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, extractRootMetaFromJson, isCodecSchema, normaliseSchema };

package/dist/core/adapter.mjs

@@ -4,7 +4,7 @@ import { SchemaNormalisationError } from "./errors.mjs";
 import { appendPointer, emitDiagnostic } from "./diagnostics.mjs";
 import { dereference } from "./ref.mjs";
 import { detectOpenApiVersion, inferJsonSchemaDraftWithReason, isSwagger2, matchJsonSchemaDraftUri } from "./version.mjs";
-import { a as normaliseJsonSchema$1, o as normaliseOpenApiSchemas } from "../normalise-Db1xaxgx.mjs";
+import { a as normaliseJsonSchema$1, o as normaliseOpenApiSchemas } from "../normalise-DB-Xtjmn.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**
@@ -20,7 +20,9 @@ import { z } from "zod";
 */
 const schemaCache = /* @__PURE__ */ new WeakMap();
 /**
-* Classify the input schema by its structural markers.
+* Classify a runtime schema input by structural markers — Zod 4, Zod 3,
+* OpenAPI document, plain JSON Schema, or an unsupported third-party
+* schema library.
 *
 * - `zod4` — has a `_zod` marker (further validation that `_zod.def` is a
 *   non-null object happens inside `normaliseZod4`).
@@ -35,6 +37,8 @@ const schemaCache = /* @__PURE__ */ new WeakMap();
 *   implementations (valibot, arktype, etc.) that would otherwise flow
 *   through as "malformed JSON Schema".
 * - `jsonSchema` — fallback for anything that does not match the above.
+*
+* @group Adapter
 */
 function detectSchemaKind(input) {
 	if (hasProperty(input, "_zod")) return "zod4";
@@ -624,6 +628,21 @@ function classifyZodConversionError(err, schema) {
 * `prefix` value and assert mutual non-prefixing.
 */
 const __CLASSIFIER_RULES_FOR_TEST = CLASSIFIER_RULES;
+/**
+* Normalise any supported schema input — Zod 4 schema, plain JSON
+* Schema (any draft), Swagger 2.0, OpenAPI 3.0 or 3.1 document — into
+* a canonical Draft 2020-12 {@link NormalisedSchema} the walker can
+* consume.
+*
+* Dispatches on {@link detectSchemaKind}, applies the appropriate
+* version normaliser, and returns the JSON Schema alongside the
+* original Zod schema (for validation) and the resolved root document
+* (for cross-document `$ref` resolution). Throws
+* `SchemaNormalisationError` for unsupported inputs (Zod 3, valibot,
+* arktype, codec or other unrepresentable Zod types).
+*
+* @group Adapter
+*/
 function normaliseSchema(input, ref, options) {
 	const usesDiagnostics = options?.diagnostics !== void 0;
 	const nonDefaultIo = options?.io !== void 0 && options.io !== "output";

package/dist/core/constraintHint.d.mts

@@ -0,0 +1,15 @@
+import { AllConstraints } from "./renderer.mjs";
+
+//#region src/core/constraintHint.d.ts
+/**
+ * Build a human-readable constraint description string.
+ *
+ * Returns `undefined` when no constraint worth announcing is present.
+ * Pattern hints are suppressed when a `format` is set because the
+ * format already implies the pattern and the resulting copy would be
+ * misleading ("Must match pattern" alongside a `format: "email"` field
+ * would read as if the schema required a non-email regex).
+ */
+declare function constraintHint(c: AllConstraints): string | undefined;
+//#endregion
+export { constraintHint };

package/dist/core/constraintHint.mjs

@@ -0,0 +1,24 @@
+//#region src/core/constraintHint.ts
+/**
+* Build a human-readable constraint description string.
+*
+* Returns `undefined` when no constraint worth announcing is present.
+* Pattern hints are suppressed when a `format` is set because the
+* format already implies the pattern and the resulting copy would be
+* misleading ("Must match pattern" alongside a `format: "email"` field
+* would read as if the schema required a non-email regex).
+*/
+function constraintHint(c) {
+	const parts = [];
+	if (c.minLength !== void 0) parts.push(`Minimum ${String(c.minLength)} characters`);
+	if (c.maxLength !== void 0) parts.push(`Maximum ${String(c.maxLength)} characters`);
+	if (c.minimum !== void 0) parts.push(`Minimum ${String(c.minimum)}`);
+	if (c.maximum !== void 0) parts.push(`Maximum ${String(c.maximum)}`);
+	if (c.pattern !== void 0 && c.format === void 0) parts.push("Must match pattern");
+	if (c.minItems !== void 0) parts.push(`Minimum ${String(c.minItems)} items`);
+	if (c.maxItems !== void 0) parts.push(`Maximum ${String(c.maxItems)} items`);
+	if (parts.length === 0) return void 0;
+	return parts.join(". ");
+}
+//#endregion
+export { constraintHint };

package/dist/core/constraints.d.mts

@@ -1,11 +1,43 @@
-import { E as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-BTB73MB8.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
+import { E as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-BrYbjC7_.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
 
 //#region src/core/constraints.d.ts
+/**
+ * Read the JSON Schema string constraint keywords (`minLength`,
+ * `maxLength`, `pattern`, `format`, `contentEncoding`,
+ * `contentMediaType`) from a schema node and return them in the
+ * `StringConstraints` shape consumed by string field renderers.
+ * Emits an `unknown-format` diagnostic for unrecognised `format`
+ * values.
+ */
 declare function extractStringConstraints(schema: Record<string, unknown>, diagnostics?: DiagnosticsOptions, pointer?: string): StringConstraints;
+/**
+ * Read the JSON Schema number constraint keywords (`minimum`,
+ * `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`)
+ * from a schema node and return them in the `NumberConstraints` shape
+ * consumed by number field renderers.
+ */
 declare function extractNumberConstraints(schema: Record<string, unknown>): NumberConstraints;
+/**
+ * Read the JSON Schema array constraint keywords (`minItems`,
+ * `maxItems`, `uniqueItems`, `minContains`, `maxContains`) from a
+ * schema node and return them in the `ArrayConstraints` shape. The
+ * `contains` and `unevaluatedItems` sub-schemas are walked separately
+ * and surfaced on the `ArrayField` / `TupleField` directly rather
+ * than as raw constraints.
+ */
 declare function extractArrayConstraints(schema: Record<string, unknown>): ArrayConstraints;
+/**
+ * Read the JSON Schema object constraint keywords (`minProperties`,
+ * `maxProperties`) from a schema node and return them in the
+ * `ObjectConstraints` shape.
+ */
 declare function extractObjectConstraints(schema: Record<string, unknown>): ObjectConstraints;
+/**
+ * Read the JSON Schema file constraints from a schema node — currently
+ * just `contentMediaType`, which surfaces as the single-entry
+ * `mimeTypes` array on `FileConstraints`.
+ */
 declare function extractFileConstraints(schema: Record<string, unknown>): FileConstraints;
 /**
  * Return a copy of the schema with constraint keywords that don't apply

package/dist/core/constraints.mjs

@@ -9,6 +9,14 @@ function getNumber(obj, key) {
 	const value = obj[key];
 	return typeof value === "number" ? value : void 0;
 }
+/**
+* Read the JSON Schema string constraint keywords (`minLength`,
+* `maxLength`, `pattern`, `format`, `contentEncoding`,
+* `contentMediaType`) from a schema node and return them in the
+* `StringConstraints` shape consumed by string field renderers.
+* Emits an `unknown-format` diagnostic for unrecognised `format`
+* values.
+*/
 function extractStringConstraints(schema, diagnostics, pointer = "") {
 	const c = {};
 	const minLength = getNumber(schema, "minLength");
@@ -22,7 +30,7 @@ function extractStringConstraints(schema, diagnostics, pointer = "") {
 		c.format = format;
 		const pattern = FORMAT_PATTERNS[format];
 		if (pattern !== void 0) c.formatPattern = pattern;
-		else if (format !== "binary") emitDiagnostic(diagnostics, {
+		else if (format !== "binary" && format !== "password") emitDiagnostic(diagnostics, {
 			code: "unknown-format",
 			message: `Unknown format: ${format}`,
 			pointer,
@@ -35,6 +43,12 @@ function extractStringConstraints(schema, diagnostics, pointer = "") {
 	if (contentMediaType !== void 0) c.contentMediaType = contentMediaType;
 	return c;
 }
+/**
+* Read the JSON Schema number constraint keywords (`minimum`,
+* `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`)
+* from a schema node and return them in the `NumberConstraints` shape
+* consumed by number field renderers.
+*/
 function extractNumberConstraints(schema) {
 	const c = {};
 	const minimum = getNumber(schema, "minimum");
@@ -49,6 +63,14 @@ function extractNumberConstraints(schema) {
 	if (multipleOf !== void 0) c.multipleOf = multipleOf;
 	return c;
 }
+/**
+* Read the JSON Schema array constraint keywords (`minItems`,
+* `maxItems`, `uniqueItems`, `minContains`, `maxContains`) from a
+* schema node and return them in the `ArrayConstraints` shape. The
+* `contains` and `unevaluatedItems` sub-schemas are walked separately
+* and surfaced on the `ArrayField` / `TupleField` directly rather
+* than as raw constraints.
+*/
 function extractArrayConstraints(schema) {
 	const c = {};
 	const minItems = getNumber(schema, "minItems");
@@ -62,6 +84,11 @@ function extractArrayConstraints(schema) {
 	if (maxContains !== void 0) c.maxContains = maxContains;
 	return c;
 }
+/**
+* Read the JSON Schema object constraint keywords (`minProperties`,
+* `maxProperties`) from a schema node and return them in the
+* `ObjectConstraints` shape.
+*/
 function extractObjectConstraints(schema) {
 	const c = {};
 	const minProperties = getNumber(schema, "minProperties");
@@ -70,6 +97,11 @@ function extractObjectConstraints(schema) {
 	if (maxProperties !== void 0) c.maxProperties = maxProperties;
 	return c;
 }
+/**
+* Read the JSON Schema file constraints from a schema node — currently
+* just `contentMediaType`, which surfaces as the single-entry
+* `mimeTypes` array on `FileConstraints`.
+*/
 function extractFileConstraints(schema) {
 	const c = {};
 	const contentMediaType = getString(schema, "contentMediaType");

package/dist/core/cssClasses.d.mts

@@ -47,6 +47,7 @@ declare const SC_CLASSES: {
   readonly never: "sc-never";
   readonly recursive: "sc-recursive";
 };
+/** Stable string-literal key into the canonical {@link SC_CLASSES} map. */
 type ScClassKey = keyof typeof SC_CLASSES;
 //#endregion
 export { ELLIPSIS, EM_DASH, SC_CLASSES, SC_ID_PREFIX, ScClassKey };

package/dist/core/diagnostics.d.mts

@@ -1,2 +1,2 @@
-import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-Cbwak-ZX.mjs";
+import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-BTrm3O6J.mjs";
 export { Diagnostic, DiagnosticCode, DiagnosticSink, DiagnosticsOptions, appendPointer, emitDiagnostic };

package/dist/core/errors.d.mts

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

package/dist/core/errors.mjs

@@ -1,12 +1,15 @@
 //#region src/core/errors.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
 */
 var SchemaError = class extends Error {
 	/** The schema input that caused the error. */
@@ -21,7 +24,12 @@ var SchemaError = class 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
 */
 var SchemaNormalisationError = class extends SchemaError {
 	kind;
@@ -38,9 +46,10 @@ var SchemaNormalisationError = class extends SchemaError {
 	}
 };
 /**
-* 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
 */
 var SchemaRenderError = class extends SchemaError {
 	/**
@@ -56,10 +65,11 @@ var SchemaRenderError = class extends SchemaError {
 	}
 };
 /**
-* 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
 */
 var SchemaFieldError = class extends SchemaError {
 	/** The unresolvable dot-separated path. */

package/dist/core/fieldOrder.d.mts

@@ -1,4 +1,4 @@
-import { j as WalkedField } from "../types-BTB73MB8.mjs";
+import { j as WalkedField } from "../types-BrYbjC7_.mjs";
 
 //#region src/core/fieldOrder.d.ts
 /**

package/dist/core/formats.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
 
 //#region src/core/formats.d.ts
 /**
@@ -52,6 +52,12 @@ type FormatValidator = RegExp | ((value: string) => boolean);
  * directly. Used by the URI safety helpers for mailto address checks.
  */
 declare const EMAIL_FORMAT_PATTERN: RegExp;
+/**
+ * Map of recognised JSON Schema string `format` values to RegExp
+ * patterns. Consumed by `extractStringConstraints` to derive a
+ * client-side `formatPattern` for renderers, and by
+ * {@link validateFormat} for runtime checks.
+ */
 declare const FORMAT_PATTERNS: Readonly<Record<string, RegExp>>;
 /**
  * Validate a string value against format constraints.

package/dist/core/formats.mjs

@@ -51,6 +51,12 @@ function dateInputType(format) {
 * directly. Used by the URI safety helpers for mailto address checks.
 */
 const EMAIL_FORMAT_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+* Map of recognised JSON Schema string `format` values to RegExp
+* patterns. Consumed by `extractStringConstraints` to derive a
+* client-side `formatPattern` for renderers, and by
+* {@link validateFormat} for runtime checks.
+*/
 const FORMAT_PATTERNS = {
 	uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
 	email: EMAIL_FORMAT_PATTERN,