[Doc] Clarify future roadmaps regarding react-map-gl v7 APIs

[jonenst]

Link

#7129

Description

Should https://deck.gl/docs/developer-guide/base-maps/using-with-mapbox#react-map-gl
recommend MapBoxOverlay first instead of Root Deck first because MapBoxOverlay allows to use all the features of the latest react-map-gl version (controls, which can be argued to be basic functionality of map) and has been used for a while now ?

note: Not sure about react-map-gl with maplibre or mapbox 1? does it work transparently ?

To decide this, a bit of context about how long and why there's this apparent paradox between the most robust form of using deck not supporting all features of recent react-map-gl versions ? Is this temporary ? Should everyone rewrite their code (and accept the new runtime behaviors) to use MapboxOverlay? Or will it be obsolete with react-map-gl 8 or deckgl 9 or something else and we just have to wait ? It's hard to know from a user point of view.

[Pessimistress]

The page you linked already contains paragraphs that explain what you need to do to use map controls depending on your react-map-gl version. Feel free to suggest a change if it's not clear to you.

how long and why there's this apparent paradox between the most robust form of using deck not supporting all features of recent react-map-gl versions

@deck.gl/core and @deck.gl/react do not require a base map to work, and they do not contain logic for any specific base map provider. Similarly, react-map-gl does not contain any logic for deck.gl. These libraries can work with each other, but are not made for each other. It is very important that users who do not need Mapbox do not have to bring such dependencies into their code base.

We do our best to make the integration painless, but it is never a goal for one library to support "all features" of another. You are only focusing on the control components, but there are a lot more features there that are incompatible, such as non-mercator projection, terrain, etc. Most of them are unsupported not by choice, but by how much API mapbox/maplibre opens to third-party developers.

will it be obsolete with react-map-gl 8 or deckgl 9 or something else and we just have to wait

The decision to drop support for deck.gl's ContextProvider is made by react-map-gl. react-map-gl does so to prioritize its own maintainability, performance, and compatibility when used standalone.

deck.gl does not "recommend" a particular react-map-gl version over another. To make that decision, it's best for you to consult the react-map-gl documentation.

deck.gl will offer its own set of UI components that are independent from any base map library. The work is tracked by this issue. Whether you want to wait for that feature depends on what controls you are trying to use. If you need controls that are Mapbox-specific, such as directions, then this effort will not help you.

Not sure about react-map-gl with maplibre or mapbox 1? does it work transparently ?

I'm not sure I understand the question.

[jonenst]

Not sure about react-map-gl with maplibre or mapbox 1? does it work transparently ?

I'm not sure I understand the question.

Sorry, this question was not very relevant (I was under the impression that the different control implementations from mapboxv2/mapboxv1/maplibre might affect compatibility with the deck control or layer but since it all goes through standard react-map-gl APIs it makes no difference obviously. Also I didn't take time to just simply code and verify this)

By the way I also noticed that in #7641 you switched almost all getting-started examples to maplibre, which I find very nice and reassuring, it gives a strong sense of support to the maplibre setup which is awesome. It goes well with the sentence "If the forked libraries and Mapbox API diverge in the future, compatibility issues may arise. deck.gl intends to support open source efforts wherever reasonable. Please report any issue on GitHub." from https://deck.gl/docs/developer-guide/base-maps/using-with-mapbox#compatibility-with-mapbox-gl-js-forks

[jonenst]

Thank you for your answer, I'll be following #7946 closely !

As for the docs, I'm happy to help if I can because this is an awesome project. Here are my thoughts:

As a user, I find it confusing that what is documented as "basic functionality" for maps (see https://deck.gl/docs/api-reference/mapbox/overview#using-mapbox-gl-controls-with-deckgl, "The Mapbox ecosystem offers many well-designed controls, from the basic functionalities of NavigationControl [...]") is not working with what feels like should be the recommended setup: latest versions of everything, and using the most "tested and robust" use cases.

I think I understand a little bit more why I was confused. I think it comes down to information order and implicit information I perceived when reading the docs:

• In the very first docs that people usually read (intro) https://deck.gl/docs#ecosystem, react-map-gl is listed as a "companion module" "A React wrapper around Mapbox GL which works seamlessly with deck.gl." "seamlessly" implies you won't have to decide between multiple integration possibilities
• In the next docs that people usually read (developer guide) https://deck.gl/docs/developer-guide/base-maps/using-with-mapbox , among the 3 described possibilities, the very first example (described as the most robust and tested use case) has controls and root deck (but only because it uses react-map-gl v5!)
• just after that, the non interleaved MapboxOverlay is described as "favorable if you need to use other mapbox-gl controls". "favorable" implies that not using it is possible, but this is true only with with old versions of react-map-gl
• in the next section, after the following sentence, "The DeckGL React component works especially well as the parent of a react-map-gl Map", a note talks about v5/v6 and v7 difference ("To use deck.gl with react-map-gl v7's controls, you must use "MapboxOverlay") but it's not obvious from the structure that v7 is in direct contradiction with the previous root deck mode recommendation of "working especially well as the parent"
• in the most advanced docs (Submodule API reference) https://deck.gl/docs/api-reference/mapbox/overview , a sentence introduces use cases "if you do not need mapbox-gl's UI controls or mixing deck and Mapbox layers" talks about UI controls first and then mixing layers, but then the next sections are in the opposite order with the most complete section about why controls can't be used in the root mode last.
• the examples with MapboxOverlay are not very declarative (the first one is using mapbox directly instead of react-map-gl, the second one uses a weird looking wrapper function of useControl which seemingly sets the props twice (first in the constructor, second in the setProps) (it's surprising when reading the code, but actually necessary))

Additionally, while it's nice to have docs that showcase the most advanced multiview/nonmercator/terrain features of deckgl in other pages, I think the https://deck.gl/docs/developer-guide/base-maps/using-with-mapbox page should prioritize the basic use case of a simple map using the latest versions of everything with navigation controls and a deckgl overlay.

As a side note it feels like the root problem is that react-map-gl v7 forcibly took control of the user input and camera away from deck.gl, and that this is unfortunate from the point of view of deckgl (So much for being a nice companion module...). I think explaining this in the docs would also help greatly to clarify things. But this means that deckgl does have to take a standpoint regarding the react-map-gl version (contrary to what you said "deck.gl does not "recommend" a particular react-map-gl version over another."

So I see a lot of different improvements ideas, maybe I can put them all in #8146 and you can choose the ones that you like ?

[jonenst]

So I just spent a few hours thinking about this and rewording the docs, I think the changes from #8146 shows how opinionated the previous version was and apply the same techniques to push in the exact opposite direction. Let me know what you think.
Cheers,
Jon

[chrisgervang]

Thank you for your help on the docs. I've taken feedback into account and updated them, so I'm closing this now. Feel free to send comments if have more feedback!