@zeno-lib/forms 0.5.0 → 0.7.0

package/src/fields/textarea-field.tsx

@@ -1,23 +1,11 @@
 "use client"
 
-import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsFieldRequiredBySchema,
-  useIsInvalid,
-} from "@zeno-lib/forms/lib/use-is-invalid"
-import { Children, type ComponentProps, type ReactNode, useId } from "react"
-import {
-  Field,
-  FieldDescription,
-  FieldError,
-  FieldLabel,
-} from "@/components/ui/field"
+import { useFieldControl } from "@zeno-lib/forms/lib/use-field-control"
+import { Children, type ComponentProps, type ReactNode } from "react"
 import { InputGroup, InputGroupTextarea } from "@/components/ui/input-group"
 import { Textarea } from "@/components/ui/textarea"
-import { RequiredIndicator } from "../lib/required-indicator"
+import { FieldShell } from "./field-shell"
 
 type TextAreaFieldProps = Omit<
   ComponentProps<typeof Textarea>,
@@ -36,33 +24,25 @@ type TextAreaFieldProps = Omit<
 function TextAreaField({
   children,
   description,
+  disabled,
   label,
   required,
   ...props
 }: TextAreaFieldProps) {
   const field = useFieldContext<string>()
-  const id = useId()
-  const errorId = `${id}-error`
-  const descriptionId = `${id}-description`
-  const isInvalid = useIsInvalid(field)
-  const hideErrors = useHideFieldErrors(field)
-  const showError = isInvalid && !hideErrors
+  // The label names the textarea through `htmlFor`, so the textarea needs no
+  // `aria-labelledby` and the hook doesn't get `label`.
+  const { controlProps, ...shell } = useFieldControl<string>({
+    description,
+    disabled,
+    required,
+  })
   const hasAddons = Children.count(children) > 0
-  const schemaRequired = useIsFieldRequired(field)
-  const isRequired = required ?? schemaRequired
-  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
-  const requiresValue = required ?? schemaRequiresValue
 
+  // A textarea keeps the `""` the user typed, where `controlProps.onChange`
+  // would store the field's empty value.
   const textareaProps = {
-    "aria-describedby": describedBy(
-      [description, descriptionId],
-      [showError, errorId]
-    ),
-    "aria-invalid": isInvalid || undefined,
-    "aria-required": requiresValue || undefined,
-    id,
-    name: field.name,
-    onBlur: field.handleBlur,
+    ...controlProps,
     onChange: (event: React.ChangeEvent<HTMLTextAreaElement>) =>
       field.handleChange(event.target.value),
     value: field.state.value ?? "",
@@ -70,13 +50,7 @@ function TextAreaField({
   }
 
   return (
-    <Field data-field={field.name} data-invalid={isInvalid}>
-      {label && (
-        <FieldLabel htmlFor={id}>
-          {label}
-          {isRequired && <RequiredIndicator />}
-        </FieldLabel>
-      )}
+    <FieldShell {...shell} description={description} label={label}>
       {hasAddons ? (
         <InputGroup>
           <InputGroupTextarea {...textareaProps} />
@@ -85,13 +59,7 @@ function TextAreaField({
       ) : (
         <Textarea {...textareaProps} />
       )}
-      {description && (
-        <FieldDescription id={descriptionId}>{description}</FieldDescription>
-      )}
-      {showError && (
-        <FieldError errors={field.state.meta.errors} id={errorId} />
-      )}
-    </Field>
+    </FieldShell>
   )
 }
 

package/src/form-dialog.test.tsx

@@ -11,7 +11,11 @@ import { type ReactNode, useState } from "react"
 import { afterEach, describe, expect, onTestFinished, test, vi } from "vitest"
 import { z } from "zod"
 import { useForm } from "./create-form"
-import { FormDialog } from "./form-dialog"
+import {
+  type DiscardPromptText,
+  FormDialog,
+  FormDialogProvider,
+} from "./form-dialog"
 import type { ActionResult } from "./lib/action-result"
 import { submitAction } from "./lib/submit-action"
 import { useFormDialog } from "./lib/use-form-dialog"
@@ -51,8 +55,10 @@ function Harness({
   onSubmit = vi.fn(),
   closeOnSubmit,
   disabled,
+  discardPrompt,
   saveFromPrompt,
   submitErrorMessage,
+  submitLabel,
 }: {
   /** Submit through `submitAction` with this server action instead. */
   action?: (values: Values) => Promise<ActionResult<unknown>>
@@ -60,8 +66,10 @@ function Harness({
   onSubmit?: (values: Values) => unknown
   closeOnSubmit?: boolean
   disabled?: boolean
+  discardPrompt?: DiscardPromptText
   saveFromPrompt?: boolean
   submitErrorMessage?: (error: unknown) => ReactNode
+  submitLabel?: ReactNode
 }) {
   const dialog = useFormDialog({ defaultValues: BLANK })
   const form = useForm({
@@ -86,9 +94,11 @@ function Harness({
         closeOnSubmit={closeOnSubmit}
         dialog={dialog}
         disabled={disabled}
+        discardPrompt={discardPrompt}
         form={form}
         saveFromPrompt={saveFromPrompt}
         submitErrorMessage={submitErrorMessage}
+        submitLabel={submitLabel}
         title="Person"
       >
         <InputField label="Name" name="name" />
@@ -650,3 +660,94 @@ describe("FormDialog", () => {
     expect(outer).not.toHaveBeenCalled()
   })
 })
+
+describe("FormDialogProvider", () => {
+  test("sets the defaults of the dialogs below it; a dialog's own prop wins", async () => {
+    const user = userEvent.setup()
+    render(
+      <FormDialogProvider
+        cancelLabel="Abbrechen"
+        discardPrompt={{
+          confirmLabel: "Verwerfen",
+          saveLabel: "Sichern",
+          saveTitle: "Speichern?",
+          title: "Verwerfen?",
+        }}
+      >
+        <FormDialogProvider saveFromPrompt submitLabel="Speichern">
+          <Harness discardPrompt={{ title: "Leave this person?" }} />
+        </FormDialogProvider>
+      </FormDialogProvider>
+    )
+    const name = await openEdit(user)
+    const dialog = screen.getByRole("dialog")
+    within(dialog).getByRole("button", { name: "Speichern" })
+    await user.type(name, "!")
+    await user.click(within(dialog).getByRole("button", { name: "Abbrechen" }))
+
+    // The prompt's copy merges key by key, and the nearest level wins: the
+    // dialog's title over the outer provider's `saveTitle`, its Discard
+    // label, and Save labelled by the inner provider's `submitLabel` over the
+    // outer one's `saveLabel`.
+    const prompt = await screen.findByRole("alertdialog")
+    within(prompt).getByText("Leave this person?")
+    within(prompt).getByRole("button", { name: "Verwerfen" })
+    within(prompt).getByRole("button", { name: "Speichern" })
+  })
+
+  test.each([
+    [true, "Unsaved changes", "Save them before you leave?"],
+    [false, "Discard changes?", "They will be lost."],
+  ])(
+    "a provider words the prompt for each mode (saveFromPrompt: %s)",
+    async (saveFromPrompt, title, description) => {
+      const user = userEvent.setup()
+      render(
+        <FormDialogProvider
+          discardPrompt={{
+            description: "They will be lost.",
+            saveDescription: "Save them before you leave?",
+            saveTitle: "Unsaved changes",
+            title: "Discard changes?",
+          }}
+        >
+          <Harness saveFromPrompt={saveFromPrompt} />
+        </FormDialogProvider>
+      )
+      const name = await openEdit(user)
+      await user.type(name, "!")
+      await user.keyboard("{Escape}")
+      const prompt = await screen.findByRole("alertdialog")
+      within(prompt).getByText(title)
+      within(prompt).getByText(description)
+    }
+  )
+
+  test("a dialog's submitLabel labels the prompt's Save over a provider's saveLabel", async () => {
+    const user = userEvent.setup()
+    render(
+      <FormDialogProvider discardPrompt={{ saveLabel: "Speichern" }}>
+        <Harness saveFromPrompt submitLabel="Create invoice" />
+      </FormDialogProvider>
+    )
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    await user.keyboard("{Escape}")
+    const prompt = await screen.findByRole("alertdialog")
+    within(prompt).getByRole("button", { name: "Create invoice" })
+  })
+
+  test("a dialog's own false wins over the provider's true", async () => {
+    const user = userEvent.setup()
+    render(
+      <FormDialogProvider saveFromPrompt>
+        <Harness saveFromPrompt={false} />
+      </FormDialogProvider>
+    )
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    await user.keyboard("{Escape}")
+    const prompt = await screen.findByRole("alertdialog")
+    expect(within(prompt).queryByRole("button", { name: "Save" })).toBeNull()
+  })
+})

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 }