schema-components 1.16.2 → 1.17.0

package/dist/core/renderer.d.mts

@@ -1,2 +1,2 @@
-import { a as HtmlRenderProps, c as RenderFunction, d as getRenderFunction, f as mergeHtmlResolvers, i as HtmlRenderFunction, l as RenderProps, m as typeToKey, n as BaseFieldProps, o as HtmlResolver, p as mergeResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as getHtmlRenderFn } from "../renderer-BdSqllx5.mjs";
+import { a as HtmlRenderProps, c as RenderFunction, d as getRenderFunction, f as mergeHtmlResolvers, i as HtmlRenderFunction, l as RenderProps, m as typeToKey, n as BaseFieldProps, o as HtmlResolver, p as mergeResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as getHtmlRenderFn } from "../renderer-B3s8o2B8.mjs";
 export { AllConstraints, BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/html/a11y.d.mts

@@ -1,5 +1,5 @@
 import { M as WalkedField } from "../types-D_5ST7SS.mjs";
-import { t as AllConstraints } from "../renderer-BdSqllx5.mjs";
+import { t as AllConstraints } from "../renderer-B3s8o2B8.mjs";
 import { HtmlAttributes, HtmlNode } from "./html.mjs";
 
 //#region src/html/a11y.d.ts

package/dist/html/renderToHtml.d.mts

@@ -1,5 +1,5 @@
 import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-BdSqllx5.mjs";
+import { o as HtmlResolver } from "../renderer-B3s8o2B8.mjs";
 
 //#region src/html/renderToHtml.d.ts
 interface RenderToHtmlOptions {

package/dist/html/renderToHtmlStream.d.mts

@@ -1,5 +1,5 @@
 import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-BdSqllx5.mjs";
+import { o as HtmlResolver } from "../renderer-B3s8o2B8.mjs";
 
 //#region src/html/renderToHtmlStream.d.ts
 interface StreamRenderOptions {

package/dist/html/renderers.d.mts

@@ -1,5 +1,5 @@
 import { M as WalkedField } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-BdSqllx5.mjs";
+import { o as HtmlResolver } from "../renderer-B3s8o2B8.mjs";
 
 //#region src/html/renderers.d.ts
 declare function dateInputType(format: string | undefined): string | undefined;

package/dist/html/streamRenderers.d.mts

@@ -1,5 +1,5 @@
 import { M as WalkedField } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-BdSqllx5.mjs";
+import { o as HtmlResolver } from "../renderer-B3s8o2B8.mjs";
 import { HtmlElement } from "./html.mjs";
 
 //#region src/html/streamRenderers.d.ts

package/dist/openapi/components.mjs

@@ -7,10 +7,24 @@ import { ApiLinks } from "./ApiLinks.mjs";
 import { ApiResponseHeaders } from "./ApiResponseHeaders.mjs";
 import { ApiSecurity } from "./ApiSecurity.mjs";
 import { getLinks, getSecurityRequirements, getSecuritySchemes, listCallbacks } from "./parser.mjs";
-import { renderField } from "../react/SchemaComponent.mjs";
+import { joinPath, renderField, sanitisePrefix } from "../react/SchemaComponent.mjs";
 import { getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, toDoc } from "./resolve.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 //#region src/openapi/components.tsx
+/**
+* OpenAPI React components with type-safe generics.
+*
+* Render API operations, parameters, request bodies, and response schemas
+* from OpenAPI 3.x documents. When the document is typed `as const`,
+* the `fields` / `overrides` props get full autocomplete.
+*
+* Type safety is enforced at the outer component's props level via
+* conditional types (InferRequestBodyFields, InferResponseFields,
+* InferParameterOverrides). Internally, schemas are extracted and
+* rendered via the walker + headless resolver directly, bypassing
+* SchemaComponent to avoid deferred-conditional-type compatibility issues.
+*/
 function noop() {}
 function renderSchema(schema, rootDocument, options) {
 	let jsonSchema;
@@ -32,8 +46,11 @@ function renderSchema(schema, rootDocument, options) {
 		rootDocument
 	};
 	const tree = walk(jsonSchema, walkOpts);
-	const renderChild = (childTree, childValue, childOnChange) => renderField(childTree, childValue, childOnChange, void 0, renderChild, options.widgets);
-	return renderField(tree, options.value, options.onChange ?? noop, void 0, renderChild, options.widgets);
+	const makeRenderChild = (parentPath) => (childTree, childValue, childOnChange, pathSuffix) => {
+		const childPath = joinPath(parentPath, pathSuffix);
+		return renderField(childTree, childValue, childOnChange, void 0, makeRenderChild(childPath), childPath, options.widgets);
+	};
+	return renderField(tree, options.value, options.onChange ?? noop, void 0, makeRenderChild(options.rootPath), options.rootPath, options.widgets);
 }
 function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets }) {
 	const rootDoc = toDoc(doc);
@@ -42,6 +59,7 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 	const securityReqs = getSecurityRequirements(parsed, path, method);
 	const securitySchemes = getSecuritySchemes(parsed);
 	const callbacks = listCallbacks(parsed, path, method);
+	const instancePrefix = sanitisePrefix(useId());
 	return /* @__PURE__ */ jsxs("section", {
 		"data-operation": `${method.toUpperCase()} ${path}`,
 		children: [
@@ -57,7 +75,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 					parameters: resolved.parameters,
 					rootDoc,
 					meta,
-					widgets
+					widgets,
+					idPrefix: joinPath(instancePrefix, "params")
 				})]
 			}),
 			resolved.requestBody?.schema !== void 0 && /* @__PURE__ */ jsxs("section", {
@@ -77,7 +96,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 						onChange: onRequestBodyChange,
 						fields: requestBodyFields,
 						meta,
-						widgets
+						widgets,
+						rootPath: joinPath(instancePrefix, "requestBody")
 					})
 				]
 			}),
