[Doc] Update Mapbox docs regarding deck v9 and react-map-gl v7

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. There are two integration modes to choose from depending on which features you need: either as a container holding deckgl layers (allowing more react-map-gl features such as controls and terrain), or as deck.gl's child interpreting deck.gl's view state (allowing more Deck features, such as multi-view and effects).
 * [nebula.gl](https://nebula.gl/) - A high-performance feature editing framework for deck.gl.
 
 

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

@@ -133,7 +133,7 @@ new MapboxOverlay(props);
 
 The constructor additionally accepts the following option:
 
-- `interleaved` (Boolean) - If `false`, a dedicated deck.gl canvas is added on top of the base map. If `true`, deck.gl layers are inserted into mapbox-gl's layer stack, and share the same WebGLRenderingContext as the base map. Default is `false`.
+- `interleaved` (Boolean) - If `false`, a dedicated deck.gl canvas is added on top of the base map. If `true`, deck.gl layers are inserted into mapbox-gl's layer stack, and share the same WebGL2RenderingContext as the base map. Default is `false`. Interleaving with WebGL1 is not supported. See [compatibility](./overview#compatibility).
 
 When using `interleaved: true`, you may optionally add a `beforeId` prop to a layer to specify its position in the Mapbox layer stack. If multiple deck.gl layers have the same `beforeId`, they are rendered in the order that is passed into the `layers` array.
 

docs/api-reference/mapbox/overview.md

@@ -1,6 +1,8 @@
 # @deck.gl/mapbox
 
-This module makes it easy to use deck.gl as native layers and controls in the Mapbox GL JS ecosystem. 
+This module makes it easy to use deck.gl as native layers and controls in the Mapbox and Maplibre GL JS ecosystem. 
+
+> For brevity, the term 'mapbox-gl' will refer collectively to any library that is compatible with Mapbox GL JS, including but not limited to maplibre-gl. Known exceptions will be clearly marked. For more, see [Compatibility with Mapbox GL JS forks](../../developer-guide/base-maps/using-with-mapbox.md#compatibility-with-mapbox-gl-js-forks)
 
 - It allows deck.gl to be used with other mapbox-gl controls such as `NavigationControl`, `GeolocateControl` and `mapbox-gl-geocoder`.
 - You may choose to interleave deck.gl layers with the base map layers, such as drawing behind map labels, z-occlusion between deck.gl 3D objects and Mapbox buildings, etc.
@@ -13,8 +15,8 @@ This module makes it easy to use deck.gl as native layers and controls in the Ma
 ### Include the Standalone Bundle
 
 ```html
-<script src="https://unpkg.com/deck.gl@^8.1.0/dist.min.js"></script>
-<script src='https://api.tiles.mapbox.com/mapbox-gl-js/v1.10.0/mapbox-gl.js'></script>
+<script src="https://unpkg.com/deck.gl@^9.0.0/dist.min.js"></script>
+<script src='https://api.tiles.mapbox.com/mapbox-gl-js/v2.13.0/mapbox-gl.js'></script>
 <script type="text/javascript">
   const {MapboxOverlay} = deck;
 </script>
@@ -33,29 +35,42 @@ import {MapboxOverlay} from '@deck.gl/mapbox';
 
 ## Use Cases
 
-One should note that this module is *not required* to use mapbox-gl as a base map for deck.gl. When you use this module, Mapbox is the root element and deck.gl is the child, with Mapbox handling all user inputs. Some of deck.gl's features are therefore unavailable due to limitations of mapbox-gl's API, see [limitations](#limitations) below. If you just want the base map as a back drop, and do not need mapbox-gl's UI controls or mixing deck and Mapbox layers, it is recommended that you use deck.gl as the root element. Visit the [mapbox base map developer guide](../../developer-guide/base-maps/using-with-mapbox.md) for examples of each option.
+One should note that this module is *not required* to use mapbox-gl as a base map for deck.gl. When you use this module, Mapbox is the root element and deck.gl is the child, with Mapbox handling all user inputs. Some of deck.gl's features are therefore unavailable due to limitations of mapbox-gl's API, see [limitations](#limitations) and [compatibility](#compatibility) below. If you just want the base map as a back drop, and do not need mapbox-gl's UI controls or mixing deck and Mapbox layers, it is recommended that you use deck.gl as the root element. Visit the [mapbox base map developer guide](../../developer-guide/base-maps/using-with-mapbox.md) for examples of each option.
 
 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 `MapboxOverlay` or `MapboxLayer` 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.
 
 To inject a deck layer into the Mapbox stack, either:
 
+- Add a `beforeId` prop to any layer passed to the [MapboxOverlay](./mapbox-overlay.md) control (recommended).
 - Create a [MapboxLayer](./mapbox-layer.md) and call the [`map.addLayer(layer, before?)`](https://www.mapbox.com/mapbox-gl-js/api/#map#addlayer) API.
-- Add a `beforeId` prop to any layer passed to the [MapboxOverlay](./mapbox-overlay.md) control.
 
 Mapbox provides an example of [finding the first label layer](https://www.mapbox.com/mapbox-gl-js/example/geojson-layer-in-stack/). For more sophisticated injection point lookups, refer to Mapbox' documentation on the format of Mapbox style layers, see [Mapbox Style Spec](https://www.mapbox.com/mapbox-gl-js/style-spec/#layers).
 
 
 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.
 
+## Compatibility
 
-### Using mapbox-gl controls with deck.gl
+Libraries utilizing WebGL1 cannot be interleaved with deck.gl. deck.gl has phased out support for WebGL1, requiring WebGL2 at a minimum. The following table details WebGL support across different versions of mapbox-gl and maplibre-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.
+| Library                       | WebGL Version   | Overlay Support | Interleaved Support |
+|-------------------------------|-----------------|-----------------|---------------------|
+| mapbox-gl (before v2.13)      | WebGL1          | Yes             | No                  |
+| mapbox-gl-js v2.13+           | WebGL1 & WebGL2 | Yes             | Yes, with `useWebGl2` flag |
+| mapbox-gl-js v3+              | WebGL2          | Yes             | Yes                 |
+| maplibre-gl-js (before v3)    | WebGL1          | Yes             | No                  |
+| maplibre-gl-js v3+            | WebGL2*         | Yes             | Yes                 |
 
+> *will fallback to WebGL1 if WebGL2 is not available
 
 ## Limitations
 

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

@@ -6,23 +6,27 @@
 
 [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 and gl context sharing).
 
-- 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 multi-view and effects, and want to use all the features of mapbox-gl, such as controls like `NavigationControl` or plugins, 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](../../api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) from the [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) module in its default mode (overlaid, which corresponds to `interleaved: false`). The [react get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/mapbox/) illustrates this pattern.
+- Otherwise, if you need the more advanced features of Deck, 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 [Minimap example](https://deck.gl/examples/multi-view) illustrates the basic pattern. This is the most tested and robust use case with respect to Deck's functionality, as you can find it in most of the [layer examples on this website](https://deck.gl/examples). You can't use all the features of mapbox-gl like controls (e.g. `NavigationControl`) and plugins, but you can instead use [@deck.gl/widgets](../../api-reference/widgets/overview). 
+- 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 (option 1), you have to use [MapboxOverlay](../../api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) in interleaved mode (`interleaved: true`). Be cautious that this feature subjects to bugs and limitations of mapbox-gl's custom layer interface, and is only compatible with WebGL2 (See [compatibility](../../api-reference/mapbox/overview#compatibility)). 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](../../api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) with react-map-gl `useControl` 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` controls (`NavigationControl`, `GeolocateControl` etc.) because of `react-map-gl` decisions to prioritize its own maintainability, performance, and compatibility when used standalone.
+
+> If you are constrained to using mapbox layers instead of a mapbox control, you can use [MapboxLayer](../../api-reference/mapbox/mapbox-layer#example) but in the general use case it is no longer recommended. Its functionality can be fully replaced by [MapboxOverlay](../../api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) with interleaved: true
 
 ## Using Mapbox basemap service (with Mapbox token)
 
@@ -63,4 +67,4 @@ Some useful resources for creating your own map service:
 
 - [Mapbox Vector Tile Spec](https://www.mapbox.com/developers/vector-tiles/)
 - [Open source tools](https://github.com/mapbox/awesome-vector-tiles)
-- [Maputnik Style editor](https://maputnik.github.io)
+- [Maputnik Style editor](https://maputnik.github.io)