@zeno-lib/forms 0.0.0

package/src/use-form.tsx

@@ -0,0 +1,450 @@
+"use client"
+
+import type {
+  AnyFormApi,
+  FormAsyncValidateOrFn,
+  FormOptions,
+  FormValidateOrFn,
+} from "@tanstack/react-form"
+import { useMemo } from "react"
+
+import { ResetButton } from "./fields/reset-button"
+import { SubmitButton } from "./fields/submit-button"
+import { useAppForm } from "./form"
+import { applyValidationError } from "./lib/apply-validation-error"
+import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults"
+import { getRequiredPaths } from "./lib/schema-required"
+import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning"
+import { ValidationError } from "./lib/validation-error"
+import { blurThenChangeLogic } from "./lib/validation-logic"
+import {
+  DEFAULT_VALIDATION_MODE,
+  setFormZenoState,
+  type ValidationMode,
+} from "./lib/validation-modes"
+import { useAppFields } from "./use-app-fields"
+
+// Structural shape of a Standard Schema (Zod, Valibot, ArkType, …). Avoids a
+// direct dependency on `@standard-schema/spec`; runtime validation goes
+// through TanStack Form's standard-schema integration unchanged.
+type StandardSchema<T> = {
+  readonly "~standard": {
+    readonly validate: (value: unknown) => unknown
+    readonly types?: { readonly input: T; readonly output: T }
+  }
+}
+
+// Recursive partial that preserves arrays, dates, and other structural types
+// as atomic — only plain object keys become optional. Used to relax
+// `defaultValues` so users can omit fields covered by the schema's
+// `.default(...)` values or by the string/array auto-fill (see
+// `lib/schema-defaults.ts`). `value` on submit is still typed as the full
+// `TFormData` because TanStack's runtime state assertion is unchanged.
+type PartialFormData<T> = T extends readonly unknown[]
+  ? T
+  : T extends Date | RegExp | ((...args: never[]) => unknown)
+    ? T
+    : T extends object
+      ? { [K in keyof T]?: PartialFormData<T[K]> }
+      : T
+
+type ZenoFormExtras<TFormData> = {
+  /**
+   * If `true`, shipped fields skip rendering their inline `<FieldError>`
+   * message. Use it when you collect errors in a single summary somewhere
+   * else (e.g. above the submit button). The fields still flip
+   * `data-invalid` and `aria-invalid`, so invalid styling is preserved.
+   */
+  hideFieldErrors?: boolean
+  /**
+   * Show a `*` next to the label of every field the schema treats as
+   * required. Defaults to `true`. Set to `false` to opt out form-wide.
+   *
+   * Required-ness is detected by probing the schema with an empty object;
+   * fields wrapped in `.optional()`, `.nullable()`, or `.default(…)` are
+   * treated as not required. Async schemas can't be probed and produce no
+   * indicators. Pass `required` directly on a field to override the
+   * schema-derived value.
+   */
+  requiredIndicator?: boolean
+  /**
+   * Warn the user before they navigate away with unsaved changes. Two
+   * trigger modes:
+   *
+   * - `"if-changed"` (recommended) — warn while current values differ
+   *   from defaults (`!state.isDefaultValue`). Clears if the user
+   *   restores the original values, or after `formApi.reset(value)` is
+   *   called post-submit to rebase defaults.
+   * - `"if-touched"` — warn after the user has edited any field, even
+   *   if they reverted (`state.isDirty`, sticky once edited).
+   *
+   * Pass `true` as shorthand for `"if-changed"`. The warning never fires
+   * while the form is mid-submit. Covers full-page navigation only — for
+   * client-side route changes, read the relevant state flag from the
+   * form yourself and prompt before pushing the next route.
+   */
+  unsavedChangesWarning?: boolean | "if-changed" | "if-touched"
+  /**
+   * Initial values for the form fields. Relaxed to a deep partial so you can
+   * omit fields whose defaults come from the schema — `.default(...)` values
+   * flow through, and `z.string()` / `z.array(...)` without a default
+   * initialise to `""` / `[]` to keep inputs controlled. See `lib/schema-defaults.ts`.
+   *
+   * Numbers, booleans, dates, and other domain-loaded types still need an
+   * explicit value here when the schema doesn't provide one.
+   */
+  defaultValues?: PartialFormData<TFormData>
+}
+
+// Schema path — `schema` drives validation. `validators` (if present) is a
+// `ValidationMode` string that selects *when* the schema fires; the matching
+// `validationLogic` is wired internally, so it must not be supplied by the
+// caller. To take manual control of `validators` / `validationLogic`, omit
+// `schema` and use the manual path instead.
+type SchemaPathExtras<TFormData> = {
+  /**
+   * A standard schema (Zod, Valibot, ArkType, …) describing the form data.
+   * Drives validation, default values, the `*` required indicator, and the
+   * `TFormData` type. Pair with `validators` (a `ValidationMode` string)
+   * to control timing.
+   */
+  schema: StandardSchema<TFormData>
+  /**
+   * When the schema runs and when errors are displayed.
+   *
+   * - `'blur-then-change'` (default) — schema runs on blur, then on every
+   *   change for fields that have already been blurred. Errors appear after
+   *   first blur. Calm typing, live corrections.
+   * - `'change'` — schema runs on every keystroke. Errors appear as soon as
+   *   the user starts typing.
+   * - `'blur'` — schema runs only on blur. Errors appear after blur, but
+   *   do not update until the next blur.
+   * - `'submit'` — schema runs only on submit. No errors before submit.
+   */
+  validators?: ValidationMode
+  /**
+   * Not accepted on the schema path — the mode chosen via `validators`
+   * selects the logic internally. Omit `schema` to supply your own.
+   */
+  validationLogic?: never
+}
+
+// Manual path — no schema. `validators` and `validationLogic` keep their
+// native TanStack Form types unchanged.
+type ManualPathExtras = {
+  schema?: never
+}
+
+type SchemaFormOptions<
+  TFormData,
+  TOnMount extends undefined | FormValidateOrFn<TFormData>,
+  TOnChange extends undefined | FormValidateOrFn<TFormData>,
+  TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnBlur extends undefined | FormValidateOrFn<TFormData>,
+  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
+  TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
+  TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta,
+> = Omit<
+  FormOptions<
+    TFormData,
+    TOnMount,
+    TOnChange,
+    TOnChangeAsync,
+    TOnBlur,
+    TOnBlurAsync,
+    TOnSubmit,
+    TOnSubmitAsync,
+    TOnDynamic,
+    TOnDynamicAsync,
+    TOnServer,
+    TSubmitMeta
+  >,
+  "defaultValues" | "validators" | "validationLogic"
+> &
+  SchemaPathExtras<TFormData> &
+  ZenoFormExtras<TFormData>
+
+type ManualFormOptions<
+  TFormData,
+  TOnMount extends undefined | FormValidateOrFn<TFormData>,
+  TOnChange extends undefined | FormValidateOrFn<TFormData>,
+  TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnBlur extends undefined | FormValidateOrFn<TFormData>,
+  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
+  TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
+  TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta,
+> = Omit<
+  FormOptions<
+    TFormData,
+    TOnMount,
+    TOnChange,
+    TOnChangeAsync,
+    TOnBlur,
+    TOnBlurAsync,
+    TOnSubmit,
+    TOnSubmitAsync,
+    TOnDynamic,
+    TOnDynamicAsync,
+    TOnServer,
+    TSubmitMeta
+  >,
+  "defaultValues"
+> &
+  ManualPathExtras &
+  ZenoFormExtras<TFormData>
+
+type UseFormOptions<
+  TFormData,
+  TOnMount extends undefined | FormValidateOrFn<TFormData>,
+  TOnChange extends undefined | FormValidateOrFn<TFormData>,
+  TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnBlur extends undefined | FormValidateOrFn<TFormData>,
+  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
+  TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
+  TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta,
+> =
+  | SchemaFormOptions<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnDynamic,
+      TOnDynamicAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+  | ManualFormOptions<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnDynamic,
+      TOnDynamicAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+
+function buildValidatorsFromSchema<TFormData>(
+  schema: StandardSchema<TFormData>,
+  mode: ValidationMode
+) {
+  switch (mode) {
+    case "change":
+    case "blur-then-change":
+      return { onChange: schema }
+    case "blur":
+      return { onBlur: schema }
+    case "submit":
+      return { onSubmit: schema }
+    default:
+      return { onChange: schema }
+  }
+}
+
+function useForm<
+  TFormData,
+  TOnMount extends undefined | FormValidateOrFn<TFormData> = undefined,
+  TOnChange extends undefined | FormValidateOrFn<TFormData> = undefined,
+  TOnChangeAsync extends
+    | undefined
+    | FormAsyncValidateOrFn<TFormData> = undefined,
+  TOnBlur extends undefined | FormValidateOrFn<TFormData> = undefined,
+  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData> = undefined,
+  TOnSubmit extends undefined | FormValidateOrFn<TFormData> = undefined,
+  TOnSubmitAsync extends
+    | undefined
+    | FormAsyncValidateOrFn<TFormData> = undefined,
+  TOnDynamic extends undefined | FormValidateOrFn<TFormData> = undefined,
+  TOnDynamicAsync extends
+    | undefined
+    | FormAsyncValidateOrFn<TFormData> = undefined,
+  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData> = undefined,
+  TSubmitMeta = never,
+>(
+  options: UseFormOptions<
+    TFormData,
+    TOnMount,
+    TOnChange,
+    TOnChangeAsync,
+    TOnBlur,
+    TOnBlurAsync,
+    TOnSubmit,
+    TOnSubmitAsync,
+    TOnDynamic,
+    TOnDynamicAsync,
+    TOnServer,
+    TSubmitMeta
+  >
+) {
+  type NativeFormOptions = FormOptions<
+    TFormData,
+    TOnMount,
+    TOnChange,
+    TOnChangeAsync,
+    TOnBlur,
+    TOnBlurAsync,
+    TOnSubmit,
+    TOnSubmitAsync,
+    TOnDynamic,
+    TOnDynamicAsync,
+    TOnServer,
+    TSubmitMeta
+  >
+  type NativeValidators = NativeFormOptions["validators"]
+  type NativeValidationLogic = NativeFormOptions["validationLogic"]
+
+  // Loosen the union for a single destructure. We narrow on `schema` below.
+  const {
+    schema,
+    validators: validatorsInput,
+    validationLogic: userValidationLogic,
+    hideFieldErrors = false,
+    requiredIndicator = true,
+    unsavedChangesWarning = false,
+    defaultValues: userDefaultValues,
+    onSubmit: userOnSubmit,
+    ...rest
+  } = options as Omit<NativeFormOptions, "defaultValues"> & {
+    schema?: StandardSchema<TFormData>
+    validators?: ValidationMode | NativeValidators
+    validationLogic?: NativeValidationLogic
+    defaultValues?: PartialFormData<TFormData>
+    hideFieldErrors?: boolean
+    requiredIndicator?: boolean
+    unsavedChangesWarning?: boolean | "if-changed" | "if-touched"
+  }
+
+  let schemaMode: ValidationMode | undefined
+  let resolvedValidators: NativeValidators | undefined
+  let resolvedValidationLogic: NativeValidationLogic | undefined
+
+  if (schema === undefined) {
+    schemaMode = undefined
+    resolvedValidators =
+      typeof validatorsInput === "object" && validatorsInput !== null
+        ? (validatorsInput as NativeValidators)
+        : undefined
+    resolvedValidationLogic = userValidationLogic
+  } else {
+    const mode: ValidationMode =
+      typeof validatorsInput === "string"
+        ? (validatorsInput as ValidationMode)
+        : DEFAULT_VALIDATION_MODE
+    schemaMode = mode
+    resolvedValidators = buildValidatorsFromSchema(
+      schema,
+      mode
+    ) as unknown as NativeValidators
+    resolvedValidationLogic =
+      mode === "blur-then-change"
+        ? (blurThenChangeLogic as unknown as NativeValidationLogic)
+        : undefined
+  }
+
+  const wrappedOnSubmit = userOnSubmit
+    ? ((async (props: { formApi: AnyFormApi; value: TFormData }) => {
+        try {
+          await (
+            userOnSubmit as unknown as (
+              p: typeof props
+            ) => unknown | Promise<unknown>
+          )(props)
+        } catch (error) {
+          if (error instanceof ValidationError) {
+            applyValidationError(props.formApi, error)
+            return
+          }
+          throw error
+        }
+      }) as typeof userOnSubmit)
+    : undefined
+
+  const requiredFields = useMemo(
+    () =>
+      schema && requiredIndicator
+        ? getRequiredPaths(schema as Parameters<typeof getRequiredPaths>[0])
+        : new Set<string>(),
+    [schema, requiredIndicator]
+  )
+
+  const schemaDefaults = useMemo(
+    () =>
+      schema
+        ? extractZodDefaults(schema as Parameters<typeof extractZodDefaults>[0])
+        : undefined,
+    [schema]
+  )
+
+  const mergedDefaultValues = useMemo(
+    () =>
+      schemaDefaults
+        ? (deepMergeDefaults(
+            schemaDefaults,
+            userDefaultValues as Record<string, unknown> | undefined
+          ) as typeof userDefaultValues)
+        : userDefaultValues,
+    [schemaDefaults, userDefaultValues]
+  )
+
+  const form = useAppForm<
+    TFormData,
+    TOnMount,
+    TOnChange,
+    TOnChangeAsync,
+    TOnBlur,
+    TOnBlurAsync,
+    TOnSubmit,
+    TOnSubmitAsync,
+    TOnDynamic,
+    TOnDynamicAsync,
+    TOnServer,
+    TSubmitMeta
+  >({
+    ...rest,
+    ...(mergedDefaultValues === undefined
+      ? {}
+      : { defaultValues: mergedDefaultValues }),
+    ...(wrappedOnSubmit ? { onSubmit: wrappedOnSubmit } : {}),
+    ...(resolvedValidators ? { validators: resolvedValidators } : {}),
+    ...(resolvedValidationLogic
+      ? { validationLogic: resolvedValidationLogic }
+      : {}),
+  } as NativeFormOptions)
+
+  setFormZenoState(form, {
+    hideFieldErrors,
+    requiredFields,
+    requiredIndicator,
+    ...(schemaMode === undefined ? {} : { validation: schemaMode }),
+  })
+
+  useUnsavedChangesWarning(form, unsavedChangesWarning)
+
+  const fields = useAppFields(form)
+  return useMemo(
+    () => Object.assign(form, fields, { ResetButton, SubmitButton }),
+    [form, fields]
+  )
+}
+
+export { useForm }

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

