schema-components 1.13.0 → 1.15.0

package/dist/react/fieldPath.d.mts

@@ -1,4 +1,4 @@
-import { j as WalkedField } from "../types-ag2jYLqQ.mjs";
+import { M as WalkedField } from "../types-D_5ST7SS.mjs";
 
 //#region src/react/fieldPath.d.ts
 /**

package/dist/react/headless.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-DseHeliw.mjs";
+import { r as ComponentResolver } from "../renderer-BdSqllx5.mjs";
 
 //#region src/react/headless.d.ts
 /**

package/dist/react/headlessRenderers.d.mts

@@ -1,4 +1,4 @@
-import { l as RenderProps } from "../renderer-DseHeliw.mjs";
+import { l as RenderProps } from "../renderer-BdSqllx5.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/headlessRenderers.d.ts

package/dist/react/headlessRenderers.mjs

@@ -1,6 +1,6 @@
 import { isObject } from "../core/guards.mjs";
-import { isValidElement, useCallback, useRef } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { isValidElement, useCallback, useRef } from "react";
 //#region src/react/headlessRenderers.tsx
 /**
 * Headless renderer functions — one per schema type.

package/dist/ref-DvWoULcy.d.mts

@@ -0,0 +1,44 @@
+import { i as DiagnosticsOptions } from "./diagnostics-DzbZmcLI.mjs";
+
+//#region src/core/ref.d.ts
+/**
+ * Resolver function for external $ref URIs.
+ * Called with the URI portion (everything before `#`) of an external ref.
+ * Returns the parsed document (JSON object) or undefined.
+ */
+type ExternalResolver = (uri: string) => unknown;
+/**
+ * Options for $ref resolution.
+ */
+interface RefOptions {
+  diagnostics?: DiagnosticsOptions;
+  externalResolver?: ExternalResolver;
+}
+/**
+ * Count all distinct `$ref` strings reachable from a root document.
+ * A chain longer than the number of distinct refs is necessarily cyclic.
+ * Returns at least 1 so that single-ref schemas have a usable bound.
+ */
+declare function countDistinctRefs(root: Record<string, unknown>): number;
+/**
+ * Resolve a `$ref` in a schema against a root document.
+ * Returns the original schema if no `$ref` is present.
+ * Returns an unknown-schema placeholder on cycle or depth exceeded.
+ *
+ * The depth bound is derived from the number of distinct `$ref` strings
+ * in the root document — a chain longer than that count is necessarily
+ * cyclic. When `maxDepth` is not provided, a reasonable default is used.
+ */
+declare function resolveRef(schema: Record<string, unknown>, rootDocument: Record<string, unknown>, visited: Set<string>, diagnostics?: DiagnosticsOptions, maxDepth?: number, externalResolver?: ExternalResolver): Record<string, unknown>;
+/**
+ * Dereference a JSON Pointer fragment (`#/path/to/schema`) or an
+ * `$anchor` (`#SomeName`) against a root document.
+ */
+declare function dereference(ref: string, root: Record<string, unknown>): Record<string, unknown> | undefined;
+/**
+ * Recursively scan a schema document for a `$anchor` matching the given name.
+ * Returns the schema object containing the anchor, or undefined.
+ */
+declare function findAnchor(node: unknown, anchorName: string): Record<string, unknown> | undefined;
+//#endregion
+export { findAnchor as a, dereference as i, RefOptions as n, resolveRef as o, countDistinctRefs as r, ExternalResolver as t };

package/dist/{renderer-DseHeliw.d.mts → renderer-BdSqllx5.d.mts}

