@zeno-lib/forms 0.6.0 → 0.7.0

package/src/fields/multi-select-field.tsx

@@ -2,6 +2,21 @@
 
 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 {
+  findOption,
+  type ItemGroup,
+  type ItemObject,
+  type ItemOption,
+  type ItemValue,
+  isItemGroup,
+  isSameValue,
+  itemLabel,
+  itemValue,
+  toItemList,
+  type ValueComparator,
+  valueKey,
+} from "@zeno-lib/forms/lib/item-options"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
@@ -9,16 +24,19 @@ import {
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
 import { XIcon } from "lucide-react"
-import { type ReactNode, useId } from "react"
+import { type ReactNode, useId, useMemo } from "react"
 import { Button } from "@/components/ui/button"
 import {
   Combobox,
   ComboboxChip,
   ComboboxChips,
   ComboboxChipsInput,
+  ComboboxCollection,
   ComboboxContent,
   ComboboxEmpty,
+  ComboboxGroup,
   ComboboxItem,
+  ComboboxLabel,
   ComboboxList,
   ComboboxValue,
   useComboboxAnchor,
@@ -31,16 +49,23 @@ import {
 } from "@/components/ui/field"
 import { RequiredIndicator } from "../lib/required-indicator"
 
-type MultiSelectItemObject<V> = { value: V; label: string }
+type MultiSelectItemObject<V> = ItemObject<V>
+
+/** Items under a heading. */
+type MultiSelectItemGroup<T> = ItemGroup<T>
+
+/** An item of `items`, or of one of its groups. */
+type MultiSelectOption<T> = ItemOption<T>
 
 /** The value stored per selected item: `item.value` for objects, else the item. */
-type MultiSelectValue<T> = T extends MultiSelectItemObject<infer V> ? V : T
+type MultiSelectValue<T> = ItemValue<T>
 
 type MultiSelectFieldProps<T = string> = {
   /**
    * Options shown in the dropdown. Pass plain strings or numbers (value ===
    * label), or `{ value, label }` objects. The form value is an array of the
-   * selected values (`item.value` for objects).
+   * selected values (`item.value` for objects). To show them under headings,
+   * pass `{ label, items }` groups instead.
    */
   items: readonly T[]
   description?: ReactNode
@@ -50,7 +75,18 @@ type MultiSelectFieldProps<T = string> = {
   /** Message shown when filtering produces zero matches. */
   emptyMessage?: ReactNode
   /** Override per-row rendering. Default: the item's label. */
-  renderItem?: (item: T) => ReactNode
+  renderItem?: (item: MultiSelectOption<T>) => ReactNode
+  /**
+   * Whether an item's value is a 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: MultiSelectValue<T>,
+    value: MultiSelectValue<T>
+  ): boolean
   /** Show a button that clears every selection. Defaults to `true`. */
   showClear?: boolean
   /** Accessible label of the clear button. Defaults to `"Clear"`. */
@@ -64,23 +100,6 @@ type MultiSelectFieldProps<T = string> = {
   required?: boolean
 }
 
-function isItemObject(item: unknown): item is MultiSelectItemObject<unknown> {
-  return (
-    typeof item === "object" &&
-    item !== null &&
-    "value" in item &&
-    "label" in item
-  )
-}
-
-function itemValue(item: unknown): unknown {
-  return isItemObject(item) ? item.value : item
-}
-
-function itemLabel(item: unknown): string {
-  return isItemObject(item) ? item.label : String(item)
-}
-
 /**
  * Multi-value combobox: the selection renders as removable chips and the form
  * value is an array (`[]` when empty).
@@ -91,6 +110,7 @@ function MultiSelectField<T = string>({
   description,
   disabled,
   emptyMessage = "No results.",
+  isItemEqualToValue,
   items,
   label,
   placeholder,
@@ -99,6 +119,7 @@ function MultiSelectField<T = string>({
   showClear = true,
 }: MultiSelectFieldProps<T>) {
   const field = useFieldContext<MultiSelectValue<T>[] | null | undefined>()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   const anchor = useComboboxAnchor()
   const id = useId()
   const errorId = `${id}-error`
@@ -111,15 +132,47 @@ function MultiSelectField<T = string>({
   const schemaRequiresValue = useIsFieldRequiredBySchema(field)
   const requiresValue = required ?? schemaRequiresValue
 
+  const list = useMemo(() => toItemList(items), [items])
+  const isEqual = isItemEqualToValue as ValueComparator | undefined
+
   const values = field.state.value ?? []
   // Map stored values back to item identities, in selection order, so Base UI
   // compares by reference and the chips keep the order the user picked.
   const selected = values
-    .map((value) => items.find((item) => Object.is(itemValue(item), value)))
-    .filter((item): item is T => item !== undefined)
+    .map((value) => findOption(list, value, isEqual))
+    .filter((option): option is MultiSelectOption<T> => option !== undefined)
+
+  // Base UI only knows the values it has a chip for. Keep the others (their
+  // group still loading) where they were, so picking an option doesn't drop
+  // them.
+  const onValueChange = (next: MultiSelectOption<T>[]) => {
+    const picked = next.map(itemValue)
+    const kept = values.filter(
+      (value) =>
+        findOption(list, value, isEqual) === undefined ||
+        picked.some((other) => isSameValue(other, value, isEqual))
+    )
+    const added = picked.filter(
+      (other) => !values.some((value) => isSameValue(other, value, isEqual))
+    )
+    field.handleChange([...kept, ...added] as MultiSelectValue<T>[])
+  }
+
+  const renderOption = (option: MultiSelectOption<T>) =>
+    renderItem ? (
+      renderItem(option)
+    ) : (
+      <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}
@@ -127,21 +180,19 @@ function MultiSelectField<T = string>({
         </FieldLabel>
       )}
       <Combobox
-        disabled={disabled}
-        items={items}
+        disabled={isDisabled}
+        items={list.items}
         multiple
-        onValueChange={(next: T[]) =>
-          field.handleChange(next.map(itemValue) as MultiSelectValue<T>[])
-        }
+        onValueChange={onValueChange}
         value={selected}
       >
         <ComboboxChips className={className} ref={anchor}>
           <ComboboxValue>
-            {(chips: T[]) => (
+            {(chips: MultiSelectOption<T>[]) => (
               <>
-                {chips.map((item) => (
-                  <ComboboxChip key={String(itemValue(item))}>
-                    {itemLabel(item)}
+                {chips.map((option) => (
+                  <ComboboxChip key={valueKey(itemValue(option))}>
+                    {itemLabel(option)}
                   </ComboboxChip>
                 ))}
                 <ComboboxChipsInput
@@ -159,7 +210,7 @@ function MultiSelectField<T = string>({
               </>
             )}
           </ComboboxValue>
-          {showClear && selected.length > 0 && !disabled && (
+          {showClear && selected.length > 0 && !isDisabled && (
             <Button
               aria-label={clearLabel}
               className="ml-auto"
@@ -175,13 +226,15 @@ function MultiSelectField<T = string>({
         <ComboboxContent anchor={anchor}>
           <ComboboxEmpty>{emptyMessage}</ComboboxEmpty>
           <ComboboxList>
-            {(item: T) =>
-              renderItem ? (
-                renderItem(item)
+            {(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>
               ) : (
-                <ComboboxItem key={String(itemValue(item))} value={item}>
-                  {itemLabel(item)}
-                </ComboboxItem>
+                renderOption(item as MultiSelectOption<T>)
               )
             }
           </ComboboxList>
@@ -197,5 +250,10 @@ function MultiSelectField<T = string>({
   )
 }
 
-export type { MultiSelectFieldProps, MultiSelectItemObject, MultiSelectValue }
+export type {
+  MultiSelectFieldProps,
+  MultiSelectItemGroup,
+  MultiSelectItemObject,
+  MultiSelectValue,
+}
 export { MultiSelectField }

package/src/fields/otp-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,
@@ -61,6 +62,7 @@ function OtpField({
   required,
 }: OtpFieldProps) {
   const field = useFieldContext<string>()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -73,7 +75,11 @@ function OtpField({
   const requiresValue = required ?? schemaRequiresValue
 
   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}
@@ -90,7 +96,7 @@ function OtpField({
         autoFocus={autoFocus}
         className={className}
         containerClassName={containerClassName}
-        disabled={disabled}
+        disabled={isDisabled}
         id={id}
         maxLength={maxLength}
         name={field.name}

package/src/fields/radio-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,
@@ -35,11 +36,13 @@ type RadioGroupFieldProps = Omit<
 function RadioGroupField({
   children,
   description,
+  disabled,
   label,
   required,
   ...props
 }: RadioGroupFieldProps) {
   const field = useFieldContext()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -52,7 +55,11 @@ function RadioGroupField({
   const requiresValue = required ?? schemaRequiresValue
 
   return (
-    <Field data-field={field.name} data-invalid={isInvalid}>
+    <Field
+      data-disabled={isDisabled || undefined}
+      data-field={field.name}
+      data-invalid={isInvalid}
+    >
       {label && (
         <FieldLabel>
           {label}
@@ -66,6 +73,7 @@ function RadioGroupField({
         )}
         aria-invalid={isInvalid || undefined}
         aria-required={requiresValue || undefined}
+        disabled={isDisabled}
         name={field.name}
         onValueChange={(value) => field.handleChange(value)}
         value={field.state.value ?? null}

package/src/fields/reset-button.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useFormContext } from "@zeno-lib/forms/lib/contexts"
+import { useIsFormDisabled } from "@zeno-lib/forms/lib/form-disabled"
 import type { ComponentProps, ReactNode } from "react"
 import { Button } from "@/components/ui/button"
 
@@ -8,12 +9,15 @@ type ResetButtonProps = Omit<ComponentProps<typeof Button>, "onClick" | "type">
 
 function ResetButton({
   children,
+  disabled,
   variant = "outline",
   ...props
 }: ResetButtonProps) {
   const form = useFormContext()
+  const isDisabled = useIsFormDisabled(form) || Boolean(disabled)
   return (
     <Button
+      disabled={isDisabled}
       onClick={() => form.reset()}
       type="button"
       variant={variant}

package/src/fields/select-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,
@@ -44,6 +45,7 @@ type SelectFieldProps = Omit<
 function SelectField({
   children,
   description,
+  disabled,
   label,
   onOpenChange,
   placeholder,
@@ -53,6 +55,7 @@ function SelectField({
   ...props
 }: SelectFieldProps) {
   const field = useFieldContext()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   // Opening the popup moves focus into it, so the trigger's blur would mark
   // the field touched, and show a required error, before anything is picked.
   // The field is touched once the popup closes, or focus leaves it closed.
@@ -82,7 +85,11 @@ function SelectField({
   }, [children])
 
   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}
@@ -90,6 +97,7 @@ function SelectField({
         </FieldLabel>
       )}
       <Select
+        disabled={isDisabled}
         items={items}
         name={field.name}
         onOpenChange={(open, eventDetails) => {

package/src/fields/slider-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,
@@ -37,12 +38,14 @@ type SliderFieldProps = Omit<
 
 function SliderField({
   description,
+  disabled,
   formatValue,
   label,
   required,
   ...props
 }: SliderFieldProps) {
   const field = useFieldContext<SliderValue>()
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -58,7 +61,11 @@ function SliderField({
   const hasReadout = readout !== null && readout !== undefined
 
   return (
-    <Field data-field={field.name} data-invalid={isInvalid}>
+    <Field
+      data-disabled={isDisabled || undefined}
+      data-field={field.name}
+      data-invalid={isInvalid}
+    >
       {(label || hasReadout) && (
         <FieldContent className="flex-row items-center justify-between">
           {label && (
@@ -80,6 +87,7 @@ function SliderField({
           [showError, errorId]
         )}
         aria-invalid={isInvalid || undefined}
+        disabled={isDisabled}
         id={id}
         name={field.name}
         onBlur={field.handleBlur}

package/src/fields/submit-button.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useFormContext } from "@zeno-lib/forms/lib/contexts"
+import { useIsFormDisabled } from "@zeno-lib/forms/lib/form-disabled"
 import type { ComponentProps } from "react"
 import { Button } from "@/components/ui/button"
 import { Spinner } from "@/components/ui/spinner"
@@ -9,13 +10,14 @@ type SubmitButtonProps = Omit<ComponentProps<typeof Button>, "type">
 
 function SubmitButton({ children, disabled, ...props }: SubmitButtonProps) {
   const form = useFormContext()
+  const isDisabled = useIsFormDisabled(form) || Boolean(disabled)
   return (
     <form.Subscribe
       selector={(state) => [state.canSubmit, state.isSubmitting] as const}
     >
       {([canSubmit, isSubmitting]) => (
         <Button
-          disabled={disabled || !canSubmit || isSubmitting}
+          disabled={isDisabled || !canSubmit || isSubmitting}
           type="submit"
           {...props}
         >

package/src/fields/switch-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 SwitchFieldProps = Omit<
 
 function SwitchField({
   description,
+  disabled,
   label,
   required,
   ...props
 }: SwitchFieldProps) {
   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 SwitchField({
 
   return (
     <Field
+      data-disabled={isDisabled || undefined}
       data-field={field.name}
       data-invalid={isInvalid}
       orientation="horizontal"
@@ -78,6 +82,7 @@ function SwitchField({
         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/textarea-field.tsx

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

package/src/form-dialog.test.tsx

@@ -11,7 +11,11 @@ import { type ReactNode, useState } from "react"
 import { afterEach, describe, expect, onTestFinished, test, vi } from "vitest"
 import { z } from "zod"
 import { useForm } from "./create-form"
-import { FormDialog } from "./form-dialog"
+import {
+  type DiscardPromptText,
+  FormDialog,
+  FormDialogProvider,
+} from "./form-dialog"
 import type { ActionResult } from "./lib/action-result"
 import { submitAction } from "./lib/submit-action"
 import { useFormDialog } from "./lib/use-form-dialog"
@@ -51,8 +55,10 @@ function Harness({
   onSubmit = vi.fn(),
   closeOnSubmit,
   disabled,
+  discardPrompt,
   saveFromPrompt,
   submitErrorMessage,
+  submitLabel,
 }: {
   /** Submit through `submitAction` with this server action instead. */
   action?: (values: Values) => Promise<ActionResult<unknown>>
@@ -60,8 +66,10 @@ function Harness({
   onSubmit?: (values: Values) => unknown
   closeOnSubmit?: boolean
   disabled?: boolean
+  discardPrompt?: DiscardPromptText
   saveFromPrompt?: boolean
   submitErrorMessage?: (error: unknown) => ReactNode
+  submitLabel?: ReactNode
 }) {
   const dialog = useFormDialog({ defaultValues: BLANK })
   const form = useForm({
@@ -86,9 +94,11 @@ function Harness({
         closeOnSubmit={closeOnSubmit}
         dialog={dialog}
         disabled={disabled}
+        discardPrompt={discardPrompt}
         form={form}
         saveFromPrompt={saveFromPrompt}
         submitErrorMessage={submitErrorMessage}
+        submitLabel={submitLabel}
         title="Person"
       >
         <InputField label="Name" name="name" />
@@ -650,3 +660,94 @@ describe("FormDialog", () => {
     expect(outer).not.toHaveBeenCalled()
   })
 })
+
+describe("FormDialogProvider", () => {
+  test("sets the defaults of the dialogs below it; a dialog's own prop wins", async () => {
+    const user = userEvent.setup()
+    render(
+      <FormDialogProvider
+        cancelLabel="Abbrechen"
+        discardPrompt={{
+          confirmLabel: "Verwerfen",
+          saveLabel: "Sichern",
+          saveTitle: "Speichern?",
+          title: "Verwerfen?",
+        }}
+      >
+        <FormDialogProvider saveFromPrompt submitLabel="Speichern">
+          <Harness discardPrompt={{ title: "Leave this person?" }} />
+        </FormDialogProvider>
+      </FormDialogProvider>
+    )
+    const name = await openEdit(user)
+    const dialog = screen.getByRole("dialog")
+    within(dialog).getByRole("button", { name: "Speichern" })
+    await user.type(name, "!")
+    await user.click(within(dialog).getByRole("button", { name: "Abbrechen" }))
+
+    // The prompt's copy merges key by key, and the nearest level wins: the
+    // dialog's title over the outer provider's `saveTitle`, its Discard
+    // label, and Save labelled by the inner provider's `submitLabel` over the
+    // outer one's `saveLabel`.
+    const prompt = await screen.findByRole("alertdialog")
+    within(prompt).getByText("Leave this person?")
+    within(prompt).getByRole("button", { name: "Verwerfen" })
+    within(prompt).getByRole("button", { name: "Speichern" })
+  })
+
+  test.each([
+    [true, "Unsaved changes", "Save them before you leave?"],
+    [false, "Discard changes?", "They will be lost."],
+  ])(
+    "a provider words the prompt for each mode (saveFromPrompt: %s)",
+    async (saveFromPrompt, title, description) => {
+      const user = userEvent.setup()
+      render(
+        <FormDialogProvider
+          discardPrompt={{
+            description: "They will be lost.",
+            saveDescription: "Save them before you leave?",
+            saveTitle: "Unsaved changes",
+            title: "Discard changes?",
+          }}
+        >
+          <Harness saveFromPrompt={saveFromPrompt} />
+        </FormDialogProvider>
+      )
+      const name = await openEdit(user)
+      await user.type(name, "!")
+      await user.keyboard("{Escape}")
+      const prompt = await screen.findByRole("alertdialog")
+      within(prompt).getByText(title)
+      within(prompt).getByText(description)
+    }
+  )
+
+  test("a dialog's submitLabel labels the prompt's Save over a provider's saveLabel", async () => {
+    const user = userEvent.setup()
+    render(
+      <FormDialogProvider discardPrompt={{ saveLabel: "Speichern" }}>
+        <Harness saveFromPrompt submitLabel="Create invoice" />
+      </FormDialogProvider>
+    )
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    await user.keyboard("{Escape}")
+    const prompt = await screen.findByRole("alertdialog")
+    within(prompt).getByRole("button", { name: "Create invoice" })
+  })
+
+  test("a dialog's own false wins over the provider's true", async () => {
+    const user = userEvent.setup()
+    render(
+      <FormDialogProvider saveFromPrompt>
+        <Harness saveFromPrompt={false} />
+      </FormDialogProvider>
+    )
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    await user.keyboard("{Escape}")
+    const prompt = await screen.findByRole("alertdialog")
+    expect(within(prompt).queryByRole("button", { name: "Save" })).toBeNull()
+  })
+})