@@ -0,0 +1,192 @@
+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 { z } from "zod"
+
+import { Form, FormProvider } from "./form"
+import { useForm } from "./use-form"
+
+const NAME_LABEL = /Name/
+
+let addSpy: ReturnType<typeof vi.spyOn>
+let removeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  addSpy = vi.spyOn(window, "addEventListener")
+  removeSpy = vi.spyOn(window, "removeEventListener")
+})
+
+afterEach(() => {
+  cleanup()
+  addSpy.mockRestore()
+  removeSpy.mockRestore()
+})
+
+function countBeforeunloadListeners() {
+  const added = addSpy.mock.calls.filter(
+    (call: unknown[]) => call[0] === "beforeunload"
+  ).length
+  const removed = removeSpy.mock.calls.filter(
+    (call: unknown[]) => call[0] === "beforeunload"
+  ).length
+  return added - removed
+}
+
+const schema = z.object({
+  name: z.string(),
+})
+
+describe("useUnsavedChangesWarning — disabled", () => {
+  test("no listener attached when option is false (default)", () => {
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    expect(countBeforeunloadListeners()).toBe(0)
+  })
+})
+
+describe("useUnsavedChangesWarning — 'if-changed' (and `true`)", () => {
+  test("listener attaches once values diverge from defaults", async () => {
+    const user = userEvent.setup()
+    function H() {
+      const form = useForm({
+        onSubmit: vi.fn(),
+        schema,
+        unsavedChangesWarning: "if-changed",
+      })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    expect(countBeforeunloadListeners()).toBe(0)
+    await user.type(screen.getByLabelText(NAME_LABEL), "Alice")
+    expect(countBeforeunloadListeners()).toBe(1)
+  })
+
+  test("`true` is shorthand for 'if-changed'", async () => {
+    const user = userEvent.setup()
+    function H() {
+      const form = useForm({
+        onSubmit: vi.fn(),
+        schema,
+        unsavedChangesWarning: true,
+      })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    expect(countBeforeunloadListeners()).toBe(0)
+    await user.type(screen.getByLabelText(NAME_LABEL), "Alice")
+    expect(countBeforeunloadListeners()).toBe(1)
+  })
+
+  test("listener detaches when value reverts to defaults", async () => {
+    const user = userEvent.setup()
+    function H() {
+      const form = useForm({
+        onSubmit: vi.fn(),
+        schema,
+        unsavedChangesWarning: "if-changed",
+      })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const input = screen.getByLabelText(NAME_LABEL) as HTMLInputElement
+    await user.type(input, "Alice")
+    expect(countBeforeunloadListeners()).toBe(1)
+    await user.clear(input)
+    expect(countBeforeunloadListeners()).toBe(0)
+  })
+})
+
+describe("useUnsavedChangesWarning — 'if-touched'", () => {
+  test("listener attaches on first edit and stays attached after revert", async () => {
+    const user = userEvent.setup()
+    function H() {
+      const form = useForm({
+        onSubmit: vi.fn(),
+        schema,
+        unsavedChangesWarning: "if-touched",
+      })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    expect(countBeforeunloadListeners()).toBe(0)
+    const input = screen.getByLabelText(NAME_LABEL) as HTMLInputElement
+    await user.type(input, "Alice")
+    expect(countBeforeunloadListeners()).toBe(1)
+    // Revert — `if-touched` is sticky once edited.
+    await user.clear(input)
+    expect(countBeforeunloadListeners()).toBe(1)
+  })
+})
+
+describe("useUnsavedChangesWarning — beforeunload event behaviour", () => {
+  test("preventDefault is called and returnValue is set", async () => {
+    const user = userEvent.setup()
+    function H() {
+      const form = useForm({
+        onSubmit: vi.fn(),
+        schema,
+        unsavedChangesWarning: "if-changed",
+      })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.type(screen.getByLabelText(NAME_LABEL), "Alice")
+    const event = new Event("beforeunload", { cancelable: true })
+    act(() => {
+      window.dispatchEvent(event)
+    })
+    expect(event.defaultPrevented).toBe(true)
+  })
+})