Update docs regarding react-map-gl integration

Make v7 control compatibility use cases more prominent

docs/README.md

@@ -104,7 +104,7 @@ deck.gl is developed in parallel with a number of companion modules, including:
 
 * [luma.gl](https://luma.gl/) - A general purpose WebGL library designed to be interoperable both with the raw WebGL API and (as far as possible) with other WebGL libraries. In particular, luma.gl does not claim ownership of the WebGL context, and can work with any supplied context, including contexts created by the application or other WebGL libraries.
 * [loaders.gl](https://loaders.gl) - a suite of framework-independent loaders for file formats focused on visualization of big data, including point clouds, 3D geometries, images, geospatial formats as well as tabular data.
-* [react-map-gl](https://visgl.github.io/react-map-gl/) - A React wrapper around Mapbox GL which works seamlessly with deck.gl.
+* [react-map-gl](https://visgl.github.io/react-map-gl/) - A React wrapper around Mapbox GL which works seamlessly with deck.gl either as a container holding deckgl layers, or as deck.gl's child interpreting deck.gl's view state.
 * [nebula.gl](https://nebula.gl/) - A high-performance feature editing framework for deck.gl.
 
 

docs/api-reference/mapbox/overview.md

@@ -37,6 +37,11 @@ One should note that this module is *not required* to use mapbox-gl as a base ma
 
 It may be easier to understand the concepts of the module if you are already a mapbox-gl developer.
 
+### Using mapbox-gl controls with deck.gl
+
+The Mapbox ecosystem offers many well-designed controls, from the basic functionalities of `NavigationControl`, `Popup` and `GeolocateControl`, to vendor-service-bound UI implementations such as `mapbox-gl-geocoder` and `mapbox-gl-directions`. These libraries require that the Mapbox Map holds the source of truth of the camera state, instead of the normal [state management](../../developer-guide/interactivity.md) by `Deck`. When you use the `MapboxLayer` or `MapboxOverlay` classes from this module, deck.gl plays nice with all the mapbox-gl peripherals.
+
+
 ### Mixing deck.gl layers and Mapbox layers
 
 One major use case for interleaving deck.gl and Mapbox is that some important information in the Mapbox map could be hidden by a deck.gl visualization layer, and controlling opacity is not enough. A typical example of this is labels and roads, where it is desirable to have a deck.gl visualization layer render on top of the Mapbox geography, but where one might still want to see e.g. labels and/or roads. Alternatively, the deck.gl visualization should cover the ground, but not the roads and labels.
@@ -52,11 +57,6 @@ Mapbox provides an example of [finding the first label layer](https://www.mapbox
 In some cases, the application wants to add a deck.gl 3D layer (e.g. ArcLayer, HexagonLayer, GeoJsonLayer) on top of a Mapbox basemap, while seamlessly blend into the z-buffer. This will interleave the useful visualization layers from both the deck.gl and Mapbox layer catalogs. In this case, a `beforeId` is not needed.
 
 
-### Using mapbox-gl controls with deck.gl
-
-The Mapbox ecosystem offers many well-designed controls, from the basic functionalities of `NavigationControl`, `Popup` and `GeolocateControl`, to vendor-service-bound UI implementations such as `mapbox-gl-geocoder` and `mapbox-gl-directions`. These libraries require that the Mapbox Map holds the source of truth of the camera state, instead of the normal [state management](../../developer-guide/interactivity.md) by `Deck`. When you use the `MapboxLayer` or `MapboxOverlay` classes from this module, deck.gl plays nice with all the mapbox-gl peripherals.
-
-
 ## Limitations
 
 * When using deck.gl's multi-view system, only one of the views can match the base map and receive interaction. See [using MapboxOverlay with multi-views](./mapbox-overlay.md#multi-view-usage) for details.

docs/developer-guide/base-maps/using-with-mapbox.md

@@ -6,23 +6,25 @@
 
 [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is a powerful open-source map renderer from [Mapbox](https://mapbox.com). deck.gl's `MapView` is designed to sync perfectly with the camera of Mapbox, at every zoom level and rotation angle.
 
-When using deck.gl and Mapbox, there are three options you can choose from:
+When using deck.gl and Mapbox, there are three options you can choose from, first based on which library handles all user input and holds the source of truth of the camera state (dictating which is the root component), and second how the content from both libraries interact (allowing simple overlaying or requiring complex interleaving).
 
-- Using the Deck canvas as a overlay on top of the Mapbox map, and Deck as the root element. In this option, deck.gl handles all user input, and holds the source of truth of the camera state. The [React get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/mapbox/) illustrates the basic pattern. This is the most tested and robust use case, as you can find in all the [examples on this website](https://deck.gl/examples/website). It supports all the features of Deck.
-- Using the Deck canvas as a overlay on top of the Mapbox map, and Mapbox as the root element. In this option, mapbox-gl handles all user input, and holds the source of truth of the camera state. The [vanilla JS get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox/) illustrates this pattern. The `MapboxOverlay` class in [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) implements the mapbox-gl control interface to insert deck into the map container. This is favorable if you need to use other mapbox-gl controls and plugins in addition to deck.gl.
-- Using deck.gl layers interleaved with Mapbox layers in the same WebGL context, using either the `MapboxOverlay` or `MapboxLayer` from the [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) module. This allows you to mix deck.gl layers with base map layers, e.g. below text labels or occlude each other correctly in 3D. Be cautious that this feature subjects to bugs and limitations of mapbox-gl's custom layer interface.
+- If you don't use the most advanced features of Deck such as non-mercator projection or terrain, and if you want to use basic mapbox-gl controls (e.g. `NavigationControl`) or plugins in addition to deck.gl while using the latest version of react-map-gl v7, then you have to use Mapbox as the root element. The recommended approach is then to use the Deck canvas as an overlay on top of the basemap, inserted into the map container using [MapboxOverlay](https://deck.gl/docs/api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) in its default mode (overlaid). The [vanilla JS get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox/) illustrates this pattern.
+- Otherwise, if you are fine with using previous versions of react-map-gl or not using mapbox-gl controls at all, then the recommended approach is to use Deck as the root element with its canvas as an overlay on top of the child Mapbox map. The [React get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/mapbox/) illustrates the basic pattern using react-map-gl v5/v6 APIs. This is the most tested and robust use case with respect to Deck's functionality, as you can find in all the [examples on this website](https://deck.gl/examples/). It supports all the most advanced features of Deck.
+- Finally, if you need to mix deck.gl layers with base map layers, e.g. having deck.gl surfaces below text labels or objects occluding each other correctly in 3D, then you have to use deck.gl layers interleaved with Mapbox layers in the same WebGL context. In addition to using Mapbox as the root element, you have to use either the `MapboxOverlay` in interleaved mode or `MapboxLayer` from the [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) module. Be cautious that this feature subjects to bugs and limitations of mapbox-gl's custom layer interface. Here's an [interactive example](https://deck.gl/examples/mapbox), and in the following image, notice that the yellow circles (first deck.gl layer) are between the ground (first mapbox layer) and the labels (second mapbox layer) and also below the buildings (third mapbox layer) which correctly occlude the arcs (second deck.gl layer)
 
 ![deck.gl interleaved with Mapbox layers](https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/mapbox-layers.jpg)
 
 ## react-map-gl
 
 [react-map-gl](https://github.com/visgl/react-map-gl) is a React wrapper around mapbox-gl. If you'd like to use deck.gl with React, this component is the recommended companion.
 
-All the [examples on this website](https://github.com/visgl/deck.gl/tree/master/examples/website) are implemented using the React integration. The `DeckGL` React component works especially well as the parent of a react-map-gl [Map](https://visgl.github.io/react-map-gl/docs/api-reference/map), which automatically interprets the deck.gl view state (i.e. latitude, longitude, zoom etc). In this configuration your deck.gl layers will render as a perfectly synchronized geospatial overlay over the underlying map.
+All the [examples on this website](https://github.com/visgl/deck.gl/tree/master/examples/website) are implemented using the React integration.
 
-> `react-map-gl` v5 and v6 exports React controls (`NavigationControl`, `GeolocateControl` etc.) that can be used with `DeckGL` with or without a base map. See [ContextProvider](../../api-reference/react/deckgl.md#contextprovider) for an example.
+When you choose the react-map-gl `Map` React component as the root component, using [MapboxOverlay](https://deck.gl/docs/api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) with react-map-gl `useControl` or [MapboxLayer](https://deck.gl/docs/api-reference/mapbox/mapbox-layer#example) works especially well to insert perfectly synchronized deckgl layers in the map container.
 
-> To use deck.gl with `react-map-gl` v7's controls, you must use [MapboxOverlay](https://deck.gl/docs/api-reference/mapbox/mapbox-overlay#using-with-react-map-gl).
+When you choose the `DeckGL` React component as the root component, react-map-gl [Map](https://visgl.github.io/react-map-gl/docs/api-reference/map) as a child automatically interprets the deck.gl view state (i.e. latitude, longitude, zoom etc). In this configuration your deck.gl layers will still render as a perfectly synchronized geospatial overlay over the underlying map.
+
+> Unfortunately, as noted at the begining of this page, using `DeckGL` as the root component is not compatible with `react-map-gl` v7's controls (`NavigationControl`, `GeolocateControl` etc.) because of `react-map-gl` decisions to prioritize its own maintainability, performance, and compatibility when used standalone. However, it is still possible with the v5 and v6 previous `react-map-gl` versions since the controls can be used with or without a base map. See [ContextProvider](../../api-reference/react/deckgl.md#contextprovider) for an example.
 
 ## Using Mapbox basemap service (with Mapbox token)