@zeno-lib/forms 0.4.0 → 0.5.0

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/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/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 }) {