@zeno-lib/forms 0.3.0 → 0.5.0

package/dist/lib/validation-modes.d.mts

@@ -1,3 +1,4 @@
+import { StandardSchemaLike } from "./schema-required.mjs";
 import { AnyFormApi } from "@tanstack/react-form";
 //#region src/lib/validation-modes.d.ts
 type ValidationMode = "change" | "blur" | "submit" | "blur-then-change";
@@ -7,10 +8,13 @@ type ZenoFormState = {
   hideFieldErrors: boolean;
   requiredIndicator: boolean;
   requiredFields: ReadonlySet<string>;
+  schema: StandardSchemaLike | undefined;
 };
 declare function setFormZenoState(form: AnyFormApi, state: Partial<ZenoFormState>): void;
 declare function getFormValidationMode(form: AnyFormApi): ValidationMode;
 declare function getFormHideFieldErrors(form: AnyFormApi): boolean;
+declare function getFormSchema(form: AnyFormApi): StandardSchemaLike | undefined;
+declare function isFieldRequiredBySchema(form: AnyFormApi, name: string): boolean;
 declare function isFieldRequired(form: AnyFormApi, name: string): boolean;
 //#endregion
-export { DEFAULT_VALIDATION_MODE, type ValidationMode, getFormHideFieldErrors, getFormValidationMode, isFieldRequired, setFormZenoState };
+export { DEFAULT_VALIDATION_MODE, type ValidationMode, getFormHideFieldErrors, getFormSchema, getFormValidationMode, isFieldRequired, isFieldRequiredBySchema, setFormZenoState };

package/dist/lib/validation-modes.mjs

@@ -6,6 +6,7 @@ const DEFAULT_FORM_STATE = {
 	hideFieldErrors: false,
 	requiredFields: /* @__PURE__ */ new Set(),
 	requiredIndicator: true,
+	schema: void 0,
 	validation: DEFAULT_VALIDATION_MODE
 };
 const formZenoState = /* @__PURE__ */ new WeakMap();
