@zeno-lib/forms 0.5.0 → 0.7.0

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)
+  })
+})

package/src/form-element.tsx

@@ -1,52 +1,87 @@
 "use client"
 
 import type { AnyFormApi } from "@tanstack/react-form"
-import type { ComponentProps, FormEvent, ReactNode } from "react"
+import {
+  type ComponentProps,
+  type FormEvent,
+  type ReactNode,
+  useMemo,
+} from "react"
 
 import { FormProvider as RawFormProvider, useFormContext } from "./lib/contexts"
 import { focusFirstInvalid, restoreFocus } from "./lib/focus-first-invalid"
+import { FormDisabledContext, useIsFormDisabled } from "./lib/form-disabled"
 import { reportSubmitError } from "./lib/submit-error"
 
 type FormProviderProps = {
   children: ReactNode
+  /**
+   * Disable every field of the form and its submit button, as
+   * `useForm({ disabled })` does. A field's own `disabled` still applies.
+   */
+  disabled?: boolean
   form: { handleSubmit: () => unknown }
 }
 
-function FormProvider({ children, form }: FormProviderProps) {
+function FormProvider({ children, disabled = false, form }: FormProviderProps) {
+  const { store } = form as AnyFormApi
+  const scope = useMemo(() => ({ disabled, key: store }), [disabled, store])
   return (
-    <RawFormProvider value={form as AnyFormApi}>{children}</RawFormProvider>
+    <RawFormProvider value={form as AnyFormApi}>
+      <FormDisabledContext value={scope}>{children}</FormDisabledContext>
+    </RawFormProvider>
   )
 }
 
-type FormProps = Omit<ComponentProps<"form">, "onSubmit">
+type FormProps = Omit<ComponentProps<"form">, "onSubmit"> & {
+  /**
+   * Disable every field and button of the kit inside, and ignore a submit. A
+   * field's own `disabled` still applies. A button outside the `<form>`
+   * (`form="id"`) isn't inside: disable the form with `useForm({ disabled })`
+   * or `<FormProvider disabled>` to reach it.
+   */
+  disabled?: boolean
+}
 
-function Form({ children, className, ...props }: FormProps) {
+function Form({ children, className, disabled = false, ...props }: FormProps) {
   const form = useFormContext()
+  const isDisabled = useIsFormDisabled(form) || disabled
+  const { store } = form
+  const scope = useMemo(
+    () => ({ disabled: isDisabled, key: store }),
+    [isDisabled, store]
+  )
   return (
-    <form
-      className={className}
-      noValidate
-      onSubmit={async (event: FormEvent<HTMLFormElement>) => {
-        event.preventDefault()
-        event.stopPropagation()
-        const node = event.currentTarget
-        const focused = node.ownerDocument.activeElement
-        // Caught so the user can retry; `useForm` keeps it for `FormError`.
-        await Promise.resolve(form.handleSubmit()).catch(reportSubmitError)
-        const { isSubmitSuccessful, isValid } = form.state
-        if (!isValid && focusFirstInvalid(node)) {
-          return
-        }
-        // A form-level failure has no field to fix, so focus stays where it
-        // was, or goes back there if the submit button's disabling dropped it.
-        if (!(isValid && isSubmitSuccessful)) {
-          restoreFocus(focused)
-        }
-      }}
-      {...props}
-    >
-      {children}
-    </form>
+    <FormDisabledContext value={scope}>
+      <form
+        className={className}
+        noValidate
+        onSubmit={async (event: FormEvent<HTMLFormElement>) => {
+          event.preventDefault()
+          event.stopPropagation()
+          // A `<button form={id}>` outside the form can still submit it.
+          if (isDisabled) {
+            return
+          }
+          const node = event.currentTarget
+          const focused = node.ownerDocument.activeElement
+          // Caught so the user can retry; `useForm` keeps it for `FormError`.
+          await Promise.resolve(form.handleSubmit()).catch(reportSubmitError)
+          const { isSubmitSuccessful, isValid } = form.state
+          if (!isValid && focusFirstInvalid(node)) {
+            return
+          }
+          // A form-level failure has no field to fix, so focus stays where it
+          // was, or goes back there if the submit button's disabling dropped it.
+          if (!(isValid && isSubmitSuccessful)) {
+            restoreFocus(focused)
+          }
+        }}
+        {...props}
+      >
+        {children}
+      </form>
+    </FormDisabledContext>
   )
 }
 

package/src/grouped-options.test-d.ts

@@ -0,0 +1,59 @@
+import { expectTypeOf, test } from "vitest"
+import { useForm } from "./create-form"
+import { ComboboxField } from "./fields/combobox-field"
+import { MultiSelectField } from "./fields/multi-select-field"
+
+type Party = { id: number; kind: "company" | "person" }
+type PartyItem = { label: string; value: Party }
+
+const GROUPS: { label: string; items: PartyItem[] }[] = [
+  {
+    items: [{ label: "Ada", value: { id: 1, kind: "person" } }],
+    label: "People",
+  },
+]
+
+const isSameParty = (a: Party, b: Party) => a.kind === b.kind && a.id === b.id
+
+test("grouped items type renderItem with an item and isItemEqualToValue with its value", () => {
+  ComboboxField({
+    isItemEqualToValue: (a, b) => {
+      expectTypeOf(a).toEqualTypeOf<Party>()
+      return isSameParty(a, b)
+    },
+    items: GROUPS,
+    renderItem: (item) => {
+      expectTypeOf(item).toEqualTypeOf<PartyItem>()
+      return null
+    },
+  })
+  MultiSelectField({
+    isItemEqualToValue: (a, b) => {
+      expectTypeOf(a).toEqualTypeOf<Party>()
+      return isSameParty(a, b)
+    },
+    items: GROUPS,
+    renderItem: (item) => {
+      expectTypeOf(item).toEqualTypeOf<PartyItem>()
+      return null
+    },
+  })
+})
+
+// `form.ComboboxField` reads the field's props with `T` as `unknown`.
+test("form fields take a comparator typed with the value", () => {
+  const form = useForm({
+    defaultValues: { parties: [] as Party[], payer: null as Party | null },
+    onSubmit: () => undefined,
+  })
+  form.ComboboxField({
+    isItemEqualToValue: isSameParty,
+    items: GROUPS,
+    name: "payer",
+  })
+  form.MultiSelectField({
+    isItemEqualToValue: isSameParty,
+    items: GROUPS,
+    name: "parties",
+  })
+})