@zeno-lib/forms 0.5.0 → 0.6.0

package/src/fields/control-field.tsx

@@ -0,0 +1,57 @@
+"use client"
+
+import {
+  type FieldControlProps,
+  useFieldControl,
+} from "@zeno-lib/forms/lib/use-field-control"
+import type { ReactNode } from "react"
+import { FieldShell } from "./field-shell"
+
+type ControlFieldProps<TValue = unknown> = {
+  description?: ReactNode
+  disabled?: boolean
+  label?: ReactNode
+  /**
+   * Renders the control, given the props that bind it to the field: `id`,
+   * `name`, `value`, `onChange(value)`, `onBlur`, `disabled` and the
+   * `aria-*`. Spread them on a control that takes its value that way, or map
+   * them for one that doesn't. Keep `aria-invalid` on the focusable element
+   * (or a group root around it): a failed submit focuses the first invalid
+   * field by it.
+   */
+  render: (control: FieldControlProps<TValue>) => ReactNode
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
+  required?: boolean
+}
+
+/**
+ * Binds a controlled component the kit has no field for (a phone input, a
+ * star rating, a color picker) in the kit's field layout. Clearing it stores
+ * the field's empty value, as the kit's fields do.
+ */
+function ControlField<TValue = unknown>({
+  description,
+  disabled,
+  label,
+  render,
+  required,
+}: ControlFieldProps<TValue>) {
+  const { controlProps, ...shell } = useFieldControl<TValue>({
+    description,
+    disabled,
+    label,
+    required,
+  })
+
+  return (
+    <FieldShell {...shell} description={description} label={label}>
+      {render(controlProps)}
+    </FieldShell>
+  )
+}
+
+export type { ControlFieldProps }
+export { ControlField }

package/src/fields/field-shell.tsx

@@ -0,0 +1,73 @@
+"use client"
+
+import type { FieldControl } from "@zeno-lib/forms/lib/use-field-control"
+import type { ReactNode } from "react"
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@/components/ui/field"
+import { RequiredIndicator } from "../lib/required-indicator"
+
+type FieldShellProps = Pick<
+  FieldControl,
+  | "descriptionId"
+  | "errorId"
+  | "errors"
+  | "id"
+  | "isInvalid"
+  | "labelId"
+  | "name"
+  | "showRequiredIndicator"
+> & {
+  /** The control, bound with `useFieldControl`'s `controlProps`. */
+  children: ReactNode
+  description?: ReactNode
+  label?: ReactNode
+}
+
+/**
+ * The field layout every kit field shares: the label with its `*`, the
+ * control, the description and the error, tied together by the ids
+ * `useFieldControl` returns. Spread the rest of its result here:
+ *
+ * ```tsx
+ * const { controlProps, ...shell } = useFieldControl({ description, label })
+ * <FieldShell {...shell} description={description} label={label}>
+ *   <MyControl {...controlProps} />
+ * </FieldShell>
+ * ```
+ */
+function FieldShell({
+  children,
+  description,
+  descriptionId,
+  errorId,
+  errors,
+  id,
+  isInvalid,
+  label,
+  labelId,
+  name,
+  showRequiredIndicator,
+}: FieldShellProps) {
+  return (
+    <Field data-field={name} data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={id} id={labelId}>
+          {label}
+          {showRequiredIndicator && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      {children}
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {errors.length > 0 && <FieldError errors={errors} id={errorId} />}
+    </Field>
+  )
+}
+
+export type { FieldShellProps }
+export { FieldShell }

package/src/fields/index.ts

@@ -2,8 +2,10 @@
 export * from "./checkbox-field"
 export * from "./checkbox-group-field"
 export * from "./combobox-field"
+export * from "./control-field"
 export * from "./date-picker-field"
 export * from "./email-field"
+export * from "./field-shell"
 export * from "./form-error"
 export * from "./input-field"
 export * from "./money-field"

package/src/fields/input-field.tsx

@@ -1,23 +1,11 @@
 "use client"
 
-import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsFieldRequiredBySchema,
-  useIsInvalid,
-} from "@zeno-lib/forms/lib/use-is-invalid"
-import { Children, type ComponentProps, type ReactNode, useId } from "react"
-import {
-  Field,
-  FieldDescription,
-  FieldError,
-  FieldLabel,
-} from "@/components/ui/field"
+import { useFieldControl } from "@zeno-lib/forms/lib/use-field-control"
+import { Children, type ComponentProps, type ReactNode } from "react"
 import { Input } from "@/components/ui/input"
 import { InputGroup, InputGroupInput } from "@/components/ui/input-group"
