@zeno-lib/forms 0.3.0 → 0.4.0

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

@@ -2,12 +2,14 @@
 
 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 {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
-import { type ComponentProps, type ReactNode, useId } from "react"
+import { type ComponentProps, type ReactNode, useId, useRef } from "react"
 import { buttonVariants } from "@/components/ui/button"
 import { Calendar } from "@/components/ui/calendar"
 import {
@@ -35,8 +37,15 @@ type DatePickerFieldProps = {
   formatValue?: (date: Date) => string
   triggerClassName?: string
   /** Pass-through to the underlying `<Calendar>` (e.g. `disabled`, `locale`). */
-  calendarProps?: Omit<CalendarProps, "mode" | "onSelect" | "selected">
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  calendarProps?: Omit<
+    CalendarProps,
+    "mode" | "onSelect" | "required" | "selected"
+  >
+  disabled?: boolean
+  /**
+   * Mark the field required, or not, over the schema. A required date shows
+   * the `*`, and picking its selected day again keeps it instead of clearing.
+   */
   required?: boolean
 }
 
@@ -53,6 +62,7 @@ function defaultFormat(date: Date): string {
 function DatePickerField({
   calendarProps,
   description,
+  disabled,
   formatValue = defaultFormat,
   label,
   placeholder = FALLBACK_PLACEHOLDER,
@@ -60,6 +70,10 @@ function DatePickerField({
   triggerClassName,
 }: DatePickerFieldProps) {
   const field = useFieldContext<Date | undefined>()
+  // 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.
+  const isOpen = useRef<boolean>(false)
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -68,6 +82,8 @@ function DatePickerField({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   const { value } = field.state
   const empty = !value
@@ -80,7 +96,14 @@ function DatePickerField({
           {isRequired && <RequiredIndicator />}
         </FieldLabel>
       )}
-      <Popover>
+      <Popover
+        onOpenChange={(open) => {
+          isOpen.current = open
+          if (!open) {
+            field.handleBlur()
+          }
+        }}
+      >
         <PopoverTrigger
           aria-describedby={describedBy(
             [description, descriptionId],
@@ -93,11 +116,13 @@ function DatePickerField({
             triggerClassName
           )}
           data-empty={empty || undefined}
+          disabled={disabled}
           id={id}
-          // Base UI's Popover handles open state — we still need blur on the
-          // form's reactive store. Passing onBlur here mirrors how `<select>`
-          // commits on close.
-          onBlur={field.handleBlur}
+          onBlur={() => {
+            if (!isOpen.current) {
+              field.handleBlur()
+            }
+          }}
         >
           <CalendarIcon />
           {empty ? <span>{placeholder}</span> : formatValue(value)}
@@ -105,7 +130,10 @@ function DatePickerField({
         <PopoverContent className="w-auto p-0">
           <Calendar
             mode="single"
-            onSelect={(next) => field.handleChange(next)}
+            onSelect={(next: Date | undefined) =>
+              field.handleChange(next ?? getEmptyValue(field, undefined))
+            }
+            required={requiresValue}
             selected={value}
             {...calendarProps}
           />

package/src/fields/email-field.tsx

@@ -2,16 +2,24 @@ import { InputField, type InputFieldProps } from "./input-field"
 
 type EmailFieldProps = Omit<InputFieldProps, "inputMode" | "type">
 
+// An address is typed as is: no capital first letter, autocorrect or spell
+// check.
 function EmailField({
+  autoCapitalize = "none",
   autoComplete = "email",
+  autoCorrect = "off",
   label = "Email",
+  spellCheck = false,
   ...props
 }: EmailFieldProps) {
   return (
     <InputField
+      autoCapitalize={autoCapitalize}
       autoComplete={autoComplete}
+      autoCorrect={autoCorrect}
       inputMode="email"
       label={label}
+      spellCheck={spellCheck}
       type="email"
       {...props}
     />

package/src/fields/input-field.tsx

@@ -5,6 +5,7 @@ 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"
@@ -26,8 +27,8 @@ type InputFieldProps = Omit<
   description?: ReactNode
   label?: ReactNode
   /**
-   * Force the required `*` indicator on or off for this field. When omitted,
-   * the value is derived from the form's schema.
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
    */
   required?: boolean
 }
@@ -49,6 +50,8 @@ function InputField({
   const hasAddons = Children.count(children) > 0
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   const inputProps = {
     "aria-describedby": describedBy(
@@ -56,6 +59,7 @@ function InputField({
       [showError, errorId]
     ),
     "aria-invalid": isInvalid || undefined,
+    "aria-required": requiresValue || undefined,
     id,
     name: field.name,
     onBlur: field.handleBlur,

package/src/fields/money-field.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
 import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
 import { type ReactNode, useMemo } from "react"
 import { InputGroupAddon, InputGroupText } from "@/components/ui/input-group"
@@ -95,7 +96,8 @@ function MoneyField({
     maximumFractionDigits: digits,
     min,
     onBlur: field.handleBlur,
-    onValueChange: (next) => field.handleChange(next),
+    onValueChange: (next) =>
+      field.handleChange(next ?? getEmptyValue(field, null)),
     padFraction: true,
     value: field.state.value,
   })

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

@@ -5,6 +5,7 @@ import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
 import { XIcon } from "lucide-react"
@@ -56,7 +57,10 @@ type MultiSelectFieldProps<T = string> = {
   clearLabel?: string
   disabled?: boolean
   className?: string
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
 }
 
@@ -104,6 +108,8 @@ function MultiSelectField<T = string>({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   const values = field.state.value ?? []
   // Map stored values back to item identities, in selection order, so Base UI
@@ -144,6 +150,7 @@ function MultiSelectField<T = string>({
                     [showError, errorId]
                   )}
                   aria-invalid={isInvalid || undefined}
+                  aria-required={requiresValue || undefined}
                   id={id}
                   name={field.name}
                   onBlur={field.handleBlur}

package/src/fields/number-field.tsx

@@ -1,15 +1,15 @@
 "use client"
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
 import type { ChangeEvent } from "react"
 import { InputField, type InputFieldProps } from "./input-field"
 
-type NumberFieldProps = Omit<
-  InputFieldProps,
-  "inputMode" | "onChange" | "type" | "value"
->
+type NumberFieldProps = Omit<InputFieldProps, "onChange" | "type" | "value">
 
-function NumberField(props: NumberFieldProps) {
+// `decimal` keeps the decimal key on phone keypads; pass `numeric` for whole
+// numbers.
+function NumberField({ inputMode = "decimal", ...props }: NumberFieldProps) {
   const field = useFieldContext<number | undefined>()
   const { value } = field.state
   const inputValue =
@@ -18,10 +18,12 @@ function NumberField(props: NumberFieldProps) {
   return (
     <InputField
       {...props}
-      inputMode="numeric"
+      inputMode={inputMode}
       onChange={(event: ChangeEvent<HTMLInputElement>) => {
         const next = event.target.valueAsNumber
-        field.handleChange(Number.isNaN(next) ? undefined : next)
+        field.handleChange(
+          Number.isNaN(next) ? getEmptyValue(field, undefined) : next
+        )
       }}
       type="number"
       value={inputValue}

package/src/fields/otp-field.tsx

@@ -5,6 +5,7 @@ import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
 import { type ReactNode, useId } from "react"
@@ -40,7 +41,10 @@ type OtpFieldProps = {
    * you need a separator between segments.
    */
   children?: ReactNode
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
 }
 
@@ -65,6 +69,8 @@ function OtpField({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   return (
     <Field data-field={field.name} data-invalid={isInvalid}>
@@ -80,6 +86,7 @@ function OtpField({
           [showError, errorId]
         )}
         aria-invalid={isInvalid || undefined}
+        aria-required={requiresValue || undefined}
         autoFocus={autoFocus}
         className={className}
         containerClassName={containerClassName}

package/src/fields/percentage-field.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
 import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
 import { InputGroupAddon, InputGroupText } from "@/components/ui/input-group"
 import { InputField, type InputFieldProps } from "./input-field"
@@ -54,7 +55,8 @@ function PercentageField({
     maximumFractionDigits: fractionDigits,
     min,
     onBlur: field.handleBlur,
-    onValueChange: (next) => field.handleChange(next),
+    onValueChange: (next) =>
+      field.handleChange(next ?? getEmptyValue(field, null)),
     value: field.state.value,
     ...(isFraction ? { fromDisplay: fromPercent, toDisplay: toPercent } : {}),
   })

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

@@ -5,6 +5,7 @@ import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
 import { type ComponentProps, type ReactNode, useId } from "react"
@@ -24,7 +25,10 @@ type RadioGroupFieldProps = Omit<
 > & {
   description?: ReactNode
   label?: ReactNode
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
 }
 
@@ -35,7 +39,7 @@ function RadioGroupField({
   required,
   ...props
 }: RadioGroupFieldProps) {
-  const field = useFieldContext<string>()
+  const field = useFieldContext()
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -44,6 +48,8 @@ function RadioGroupField({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   return (
     <Field data-field={field.name} data-invalid={isInvalid}>
@@ -59,9 +65,10 @@ function RadioGroupField({
           [showError, errorId]
         )}
         aria-invalid={isInvalid || undefined}
+        aria-required={requiresValue || undefined}
         name={field.name}
-        onValueChange={(value) => field.handleChange(String(value))}
-        value={field.state.value ?? ""}
+        onValueChange={(value) => field.handleChange(value)}
+        value={field.state.value ?? null}
         {...props}
       >
         {children}

package/src/fields/select-field.tsx

@@ -5,10 +5,11 @@ import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
 import type { ComponentProps, ReactNode } from "react"
-import { Children, isValidElement, useId, useMemo } from "react"
+import { Children, isValidElement, useId, useMemo, useRef } from "react"
 import {
   Field,
   FieldDescription,
@@ -31,7 +32,10 @@ type SelectFieldProps = Omit<
   description?: ReactNode
   label?: ReactNode
   placeholder?: string
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
   triggerClassName?: string
   triggerSize?: ComponentProps<typeof SelectTrigger>["size"]
@@ -41,6 +45,7 @@ function SelectField({
   children,
   description,
   label,
+  onOpenChange,
   placeholder,
   required,
   triggerClassName,
@@ -48,6 +53,10 @@ function SelectField({
   ...props
 }: SelectFieldProps) {
   const field = useFieldContext()
+  // 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.
+  const isOpen = useRef<boolean>(false)
   const id = useId()
   const errorId = `${id}-error`
   const descriptionId = `${id}-description`
@@ -56,6 +65,8 @@ function SelectField({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   const items = useMemo(() => {
     const map: Record<string, ReactNode> = {}
@@ -81,6 +92,13 @@ function SelectField({
       <Select
         items={items}
         name={field.name}
+        onOpenChange={(open, eventDetails) => {
+          isOpen.current = open
+          if (!open) {
+            field.handleBlur()
+          }
+          onOpenChange?.(open, eventDetails)
+        }}
         onValueChange={(value) => field.handleChange(value)}
         value={field.state.value ?? null}
         {...props}
@@ -91,9 +109,14 @@ function SelectField({
             [showError, errorId]
           )}
           aria-invalid={isInvalid || undefined}
+          aria-required={requiresValue || undefined}
           className={triggerClassName}
           id={id}
-          onBlur={field.handleBlur}
+          onBlur={() => {
+            if (!isOpen.current) {
+              field.handleBlur()
+            }
+          }}
           size={triggerSize}
         >
           <SelectValue placeholder={placeholder} />

package/src/fields/switch-field.tsx

@@ -5,6 +5,7 @@ import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
 import { type ComponentProps, type ReactNode, useId } from "react"
@@ -24,7 +25,10 @@ type SwitchFieldProps = Omit<
 > & {
   description?: ReactNode
   label?: ReactNode
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
 }
 
@@ -43,6 +47,8 @@ function SwitchField({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   return (
     <Field
@@ -70,6 +76,7 @@ function SwitchField({
           [showError, errorId]
         )}
         aria-invalid={isInvalid || undefined}
+        aria-required={requiresValue || undefined}
         checked={field.state.value ?? false}
         id={id}
         name={field.name}

package/src/fields/textarea-field.tsx

@@ -5,6 +5,7 @@ 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"
@@ -25,7 +26,10 @@ type TextAreaFieldProps = Omit<
   children?: ReactNode
   description?: ReactNode
   label?: ReactNode
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
 }
 
@@ -46,6 +50,8 @@ function TextAreaField({
   const hasAddons = Children.count(children) > 0
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   const textareaProps = {
     "aria-describedby": describedBy(
@@ -53,6 +59,7 @@ function TextAreaField({
       [showError, errorId]
     ),
     "aria-invalid": isInvalid || undefined,
+    "aria-required": requiresValue || undefined,
     id,
     name: field.name,
     onBlur: field.handleBlur,

package/src/fields/year-field.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
 import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
 import { InputField, type InputFieldProps } from "./input-field"
 
@@ -36,7 +37,8 @@ function YearField({ max, min, ...props }: YearFieldProps) {
     maximumFractionDigits: 0,
     min,
     onBlur: field.handleBlur,
-    onValueChange: (next) => field.handleChange(next),
+    onValueChange: (next) =>
+      field.handleChange(next ?? getEmptyValue(field, null)),
     useGrouping: false,
     value: field.state.value,
   })

package/src/index.ts

@@ -21,6 +21,7 @@ export {
 export {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "./lib/use-is-invalid"
 export { type FieldMessage, ValidationError } from "./lib/validation-error"

package/src/lib/empty-value.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest"
+import { z } from "zod"
+
+import { emptyValueFor, withEmptyStartValues } from "./empty-value"
+import { extractZodDefaults } from "./schema-defaults"
+
+const FALLBACK = Symbol("fallback")
+
+function cleared(field: z.ZodType, name = "field", values: unknown = {}) {
+  return emptyValueFor(z.object({ field }), values, name, FALLBACK)
+}
+
+describe("emptyValueFor", () => {
+  test("null, then undefined, then the type's own empty value", () => {
+    expect(cleared(z.string().nullable())).toBeNull()
+    expect(cleared(z.string().optional())).toBeUndefined()
+    expect(cleared(z.string())).toBe("")
+    expect(cleared(z.array(z.string()))).toEqual([])
+    expect(cleared(z.uuid().nullable())).toBeNull()
+    expect(cleared(z.enum(["a", "b"]).optional())).toBeUndefined()
+    expect(cleared(z.number().nullable())).toBeNull()
+    expect(cleared(z.date().nullish())).toBeNull()
+  })
+
+  test("a field that accepts no empty value keeps the field's own fallback", () => {
+    expect(cleared(z.string().min(1))).toBe(FALLBACK)
+    expect(cleared(z.number())).toBe(FALLBACK)
+  })
+
+  test("array rows follow the row schema", () => {
+    const schema = z.object({
+      members: z.array(
+        z.object({
+          id: z.uuid().nullable(),
+          name: z.string(),
+          note: z.string().optional(),
+        })
+      ),
+    })
+    const values = { members: [{ id: "x" }, { id: "y" }] }
+    const at = (name: string) => emptyValueFor(schema, values, name, FALLBACK)
+    expect(at("members[1].id")).toBeNull()
+    expect(at("members[1].name")).toBe("")
+    expect(at("members[1].note")).toBeUndefined()
+  })
+
+  test("without a schema, or with an async one, the fallback stands", () => {
+    expect(emptyValueFor(undefined, {}, "field", FALLBACK)).toBe(FALLBACK)
+    const asyncSchema = z.object({
+      field: z.string().refine(async () => true),
+    })
+    expect(emptyValueFor(asyncSchema, {}, "field", FALLBACK)).toBe(FALLBACK)
+  })
+})
+
+describe("withEmptyStartValues", () => {
+  test('starts a field whose schema rejects `""` at its empty value', () => {
+    const schema = z.object({
+      email: z.email().optional(),
+      name: z.string().min(1),
+      note: z.string(),
+      ownerId: z.uuid().nullable(),
+    })
+    const start = withEmptyStartValues(schema, extractZodDefaults(schema))
+    expect(start).toEqual({
+      email: undefined,
+      name: "",
+      note: "",
+      ownerId: null,
+    })
+  })
+})