@@ -90,7 +110,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 					meta,
 					widgets,
 					path,
-					method
+					method,
+					idPrefix: joinPath(instancePrefix, `response-${response.statusCode}`)
 				}, response.statusCode))]
 			})
 		]
@@ -99,6 +120,7 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 function ApiParameters({ schema: doc, path, method, meta, overrides, widgets }) {
 	const rootDoc = toDoc(doc);
 	const params = resolveParameters(rootDoc, path, method);
+	const instancePrefix = sanitisePrefix(useId());
 	if (params.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-parameters": true,
@@ -107,13 +129,15 @@ function ApiParameters({ schema: doc, path, method, meta, overrides, widgets })
 			rootDoc,
 			overrides,
 			meta,
-			widgets
+			widgets,
+			idPrefix: instancePrefix
 		})]
 	});
 }
 function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets }) {
 	const rootDoc = toDoc(doc);
 	const requestBody = resolveRequestBody(rootDoc, path, method);
+	const instancePrefix = sanitisePrefix(useId());
 	if (requestBody?.schema === void 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-request-body": true,
@@ -132,7 +156,8 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 				onChange,
 				fields,
 				meta,
-				widgets
+				widgets,
+				rootPath: instancePrefix
 			})
 		]
 	});
@@ -140,6 +165,7 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets }) {
 	const rootDoc = toDoc(doc);
 	const response = resolveResponse(rootDoc, path, method, status);
+	const instancePrefix = sanitisePrefix(useId());
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": status,
 		children: [
@@ -156,7 +182,8 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields, w
 		meta,
 		widgets,
 		path,
-		method
+		method,
+		idPrefix: instancePrefix
 	});
 }
 function OperationHeader({ operation }) {
@@ -173,7 +200,7 @@ function OperationHeader({ operation }) {
 		})
 	] });
 }
