@zeno-lib/forms 0.5.0 → 0.7.0

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/control-field.tsx

@@ -0,0 +1,57 @@
+"use client"
+
+import {
+  type FieldControlProps,
+  useFieldControl,
+} from "@zeno-lib/forms/lib/use-field-control"
+import type { ReactNode } from "react"
+import { FieldShell } from "./field-shell"
+
+type ControlFieldProps<TValue = unknown> = {
+  description?: ReactNode
+  disabled?: boolean
+  label?: ReactNode
+  /**
+   * Renders the control, given the props that bind it to the field: `id`,
+   * `name`, `value`, `onChange(value)`, `onBlur`, `disabled` and the
+   * `aria-*`. Spread them on a control that takes its value that way, or map
+   * them for one that doesn't. Keep `aria-invalid` on the focusable element
+   * (or a group root around it): a failed submit focuses the first invalid
+   * field by it.
+   */
+  render: (control: FieldControlProps<TValue>) => ReactNode
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
+  required?: boolean
+}
+
+/**
+ * Binds a controlled component the kit has no field for (a phone input, a
+ * star rating, a color picker) in the kit's field layout. Clearing it stores
+ * the field's empty value, as the kit's fields do.
+ */
+function ControlField<TValue = unknown>({
+  description,
+  disabled,
+  label,
+  render,
+  required,
+}: ControlFieldProps<TValue>) {
+  const { controlProps, ...shell } = useFieldControl<TValue>({
+    description,
+    disabled,
+    label,
+    required,
+  })
+
+  return (
+    <FieldShell {...shell} description={description} label={label}>
+      {render(controlProps)}
+    </FieldShell>
+  )
+}
+
+export type { ControlFieldProps }
+export { ControlField }

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

@@ -0,0 +1,80 @@
+"use client"
+
+import type { FieldControl } from "@zeno-lib/forms/lib/use-field-control"
+import type { ReactNode } from "react"
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@/components/ui/field"
+import { RequiredIndicator } from "../lib/required-indicator"
+
+type FieldShellProps = Pick<
+  FieldControl,
+  | "descriptionId"
+  | "errorId"
+  | "errors"
+  | "id"
+  | "isInvalid"
+  | "labelId"
+  | "name"
+  | "showRequiredIndicator"
+> & {
+  /** The control, bound with `useFieldControl`'s `controlProps`. */
+  children: ReactNode
+  description?: ReactNode
+  /** Dims the label. `useFieldControl` returns it. */
+  isDisabled?: boolean
+  label?: ReactNode
+}
+
+/**
+ * The field layout every kit field shares: the label with its `*`, the
+ * control, the description and the error, tied together by the ids
+ * `useFieldControl` returns. Spread the rest of its result here:
+ *
+ * ```tsx
+ * const { controlProps, ...shell } = useFieldControl({ description, label })
+ * <FieldShell {...shell} description={description} label={label}>
+ *   <MyControl {...controlProps} />
+ * </FieldShell>
+ * ```
+ */
+function FieldShell({
+  children,
+  description,
+  descriptionId,
+  errorId,
+  errors,
+  id,
+  isDisabled,
+  isInvalid,
+  label,
+  labelId,
+  name,
+  showRequiredIndicator,
+}: FieldShellProps) {
+  return (
+    <Field
+      data-disabled={isDisabled || undefined}
+      data-field={name}
+      data-invalid={isInvalid}
+    >
+      {label && (
+        <FieldLabel htmlFor={id} id={labelId}>
+          {label}
+          {showRequiredIndicator && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      {children}
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {errors.length > 0 && <FieldError errors={errors} id={errorId} />}
+    </Field>
+  )
+}
+
+export type { FieldShellProps }
+export { FieldShell }

package/src/fields/index.ts

@@ -2,8 +2,10 @@
 export * from "./checkbox-field"
 export * from "./checkbox-group-field"
 export * from "./combobox-field"
+export * from "./control-field"
 export * from "./date-picker-field"
 export * from "./email-field"
+export * from "./field-shell"
 export * from "./form-error"
 export * from "./input-field"
 export * from "./money-field"