schema-components 1.3.3 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [1.4.0](https://github.com/Mearman/schema-components/compare/v1.3.3...v1.4.0) (2026-05-14)
+
+### Features
+
+* add scoped widget resolution at instance, context, and global levels ([b330baf](https://github.com/Mearman/schema-components/commit/b330baf183d00bebf999108f16c9dabd40c243be))
+
+### Documentation
+
+* update README with scoped widget resolution documentation ([21ac50d](https://github.com/Mearman/schema-components/commit/21ac50dc9a55144fc319fcf482ffad6a16585a27))
+
 ## [1.3.3](https://github.com/Mearman/schema-components/compare/v1.3.2...v1.3.3) (2026-05-14)
 
 ### Refactoring

package/README.md

@@ -434,7 +434,15 @@ Custom resolvers fall back to the default for any type you don't override.
 
 ## Custom widgets
 
-Register widgets by `.meta({ component })` hint:
+Widgets let you override rendering for specific fields using `.meta({ component: name })`. Three scopes are available, checked in order:
+
+1. **Instance** — `widgets` prop on `<SchemaComponent>`
+2. **Context** — `widgets` prop on `<SchemaProvider>`
+3. **Global** — `registerWidget()` for app-wide defaults
+
+If none match, the theme adapter or headless default handles the field.
+
+### Global registration
 
 ```tsx
 import { registerWidget } from "schema-components/react/SchemaComponent";
@@ -443,13 +451,65 @@ registerWidget("richtext", ({ value, onChange }) => (
   <RichTextEditor value={value} onChange={onChange} />
 ));
 
-// In schema
 const schema = z.object({
   bio: z.string().meta({ component: "richtext" }),
 });
 ```
 
-Resolution order: `.meta({ component })` → registered widget → theme adapter → headless default.
+### Context-scoped widgets
+
+Share widgets across a subtree via `<SchemaProvider>`:
+
+```tsx
+import { SchemaProvider } from "schema-components/react/SchemaComponent";
+import type { WidgetMap } from "schema-components/react/SchemaComponent";
+
+const adminWidgets: WidgetMap = new Map([
+  ["richtext", ({ value, onChange }) => <RichTextEditor value={value} onChange={onChange} />],
+  ["avatar", ({ value, onChange }) => <AvatarUploader value={value} onChange={onChange} />],
+]);
+
+<SchemaProvider resolver={shadcnResolver} widgets={adminWidgets}>
+  <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+  <SchemaComponent schema={profileSchema} value={profile} onChange={setProfile} />
+</SchemaProvider>
+```
+
+### Instance-scoped widgets
+
+Override widgets for a single form:
+
+```tsx
+const formWidgets: WidgetMap = new Map([
+  ["richtext", ({ value, onChange }) => <SimpleTextarea value={value} onChange={onChange} />],
+]);
+
+<SchemaComponent schema={formSchema} value={form} widgets={formWidgets} />
+```
+
+### Resolution order
+
+```.meta({ component }) hint → instance widgets → context widgets → global registerWidget() → theme adapter → headless default
+```
+
+Instance overrides context. Context overrides global. Unhinted fields skip the widget layer entirely.
+
+### `WidgetMap` type
+
+```tsx
+import type { WidgetMap } from "schema-components/react/SchemaComponent";
+
+// ReadonlyMap<string, (props: RenderProps) => unknown>
+const widgets: WidgetMap = new Map([
+  ["name", (props) => <MyInput {...props} />],
+]);
+```
+
+Server Components: `<SchemaView>` accepts a `widgets` prop directly (no React context available):
+
+```tsx
+<SchemaView schema={schema} value={data} widgets={serverWidgets} />
+```
 
 ## Validation
 

package/dist/openapi/components.d.mts

@@ -1,4 +1,5 @@
 import { c as InferResponseFields, m as SchemaMeta, o as InferParameterOverrides, r as FieldOverride, s as InferRequestBodyFields } from "../types-DDCD6Xnx.mjs";
+import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/components.d.ts
@@ -11,6 +12,8 @@ interface ApiOperationProps<Doc = unknown, Path extends string = string, Method
   responseValue?: unknown;
   meta?: SchemaMeta;
   requestBodyFields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 declare function ApiOperation<Doc = unknown, Path extends string = string, Method extends string = string>({
   schema: doc,
@@ -20,7 +23,8 @@ declare function ApiOperation<Doc = unknown, Path extends string = string, Metho
   onRequestBodyChange,
   responseValue,
   meta,
-  requestBodyFields
+  requestBodyFields,
+  widgets
 }: ApiOperationProps<Doc, Path, Method>): ReactNode;
 interface ApiParametersProps<Doc = unknown, Path extends string = string, Method extends string = string> {
   schema: Doc;
@@ -28,13 +32,16 @@ interface ApiParametersProps<Doc = unknown, Path extends string = string, Method
   method: Method;
   meta?: SchemaMeta;
   overrides?: Doc extends Record<string, unknown> ? InferParameterOverrides<Doc, Path, Method> : Record<string, FieldOverride>;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 declare function ApiParameters<Doc = unknown, Path extends string = string, Method extends string = string>({
   schema: doc,
   path,
   method,
   meta,
-  overrides
+  overrides,
+  widgets
 }: ApiParametersProps<Doc, Path, Method>): ReactNode;
 interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Method extends string = string> {
   schema: Doc;
@@ -44,6 +51,8 @@ interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Metho
   onChange?: (value: unknown) => void;
   meta?: SchemaMeta;
   fields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 declare function ApiRequestBody<Doc = unknown, Path extends string = string, Method extends string = string>({
   schema: doc,
@@ -52,7 +61,8 @@ declare function ApiRequestBody<Doc = unknown, Path extends string = string, Met
   value,
   onChange,
   meta,
-  fields
+  fields,
+  widgets
 }: ApiRequestBodyProps<Doc, Path, Method>): ReactNode;
 interface ApiResponseProps<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string> {
   schema: Doc;
@@ -62,6 +72,8 @@ interface ApiResponseProps<Doc = unknown, Path extends string = string, Method e
   value?: unknown;
   meta?: SchemaMeta;
   fields?: Doc extends Record<string, unknown> ? InferResponseFields<Doc, Path, Method, Status> : Record<string, FieldOverride>;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 declare function ApiResponse<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string>({
   schema: doc,
@@ -70,7 +82,8 @@ declare function ApiResponse<Doc = unknown, Path extends string = string, Method
   status,
   value,
   meta,
-  fields
+  fields,
+  widgets
 }: ApiResponseProps<Doc, Path, Method, Status>): ReactNode;
 //#endregion
 export { ApiOperation, ApiOperationProps, ApiParameters, ApiParametersProps, ApiRequestBody, ApiRequestBodyProps, ApiResponse, ApiResponseProps };

package/dist/openapi/components.mjs

@@ -27,10 +27,10 @@ function renderSchema(schema, rootDocument, options) {
 		rootDocument
 	};
 	const tree = walk(jsonSchema, walkOpts);
-	const renderChild = (childTree, childValue, childOnChange) => renderField(childTree, childValue, childOnChange, void 0, renderChild);
-	return renderField(tree, options.value, options.onChange ?? noop, void 0, renderChild);
+	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);
 }
-function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields }) {
+function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets }) {
 	const rootDoc = toDoc(doc);
 	const resolved = resolveOperation(rootDoc, path, method);
 	return /* @__PURE__ */ jsxs("section", {
@@ -42,7 +42,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 				children: [/* @__PURE__ */ jsx("h4", { children: "Parameters" }), /* @__PURE__ */ jsx(ParameterList, {
 					parameters: resolved.parameters,
 					rootDoc,
-					meta
+					meta,
+					widgets
 				})]
 			}),
 			resolved.requestBody?.schema !== void 0 && /* @__PURE__ */ jsxs("section", {
@@ -61,7 +62,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 						value: requestBodyValue,
 						onChange: onRequestBodyChange,
 						fields: requestBodyFields,
-						meta
+						meta,
+						widgets
 					})
 				]
 			}),
@@ -71,13 +73,14 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 					response,
 					rootDoc,
 					value: responseValue,
-					meta
+					meta,
+					widgets
 				}, response.statusCode))]
 			})
 		]
 	});
 }
