@zeno-lib/forms 0.9.1 → 0.10.0

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

@@ -1,6 +1,7 @@
 import { StandardSchemaLike } from "./schema-required.mjs";
 import { AnyFieldApi } from "@tanstack/react-form";
 //#region src/lib/empty-value.d.ts
+declare function toPathKeys(name: string): PropertyKey[];
 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>;
 /**
@@ -8,5 +9,12 @@ declare function withEmptyStartValues(schema: StandardSchemaLike, defaults: Reco
  * the field's value, since the same schema decides both.
  */
 declare function getEmptyValue<T>(field: AnyFieldApi, fallback: T): T;
+/**
+ * What a text control stores once its text is cleared: `null` where the field
+ * starts at `null` (a nullable string), so it saves as none, and `""`
+ * otherwise. Read from the schema's shape rather than by validating the form,
+ * so the other fields' values never change it.
+ */
+declare function getNoTextValue(field: AnyFieldApi): string | null;
 //#endregion
-export { emptyValueFor, getEmptyValue, withEmptyStartValues };
+export { emptyValueFor, getEmptyValue, getNoTextValue, toPathKeys, withEmptyStartValues };

package/dist/lib/empty-value.mjs

@@ -88,5 +88,16 @@ function withEmptyStartValues(schema, defaults) {
 function getEmptyValue(field, fallback) {
 	return emptyValueFor(getFormSchema(field.form), field.form.state.values, field.name, fallback);
 }
+/**
+* What a text control stores once its text is cleared: `null` where the field
+* starts at `null` (a nullable string), so it saves as none, and `""`
+* otherwise. Read from the schema's shape rather than by validating the form,
+* so the other fields' values never change it.
+*/
+function getNoTextValue(field) {
+	const schema = getFormSchema(field.form);
+	const start = schema ? extractZodDefaultAt(schema, toPathKeys(field.name)) : { ok: false };
+	return start.ok && start.value === null ? null : "";
+}
 //#endregion
-export { emptyValueFor, getEmptyValue, withEmptyStartValues };
+export { emptyValueFor, getEmptyValue, getNoTextValue, toPathKeys, withEmptyStartValues };

package/dist/lib/field-hints.d.mts

@@ -0,0 +1,18 @@
+import { AnyFieldApi } from "@tanstack/react-form";
+//#region src/lib/field-hints.d.ts
+/**
+ * What a field reads from the column its schema comes from, when the column's
+ * hint names it. The `percentage()` and `year()` columns of
+ * `@zeno-lib/db/schema` give one, so `PercentageField` and `YearField` show
+ * and clamp what the column accepts with no props: the scale from the hint,
+ * the bounds from the schema's own `.min()` and `.max()`, a caller's
+ * narrowing included. A prop the field is given wins.
+ */
+type FieldHints = {
+  readonly max?: number | undefined;
+  readonly min?: number | undefined;
+  readonly scale?: "fraction" | "percent" | undefined;
+};
+declare function getFieldHints(field: AnyFieldApi, kind: string): FieldHints;
+//#endregion
+export { type FieldHints, getFieldHints };

package/dist/lib/field-hints.mjs

@@ -0,0 +1,24 @@
+import { findZodSchemaAt } from "./schema-defaults.mjs";
+import { getFormSchema } from "./validation-modes.mjs";
+import { toPathKeys } from "./empty-value.mjs";
+//#region src/lib/field-hints.ts
+const FIELD_HINTS_KEY = Symbol.for("@zeno-lib/field-hints");
+const readHint = (node) => {
+	const hint = globalThis[FIELD_HINTS_KEY]?.get(node);
+	return typeof hint?.field === "string" ? hint : void 0;
+};
+const toBound = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+function getFieldHints(field, kind) {
+	const schema = getFormSchema(field.form);
+	const found = schema ? findZodSchemaAt(schema, toPathKeys(field.name), readHint) : void 0;
+	if (found?.value.field !== kind) return {};
+	const { scale } = found.value;
+	const { maxValue, minValue } = found.node;
+	return {
+		max: toBound(maxValue),
+		min: toBound(minValue),
+		scale: scale === "fraction" || scale === "percent" ? scale : void 0
+	};
+}
+//#endregion
+export { getFieldHints };

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

@@ -10,6 +10,7 @@ type SchemaDef = {
   readonly shape?: Record<string, SchemaNode>;
   readonly catchall?: SchemaNode;
   readonly in?: SchemaNode;
+  readonly out?: SchemaNode;
   readonly element?: SchemaNode;
   readonly defaultValue?: unknown;
 };
@@ -21,7 +22,11 @@ type ExtractResult = {
 };
 declare function extractZodDefaults(schema: SchemaNode): Record<string, unknown>;
 declare function extractZodDefaultAt(schema: SchemaNode, keys: readonly PropertyKey[]): ExtractResult;
+declare function findZodSchemaAt<T>(schema: SchemaNode, keys: readonly PropertyKey[], read: (node: SchemaNode) => T | undefined): {
+  node: SchemaNode;
+  value: T;
+} | undefined;
 declare function pickSchemaShape<T>(schema: SchemaNode, value: T): T;
 declare function deepMergeDefaults(schemaDefaults: Record<string, unknown>, userDefaults: Record<string, unknown> | undefined): Record<string, unknown>;
 //#endregion
-export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults, pickSchemaShape };
+export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults, findZodSchemaAt, pickSchemaShape };

