@zeno-lib/forms 0.3.0 → 0.5.0

package/src/lib/submit-error.ts

@@ -0,0 +1,133 @@
+"use client"
+
+import { useCallback, useSyncExternalStore } from "react"
+
+// A submit whose handler threw (a network failure, an unexpected server
+// error), kept per form so `FormError` can show it.
+//
+// Not written to TanStack's `errorMap`: any entry there makes the form
+// invalid, which disables `SubmitButton`, and `handleSubmit` then skips
+// `onSubmit` until an edit clears the entry. The user couldn't retry a failed
+// save as is.
+
+type SubmitErrorState = {
+  readonly submissionAttempts: number
+  readonly values: unknown
+}
+
+// The slice of a form the helpers read. Keyed by `store`, as the per-form
+// Zeno state is (`validation-modes.ts`): it is the one reference shared by
+// the `useForm()` result and the form API that fields and context receive.
+type SubmitErrorForm = {
+  readonly state: SubmitErrorState
+  readonly store: {
+    subscribe: (listener: () => void) => { unsubscribe: () => void }
+  }
+}
+
+type SubmitError = {
+  /** What the submit handler threw. */
+  readonly error: unknown
+}
+
+type Entry = {
+  readonly submitError: SubmitError
+  readonly unsubscribe: () => void
+}
+
+const entries = new WeakMap<object, Entry>()
+const listeners = new WeakMap<object, Set<() => void>>()
+
+function notify(key: object): void {
+  for (const listener of listeners.get(key) ?? []) {
+    listener()
+  }
+}
+
+function clear(key: object): void {
+  const entry = entries.get(key)
+  if (entry) {
+    entry.unsubscribe()
+    entries.delete(key)
+    notify(key)
+  }
+}
+
+// Next.js `redirect()`, `notFound()`, `forbidden()` and `unauthorized()` throw
+// an error whose `digest` starts with `NEXT_`, and a server action that calls
+// one rejects with it on the client. Next navigates on its own: no failure.
+function isNavigationError(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("digest" in error)) {
+    return false
+  }
+  return typeof error.digest === "string" && error.digest.startsWith("NEXT_")
+}
+
+/**
+ * Record that `form`'s submit threw `error`. `useForm` calls it for what
+ * `onSubmit` throws; call it for a failure your own submit code catches
+ * outside `onSubmit`. The error lasts until the values change or the next
+ * submit starts (`reset()` does both), so an edit or a retry clears it. A
+ * Next.js navigation (`redirect()`, `notFound()`) is ignored.
+ */
+function setSubmitError(form: SubmitErrorForm, error: unknown): void {
+  if (isNavigationError(error)) {
+    return
+  }
+  const key = form.store
+  entries.get(key)?.unsubscribe()
+  const { submissionAttempts, values } = form.state
+  // Dropped, not just hidden, once stale: a reset restores the attempt count
+  // and can restore the same values object, which would bring it back.
+  const subscription = form.store.subscribe(() => {
+    const { state } = form
+    if (
+      state.values !== values ||
+      state.submissionAttempts !== submissionAttempts
+    ) {
+      clear(key)
+    }
+  })
+  entries.set(key, {
+    submitError: { error },
+    unsubscribe: subscription.unsubscribe,
+  })
+  notify(key)
+}
+
+/**
+ * Report a submit rejection that is caught so the user can retry, as
+ * `<Form>` and `FormDialog` do: `reportError` logs it and passes it to the
+ * page's `error` listeners (where error monitoring hooks in), as if it were
+ * uncaught. A Next.js navigation is skipped.
+ */
+function reportSubmitError(error: unknown): void {
+  if (!isNavigationError(error)) {
+    // Missing in jsdom and older browsers.
+    globalThis.reportError?.(error)
+  }
+}
+
+/** The error `form`'s last submit threw, until it went stale. */
+function useSubmitError(form: SubmitErrorForm): SubmitError | undefined {
+  const key = form.store
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      const set = listeners.get(key) ?? new Set()
+      listeners.set(key, set)
+      set.add(listener)
+      return () => {
+        set.delete(listener)
+      }
+    },
+    [key]
+  )
+  return useSyncExternalStore(
+    subscribe,
+    () => entries.get(key)?.submitError,
+    () => undefined
+  )
+}
+
+export type { SubmitError, SubmitErrorForm }
+export { reportSubmitError, setSubmitError, useSubmitError }

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

