schema-components 1.6.0 → 1.7.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [1.7.1](https://github.com/Mearman/schema-components/compare/v1.7.0...v1.7.1) (2026-05-14)
+
+### Documentation
+
+* update README and add Storybook stories for visibility, ordering, and per-field validation ([4be4b6f](https://github.com/Mearman/schema-components/commit/4be4b6feaaa4819937280c010eacb3f36a521a54))
+
+## [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

package/README.md

@@ -525,6 +525,25 @@ Server Components: `<SchemaView>` accepts a `widgets` prop directly (no React co
 
 Validation uses the original Zod schema (if input was Zod) or `z.fromJSONSchema()` (if input was JSON Schema / OpenAPI).
 
+### Per-field validation errors
+
+Add `onValidationError` to individual field overrides to receive errors for specific fields:
+
+```tsx
+<SchemaComponent
+  schema={userSchema}
+  value={user}
+  onChange={setUser}
+  validate
+  fields={{
+    email: { onValidationError: (err) => setEmailError(err) },
+    name: { onValidationError: (err) => setNameError(err) },
+  }}
+/>
+```
+
+Errors are dispatched based on Zod error paths. The root-level `onValidationError` still receives all errors.
+
 ## Discriminated unions
 
 Discriminated unions (`z.discriminatedUnion` or JSON Schema `oneOf` with `const` properties) render as tabbed panels. Each tab is labelled by the discriminator's `const` value. Clicking a tab resets the value with the new discriminator.
@@ -578,6 +597,48 @@ const schema = z.object({
 
 Defaults propagate through nested objects — each field uses its own default independently.
 
+## Field visibility
+
+Hide fields conditionally using the `visible` override:
+
+```tsx
+<SchemaComponent
+  schema={paymentSchema}
+  value={payment}
+  fields={{
+    cardNumber: { visible: payment.method === "card" },
+    sortCode: { visible: payment.method === "bank" },
+  }}
+/>
+```
+
+When `visible: false`, the field is completely removed — no label, no empty placeholder, no hidden input. The parent component controls visibility based on the current value.
+
+## Field ordering
+
+Control the order fields appear in rendered objects using `order`:
+
+```tsx
+<SchemaComponent
+  schema={userSchema}
+  value={user}
+  fields={{
+    email: { order: 1 },
+    name: { order: 2 },
+    role: { order: 3 },
+  }}
+/>
+```
+
+Lower `order` values render first. Fields without `order` keep their insertion order and appear after ordered fields. Can also be set in schema metadata:
+
+```tsx
+const schema = z.object({
+  summary: z.string().meta({ order: 1 }),
+  title: z.string().meta({ order: 2 }),
+});
+```
+
 ## Server Components
 
 For read-only rendering in a React Server Component, use `<SchemaView>`. It has zero hooks — no `useContext`, no `useMemo`, no `useCallback` — so it works without the `"use client"` directive.

package/dist/core/adapter.d.mts

@@ -1,4 +1,4 @@
-import { l as JsonObject, m as SchemaMeta } from "../types-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.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

@@ -125,6 +125,7 @@ function runValidation(zodSchema, jsonSchema, value) {
 	}
 }
 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);

package/dist/react/SchemaView.d.mts

@@ -1,4 +1,4 @@
-import { b as ComponentResolver, m as SchemaMeta } from "../types-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.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-CnlV7bBK.mjs";
+import { b as ComponentResolver } from "../types-BJzEgJdX.mjs";
 
 //#region src/themes/shadcn.d.ts
 declare const shadcnResolver: ComponentResolver;

package/dist/{types-CnlV7bBK.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;
 }
@@ -172,11 +174,12 @@ declare function resolveEditability(propertyMeta: SchemaMeta | undefined, compon
  */
 type FieldOverrides<T> = { [K in keyof T]?: T[K] extends object ? FieldOverrides<T[K]> & FieldOverride : FieldOverride };
 /**
- * Per-field override. Extends SchemaMeta with a React-layer callback
- * for per-field validation errors.
+ * Per-field override. Extends SchemaMeta with rendering controls
+ * and a per-field validation error callback.
  */
 type FieldOverride = Partial<SchemaMeta> & {
-  /** Called with the ZodError when this field fails validation. */onValidationError?: (error: unknown) => void;
+  /** 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 {

package/package.json

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