@zeno-lib/forms 0.5.0 → 0.7.0

package/src/fields/input-field.tsx

@@ -1,23 +1,11 @@
 "use client"
 
-import { describedBy } from "@zeno-lib/forms/lib/aria"
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsFieldRequiredBySchema,
-  useIsInvalid,
-} from "@zeno-lib/forms/lib/use-is-invalid"
-import { Children, type ComponentProps, type ReactNode, useId } from "react"
-import {
-  Field,
-  FieldDescription,
-  FieldError,
-  FieldLabel,
-} from "@/components/ui/field"
+import { useFieldControl } from "@zeno-lib/forms/lib/use-field-control"
+import { Children, type ComponentProps, type ReactNode } from "react"
 import { Input } from "@/components/ui/input"
 import { InputGroup, InputGroupInput } from "@/components/ui/input-group"
-import { RequiredIndicator } from "../lib/required-indicator"
+import { FieldShell } from "./field-shell"
 
 type InputFieldProps = Omit<
   ComponentProps<typeof Input>,
@@ -36,33 +24,25 @@ type InputFieldProps = Omit<
 function InputField({
   children,
   description,
+  disabled,
   label,
   required,
   ...props
 }: InputFieldProps) {
   const field = useFieldContext<string>()
-  const id = useId()
-  const errorId = `${id}-error`
-  const descriptionId = `${id}-description`
-  const isInvalid = useIsInvalid(field)
-  const hideErrors = useHideFieldErrors(field)
-  const showError = isInvalid && !hideErrors
+  // The label names the input through `htmlFor`, so the input needs no
+  // `aria-labelledby` and the hook doesn't get `label`.
+  const { controlProps, ...shell } = useFieldControl<string>({
+    description,
+    disabled,
+    required,
+  })
   const hasAddons = Children.count(children) > 0
-  const schemaRequired = useIsFieldRequired(field)
-  const isRequired = required ?? schemaRequired
-  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
-  const requiresValue = required ?? schemaRequiresValue
 
+  // A text input keeps the `""` the user typed, where `controlProps.onChange`
+  // would store the field's empty value.
   const inputProps = {
-    "aria-describedby": describedBy(
-      [description, descriptionId],
-      [showError, errorId]
-    ),
-    "aria-invalid": isInvalid || undefined,
-    "aria-required": requiresValue || undefined,
-    id,
-    name: field.name,
-    onBlur: field.handleBlur,
+    ...controlProps,
     onChange: (event: React.ChangeEvent<HTMLInputElement>) =>
       field.handleChange(event.target.value),
     value: field.state.value ?? "",
@@ -70,13 +50,7 @@ function InputField({
   }
 
   return (
-    <Field data-field={field.name} data-invalid={isInvalid}>
-      {label && (
-        <FieldLabel htmlFor={id}>
-          {label}
-          {isRequired && <RequiredIndicator />}
-        </FieldLabel>
-      )}
+    <FieldShell {...shell} description={description} label={label}>
       {hasAddons ? (
         <InputGroup>
           <InputGroupInput {...inputProps} />
@@ -85,13 +59,7 @@ function InputField({
       ) : (
         <Input {...inputProps} />
       )}
-      {description && (
-        <FieldDescription id={descriptionId}>{description}</FieldDescription>
-      )}
-      {showError && (
-        <FieldError errors={field.state.meta.errors} id={errorId} />
-      )}
-    </Field>
+    </FieldShell>
   )
 }
 

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}