@zeno-lib/forms 0.5.0 → 0.7.0

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,12 +12,19 @@ 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,
   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/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)

package/src/lib/form-disabled.ts

@@ -0,0 +1,95 @@
+"use client"
+
+import type { AnyFormApi } from "@tanstack/react-form"
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useSyncExternalStore,
+} from "react"
+
+import { formContext } from "./contexts"
+
+// `useForm({ disabled })`, per form. Keyed by `form.store`, as the rest of the
+// per-form Zeno state is (`validation-modes.ts`), and read through
+// `useSyncExternalStore`, so a toggle re-renders every field, a memoized one
+// or one with no provider above it included.
+const disabledOption = new WeakMap<object, boolean>()
+const listeners = new WeakMap<object, Set<() => void>>()
+
+function subscribe(key: object, listener: () => void): () => void {
+  let set = listeners.get(key)
+  if (!set) {
+    set = new Set()
+    listeners.set(key, set)
+  }
+  set.add(listener)
+  return () => {
+    set.delete(listener)
+  }
+}
+
+/** Apply `useForm({ disabled })` to `form`. */
+function useDisabledOption(form: AnyFormApi, disabled: boolean): void {
+  const key = form.store
+  // Seeded while rendering, so the first render, the server's included,
+  // already has it. A change lands on commit, so a render React drops (a
+  // suspended transition) never reaches the fields.
+  if (!disabledOption.has(key)) {
+    disabledOption.set(key, disabled)
+  }
+  useLayoutEffect(() => {
+    if (disabledOption.get(key) === disabled) {
+      return
+    }
+    disabledOption.set(key, disabled)
+    for (const listener of listeners.get(key) ?? []) {
+      listener()
+    }
+  }, [key, disabled])
+}
+
+type FormDisabledScope = {
+  readonly disabled: boolean
+  /** The `store` of the form it disables. */
+  readonly key: object
+}
+
+/**
+ * The disabled state `FormProvider` and `<Form>` give what they wrap, for
+ * their own form only: a field of another form rendered inside (a quick-add
+ * popover) keeps that form's state.
+ */
+const FormDisabledContext = createContext<FormDisabledScope | null>(null)
+
+/**
+ * Whether the form is disabled, by `useForm({ disabled })`,
+ * `<FormProvider disabled>`, `<Form disabled>` or `FormDialog`'s `disabled`.
+ * Every kit field reads it, so a control the fieldset of a disabled dialog
+ * can't reach (a checkbox, a switch, a radio, a slider) turns off too.
+ *
+ * Reads the form of the nearest provider; inside a field, pass `field.form`.
+ * `useForm({ disabled })` applies even where no provider of the form is
+ * mounted.
+ */
+function useIsFormDisabled(form?: AnyFormApi): boolean {
+  const scope = useContext(FormDisabledContext)
+  const contextForm = useContext(formContext) as AnyFormApi | null
+  const key = (form ?? contextForm)?.store
+  const subscribeToKey = useCallback(
+    (listener: () => void) => (key ? subscribe(key, listener) : () => null),
+    [key]
+  )
+  const getSnapshot = () => (key ? (disabledOption.get(key) ?? false) : false)
+  const byOption = useSyncExternalStore(
+    subscribeToKey,
+    getSnapshot,
+    getSnapshot
+  )
+  const byScope =
+    scope?.disabled === true && (key === undefined || scope.key === key)
+  return byScope || byOption
+}
+
+export { FormDisabledContext, useDisabledOption, useIsFormDisabled }

package/src/lib/item-options.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, test } from "vitest"
+
+import { valueKey } from "./item-options"
+
+describe("valueKey", () => {
+  test("keeps values that print alike apart, so React keys don't collide", () => {
+    expect(valueKey(1)).not.toBe(valueKey("1"))
+    expect(valueKey(null)).not.toBe(valueKey("null"))
+    expect(valueKey({ id: 1 })).not.toBe(valueKey('{"id":1}'))
+  })
+})