@zeno-lib/forms 0.6.0 → 0.7.1

package/src/default-props.test.tsx

@@ -0,0 +1,165 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { createZenoForm } from "./create-zeno-form"
+import { FormError } from "./fields/form-error"
+import { InputField } from "./fields/input-field"
+import { MoneyField } from "./fields/money-field"
+import { SubmitButton } from "./fields/submit-button"
+import { FormDialog } from "./form-dialog"
+import { Form, FormProvider } from "./form-element"
+import { useFormDialog } from "./lib/use-form-dialog"
+
+afterEach(() => {
+  cleanup()
+  vi.unstubAllGlobals()
+})
+
+const { useForm } = createZenoForm({
+  defaultProps: {
+    FormError: { submitErrorMessage: "Not saved. Try again later." },
+    MoneyField: { currency: "CHF", currencyDisplay: "code", placeholder: "0" },
+  },
+  fieldComponents: { InputField, MoneyField },
+  formComponents: { FormError, SubmitButton },
+})
+
+const VALUES = {
+  amount: null as number | null,
+  fee: null as number | null,
+  name: "",
+  total: null as number | null,
+}
+
+function Harness({ onSubmit = vi.fn() }: { onSubmit?: () => unknown }) {
+  const form = useForm({ defaultValues: VALUES, onSubmit })
+  const unset: string | undefined = undefined
+  return (
+    <FormProvider form={form}>
+      <Form>
+        <form.MoneyField label="Amount" name="amount" />
+        <form.MoneyField currency="EUR" label="Fee" name="fee" />
+        <form.MoneyField currency={unset} label="Total" name="total" />
+        <form.InputField label="Name" name="name" />
+        <form.FormError />
+        <form.SubmitButton>Submit</form.SubmitButton>
+      </Form>
+    </FormProvider>
+  )
+}
+
+function addonOf(label: string) {
+  return screen
+    .getByLabelText(label)
+    .closest("[data-slot=input-group]")
+    ?.querySelector("[data-slot=input-group-addon]")?.textContent
+}
+
+describe("createZenoForm({ defaultProps })", () => {
+  test("a field renders with its defaults, and a prop passed at the call site wins", () => {
+    render(<Harness />)
+    expect(addonOf("Amount")).toBe("CHF")
+    expect(addonOf("Fee")).toBe("EUR")
+  })
+
+  test("a prop passed as undefined keeps the default", () => {
+    render(<Harness />)
+    expect(addonOf("Total")).toBe("CHF")
+  })
+
+  test("a component with no defaults renders as before", () => {
+    render(<Harness />)
+    expect(screen.getByLabelText("Amount").getAttribute("placeholder")).toBe(
+      "0"
+    )
+    // InputField shares MoneyField's props, but not its defaults.
+    expect(screen.getByLabelText("Name").hasAttribute("placeholder")).toBe(
+      false
+    )
+  })
+
+  test("a form component renders with its defaults", async () => {
+    vi.stubGlobal("reportError", vi.fn())
+    const user = userEvent.setup()
+    render(
+      <Harness
+        onSubmit={() => {
+          throw new Error("offline")
+        }}
+      />
+    )
+    await user.click(screen.getByRole("button", { name: "Submit" }))
+    expect((await screen.findByRole("alert")).textContent).toBe(
+      "Not saved. Try again later."
+    )
+  })
+
+  test("a FormDialog renders the form's FormError, with its defaults", async () => {
+    vi.stubGlobal("reportError", vi.fn())
+    const user = userEvent.setup()
+    function DialogHarness() {
+      const dialog = useFormDialog({ defaultValues: VALUES })
+      const form = useForm({
+        defaultValues: dialog.defaultValues,
+        onSubmit: () => {
+          throw new Error("offline")
+        },
+      })
+      return (
+        <>
+          <button onClick={() => dialog.open()} type="button">
+            New
+          </button>
+          <FormDialog dialog={dialog} form={form} title="Payment">
+            <form.InputField label="Name" name="name" />
+          </FormDialog>
+        </>
+      )
+    }
+    render(<DialogHarness />)
+    await user.click(screen.getByRole("button", { name: "New" }))
+    await user.click(await screen.findByRole("button", { name: "Save" }))
+    expect((await screen.findByRole("alert")).textContent).toBe(
+      "Not saved. Try again later."
+    )
+  })
+
+  test("a component with defaults keeps its statics", () => {
+    function Hint({ text = "None" }: { text?: string }) {
+      return <p>{text}</p>
+    }
+    Hint.Icon = () => <span>i</span>
+    const { useForm: useHintForm } = createZenoForm({
+      defaultProps: { Hint: { text: "Marked fields are required" } },
+      fieldComponents: { InputField },
+      formComponents: { Hint },
+    })
+    function HintHarness() {
+      const form = useHintForm({ defaultValues: {}, onSubmit: vi.fn() })
+      return (
+        <FormProvider form={form}>
+          <form.Hint />
+          <form.Hint.Icon />
+        </FormProvider>
+      )
+    }
+    render(<HintHarness />)
+    screen.getByText("Marked fields are required")
+    screen.getByText("i")
+  })
+
+  test("a field rendered through AppField gets its defaults too", () => {
+    function AppFieldHarness() {
+      const form = useForm({ defaultValues: VALUES, onSubmit: vi.fn() })
+      return (
+        <FormProvider form={form}>
+          <form.AppField name="amount">
+            {(field) => <field.MoneyField label="Amount" />}
+          </form.AppField>
+        </FormProvider>
+      )
+    }
+    render(<AppFieldHarness />)
+    expect(addonOf("Amount")).toBe("CHF")
+  })
+})

