@zeno-lib/forms 0.0.0

package/src/lib/validation-logic.ts

@@ -0,0 +1,192 @@
+"use client"
+
+import type { AnyFormApi, ValidationLogicFn } from "@tanstack/react-form"
+
+type Validators = Parameters<ValidationLogicFn>[0]["validators"]
+type RawRunValidation = Parameters<ValidationLogicFn>[0]["runValidation"]
+
+// TanStack Form types `runValidation` and `ValidationLogicFn` as returning
+// `void`, but at runtime `getSyncValidatorArray` does
+// `return options.validationLogic(...)` and forwards whatever
+// `runValidation` returns as the validators array. So we must actually
+// return the value, even though TS says we shouldn't.
+type RunValidation = (
+  props: Parameters<RawRunValidation>[0]
+) => ReturnType<RawRunValidation> & unknown
+
+function pickLiveValidator(validators: Validators, isAsync: boolean) {
+  const fn = isAsync
+    ? (validators?.onChangeAsync ?? validators?.onBlurAsync)
+    : (validators?.onChange ?? validators?.onBlur)
+  return fn ? { cause: "change" as const, fn } : undefined
+}
+
+function shouldRunFormChange(form: AnyFormApi): boolean {
+  if (form.state.submissionAttempts > 0) {
+    return true
+  }
+  // Form-level call: re-validate the whole schema if at least one field has
+  // been blurred. Keeps cross-field checks (password confirmation, dependent
+  // fields) live once the user has committed to editing somewhere.
+  return Object.values(form.state.fieldMeta).some(
+    (meta) => meta?.isBlurred === true
+  )
+}
+
+// Standard cause-matching logic for field-level validators. Per-field
+// `validators={{ onChange, onBlur, … }}` are user-authored opt-ins, so we
+// honour the cause they're declared on directly — no extra gating. Mirrors
+// TanStack Form's `defaultValidationLogic` for the field path.
+function fieldLevelLogic(props: Parameters<ValidationLogicFn>[0]) {
+  const { event, validators, form } = props
+  const run = props.runValidation as RunValidation
+
+  if (!validators) {
+    return run({ form, validators: [] })
+  }
+
+  const isAsync = event.async
+
+  if (event.type === "mount") {
+    return run({
+      form,
+      validators: isAsync
+        ? []
+        : [{ cause: "mount" as const, fn: validators.onMount }],
+    })
+  }
+  if (event.type === "change") {
+    return run({
+      form,
+      validators: [
+        {
+          cause: "change" as const,
+          fn: isAsync ? validators.onChangeAsync : validators.onChange,
+        },
+      ],
+    })
+  }
+  if (event.type === "blur") {
+    return run({
+      form,
+      validators: [
+        {
+          cause: "blur" as const,
+          fn: isAsync ? validators.onBlurAsync : validators.onBlur,
+        },
+      ],
+    })
+  }
+  if (event.type === "submit") {
+    return run({
+      form,
+      validators: [
+        {
+          cause: "change" as const,
+          fn: isAsync ? validators.onChangeAsync : validators.onChange,
+        },
+        {
+          cause: "blur" as const,
+          fn: isAsync ? validators.onBlurAsync : validators.onBlur,
+        },
+        {
+          cause: "submit" as const,
+          fn: isAsync ? validators.onSubmitAsync : validators.onSubmit,
+        },
+      ],
+    })
+  }
+  return run({ form, validators: [] })
+}
+
+function buildSubmitValidators(
+  validators: NonNullable<Validators>,
+  isAsync: boolean,
+  liveValidator: ReturnType<typeof pickLiveValidator>
+) {
+  return [
+    ...(liveValidator ? [liveValidator] : []),
+    {
+      cause: "submit" as const,
+      fn: isAsync ? validators.onSubmitAsync : validators.onSubmit,
+    },
+    ...(isAsync ? [] : [{ cause: "server" as const, fn: () => undefined }]),
+  ]
+}
+
+// Custom validation logic implementing the "blur first, change after" pattern
+// used by `useForm` by default.
+//
+// **Why this exists.** TanStack Form's default logic stores errors per cause:
+// the `onBlur` validator writes to `errorMap.onBlur`, the `onChange` validator
+// writes to `errorMap.onChange`. When both are set to the same schema, blurring
+// with an invalid value populates the blur slot, and a subsequent successful
+// change only clears the change slot — the stale blur error sticks, so the UI
+// keeps showing it even after the value is fixed.
+//
+// **What this does for the form-level schema.** A single user-provided schema
+// (read from `onChange`, or `onBlur` as a fallback) is run on:
+//
+//   - every **blur** event (so empty required fields error on first commit),
+//   - **change** events only after at least one field has been blurred (so
+//     pristine typing stays quiet, but correcting an existing error is live),
+//   - **submit** events.
+//
+// **Per-field validators bypass this gate.** When the user opts into a cause
+// directly via `validators={{ onChange: … }}` on a field, that's an explicit
+// opt-in — we run the matching slot whenever the cause fires, no gating. This
+// preserves "I asked for onChange, I get onChange" intuition.
+//
+// All form-level errors are written to the `change` slot, so there is exactly
+// one place errors live — no per-cause stickiness.
+function blurThenChangeLogicImpl(props: Parameters<ValidationLogicFn>[0]) {
+  // Field-level call (validators are the field's own opt-ins) — pass through
+  // standard cause-matching with no gating.
+  if (props.event.fieldName !== undefined) {
+    return fieldLevelLogic(props)
+  }
+
+  const { event, validators, form } = props
+  const run = props.runValidation as RunValidation
+
+  if (!validators) {
+    return run({ form, validators: [] })
+  }
+
+  const isAsync = event.async
+  const liveValidator = pickLiveValidator(validators, isAsync)
+
+  if (event.type === "mount") {
+    return run({
+      form,
+      validators: isAsync
+        ? []
+        : [{ cause: "mount" as const, fn: validators.onMount }],
+    })
+  }
+  if (event.type === "blur") {
+    return run({
+      form,
+      validators: liveValidator ? [liveValidator] : [],
+    })
+  }
+  if (event.type === "change") {
+    const shouldRun = liveValidator && shouldRunFormChange(form)
+    return run({
+      form,
+      validators: shouldRun ? [liveValidator] : [],
+    })
+  }
+  if (event.type === "submit") {
+    return run({
+      form,
+      validators: buildSubmitValidators(validators, isAsync, liveValidator),
+    })
+  }
+
+  return run({ form, validators: [] })
+}
+
+const blurThenChangeLogic = blurThenChangeLogicImpl as ValidationLogicFn
+
+export { blurThenChangeLogic }