package/dist/lib/schema-defaults.mjs

@@ -5,6 +5,7 @@ function getDef(node) {
 }
 function extractDefaultForField(node) {
 	let current = node;
+	let isNullable = false;
 	for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
 		const def = getDef(current);
 		if (!def?.type) return { ok: false };
@@ -14,8 +15,11 @@ function extractDefaultForField(node) {
 				ok: true,
 				value: def.defaultValue
 			};
-			case "optional":
 			case "nullable":
+				isNullable = true;
+				current = def.innerType;
+				continue;
+			case "optional":
 			case "nonoptional":
 			case "readonly":
 				current = def.innerType;
@@ -25,7 +29,7 @@ function extractDefaultForField(node) {
 				continue;
 			case "string": return {
 				ok: true,
-				value: ""
+				value: isNullable ? null : ""
 			};
 			case "array": return {
 				ok: true,
@@ -89,6 +93,35 @@ function extractZodDefaultAt(schema, keys) {
 		return { ok: false };
 	}
 }
+function unwrapped(node) {
+	const def = getDef(node);
+	switch (def?.type) {
+		case "catch":
+		case "default":
+		case "nonoptional":
+		case "nullable":
+		case "optional":
+		case "prefault":
+		case "readonly": return def.innerType;
+		case "pipe": return getDef(def.in)?.type === "transform" ? def.out : def.in;
+		default: return;
+	}
+}
+function findZodSchemaAt(schema, keys, read) {
+	try {
+		let node = schema;
+		for (const key of keys) node = node && childAt(node, key);
+		let current = node && keys.length > 0 ? node : void 0;
+		for (let depth = 0; current && depth < MAX_WRAPPER_DEPTH; depth += 1) {
+			const value = read(current);
+			if (value !== void 0) return {
+				node: current,
+				value
+			};
+			current = unwrapped(current);
+		}
+	} catch {}
+}
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
 }
@@ -146,4 +179,4 @@ function deepMergeDefaults(schemaDefaults, userDefaults) {
 	return result;
 }
 //#endregion
-export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults, pickSchemaShape };
+export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults, findZodSchemaAt, pickSchemaShape };

package/package.json

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

package/src/field-hints.test.tsx

