@zeno-lib/forms 0.7.1 → 0.9.0

package/src/create-zeno-form.tsx

@@ -3,20 +3,34 @@
 
 import type {
   AnyFormApi,
+  AppFieldExtendedReactFieldGroupApi,
+  AppFieldExtendedReactFormApi,
+  BaseFormOptions,
   DeepKeys,
   DeepValue,
+  FieldsMap,
   FormAsyncValidateOrFn,
   FormOptions,
   FormValidateOrFn,
+  WithFormProps,
 } from "@tanstack/react-form"
 import { createFormHook } from "@tanstack/react-form"
-import { type ComponentProps, type ReactNode, useMemo } from "react"
+import {
+  type ComponentProps,
+  type PropsWithChildren,
+  type ReactNode,
+  useMemo,
+} from "react"
 import { applyValidationError } from "./lib/apply-validation-error"
 import { fieldContext, formContext } from "./lib/contexts"
 import { withDefaultProps } from "./lib/default-props"
 import { withEmptyStartValues } from "./lib/empty-value"
 import { useDisabledOption } from "./lib/form-disabled"
-import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults"
+import {
+  deepMergeDefaults,
+  extractZodDefaults,
+  pickSchemaShape,
+} from "./lib/schema-defaults"
 import {
   getRequiredPaths,
   type StandardSchemaLike,
@@ -390,42 +404,211 @@ export function createZenoForm<
     config.formComponents,
     config.defaultProps
   )
