schema-components 1.21.0 → 1.23.0

package/dist/react/SchemaComponent.mjs

@@ -1,5 +1,6 @@
 "use client";
-import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import { getProperty, isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import "../core/limits.mjs";
 import { SchemaFieldError, SchemaNormalisationError, SchemaRenderError } from "../core/errors.mjs";
 import { normaliseSchema } from "../core/adapter.mjs";
 import { buildRenderProps, getRenderFunction, mergeResolvers } from "../core/renderer.mjs";
@@ -46,7 +47,8 @@ const globalWidgets = /* @__PURE__ */ new Map();
 function registerWidget(name, render) {
 	globalWidgets.set(name, render);
 }
-function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, onDiagnostic, strict, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets, idPrefix }) {
+function SchemaComponent(props) {
+	const { schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, onDiagnostic, strict, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets, idPrefix } = props;
 	const userResolver = useContext(UserResolverContext);
 	const contextWidgets = useContext(WidgetsContext);
 	const generatedId = useId();
@@ -85,12 +87,23 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 		}
 		throw error;
 	}
+	const fieldsRecord = toRecordOrUndefined(fields);
 	const handleChange = useCallback((nextValue) => {
 		if (validate) {
-			const error = runValidation(zodSchema, jsonSchema, nextValue, onDiagnostic);
+			let error;
+			try {
+				error = runValidation(zodSchema, jsonSchema, nextValue, onDiagnostic);
+			} catch (err) {
+				const normalised = err instanceof SchemaNormalisationError ? err : new SchemaNormalisationError(err instanceof Error ? err.message : "Fallback validation failed", schemaInput, "zod-conversion-failed", void 0, err);
+				if (onError !== void 0) {
+					onError(normalised);
+					return;
+				}
+				throw normalised;
+			}
 			if (error !== void 0) {
 				onValidationError?.(error);
-				dispatchFieldErrors(fields, error);
+				dispatchFieldErrors(fieldsRecord, error);
 			}
 		}
 		onChange?.(nextValue);
@@ -100,13 +113,15 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 		jsonSchema,
 		onChange,
 		onValidationError,
-		fields,
-		onDiagnostic
+		fieldsRecord,
+		onDiagnostic,
+		onError,
+		schemaInput
 	]);
 	const walkOptions = {
 		componentMeta: mergedMeta,
 		rootMeta,
-		fieldOverrides: fields,
+		fieldOverrides: fieldsRecord,
 		rootDocument,
 		...diagnostics !== void 0 ? { diagnostics } : {}
 	};