-function ApiParameters({ schema: doc, path, method, meta, overrides }) {
+function ApiParameters({ schema: doc, path, method, meta, overrides, widgets }) {
 	const rootDoc = toDoc(doc);
 	const params = resolveParameters(rootDoc, path, method);
 	if (params.length === 0) return null;
@@ -87,11 +90,12 @@ function ApiParameters({ schema: doc, path, method, meta, overrides }) {
 			parameters: params,
 			rootDoc,
 			overrides,
-			meta
+			meta,
+			widgets
 		})]
 	});
 }
-function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields }) {
+function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets }) {
 	const rootDoc = toDoc(doc);
 	const requestBody = resolveRequestBody(rootDoc, path, method);
 	if (requestBody?.schema === void 0) return null;
@@ -111,12 +115,13 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 				value,
 				onChange,
 				fields,
-				meta
+				meta,
+				widgets
 			})
 		]
 	});
 }
-function ApiResponse({ schema: doc, path, method, status, value, meta, fields }) {
+function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets }) {
 	const rootDoc = toDoc(doc);
 	const response = resolveResponse(rootDoc, path, method, status);
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
@@ -132,7 +137,8 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields })
 		rootDoc,
 		value,
 		fields,
-		meta
+		meta,
+		widgets
 	});
 }
 function OperationHeader({ operation }) {
@@ -149,7 +155,7 @@ function OperationHeader({ operation }) {
 		})
 	] });
 }
