@zeno-lib/forms 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "repository": {
     "url": "https://github.com/zeno-lib/zeno.git",
     "directory": "packages/forms"

package/src/form-dialog.test.tsx

@@ -18,7 +18,7 @@ import {
 } from "./form-dialog"
 import type { ActionResult } from "./lib/action-result"
 import { submitAction } from "./lib/submit-action"
-import { useFormDialog } from "./lib/use-form-dialog"
+import { type FormDialogController, useFormDialog } from "./lib/use-form-dialog"
 
 const NAME = /Name/
 const EMAIL = /Email/
@@ -54,8 +54,10 @@ function Harness({
   children,
   onSubmit = vi.fn(),
   closeOnSubmit,
+  controller,
   disabled,
   discardPrompt,
+  formDisabled,
   saveFromPrompt,
   submitErrorMessage,
   submitLabel,
@@ -65,15 +67,23 @@ function Harness({
   children?: ReactNode
   onSubmit?: (values: Values) => unknown
   closeOnSubmit?: boolean
+  /** Gets the dialog's controller, to close it from outside. */
+  controller?: { current?: FormDialogController<Values> }
   disabled?: boolean
   discardPrompt?: DiscardPromptText
+  /** Disable the form through `useForm({ disabled })`. */
+  formDisabled?: boolean
   saveFromPrompt?: boolean
   submitErrorMessage?: (error: unknown) => ReactNode
   submitLabel?: ReactNode
 }) {
   const dialog = useFormDialog({ defaultValues: BLANK })
+  if (controller) {
+    controller.current = dialog
+  }
   const form = useForm({
     defaultValues: dialog.defaultValues,
+    disabled: formDisabled,
     onSubmit: (submit) =>
       action ? submitAction(submit, action) : onSubmit(submit.value),
     schema,
@@ -119,6 +129,13 @@ function dropFocus() {
   sink.remove()
 }
 
+// Whether leaving the page now would make the browser ask first.
+function warnsOnUnload(): boolean {
+  const event = new Event("beforeunload", { cancelable: true })
+  window.dispatchEvent(event)
+  return event.defaultPrevented
+}
+
 // The alerts added where assistive tech could see them. One added under an
 // `aria-hidden` ancestor (the dialog, while the leave prompt is open) is never
 // announced, not even once that ancestor is shown again.
@@ -277,6 +294,110 @@ describe("FormDialog", () => {
     expect(screen.getByRole("dialog")).toBeTruthy()
   })
 
+  for (const closeOnSubmit of [true, false]) {
+    test(`a leave asked for while a Save runs goes through once it saves (closeOnSubmit: ${closeOnSubmit})`, async () => {
+      const user = userEvent.setup()
+      let finishSave: () => void = () => undefined
+      const onSubmit = vi.fn(
+        () =>
+          new Promise<void>((resolve) => {
+            finishSave = resolve
+          })
+      )
+      render(<Harness closeOnSubmit={closeOnSubmit} onSubmit={onSubmit} />)
+      const name = await openEdit(user)
+      await user.type(name, "!")
+      await user.click(screen.getByRole("button", { name: "Save" }))
+      await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+      await user.keyboard("{Escape}")
+      await screen.findByRole("alertdialog")
+
+      finishSave()
+      await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull())
+      expect(screen.queryByRole("alertdialog")).toBeNull()
+    })
+  }
+
+  test("an edit made while a Save runs keeps the leave prompt asking once it saves", async () => {
+    const user = userEvent.setup()
+    let finishSave: () => void = () => undefined
+    const onSubmit = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          finishSave = resolve
+        })
+    )
+    render(<Harness onSubmit={onSubmit} />)
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    await user.click(screen.getByRole("button", { name: "Save" }))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+    await user.type(name, "?")
+    await user.keyboard("{Escape}")
+    const prompt = await screen.findByRole("alertdialog")
+
+    finishSave()
+    await waitFor(() =>
+      expect(screen.queryByRole("status", { hidden: true })).toBeNull()
+    )
+    expect(screen.getByRole("alertdialog")).toBe(prompt)
+    await user.click(
+      within(prompt).getByRole("button", { name: "Keep editing" })
+    )
+    await waitFor(() => expect(screen.queryByRole("alertdialog")).toBeNull())
+    expect(name.value).toBe("Ada!?")
+  })
+
+  test("a Save that fails while the leave prompt asks focuses the invalid field once it closes", async () => {
+    const user = userEvent.setup()
+    let finishSave: (result: ActionResult<never>) => void = () => undefined
+    const action = vi.fn(
+      () =>
+        new Promise<ActionResult<never>>((resolve) => {
+          finishSave = resolve
+        })
+    )
+    render(<Harness action={action} />)
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    await user.click(screen.getByRole("button", { name: "Save" }))
+    await waitFor(() => expect(action).toHaveBeenCalled())
+    await user.keyboard("{Escape}")
+    const prompt = await screen.findByRole("alertdialog")
+    await waitFor(() =>
+      expect(prompt.contains(document.activeElement)).toBe(true)
+    )
+
+    finishSave({
+      error: { fieldErrors: { email: ["Already taken"] }, formErrors: [] },
+      ok: false,
+    })
+    const email = screen.getByLabelText(EMAIL)
+    await waitFor(() => expect(email.getAttribute("aria-invalid")).toBe("true"))
+    expect(prompt.contains(document.activeElement)).toBe(true)
+    await user.click(
+      within(prompt).getByRole("button", { name: "Keep editing" })
+    )
+    await waitFor(() => expect(document.activeElement).toBe(email))
+  })
+
+  test("closing the dialog from outside closes its leave prompt for good", async () => {
+    const user = userEvent.setup()
+    const controller: { current?: FormDialogController<Values> } = {}
+    render(<Harness controller={controller} />)
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    await user.keyboard("{Escape}")
+    await screen.findByRole("alertdialog")
+
+    act(() => controller.current?.close())
+    await waitFor(() => expect(screen.queryByRole("alertdialog")).toBeNull())
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull())
+    await user.click(screen.getByRole("button", { name: "Edit" }))
+    await screen.findByRole("dialog")
+    expect(screen.queryByRole("alertdialog")).toBeNull()
+  })
+
   test("a field error from the server focuses that field", async () => {
     const user = userEvent.setup()
     const action = vi.fn(() =>
@@ -583,17 +704,46 @@ describe("FormDialog", () => {
     expect(screen.getByRole("dialog")).toBeTruthy()
   })
 
-  test("disabled also turns off Save in the leave prompt", async () => {
+  for (const via of ["disabled", "useForm({ disabled })"]) {
+    test(`with ${via}, a changed dialog still asks and warns, without offering Save`, async () => {
+      const user = userEvent.setup()
+      const { rerender } = render(<Harness saveFromPrompt />)
+      const name = await openEdit(user)
+      await user.type(name, "!")
+
+      rerender(
+        <Harness
+          disabled={via === "disabled"}
+          formDisabled={via !== "disabled"}
+          saveFromPrompt
+        />
+      )
+      expect(warnsOnUnload()).toBe(true)
+      await user.click(screen.getByRole("button", { name: "Cancel" }))
+      const prompt = await screen.findByRole("alertdialog")
+      expect(within(prompt).getByText("Discard changes?")).toBeTruthy()
+      expect(within(prompt).queryByRole("button", { name: "Save" })).toBeNull()
+      await user.click(within(prompt).getByRole("button", { name: "Discard" }))
+      await waitFor(() => expect(screen.queryByRole("alertdialog")).toBeNull())
+      await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull())
+    })
+  }
+
+  test("disabled while the leave prompt asks keeps it, with its Save off", async () => {
     const user = userEvent.setup()
     const onSubmit = vi.fn()
     const { rerender } = render(<Harness onSubmit={onSubmit} saveFromPrompt />)
     const name = await openEdit(user)
     await user.type(name, "!")
-    rerender(<Harness disabled onSubmit={onSubmit} saveFromPrompt />)
     await user.click(screen.getByRole("button", { name: "Cancel" }))
     const prompt = await screen.findByRole("alertdialog")
+
+    rerender(<Harness disabled onSubmit={onSubmit} saveFromPrompt />)
     await user.click(within(prompt).getByRole("button", { name: "Save" }))
     expect(onSubmit).not.toHaveBeenCalled()
+    expect(screen.getByRole("alertdialog")).toBe(prompt)
+    await user.click(within(prompt).getByRole("button", { name: "Discard" }))
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull())
   })
 
   test("Save in the leave prompt doesn't submit again while a submit runs", async () => {

package/src/form-dialog.tsx

@@ -110,7 +110,11 @@ type FormDialogProps<TValues> = {
   cancelLabel?: ReactNode
   /** Extra footer content, rendered before Cancel / Save. */
   footer?: ReactNode
-  /** Close after a successful submit. Defaults to `true`. */
+  /**
+   * Close after a successful submit. Defaults to `true`. A close the user
+   * asked for while the submit ran goes through once it succeeds either way,
+   * unless they edited a field since.
+   */
   closeOnSubmit?: boolean
   /**
    * Shown above the footer when the submit handler throws. Defaults to the
@@ -127,13 +131,15 @@ type FormDialogProps<TValues> = {
   discardPrompt?: DiscardPromptText
   /**
    * Offer Save in the discard prompt, next to Discard: it submits, and closes
-   * the dialog if the submit succeeds. Defaults to `false`.
+   * the dialog if the submit succeeds. Not in a prompt that opens while the
+   * dialog is disabled. Defaults to `false`.
    */
   saveFromPrompt?: boolean
   /**
    * Disable every field, Save and ⌘/Ctrl+Enter, as `useForm({ disabled })`
    * does. A `<fieldset disabled>` also disables native controls of your own.
-   * Defaults to `false`.
+   * A discard prompt that opens while disabled doesn't offer Save. Defaults
+   * to `false`.
    */
   disabled?: boolean
   /** Class for the dialog popup (e.g. a wider `sm:max-w-lg`). */
@@ -257,8 +263,8 @@ function FormDialog<TValues>(props: FormDialogProps<TValues>) {
     useIsFormDisabled(form as unknown as AnyFormApi) || disabled
   const popupRef = useRef<HTMLDivElement>(null)
   const formRef = useRef<HTMLFormElement>(null)
-  // Set when a Save from the discard prompt fails, so the prompt hands focus
-  // to the first invalid field as it closes.
+  // Set when a submit fails while the discard prompt is open, so the prompt
+  // hands focus to the first invalid field as it closes.
   const focusInvalidOnPromptClose = useRef<boolean>(false)
   // The open prompt hides the dialog from assistive tech, so a form-level
   // error that shows up meanwhile (a Save from the prompt, or a footer Save
@@ -266,9 +272,13 @@ function FormDialog<TValues>(props: FormDialogProps<TValues>) {
   // the prompt has closed, which announces it.
   const announceOnPromptClosed = useRef<boolean>(false)
   const [formErrorKey, setFormErrorKey] = useState(0)
+  // Whether the discard prompt offers Save, set as it opens: a disabled
+  // dialog can't save. Kept while it's open, so the prompt doesn't change
+  // under the user; one disabled meanwhile only turns its Save off.
+  const [promptOffersSave, setPromptOffersSave] = useState(false)
   const { close, defaultValues, focus, isOpen, open, session } = dialog
   const DialogFormError = form.FormError ?? FormError
-  const promptCopy = getPromptCopy(discardPrompt, saveFromPrompt)
+  const promptCopy = getPromptCopy(discardPrompt, promptOffersSave)
   // Read after a submit's await: the dialog may have closed, or reopened on
   // another record, while a slow save was in flight.
   const latest = useRef({ isOpen, session })
@@ -313,6 +323,12 @@ function FormDialog<TValues>(props: FormDialogProps<TValues>) {
     }
   }, [session])
 
+  // A held leave belongs to the session it was asked in. Drop it when that
+  // session ends some other way (`dialog.close()`, a submit that closes it,
+  // `dialog.open()` on another record), so the prompt never outlives it.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: on every session change.
+  useLayoutEffect(() => cancelLeave, [isOpen, session])
+
   // Every way to submit (footer Save, ⌘/Ctrl+Enter, the prompt's Save) checks
   // this first. TanStack only refuses a second `handleSubmit` while one runs on
   // the very first attempt, and `isOpen` is false through the exit animation,
@@ -342,10 +358,25 @@ function FormDialog<TValues>(props: FormDialogProps<TValues>) {
     }
     const node = event.currentTarget
     const focused = node.ownerDocument.activeElement
+    // The fields stay editable while the submit runs. TanStack replaces
+    // `values` on every edit, so the same object means none came after.
+    const submitted = form.state.values
     const saved = await submit()
     if (!latest.current.isOpen || latest.current.session !== session) {
       return // the session this submit belongs to is over
     }
+    if (isConfirmingRef.current) {
+      // The user asked to leave while the submit ran. If it saved every
+      // change, that leave goes through, `closeOnSubmit` or not. After a
+      // failure or a later edit, the prompt waits for the user's answer, and
+      // it traps focus, so it moves focus to an invalid field as it closes.
+      if (saved && form.state.values === submitted) {
+        confirmLeave()
+      } else {
+        focusInvalidOnPromptClose.current = !saved
+      }
+      return
+    }
     if (saved) {
       if (closeOnSubmit) {
         // Close directly, past the guard: the changes are saved. The form is
@@ -392,6 +423,7 @@ function FormDialog<TValues>(props: FormDialogProps<TValues>) {
         if (next) {
           open()
         } else {
+          setPromptOffersSave(saveFromPrompt && !isDisabled)
           requestLeave(close)
         }
       }}
@@ -480,21 +512,24 @@ function FormDialog<TValues>(props: FormDialogProps<TValues>) {
             setFormErrorKey((key) => key + 1)
           }
         }}
-        open={isConfirming}
+        // Closes in the same render as the dialog.
+        open={isConfirming && isOpen}
       >
         <AlertDialogContent
           // The prompt traps focus while open, so a failed Save's invalid
           // field gets focus as the prompt closes, not from `submit`.
           finalFocus={() => {
-            if (!focusInvalidOnPromptClose.current) {
+            const focusInvalid = focusInvalidOnPromptClose.current
+            focusInvalidOnPromptClose.current = false
+            // After Discard, the closing dialog hands focus back itself.
+            if (!(focusInvalid && latest.current.isOpen)) {
               return true
             }
-            focusInvalidOnPromptClose.current = false
             // Base UI focuses what this returns too; focusing here first
             // finds a field that takes focus, skipping disabled or hidden ones.
             return focusFirstInvalid(formRef.current) ?? true
           }}
-          size={saveFromPrompt ? "default" : "sm"}
+          size={promptOffersSave ? "default" : "sm"}
         >
           <AlertDialogHeader>
             <AlertDialogTitle>{promptCopy.title}</AlertDialogTitle>
@@ -513,7 +548,7 @@ function FormDialog<TValues>(props: FormDialogProps<TValues>) {
             >
               {discardPrompt?.confirmLabel ?? "Discard"}
             </AlertDialogAction>
-            {saveFromPrompt && (
+            {promptOffersSave && (
               <AlertDialogAction
                 disabled={isDisabled || isSaving || isSubmitting}
                 onClick={saveAndLeave}