@@ -0,0 +1,118 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(cleanup)
+
+type Hint = { field: string; scale?: "fraction" | "percent" }
+
+// Where `@zeno-lib/schema` registers a column's hint.
+const HINTS_KEY = Symbol.for("@zeno-lib/field-hints")
+const holder = globalThis as {
+  [HINTS_KEY]?: z.core.$ZodRegistry<Hint>
+}
+const hints = holder[HINTS_KEY] ?? z.registry<Hint>()
+holder[HINTS_KEY] = hints
+
+const hinted = <T extends z.ZodType>(column: T, hint: Hint) => {
+  hints.add(column, hint)
+  return column
+}
+
+// What a `percentage()` or `year()` column of `@zeno-lib/db/schema` hands a
+// form: the rule, its hint, and the wrappers of a nullable column.
+const schema = z.object({
+  built: hinted(z.int().min(1900).max(2100), { field: "year" })
+    .nullable()
+    .optional(),
+  occupancy: hinted(z.number().min(0).max(1), {
+    field: "percentage",
+    scale: "fraction",
+  })
+    .nullable()
+    .optional()
+    // Metadata of the form's own, around the column's schema.
+    .describe("Share of the floor area let"),
+  rate: hinted(z.number().min(-1).max(1), {
+    field: "percentage",
+    scale: "fraction",
+  })
+    // A caller's refinement narrows the column's bounds.
+    .max(0.5)
+    .nullable()
+    .optional(),
+})
+
+const captured: { values?: z.input<typeof schema> } = {}
+
+function Harness({ occupancyMax }: { occupancyMax?: number }) {
+  const form = useForm({
+    defaultValues: { occupancy: 0.125 },
+    onSubmit: vi.fn(),
+    schema,
+  })
+  const { PercentageField, Subscribe, YearField } = form
+  return (
+    <FormProvider form={form}>
+      <Form>
+        <PercentageField
+          label="Occupancy"
+          locale="en-US"
+          max={occupancyMax}
+          name="occupancy"
+        />
+        <PercentageField label="Rate" locale="en-US" name="rate" />
+        <YearField label="Built" name="built" />
+        <Subscribe selector={(state) => state.values}>
+          {(values) => {
+            captured.values = values
+            return null
+          }}
+        </Subscribe>
+      </Form>
+    </FormProvider>
+  )
+}
+
+test("a percentage field takes its scale and bounds from the column's hint", async () => {
+  const user = userEvent.setup()
+  render(<Harness />)
+  const occupancy = screen.getByLabelText("Occupancy") as HTMLInputElement
+  expect(occupancy.value).toBe("12.5")
+
+  await user.clear(occupancy)
+  await user.type(occupancy, "150")
+  await user.tab()
+  expect(captured.values?.occupancy).toBe(1)
+
+  // A bound below 0 lets the field take a negative rate, and the field
+  // clamps to the bound the schema narrowed.
+  const rate = screen.getByLabelText("Rate")
+  await user.type(rate, "-25")
+  await user.tab()
+  expect(captured.values?.rate).toBe(-0.25)
+  await user.clear(rate)
+  await user.type(rate, "90")
+  await user.tab()
+  expect(captured.values?.rate).toBe(0.5)
+})
+
+test("a year field clamps to the column's hinted bounds", async () => {
+  const user = userEvent.setup()
+  render(<Harness />)
+  await user.type(screen.getByLabelText("Built"), "1850")
+  await user.tab()
+  expect(captured.values?.built).toBe(1900)
+})
+
+test("a prop wins over the hint", async () => {
+  const user = userEvent.setup()
+  render(<Harness occupancyMax={0.5} />)
+  const occupancy = screen.getByLabelText("Occupancy")
+  await user.clear(occupancy)
+  await user.type(occupancy, "90")
+  await user.tab()
+  expect(captured.values?.occupancy).toBe(0.5)
+})

package/src/fields/input-field.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { getNoTextValue } from "@zeno-lib/forms/lib/empty-value"
 import { useFieldControl } from "@zeno-lib/forms/lib/use-field-control"
 import { Children, type ComponentProps, type ReactNode } from "react"
 import { Input } from "@/components/ui/input"
