@zeno-lib/forms 0.2.2 → 0.4.0

package/src/lib/schema-required.ts

@@ -9,9 +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 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`).
@@ -42,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+$/
 
@@ -86,22 +95,26 @@ function toRequiredPathKey(name: string): string {
   return name.replace(INDEX_IN_NAME, "[0]")
 }
 
-function probeContainer(expected: unknown): unknown {
-  if (typeof expected !== "string") {
-    return
-  }
-  const kind = expected.toLowerCase()
-  if (kind === "object") {
-    return {}
+function probeValue(expected: unknown): unknown {
+  switch (typeof expected === "string" ? expected.toLowerCase() : undefined) {
+    case "object":
+      return {}
+    case "array":
+      return []
+    case "string":
+      return ""
+    default:
+      return null
   }
-  return kind === "array" ? [{}] : undefined
 }
 
-// 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)) {
@@ -112,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
@@ -135,27 +148,98 @@ 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 failing: ReadonlySet<string>
+  readonly filled: readonly ProbeFill[]
+}
+
+// Record one pass's failing paths, and fill the probe at each of them for the
+// 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>,
+  cleared: ReadonlySet<string>
+): ProbePass {
+  const failing = new Set<string>()
+  const filled: ProbeFill[] = []
+  for (const issue of issues) {
+    const keys = issue.path?.map(pathKey) ?? []
+    if (keys.length === 0) {
+      continue
+    }
+    const path = joinPath(keys)
+    failing.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
+    }
+  }
+  return { descended, next }
+}
+
 function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
   const required = new Set<string>()
+  const cleared = new Set<string>()
   const probe: Record<PropertyKey, unknown> = {}
+  // 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
     }
-    let descended = false
-    for (const issue of issues) {
-      const keys = issue.path?.map(pathKey) ?? []
-      if (keys.length === 0) {
-        continue
-      }
-      required.add(joinPath(keys))
-      const container = probeContainer(issue.expected)
-      if (container !== undefined && fillAt(probe, keys, container)) {
-        descended = true
-      }
-    }
-    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
     }
   }
@@ -163,4 +247,4 @@ function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
 }
 
 export type { StandardSchemaLike }
-export { getRequiredPaths, toRequiredPathKey }
+export { getRequiredPaths, toRequiredPathKey, validateSync }

package/src/lib/use-form-dialog.ts

@@ -156,8 +156,9 @@ function attributeSelector(attribute: string, value: string): string {
 
 /**
  * Find the element to focus for field `name` inside `root`: the control with
- * `id={name}` (what the shipped fields render), else the first focusable
- * element inside the field root marked `data-field={name}`.
+ * `id={name}` (fields that use the name as their id), else, inside the field
+ * root marked `data-field={name}`, the control its label points at (the shipped
+ * fields' ids come from `useId`), else that root's first focusable element.
  */
 function findFieldElement(
   root: ParentNode | null | undefined,
@@ -171,7 +172,14 @@ function findFieldElement(
     return byId
   }
   const fieldRoot = root.querySelector(attributeSelector("data-field", name))
-  return fieldRoot?.querySelector<HTMLElement>(FOCUSABLE) ?? null
+  if (!fieldRoot) {
+    return null
+  }
+  const labelFor = fieldRoot.querySelector("label[for]")?.getAttribute("for")
+  const labelled = labelFor
+    ? fieldRoot.querySelector<HTMLElement>(attributeSelector("id", labelFor))
+    : null
+  return labelled ?? fieldRoot.querySelector<HTMLElement>(FOCUSABLE)
 }
 
 export type {

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,
 }

package/src/use-app-fields.test.tsx

@@ -1,13 +1,29 @@
-import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@zeno-lib/test/testing-library"
 import userEvent from "@zeno-lib/test/user-event"
 import { afterEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
-import { Form, FormProvider, useForm } from "./create-form"
+import { SelectItem } from "@/components/ui/select"
+import { Form, FormProvider, RadioGroupFieldItem, useForm } from "./create-form"
 
 const CONTACT_EMAIL_LABEL = /Contact email/
 const PASSWORD_LABEL = /Password/
 const NAME_LABEL = /Name/
 const ACCEPT_NAME = /Accept/
+const TITLE_LABEL = /Title/
+const NOTE_LABEL = /Note/
+const DAY_LABEL = /Day/
+const PICKED_DAY = /October 9/
+const ROLE_LABEL = /Role/
+const OWNER_LABEL = /Owner/
+const PICK_A_ROLE = "Pick a role"
+const PICK_A_DAY = "Pick a day"
 
 afterEach(() => {
   cleanup()
@@ -30,7 +46,6 @@ describe("EmailField / PasswordField", () => {
     }
     render(<H />)
     const input = screen.getByLabelText(CONTACT_EMAIL_LABEL) as HTMLInputElement
-    expect(input.id).toBe("contactEmail")
     expect(input.name).toBe("contactEmail")
     await user.type(input, "u@example.com")
     expect(input.value).toBe("u@example.com")
@@ -54,7 +69,6 @@ describe("EmailField / PasswordField", () => {
     }
     render(<H />)
     const input = screen.getByLabelText(PASSWORD_LABEL) as HTMLInputElement
-    expect(input.id).toBe("password")
     expect(input.name).toBe("password")
     expect(input.type).toBe("password")
   })
@@ -137,3 +151,326 @@ describe("CheckboxField — boolean state wrapper", () => {
     expect(checkbox.getAttribute("aria-checked")).toBe("true")
   })
 })
+
+describe("field ids", () => {
+  test("two forms with the same field name label their own controls", () => {
+    const schema = z.object({ description: z.string().min(1) })
+    function H({ label }: { label: string }) {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField description="Hint" label={label} name="description" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(
+      <>
+        <H label="Page description" />
+        <H label="Dialog description" />
+      </>
+    )
+    const page = screen.getByRole("textbox", { name: "Page description" })
+    const dialog = screen.getByRole("textbox", { name: "Dialog description" })
+    expect(dialog).not.toBe(page)
+    const hints = screen.getAllByText("Hint")
+    expect(page.getAttribute("aria-describedby")).toBe(hints[0]?.id)
+    expect(dialog.getAttribute("aria-describedby")).toBe(hints[1]?.id)
+  })
+})
+
+describe("ComboboxField", () => {
+  test("offers to clear an optional value but not a required one", () => {
+    const schema = z.object({
+      forced: z.string().optional(),
+      kind: z.string().min(1),
+      note: z.string().optional(),
+      overridden: z.string().min(1),
+    })
+    const ITEMS = ["a", "b"]
+    function H() {
+      const form = useForm({
+        defaultValues: { forced: "a", kind: "a", note: "a", overridden: "a" },
+        onSubmit: vi.fn(),
+        schema,
+      })
+      const { ComboboxField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ComboboxField items={ITEMS} name="note" />
+            <ComboboxField items={ITEMS} name="kind" />
+            <ComboboxField items={ITEMS} name="forced" required />
+            <ComboboxField items={ITEMS} name="overridden" showClear />
+          </Form>
+        </FormProvider>
+      )
+    }
+    const { container } = render(<H />)
+    const hasClear = (name: string) => {
+      const root = container.querySelector<HTMLElement>(
+        `[data-field="${name}"]`
+      )
+      return root
+        ? within(root).queryByRole("button", { name: "Clear" }) !== null
+        : false
+    }
+    expect(hasClear("note")).toBe(true)
+    expect(hasClear("kind")).toBe(false)
+    expect(hasClear("forced")).toBe(false)
+    expect(hasClear("overridden")).toBe(true)
+  })
+})
+
+describe("required fields", () => {
+  test("a required control says so to assistive tech, with or without the `*`", () => {
+    const schema = z.object({
+      kind: z.string().min(1),
+      note: z.string(),
+      title: z.string().min(1),
+    })
+    function H({ requiredIndicator }: { requiredIndicator: boolean }) {
+      const form = useForm({
+        defaultValues: { kind: "a" },
+        onSubmit: vi.fn(),
+        requiredIndicator,
+        schema,
+      })
+      const { ComboboxField, InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Title" name="title" />
+            <InputField label="Note" name="note" />
+            <ComboboxField items={["a", "b"]} label="Kind" name="kind" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    for (const requiredIndicator of [true, false]) {
+      const { container, unmount } = render(
+        <H requiredIndicator={requiredIndicator} />
+      )
+      const title = screen.getByRole("textbox", { name: TITLE_LABEL })
+      const note = screen.getByRole("textbox", { name: NOTE_LABEL })
+      expect(title.getAttribute("aria-required")).toBe("true")
+      expect(note.hasAttribute("aria-required")).toBe(false)
+      expect(
+        container.querySelectorAll('[data-slot="required-indicator"]')
+      ).toHaveLength(requiredIndicator ? 2 : 0)
+      expect(
+        container.querySelector(
+          '[data-field="kind"] [data-slot="combobox-clear"]'
+        )
+      ).toBeNull()
+      unmount()
+    }
+  })
+})
+
+describe("DatePickerField", () => {
+  const DAY = new Date(2026, 9, 9)
+
+  async function pickSelectedDayAgain(required: boolean) {
+    const captured: { day?: Date } = {}
+    function H() {
+      const form = useForm({
+        defaultValues: { day: DAY as Date | undefined },
+        onSubmit: vi.fn(),
+      })
+      const { DatePickerField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <DatePickerField label="Day" name="day" required={required} />
+            <Subscribe selector={(state) => state.values.day}>
+              {(day) => {
+                captured.day = day
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    const user = userEvent.setup()
+    render(<H />)
+    fireEvent.click(screen.getByRole("button", { name: DAY_LABEL }))
+    await user.click(await screen.findByRole("button", { name: PICKED_DAY }))
+    return captured.day
+  }
+
+  test("picking a required date's day again keeps it", async () => {
+    expect(await pickSelectedDayAgain(true)).toEqual(DAY)
+  })
+
+  test("picking an optional date's day again clears it", async () => {
+    expect(await pickSelectedDayAgain(false)).toBeUndefined()
+  })
+})
+
+describe("ComboboxField with items still loading", () => {
+  test("shows a stored id's label once its item arrives, never the raw id", () => {
+    function H({ items }: { items: { label: string; value: string }[] }) {
+      const form = useForm({
+        defaultValues: { ownerId: "user-7" },
+        onSubmit: vi.fn(),
+      })
+      const { ComboboxField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ComboboxField items={items} label="Owner" name="ownerId" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    const { rerender } = render(<H items={[]} />)
+    const input = screen.getByRole("combobox", { name: OWNER_LABEL })
+    expect(input).toHaveProperty("value", "")
+    rerender(<H items={[{ label: "Ada Lovelace", value: "user-7" }]} />)
+    expect(input).toHaveProperty("value", "Ada Lovelace")
+  })
+})
+
+describe("popup fields", () => {
+  test("a required select shows its error once the popup closes, not while it is open", async () => {
+    const user = userEvent.setup()
+    function H() {
+      const form = useForm({
+        onSubmit: vi.fn(),
+        schema: z.object({ role: z.string().min(1, PICK_A_ROLE) }),
+      })
+      const { SelectField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <SelectField label="Role" name="role">
+              <SelectItem value="admin">Admin</SelectItem>
+            </SelectField>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByRole("combobox", { name: ROLE_LABEL }))
+    await screen.findByRole("option", { name: "Admin" })
+    expect(screen.queryByText(PICK_A_ROLE)).toBeNull()
+    await user.keyboard("{Escape}")
+    expect(await screen.findByText(PICK_A_ROLE)).toBeTruthy()
+  })
+
+  test("a required date shows its error once the popover closes, not while it is open", async () => {
+    const user = userEvent.setup()
+    function H() {
+      const form = useForm({
+        onSubmit: vi.fn(),
+        schema: z.object({ day: z.date({ error: PICK_A_DAY }) }),
+      })
+      const { DatePickerField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <DatePickerField label="Day" name="day" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const trigger = screen.getByRole("button", { name: DAY_LABEL })
+    trigger.focus()
+    fireEvent.click(trigger)
+    await screen.findByRole("grid")
+    // The trigger's blur is what used to mark the field touched.
+    await waitFor(() => expect(document.activeElement).not.toBe(trigger))
+    expect(screen.queryByText(PICK_A_DAY)).toBeNull()
+    await user.keyboard("{Escape}")
+    expect(await screen.findByText(PICK_A_DAY)).toBeTruthy()
+  })
+})
+
+describe("RadioGroupField", () => {
+  test("stores each item's value as is", async () => {
+    const user = userEvent.setup()
+    const captured: { consent?: unknown } = {}
+    function H() {
+      const form = useForm({
+        defaultValues: { consent: undefined as boolean | undefined },
+        onSubmit: vi.fn(),
+      })
+      const { RadioGroupField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <RadioGroupField label="Consent" name="consent">
+              <RadioGroupFieldItem value={true}>Yes</RadioGroupFieldItem>
+              <RadioGroupFieldItem value={false}>No</RadioGroupFieldItem>
+            </RadioGroupField>
+            <Subscribe selector={(state) => state.values.consent}>
+              {(consent) => {
+                captured.consent = consent
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByRole("radio", { name: "No" }))
+    expect(captured.consent).toBe(false)
+    await user.click(screen.getByRole("radio", { name: "Yes" }))
+    expect(captured.consent).toBe(true)
+  })
+})
+
+describe("clearing a field", () => {
+  test("empties it to a value its schema accepts", async () => {
+    const user = userEvent.setup()
+    const OWNER_ID = "00000000-0000-4000-8000-000000000001"
+    const schema = z.object({ kind: z.string(), ownerId: z.uuid().nullable() })
+    const captured: { values?: unknown } = {}
+    function H() {
+      const form = useForm({
+        defaultValues: { kind: "a", ownerId: OWNER_ID },
+        onSubmit: vi.fn(),
+        schema,
+      })
+      const { ComboboxField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ComboboxField items={["a", "b"]} label="Kind" name="kind" />
+            <ComboboxField
+              items={[{ label: "Ada Lovelace", value: OWNER_ID }]}
+              label="Owner"
+              name="ownerId"
+            />
+            <Subscribe selector={(state) => state.values}>
+              {(values) => {
+                captured.values = values
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    const { container } = render(<H />)
+    const clearButton = (name: string) => {
+      const root = container.querySelector<HTMLElement>(
+        `[data-field="${name}"]`
+      )
+      if (!root) {
+        throw new Error(`no ${name} field`)
+      }
+      return within(root).getByRole("button", { name: "Clear" })
+    }
+    await user.click(clearButton("kind"))
+    await user.click(clearButton("ownerId"))
+    expect(captured.values).toEqual({ kind: "", ownerId: null })
+    expect(schema.safeParse(captured.values).success).toBe(true)
+  })
+})