Merge 5a17ecd into 4c4db33

docs/api-reference/google-maps/google-maps-overlay.md

@@ -2,40 +2,111 @@
 
 This class implements the [OverlayView](https://developers.google.com/maps/documentation/javascript/reference/overlay-view#OverlayView)/[WebGLOverlayView](https://developers.google.com/maps/documentation/javascript/reference/webgl#WebGLOverlayView) (depending on map rendering type) interface and can be used as any other Google Maps overlay.
 
-## Vector/Raster maps
-
 As detailed in the [overview](./overview.md), the overlay supports both Vector and Raster Google map rendering. Depending on the Google Map configuration, the correct deck.gl overlay rendering method will be chosen at runtime.
 
-## Usage
+## Example
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs groupId="language">
+  <TabItem value="ts" label="TypeScript">
 
-```js
-  import {GoogleMapsOverlay as DeckOverlay} from '@deck.gl/google-maps';
-  import {GeoJsonLayer} from '@deck.gl/layers';
+```ts
+import {Loader} from "@googlemaps/js-api-loader";
+import {GoogleMapsOverlay} from '@deck.gl/google-maps';
+import {ScatterplotLayer} from '@deck.gl/layers';
 
-  // Create map
-  const map = new google.maps.Map(document.getElementById('map'), {
-    center: { lat: 40, lng: -100 },
+const loader = new Loader({
+  apiKey: '<google_maps_api_key>',
+  version: "quarterly"
+});
+
+loader.importLibrary('maps').then((googlemaps) => {
+  const map = new googlemaps.Map(document.getElementById('map'), {
+    center: {lat: 51.47, lng: 0.45},
     zoom: 5,
-    mapId: GOOGLE_MAP_ID // Only required for Vector maps
+    mapId: '<google_map_id>'
   });
 
-  // Create overlay instance
-  const overlay = new DeckOverlay({
+  const overlay = new GoogleMapsOverlay({
     layers: [
-      new GeoJsonLayer({
-        ...
+      new ScatterplotLayer({
+        id: 'deckgl-circle',
+        data: [
+          {position: [0.45, 51.47]}
+        ],
+        getPosition: d => d.position,
+        getFillColor: [255, 0, 0, 100],
+        getRadius: 1000
       })
     ]
   });
-  // Add overlay to map
+
   overlay.setMap(map);
+});
 ```
 
+  </TabItem>
+  <TabItem value="react" label="React">
+
+```tsx
+import React, {useMemo, useEffect} from 'react';
+import {APIProvider, Map, useMap} from '@vis.gl/react-google-maps';
+import {DeckProps} from '@deck.gl/core';
+import {ScatterplotLayer} from '@deck.gl/layers';
+import {GoogleMapsOverlay} from '@deck.gl/google-maps';
+
+function DeckGLOverlay(props: DeckProps) {
+  const map = useMap();
+  const overlay = useMemo(() => new GoogleMapsOverlay(props));
+
+  useEffect(() => {
+    if (map) {
+      overlay.setMap(map);
+      return () => overlay.setMap(null);
+    }
+    return undefined;
+  }, [map])
+
+  overlay.setProps(props);
+  return null;
+}
+
+function App() {
+  const layers = [
+    new ScatterplotLayer({
+      id: 'deckgl-circle',
+      data: [
+        {position: [0.45, 51.47]}
+      ],
+      getPosition: d => d.position,
+      getFillColor: [255, 0, 0, 100],
+      getRadius: 1000
+    })
+  ];
+
+  return <APIProvider apiKey="<google_maps_api_key>">
+    <Map
+      defaultCenter={{lat: 51.47, lng: 0.45}}
+      defaultZoom={4}
+      mapId="<google_maps_id>" >
+      <DeckGLOverlay layers={layers} />
+    </Map>
+  </APIProvider>;
+}
+```
+
+  </TabItem>
+</Tabs>
 
 ## Constructor
 
-```js
-const overlay = new GoogleMapsOverlay(props)
+```ts
+import {GoogleMapsOverlay} from '@deck.gl/google-maps';
+import type {GoogleMapsOverlayProps} from '@deck.gl/google-maps';
+
+new GoogleMapsOverlay(props: GoogleMapsOverlayProps);
 ```
 
 `props` are forwarded to a `Deck` instance. The following [Deck](../core/deck.md) props are supported:
@@ -59,15 +130,15 @@ The constructor additionally accepts the following option:
 
 #### `setMap` {#setmap}
 
-```js
+```ts
 overlay.setMap(map);
 ```
 
 Add/remove the overlay from a map. An overlay can be temporarily hidden from a map by calling `setMap(null)`. Removing an overlay does not destroy the WebGL2 context; use `finalize()` if the overlay should be permanently removed.
 
 #### `setProps` {#setprops}
 
-```js
+```ts
 overlay.setProps(props);
 ```
 
@@ -87,12 +158,8 @@ Equivalent of [deck.pickMultipleObjects](../core/deck.md).
 
 #### `finalize` {#finalize}
 
-```js
-overlay.finalize();
-```
-
 Remove the overlay and release all underlying resources.
 
 ##### getCanvas
 
-See [Deck.getCanvas](../core/deck.md#getcanvas). When using `interleaved: true`, returns the base map's `canvas`.
+See [Deck.getCanvas](../core/deck.md#getcanvas). When using `interleaved: true`, returns the base map's `canvas`.

docs/api-reference/mapbox/mapbox-overlay.md

@@ -4,130 +4,113 @@
 
 ## Example
 
-### Overlaid
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-```js
-import {MapboxOverlay} from '@deck.gl/mapbox';
-import {ScatterplotLayer} from '@deck.gl/layers';
+<Tabs groupId="language">
+  <TabItem value="ts" label="TypeScript">
 
-const map = new mapboxgl.Map({
-  center: [-74.5, 40],
-  zoom: 14,
-  antialias: true // Improves the rendering quality
-});
-
-const overlay = new MapboxOverlay({
-  interleaved: false,
-  layers: [
-    new ScatterplotLayer({
-      id: 'my-scatterplot',
-      data: [
-        {position: [-74.5, 40], size: 100}
-      ],
-      getPosition: d => d.position,
-      getRadius: d => d.size,
-      getFillColor: [255, 0, 0]
-    })
-  ]
-});
-
-map.addControl(overlay);
-```
-
-### Interleaved
-
-```js
+```ts
 import {MapboxOverlay} from '@deck.gl/mapbox';
 import {ScatterplotLayer} from '@deck.gl/layers';
+import mapboxgl from 'mapbox-gl';
+import 'mapbox-gl/dist/mapbox-gl.css';
 
 const map = new mapboxgl.Map({
-  center: [-74.5, 40],
-  zoom: 14,
-  antialias: true // Improves the rendering quality
+  container: 'map',
+  style: 'mapbox://styles/mapbox/light-v9',
+  accessToken: '<mapbox_access_token>',
+  center: [0.45, 51.47],
+  zoom: 11
 });
 
-const overlay = new MapboxOverlay({
-  interleaved: true,
-  layers: [
-    new ScatterplotLayer({
-      id: 'my-scatterplot',
-      data: [
-        {position: [-74.5, 40], size: 100}
-      ],
-      getPosition: d => d.position,
-      getRadius: d => d.size,
-      getFillColor: [255, 0, 0],
+map.once('load', () => {
+  const deckOverlay = new MapboxOverlay({
+    interleaved: true,
+    layers: [
+      new ScatterplotLayer({
+        id: 'deckgl-circle',
+        data: [
+          {position: [0.45, 51.47]}
+        ],
+        getPosition: d => d.position,
+        getFillColor: [255, 0, 0, 100],
+        getRadius: 1000,
+        beforeId: 'waterway-label' // In interleaved mode render the layer under map labels
+      })
+    ]
+  });
 
-      beforeId: 'admin_labels' // Insert before this Mapbox layer
-    })
-  ]
+  map.addControl(deckOverlay);
 });
-
-map.addControl(overlay);
 ```
 
-### Using with [react-map-gl](https://visgl.github.io/react-map-gl)
-
-The following code demonstrates how to create a React component from `MapboxOverlay` with `react-map-gl@7.x` and Typescript:
+  </TabItem>
+  <TabItem value="react" label="React">
 
 ```tsx
+import React from 'react';
+import {Map, useControl} from 'react-map-gl';
+import {MapboxOverlay} from '@deck.gl/mapbox';
+import {DeckProps} from '@deck.gl/core';
 import {ScatterplotLayer} from '@deck.gl/layers';
-import {MapboxOverlay, MapboxOverlayProps} from '@deck.gl/mapbox';
-import {useControl} from 'react-map-gl';
+import 'mapbox-gl/dist/mapbox-gl.css';
 
-import Map, {NavigationControl} from 'react-map-gl';
-
-function DeckGLOverlay(props: MapboxOverlayProps & {
-  interleaved?: boolean;
-}) {
+function DeckGLOverlay(props: DeckProps) {
   const overlay = useControl<MapboxOverlay>(() => new MapboxOverlay(props));
   overlay.setProps(props);
   return null;
 }
 
-export default function App() {
-  const scatterplotLayer = new ScatterplotLayer({
-    id: 'my-scatterplot',
-    data: [
-      {position: [-74.5, 40], size: 100}
-    ],
-    getPosition: d => d.position,
-    getRadius: d => d.size,
-    getFillColor: [255, 0, 0]
-  });
+function App() {
+  const layers: [
+    new ScatterplotLayer({
+      id: 'deckgl-circle',
+      data: [
+        {position: [0.45, 51.47]}
+      ],
+      getPosition: d => d.position,
+      getFillColor: [255, 0, 0, 100],
+      getRadius: 1000,
+      beforeId: 'waterway-label' // In interleaved mode render the layer under map labels
+    })
+  ];
 
   return (
     <Map
       initialViewState={{
-        latitude: 40,
-        longitude: -74.5,
-        zoom: 12
+        longitude: 0.45,
+        latitude: 51.47,
+        zoom: 11
       }}
       mapStyle="mapbox://styles/mapbox/light-v9"
-      mapboxAccessToken=""
+      mapboxAccessToken="<mapbox_access_token>"
     >
-      <DeckGLOverlay layers={[scatterplotLayer]} />
-      <NavigationControl />
+      <DeckGLOverlay layers={layers} interleaved />
     </Map>
   );
 }
 ```
 
 See react-map-gl's [useControl](https://visgl.github.io/react-map-gl/docs/api-reference/use-control) hook.
-See [using deck.gl with Typescript](https://deck.gl/docs/get-started/using-with-typescript).
+
+  </TabItem>
+</Tabs>
 
 
 ## Constructor
 
-```js
+```ts
 import {MapboxOverlay} from '@deck.gl/mapbox';
-new MapboxOverlay(props);
+import type {MapboxOverlayProps} from '@deck.gl/mapbox';
+
+new MapboxOverlay(props: MapboxOverlayProps);
 ```
 
 `MapboxOverlay` accepts the same props as the [Deck](../core/deck.md) class, with the following exceptions:
 
 - `views` - multi-view support is limited. There is only one `MapView` that can synchronize with the base map. See the [using with multi-views](#multi-view-usage) section for details.
-- `parent` / `canvas` / `gl` - context creation is managed internally.
+- `parent` / `canvas` / `device` - context creation is managed internally.
 - `viewState` / `initialViewState` - camera state is managed internally.
 - `controller` - always disabled (to use Mapbox's interaction handlers).
 
@@ -141,7 +124,7 @@ When using `interleaved: true`, you may optionally add a `beforeId` prop to a la
 
 ##### setProps
 
-```js
+```ts
 const overlay = new MapboxOverlay({
   interleaved: true,
   layers: []
@@ -188,7 +171,7 @@ With that said, it is still possible to take advantage of deck's multi-view syst
 - To use multiple views, define a `MapView` with the id `“mapbox”`. This view will receive the state that matches the base map at each render.
 - If views are provided but the array does not contain this id, then a `MapView({id: 'mapbox'})` will be inserted at the bottom of the stack.
 
-```js
+```ts
 import {MapboxOverlay} from '@deck.gl/mapbox';
 import {Deck, MapView, OrthographicView} from '@deck.gl/core';
 import {ScatterplotLayer} from '@deck.gl/layers';