package/src/fields/checkbox-field.tsx

@@ -2,6 +2,7 @@
 
 import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { useIsFormDisabled } from "@zeno-lib/forms/lib/form-disabled"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
@@ -34,11 +35,13 @@ type CheckboxFieldProps = Omit<
 
 function CheckboxField({
   description,
+  disabled,
   label,
   required,
   ...props
 }: CheckboxFieldProps) {
   const field = useFieldContext<boolean>()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -52,6 +55,7 @@ function CheckboxField({
 
   return (
     <Field
+      data-disabled={isDisabled || undefined}
       data-field={field.name}
       data-invalid={isInvalid}
       orientation="horizontal"
@@ -64,6 +68,7 @@ function CheckboxField({
         aria-invalid={isInvalid || undefined}
         aria-required={requiresValue || undefined}
         checked={field.state.value ?? false}
+        disabled={isDisabled}
         id={id}
         name={field.name}
         onBlur={field.handleBlur}

package/src/fields/checkbox-group-field.tsx

@@ -2,6 +2,7 @@
 
 import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { useIsFormDisabled } from "@zeno-lib/forms/lib/form-disabled"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
@@ -64,6 +65,7 @@ function CheckboxGroupField<V = string>({
   required,
 }: CheckboxGroupFieldProps<V>) {
   const field = useFieldContext<V[] | null | undefined>()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -97,9 +99,10 @@ function CheckboxGroupField<V = string>({
       )}
       aria-invalid={isInvalid || undefined}
       className={className}
+      data-disabled={isDisabled || undefined}
       data-field={field.name}
       data-invalid={isInvalid}
-      disabled={disabled}
+      disabled={isDisabled}
     >
       {label && (
         <FieldLegend variant="label">
@@ -120,6 +123,7 @@ function CheckboxGroupField<V = string>({
           const optionId = `${id}-${index}`
           return (
             <Field
+              data-disabled={isDisabled || option.disabled || undefined}
               data-invalid={isInvalid}
               key={String(option.value)}
               orientation="horizontal"
@@ -127,7 +131,7 @@ function CheckboxGroupField<V = string>({
               <Checkbox
                 aria-invalid={isInvalid || undefined}
                 checked={checked.includes(option.value)}
-                disabled={disabled || option.disabled}
+                disabled={isDisabled || option.disabled}
                 id={optionId}
                 name={field.name}
                 onBlur={field.handleBlur}

package/src/fields/combobox-field.tsx

@@ -3,19 +3,38 @@
 import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
+import { useIsFormDisabled } from "@zeno-lib/forms/lib/form-disabled"
+import {
+  findOption,
+  type ItemGroup,
+  type ItemObject,
+  type ItemOption,
+  type ItemValue,
+  isItemGroup,
+  isItemObject,
+  isSameValue,
+  itemLabel,
+  itemValue,
+  toItemList,
+  type ValueComparator,
+  valueKey,
+} from "@zeno-lib/forms/lib/item-options"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
   useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
-import { type ReactNode, useId } from "react"
+import { type ReactNode, useId, useMemo, useState } from "react"
 import {
   Combobox,
+  ComboboxCollection,
   ComboboxContent,
   ComboboxEmpty,
+  ComboboxGroup,
   ComboboxInput,
   ComboboxItem,
+  ComboboxLabel,
   ComboboxList,
 } from "@/components/ui/combobox"
 import {
@@ -28,13 +47,23 @@ import { InputGroupAddon } from "@/components/ui/input-group"
 import { Spinner } from "@/components/ui/spinner"
 import { RequiredIndicator } from "../lib/required-indicator"
 
-type ComboboxItemObject<V> = { value: V; label: string }
+type ComboboxItemObject<V> = ItemObject<V>
+
+/** Items under a heading. */
+type ComboboxItemGroup<T> = ItemGroup<T>
+
+/** An item of `items`, or of one of its groups. */
+type ComboboxOption<T> = ItemOption<T>
+
+/** What picking an item stores: `item.value` for an object, else the item. */
+type ComboboxOptionValue<T> = ItemValue<T>
 
 type ComboboxFieldProps<T = string> = {
   /**
    * Items shown in the dropdown. Pass plain strings (value === label) or
    * `{ value, label }` objects when the value isn't a string (e.g. numeric
-   * database IDs).
+   * database IDs, or an object). To show them under headings, pass
+   * `{ label, items }` groups instead.
    */
   items: readonly T[]
   description?: ReactNode
@@ -43,7 +72,18 @@ type ComboboxFieldProps<T = string> = {
   /** Message shown when filtering produces zero matches. */
   emptyMessage?: ReactNode
   /** Override per-row rendering. Default: plain `<ComboboxItem>{label}</ComboboxItem>`. */
-  renderItem?: (item: T) => ReactNode
+  renderItem?: (item: ComboboxOption<T>) => ReactNode
+  /**
+   * Whether an item's value is the stored value. Defaults to `Object.is`.
+   * Pass it when the values are objects (`{ kind, id }`), which a reload or a
+   * refetch rebuilds: `(a, b) => a.kind === b.kind && a.id === b.id`. Never
+   * called with an empty value.
+   */
+  // biome-ignore lint/style/useConsistentMethodSignatures: a method's parameters are bivariant, so a comparator typed with the value fits `form.<Field>`, whose props see the items as `unknown`.
+  isItemEqualToValue?(
+    itemValue: ComboboxOptionValue<T>,
+    value: ComboboxOptionValue<T>
+  ): boolean
   /**
    * Show the clear button when a value is selected. Defaults to `true` on an
    * optional field and `false` on a required one (from the schema or
@@ -68,7 +108,7 @@ type ComboboxFieldProps<T = string> = {
    * Replace Base UI's built-in client-side filter. Pass `null` for
    * server-driven search where `items` is already filtered by the consumer.
    */
-  filter?: ((item: T, query: string) => boolean) | null
+  filter?: ((item: ComboboxOption<T>, query: string) => boolean) | null
   /**
    * Show a spinner addon inside the input while options are being fetched.
    * Pair with `onInputValueChange` to drive a debounced server query.
@@ -76,13 +116,24 @@ type ComboboxFieldProps<T = string> = {
   loading?: boolean
 }
 
-function isItemObject(item: unknown): item is ComboboxItemObject<unknown> {
-  return (
-    typeof item === "object" &&
-    item !== null &&
-    "value" in item &&
-    "label" in item
-  )
+// Base UI copies the selected label into the input whenever `value` is a new
+// object, so items rebuilt on every render (mapped from fetched rows) would
+// overwrite what the user types. Keep the item found until it stands for
+// another value or label.
+function useHeldOption<O>(
+  match: O | undefined,
+  isEqual: ValueComparator | undefined
+): O | undefined {
+  const [held, setHeld] = useState(match)
+  const keepsHeld =
+    held !== undefined &&
+    match !== undefined &&
+    isSameValue(itemValue(held), itemValue(match), isEqual) &&
+    itemLabel(held) === itemLabel(match)
+  if (held !== match && !keepsHeld) {
+    setHeld(match)
+  }
+  return keepsHeld ? held : match
 }
 
 function ComboboxField<T = string>({
@@ -92,6 +143,7 @@ function ComboboxField<T = string>({
   emptyMessage = "No results.",
   filter,
   inputValue,
+  isItemEqualToValue,
   items,
   label,
   loading,
@@ -102,6 +154,7 @@ function ComboboxField<T = string>({
   showClear,
 }: ComboboxFieldProps<T>) {
   const field = useFieldContext()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -114,37 +167,57 @@ function ComboboxField<T = string>({
   const requiresValue = required ?? schemaRequiresValue
   const canClear = showClear ?? !requiresValue
 
+  const list = useMemo(() => toItemList(items), [items])
+  const isEqual = isItemEqualToValue as ValueComparator | undefined
+
   const fieldValue = field.state.value
   // Base UI shows the value it gets as text, so a stored id whose item isn't
   // in `items` (options still loading, or a search that dropped it) would
   // show raw. Only a plain string or number item is its own label.
-  const match = items.find(
-    (item) => (isItemObject(item) ? item.value : item) === fieldValue
-  )
-  const plainItems = items.length > 0 && !items.some(isItemObject)
+  const match = useHeldOption(findOption(list, fieldValue, isEqual), isEqual)
+  const plainItems = list.options.length > 0 && !list.options.some(isItemObject)
   const value = (match ??
-    (plainItems ? (fieldValue ?? null) : null)) as T | null
+    (plainItems ? (fieldValue ?? null) : null)) as ComboboxOption<T> | null
+
+  const renderOption = (option: ComboboxOption<T>) => {
+    if (renderItem) {
+      return renderItem(option)
+    }
+    return (
+      <ComboboxItem key={valueKey(itemValue(option))} value={option}>
+        {itemLabel(option)}
+      </ComboboxItem>
+    )
+  }
 
   return (
-    <Field data-field={field.name} data-invalid={isInvalid}>
+    <Field
+      data-disabled={isDisabled || undefined}
+      data-field={field.name}
+      data-invalid={isInvalid}
+    >
       {label && (
         <FieldLabel htmlFor={id}>
           {label}
           {isRequired && <RequiredIndicator />}
         </FieldLabel>
       )}
-      <Combobox
-        disabled={disabled}
+      <Combobox<ComboboxOption<T>>
+        disabled={isDisabled}
         filter={filter}
         inputValue={inputValue}
-        items={items}
+        // The held item may be one `items` no longer has.
+        isItemEqualToValue={(item, selected) =>
+          isSameValue(itemValue(item), itemValue(selected), isEqual)
+        }
+        items={list.items}
         onInputValueChange={onInputValueChange}
         onValueChange={(next) => {
           if (next === null) {
             field.handleChange(getEmptyValue(field, undefined))
             return
           }
-          field.handleChange(isItemObject(next) ? next.value : next)
+          field.handleChange(itemValue(next))
         }}
         value={value}
       >
@@ -156,7 +229,7 @@ function ComboboxField<T = string>({
           aria-invalid={isInvalid || undefined}
           aria-required={requiresValue || undefined}
           className={className}
-          disabled={disabled}
+          disabled={isDisabled}
           id={id}
           name={field.name}
           onBlur={field.handleBlur}
@@ -172,23 +245,17 @@ function ComboboxField<T = string>({
         <ComboboxContent>
           <ComboboxEmpty>{emptyMessage}</ComboboxEmpty>
           <ComboboxList>
-            {(item: T) => {
-              if (renderItem) {
-                return renderItem(item)
-              }
-              if (isItemObject(item)) {
-                return (
-                  <ComboboxItem key={String(item.value)} value={item}>
-                    {item.label}
-                  </ComboboxItem>
-                )
-              }
-              return (
-                <ComboboxItem key={String(item)} value={item}>
-                  {String(item)}
-                </ComboboxItem>
+            {(item: T, index: number) =>
+              isItemGroup(item) ? (
+                // Two groups can share a heading, or have none.
+                <ComboboxGroup items={item.items} key={index}>
+                  {item.label && <ComboboxLabel>{item.label}</ComboboxLabel>}
+                  <ComboboxCollection>{renderOption}</ComboboxCollection>
+                </ComboboxGroup>
+              ) : (
+                renderOption(item as ComboboxOption<T>)
               )
-            }}
+            }
           </ComboboxList>
         </ComboboxContent>
       </Combobox>
@@ -202,5 +269,5 @@ function ComboboxField<T = string>({
   )
 }
 
-export type { ComboboxFieldProps, ComboboxItemObject }
+export type { ComboboxFieldProps, ComboboxItemGroup, ComboboxItemObject }
 export { ComboboxField }

package/src/fields/date-picker-field.tsx

@@ -2,7 +2,13 @@
 
 import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  type DateValueType,
+  parseDateValue,
+  toDateValue,
+} from "@zeno-lib/forms/lib/date-value"
 import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
+import { useIsFormDisabled } from "@zeno-lib/forms/lib/form-disabled"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
@@ -47,6 +53,15 @@ type DatePickerFieldProps = {
    * the `*`, and picking its selected day again keeps it instead of clearing.
    */
   required?: boolean
+  /**
+   * What the form value is. Whatever it is, the field reads a stored `Date`
+   * or ISO string.
+   * - `"date"` (default): a `Date`, at local midnight of the picked day.
+   * - `"iso-date"`: the day as `YYYY-MM-DD`, for a `date` column.
+   * - `"iso-datetime"`: the day's local midnight as an ISO 8601 timestamp
+   *   (`toISOString()`), for a timestamp column.
+   */
+  valueType?: DateValueType
 }
 
 const FALLBACK_PLACEHOLDER = "Pick a date"
@@ -68,8 +83,10 @@ function DatePickerField({
   placeholder = FALLBACK_PLACEHOLDER,
   required,
   triggerClassName,
+  valueType = "date",
 }: DatePickerFieldProps) {
-  const field = useFieldContext<Date | undefined>()
+  const field = useFieldContext<Date | string | null | undefined>()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   // Opening the popover moves focus into it, so the trigger's blur would mark
   // the field touched, and show a required error, before a day is picked.
   // The field is touched once the popover closes, or focus leaves it closed.
@@ -85,11 +102,14 @@ function DatePickerField({
   const schemaRequiresValue = useIsFieldRequiredBySchema(field)
   const requiresValue = required ?? schemaRequiresValue
 
-  const { value } = field.state
-  const empty = !value
+  const date = parseDateValue(field.state.value)
 
   return (
-    <Field data-field={field.name} data-invalid={isInvalid}>
+    <Field
+      data-disabled={isDisabled || undefined}
+      data-field={field.name}
+      data-invalid={isInvalid}
+    >
       {label && (
         <FieldLabel htmlFor={id}>
           {label}
@@ -115,8 +135,8 @@ function DatePickerField({
             "w-full justify-start text-left font-normal data-[empty=true]:text-muted-foreground",
             triggerClassName
           )}
-          data-empty={empty || undefined}
-          disabled={disabled}
+          data-empty={date ? undefined : true}
+          disabled={isDisabled}
           id={id}
           onBlur={() => {
             if (!isOpen.current) {
@@ -125,16 +145,21 @@ function DatePickerField({
           }}
         >
           <CalendarIcon />
-          {empty ? <span>{placeholder}</span> : formatValue(value)}
+          {date ? formatValue(date) : <span>{placeholder}</span>}
         </PopoverTrigger>
         <PopoverContent className="w-auto p-0">
           <Calendar
+            defaultMonth={date}
             mode="single"
             onSelect={(next: Date | undefined) =>
-              field.handleChange(next ?? getEmptyValue(field, undefined))
+              field.handleChange(
+                next
+                  ? toDateValue(next, valueType)
+                  : getEmptyValue(field, undefined)
+              )
             }
             required={requiresValue}
-            selected={value}
+            selected={date}
             {...calendarProps}
           />
         </PopoverContent>
@@ -155,7 +180,6 @@ function CalendarIcon() {
       aria-hidden
       className="size-4 shrink-0 opacity-60"
       fill="none"
-      role="img"
       stroke="currentColor"
       strokeLinecap="round"
       strokeLinejoin="round"
@@ -163,7 +187,6 @@ function CalendarIcon() {
       viewBox="0 0 24 24"
       xmlns="http://www.w3.org/2000/svg"
     >
-      <title>Calendar</title>
       <path d="M8 2v3M16 2v3M3 10h18M5 4h14a2 2 0 012 2v14a2 2 0 01-2 2H5a2 2 0 01-2-2V6a2 2 0 012-2z" />
     </svg>
   )

package/src/fields/field-shell.tsx

@@ -24,6 +24,8 @@ type FieldShellProps = Pick<
   /** The control, bound with `useFieldControl`'s `controlProps`. */
   children: ReactNode
   description?: ReactNode
+  /** Dims the label. `useFieldControl` returns it. */
+  isDisabled?: boolean
   label?: ReactNode
 }
 
@@ -46,6 +48,7 @@ function FieldShell({
   errorId,
   errors,
   id,
+  isDisabled,
   isInvalid,
   label,
   labelId,
@@ -53,7 +56,11 @@ function FieldShell({
   showRequiredIndicator,
 }: FieldShellProps) {
   return (
-    <Field data-field={name} data-invalid={isInvalid}>
+    <Field
+      data-disabled={isDisabled || undefined}
+      data-field={name}
+      data-invalid={isInvalid}
+    >
       {label && (
         <FieldLabel htmlFor={id} id={labelId}>
           {label}

package/src/fields/input-field.tsx

@@ -24,6 +24,7 @@ type InputFieldProps = Omit<
 function InputField({
   children,
   description,
+  disabled,
   label,
   required,
   ...props
@@ -33,6 +34,7 @@ function InputField({
   // `aria-labelledby` and the hook doesn't get `label`.
   const { controlProps, ...shell } = useFieldControl<string>({
     description,
+    disabled,
     required,
   })
   const hasAddons = Children.count(children) > 0