package/src/lib/validation-modes.test-d.ts

@@ -0,0 +1,9 @@
+import { expectTypeOf, test } from "@zeno-lib/vitest"
+
+import type { ValidationMode } from "./validation-modes"
+
+test("ValidationMode is the exact union of the four supported modes", () => {
+  expectTypeOf<ValidationMode>().toEqualTypeOf<
+    "change" | "blur" | "submit" | "blur-then-change"
+  >()
+})

package/src/lib/validation-modes.test.ts

@@ -0,0 +1,72 @@
+import type { AnyFormApi } from "@tanstack/react-form"
+import { describe, expect, test } from "@zeno-lib/vitest"
+
+import {
+  DEFAULT_VALIDATION_MODE,
+  getFormHideFieldErrors,
+  getFormValidationMode,
+  isFieldRequired,
+  setFormZenoState,
+} from "./validation-modes"
+
+function makeFormStub() {
+  return { store: {} } as unknown as AnyFormApi
+}
+
+describe("validation-modes WeakMap state", () => {
+  test("default mode is 'blur-then-change'", () => {
+    expect(DEFAULT_VALIDATION_MODE).toBe("blur-then-change")
+  })
+
+  test("unset form returns default state", () => {
+    const form = makeFormStub()
+    expect(getFormValidationMode(form)).toBe("blur-then-change")
+    expect(getFormHideFieldErrors(form)).toBe(false)
+    expect(isFieldRequired(form, "email")).toBe(false)
+  })
+
+  test("setFormZenoState merges partial updates onto current state", () => {
+    const form = makeFormStub()
+    setFormZenoState(form, { validation: "submit" })
+    expect(getFormValidationMode(form)).toBe("submit")
+    expect(getFormHideFieldErrors(form)).toBe(false)
+
+    setFormZenoState(form, { hideFieldErrors: true })
+    // first partial preserved
+    expect(getFormValidationMode(form)).toBe("submit")
+    expect(getFormHideFieldErrors(form)).toBe(true)
+  })
+
+  test("isFieldRequired honours requiredIndicator flag", () => {
+    const form = makeFormStub()
+    setFormZenoState(form, {
+      requiredFields: new Set(["email"]),
+      requiredIndicator: true,
+    })
+    expect(isFieldRequired(form, "email")).toBe(true)
+    expect(isFieldRequired(form, "password")).toBe(false)
+
+    setFormZenoState(form, { requiredIndicator: false })
+    expect(isFieldRequired(form, "email")).toBe(false)
+  })
+
+  test("two forms keyed on different store references are independent", () => {
+    const a = makeFormStub()
+    const b = makeFormStub()
+    setFormZenoState(a, { validation: "change" })
+    setFormZenoState(b, { validation: "submit" })
+    expect(getFormValidationMode(a)).toBe("change")
+    expect(getFormValidationMode(b)).toBe("submit")
+  })
+
+  test("state is keyed on store, not the form object identity", () => {
+    const store = {}
+    const formA = { store } as unknown as AnyFormApi
+    const formB = { extra: "spread", store } as unknown as AnyFormApi
+    setFormZenoState(formA, { validation: "change" })
+    // Both reach the same WeakMap entry because they share `store` — this
+    // mirrors how TanStack's `useForm` spread differs from the FormApi seen
+    // by child fields.
+    expect(getFormValidationMode(formB)).toBe("change")
+  })
+})

