@zeno-lib/forms 0.0.1 → 0.2.0

package/src/use-form.focus-invalid.test.tsx

@@ -0,0 +1,198 @@
+import {
+  cleanup,
+  render,
+  screen,
+  waitFor,
+} from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import type { ReactNode } from "react"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, RadioGroupFieldItem, useForm } from "./create-form"
+
+afterEach(() => {
+  cleanup()
+})
+
+const schema = z.object({
+  email: z.email("Enter a valid email"),
+  name: z.string().min(1, "Required"),
+})
+
+// Forms in these tests reuse field names (and so ids), so look controls up
+// inside their own form rather than through label association.
+function control(form: string, name: string) {
+  return screen
+    .getByRole("form", { name: form })
+    .querySelector<HTMLElement>(`[name="${name}"]`)
+}
+
+function ProfileForm({
+  id,
+  label,
+  onSubmitInvalid,
+  outsideSubmit,
+}: {
+  id?: string
+  label: string
+  onSubmitInvalid?: () => void
+  outsideSubmit?: boolean
+}) {
+  const form = useForm({
+    ...(onSubmitInvalid ? { onSubmitInvalid } : {}),
+    defaultValues: { email: "valid@example.com" },
+    onSubmit: vi.fn(),
+    schema,
+  })
+  const { EmailField, InputField, SubmitButton } = form
+  const submit: ReactNode = (
+    <SubmitButton form={id}>{`${label} submit`}</SubmitButton>
+  )
+  return (
+    <FormProvider form={form}>
+      <Form aria-label={label} id={id}>
+        <EmailField name="email" />
+        <InputField label="Name" name="name" />
+        {outsideSubmit ? null : submit}
+      </Form>
+      {outsideSubmit ? submit : null}
+    </FormProvider>
+  )
+}
+
+describe("<Form> — focus the first invalid field on a failed submit", () => {
+  test("focuses the first invalid field; onSubmitInvalid passes through", async () => {
+    const user = userEvent.setup()
+    const onSubmitInvalid = vi.fn()
+    render(<ProfileForm label="Profile" onSubmitInvalid={onSubmitInvalid} />)
+    await user.click(screen.getByRole("button", { name: "Profile submit" }))
+    await waitFor(() =>
+      expect(document.activeElement).toBe(control("Profile", "name"))
+    )
+    expect(onSubmitInvalid).toHaveBeenCalledTimes(1)
+  })
+
+  test("only the submitted form's field gets focus", async () => {
+    const user = userEvent.setup()
+    render(
+      <>
+        <ProfileForm label="Page" />
+        <div role="dialog">
+          <ProfileForm label="Dialog" />
+        </div>
+      </>
+    )
+    await user.click(screen.getByRole("button", { name: "Page submit" }))
+    await waitFor(() =>
+      expect(document.activeElement).toBe(control("Page", "name"))
+    )
+    // The page form is still invalid, but the dialog's submit must stay in
+    // the dialog.
+    await user.click(screen.getByRole("button", { name: "Dialog submit" }))
+    await waitFor(() =>
+      expect(document.activeElement).toBe(control("Dialog", "name"))
+    )
+  })
+
+  test("works for an external <button form={id}> submit", async () => {
+    const user = userEvent.setup()
+    render(<ProfileForm id="profile-form" label="Profile" outsideSubmit />)
+    await user.click(screen.getByRole("button", { name: "Profile submit" }))
+    await waitFor(() =>
+      expect(document.activeElement).toBe(control("Profile", "name"))
+    )
+  })
+
+  test("a radio group or slider root hands focus to its tabbable child", async () => {
+    const user = userEvent.setup()
+    function Harness({ sliderFirst }: { sliderFirst: boolean }) {
+      const form = useForm({
+        defaultValues: { volume: 10 },
+        onSubmit: vi.fn(),
+        schema: z.object({
+          plan: z.enum(["basic", "pro"]),
+          volume: z.number().min(50),
+        }),
+      })
+      const { RadioGroupField, SliderField, SubmitButton } = form
+      const radio = (
+        <RadioGroupField key="plan" label="Plan" name="plan">
+          <RadioGroupFieldItem value="basic">Basic</RadioGroupFieldItem>
+          <RadioGroupFieldItem value="pro">Pro</RadioGroupFieldItem>
+        </RadioGroupField>
+      )
+      const slider = <SliderField key="volume" label="Volume" name="volume" />
+      return (
+        <FormProvider form={form}>
+          <Form aria-label="Settings">
+            {sliderFirst ? [slider, radio] : [radio, slider]}
+            <SubmitButton>Save</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+
+    const { unmount } = render(<Harness sliderFirst={false} />)
+    await user.click(screen.getByRole("button", { name: "Save" }))
+    await waitFor(() =>
+      expect(document.activeElement?.getAttribute("role")).toBe("radio")
+    )
+    unmount()
+
+    render(<Harness sliderFirst />)
+    await user.click(screen.getByRole("button", { name: "Save" }))
+    await waitFor(() =>
+      expect(document.activeElement?.closest('[data-field="volume"]')).not.toBe(
+        null
+      )
+    )
+  })
+})
+
+describe("fields — data-field and array rows", () => {
+  test("every Field root carries data-field={name}; array rows get the required indicator", () => {
+    const rowsSchema = z.object({
+      email: z.email(),
+      members: z.array(
+        z.object({
+          name: z.string().min(1),
+          note: z.string().optional(),
+        })
+      ),
+    })
+    function Harness() {
+      const form = useForm({
+        defaultValues: { members: [{ name: "" }, { name: "" }] },
+        onSubmit: vi.fn(),
+        schema: rowsSchema,
+      })
+      const { EmailField, InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <EmailField label="Email" name="email" />
+            <InputField label="Row 1 name" name="members[0].name" />
+            <InputField label="Row 2 name" name="members[1].name" />
+            <InputField label="Row 2 note" name="members[1].note" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    const { container } = render(<Harness />)
+    for (const name of [
+      "email",
+      "members[0].name",
+      "members[1].name",
+      "members[1].note",
+    ]) {
+      const root = container.querySelector(`[data-field="${name}"]`)
+      expect(root).not.toBeNull()
+      expect(root?.getAttribute("data-slot")).toBe("field")
+    }
+    const indicator = (label: string) =>
+      screen.getByText(label).querySelector('[data-slot="required-indicator"]')
+    expect(indicator("Row 1 name")).not.toBeNull()
+    expect(indicator("Row 2 name")).not.toBeNull()
+    expect(indicator("Row 2 note")).toBeNull()
+  })
+})

package/src/use-form.reset-defaults.test.tsx

@@ -0,0 +1,125 @@
+import {
+  act,
+  cleanup,
+  render,
+  screen,
+  waitFor,
+} from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(() => {
+  cleanup()
+})
+
+const TITLE = /Title/
+const SAVE = /Save/
+
+const schema = z.object({ title: z.string().min(1) })
+
+type Captured = {
+  isDefaultValue: boolean
+  isDirty: boolean
+  isTouched: boolean
+  values: { title: string }
+}
+
+function EditTitle({
+  capture,
+  record,
+  tick,
+}: {
+  capture: (state: Captured) => void
+  record: { title: string }
+  tick?: number
+}) {
+  const form = useForm({
+    // A fresh literal every render, like most callers write it.
+    defaultValues: { title: record.title },
+    onSubmit: ({ formApi, value }) => {
+      formApi.reset(value)
+    },
+    schema,
+  })
+  const { InputField, SubmitButton } = form
+  capture({
+    isDefaultValue: form.state.isDefaultValue,
+    isDirty: form.state.isDirty,
+    isTouched: form.state.isTouched,
+    values: form.state.values,
+  })
+  return (
+    <FormProvider form={form}>
+      <Form data-tick={tick}>
+        <InputField label="Title" name="title" />
+        <SubmitButton>Save</SubmitButton>
+      </Form>
+    </FormProvider>
+  )
+}
+
+function titleInput() {
+  return screen.getByLabelText(TITLE) as HTMLInputElement
+}
+
+describe("useForm — reset(values) rebases defaults", () => {
+  test("reset after submit sticks across rerenders with fixed defaults", async () => {
+    const user = userEvent.setup()
+    let state: Captured | undefined
+    const capture = vi.fn((next: Captured) => {
+      state = next
+    })
+    const record = { title: "Draft" }
+    const { rerender } = render(<EditTitle capture={capture} record={record} />)
+
+    await user.clear(titleInput())
+    await user.type(titleInput(), "Saved title")
+    await user.click(screen.getByRole("button", { name: SAVE }))
+
+    await waitFor(() => expect(state?.isTouched).toBe(false))
+    for (const tick of [1, 2, 3]) {
+      rerender(<EditTitle capture={capture} record={record} tick={tick} />)
+    }
+    await act(() => Promise.resolve())
+
+    expect(titleInput().value).toBe("Saved title")
+    expect(state?.values).toEqual({ title: "Saved title" })
+    expect(state?.isDefaultValue).toBe(true)
+    expect(state?.isDirty).toBe(false)
+  })
+
+  test("new caller defaults apply while the form is untouched", async () => {
+    let state: Captured | undefined
+    const capture = (next: Captured) => {
+      state = next
+    }
+    const { rerender } = render(
+      <EditTitle capture={capture} record={{ title: "v1" }} />
+    )
+    expect(titleInput().value).toBe("v1")
+
+    rerender(<EditTitle capture={capture} record={{ title: "v2" }} />)
+    await waitFor(() => expect(titleInput().value).toBe("v2"))
+    expect(state?.isDefaultValue).toBe(true)
+  })
+
+  test("new caller defaults are not applied once the form is touched", async () => {
+    const user = userEvent.setup()
+    let state: Captured | undefined
+    const capture = (next: Captured) => {
+      state = next
+    }
+    const { rerender } = render(
+      <EditTitle capture={capture} record={{ title: "v1" }} />
+    )
+    await user.type(titleInput(), " edited")
+
+    rerender(<EditTitle capture={capture} record={{ title: "v2" }} />)
+    await act(() => Promise.resolve())
+
+    expect(titleInput().value).toBe("v1 edited")
+    expect(state?.values).toEqual({ title: "v1 edited" })
+  })
+})

package/src/use-form.test-d.ts

@@ -1,7 +1,6 @@
-import { expectTypeOf, test } from "@zeno-lib/vitest"
+import { expectTypeOf, test } from "vitest"
 import { z } from "zod"
-
-import { useForm } from "./use-form"
+import { useForm } from "./create-form"
 
 const stringSchema = z.object({
   age: z.number(),

package/src/use-form.test.tsx

@@ -1,12 +1,10 @@
-import { afterEach, describe, expect, test, vi } from "@zeno-lib/vitest"
-import { act, cleanup, render, screen } from "@zeno-lib/vitest/testing-library"
-import userEvent from "@zeno-lib/vitest/user-event"
+import { act, cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
 import { useRef } from "react"
+import { afterEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
-
-import { Form, FormProvider } from "./form"
+import { Form, FormProvider, useForm } from "./create-form"
 import { ValidationError } from "./lib/validation-error"
-import { useForm } from "./use-form"
 
 const EMAIL_LABEL = /Email/
 const VALID_EMAIL_MSG = /Enter a valid email/i
@@ -76,7 +74,7 @@ describe("useForm — required indicator", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" />
+            <EmailField label="Email" name="email" />
             <InputField label="Role" name="role" />
           </Form>
         </FormProvider>
@@ -105,7 +103,7 @@ describe("useForm — required indicator", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" />
+            <EmailField label="Email" name="email" />
           </Form>
         </FormProvider>
       )
@@ -134,7 +132,7 @@ describe("useForm — hideFieldErrors", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" />
+            <EmailField label="Email" name="email" />
             <SubmitButton>Submit</SubmitButton>
           </Form>
         </FormProvider>
@@ -164,7 +162,7 @@ describe("useForm — ValidationError from onSubmit", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" />
+            <EmailField label="Email" name="email" />
             <SubmitButton>Submit</SubmitButton>
           </Form>
         </FormProvider>
@@ -195,7 +193,7 @@ describe("useForm — ValidationError from onSubmit", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" />
+            <EmailField label="Email" name="email" />
             <SubmitButton>Submit</SubmitButton>
           </Form>
         </FormProvider>
@@ -224,7 +222,7 @@ describe("useForm — ValidationError from onSubmit", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" />
+            <EmailField label="Email" name="email" />
             <SubmitButton>Submit</SubmitButton>
           </Form>
         </FormProvider>
@@ -247,7 +245,7 @@ describe("useForm — ValidationError from onSubmit", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" />
+            <EmailField label="Email" name="email" />
             <SubmitButton>Submit</SubmitButton>
           </Form>
         </FormProvider>
@@ -275,7 +273,7 @@ describe("useForm — SubmitButton state", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" />
+            <EmailField label="Email" name="email" />
             <SubmitButton>Submit</SubmitButton>
           </Form>
         </FormProvider>

package/src/use-form.unsaved-warning.test.tsx

@@ -1,17 +1,8 @@
-import {
-  afterEach,
-  beforeEach,
-  describe,
-  expect,
-  test,
-  vi,
-} from "@zeno-lib/vitest"
-import { act, cleanup, render, screen } from "@zeno-lib/vitest/testing-library"
-import userEvent from "@zeno-lib/vitest/user-event"
+import { act, cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
-
-import { Form, FormProvider } from "./form"
-import { useForm } from "./use-form"
+import { Form, FormProvider, useForm } from "./create-form"
 
 const NAME_LABEL = /Name/
 

package/src/use-form.validation-modes.test.tsx

@@ -1,11 +1,9 @@
-import { afterEach, describe, expect, test, vi } from "@zeno-lib/vitest"
-import { cleanup, render, screen } from "@zeno-lib/vitest/testing-library"
-import userEvent from "@zeno-lib/vitest/user-event"
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
-
-import { Form, FormProvider } from "./form"
+import { Form, FormProvider, useForm } from "./create-form"
 import type { ValidationMode } from "./lib/validation-modes"
-import { useForm } from "./use-form"
 
 afterEach(() => {
   cleanup()
@@ -25,7 +23,7 @@ function Harness({ mode }: { mode?: ValidationMode }) {
   return (
     <FormProvider form={form}>
       <Form>
-        <EmailField label="Email" />
+        <EmailField label="Email" name="email" />
         <SubmitButton>Submit</SubmitButton>
       </Form>
     </FormProvider>
@@ -133,7 +131,11 @@ describe("per-field validators bypass form-level gating", () => {
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField label="Email" validators={{ onChange: validator }} />
+            <EmailField
+              label="Email"
+              name="email"
+              validators={{ onChange: validator }}
+            />
           </Form>
         </FormProvider>
       )

package/src/form.tsx

@@ -1,105 +0,0 @@
-/* biome-ignore-all lint/performance/noBarrelFile: so consumers depend only on `@zeno-lib/forms`. */
-"use client"
-
-import { type AnyFormApi, createFormHook } from "@tanstack/react-form"
-import type { ComponentProps, FormEvent, ReactNode } from "react"
-
-import { CheckboxField } from "./fields/checkbox-field"
-import { ComboboxField } from "./fields/combobox-field"
-import { DatePickerField } from "./fields/date-picker-field"
-import { EmailField } from "./fields/email-field"
-import { InputField } from "./fields/input-field"
-import { NumberField } from "./fields/number-field"
-import { OtpField } from "./fields/otp-field"
-import { PasswordField } from "./fields/password-field"
-import { RadioGroupField } from "./fields/radio-group-field"
-import { ResetButton } from "./fields/reset-button"
-import { SelectField } from "./fields/select-field"
-import { SliderField } from "./fields/slider-field"
-import { SubmitButton } from "./fields/submit-button"
-import { SwitchField } from "./fields/switch-field"
-import { TextAreaField } from "./fields/textarea-field"
-import {
-  fieldContext,
-  formContext,
-  FormProvider as RawFormProvider,
-  useFormContext,
-} from "./lib/contexts"
-
-export * from "./addons"
-export { RadioGroupFieldItem } from "./fields/radio-group-field"
-export { applyValidationError } from "./lib/apply-validation-error"
-export { useFieldContext, useFormContext } from "./lib/contexts"
-export {
-  RequiredIndicator,
-  type RequiredIndicatorProps,
-} from "./lib/required-indicator"
-export {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "./lib/use-is-invalid"
-export { type FieldMessage, ValidationError } from "./lib/validation-error"
-export { blurThenChangeLogic } from "./lib/validation-logic"
-export type { ValidationMode } from "./lib/validation-modes"
-export { useAppFields } from "./use-app-fields"
-export { useForm } from "./use-form"
-
-const { useAppForm, withFieldGroup, withForm } = createFormHook({
-  fieldComponents: {
-    CheckboxField,
-    ComboboxField,
-    DatePickerField,
-    EmailField,
-    InputField,
-    NumberField,
-    OtpField,
-    PasswordField,
-    RadioGroupField,
-    SelectField,
-    SliderField,
-    SwitchField,
-    TextAreaField,
-  },
-  fieldContext,
-  formComponents: {
-    ResetButton,
-    SubmitButton,
-  },
-  formContext,
-})
-
-export { useAppForm, withFieldGroup, withForm }
-
-type FormProviderProps = {
-  children: ReactNode
-  form: { handleSubmit: () => unknown }
-}
-
-function FormProvider({ children, form }: FormProviderProps) {
-  return (
-    <RawFormProvider value={form as AnyFormApi}>{children}</RawFormProvider>
-  )
-}
-
-type FormProps = Omit<ComponentProps<"form">, "onSubmit">
-
-function Form({ children, className, ...props }: FormProps) {
-  const form = useFormContext()
-  return (
-    <form
-      className={className}
-      noValidate
-      onSubmit={(event: FormEvent<HTMLFormElement>) => {
-        event.preventDefault()
-        event.stopPropagation()
-        Promise.resolve(form.handleSubmit()).catch(() => undefined)
-      }}
-      {...props}
-    >
-      {children}
-    </form>
-  )
-}
-
-export { Form, FormProvider }