[v8] Documentation (#2471)

Author: Pessimistress

README.md

@@ -36,6 +36,7 @@ npm install react-map-gl mapbox-gl
 // Using Maplibre
 import * as React from 'react';
 import Map from 'react-map-gl/maplibre';
+import 'maplibre-gl/dist/maplibre-gl.css';
 
 function App() {
   return (
@@ -56,11 +57,13 @@ _or_
 ```js
 // Using Mapbox
 import * as React from 'react';
-import Map from 'react-map-gl';
+import Map from 'react-map-gl/mapbox';
+import 'mapbox-gl/dist/mapbox-gl.css';
 
 function App() {
   return (
     <Map
+      // https://visgl.github.io/react-map-gl/docs/get-started/mapbox-tokens
       mapboxAccessToken="<Mapbox access token>"
       initialViewState={{
         longitude: -100,
@@ -76,18 +79,6 @@ function App() {
 
 Learn more with in our [Getting Started](https://visgl.github.io/react-map-gl/docs/get-started) guide.
 
-### Using Mapbox Tokens
-
-**Starting with v2.0, mapbox-gl requires a Mapbox token for any usage, with or without the Mapbox data service. See [about Mapbox tokens](/docs/get-started/mapbox-tokens.md) for your options.**
-
-To show maps from a service such as Mapbox you will need to register on their website in order to retrieve an access token required by the map component, which will be used to identify you and start serving up map tiles. The service will be free until a certain level of traffic is exceeded.
-
-There are several ways to provide a token to your app, as showcased in some of the example folders:
-
-* Provide a `mapboxAccessToken` prop to the map component
-* Set the `MapboxAccessToken` environment variable (or set `REACT_APP_MAPBOX_ACCESS_TOKEN` if you are using Create React App)
-* Provide it in the URL, e.g `?access_token=TOKEN`
-
 
 ### Contribute
 

docs/README.md

@@ -1,33 +1,25 @@
 
 # Introduction
 
-<p align="center">
-  These docs are for
-  <a href="https://github.com/visgl/react-map-gl/tree/7.0-release/docs">
-    <img src="https://img.shields.io/badge/v7.0-brightgreen.svg?style=flat-square" />
-  </a>
-  Looking for an old version?
-  <a href="https://github.com/visgl/react-map-gl/tree/6.1-release/docs">
-    <img src="https://img.shields.io/badge/v6.1-brightgreen.svg?style=flat-square" />
-  </a>
-  <a href="https://github.com/visgl/react-map-gl/tree/5.3-release/docs">
-    <img src="https://img.shields.io/badge/v5.3-brightgreen.svg?style=flat-square" />
-  </a>
-</p>
+> These docs are for v8.0. For v7, see [here](https://github.com/visgl/react-map-gl/tree/7.1-release/docs).
 
 react-map-gl is a suite of [React](http://facebook.github.io/react/) components for
-[mapbox-gl](https://github.com/mapbox/mapbox-gl-js), [maplibre-gl](https://maplibre.org/maplibre-gl-js/docs/) or compatible libraries.
+[mapbox-gl](https://www.npmjs.com/package/mapbox-gl), [maplibre-gl](https://www.npmjs.com/package/maplibre-gl) or compatible libraries.
 
 | Library | Description |
 | --- | --- | 
-| [MapLibre GL JS](https://github.com/MapLibre/maplibre-gl-js) | An open fork of mapbox-gl v1, that can be used without a mapbox token. |
-| [Mapbox GL JS v1](https://github.com/mapbox/mapbox-gl-js) | The previous version of mapbox GL JS. This version is free open source and can be used with non-mapbox basemaps without a mapbox token. |
-| [Mapbox GL JS v2](https://github.com/mapbox/mapbox-gl-js) | The latest version of Mapbox GL JS. Note that version 2 is not free open source, and a mapbox token is required and billable events are generated even if you do not use mapbox hosted basemaps. |
-| Other mapbox-gl forks | It may be possible to use react-map-gl with other mapbox forks, but this is not a supported use case. Minor PRs to enable other forks to be used may be accepted. |
+| [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) | An Open-source TypeScript library for publishing web maps. |
+| [Mapbox GL JS](https://www.mapbox.com/mapbox-gljs) | A JavaScript library for interactive, customizable vector maps on the web. |
+| [Mapbox GL JS v1](https://github.com/mapbox/mapbox-gl-js/tree/release-v1.13.3) | The last free-open-source version of Mapbox GL JS. This version can be used without a Mapbox token if you do not use Mapbox hosted basemaps. |
+| Other compatible forks | It may be possible to use react-map-gl with mapbox-gl/maplibre-gl forks, but this is not a supported use case. Minor PRs to enable other forks to be used may be accepted. |
 
-For basemaps:
-- You can load map data from Mapbox's own service.
-- You can create and host your own map data using one of the many [open source tools](https://github.com/mapbox/awesome-vector-tiles).
+If you need help choosing a base map library that is right for you:
+
+- Decide where to get your vector map data.
+  + `mapbox-gl` is designed to work seamlessly with Mapbox's own data service. You will need a billable Mapbox token to use it.
+  + There are a number of [map data providers](./get-started/mapbox-tokens.md#display-maps-without-a-mapbox-token) who support `maplibre-gl`, with a variaty of data quality and price options.
+  + You can create and host your own map tiles and use them with `maplibre-gl` for (almost) free, if you are comfortable of using [open source tools](./get-started/mapbox-tokens.md#display-maps-without-a-mapbox-token) and setting up a cloud storage account.
+- Visit Mapbox and MapLibre websites for examples and documentation. Each library offer unique features that may not exist in another.
 
 New to react-map-gl? [Get Started](./get-started/get-started.md)
 
@@ -44,10 +36,10 @@ This does not scale when we have many components that need to synchronize with e
 
 Ultimately, in the spirit of the [reactive programming paradigm](https://en.wikipedia.org/wiki/Reactive_programming), data always flows **down**. As long as the map manages its own state, as mapbox-gl is designed to do, we risk the components going out of sync.
 
-react-map-gl creates a fully reactive wrapper for mapbox-gl. The [Map](./api-reference/map.md) component can be fully [controlled](https://reactjs.org/docs/forms.html#controlled-components), that is, the map's camera would never deviate from the props that it's assigned. Read more about this core behavior in [state management](./get-started/state-management.md).
+react-map-gl creates a fully reactive wrapper for mapbox-gl/maplibre-gl. The [Map](./api-reference/maplibre/map.md) component can be fully [controlled](https://reactjs.org/docs/forms.html#controlled-components), that is, the map's camera would never deviate from the props that it's assigned. Read more about this core behavior in [state management](./get-started/state-management.md).
 
 ## Limitations
 
 In v7.0, react-map-gl was fully rewritten to better align its API with the underlying Mapbox GL JS library. Wherever the reactive usage patterns permits, the wrapper's props and methods are 1:1 mappings to their native API equivelants.
 
-It is possible to call the native methods directly from the `Map` instance obtained via [getMap](./api-reference/map.md#gemap). However, doing so may result in the map's state to deviate from its props. For example, calling `map.setMaxZoom` directly will cause the map's constraint settings to differ from the value of the `maxZoom` prop. Generally speaking, calling a native method is disencouraged if the same thing can be achieved through the React interface. If a third-party plugin does so, then it may lead to some unexpected behaviors.
+It is possible to call the native methods directly from the `Map` instance obtained via [getMap](./api-reference/maplibre/map.md#gemap). However, doing so may result in the map's state to deviate from its props. For example, calling `map.setMaxZoom` directly will cause the map's constraint settings to differ from the value of the `maxZoom` prop. Generally speaking, calling a native method is disencouraged if the same thing can be achieved through the React interface. If a third-party plugin does so, then it may lead to some unexpected behaviors.

docs/api-reference/attribution-control.md …-reference/mapbox/attribution-control.mddocs/api-reference/attribution-control.md renamed to docs/api-reference/mapbox/attribution-control.md docs/api-reference/attribution-control.md renamed to docs/api-reference/mapbox/attribution-control.md

@@ -1,17 +1,11 @@
 # AttributionControl
 
-React component that wraps the base library's `AttributionControl` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#attributioncontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/AttributionControl/)).
-
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs groupId="map-library">
-  <TabItem value="mapbox" label="Mapbox">
+React component that wraps mapbox-gl's [AttributionControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#attributioncontrol) class.
 
 ```tsx
 import * as React from 'react';
-import Map, {AttributionControl} from 'react-map-gl';
+import Map, {AttributionControl} from 'react-map-gl/mapbox';
+import 'mapbox-gl/dist/mapbox-gl.css';
 
 function App() {
   return <Map
@@ -30,37 +24,11 @@ function App() {
 }
 ```
 
-  </TabItem>
-  <TabItem value="maplibre" label="Maplibre">
-
-```tsx
-import * as React from 'react';
-import Map, {AttributionControl} from 'react-map-gl/maplibre';
-
-function App() {
-  return <Map
-    initialViewState={{
-      longitude: -100,
-      latitude: 40,
-      zoom: 3.5
-    }}
-    mapStyle="https://api.maptiler.com/maps/streets/style.json?key=get_your_own_key"
-    // disable the default attribution
-    attributionControl={false}
-  >
-    <AttributionControl customAttribution="Map design by me" />
-  </Map>;
-}
-```
-
-  </TabItem>
-</Tabs>
-
 ## Properties
 
 ### Reactive Properties
 
-#### `style`: CSSProperties {#style}
+#### `style`: CSSProperties {#style}
 
 CSS style override that applies to the control's container.
 
@@ -75,7 +43,7 @@ Any options supported by the `AttributionControl` class ([Mapbox](https://docs.m
 
 Plus the following:
 
-#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}
+#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}
 
 Default: `'bottom-right'`
 

docs/api-reference/fullscreen-control.md …i-reference/mapbox/fullscreen-control.mddocs/api-reference/fullscreen-control.md renamed to docs/api-reference/mapbox/fullscreen-control.md docs/api-reference/fullscreen-control.md renamed to docs/api-reference/mapbox/fullscreen-control.md

@@ -1,17 +1,11 @@
 # FullscreenControl
 
-React component that wraps the base library's `FullscreenControl` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#fullscreencontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/FullscreenControl/)).
-
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs groupId="map-library">
-  <TabItem value="mapbox" label="Mapbox">
+React component that wraps mapbox-gl's [FullscreenControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#fullscreencontrol) class.
 
 ```tsx
 import * as React from 'react';
-import Map, {FullscreenControl} from 'react-map-gl';
+import Map, {FullscreenControl} from 'react-map-gl/mapbox';
+import 'mapbox-gl/dist/mapbox-gl.css';
 
 function App() {
   return <Map
@@ -28,29 +22,6 @@ function App() {
 }
 ```
 
-  </TabItem>
-  <TabItem value="maplibre" label="Maplibre">
-
-```tsx
-import * as React from 'react';
-import Map, {FullscreenControl} from 'react-map-gl/maplibre';
-
-function App() {
-  return <Map
-    initialViewState={{
-      longitude: -100,
-      latitude: 40,
-      zoom: 3.5
-    }}
-    mapStyle="https://api.maptiler.com/maps/streets/style.json?key=get_your_own_key"
-  >
-    <FullscreenControl />
-  </Map>;
-}
-```
-
-  </TabItem>
-</Tabs>
 
 ## Properties
 

docs/api-reference/geolocate-control.md …pi-reference/mapbox/geolocate-control.mddocs/api-reference/geolocate-control.md renamed to docs/api-reference/mapbox/geolocate-control.md docs/api-reference/geolocate-control.md renamed to docs/api-reference/mapbox/geolocate-control.md

@@ -1,17 +1,11 @@
 # GeolocateControl
 
-React component that wraps the base library's `GeolocateControl` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/)).
-
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs groupId="map-library">
-  <TabItem value="mapbox" label="Mapbox">
+React component that wraps mapbox-gl's [GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) class.
 
 ```tsx
 import * as React from 'react';
-import Map, {GeolocateControl} from 'react-map-gl';
+import Map, {GeolocateControl} from 'react-map-gl/mapbox';
+import 'mapbox-gl/dist/mapbox-gl.css';
 
 function App() {
   return <Map
@@ -28,58 +22,33 @@ function App() {
 }
 ```
 
-  </TabItem>
-  <TabItem value="maplibre" label="Maplibre">
-
-```tsx
-import * as React from 'react';
-import Map, {GeolocateControl} from 'react-map-gl/maplibre';
-
-function App() {
-  return <Map
-    initialViewState={{
-      longitude: -100,
-      latitude: 40,
-      zoom: 3.5
-    }}
-    mapStyle="https://api.maptiler.com/maps/streets/style.json?key=get_your_own_key"
-  >
-    <GeolocateControl />
-  </Map>;
-}
-```
-
-  </TabItem>
-</Tabs>
-
-
 ## Properties
 
 ### Reactive Properties
 
-#### `style`: CSSProperties {#style}
+#### `style`: CSSProperties {#style}
 
 CSS style override that applies to the control's container.
 
 ### Callbacks
 
-#### `onGeolocate`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#ongeolocate}
+#### `onGeolocate`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#ongeolocate}
 
 Called on each Geolocation API position update that returned as success.
 
-#### `onError`: (evt: [GeolocateErrorEvent](./types.md#geolocateerrorevent)) => void {#onerror}
+#### `onError`: (evt: [GeolocateErrorEvent](./types.md#geolocateerrorevent)) => void {#onerror}
 
 Called on each Geolocation API position update that returned as an error.
 
-#### `onOutOfMaxBounds`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#onoutofmaxbounds}
+#### `onOutOfMaxBounds`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#onoutofmaxbounds}
 
 Called on each Geolocation API position update that returned as success but user position is out of map `maxBounds`.
 
-#### `onTrackUserLocationStart`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationstart}
+#### `onTrackUserLocationStart`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationstart}
 
 Called when the GeolocateControl changes to the active lock state.
 
-#### `onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend}
+#### `onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend}
 
 Called when the GeolocateControl changes to the background state.
 
@@ -98,7 +67,7 @@ Any options supported by the `GeolocateControl` class ([Mapbox](https://docs.map
 
 Plus the following:
 
-#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}
+#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}
 
 Default: `'bottom-right'`
 
@@ -110,13 +79,10 @@ Placement of the control relative to the map.
 The underlying native `GeolocateControl` instance is accessible via a [React ref](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) hook.
 You may use it to call any imperative methods:
 
-<Tabs groupId="map-library">
-  <TabItem value="mapbox" label="Mapbox">
-
 ```tsx
 import * as React from 'react';
 import {useRef, useEffect} from 'react';
-import Map, {GeolocateControl} from 'react-map-gl';
+import Map, {GeolocateControl} from 'react-map-gl/mapbox';
 import type mapboxgl from 'mapbox-gl';
 
 function App() {
@@ -133,33 +99,6 @@ function App() {
 }
 ```
 
-  </TabItem>
-  <TabItem value="maplibre" label="Maplibre">
-
-
-```tsx
-import * as React from 'react';
-import {useRef, useEffect} from 'react';
-import Map, {GeolocateControl} from 'react-map-gl/maplibre';
-import type maplibregl from 'maplibre-gl';
-
-function App() {
-  const geoControlRef = useRef<maplibregl.GeolocateControl>();
-
-  useEffect(() => {
-    // Activate as soon as the control is loaded
-    geoControlRef.current?.trigger();
-  }, [geoControlRef.current]);
-
-  return <Map>
-    <GeolocateControl ref={geoControlRef} />
-  </Map>;
-}
-```
-
-  </TabItem>
-</Tabs>
-
 
 ## Source