package/src/lib/validation-modes.ts

@@ -0,0 +1,73 @@
+"use client"
+
+import type { AnyFormApi } from "@tanstack/react-form"
+
+type ValidationMode = "change" | "blur" | "submit" | "blur-then-change"
+
+const DEFAULT_VALIDATION_MODE: ValidationMode = "blur-then-change"
+
+type ZenoFormState = {
+  validation: ValidationMode
+  hideFieldErrors: boolean
+  requiredIndicator: boolean
+  requiredFields: ReadonlySet<string>
+}
+
+const EMPTY_REQUIRED_FIELDS: ReadonlySet<string> = new Set<string>()
+
+const DEFAULT_FORM_STATE: ZenoFormState = {
+  hideFieldErrors: false,
+  requiredFields: EMPTY_REQUIRED_FIELDS,
+  requiredIndicator: true,
+  validation: DEFAULT_VALIDATION_MODE,
+}
+
+// Per-form Zeno-specific state. Keyed by `form.store` rather than the form
+// object: TanStack Form's `useForm` returns a spread `{ ...formApi, ... }`
+// whose identity differs from the underlying `formApi` that fields receive
+// via `field.form`. The `store` instance is set in the FormApi constructor
+// and survives the spread, so it's the only reference shared by both the
+// caller of `useForm` and every child field.
+const formZenoState = new WeakMap<object, ZenoFormState>()
+
+function stateKey(form: AnyFormApi): object {
+  return (form as { store: object }).store
+}
+
+function setFormZenoState(
+  form: AnyFormApi,
+  state: Partial<ZenoFormState>
+): void {
+  const key = stateKey(form)
+  const current = formZenoState.get(key) ?? DEFAULT_FORM_STATE
+  formZenoState.set(key, { ...current, ...state })
+}
+
+function getFormZenoState(form: AnyFormApi): ZenoFormState {
+  return formZenoState.get(stateKey(form)) ?? DEFAULT_FORM_STATE
+}
+
+function getFormValidationMode(form: AnyFormApi): ValidationMode {
+  return getFormZenoState(form).validation
+}
+
+function getFormHideFieldErrors(form: AnyFormApi): boolean {
+  return getFormZenoState(form).hideFieldErrors
+}
+
+function isFieldRequired(form: AnyFormApi, name: string): boolean {
+  const state = getFormZenoState(form)
+  if (!state.requiredIndicator) {
+    return false
+  }
+  return state.requiredFields.has(name)
+}
+
+export {
+  DEFAULT_VALIDATION_MODE,
+  getFormHideFieldErrors,
+  getFormValidationMode,
+  isFieldRequired,
+  setFormZenoState,
+  type ValidationMode,
+}

