feat: add new onError prop for api provider (#541)

Add an optional prop onError to the APIProvider that will trigger if the Maps JavaScript API fails to load.

Author: timmchi

docs/api-reference/components/api-provider.md

@@ -105,12 +105,12 @@ A list of [libraries][gmp-libs] to load immediately
 
 #### `solutionChannel`: string
 
-To help Google to better understand types of usage of the Google Maps 
-JavaScript API, the query parameter `solution_channel` can be set when 
-loading the API. 
+To help Google to better understand types of usage of the Google Maps
+JavaScript API, the query parameter `solution_channel` can be set when
+loading the API.
 
-The `@vis.gl/react-google-maps` library will by default set 
-this to a generic value unique to this library (`GMP_VISGL_react`). You may 
+The `@vis.gl/react-google-maps` library will by default set
+this to a generic value unique to this library (`GMP_VISGL_react`). You may
 opt out at any time by setting this prop to an empty string.
 Read more in the [documentation][gmp-solutions-usage].
 
@@ -121,6 +121,11 @@ Read more in the [documentation][gmp-solutions-usage].
 a callback that is called once the Maps JavaScript
 API finished loading.
 
+#### `onError`: (error: unknown) => void {#onError}
+
+a callback that is called if there is an error loading
+the Google Maps JavaScript API.
+
 ## Context
 
 The APIProvider creates a context value `APIProviderContext` to be used by

src/components/__tests__/api-provider.test.tsx

@@ -27,6 +27,7 @@ const ContextSpyComponent = () => {
 ContextSpyComponent.spy = jest.fn();
 
 let triggerMapsApiLoaded: () => void;
+let triggerLoadingFailed: () => void;
 
 jest.mock('../../libraries/google-maps-api-loader', () => {
   class GoogleMapsApiLoader {
@@ -38,14 +39,20 @@ jest.mock('../../libraries/google-maps-api-loader', () => {
       onLoadingStatusChange(APILoadingStatus.LOADING);
 
       google.maps.importLibrary = importLibraryMock;
-      return new Promise(
-        resolve =>
-          (triggerMapsApiLoaded = () => {
-            resolve();
-            onLoadingStatusChange(APILoadingStatus.LOADED);
-          })
-      );
+
+      return new Promise((resolve, reject) => {
+        triggerLoadingFailed = () => {
+          reject();
+          onLoadingStatusChange(APILoadingStatus.FAILED);
+        };
+
+        triggerMapsApiLoaded = () => {
+          resolve();
+          onLoadingStatusChange(APILoadingStatus.LOADED);
+        };
+      });
     }
+
     static unload() {
       apiUnloadSpy();
     }
@@ -178,3 +185,13 @@ test('map instance management: add, access and remove', async () => {
   actualContext = contextSpy.mock.lastCall[0];
   expect(actualContext.mapInstances).toEqual({'map-id-2': map2});
 });
+
+test('calls onError when loading the Google Maps JavaScript API fails', async () => {
+  const onErrorMock = jest.fn();
+
+  render(<APIProvider apiKey={'apikey'} onError={onErrorMock}></APIProvider>);
+
+  await act(() => triggerLoadingFailed());
+
+  expect(onErrorMock).toHaveBeenCalled();
+});

src/components/api-provider.tsx

@@ -79,6 +79,10 @@ export type APIProviderProps = {
    * A function that can be used to execute code after the Google Maps JavaScript API has been loaded.
    */
   onLoad?: () => void;
+  /**
+   * A function that will be called if there was an error when loading the Google Maps JavaScript API.
+   */
+  onError?: (error: unknown) => void;
 };
 
 /**
@@ -110,7 +114,14 @@ function useMapInstances() {
  * @param props
  */
 function useGoogleMapsApiLoader(props: APIProviderProps) {
-  const {onLoad, apiKey, version, libraries = [], ...otherApiParams} = props;
+  const {
+    onLoad,
+    onError,
+    apiKey,
+    version,
+    libraries = [],
+    ...otherApiParams
+  } = props;
 
   const [status, setStatus] = useState<APILoadingStatus>(
     GoogleMapsApiLoader.loadingStatus
@@ -176,10 +187,14 @@ function useGoogleMapsApiLoader(props: APIProviderProps) {
             onLoad();
           }
         } catch (error) {
-          console.error(
-            '<ApiProvider> failed to load the Google Maps JavaScript API',
-            error
-          );
+          if (onError) {
+            onError(error);
+          } else {
+            console.error(
+              '<ApiProvider> failed to load the Google Maps JavaScript API',
+              error
+            );
+          }
         }
       })();
     },