-function ParameterList({ parameters, rootDoc, overrides, meta }) {
+function ParameterList({ parameters, rootDoc, overrides, meta, widgets }) {
 	return /* @__PURE__ */ jsx(Fragment, { children: parameters.map((param) => /* @__PURE__ */ jsxs("div", {
 		"data-parameter": param.name,
 		children: [
@@ -161,11 +167,14 @@ function ParameterList({ parameters, rootDoc, overrides, meta }) {
 				"data-description": true,
 				children: param.description
 			}),
-			renderSchema(param.schema ?? { type: "string" }, rootDoc, { meta: buildParamMeta(param, overrides, meta) })
+			renderSchema(param.schema ?? { type: "string" }, rootDoc, {
+				meta: buildParamMeta(param, overrides, meta),
+				widgets
+			})
 		]
 	}, param.name)) });
 }
-function ResponseCard({ response, rootDoc, value, fields, meta }) {
+function ResponseCard({ response, rootDoc, value, fields, meta, widgets }) {
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": response.statusCode,
 		children: [
@@ -185,7 +194,8 @@ function ResponseCard({ response, rootDoc, value, fields, meta }) {
 				meta: {
 					readOnly: true,
 					...meta
-				}
+				},
+				widgets
 			})
 		]
 	});

package/dist/react/SchemaComponent.d.mts

@@ -5,13 +5,33 @@ import { ReactNode } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/react/SchemaComponent.d.ts
+/**
+ * Widget map — maps component hints (from `.meta({ component })`) to render
+ * functions. Scoped at three levels:
+ *
+ * 1. **Per-instance** — `widgets` prop on `<SchemaComponent>`
+ * 2. **Context-scoped** — `widgets` prop on `<SchemaProvider>`
+ * 3. **Global** — `registerWidget()` (app-wide defaults)
+ *
+ * Resolution order: instance → context → global → resolver → headless.
+ */
+type WidgetMap = ReadonlyMap<string, (props: RenderProps) => unknown>;
 declare function SchemaProvider({
   resolver,
+  widgets,
   children
 }: {
-  resolver: ComponentResolver;
+  resolver: ComponentResolver; /** Scoped widgets available to all SchemaComponents in this subtree. */
+  widgets?: WidgetMap;
   children: ReactNode;
 }): _$react_jsx_runtime0.JSX.Element;
