@zeno-lib/forms 0.3.0 → 0.5.0

package/src/lib/empty-value.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest"
+import { z } from "zod"
+
+import { emptyValueFor, withEmptyStartValues } from "./empty-value"
+import { extractZodDefaults } from "./schema-defaults"
+
+const FALLBACK = Symbol("fallback")
+
+function cleared(field: z.ZodType, name = "field", values: unknown = {}) {
+  return emptyValueFor(z.object({ field }), values, name, FALLBACK)
+}
+
+describe("emptyValueFor", () => {
+  test("null, then undefined, then the type's own empty value", () => {
+    expect(cleared(z.string().nullable())).toBeNull()
+    expect(cleared(z.string().optional())).toBeUndefined()
+    expect(cleared(z.string())).toBe("")
+    expect(cleared(z.array(z.string()))).toEqual([])
+    expect(cleared(z.uuid().nullable())).toBeNull()
+    expect(cleared(z.enum(["a", "b"]).optional())).toBeUndefined()
+    expect(cleared(z.number().nullable())).toBeNull()
+    expect(cleared(z.date().nullish())).toBeNull()
+  })
+
+  test("a field that accepts no empty value keeps the field's own fallback", () => {
+    expect(cleared(z.string().min(1))).toBe(FALLBACK)
+    expect(cleared(z.number())).toBe(FALLBACK)
+  })
+
+  test("array rows follow the row schema", () => {
+    const schema = z.object({
+      members: z.array(
+        z.object({
+          id: z.uuid().nullable(),
+          name: z.string(),
+          note: z.string().optional(),
+        })
+      ),
+    })
+    const values = { members: [{ id: "x" }, { id: "y" }] }
+    const at = (name: string) => emptyValueFor(schema, values, name, FALLBACK)
+    expect(at("members[1].id")).toBeNull()
+    expect(at("members[1].name")).toBe("")
+    expect(at("members[1].note")).toBeUndefined()
+  })
+
+  test("without a schema, or with an async one, the fallback stands", () => {
+    expect(emptyValueFor(undefined, {}, "field", FALLBACK)).toBe(FALLBACK)
+    const asyncSchema = z.object({
+      field: z.string().refine(async () => true),
+    })
+    expect(emptyValueFor(asyncSchema, {}, "field", FALLBACK)).toBe(FALLBACK)
+  })
+})
+
+describe("withEmptyStartValues", () => {
+  test('starts a field whose schema rejects `""` at its empty value', () => {
+    const schema = z.object({
+      email: z.email().optional(),
+      name: z.string().min(1),
+      note: z.string(),
+      ownerId: z.uuid().nullable(),
+    })
+    const start = withEmptyStartValues(schema, extractZodDefaults(schema))
+    expect(start).toEqual({
+      email: undefined,
+      name: "",
+      note: "",
+      ownerId: null,
+    })
+  })
+})

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/focus-first-invalid.test.ts

@@ -0,0 +1,22 @@
+import { afterEach, describe, expect, test } from "vitest"
+import { focusFirstInvalid } from "./focus-first-invalid"
+
+afterEach(() => {
+  document.body.innerHTML = ""
+})
+
+describe("focusFirstInvalid", () => {
+  test("skips an invalid control that won't take focus", () => {
+    document.body.innerHTML = `
+      <form>
+        <input aria-invalid="true" disabled name="locked" />
+        <div aria-invalid="true" role="radiogroup">
+          <button disabled role="radio" type="button">A</button>
+          <button role="radio" type="button">B</button>
+        </div>
+      </form>`
+    const focused = focusFirstInvalid(document.querySelector("form"))
+    expect(focused?.textContent).toBe("B")
+    expect(document.activeElement).toBe(focused)
+  })
+})

package/src/lib/focus-first-invalid.ts

@@ -0,0 +1,52 @@
+/**
+ * Move focus to the first invalid control inside `root` (a `<form>`): the
+ * first element with `aria-invalid="true"`, or, for a group root that can't
+ * take focus itself (radio group, slider), its first tabbable descendant. An
+ * invalid control that won't take focus (disabled, hidden) is skipped for the
+ * next one. Call it after `await form.handleSubmit()` leaves the form invalid.
+ * Searching only `root` keeps focus inside the submitted form, so a dialog's
+ * form never sends it to the page behind. Returns the focused element, or
+ * `null`.
+ */
+function focusFirstInvalid(
+  root: ParentNode | null | undefined
+): HTMLElement | null {
+  const invalid = root?.querySelectorAll<HTMLElement>('[aria-invalid="true"]')
+  for (const element of invalid ?? []) {
+    for (const target of [
+      element,
+      ...element.querySelectorAll<HTMLElement>("*"),
+    ]) {
+      if (target.tabIndex < 0) {
+        continue
+      }
+      target.focus()
+      if (target.ownerDocument.activeElement === target) {
+        return target
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Give focus back to `element`, what had it when the submit started, if the
+ * submit dropped it to the body. A submit button that disables itself while
+ * submitting does that in browsers, so a failed submit with no invalid field
+ * to focus would otherwise leave the user nowhere. It doesn't scroll, so a
+ * user who scrolled away during a slow submit stays put. Returns whether it
+ * moved focus.
+ */
+function restoreFocus(element: Element | null): boolean {
+  if (!(element instanceof HTMLElement && element.isConnected)) {
+    return false
+  }
+  const active = element.ownerDocument.activeElement
+  if (active !== null && active !== element.ownerDocument.body) {
+    return false
+  }
+  element.focus({ preventScroll: true })
+  return element.ownerDocument.activeElement === element
+}
+
+export { focusFirstInvalid, restoreFocus }

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 }