-function ParameterList({ parameters, rootDoc, overrides, meta, widgets }) {
+function ParameterList({ parameters, rootDoc, overrides, meta, widgets, idPrefix }) {
 	return /* @__PURE__ */ jsx(Fragment, { children: parameters.map((param) => /* @__PURE__ */ jsxs("div", {
 		"data-parameter": param.name,
 		children: [
@@ -187,12 +214,13 @@ function ParameterList({ parameters, rootDoc, overrides, meta, widgets }) {
 			}),
 			renderSchema(param.schema ?? { type: "string" }, rootDoc, {
 				meta: buildParamMeta(param, overrides, meta),
-				widgets
+				widgets,
+				rootPath: joinPath(idPrefix, param.name)
 			})
 		]
 	}, param.name)) });
 }
-function ResponseCard({ response, rootDoc, value, fields, meta, widgets, path, method }) {
+function ResponseCard({ response, rootDoc, value, fields, meta, widgets, path, method, idPrefix }) {
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": response.statusCode,
 		children: [
@@ -217,7 +245,8 @@ function ResponseCard({ response, rootDoc, value, fields, meta, widgets, path, m
 					readOnly: true,
 					...meta
 				},
-				widgets
+				widgets,
+				rootPath: idPrefix
 			}),
 			/* @__PURE__ */ jsx(ApiResponseHeaders, { headers: response.headers }),
 			/* @__PURE__ */ jsx(ApiLinks, { links })

package/dist/react/SchemaComponent.d.mts

@@ -1,7 +1,7 @@
 import { M as WalkedField, T as SchemaMeta, d as FieldOverrides, u as FieldOverride } from "../types-D_5ST7SS.mjs";
 import { t as Diagnostic } from "../diagnostics-DzbZmcLI.mjs";
 import { t as SchemaError } from "../errors-C5zRC2PU.mjs";
-import { l as RenderProps, r as ComponentResolver } from "../renderer-BdSqllx5.mjs";
+import { l as RenderProps, r as ComponentResolver } from "../renderer-B3s8o2B8.mjs";
 import { c as ResolveOpenAPIRef, s as PathOfType, t as FromJSONSchema } from "../typeInference-k7FXfTVO.mjs";
 import { z } from "zod";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
@@ -70,6 +70,13 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
   description?: string;
   /** Instance-scoped widgets — override context and global widgets. */
   widgets?: WidgetMap;
+  /**
+   * Prefix used for every input `id`/label `htmlFor` in this component
+   * subtree. Defaults to a per-instance value from `useId()` so multiple
+   * `<SchemaComponent>` instances on the same page never collide. Override
+   * for deterministic ids in screenshot tests.
+   */
+  idPrefix?: string;
 }
 declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined>({
   schema: schemaInput,
@@ -86,9 +93,30 @@ declare function SchemaComponent<T = unknown, Ref extends string | undefined = u
   readOnly,
   writeOnly,
   description,
-  widgets: instanceWidgets
+  widgets: instanceWidgets,
+  idPrefix
 }: SchemaComponentProps<T, Ref>): ReactNode;
-declare function renderField(tree: WalkedField, value: unknown, onChange: (v: unknown) => void, userResolver: ComponentResolver | undefined, renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void) => ReactNode, instanceWidgets?: WidgetMap, contextWidgets?: WidgetMap, depth?: number): ReactNode;
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare function joinPath(parent: string, suffix: string | undefined): string;
+/**
+ * Normalise a `useId()` value into a DOM-id-safe prefix. React's `useId`
+ * returns values containing `:` characters (e.g. `«:r0:»`) which are
+ * invalid in CSS selectors. Replace any run of non-alphanumeric characters
+ * with a single hyphen and trim leading/trailing hyphens.
+ */
+declare function sanitisePrefix(value: string): string;
+declare function renderField(tree: WalkedField, value: unknown, onChange: (v: unknown) => void, userResolver: ComponentResolver | undefined, renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void, pathSuffix?: string) => ReactNode, path: string, instanceWidgets?: WidgetMap, contextWidgets?: WidgetMap, depth?: number): ReactNode;
 /**
  * Infer the schema's output type for SchemaField path inference.
  */