@@ -119,20 +134,19 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 	return renderField(tree, value ?? tree.defaultValue, handleChange, userResolver, renderChild, rootPath, instanceWidgets, contextWidgets, 0);
 }
 /**
-* Default root-path sentinel used when no `idPrefix` is supplied AND the
-* component is rendered outside a React tree (e.g. server-side bundling
-* test harnesses). Production callers receive a `useId()`-derived prefix
-* that is unique per instance.
-*/
-const ROOT_PATH = "root";
-/**
 * Append a child path suffix to a parent path. When the suffix is omitted
 * (e.g. transparent wrappers like union options), the parent path is
 * returned unchanged so the child inherits the parent's id.
+*
+* Bracketed array indices like `[0]` append directly so `tags` + `[0]`
+* becomes `tags[0]` rather than `tags.[0]` — matching the canonical form
+* used by `html/a11y.ts` `joinPath` and `react/fieldPath.ts` `resolvePath`,
+* which already parses bracket notation when navigating WalkedField trees.
 */
 function joinPath(parent, suffix) {
 	if (suffix === void 0 || suffix.length === 0) return parent;
 	if (parent.length === 0) return suffix;
+	if (suffix.startsWith("[")) return `${parent}${suffix}`;
 	return `${parent}.${suffix}`;
 }
 /**
@@ -146,11 +160,26 @@ function sanitisePrefix(value) {
 	if (sanitised.length === 0) throw new Error(`Cannot derive a DOM-safe id prefix from "${value}". Pass an explicit idPrefix prop.`);
 	return sanitised;
 }
+/**
+* Run validation against the supplied value.
+*
+* Returns the validation error (Zod error or equivalent) on failure, or
+* `undefined` when the value is valid OR when the fallback validation
+* path was skipped because a diagnostic sink absorbed the conversion
+* failure.
+*
+* Throws `SchemaNormalisationError` (kind `zod-conversion-failed`) when
+* the JSON-Schema → Zod fallback is taken AND no diagnostic sink is
+* wired up. The project's no-silent-fallback rule requires the failure
+* to surface somewhere — diagnostics if the consumer opted in, an error
+* otherwise — so the caller can route it through `onError` / an error
+* boundary rather than have validation quietly disappear.
+*/
 function runValidation(zodSchema, jsonSchema, value, onDiagnostic) {
 	if (zodSchema !== void 0 && isObject(zodSchema)) {
-		const safeParseFn = zodSchema.safeParse;
-		if (isCallable(safeParseFn)) {
-			const result = safeParseFn(value);
+		const validateFn = isCodecSchema(zodSchema) ? zodSchema.safeEncode : zodSchema.safeParse;
+		if (isCallable(validateFn)) {
+			const result = validateFn(value);
 			if (isObject(result) && "success" in result && result.success !== true) return result.error;
 			return;
 		}
@@ -159,8 +188,16 @@ function runValidation(zodSchema, jsonSchema, value, onDiagnostic) {
 	try {
 		parsed = z.fromJSONSchema(jsonSchema);
 	} catch (err) {
-		emitFromJsonSchemaDiagnostic(err, onDiagnostic);
-		return;
+		if (onDiagnostic !== void 0) {
+			onDiagnostic({
+				code: "unsupported-type",
+				message: `Skipping fallback validation: z.fromJSONSchema could not round-trip the normalised JSON Schema. Original message: ${err instanceof Error ? err.message : "z.fromJSONSchema threw a non-Error value"}`,
+				pointer: "",
+				detail: { source: "z.fromJSONSchema" }
+			});
+			return;
+		}
+		throw new SchemaNormalisationError(`Fallback validation failed: z.fromJSONSchema could not round-trip the normalised JSON Schema. Original message: ${err instanceof Error ? err.message : "z.fromJSONSchema threw a non-Error value"}`, jsonSchema, "zod-conversion-failed", void 0, err);
 	}
 	if (isObject(parsed)) {
 		const safeParseFn = parsed.safeParse;
@@ -170,39 +207,13 @@ function runValidation(zodSchema, jsonSchema, value, onDiagnostic) {
 		}
 	}
 }
-/**
-* Emit a diagnostic when `z.fromJSONSchema` refuses to round-trip the
-* already-normalised JSON Schema. The diagnostic reuses the existing
-* `unsupported-type` code because the failure mode is the same — a
-* keyword/structure Zod cannot represent — and the consumer should be
-* able to opt in to noticing it via the existing diagnostics channel.
-*
-* Best-effort: when no `onDiagnostic` sink is configured we still swallow
-* the throw (the alternative would crash the React render for a
-* non-essential validation step), matching the silent-fallback contract
-* the rest of the diagnostics system uses.
-*/
-function emitFromJsonSchemaDiagnostic(err, onDiagnostic) {
-	if (onDiagnostic === void 0) return;
-	onDiagnostic({
-		code: "unsupported-type",
-		message: `Skipping fallback validation: z.fromJSONSchema could not round-trip the normalised JSON Schema. Original message: ${err instanceof Error ? err.message : "z.fromJSONSchema threw a non-Error value"}`,
-		pointer: "",
-		detail: { source: "z.fromJSONSchema" }
-	});
-}
-/** Maximum rendering depth before treating a field as recursive. */
-const MAX_RENDER_DEPTH = 10;
 function renderField(tree, value, onChange, userResolver, renderChild, path, instanceWidgets, contextWidgets, depth = 0) {
-	if (path.length === 0) throw new Error("renderField requires a non-empty path. Pass ROOT_PATH for the root field and use renderChild's pathSuffix to derive child paths.");
-	if (depth >= MAX_RENDER_DEPTH) {
-		const refTarget = tree.type === "recursive" ? tree.refTarget : "";
-		return /* @__PURE__ */ jsx("fieldset", { children: /* @__PURE__ */ jsxs("em", { children: [
-			"↻ ",
-			(typeof tree.meta.description === "string" ? tree.meta.description : refTarget) || "schema",
-			" (recursive)"
-		] }) });
-	}
+	if (path.length === 0) throw new Error("renderField requires a non-empty path. Pass the root path (derived from `idPrefix` or `useId()`) for the root field, and use renderChild's pathSuffix to derive child paths.");
+	if (depth >= 10) return /* @__PURE__ */ jsx("fieldset", { children: /* @__PURE__ */ jsxs("em", { children: [
+		"↻ ",
+		typeof tree.meta.description === "string" ? tree.meta.description : "schema",
+		" (recursive)"
+	] }) });
 	const componentHint = tree.meta.component;
 	if (typeof componentHint === "string") {
 		const widget = instanceWidgets?.get(componentHint) ?? contextWidgets?.get(componentHint) ?? globalWidgets.get(componentHint);
@@ -257,12 +268,11 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 	if (fieldTree === void 0) throw new SchemaFieldError(`Field not found: ${path}`, schemaInput, path);
 	const fieldValue = resolveValue(value, path);
 	const handleChange = useCallback((nextFieldValue) => {
+		const newRootValue = setNestedValue(value, path, nextFieldValue);
 		if (validate) {
-			const newRootValue = setNestedValue(value, path, nextFieldValue);
 			const error = runValidation(zodSchema, jsonSchema, newRootValue);
 			if (error !== void 0) onValidationError?.(error);
 		}
-		const newRootValue = setNestedValue(value, path, nextFieldValue);
 		onChange?.(newRootValue);
 	}, [
 		validate,
@@ -283,15 +293,22 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 /**
 * Dispatch Zod errors to per-field onValidationError callbacks.
 * Walks the fields override tree and matches errors by path prefix.
+*
+* The runtime shape of `fields` is always `Record<string, FieldOverride>`
+* after `InferFields<T, Ref>` is erased — the typed variants
+* (`FieldOverrides<U>`) and the loose `Record<string, FieldOverride>`
+* fallback share the same structural shape, so the dispatch logic only
+* needs the loose record. The previous parameter union
+* (`Record<string, FieldOverride> | FieldOverrides<unknown> |
+* undefined`) collapsed because `FieldOverrides<unknown>` reduces to
+* `{}`, contributing no extra precision while adding noise to readers.
 */
 function dispatchFieldErrors(fields, error) {
 	if (fields === void 0 || !isObject(error)) return;
 	if (!("issues" in error)) return;
 	const issues = error.issues;
 	if (!Array.isArray(issues)) return;
-	const overrides = toRecordOrUndefined(fields);
-	if (overrides === void 0) return;
-	for (const [key, override] of Object.entries(overrides)) {
+	for (const [key, override] of Object.entries(fields)) {
 		if (override === void 0 || typeof override !== "object") continue;
 		if (override === null) continue;
 		if (!("onValidationError" in override)) continue;
@@ -313,5 +330,26 @@ function isFieldErrorCallback(value) {
 function isCallable(value) {
 	return typeof value === "function";
 }
+/**
+* True when `value` is a Zod schema implemented as a codec.
+*
+* Detection looks for `"$ZodCodec"` in the schema's `_zod.traits`
+* Set, mirroring the runtime detection used inside
+* `core/adapter.ts` (`isCodecSchema` there) and Zod's own
+* `isTransforming` helper. Duplicated here rather than imported
+* because adapter.ts does not export the helper and is outside this
+* fix-cycle's owned files.
+*
+* TODO(round7-integration): replace with an `import` once
+* `isCodecSchema` is exported from `core/adapter.ts` (or promoted to
+* `core/guards.ts`) by a coordinating commit.
+*/
+function isCodecSchema(value) {
+	const zod = getProperty(value, "_zod");
+	if (!isObject(zod)) return false;
+	const traits = zod.traits;
+	if (traits instanceof Set) return traits.has("$ZodCodec");
+	return false;
+}
 //#endregion
-export { ROOT_PATH, SchemaComponent, SchemaField, SchemaProvider, joinPath, registerWidget, renderField, sanitisePrefix };
+export { SchemaComponent, SchemaField, SchemaProvider, joinPath, registerWidget, renderField, sanitisePrefix };

package/dist/react/SchemaView.d.mts

@@ -1,16 +1,36 @@
-import { T as SchemaMeta } from "../types-BnxPEElk.mjs";
-import { t as Diagnostic } from "../diagnostics-CbBPsxSt.mjs";
-import { r as ComponentResolver } from "../renderer-DI6ZYf7a.mjs";
+import { w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { t as Diagnostic } from "../diagnostics-BS2kaUyE.mjs";
+import { r as ComponentResolver } from "../renderer-CXJ8y0qw.mjs";
+import { RejectUnrepresentableZod } from "../core/typeInference.mjs";
 import { WidgetMap } from "./SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/SchemaView.d.ts
-interface SchemaViewProps {
-  /** Zod schema, JSON Schema object, or OpenAPI document. */
-  schema: unknown;
+interface SchemaViewProps<T = unknown, Ref extends string | undefined = undefined> {
+  /**
+   * Zod schema, JSON Schema object, or OpenAPI document.
+   *
+   * Subject to the same compile-time rejection of unrepresentable
+   * Zod 4 types as {@link SchemaComponentProps.schema} — see
+   * {@link RejectUnrepresentableZod}.
+   */
+  schema: RejectUnrepresentableZod<T>;
   /** For OpenAPI: a ref string like "#/components/schemas/User". */
-  ref?: string;
-  /** Current value to render. */
+  ref?: Ref;
+  /**
+   * Current value to render.
+   *
+   * TYPE BOUNDARY NOTE: mirrors `SchemaComponentProps.value` — kept
+   * as `unknown` so the same boundary holds for both the editable
+   * (`SchemaComponent`) and read-only (`SchemaView`) entry points.
+   * The {@link InferredOutputValue} alias is the recommended way
+   * for callers to narrow on the consumer side.
+   *
+   * TODO(round7-integration): promote to
+   * `InferSchemaValue<T, Ref, "output">` alongside the matching
+   * `SchemaComponent` change. See the type-boundary note on
+   * `SchemaComponentProps.value` for the migration coordination.
+   */
   value?: unknown;
   /** Per-field meta overrides. */
   fields?: Record<string, unknown>;
@@ -44,7 +64,7 @@ interface SchemaViewProps {
  * Always renders in read-only mode. For editable forms, use
  * `<SchemaComponent>` with `"use client"`.
  */
-declare function SchemaView({
+declare function SchemaView<T = unknown, Ref extends string | undefined = undefined>({
   schema: schemaInput,
   ref: refInput,
   value,
@@ -56,6 +76,6 @@ declare function SchemaView({
   onDiagnostic,
   strict,
   idPrefix
-}: SchemaViewProps): ReactNode;
+}: SchemaViewProps<T, Ref>): ReactNode;
 //#endregion
 export { SchemaView, SchemaViewProps };

package/dist/react/SchemaView.mjs

@@ -1,3 +1,4 @@
+import "../core/limits.mjs";
 import { SchemaNormalisationError, SchemaRenderError } from "../core/errors.mjs";
 import { normaliseSchema } from "../core/adapter.mjs";
 import { buildRenderProps, getRenderFunction, mergeResolvers } from "../core/renderer.mjs";
@@ -74,10 +75,9 @@ function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: c
 	};
 	const tree = walk(jsonSchema, walkOptions);
 	const userResolver = resolver !== void 0 ? mergeResolvers(resolver, headlessResolver) : headlessResolver;
-	const MAX_SERVER_DEPTH = 10;
 	const makeRenderChild = (currentDepth, parentPath) => (childTree, childValue, pathSuffix) => {
 		const childPath = joinPath(parentPath, pathSuffix);
-		if (currentDepth >= MAX_SERVER_DEPTH) return createElement("fieldset", null, createElement("em", null, `\u21bb ${typeof childTree.meta.description === "string" ? childTree.meta.description : childTree.type === "recursive" ? childTree.refTarget : "schema"} (recursive)`));
+		if (currentDepth >= 10) return createElement("fieldset", null, createElement("em", null, `\u21bb ${typeof childTree.meta.description === "string" ? childTree.meta.description : "schema"} (recursive)`));
 		return renderFieldServer(childTree, childValue, userResolver, makeRenderChild(currentDepth + 1, childPath), childPath, widgets);
 	};
 	const renderChild = makeRenderChild(0, rootPath);

package/dist/react/a11y.d.mts

@@ -0,0 +1,21 @@
+import { j as WalkedField } from "../types-BTB73MB8.mjs";
+
+//#region src/react/a11y.d.ts
+/**
+ * Build the ARIA attribute bundle for a renderer.
+ *
+ * - `aria-required="true"` whenever the field is non-optional.
+ * - `aria-label=<description>` when a non-empty description is supplied.
+ *
+ * Returns a plain `Record<string, string>` (rather than a typed
+ * attribute interface) so callers can spread the result into any JSX
+ * element type without per-element TypeScript widening.
+ *
+ * Each helper from `html/a11y.ts` returns its corresponding fragment
+ * separately. The React renderers merge them into a single object
+ * here because the headless renderers compose one attribute bag per
+ * `<input>` element rather than threading multiple bags through `h()`.
+ */
+declare function buildAriaAttrs(tree: WalkedField, description?: unknown): Record<string, string>;
+//#endregion
+export { buildAriaAttrs };

package/dist/react/a11y.mjs

@@ -0,0 +1,24 @@
+//#region src/react/a11y.ts
+/**
+* Build the ARIA attribute bundle for a renderer.
+*
+* - `aria-required="true"` whenever the field is non-optional.
+* - `aria-label=<description>` when a non-empty description is supplied.
+*
+* Returns a plain `Record<string, string>` (rather than a typed
+* attribute interface) so callers can spread the result into any JSX
+* element type without per-element TypeScript widening.
+*
+* Each helper from `html/a11y.ts` returns its corresponding fragment
+* separately. The React renderers merge them into a single object
+* here because the headless renderers compose one attribute bag per
+* `<input>` element rather than threading multiple bags through `h()`.
+*/
+function buildAriaAttrs(tree, description) {
+	const attrs = {};
+	if (tree.isOptional === false) attrs["aria-required"] = "true";
+	if (typeof description === "string" && description.length > 0) attrs["aria-label"] = description;
+	return attrs;
+}
+//#endregion
+export { buildAriaAttrs };

package/dist/react/fieldPath.d.mts

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

package/dist/react/headless.d.mts

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

package/dist/react/headless.mjs

@@ -1,4 +1,4 @@
-import { renderArray, renderBoolean, renderConditional, renderDiscriminatedUnion, renderEnum, renderFile, renderLiteral, renderNegation, renderNever, renderNull, renderNumber, renderObject, renderRecord, renderRecursive, renderString, renderTuple, renderUnion, renderUnknown } from "./headlessRenderers.mjs";
+import { renderArray, renderBoolean, renderConditional, renderDiscriminatedUnion, renderEnum, renderFile, renderLiteral, renderNegation, renderNever, renderNull, renderNumber, renderObject, renderRecord, renderString, renderTuple, renderUnion, renderUnknown } from "./headlessRenderers.mjs";
 //#region src/react/headless.tsx
 /**
 * The headless resolver uses props.renderChild for recursive rendering.
@@ -27,7 +27,6 @@ const headlessResolver = {
 	negation: renderNegation,
 	literal: renderLiteral,
 	file: renderFile,
-	recursive: renderRecursive,
 	never: renderNever,
 	unknown: renderUnknown
 };

package/dist/react/headlessRenderers.d.mts

@@ -1,5 +1,5 @@
-import { M as WalkedField } from "../types-BnxPEElk.mjs";
-import { l as RenderProps } from "../renderer-DI6ZYf7a.mjs";
+import { j as WalkedField } from "../types-BTB73MB8.mjs";
+import { l as RenderProps } from "../renderer-CXJ8y0qw.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/headlessRenderers.d.ts
@@ -10,15 +10,14 @@ import { ReactNode } from "react";
 declare function toReactNode(value: unknown): ReactNode;
 /**
  * Build a stable, unique input ID from the path.
- * Used for `htmlFor`/`id` association between labels and inputs.
  *
- * Throws on an empty path: the previous "sc-field" fallback caused every
- * input across a form to share the same id, breaking label-input pairing
- * and screen reader navigation. Callers must thread a non-empty path
- * (see `ROOT_PATH` and `joinPath` in `SchemaComponent.tsx`).
+ * Re-exported alias for {@link fieldDomId} so external themes (shadcn,
+ * MUI, mantine, radix) keep importing `inputId` from the React entry
+ * point. Both the React and HTML renderers must derive the same id from
+ * the same path — `fieldDomId` in `core/idPath.ts` is the single
+ * source-of-truth.
  *
- * Dots and bracket indices in paths are converted to hyphens to keep the
- * id valid as a CSS selector and predictable in test queries.
+ * Throws on an empty path; see `fieldDomId` for the rationale.
  */
 declare function inputId(path: string): string;
 declare function renderString(props: RenderProps): ReactNode;
@@ -56,7 +55,6 @@ declare function renderDiscriminatedUnion(props: RenderProps): ReactNode;
  */
 declare function discriminatedUnionValueForTab(optionLabels: readonly string[], discKey: string, newIndex: number): Record<string, string> | undefined;
 declare function renderFile(props: RenderProps): ReactNode;
-declare function renderRecursive(props: RenderProps): ReactNode;
 /**
  * Render a literal field — `z.literal("a")` or `{ const: 5 }`.
  *
@@ -110,4 +108,4 @@ declare function renderConditional(props: RenderProps): ReactNode;
 declare function renderNegation(props: RenderProps): ReactNode;
 declare function renderUnknown(props: RenderProps): ReactNode;
 //#endregion
-export { defaultRecordValue, discriminatedUnionValueForTab, inputId, nextRecordKey, renameRecordKey, renderArray, renderBoolean, renderConditional, renderDiscriminatedUnion, renderEnum, renderFile, renderLiteral, renderNegation, renderNever, renderNull, renderNumber, renderObject, renderRecord, renderRecursive, renderString, renderTuple, renderUnion, renderUnknown, toReactNode };
+export { defaultRecordValue, discriminatedUnionValueForTab, inputId, nextRecordKey, renameRecordKey, renderArray, renderBoolean, renderConditional, renderDiscriminatedUnion, renderEnum, renderFile, renderLiteral, renderNegation, renderNever, renderNull, renderNumber, renderObject, renderRecord, renderString, renderTuple, renderUnion, renderUnknown, toReactNode };