@zeno-lib/forms 0.3.0 → 0.4.0

package/dist/create-zeno-form.mjs

@@ -3,11 +3,12 @@ import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { fieldContext, formContext } from "./lib/contexts.mjs";
 import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults.mjs";
 import { getRequiredPaths } from "./lib/schema-required.mjs";
+import { DEFAULT_VALIDATION_MODE, setFormZenoState } from "./lib/validation-modes.mjs";
+import { withEmptyStartValues } from "./lib/empty-value.mjs";
 import { useRebasedDefaultValues } from "./lib/use-rebased-default-values.mjs";
 import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning.mjs";
 import { ValidationError } from "./lib/validation-error.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
-import { DEFAULT_VALIDATION_MODE, setFormZenoState } from "./lib/validation-modes.mjs";
 import { createFormHook } from "@tanstack/react-form";
 import { useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
@@ -86,8 +87,8 @@ function createZenoForm(config) {
 				throw error;
 			}
 		}) : void 0;
-		const requiredFields = useMemo(() => schema && requiredIndicator ? getRequiredPaths(schema) : /* @__PURE__ */ new Set(), [schema, requiredIndicator]);
-		const schemaDefaults = useMemo(() => schema ? extractZodDefaults(schema) : void 0, [schema]);
+		const requiredFields = useMemo(() => schema ? getRequiredPaths(schema) : /* @__PURE__ */ new Set(), [schema]);
+		const schemaDefaults = useMemo(() => schema ? withEmptyStartValues(schema, extractZodDefaults(schema)) : void 0, [schema]);
 		const mergedDefaultValues = useMemo(() => schemaDefaults ? deepMergeDefaults(schemaDefaults, userDefaultValues) : userDefaultValues, [schemaDefaults, userDefaultValues]);
 		const rebased = useRebasedDefaultValues(mergedDefaultValues);
 		const listeners = withMountListener(rest.listeners, rebased.onMount);
@@ -103,6 +104,7 @@ function createZenoForm(config) {
 			hideFieldErrors,
 			requiredFields,
 			requiredIndicator,
+			schema,
 			...schemaMode === void 0 ? {} : { validation: schemaMode }
 		});
 		useUnsavedChangesWarning(form, unsavedChangesWarning);

package/dist/index.d.mts

@@ -6,7 +6,7 @@ import { FieldMessage, ValidationError } from "./lib/validation-error.mjs";
 import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { useFieldContext, useFormContext } from "./lib/contexts.mjs";
 import { SubmitActionOptions, SubmitActionSchema, applyActionError, submitAction } from "./lib/submit-action.mjs";
-import { useHideFieldErrors, useIsFieldRequired, useIsInvalid } from "./lib/use-is-invalid.mjs";
+import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./lib/use-is-invalid.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
 import { useSelector } from "@tanstack/react-form";
-export { type ActionError, type ActionIssue, type ActionResult, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsInvalid, useSelector };
+export { type ActionError, type ActionIssue, type ActionResult, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };

package/dist/index.mjs

@@ -1,11 +1,11 @@
 import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { useFieldContext, useFormContext } from "./lib/contexts.mjs";
+import { toActionError, toFieldName } from "./lib/action-result.mjs";
 import { ValidationError } from "./lib/validation-error.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
 import { createZenoForm } from "./create-zeno-form.mjs";
 import { Form, FormProvider } from "./form-element.mjs";
-import { toActionError, toFieldName } from "./lib/action-result.mjs";
 import { applyActionError, submitAction } from "./lib/submit-action.mjs";
-import { useHideFieldErrors, useIsFieldRequired, useIsInvalid } from "./lib/use-is-invalid.mjs";
+import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./lib/use-is-invalid.mjs";
 import { useSelector } from "@tanstack/react-form";
-export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsInvalid, useSelector };
+export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };

package/dist/lib/empty-value.d.mts

