schema-components 1.16.3 → 1.18.0

package/dist/openapi/bundle.mjs

@@ -29,28 +29,38 @@ import { isObject } from "../core/guards.mjs";
 *
 * Walks every $ref in the document. For external refs (not starting with `#`),
 * calls the resolver to fetch the external document, extracts the referenced
-* schema, inlines it into `components.schemas` with a synthesised name, and
-* rewrites the $ref to point to the inlined copy.
+* schema, inlines it into `components.schemas` under a synthesised name, and
+* rewrites the original $ref to point at the new internal location
+* (`#/components/schemas/<name>`).
+*
+* Identical external refs share a single entry — the second occurrence of
+* the same `(uri, fragment)` pair reuses the name produced for the first.
+* Name collisions between different refs are resolved by suffixing a counter.
 *
 * The resolver is called once per unique URI and the result is cached.
 *
-* Returns a deep-cloned document with all external refs resolved.
-* The original document is never mutated.
+* Returns a deep-cloned document with all external refs replaced by internal
+* refs. The original document is never mutated.
 */
 async function bundleOpenApiDoc(doc, resolver) {
 	const result = structuredClone(doc);
 	const uriCache = /* @__PURE__ */ new Map();
+	const inlineCache = /* @__PURE__ */ new Map();
 	if (!isObject(result.components)) result.components = {};
-	if (!isObject(result.components)) result.components = {};
-	if (isObject(result.components) && !isObject(result.components.schemas)) result.components.schemas = {};
-	await walkAndInline(result, uriCache, resolver);
+	const components = result.components;
+	if (!isObject(components)) throw new Error("bundleOpenApiDoc: components is not an object");
+	if (!isObject(components.schemas)) components.schemas = {};
+	const schemasNode = components.schemas;
+	if (!isObject(schemasNode)) throw new Error("bundleOpenApiDoc: components.schemas is not an object");
+	await walkAndInline(result, schemasNode, uriCache, inlineCache, resolver);
 	return result;
 }
 /**
 * Walk a document tree, find external $ref strings, resolve them,
-* inline the targets, and rewrite the refs.
+* inline the targets into `components.schemas`, and rewrite each $ref
+* to point at the new internal location.
 */
