chore: adding reset to an InternalError as well as cleaning up error messages

Author: dmortal

docs/04/01/error-handling.md

@@ -0,0 +1,33 @@
+# Error Handling in the React SDK
+
+Error handling in the React SDK occurs across multiple layers:
+
+1. **Top-Level Error Boundary** — in `GustoProviderCustomUIAdapter.tsx`
+2. **Component-Level Error Boundary** — in `Base.tsx`
+3. **Error Processing Logic** — in `Base.tsx`
+
+---
+
+## Known Errors
+
+The `Base` component handles three main categories of known errors:
+
+- **API client errors** caused by Zod validation failures on request or response schemas
+- **Explicitly set errors** from descendants of the `Base` component
+- **Errors returned directly by the API**
+
+These known errors are rendered alongside the component’s children at the top level of `Base.tsx`. They differ in structure and are displayed with context-specific UI.
+
+---
+
+## Catastrophic Errors
+
+Unexpected errors thrown by descendants of the `Base` component are caught by the error boundary in `Base.tsx` and rendered using the `InternalError` component or a custom `FallbackComponent` if provided. These are considered **catastrophic errors**, meaning the component cannot render itself.
+
+In such cases, a **"Try again"** button is shown, which allows users to attempt a re-render of the component.
+
+---
+
+## Unrecognized Errors
+
+Errors that are caught by `Base.tsx` but not recognized as known error types are re-thrown. These are then handled by the top-level error boundary in `GustoProviderCustomUIAdapter.tsx`, unless a partner provides additional error boundaries between `GustoProvider` and t

docs/04/integration-guide.md

@@ -9,3 +9,4 @@ The integration guide will provide general concepts for building with the Gusto
 | Providing Your Own Data              | How to supply your own data to SDK forms                                                                                                                                                                |
 | Translation                          | How to customize copy within SDK components and support for internationalization                                                                                                                        |
 | Routing                              | Example of integrating the SDK with your application router                                                                                                                                             |
+| Error Handling                       | How does SDK handle internal errors router                                                                                                                                                              |

src/components/Base/Base.tsx

@@ -7,6 +7,7 @@ import { APIError } from '@gusto/embedded-api/models/errors/apierror'
 import { SDKValidationError } from '@gusto/embedded-api/models/errors/sdkvalidationerror'
 import { UnprocessableEntityErrorObject } from '@gusto/embedded-api/models/errors/unprocessableentityerrorobject'
 import type { EntityErrorObject } from '@gusto/embedded-api/models/components/entityerrorobject'
+import { QueryErrorResetBoundary } from '@tanstack/react-query'
 import { FadeIn } from '../Common/FadeIn/FadeIn'
 import { BaseContext, type FieldError, type KnownErrors, type OnEventType } from './useBase'
 import { componentEvents, type EventType } from '@/shared/constants'
@@ -31,7 +32,7 @@ export interface BaseComponentInterface<TResourceKey extends keyof Resources = k
 }
 
 /**Traverses errorList and finds items with message properties */