@@ -0,0 +1,12 @@
+import { StandardSchemaLike } from "./schema-required.mjs";
+import { AnyFieldApi } from "@tanstack/react-form";
+//#region src/lib/empty-value.d.ts
+declare function emptyValueFor(schema: StandardSchemaLike | undefined, values: unknown, name: string, fallback: unknown): unknown;
+declare function withEmptyStartValues(schema: StandardSchemaLike, defaults: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The value `field` takes when the user clears it, by the rule above. Typed as
+ * the field's value, since the same schema decides both.
+ */
+declare function getEmptyValue<T>(field: AnyFieldApi, fallback: T): T;
+//#endregion
+export { emptyValueFor, getEmptyValue, withEmptyStartValues };

package/dist/lib/empty-value.mjs

@@ -0,0 +1,68 @@
+import { toFieldName } from "./action-result.mjs";
+import { extractZodDefaultAt } from "./schema-defaults.mjs";
+import { validateSync } from "./schema-required.mjs";
+import { getFormSchema } from "./validation-modes.mjs";
+//#region src/lib/empty-value.ts
+const NAME_SEGMENT = /[^.[\]]+/g;
+const INDEX = /^\d+$/;
+function toPathKeys(name) {
+	return (name.match(NAME_SEGMENT) ?? []).map((part) => INDEX.test(part) ? Number(part) : part);
+}
+function valueAt(root, keys) {
+	let node = root;
+	for (const key of keys) {
+		if (typeof node !== "object" || node === null) return;
+		node = node[key];
+	}
+	return node;
+}
+function withValueAt(root, keys, value) {
+	const [key, ...rest] = keys;
+	if (key === void 0) return value;
+	const node = root ?? (typeof key === "number" ? [] : {});
+	const copy = Array.isArray(node) ? [...node] : { ...node };
+	copy[key] = withValueAt(node[key], rest, value);
+	return copy;
+}
+function emptyValueFor(schema, values, name, fallback) {
+	if (!schema) return fallback;
+	const keys = toPathKeys(name);
+	const fieldName = toFieldName(keys);
+	const typeEmpty = extractZodDefaultAt(schema, keys);
+	const candidates = typeEmpty.ok ? [
+		null,
+		void 0,
+		typeEmpty.value
+	] : [null, void 0];
+	for (const candidate of candidates) {
+		const issues = validateSync(schema, withValueAt(values, keys, candidate));
+		if (!issues) return fallback;
+		if (!issues.some((issue) => toFieldName(issue.path) === fieldName)) return candidate;
+	}
+	return fallback;
+}
+function isTypeEmpty(value) {
+	return value === "" || Array.isArray(value) && value.length === 0;
+}
+function withEmptyStartValues(schema, defaults) {
+	const issues = validateSync(schema, defaults);
+	let result = defaults;
+	for (const issue of issues ?? []) {
+		const name = toFieldName(issue.path);
+		const keys = toPathKeys(name);
+		const start = valueAt(defaults, keys);
+		if (keys.length === 0 || !isTypeEmpty(start)) continue;
+		const empty = emptyValueFor(schema, result, name, start);
+		if (empty !== start) result = withValueAt(result, keys, empty);
+	}
+	return result;
+}
+/**
+* The value `field` takes when the user clears it, by the rule above. Typed as
+* the field's value, since the same schema decides both.
+*/
+function getEmptyValue(field, fallback) {
+	return emptyValueFor(getFormSchema(field.form), field.form.state.values, field.name, fallback);
+}
+//#endregion
+export { emptyValueFor, getEmptyValue, withEmptyStartValues };

package/dist/lib/schema-defaults.d.mts

@@ -9,9 +9,17 @@ type SchemaDef = {
   readonly innerType?: SchemaNode;
   readonly shape?: Record<string, SchemaNode>;
   readonly in?: SchemaNode;
+  readonly element?: SchemaNode;
   readonly defaultValue?: unknown;
 };
+type ExtractResult = {
+  ok: true;
+  value: unknown;
+} | {
+  ok: false;
+};
 declare function extractZodDefaults(schema: SchemaNode): Record<string, unknown>;
+declare function extractZodDefaultAt(schema: SchemaNode, keys: readonly PropertyKey[]): ExtractResult;
 declare function deepMergeDefaults(schemaDefaults: Record<string, unknown>, userDefaults: Record<string, unknown> | undefined): Record<string, unknown>;
 //#endregion
-export { deepMergeDefaults, extractZodDefaults };
+export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults };

package/dist/lib/schema-defaults.mjs

@@ -57,6 +57,38 @@ function extractZodDefaults(schema) {
 		return {};
 	}
 }
