react-map-gl-draw: update docs and examples (uber#392)

docs/api-reference/react-map-gl-draw/react-map-gl-draw.md

@@ -3,20 +3,24 @@
 `react-map-gl-draw` is a react based drawing library tailored for [`react-map-gl`](https://github.com/uber/react-map-gl).
 
 ## Options
-- `mode` (Object, Optional)
-  - `EditorModes.READ_ONLY` - Not interactive. This is the default mode.
-  - `EditorModes.SELECT` - Lets you select, delete, and drag features.
-  - `EditorModes.EDITTING` - Lets you select, delete, and drag vertices; and drag features.
-  - `EditorModes.DRAW_PATH` - Lets you draw a GeoJson `LineString` feature.
-  - `EditorModes.DRAW_POLYGON` - Lets you draw a GeoJson `Polygon` feature.
-  - `EditorModes.DRAW_POINT` - Lets you draw a GeoJson `Point` feature.
-  - `EditorModes.DRAW_RECTANGLE` - Lets you draw a `Rectangle` (represented as GeoJson `Polygon` feature).
-
-- `features` (Feature[], Optional) - List of features in GeoJson format. `react-map-gl-draw` respect the user' input `features`. If not provided, will manage `features` internally, and user can access and manipulate the `features` by calling `getFeatures`, `addFeatures`, and `deleteFeatures`.
-- `selectedFeatureIndex` (String, Optional) - Index of the selected feature. If not provided, will manage it internally.
+- `mode` (Object, Optional) - A mode instance. default to null. 
+
+Support the following modes from `@nebula.gl/edit-modes`. Note: Currently `react-map-gl-draw` does not support `modeConfig` in `@nebula.gl/edit-modes`.   
+  - `DrawCircleByDiameterMode`: Lets you draw a GeoJson `Circle` feature.
+  - `DrawCircleFromCenterMode`: Lets you draw a GeoJson `Circle` feature.
+  - `DrawPointMode`: Lets you draw a GeoJson `Point` feature.
+  - `DrawLineStringMode`: Lets you draw a GeoJson `LineString` feature.
+  - `DrawPolygonMode`: Lets you draw a GeoJson `Polygon` feature.
+  - `DrawRectangleMode`: Lets you draw a `Rectangle` (represented as GeoJson `Polygon` feature) with two clicks - start drawing on first click, and finish drawing on second click.
+
+And an advanced
+  - `EditingMode`: Lets you select and drag vertices; and drag features.
+
+- `features` (Feature[], Optional) - List of features in GeoJson format. If `features` are provided from users, then `react-map-gl-draw` respect the users' input, and therefore ignore any internal `features`. But if `features` are not provided, then `react-map-gl-draw` manages `features` internally, and users can access and manipulate the features by calling `getFeatures`, `addFeatures`, and `deleteFeatures`.
+- `selectedFeatureIndex` (String, Optional) - Index of the selected feature.
 - `clickRadius` (Number, Optional) - Radius to detect features around a hovered or clicked point. Default value is `0`
 
-- `onSelect` (Function, Optional) - callback when clicking a position under `SELECT` and `EDITTING` mode. Receives an object containing the following parameters
+- `onSelect` (Function, Optional) - callback when clicking a position when `selectable` set to true. Receives an object containing the following parameters
   - `selectedFeature`: selected feature. `null` if clicked an empty space.
   - `selectedFeatureIndex`: selected feature index.`null` if clicked an empty space.
   - `editHandleIndex`: selected editHandle index. `null` if clicked an empty space.
@@ -105,66 +109,133 @@ As shown in the above image, for the feature currently being edited,
 - Delete a single or multiple GeoJson features to editor.
 
 ## Code Example
+
+**Simple example: Draw polygon**
+
 ```js
 import React, { Component } from 'react';
 import MapGL from 'react-map-gl';
-import { Editor, EditorModes } from 'react-map-gl-draw';
+import {
+  Editor,
+  DrawPolygonMode,
+} from 'react-map-gl-draw';
+
+const DEFAULT_VIEWPORT = {
+  width: 800,
+  height: 600,
+  longitude: -122.45,
+  latitude: 37.78,
+  zoom: 14,
+};
+
+export default class App extends Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      viewport: DEFAULT_VIEWPORT,
+      modeHandler: null,
+    };
+  }
+
+  _updateViewport = (viewport) => {
+    this.setState({ viewport });
+  };
+
+  render() {
+    const { viewport } = this.state;
+    return (
+      <MapGL
+        {...viewport}
+        width="100%"
+        height="100%"
+        mapStyle={'mapbox://styles/mapbox/light-v9'}
+        onViewportChange={this._updateViewport}
+      >
+        <Editor
+          // to make the lines/vertices easier to interact with
+          clickRadius={12}
+          mode={new DrawPolygonMode()}
+        />
+        {this._renderToolbar()}
+      </MapGL>
+    );
+  }
+}
+```
+
+**Advanced example: multiple draw modes and editing drawn features**
+
+```js
+import React, { Component } from 'react';
+import { render } from 'react-dom';
+import MapGL from 'react-map-gl';
+import {
+  Editor,
+  EditingMode,
+  DrawLineStringMode,
+  DrawPolygonMode,
+} from 'react-map-gl-draw';
 
 const MODES = [
-  { id: EditorModes.EDITING, text: 'Select and Edit Feature'},
-  { id: EditorModes.DRAW_POINT, text: 'Draw Point'},
-  { id: EditorModes.DRAW_PATH, text: 'Draw Polyline'},
-  { id: EditorModes.DRAW_POLYGON, text: 'Draw Polygon'},
-  { id: EditorModes.DRAW_RECTANGLE, text: 'Draw Rectangle'}
+  { id: 'drawPolyline', text: 'Draw Polyline', handler: DrawLineStringMode },
+  { id: 'drawPolygon', text: 'Draw Polygon', handler: DrawPolygonMode },
+  { id: 'editing', text: 'Edit Feature', handler: EditingMode },
 ];
 
 const DEFAULT_VIEWPORT = {
   width: 800,
   height: 600,
   longitude: -122.45,
   latitude: 37.78,
-  zoom: 14
+  zoom: 14,
 };
 
-class App extends Component {
-  state = {
-    // map
-    viewport: DEFAULT_VIEWPORT,
-    // editor
-    selectedMode: EditorModes.READ_ONLY
-  };
+export default class App extends Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      viewport: DEFAULT_VIEWPORT,
+      modeId: null,
+      modeHandler: null,
+    };
+  }
 
   _switchMode = evt => {
-    const selectedMode = evt.target.id;
-    this.setState({
-     selectedMode: selectedMode === this.state.selectedMode ? null : selectedMode
-    });
+    const modeId = evt.target.value === this.state.modeId ? null : evt.target.value;
+    const mode = MODES.find(m => m.id === modeId);
+    const modeHandler = mode ? new mode.handler() : null;
+    this.setState({modeId, modeHandler});
   };
 
   _renderToolbar = () => {
     return (
-      <div style={{position: absolute, top: 0, right: 0, maxWidth: '320px'}}>
+      <div style={{position: 'absolute', top: 0, right: 0, maxWidth: '320px'}}>
         <select onChange={this._switchMode}>
-          <option value="">--Please choose a mode--</option>
-          {MODES.map(mode => <option value={mode.id}>{mode.text}</option>)}
+          <option value="">--Please choose a draw mode--</option>
+          {MODES.map(mode => <option key={mode.id} value={mode.id}>{mode.text}</option>)}
         </select>
       </div>
     );
   };
 
+  _updateViewport = (viewport) => {
+    this.setState({ viewport });
+  };
+
   render() {
-    const { viewport, selectedMode } = this.state;
+    const { viewport, modeHandler } = this.state;
     return (
       <MapGL
         {...viewport}
         width="100%"
         height="100%"
         mapStyle={'mapbox://styles/mapbox/light-v9'}
-        onViewportChange={this.setState({ viewport })}
+        onViewportChange={this._updateViewport}
       >
         <Editor
+          // to make the lines/vertices easier to interact with
           clickRadius={12}
-          mode={selectedMode}
+          mode={modeHandler}
         />
         {this._renderToolbar()}
       </MapGL>

examples/react-map-gl-draw/app.js

@@ -42,6 +42,7 @@ export default class App extends Component {
       // editor
       selectedMode: null,
       selectedFeatureIndex: null,
+      selectable: false,
     };
     this._editorRef = null;
   }

examples/react-map-gl-draw/package.json

@@ -11,7 +11,7 @@
     "react": "^16.3.0",
     "react-dom": "^16.3.0",
     "react-map-gl": "^4.0.0",
-    "react-map-gl-draw": "^0.18.0-alpha.2",
+    "react-map-gl-draw": "^0.18.1",
     "@math.gl/core": "^3.1.3"
   },
   "devDependencies": {