@@ -1,4 +1,4 @@
-import { E as StringConstraints, b as ObjectConstraints, f as FileConstraints, j as WalkedField, t as ArrayConstraints, v as NumberConstraints, w as SchemaMeta } from "./types-ag2jYLqQ.mjs";
+import { D as StringConstraints, M as WalkedField, T as SchemaMeta, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "./types-D_5ST7SS.mjs";
 
 //#region src/core/renderer.d.ts
 /**

package/dist/themes/mantine.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-DseHeliw.mjs";
+import { r as ComponentResolver } from "../renderer-BdSqllx5.mjs";
 
 //#region src/themes/mantine.d.ts
 /**

package/dist/themes/mui.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-DseHeliw.mjs";
+import { r as ComponentResolver } from "../renderer-BdSqllx5.mjs";
 
 //#region src/themes/mui.d.ts
 /**

package/dist/themes/mui.mjs

@@ -1,8 +1,8 @@
 import { isObject } from "../core/guards.mjs";
 import { toReactNode } from "../react/headlessRenderers.mjs";
 import { headlessResolver } from "../react/headless.mjs";
-import { isValidElement } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { isValidElement } from "react";
 //#region src/themes/mui.tsx
 function ariaRequired(tree) {
 	return { required: tree.isOptional === false };

package/dist/themes/radix.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-DseHeliw.mjs";
+import { r as ComponentResolver } from "../renderer-BdSqllx5.mjs";
 
 //#region src/themes/radix.d.ts
 /**

package/dist/themes/shadcn.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-DseHeliw.mjs";
+import { r as ComponentResolver } from "../renderer-BdSqllx5.mjs";
 
 //#region src/themes/shadcn.d.ts
 declare const shadcnResolver: ComponentResolver;

package/dist/{typeInference-CRPqVwKu.d.mts → typeInference-k7FXfTVO.d.mts}

@@ -1,4 +1,4 @@
-import { d as FieldOverrides, u as FieldOverride } from "./types-ag2jYLqQ.mjs";
+import { d as FieldOverrides, u as FieldOverride } from "./types-D_5ST7SS.mjs";
 
 //#region src/core/typeInference.d.ts
 /**
@@ -52,6 +52,38 @@ type FromJSONSchema<S, Defs extends Record<string, unknown> = Record<string, nev
 } ? ArrayToUnion<E> : S extends {
   type: infer T;
 } ? TypeToTs<T, S, Defs> : S extends readonly (infer E)[] ? E : unknown;
+/**
+ * Marker type emitted when OpenAPI $ref resolution hits the type-level
+ * recursion depth limit. Instead of silently falling back to
+ * `Record<string, FieldOverride>`, produces this branded type so
+ * consumers can detect it via conditional types.
+ *
+ * Usage:
+ * ```ts
+ * type Fields = InferRequestBodyFields<Doc, "/users", "post">;
+ * type IsFallback = Fields extends __SchemaInferenceFellBack ? true : false;
+ * ```
+ */
+interface __SchemaInferenceFellBack {
+  readonly __schemaInferenceFallback: unique symbol;
+}
+/**
+ * Escape hatch for recursive schemas where type-level inference
+ * cannot proceed. Typed as `Record<string, FieldOverride>` but
+ * explicitly branded so callers know they are using the unsafe path.
+ *
+ * JSDoc trade-off note: This bypasses field-level type safety.
+ * Prefer restructuring the schema to avoid deep $ref chains
+ * when possible.
+ */
+type UnsafeFields = Record<string, FieldOverride> & {
+  /** Marks this as the unsafe fallback for recursive schemas. */readonly __unsafe?: true;
+};
+/**
+ * Convert a `FromJSONSchema` result to `unknown` when recursion is detected.
+ * Returns the original type when the schema is non-recursive.
+ */
+type DetectRecursiveFallback<T> = unknown extends T ? __SchemaInferenceFellBack : T;
 /**
  * Resolve a $ref against the local definitions context.
  * Supports:
@@ -59,7 +91,7 @@ type FromJSONSchema<S, Defs extends Record<string, unknown> = Record<string, nev
  * - `#/$defs/Name` and `#/definitions/Name` (named definitions)
  * - `#SomeName` ($anchor, $dynamicAnchor resolved from definitions)
  */
-type ResolveSchemaRef<R extends string, Defs extends Record<string, unknown>> = R extends "#" ? unknown : R extends `#/$defs/${infer Name}` ? Name extends keyof Defs ? FromJSONSchema<Defs[Name], Defs> : unknown : R extends `#/definitions/${infer Name}` ? Name extends keyof Defs ? FromJSONSchema<Defs[Name], Defs> : unknown : R extends `#${infer AnchorName}` ? AnchorName extends keyof Defs ? FromJSONSchema<Defs[AnchorName], Defs> : unknown : unknown;
+type ResolveSchemaRef<R extends string, Defs extends Record<string, unknown>, Depth extends number = 0> = Depth extends 10 ? __SchemaInferenceFellBack : R extends "#" ? unknown : R extends `#/$defs/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#/definitions/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#${infer AnchorName}` ? AnchorName extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[AnchorName], Defs>> : unknown : unknown;
 /**
  * Merge an allOf array into an intersection type.
  */
@@ -264,17 +296,21 @@ type OpenAPIRequestBodyType<Doc, Path extends string, Method extends string> = R
 type OpenAPIResponseType<Doc, Path extends string, Method extends string, Status extends string> = ResolveMaybeRef<Doc, ResponseSchemaOf<OperationOf<PathItemOf<Doc, Path>, Method>, Status>>;
 /**
  * Infer the fields prop type for ApiRequestBody.
- * Falls back to Record<string, FieldOverride> for runtime documents.
+ * Surfaces `__SchemaInferenceFellBack` when the schema contains
+ * recursive $ref chains that exceed type-level depth limits.
+ * Falls back to `Record<string, FieldOverride>` for runtime documents.
  */
-type InferRequestBodyFields<Doc, Path extends string, Method extends string> = unknown extends OpenAPIRequestBodyType<Doc, Path, Method> ? Record<string, FieldOverride> : FieldOverrides<OpenAPIRequestBodyType<Doc, Path, Method>>;
+type InferRequestBodyFields<Doc, Path extends string, Method extends string> = unknown extends OpenAPIRequestBodyType<Doc, Path, Method> ? OpenAPIRequestBodyType<Doc, Path, Method> extends __SchemaInferenceFellBack ? __SchemaInferenceFellBack : Record<string, FieldOverride> : FieldOverrides<OpenAPIRequestBodyType<Doc, Path, Method>>;
 /**
  * Infer the fields prop type for ApiResponse.
- * Falls back to Record<string, FieldOverride> for runtime documents.
+ * Surfaces `__SchemaInferenceFellBack` when the schema contains
+ * recursive $ref chains that exceed type-level depth limits.
+ * Falls back to `Record<string, FieldOverride>` for runtime documents.
  */
-type InferResponseFields<Doc, Path extends string, Method extends string, Status extends string> = unknown extends OpenAPIResponseType<Doc, Path, Method, Status> ? Record<string, FieldOverride> : FieldOverrides<OpenAPIResponseType<Doc, Path, Method, Status>>;
+type InferResponseFields<Doc, Path extends string, Method extends string, Status extends string> = unknown extends OpenAPIResponseType<Doc, Path, Method, Status> ? OpenAPIResponseType<Doc, Path, Method, Status> extends __SchemaInferenceFellBack ? __SchemaInferenceFellBack : Record<string, FieldOverride> : FieldOverrides<OpenAPIResponseType<Doc, Path, Method, Status>>;
 /**
  * Infer the overrides prop type for ApiParameters.
- * Falls back to Record<string, FieldOverride> for runtime documents.
+ * Falls back to `Record<string, FieldOverride>` for runtime documents.
  */
 type InferParameterOverrides<Doc, Path extends string, Method extends string> = string extends ParameterNamesOf<Doc, Path, Method> ? Record<string, FieldOverride> : Partial<Record<ParameterNamesOf<Doc, Path, Method>, FieldOverride>>;
 /**
@@ -296,4 +332,4 @@ type PathOfType<T, Prefix extends string = ""> = IsNarrowObject<T> extends true
  */
 type TypeAtPath<T, P extends string> = P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? TypeAtPath<T[Key], Rest> : unknown : P extends keyof T ? T[P] : unknown;
 //#endregion
-export { OpenAPIRequestBodyType as a, ResolveOpenAPIRef as c, InferResponseFields as i, TypeAtPath as l, InferParameterOverrides as n, OpenAPIResponseType as o, InferRequestBodyFields as r, PathOfType as s, FromJSONSchema as t };
+export { OpenAPIRequestBodyType as a, ResolveOpenAPIRef as c, __SchemaInferenceFellBack as d, InferResponseFields as i, TypeAtPath as l, InferParameterOverrides as n, OpenAPIResponseType as o, InferRequestBodyFields as r, PathOfType as s, FromJSONSchema as t, UnsafeFields as u };

package/dist/{types-ag2jYLqQ.d.mts → types-D_5ST7SS.d.mts}

@@ -59,13 +59,15 @@ type FieldOverride = Partial<SchemaMeta> & {
  * All schema types the walker can produce.
  * Used as the discriminant in the WalkedField tagged union.
  */
-type SchemaType = "string" | "number" | "boolean" | "null" | "enum" | "literal" | "object" | "array" | "tuple" | "record" | "union" | "discriminatedUnion" | "conditional" | "negation" | "recursive" | "file" | "unknown";
+type SchemaType = "string" | "number" | "boolean" | "null" | "enum" | "literal" | "object" | "array" | "tuple" | "record" | "union" | "discriminatedUnion" | "conditional" | "negation" | "recursive" | "file" | "never" | "unknown";
 /** Constraints that apply to string schemas. */
 interface StringConstraints {
   minLength?: number;
   maxLength?: number;
   pattern?: string;
   format?: string;
+  /** Derived RegExp from the format string, if the format is recognised. */
+  formatPattern?: RegExp;
   contentEncoding?: string;
   contentMediaType?: string;
 }
@@ -231,6 +233,11 @@ interface RecursiveField extends FieldBase {
   /** The $ref string that would create the cycle (e.g. "#" or "#Node"). */
   refTarget: string;
 }
+/** Schema position where `false` appears — the field cannot have any value. */
+interface NeverField extends FieldBase {
+  type: "never";
+  constraints: Record<string, never>;
+}
 interface UnknownField extends FieldBase {
   type: "unknown";
   constraints: Record<string, never>;
@@ -239,7 +246,7 @@ interface UnknownField extends FieldBase {
  * Tagged union of all schema field types produced by the walker.
  * Use `field.type` to narrow to a specific variant.
  */
-type WalkedField = StringField | NumberField | BooleanField | NullField | EnumField | LiteralField | ObjectField | ArrayField | TupleField | RecordField | UnionField | DiscriminatedUnionField | ConditionalField | NegationField | RecursiveField | FileField | UnknownField;
+type WalkedField = StringField | NumberField | BooleanField | NullField | EnumField | LiteralField | ObjectField | ArrayField | TupleField | RecordField | UnionField | DiscriminatedUnionField | ConditionalField | NegationField | RecursiveField | NeverField | FileField | UnknownField;
 declare function isStringField(field: WalkedField): field is StringField;
 declare function isNumberField(field: WalkedField): field is NumberField;
 declare function isBooleanField(field: WalkedField): field is BooleanField;
@@ -256,6 +263,7 @@ declare function isConditionalField(field: WalkedField): field is ConditionalFie
 declare function isNegationField(field: WalkedField): field is NegationField;
 declare function isFileField(field: WalkedField): field is FileField;
 declare function isRecursiveField(field: WalkedField): field is RecursiveField;
+declare function isNeverField(field: WalkedField): field is NeverField;
 declare function isUnknownField(field: WalkedField): field is UnknownField;
 //#endregion
-export { UnknownField as A, isNullField as B, RecursiveField as C, StringField as D, StringConstraints as E, isDiscriminatedUnionField as F, isStringField as G, isObjectField as H, isEnumField as I, isUnknownField as J, isTupleField as K, isFileField as L, isArrayField as M, isBooleanField as N, TupleField as O, isConditionalField as P, isLiteralField as R, RecordField as S, SchemaType as T, isRecordField as U, isNumberField as V, isRecursiveField as W, resolveEditability as Y, NullField as _, DiscriminatedUnionField as a, ObjectConstraints as b, FieldBase as c, FieldOverrides as d, FileConstraints as f, NegationField as g, LiteralField as h, ConditionalField as i, WalkedField as j, UnionField as k, FieldConstraints as l, JsonObject as m, ArrayField as n, Editability as o, FileField as p, isUnionField as q, BooleanField as r, EnumField as s, ArrayConstraints as t, FieldOverride as u, NumberConstraints as v, SchemaMeta as w, ObjectField as x, NumberField as y, isNegationField as z };
+export { UnionField as A, isNegationField as B, RecordField as C, StringConstraints as D, SchemaType as E, isConditionalField as F, isRecordField as G, isNullField as H, isDiscriminatedUnionField as I, isTupleField as J, isRecursiveField as K, isEnumField as L, WalkedField as M, isArrayField as N, StringField as O, isBooleanField as P, isFileField as R, ObjectField as S, SchemaMeta as T, isNumberField as U, isNeverField as V, isObjectField as W, isUnknownField as X, isUnionField as Y, resolveEditability as Z, NeverField as _, DiscriminatedUnionField as a, NumberField as b, FieldBase as c, FieldOverrides as d, FileConstraints as f, NegationField as g, LiteralField as h, ConditionalField as i, UnknownField as j, TupleField as k, FieldConstraints as l, JsonObject as m, ArrayField as n, Editability as o, FileField as p, isStringField as q, BooleanField as r, EnumField as s, ArrayConstraints as t, FieldOverride as u, NullField as v, RecursiveField as w, ObjectConstraints as x, NumberConstraints as y, isLiteralField as z };

package/dist/version-B5NV-35j.d.mts

@@ -0,0 +1,69 @@
+//#region src/core/version.d.ts
+/**
+ * JSON Schema draft and OpenAPI version detection.
+ *
+ * Detects the version from `$schema` URIs and OpenAPI `openapi`/`swagger`
+ * fields. Used by the normaliser to apply version-specific transformations
+ * before the walker processes the schema.
+ */
+type JsonSchemaDraft = "draft-04" | "draft-06" | "draft-07" | "draft-2019-09" | "draft-2020-12";
+/**
+ * Detect the JSON Schema draft version from a schema's `$schema` URI.
+ * When `$schema` is absent, uses heuristic keyword detection via
+ * `inferJsonSchemaDraft` to guess the draft version.
+ * Returns `"draft-2020-12"` as the final fallback when no heuristic
+ * matches either.
+ */
+declare function detectJsonSchemaDraft(schema: Record<string, unknown>): JsonSchemaDraft;
+/**
+ * Inference result carrying the detected draft and the heuristic
+ * that triggered it.
+ */
+interface InferredDraft {
+  draft: JsonSchemaDraft;
+  inferredFrom: string;
+}
+/**
+ * Infer the JSON Schema draft from keyword presence when `$schema`
+ * is absent. Examined from highest-confidence to lowest.
+ *
+ * Heuristics:
+ * 1. `$dynamicRef` / `$dynamicAnchor` / `prefixItems` → Draft 2020-12
+ * 2. `$recursiveRef` / `$recursiveAnchor` / `unevaluatedProperties` /
+ *    `dependentSchemas` → Draft 2019-09
+ * 3. `if` / `then` / `else`, `contentEncoding` / `contentMediaType` → Draft 07
+ * 4. `const`, `examples` (array), `propertyNames` → Draft 06
+ * 5. Boolean `exclusiveMinimum`, `id` (no `$`), `definitions` only → Draft 04
+ * 6. No signal → Draft 2020-12
+ */
+declare function inferJsonSchemaDraft(schema: Record<string, unknown>): JsonSchemaDraft;
+/**
+ * Like `inferJsonSchemaDraft` but also returns the heuristic that
+ * triggered the inference, for diagnostic emission.
+ */
+declare function inferJsonSchemaDraftWithReason(schema: Record<string, unknown>): InferredDraft;
+interface OpenApiVersionInfo {
+  major: number;
+  minor: number;
+  patch: number;
+}
+/**
+ * Detect the OpenAPI/Swagger version from a document.
+ * Returns `undefined` for documents that are not OpenAPI or Swagger.
+ */
+declare function detectOpenApiVersion(doc: Record<string, unknown>): OpenApiVersionInfo | undefined;
+/**
+ * Check if an OpenAPI version is 3.0.x (uses modified Draft 04 schemas
+ * with `nullable` instead of `anyOf [T, null]`).
+ */
+declare function isOpenApi30(version: OpenApiVersionInfo): boolean;
+/**
+ * Check if an OpenAPI version is 3.1.x (uses standard Draft 2020-12).
+ */
+declare function isOpenApi31(version: OpenApiVersionInfo): boolean;
+/**
+ * Check if a document is Swagger 2.0.
+ */
+declare function isSwagger2(version: OpenApiVersionInfo): boolean;
+//#endregion
+export { detectOpenApiVersion as a, isOpenApi30 as c, detectJsonSchemaDraft as i, isOpenApi31 as l, JsonSchemaDraft as n, inferJsonSchemaDraft as o, OpenApiVersionInfo as r, inferJsonSchemaDraftWithReason as s, InferredDraft as t, isSwagger2 as u };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "schema-components",
-    "version": "1.13.0",
+    "version": "1.15.0",
     "description": "React components that render UI from Zod schemas, JSON Schema, and OpenAPI documents",
     "type": "module",
     "main": "./dist/index.mjs",

package/dist/version-CLchheaH.d.mts

@@ -1,40 +0,0 @@
-//#region src/core/version.d.ts
-/**
- * JSON Schema draft and OpenAPI version detection.
- *
- * Detects the version from `$schema` URIs and OpenAPI `openapi`/`swagger`
- * fields. Used by the normaliser to apply version-specific transformations
- * before the walker processes the schema.
- */
-type JsonSchemaDraft = "draft-04" | "draft-06" | "draft-07" | "draft-2019-09" | "draft-2020-12";
-/**
- * Detect the JSON Schema draft version from a schema's `$schema` URI.
- * Returns `"draft-2020-12"` as the default when `$schema` is absent —
- * this is the most compatible assumption for modern schemas.
- */
-declare function detectJsonSchemaDraft(schema: Record<string, unknown>): JsonSchemaDraft;
-interface OpenApiVersionInfo {
-  major: number;
-  minor: number;
-  patch: number;
-}
-/**
- * Detect the OpenAPI/Swagger version from a document.
- * Returns `undefined` for documents that are not OpenAPI or Swagger.
- */
-declare function detectOpenApiVersion(doc: Record<string, unknown>): OpenApiVersionInfo | undefined;
-/**
- * Check if an OpenAPI version is 3.0.x (uses modified Draft 04 schemas
- * with `nullable` instead of `anyOf [T, null]`).
- */
-declare function isOpenApi30(version: OpenApiVersionInfo): boolean;
-/**
- * Check if an OpenAPI version is 3.1.x (uses standard Draft 2020-12).
- */
-declare function isOpenApi31(version: OpenApiVersionInfo): boolean;
-/**
- * Check if a document is Swagger 2.0.
- */
-declare function isSwagger2(version: OpenApiVersionInfo): boolean;
-//#endregion
-export { isOpenApi30 as a, detectOpenApiVersion as i, OpenApiVersionInfo as n, isOpenApi31 as o, detectJsonSchemaDraft as r, isSwagger2 as s, JsonSchemaDraft as t };