@zeno-lib/forms 0.4.0 → 0.6.0

package/src/control-field.test.tsx

@@ -0,0 +1,338 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import type { ComponentProps } from "react"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(() => {
+  cleanup()
+})
+
+const PHONE = /Phone/
+const SUBMIT = { name: "Submit" }
+
+// A control a `<label htmlFor>` can't name: only `aria-labelledby` does.
+function StarRating({
+  disabled,
+  name: _name,
+  onChange,
+  value,
+  ...props
+}: Omit<ComponentProps<"div">, "onChange"> & {
+  disabled?: boolean
+  name?: string
+  onChange: (value: number) => void
+  value?: number | null
+}) {
+  return (
+    <div role="radiogroup" {...props}>
+      {[1, 2, 3].map((star) => (
+        // biome-ignore lint/a11y/useSemanticElements: a custom radio group, as a star rating draws one.
+        <button
+          aria-checked={value === star}
+          disabled={disabled}
+          key={star}
+          onClick={() => onChange(star)}
+          role="radio"
+          type="button"
+        >
+          {star}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+// A text control that reports its value, not a change event.
+function PhoneInput({
+  onChange,
+  ...props
+}: Omit<ComponentProps<"input">, "onChange" | "value"> & {
+  onChange: (value: string) => void
+  value: string
+}) {
+  return (
+    <input
+      {...props}
+      onChange={(event) => onChange(event.target.value)}
+      type="tel"
+    />
+  )
+}
+
+describe("ControlField", () => {
+  test("names and describes its control, and flags it once invalid", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ rating: z.number("Rate it") })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { ControlField, SubmitButton } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              description="Out of three."
+              label="Rating"
+              name="rating"
+              render={(control) => <StarRating {...control} />}
+            />
+            <SubmitButton>Submit</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+    const { container } = render(<H />)
+    const group = screen.getByRole("radiogroup", { name: "Rating" })
+    const description = screen.getByText("Out of three.")
+    expect(group.getAttribute("aria-describedby")).toBe(description.id)
+    expect(group.hasAttribute("aria-invalid")).toBe(false)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+    const error = await screen.findByRole("alert")
+    expect(error.textContent).toBe("Rate it")
+    expect(group.getAttribute("aria-invalid")).toBe("true")
+    expect(group.getAttribute("aria-describedby")).toBe(
+      `${description.id} ${error.id}`
+    )
+    expect(
+      container
+        .querySelector('[data-field="rating"]')
+        ?.getAttribute("data-invalid")
+    ).toBe("true")
+
+    await user.click(screen.getByRole("radio", { name: "2" }))
+    expect(screen.queryByRole("alert")).toBeNull()
+    expect(group.hasAttribute("aria-invalid")).toBe(false)
+  })
+
+  test("marks the field touched on blur, so its error shows", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ phone: z.string().min(1, "Enter a phone") })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={(control) => <PhoneInput {...control} />}
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByLabelText(PHONE))
+    expect(screen.queryByRole("alert")).toBeNull()
+    await user.tab()
+    expect((await screen.findByRole("alert")).textContent).toBe("Enter a phone")
+  })
+
+  test("takes required from the schema unless `required` says otherwise", () => {
+    const schema = z.object({
+      forced: z.string().optional(),
+      kept: z.string().min(1),
+      lifted: z.string().min(1),
+      open: z.string().optional(),
+    })
+    const FIELDS = [
+      { name: "kept" },
+      { name: "open" },
+      { name: "forced", required: true },
+      { name: "lifted", required: false },
+    ] as const
+    function H({ requiredIndicator }: { requiredIndicator: boolean }) {
+      const form = useForm({ onSubmit: vi.fn(), requiredIndicator, schema })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            {FIELDS.map((props) => (
+              <ControlField
+                key={props.name}
+                label={props.name}
+                render={(control) => (
+                  <PhoneInput {...control} value={control.value ?? ""} />
+                )}
+                {...props}
+              />
+            ))}
+          </Form>
+        </FormProvider>
+      )
+    }
+    for (const requiredIndicator of [true, false]) {
+      const { container, unmount } = render(
+        <H requiredIndicator={requiredIndicator} />
+      )
+      const required = screen
+        .getAllByRole("textbox")
+        .filter((input) => input.getAttribute("aria-required") === "true")
+        .map((input) => input.getAttribute("name"))
+      expect(required).toEqual(["kept", "forced"])
+      // `required` overrides `requiredIndicator: false` too.
+      expect(
+        container.querySelectorAll('[data-slot="required-indicator"]')
+      ).toHaveLength(requiredIndicator ? 2 : 1)
+      unmount()
+    }
+  })
+
+  test("clearing stores the value the schema accepts as empty", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({
+      count: z.number().nullable(),
+      nullable: z.string().min(1).nullable(),
+      optional: z.string().min(1).optional(),
+      tags: z.array(z.string()),
+      text: z.string(),
+    })
+    const captured: { values?: unknown } = {}
+    function H() {
+      const form = useForm({
+        defaultValues: {
+          count: 1,
+          nullable: "a",
+          optional: "b",
+          tags: ["c"],
+          text: "d",
+        },
+        onSubmit: vi.fn(),
+        schema,
+      })
+      const { ControlField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            {(["nullable", "optional", "text"] as const).map((name) => (
+              <ControlField
+                key={name}
+                label={name}
+                name={name}
+                render={(control) => (
+                  <PhoneInput {...control} value={control.value ?? ""} />
+                )}
+              />
+            ))}
+            <ControlField
+              label="Tags"
+              name="tags"
+              render={({ onChange }) => (
+                <button onClick={() => onChange([])} type="button">
+                  Clear tags
+                </button>
+              )}
+            />
+            {/* A number control reports `NaN` once cleared. */}
+            <ControlField
+              label="Count"
+              name="count"
+              render={({ onChange }) => (
+                <button onClick={() => onChange(Number.NaN)} type="button">
+                  Clear count
+                </button>
+              )}
+            />
+            <Subscribe selector={(state) => state.values}>
+              {(values) => {
+                captured.values = values
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.clear(screen.getByLabelText("nullable"))
+    await user.clear(screen.getByLabelText("optional"))
+    await user.clear(screen.getByLabelText("text"))
+    await user.click(screen.getByRole("button", { name: "Clear tags" }))
+    await user.click(screen.getByRole("button", { name: "Clear count" }))
+    expect(captured.values).toStrictEqual({
+      count: null,
+      nullable: null,
+      optional: undefined,
+      tags: [],
+      text: "",
+    })
+    expect(schema.safeParse(captured.values).success).toBe(true)
+  })
+
+  test("keeps one `onChange` across renders, so a control can memoize on it", async () => {
+    const user = userEvent.setup()
+    const handlers = new Set<unknown>()
+    function H() {
+      const form = useForm({ defaultValues: { phone: "" }, onSubmit: vi.fn() })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={(control) => {
+                handlers.add(control.onChange)
+                return <PhoneInput {...control} />
+              }}
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.type(screen.getByLabelText(PHONE), "079")
+    expect(handlers.size).toBe(1)
+  })
+
+  test("refuses a change event, rather than storing it", async () => {
+    const user = userEvent.setup()
+    const errors: unknown[] = []
+    const onError = (event: ErrorEvent) => {
+      event.preventDefault()
+      errors.push(event.error)
+    }
+    window.addEventListener("error", onError)
+    const captured: { values?: unknown } = {}
+    function H() {
+      const form = useForm({ defaultValues: { phone: "" }, onSubmit: vi.fn() })
+      const { ControlField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={({ onChange }) => (
+                // The mistake: an event handed to `onChange` as the value.
+                <button
+                  onClick={(event) => onChange(event as never)}
+                  type="button"
+                >
+                  Set
+                </button>
+              )}
+            />
+            <Subscribe selector={(state) => state.values}>
+              {(values) => {
+                captured.values = values
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    try {
+      render(<H />)
+      await user.click(screen.getByRole("button", { name: "Set" }))
+    } finally {
+      window.removeEventListener("error", onError)
+    }
+    expect(errors).toEqual([expect.any(TypeError)])
+    expect(captured.values).toStrictEqual({ phone: "" })
+  })
+})

package/src/create-form.tsx

@@ -6,8 +6,10 @@ import { createZenoForm } from "@zeno-lib/forms"
 import { CheckboxField } from "./fields/checkbox-field"
 import { CheckboxGroupField } from "./fields/checkbox-group-field"
 import { ComboboxField } from "./fields/combobox-field"
+import { ControlField } from "./fields/control-field"
 import { DatePickerField } from "./fields/date-picker-field"
 import { EmailField } from "./fields/email-field"
+import { FormError } from "./fields/form-error"
 import { InputField } from "./fields/input-field"
 import { MoneyField } from "./fields/money-field"
 import { MultiSelectField } from "./fields/multi-select-field"
@@ -31,6 +33,7 @@ const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
     CheckboxField,
     CheckboxGroupField,
     ComboboxField,
+    ControlField,
     DatePickerField,
     EmailField,
     InputField,
@@ -48,6 +51,7 @@ const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
     YearField,
   },
   formComponents: {
+    FormError,
     ResetButton,
     SubmitButton,
   },
@@ -55,5 +59,6 @@ const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
 
 export * from "@zeno-lib/forms"
 export { ValidationSpinner } from "./addons/validation-spinner"
+export { FieldShell } from "./fields/field-shell"
 export { RadioGroupFieldItem } from "./fields/radio-group-field"
 export { useAppForm, useForm, withFieldGroup, withForm }

package/src/create-zeno-form.tsx

@@ -4,6 +4,7 @@
 import type {
   AnyFormApi,
   DeepKeys,
+  DeepValue,
   FormAsyncValidateOrFn,
   FormOptions,
   FormValidateOrFn,
@@ -18,6 +19,8 @@ import {
   getRequiredPaths,
   type StandardSchemaLike,
 } from "./lib/schema-required"
+import { setSubmitError } from "./lib/submit-error"
+import type { FieldControlProps } from "./lib/use-field-control"
 import { useRebasedDefaultValues } from "./lib/use-rebased-default-values"
 import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning"
 import { ValidationError } from "./lib/validation-error"
@@ -272,9 +275,26 @@ type WithValidators = {
 // biome-ignore lint/suspicious/noExplicitAny: field components accept arbitrary props.
 type AnyComponent = React.ComponentType<any>
 
+// A field that hands `render` a `FieldControlProps` (the kit's `ControlField`)
+// gets the control typed with the value at `name`, which its own generic
+// can't see. Matching on the parameter, not on `render` as a whole, leaves a
+// field whose `render` takes something else (or nothing) as declared.
+type WithControlValue<P, V> = P extends {
+  render: (control: infer C) => ReactNode
+}
+  ? // biome-ignore lint/suspicious/noExplicitAny: matches any value type.
+    [C] extends [FieldControlProps<any>]
+    ? Omit<P, "render"> & {
+        render: (control: FieldControlProps<V>) => ReactNode
+      }
+    : P
+  : P
+
 type FieldWrappers<FC extends Record<string, AnyComponent>, T> = {
   [K in keyof FC]: <N extends DeepKeys<T>>(
-    props: ComponentProps<FC[K]> & { name: N } & WithValidators
+    props: WithControlValue<ComponentProps<FC[K]>, DeepValue<T, N>> & {
+      name: N
+    } & WithValidators
   ) => ReactNode
 }
 
@@ -439,6 +459,7 @@ export function createZenoForm<
 
     const wrappedOnSubmit = userOnSubmit
       ? ((async (props: { formApi: AnyFormApi; value: TFormData }) => {
+          const { submissionAttempts } = props.formApi.state
           try {
             await (
               userOnSubmit as unknown as (
@@ -450,6 +471,16 @@ export function createZenoForm<
               applyValidationError(props.formApi, error)
               return
             }
+            // Kept for `FormError`, unless an edit, a reset (a dialog closed
+            // meanwhile) or a newer submit came first: then it is about
+            // values no longer on screen.
+            const { state } = props.formApi
+            if (
+              state.values === props.value &&
+              state.submissionAttempts === submissionAttempts
+            ) {
+              setSubmitError(props.formApi, error)
+            }
             throw error
           }
         }) as typeof userOnSubmit)

package/src/fields/control-field.tsx

@@ -0,0 +1,57 @@
+"use client"
+
+import {
+  type FieldControlProps,
+  useFieldControl,
+} from "@zeno-lib/forms/lib/use-field-control"
+import type { ReactNode } from "react"
+import { FieldShell } from "./field-shell"
+
+type ControlFieldProps<TValue = unknown> = {
+  description?: ReactNode
+  disabled?: boolean
+  label?: ReactNode
+  /**
+   * Renders the control, given the props that bind it to the field: `id`,
+   * `name`, `value`, `onChange(value)`, `onBlur`, `disabled` and the
+   * `aria-*`. Spread them on a control that takes its value that way, or map
+   * them for one that doesn't. Keep `aria-invalid` on the focusable element
+   * (or a group root around it): a failed submit focuses the first invalid
+   * field by it.
+   */
+  render: (control: FieldControlProps<TValue>) => ReactNode
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
+  required?: boolean
+}
+
+/**
+ * Binds a controlled component the kit has no field for (a phone input, a
+ * star rating, a color picker) in the kit's field layout. Clearing it stores
+ * the field's empty value, as the kit's fields do.
+ */
+function ControlField<TValue = unknown>({
+  description,
+  disabled,
+  label,
+  render,
+  required,
+}: ControlFieldProps<TValue>) {
+  const { controlProps, ...shell } = useFieldControl<TValue>({
+    description,
+    disabled,
+    label,
+    required,
+  })
+
+  return (
+    <FieldShell {...shell} description={description} label={label}>
+      {render(controlProps)}
+    </FieldShell>
+  )
+}
+
+export type { ControlFieldProps }
+export { ControlField }

package/src/fields/field-shell.tsx

@@ -0,0 +1,73 @@
+"use client"
+
+import type { FieldControl } from "@zeno-lib/forms/lib/use-field-control"
+import type { ReactNode } from "react"
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@/components/ui/field"
+import { RequiredIndicator } from "../lib/required-indicator"
+
+type FieldShellProps = Pick<
+  FieldControl,
+  | "descriptionId"
+  | "errorId"
+  | "errors"
+  | "id"
+  | "isInvalid"
+  | "labelId"
+  | "name"
+  | "showRequiredIndicator"
+> & {
+  /** The control, bound with `useFieldControl`'s `controlProps`. */
+  children: ReactNode
+  description?: ReactNode
+  label?: ReactNode
+}
+
+/**
+ * The field layout every kit field shares: the label with its `*`, the
+ * control, the description and the error, tied together by the ids
+ * `useFieldControl` returns. Spread the rest of its result here:
+ *
+ * ```tsx
+ * const { controlProps, ...shell } = useFieldControl({ description, label })
+ * <FieldShell {...shell} description={description} label={label}>
+ *   <MyControl {...controlProps} />
+ * </FieldShell>
+ * ```
+ */
+function FieldShell({
+  children,
+  description,
+  descriptionId,
+  errorId,
+  errors,
+  id,
+  isInvalid,
+  label,
+  labelId,
+  name,
+  showRequiredIndicator,
+}: FieldShellProps) {
+  return (
+    <Field data-field={name} data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={id} id={labelId}>
+          {label}
+          {showRequiredIndicator && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      {children}
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {errors.length > 0 && <FieldError errors={errors} id={errorId} />}
+    </Field>
+  )
+}
+
+export type { FieldShellProps }
+export { FieldShell }

package/src/fields/form-error.tsx

@@ -0,0 +1,61 @@
+"use client"
+
+import { useFormContext } from "@zeno-lib/forms/lib/contexts"
+import { useSubmitError } from "@zeno-lib/forms/lib/submit-error"
+import { useSelector } from "@zeno-lib/forms/tanstack"
+import type { ComponentProps, ReactNode } from "react"
+import { FieldError } from "@/components/ui/field"
+
+type FormErrorProps = Omit<
+  ComponentProps<typeof FieldError>,
+  "children" | "errors"
+> & {
+  /**
+   * Shown when the submit handler throws (a network failure, an unexpected
+   * server error). Defaults to `"Something went wrong. Try again."`. A
+   * function gets what was thrown.
+   */
+  submitErrorMessage?: ReactNode | ((error: unknown) => ReactNode)
+}
+
+/**
+ * The form-level error, as a `role="alert"` message: the `formErrors` an
+ * action returns through `submitAction`, a `ValidationError`'s `formError`,
+ * or `submitErrorMessage` when the submit throws. Renders nothing otherwise.
+ * It clears when the user edits the form, and a thrown one also when they
+ * submit again.
+ */
+function FormError({
+  submitErrorMessage = "Something went wrong. Try again.",
+  ...props
+}: FormErrorProps) {
+  const form = useFormContext()
+  const formError = useSelector(form.store, (state) => state.errorMap.onSubmit)
+  const submitError = useSubmitError(form)
+
+  // `submitAction` joins several messages with a line break. A schema's
+  // form-level result is an object, not a message, and isn't shown here. It
+  // wins over a thrown submit: it says what went wrong.
+  if (typeof formError === "string" && formError !== "") {
+    return (
+      <FieldError
+        data-slot="form-error"
+        errors={formError.split("\n").map((message) => ({ message }))}
+        {...props}
+      />
+    )
+  }
+  if (!submitError) {
+    return null
+  }
+  return (
+    <FieldError data-slot="form-error" {...props}>
+      {typeof submitErrorMessage === "function"
+        ? submitErrorMessage(submitError.error)
+        : submitErrorMessage}
+    </FieldError>
+  )
+}
+
+export type { FormErrorProps }
+export { FormError }

package/src/fields/index.ts

@@ -2,8 +2,11 @@
 export * from "./checkbox-field"
 export * from "./checkbox-group-field"
 export * from "./combobox-field"
+export * from "./control-field"
 export * from "./date-picker-field"
 export * from "./email-field"
+export * from "./field-shell"
+export * from "./form-error"
 export * from "./input-field"
 export * from "./money-field"
 export * from "./multi-select-field"