Docs polish for 3.2 release (#436)

README.md

@@ -20,15 +20,11 @@ In addition to exposing MapboxGL functionality to React apps, react-map-gl also
 
 ### Installation
 
-    npm install --save react-map-gl
+Using `react-map-gl` requires `node >= v4` and `react >= 15.4`.
 
-* `browserify` - react-map-gl is extensively tested with `browserify` and works without configuration.
-
-* `webpack 2` - Most of the provided react-map-gl examples use webpack 2. For a minimal example, look at the [exhibit-webpack](https://github.com/uber/react-map-gl/tree/master/examples/exhibit-webpack) folder, demonstrating a working demo using `webpack 2`.
-
-* `create-react-app` - At this point configuration-free builds are not possible with webpack due to the way the mapbox-gl-js module is published. You will need to eject your app and add an alias to your webpack config, as shown in the exhibit-webpack.
-
-There's many other ready-to-run [examples](https://github.com/uber/react-map-gl/blob/master/examples) you can take a look at if you need more inspiration.
+```sh
+npm install --save react-map-gl
+```
 
 ### Example
 
@@ -37,18 +33,22 @@ import {Component} from 'react';
 import ReactMapGL from 'react-map-gl';
 
 class Map extends Component {
+
+  state = {
+    viewport: {
+      width: 400,
+      height: 400,
+      latitude: 37.7577,
+      longitude: -122.4376,
+      zoom: 8
+    }
+  };
+
   render() {
     return (
       <ReactMapGL
-        width={400}
-        height={400}
-        latitude={37.7577}
-        longitude={-122.4376}
-        zoom={8}
-        onViewportChange={(viewport) => {
-          const {width, height, latitude, longitude, zoom} = viewport;
-          // Optionally call `setState` and use the state to update the map.
-        }}
+        {...this.state.viewport}
+        onViewportChange={(viewport) => this.setState({viewport})}
       />
     );
   }
@@ -66,11 +66,3 @@ There are several ways to provide a token to your app, as showcased in some of t
 * Provide it in the URL, e.g `?access_token=TOKEN`
 
 But we would recommend using something like [dotenv](https://github.com/motdotla/dotenv) and put your key in an untracked `.env` file, that will then expose it as a `process.env` variable, with much less leaking risks.
-
-### Redux Usage
-
-If you're using redux, it is very easy to hook this component up to store state in the redux state tree.
-The simplest way is to take all properties passed to the `onViewportChange` function property and add them
-directly into the store. This state can then be passed back to the `<ReactMapGL>` component without any transformation.
-
-You can even use the package [redux-map-gl](https://github.com/Willyham/redux-map-gl) to save you some writing.

docs/advanced/custom-map-controls.md

@@ -2,10 +2,61 @@
 
 ## Overriding The Default Map Controller
 
-To change the default behavior of map interaction, you can implement/extend the `MapControls`
-class add pass an instance to the `mapControls` prop of `InteractiveMap`.
+To change the default behavior of map interaction, you can provide a custom map control to the `mapControls` prop of `InteractiveMap`.
 
-A simple example to disable mouse wheel:
+This custom map control must offer the following interface:
+- `setOptions(options)` - called by `InteractiveMap` when props change.
+
+```jsx
+  const mapControls = new MyMapControls();
+
+  render() {
+    return <ReactMapGL mapControls={mapControls} ... />;
+  }
+```
+
+
+Documentation of [the MapControls class](/docs/components/map-controls.md).
+
+
+## Examples
+
+A simple example to swap drag pan and drag rotate:
+```js
+  /// my-map-controls.js
+  import {experimental} from 'react-map-gl';
+
+  export default class MyMapControls extends experimental.MapControls {
+
+    _onPan(event) {
+      return this.isFunctionKeyPressed(event) || event.rightButton ?
+    //  Default implementation in MapControls
+    //  this._onPanRotate(event) : this._onPanMove(event);
+        this._onPanMove(event) : this._onPanRotate(event);
+    }
+  }
+```
+
+Overwrite existing event handling:
+```js
+  /// my-map-controls.js
+  import {experimental} from 'react-map-gl';
+
+  export default class MyMapControls extends experimental.MapControls {
+
+    // Override the default double tap handler
+    _onDoubleTap(event) {
+      // Go to New York City
+      this.updateViewport(this.getMapState(), {
+        longitude: -74.0,
+        latitude: 40.7,
+        zoom: 10
+      });
+    }
+  }
+```
+
+Listen to additional events:
 ```js
   /// my-map-controls.js
   import {experimental} from 'react-map-gl';
@@ -21,65 +72,30 @@ A simple example to disable mouse wheel:
     // Override the default handler in MapControls
     handleEvent(event) {
       if (event.type === 'click') {
-        console.log('hi!');
+        console.log('hi');
       }
       return super.handleEvent(event);
     }
   }
 ```
-Then pass it to the map during render:
-```jsx
-  const mapControls = new MyMapControls();
-  <ReactMapGL mapControls={mapControls} ... />
+
+Add a custom callback:
+```js
+  /// my-map-controls.js
+  import {experimental} from 'react-map-gl';
+
+  export default class MyMapControls extends experimental.MapControls {
+
+    setOptions(options) {
+      super.setOptions(options);
+      // save the custom callback
+      this.onRotate = options.onRotate;
+    }
+
+    _onPanRotate(event) {
+      super._onPanRotate(event);
+      this.onRotate();
+    }
+  }
 ```
 
-
-## MapControls Interface
-
-A custom map controls class must implement the following interface:
-
-### Properties
-
-##### `events` (Array)
-
-A list of additional event names that this control subscribes to.
-
-Available events: `click`, `dblclick`, `tap`, `doubletap`, `press`, `pinch`, `pinchin`, `pinchout`, `pinchstart`, `pinchmove`, `pinchend`, `pinchcancel`, `rotate`, `rotatestart`, `rotatemove`, `rotateend`, `rotatecancel`, `pan`, `panstart`, `panmove`, `panup`, `pandown`, `panleft`, `panright`, `panend`, `pancancel`, `swipe`, `swipeleft`, `swiperight`, `swipeup`, `swipedown`, `pointerdown`, `pointermove`, `pointerup`, `touchstart`, `touchmove`, `touchend`, `mousedown`, `mousemove`, `mouseup`, `keydown`, and `keyup`.
-
-The following events are toggled on/off by InteractiveMap props: 
-
-- `scrollZoom` - `['wheel']`
-- `dragPan` and `dragRotate` - `['panstart', 'panmove', 'panend']`
-- `touchZoomRotate` - `['pinchstart', 'pinchmove', 'pinchend']`
-- `doubleClickZoom` - `['doubletap']`
-- `keyboar` - `['keydown']`
-
-Event object is generated by [mjolnir.js](https://github.com/uber-web/mjolnir.js). It always has the following properties:
-
-* `type` (string) -  The event type to which the event handler is subscribed, e.g. `'click'` or `'pointermove'`
-* `center` (Object `{x, y}`) - The center of the event location (e.g. the centroid of a touch) relative to the viewport (basically, [`clientX/Y`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/clientX))
-* `offsetCenter` (Object `{x, y}`) - The center of the event location relative to the map.
-* `target` (Object) - The target of the event, as specified by the original `srcEvent`
-* `srcEvent` (Object) - The original event object dispatched by the browser to the JS runtime
-
-Additionally, event objects for different event types contain a subset of the following properties:
-
-* `key` (number) - The keycode of the keyboard event
-* `leftButton` (boolean) - Flag indicating whether the left button is involved during the event
-* `middleButton` (boolean) - Flag indicating whether the middle button is involved during the event
-* `rightButton` (boolean) - Flag indicating whether the right button is involved during the event
-* `pointerType` (string) - A string indicating the type of input (e.g. `'mouse'`, `'touch'`, `'pointer'`)
-* `delta` (number) - The scroll magnitude/distance of a wheel event
-
-
-### Methods
-
-##### `handleEvent(event)`
-
-Called by `InteractiveMap` to handle pointer events.
-
-##### `setOptions(options)`
-
-Called by `InteractiveMap` when props change.
-
-

docs/advanced/viewport-transition.md

@@ -1,4 +1,4 @@
-# Transitions
+# Viewport Transition
 
 `react-map-gl` does not expose the transition API from `mapbox-gl-js` since it is designed to be a stateless component, and needs to synchronize with separate overlay systems such as deck.gl.
 
@@ -15,10 +15,10 @@ import d3 from 'd3-ease';
     transitionEasing={d3.easeCubic}
     onTransitionEnd={() => {
         // do something
-        }} >
+        }} />
 ```
 
-See [viewport transition](#examples/viewport-transition) for a complete example.
+See [viewport animation](#examples/viewport-animation) for a complete example.
 
 ## InteractiveMap's Transition Props
 
@@ -32,6 +32,22 @@ See properties of [InteractiveMap](/docs/components/interactive-map.md).
 - `onTransitionInterrupt` {Function}
 - `onTransitionEnd` {Function}
 
+
+## Transition and the onViewportChange Callback
+
+`InteractiveMap` is designed to be a stateless component. For transitions to work, the application must update the viewport props returned by the `onViewportChange` callback:
+```
+<ReactMapGL
+    {...this.state.viewport}
+    onViewportChange={(viewport) => this.setState({viewport})}
+```
+
+Remarks:
+- The props returned by the callback may contain transition properties. For example, during panning and rotating, the callback is invoked with `transitionDuration: 0`, meaning that the map movement instantly matches the change of the pointer. When panning or zooming with keyboard, the callback is invoked with a 300ms linear transition.
+- It is recommended that when programatically triggering a transition, always explicitly set the transition properties (interpolator, easing and duration).
+- The default interaction/transition behavior can always be intercepted and overwritten in the handler for `onViewportChange`. However, if a transition is in progress, the properties that are being transitioned (e.g. longitude and latitude) should not be manipulated, otherwise the change will be interpreted as an interruption of the transition.
+
+
 ## Transition Interpolators
 
 A `TransitionInterpolator` instance must be supplied to the `transitionInterpolator` prop. It contains the following methods:
@@ -39,21 +55,6 @@ A `TransitionInterpolator` instance must be supplied to the `transitionInterpola
 - `initiateProps(startProps, endProps)` - called before transition starts to pre-process the start and end viewport props.
 - `interpolateProps(startProps, endProps, t)` - called to get viewport props in transition. `t` is a time factor between `[0, 1]`.
 
-### `LinearInterpolator`
-
-Interpolates all viewport props linearly. This interpolator offers similar behavior to Mapbox's `easeTo` when combined with a `transitionEasing` function. You may optionally limit the transition to selected viewport props, for example `new LinearInterpolator(['pitch', 'bearing'])` animates pitch and bearing while the user is still allowed to pan and zoom.
-
-##### constructor
-
-`new LinearInterpolator([transitionProps])`
-
-Parameters:
-- `transitionProps` {Array} (optional) - list of prop names to interpolate. Default: `['longitude', 'latitude', 'zoom', 'pitch', 'bearing']`.
-
-### `FlyToInterpolator`
-
-This interpolator offers similar behavior to Mapbox's `flyTo` method. 
-
-##### constructor
-
-`new FlyToInterpolator()`
+react-map-gl offers two built-in interpolator classes:
+- [LinearInterpolator](/docs/components/linear-interpolator.md)
+- [FlyToInterpolator](/docs/components/fly-to-interpolator.md)

docs/components/fly-to-interpolator.md

@@ -0,0 +1,23 @@
+# FlyToInterpolator
+
+Implements the `TransitionInterpolator` interface. Designed to use with the `transitionInterpolator` prop of [InteractiveMap](/docs/components/interactive-map.md).
+
+This interpolator offers similar behavior to Mapbox's `flyTo` method.
+
+```jsx
+import ReactMapGL, {FlyToInterpolator} from 'react-map-gl';
+
+<ReactMapGL
+    ...
+    transitionDuration={1000}
+    transitionInterpolator={new FlyToInterpolator()} />
+```
+
+##### constructor
+
+`new FlyToInterpolator()`
+
+
+## Source
+[viewport-fly-to-interpolator.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/utils/transition/viewport-fly-to-interpolator.js)
+

docs/components/interactive-map.md

@@ -136,7 +136,7 @@ import ReactMapGL, {LinearInterpolator, FlyToInterpolator} from 'react-map-gl';
 
 Default: `new LinearInterpolator()`
 
-For details about using transition interpolators, see [transitions](/docs/user-guide/transitions.md).
+For details about using transition interpolators, see [transitions](/docs/advanced/viewport-transitions.md).
 
 ##### `transitionEasing` {Function}
 Easing function that maps a value from `[0, 1]` to `[0, 1]`. Default to `t => t` (linear). Check out [http://easings.net/](http://easings.net/) for common easing curves.
@@ -166,3 +166,7 @@ Callback that is fired when a transition is complete.
 ## Methods
 
 Same methods as [StaticMap](/docs/components/static-map.md).
+
+## Source
+[interactive-map.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/components/interactive-map.js)
+

docs/components/linear-interpolator.md

@@ -0,0 +1,26 @@
+# LinearInterpolator
+
+Implements the `TransitionInterpolator` interface. Designed to use with the `transitionInterpolator` prop of [InteractiveMap](/docs/components/interactive-map.md).
+
+Interpolates all viewport props linearly. This interpolator offers similar behavior to Mapbox's `easeTo` when combined with a `transitionEasing` function. You may optionally limit the transition to selected viewport props, for example `new LinearInterpolator(['pitch', 'bearing'])` animates pitch and bearing while the user is still allowed to pan and zoom.
+
+```jsx
+import ReactMapGL, {LinearInterpolator} from 'react-map-gl';
+
+<ReactMapGL
+    ...
+    transitionDuration={1000}
+    transitionInterpolator={new LinearInterpolator()} />
+```
+
+##### constructor
+
+`new LinearInterpolator([transitionProps])`
+
+Parameters:
+- `transitionProps` {Array} (optional) - list of prop names to interpolate. Default: `['longitude', 'latitude', 'zoom', 'pitch', 'bearing']`.
+
+
+## Source
+[linear-interpolator.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/utils/transition/linear-interpolator.js)
+

docs/components/map-controls.md

@@ -0,0 +1,72 @@
+# MapControls (experimental)
+
+The easiest way to create a custom map control is to extend the default `MapControls` class.
+
+## Properties
+
+##### `events` (Array)
+
+A list of additional event names that this control subscribes to.
+
+Available events: `click`, `dblclick`, `tap`, `doubletap`, `press`, `pinch`, `pinchin`, `pinchout`, `pinchstart`, `pinchmove`, `pinchend`, `pinchcancel`, `rotate`, `rotatestart`, `rotatemove`, `rotateend`, `rotatecancel`, `pan`, `panstart`, `panmove`, `panup`, `pandown`, `panleft`, `panright`, `panend`, `pancancel`, `swipe`, `swipeleft`, `swiperight`, `swipeup`, `swipedown`, `pointerdown`, `pointermove`, `pointerup`, `touchstart`, `touchmove`, `touchend`, `mousedown`, `mousemove`, `mouseup`, `keydown`, and `keyup`.
+
+The following events are toggled on/off by InteractiveMap props: 
+
+- `scrollZoom` - `['wheel']`
+- `dragPan` and `dragRotate` - `['panstart', 'panmove', 'panend']`
+- `touchZoomRotate` - `['pinchstart', 'pinchmove', 'pinchend']`
+- `doubleClickZoom` - `['doubletap']`
+- `keyboar` - `['keydown']`
+
+Event object is generated by [mjolnir.js](https://github.com/uber-web/mjolnir.js). It always has the following properties:
+
+* `type` (string) -  The event type to which the event handler is subscribed, e.g. `'click'` or `'pointermove'`
+* `center` (Object `{x, y}`) - The center of the event location (e.g. the centroid of a touch) relative to the viewport (basically, [`clientX/Y`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/clientX))
+* `offsetCenter` (Object `{x, y}`) - The center of the event location relative to the map.
+* `target` (Object) - The target of the event, as specified by the original `srcEvent`
+* `srcEvent` (Object) - The original event object dispatched by the browser to the JS runtime
+
+Additionally, event objects for different event types contain a subset of the following properties:
+
+* `key` (number) - The keycode of the keyboard event
+* `leftButton` (boolean) - Flag indicating whether the left button is involved during the event
+* `middleButton` (boolean) - Flag indicating whether the middle button is involved during the event
+* `rightButton` (boolean) - Flag indicating whether the right button is involved during the event
+* `pointerType` (string) - A string indicating the type of input (e.g. `'mouse'`, `'touch'`, `'pointer'`)
+* `delta` (number) - The scroll magnitude/distance of a wheel event
+
+
+## Methods
+
+##### `handleEvent(event)`
+
+Called by the event manager to handle pointer events. This method delegate to the following methods to handle the default events:
+- `_onPanStart(event)`
+- `_onPan(event)`
+- `_onPanEnd(event)`
+- `_onPinchStart(event)`
+- `_onPinch(event)`
+- `_onPinchEnd(event)`
+- `_onDoubleTap(event)`
+- `_onWheel(event)`
+- `_onKeyDown(event)`
+
+##### `getMapState(overrides)`
+
+Get a new descriptor object of the map state. If specified, props in the `overrides` object override the current map props.
+
+##### `setOptions(options)`
+
+Add/remove event listeners based on the latest `InteractiveMap` props.
+
+##### `setState(newState)`
+
+Save a persistent state (e.g. isDragging) for future use.
+
+##### `updateViewport(newMapState, extraProps, extraState)`
+
+Invoke `onViewportChange` callback with a new map state.
+
+
+## Source
+[map-controls.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/utils/map-controls.js)

docs/components/marker.md

@@ -46,3 +46,11 @@ Stop propagation of click event to the map component. Can be used to stop map fr
 
 ##### `captureDoubleClick` {Boolean} - default: `true`
 Stop propagation of dblclick event to the map component. Can be used to stop map from zooming when this component is double clicked.
+
+## Styling
+
+Like its Mapbox counterpart, this control relies on the mapbox-gl stylesheet to work properly. Make sure to add the stylesheet to your page.
+
+## Source
+[marker.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/components/marker.js)
+

docs/components/navigation-control.md

@@ -40,17 +40,8 @@ Stop propagation of dblclick event to the map component. Can be used to stop map
 
 ## Styling
 
-Like its Mapbox counterpart, this control relies on the mapbox-gl stylesheet to work properly.
+Like its Mapbox counterpart, this control relies on the mapbox-gl stylesheet to work properly. Make sure to add the stylesheet to your page.
 
-You may add the stylesheet to your page:
-```html
-<!-- index.html -->
-<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.37.0/mapbox-gl.css' rel='stylesheet' />
-```
+## Source
+[navigation-control.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/components/navigation-control.js)
 
-Or embed it in your app by using - [browserify-css](https://www.npmjs.com/package/browserify-css)
-with Browserify or - [css-loader](https://webpack.github.io/docs/stylesheets.html) with Webpack:
-```js
-// app.js
-import 'mapbox-gl/dist/mapbox-gl.css';
-```

docs/components/popup.md

@@ -68,17 +68,8 @@ Stop propagation of dblclick event to the map component. Can be used to stop map
 
 ## Styling
 
-Like its Mapbox counterpart, this control relies on the mapbox-gl stylesheet to work properly.
+Like its Mapbox counterpart, this control relies on the mapbox-gl stylesheet to work properly. Make sure to add the stylesheet to your page.
 
-You may add the stylesheet to your page:
-```html
-<!-- index.html -->
-<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.37.0/mapbox-gl.css' rel='stylesheet' />
-```
+## Source
+[popup.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/components/popup.js)
 
-Or embed it in your app by using - [browserify-css](https://www.npmjs.com/package/browserify-css)
-with Browserify or - [css-loader](https://webpack.github.io/docs/stylesheets.html) with Webpack:
-```js
-// app.js
-import 'mapbox-gl/dist/mapbox-gl.css';
-```

docs/components/static-map.md

@@ -84,6 +84,13 @@ map from reloading and flickering when the map style changes.
 
 There are known issues with style diffing. As stopgap, use this option to prevent style diffing.
 
+##### `reuseMaps` {Bool} - default: `false`
+** This prop is experimental. **
+
+If `true`, when the map component is unmounted, instead of calling `remove` on the Mapbox map instance, save it for later reuse. This will avoid repeatedly creating new Mapbox map instances if possible.
+
+Applications that frequently mount and unmount maps may try this prop to help work around a mapbox-gl resource leak issue that can lead to a browser crash in certain situations.
+
 ##### `onLoad` {Function} - default: `no-op function`
 A callback run when the map emits a `load` event.
 [Mapbox docs](https://www.mapbox.com/mapbox-gl-js/api#map.event:load)
@@ -115,3 +122,7 @@ Parameters:
 - `parameters`
   Query options. For more details, see
   [Mapbox API documentation](https://www.mapbox.com/mapbox-gl-js/api/#Map#queryRenderedFeatures).
+
+## Source
+[static-map.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/components/static-map.js)
+

docs/get-started/adding-custom-data.md

@@ -1,11 +1,54 @@
-# Overlays
+# Adding Custom Data
+
+## Native Mapbox Layers
+
+You can inject data and mapbox native layers by modifying the map style object:
+
+```js
+import fromJS from 'immutable';
+const mapStyle = fromJS({
+    version: 8,
+    sources: {
+        points: {
+            type: 'geojson',
+            data: {
+                type: 'FeatureCollection',
+                features: [
+                    {type: 'Feature', geometry: {type: 'Point', coordinates: [-122.45, 37.78]}}
+                ]
+            }
+        }
+    },
+    layers: [
+        {
+            id: 'my-layer',
+            type: 'circle',
+            source: 'points',
+            paint: {
+                'circle-color': '#f00',
+                'circle-radius': '4'
+            }
+        }
+    ]
+});
+
+<ReactMapGL mapStyle={mapStyle} ... />
+
+```
+
+For details about data sources and layer configuration, check out the [Mapbox style specification](https://www.mapbox.com/mapbox-gl-js/style-spec).
+
+For dynamically updating data and layers, check out the [GeoJSON](#examples/geojson) and [GeoJSON animation](#examples/geojson-animation) examples.
+
+
+## Overlays
 
 react-map-gl provides a basic overlay API that enables applications to overlay data on top of maps.
 
-Note that the built-in overlays are intended to provide basic functionality only. For more feature rich and performant data visualization overlay use cases, consider using [deck.gl](deck.gl) and/or mapbox styles.
+Note that the built-in overlays are intended to provide basic functionality only. For more feature rich and performant data visualization overlay use cases, consider using [deck.gl](deck.gl).
 
 
-## Example
+### Example
 
 ```js
 import {SVGOverlay} from 'react-map-gl';
@@ -21,14 +64,14 @@ function redraw({project}) {
 ```
 
 
-## Built-in Overlays
+### Built-in Overlays
 
 Built-in overlays are: `SVGOverlay`, `HTMLOverlay`, and `CanvasOverlay`. They are imported using
 ```
 import {SVGOverlay, HTMLOverlay, CanvasOverlay} from 'react-map-gl';
 ```
 
-## Example Overlays
+### Example Overlays
 
 There are a couple of [additional overlays](https://github.com/uber/react-map-gl/tree/master/examples/additional-overlays) in the examples folder that can be copied into applications `ScatterplotOverlay`, `DraggablePointsOverlay`, `ChoroplethOverlay`.
 
@@ -49,6 +92,3 @@ import cities from 'example-cities';
 ```
 
 Want to create and share your own overlay? Check the [examples/additional-overlays](https://github.com/uber/react-map-gl/tree/master/examples/additional-overlays) folder for examples.
-
-## Remarks
-* In `react-map-gl` v1, overlays were exported directly from 'react-map-gl'.

docs/get-started/get-started.md

@@ -1,7 +1,7 @@
 # Get Started
 
 
-# Installation
+## Installation
 
 Using `react-map-gl` requires `node >= v4` and `react >= 15.4`.
 
@@ -9,6 +9,52 @@ Using `react-map-gl` requires `node >= v4` and `react >= 15.4`.
 npm install --save react-map-gl
 ```
 
+## Example
+
+```js
+import {Component} from 'react';
+import ReactMapGL from 'react-map-gl';
+
+class Map extends Component {
+
+  state = {
+    viewport: {
+      width: 400,
+      height: 400,
+      latitude: 37.7577,
+      longitude: -122.4376,
+      zoom: 8
+    }
+  };
+
+  render() {
+    return (
+      <ReactMapGL
+        {...this.state.viewport}
+        onViewportChange={(viewport) => this.setState({viewport})}
+      />
+    );
+  }
+}
+```
+
+## Styling
+
+The current mapbox-gl release requires its stylesheet be included at all times. The marker, popup and navigation components in react-map-gl also need the stylesheet to work properly.
+
+You may add the stylesheet to the head of your page:
+```html
+<!-- index.html -->
+<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.42.0/mapbox-gl.css' rel='stylesheet' />
+```
+
+Or embed it in your app by using - [browserify-css](https://www.npmjs.com/package/browserify-css)
+with Browserify or - [css-loader](https://webpack.github.io/docs/stylesheets.html) with Webpack:
+```js
+// app.js
+import 'mapbox-gl/dist/mapbox-gl.css';
+```
+
 ## Using with Browserify, Webpack, and other JavaScript Bundlers
 
 * `browserify` - react-map-gl is extensively tested with `browserify` and works without configuration.
@@ -18,28 +64,3 @@ npm install --save react-map-gl
 * `create-react-app` - At this point configuration-free builds are not possible with webpack due to the way the mapbox-gl-js module is published. You will need to eject your app and add an alias to your webpack config. The following [tutorial](https://github.com/zjhch123/react-map-gl-demo-with-create-react-app) might be helpful.
 
 There's many other ready-to-run [examples](https://github.com/uber/react-map-gl/blob/master/examples) you can take a look at if you need more inspiration.
-
-## Example Code
-
-```js
-import {Component} from 'react';
-import ReactMapGL from 'react-map-gl';
-
-class Map extends Component {
-  render() {
-    return (
-      <ReactMapGL
-        width={400}
-        height={400}
-        latitude={37.7577}
-        longitude={-122.4376}
-        zoom={8}
-        onViewportChange={(viewport) => {
-          const {width, height, latitude, longitude, zoom} = viewport;
-          // Optionally call `setState` and use the state to update the map.
-        }}
-      />
-    );
-  }
-}
-```

docs/get-started/state-management.md

@@ -0,0 +1,21 @@
+# State Management
+
+`InteractiveMap` is designed to be a stateless component. Its appearance is entirely controlled by the properties that are passed in from its parent. In this architecture, transition works the same way as interaction: the component shall notify the application of "user intent" by calling the `onViewportChange` callback, but ultimately the application needs to decide what to do with it.
+
+The most simple handling of this intent is to save it and pass it back to the component:
+```jsx
+<ReactMapGL
+    {...this.state.viewport}
+    onViewportChange={(viewport) => this.setState({viewport})} />
+```
+
+User interaction and transition will not work without a valid `onViewportChange` handler.
+
+
+## Using with Redux
+
+If you're using redux, it is very easy to hook this component up to store state in the redux state tree.
+The simplest way is to take all properties passed to the `onViewportChange` function property and add them
+directly into the store. This state can then be passed back to the `<ReactMapGL>` component without any transformation.
+
+You can even use the package [redux-map-gl](https://github.com/Willyham/redux-map-gl) to save you some writing.

docs/get-started/using-with-redux.md

@@ -1,7 +0,0 @@
-## Using with Redux
-
-If you're using redux, it is very easy to hook this component up to store state in the redux state tree.
-The simplest way is to take all properties passed to the `onViewportChange` function property and add them
-directly into the store. This state can then be passed back to the `<ReactMapGL>` component without any transformation.
-
-You can even use the package [redux-map-gl](https://github.com/Willyham/redux-map-gl) to save you some writing.

docs/overlays/canvas-overlay.md

@@ -26,3 +26,8 @@ Stop propagation of click event to the map component. Can be used to stop map fr
 
 ##### `captureDoubleClick` {Boolean} - default: `false`
 Stop propagation of dblclick event to the map component. Can be used to stop map from zooming when this component is double clicked.
+
+
+## Source
+[canvas-overlay.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/overlays/canvas-overlay.js)
+

docs/overlays/html-overlay.md

@@ -29,3 +29,6 @@ Stop propagation of click event to the map component. Can be used to stop map fr
 
 ##### `captureDoubleClick` {Boolean} - default: `false`
 Stop propagation of dblclick event to the map component. Can be used to stop map from zooming when this component is double clicked.
+
+## Source
+[html-overlay.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/overlays/html-overlay.js)

docs/overlays/svg-overlay.md

@@ -29,3 +29,6 @@ Stop propagation of click event to the map component. Can be used to stop map fr
 
 ##### `captureDoubleClick` {Boolean} - default: `false`
 Stop propagation of dblclick event to the map component. Can be used to stop map from zooming when this component is double clicked.
+
+## Source
+[svg-overlay.js](https://github.com/uber/react-map-gl/tree/3.2-release/src/overlays/svg-overlay.js)

docs/upgrade-guide.md

@@ -1,5 +1,11 @@
 # Upgrade Guide
 
+## Upgrading to v3.2
+
+- The latest mapbox-gl release requires stylesheet to be included at all times. See [Get Started](/docs/get-started/get-started.md) for information about styling.
+- Immutable.js is no longer a hard dependency and will be removed in the next major release. If you are importing immutable in your application, it is recommended that you explicitly list it in the application's dependencies.
+
+
 ## Upgrading to v3
 
 v3 is a major upgrade of react-map-gl. While we have tried to gently deprecated any changed or removed features, a few breaking changes could not be avoided.

docs/user-guide/perspective-mode.md

@@ -1,13 +0,0 @@
-## Perspective Mode
-
-Perspective mode is exposed using the `pitch` and `bearing` props (both default to `0`), which will show the map "tilted" `pitch` degrees (overhead being 0 degrees), looking towards `bearing` (0 degrees is north).
-
-In addition, the `perspectiveEnabled` prop (default: `false`) will activate mouse handlers that allow the user to change `pitch` and `bearing` using the mouse while holding down any function key {command, shift, ctrl, alt}.
-
-If `perspectiveEnabled` is not set to `true` then the user will not be able to change the pitch and bearing, which means that the default props will show an overhead map and only enable standard pan and zoom mouse actions on that map.
-
-**Considerations:**
-
-- Mapbox-gl-js limits the pitch to 60 degrees.
-- When using pitch, several additional fields are passed in the onViewportChange callback, make sure to pass all received props back to the component.
-- Not all overlays are compatible with perspective mode. For a set of overlays that do work with perspective mode, look at [deck.gl](https://github.com/uber/deck.gl).

docs/whats-new.md

@@ -1,9 +1,17 @@
 # react-map-gl v3.2
 
-Under development
+Realease date: January, 2018
+
+## Highlights
 
-- **Support for Map Reuse**: A new property `reuseMaps` is provided for applications that create and destroy maps, to help work around a mapbox-gl resource leak issue that can lead to a browser crash in certain situations.
 - **Viewport transition**: feature equivalent to Mapbox's flyTo and easeTo; smooth transition when using keyboard navigation or the NavigationControl.
+- **Better parity of Mapbox interaction**: navigation using keyboard and the navigation control matches Mapbox behavior, including smooth transition when zooming and panning.
+- **Support for Map Reuse (experimental)**: A new property `reuseMaps` is provided for applications that create and destroy maps, to help work around a mapbox-gl resource leak issue that can lead to a browser crash in certain situations.
+- **mapbox-gl 0.42.2**
+- **New props** of the InteractiveMap component:
+  + Map creation: `transformRequest`, `reuseMaps`
+  + Interaction: `touchZoom`, `touchRotate`
+  + Transition: `transitionDuration`, `transitionInterpolator`, `transitionEasing`, `transitionInterruption`, `onTransitionStart`, `onTransitionInterrupt`, `onTransitionEnd`
 
 # react-map-gl v3.1
 

examples/controls/src/control-panel.js

@@ -12,7 +12,7 @@ export default class ControlPanel extends PureComponent {
         <p>Map showing top 20 most populated cities of the United States. Click on a marker to learn more.</p>
         <p>Data source: <a href="https://en.wikipedia.org/wiki/List_of_United_States_cities_by_population">Wikipedia</a></p>
         <div className="source-link">
-          <a href="https://github.com/uber/react-map-gl/tree/master/examples/controls" target="_new">View Code ↗</a>
+          <a href="https://github.com/uber/react-map-gl/tree/3.2-release/examples/controls" target="_new">View Code ↗</a>
         </div>
       </Container>
     );

examples/filter/src/control-panel.js

@@ -13,7 +13,7 @@ export default class ControlPanel extends PureComponent {
         <h3>Highlight Features Containing Similar Data</h3>
         <p>Hover over counties to highlight counties that share the same name.</p>
         <div className="source-link">
-          <a href="https://github.com/uber/react-map-gl/tree/master/examples/filter" target="_new">View Code ↗</a>
+          <a href="https://github.com/uber/react-map-gl/tree/3.2-release/examples/filter" target="_new">View Code ↗</a>
         </div>
       </Container>
     );

examples/geojson-animation/src/control-panel.js

@@ -11,7 +11,7 @@ export default class ControlPanel extends PureComponent {
         <h3>Animated GeoJSON</h3>
         <p>Render animation by updating GeoJSON data source.</p>
         <div className="source-link">
-          <a href="https://github.com/uber/react-map-gl/tree/master/examples/geojson-animation"
+          <a href="https://github.com/uber/react-map-gl/tree/3.2-release/examples/geojson-animation"
             target="_new">
             View Code ↗
           </a>

examples/geojson/src/control-panel.js

@@ -14,7 +14,7 @@ export default class ControlPanel extends PureComponent {
         Hover over a state to see details.</p>
         <p>Data source: <a href="www.census.gov">US Census Bureau</a></p>
         <div className="source-link">
-          <a href="https://github.com/uber/react-map-gl/tree/master/examples/geojson" target="_new">View Code ↗</a>
+          <a href="https://github.com/uber/react-map-gl/tree/3.2-release/examples/geojson" target="_new">View Code ↗</a>
         </div>
         <hr />
 

examples/interaction/src/control-panel.js

@@ -49,7 +49,7 @@ export default class ControlPanel extends PureComponent {
         <h3>Limit Map Interaction</h3>
         <p>Turn interactive features off/on.</p>
         <div className="source-link">
-          <a href="https://github.com/uber/react-map-gl/tree/master/examples/interaction" target="_new">View Code ↗</a>
+          <a href="https://github.com/uber/react-map-gl/tree/3.2-release/examples/interaction" target="_new">View Code ↗</a>
         </div>
         <hr />
 

examples/layers/src/control-panel.js

@@ -111,7 +111,7 @@ export default class StyleControls extends PureComponent {
         <h3>Dynamic Styling</h3>
         <p>Dynamically show/hide map layers and change color with Immutable map style.</p>
         <div className="source-link">
-          <a href="https://github.com/uber/react-map-gl/tree/master/examples/layers" target="_new">
+          <a href="https://github.com/uber/react-map-gl/tree/3.2-release/examples/layers" target="_new">
             View Code ↗
           </a>
         </div>

examples/viewport-animation/src/control-panel.js

@@ -26,7 +26,7 @@ export default class ControlPanel extends PureComponent {
         <h3>Camera Transition</h3>
         <p>Smooth animate of the viewport.</p>
         <div className="source-link">
-          <a href="https://github.com/uber/react-map-gl/tree/master/examples/viewport-animation" target="_new">View Code ↗</a>
+          <a href="https://github.com/uber/react-map-gl/tree/3.2-release/examples/viewport-animation" target="_new">View Code ↗</a>
         </div>
         <hr />
         

website/src/constants/pages.js

@@ -60,16 +60,37 @@ const docPages = {
       children: [
         {
           name: 'Get Started',
-          content: getDocUrl('get-started/README.md')
+          content: getDocUrl('get-started/get-started.md')
         },
         {
           name: 'About Mapbox Tokens',
           content: getDocUrl('get-started/mapbox-tokens.md')
         },
         {
-          name: 'Using with Redux',
-          content: getDocUrl('get-started/using-with-redux.md')
+          name: 'State Management',
+          content: getDocUrl('get-started/state-management.md')
         },
+        {
+          name: 'Adding Custom Data',
+          content: getDocUrl('get-started/adding-custom-data.md')
+        }
+      ]
+    },
+    {
+      name: 'Advanced',
+      children: [
+        {
+          name: 'Custom Map Controls',
+          content: getDocUrl('advanced/custom-map-controls.md')
+        },
+        {
+          name: 'Custom Overlays',
+          content: getDocUrl('overlays/custom-overlays.md')
+        },
+        {
+          name: 'Viewport Transition',
+          content: getDocUrl('advanced/viewport-transition.md')
+        }
       ]
     },
     {
@@ -80,6 +101,10 @@ const docPages = {
           name: 'CanvasOverlay',
           content: getDocUrl('overlays/canvas-overlay.md')
         },
+        {
+          name: 'FlyToInterpolator',
+          content: getDocUrl('components/fly-to-interpolator.md')
+        },
         {
           name: 'HTMLOverlay',
           content: getDocUrl('overlays/html-overlay.md')
@@ -88,10 +113,18 @@ const docPages = {
           name: 'Interactive Map',
           content: getDocUrl('components/interactive-map.md')
         },
+        {
+          name: 'LinearInterpolator',
+          content: getDocUrl('components/linear-interpolator.md')
+        },
         {
           name: 'Marker',
           content: getDocUrl('components/marker.md')
         },
+        {
+          name: 'MapControls',
+          content: getDocUrl('components/map-controls.md')
+        },
         {
           name: 'Navigation Control',
           content: getDocUrl('components/navigation-control.md')
@@ -109,15 +142,6 @@ const docPages = {
           content: getDocUrl('overlays/svg-overlay.md')
         },
       ]
-    },
-    {
-      name: 'Advanced',
-      children: [
-        {
-          name: 'Custom Map Controls',
-          content: getDocUrl('advanced/custom-map-controls.md')
-        },
-      ]
     }
   ])
 };