@zeno-lib/forms 0.5.0 → 0.6.0

package/dist/create-zeno-form.d.mts

@@ -1,5 +1,6 @@
+import { FieldControlProps } from "./lib/use-field-control.mjs";
 import { ValidationMode } from "./lib/validation-modes.mjs";
-import { DeepKeys, FormAsyncValidateOrFn, FormOptions, FormValidateOrFn } from "@tanstack/react-form";
+import { DeepKeys, DeepValue, FormAsyncValidateOrFn, FormOptions, FormValidateOrFn } from "@tanstack/react-form";
 import { ComponentProps, ReactNode } from "react";
 //#region src/create-zeno-form.d.ts
 type StandardSchema<T> = {
@@ -84,7 +85,12 @@ type WithValidators = {
   listeners?: AnyFieldListeners;
 };
 type AnyComponent = React.ComponentType<any>;
-type FieldWrappers<FC extends Record<string, AnyComponent>, T> = { [K in keyof FC]: <N extends DeepKeys<T>>(props: ComponentProps<FC[K]> & {
+type WithControlValue<P, V> = P extends {
+  render: (control: infer C) => ReactNode;
+} ? [C] extends [FieldControlProps<any>] ? Omit<P, "render"> & {
+  render: (control: FieldControlProps<V>) => ReactNode;
+} : P : P;
+type FieldWrappers<FC extends Record<string, AnyComponent>, T> = { [K in keyof FC]: <N extends DeepKeys<T>>(props: WithControlValue<ComponentProps<FC[K]>, DeepValue<T, N>> & {
   name: N;
 } & WithValidators) => ReactNode; };
 type CreateZenoFormConfig<FC extends Record<string, AnyComponent>, FMC extends Record<string, AnyComponent>> = {

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { FieldControl, FieldControlProps, UseFieldControlOptions, useFieldControl } from "./lib/use-field-control.mjs";
 import { ValidationMode } from "./lib/validation-modes.mjs";
 import { createZenoForm } from "./create-zeno-form.mjs";
 import { Form, FormProvider } from "./form-element.mjs";
@@ -9,4 +10,4 @@ import { SubmitActionOptions, SubmitActionSchema, applyActionError, submitAction
 import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./lib/use-is-invalid.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
 import { useSelector } from "@tanstack/react-form";
-export { type ActionError, type ActionIssue, type ActionResult, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };
+export { type ActionError, type ActionIssue, type ActionResult, type FieldControl, type FieldControlProps, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, type UseFieldControlOptions, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFieldControl, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };

package/dist/index.mjs

@@ -7,5 +7,6 @@ import { createZenoForm } from "./create-zeno-form.mjs";
 import { Form, FormProvider } from "./form-element.mjs";
 import { applyActionError, submitAction } from "./lib/submit-action.mjs";
 import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./lib/use-is-invalid.mjs";
+import { useFieldControl } from "./lib/use-field-control.mjs";
 import { useSelector } from "@tanstack/react-form";
-export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };
+export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFieldControl, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };

package/dist/lib/submit-action.d.mts

@@ -40,7 +40,9 @@ type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<TV
   /**
    * Parsed on the client before the call: `onSubmit` receives the form's
    * input values, and the action gets the schema's output. A failure is
-   * applied to the form and the action is never called.
+   * applied to the form and the action is never called. Replaces the form's
+   * own `schema` for this call; pass one only when the action takes a
+   * different schema than the form.
    */
   schema: SubmitActionSchema<TOutput>;
 };
@@ -49,9 +51,13 @@ type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<TV
  * form. Pass `onSubmit`'s own argument straight through:
  *
  * ```ts
- * onSubmit: (submit) => submitAction(submit, saveProfile, { reset: true, schema })
+ * onSubmit: (submit) => submitAction(submit, saveProfile, { reset: true })
  * ```
  *
+ * The values are parsed with `options.schema`, else with the form's own
+ * `useForm({ schema })`, and the action gets the schema's output. A form with
+ * no schema (`useForm` without one, `useAppForm`) sends its values as they are.
+ *
  * On `{ ok: false }` the field errors land on their fields (array paths like
  * `owners[0].percentage` included) and clear as each field is edited. On
  * `{ ok: true }` the form is optionally reset. Either way the result is

package/dist/lib/submit-action.mjs

@@ -1,5 +1,6 @@
 import { applyValidationError } from "./apply-validation-error.mjs";
 import { toActionError } from "./action-result.mjs";
+import { getFormSchema } from "./validation-modes.mjs";
 import { ValidationError } from "./validation-error.mjs";
 //#region src/lib/submit-action.ts
 function applyActionError(formApi, error) {
@@ -15,9 +16,10 @@ function applyActionError(formApi, error) {
 }
 async function submitAction(props, action, options = {}) {
 	const { formApi, value } = props;
+	const schema = options.schema ?? getFormSchema(formApi);
 	let input = value;
-	if (options.schema) {
-		const parsed = await options.schema["~standard"].validate(value);
+	if (schema) {
+		const parsed = await schema["~standard"].validate(value);
 		if (parsed.issues) {
 			const error = toActionError(parsed.issues);
 			applyActionError(formApi, error);

package/dist/lib/use-field-control.d.mts

@@ -0,0 +1,76 @@
+import { AnyFieldMeta } from "@tanstack/react-form";
+import { ReactNode } from "react";
+//#region src/lib/use-field-control.d.ts
+type UseFieldControlOptions = {
+  /**
+   * The description the field renders, if any. The control is described by
+   * it, and by the error while one shows.
+   */
+  description?: ReactNode;
+  disabled?: boolean;
+  /**
+   * The label the field renders, if any. The control gets `aria-labelledby`,
+   * which names a control a `<label htmlFor>` can't, such as a
+   * `role="radiogroup"`.
+   */
+  label?: ReactNode;
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
+  required?: boolean;
+};
+/** The props that bind a control to its field. Spread them on the control. */
+type FieldControlProps<TValue = unknown> = {
+  "aria-describedby": string | undefined;
+  "aria-invalid": true | undefined;
+  "aria-labelledby": string | undefined;
+  "aria-required": true | undefined;
+  disabled: boolean | undefined;
+  id: string;
+  name: string;
+  /** Marks the field touched. */
+  onBlur: () => void;
+  /**
+   * Stores `value`, not a change event: a control that reports one maps it
+   * (`onChange(event.target.value)`). An empty value (`null`, `undefined`,
+   * `""`, `NaN` or `[]`) stores the field's empty value instead, which its
+   * schema picks. Stable across renders.
+   */
+  onChange: (value: TValue) => void;
+  /**
+   * The value as stored, the field's empty value (`undefined` or `null`)
+   * included. A control that needs a defined value maps it
+   * (`value={value ?? ""}`), or it turns uncontrolled once the field empties.
+   */
+  value: TValue;
+};
+type FieldControl<TValue = unknown> = {
+  controlProps: FieldControlProps<TValue>;
+  descriptionId: string;
+  errorId: string;
+  /**
+   * The errors to render: none while the field's errors are hidden, by the
+   * form's validation mode or `hideFieldErrors`.
+   */
+  errors: AnyFieldMeta["errors"];
+  /** The control's id, for the label's `htmlFor`. */
+  id: string;
+  isInvalid: boolean;
+  /** The field requires a value, by the schema or `required`. */
+  isRequired: boolean;
+  /** The label's id, when `label` is passed. */
+  labelId: string | undefined;
+  name: string;
+  /** Show the `*`: as `isRequired`, but off under `requiredIndicator: false`. */
+  showRequiredIndicator: boolean;
+};
+/**
+ * Everything a control needs to act as a field of the form, inside a field
+ * component the form renders (`form.AppField`, or one registered with
+ * `createZenoForm`): the props to spread on the control, and the ids and
+ * state its label, description and error need.
+ */
+declare function useFieldControl<TValue = unknown>({ description, disabled, label, required }?: UseFieldControlOptions): FieldControl<TValue>;
+//#endregion
+export { type FieldControl, type FieldControlProps, type UseFieldControlOptions, useFieldControl };

package/dist/lib/use-field-control.mjs

@@ -0,0 +1,67 @@
+"use client";
+import { useFieldContext } from "./contexts.mjs";
+import { getFormSchema } from "./validation-modes.mjs";
+import { emptyValueFor } from "./empty-value.mjs";
+import { describedBy } from "./aria.mjs";
+import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./use-is-invalid.mjs";
+import { useCallback, useId } from "react";
+//#region src/lib/use-field-control.ts
+function isEmpty(value) {
+	return value === null || value === void 0 || value === "" || Number.isNaN(value) || Array.isArray(value) && value.length === 0;
+}
+function isSyntheticEvent(value) {
+	return typeof value === "object" && value !== null && "nativeEvent" in value && "target" in value;
+}
+/**
+* Everything a control needs to act as a field of the form, inside a field
+* component the form renders (`form.AppField`, or one registered with
+* `createZenoForm`): the props to spread on the control, and the ids and
+* state its label, description and error need.
+*/
+function useFieldControl({ description, disabled, label, required } = {}) {
+	const field = useFieldContext();
+	const id = useId();
+	const labelId = label ? `${id}-label` : void 0;
+	const descriptionId = `${id}-description`;
+	const errorId = `${id}-error`;
+	const isInvalid = useIsInvalid(field);
+	const hideErrors = useHideFieldErrors(field);
+	const showError = isInvalid && !hideErrors;
+	const schemaRequired = useIsFieldRequired(field);
+	const schemaRequiresValue = useIsFieldRequiredBySchema(field);
+	const isRequired = required ?? schemaRequiresValue;
+	const { form, handleBlur, handleChange, name } = field;
+	const onChange = useCallback((value) => {
+		if (isSyntheticEvent(value)) throw new TypeError(`Field "${name}" got a change event, not a value. Map it in the control: onChange(event.target.value).`);
+		handleChange(isEmpty(value) ? emptyValueFor(getFormSchema(form), form.state.values, name, value) : value);
+	}, [
+		form,
+		handleChange,
+		name
+	]);
+	return {
+		controlProps: {
+			"aria-describedby": describedBy([description, descriptionId], [showError, errorId]),
+			"aria-invalid": isInvalid || void 0,
+			"aria-labelledby": labelId,
+			"aria-required": isRequired || void 0,
+			disabled,
+			id,
+			name,
+			onBlur: handleBlur,
+			onChange,
+			value: field.state.value
+		},
+		descriptionId,
+		errorId,
+		errors: showError ? field.state.meta.errors : [],
+		id,
+		isInvalid,
+		isRequired,
+		labelId,
+		name,
+		showRequiredIndicator: required ?? schemaRequired
+	};
+}
+//#endregion
+export { useFieldControl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "repository": {
     "url": "https://github.com/zeno-lib/zeno.git",
     "directory": "packages/forms"

package/src/control-field.test.tsx

@@ -0,0 +1,338 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import type { ComponentProps } from "react"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(() => {
+  cleanup()
+})
+
+const PHONE = /Phone/
+const SUBMIT = { name: "Submit" }
+
+// A control a `<label htmlFor>` can't name: only `aria-labelledby` does.
+function StarRating({
+  disabled,
+  name: _name,
+  onChange,
+  value,
+  ...props
+}: Omit<ComponentProps<"div">, "onChange"> & {
+  disabled?: boolean
+  name?: string
+  onChange: (value: number) => void
+  value?: number | null
+}) {
+  return (
+    <div role="radiogroup" {...props}>
+      {[1, 2, 3].map((star) => (
+        // biome-ignore lint/a11y/useSemanticElements: a custom radio group, as a star rating draws one.
+        <button
+          aria-checked={value === star}
+          disabled={disabled}
+          key={star}
+          onClick={() => onChange(star)}
+          role="radio"
+          type="button"
+        >
+          {star}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+// A text control that reports its value, not a change event.
+function PhoneInput({
+  onChange,
+  ...props
+}: Omit<ComponentProps<"input">, "onChange" | "value"> & {
+  onChange: (value: string) => void
+  value: string
+}) {
+  return (
+    <input
+      {...props}
+      onChange={(event) => onChange(event.target.value)}
+      type="tel"
+    />
+  )
+}
+
+describe("ControlField", () => {
+  test("names and describes its control, and flags it once invalid", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ rating: z.number("Rate it") })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { ControlField, SubmitButton } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              description="Out of three."
+              label="Rating"
+              name="rating"
+              render={(control) => <StarRating {...control} />}
+            />
+            <SubmitButton>Submit</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+    const { container } = render(<H />)
+    const group = screen.getByRole("radiogroup", { name: "Rating" })
+    const description = screen.getByText("Out of three.")
+    expect(group.getAttribute("aria-describedby")).toBe(description.id)
+    expect(group.hasAttribute("aria-invalid")).toBe(false)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+    const error = await screen.findByRole("alert")
+    expect(error.textContent).toBe("Rate it")
+    expect(group.getAttribute("aria-invalid")).toBe("true")
+    expect(group.getAttribute("aria-describedby")).toBe(
+      `${description.id} ${error.id}`
+    )
+    expect(
+      container
+        .querySelector('[data-field="rating"]')
+        ?.getAttribute("data-invalid")
+    ).toBe("true")
+
+    await user.click(screen.getByRole("radio", { name: "2" }))
+    expect(screen.queryByRole("alert")).toBeNull()
+    expect(group.hasAttribute("aria-invalid")).toBe(false)
+  })
+
+  test("marks the field touched on blur, so its error shows", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ phone: z.string().min(1, "Enter a phone") })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={(control) => <PhoneInput {...control} />}
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByLabelText(PHONE))
+    expect(screen.queryByRole("alert")).toBeNull()
+    await user.tab()
+    expect((await screen.findByRole("alert")).textContent).toBe("Enter a phone")
+  })
+
+  test("takes required from the schema unless `required` says otherwise", () => {
+    const schema = z.object({
+      forced: z.string().optional(),
+      kept: z.string().min(1),
+      lifted: z.string().min(1),
+      open: z.string().optional(),
+    })
+    const FIELDS = [
+      { name: "kept" },
+      { name: "open" },
+      { name: "forced", required: true },
+      { name: "lifted", required: false },
+    ] as const
+    function H({ requiredIndicator }: { requiredIndicator: boolean }) {
+      const form = useForm({ onSubmit: vi.fn(), requiredIndicator, schema })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            {FIELDS.map((props) => (
+              <ControlField
+                key={props.name}
+                label={props.name}
+                render={(control) => (
+                  <PhoneInput {...control} value={control.value ?? ""} />
+                )}
+                {...props}
+              />
+            ))}
+          </Form>
+        </FormProvider>
+      )
+    }
+    for (const requiredIndicator of [true, false]) {
+      const { container, unmount } = render(
+        <H requiredIndicator={requiredIndicator} />
+      )
+      const required = screen
+        .getAllByRole("textbox")
+        .filter((input) => input.getAttribute("aria-required") === "true")
+        .map((input) => input.getAttribute("name"))
+      expect(required).toEqual(["kept", "forced"])
+      // `required` overrides `requiredIndicator: false` too.
+      expect(
+        container.querySelectorAll('[data-slot="required-indicator"]')
+      ).toHaveLength(requiredIndicator ? 2 : 1)
+      unmount()
+    }
+  })
+
+  test("clearing stores the value the schema accepts as empty", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({
+      count: z.number().nullable(),
+      nullable: z.string().min(1).nullable(),
+      optional: z.string().min(1).optional(),
+      tags: z.array(z.string()),
+      text: z.string(),
+    })
+    const captured: { values?: unknown } = {}
+    function H() {
+      const form = useForm({
+        defaultValues: {
+          count: 1,
+          nullable: "a",
+          optional: "b",
+          tags: ["c"],
+          text: "d",
+        },
+        onSubmit: vi.fn(),
+        schema,
+      })
+      const { ControlField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            {(["nullable", "optional", "text"] as const).map((name) => (
+              <ControlField
+                key={name}
+                label={name}
+                name={name}
+                render={(control) => (
+                  <PhoneInput {...control} value={control.value ?? ""} />
+                )}
+              />
+            ))}
+            <ControlField
+              label="Tags"
+              name="tags"
+              render={({ onChange }) => (
+                <button onClick={() => onChange([])} type="button">
+                  Clear tags
+                </button>
+              )}
+            />
+            {/* A number control reports `NaN` once cleared. */}
+            <ControlField
+              label="Count"
+              name="count"
+              render={({ onChange }) => (
+                <button onClick={() => onChange(Number.NaN)} type="button">
+                  Clear count
+                </button>
+              )}
+            />
+            <Subscribe selector={(state) => state.values}>
+              {(values) => {
+                captured.values = values
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.clear(screen.getByLabelText("nullable"))
+    await user.clear(screen.getByLabelText("optional"))
+    await user.clear(screen.getByLabelText("text"))
+    await user.click(screen.getByRole("button", { name: "Clear tags" }))
+    await user.click(screen.getByRole("button", { name: "Clear count" }))
+    expect(captured.values).toStrictEqual({
+      count: null,
+      nullable: null,
+      optional: undefined,
+      tags: [],
+      text: "",
+    })
+    expect(schema.safeParse(captured.values).success).toBe(true)
+  })
+
+  test("keeps one `onChange` across renders, so a control can memoize on it", async () => {
+    const user = userEvent.setup()
+    const handlers = new Set<unknown>()
+    function H() {
+      const form = useForm({ defaultValues: { phone: "" }, onSubmit: vi.fn() })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={(control) => {
+                handlers.add(control.onChange)
+                return <PhoneInput {...control} />
+              }}
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.type(screen.getByLabelText(PHONE), "079")
+    expect(handlers.size).toBe(1)
+  })
+
+  test("refuses a change event, rather than storing it", async () => {
+    const user = userEvent.setup()
+    const errors: unknown[] = []
+    const onError = (event: ErrorEvent) => {
+      event.preventDefault()
+      errors.push(event.error)
+    }
+    window.addEventListener("error", onError)
+    const captured: { values?: unknown } = {}
+    function H() {
+      const form = useForm({ defaultValues: { phone: "" }, onSubmit: vi.fn() })
+      const { ControlField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={({ onChange }) => (
+                // The mistake: an event handed to `onChange` as the value.
+                <button
+                  onClick={(event) => onChange(event as never)}
+                  type="button"
+                >
+                  Set
+                </button>
+              )}
+            />
+            <Subscribe selector={(state) => state.values}>
+              {(values) => {
+                captured.values = values
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    try {
+      render(<H />)
+      await user.click(screen.getByRole("button", { name: "Set" }))
+    } finally {
+      window.removeEventListener("error", onError)
+    }
+    expect(errors).toEqual([expect.any(TypeError)])
+    expect(captured.values).toStrictEqual({ phone: "" })
+  })
+})

package/src/create-form.tsx

@@ -6,6 +6,7 @@ import { createZenoForm } from "@zeno-lib/forms"
 import { CheckboxField } from "./fields/checkbox-field"
 import { CheckboxGroupField } from "./fields/checkbox-group-field"
 import { ComboboxField } from "./fields/combobox-field"
+import { ControlField } from "./fields/control-field"
 import { DatePickerField } from "./fields/date-picker-field"
 import { EmailField } from "./fields/email-field"
 import { FormError } from "./fields/form-error"
@@ -32,6 +33,7 @@ const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
     CheckboxField,
     CheckboxGroupField,
     ComboboxField,
+    ControlField,
     DatePickerField,
     EmailField,
     InputField,
@@ -57,5 +59,6 @@ const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
 
 export * from "@zeno-lib/forms"
 export { ValidationSpinner } from "./addons/validation-spinner"
+export { FieldShell } from "./fields/field-shell"
 export { RadioGroupFieldItem } from "./fields/radio-group-field"
 export { useAppForm, useForm, withFieldGroup, withForm }

package/src/create-zeno-form.tsx

@@ -4,6 +4,7 @@
 import type {
   AnyFormApi,
   DeepKeys,
+  DeepValue,
   FormAsyncValidateOrFn,
   FormOptions,
   FormValidateOrFn,
@@ -19,6 +20,7 @@ import {
   type StandardSchemaLike,
 } from "./lib/schema-required"
 import { setSubmitError } from "./lib/submit-error"
+import type { FieldControlProps } from "./lib/use-field-control"
 import { useRebasedDefaultValues } from "./lib/use-rebased-default-values"
 import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning"
 import { ValidationError } from "./lib/validation-error"
@@ -273,9 +275,26 @@ type WithValidators = {
 // biome-ignore lint/suspicious/noExplicitAny: field components accept arbitrary props.
 type AnyComponent = React.ComponentType<any>
 
+// A field that hands `render` a `FieldControlProps` (the kit's `ControlField`)
+// gets the control typed with the value at `name`, which its own generic
+// can't see. Matching on the parameter, not on `render` as a whole, leaves a
+// field whose `render` takes something else (or nothing) as declared.
+type WithControlValue<P, V> = P extends {
+  render: (control: infer C) => ReactNode
+}
+  ? // biome-ignore lint/suspicious/noExplicitAny: matches any value type.
+    [C] extends [FieldControlProps<any>]
+    ? Omit<P, "render"> & {
+        render: (control: FieldControlProps<V>) => ReactNode
+      }
+    : P
+  : P
+
 type FieldWrappers<FC extends Record<string, AnyComponent>, T> = {
   [K in keyof FC]: <N extends DeepKeys<T>>(
-    props: ComponentProps<FC[K]> & { name: N } & WithValidators
+    props: WithControlValue<ComponentProps<FC[K]>, DeepValue<T, N>> & {
+      name: N
+    } & WithValidators
   ) => ReactNode
 }