-  const { useAppForm, withFieldGroup, withForm } = createFormHook({
+  const {
+    useAppForm,
+    withFieldGroup: withTanStackFieldGroup,
+    withForm: withTanStackForm,
+  } = createFormHook({
     fieldComponents,
     fieldContext,
     formComponents,
     formContext,
   })
 
-  function useAppFields<TForm extends AnyAppForm>(form: TForm) {
-    type T = FormDataOf<TForm>
-    return useMemo(() => {
-      const Field = form.AppField as React.ComponentType<{
+  // One set of named fields per form, shared by `useForm`, `useAppFields` and
+  // every section and group that renders the form.
+  const fieldsByForm = new WeakMap<object, Record<string, AnyComponent>>()
+
+  function getAppFields<TForm extends AnyAppForm>(form: TForm) {
+    type Fields = FieldWrappers<FC, FormDataOf<TForm>>
+    const cached = fieldsByForm.get(form)
+    if (cached !== undefined) {
+      return cached as Fields
+    }
+    const Field = form.AppField as React.ComponentType<{
+      name: string
+      validators?: AnyFieldValidators
+      listeners?: AnyFieldListeners
+      children: () => ReactNode
+    }>
+    const wrappers: Record<string, AnyComponent> = {}
+    for (const key of Object.keys(fieldComponents)) {
+      const Impl = fieldComponents[key] as AnyComponent
+      wrappers[key] = ({
+        name,
+        validators,
+        listeners,
+        ...props
+      }: {
         name: string
         validators?: AnyFieldValidators
         listeners?: AnyFieldListeners
-        children: () => ReactNode
-      }>
-      const wrappers: Record<string, AnyComponent> = {}
-      for (const key of Object.keys(fieldComponents)) {
-        const Impl = fieldComponents[key] as AnyComponent
-        wrappers[key] = ({
-          name,
-          validators,
-          listeners,
-          ...props
-        }: {
-          name: string
-          validators?: AnyFieldValidators
-          listeners?: AnyFieldListeners
-        }) => (
-          <Field listeners={listeners} name={name} validators={validators}>
-            {() => <Impl {...props} />}
-          </Field>
-        )
+      }) => (
+        <Field listeners={listeners} name={name} validators={validators}>
+          {() => <Impl {...props} />}
+        </Field>
+      )
+    }
+    fieldsByForm.set(form, wrappers)
+    return wrappers as Fields
+  }
+
+  function useAppFields<TForm extends AnyAppForm>(form: TForm) {
+    return getAppFields(form)
+  }
+
+  // Puts the named fields on `target` (a section's form, a group) where it has
+  // none of that name. The same fields every time, so running it on each
+  // render changes nothing after the first.
+  function withNamedFields<T extends AnyAppForm>(target: T): T {
+    for (const [name, field] of Object.entries(getAppFields(target))) {
+      if (!(name in target)) {
+        Object.assign(target, { [name]: field })
       }
-      return wrappers as FieldWrappers<FC, T>
-    }, [form])
+    }
+    return target
+  }
+
+  /**
+   * TanStack's `withForm`, whose `render` gets a `form` carrying the typed
+   * fields, as `useForm`'s does: `<form.InputField name="email" />`.
+   */
+  function withForm<
+    TFormData,
+    TOnMount extends SyncValidator<TFormData>,
+    TOnChange extends SyncValidator<TFormData>,
+    TOnChangeAsync extends AsyncValidator<TFormData>,
+    TOnBlur extends SyncValidator<TFormData>,
+    TOnBlurAsync extends AsyncValidator<TFormData>,
+    TOnSubmit extends SyncValidator<TFormData>,
+    TOnSubmitAsync extends AsyncValidator<TFormData>,
+    TOnDynamic extends SyncValidator<TFormData>,
+    TOnDynamicAsync extends AsyncValidator<TFormData>,
+    TOnServer extends AsyncValidator<TFormData>,
+    TSubmitMeta,
+    // biome-ignore lint/complexity/noBannedTypes: TanStack's own default, so a section without `props` infers as it does.
+    TRenderProps extends object = {},
+  >({
+    render,
+    ...options
+  }: Omit<
+    WithFormProps<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnDynamic,
+      TOnDynamicAsync,
+      TOnServer,
+      TSubmitMeta,
+      FC,
+      FMC,
+      TRenderProps
+    >,
+    "render"
+  > & {
+    render: (
+      props: PropsWithChildren<
+        NoInfer<TRenderProps> & {
+          // The named fields ride in the form components' slot, so the type
+          // stays TanStack's and a nested `withFieldGroup` still infers it.
+          form: AppFieldExtendedReactFormApi<
+            TFormData,
+            TOnMount,
+            TOnChange,
+            TOnChangeAsync,
+            TOnBlur,
+            TOnBlurAsync,
+            TOnSubmit,
+            TOnSubmitAsync,
+            TOnDynamic,
+            TOnDynamicAsync,
+            TOnServer,
+            TSubmitMeta,
+            FC,
+            FMC & FieldWrappers<FC, TFormData>
+          >
+        }
+      >
+    ) => ReactNode
+  }) {
+    return withTanStackForm<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnDynamic,
+      TOnDynamicAsync,
+      TOnServer,
+      TSubmitMeta,
+      TRenderProps
+    >({
+      ...options,
+      render: (props) =>
+        render({
+          ...props,
+          form: withNamedFields(props.form),
+        } as Parameters<typeof render>[0]),
+    })
+  }
+
+  /**
+   * TanStack's `withFieldGroup`, whose `render` gets a `group` carrying the
+   * typed fields of the group's own values, as `useForm`'s form does:
+   * `<group.InputField name="street" />`.
+   */
+  function withFieldGroup<
+    TFieldGroupData,
+    TSubmitMeta,
+    // biome-ignore lint/complexity/noBannedTypes: TanStack's own default, so a group without `props` infers as it does.
+    TRenderProps extends object = {},
+  >({
+    render,
+    ...options
+  }: BaseFormOptions<TFieldGroupData, TSubmitMeta> & {
+    props?: TRenderProps
+    render: (
+      props: PropsWithChildren<
+        NoInfer<TRenderProps> & {
+          // As `withForm`'s, with TanStack's own arguments for the rest.
+          group: AppFieldExtendedReactFieldGroupApi<
+            unknown,
+            TFieldGroupData,
+            string | FieldsMap<unknown, TFieldGroupData>,
+            undefined | FormValidateOrFn<unknown>,
+            undefined | FormValidateOrFn<unknown>,
+            undefined | FormAsyncValidateOrFn<unknown>,
+            undefined | FormValidateOrFn<unknown>,
+            undefined | FormAsyncValidateOrFn<unknown>,
+            undefined | FormValidateOrFn<unknown>,
+            undefined | FormAsyncValidateOrFn<unknown>,
+            undefined | FormValidateOrFn<unknown>,
+            undefined | FormAsyncValidateOrFn<unknown>,
+            undefined | FormAsyncValidateOrFn<unknown>,
+            unknown extends TSubmitMeta ? never : TSubmitMeta,
+            FC,
+            FMC & FieldWrappers<FC, TFieldGroupData>
+          >
+        }
+      >
+    ) => ReactNode
+  }) {
+    return withTanStackFieldGroup<TFieldGroupData, TSubmitMeta, TRenderProps>({
+      ...options,
+      render: (props) =>
+        render({
+          ...props,
+          group: withNamedFields(props.group),
+        } as Parameters<typeof render>[0]),
+    })
   }
 
   // An unset generic defaults to its constraint, which is what TanStack's own
@@ -531,7 +714,17 @@ export function createZenoForm<
 
     const wrappedOnSubmit = userOnSubmit
       ? ((async (props: { formApi: AnyFormApi; value: TFormData }) => {
-          const { submissionAttempts } = props.formApi.state
+          const { formApi } = props
+          const { submissionAttempts } = formApi.state
+          // A reset (a dialog closed meanwhile) or a newer submit while this
+          // one runs makes its failure stale, even once a later submit brings
+          // the count back. An edit doesn't: the save still didn't happen.
+          let superseded = false
+          const watch = formApi.store.subscribe(() => {
+            if (formApi.state.submissionAttempts !== submissionAttempts) {
+              superseded = true
+            }
+          })
           try {
             await (
               userOnSubmit as unknown as (
@@ -540,20 +733,15 @@ export function createZenoForm<
             )(props)
           } catch (error) {
             if (error instanceof ValidationError) {
-              applyValidationError(props.formApi, error)
+              applyValidationError(formApi, error)
               return
             }
-            // Kept for `FormError`, unless an edit, a reset (a dialog closed
-            // meanwhile) or a newer submit came first: then it is about
-            // values no longer on screen.
-            const { state } = props.formApi
-            if (
-              state.values === props.value &&
-              state.submissionAttempts === submissionAttempts
-            ) {
-              setSubmitError(props.formApi, error)
+            if (!superseded) {
+              setSubmitError(formApi, error)
             }
             throw error
+          } finally {
+            watch.unsubscribe()
           }
         }) as typeof userOnSubmit)
       : undefined
@@ -579,15 +767,21 @@ export function createZenoForm<
       [schema]
     )
 
+    // The caller's values keep only the keys the schema describes, so a
+    // record as read (`id`, `createdAt`, …) doesn't fail a `.strict()` schema
+    // on submit. The schema's own defaults then fill the keys left out.
     const mergedDefaultValues = useMemo(
       () =>
         schemaDefaults
           ? (deepMergeDefaults(
               schemaDefaults,
-              userDefaultValues as Record<string, unknown> | undefined
+              pickSchemaShape(
+                schema as Parameters<typeof pickSchemaShape>[0],
+                userDefaultValues as Record<string, unknown> | undefined
+              )
             ) as typeof userDefaultValues)
           : userDefaultValues,
-      [schemaDefaults, userDefaultValues]
+      [schema, schemaDefaults, userDefaultValues]
     )
 
     // Keep `formApi.reset(values)` from being undone by the next render; see
@@ -632,10 +826,9 @@ export function createZenoForm<
     useDisabledOption(form, disabled)
     useUnsavedChangesWarning(form, unsavedChangesWarning)
 
-    const fields = useAppFields(form)
     return useMemo(
-      () => Object.assign(form, fields, formComponents),
-      [form, fields]
+      () => Object.assign(form, getAppFields(form), formComponents),
+      [form]
     )
   }
 

package/src/default-props.test.tsx

@@ -15,7 +15,7 @@ afterEach(() => {
   vi.unstubAllGlobals()
 })
 
-const { useForm } = createZenoForm({
+const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
   defaultProps: {
     FormError: { submitErrorMessage: "Not saved. Try again later." },
     MoneyField: { currency: "CHF", currencyDisplay: "code", placeholder: "0" },
@@ -162,4 +162,28 @@ describe("createZenoForm({ defaultProps })", () => {
     render(<AppFieldHarness />)
     expect(addonOf("Amount")).toBe("CHF")
   })
+
+  test("a section's and a group's fields get their defaults too", () => {
+    const AmountSection = withForm({
+      defaultValues: VALUES,
+      render: ({ form }) => <form.MoneyField label="Amount" name="amount" />,
+    })
+    const FeeGroup = withFieldGroup({
+      defaultValues: { fee: VALUES.fee },
+      render: ({ group }) => <group.MoneyField label="Fee" name="fee" />,
+    })
+    function SectionHarness() {
+      // `useAppForm`'s form has no named fields until a section renders it.
+      const form = useAppForm({ defaultValues: VALUES, onSubmit: vi.fn() })
+      return (
+        <FormProvider form={form}>
+          <AmountSection form={form} />
+          <FeeGroup fields={{ fee: "fee" }} form={form} />
+        </FormProvider>
+      )
+    }
+    render(<SectionHarness />)
+    expect(addonOf("Amount")).toBe("CHF")
+    expect(addonOf("Fee")).toBe("CHF")
+  })
 })

package/src/form-dialog.test.tsx

@@ -178,6 +178,40 @@ describe("FormDialog", () => {
     expect(name.value).toBe("Ada")
   })
 
+  test("an edit opened on a record with keys the schema lacks saves to a .strict() schema", async () => {
+    const user = userEvent.setup()
+    const strictSchema = schema.strict()
+    const record = { ...ROW, createdAt: "2026-01-01", id: 7 }
+    const onSubmit = vi.fn()
+    function StrictHarness() {
+      const dialog = useFormDialog<Values>({ defaultValues: BLANK })
+      const form = useForm({
+        defaultValues: dialog.defaultValues,
+        onSubmit: ({ value }) => onSubmit(value),
+        schema: strictSchema,
+      })
+      const { InputField } = form
+      return (
+        <>
+          <button
+            onClick={() => dialog.open({ defaultValues: record })}
+            type="button"
+          >
+            Edit
+          </button>
+          <FormDialog dialog={dialog} form={form} title="Person">
+            <InputField label="Name" name="name" />
+          </FormDialog>
+        </>
+      )
+    }
+    render(<StrictHarness />)
+    await user.click(screen.getByRole("button", { name: "Edit" }))
+    await screen.findByLabelText(NAME)
+    await user.click(screen.getByRole("button", { name: "Save" }))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledWith(ROW))
+  })
+
   test("closes without asking when nothing changed", async () => {
     const user = userEvent.setup()
     render(<Harness />)

package/src/form-error.test.tsx

@@ -136,6 +136,53 @@ describe("<FormError> with <Form>", () => {
     expect(screen.queryByRole("alert")).toBeNull()
   })
 
+  test("a submit that throws after an edit made while it ran still shows", async () => {
+    const user = userEvent.setup()
+    let rejectSubmit: (error: Error) => void = () => undefined
+    const onSubmit = vi.fn(
+      () =>
+        new Promise((_, reject) => {
+          rejectSubmit = reject
+        })
+    )
+    render(<Profile onSubmit={onSubmit} />)
+    await user.click(screen.getByRole("button", SUBMIT))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+
+    await user.type(screen.getByLabelText(NAME), "!")
+    rejectSubmit(new Error("offline"))
+    expect(await screen.findByRole("alert")).toBeTruthy()
+
+    // The next edit clears it, as after any thrown submit.
+    await user.type(screen.getByLabelText(NAME), "?")
+    expect(screen.queryByRole("alert")).toBeNull()
+  })
+
+  test("a reset while a submit runs drops its error, even after a new submit", async () => {
+    const user = userEvent.setup()
+    let rejectFirst: (error: Error) => void = () => undefined
+    const onSubmit = vi
+      .fn<(values: Values) => unknown>()
+      .mockImplementationOnce(
+        () =>
+          new Promise((_, reject) => {
+            rejectFirst = reject
+          })
+      )
+      .mockImplementationOnce(() => new Promise(() => undefined))
+    render(<Profile onSubmit={onSubmit} />)
+    await user.click(screen.getByRole("button", SUBMIT))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+
+    await user.click(screen.getByRole("button", { name: "Reset" }))
+    // Back to the first submit's attempt count, still running.
+    await user.click(screen.getByRole("button", SUBMIT))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(2))
+    rejectFirst(new Error("offline"))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(screen.queryByRole("alert")).toBeNull()
+  })
+
   test("a reset drops a thrown submit's error, even when it restores the same values", async () => {
     const user = userEvent.setup()
     let resolveRetry: () => void = () => undefined

package/src/lib/schema-defaults.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from "vitest"
 import { z } from "zod"
-import { deepMergeDefaults, extractZodDefaults } from "./schema-defaults"
+import {
+  deepMergeDefaults,
+  extractZodDefaults,
+  pickSchemaShape,
+} from "./schema-defaults"
 
 describe("extractZodDefaults — primitives", () => {
   test("z.string() → ''", () => {
@@ -192,3 +196,126 @@ describe("deepMergeDefaults", () => {
     expect(deepMergeDefaults({ x: { a: 1 } }, { x: null })).toEqual({ x: null })
   })
 })
+
+describe("pickSchemaShape", () => {
+  test("keeps only the keys the schema describes, at every depth", () => {
+    const schema = z
+      .object({
+        address: z.object({ city: z.string() }).strict(),
+        name: z.string(),
+      })
+      .strict()
+    const record = {
+      address: { city: "Geneva", geocodedAt: "2026-01-01" },
+      createdAt: new Date(),
+      id: 7,
+      name: "Ada",
+    }
+    expect(pickSchemaShape(schema, record)).toEqual({
+      address: { city: "Geneva" },
+      name: "Ada",
+    })
+    // The record is copied, never trimmed in place.
+    expect(record).toHaveProperty("id", 7)
+  })
+
+  test("maps an array's element over every row", () => {
+    const schema = z.object({
+      lines: z.array(z.object({ amount: z.number(), label: z.string() })),
+    })
+    expect(
+      pickSchemaShape(schema, {
+        lines: [
+          { amount: 1, id: 10, label: "Design" },
+          { amount: 2, id: 11, label: "Build" },
+        ],
+      })
+    ).toEqual({
+      lines: [
+        { amount: 1, label: "Design" },
+        { amount: 2, label: "Build" },
+      ],
+    })
+  })
+
+  test("unwraps optional, nullable and default, keeping null and absent keys", () => {
+    const address = z.object({ city: z.string() })
+    const schema = z.object({
+      billing: address.nullable(),
+      shipping: address.optional(),
+      tags: z.array(z.object({ label: z.string() })).default([]),
+      work: address.nullable(),
+    })
+    const picked = pickSchemaShape(schema, {
+      billing: null,
+      tags: [{ id: 1, label: "vip" }],
+      work: { city: "Bern", id: 3 },
+    })
+    expect(picked).toEqual({
+      billing: null,
+      tags: [{ label: "vip" }],
+      work: { city: "Bern" },
+    })
+    expect(picked).not.toHaveProperty("shipping")
+  })
+
+  test("reads a pipe or a transform through its input", () => {
+    const schema = z
+      .object({
+        amount: z.string().transform(Number),
+        period: z
+          .object({ from: z.string(), to: z.string() })
+          .transform(({ from, to }) => `${from}/${to}`),
+      })
+      .transform((invoice) => ({ ...invoice, total: invoice.amount }))
+    expect(
+      pickSchemaShape(schema, {
+        amount: "12",
+        id: 4,
+        period: { from: "2026-01", id: 9, to: "2026-02" },
+      })
+    ).toEqual({ amount: "12", period: { from: "2026-01", to: "2026-02" } })
+  })
+
+  test("keeps as is what the schema doesn't describe for certain", () => {
+    const schema = z.object({
+      contact: z.union([
+        z.object({ email: z.string() }),
+        z.object({ phone: z.string() }),
+      ]),
+      extra: z.object({ a: z.string() }).catchall(z.string()),
+      labels: z.record(z.string(), z.object({ text: z.string() })),
+      loose: z.looseObject({ a: z.string() }),
+      meta: z.unknown(),
+      profile: z.object({ nick: z.string() }),
+    })
+    const value = {
+      contact: { email: "ada@example.com", id: 1 },
+      extra: { a: "x", b: "y" },
+      labels: { en: { id: 2, text: "Hello" } },
+      loose: { a: "x", b: "y" },
+      meta: { anything: true },
+      profile: "not an object",
+    }
+    expect(pickSchemaShape(schema, value)).toEqual(value)
+  })
+
+  test("leaves a value alone without a Zod schema", () => {
+    const value = { id: 1, name: "Ada" }
+    expect(
+      pickSchemaShape({} as Parameters<typeof pickSchemaShape>[0], value)
+    ).toBe(value)
+  })
+
+  test("leaves a missing key absent, for the schema default to fill", () => {
+    const schema = z.object({
+      name: z.string(),
+      role: z.string().default("member"),
+    })
+    const picked = pickSchemaShape(schema, { id: 7, name: "Ada" })
+    expect(deepMergeDefaults(extractZodDefaults(schema), picked)).toEqual({
+      name: "Ada",
+      role: "member",
+    })
+  })
+})