diff --git a/docs/README.md b/docs/README.md index 23f21f76..30c6e99c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,21 +1,21 @@ -# Overview +# Introduction -react-map-gl is a react friendly API wrapper around +react-map-gl is a suite of React components for [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js). ## Example ```js -import MapGL from 'react-map-gl'; +import ReactMapGL from 'react-map-gl'; - { - const {latitude, longitude, zoom} = viewport; + onViewportChange={(viewport) => { + const {width, height, latitude, longitude, zoom} = viewport; // Optionally call `setState` and use the state to update the map. }} /> diff --git a/docs/advanced/custom-map-controls.md b/docs/advanced/custom-map-controls.md index 7b8552c5..9b3595c2 100644 --- a/docs/advanced/custom-map-controls.md +++ b/docs/advanced/custom-map-controls.md @@ -23,7 +23,7 @@ A simple example to disable mouse wheel: ``` Then pass it to the map during render: ```jsx - + ``` diff --git a/docs/components/interactive-map.md b/docs/components/interactive-map.md index 51144d20..5119f26f 100644 --- a/docs/components/interactive-map.md +++ b/docs/components/interactive-map.md @@ -18,7 +18,7 @@ class Map extends Component { longitude={-122.4376} zoom={8} onViewportChange={(viewport) => { - const {latitude, longitude, zoom} = viewport; + const {width, height, latitude, longitude, zoom} = viewport; // Optionally call `setState` and use the state to update the map. }} /> diff --git a/docs/get-started/README.md b/docs/get-started/README.md index 033c7f68..c5f3bf62 100644 --- a/docs/get-started/README.md +++ b/docs/get-started/README.md @@ -1,6 +1,6 @@ # Get Started -`ReactMapGL` is a [React](http://facebook.github.io/react/)-friendly +`react-map-gl` is a [React](http://facebook.github.io/react/)-friendly wrapper for [MapboxGL](https://www.mapbox.com/mapbox-gl-js/), a WebGL-powered vector and raster tile mapping library. On top of exposing as much of `MapboxGL` as possible, we also introduced our own event handling classes @@ -9,7 +9,7 @@ that aim to make working with external overlays, such as # Installation -`ReactMapGL` requires `node >= v4` and `react >= 15.4`. +`react-map-gl` requires `node >= v4` and `react >= 15.4`. ```sh npm install --save react-map-gl @@ -35,7 +35,7 @@ class Map extends Component { longitude={-122.4376} zoom={8} onViewportChange={(viewport) => { - const {latitude, longitude, zoom} = viewport; + const {width, height, latitude, longitude, zoom} = viewport; // Optionally call `setState` and use the state to update the map. }} /> @@ -46,25 +46,13 @@ class Map extends Component { ## Server Side Rendering -`ReactMapGL` depends on `gl`, which may cause issues when running in a server +`react-map-gl` depends on `gl`, which may cause issues when running in a server environment without `gl` installed. You can either make sure that your system -has `gl` installed or use the following work-around to ensure you only require -`ReactMapGL` on the client. - -```js -// is-browser is an npm package, but you can use any other solution to make sure -// that you are in a browser environment. -import isBrowser from 'is-browser'; - -const ReactMapGL = 'div'; -if (isBrowser) { - ReactMapGL = require('react-map-gl').default; -} -``` +has `gl` installed or make sure you only import `react-map-gl` on the client. ## Using with Browserify, Webpack, and other environments -* `browserify` - `ReactMapGL` is extensively tested with `browserify` and works +* `browserify` - `react-map-gl` is extensively tested with `browserify` and works without issue. * `webpack 1` - look at the [deck.gl exhibits](https://github.com/uber/deck.gl/tree/master/exhibits) diff --git a/docs/get-started/using-with-isomorphic-rendering.md b/docs/get-started/using-with-isomorphic-rendering.md deleted file mode 100644 index 8c7c5835..00000000 --- a/docs/get-started/using-with-isomorphic-rendering.md +++ /dev/null @@ -1,5 +0,0 @@ -# Using with Isomorphic Rendering - -Running under Node.js - -TBA \ No newline at end of file diff --git a/docs/get-started/using-with-redux.md b/docs/get-started/using-with-redux.md index 1db59bda..5947bfcf 100644 --- a/docs/get-started/using-with-redux.md +++ b/docs/get-started/using-with-redux.md @@ -8,4 +8,3 @@ without any transformation. You can use the package [redux-map-gl](https://github.com/Willyham/redux-map-gl) to save writing this code yourself. - diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md index 1fa88650..666258d1 100644 --- a/docs/upgrade-guide.md +++ b/docs/upgrade-guide.md @@ -4,26 +4,6 @@ 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. -### Two Map Components - -v3 now exposes two React components: `StaticMap` and `InteractiveMap`. -`InteractiveMap` is the default export. - -### StaticMap - -This is the React wrapper around `Mapbox GL JS` and takes in viewport properties -such as `width`, `height`, `latitude`, `longitude`. Style diffing and updating -logic also live here. See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/static-map.js) -for more information. - -### InteractiveMap - -This is a wrapper on top of `StaticMap`. It takes all the props -of `StaticMap` and additional ones such as `onViewportChange`, `scrollZoom`, -`dragRotate`, etc. to control interactivity on the map. -See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js) -for more information. - ### Breaking Changes #### `onChangeViewport` / `onViewportChange` viewport @@ -71,6 +51,27 @@ const viewport = new PerspectiveMercatorViewport({width: 600, height: 400}).fitB // } ``` +### Two Map Components + +v3 now exposes two React components: `StaticMap` and `InteractiveMap`. +`InteractiveMap` is the default export, and designed to be as compatible as +possible with the v2 default export. + +#### StaticMap + +This is the React wrapper around `Mapbox GL JS` and takes in viewport properties +such as `width`, `height`, `latitude`, `longitude`. Style diffing and updating +logic also live here. See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/static-map.js) +for more information. + +#### InteractiveMap + +This is a wrapper on top of `StaticMap`. It takes all the props +of `StaticMap` and additional ones such as `onViewportChange`, `scrollZoom`, +`dragRotate`, etc. to control interactivity on the map. +See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js) +for more information. + ### Deprecations We have started to deprecate a few React props. In all the cases below, the old `props` will still work (you'll get a warning in the console), but they will likely be removed in the next major version of react-map-gl so you should start using the new `props` as soon as possible. diff --git a/docs/whats-new.md b/docs/whats-new.md index 9c0a40b9..69e02287 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -7,63 +7,27 @@ Release date: End of Q2, 2017 (TBD) - **Node Version Requirement** is now **>=v6.4.0**: This is introduced in [Mapbox GL JS v0.38.0](https://github.com/mapbox/mapbox-gl-js/releases/tag/v0.38.0) - **Event Handling**: New event handling architecture that enables full customization of event handling (experimental). - **Multi-Touch Support**: Full support for multi-touch gestures such as pinch-to-zoom and rotate. +- **Two Map Components**: `StaticMap` and `InteractiveMap` are now exported from +the library, with the default being `InteractiveMap`. - **New Components**: `Popup`, `Marker`, `NavigationControl` have been added to provide parity with `Mapbox GL JS`. -`StaticMap` is also added, which provides a static React wrapper around a `mapbox` instance. +- **New Props**: `maxPitch`, `minPitch`, `dragPan`, `doubleClickZoom`, `touchZoomRotate`, +`scrollZoom` are now provided to allow granular control of map interactivity. - **Documentation**: Significantly expanded and linked with our other geospatial frameworks. - **Examples**: Additional stand-alone examples to get you instantly started with new features. -- **Latest Mapbox GL JS**: Bumps `Mapbox GL JS` to the [latest version](https://github.com/mapbox/mapbox-gl-js/releases) and enables us to stay in sync with future versions. - **Improved overlay components**: Vi ewport props (`width` `height` `zoom` `longitude` and `latitude`) are no longer required if you render `SVGOverlay` `CanvasOverlay` or `HTMLOverlay` as a child of the map. Perspective mode is now supported in all overlays. - -## New Props - -##### `{Bool} visible`: exposed on `StaticMap` -Allows control visibility of the map component. This uses CSS's `display` property internally. - -##### `{Func} getCursor`: exposed on `InteractiveMap` to determine the current cursor. -See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js#L97) -for more information. - -##### `{Number} maxPitch, {Number} minPitch`: exposed on `InteractiveMap` -Set the minimum and maximum allowed pitch. - -##### `{Bool} dragPan`: exposed on `InteractiveMap` -Set panning. Defaults to `true`. - -##### `{Bool} doubleClickZoom`: exposed on `InteractiveMap` -Set double clicking to zoom. Defaults to `true`. - -##### `{Bool} touchZoomRotate`: exposed on `InteractiveMap` -Set touch interaction. Defaults to `true`. - -##### `{Object} mapControls`: exposed on `InteractiveMap` -A map control instance to replace the default map controls. -The object must expose one property: `events` as an array of subscribed -event names; and two methods: `setState(state)` and `handle(event)` -See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js#L88) -for more information - -## Experimental Props - -##### `{Object} visibilityConstraints`: exposed on `InteractiveMap` -A set of constraints to keep map visible. This automatically takes care of toggling -`visible` on the `StaticMap` layer underneath. See -[Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js#L79) -for more information. - -## New API - -- `queryRenderedFeatures`: exposed on `StaticMap` and `InteractiveMap` +- **Latest Mapbox GL JS**: Bumps `Mapbox GL JS` to the [latest version](https://github.com/mapbox/mapbox-gl-js/releases) and enables us to stay in sync with future versions. ## Deprecations - **Property Names** - some prop names have been modernized, the old ones will still work for now with a warning. -- **Internal Properties** such as `isHovering` and `isDragging` have been removed. +- **Internal Properties** such as `isHovering`, `isDragging`, `startDragLngLat` have been removed. These were never meant to be useful publicly and have caused confusions in the past. ## Breaking Changes - **Overlay Support** - Three overlays (`ScatterplotOverlay`, `DraggablePointsOverlay`, `ChoroplethOverlay`), ... are now only provided as examples. -- **fitBounds**: `fitBounds` has been rewritten to provide a better interface. +- **fitBounds**: `fitBounds` has been moved to another repository, [viewport-mercator-project](https://github.com/uber-common/viewport-mercator-project). +It is also rewritten to provide a better interface. For more information, see `Upgrade Guide`. diff --git a/website/src/components/header.js b/website/src/components/header.js index 3f374cfa..f79a8a24 100644 --- a/website/src/components/header.js +++ b/website/src/components/header.js @@ -23,6 +23,12 @@ export default class Header extends Component { rel="noopener noreferrer"> Github + + Mapbox GL JS + diff --git a/website/src/components/home.js b/website/src/components/home.js index 7d91b8ed..8301621a 100644 --- a/website/src/components/home.js +++ b/website/src/components/home.js @@ -9,7 +9,7 @@ export default class Home extends Component { @@ -36,21 +36,22 @@ export default class Home extends Component { Component Library

