@zeno-lib/forms 0.5.0 → 0.7.0

package/src/lib/item-options.ts

@@ -0,0 +1,165 @@
+// The items of `ComboboxField` and `MultiSelectField`: plain values, which
+// are their own label, `{ value, label }` objects, or `{ label, items }`
+// groups of either.
+
+/** An item whose value isn't its label. */
+type ItemObject<V> = { value: V; label: string }
+
+/** Items under a heading. */
+type ItemGroup<T> = { label: string; items: readonly T[] }
+
+/** An item of `items`, or of one of its groups. */
+type ItemOption<T> = T extends ItemGroup<infer I> ? I : T
+
+/** What picking an item stores: `item.value` for an object, else the item. */
+type ItemValue<T> =
+  T extends ItemGroup<infer I>
+    ? ItemValue<I>
+    : T extends ItemObject<infer V>
+      ? V
+      : T
+
+/** Whether an item's value is a stored one, as `isItemEqualToValue` says. */
+type ValueComparator = (itemValue: unknown, value: unknown) => boolean
+
+function isItemObject(item: unknown): item is ItemObject<unknown> {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    "value" in item &&
+    "label" in item
+  )
+}
+
+/** What Base UI takes for a group: an object with an `items` array. */
+function isItemGroup(item: unknown): item is ItemGroup<unknown> {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    Array.isArray((item as { items?: unknown }).items)
+  )
+}
+
+function itemValue(item: unknown): unknown {
+  return isItemObject(item) ? item.value : item
+}
+
+function itemLabel(item: unknown): string {
+  return isItemObject(item) ? item.label : String(item)
+}
+
+/** A React key per value: `1` and `"1"` get two, an object gets its JSON. */
+function valueKey(value: unknown): string {
+  if (typeof value !== "object" || value === null) {
+    return `${typeof value}:${String(value)}`
+  }
+  try {
+    return `object:${JSON.stringify(value)}`
+  } catch {
+    return `object:${String(value)}`
+  }
+}
+
+type ItemList<T> = {
+  /**
+   * `items` as Base UI takes them. It tells a grouped list by its first entry
+   * alone, so once there is a group, each run of plain items beside one goes
+   * under a group with no heading (`label: ""`).
+   */
+  readonly items: readonly T[]
+  /** Every option, the grouped ones included, in order. */
+  readonly options: readonly ItemOption<T>[]
+  /** The first option of each `valueKey`, so finding a value is no scan. */
+  readonly byKey: ReadonlyMap<string, ItemOption<T>>
+}
+
+function toItemList<T>(items: readonly T[]): ItemList<T> {
+  const hasGroup = items.some(isItemGroup)
+  const options: ItemOption<T>[] = []
+  const groups: ItemGroup<unknown>[] = []
+  let run: unknown[] | undefined
+  for (const item of items) {
+    if (isItemGroup(item)) {
+      for (const option of item.items) {
+        options.push(option as ItemOption<T>)
+      }
+      groups.push(item)
+      run = undefined
+    } else {
+      options.push(item as ItemOption<T>)
+      if (hasGroup && !run) {
+        run = []
+        groups.push({ items: run, label: "" })
+      }
+      run?.push(item)
+    }
+  }
+  const byKey = new Map<string, ItemOption<T>>()
+  for (const option of options) {
+    const key = valueKey(itemValue(option))
+    if (!byKey.has(key)) {
+      byKey.set(key, option)
+    }
+  }
+  return {
+    byKey,
+    items: hasGroup ? (groups as unknown as readonly T[]) : items,
+    options,
+  }
+}
+
+/**
+ * `Object.is`, then `isItemEqualToValue`, which never sees an empty value.
+ */
+function isSameValue(
+  a: unknown,
+  b: unknown,
+  isItemEqualToValue: ValueComparator | undefined
+): boolean {
+  if (Object.is(a, b)) {
+    return true
+  }
+  if (a === null || a === undefined || b === null || b === undefined) {
+    return false
+  }
+  return isItemEqualToValue?.(a, b) ?? false
+}
+
+/** The option whose value is `value`, if `items` has it. */
+function findOption<T>(
+  list: ItemList<T>,
+  value: unknown,
+  isItemEqualToValue: ValueComparator | undefined
+): ItemOption<T> | undefined {
+  const hit = list.byKey.get(valueKey(value))
+  if (
+    hit !== undefined &&
+    isSameValue(itemValue(hit), value, isItemEqualToValue)
+  ) {
+    return hit
+  }
+  // A comparator can match values whose keys differ (`{ id }` against
+  // `{ id, name }`).
+  return list.options.find((option) =>
+    isSameValue(itemValue(option), value, isItemEqualToValue)
+  )
+}
+
+export type {
+  ItemGroup,
+  ItemList,
+  ItemObject,
+  ItemOption,
+  ItemValue,
+  ValueComparator,
+}
+export {
+  findOption,
+  isItemGroup,
+  isItemObject,
+  isSameValue,
+  itemLabel,
+  itemValue,
+  toItemList,
+  valueKey,
+}

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