@@ -29,10 +30,14 @@ function getFormValidationMode(form) {
 function getFormHideFieldErrors(form) {
 	return getFormZenoState(form).hideFieldErrors;
 }
+function getFormSchema(form) {
+	return getFormZenoState(form).schema;
+}
+function isFieldRequiredBySchema(form, name) {
+	return getFormZenoState(form).requiredFields.has(toRequiredPathKey(name));
+}
 function isFieldRequired(form, name) {
-	const state = getFormZenoState(form);
-	if (!state.requiredIndicator) return false;
-	return state.requiredFields.has(toRequiredPathKey(name));
+	return getFormZenoState(form).requiredIndicator && isFieldRequiredBySchema(form, name);
 }
 //#endregion
-export { DEFAULT_VALIDATION_MODE, getFormHideFieldErrors, getFormValidationMode, isFieldRequired, setFormZenoState };
+export { DEFAULT_VALIDATION_MODE, getFormHideFieldErrors, getFormSchema, getFormValidationMode, isFieldRequired, isFieldRequiredBySchema, setFormZenoState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "repository": {
     "url": "https://github.com/zeno-lib/zeno.git",
     "directory": "packages/forms"

package/src/create-form.tsx

@@ -8,6 +8,7 @@ import { CheckboxGroupField } from "./fields/checkbox-group-field"
 import { ComboboxField } from "./fields/combobox-field"
 import { DatePickerField } from "./fields/date-picker-field"
 import { EmailField } from "./fields/email-field"
+import { FormError } from "./fields/form-error"
 import { InputField } from "./fields/input-field"
 import { MoneyField } from "./fields/money-field"
 import { MultiSelectField } from "./fields/multi-select-field"
@@ -48,6 +49,7 @@ const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
     YearField,
   },
   formComponents: {
+    FormError,
     ResetButton,
     SubmitButton,
   },

package/src/create-zeno-form.tsx

@@ -12,8 +12,13 @@ import { createFormHook } from "@tanstack/react-form"
 import { type ComponentProps, type ReactNode, useMemo } from "react"
 import { applyValidationError } from "./lib/apply-validation-error"
 import { fieldContext, formContext } from "./lib/contexts"
+import { withEmptyStartValues } from "./lib/empty-value"
 import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults"
-import { getRequiredPaths } from "./lib/schema-required"
+import {
+  getRequiredPaths,
+  type StandardSchemaLike,
+} from "./lib/schema-required"
+import { setSubmitError } from "./lib/submit-error"
 import { useRebasedDefaultValues } from "./lib/use-rebased-default-values"
 import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning"
 import { ValidationError } from "./lib/validation-error"
@@ -435,6 +440,7 @@ export function createZenoForm<
 
     const wrappedOnSubmit = userOnSubmit
       ? ((async (props: { formApi: AnyFormApi; value: TFormData }) => {
+          const { submissionAttempts } = props.formApi.state
           try {
             await (
               userOnSubmit as unknown as (
@@ -446,6 +452,16 @@ export function createZenoForm<
               applyValidationError(props.formApi, error)
               return
             }
+            // Kept for `FormError`, unless an edit, a reset (a dialog closed
+            // meanwhile) or a newer submit came first: then it is about
+            // values no longer on screen.
+            const { state } = props.formApi
+            if (
+              state.values === props.value &&
+              state.submissionAttempts === submissionAttempts
+            ) {
+              setSubmitError(props.formApi, error)
+            }
             throw error
           }
         }) as typeof userOnSubmit)
@@ -453,17 +469,20 @@ export function createZenoForm<
 
     const requiredFields = useMemo(
       () =>
-        schema && requiredIndicator
+        schema
           ? getRequiredPaths(schema as Parameters<typeof getRequiredPaths>[0])
           : new Set<string>(),
-      [schema, requiredIndicator]
+      [schema]
     )
 
     const schemaDefaults = useMemo(
       () =>
         schema
-          ? extractZodDefaults(
-              schema as Parameters<typeof extractZodDefaults>[0]
+          ? withEmptyStartValues(
+              schema as StandardSchemaLike,
+              extractZodDefaults(
+                schema as Parameters<typeof extractZodDefaults>[0]
+              )
             )
           : undefined,
       [schema]
@@ -515,6 +534,7 @@ export function createZenoForm<
       hideFieldErrors,
       requiredFields,
       requiredIndicator,
+      schema: schema as StandardSchemaLike | undefined,
       ...(schemaMode === undefined ? {} : { validation: schemaMode }),
     })
 

package/src/fields/checkbox-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 CheckboxFieldProps = 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 CheckboxField({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   return (
     <Field
@@ -56,6 +62,7 @@ function CheckboxField({
           [showError, errorId]
         )}
         aria-invalid={isInvalid || undefined}
+        aria-required={requiresValue || undefined}
         checked={field.state.value ?? false}
         id={id}
         name={field.name}

package/src/fields/combobox-field.tsx

@@ -2,9 +2,11 @@
 
 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 ReactNode, useId } from "react"
@@ -43,13 +45,17 @@ type ComboboxFieldProps<T = string> = {
   /** Override per-row rendering. Default: plain `<ComboboxItem>{label}</ComboboxItem>`. */
   renderItem?: (item: T) => ReactNode
   /**
-   * If `true`, show the clear button when a value is selected. Defaults to
-   * `true` — pass `false` for required-style comboboxes where clearing is
-   * disallowed.
+   * 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
+   * `required`), where clearing could only make the form invalid.
    */
   showClear?: boolean
+  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 `*`,
+   * `aria-required` and the `showClear` default.
+   */
   required?: boolean
   /**
    * Controlled input text — pair with `onInputValueChange` for server-side
@@ -82,6 +88,7 @@ function isItemObject(item: unknown): item is ComboboxItemObject<unknown> {
 function ComboboxField<T = string>({
   className,
   description,
+  disabled,
   emptyMessage = "No results.",
   filter,
   inputValue,
@@ -92,7 +99,7 @@ function ComboboxField<T = string>({
   placeholder,
   renderItem,
   required,
-  showClear = true,
+  showClear,
 }: ComboboxFieldProps<T>) {
   const field = useFieldContext()
   const id = useId()
@@ -103,13 +110,20 @@ function ComboboxField<T = string>({
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
+  const canClear = showClear ?? !requiresValue
 
   const fieldValue = field.state.value
-  const hasObjectItems = items.some(isItemObject)
-  const value = hasObjectItems
-    ? ((items.find((item) => isItemObject(item) && item.value === fieldValue) ??
-        null) as T | null)
-    : ((fieldValue ?? null) as T | null)
+  // 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 value = (match ??
+    (plainItems ? (fieldValue ?? null) : null)) as T | null
 
   return (
     <Field data-field={field.name} data-invalid={isInvalid}>
@@ -120,13 +134,14 @@ function ComboboxField<T = string>({
         </FieldLabel>
       )}
       <Combobox
+        disabled={disabled}
         filter={filter}
         inputValue={inputValue}
         items={items}
         onInputValueChange={onInputValueChange}
         onValueChange={(next) => {
           if (next === null) {
-            field.handleChange(undefined)
+            field.handleChange(getEmptyValue(field, undefined))
             return
           }
           field.handleChange(isItemObject(next) ? next.value : next)
@@ -139,12 +154,14 @@ function ComboboxField<T = string>({
             [showError, errorId]
           )}
           aria-invalid={isInvalid || undefined}
+          aria-required={requiresValue || undefined}
           className={className}
+          disabled={disabled}
           id={id}
           name={field.name}
           onBlur={field.handleBlur}
           placeholder={placeholder}
-          showClear={showClear && value !== null && value !== "" && !loading}
+          showClear={canClear && value !== null && value !== "" && !loading}
         >
           {loading && (
             <InputGroupAddon align="inline-end">

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/form-error.tsx

@@ -0,0 +1,61 @@
+"use client"
+
+import { useFormContext } from "@zeno-lib/forms/lib/contexts"
+import { useSubmitError } from "@zeno-lib/forms/lib/submit-error"
+import { useSelector } from "@zeno-lib/forms/tanstack"
+import type { ComponentProps, ReactNode } from "react"
+import { FieldError } from "@/components/ui/field"
+
+type FormErrorProps = Omit<
+  ComponentProps<typeof FieldError>,
+  "children" | "errors"
+> & {
+  /**
+   * Shown when the submit handler throws (a network failure, an unexpected
+   * server error). Defaults to `"Something went wrong. Try again."`. A
+   * function gets what was thrown.
+   */
+  submitErrorMessage?: ReactNode | ((error: unknown) => ReactNode)
+}
+
+/**
+ * The form-level error, as a `role="alert"` message: the `formErrors` an
+ * action returns through `submitAction`, a `ValidationError`'s `formError`,
+ * or `submitErrorMessage` when the submit throws. Renders nothing otherwise.
+ * It clears when the user edits the form, and a thrown one also when they
+ * submit again.
+ */
+function FormError({
+  submitErrorMessage = "Something went wrong. Try again.",
+  ...props
+}: FormErrorProps) {
+  const form = useFormContext()
+  const formError = useSelector(form.store, (state) => state.errorMap.onSubmit)
+  const submitError = useSubmitError(form)
+
+  // `submitAction` joins several messages with a line break. A schema's
+  // form-level result is an object, not a message, and isn't shown here. It
+  // wins over a thrown submit: it says what went wrong.
+  if (typeof formError === "string" && formError !== "") {
+    return (
+      <FieldError
+        data-slot="form-error"
+        errors={formError.split("\n").map((message) => ({ message }))}
+        {...props}
+      />
+    )
+  }
+  if (!submitError) {
+    return null
+  }
+  return (
+    <FieldError data-slot="form-error" {...props}>
+      {typeof submitErrorMessage === "function"
+        ? submitErrorMessage(submitError.error)
+        : submitErrorMessage}
+    </FieldError>
+  )
+}
+
+export type { FormErrorProps }
+export { FormError }

package/src/fields/index.ts

@@ -4,6 +4,7 @@ export * from "./checkbox-group-field"
 export * from "./combobox-field"
 export * from "./date-picker-field"
 export * from "./email-field"
+export * from "./form-error"
 export * from "./input-field"
 export * from "./money-field"
 export * from "./multi-select-field"

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}