@zeno-lib/forms 0.6.0 → 0.7.1

package/src/form-dialog.tsx

@@ -1,10 +1,12 @@
 "use client"
 
 import { FormProvider } from "@zeno-lib/forms"
+import { withDefaultProps } from "@zeno-lib/forms/lib/default-props"
 import {
   focusFirstInvalid,
   restoreFocus,
 } from "@zeno-lib/forms/lib/focus-first-invalid"
+import { useIsFormDisabled } from "@zeno-lib/forms/lib/form-disabled"
 import { reportSubmitError } from "@zeno-lib/forms/lib/submit-error"
 import {
   type FormDialogController,
@@ -14,10 +16,13 @@ import {
 import { useUnsavedChangesWarning } from "@zeno-lib/forms/lib/use-unsaved-changes-warning"
 import { type AnyFormApi, useSelector } from "@zeno-lib/forms/tanstack"
 import {
+  type ComponentType,
+  createContext,
   type FormEvent,
   type KeyboardEvent,
   type ReactElement,
   type ReactNode,
+  useContext,
   useId,
   useLayoutEffect,
   useRef,
@@ -45,7 +50,7 @@ import {
   DialogTrigger,
 } from "@/components/ui/dialog"
 import { Spinner } from "@/components/ui/spinner"
-import { FormError } from "./fields/form-error"
+import { FormError, type FormErrorProps } from "./fields/form-error"
 
 type DiscardPromptText = {
   title?: ReactNode
@@ -54,6 +59,10 @@ type DiscardPromptText = {
   cancelLabel?: ReactNode
   /** The Save action's label (`saveFromPrompt`). Defaults to `submitLabel`. */
   saveLabel?: ReactNode
+  /** The title with `saveFromPrompt`. Defaults to `title`. */
+  saveTitle?: ReactNode
+  /** The description with `saveFromPrompt`. Defaults to `description`. */
+  saveDescription?: ReactNode
 }
 
 // The slice of the `useForm()` API the dialog uses. Structural, so any Zeno /
@@ -77,6 +86,11 @@ type DialogForm<TValues> = {
   readonly state: DialogFormState
   handleSubmit: () => unknown
   reset: (values?: TValues) => void
+  /**
+   * The form's own `FormError` (`useForm` attaches it), rendered with the
+   * app's `defaultProps`. The dialog falls back to the kit's.
+   */
+  FormError?: ComponentType<Pick<FormErrorProps, "submitErrorMessage">>
 }
 
 type FormDialogProps<TValues> = {
@@ -96,12 +110,16 @@ 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
-   * `FormError`'s `"Something went wrong. Try again."`. A function gets what
-   * was thrown.
+   * Shown above the footer when the submit handler throws. Defaults to the
+   * form's `FormError` default: your `defaultProps`, or
+   * `"Something went wrong. Try again."`. A function gets what was thrown.
    */
   submitErrorMessage?: ReactNode | ((error: unknown) => ReactNode)
   /**
@@ -113,12 +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 Save, ⌘/Ctrl+Enter, and the native controls in the form (through
-   * a `<fieldset disabled>`). Defaults to `false`.
+   * Disable every field, Save and ⌘/Ctrl+Enter, as `useForm({ disabled })`
+   * does. A `<fieldset disabled>` also disables native controls of your own.
+   * 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`). */
@@ -127,6 +148,87 @@ type FormDialogProps<TValues> = {
   formClassName?: string
 }
 
+/** The `FormDialog` props a `FormDialogProvider` can set for every dialog. */
+type FormDialogDefaults = Omit<
+  FormDialogProps<unknown>,
+  | "children"
+  | "description"
+  | "dialog"
+  | "disabled"
+  | "footer"
+  | "form"
+  | "title"
+  | "trigger"
+>
+
+const FormDialogDefaultsContext = createContext<FormDialogDefaults | undefined>(
+  undefined
+)
+
+// `props` over `defaults`, with the discard prompt's copy merged key by key.
+function withDialogDefaults<P extends FormDialogDefaults>(
+  defaults: FormDialogDefaults | undefined,
+  props: P
+): P {
+  if (defaults === undefined) {
+    return props
+  }
+  const merged = withDefaultProps(defaults as Partial<P>, props)
+  // With `saveFromPrompt`, a `save*` key falls back to `title`, `description`
+  // or `submitLabel`. The nearest level wins: one that sets the fallback but
+  // not the `save*` key drops the `save*` key set further up.
+  const own = props.discardPrompt ?? {}
+  const inherited: DiscardPromptText = { ...defaults.discardPrompt }
+  if (props.submitLabel !== undefined) {
+    inherited.saveLabel = undefined
+  }
+  if (own.title !== undefined) {
+    inherited.saveTitle = undefined
+  }
+  if (own.description !== undefined) {
+    inherited.saveDescription = undefined
+  }
+  merged.discardPrompt = withDefaultProps(inherited, own)
+  return merged
+}
+
+// The prompt's title and description for its mode.
+function getPromptCopy(
+  text: DiscardPromptText | undefined,
+  saveFromPrompt: boolean
+) {
+  if (saveFromPrompt) {
+    return {
+      description:
+        text?.saveDescription ??
+        text?.description ??
+        "Your unsaved changes will be lost unless you save them.",
+      title: text?.saveTitle ?? text?.title ?? "Save changes?",
+    }
+  }
+  return {
+    description: text?.description ?? "Your unsaved changes will be lost.",
+    title: text?.title ?? "Discard changes?",
+  }
+}
+
+/**
+ * Sets the default props of every `FormDialog` below it, such as its copy or
+ * `saveFromPrompt`. A prop passed to a dialog wins, and `discardPrompt` merges
+ * key by key. A nested provider merges over its parent the same way.
+ */
+function FormDialogProvider({
+  children,
+  ...defaults
+}: FormDialogDefaults & { children: ReactNode }) {
+  const parent = useContext(FormDialogDefaultsContext)
+  return (
+    <FormDialogDefaultsContext value={withDialogDefaults(parent, defaults)}>
+      {children}
+    </FormDialogDefaultsContext>
+  )
+}
+
 /**
  * A dialog-hosted form: opens with fresh values and fields per session,
  * submits from a footer button outside the `<form>` (via `form="id"`), shows a
@@ -135,30 +237,34 @@ type FormDialogProps<TValues> = {
  * submit) above the footer, closes on success, and asks before discarding
  * unsaved changes (Cancel, ×, Escape, outside press) or leaving the page.
  */
-function FormDialog<TValues>({
-  cancelLabel = "Cancel",
-  children,
-  className,
-  closeOnSubmit = true,
-  description,
-  dialog,
-  disabled = false,
-  discardPrompt,
-  footer,
-  form,
-  formClassName,
-  guard = true,
-  saveFromPrompt = false,
-  submitErrorMessage,
-  submitLabel = "Save",
-  title,
-  trigger,
-}: FormDialogProps<TValues>) {
+function FormDialog<TValues>(props: FormDialogProps<TValues>) {
+  const {
+    cancelLabel = "Cancel",
+    children,
+    className,
+    closeOnSubmit = true,
+    description,
+    dialog,
+    disabled = false,
+    discardPrompt,
+    footer,
+    form,
+    formClassName,
+    guard = true,
+    saveFromPrompt = false,
+    submitErrorMessage,
+    submitLabel = "Save",
+    title,
+    trigger,
+  } = withDialogDefaults(useContext(FormDialogDefaultsContext), props)
   const formId = useId()
+  // `useForm({ disabled })` locks the dialog as this prop does.
+  const isDisabled =
+    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
@@ -166,7 +272,13 @@ function FormDialog<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, 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 })
@@ -211,12 +323,18 @@ function FormDialog<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,
   // while the fields still hold the values just saved.
   function canSubmit(): boolean {
-    return isOpen && !(disabled || form.state.isSubmitting)
+    return isOpen && !(isDisabled || form.state.isSubmitting)
   }
 
   // Resolves whether the form saved. A submit handler that throws leaves
@@ -240,10 +358,25 @@ function FormDialog<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
@@ -290,6 +423,7 @@ function FormDialog<TValues>({
         if (next) {
           open()
         } else {
+          setPromptOffersSave(saveFromPrompt && !isDisabled)
           requestLeave(close)
         }
       }}
@@ -308,7 +442,7 @@ function FormDialog<TValues>({
         initialFocus={() => {
           // A disabled control can't take focus.
           const target =
-            focus && !disabled
+            focus && !isDisabled
               ? findFieldElement(popupRef.current, focus)
               : null
           return target ?? true
@@ -320,11 +454,11 @@ function FormDialog<TValues>({
           <DialogTitle>{title}</DialogTitle>
           {description && <DialogDescription>{description}</DialogDescription>}
         </DialogHeader>
-        <FormProvider form={form}>
+        <FormProvider disabled={disabled} form={form}>
           {/* Around the <form>, not inside it, so `formClassName` child
               selectors (`space-y-4`) still reach the fields. `min-w-0` is
               for a browser that ignores `contents` on a fieldset. */}
-          <fieldset className="contents min-w-0" disabled={disabled}>
+          <fieldset className="contents min-w-0" disabled={isDisabled}>
             {/* Keyed on the session so every open mounts fresh fields. The
                 popup stays mounted through its exit animation, so reopening
                 before it ends would keep each field's local state (and any
@@ -343,7 +477,7 @@ function FormDialog<TValues>({
           {/* Next to the Save button that failed, and outside the <form>, so
               it stays in view when the fields scroll and adds no child for
               `formClassName` selectors to match. */}
-          <FormError
+          <DialogFormError
             key={formErrorKey}
             submitErrorMessage={submitErrorMessage}
           />
@@ -354,7 +488,7 @@ function FormDialog<TValues>({
             {cancelLabel}
           </DialogClose>
           <Button
-            disabled={disabled || isSubmitting}
+            disabled={isDisabled || isSubmitting}
             form={formId}
             type="submit"
           >
@@ -378,32 +512,29 @@ function FormDialog<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>
-              {discardPrompt?.title ??
-                (saveFromPrompt ? "Save changes?" : "Discard changes?")}
-            </AlertDialogTitle>
+            <AlertDialogTitle>{promptCopy.title}</AlertDialogTitle>
             <AlertDialogDescription>
-              {discardPrompt?.description ??
-                (saveFromPrompt
-                  ? "Your unsaved changes will be lost unless you save them."
-                  : "Your unsaved changes will be lost.")}
+              {promptCopy.description}
             </AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
@@ -417,9 +548,9 @@ function FormDialog<TValues>({
             >
               {discardPrompt?.confirmLabel ?? "Discard"}
             </AlertDialogAction>
-            {saveFromPrompt && (
+            {promptOffersSave && (
               <AlertDialogAction
-                disabled={disabled || isSaving || isSubmitting}
+                disabled={isDisabled || isSaving || isSubmitting}
                 onClick={saveAndLeave}
               >
                 {isSaving && <Spinner />}
@@ -433,5 +564,10 @@ function FormDialog<TValues>({
   )
 }
 
-export type { DialogForm, DiscardPromptText, FormDialogProps }
-export { FormDialog }
+export type {
+  DialogForm,
+  DiscardPromptText,
+  FormDialogDefaults,
+  FormDialogProps,
+}
+export { FormDialog, FormDialogProvider }