schema-components 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [1.7.0](https://github.com/Mearman/schema-components/compare/v1.6.0...v1.7.0) (2026-05-14)
+
+### Features
+
+* add field visibility and ordering controls ([27cb3e1](https://github.com/Mearman/schema-components/commit/27cb3e19ba930200116c79293078fa6fa2743723))
+
+## [1.6.0](https://github.com/Mearman/schema-components/compare/v1.5.1...v1.6.0) (2026-05-14)
+
+### Features
+
+* add per-field onValidationError and writeOnly tests ([bc65589](https://github.com/Mearman/schema-components/commit/bc655893601b8e015dd3c717eccc9bf9dffbbb42))
+
+### Tests
+
+* add writeOnly behaviour tests across all renderers ([abfb293](https://github.com/Mearman/schema-components/commit/abfb293498efc4d4095dec072fd1e5a9c3239035))
+
 ## [1.5.1](https://github.com/Mearman/schema-components/compare/v1.5.0...v1.5.1) (2026-05-14)
 
 ### Bug Fixes

package/dist/core/adapter.d.mts

@@ -1,4 +1,4 @@
-import { l as JsonObject, m as SchemaMeta } from "../types-DDCD6Xnx.mjs";
+import { l as JsonObject, m as SchemaMeta } from "../types-BJzEgJdX.mjs";
 
 //#region src/core/adapter.d.ts
 type SchemaInput = Record<string, unknown>;

package/dist/core/renderer.d.mts

@@ -1,2 +1,2 @@
-import { A as mergeResolvers, C as HtmlResolver, D as getHtmlRenderFn, E as RenderProps, O as getRenderFunction, S as HtmlRenderProps, T as RenderFunction, b as ComponentResolver, j as typeToKey, k as mergeHtmlResolvers, w as RESOLVER_KEYS, x as HtmlRenderFunction, y as BaseFieldProps } from "../types-DDCD6Xnx.mjs";
+import { A as mergeResolvers, C as HtmlResolver, D as getHtmlRenderFn, E as RenderProps, O as getRenderFunction, S as HtmlRenderProps, T as RenderFunction, b as ComponentResolver, j as typeToKey, k as mergeHtmlResolvers, w as RESOLVER_KEYS, x as HtmlRenderFunction, y as BaseFieldProps } from "../types-BJzEgJdX.mjs";
 export { BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/core/types.d.mts

@@ -1,3 +1,3 @@
-import { C as HtmlResolver, E as RenderProps, S as HtmlRenderProps, T as RenderFunction, _ as WalkedField, a as FromJSONSchema, b as ComponentResolver, c as InferResponseFields, d as OpenAPIResponseType, f as PathOfType, g as TypeAtPath, h as SchemaType, i as FieldOverrides, l as JsonObject, m as SchemaMeta, n as FieldConstraints, o as InferParameterOverrides, p as ResolveOpenAPIRef, r as FieldOverride, s as InferRequestBodyFields, t as Editability, u as OpenAPIRequestBodyType, v as resolveEditability, x as HtmlRenderFunction, y as BaseFieldProps } from "../types-DDCD6Xnx.mjs";
+import { C as HtmlResolver, E as RenderProps, S as HtmlRenderProps, T as RenderFunction, _ as WalkedField, a as FromJSONSchema, b as ComponentResolver, c as InferResponseFields, d as OpenAPIResponseType, f as PathOfType, g as TypeAtPath, h as SchemaType, i as FieldOverrides, l as JsonObject, m as SchemaMeta, n as FieldConstraints, o as InferParameterOverrides, p as ResolveOpenAPIRef, r as FieldOverride, s as InferRequestBodyFields, t as Editability, u as OpenAPIRequestBodyType, v as resolveEditability, x as HtmlRenderFunction, y as BaseFieldProps } from "../types-BJzEgJdX.mjs";
 import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-DIKI2C78.mjs";
 export { BaseFieldProps, ComponentResolver, Editability, FieldConstraints, FieldOverride, FieldOverrides, FromJSONSchema, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, InferParameterOverrides, InferRequestBodyFields, InferResponseFields, JsonObject, OpenAPIRequestBodyType, OpenAPIResponseType, PathOfType, RenderFunction, RenderProps, ResolveOpenAPIRef, SchemaError, SchemaFieldError, SchemaMeta, SchemaNormalisationError, SchemaRenderError, SchemaType, TypeAtPath, WalkedField, resolveEditability };

package/dist/core/walker.d.mts

@@ -1,4 +1,4 @@
-import { _ as WalkedField, m as SchemaMeta } from "../types-DDCD6Xnx.mjs";
+import { _ as WalkedField, m as SchemaMeta } from "../types-BJzEgJdX.mjs";
 
 //#region src/core/walker.d.ts
 interface WalkOptions {

package/dist/core/walker.mjs

@@ -160,7 +160,9 @@ const OVERRIDE_META_KEYS = new Set([
 	"description",
 	"title",
 	"deprecated",
-	"component"
+	"component",
+	"visible",
+	"order"
 ]);
 function extractSchemaMetaFields(overrides) {
 	if (overrides === void 0) return void 0;

package/dist/html/a11y.d.mts

@@ -1,4 +1,4 @@
-import { _ as WalkedField, n as FieldConstraints } from "../types-DDCD6Xnx.mjs";
+import { _ as WalkedField, n as FieldConstraints } from "../types-BJzEgJdX.mjs";
 import { HtmlAttributes, HtmlNode } from "./html.mjs";
 
 //#region src/html/a11y.d.ts

package/dist/html/renderToHtml.d.mts

@@ -1,4 +1,4 @@
-import { C as HtmlResolver, S as HtmlRenderProps, m as SchemaMeta, x as HtmlRenderFunction } from "../types-DDCD6Xnx.mjs";
+import { C as HtmlResolver, S as HtmlRenderProps, m as SchemaMeta, x as HtmlRenderFunction } from "../types-BJzEgJdX.mjs";
 
 //#region src/html/renderToHtml.d.ts
 interface RenderToHtmlOptions {

package/dist/html/renderToHtml.mjs

@@ -180,10 +180,13 @@ function renderObjectNode(props) {
 	const obj = isRecord(props.value) ? props.value : {};
 	const descriptionText = typeof props.meta.description === "string" ? props.meta.description : void 0;
 	const legend = descriptionText !== void 0 ? h("legend", {}, descriptionText) : void 0;
+	const sortedEntries = Object.entries(fields).sort((a, b) => {
+		return (typeof a[1].meta.order === "number" ? a[1].meta.order : Infinity) - (typeof b[1].meta.order === "number" ? b[1].meta.order : Infinity);
+	}).filter(([, field]) => field.meta.visible !== false);
 	if (props.readOnly) {
 		const children = [];
 		if (legend !== void 0) children.push(legend);
-		for (const [key, field] of Object.entries(fields)) {
+		for (const [key, field] of sortedEntries) {
 			const label = typeof field.meta.description === "string" ? field.meta.description : key;
 			const childValue = obj[key];
 			const childHtml = props.renderChild(field, childValue, props.path ? `${props.path}.${key}` : key);
@@ -196,7 +199,7 @@ function renderObjectNode(props) {
 	}
 	const children = [];
 	if (legend !== void 0) children.push(legend);
-	for (const [key, field] of Object.entries(fields)) {
+	for (const [key, field] of sortedEntries) {
 		const label = typeof field.meta.description === "string" ? field.meta.description : key;
 		const fieldId = buildInputId(props.path, key);
 		const childPath = props.path ? `${props.path}.${key}` : key;
@@ -413,6 +416,7 @@ function renderToHtml(schema, options = {}) {
 	return renderFieldHtml(tree, options.value ?? tree.defaultValue, resolver, "", renderChild);
 }
 function renderFieldHtml(tree, value, resolver, path, renderChild) {
+	if (tree.meta.visible === false) return "";
 	const effectiveValue = value ?? tree.defaultValue;
 	const mergedResolver = mergeHtmlResolvers(resolver, defaultHtmlResolver);
 	const renderFn = getHtmlRenderFn(tree.type, mergedResolver);

package/dist/openapi/components.d.mts

@@ -1,4 +1,4 @@
-import { c as InferResponseFields, m as SchemaMeta, o as InferParameterOverrides, r as FieldOverride, s as InferRequestBodyFields } from "../types-DDCD6Xnx.mjs";
+import { c as InferResponseFields, m as SchemaMeta, o as InferParameterOverrides, r as FieldOverride, s as InferRequestBodyFields } from "../types-BJzEgJdX.mjs";
 import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/parser.d.mts

@@ -1,4 +1,4 @@
-import { l as JsonObject } from "../types-DDCD6Xnx.mjs";
+import { l as JsonObject } from "../types-BJzEgJdX.mjs";
 
 //#region src/openapi/parser.d.ts
 interface OpenApiDocument {

package/dist/react/SchemaComponent.d.mts

@@ -1,4 +1,4 @@
-import { E as RenderProps, _ as WalkedField, a as FromJSONSchema, b as ComponentResolver, f as PathOfType, i as FieldOverrides, m as SchemaMeta, p as ResolveOpenAPIRef, r as FieldOverride } from "../types-DDCD6Xnx.mjs";
+import { E as RenderProps, _ as WalkedField, a as FromJSONSchema, b as ComponentResolver, f as PathOfType, i as FieldOverrides, m as SchemaMeta, p as ResolveOpenAPIRef, r as FieldOverride } from "../types-BJzEgJdX.mjs";
 import { t as SchemaError } from "../errors-DIKI2C78.mjs";
 import { z } from "zod";
 import { ReactNode } from "react";

package/dist/react/SchemaComponent.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { isObject, toRecord } from "../core/guards.mjs";
+import { isObject, toRecord, toRecordOrUndefined } from "../core/guards.mjs";
 import { normaliseSchema } from "../core/adapter.mjs";
 import { SchemaFieldError, SchemaNormalisationError, SchemaRenderError } from "../core/errors.mjs";
 import { getRenderFunction, mergeResolvers } from "../core/renderer.mjs";
@@ -79,14 +79,21 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 		throw error;
 	}
 	const handleChange = useCallback((nextValue) => {
-		if (validate) runValidation(zodSchema, jsonSchema, nextValue, onValidationError);
+		if (validate) {
+			const error = runValidation(zodSchema, jsonSchema, nextValue);
+			if (error !== void 0) {
+				onValidationError?.(error);
+				dispatchFieldErrors(fields, error);
+			}
+		}
 		onChange?.(nextValue);
 	}, [
 		validate,
 		zodSchema,
 		jsonSchema,
 		onChange,
-		onValidationError
+		onValidationError,
+		fields
 	]);
 	const tree = walk(jsonSchema, {
 		componentMeta: mergedMeta,
@@ -99,15 +106,12 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 	};
 	return renderField(tree, value ?? tree.defaultValue, handleChange, userResolver, renderChild, instanceWidgets, contextWidgets);
 }
-function runValidation(zodSchema, jsonSchema, value, onError) {
+function runValidation(zodSchema, jsonSchema, value) {
 	if (zodSchema !== void 0 && isObject(zodSchema)) {
 		const safeParseFn = zodSchema.safeParse;
 		if (isCallable(safeParseFn)) {
 			const result = safeParseFn(value);
-			if (isObject(result) && "success" in result && result.success !== true) {
-				onError?.(result.error);
-				return;
-			}
+			if (isObject(result) && "success" in result && result.success !== true) return result.error;
 			return;
 		}
 	}
@@ -116,11 +120,12 @@ function runValidation(zodSchema, jsonSchema, value, onError) {
 		const safeParseFn = parsed.safeParse;
 		if (isCallable(safeParseFn)) {
 			const result = safeParseFn(value);
-			if (isObject(result) && "success" in result && result.success !== true) onError?.(result.error);
+			if (isObject(result) && "success" in result && result.success !== true) return result.error;
 		}
 	}
 }
 function renderField(tree, value, onChange, userResolver, renderChild, instanceWidgets, contextWidgets) {
+	if (tree.meta.visible === false) return null;
 	const componentHint = tree.meta.component;
 	if (typeof componentHint === "string") {
 		const widget = instanceWidgets?.get(componentHint) ?? contextWidgets?.get(componentHint) ?? globalWidgets.get(componentHint);
@@ -197,7 +202,8 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 	const handleChange = useCallback((nextFieldValue) => {
 		if (validate) {
 			const newRootValue = setNestedValue(value, path, nextFieldValue);
-			runValidation(zodSchema, jsonSchema, newRootValue, onValidationError);
+			const error = runValidation(zodSchema, jsonSchema, newRootValue);
+			if (error !== void 0) onValidationError?.(error);
 		}
 		const newRootValue = setNestedValue(value, path, nextFieldValue);
 		onChange?.(newRootValue);
@@ -280,6 +286,36 @@ function setNestedValue(root, path, leafValue) {
 	}
 	return result;
 }
+function isFieldErrorCallback(value) {
+	return typeof value === "function";
+}
+/**
+* Dispatch Zod errors to per-field onValidationError callbacks.
+* Walks the fields override tree and matches errors by path prefix.
+*/
+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)) {
+		if (override === void 0 || typeof override !== "object") continue;
+		if (override === null) continue;
+		if (!("onValidationError" in override)) continue;
+		const fieldCallback = override.onValidationError;
+		if (typeof fieldCallback !== "function") continue;
+		const fieldErrors = issues.filter((issue) => {
+			if (!isObject(issue)) return false;
+			if (!("path" in issue)) return false;
+			const path = issue.path;
+			if (!Array.isArray(path)) return false;
+			return path[0] === key;
+		});
+		if (fieldErrors.length > 0 && isFieldErrorCallback(fieldCallback)) fieldCallback({ issues: fieldErrors });
+	}
+}
 function isCallable(value) {
 	return typeof value === "function";
 }

package/dist/react/SchemaView.d.mts

@@ -1,4 +1,4 @@
-import { b as ComponentResolver, m as SchemaMeta } from "../types-DDCD6Xnx.mjs";
+import { b as ComponentResolver, m as SchemaMeta } from "../types-BJzEgJdX.mjs";
 import { WidgetMap } from "./SchemaComponent.mjs";
 import { ReactNode } from "react";
 

package/dist/react/headless.d.mts

@@ -1,4 +1,4 @@
-import { b as ComponentResolver } from "../types-DDCD6Xnx.mjs";
+import { b as ComponentResolver } from "../types-BJzEgJdX.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/headless.d.ts

package/dist/react/headless.mjs

@@ -237,7 +237,10 @@ function renderObject(props) {
 	const obj = isObject(props.value) ? props.value : {};
 	const fields = props.fields;
 	if (fields === void 0) return null;
-	return /* @__PURE__ */ jsxs("fieldset", { children: [typeof props.meta.description === "string" && /* @__PURE__ */ jsx("legend", { children: props.meta.description }), Object.entries(fields).map(([key, field]) => {
+	const sortedEntries = Object.entries(fields).sort((a, b) => {
+		return (typeof a[1].meta.order === "number" ? a[1].meta.order : Infinity) - (typeof b[1].meta.order === "number" ? b[1].meta.order : Infinity);
+	});
+	return /* @__PURE__ */ jsxs("fieldset", { children: [typeof props.meta.description === "string" && /* @__PURE__ */ jsx("legend", { children: props.meta.description }), sortedEntries.filter(([, field]) => field.meta.visible !== false).map(([key, field]) => {
 		const childValue = obj[key];
 		const childId = inputId(props.path ? `${props.path}.${key}` : key);
 		const childOnChange = (v) => {

package/dist/themes/mui.d.mts

@@ -1,4 +1,4 @@
-import { b as ComponentResolver } from "../types-DDCD6Xnx.mjs";
+import { b as ComponentResolver } from "../types-BJzEgJdX.mjs";
 
 //#region src/themes/mui.d.ts
 /**

package/dist/themes/shadcn.d.mts

@@ -1,4 +1,4 @@
-import { b as ComponentResolver } from "../types-DDCD6Xnx.mjs";
+import { b as ComponentResolver } from "../types-BJzEgJdX.mjs";
 
 //#region src/themes/shadcn.d.ts
 declare const shadcnResolver: ComponentResolver;

package/dist/{types-DDCD6Xnx.d.mts → types-BJzEgJdX.d.mts}

@@ -147,6 +147,8 @@ interface SchemaMeta {
   deprecated?: boolean;
   /** Component hint — resolved before theme adapter. */
   component?: string;
+  /** Sort order for object fields. Lower values render first. */
+  order?: number;
   /** Arbitrary UI hints passed through to theme adapters. */
   [key: string]: unknown;
 }
@@ -166,14 +168,19 @@ type Editability = "presentation" | "input" | "editable";
 declare function resolveEditability(propertyMeta: SchemaMeta | undefined, componentMeta: SchemaMeta | undefined, rootMeta: SchemaMeta | undefined): Editability;
 /**
  * Recursive mapped type that mirrors a schema's shape for per-field
- * meta overrides. Each leaf is `Partial<SchemaMeta>`, objects recurse
- * and also accept their own `SchemaMeta`.
+ * overrides. Each leaf accepts schema meta overrides and an optional
+ * per-field validation error callback. Objects recurse and also accept
+ * their own overrides.
  */
-type FieldOverrides<T> = { [K in keyof T]?: T[K] extends object ? FieldOverrides<T[K]> & Partial<SchemaMeta> : Partial<SchemaMeta> };
+type FieldOverrides<T> = { [K in keyof T]?: T[K] extends object ? FieldOverrides<T[K]> & FieldOverride : FieldOverride };
 /**
- * Fallback type for runtime schemas (no compile-time shape).
+ * Per-field override. Extends SchemaMeta with rendering controls
+ * and a per-field validation error callback.
  */
-type FieldOverride = Partial<SchemaMeta>;
+type FieldOverride = Partial<SchemaMeta> & {
+  /** Called with the ZodError when this field fails validation. */onValidationError?: (error: unknown) => void; /** Hide this field when false. Defaults to true (visible). */
+  visible?: boolean;
+};
 type SchemaType = "string" | "number" | "boolean" | "null" | "enum" | "literal" | "object" | "array" | "record" | "union" | "discriminatedUnion" | "optional" | "nullable" | "default" | "readonly" | "pipe" | "lazy" | "file" | "unknown";
 interface WalkedField {
   type: SchemaType;

package/package.json

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