@zeno-lib/forms 0.0.1 → 0.2.0

package/src/use-form.tsx

@@ -1,450 +0,0 @@
-"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 }