docs: update api-provider docs

Author: usefulthink

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

@@ -1,23 +1,42 @@
 # `<APIProvider>` Component
 
 The `APIProvider` is our component to load the Google Maps JavaScript API.
+Besides that, it provides context information and functions for the other
+components and hooks of this library.
+
+It can be added at any level of the application (typically somewhere
+at the top of your component-tree), and it will render all child components
+unmodified. A re-render is only triggered once the loading status of the
+Google Maps API changes.
+
+Normally, there should only be a single instance of the APIProvider in a page,
+but there are situations (e.g., multiple React render-roots in a page) where
+this isn't possible. In those cases, make sure to create all `APIProvider`
+components using the exact same props, since only the first one to
+render will actually load the maps API.
+
+When the Google Maps API has already been loaded externally
+(i.e., the [`google.maps.importLibrary`][gmp-import-library] function exists),
+the
+`APIProvider` will ignore all specified props and use the existing
+`importLibrary` function.
+
+:::info[Important]
+
+The Maps JavaScript API can only be loaded once, and settings like the
+language and region cannot be changed after loading. Therefore, it is
+important to make sure the props are specified with their final values when
+the `APIProvider` component is first rendered. Changing these props after the
+first render will in most cases have no effect, cause an error, or both.
 
-This component can be added at any level of the application (typically somewhere
-at the top), and it will render all child components unmodified.
-
-Besides handling the loading of the Maps JavaScript API, it also provides context
-information and functions for the other components and hooks of this library.
+:::
 
-> **Please Note:** since the Maps JavaScript API can only be loaded once, and
-> settings like the language and region cannot be changed after loading, it is
-> important to make sure the props are specified with their final values when
-> the APIProvider component is rendered. Changing these props after the first
-> render will in most cases have no effect, cause an error, or both.
+## Usage
 
 The `APIProvider` only needs the [Google Maps API Key][gmp-api-keys] to function.
 This has to be provided via the `apiKey` prop:
 
-```tsx title="app.jsx"
+```tsx
 import React from 'react';
 import {APIProvider} from '@vis.gl/react-google-maps';
 
@@ -34,9 +53,13 @@ export default App;
 The props are based on [the parameters][gmp-params] available for the
 'Dynamic Library Import' API which we are using under the hood.
 
-> Note that most of the props below are marked with 'first-render only',
-> which refers to the fact that these can only be specified on
-> first render, later changes to the values will have no effect.
+:::note
+
+Most of the props below are marked with 'first-render only',
+which refers to the fact that these can only be specified on
+first render, later changes to the values will have no effect.
+
+:::
 
 ### Required
 
@@ -96,8 +119,8 @@ map-instances, libraries and the loading-status.
 
 Client code should never need to interact with the context directly, always
 use the corresponding hooks instead.
-If you feel like you need to directly access the context, please file a
-bug report about this.
+If you feel like you need to directly access the context, please [file a
+bug report or feature request][rgm-new-issue] about this.
 
 :::
 
@@ -112,10 +135,12 @@ The following hooks are built to work with the `APIProvider` Component:
 
 [`src/components/api-provider.tsx`][api-provider-src].
 
+[gmp-import-library]: https://developers.google.com/maps/documentation/javascript/load-maps-js-api#dynamic-library-import
 [gmp-api-keys]: https://developers.google.com/maps/documentation/javascript/get-api-key
 [gmp-params]: https://developers.google.com/maps/documentation/javascript/load-maps-js-api#required_parameters
 [gmp-api-version]: https://developers.google.com/maps/documentation/javascript/versions
 [gmp-libs]: https://developers.google.com/maps/documentation/javascript/libraries
 [gmp-region]: https://developers.google.com/maps/documentation/javascript/localization#Region
 [gmp-lang]: https://developers.google.com/maps/documentation/javascript/localization
 [api-provider-src]: https://github.com/visgl/react-google-maps/blob/main/src/components/api-provider.tsx
+[rgm-new-issue]: https://github.com/visgl/react-google-maps/issues/new/choose