@zeno-lib/forms 0.3.0 → 0.4.0

package/src/lib/empty-value.ts

@@ -0,0 +1,130 @@
+import type { AnyFieldApi } from "@tanstack/react-form"
+
+import { toFieldName } from "./action-result"
+import { extractZodDefaultAt } from "./schema-defaults"
+import { type StandardSchemaLike, validateSync } from "./schema-required"
+import { getFormSchema } from "./validation-modes"
+
+// A field's empty value is the first one its schema accepts of `null`,
+// `undefined` and the type's own empty value (`""` for a string, `[]` for an
+// array, through `extractZodDefaults`). So `.nullable()` empties to `null`,
+// `.optional()` to `undefined`, and a bare `z.string()` to `""`. A field that
+// accepts none of them is required. A cleared field holds its empty value,
+// and so does an untouched one whose schema rejects `""` or `[]`.
+
+const NAME_SEGMENT = /[^.[\]]+/g
+const INDEX = /^\d+$/
+
+// `members[2].name` (or `members.2.name`) → `["members", 2, "name"]`.
+function toPathKeys(name: string): PropertyKey[] {
+  return (name.match(NAME_SEGMENT) ?? []).map((part) =>
+    INDEX.test(part) ? Number(part) : part
+  )
+}
+
+function valueAt(root: unknown, keys: readonly PropertyKey[]): unknown {
+  let node = root
+  for (const key of keys) {
+    if (typeof node !== "object" || node === null) {
+      return
+    }
+    node = (node as Record<PropertyKey, unknown>)[key]
+  }
+  return node
+}
+
+// A copy of `root` with `value` at `keys`, copying only the nodes on the way.
+function withValueAt(
+  root: unknown,
+  keys: readonly PropertyKey[],
+  value: unknown
+): unknown {
+  const [key, ...rest] = keys
+  if (key === undefined) {
+    return value
+  }
+  const node = (root ?? (typeof key === "number" ? [] : {})) as Record<
+    PropertyKey,
+    unknown
+  >
+  const copy = (Array.isArray(node) ? [...node] : { ...node }) as Record<
+    PropertyKey,
+    unknown
+  >
+  copy[key] = withValueAt(node[key], rest, value)
+  return copy
+}
+
+function emptyValueFor(
+  schema: StandardSchemaLike | undefined,
+  values: unknown,
+  name: string,
+  fallback: unknown
+): unknown {
+  if (!schema) {
+    return fallback
+  }
+  const keys = toPathKeys(name)
+  const fieldName = toFieldName(keys)
+  const typeEmpty = extractZodDefaultAt(
+    schema as Parameters<typeof extractZodDefaultAt>[0],
+    keys
+  )
+  const candidates = typeEmpty.ok
+    ? [null, undefined, typeEmpty.value]
+    : [null, undefined]
+  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: unknown): boolean {
+  return value === "" || (Array.isArray(value) && value.length === 0)
+}
+
+// `extractZodDefaults` starts every string at `""` and every array at `[]`.
+// Where the schema rejects that (`z.uuid().nullable()`,
+// `z.email().optional()`), start the field at its empty value instead, so an
+// untouched optional field passes. A required one keeps `""` or `[]`.
+function withEmptyStartValues(
+  schema: StandardSchemaLike,
+  defaults: Record<string, unknown>
+): Record<string, unknown> {
+  const issues = validateSync(schema, defaults)
+  let result: unknown = 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 as 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.
+ */
+function getEmptyValue<T>(field: AnyFieldApi, fallback: T): T {
+  return emptyValueFor(
+    getFormSchema(field.form),
+    field.form.state.values,
+    field.name,
+    fallback
+  ) as T
+}
+
+export { emptyValueFor, getEmptyValue, withEmptyStartValues }

package/src/lib/schema-defaults.ts

@@ -24,6 +24,7 @@ type SchemaDef = {
   readonly innerType?: SchemaNode
   readonly shape?: Record<string, SchemaNode>
   readonly in?: SchemaNode
+  readonly element?: SchemaNode
   readonly defaultValue?: unknown
 }
 
@@ -91,6 +92,54 @@ function extractZodDefaults(schema: SchemaNode): Record<string, unknown> {
   }
 }
 