-async function walkAndInline(node, uriCache, resolver) {
+async function walkAndInline(node, schemasNode, uriCache, inlineCache, resolver) {
 	if (!isObject(node)) return;
 	if (typeof node.$ref === "string" && !node.$ref.startsWith("#")) {
 		const ref = node.$ref;
@@ -66,15 +76,21 @@ async function walkAndInline(node, uriCache, resolver) {
 			}
 		}
 		if (externalDoc !== void 0) {
-			const target = resolveFragment(externalDoc, fragment);
-			if (isObject(target)) {
-				delete node.$ref;
-				for (const [key, value] of Object.entries(target)) node[key] = value;
+			const cacheKey = `${uri}${fragment}`;
+			let inlinedName = inlineCache.get(cacheKey);
+			if (inlinedName === void 0) {
+				const target = resolveFragment(externalDoc, fragment);
+				if (isObject(target)) {
+					inlinedName = registerInline(schemasNode, uri, fragment, target);
+					inlineCache.set(cacheKey, inlinedName);
+					await walkAndInline(schemasNode[inlinedName], schemasNode, uriCache, inlineCache, resolver);
+				}
 			}
+			if (inlinedName !== void 0) node.$ref = `#/components/schemas/${inlinedName}`;
 		}
 	}
-	for (const value of Object.values(node)) if (isObject(value)) await walkAndInline(value, uriCache, resolver);
-	else if (Array.isArray(value)) for (const item of value) await walkAndInline(item, uriCache, resolver);
+	for (const value of Object.values(node)) if (isObject(value)) await walkAndInline(value, schemasNode, uriCache, inlineCache, resolver);
+	else if (Array.isArray(value)) for (const item of value) await walkAndInline(item, schemasNode, uriCache, inlineCache, resolver);
 }
 /**
 * Resolve a JSON Pointer fragment within a document.
@@ -91,5 +107,47 @@ function resolveFragment(doc, fragment) {
 	}
 	return isObject(current) ? current : void 0;
 }
+/**
+* Derive a candidate identifier for an inlined external schema. Prefers
+* the last meaningful segment of the JSON Pointer fragment; falls back
+* to the URI's filename (sans extension), then to a generic prefix.
+*/
+function deriveCandidateName(uri, fragment) {
+	if (fragment.startsWith("#/")) {
+		const last = fragment.slice(2).split("/").at(-1);
+		if (last !== void 0 && last.length > 0) return sanitiseName(last);
+	}
+	const pathOnly = uri.split(/[?#]/)[0] ?? uri;
+	const lastSlash = pathOnly.lastIndexOf("/");
+	const filename = lastSlash >= 0 ? pathOnly.slice(lastSlash + 1) : pathOnly;
+	const dot = filename.lastIndexOf(".");
+	const stem = dot > 0 ? filename.slice(0, dot) : filename;
+	if (stem.length > 0) return sanitiseName(stem);
+	return "ExternalSchema";
+}
+/**
+* Sanitise a string into a JSON Pointer-safe identifier: alphanumerics
+* and underscores only. An empty result falls back to "Schema".
+*/
+function sanitiseName(raw) {
+	const cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
+	return cleaned.length > 0 ? cleaned : "Schema";
+}
+/**
+* Place the resolved target into `components.schemas` under a unique
+* name derived from the ref, and return the chosen name. Collisions
+* with existing entries are resolved by suffixing a counter.
+*/
+function registerInline(schemasNode, uri, fragment, target) {
+	const base = deriveCandidateName(uri, fragment);
+	let name = base;
+	let counter = 2;
+	while (name in schemasNode) {
+		name = `${base}_${String(counter)}`;
+		counter++;
+	}
+	schemasNode[name] = structuredClone(target);
+	return name;
+}
 //#endregion
 export { bundleOpenApiDoc };

package/dist/openapi/components.d.mts

@@ -1,5 +1,5 @@
 import { T as SchemaMeta, u as FieldOverride } from "../types-D_5ST7SS.mjs";
-import { i as InferResponseFields, n as InferParameterOverrides, r as InferRequestBodyFields, u as UnsafeFields } from "../typeInference-k7FXfTVO.mjs";
+import { a as InferResponseFields, d as UnsafeFields, i as InferRequestBodyFields, r as InferParameterOverrides } from "../typeInference-5JiqIZ8t.mjs";
 import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/components.mjs

@@ -1,39 +1,46 @@
-import { toRecordOrUndefined } from "../core/guards.mjs";
-import { SchemaNormalisationError } from "../core/errors.mjs";
-import { normaliseSchema } from "../core/adapter.mjs";
+import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
 import { walk } from "../core/walker.mjs";
+import { joinPath, renderField, sanitisePrefix } from "../react/SchemaComponent.mjs";
 import { ApiCallbacks } from "./ApiCallbacks.mjs";
 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 { getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, toDoc } from "./resolve.mjs";
+import { useId } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#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;
-	let rootMeta;
-	try {
-		const normalised = normaliseSchema(schema);
-		jsonSchema = normalised.jsonSchema;
-		rootMeta = normalised.rootMeta;
-	} catch (err) {
-		throw new SchemaNormalisationError(err instanceof Error ? err.message : "Failed to normalise schema", schema, "unknown");
-	}
+	if (!isObject(schema)) throw new Error("renderSchema received a non-object schema from the resolver.");
+	const rootMeta = extractRootMetaFromSchema(schema);
 	const componentMeta = {};
 	if (options.readOnly === true) componentMeta.readOnly = true;
 	if (options.meta !== void 0) for (const [k, v] of Object.entries(options.meta)) componentMeta[k] = v;
-	const walkOpts = {
+	const tree = walk(schema, {
 		componentMeta,
 		rootMeta,
 		fieldOverrides: toRecordOrUndefined(options.fields),
 		rootDocument
+	});
+	const makeRenderChild = (parentPath) => (childTree, childValue, childOnChange, pathSuffix) => {
+		const childPath = joinPath(parentPath, pathSuffix);
+		return renderField(childTree, childValue, childOnChange, void 0, makeRenderChild(childPath), childPath, options.widgets);
 	};
-	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);
+	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 +49,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 +65,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 +86,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 						onChange: onRequestBodyChange,
 						fields: requestBodyFields,
 						meta,
-						widgets
+						widgets,
+						rootPath: joinPath(instancePrefix, "requestBody")
 					})
 				]
 			}),