-import { RequiredIndicator } from "../lib/required-indicator"
+import { FieldShell } from "./field-shell"
 
 type InputFieldProps = Omit<
   ComponentProps<typeof Input>,
@@ -41,28 +29,18 @@ function InputField({
   ...props
 }: InputFieldProps) {
   const field = useFieldContext<string>()
-  const id = useId()
-  const errorId = `${id}-error`
-  const descriptionId = `${id}-description`
-  const isInvalid = useIsInvalid(field)
-  const hideErrors = useHideFieldErrors(field)
-  const showError = isInvalid && !hideErrors
+  // The label names the input through `htmlFor`, so the input needs no
+  // `aria-labelledby` and the hook doesn't get `label`.
+  const { controlProps, ...shell } = useFieldControl<string>({
+    description,
+    required,
+  })
   const hasAddons = Children.count(children) > 0
-  const schemaRequired = useIsFieldRequired(field)
-  const isRequired = required ?? schemaRequired
-  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
-  const requiresValue = required ?? schemaRequiresValue
 
+  // A text input keeps the `""` the user typed, where `controlProps.onChange`
+  // would store the field's empty value.
   const inputProps = {
-    "aria-describedby": describedBy(
-      [description, descriptionId],
-      [showError, errorId]
-    ),
-    "aria-invalid": isInvalid || undefined,
-    "aria-required": requiresValue || undefined,
-    id,
-    name: field.name,
-    onBlur: field.handleBlur,
+    ...controlProps,
     onChange: (event: React.ChangeEvent<HTMLInputElement>) =>
       field.handleChange(event.target.value),
     value: field.state.value ?? "",
@@ -70,13 +48,7 @@ function InputField({
   }
 
   return (
-    <Field data-field={field.name} data-invalid={isInvalid}>
-      {label && (
-        <FieldLabel htmlFor={id}>
-          {label}
-          {isRequired && <RequiredIndicator />}
-        </FieldLabel>
-      )}
+    <FieldShell {...shell} description={description} label={label}>
       {hasAddons ? (
         <InputGroup>
           <InputGroupInput {...inputProps} />
@@ -85,13 +57,7 @@ function InputField({
       ) : (
         <Input {...inputProps} />
       )}
-      {description && (
-        <FieldDescription id={descriptionId}>{description}</FieldDescription>
-      )}
-      {showError && (
-        <FieldError errors={field.state.meta.errors} id={errorId} />
-      )}
-    </Field>
+    </FieldShell>
   )
 }
 

package/src/fields/textarea-field.tsx

@@ -1,23 +1,11 @@
 "use client"
 
-import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsFieldRequiredBySchema,
-  useIsInvalid,
-} from "@zeno-lib/forms/lib/use-is-invalid"
-import { Children, type ComponentProps, type ReactNode, useId } from "react"
-import {
-  Field,
-  FieldDescription,
-  FieldError,
-  FieldLabel,
-} from "@/components/ui/field"
+import { useFieldControl } from "@zeno-lib/forms/lib/use-field-control"
+import { Children, type ComponentProps, type ReactNode } from "react"
 import { InputGroup, InputGroupTextarea } from "@/components/ui/input-group"
 import { Textarea } from "@/components/ui/textarea"
-import { RequiredIndicator } from "../lib/required-indicator"
+import { FieldShell } from "./field-shell"
 
 type TextAreaFieldProps = Omit<
   ComponentProps<typeof Textarea>,
@@ -41,28 +29,18 @@ function TextAreaField({
   ...props
 }: TextAreaFieldProps) {
   const field = useFieldContext<string>()
-  const id = useId()
-  const errorId = `${id}-error`
-  const descriptionId = `${id}-description`
-  const isInvalid = useIsInvalid(field)
-  const hideErrors = useHideFieldErrors(field)
-  const showError = isInvalid && !hideErrors
+  // The label names the textarea through `htmlFor`, so the textarea needs no
+  // `aria-labelledby` and the hook doesn't get `label`.
+  const { controlProps, ...shell } = useFieldControl<string>({
+    description,
+    required,
+  })
   const hasAddons = Children.count(children) > 0
-  const schemaRequired = useIsFieldRequired(field)
-  const isRequired = required ?? schemaRequired
-  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
-  const requiresValue = required ?? schemaRequiresValue
 
+  // A textarea keeps the `""` the user typed, where `controlProps.onChange`
+  // would store the field's empty value.
   const textareaProps = {
-    "aria-describedby": describedBy(
-      [description, descriptionId],
-      [showError, errorId]
-    ),
-    "aria-invalid": isInvalid || undefined,
-    "aria-required": requiresValue || undefined,
-    id,
-    name: field.name,
-    onBlur: field.handleBlur,
+    ...controlProps,
     onChange: (event: React.ChangeEvent<HTMLTextAreaElement>) =>
       field.handleChange(event.target.value),
     value: field.state.value ?? "",
@@ -70,13 +48,7 @@ function TextAreaField({
   }
 
   return (
-    <Field data-field={field.name} data-invalid={isInvalid}>
-      {label && (
-        <FieldLabel htmlFor={id}>
-          {label}
-          {isRequired && <RequiredIndicator />}
-        </FieldLabel>
-      )}
+    <FieldShell {...shell} description={description} label={label}>
       {hasAddons ? (
         <InputGroup>
           <InputGroupTextarea {...textareaProps} />
@@ -85,13 +57,7 @@ function TextAreaField({
       ) : (
         <Textarea {...textareaProps} />
       )}
-      {description && (
-        <FieldDescription id={descriptionId}>{description}</FieldDescription>
-      )}
-      {showError && (
-        <FieldError errors={field.state.meta.errors} id={errorId} />
-      )}
-    </Field>
+    </FieldShell>
   )
 }
 

package/src/index.ts

@@ -18,6 +18,12 @@ export {
   type SubmitActionSchema,
   submitAction,
 } from "./lib/submit-action"
+export {
+  type FieldControl,
+  type FieldControlProps,
+  type UseFieldControlOptions,
+  useFieldControl,
+} from "./lib/use-field-control"
 export {
   useHideFieldErrors,
   useIsFieldRequired,

package/src/lib/submit-action.ts

@@ -8,6 +8,7 @@ import {
 } from "./action-result"
 import { applyValidationError } from "./apply-validation-error"
 import { ValidationError } from "./validation-error"
+import { getFormSchema } from "./validation-modes"
 
 // Write an action's failure onto the form. Field messages go through
 // `applyValidationError`, so they live in `errorMap.onChange` and clear the
@@ -110,7 +111,9 @@ type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<
   /**
    * 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>
 }
@@ -120,9 +123,13 @@ type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<
  * 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
@@ -145,10 +152,17 @@ async function submitAction(
   options: { reset?: unknown; schema?: SubmitActionSchema<unknown> } = {}
 ): Promise<ActionResult<unknown>> {
   const { formApi, value } = props
+  // `useForm` types its schema as `StandardSchema<Values>`, so the output
+  // still fits the `TValues` the action is typed against.
+  const schema =
+    options.schema ??
+    (getFormSchema(formApi as AnyFormApi) as
+      | SubmitActionSchema<unknown>
+      | undefined)
   let input: unknown = 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/src/lib/use-field-control.ts

@@ -0,0 +1,181 @@
+"use client"
+
+import type { AnyFieldMeta } from "@tanstack/react-form"
+import { type ReactNode, useCallback, useId } from "react"
+
+import { describedBy } from "./aria"
+import { useFieldContext } from "./contexts"
+import { emptyValueFor } from "./empty-value"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsFieldRequiredBySchema,
+  useIsInvalid,
+} from "./use-is-invalid"
+import { getFormSchema } from "./validation-modes"
+
+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
+}
+
+function isEmpty(value: unknown): boolean {
+  return (
+    value === null ||
+    value === undefined ||
+    value === "" ||
+    Number.isNaN(value) ||
+    (Array.isArray(value) && value.length === 0)
+  )
+}
+
+// A React synthetic event, from spreading the control props on a native input
+// or an event-emitting component. Storing it would put the event in the form.
+function isSyntheticEvent(value: unknown): boolean {
+  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<TValue = unknown>({
+  description,
+  disabled,
+  label,
+  required,
+}: UseFieldControlOptions = {}): FieldControl<TValue> {
+  const field = useFieldContext<TValue>()
+  const id = useId()
+  const labelId = label ? `${id}-label` : undefined
+  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
+  // `field` is rebuilt on every value change; these members aren't, so a
+  // control that memoizes on `onChange` doesn't see a new one each render.
+  const { form, handleBlur, handleChange, name } = field
+  const onChange = useCallback(
+    (value: TValue) => {
+      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
+            ) as TValue)
+          : value
+      )
+    },
+    [form, handleChange, name]
+  )
+
+  return {
+    controlProps: {
+      "aria-describedby": describedBy(
+        [description, descriptionId],
+        [showError, errorId]
+      ),
+      "aria-invalid": isInvalid || undefined,
+      "aria-labelledby": labelId,
+      "aria-required": isRequired || undefined,
+      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,
+  }
+}
+
+export type { FieldControl, FieldControlProps, UseFieldControlOptions }
+export { useFieldControl }

package/src/submit-action.test.tsx

@@ -244,6 +244,109 @@ describe("submitAction — field errors from the action", () => {
 })
 
 describe("submitAction — schema", () => {
+  test("parses with the form's own schema, and reset: true rebases on what the action saved", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ age: z.coerce.number(), name: z.string().trim() })
+    type Values = z.input<typeof schema>
+    const action = vi.fn((input: Values) =>
+      Promise.resolve<ActionResult<Values>>({ data: input, ok: true })
+    )
+    const formRef: { current: unknown } = { current: undefined }
+    function Harness() {
+      const form = useForm({
+        defaultValues: { age: "42", name: " Ada " },
+        onSubmit: (submit) => submitAction(submit, action, { reset: true }),
+        schema,
+      })
+      formRef.current = form
+      const { InputField, SubmitButton } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+            <SubmitButton>Submit</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<Harness />)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+
+    await vi.waitFor(() =>
+      expect(action).toHaveBeenCalledWith({ age: 42, name: "Ada" })
+    )
+    const form = formRef.current as {
+      state: { isDefaultValue: boolean; values: Values }
+    }
+    await vi.waitFor(() =>
+      expect(form.state.values).toEqual({ age: 42, name: "Ada" })
+    )
+    expect(form.state.isDefaultValue).toBe(true)
+  })
+
+  test("an explicit schema wins over the form's", async () => {
+    const user = userEvent.setup()
+    const action = vi.fn((_input: { name: string }) =>
+      Promise.resolve<ActionResult<null>>({ data: null, ok: true })
+    )
+    const actionSchema = z.object({ name: z.string().toUpperCase() })
+    function Harness() {
+      const form = useForm({
+        defaultValues: { name: " Ada " },
+        onSubmit: (submit) =>
+          submitAction(submit, action, { schema: actionSchema }),
+        schema: z.object({ name: z.string().trim() }),
+      })
+      const { InputField, SubmitButton } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+            <SubmitButton>Submit</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<Harness />)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+
+    await vi.waitFor(() =>
+      expect(action).toHaveBeenCalledWith({ name: " ADA " })
+    )
+  })
+
+  // A schema passed as a plain TanStack validator is not the form's schema:
+  // the action gets the values as they are, as before.
+  const trimmed = z.object({ name: z.string().trim() })
+
+  test("useForm without a schema sends the values as they are", async () => {
+    const user = userEvent.setup()
+    const action = vi.fn((_input: { name: string }) =>
+      Promise.resolve<ActionResult<null>>({ data: null, ok: true })
+    )
+    function Harness() {
+      const form = useForm({
+        defaultValues: { name: " Ada " },
+        onSubmit: (submit) => submitAction(submit, action),
+        validators: { onChange: trimmed },
+      })
+      return (
+        <button onClick={() => form.handleSubmit()} type="button">
+          Submit
+        </button>
+      )
+    }
+    render(<Harness />)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+
+    await vi.waitFor(() =>
+      expect(action).toHaveBeenCalledWith({ name: " Ada " })
+    )
+  })
+
   test("passes the schema output to the action, not the input values", async () => {
     const user = userEvent.setup()
     const schema = z.object({