@zeno-lib/forms 0.6.0 → 0.7.0

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> = {
@@ -99,9 +113,9 @@ type FormDialogProps<TValues> = {
   /** Close after a successful submit. Defaults to `true`. */
   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)
   /**
@@ -117,8 +131,9 @@ type FormDialogProps<TValues> = {
    */
   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.
+   * Defaults to `false`.
    */
   disabled?: boolean
   /** Class for the dialog popup (e.g. a wider `sm:max-w-lg`). */
@@ -127,6 +142,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,26 +231,30 @@ 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
@@ -167,6 +267,8 @@ function FormDialog<TValues>({
   const announceOnPromptClosed = useRef<boolean>(false)
   const [formErrorKey, setFormErrorKey] = useState(0)
   const { close, defaultValues, focus, isOpen, open, session } = dialog
+  const DialogFormError = form.FormError ?? FormError
+  const promptCopy = getPromptCopy(discardPrompt, saveFromPrompt)
   // 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 })
@@ -216,7 +318,7 @@ function FormDialog<TValues>({
   // 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
@@ -308,7 +410,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 +422,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 +445,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 +456,7 @@ function FormDialog<TValues>({
             {cancelLabel}
           </DialogClose>
           <Button
-            disabled={disabled || isSubmitting}
+            disabled={isDisabled || isSubmitting}
             form={formId}
             type="submit"
           >
@@ -395,15 +497,9 @@ function FormDialog<TValues>({
           size={saveFromPrompt ? "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>
@@ -419,7 +515,7 @@ function FormDialog<TValues>({
             </AlertDialogAction>
             {saveFromPrompt && (
               <AlertDialogAction
-                disabled={disabled || isSaving || isSubmitting}
+                disabled={isDisabled || isSaving || isSubmitting}
                 onClick={saveAndLeave}
               >
                 {isSaving && <Spinner />}
@@ -433,5 +529,10 @@ function FormDialog<TValues>({
   )
 }
 
-export type { DialogForm, DiscardPromptText, FormDialogProps }
-export { FormDialog }
+export type {
+  DialogForm,
+  DiscardPromptText,
+  FormDialogDefaults,
+  FormDialogProps,
+}
+export { FormDialog, FormDialogProvider }

package/src/form-disabled.test.tsx

@@ -0,0 +1,329 @@
+import {
+  cleanup,
+  render,
+  screen,
+  waitFor,
+} from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { memo, type ReactNode, useState } from "react"
+import { createPortal } from "react-dom"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { Form, FormProvider, RadioGroupFieldItem, useForm } from "./create-form"
+import { FormDialog } from "./form-dialog"
+import { useFormDialog } from "./lib/use-form-dialog"
+
+afterEach(() => {
+  cleanup()
+})
+
+type Values = { accept: boolean; name: string; notify: boolean; plan: string }
+const DEFAULTS: Values = {
+  accept: false,
+  name: "",
+  notify: false,
+  plan: "free",
+}
+
+type Box = { current: Values | undefined }
+
+// The fields that draw their own controls, which a `<fieldset disabled>`
+// doesn't reach, plus a native input. `notify` passes `disabled={false}`.
+function renderFields(form: ReturnType<typeof useTestForm>) {
+  const { CheckboxField, InputField, RadioGroupField, SwitchField } = form
+  return (
+    <>
+      <CheckboxField label="Accept" name="accept" />
+      <SwitchField disabled={false} label="Notify" name="notify" />
+      <RadioGroupField label="Plan" name="plan">
+        <RadioGroupFieldItem value="free">Free</RadioGroupFieldItem>
+        <RadioGroupFieldItem value="pro">Pro</RadioGroupFieldItem>
+      </RadioGroupField>
+      <InputField label="Name" name="name" />
+    </>
+  )
+}
+
+function useTestForm(options: { disabled?: boolean; onSubmit?: () => void }) {
+  return useForm({
+    defaultValues: DEFAULTS,
+    disabled: options.disabled,
+    onSubmit: options.onSubmit ?? vi.fn(),
+  })
+}
+
+function Capture({
+  captured,
+  form,
+}: {
+  captured: Box
+  form: ReturnType<typeof useTestForm>
+}) {
+  const { Subscribe } = form
+  return (
+    <Subscribe selector={(state) => state.values}>
+      {(values) => {
+        captured.current = values
+        return null
+      }}
+    </Subscribe>
+  )
+}
+
+const DRAWN_CONTROLS = [
+  ["checkbox", "Accept"],
+  ["switch", "Notify"],
+  ["radio", "Pro"],
+] as const
+
+// Clicks each control the fields draw, then checks that none took the click
+// and that each shows as disabled. They are spans over a hidden input: a
+// `<fieldset disabled>` disables only the input, so the span still looks,
+// focuses and announces as enabled.
+async function expectDrawnControlsDisabled(
+  user: ReturnType<typeof userEvent.setup>,
+  captured: Box
+) {
+  const [checkbox, toggle, radio] = DRAWN_CONTROLS.map(([role, name]) =>
+    screen.getByRole(role, { name })
+  ) as [HTMLElement, HTMLElement, HTMLElement]
+  await user.click(checkbox)
+  await user.click(toggle)
+  await user.click(radio)
+  expect(captured.current).toEqual(DEFAULTS)
+  for (const [role, name] of DRAWN_CONTROLS) {
+    expect(screen.getByRole(role, { name }).hasAttribute("data-disabled")).toBe(
+      true
+    )
+  }
+}
+
+describe("a disabled form", () => {
+  test.each(["useForm({ disabled })", "<Form disabled>"])(
+    "%s turns off every field, a field's `disabled={false}` included, and the submit",
+    async (via) => {
+      const user = userEvent.setup()
+      const onSubmit = vi.fn()
+      const captured: Box = { current: undefined }
+      function H() {
+        const form = useTestForm({
+          disabled: via.startsWith("useForm"),
+          onSubmit,
+        })
+        const { SubmitButton } = form
+        return (
+          <FormProvider form={form}>
+            <Form disabled={via.startsWith("<Form")} id="profile">
+              {renderFields(form)}
+              <SubmitButton>Save</SubmitButton>
+              <Capture captured={captured} form={form} />
+            </Form>
+            <button form="profile" type="submit">
+              Save from outside
+            </button>
+          </FormProvider>
+        )
+      }
+      render(<H />)
+      await expectDrawnControlsDisabled(user, captured)
+      expect(
+        screen.getByRole("textbox", { name: "Name" }).matches(":disabled")
+      ).toBe(true)
+      expect(
+        screen.getByRole("button", { name: "Save" }).matches(":disabled")
+      ).toBe(true)
+      await user.click(
+        screen.getByRole("button", { name: "Save from outside" })
+      )
+      expect(onSubmit).not.toHaveBeenCalled()
+    }
+  )
+
+  test("a field's own `disabled` still applies in an enabled form", async () => {
+    const user = userEvent.setup()
+    const captured: Box = { current: undefined }
+    function H() {
+      const form = useTestForm({})
+      const { CheckboxField, SwitchField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <CheckboxField label="Accept" name="accept" />
+            <SwitchField disabled label="Notify" name="notify" />
+            <Capture captured={captured} form={form} />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByRole("checkbox", { name: "Accept" }))
+    await user.click(screen.getByRole("switch", { name: "Notify" }))
+    expect(captured.current).toEqual({ ...DEFAULTS, accept: true })
+  })
+
+  test("toggling `useForm({ disabled })` reaches fields under a memoized parent", async () => {
+    const user = userEvent.setup()
+    const captured: Box = { current: undefined }
+    const Section = memo(({ form }: { form: ReturnType<typeof useTestForm> }) =>
+      renderFields(form)
+    )
+    function H() {
+      const [locked, setLocked] = useState(false)
+      const form = useTestForm({ disabled: locked })
+      return (
+        <FormProvider form={form}>
+          <button onClick={() => setLocked(true)} type="button">
+            Lock
+          </button>
+          <Form>
+            <Section form={form} />
+            <Capture captured={captured} form={form} />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByRole("button", { name: "Lock" }))
+    await expectDrawnControlsDisabled(user, captured)
+  })
+
+  test("toggling `useForm({ disabled })` reaches memoized fields with no Zeno provider", async () => {
+    const user = userEvent.setup()
+    const captured: Box = { current: undefined }
+    const Section = memo(({ form }: { form: ReturnType<typeof useTestForm> }) =>
+      renderFields(form)
+    )
+    function H() {
+      const [locked, setLocked] = useState(false)
+      const form = useTestForm({ disabled: locked })
+      return (
+        <form.AppForm>
+          <button onClick={() => setLocked(true)} type="button">
+            Lock
+          </button>
+          <Section form={form} />
+          <Capture captured={captured} form={form} />
+        </form.AppForm>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByRole("button", { name: "Lock" }))
+    await expectDrawnControlsDisabled(user, captured)
+  })
+
+  test("a form rendered inside another's `<Form disabled>` keeps its own state", async () => {
+    const user = userEvent.setup()
+    const onSubmit = vi.fn()
+    function H() {
+      const outer = useTestForm({})
+      const inner = useForm({ defaultValues: { title: "" }, onSubmit })
+      return (
+        <FormProvider form={outer}>
+          <Form disabled>
+            <outer.InputField label="Name" name="name" />
+            {/* A quick-add popover: portalled, under TanStack's provider. */}
+            {createPortal(
+              <inner.AppForm>
+                <Form>
+                  <inner.InputField label="Title" name="title" />
+                  <inner.SubmitButton>Add</inner.SubmitButton>
+                </Form>
+              </inner.AppForm>,
+              document.body
+            )}
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    expect(
+      screen.getByRole("textbox", { name: "Name" }).matches(":disabled")
+    ).toBe(true)
+    await user.type(screen.getByRole("textbox", { name: "Title" }), "Draft")
+    await user.click(screen.getByRole("button", { name: "Add" }))
+    expect(onSubmit).toHaveBeenCalledOnce()
+  })
+
+  test("CheckboxGroupField dims each option's label", () => {
+    function H() {
+      const form = useForm({
+        defaultValues: { channels: [] as string[] },
+        disabled: true,
+      })
+      return (
+        <FormProvider form={form}>
+          <form.CheckboxGroupField
+            items={[{ label: "Email", value: "email" }]}
+            label="Channels"
+            name="channels"
+          />
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const option = screen.getByRole("checkbox", { name: "Email" })
+    expect(
+      option.closest('[data-slot="field"]')?.getAttribute("data-disabled")
+    ).toBe("true")
+  })
+})
+
+describe("FormDialog", () => {
+  function DialogHarness({
+    captured,
+    children,
+    disabled,
+    formDisabled,
+  }: {
+    captured: Box
+    children?: ReactNode
+    disabled?: boolean
+    formDisabled?: boolean
+  }) {
+    const dialog = useFormDialog({ defaultValues: DEFAULTS })
+    const form = useForm({
+      defaultValues: dialog.defaultValues,
+      disabled: formDisabled,
+      onSubmit: vi.fn(),
+    })
+    return (
+      <>
+        <button onClick={() => dialog.open()} type="button">
+          Open
+        </button>
+        <FormDialog
+          dialog={dialog}
+          disabled={disabled}
+          form={form}
+          title="Profile"
+        >
+          {renderFields(form)}
+          <Capture captured={captured} form={form} />
+          {children}
+        </FormDialog>
+      </>
+    )
+  }
+
+  test("disabled reaches the checkbox, switch and radio its fieldset can't", async () => {
+    const user = userEvent.setup()
+    const captured: Box = { current: undefined }
+    render(<DialogHarness captured={captured} disabled />)
+    await user.click(screen.getByRole("button", { name: "Open" }))
+    await screen.findByRole("dialog")
+    await expectDrawnControlsDisabled(user, captured)
+  })
+
+  test("`useForm({ disabled })` turns off Save, as the prop does", async () => {
+    const user = userEvent.setup()
+    const captured: Box = { current: undefined }
+    render(<DialogHarness captured={captured} formDisabled />)
+    await user.click(screen.getByRole("button", { name: "Open" }))
+    await screen.findByRole("dialog")
+    await waitFor(() =>
+      expect(
+        screen.getByRole("button", { name: "Save" }).matches(":disabled")
+      ).toBe(true)
+    )
+    await expectDrawnControlsDisabled(user, captured)
+  })
+})