Form UI Integration

This project implements a robust form system by integrating react-hook-form for state management with a set of custom UI components located in frontend/src/components/ui/form.tsx. This integration ensures type safety, consistent styling, and automatic accessibility (ARIA) compliance through specialized React Context providers.

Core Context Providers

The form system relies on two primary context providers to share state and metadata across the component tree without manual prop drilling.

FormFieldContextValue

The FormFieldContextValue is used to track the specific field name within a form. It is provided by the FormField component, which wraps the Controller from react-hook-form.

// frontend/src/components/ui/form.tsx

type FormFieldContextValue<
  TFieldValues extends FieldValues = FieldValues,
  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
> = {
  name: TName
}

const FormFieldContext = React.createContext<FormFieldContextValue>(
  {} as FormFieldContextValue
)

By providing the name via context, child components like FormLabel and FormMessage can automatically retrieve the field's current state (e.g., validation errors) from react-hook-form.

FormItemContextValue

The FormItemContextValue manages unique identifiers for individual form rows. It is provided by the FormItem component.

// frontend/src/components/ui/form.tsx

type FormItemContextValue = {
  id: string
}

const FormItemContext = React.createContext<FormItemContextValue>(
  {} as FormItemContextValue
)

Inside FormItem, a unique ID is generated using React.useId(). This ID is then used to derive specific IDs for the label, the input control, and the error message, ensuring that ARIA attributes like aria-describedby and htmlFor are correctly linked.

The useFormField Hook

The useFormField hook is the central bridge between the UI components and the form logic. It consumes both FormFieldContext and FormItemContext, along with the standard useFormContext from react-hook-form.

// frontend/src/components/ui/form.tsx

const useFormField = () => {
  const fieldContext = React.useContext(FormFieldContext)
  const itemContext = React.useContext(FormItemContext)
  const { getFieldState } = useFormContext()
  const formState = useFormState({ name: fieldContext.name })
  const fieldState = getFieldState(fieldContext.name, formState)

  const { id } = itemContext

  return {
    id,
    name: fieldContext.name,
    formItemId: `${id}-form-item`,
    formDescriptionId: `${id}-form-item-description`,
    formMessageId: `${id}-form-item-message`,
    ...fieldState,
  }
}

This hook allows components like FormControl to automatically apply the correct id and aria-invalid attributes based on the field's validation state.

Type Safety with FormData

Type safety is enforced by defining Zod schemas and inferring the FormData type. This pattern is used across the application, such as in frontend/src/routes/signup.tsx and frontend/src/routes/login.tsx.

// frontend/src/routes/signup.tsx

const formSchema = z.object({
  email: z.email(),
  full_name: z.string().min(1, { message: "Full Name is required" }),
  // ... other fields
})

type FormData = z.infer<typeof formSchema>

When initializing the form with useForm<FormData>, TypeScript ensures that the name prop passed to FormField matches the keys defined in the schema.

Component Architecture

The form UI is built using a hierarchical structure where each component has a specific responsibility:

1. Form: A re-export of FormProvider, making the react-hook-form methods available to all nested components.
2. FormField: Wraps the Controller and provides the FormFieldContext.
3. FormItem: Provides the FormItemContext and acts as a layout container (usually a div with a grid gap).
4. FormLabel: A wrapper around Radix UI's Label that automatically sets the htmlFor attribute and applies error styling if the field is invalid.
5. FormControl: Uses the Radix UI Slot component to inject ARIA attributes (id, aria-describedby, aria-invalid) directly into its child (e.g., an Input or PasswordInput).
6. FormMessage: Displays the validation error message if one exists, linked via the formMessageId.

Implementation Example

The following example from frontend/src/routes/signup.tsx demonstrates how these pieces fit together:

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField
      control={form.control}
      name="full_name"
      render={({ field }) => (
        <FormItem>
          <FormLabel>Full Name</FormLabel>
          <FormControl>
            <Input
              placeholder="User"
              {...field}
            />
          </FormControl>
          <FormMessage />
        </FormItem>
      )}
    />
    {/* ... other fields */}
  </form>
</Form>

In this structure, FormControl ensures the Input receives the correct ID generated by FormItem, while FormMessage automatically displays errors caught by the Zod resolver attached to the form instance.