@@ -90,7 +100,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 					meta,
 					widgets,
 					path,
-					method
+					method,
+					idPrefix: joinPath(instancePrefix, `response-${response.statusCode}`)
 				}, response.statusCode))]
 			})
 		]
@@ -99,6 +110,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 +119,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 +146,8 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 				onChange,
 				fields,
 				meta,
-				widgets
+				widgets,
+				rootPath: instancePrefix
 			})
 		]
 	});
@@ -140,6 +155,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 +172,8 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields, w
 		meta,
 		widgets,
 		path,
-		method
+		method,
+		idPrefix: instancePrefix
 	});
 }
 function OperationHeader({ operation }) {
@@ -173,7 +190,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 +204,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 +235,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 })
@@ -233,5 +252,20 @@ function buildParamMeta(param, overrides, meta) {
 	if (meta !== void 0) for (const [k, v] of Object.entries(meta)) result[k] = v;
 	return Object.keys(result).length > 0 ? result : void 0;
 }
+/**
+* Extract root-level meta (title, description, readOnly, etc.) from a
+* JSON Schema node. Mirrors `extractRootMetaFromJson` in the adapter so
+* pre-normalised schemas (extracted from `getParsed`) still surface root
+* meta to the walker without an extra adapter round-trip.
+*/
+function extractRootMetaFromSchema(jsonSchema) {
+	const meta = {};
+	if (jsonSchema.readOnly === true) meta.readOnly = true;
+	if (jsonSchema.writeOnly === true) meta.writeOnly = true;
+	if (typeof jsonSchema.description === "string") meta.description = jsonSchema.description;
+	if (typeof jsonSchema.title === "string") meta.title = jsonSchema.title;
+	if (typeof jsonSchema.deprecated === "boolean") meta.deprecated = jsonSchema.deprecated;
+	return Object.keys(meta).length > 0 ? meta : void 0;
+}
 //#endregion
 export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse };

package/dist/openapi/parser.mjs

@@ -79,22 +79,22 @@ function getParameters(parsed, path, method) {
 	if (pathItem === void 0) return [];
 	const operation = getProperty(pathItem, method);
 	if (!isObject(operation)) return [];
-	const pathParams = extractParameterList(getProperty(pathItem, "parameters"));
-	const opParams = extractParameterList(getProperty(operation, "parameters"));
+	const pathParams = extractParameterList(parsed.doc, getProperty(pathItem, "parameters"));
+	const opParams = extractParameterList(parsed.doc, getProperty(operation, "parameters"));
 	const map = /* @__PURE__ */ new Map();
 	for (const param of pathParams) map.set(`${param.name}:${param.location}`, param);
 	for (const param of opParams) map.set(`${param.name}:${param.location}`, param);
 	return [...map.values()];
 }
