@zeno-lib/forms 0.0.0

package/src/use-app-fields.tsx

@@ -0,0 +1,272 @@
+"use client"
+
+import type { DeepKeys } from "@tanstack/react-form"
+import { type ComponentProps, useMemo } from "react"
+
+import { CheckboxField as CheckboxFieldImpl } from "./fields/checkbox-field"
+import { ComboboxField as ComboboxFieldImpl } from "./fields/combobox-field"
+import { DatePickerField as DatePickerFieldImpl } from "./fields/date-picker-field"
+import { EmailField as EmailFieldImpl } from "./fields/email-field"
+import { InputField as InputFieldImpl } from "./fields/input-field"
+import { NumberField as NumberFieldImpl } from "./fields/number-field"
+import { OtpField as OtpFieldImpl } from "./fields/otp-field"
+import { PasswordField as PasswordFieldImpl } from "./fields/password-field"
+import { RadioGroupField as RadioGroupFieldImpl } from "./fields/radio-group-field"
+import { SelectField as SelectFieldImpl } from "./fields/select-field"
+import { SliderField as SliderFieldImpl } from "./fields/slider-field"
+import { SwitchField as SwitchFieldImpl } from "./fields/switch-field"
+import { TextAreaField as TextAreaFieldImpl } from "./fields/textarea-field"
+
+type FormDataOf<F> = F extends { state: { values: infer V } } ? V : never
+
+type AnyAppForm = {
+  AppField: unknown
+  state: { values: unknown }
+}
+
+type WithDefaultName<T, D extends string> =
+  D extends DeepKeys<T> ? { name?: DeepKeys<T> } : { name: DeepKeys<T> }
+
+// Loose validators type for the typed wrappers — name-aware validator typing
+// from TanStack Form would collide with our per-field generics. Callers pass
+// standard schemas (Zod) or functions; both flow through to `<Field>` at
+// runtime unchanged. The structural shape mirrors TanStack's `FieldValidators`
+// slots so prop-name autocomplete still works.
+type AnyFieldValidators = {
+  onMount?: unknown
+  onChange?: unknown
+  onChangeAsync?: unknown
+  onChangeAsyncDebounceMs?: number
+  onBlur?: unknown
+  onBlurAsync?: unknown
+  onBlurAsyncDebounceMs?: number
+  onSubmit?: unknown
+  onSubmitAsync?: unknown
+  onSubmitAsyncDebounceMs?: number
+  onDynamic?: unknown
+  onDynamicAsync?: unknown
+}
+
+// Mirrors TanStack's `FieldListeners`. Same loose-shape rationale as
+// `AnyFieldValidators`: prop-name autocomplete with no per-field generic
+// collisions. Use for cascade patterns where changing one field updates
+// another (`form.setFieldValue(...)` inside `onChange`).
+type AnyFieldListeners = {
+  onChange?: unknown
+  onChangeDebounceMs?: number
+  onBlur?: unknown
+  onBlurDebounceMs?: number
+  onMount?: unknown
+  onSubmit?: unknown
+}
+
+type WithValidators = {
+  validators?: AnyFieldValidators
+  listeners?: AnyFieldListeners
+}
+
+function useAppFields<TForm extends AnyAppForm>(form: TForm) {
+  type T = FormDataOf<TForm>
+
+  return useMemo(() => {
+    const Field = form.AppField as React.ComponentType<{
+      name: string
+      validators?: AnyFieldValidators
+      listeners?: AnyFieldListeners
+      children: () => React.ReactNode
+    }>
+
+    return {
+      CheckboxField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof CheckboxFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <CheckboxFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      ComboboxField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof ComboboxFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <ComboboxFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      DatePickerField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof DatePickerFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <DatePickerFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      EmailField({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof EmailFieldImpl> &
+        WithDefaultName<T, "email"> &
+        WithValidators) {
+        return (
+          <Field
+            listeners={listeners}
+            name={(name ?? "email") as string}
+            validators={validators}
+          >
+            {() => <EmailFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      InputField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof InputFieldImpl> & { name: N } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <InputFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      NumberField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof NumberFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <NumberFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      OtpField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof OtpFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <OtpFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      PasswordField({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof PasswordFieldImpl> &
+        WithDefaultName<T, "password"> &
+        WithValidators) {
+        return (
+          <Field
+            listeners={listeners}
+            name={(name ?? "password") as string}
+            validators={validators}
+          >
+            {() => <PasswordFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      RadioGroupField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof RadioGroupFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <RadioGroupFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      SelectField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof SelectFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <SelectFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      SliderField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof SliderFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <SliderFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      SwitchField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof SwitchFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <SwitchFieldImpl {...props} />}
+          </Field>
+        )
+      },
+      TextAreaField<N extends DeepKeys<T>>({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: ComponentProps<typeof TextAreaFieldImpl> & {
+        name: N
+      } & WithValidators) {
+        return (
+          <Field listeners={listeners} name={name} validators={validators}>
+            {() => <TextAreaFieldImpl {...props} />}
+          </Field>
+        )
+      },
+    }
+  }, [form])
+}
+
+export { useAppFields }

package/src/use-form.cascade.test.tsx

@@ -0,0 +1,83 @@
+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 DIET_LABEL = /Diet/
+const SAUSAGE_LABEL = /Sausage/
+
+afterEach(() => {
+  cleanup()
+})
+
+describe("Field listeners — cascade pattern", () => {
+  test("onChange listener can call form.setFieldValue to update a sibling field", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({
+      diet: z.string().default("none"),
+      sausage: z.string().default("yes"),
+    })
+
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField
+              label="Diet"
+              listeners={{
+                onChange: ({ value }: { value: string }) => {
+                  if (value === "vegan") {
+                    form.setFieldValue("sausage", "no")
+                  }
+                },
+              }}
+              name="diet"
+            />
+            <InputField label="Sausage" name="sausage" />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const diet = screen.getByLabelText(DIET_LABEL) as HTMLInputElement
+    const sausage = screen.getByLabelText(SAUSAGE_LABEL) as HTMLInputElement
+
+    expect(sausage.value).toBe("yes")
+    await user.clear(diet)
+    await user.type(diet, "vegan")
+    expect(sausage.value).toBe("no")
+  })
+
+  test("listener fires per change without triggering the field's own validator", async () => {
+    const user = userEvent.setup()
+    type Values = { diet: string }
+    const listener = vi.fn()
+    function H() {
+      const form = useForm<Values>({
+        defaultValues: { diet: "" },
+        onSubmit: vi.fn(),
+      })
+      const { InputField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField
+              label="Diet"
+              listeners={{ onChange: listener }}
+              name="diet"
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.type(screen.getByLabelText(DIET_LABEL), "abc")
+    // "abc" — three keystrokes → listener fired at least three times.
+    expect(listener.mock.calls.length).toBeGreaterThanOrEqual(3)
+  })
+})

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

@@ -0,0 +1,153 @@
+import { expectTypeOf, test } from "@zeno-lib/vitest"
+import { z } from "zod"
+
+import { useForm } from "./use-form"
+
+const stringSchema = z.object({
+  age: z.number(),
+  email: z.string(),
+  profile: z.object({ nick: z.string() }),
+  tags: z.array(z.string()),
+})
+
+type Schema = z.infer<typeof stringSchema>
+
+test("schema path: defaultValues is PartialFormData (deep partial for plain objects)", () => {
+  // Plain object keys are optional…
+  useForm({
+    defaultValues: { email: "x" },
+    onSubmit: () => undefined,
+    schema: stringSchema,
+  })
+  useForm({
+    defaultValues: {},
+    onSubmit: () => undefined,
+    schema: stringSchema,
+  })
+  // Nested object keys are partial…
+  useForm({
+    defaultValues: { profile: { nick: "x" } },
+    onSubmit: () => undefined,
+    schema: stringSchema,
+  })
+  useForm({
+    defaultValues: { profile: {} },
+    onSubmit: () => undefined,
+    schema: stringSchema,
+  })
+  // Arrays remain atomic (no per-element relaxation).
+  useForm({
+    defaultValues: { tags: ["a", "b"] },
+    onSubmit: () => undefined,
+    schema: stringSchema,
+  })
+  useForm({
+    // @ts-expect-error — array element type still enforced (number ≠ string)
+    defaultValues: { tags: [1] },
+    onSubmit: () => undefined,
+    schema: stringSchema,
+  })
+})
+
+test("schema path: validationLogic is forbidden (type never)", () => {
+  // Error lands on the overall call argument, not on `validationLogic`:
+  // `validationLogic: never` makes the whole options object incompatible.
+  // @ts-expect-error — validationLogic is `never` on the schema path
+  useForm({
+    onSubmit: () => undefined,
+    schema: stringSchema,
+    validationLogic: () => undefined,
+  })
+})
+
+test("schema path: validators rejects the native object shape", () => {
+  // @ts-expect-error — object form is not allowed on the schema path
+  useForm({
+    onSubmit: () => undefined,
+    schema: stringSchema,
+    validators: { onChange: () => undefined },
+  })
+})
+
+test("schema path: validators accepts a ValidationMode string", () => {
+  useForm({
+    onSubmit: () => undefined,
+    schema: stringSchema,
+    validators: "change",
+  })
+  useForm({
+    onSubmit: () => undefined,
+    schema: stringSchema,
+    validators: "blur",
+  })
+  useForm({
+    onSubmit: () => undefined,
+    schema: stringSchema,
+    validators: "submit",
+  })
+  useForm({
+    onSubmit: () => undefined,
+    schema: stringSchema,
+    validators: "blur-then-change",
+  })
+})
+
+test("schema path: validators rejects unknown string values", () => {
+  useForm({
+    onSubmit: () => undefined,
+    schema: stringSchema,
+    // @ts-expect-error — must be a ValidationMode
+    validators: "bogus",
+  })
+})
+
+test("schema path: onSubmit `value` is typed from the schema output", () => {
+  useForm({
+    onSubmit: ({ value }) => {
+      expectTypeOf(value).toEqualTypeOf<Schema>()
+    },
+    schema: stringSchema,
+  })
+})
+
+test("manual path: defaultValues accepts the full TFormData shape", () => {
+  // Note: the wrapper applies `PartialFormData<TFormData>` on both branches
+  // via `ZenoFormExtras`, so omitting keys typechecks here too. This test
+  // documents that the full shape is always accepted; the *required* shape
+  // contract is enforced by TanStack's runtime, not the wrapper's types.
+  useForm<{ a: string; b: number }>({
+    defaultValues: { a: "x", b: 1 },
+    onSubmit: () => undefined,
+  })
+})
+
+test("manual path: validators string requires the schema path", () => {
+  // Supplying a `validators: "change"` string narrows the union to the
+  // schema branch, which then demands `schema`. The error lands on the
+  // overall call (no `schema` provided), not on the `validators` line.
+  // @ts-expect-error — schema becomes required when validators is a string
+  useForm({
+    defaultValues: { a: "" },
+    onSubmit: () => undefined,
+    validators: "change",
+  })
+})
+
+test("manual path: validationLogic is accepted (native function shape)", () => {
+  useForm({
+    defaultValues: { a: "" },
+    onSubmit: () => undefined,
+    validationLogic: () => undefined,
+  })
+})
+
+test("returned form retains the TanStack Form API surface", () => {
+  const form = useForm({
+    onSubmit: () => undefined,
+    schema: stringSchema,
+  })
+  expectTypeOf(form.handleSubmit).toBeFunction()
+  expectTypeOf(form.reset).toBeFunction()
+  expectTypeOf(form.setFieldValue).toBeFunction()
+  expectTypeOf(form.state).not.toBeNever()
+})