@@ -97,6 +97,11 @@ function useFormDialog<TValues>(
 type UseLeaveGuardOptions = {
   /** Whether leaving now would lose changes. */
   hasUnsavedChanges: boolean
+  /**
+   * Save the changes and resolve whether that worked. Backs `saveAndLeave`,
+   * so the confirm UI can offer Save next to Discard.
+   */
+  onSave?: () => boolean | Promise<boolean>
 }
 
 type LeaveGuard = {
@@ -111,14 +116,25 @@ type LeaveGuard = {
   confirmLeave: () => void
   /** The user chose to stay: drop the held leave. */
   cancelLeave: () => void
+  /**
+   * The user chose to save: run `onSave`, then the held leave if it saved.
+   * Either way the confirm UI closes; after a failed save the user stays.
+   * Resolves whether it saved. A rejection from `onSave` keeps the leave held
+   * and propagates.
+   */
+  saveAndLeave: () => Promise<boolean>
+  /** Whether `saveAndLeave` is waiting on `onSave`. */
+  isSaving: boolean
 }
 
 /** Ask before a leave (close, navigate, switch record) drops unsaved changes. */
 function useLeaveGuard({
   hasUnsavedChanges,
+  onSave,
 }: UseLeaveGuardOptions): LeaveGuard {
   const pending = useRef<(() => void) | null>(null)
   const [isConfirming, setIsConfirming] = useState(false)
+  const [isSaving, setIsSaving] = useState(false)
 
   const requestLeave = useCallback(
     (proceed: () => void) => {
@@ -144,7 +160,39 @@ function useLeaveGuard({
     setIsConfirming(false)
   }, [])
 
-  return { cancelLeave, confirmLeave, isConfirming, requestLeave }
+  const saveAndLeave = useCallback(async () => {
+    const proceed = pending.current
+    if (!(proceed && onSave)) {
+      return false
+    }
+    setIsSaving(true)
+    let saved = false
+    try {
+      saved = await onSave()
+    } finally {
+      setIsSaving(false)
+    }
+    // Answered otherwise while saving (cancelled, or a newer leave replaced
+    // this one): leave that answer alone.
+    if (pending.current !== proceed) {
+      return saved
+    }
+    pending.current = null
+    setIsConfirming(false)
+    if (saved) {
+      proceed()
+    }
+    return saved
+  }, [onSave])
+
+  return {
+    cancelLeave,
+    confirmLeave,
+    isConfirming,
+    isSaving,
+    requestLeave,
+    saveAndLeave,
+  }
 }
 
 const FOCUSABLE =

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()
@@ -164,3 +180,297 @@ describe("field ids", () => {
     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)
+  })
+})

package/src/use-form.focus-invalid.test.tsx

@@ -9,6 +9,7 @@ import type { ReactNode } from "react"
 import { afterEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
 import { Form, FormProvider, RadioGroupFieldItem, useForm } from "./create-form"
+import { submitAction } from "./lib/submit-action"
 
 afterEach(() => {
   cleanup()
@@ -103,6 +104,39 @@ describe("<Form> — focus the first invalid field on a failed submit", () => {
     )
   })
 
+  test("focuses a field error returned through submitAction", async () => {
+    const user = userEvent.setup()
+    function Harness() {
+      const form = useForm({
+        defaultValues: { email: "ada@example.com", name: "Ada" },
+        onSubmit: (submit) =>
+          submitAction(submit, () =>
+            Promise.resolve({
+              error: { fieldErrors: { name: ["Taken"] }, formErrors: [] },
+              ok: false as const,
+            })
+          ),
+        schema,
+      })
+      const { EmailField, InputField, SubmitButton } = form
+      return (
+        <FormProvider form={form}>
+          <Form aria-label="Profile">
+            <EmailField name="email" />
+            <InputField label="Name" name="name" />
+            <SubmitButton>Save</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<Harness />)
+    await user.click(screen.getByRole("button", { name: "Save" }))
+    expect(await screen.findByText("Taken")).toBeTruthy()
+    await waitFor(() =>
+      expect(document.activeElement).toBe(control("Profile", "name"))
+    )
+  })
+
   test("a radio group or slider root hands focus to its tabbable child", async () => {
     const user = userEvent.setup()
     function Harness({ sliderFirst }: { sliderFirst: boolean }) {