@@ -125,4 +153,4 @@ declare function SchemaField<T = unknown, Ref extends string | undefined = undef
   onValidationError
 }: SchemaFieldProps<T, Ref, P>): ReactNode;
 //#endregion
-export { SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, WidgetMap, registerWidget, renderField };
+export { ROOT_PATH, SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, WidgetMap, joinPath, registerWidget, renderField, sanitisePrefix };

package/dist/react/SchemaComponent.mjs

@@ -8,7 +8,7 @@ import { headlessResolver } from "./headless.mjs";
 import { resolvePath, resolveValue, setNestedValue } from "./fieldPath.mjs";
 import { z } from "zod";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { createContext, isValidElement, useCallback, useContext, useMemo } from "react";
+import { createContext, isValidElement, useCallback, useContext, useId, useMemo } from "react";
 //#region src/react/SchemaComponent.tsx
 /**
 * <SchemaComponent> — renders UI from Zod, JSON Schema, or OpenAPI schemas.
@@ -46,9 +46,11 @@ 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 }) {
+function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, onDiagnostic, strict, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets, idPrefix }) {
 	const userResolver = useContext(UserResolverContext);
 	const contextWidgets = useContext(WidgetsContext);
+	const generatedId = useId();
+	const rootPath = idPrefix ?? sanitisePrefix(generatedId);
 	const mergedMeta = useMemo(() => {
 		const merged = { ...componentMeta };
 		if (readOnly === true) merged.readOnly = true;
@@ -108,11 +110,40 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 		...diagnostics !== void 0 ? { diagnostics } : {}
 	};
 	const tree = walk(jsonSchema, walkOptions);
-	const makeRenderChild = (currentDepth) => (childTree, childValue, childOnChange) => {
-		return renderField(childTree, childValue, childOnChange, userResolver, makeRenderChild(currentDepth + 1), instanceWidgets, contextWidgets, currentDepth + 1);
+	const makeRenderChild = (currentDepth, parentPath) => (childTree, childValue, childOnChange, pathSuffix) => {
+		const childPath = joinPath(parentPath, pathSuffix);
+		return renderField(childTree, childValue, childOnChange, userResolver, makeRenderChild(currentDepth + 1, childPath), childPath, instanceWidgets, contextWidgets, currentDepth + 1);
 	};
-	const renderChild = makeRenderChild(0);
-	return renderField(tree, value ?? tree.defaultValue, handleChange, userResolver, renderChild, instanceWidgets, contextWidgets, 0);
+	const renderChild = makeRenderChild(0, rootPath);
+	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.
+*/
+function joinPath(parent, suffix) {
+	if (suffix === void 0 || suffix.length === 0) return parent;
+	if (parent.length === 0) return suffix;
+	return `${parent}.${suffix}`;
+}
+/**
+* Normalise a `useId()` value into a DOM-id-safe prefix. React's `useId`
+* returns values containing `:` characters (e.g. `«:r0:»`) which are
+* invalid in CSS selectors. Replace any run of non-alphanumeric characters
+* with a single hyphen and trim leading/trailing hyphens.
+*/
+function sanitisePrefix(value) {
+	const sanitised = value.replace(/[^a-zA-Z0-9_]+/g, "-").replace(/^-+|-+$/g, "");
+	if (sanitised.length === 0) throw new Error(`Cannot derive a DOM-safe id prefix from "${value}". Pass an explicit idPrefix prop.`);
+	return sanitised;
 }
 function runValidation(zodSchema, jsonSchema, value) {
 	if (zodSchema !== void 0 && isObject(zodSchema)) {
@@ -134,7 +165,8 @@ function runValidation(zodSchema, jsonSchema, value) {
 }
 /** Maximum rendering depth before treating a field as recursive. */
 const MAX_RENDER_DEPTH = 10;
-function renderField(tree, value, onChange, userResolver, renderChild, instanceWidgets, contextWidgets, depth = 0) {
+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: [
@@ -147,7 +179,7 @@ function renderField(tree, value, onChange, userResolver, renderChild, instanceW
 	if (typeof componentHint === "string") {
 		const widget = instanceWidgets?.get(componentHint) ?? contextWidgets?.get(componentHint) ?? globalWidgets.get(componentHint);
 		if (widget !== void 0) {
-			const result = widget(buildRenderProps(tree, value, onChange, renderChild));
+			const result = widget(buildRenderProps(tree, value, onChange, renderChild, path));
 			if (result !== void 0 && result !== null) {
 				if (isValidElement(result)) return result;
 				if (typeof result === "string" || typeof result === "number") return result;
@@ -160,7 +192,7 @@ function renderField(tree, value, onChange, userResolver, renderChild, instanceW
 	if (renderFn !== void 0) {
 		let result;
 		try {
-			result = renderFn(buildRenderProps(tree, value, onChange, renderChild));
+			result = renderFn(buildRenderProps(tree, value, onChange, renderChild, path));
 		} catch (err) {
 			throw new SchemaRenderError(err instanceof Error ? err.message : `Render function threw for type "${tree.type}"`, tree, tree.type, err);
 		}
@@ -171,7 +203,7 @@ function renderField(tree, value, onChange, userResolver, renderChild, instanceW
 	if (value === void 0 || value === null) return /* @__PURE__ */ jsx("span", { children: "—" });
 	return /* @__PURE__ */ jsx("span", { children: typeof value === "string" ? value : JSON.stringify(value) });
 }
-function buildRenderProps(tree, value, onChange, renderChild) {
+function buildRenderProps(tree, value, onChange, renderChild, path) {
 	const props = {
 		value,
 		onChange,
@@ -179,7 +211,7 @@ function buildRenderProps(tree, value, onChange, renderChild) {
 		writeOnly: tree.editability === "input",
 		meta: tree.meta,
 		constraints: tree.constraints,
-		path: "",
+		path,
 		tree,
 		renderChild
 	};
@@ -203,6 +235,7 @@ function buildRenderProps(tree, value, onChange, renderChild) {
 function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange, meta: fieldMeta, validate, onValidationError }) {
 	const userResolver = useContext(UserResolverContext);
 	const contextWidgets = useContext(WidgetsContext);
+	const generatedId = useId();
 	let jsonSchema;
 	let zodSchema;
 	let rootMeta;
@@ -240,10 +273,12 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 		onChange,
 		onValidationError
 	]);
-	const makeRenderChild = (currentDepth) => (childTree, childValue, childOnChange) => {
-		return renderField(childTree, childValue, childOnChange, userResolver, makeRenderChild(currentDepth + 1), void 0, contextWidgets, currentDepth + 1);
+	const makeRenderChild = (currentDepth, parentPath) => (childTree, childValue, childOnChange, pathSuffix) => {
+		const childPath = joinPath(parentPath, pathSuffix);
+		return renderField(childTree, childValue, childOnChange, userResolver, makeRenderChild(currentDepth + 1, childPath), childPath, void 0, contextWidgets, currentDepth + 1);
 	};
-	return renderField(fieldTree, fieldValue, handleChange, userResolver, makeRenderChild(0), void 0, contextWidgets, 0);
+	const rootPath = joinPath(sanitisePrefix(generatedId), path);
+	return renderField(fieldTree, fieldValue, handleChange, userResolver, makeRenderChild(0, rootPath), rootPath, void 0, contextWidgets, 0);
 }
 /**
 * Dispatch Zod errors to per-field onValidationError callbacks.
@@ -290,4 +325,4 @@ function detectNormalisationKind(err) {
 	return "unknown";
 }
 //#endregion
-export { SchemaComponent, SchemaField, SchemaProvider, registerWidget, renderField };
+export { ROOT_PATH, SchemaComponent, SchemaField, SchemaProvider, joinPath, registerWidget, renderField, sanitisePrefix };

package/dist/react/SchemaView.d.mts

@@ -1,6 +1,6 @@
 import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
 import { t as Diagnostic } from "../diagnostics-DzbZmcLI.mjs";
-import { r as ComponentResolver } from "../renderer-BdSqllx5.mjs";
+import { r as ComponentResolver } from "../renderer-B3s8o2B8.mjs";
 import { WidgetMap } from "./SchemaComponent.mjs";
 import { ReactNode } from "react";
 
@@ -30,6 +30,12 @@ interface SchemaViewProps {
   onDiagnostic?: (diagnostic: Diagnostic) => void;
   /** When true, any diagnostic becomes a thrown error. */
   strict?: boolean;
+  /**
+   * Prefix used for every input `id`/label `htmlFor` in this view subtree.
+   * Defaults to a per-instance value from `useId()`; pass a deterministic
+   * value when stable ids matter (e.g. snapshot tests).
+   */
+  idPrefix?: string;
 }
 /**
  * Server-safe schema renderer — no hooks, no context, no state.
@@ -47,7 +53,8 @@ declare function SchemaView({
   resolver,
   widgets,
   onDiagnostic,
-  strict
+  strict,
+  idPrefix
 }: SchemaViewProps): ReactNode;
 //#endregion
 export { SchemaView, SchemaViewProps };

package/dist/react/SchemaView.mjs

@@ -3,8 +3,9 @@ import { normaliseSchema } from "../core/adapter.mjs";
 import { getRenderFunction, mergeResolvers } from "../core/renderer.mjs";
 import { walk } from "../core/walker.mjs";
 import { headlessResolver } from "./headless.mjs";
+import { joinPath, sanitisePrefix } from "./SchemaComponent.mjs";
 import { jsx } from "react/jsx-runtime";
-import { createElement, isValidElement } from "react";
+import { createElement, isValidElement, useId } from "react";
 //#region src/react/SchemaView.tsx
 /**
 * React Server Component for read-only schema rendering.
@@ -37,7 +38,9 @@ function noop() {}
 * Always renders in read-only mode. For editable forms, use
 * `<SchemaComponent>` with `"use client"`.
 */
-function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: componentMeta, description, resolver, widgets, onDiagnostic, strict }) {
+function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: componentMeta, description, resolver, widgets, onDiagnostic, strict, idPrefix }) {
+	const generatedId = useId();
+	const rootPath = idPrefix ?? sanitisePrefix(generatedId);
 	const mergedMeta = {
 		...componentMeta,
 		readOnly: true
@@ -68,18 +71,21 @@ 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) => (childTree, childValue) => {
+	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)`));
-		return renderFieldServer(childTree, childValue, userResolver, makeRenderChild(currentDepth + 1), widgets);
+		return renderFieldServer(childTree, childValue, userResolver, makeRenderChild(currentDepth + 1, childPath), childPath, widgets);
 	};
-	const renderChild = makeRenderChild(0);
-	return renderFieldServer(tree, value ?? tree.defaultValue, userResolver, renderChild, widgets);
+	const renderChild = makeRenderChild(0, rootPath);
+	return renderFieldServer(tree, value ?? tree.defaultValue, userResolver, renderChild, rootPath, widgets);
 }
-function renderFieldServer(tree, value, resolver, renderChild, widgets) {
+function renderFieldServer(tree, value, resolver, renderChild, path, widgets) {
+	if (path.length === 0) throw new Error("renderFieldServer requires a non-empty path. Pass ROOT_PATH at the root and join children via joinPath().");
 	const componentHint = tree.meta.component;
 	if (typeof componentHint === "string") {
 		const widget = widgets?.get(componentHint);
 		if (widget !== void 0) {
+			const wrapRenderChild = (childTree, childValue, _childOnChange, pathSuffix) => renderChild(childTree, childValue, pathSuffix);
 			const result = widget({
 				value,
 				onChange: noop,
@@ -87,9 +93,9 @@ function renderFieldServer(tree, value, resolver, renderChild, widgets) {
 				writeOnly: false,
 				meta: tree.meta,
 				constraints: tree.constraints,
-				path: "",
+				path,
 				tree,
-				renderChild: (childTree, childValue) => renderChild(childTree, childValue)
+				renderChild: wrapRenderChild
 			});
 			if (result !== void 0 && result !== null) {
 				if (isValidElement(result)) return result;
@@ -106,9 +112,9 @@ function renderFieldServer(tree, value, resolver, renderChild, widgets) {
 			writeOnly: false,
 			meta: tree.meta,
 			constraints: tree.constraints,
-			path: "",
+			path,
 			tree,
-			renderChild: (childTree, childValue) => renderChild(childTree, childValue)
+			renderChild: (childTree, childValue, _childOnChange, pathSuffix) => renderChild(childTree, childValue, pathSuffix)
 		};
 		if (tree.type === "enum") props.enumValues = tree.enumValues;
 		if (tree.type === "array" && tree.element !== void 0) props.element = tree.element;

package/dist/react/headless.d.mts

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

package/dist/react/headlessRenderers.d.mts

@@ -1,4 +1,5 @@
-import { l as RenderProps } from "../renderer-BdSqllx5.mjs";
+import { M as WalkedField } from "../types-D_5ST7SS.mjs";
+import { l as RenderProps } from "../renderer-B3s8o2B8.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/headlessRenderers.d.ts
@@ -7,17 +8,55 @@ import { ReactNode } from "react";
  * Returns `null` for unrecognised values.
  */
 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`).
+ *
+ * Dots and bracket indices in paths are converted to hyphens to keep the
+ * id valid as a CSS selector and predictable in test queries.
+ */
+declare function inputId(path: string): string;
 declare function renderString(props: RenderProps): ReactNode;
 declare function renderNumber(props: RenderProps): ReactNode;
 declare function renderBoolean(props: RenderProps): ReactNode;
 declare function renderEnum(props: RenderProps): ReactNode;
 declare function renderObject(props: RenderProps): ReactNode;
+/**
+ * Compute the default value for a freshly added record entry based on the
+ * record's value-type schema. Mirrors the read of `defaultValue` used
+ * elsewhere in the renderer, falling back to a type-appropriate empty value.
+ */
+declare function defaultRecordValue(valueType: WalkedField): unknown;
+/**
+ * Generate a unique, currently-unused key for a new record entry.
+ * Picks the first of `key`, `key-1`, `key-2`, … that is not in `existing`.
+ */
+declare function nextRecordKey(existing: readonly string[], base?: string): string;
+/**
+ * Rename a key in an object while preserving insertion order. Returns the
+ * original object reference when the rename is a no-op (oldKey === newKey)
+ * or when newKey collides with an existing key.
+ */
+declare function renameRecordKey(obj: Record<string, unknown>, oldKey: string, newKey: string): Record<string, unknown>;
 declare function renderRecord(props: RenderProps): ReactNode;
 declare function renderArray(props: RenderProps): ReactNode;
 declare function renderUnion(props: RenderProps): ReactNode;
 declare function renderDiscriminatedUnion(props: RenderProps): ReactNode;
+/**
+ * Pure helper: convert a tab index into the new value the discriminated
+ * union should emit. Returns `undefined` when the index is out of bounds.
+ *
+ * Extracted from `DiscriminatedUnionTabs` so the contract is unit-testable
+ * without rendering the tabs component (which relies on React hooks).
+ */
+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;
 declare function renderUnknown(props: RenderProps): ReactNode;
 //#endregion
-export { renderArray, renderBoolean, renderDiscriminatedUnion, renderEnum, renderFile, renderNumber, renderObject, renderRecord, renderRecursive, renderString, renderUnion, renderUnknown, toReactNode };
+export { defaultRecordValue, discriminatedUnionValueForTab, inputId, nextRecordKey, renameRecordKey, renderArray, renderBoolean, renderDiscriminatedUnion, renderEnum, renderFile, renderNumber, renderObject, renderRecord, renderRecursive, renderString, renderUnion, renderUnknown, toReactNode };