+// Step from an object or array schema into its `key` child, through any
+// wrapper around it. `null` when there is none.
+function childAt(node: SchemaNode, key: PropertyKey): SchemaNode | null {
+  let current: SchemaNode | undefined = node
+  for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
+    const def: SchemaDef | undefined = 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
+}
+
+// The value `extractZodDefaults` starts the field at `keys` at, array rows
+// included (`["members", 2, "name"]`). `{ ok: false }` when it gives none.
+function extractZodDefaultAt(
+  schema: SchemaNode,
+  keys: readonly PropertyKey[]
+): ExtractResult {
+  try {
+    let node: SchemaNode | null = 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: unknown): value is Record<string, unknown> {
   return (
     typeof value === "object" &&
@@ -124,4 +173,4 @@ function deepMergeDefaults(
   return result
 }
 
-export { deepMergeDefaults, extractZodDefaults }
+export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults }

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

@@ -58,6 +58,22 @@ describe("getRequiredPaths", () => {
     expect(required.has("members[0].name")).toBe(true)
   })
 
+  test("a field that accepts null is not required", () => {
+    const schema = z.object({
+      count: z.number(),
+      day: z.date().nullable(),
+      kind: z.enum(["a", "b"]).nullable(),
+      ownerId: z.uuid().nullable(),
+      total: z.number().nullable(),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("count")).toBe(true)
+    expect(required.has("day")).toBe(false)
+    expect(required.has("kind")).toBe(false)
+    expect(required.has("ownerId")).toBe(false)
+    expect(required.has("total")).toBe(false)
+  })
+
   test("nested z.object reports the parent and its required children", () => {
     const schema = z.object({
       profile: z.object({
@@ -80,20 +96,26 @@ describe("getRequiredPaths", () => {
 
   test("array rows are reported with TanStack bracket syntax", () => {
     const schema = z.object({
+      emails: z.array(z.email()),
       members: z.array(
         z.object({
           name: z.string().min(1),
           note: z.string().optional(),
         })
       ),
+      picked: z.array(z.string()).min(1),
       tags: z.array(z.string()),
     })
     const required = getRequiredPaths(schema)
-    expect(required.has("members")).toBe(true)
     expect(required.has("members[0].name")).toBe(true)
     expect(required.has("members.0.name")).toBe(false)
     expect(required.has("members[0].note")).toBe(false)
-    expect(required.has("tags[0]")).toBe(true)
+    expect(required.has("emails[0]")).toBe(true)
+    expect(required.has("picked")).toBe(true)
+    // `[]` and `""` are what the form starts them at, and both pass.
+    expect(required.has("members")).toBe(false)
+    expect(required.has("tags")).toBe(false)
+    expect(required.has("tags[0]")).toBe(false)
   })
 
   test("nested arrays descend through every level", () => {

package/src/lib/schema-required.ts

@@ -9,14 +9,17 @@
 // A missing parent hides its children (the schema stops at the missing key), so
 // the probe descends: when an issue says it expected an object or an array
 // (Zod and Valibot both put that on `issue.expected`), the next pass fills that
-// path with `{}` / `[{}]` and validates again. Array rows are probed through
-// index `0` and recorded index-agnostically, so `members[0].name` in the set
-// matches every row's `members[3].name` via `toRequiredPathKey`.
+// path and validates again. An object gets `{}`. An array gets one missing row
+// (`[undefined]`), so the following pass probes the row's own schema. Rows are
+// probed through index `0` and recorded index-agnostically, so
+// `members[0].name` in the set matches every row's `members[3].name` via
+// `toRequiredPathKey`.
 //
-// A missing string is probed again as `""`, the value the form starts it at
-// (`extractZodDefaults`). A field that accepts `""` (a bare `z.string()`)
-// can't fail while untouched, so it leaves the set; one that rejects it
-// (`.min(1)`, `z.email()`) stays.
+// A missing field is then probed with an empty value: `""` for a string, then
+// `null`; `[]` for an array; `null` for anything else. A field that accepts one
+// (a bare `z.string()` or `z.array()`, anything `.nullable()`) leaves the set,
+// matching `lib/empty-value.ts`; one that rejects them all (`.min(1)`,
+// `z.email()`, a bare `z.number()`) stays.
 //
 // Paths use TanStack Form's field-name syntax: dots for object keys, brackets
 // for array indices (`members[0].name`, not `members.0.name`).
@@ -47,7 +50,8 @@ type StandardSchemaLike = {
   }
 }
 
-const MAX_PROBE_DEPTH = 8
+// Each level can take two passes: the empty value, then the descent.
+const MAX_PROBE_DEPTH = 16
 
 const INDEX_SEGMENT = /^\d+$/
 
@@ -92,26 +96,25 @@ function toRequiredPathKey(name: string): string {
 }
 
 function probeValue(expected: unknown): unknown {
-  if (typeof expected !== "string") {
-    return
-  }
-  switch (expected.toLowerCase()) {
+  switch (typeof expected === "string" ? expected.toLowerCase() : undefined) {
     case "object":
       return {}
     case "array":
-      return [{}]
+      return []
     case "string":
       return ""
     default:
-      return
+      return null
   }
 }
 
-// Write `value` at `keys` inside `root`, only where nothing is set yet.
+// Write `value` at `keys` inside `root`, only where nothing is set yet unless
+// `replace` is set.
 function fillAt(
   root: Record<PropertyKey, unknown>,
   keys: readonly PropertyKey[],
-  value: unknown
+  value: unknown,
+  replace = false
 ): boolean {
   let node: Record<PropertyKey, unknown> = root
   for (const key of keys.slice(0, -1)) {
@@ -122,7 +125,7 @@ function fillAt(
     node = next as Record<PropertyKey, unknown>
   }
   const last = keys.at(-1) as PropertyKey
-  if (node[last] !== undefined) {
+  if (!replace && node[last] !== undefined) {
     return false
   }
   node[last] = value
@@ -145,22 +148,27 @@ function validateSync(
   return "issues" in result && result.issues ? result.issues : []
 }
 
+type ProbeFill = {
+  readonly keys: readonly PropertyKey[]
+  readonly path: string
+  readonly value: unknown
+}
+
 type ProbePass = {
-  readonly descended: boolean
   readonly failing: ReadonlySet<string>
-  readonly filledStrings: readonly string[]
+  readonly filled: readonly ProbeFill[]
 }
 
 // Record one pass's failing paths, and fill the probe at each of them for the
-// next pass.
+// next pass. A path whose empty value already passed stays out of the set.
 function recordPass(
   issues: readonly StandardIssue[],
   probe: Record<PropertyKey, unknown>,
-  required: Set<string>
+  required: Set<string>,
+  cleared: ReadonlySet<string>
 ): ProbePass {
   const failing = new Set<string>()
-  const filledStrings: string[] = []
-  let descended = false
+  const filled: ProbeFill[] = []
   for (const issue of issues) {
     const keys = issue.path?.map(pathKey) ?? []
     if (keys.length === 0) {
@@ -168,40 +176,70 @@ function recordPass(
     }
     const path = joinPath(keys)
     failing.add(path)
-    required.add(path)
+    if (!cleared.has(path)) {
+      required.add(path)
+    }
     const value = probeValue(issue.expected)
     if (value !== undefined && fillAt(probe, keys, value)) {
+      filled.push({ keys, path, value })
+    }
+  }
+  return { failing, filled }
+}
+
+function isEmptyProbe(value: unknown): boolean {
+  return value === "" || value === null || Array.isArray(value)
+}
+
+// Settle what the previous pass filled with an empty value: a path that now
+// passes leaves the required set. A string that rejects `""` gets `null` next,
+// and an array checked empty gets one missing row, so the row is probed.
+function settleEmptied(
+  emptied: readonly ProbeFill[],
+  failing: ReadonlySet<string>,
+  probe: Record<PropertyKey, unknown>,
+  required: Set<string>,
+  cleared: Set<string>
+): { readonly next: ProbeFill[]; readonly descended: boolean } {
+  const next: ProbeFill[] = []
+  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(undefined)
+      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 }
+  return { descended, next }
 }
 
 function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
   const required = new Set<string>()
+  const cleared = new Set<string>()
   const probe: Record<PropertyKey, unknown> = {}
-  // Paths the previous pass filled with `""`: they stay only if they still fail.
-  let filledStrings: readonly string[] = []
+  // What the previous pass filled with an empty value: each stays required
+  // only if it still fails.
+  let emptied: readonly ProbeFill[] = []
   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) {
+    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
     }
   }
@@ -209,4 +247,4 @@ function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
 }
 
 export type { StandardSchemaLike }
-export { getRequiredPaths, toRequiredPathKey }
+export { getRequiredPaths, toRequiredPathKey, validateSync }

package/src/lib/use-is-invalid.ts

@@ -6,6 +6,7 @@ import {
   getFormHideFieldErrors,
   getFormValidationMode,
   isFieldRequired,
+  isFieldRequiredBySchema,
   type ValidationMode,
 } from "./validation-modes"
 
@@ -106,4 +107,16 @@ function useIsFieldRequired(field: AnyFieldApi): boolean {
   return isFieldRequired(field.form, field.name)
 }
 
-export { useHideFieldErrors, useIsFieldRequired, useIsInvalid }
+// Returns whether the form's schema requires this field, even with
+// `requiredIndicator: false`. Drives what a required field does (no clear
+// button, `aria-required`), where `useIsFieldRequired` drives the `*`.
+function useIsFieldRequiredBySchema(field: AnyFieldApi): boolean {
+  return isFieldRequiredBySchema(field.form, field.name)
+}
+
+export {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsFieldRequiredBySchema,
+  useIsInvalid,
+}

package/src/lib/validation-modes.ts

@@ -2,7 +2,7 @@
 
 import type { AnyFormApi } from "@tanstack/react-form"
 
-import { toRequiredPathKey } from "./schema-required"
+import { type StandardSchemaLike, toRequiredPathKey } from "./schema-required"
 
 type ValidationMode = "change" | "blur" | "submit" | "blur-then-change"
 
@@ -13,6 +13,7 @@ type ZenoFormState = {
   hideFieldErrors: boolean
   requiredIndicator: boolean
   requiredFields: ReadonlySet<string>
+  schema: StandardSchemaLike | undefined
 }
 
 const EMPTY_REQUIRED_FIELDS: ReadonlySet<string> = new Set<string>()
@@ -21,6 +22,7 @@ const DEFAULT_FORM_STATE: ZenoFormState = {
   hideFieldErrors: false,
   requiredFields: EMPTY_REQUIRED_FIELDS,
   requiredIndicator: true,
+  schema: undefined,
   validation: DEFAULT_VALIDATION_MODE,
 }
 
@@ -57,19 +59,29 @@ function getFormHideFieldErrors(form: AnyFormApi): boolean {
   return getFormZenoState(form).hideFieldErrors
 }
 
+// Whether the schema requires the field, whatever `requiredIndicator` says.
+function getFormSchema(form: AnyFormApi): StandardSchemaLike | undefined {
+  return getFormZenoState(form).schema
+}
+
+function isFieldRequiredBySchema(form: AnyFormApi, name: string): boolean {
+  return getFormZenoState(form).requiredFields.has(toRequiredPathKey(name))
+}
+
 function isFieldRequired(form: AnyFormApi, name: string): boolean {
-  const state = getFormZenoState(form)
-  if (!state.requiredIndicator) {
-    return false
-  }
-  return state.requiredFields.has(toRequiredPathKey(name))
+  return (
+    getFormZenoState(form).requiredIndicator &&
+    isFieldRequiredBySchema(form, name)
+  )
 }
 
 export {
   DEFAULT_VALIDATION_MODE,
   getFormHideFieldErrors,
+  getFormSchema,
   getFormValidationMode,
   isFieldRequired,
+  isFieldRequiredBySchema,
   setFormZenoState,
   type ValidationMode,
 }