feat(ui-react-storage): allow custom error boundary (#6408)

* feat(ui-react-storage): allow custom error boundary

* feat: allow functional error boundary and null to disable

---------

Co-authored-by: Danny Banks <djb@amazon.com>

Author: AllanZhengYP

examples/next/pages/ui/components/storage/storage-browser/custom-actions/index.page.tsx

@@ -1,12 +1,33 @@
 import React from 'react';
-
 import { createStorageBrowser } from '@aws-amplify/ui-react-storage/browser';
-
-import { Flex } from '@aws-amplify/ui-react';
+import { Flex, Message } from '@aws-amplify/ui-react';
+import './styles.css';
 
 import '@aws-amplify/ui-react-storage/styles.css';
 
-const { StorageBrowser } = createStorageBrowser({
+class CustomErrorBoundary extends React.Component<React.PropsWithChildren> {
+  state = {
+    hasError: false,
+  };
+
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <Message variation="outlined" colorTheme="error">
+          Oops. An unexpected error has happened.
+        </Message>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+const { StorageBrowser, useView } = createStorageBrowser({
   actions: {
     default: {
       copy: {
@@ -83,7 +104,24 @@ const { StorageBrowser } = createStorageBrowser({
           nextToken: undefined,
         }),
     },
+    custom: {
+      mockRuntimeError: {
+        actionListItem: {
+          icon: 'error',
+          label: 'Mock unexpected error',
+        },
+        // Not used but to keep ts happy
+        handler: () => ({
+          result: Promise.resolve({
+            status: 'COMPLETE',
+            value: { key: 'trigger-runtime-error' },
+          }),
+        }),
+        viewName: 'LocationDetailView',
+      },
+    },
   },
+  ErrorBoundary: CustomErrorBoundary,
   config: {
     getLocationCredentials: () =>
       Promise.resolve({
@@ -112,6 +150,16 @@ const { StorageBrowser } = createStorageBrowser({
   },
 });
 
+function LocationDetailViewWithExpectedError() {
+  const { actionType } = useView('LocationDetail');
+
+  if (actionType === 'mockRuntimeError') {
+    throw new Error('Unexpected Error');
+  }
+
+  return <StorageBrowser.LocationDetailView />;
+}
+
 function Example() {
   return (
     <Flex
@@ -121,7 +169,11 @@ function Example() {
       overflow="hidden"
       padding="xl"
     >
-      <StorageBrowser />
+      <StorageBrowser
+        views={{
+          LocationDetailView: LocationDetailViewWithExpectedError,
+        }}
+      />
     </Flex>
   );
 }

examples/next/pages/ui/components/storage/storage-browser/custom-actions/styles.css

@@ -0,0 +1,4 @@
+/* Intentionally to test error boundary. No effect in prod mode. */
+nextjs-portal {
+  display: none;
+}

packages/e2e/cypress/integration/common/shared.ts

@@ -231,6 +231,12 @@ Given(
   }
 );
 
+Given('I expect an exception', () => {
+  Cypress.on('uncaught:exception', () => {
+    return false;
+  });
+});
+
 When('Sign in was called with {string}', (username: string) => {
   let tempStub = stub.calledWith(username, Cypress.env('VALID_PASSWORD'));
   stub = null;

packages/e2e/features/ui/components/storage/storage-browser/observability.feature

@@ -0,0 +1,14 @@
+Feature: Monitoring errors
+
+  Background:
+    Given I'm running the example "ui/components/storage/storage-browser/custom-actions"
+
+  @react
+  Scenario: Shows custom error boundary when unexpected error happens
+    Given I expect an exception
+    When I click the first button containing "my-prefix"
+    Then I see the "Menu Toggle" button
+    When I click the "Menu Toggle" button
+    Then I see the "Mock unexpected error" menuitem
+    When I click the "Mock unexpected error" menuitem
+    Then I see "An unexpected error has happened."

packages/react-storage/src/components/StorageBrowser/ErrorBoundary/ErrorBoundary.tsx

@@ -2,10 +2,6 @@ import React from 'react';
 
 import { STORAGE_BROWSER_BLOCK_TO_BE_UPDATED } from '../constants';
 
-interface ErrorBoundaryProps {
-  children: React.ReactNode;
-}
-
 interface ErrorBoundaryState {
   hasError: boolean;
 }
@@ -18,11 +14,13 @@ const Fallback = (): React.JSX.Element => (
   </div>
 );
 
+export type ErrorBoundaryType = React.ComponentType<React.PropsWithChildren>;
+
 export class ErrorBoundary extends React.Component<
-  ErrorBoundaryProps,
+  React.PropsWithChildren,
   ErrorBoundaryState
 > {
-  constructor(props: ErrorBoundaryProps) {
+  constructor(props: React.PropsWithChildren) {
     super(props);
     this.state = { hasError: false };
   }

packages/react-storage/src/components/StorageBrowser/ErrorBoundary/index.ts

@@ -1 +1 @@
-export { ErrorBoundary } from './ErrorBoundary';
+export { ErrorBoundary, ErrorBoundaryType } from './ErrorBoundary';

packages/react-storage/src/components/StorageBrowser/__tests__/createStorageBrowser.spec.tsx

@@ -99,4 +99,57 @@ describe('createStorageBrowser', () => {
       version: expect.any(String),
     });
   });
+
+  it('should accept custom error boundary', async () => {
+    class CustomErrorBoundary extends React.Component<React.PropsWithChildren> {
+      constructor(props: React.PropsWithChildren) {
+        super(props);
+      }
+
+      render() {
+        const { children } = this.props;
+        return (
+          <div>
+            <p>Custom Error Boundary</p>
+            {children}
+          </div>
+        );
+      }
+    }
+
+    const { StorageBrowser } = createStorageBrowser({
+      config: input.config,
+      ErrorBoundary: CustomErrorBoundary,
+    });
+
+    await waitFor(() => {
+      render(<StorageBrowser />);
+    });
+
+    expect(screen.getByText('Custom Error Boundary')).toBeInTheDocument();
+  });
+
+  it('should support disabling error boundary', () => {
+    const { StorageBrowser } = createStorageBrowser({
+      config: input.config,
+      ErrorBoundary: null,
+    });
+
+    const LocationsViewWithError = () => {
+      React.useEffect(() => {
+        throw new Error('Unexpected Error');
+      }, []);
+      return <StorageBrowser.LocationsView />;
+    };
+
+    expect(() => {
+      render(
+        <StorageBrowser
+          views={{
+            LocationsView: LocationsViewWithError,
+          }}
+        />
+      );
+    }).toThrow('Unexpected Error');
+  });
 });

packages/react-storage/src/components/StorageBrowser/createStorageBrowser.tsx

@@ -15,7 +15,7 @@ import { elementsDefault } from './context/elements';
 import { ComponentsProvider } from './ComponentsProvider';
 import { componentsDefault } from './componentsDefault';
 import { DisplayTextProvider } from './displayText';
-import { ErrorBoundary } from './ErrorBoundary';
+import { ErrorBoundary as DefaultErrorBoundary } from './ErrorBoundary';
 import { createConfigurationProvider, StoreProvider } from './providers';
 import { StorageBrowserDefault } from './StorageBrowserDefault';
 import {
@@ -131,6 +131,11 @@ export function createStorageBrowser<
     );
   }
 
+  const ErrorBoundary =
+    input.ErrorBoundary === null
+      ? React.Fragment
+      : input.ErrorBoundary ?? DefaultErrorBoundary;
+
   const StorageBrowser: StorageBrowserType<
     DerivedActionViewType<RInput>,
     DerivedActionViews<RInput>

packages/react-storage/src/components/StorageBrowser/types.ts

@@ -8,6 +8,7 @@ import {
 } from './actions';
 import { GetLocationCredentials } from './credentials/types';
 import { Components } from './ComponentsProvider';
+import { ErrorBoundaryType } from './ErrorBoundary';
 import { RegisterAuthListener, StoreProviderProps } from './providers';
 
 import {
@@ -44,6 +45,11 @@ export interface CreateStorageBrowserInput {
   actions?: StorageBrowserActions;
   config: Config;
   components?: Components;
+  /**
+   * Custom ErrorBoundary class. If omitted, a default ErrorBoundary is provided.
+   * To disable ErrorBoundary, set to `null`.
+   */
+  ErrorBoundary?: ErrorBoundaryType | null;
 }
 
 export interface StorageBrowserProps<K = string, V = {}> {