+/**
+ * Register a widget globally. The widget is resolved when a schema field
+ * has `.meta({ component: name })`.
+ *
+ * For scoped registration, use the `widgets` prop on `<SchemaComponent>`
+ * or `<SchemaProvider>` instead.
+ */
 declare function registerWidget(name: string, render: (props: RenderProps) => unknown): void;
 type InferFields<T, Ref extends string | undefined> = T extends z.ZodType ? FieldOverrides<z.infer<T>> : T extends {
   openapi: unknown;
@@ -41,6 +61,8 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
   writeOnly?: boolean;
   /** Convenience: sets description on the root. */
   description?: string;
+  /** Instance-scoped widgets — override context and global widgets. */
+  widgets?: WidgetMap;
 }
 declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined>({
   schema: schemaInput,
@@ -54,9 +76,10 @@ declare function SchemaComponent<T = unknown, Ref extends string | undefined = u
   meta: componentMeta,
   readOnly,
   writeOnly,
-  description
+  description,
+  widgets: instanceWidgets
 }: 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): 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): ReactNode;
 /**
  * Infer the schema's output type for SchemaField path inference.
  */
@@ -93,4 +116,4 @@ declare function SchemaField<T = unknown, Ref extends string | undefined = undef
   onValidationError
 }: SchemaFieldProps<T, Ref, P>): ReactNode;
 //#endregion
-export { SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, registerWidget, renderField };
+export { SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, WidgetMap, registerWidget, renderField };

package/dist/react/SchemaComponent.mjs

@@ -23,18 +23,31 @@ import { jsx } from "react/jsx-runtime";
 * - Runtime schemas → Record<string, FieldOverride> (no autocomplete)
 */
 const UserResolverContext = createContext(void 0);
-function SchemaProvider({ resolver, children }) {
+const WidgetsContext = createContext(void 0);
+function SchemaProvider({ resolver, widgets, children }) {
 	return /* @__PURE__ */ jsx(UserResolverContext.Provider, {
 		value: resolver,
-		children
+		children: /* @__PURE__ */ jsx(WidgetsContext.Provider, {
+			value: widgets,
+			children
+		})
 	});
 }
-const widgetRegistry = /* @__PURE__ */ new Map();
+/** Global widget registry — app-wide defaults. */
+const globalWidgets = /* @__PURE__ */ new Map();
+/**
+* Register a widget globally. The widget is resolved when a schema field
+* has `.meta({ component: name })`.
+*
+* For scoped registration, use the `widgets` prop on `<SchemaComponent>`
+* or `<SchemaProvider>` instead.
+*/
 function registerWidget(name, render) {
-	widgetRegistry.set(name, render);
+	globalWidgets.set(name, render);
 }
-function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, fields, meta: componentMeta, readOnly, writeOnly, description }) {
+function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets }) {
 	const userResolver = useContext(UserResolverContext);
+	const contextWidgets = useContext(WidgetsContext);
 	const mergedMeta = useMemo(() => {
 		const merged = { ...componentMeta };
 		if (readOnly === true) merged.readOnly = true;
@@ -82,9 +95,9 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 		rootDocument
 	});
 	const renderChild = (childTree, childValue, childOnChange) => {
-		return renderField(childTree, childValue, childOnChange, userResolver, renderChild);
+		return renderField(childTree, childValue, childOnChange, userResolver, renderChild, instanceWidgets, contextWidgets);
 	};
-	return renderField(tree, value ?? tree.defaultValue, handleChange, userResolver, renderChild);
+	return renderField(tree, value ?? tree.defaultValue, handleChange, userResolver, renderChild, instanceWidgets, contextWidgets);
 }
 function runValidation(zodSchema, jsonSchema, value, onError) {
 	if (zodSchema !== void 0 && isObject(zodSchema)) {
@@ -107,10 +120,10 @@ function runValidation(zodSchema, jsonSchema, value, onError) {
 		}
 	}
 }
