schema-components 1.28.2 → 2.0.0

package/dist/core/swagger2.mjs

@@ -1,2 +1,2 @@
-import { c as normaliseSwagger2Document } from "../normalise-Db1xaxgx.mjs";
+import { c as normaliseSwagger2Document } from "../normalise-DB-Xtjmn.mjs";
 export { normaliseSwagger2Document };

package/dist/core/typeInference.d.mts

@@ -1,5 +1,5 @@
-import { d as FieldOverrides, u as FieldOverride } from "../types-BTB73MB8.mjs";
-import { i as MaxRefDepth } from "../limits-DJhgx5Ay.mjs";
+import { d as FieldOverrides, u as FieldOverride } from "../types-BrYbjC7_.mjs";
+import { i as MaxRefDepth } from "../limits-x4OiyJxh.mjs";
 import { z } from "zod";
 
 //#region src/core/typeInference.d.ts
@@ -790,7 +790,7 @@ type RequestBodySchemaOf<Op, ContentType extends string = DEFAULT_OPENAPI_CONTEN
  * Without this fallback, querying a concrete status against a document
  * that declares only `"2XX"` or `"default"` would silently produce
  * `unknown`. The runtime resolver applies the same fall-through
- * behaviour in `resolveResponseFromParsed`.
+ * behaviour in `resolveResponse`.
  */
 type ResponseSchemaOf<Op, Status extends string, ContentType extends string = DEFAULT_OPENAPI_CONTENT_TYPE> = Op extends {
   responses: infer Rs extends Record<string, unknown>;

package/dist/core/types.d.mts

@@ -1,2 +1,2 @@
-import { A as UnknownField, B as isNeverField, C as RecordField, D as StringField, E as StringConstraints, F as isDiscriminatedUnionField, G as isStringField, H as isNumberField, I as isEnumField, J as isUnknownField, K as isTupleField, L as isFileField, M as isArrayField, N as isBooleanField, O as TupleField, P as isConditionalField, R as isLiteralField, S as ObjectField, T as SchemaType, U as isObjectField, V as isNullField, W as isRecordField, Y as resolveEditability, _ as NeverField, a as DiscriminatedUnionField, b as NumberField, c as FieldBase, d as FieldOverrides, f as FileConstraints, g as NegationField, h as LiteralField, i as ConditionalField, j as WalkedField, k as UnionField, l as FieldConstraints, m as JsonObject, n as ArrayField, o as Editability, p as FileField, q as isUnionField, r as BooleanField, s as EnumField, t as ArrayConstraints, u as FieldOverride, v as NullField, w as SchemaMeta, x as ObjectConstraints, y as NumberConstraints, z as isNegationField } from "../types-BTB73MB8.mjs";
+import { A as UnknownField, B as isNeverField, C as RecordField, D as StringField, E as StringConstraints, F as isDiscriminatedUnionField, G as isStringField, H as isNumberField, I as isEnumField, J as isUnknownField, K as isTupleField, L as isFileField, M as isArrayField, N as isBooleanField, O as TupleField, P as isConditionalField, R as isLiteralField, S as ObjectField, T as SchemaType, U as isObjectField, V as isNullField, W as isRecordField, Y as resolveEditability, _ as NeverField, a as DiscriminatedUnionField, b as NumberField, c as FieldBase, d as FieldOverrides, f as FileConstraints, g as NegationField, h as LiteralField, i as ConditionalField, j as WalkedField, k as UnionField, l as FieldConstraints, m as JsonObject, n as ArrayField, o as Editability, p as FileField, q as isUnionField, r as BooleanField, s as EnumField, t as ArrayConstraints, u as FieldOverride, v as NullField, w as SchemaMeta, x as ObjectConstraints, y as NumberConstraints, z as isNegationField } from "../types-BrYbjC7_.mjs";
 export { ArrayConstraints, ArrayField, BooleanField, ConditionalField, DiscriminatedUnionField, Editability, EnumField, FieldBase, FieldConstraints, FieldOverride, FieldOverrides, FileConstraints, FileField, JsonObject, LiteralField, NegationField, NeverField, NullField, NumberConstraints, NumberField, ObjectConstraints, ObjectField, RecordField, SchemaMeta, SchemaType, StringConstraints, StringField, TupleField, UnionField, UnknownField, WalkedField, isArrayField, isBooleanField, isConditionalField, isDiscriminatedUnionField, isEnumField, isFileField, isLiteralField, isNegationField, isNeverField, isNullField, isNumberField, isObjectField, isRecordField, isStringField, isTupleField, isUnionField, isUnknownField, resolveEditability };

package/dist/core/types.mjs

@@ -38,54 +38,71 @@ function resolveEditability(propertyMeta, componentMeta, rootMeta) {
 function isField(field, t) {
 	return field.type === t;
 }
+/** Type guard: narrows a `WalkedField` to its `string` variant. */
 function isStringField(field) {
 	return isField(field, "string");
 }
+/** Type guard: narrows a `WalkedField` to its `number` variant. */
 function isNumberField(field) {
 	return isField(field, "number");
 }
+/** Type guard: narrows a `WalkedField` to its `boolean` variant. */
 function isBooleanField(field) {
 	return isField(field, "boolean");
 }
+/** Type guard: narrows a `WalkedField` to its `null` variant. */
 function isNullField(field) {
 	return isField(field, "null");
 }
+/** Type guard: narrows a `WalkedField` to its `enum` variant. */
 function isEnumField(field) {
 	return isField(field, "enum");
 }
+/** Type guard: narrows a `WalkedField` to its `literal` variant. */
 function isLiteralField(field) {
 	return isField(field, "literal");
 }
+/** Type guard: narrows a `WalkedField` to its `object` variant. */
 function isObjectField(field) {
 	return isField(field, "object");
 }
+/** Type guard: narrows a `WalkedField` to its `array` variant. */
 function isArrayField(field) {
 	return isField(field, "array");
 }
+/** Type guard: narrows a `WalkedField` to its `tuple` variant. */
 function isTupleField(field) {
 	return isField(field, "tuple");
 }
+/** Type guard: narrows a `WalkedField` to its `record` variant. */
 function isRecordField(field) {
 	return isField(field, "record");
 }
+/** Type guard: narrows a `WalkedField` to its plain `union` variant. */
 function isUnionField(field) {
 	return isField(field, "union");
 }
+/** Type guard: narrows a `WalkedField` to its `discriminatedUnion` variant. */
 function isDiscriminatedUnionField(field) {
 	return isField(field, "discriminatedUnion");
 }
+/** Type guard: narrows a `WalkedField` to its `conditional` (if/then/else) variant. */
 function isConditionalField(field) {
 	return isField(field, "conditional");
 }
+/** Type guard: narrows a `WalkedField` to its `negation` (`not`) variant. */
 function isNegationField(field) {
 	return isField(field, "negation");
 }
+/** Type guard: narrows a `WalkedField` to its `file` variant. */
 function isFileField(field) {
 	return isField(field, "file");
 }
+/** Type guard: narrows a `WalkedField` to its `never` variant (false schema). */
 function isNeverField(field) {
 	return isField(field, "never");
 }
+/** Type guard: narrows a `WalkedField` to its `unknown` variant (permissive). */
 function isUnknownField(field) {
 	return isField(field, "unknown");
 }

package/dist/core/unionMatch.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/unionMatch.d.ts
 /**

package/dist/core/uri.d.mts

@@ -17,16 +17,24 @@
  * Returns `true` when the value is either a relative reference (no scheme
  * component) or an absolute URI using `http`/`https`. Returns `false`
  * for any other scheme, including dangerous ones like `javascript:` and
- * `data:`.
+ * `data:`, and for any value that splices ASCII tab/newline/NUL bytes
+ * into its scheme — the WHATWG URL parser strips those before scheme
+ * detection, so accepting them would let `"java\tscript:alert(1)"`
+ * resolve to `javascript:alert(1)` in a browser.
  */
 declare function isSafeHyperlink(value: string): boolean;
 /**
  * Decide whether `value` is safe to interpolate into a `mailto:` URI.
  *
  * The check rejects values that do not match the standard email format
- * pattern. The format pattern excludes whitespace, which means a CRLF
- * sequence (or its percent-encoded form embedded by the caller) cannot
- * pass — eliminating the SMTP/`mailto` header-injection vector.
+ * pattern. The format pattern excludes whitespace, but it does permit
+ * `%`, and a browser decodes percent-escapes at click time — so a value
+ * such as `"foo%0Abcc:victim@bar.com"` would inject a `Bcc:` header into
+ * the resulting `mailto:` URI. Refuse any value containing `%` to close
+ * that header-injection vector. The plain email-format regex stays a
+ * pure email-syntax check; the additional `%` filter lives here so other
+ * callers of the format pattern (form validators, JSON Schema `format:
+ * email` checks) are not affected.
  */
 declare function isSafeMailtoAddress(value: string): boolean;
 /**

package/dist/core/uri.mjs

@@ -20,6 +20,22 @@ import { EMAIL_FORMAT_PATTERN } from "./formats.mjs";
 */
 const ABSOLUTE_URI_SCHEME = /^\s*([a-z][a-z0-9+\-.]*):/i;
 /**
+* ASCII control characters that the WHATWG URL parser strips before it
+* detects a scheme. A value such as `"java\tscript:alert(1)"` therefore
+* resolves to `javascript:alert(1)` in a browser, even though the literal
+* scheme regex would not match. Splicing any of these characters into a
+* URI is unambiguously hostile, so the safe-scheme check refuses such
+* values outright.
+*
+* Source: WHATWG URL Living Standard §4.4 "URL parsing" — tab and newline
+* (`\t`, `\n`, `\r`) are removed prior to state-machine entry. NUL bytes
+* (`\0`) are likewise stripped by some user agents and never legitimate
+* inside a URI.
+*
+* https://web.archive.org/web/20251101000000*\/https://url.spec.whatwg.org/#concept-basic-url-parser
+*/
+const URL_CONTROL_CHARACTERS = /[\t\n\r\0]/;
+/**
 * Schemes safe to emit unmodified into an `href` attribute. Anything
 * outside this set — most importantly `javascript:`, `data:`, `vbscript:`
 * and `file:` — is rejected and rendered as text.
@@ -31,9 +47,13 @@ const SAFE_HYPERLINK_SCHEMES = new Set(["http", "https"]);
 * Returns `true` when the value is either a relative reference (no scheme
 * component) or an absolute URI using `http`/`https`. Returns `false`
 * for any other scheme, including dangerous ones like `javascript:` and
-* `data:`.
+* `data:`, and for any value that splices ASCII tab/newline/NUL bytes
+* into its scheme — the WHATWG URL parser strips those before scheme
+* detection, so accepting them would let `"java\tscript:alert(1)"`
+* resolve to `javascript:alert(1)` in a browser.
 */
 function isSafeHyperlink(value) {
+	if (URL_CONTROL_CHARACTERS.test(value)) return false;
 	const match = ABSOLUTE_URI_SCHEME.exec(value);
 	if (match === null) return true;
 	const scheme = match[1];
@@ -44,11 +64,17 @@ function isSafeHyperlink(value) {
 * Decide whether `value` is safe to interpolate into a `mailto:` URI.
 *
 * The check rejects values that do not match the standard email format
-* pattern. The format pattern excludes whitespace, which means a CRLF
-* sequence (or its percent-encoded form embedded by the caller) cannot
-* pass — eliminating the SMTP/`mailto` header-injection vector.
+* pattern. The format pattern excludes whitespace, but it does permit
+* `%`, and a browser decodes percent-escapes at click time — so a value
+* such as `"foo%0Abcc:victim@bar.com"` would inject a `Bcc:` header into
+* the resulting `mailto:` URI. Refuse any value containing `%` to close
+* that header-injection vector. The plain email-format regex stays a
+* pure email-syntax check; the additional `%` filter lives here so other
+* callers of the format pattern (form validators, JSON Schema `format:
+* email` checks) are not affected.
 */
 function isSafeMailtoAddress(value) {
+	if (value.includes("%")) return false;
 	return EMAIL_FORMAT_PATTERN.test(value);
 }
 /**

package/dist/core/version.d.mts

@@ -1,2 +1,2 @@
-import { a as detectJsonSchemaDraft, c as inferJsonSchemaDraftWithReason, d as isSwagger2, f as matchJsonSchemaDraftUri, i as OpenApiVersionInfo, l as isOpenApi30, n as JsonSchemaDialectInfo, o as detectOpenApiVersion, p as readJsonSchemaDialect, r as JsonSchemaDraft, s as inferJsonSchemaDraft, t as InferredDraft, u as isOpenApi31 } from "../version-ZzL5R6cS.mjs";
+import { a as detectJsonSchemaDraft, c as inferJsonSchemaDraftWithReason, d as isSwagger2, f as matchJsonSchemaDraftUri, i as OpenApiVersionInfo, l as isOpenApi30, n as JsonSchemaDialectInfo, o as detectOpenApiVersion, p as readJsonSchemaDialect, r as JsonSchemaDraft, s as inferJsonSchemaDraft, t as InferredDraft, u as isOpenApi31 } from "../version-DL8U5RuA.mjs";
 export { InferredDraft, JsonSchemaDialectInfo, JsonSchemaDraft, OpenApiVersionInfo, detectJsonSchemaDraft, detectOpenApiVersion, inferJsonSchemaDraft, inferJsonSchemaDraftWithReason, isOpenApi30, isOpenApi31, isSwagger2, matchJsonSchemaDraftUri, readJsonSchemaDialect };

package/dist/core/walkBuilders.d.mts

@@ -1,16 +1,38 @@
-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, d as FieldOverrides, j as WalkedField, o as Editability, p as FileField, r as BooleanField, v as NullField, w as SchemaMeta } from "../types-BrYbjC7_.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
+import { t as ExternalResolver } from "../ref-DdsbekXX.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;
-interface WalkOptions {
+/**
+ * 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.
+ *
+ * `WalkOptions` is generic in the schema's value type so callers that
+ * walk a typed schema can carry `FieldOverrides<T>` through. The
+ * default `T = unknown` preserves the loose runtime record shape for
+ * existing non-generic callers — `Record<string, unknown>`.
+ *
+ * @group Walkers
+ */
+interface WalkOptions<T = unknown> {
   componentMeta?: SchemaMeta | undefined;
   rootMeta?: SchemaMeta | undefined;
-  /** Nested field overrides — same shape as the schema. */
-  fieldOverrides?: Record<string, unknown> | undefined;
+  /**
+   * Nested field overrides — same shape as the schema.
+   *
+   * Typed against `FieldOverrides<T>` when a schema value type is
+   * supplied; falls back to `Record<string, unknown>` for the
+   * default `T = unknown` so the loose runtime shape continues to
+   * compile.
+   */
+  fieldOverrides?: unknown extends T ? Record<string, unknown> | undefined : FieldOverrides<T> | undefined;
   /** The root document for $ref resolution. */
   rootDocument?: Record<string, unknown> | undefined;
   /** Diagnostics channel for surfacing silent fallbacks. */
@@ -18,9 +40,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 +93,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 +122,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,13 +105,17 @@ function buildStringField(schema, ctx) {
 		constraints: extractStringConstraints(schema, ctx.diagnostics, ctx.pointer)
 	};
 }
+/** Build a walked `NumberField` from a JSON Schema node. */
 function buildNumberField(schema, ctx) {
+	const isInteger = schema.type === "integer";
 	return {
 		...buildBase(schema, ctx),
 		type: "number",
-		constraints: extractNumberConstraints(schema)
+		constraints: extractNumberConstraints(schema),
+		isInteger
 	};
 }
+/** Build a walked `BooleanField` from a JSON Schema node. */
 function buildBooleanField(schema, ctx) {
 	return {
 		...buildBase(schema, ctx),
@@ -98,6 +123,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 +131,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 +139,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 +176,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-BrYbjC7_.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);
@@ -310,6 +323,11 @@ function walkBoolean(schema, ctx) {
 	return buildBooleanField(schema, ctx);
 }
 function walkEnum(schema, enumValues, ctx) {
+	if (enumValues.length === 0) emitDiagnostic(ctx.diagnostics, {
+		code: "enum-empty",
+		message: "`enum` array is empty; per Draft 2020-12 §6.1.2 it must be non-empty. The schema describes an unsatisfiable value set.",
+		pointer: ctx.pointer
+	});
 	return {
 		...buildBase(schema, ctx),
 		type: "enum",

package/dist/{diagnostics-Cbwak-ZX.d.mts → diagnostics-BTrm3O6J.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";
+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-duplicate" | "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-empty" | "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-Dki7tji4.d.mts}

@@ -1,14 +1,17 @@
-import { T as SchemaType } from "./types-BTB73MB8.mjs";
+import { T as SchemaType } from "./types-BrYbjC7_.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,6 @@
-import { j as WalkedField } from "../types-BTB73MB8.mjs";
-import { t as AllConstraints } from "../renderer-Ul9taFYp.mjs";
+import { j as WalkedField } from "../types-BrYbjC7_.mjs";
+import { AllConstraints } from "../core/renderer.mjs";
+import { constraintHint } from "../core/constraintHint.mjs";
 import { HtmlAttributes, HtmlNode } from "./html.mjs";
 
 //#region src/html/a11y.d.ts
@@ -27,11 +28,6 @@ declare function buildInputId(path: string, key: string): string;
  * the HTML renderers.
  */
 declare function buildHintId(inputId: string): string;
-/**
- * Build a human-readable constraint description string.
- * Returns undefined if no constraints are present.
- */
-declare function constraintHint(c: AllConstraints): string | undefined;
 /**
  * Build `aria-required` attribute for required fields.
  * Returns an object to spread into `h()` attributes, or empty object.

package/dist/html/a11y.mjs

@@ -1,3 +1,4 @@
+import { constraintHint } from "../core/constraintHint.mjs";
 import { fieldDomId, hintIdFor } from "../core/idPath.mjs";
 import { h } from "./html.mjs";
 //#region src/html/a11y.ts
@@ -35,22 +36,6 @@ function buildHintId(inputId) {
 	return hintIdFor(inputId);
 }
 /**
-* Build a human-readable constraint description string.
-* Returns undefined if no constraints are present.
-*/
-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(". ");
-}
-/**
 * Build `aria-required` attribute for required fields.
 * Returns an object to spread into `h()` attributes, or empty object.
 */