@zeno-lib/forms 0.6.0 → 0.7.0

package/src/form-element.tsx

@@ -1,52 +1,87 @@
 "use client"
 
 import type { AnyFormApi } from "@tanstack/react-form"
-import type { ComponentProps, FormEvent, ReactNode } from "react"
+import {
+  type ComponentProps,
+  type FormEvent,
+  type ReactNode,
+  useMemo,
+} from "react"
 
 import { FormProvider as RawFormProvider, useFormContext } from "./lib/contexts"
 import { focusFirstInvalid, restoreFocus } from "./lib/focus-first-invalid"
+import { FormDisabledContext, useIsFormDisabled } from "./lib/form-disabled"
 import { reportSubmitError } from "./lib/submit-error"
 
 type FormProviderProps = {
   children: ReactNode
+  /**
+   * Disable every field of the form and its submit button, as
+   * `useForm({ disabled })` does. A field's own `disabled` still applies.
+   */
+  disabled?: boolean
   form: { handleSubmit: () => unknown }
 }
 
-function FormProvider({ children, form }: FormProviderProps) {
+function FormProvider({ children, disabled = false, form }: FormProviderProps) {
+  const { store } = form as AnyFormApi
+  const scope = useMemo(() => ({ disabled, key: store }), [disabled, store])
   return (
-    <RawFormProvider value={form as AnyFormApi}>{children}</RawFormProvider>
+    <RawFormProvider value={form as AnyFormApi}>
+      <FormDisabledContext value={scope}>{children}</FormDisabledContext>
+    </RawFormProvider>
   )
 }
 
-type FormProps = Omit<ComponentProps<"form">, "onSubmit">
+type FormProps = Omit<ComponentProps<"form">, "onSubmit"> & {
+  /**
+   * Disable every field and button of the kit inside, and ignore a submit. A
+   * field's own `disabled` still applies. A button outside the `<form>`
+   * (`form="id"`) isn't inside: disable the form with `useForm({ disabled })`
+   * or `<FormProvider disabled>` to reach it.
+   */
+  disabled?: boolean
+}
 
-function Form({ children, className, ...props }: FormProps) {
+function Form({ children, className, disabled = false, ...props }: FormProps) {
   const form = useFormContext()
+  const isDisabled = useIsFormDisabled(form) || disabled
+  const { store } = form
+  const scope = useMemo(
+    () => ({ disabled: isDisabled, key: store }),
+    [isDisabled, store]
+  )
   return (
-    <form
-      className={className}
-      noValidate
-      onSubmit={async (event: FormEvent<HTMLFormElement>) => {
-        event.preventDefault()
-        event.stopPropagation()
-        const node = event.currentTarget
-        const focused = node.ownerDocument.activeElement
-        // Caught so the user can retry; `useForm` keeps it for `FormError`.
-        await Promise.resolve(form.handleSubmit()).catch(reportSubmitError)
-        const { isSubmitSuccessful, isValid } = form.state
-        if (!isValid && focusFirstInvalid(node)) {
-          return
-        }
-        // A form-level failure has no field to fix, so focus stays where it
-        // was, or goes back there if the submit button's disabling dropped it.
-        if (!(isValid && isSubmitSuccessful)) {
-          restoreFocus(focused)
-        }
-      }}
-      {...props}
-    >
-      {children}
-    </form>
+    <FormDisabledContext value={scope}>
+      <form
+        className={className}
+        noValidate
+        onSubmit={async (event: FormEvent<HTMLFormElement>) => {
+          event.preventDefault()
+          event.stopPropagation()
+          // A `<button form={id}>` outside the form can still submit it.
+          if (isDisabled) {
+            return
+          }
+          const node = event.currentTarget
+          const focused = node.ownerDocument.activeElement
+          // Caught so the user can retry; `useForm` keeps it for `FormError`.
+          await Promise.resolve(form.handleSubmit()).catch(reportSubmitError)
+          const { isSubmitSuccessful, isValid } = form.state
+          if (!isValid && focusFirstInvalid(node)) {
+            return
+          }
+          // A form-level failure has no field to fix, so focus stays where it
+          // was, or goes back there if the submit button's disabling dropped it.
+          if (!(isValid && isSubmitSuccessful)) {
+            restoreFocus(focused)
+          }
+        }}
+        {...props}
+      >
+        {children}
+      </form>
+    </FormDisabledContext>
   )
 }
 

package/src/grouped-options.test-d.ts

@@ -0,0 +1,59 @@
+import { expectTypeOf, test } from "vitest"
+import { useForm } from "./create-form"
+import { ComboboxField } from "./fields/combobox-field"
+import { MultiSelectField } from "./fields/multi-select-field"
+
+type Party = { id: number; kind: "company" | "person" }
+type PartyItem = { label: string; value: Party }
+
+const GROUPS: { label: string; items: PartyItem[] }[] = [
+  {
+    items: [{ label: "Ada", value: { id: 1, kind: "person" } }],
+    label: "People",
+  },
+]
+
+const isSameParty = (a: Party, b: Party) => a.kind === b.kind && a.id === b.id
+
+test("grouped items type renderItem with an item and isItemEqualToValue with its value", () => {
+  ComboboxField({
+    isItemEqualToValue: (a, b) => {
+      expectTypeOf(a).toEqualTypeOf<Party>()
+      return isSameParty(a, b)
+    },
+    items: GROUPS,
+    renderItem: (item) => {
+      expectTypeOf(item).toEqualTypeOf<PartyItem>()
+      return null
+    },
+  })
+  MultiSelectField({
+    isItemEqualToValue: (a, b) => {
+      expectTypeOf(a).toEqualTypeOf<Party>()
+      return isSameParty(a, b)
+    },
+    items: GROUPS,
+    renderItem: (item) => {
+      expectTypeOf(item).toEqualTypeOf<PartyItem>()
+      return null
+    },
+  })
+})
+
+// `form.ComboboxField` reads the field's props with `T` as `unknown`.
+test("form fields take a comparator typed with the value", () => {
+  const form = useForm({
+    defaultValues: { parties: [] as Party[], payer: null as Party | null },
+    onSubmit: () => undefined,
+  })
+  form.ComboboxField({
+    isItemEqualToValue: isSameParty,
+    items: GROUPS,
+    name: "payer",
+  })
+  form.MultiSelectField({
+    isItemEqualToValue: isSameParty,
+    items: GROUPS,
+    name: "parties",
+  })
+})

package/src/grouped-options.test.tsx

@@ -0,0 +1,251 @@
+import { cleanup, render, screen, within } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { useState } from "react"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(() => {
+  cleanup()
+})
+
+const party = z.object({ id: z.number(), kind: z.enum(["company", "person"]) })
+type Party = z.infer<typeof party>
+
+const schema = z.object({
+  parties: z.array(party),
+  payer: party.nullable(),
+})
+type Values = z.infer<typeof schema>
+
+// Rebuilt on every render, as options mapped from fetched rows are, so no
+// item value is ever the stored object. A person and a company share an id.
+function partyGroups() {
+  return [
+    {
+      items: [{ label: "Ada Lovelace", value: { id: 1, kind: "person" } }],
+      label: "People",
+    },
+    {
+      items: [
+        { label: "Globex", value: { id: 1, kind: "company" } },
+        { label: "Initech", value: { id: 2, kind: "company" } },
+      ],
+      label: "Companies",
+    },
+  ]
+}
+
+const isSameParty = (a: Party, b: Party) => a.kind === b.kind && a.id === b.id
+
+function Harness({ captured }: { captured: { values?: Values } }) {
+  const form = useForm({
+    defaultValues: {
+      parties: [{ id: 1, kind: "company" }],
+      payer: { id: 1, kind: "company" },
+    } as Values,
+    onSubmit: vi.fn(),
+    schema,
+  })
+  const { ComboboxField, MultiSelectField, Subscribe } = form
+  return (
+    <FormProvider form={form}>
+      <Form>
+        <ComboboxField
+          isItemEqualToValue={isSameParty}
+          items={partyGroups()}
+          label="Payer"
+          name="payer"
+        />
+        <MultiSelectField
+          isItemEqualToValue={isSameParty}
+          items={partyGroups()}
+          label="Parties"
+          name="parties"
+        />
+        <Subscribe selector={(state) => state.values}>
+          {(values) => {
+            captured.values = values
+            return null
+          }}
+        </Subscribe>
+      </Form>
+    </FormProvider>
+  )
+}
+
+function fieldRoot(container: HTMLElement, name: string): HTMLElement {
+  const root = container.querySelector<HTMLElement>(`[data-field="${name}"]`)
+  if (!root) {
+    throw new Error(`no ${name} field`)
+  }
+  return root
+}
+
+function chips(container: HTMLElement): string[] {
+  return [
+    ...fieldRoot(container, "parties").querySelectorAll(
+      '[data-slot="combobox-chip"]'
+    ),
+  ].map((chip) => chip.textContent ?? "")
+}
+
+describe("grouped options with object values", () => {
+  test("ComboboxField keeps a stored object selected, stores the picked one, and clears to the empty value", async () => {
+    const user = userEvent.setup()
+    const captured: { values?: Values } = {}
+    const { container, rerender } = render(<Harness captured={captured} />)
+    const input = screen.getByRole("combobox", { name: "Payer" })
+    expect(input).toHaveProperty("value", "Globex")
+
+    await user.click(input)
+    const companies = await screen.findByRole("group", { name: "Companies" })
+    expect(
+      within(companies)
+        .getByRole("option", { name: "Globex" })
+        .getAttribute("aria-selected")
+    ).toBe("true")
+    await user.click(screen.getByRole("option", { name: "Ada Lovelace" }))
+    expect(captured.values?.payer).toEqual({ id: 1, kind: "person" })
+
+    rerender(<Harness captured={captured} />)
+    expect(input).toHaveProperty("value", "Ada Lovelace")
+
+    await user.click(
+      within(fieldRoot(container, "payer")).getByRole("button", {
+        name: "Clear",
+      })
+    )
+    expect(captured.values?.payer).toBeNull()
+  })
+
+  test("MultiSelectField keeps stored objects selected, adds the picked one, and clears", async () => {
+    const user = userEvent.setup()
+    const captured: { values?: Values } = {}
+    const { container, rerender } = render(<Harness captured={captured} />)
+    expect(chips(container)).toEqual(["Globex"])
+
+    await user.click(screen.getByRole("combobox", { name: "Parties" }))
+    const people = await screen.findByRole("group", { name: "People" })
+    await user.click(
+      within(people).getByRole("option", { name: "Ada Lovelace" })
+    )
+    await user.keyboard("{Escape}")
+    expect(captured.values?.parties).toEqual([
+      { id: 1, kind: "company" },
+      { id: 1, kind: "person" },
+    ])
+
+    rerender(<Harness captured={captured} />)
+    expect(chips(container)).toEqual(["Globex", "Ada Lovelace"])
+
+    await user.click(
+      within(fieldRoot(container, "parties")).getByRole("button", {
+        name: "Clear",
+      })
+    )
+    expect(captured.values?.parties).toEqual([])
+  })
+})
+
+describe("grouped options", () => {
+  test.each([
+    ["a group first", [{ items: ["Ada"], label: "People" }, "Globex"]],
+    ["a plain item first", ["Globex", { items: ["Ada"], label: "People" }]],
+  ])("mix groups and plain items, with %s", async (_, items) => {
+    const user = userEvent.setup()
+    const captured: { values?: { name: string | null } } = {}
+    function H() {
+      const form = useForm({
+        defaultValues: { name: null as string | null },
+        onSubmit: vi.fn(),
+      })
+      return (
+        <FormProvider form={form}>
+          <form.ComboboxField items={items} label="Name" name="name" />
+          <form.Subscribe selector={(state) => state.values}>
+            {(values) => {
+              captured.values = values
+              return null
+            }}
+          </form.Subscribe>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const input = screen.getByRole("combobox", { name: "Name" })
+    await user.type(input, "Ad")
+    const people = await screen.findByRole("group", { name: "People" })
+    await user.click(within(people).getByRole("option", { name: "Ada" }))
+    expect(captured.values?.name).toBe("Ada")
+    await user.clear(input)
+    await user.type(input, "Glo")
+    await user.click(await screen.findByRole("option", { name: "Globex" }))
+    expect(captured.values?.name).toBe("Globex")
+  })
+
+  test("ComboboxField keeps what the user types while the items are rebuilt", async () => {
+    const user = userEvent.setup()
+    function H() {
+      const [, setQuery] = useState("")
+      const form = useForm({
+        defaultValues: { payer: { id: 1, kind: "company" } } as Values,
+        onSubmit: vi.fn(),
+        schema,
+      })
+      return (
+        <FormProvider form={form}>
+          <form.ComboboxField
+            isItemEqualToValue={isSameParty}
+            items={partyGroups()}
+            label="Payer"
+            name="payer"
+            onInputValueChange={setQuery}
+          />
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    const input = screen.getByRole("combobox", { name: "Payer" })
+    await user.type(input, " Corp")
+    expect(input).toHaveProperty("value", "Globex Corp")
+  })
+
+  test("MultiSelectField keeps a stored value whose item isn't loaded yet", async () => {
+    const user = userEvent.setup()
+    const captured: { values?: Values } = {}
+    function H() {
+      const form = useForm({
+        defaultValues: { parties: [{ id: 9, kind: "company" }] } as Values,
+        onSubmit: vi.fn(),
+        schema,
+      })
+      return (
+        <FormProvider form={form}>
+          <form.MultiSelectField
+            isItemEqualToValue={isSameParty}
+            // The companies are still loading.
+            items={partyGroups().slice(0, 1)}
+            label="Parties"
+            name="parties"
+          />
+          <form.Subscribe selector={(state) => state.values}>
+            {(values) => {
+              captured.values = values
+              return null
+            }}
+          </form.Subscribe>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByRole("combobox", { name: "Parties" }))
+    await user.click(
+      await screen.findByRole("option", { name: "Ada Lovelace" })
+    )
+    expect(captured.values?.parties).toEqual([
+      { id: 9, kind: "company" },
+      { id: 1, kind: "person" },
+    ])
+  })
+})

package/src/index.ts

@@ -12,6 +12,7 @@ export {
 } from "./lib/action-result"
 export { applyValidationError } from "./lib/apply-validation-error"
 export { useFieldContext, useFormContext } from "./lib/contexts"
+export { useIsFormDisabled } from "./lib/form-disabled"
 export {
   applyActionError,
   type SubmitActionOptions,

package/src/lib/date-value.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest"
+import { formatIsoDate, parseDateValue } from "./date-value"
+
+describe("parseDateValue", () => {
+  test("reads a day the month doesn't have as empty, not as next month's", () => {
+    expect(parseDateValue("2026-02-31")).toBeUndefined()
+  })
+
+  test("keeps a year below 100, which `new Date(y, m, d)` reads as 19yy", () => {
+    const date = parseDateValue("0042-03-01")
+    expect(date?.getFullYear()).toBe(42)
+    expect(date && formatIsoDate(date)).toBe("0042-03-01")
+  })
+})

package/src/lib/date-value.ts

@@ -0,0 +1,70 @@
+/**
+ * What a date field stores for a picked day:
+ * - `"date"`: a `Date`, at local midnight.
+ * - `"iso-date"`: the day as `YYYY-MM-DD`, as `z.iso.date()` accepts and a
+ *   `date` column stores it.
+ * - `"iso-datetime"`: the day's local midnight as an ISO 8601 timestamp in
+ *   UTC (`toISOString()`), as `z.iso.datetime()` accepts and a timestamp
+ *   column takes it.
+ */
+type DateValueType = "date" | "iso-date" | "iso-datetime"
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/
+
+function pad(value: number, length: number): string {
+  return String(value).padStart(length, "0")
+}
+
+// `new Date("2026-10-09")` reads a date-only string as UTC midnight, which is
+// the day before anywhere west of UTC. Read it as the local day instead.
+function parseIsoDate(value: string): Date | undefined {
+  const match = ISO_DATE.exec(value)
+  if (!match) {
+    return
+  }
+  const [year, month, day] = match.slice(1).map(Number) as [
+    number,
+    number,
+    number,
+  ]
+  const date = new Date(year, month - 1, day)
+  // `new Date` reads the years 0 to 99 as 1900 to 1999.
+  date.setFullYear(year, month - 1, day)
+  // `2026-02-31` would roll over to March.
+  return date.getMonth() === month - 1 ? date : undefined
+}
+
+/**
+ * The day a stored value stands for, as a local `Date`, or `undefined` for an
+ * empty or unreadable one. Reads a `Date`, a `YYYY-MM-DD` string as that day
+ * in local time, and any other string `Date` parses, such as an ISO 8601
+ * timestamp.
+ */
+function parseDateValue(value: unknown): Date | undefined {
+  let date: Date | undefined
+  if (value instanceof Date) {
+    date = value
+  } else if (typeof value === "string" && value !== "") {
+    date = ISO_DATE.test(value) ? parseIsoDate(value) : new Date(value)
+  }
+  return date && !Number.isNaN(date.getTime()) ? date : undefined
+}
+
+/** The day of a local `Date` as `YYYY-MM-DD`, without going through UTC. */
+function formatIsoDate(date: Date): string {
+  return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1, 2)}-${pad(date.getDate(), 2)}`
+}
+
+/** The value to store for `date`, a day picked in local time. */
+function toDateValue(date: Date, type: DateValueType): Date | string {
+  if (type === "iso-date") {
+    return formatIsoDate(date)
+  }
+  if (type === "iso-datetime") {
+    return date.toISOString()
+  }
+  return date
+}
+
+export type { DateValueType }
+export { formatIsoDate, parseDateValue, toDateValue }

package/src/lib/default-props.ts

@@ -0,0 +1,19 @@
+/**
+ * The props a component renders with: `props` over `defaults`. A prop passed
+ * as `undefined` keeps its default, as a destructuring default would.
+ */
+export function withDefaultProps<P extends object>(
+  defaults: Partial<P> | undefined,
+  props: P
+): P {
+  if (defaults === undefined) {
+    return props
+  }
+  const merged: Record<string, unknown> = { ...defaults }
+  for (const [key, value] of Object.entries(props)) {
+    if (value !== undefined) {
+      merged[key] = value
+    }
+  }
+  return merged as P
+}

package/src/lib/empty-value.test.ts

@@ -69,4 +69,23 @@ describe("withEmptyStartValues", () => {
       ownerId: null,
     })
   })
+
+  test("starts an object the defaults only partly fill at its empty value, when it can be absent", () => {
+    const reference = z.object({ id: z.uuid(), table: z.string() })
+    const schema = z.object({
+      address: z.object({ city: z.string(), street: z.string() }).nullable(),
+      owner: reference,
+      payee: reference.optional(),
+      payer: reference.nullable(),
+    })
+    const start = withEmptyStartValues(schema, extractZodDefaults(schema))
+    expect(start).toEqual({
+      // Valid as filled, so its inputs stay controlled.
+      address: { city: "", street: "" },
+      // Required: its own fields still report what is missing.
+      owner: { id: "", table: "" },
+      payee: undefined,
+      payer: null,
+    })
+  })
 })

package/src/lib/empty-value.ts

@@ -89,21 +89,65 @@ function isTypeEmpty(value: unknown): boolean {
   return value === "" || (Array.isArray(value) && value.length === 0)
 }
 
+function isUnder(name: string, prefix: string): boolean {
+  return (
+    name === prefix ||
+    name.startsWith(`${prefix}.`) ||
+    name.startsWith(`${prefix}[`)
+  )
+}
+
+// The outermost object above `keys` that the defaults fill and the schema
+// lets be absent, with its empty value (`null` or `undefined`).
+function emptiableAncestor(
+  schema: StandardSchemaLike,
+  values: unknown,
+  keys: readonly PropertyKey[]
+): { keys: readonly PropertyKey[]; value: unknown } | null {
+  for (let length = 1; length < keys.length; length += 1) {
+    const prefix = keys.slice(0, length)
+    const start = valueAt(values, prefix)
+    if (typeof start !== "object" || start === null || Array.isArray(start)) {
+      continue
+    }
+    const empty = emptyValueFor(schema, values, toFieldName(prefix), start)
+    if (empty === null || empty === undefined) {
+      return { keys: prefix, value: empty }
+    }
+  }
+  return null
+}
+
 // `extractZodDefaults` starts every string at `""` and every array at `[]`.
 // Where the schema rejects that (`z.uuid().nullable()`,
 // `z.email().optional()`), start the field at its empty value instead, so an
 // untouched optional field passes. A required one keeps `""` or `[]`.
+//
+// An object the defaults only partly fill (`{ table: "" }` for
+// `z.object({ table: z.string(), id: z.number() }).nullable()`, a combobox's
+// value) would block submit on a path no field shows: start it at its empty
+// value too, when the schema lets it be absent.
 function withEmptyStartValues(
   schema: StandardSchemaLike,
   defaults: Record<string, unknown>
 ): Record<string, unknown> {
   const issues = validateSync(schema, defaults)
   let result: unknown = defaults
+  const emptied: string[] = []
   for (const issue of issues ?? []) {
     const name = toFieldName(issue.path)
     const keys = toPathKeys(name)
+    if (keys.length === 0 || emptied.some((prefix) => isUnder(name, prefix))) {
+      continue
+    }
+    const ancestor = emptiableAncestor(schema, result, keys)
+    if (ancestor) {
+      result = withValueAt(result, ancestor.keys, ancestor.value)
+      emptied.push(toFieldName(ancestor.keys))
+      continue
+    }
     const start = valueAt(defaults, keys)
-    if (keys.length === 0 || !isTypeEmpty(start)) {
+    if (!isTypeEmpty(start)) {
       continue
     }
     const empty = emptyValueFor(schema, result, name, start)