+function childAt(node, key) {
+	let current = node;
+	for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
+		const def = getDef(current);
+		switch (def?.type) {
+			case "object": return typeof key === "string" && def.shape?.[key] || null;
+			case "array": return typeof key === "number" && def.element || null;
+			case "default":
+			case "nonoptional":
+			case "nullable":
+			case "optional":
+			case "prefault":
+			case "readonly":
+				current = def.innerType;
+				continue;
+			case "pipe":
+				current = def.in;
+				continue;
+			default: return null;
+		}
+	}
+	return null;
+}
+function extractZodDefaultAt(schema, keys) {
+	try {
+		let node = schema;
+		for (const key of keys) node = node && childAt(node, key);
+		return node && keys.length > 0 ? extractDefaultForField(node) : { ok: false };
+	} catch {
+		return { ok: false };
+	}
+}
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
 }
@@ -72,4 +104,4 @@ function deepMergeDefaults(schemaDefaults, userDefaults) {
 	return result;
 }
 //#endregion
-export { deepMergeDefaults, extractZodDefaults };
+export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults };

package/dist/lib/schema-required.d.mts

@@ -20,6 +20,7 @@ type StandardSchemaLike = {
  * `getRequiredPaths` records (`members[0].name`).
  */
 declare function toRequiredPathKey(name: string): string;
+declare function validateSync(schema: StandardSchemaLike, value: unknown): readonly StandardIssue[] | undefined;
 declare function getRequiredPaths(schema: StandardSchemaLike): Set<string>;
 //#endregion
-export { type StandardSchemaLike, getRequiredPaths, toRequiredPathKey };
+export { type StandardSchemaLike, getRequiredPaths, toRequiredPathKey, validateSync };

package/dist/lib/schema-required.mjs

@@ -1,5 +1,5 @@
 //#region src/lib/schema-required.ts
-const MAX_PROBE_DEPTH = 8;
+const MAX_PROBE_DEPTH = 16;
 const INDEX_SEGMENT = /^\d+$/;
 const INDEX_IN_NAME = /\[\d+\]|\.(\d+)(?=\.|\[|$)/g;
 function pathKey(part) {
@@ -23,15 +23,14 @@ function toRequiredPathKey(name) {
 	return name.replace(INDEX_IN_NAME, "[0]");
 }
 function probeValue(expected) {
-	if (typeof expected !== "string") return;
-	switch (expected.toLowerCase()) {
+	switch (typeof expected === "string" ? expected.toLowerCase() : void 0) {
 		case "object": return {};
-		case "array": return [{}];
+		case "array": return [];
 		case "string": return "";
-		default: return;
+		default: return null;
 	}
 }
-function fillAt(root, keys, value) {
+function fillAt(root, keys, value, replace = false) {
 	let node = root;
 	for (const key of keys.slice(0, -1)) {
 		const next = node[key];
@@ -39,7 +38,7 @@ function fillAt(root, keys, value) {
 		node = next;
 	}
 	const last = keys.at(-1);
-	if (node[last] !== void 0) return false;
+	if (!replace && node[last] !== void 0) return false;
 	node[last] = value;
 	return true;
 }
@@ -53,41 +52,70 @@ function validateSync(schema, value) {
 	if (result instanceof Promise) return;
 	return "issues" in result && result.issues ? result.issues : [];
 }
-function recordPass(issues, probe, required) {
+function recordPass(issues, probe, required, cleared) {
 	const failing = /* @__PURE__ */ new Set();
-	const filledStrings = [];
-	let descended = false;
+	const filled = [];
 	for (const issue of issues) {
 		const keys = issue.path?.map(pathKey) ?? [];
 		if (keys.length === 0) continue;
 		const path = joinPath(keys);
 		failing.add(path);
-		required.add(path);
+		if (!cleared.has(path)) required.add(path);
 		const value = probeValue(issue.expected);
-		if (value !== void 0 && fillAt(probe, keys, value)) {
+		if (value !== void 0 && fillAt(probe, keys, value)) filled.push({
+			keys,
+			path,
+			value
+		});
+	}
+	return {
+		failing,
+		filled
+	};
+}
+function isEmptyProbe(value) {
+	return value === "" || value === null || Array.isArray(value);
+}
+function settleEmptied(emptied, failing, probe, required, cleared) {
+	const next = [];
+	let descended = false;
+	for (const fill of emptied) {
+		const passed = !failing.has(fill.path);
+		if (passed) {
+			required.delete(fill.path);
+			cleared.add(fill.path);
+		}
+		if (Array.isArray(fill.value)) {
+			fill.value.push(void 0);
+			descended = true;
+		} else if (!passed && fill.value === "") {
+			fillAt(probe, fill.keys, null, true);
+			next.push({
+				...fill,
+				value: null
+			});
 			descended = true;
-			if (value === "") filledStrings.push(path);
 		}
 	}
 	return {
 		descended,
-		failing,
-		filledStrings
+		next
 	};
 }
 function getRequiredPaths(schema) {
 	const required = /* @__PURE__ */ new Set();
+	const cleared = /* @__PURE__ */ new Set();
 	const probe = {};
-	let filledStrings = [];
+	let emptied = [];
 	for (let depth = 0; depth < MAX_PROBE_DEPTH; depth += 1) {
 		const issues = validateSync(schema, probe);
 		if (!issues) return required;
-		const { descended, failing, filledStrings: filled } = recordPass(issues, probe, required);
-		for (const path of filledStrings) if (!failing.has(path)) required.delete(path);
-		filledStrings = filled;
-		if (!descended) break;
+		const { failing, filled } = recordPass(issues, probe, required, cleared);
+		const settled = settleEmptied(emptied, failing, probe, required, cleared);
+		emptied = [...filled.filter(({ value }) => isEmptyProbe(value)), ...settled.next];
+		if (filled.length === 0 && !settled.descended) break;
 	}
 	return required;
 }
 //#endregion
-export { getRequiredPaths, toRequiredPathKey };
+export { getRequiredPaths, toRequiredPathKey, validateSync };

package/dist/lib/submit-action.mjs

@@ -1,6 +1,6 @@
 import { applyValidationError } from "./apply-validation-error.mjs";
-import { ValidationError } from "./validation-error.mjs";
 import { toActionError } from "./action-result.mjs";
+import { ValidationError } from "./validation-error.mjs";
 //#region src/lib/submit-action.ts
 function applyActionError(formApi, error) {
 	const fields = {};

package/dist/lib/use-is-invalid.d.mts

@@ -3,5 +3,6 @@ import { AnyFieldApi } from "@tanstack/react-form";
 declare function useIsInvalid(field: AnyFieldApi): boolean;
 declare function useHideFieldErrors(field: AnyFieldApi): boolean;
 declare function useIsFieldRequired(field: AnyFieldApi): boolean;
+declare function useIsFieldRequiredBySchema(field: AnyFieldApi): boolean;
 //#endregion
-export { useHideFieldErrors, useIsFieldRequired, useIsInvalid };
+export { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid };

package/dist/lib/use-is-invalid.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { getFormHideFieldErrors, getFormValidationMode, isFieldRequired } from "./validation-modes.mjs";
+import { getFormHideFieldErrors, getFormValidationMode, isFieldRequired, isFieldRequiredBySchema } from "./validation-modes.mjs";
 import { useSelector } from "@tanstack/react-form";
 //#region src/lib/use-is-invalid.ts
 function hasFieldLevelError(errorMap, errorSourceMap, cause) {
@@ -27,5 +27,8 @@ function useHideFieldErrors(field) {
 function useIsFieldRequired(field) {
 	return isFieldRequired(field.form, field.name);
 }
+function useIsFieldRequiredBySchema(field) {
+	return isFieldRequiredBySchema(field.form, field.name);
+}
 //#endregion
-export { useHideFieldErrors, useIsFieldRequired, useIsInvalid };
+export { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid };

package/dist/lib/validation-modes.d.mts

@@ -1,3 +1,4 @@
+import { StandardSchemaLike } from "./schema-required.mjs";
 import { AnyFormApi } from "@tanstack/react-form";
 //#region src/lib/validation-modes.d.ts
 type ValidationMode = "change" | "blur" | "submit" | "blur-then-change";
@@ -7,10 +8,13 @@ type ZenoFormState = {
   hideFieldErrors: boolean;
   requiredIndicator: boolean;
   requiredFields: ReadonlySet<string>;
+  schema: StandardSchemaLike | undefined;
 };
 declare function setFormZenoState(form: AnyFormApi, state: Partial<ZenoFormState>): void;
 declare function getFormValidationMode(form: AnyFormApi): ValidationMode;
 declare function getFormHideFieldErrors(form: AnyFormApi): boolean;
+declare function getFormSchema(form: AnyFormApi): StandardSchemaLike | undefined;
+declare function isFieldRequiredBySchema(form: AnyFormApi, name: string): boolean;
 declare function isFieldRequired(form: AnyFormApi, name: string): boolean;
 //#endregion
-export { DEFAULT_VALIDATION_MODE, type ValidationMode, getFormHideFieldErrors, getFormValidationMode, isFieldRequired, setFormZenoState };
+export { DEFAULT_VALIDATION_MODE, type ValidationMode, getFormHideFieldErrors, getFormSchema, getFormValidationMode, isFieldRequired, isFieldRequiredBySchema, setFormZenoState };

package/dist/lib/validation-modes.mjs

@@ -6,6 +6,7 @@ const DEFAULT_FORM_STATE = {
 	hideFieldErrors: false,
 	requiredFields: /* @__PURE__ */ new Set(),
 	requiredIndicator: true,
+	schema: void 0,
 	validation: DEFAULT_VALIDATION_MODE
 };
 const formZenoState = /* @__PURE__ */ new WeakMap();
@@ -29,10 +30,14 @@ function getFormValidationMode(form) {
 function getFormHideFieldErrors(form) {
 	return getFormZenoState(form).hideFieldErrors;
 }
+function getFormSchema(form) {
+	return getFormZenoState(form).schema;
+}
+function isFieldRequiredBySchema(form, name) {
+	return getFormZenoState(form).requiredFields.has(toRequiredPathKey(name));
+}
 function isFieldRequired(form, name) {
-	const state = getFormZenoState(form);
-	if (!state.requiredIndicator) return false;
-	return state.requiredFields.has(toRequiredPathKey(name));
+	return getFormZenoState(form).requiredIndicator && isFieldRequiredBySchema(form, name);
 }
 //#endregion
-export { DEFAULT_VALIDATION_MODE, getFormHideFieldErrors, getFormValidationMode, isFieldRequired, setFormZenoState };
+export { DEFAULT_VALIDATION_MODE, getFormHideFieldErrors, getFormSchema, getFormValidationMode, isFieldRequired, isFieldRequiredBySchema, setFormZenoState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "repository": {
     "url": "https://github.com/zeno-lib/zeno.git",
     "directory": "packages/forms"

package/src/create-zeno-form.tsx

@@ -12,8 +12,12 @@ import { createFormHook } from "@tanstack/react-form"
 import { type ComponentProps, type ReactNode, useMemo } from "react"
 import { applyValidationError } from "./lib/apply-validation-error"
 import { fieldContext, formContext } from "./lib/contexts"
+import { withEmptyStartValues } from "./lib/empty-value"
 import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults"
-import { getRequiredPaths } from "./lib/schema-required"
+import {
+  getRequiredPaths,
+  type StandardSchemaLike,
+} from "./lib/schema-required"
 import { useRebasedDefaultValues } from "./lib/use-rebased-default-values"
 import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning"
 import { ValidationError } from "./lib/validation-error"
@@ -453,17 +457,20 @@ export function createZenoForm<
 
     const requiredFields = useMemo(
       () =>
-        schema && requiredIndicator
+        schema
           ? getRequiredPaths(schema as Parameters<typeof getRequiredPaths>[0])
           : new Set<string>(),
-      [schema, requiredIndicator]
+      [schema]
     )
 
     const schemaDefaults = useMemo(
       () =>
         schema
-          ? extractZodDefaults(
-              schema as Parameters<typeof extractZodDefaults>[0]
+          ? withEmptyStartValues(
+              schema as StandardSchemaLike,
+              extractZodDefaults(
+                schema as Parameters<typeof extractZodDefaults>[0]
+              )
             )
           : undefined,
       [schema]
@@ -515,6 +522,7 @@ export function createZenoForm<
       hideFieldErrors,
       requiredFields,
       requiredIndicator,
+      schema: schema as StandardSchemaLike | undefined,
       ...(schemaMode === undefined ? {} : { validation: schemaMode }),
     })
 

package/src/fields/checkbox-field.tsx

@@ -5,6 +5,7 @@ import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
 import { type ComponentProps, type ReactNode, useId } from "react"
@@ -24,7 +25,10 @@ type CheckboxFieldProps = Omit<
 > & {
   description?: ReactNode
   label?: ReactNode
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
 }
 
@@ -43,6 +47,8 @@ function CheckboxField({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   return (
     <Field
@@ -56,6 +62,7 @@ function CheckboxField({
           [showError, errorId]
         )}
         aria-invalid={isInvalid || undefined}
+        aria-required={requiresValue || undefined}
         checked={field.state.value ?? false}
         id={id}
         name={field.name}

package/src/fields/combobox-field.tsx

@@ -2,9 +2,11 @@
 
 import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
 import { type ReactNode, useId } from "react"
@@ -43,13 +45,17 @@ type ComboboxFieldProps<T = string> = {
   /** Override per-row rendering. Default: plain `<ComboboxItem>{label}</ComboboxItem>`. */
   renderItem?: (item: T) => ReactNode
   /**
-   * If `true`, show the clear button when a value is selected. Defaults to
-   * `true` — pass `false` for required-style comboboxes where clearing is
-   * disallowed.
+   * Show the clear button when a value is selected. Defaults to `true` on an
+   * optional field and `false` on a required one (from the schema or
+   * `required`), where clearing could only make the form invalid.
    */
   showClear?: boolean
+  disabled?: boolean
   className?: string
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*`,
+   * `aria-required` and the `showClear` default.
+   */
   required?: boolean
   /**
    * Controlled input text — pair with `onInputValueChange` for server-side
@@ -82,6 +88,7 @@ function isItemObject(item: unknown): item is ComboboxItemObject<unknown> {
 function ComboboxField<T = string>({
   className,
   description,
+  disabled,
   emptyMessage = "No results.",
   filter,
   inputValue,
@@ -92,7 +99,7 @@ function ComboboxField<T = string>({
   placeholder,
   renderItem,
   required,
-  showClear = true,
+  showClear,
 }: ComboboxFieldProps<T>) {
   const field = useFieldContext()
   const id = useId()
@@ -103,13 +110,20 @@ function ComboboxField<T = string>({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
+  const canClear = showClear ?? !requiresValue
 
   const fieldValue = field.state.value
-  const hasObjectItems = items.some(isItemObject)
-  const value = hasObjectItems
-    ? ((items.find((item) => isItemObject(item) && item.value === fieldValue) ??
-        null) as T | null)
-    : ((fieldValue ?? null) as T | null)
+  // Base UI shows the value it gets as text, so a stored id whose item isn't
+  // in `items` (options still loading, or a search that dropped it) would
+  // show raw. Only a plain string or number item is its own label.
+  const match = items.find(
+    (item) => (isItemObject(item) ? item.value : item) === fieldValue
+  )
+  const plainItems = items.length > 0 && !items.some(isItemObject)
+  const value = (match ??
+    (plainItems ? (fieldValue ?? null) : null)) as T | null
 
   return (
     <Field data-field={field.name} data-invalid={isInvalid}>
@@ -120,13 +134,14 @@ function ComboboxField<T = string>({
         </FieldLabel>
       )}
       <Combobox
+        disabled={disabled}
         filter={filter}
         inputValue={inputValue}
         items={items}
         onInputValueChange={onInputValueChange}
         onValueChange={(next) => {
           if (next === null) {
-            field.handleChange(undefined)
+            field.handleChange(getEmptyValue(field, undefined))
             return
           }
           field.handleChange(isItemObject(next) ? next.value : next)
@@ -139,12 +154,14 @@ function ComboboxField<T = string>({
             [showError, errorId]
           )}
           aria-invalid={isInvalid || undefined}
+          aria-required={requiresValue || undefined}
           className={className}
+          disabled={disabled}
           id={id}
           name={field.name}
           onBlur={field.handleBlur}
           placeholder={placeholder}
-          showClear={showClear && value !== null && value !== "" && !loading}
+          showClear={canClear && value !== null && value !== "" && !loading}
         >
           {loading && (
             <InputGroupAddon align="inline-end">