docs: Add documentation for accessing the map object in <MapView> (#1936)

* Add documentation for ref and useMap

* Link to React's useRef hook

Author: slaymance

docs/src/pages/[platform]/components/geo/fragments/map-ref.react.mdx

@@ -0,0 +1,26 @@
+```jsx{12,15,21}
+import { Button, MapView } from '@aws-amplify/ui-react';
+import { Amplify } from 'aws-amplify';
+import { useCallback, useRef } from 'react';
+
+import '@aws-amplify/ui-react/styles.css';
+
+import awsExports from './aws-exports';
+
+Amplify.configure(awsExports);
+
+export default function MapWithRef() {
+  const mapRef = useRef();
+
+  const flyToMordor = useCallback(() => {
+    mapRef.current.flyTo({ center: [172.78, -42.28], zoom: 5 });
+  }, []);
+
+  return (
+    <>
+      <Button onClick={flyToMordor}>Fly, you fools!</Button>
+      <MapView ref={mapRef} />
+    </>
+  );
+}
+```

docs/src/pages/[platform]/components/geo/fragments/use-map.react.mdx

@@ -0,0 +1,29 @@
+```jsx
+import { Button, MapView } from '@aws-amplify/ui-react';
+import { Amplify } from 'aws-amplify';
+import { useMap } from 'react-map-gl';
+
+import '@aws-amplify/ui-react/styles.css';
+
+import awsExports from './aws-exports';
+
+Amplify.configure(awsExports);
+
+function FlyToButton() {
+  const { current: map } = useMap();
+
+  const flyToMordor = () => {
+    map.flyTo({ center: [172.78, -42.28], zoom: 5 });
+  };
+
+  return <Button onClick={flyToMordor}>Fly, you fools!</Button>;
+}
+
+export default function MapWithButton() {
+  return (
+    <MapView>
+      <FlyToButton />
+    </MapView>
+  );
+}
+```

docs/src/pages/[platform]/components/geo/react.mdx

@@ -61,6 +61,20 @@ when the marker is clicked. The `offset` property can be used to prevent the pop
 _Note: Ensure `originalEvent.stopPropagation()` is called in the marker click handler. This allows the `showPopup`
 state to be handled by the component._
 
+### Animation and Native Map Methods
+
+You may want to access the [native maplibre-gl map object](https://maplibre.org/maplibre-gl-js-docs/api/map/) from within the component that renders `<MapView>` (to animate a viewport transition with `flyTo`, for example). To accomplish this, you can pass your own ref to `<MapView>` using [React's `useRef` hook](https://reactjs.org/docs/hooks-reference.html#useref) which will contain the `map` object:
+
+<Fragment platforms={['react']}>
+  {({ platform }) => import(`./fragments/map-ref.${platform}.mdx`)}
+</Fragment>
+
+If you want access to the `map` object in a child component of `<MapView>`, you can use the [useMap hook from react-map-gl](https://visgl.github.io/react-map-gl/docs/api-reference/use-map) instead:
+
+<Fragment platforms={['react']}>
+  {({ platform }) => import(`./fragments/use-map.${platform}.mdx`)}
+</Fragment>
+
 ## Location Search
 
 _Component can also be imported as `Geocoder`_