-function extractParameterList(parameters) {
+function extractParameterList(doc, parameters) {
 	if (!Array.isArray(parameters)) return [];
 	const result = [];
 	for (const param of parameters) {
 		if (!isObject(param)) continue;
-		const name = getProperty(param, "name");
-		const location = getProperty(param, "in");
+		const resolved = resolveParam(doc, param);
+		const name = getProperty(resolved, "name");
+		const location = getProperty(resolved, "in");
 		if (typeof name !== "string" || typeof location !== "string") continue;
-		const resolved = resolveParam(param);
 		const schema = getProperty(resolved, "schema");
 		result.push({
 			name,
@@ -107,10 +107,10 @@ function extractParameterList(parameters) {
 	}
 	return result;
 }
-function resolveParam(param) {
+function resolveParam(doc, param) {
 	const ref = getProperty(param, "$ref");
 	if (typeof ref === "string" && ref.startsWith("#/")) {
-		const resolved = resolveRefInDoc(param, ref);
+		const resolved = resolveRefInDoc(doc, ref);
 		if (resolved !== void 0) return resolved;
 	}
 	return param;

package/dist/openapi/resolve.d.mts

@@ -2,8 +2,19 @@ import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequest
 
 //#region src/openapi/resolve.d.ts
 /**
- * Parse and cache an OpenAPI document. Returns cached version if
- * the same object identity has been seen before.
+ * Parse and cache an OpenAPI document. Returns the cached parse for the
+ * same object identity.
+ *
+ * Before parsing, the document is run through the version-aware
+ * normalisation pipeline (`normaliseOpenApiSchemas`) so OpenAPI 3.0.x
+ * keywords (`nullable`, `discriminator`, `example`) and Swagger 2.0
+ * documents are converted to canonical Draft 2020-12 form. The parser
+ * and downstream extractors (`getRequestBody`, `getResponses`, etc.) then
+ * observe schemas in the same form `<SchemaComponent>` does, keeping the
+ * OpenAPI components on the same pipeline as the top-level adapter.
+ *
+ * The cache is keyed by the caller-supplied document so subsequent calls
+ * with the same input bypass both normalisation and parsing.
  */
 declare function getParsed(doc: Record<string, unknown>): OpenApiDocument;
 /**

package/dist/openapi/resolve.mjs

@@ -1,4 +1,6 @@
 import { isObject } from "../core/guards.mjs";
+import { detectOpenApiVersion } from "../core/version.mjs";
+import { i as normaliseOpenApiSchemas } from "../normalise-tL9FckAk.mjs";
 import { getParameters, getRequestBody, getResponses, listOperations, parseOpenApiDocument } from "./parser.mjs";
 //#region src/openapi/resolve.ts
 /**
@@ -10,14 +12,28 @@ import { getParameters, getRequestBody, getResponses, listOperations, parseOpenA
 */
 const docCache = /* @__PURE__ */ new WeakMap();
 /**
-* Parse and cache an OpenAPI document. Returns cached version if
-* the same object identity has been seen before.
+* Parse and cache an OpenAPI document. Returns the cached parse for the
+* same object identity.
+*
+* Before parsing, the document is run through the version-aware
+* normalisation pipeline (`normaliseOpenApiSchemas`) so OpenAPI 3.0.x
+* keywords (`nullable`, `discriminator`, `example`) and Swagger 2.0
+* documents are converted to canonical Draft 2020-12 form. The parser
+* and downstream extractors (`getRequestBody`, `getResponses`, etc.) then
+* observe schemas in the same form `<SchemaComponent>` does, keeping the
+* OpenAPI components on the same pipeline as the top-level adapter.
+*
+* The cache is keyed by the caller-supplied document so subsequent calls
+* with the same input bypass both normalisation and parsing.
 */
 function getParsed(doc) {
 	const cached = docCache.get(doc);
 	if (cached !== void 0) return cached;
-	const parsed = parseOpenApiDocument(doc);
+	const version = detectOpenApiVersion(doc);
+	const normalisedDoc = version !== void 0 ? normaliseOpenApiSchemas(doc, version) : doc;
+	const parsed = parseOpenApiDocument(normalisedDoc);
 	docCache.set(doc, parsed);
+	if (normalisedDoc !== doc) docCache.set(normalisedDoc, parsed);
 	return parsed;
 }
 /**

package/dist/react/SchemaComponent.d.mts

@@ -1,11 +1,11 @@
 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 Diagnostic } from "../diagnostics-BYk63jsC.mjs";
 import { t as SchemaError } from "../errors-C5zRC2PU.mjs";
-import { l as RenderProps, r as ComponentResolver } from "../renderer-BdSqllx5.mjs";
-import { c as ResolveOpenAPIRef, s as PathOfType, t as FromJSONSchema } from "../typeInference-k7FXfTVO.mjs";
+import { l as RenderProps, r as ComponentResolver } from "../renderer-DXo-rXHJ.mjs";
+import { c as PathOfType, l as ResolveOpenAPIRef, n as FromJSONSchema } from "../typeInference-5JiqIZ8t.mjs";
 import { z } from "zod";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { ReactNode } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/react/SchemaComponent.d.ts
 /**
@@ -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 };