@@ -29,10 +30,10 @@ function InputField({
   required,
   ...props
 }: InputFieldProps) {
-  const field = useFieldContext<string>()
+  const field = useFieldContext<string | null>()
   // The label names the input through `htmlFor`, so the input needs no
   // `aria-labelledby` and the hook doesn't get `label`.
-  const { controlProps, ...shell } = useFieldControl<string>({
+  const { controlProps, ...shell } = useFieldControl<string | null>({
     description,
     disabled,
     required,
@@ -40,11 +41,12 @@ function InputField({
   const hasAddons = Children.count(children) > 0
 
   // A text input keeps the `""` the user typed, where `controlProps.onChange`
-  // would store the field's empty value.
+  // would store the field's empty value, unless the schema takes `null`: then
+  // no text is `null`, as the field starts, so it saves as none.
   const inputProps = {
     ...controlProps,
     onChange: (event: React.ChangeEvent<HTMLInputElement>) =>
-      field.handleChange(event.target.value),
+      field.handleChange(event.target.value || getNoTextValue(field)),
     value: field.state.value ?? "",
     ...props,
   }

package/src/fields/percentage-field.tsx

@@ -2,6 +2,7 @@
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
+import { getFieldHints } from "@zeno-lib/forms/lib/field-hints"
 import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
 import { InputGroupAddon, InputGroupText } from "@/components/ui/input-group"
 import { InputField, type InputFieldProps } from "./input-field"
@@ -14,13 +15,16 @@ type PercentageFieldProps = Omit<
    * How the form value relates to what the user types:
    * - `"percent"` (default): the value is the number shown, `12.5` ↔ `12.5 %`.
    * - `"fraction"`: the value is a ratio, `0.125` ↔ `12.5 %`.
+   *
+   * A `percentage()` column of `@zeno-lib/db/schema` sets it, as it sets
+   * `min` and `max`.
    */
   scale?: "fraction" | "percent"
   /** BCP 47 locale driving the decimal separator. Defaults to the runtime locale. */
   locale?: string
   /** Digits allowed after the decimal separator (of the shown percentage). Defaults to `2`. */
   fractionDigits?: number
-  /** Accept negative percentages. Defaults to `false`. */
+  /** Accept negative percentages. Defaults to whether `min` is below 0. */
   allowNegative?: boolean
   /** Clamp on blur, in the form value's scale. */
   min?: number
@@ -33,23 +37,27 @@ const fromPercent = (value: number) => value / 100
 
 /**
  * Percentage input with a `%` add-on. The form value is `number | null`, on
- * the `scale` you pick (`0–100` by default, `0–1` with `scale="fraction"`).
+ * the `scale` you pick, or the one the schema's `percentage()` column hints
+ * (`0–100` by default, `0–1` with `scale="fraction"`).
  */
 function PercentageField({
-  allowNegative = false,
+  allowNegative,
   children,
   fractionDigits = 2,
   locale,
-  max,
-  min,
-  scale = "percent",
+  max: maxProp,
+  min: minProp,
+  scale: scaleProp,
   ...props
 }: PercentageFieldProps) {
   const field = useFieldContext<number | null | undefined>()
-  const isFraction = scale === "fraction"
+  const hints = getFieldHints(field, "percentage")
+  const max = maxProp ?? hints.max
+  const min = minProp ?? hints.min
+  const isFraction = (scaleProp ?? hints.scale ?? "percent") === "fraction"
 
   const inputProps = useFormattedNumber({
-    allowNegative,
+    allowNegative: allowNegative ?? (min !== undefined && min < 0),
     locale,
     max,
     maximumFractionDigits: fractionDigits,

package/src/fields/textarea-field.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { getNoTextValue } from "@zeno-lib/forms/lib/empty-value"
 import { useFieldControl } from "@zeno-lib/forms/lib/use-field-control"
 import { Children, type ComponentProps, type ReactNode } from "react"
 import { InputGroup, InputGroupTextarea } from "@/components/ui/input-group"
@@ -29,10 +30,10 @@ function TextAreaField({
   required,
   ...props
 }: TextAreaFieldProps) {
-  const field = useFieldContext<string>()
+  const field = useFieldContext<string | null>()
   // The label names the textarea through `htmlFor`, so the textarea needs no
   // `aria-labelledby` and the hook doesn't get `label`.
-  const { controlProps, ...shell } = useFieldControl<string>({
+  const { controlProps, ...shell } = useFieldControl<string | null>({
     description,
     disabled,
     required,
@@ -40,11 +41,12 @@ function TextAreaField({
   const hasAddons = Children.count(children) > 0
 
   // A textarea keeps the `""` the user typed, where `controlProps.onChange`
-  // would store the field's empty value.
+  // would store the field's empty value, unless the schema takes `null`: then
+  // no text is `null`, as the field starts, so it saves as none.
   const textareaProps = {
     ...controlProps,
     onChange: (event: React.ChangeEvent<HTMLTextAreaElement>) =>
-      field.handleChange(event.target.value),
+      field.handleChange(event.target.value || getNoTextValue(field)),
     value: field.state.value ?? "",
     ...props,
   }

package/src/fields/year-field.tsx

@@ -2,6 +2,7 @@
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
+import { getFieldHints } from "@zeno-lib/forms/lib/field-hints"
 import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
 import { InputField, type InputFieldProps } from "./input-field"
 
@@ -25,13 +26,17 @@ type YearFieldProps = Omit<
 
 /**
  * Four-digit year input. The form value is an integer year or `null`. No
- * thousands separator, digits only, clamped to `min`/`max` on blur.
+ * thousands separator, digits only, clamped on blur to `min`/`max`, or to the
+ * bounds the schema's `year()` column hints.
  */
-function YearField({ max, min, ...props }: YearFieldProps) {
+function YearField({ max: maxProp, min: minProp, ...props }: YearFieldProps) {
   const field = useFieldContext<number | null | undefined>()
+  const hints = getFieldHints(field, "year")
+  const max = maxProp ?? hints.max
+  const min = minProp ?? hints.min
 
   const inputProps = useFormattedNumber({
-    allowNegative: false,
+    allowNegative: min !== undefined && min < 0,
     max,
     maxIntegerDigits: 4,
     maximumFractionDigits: 0,

package/src/lib/empty-value.ts

@@ -171,4 +171,27 @@ function getEmptyValue<T>(field: AnyFieldApi, fallback: T): T {
   ) as T
 }
 
-export { emptyValueFor, getEmptyValue, withEmptyStartValues }
+/**
+ * What a text control stores once its text is cleared: `null` where the field
+ * starts at `null` (a nullable string), so it saves as none, and `""`
+ * otherwise. Read from the schema's shape rather than by validating the form,
+ * so the other fields' values never change it.
+ */
+function getNoTextValue(field: AnyFieldApi): string | null {
+  const schema = getFormSchema(field.form)
+  const start = schema
+    ? extractZodDefaultAt(
+        schema as Parameters<typeof extractZodDefaultAt>[0],
+        toPathKeys(field.name)
+      )
+    : { ok: false as const }
+  return start.ok && start.value === null ? null : ""
+}
+
+export {
+  emptyValueFor,
+  getEmptyValue,
+  getNoTextValue,
+  toPathKeys,
+  withEmptyStartValues,
+}

package/src/lib/field-hints.ts

@@ -0,0 +1,64 @@
+import type { AnyFieldApi } from "@tanstack/react-form"
+import { toPathKeys } from "./empty-value"
+import { findZodSchemaAt } from "./schema-defaults"
+import { getFormSchema } from "./validation-modes"
+
+/**
+ * What a field reads from the column its schema comes from, when the column's
+ * hint names it. The `percentage()` and `year()` columns of
+ * `@zeno-lib/db/schema` give one, so `PercentageField` and `YearField` show
+ * and clamp what the column accepts with no props: the scale from the hint,
+ * the bounds from the schema's own `.min()` and `.max()`, a caller's
+ * narrowing included. A prop the field is given wins.
+ */
+type FieldHints = {
+  readonly max?: number | undefined
+  readonly min?: number | undefined
+  readonly scale?: "fraction" | "percent" | undefined
+}
+
+// The registry `@zeno-lib/schema` puts each column's hint in, under a
+// `globalThis` symbol both packages name, so this one reads it without
+// importing that one. Absent until `@zeno-lib/schema` loads, and then no
+// field has a hint.
+const FIELD_HINTS_KEY = Symbol.for("@zeno-lib/field-hints")
+
+type HintRegistry = { readonly get: (schema: object) => unknown }
+
+type Bounded = { readonly maxValue?: unknown; readonly minValue?: unknown }
+
+const readHint = (node: object) => {
+  const registry = (globalThis as { [FIELD_HINTS_KEY]?: HintRegistry })[
+    FIELD_HINTS_KEY
+  ]
+  const hint = registry?.get(node) as { field?: unknown } | undefined
+  return typeof hint?.field === "string" ? hint : undefined
+}
+
+// A schema with no `.min()` or `.max()` reports `null` or an infinity.
+const toBound = (value: unknown) =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined
+
+function getFieldHints(field: AnyFieldApi, kind: string): FieldHints {
+  const schema = getFormSchema(field.form)
+  const found = schema
+    ? findZodSchemaAt(
+        schema as Parameters<typeof findZodSchemaAt>[0],
+        toPathKeys(field.name),
+        readHint
+      )
+    : undefined
+  if (found?.value.field !== kind) {
+    return {}
+  }
+  const { scale } = found.value as { scale?: unknown }
+  const { maxValue, minValue } = found.node as Bounded
+  return {
+    max: toBound(maxValue),
+    min: toBound(minValue),
+    scale: scale === "fraction" || scale === "percent" ? scale : undefined,
+  }
+}
+
+export type { FieldHints }
+export { getFieldHints }

package/src/lib/schema-defaults.test.ts

@@ -65,9 +65,12 @@ describe("extractZodDefaults — wrappers", () => {
     expect(extractZodDefaults(schema)).toEqual({ x: "" })
   })
 
-  test(".nullable() unwraps to inner string → ''", () => {
-    const schema = z.object({ x: z.string().nullable() })
-    expect(extractZodDefaults(schema)).toEqual({ x: "" })
+  test(".nullable() starts a string at null, which a nullable column stores", () => {
+    const schema = z.object({
+      x: z.string().nullable(),
+      y: z.string().nullable().optional(),
+    })
+    expect(extractZodDefaults(schema)).toEqual({ x: null, y: null })
   })
 
   test(".readonly() unwraps to inner string → ''", () => {

package/src/lib/schema-defaults.ts

@@ -4,7 +4,8 @@
 // Tier A+ semantics:
 //   - `.default(...)` / `.prefault(...)` values flow through.
 //   - Strings (and string-format subtypes — email, url, uuid, regex, …) without
-//     a default fall back to `""` so React inputs render controlled.
+//     a default fall back to `""` so React inputs render controlled, or to
+//     `null` under `.nullable()`, which the fields render as no text.
 //   - Arrays without a default fall back to `[]`.
 //   - Nested `z.object(...)` recurses; emits a sub-record only if at least one
 //     leaf produced a value.
@@ -26,6 +27,7 @@ type SchemaDef = {
   readonly shape?: Record<string, SchemaNode>
   readonly catchall?: SchemaNode
   readonly in?: SchemaNode
+  readonly out?: SchemaNode
   readonly element?: SchemaNode
   readonly defaultValue?: unknown
 }
@@ -40,6 +42,7 @@ function getDef(node: SchemaNode | undefined): SchemaDef | undefined {
 
 function extractDefaultForField(node: SchemaNode): ExtractResult {
   let current: SchemaNode | undefined = node
+  let isNullable = false
   for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
     const def: SchemaDef | undefined = getDef(current)
     if (!def?.type) {
@@ -49,8 +52,11 @@ function extractDefaultForField(node: SchemaNode): ExtractResult {
       case "default":
       case "prefault":
         return { ok: true, value: def.defaultValue }
-      case "optional":
       case "nullable":
+        isNullable = true
+        current = def.innerType
+        continue
+      case "optional":
       case "nonoptional":
       case "readonly":
         current = def.innerType
@@ -58,8 +64,10 @@ function extractDefaultForField(node: SchemaNode): ExtractResult {
       case "pipe":
         current = def.in
         continue
+      // No text is `null` where the schema takes it, as a nullable column
+      // stores it, so a field left blank saves as none rather than as `""`.
       case "string":
-        return { ok: true, value: "" }
+        return { ok: true, value: isNullable ? null : "" }
       case "array":
         return { ok: true, value: [] }
       case "object": {
@@ -142,6 +150,54 @@ function extractZodDefaultAt(
   }
 }
 
+// The schema inside a wrapper, or `undefined` past the last one.
+function unwrapped(node: SchemaNode): SchemaNode | undefined {
+  const def: SchemaDef | undefined = getDef(node)
+  switch (def?.type) {
+    case "catch":
+    case "default":
+    case "nonoptional":
+    case "nullable":
+    case "optional":
+    case "prefault":
+    case "readonly":
+      return def.innerType
+    // `z.preprocess` pipes a transform into the schema it feeds.
+    case "pipe":
+      return getDef(def.in)?.type === "transform" ? def.out : def.in
+    default:
+      return undefined
+  }
+}
+
+// The schema at `keys`, or inside one of its wrappers, that `read` finds a
+// value on, with that value. A Zod registry keeps an entry on the schema it
+// was set on, not on the `.optional()` or `.nullable()` around it.
+function findZodSchemaAt<T>(
+  schema: SchemaNode,
+  keys: readonly PropertyKey[],
+  read: (node: SchemaNode) => T | undefined
+): { node: SchemaNode; value: T } | undefined {
+  try {
+    let node: SchemaNode | null = schema
+    for (const key of keys) {
+      node = node && childAt(node, key)
+    }
+    let current: SchemaNode | undefined =
+      node && keys.length > 0 ? node : undefined
+    for (let depth = 0; current && depth < MAX_WRAPPER_DEPTH; depth += 1) {
+      const value = read(current)
+      if (value !== undefined) {
+        return { node: current, value }
+      }
+      current = unwrapped(current)
+    }
+  } catch {
+    // An unrecognised schema has nothing to offer.
+  }
+  return undefined
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return (
     typeof value === "object" &&
@@ -244,5 +300,6 @@ export {
   deepMergeDefaults,
   extractZodDefaultAt,
   extractZodDefaults,
+  findZodSchemaAt,
   pickSchemaShape,
 }

package/src/nullable-text.test.tsx

@@ -0,0 +1,80 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(cleanup)
+
+test("a nullable text field holds null for no text, from the start and once emptied", async () => {
+  const user = userEvent.setup()
+  const schema = z.object({
+    note: z.string().nullable(),
+    optional: z.string().optional(),
+    title: z.string(),
+  })
+  const captured: { values?: unknown } = {}
+  function H() {
+    const form = useForm({ onSubmit: vi.fn(), schema })
+    const { InputField, Subscribe, TextAreaField } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <TextAreaField label="Note" name="note" />
+          <InputField label="Optional" name="optional" />
+          <InputField label="Title" name="title" />
+          <Subscribe selector={(state) => state.values}>
+            {(values) => {
+              captured.values = values
+              return null
+            }}
+          </Subscribe>
+        </Form>
+      </FormProvider>
+    )
+  }
+  render(<H />)
+  // An optional field keeps `""`: an update skips an `undefined` column, so
+  // emptying it would keep the stored text.
+  const empty = { note: null, optional: "", title: "" }
+  expect(captured.values).toStrictEqual(empty)
+
+  for (const label of ["Note", "Optional", "Title"]) {
+    // biome-ignore lint/performance/noAwaitInLoops: one field after another, as a user types
+    await user.type(screen.getByLabelText(label), "x")
+    await user.clear(screen.getByLabelText(label))
+  }
+  expect(captured.values).toStrictEqual(empty)
+})
+
+test("an emptied nullable text field holds null whatever the other fields hold", async () => {
+  const user = userEvent.setup()
+  // Once every field passes, the async refinement keeps the form from being
+  // checked synchronously.
+  const schema = z
+    .object({ note: z.string().nullable() })
+    .refine(async () => await Promise.resolve(true))
+  const captured: { values?: unknown } = {}
+  function H() {
+    const form = useForm({ onSubmit: vi.fn(), schema })
+    const { InputField, Subscribe } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <InputField label="Note" name="note" />
+          <Subscribe selector={(state) => state.values}>
+            {(values) => {
+              captured.values = values
+              return null
+            }}
+          </Subscribe>
+        </Form>
+      </FormProvider>
+    )
+  }
+  render(<H />)
+
+  await user.type(screen.getByRole("textbox"), "x")
+  await user.clear(screen.getByRole("textbox"))
+  expect(captured.values).toStrictEqual({ note: null })
+})