hook-example: Explain how useMap in code comments

- Show how useMap works on first render, second render
- Hint at useMap not working outside

Add console statements and code comments to reference how useMap works in the different situations. The code comment help understand that useMap returns undefined first; and what the shape of the returned object looks like.

The controls2 component shows how the "current" works when useMap is used inside a Map component.

All console logs are formatted as code comments so they are easy to reproduce but don't actually log.

Author: tordans

examples/get-started/hook/app.jsx

@@ -7,6 +7,8 @@ import Map from './map';
 import Controls from './controls';
 
 function Root() {
+  // Note: `useMap` will not work here, only child components of `MapProvider` or `Map` can use `useMap`
+
   return (
     <MapProvider>
       <Controls />

examples/get-started/hook/controls.jsx

@@ -4,7 +4,33 @@ import {useCallback, useState, useEffect} from 'react';
 import {useMap} from 'react-map-gl';
 
 export default function Controls() {
-  const {mymap} = useMap();
+  /**
+   * ## This is how `useMap` works:
+   * ```
+   * const demo = useMap();
+   * console.log('Controls', {demo});
+   * ```
+   * ### First render:
+   * ```
+   * {
+   *     "demo": {
+   *         "current": undefined
+   *     }
+   * }
+   * ```
+   * ### Second render:
+   * ```
+   * {
+   *   "demo": {
+   *     "current": undefined,
+   *     "mymap": {...} // See https://visgl.github.io/react-map-gl/docs/api-reference/types#mapref
+   *   }
+   * }
+   * ```
+   */
+
+  const {mymap} = useMap(); // `mymap` is the id in <Map id="mymap" />
+
   const [inputValue, setInputValue] = useState('');
   const [hasError, setError] = useState(false);
 

examples/get-started/hook/controls2.js

@@ -0,0 +1,26 @@
+import {useMap} from 'react-map-gl';
+
+export default function Controls2() {
+  /**
+   * ## This is how `useMap` works:
+   * This component does nothing. It's purpose is to demo `useMap`.
+   * When a component is a child of `<Map>`, `useMap` has a `current` field that references the containing map.
+   * See https://visgl.github.io/react-map-gl/docs/api-reference/use-map
+   * See https://visgl.github.io/react-map-gl/docs/api-reference/types#mapref
+   * ```
+   * const demo = useMap();
+   * console.log('Controls2', {demo});
+   * ```
+   * ### First render:
+   * ```
+   * {
+   *     "demo": {
+   *       "current": {...},
+   *       "mymap": {...}
+   *     }
+   * }
+   * ```
+   */
+
+  return null;
+}

examples/get-started/hook/map.jsx

@@ -1,14 +1,38 @@
 import * as React from 'react';
-import Map from 'react-map-gl';
+import Map, {useMap} from 'react-map-gl';
 
 import 'mapbox-gl/dist/mapbox-gl.css';
+import Controls2 from './controls2';
 
 const MAPBOX_TOKEN = ''; // Set your mapbox token here
 
 export default function MapView() {
+  /**
+   * ## This is how `useMap` works:
+   * ```
+   * const demo = useMap();
+   * console.log('MapView', {demo});
+   * ```
+   * ### First render:
+   * ```
+   * {
+   *     "demo": {
+   *         "current": undefined
+   *     }
+   * }
+   * Second render:
+   * {
+   *     "demo": {
+   *         "current": undefined,
+   *         "mymap": {...} // See https://visgl.github.io/react-map-gl/docs/api-reference/types#mapref
+   *     }
+   * }
+   * ```
+   */
+
   return (
     <Map
-      id="mymap"
+      id="mymap" // relevant for `useMap`, see control.js, controls2.js
       initialViewState={{
         longitude: -122.4,
         latitude: 37.8,
@@ -17,6 +41,8 @@ export default function MapView() {
       style={{width: 800, height: 600}}
       mapStyle="mapbox://styles/mapbox/streets-v9"
       mapboxAccessToken={MAPBOX_TOKEN}
-    />
+    >
+      <Controls2 />
+    </Map>
   );
 }