-function renderField(tree, value, onChange, userResolver, renderChild) {
+function renderField(tree, value, onChange, userResolver, renderChild, instanceWidgets, contextWidgets) {
 	const componentHint = tree.meta.component;
 	if (typeof componentHint === "string") {
-		const widget = widgetRegistry.get(componentHint);
+		const widget = instanceWidgets?.get(componentHint) ?? contextWidgets?.get(componentHint) ?? globalWidgets.get(componentHint);
 		if (widget !== void 0) {
 			const result = widget(buildRenderProps(tree, value, onChange, renderChild));
 			if (result !== void 0 && result !== null) {
@@ -160,6 +173,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);
 	let jsonSchema;
 	let zodSchema;
 	let rootMeta;
@@ -197,9 +211,9 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 		onValidationError
 	]);
 	const renderChild = (childTree, childValue, childOnChange) => {
-		return renderField(childTree, childValue, childOnChange, userResolver, renderChild);
+		return renderField(childTree, childValue, childOnChange, userResolver, renderChild, void 0, contextWidgets);
 	};
-	return renderField(fieldTree, fieldValue, handleChange, userResolver, renderChild);
+	return renderField(fieldTree, fieldValue, handleChange, userResolver, renderChild, void 0, contextWidgets);
 }
 function resolvePath(tree, path) {
 	if (path.length === 0) return tree;

package/dist/react/SchemaView.d.mts

@@ -1,4 +1,5 @@
 import { b as ComponentResolver, m as SchemaMeta } from "../types-DDCD6Xnx.mjs";
+import { WidgetMap } from "./SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/SchemaView.d.ts
@@ -21,6 +22,8 @@ interface SchemaViewProps {
    * Falls back to the headless resolver if omitted.
    */
   resolver?: ComponentResolver;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 /**
  * Server-safe schema renderer — no hooks, no context, no state.
@@ -35,7 +38,8 @@ declare function SchemaView({
   fields,
   meta: componentMeta,
   description,
-  resolver
+  resolver,
+  widgets
 }: SchemaViewProps): ReactNode;
 //#endregion
 export { SchemaView, SchemaViewProps };

package/dist/react/SchemaView.mjs

@@ -37,7 +37,7 @@ 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 }) {
+function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: componentMeta, description, resolver, widgets }) {
 	const mergedMeta = {
 		...componentMeta,
 		readOnly: true
@@ -61,10 +61,31 @@ function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: c
 		rootDocument
 	});
 	const userResolver = resolver !== void 0 ? mergeResolvers(resolver, headlessResolver) : headlessResolver;
-	const renderChild = (childTree, childValue) => renderFieldServer(childTree, childValue, userResolver, renderChild);
-	return renderFieldServer(tree, value ?? tree.defaultValue, userResolver, renderChild);
+	const renderChild = (childTree, childValue) => renderFieldServer(childTree, childValue, userResolver, renderChild, widgets);
+	return renderFieldServer(tree, value ?? tree.defaultValue, userResolver, renderChild, widgets);
 }
-function renderFieldServer(tree, value, resolver, renderChild) {
+function renderFieldServer(tree, value, resolver, renderChild, widgets) {
+	const componentHint = tree.meta.component;
+	if (typeof componentHint === "string") {
+		const widget = widgets?.get(componentHint);
+		if (widget !== void 0) {
+			const result = widget({
+				value,
+				onChange: noop,
+				readOnly: true,
+				writeOnly: false,
+				meta: tree.meta,
+				constraints: tree.constraints,
+				path: "",
+				tree,
+				renderChild: (childTree, childValue) => renderChild(childTree, childValue)
+			});
+			if (result !== void 0 && result !== null) {
+				if (isValidElement(result)) return result;
+				if (typeof result === "string" || typeof result === "number") return result;
+			}
+		}
+	}
 	const renderFn = getRenderFunction(tree.type, resolver);
 	if (renderFn !== void 0) {
 		const props = {

package/package.json

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