@@ -87,6 +87,15 @@ describe("getRequiredPaths", () => {
     expect(required.has("profile.bio")).toBe(false)
   })
 
+  test("a nullable object is not required, though its own fields are", () => {
+    const schema = z.object({
+      payer: z.object({ id: z.number(), kind: z.string().min(1) }).nullable(),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("payer")).toBe(false)
+    expect(required.has("payer.kind")).toBe(true)
+  })
+
   test("optional nested object is not descended into", () => {
     const schema = z.object({
       profile: z.object({ email: z.email() }).optional(),

package/src/lib/schema-required.ts

@@ -221,6 +221,38 @@ function settleEmptied(
   return { descended, next }
 }
 
+// The probe descends into a missing object with `{}`, so it never tries
+// `null` there. Try it on the side: a `.nullable()` object accepts it, so it
+// isn't required, though its own fields still are once it is set.
+function clearNullableObjects(
+  schema: StandardSchemaLike,
+  filled: readonly ProbeFill[],
+  probe: Record<PropertyKey, unknown>,
+  required: Set<string>,
+  cleared: Set<string>
+): void {
+  for (const fill of filled) {
+    if (isEmptyProbe(fill.value) || cleared.has(fill.path)) {
+      continue
+    }
+    fillAt(probe, fill.keys, null, true)
+    const issues = validateSync(schema, probe)
+    fillAt(probe, fill.keys, fill.value, true)
+    const rejected = issues?.some((issue) => {
+      const path = joinPath(issue.path?.map(pathKey) ?? [])
+      return (
+        path === fill.path ||
+        path.startsWith(`${fill.path}.`) ||
+        path.startsWith(`${fill.path}[`)
+      )
+    })
+    if (issues && !rejected) {
+      required.delete(fill.path)
+      cleared.add(fill.path)
+    }
+  }
+}
+
 function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
   const required = new Set<string>()
   const cleared = new Set<string>()
@@ -234,6 +266,7 @@ function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
       return required
     }
     const { failing, filled } = recordPass(issues, probe, required, cleared)
+    clearNullableObjects(schema, filled, probe, required, cleared)
     const settled = settleEmptied(emptied, failing, probe, required, cleared)
     emptied = [
       ...filled.filter(({ value }) => isEmptyProbe(value)),

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,191 @@
+"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 { useIsFormDisabled } from "./form-disabled"
+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
+  /**
+   * Disable the control. A disabled form (`useForm({ disabled })`,
+   * `<Form disabled>`, `FormDialog`'s `disabled`) disables it either way.
+   */
+  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
+  /** The field's own `disabled`, or the form's. */
+  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
+  /** The field is disabled, by its own `disabled` or the form's. */
+  isDisabled: boolean
+  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
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
+  // `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: isDisabled,
+      id,
+      name,
+      onBlur: handleBlur,
+      onChange,
+      value: field.state.value,
+    },
+    descriptionId,
+    errorId,
+    errors: showError ? field.state.meta.errors : [],
+    id,
+    isDisabled,
+    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({

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

@@ -1,6 +1,8 @@
-import { test } from "vitest"
+import type { ReactNode } from "react"
+import { expectTypeOf, test } from "vitest"
 import { z } from "zod"
 import { useForm } from "./create-form"
+import { createZenoForm } from "./create-zeno-form"
 
 const schema = z.object({
   accept: z.boolean(),
@@ -93,3 +95,51 @@ test("listeners prop is accepted on every field wrapper", () => {
     name: "email",
   })
 })
+
+test("ControlField types its control with the value at `name`", () => {
+  const form = useForm({
+    onSubmit: () => undefined,
+    schema: z.object({
+      phone: z.string().nullable(),
+      rating: z.number(),
+    }),
+  })
+  form.ControlField({
+    name: "phone",
+    render: (control) => {
+      expectTypeOf(control.value).toEqualTypeOf<string | null>()
+      return null
+    },
+  })
+  form.ControlField({
+    name: "rating",
+    render: (control) => {
+      control.onChange(3)
+      // @ts-expect-error — the field holds a number
+      control.onChange("3")
+      return null
+    },
+  })
+  // @ts-expect-error — not a valid path
+  form.ControlField({ name: "nonexistent", render: () => null })
+})
+
+test("a field whose `render` takes another argument keeps its own type", () => {
+  const { useForm: useListForm } = createZenoForm({
+    fieldComponents: {
+      ListField: (_: { render: (row: { id: string }) => ReactNode }) => null,
+    },
+    formComponents: {},
+  })
+  const form = useListForm({
+    onSubmit: () => undefined,
+    schema: z.object({ rows: z.array(z.string()) }),
+  })
+  form.ListField({
+    name: "rows",
+    render: (row) => {
+      expectTypeOf(row).toEqualTypeOf<{ id: string }>()
+      return null
+    },
+  })
+})