-const renderErrorList = (errorList: FieldError[]): React.ReactNode => {
+const renderErrorList = (errorList: FieldError[]): React.ReactNode[] => {
   return errorList.map(errorFromList => {
     if (errorFromList.message) {
       return <li key={errorFromList.key}>{errorFromList.message}</li>
@@ -91,7 +92,7 @@ export const BaseComponent = <TResourceKey extends keyof Resources = keyof Resou
   const processError = (error: KnownErrors) => {
     setError(error)
     //422	application/json - content relaited error
-    if (error instanceof UnprocessableEntityErrorObject && Array.isArray(error.errors)) {
+    if (error instanceof UnprocessableEntityErrorObject) {
       setFieldErrors(error.errors.flatMap(err => getFieldErrors(err)))
     }
   }
@@ -125,21 +126,32 @@ export const BaseComponent = <TResourceKey extends keyof Resources = keyof Resou
         baseSubmitHandler,
       }}
     >
-      <ErrorBoundary
-        FallbackComponent={FallbackComponent}
-        onError={err => {
-          onEvent(componentEvents.ERROR, err)
-        }}
-      >
-        {(error || fieldErrors) && (
-          <Components.Alert label={t('status.errorEncountered')} status="error">
-            {fieldErrors && <ul>{renderErrorList(fieldErrors)}</ul>}
-          </Components.Alert>
+      <QueryErrorResetBoundary>
+        {({ reset: resetQueries }) => (
+          <ErrorBoundary
+            FallbackComponent={FallbackComponent}
+            onReset={resetQueries}
+            onError={err => {
+              onEvent(componentEvents.ERROR, err)
+            }}
+          >
+            {(error || fieldErrors) && (
+              <Components.Alert label={t('status.errorEncountered')} status="error">
+                {fieldErrors && <Components.UnorderedList items={renderErrorList(fieldErrors)} />}
+                {error && error instanceof APIError && (
+                  <Components.Text>{error.message}</Components.Text>
+                )}
+                {error && error instanceof SDKValidationError && (
+                  <Components.Text as="pre">{error.pretty()}</Components.Text>
+                )}
+              </Components.Alert>
+            )}
+            <Suspense fallback={<LoaderComponent />}>
+              <FadeIn>{children}</FadeIn>
+            </Suspense>
+          </ErrorBoundary>
         )}
-        <Suspense fallback={<LoaderComponent />}>
-          <FadeIn>{children}</FadeIn>
-        </Suspense>
-      </ErrorBoundary>
+      </QueryErrorResetBoundary>
     </BaseContext.Provider>
   )
 }

src/components/Common/InternalError/InternalError.tsx

@@ -4,7 +4,6 @@ import styles from './InternalError.module.scss'
 import { useComponentContext } from '@/contexts/ComponentAdapter/useComponentContext'
 
 export const InternalError = ({ error, resetErrorBoundary }: FallbackProps) => {
-  //TODO: Need to integrate useQueryErrorResetBoundary from tanstac to reset query cach on "try again" - GWS-3926
   const { t } = useTranslation('common')
   const Components = useComponentContext()
   const errorMessage =
@@ -13,7 +12,6 @@ export const InternalError = ({ error, resetErrorBoundary }: FallbackProps) => {
       : error instanceof Error
         ? error.message
         : t('errors.unknownError')
-
   return (
     <div className={styles.internalErrorCard} role="alert" data-testid="internal-error-card">
       <div>

src/components/Common/UI/Text/TextTypes.ts

@@ -4,7 +4,7 @@ export interface TextProps extends Pick<HTMLAttributes<HTMLParagraphElement>, 'c
   /**
    * HTML element to render the text as
    */
-  as?: 'p' | 'span' | 'div'
+  as?: 'p' | 'span' | 'div' | 'pre'
   /**
    * Size variant of the text
    */

src/components/Contractor/PaymentMethod/PaymentMethod.tsx

@@ -86,10 +86,10 @@ function Root({ contractorId, className, dictionary }: PaymentMethodProps) {
   })
 
   const watchedType = useWatch({ control: formMethods.control, name: 'type' })
-
   const onSubmit: SubmitHandler<PaymentMethodSchemaInputs> = async data => {
     await baseSubmitHandler(data, async payload => {
       let permitBankSubmission = true
+
       if (payload.type === PAYMENT_METHODS.directDeposit) {
         /** Custom validation logic for accountNumber - because masked account value is used as default value, it is only validated when any of the bank-related fields are modified*/
         const { name, accountNumber, routingNumber, accountType } = payload
@@ -128,7 +128,7 @@ function Root({ contractorId, className, dictionary }: PaymentMethodProps) {
             contractorUuid: contractorId,
             requestBody: {
               name: payload.name,
-              routingNumber: payload.routingNumber,
+              routingNumber: '654789878',
               accountNumber: payload.accountNumber,
               accountType: payload.accountType,
             },