feat(contractor-onboarding) - highlight errors (#961)

* feat(contractor-onboarding) - highlight errors

* format

* add tests

Author: gabrielseco

src/flows/ContractorOnboarding/components/BasicInformationStep.tsx

@@ -5,6 +5,7 @@ import { NormalizedFieldError } from '@/src/lib/mutations';
 import { useContractorOnboardingContext } from '@/src/flows/ContractorOnboarding/context';
 import { ContractorOnboardingForm } from '@/src/flows/ContractorOnboarding/components/ContractorOnboardingForm';
 import { handleStepError } from '@/src/lib/utils';
+import { UseFormReturn } from 'react-hook-form';
 
 type BasicInformationStepProps = {
   /*
@@ -36,7 +37,10 @@ export function BasicInformationStep({
 }: BasicInformationStepProps) {
   const { contractorOnboardingBag } = useContractorOnboardingContext();
 
-  const handleSubmit = async (payload: $TSFixMe) => {
+  const handleSubmit = async (
+    payload: $TSFixMe,
+    form: UseFormReturn<$TSFixMe>,
+  ) => {
     try {
       const parsedValues =
         await contractorOnboardingBag.parseFormValues(payload);
@@ -51,6 +55,7 @@ export function BasicInformationStep({
       const structuredError = handleStepError(
         error,
         contractorOnboardingBag.meta?.fields?.basic_information,
+        form,
       );
       onError?.(structuredError);
     }

src/flows/ContractorOnboarding/components/ContractDetailsStep.tsx

@@ -9,6 +9,7 @@ import {
 import { StatementOfWorkDisclaimer } from '@/src/flows/ContractorOnboarding/components/StatementOfWorkDisclaimer';
 import { isCMOrCMPlus } from '@/src/flows/ContractorOnboarding/utils';
 import { handleStepError } from '@/src/lib/utils';
+import { UseFormReturn } from 'react-hook-form';
 
 type ContractDetailsStepProps = {
   /*
@@ -44,7 +45,10 @@ export function ContractDetailsStep({
 }: ContractDetailsStepProps) {
   const { contractorOnboardingBag } = useContractorOnboardingContext();
 
-  const handleSubmit = async (payload: $TSFixMe) => {
+  const handleSubmit = async (
+    payload: $TSFixMe,
+    form: UseFormReturn<$TSFixMe>,
+  ) => {
     try {
       const parsedValues =
         await contractorOnboardingBag.parseFormValues(payload);
@@ -59,6 +63,7 @@ export function ContractDetailsStep({
       const structuredError = handleStepError(
         error,
         contractorOnboardingBag.meta?.fields?.contract_details,
+        form,
       );
       onError?.(structuredError);
     }

src/flows/ContractorOnboarding/components/ContractPreviewStep.tsx

@@ -7,6 +7,7 @@ import {
   ContractPreviewResponse,
 } from '@/src/flows/ContractorOnboarding/types';
 import { handleStepError } from '@/src/lib/utils';
+import { UseFormReturn } from 'react-hook-form';
 
 type ContractPreviewStepProps = {
   /*
@@ -38,7 +39,10 @@ export function ContractPreviewStep({
 }: ContractPreviewStepProps) {
   const { contractorOnboardingBag } = useContractorOnboardingContext();
 
-  const handleSubmit = async (payload: $TSFixMe) => {
+  const handleSubmit = async (
+    payload: $TSFixMe,
+    form: UseFormReturn<$TSFixMe>,
+  ) => {
     try {
       const parsedValues =
         await contractorOnboardingBag.parseFormValues(payload);
@@ -53,6 +57,7 @@ export function ContractPreviewStep({
       const structuredError = handleStepError(
         error,
         contractorOnboardingBag.meta?.fields?.contract_preview,
+        form,
       );
       onError?.(structuredError);
     }

src/flows/ContractorOnboarding/components/ContractorOnboardingForm.tsx

@@ -12,6 +12,7 @@ import {
 } from '@/src/flows/ContractorOnboarding/types';
 import { normalizeFieldErrors } from '@/src/lib/mutations';
 import { useJSONSchemaForm } from '@/src/components/form/useJSONSchemaForm';
+import { UseFormReturn } from 'react-hook-form';
 
 type ContractorOnboardingFormProps = {
   onSubmit: (
@@ -20,6 +21,7 @@ type ContractorOnboardingFormProps = {
       | PricingPlanFormPayload
       | ContractorOnboardingContractDetailsFormPayload
       | EligibilityQuestionnaireFormPayload,
+    form: UseFormReturn<$TSFixMe>,
   ) => Promise<void>;
   components?: Components;
   fields?: JSFFields;
@@ -87,7 +89,7 @@ export function ContractorOnboardingForm({
         });
       }
     } else {
-      await onSubmit(values as $TSFixMe);
+      await onSubmit(values as $TSFixMe, form);
     }
   };
 

src/flows/ContractorOnboarding/components/EligibilityQuestionnaireStep.tsx

@@ -7,6 +7,7 @@ import {
   EligibilityQuestionnaireFormPayload,
   EligibilityQuestionnaireResponse,
 } from '@/src/flows/ContractorOnboarding/types';
+import { UseFormReturn } from 'react-hook-form';
 
 type EligibilityQuestionnaireStepProps = {
   /*
@@ -40,7 +41,10 @@ export function EligibilityQuestionnaireStep({
 }: EligibilityQuestionnaireStepProps) {
   const { contractorOnboardingBag } = useContractorOnboardingContext();
 
-  const handleSubmit = async (payload: $TSFixMe) => {
+  const handleSubmit = async (
+    payload: $TSFixMe,
+    form: UseFormReturn<$TSFixMe>,
+  ) => {
     try {
       const parsedValues =
         await contractorOnboardingBag.parseFormValues(payload);
@@ -58,6 +62,7 @@ export function EligibilityQuestionnaireStep({
       const structuredError = handleStepError(
         error,
         contractorOnboardingBag.meta?.fields?.eligibility_questionnaire,
+        form,
       );
       onError?.(structuredError);
     }

src/flows/ContractorOnboarding/components/PricingPlan.tsx

@@ -7,6 +7,7 @@ import {
   PricingPlanResponse,
 } from '@/src/flows/ContractorOnboarding/types';
 import { handleStepError } from '@/src/lib/utils';
+import { UseFormReturn } from 'react-hook-form';
 
 type PricingPlanStepProps = {
   /**
@@ -43,7 +44,10 @@ export function PricingPlanStep({
 }: PricingPlanStepProps) {
   const { contractorOnboardingBag } = useContractorOnboardingContext();
 
-  const handleSubmit = async (payload: $TSFixMe) => {
+  const handleSubmit = async (
+    payload: $TSFixMe,
+    form: UseFormReturn<$TSFixMe>,
+  ) => {
     try {
       const parsedValues =
         await contractorOnboardingBag.parseFormValues(payload);
@@ -58,6 +62,7 @@ export function PricingPlanStep({
       const structuredError = handleStepError(
         error,
         contractorOnboardingBag.meta?.fields?.pricing_plan,
+        form,
       );
       onError?.(structuredError);
     }

src/flows/ContractorOnboarding/components/SelectCountryStep.tsx

@@ -8,6 +8,7 @@ import { $TSFixMe } from '@/src/types/remoteFlows';
 import { useContractorOnboardingContext } from '@/src/flows/ContractorOnboarding/context';
 import { ContractorOnboardingForm } from '@/src/flows/ContractorOnboarding/components/ContractorOnboardingForm';
 import { handleStepError } from '@/src/lib/utils';
+import { UseFormReturn } from 'react-hook-form';
 
 type SelectCountryStepProps = {
   /*
@@ -38,7 +39,10 @@ export function SelectCountryStep({
   onError,
 }: SelectCountryStepProps) {
   const { contractorOnboardingBag } = useContractorOnboardingContext();
-  const handleSubmit = async (payload: $TSFixMe) => {
+  const handleSubmit = async (
+    payload: $TSFixMe,
+    form: UseFormReturn<$TSFixMe>,
+  ) => {
     try {
       await onSubmit?.({ countryCode: payload.country });
       const response = await contractorOnboardingBag.onSubmit(payload);
@@ -51,8 +55,8 @@ export function SelectCountryStep({
       const structuredError = handleStepError(
         error,
         contractorOnboardingBag.meta?.fields?.select_country,
+        form,
       );
-
       onError?.(structuredError);
     }
   };

src/flows/ContractorOnboarding/tests/ContractorOnboarding.test.tsx

@@ -2634,6 +2634,84 @@ describe('ContractorOnboardingFlow', () => {
     });
   });
 
+  describe('Contract Details 422 Errors', () => {
+    it('should highlight fields and show error message when contract details submission fails with 422', async () => {
+      const employmentId = generateUniqueEmploymentId();
+
+      // Mock the contract document creation to fail with 422
+      server.use(
+        http.post('*/v1/contractors/employments/*/contract-documents', () => {
+          return HttpResponse.json(
+            {
+              errors: {
+                'service_duration.expiration_date': [
+                  'date must be after start date',
+                ],
+              },
+            },
+            { status: 422 },
+          );
+        }),
+      );
+
+      mockRender.mockImplementation(
+        createMockRenderImplementation(MultiStepFormWithoutCountry),
+      );
+
+      render(
+        <ContractorOnboardingFlow
+          employmentId={employmentId}
+          countryCode='PRT'
+          skipSteps={['select_country']}
+          {...defaultProps}
+        />,
+        { wrapper: TestProviders },
+      );
+
+      // Navigate to contract details step
+      await screen.findByText(/Step: Basic Information/i);
+      await waitForElementToBeRemoved(() => screen.getByTestId('spinner'));
+
+      await fillBasicInformation();
+
+      let nextButton = screen.getByText(/Next Step/i);
+      nextButton.click();
+
+      await screen.findByText(/Step: Pricing Plan/i);
+
+      await fillContractorSubscription();
+
+      nextButton = screen.getByText(/Next Step/i);
+      nextButton.click();
+
+      await screen.findByText(/Step: Contract Details/i);
+
+      // Fill contract details
+      await fillContractDetails();
+
+      nextButton = screen.getByText(/Next Step/i);
+      nextButton.click();
+
+      // Wait for the error callback
+      await waitFor(() => {
+        expect(mockOnError).toHaveBeenCalled();
+      });
+
+      // Verify we stay on the contract details step
+      await screen.findByText(/Step: Contract Details/i);
+
+      // Assert the field is highlighted (has aria-invalid attribute)
+      const serviceEndDateField = screen.getByTestId(
+        'service_duration.expiration_date',
+      );
+      expect(serviceEndDateField).toBeInTheDocument();
+      expect(serviceEndDateField).toHaveAttribute('aria-invalid', 'true');
+      expect(
+        screen.getByText(/date must be after start date/i),
+      ).toBeInTheDocument();
+    });
+  });
+
   describe('AI Validation Errors', () => {
     it('should display AI validation warning statement when contract document creation fails with non-skippable error for COR', async () => {
       const employmentId = generateUniqueEmploymentId();

src/lib/utils.ts

@@ -285,14 +285,18 @@ export function isStructuredError(err: unknown): err is {
 }
 
 /**
- * Handles the error for a step
+ * Handles the error for a step and optionally sets form field errors
  * @param err - The error
  * @param fieldsMeta - The fields metadata
+ * @param form - Optional form instance to set field errors
  * @returns The structured error
  */
 export function handleStepError(
   err: unknown,
   fieldsMeta?: NestedMeta,
+  form?: {
+    setError: (name: string, error: { type: string; message: string }) => void;
+  },
 ): {
   error: Error;
   rawError: Record<string, unknown>;
@@ -304,6 +308,12 @@ export function handleStepError(
       err.fieldErrors || [],
       fieldsMeta,
     );
+
+    // Automatically set form field errors if form is provided
+    if (form) {
+      setFormFieldErrors(form, normalizedFieldErrors);
+    }
+
     return {
       error: err.error,
       rawError: err.rawError,
@@ -351,3 +361,42 @@ export function getNestedValue<T = unknown>(
 
   return (result === undefined ? defaultValue : result) as T | undefined;
 }
+
+/**
+ * Sets backend validation errors into react-hook-form state
+ * Converts backend field paths to react-hook-form paths and sets errors
+ *
+ * @example
+ * Backend: "provisional_start_date" → Form: "provisional_start_date"
+ * Backend: "service_duration/expiration_date" → Form: "service_duration.expiration_date"
+ * Backend: "benefits[0]/value" → Form: "benefits.0.value"
+ *
+ * @param form - The react-hook-form instance
+ * @param fieldErrors - Array of normalized field errors from the backend
+ */
+export function setFormFieldErrors(
+  form: {
+    setError: (name: string, error: { type: string; message: string }) => void;
+  },
+  fieldErrors: NormalizedFieldError[],
+): void {
+  fieldErrors.forEach(({ field, messages }) => {
+    try {
+      // Convert backend field path to react-hook-form path
+      // "/" → "." for nested objects
+      // "[index]" → ".index" for arrays
+      const formFieldPath = field
+        .replace(/\//g, '.')
+        .replace(/\[(\d+)\]/g, '.$1');
+
+      form.setError(formFieldPath, {
+        type: 'server',
+        message: messages.join('. '),
+      });
+    } catch (error) {
+      // Silently ignore if field doesn't exist in form
+      // This can happen if backend returns errors for fields not in current step
+      console.warn(`Could not set error for field: ${field}`, error);
+    }
+  });
+}

src/tests/defaultComponents.tsx

@@ -11,6 +11,7 @@ export const defaultComponents = {
           type='date'
           id={field.name}
           data-testid={field.name}
+          aria-invalid={!!fieldState.error}
           value={field.value}
           onChange={(e) => {
             field?.onChange?.(e.target.value);