package/src/tanstack.ts

@@ -0,0 +1,2 @@
+/** biome-ignore-all lint/performance/noBarrelFile: re-exporting for convenience */
+export * from "@tanstack/react-form"

package/src/use-app-fields.test-d.ts

@@ -0,0 +1,112 @@
+import { test } from "@zeno-lib/vitest"
+import { z } from "zod"
+
+import { useForm } from "./use-form"
+
+const schema = z.object({
+  accept: z.boolean(),
+  age: z.number(),
+  bio: z.string(),
+  email: z.string(),
+  notes: z.string(),
+  password: z.string(),
+  profile: z.object({ nick: z.string() }),
+  size: z.string(),
+})
+
+const schemaNoEmail = z.object({
+  contact: z.string(),
+})
+
+test("InputField.name is constrained to DeepKeys<T>", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  const { InputField } = form
+  InputField({ name: "email" })
+  InputField({ name: "profile.nick" })
+  // @ts-expect-error — not a valid path
+  InputField({ name: "nonexistent" })
+  // @ts-expect-error — wrong nested path
+  InputField({ name: "profile.unknown" })
+})
+
+test("NumberField.name is constrained to DeepKeys<T>", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  form.NumberField({ name: "age" })
+  // @ts-expect-error — not a valid path
+  form.NumberField({ name: "nonexistent" })
+})
+
+test("CheckboxField.name is constrained to DeepKeys<T>", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  form.CheckboxField({ name: "accept" })
+  // @ts-expect-error — not a valid path
+  form.CheckboxField({ name: "nonexistent" })
+})
+
+test("SelectField.name is constrained to DeepKeys<T>", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  form.SelectField({ children: null, name: "size" })
+  // @ts-expect-error — not a valid path
+  form.SelectField({ children: null, name: "nonexistent" })
+})
+
+test("TextAreaField.name is constrained to DeepKeys<T>", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  form.TextAreaField({ name: "notes" })
+  // @ts-expect-error — not a valid path
+  form.TextAreaField({ name: "nonexistent" })
+})
+
+test("EmailField.name is optional when T has an `email` field", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  const { EmailField } = form
+  // No `name` required.
+  EmailField({})
+  EmailField({ label: "Email" })
+  EmailField({ name: "email" })
+})
+
+test("EmailField.name is required when T has no `email` field", () => {
+  const form = useForm({ onSubmit: () => undefined, schema: schemaNoEmail })
+  // @ts-expect-error — name becomes required without an "email" key on T
+  form.EmailField({})
+  form.EmailField({ name: "contact" })
+})
+
+test("PasswordField.name is optional when T has a `password` field", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  const { PasswordField } = form
+  PasswordField({})
+  PasswordField({ name: "password" })
+})
+
+test("PasswordField.name is required when T has no `password` field", () => {
+  const form = useForm({ onSubmit: () => undefined, schema: schemaNoEmail })
+  // @ts-expect-error — name becomes required without a "password" key on T
+  form.PasswordField({})
+  form.PasswordField({ name: "contact" })
+})
+
+test("validators prop is accepted on every field wrapper", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  form.InputField({
+    name: "email",
+    validators: {
+      onChange: () => undefined,
+      onChangeAsyncDebounceMs: 300,
+    },
+  })
+  form.SelectField({
+    children: null,
+    name: "size",
+    validators: { onBlur: () => undefined },
+  })
+})
+
+test("listeners prop is accepted on every field wrapper", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  form.InputField({
+    listeners: { onChange: () => undefined, onChangeDebounceMs: 50 },
+    name: "email",
+  })
+})