- react-map-gl comes with additional React component that - synchronize with the map camera system. + react-map-gl comes with additional React components that + synchronize with the map camera system. Use one of the supported + overlays to visualize data, or build your own.

- Perfect Companion to deck.gl + Part of Uber Visualization's Framework Suite

- deck.gl is a great match with React, supporting - efficient WebGL rendering under the Reactive programming - paradigm. And when used with Mapbox GL it automatically - coordinates with the Mapbox camera system to provide - compelling 2D and 3D visualizations on top of your Mapbox - based maps. + Use together with e.g. + deck.gl to render performant and compelling 2D and 3D + WebGL visualizations on top of your Mapbox GL JS based maps.

diff --git a/website/src/constants/pages.js b/website/src/constants/pages.js index 3d559245..126f41b0 100644 --- a/website/src/constants/pages.js +++ b/website/src/constants/pages.js @@ -39,10 +39,10 @@ const docPages = { pageComponent: PagesComponent, paths: generatePath([ { - name: 'Overview', + name: 'Introduction', children: [ { - name: 'Overview', + name: 'Introduction', content: getDocUrl('README.md') }, { @@ -62,31 +62,36 @@ const docPages = { name: 'Get Started', content: getDocUrl('get-started/README.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: 'Using with Isomorphic Rendering', - content: getDocUrl('get-started/using-with-isomorphic-rendering.md') - }, - { - name: 'About Mapbox Tokens', - content: getDocUrl('get-started/mapbox-tokens.md') - } ] }, { - name: 'Components', + name: 'API Reference', children: [ + // NOTE: Keep this ordered Alphabetically { - name: 'Static Map', - content: getDocUrl('components/static-map.md') + name: 'CanvasOverlay', + content: getDocUrl('overlays/canvas-overlay.md') + }, + { + name: 'HTMLOverlay', + content: getDocUrl('overlays/html-overlay.md') }, { name: 'Interactive Map', content: getDocUrl('components/interactive-map.md') }, + { + name: 'Marker', + content: getDocUrl('components/marker.md') + }, { name: 'Navigation Control', content: getDocUrl('components/navigation-control.md') @@ -96,26 +101,13 @@ const docPages = { content: getDocUrl('components/popup.md') }, { - name: 'Marker', - content: getDocUrl('components/marker.md') + name: 'Static Map', + content: getDocUrl('components/static-map.md') }, - ] - }, - { - name: 'Overlays', - children: [ { name: 'SVGOverlay', content: getDocUrl('overlays/svg-overlay.md') }, - { - name: 'CanvasOverlay', - content: getDocUrl('overlays/canvas-overlay.md') - }, - { - name: 'HTMLOverlay', - content: getDocUrl('overlays/html-overlay.md') - }, ] }, { diff --git a/website/src/static/index.html b/website/src/static/index.html index 370e390b..803dea2d 100644 --- a/website/src/static/index.html +++ b/website/src/static/index.html @@ -4,16 +4,16 @@ react-map-gl - + - - - - + + + + @@ -23,8 +23,8 @@ - - + +