Update docs for transition props (#389)

docs/components/interactive-map.md

@@ -19,7 +19,7 @@ class Map extends Component {
         zoom={8}
         onViewportChange={(viewport) => {
           const {width, height, latitude, longitude, zoom} = viewport;
-          // Optionally call `setState` and use the state to update the map.
+          // call `setState` and use the state to update the map.
         }}
       />
     );
@@ -116,6 +116,50 @@ Parameters
   + `state.isDragging` - If the map is being dragged.
   + `state.isHovering` - If the pointer is over a clickable feature.
 
+##### `transitionDuration` {Number}
+Duration of transition in milliseconds. If specified, the map's viewport will smoothly move from the previous props to the current one. Default `0`;
+
+##### `transitionInterpolator` {Object}
+An interpolator object that defines the transition behavior between two map states. `react-map-gl` offers two interpolators:
+- `LinearInterpolator` - similar to Mapbox's `easeTo` behavior.
+- `FlyToInterpolator` - similar to Mapbox's `flyTo` behavior.
+
+You may import them as follows:
+```jsx
+import ReactMapGL, {LinearInterpolator, FlyToInterpolator} from 'react-map-gl';
+
+<ReactMapGL transitionDuration={1000} transitionInterpolator={new FlyToInterpolator()}>
+```
+
+Default: `new LinearInterpolator()`
+
+For details about using transition interpolators, see [transitions](/docs/user-guide/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.
+
+##### `transitionInterruption` {Number}
+What to do if an ongoing transition is interrupted by another transition. There are 3 options:
+- `TRANSITION_EVENTS.BREAK` - Start new transition from the current view. This is the default.
+- `TRANSITION_EVENTS.SNAP_TO_END` - Jump to the end of the previous transition before starting the new transition.
+- `TRANSITION_EVENTS.IGNORE` - Complete the previous transition and ignore the new viewport change.
+
+You may import the constants as follows:
+```
+import {TRANSITION_EVENTS} from 'react-map-gl';
+```
+
+##### `onTransitionStart` {Function}
+
+Callback that is fired when a transition is triggered.
+
+##### `onTransitionInterrupt` {Function}
+Callback that is fired when an ongoing transition is interrupted by another transition.
+
+##### `onTransitionEnd` {Function}
+
+Callback that is fired when a transition is complete.
+
 ## Methods
 
 Same methods as [StaticMap](/docs/components/static-map.md).

docs/user-guide/transitions.md

@@ -1,19 +1,59 @@
-## Transitions
+# Transitions
 
-`react-map-gl` does not expose the transition API for `mapbox-gl-js` since it is designed to be a stateless component, and needs to synchronize with separate overlay systems such as deck.gl.
+`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.
 
-Instead it is recommended to use a separate module like [react-motion](https://github.com/chenglou/react-motion) to animate properties.
+Instead, transitions can be defined using [InteractiveMap](/docs/components/interactive-map.md)'s transition props. For example:
+```jsx
+import ReactMapGL, {LinearInterpolator, FlyToInterpolator} from 'react-map-gl';
+// 3rd-party easing functions
+import d3 from 'd3-ease';
 
-```js
-<Motion style={{
-  latitude: spring(viewport.latitude, { stiffness: 170, damping: 26, precision: 0.000001 }),
-  longitude: spring(viewport.longitude, { stiffness: 170, damping: 26, precision: 0.000001 })
-}}>
-  {({ latitude, longitude }) => <MapGL
+<ReactMapGL
     {...viewport}
-    latitude={latitude}
-    longitude={longitude}
-    mapStyle={mapboxStyle}
-  />}
-</Motion>
+    transitionDuration={1000}
+    transitionInterpolator={new FlyToInterpolator()}
+    transitionEasing={d3.easeCubic}
+    onTransitionEnd={() => {
+        // do something
+        }} >
 ```
+
+See [viewport transition](#examples/viewport-transition) for a complete example.
+
+## InteractiveMap's Transition Props
+
+See properties of [InteractiveMap](/docs/components/interactive-map.md).
+
+- `transitionDuration` {Number}
+- `transitionInterpolator` {Object}
+- `transitionEasing` {Function}
+- `transitionInterruption` {Number}
+- `onTransitionStart` {Function}
+- `onTransitionInterrupt` {Function}
+- `onTransitionEnd` {Function}
+
+## Transition Interpolators
+
+A `TransitionInterpolator` instance must be supplied to the `transitionInterpolator` prop. It contains the following methods:
+- `arePropsEqual(currentProps, nextProps)` - called to determine if transition should be triggered when viewport props update.
+- `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()`

examples/viewport-animation/package.json

@@ -7,7 +7,7 @@
     "immutable": "^3.8.1",
     "react": "^16.0.0",
     "react-dom": "^16.0.0",
-    "react-map-gl": "^3.1.0",
+    "react-map-gl": ">=3.2.0-alpha.1",
     "tween.js": "^16.6.0"
   },
   "devDependencies": {