package/src/use-app-fields.test.tsx

@@ -0,0 +1,163 @@
+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 { z } from "zod"
+
+import { Form, FormProvider } from "./form"
+import { useForm } from "./use-form"
+
+const EMAIL_LABEL = /Email/
+const CONTACT_EMAIL_LABEL = /Contact email/
+const PASSWORD_LABEL = /Password/
+const NAME_LABEL = /Name/
+const ACCEPT_NAME = /Accept/
+
+afterEach(() => {
+  cleanup()
+})
+
+describe("EmailField / PasswordField — default name", () => {
+  test("EmailField with no `name` renders an input with id='email'", () => {
+    const schema = z.object({ email: z.email() })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { EmailField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <EmailField label="Email" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const input = screen.getByLabelText(EMAIL_LABEL) as HTMLInputElement
+    expect(input.id).toBe("email")
+    expect(input.name).toBe("email")
+    expect(input.type).toBe("email")
+  })
+
+  test("EmailField with an explicit `name` binds to that field", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ contactEmail: z.email() })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { EmailField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <EmailField label="Contact email" name="contactEmail" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const input = screen.getByLabelText(CONTACT_EMAIL_LABEL) as HTMLInputElement
+    expect(input.id).toBe("contactEmail")
+    expect(input.name).toBe("contactEmail")
+    await user.type(input, "u@example.com")
+    expect(input.value).toBe("u@example.com")
+  })
+
+  test("PasswordField with no `name` renders an input with id='password'", () => {
+    const schema = z.object({
+      email: z.email(),
+      password: z.string().min(1),
+    })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { EmailField, PasswordField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <EmailField />
+            <PasswordField label="Password" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const input = screen.getByLabelText(PASSWORD_LABEL) as HTMLInputElement
+    expect(input.id).toBe("password")
+    expect(input.name).toBe("password")
+    expect(input.type).toBe("password")
+  })
+})
+
+describe("validators & listeners props forward into the underlying AppField", () => {
+  test("InputField forwards validators (runs on user input)", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ name: z.string() })
+    const validator = vi.fn(() => undefined)
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField
+              label="Name"
+              name="name"
+              validators={{ onChange: validator }}
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.type(screen.getByLabelText(NAME_LABEL), "Alice")
+    expect(validator).toHaveBeenCalled()
+  })
+
+  test("InputField forwards listeners (fires on user input)", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ name: z.string() })
+    const listener = vi.fn()
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField
+              label="Name"
+              listeners={{ onChange: listener }}
+              name="name"
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.type(screen.getByLabelText(NAME_LABEL), "Bob")
+    expect(listener).toHaveBeenCalled()
+  })
+})
+
+describe("CheckboxField — boolean state wrapper", () => {
+  test("binds boolean state and reflects toggle clicks", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ accept: z.boolean() })
+    function H() {
+      const form = useForm({
+        defaultValues: { accept: false },
+        onSubmit: vi.fn(),
+        schema,
+      })
+      const { CheckboxField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <CheckboxField label="Accept" name="accept" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    // BaseUI renders the checkbox as a <button role="checkbox">.
+    const checkbox = screen.getByRole("checkbox", { name: ACCEPT_NAME })
+    expect(checkbox.getAttribute("aria-checked")).toBe("false")
+    await user.click(checkbox)
+    expect(checkbox.getAttribute("aria-checked")).toBe("true")
+  })
+})