Merge pull request #98 from mapbox/icontrol

update mapboxgl control system, 0.27.0 fixes

.gitignore

@@ -1,2 +1,3 @@
 env.test.sh
 node_modules/
+dist/

API.md

@@ -1,6 +1,6 @@
-# mapboxgl.Directions
+# MapboxDirections
 
-A directions component using Mapbox Directions APi
+A directions component using Mapbox Directions API
 
 **Parameters**
 
@@ -10,7 +10,6 @@ A directions component using Mapbox Directions APi
     -   `options.interactive` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** Enable/Disable mouse or touch interactivity from the plugin (optional, default `true`)
     -   `options.profile` **\[[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** Routing profile to use. Options: `driving`, `walking`, `cycling` (optional, default `"driving"`)
     -   `options.unit` **\[[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** Measurement system to be used in navigation instructions. Options: `imperial`, `metric` (optional, default `"imperial"`)
-    -   `options.container` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element))** HTML element to initialize the map in (or element id as string). If no container is passed map.getContainer() is used instead.
     -   `options.geocoder` **\[[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** Pass options available to mapbox-gl-geocoder as [documented here](https://github.com/mapbox/mapbox-gl-geocoder/blob/master/API.md#mapboxglgeocoder).
     -   `options.controls` **\[[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** 
         -   `options.controls.inputs` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** Hide or display the inputs control. (optional, default `true`)
@@ -19,34 +18,46 @@ A directions component using Mapbox Directions APi
 **Examples**
 
 ```javascript
-var directions = new mapboxgl.Directions({
-  container: 'directions',
+var MapboxDirections = require('../src/index');
+var directions = new MapboxDirections({
+  accessToken: 'YOUR-MAPBOX-ACCESS-TOKEN',
   unit: 'metric',
-  profile: 'walking'
+  profile: 'cycling'
 });
-
+// add to your mapboxgl map
 map.addControl(directions);
 ```
 
-Returns **Directions** `this`
+Returns **[MapboxDirections](#mapboxdirections)** `this`
+
+## onRemove
+
+Removes the control from the map it has been added to. This is called by `map.removeControl`,
+which is the recommended method to remove controls.
+
+**Parameters**
+
+-   `map`  
 
-# interactive
+Returns **Control** `this`
+
+## interactive
 
 Turn on or off interactivity
 
 **Parameters**
 
 -   `state` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** sets interactivity based on a state of `true` or `false`.
 
-Returns **Directions** this
+Returns **[MapboxDirections](#mapboxdirections)** this
 
-# getOrigin
+## getOrigin
 
 Returns the origin of the current route.
 
 Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** origin
 
-# setOrigin
+## setOrigin
 
 Sets origin. _Note:_ calling this method requires the [map load event](https://www.mapbox.com/mapbox-gl-js/api/#Map.load)
 to have run.
@@ -55,15 +66,15 @@ to have run.
 
 -   `query` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> | [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** An array of coordinates [lng, lat] or location name as a string.
 
-Returns **Directions** this
+Returns **[MapboxDirections](#mapboxdirections)** this
 
-# getDestination
+## getDestination
 
 Returns the destination of the current route.
 
 Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** destination
 
-# setDestination
+## setDestination
 
 Sets destination. _Note:_ calling this method requires the [map load event](https://www.mapbox.com/mapbox-gl-js/api/#Map.load)
 to have run.
@@ -72,15 +83,15 @@ to have run.
 
 -   `query` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> | [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** An array of coordinates [lng, lat] or location name as a string.
 
-Returns **Directions** this
+Returns **[MapboxDirections](#mapboxdirections)** this
 
-# reverse
+## reverse
 
 Swap the origin and destination.
 
-Returns **Directions** this
+Returns **[MapboxDirections](#mapboxdirections)** this
 
-# addWaypoint
+## addWaypoint
 
 Add a waypoint to the route. _Note:_ calling this method requires the
 [map load event](https://www.mapbox.com/mapbox-gl-js/api/#Map.load) to have run.
@@ -90,9 +101,9 @@ Add a waypoint to the route. _Note:_ calling this method requires the
 -   `index` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** position waypoint should be placed in the waypoint array
 -   `waypoint` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> | Point)** can be a GeoJSON Point Feature or [lng, lat] coordinates.
 
-Returns **Directions** this;
+Returns **[MapboxDirections](#mapboxdirections)** this;
 
-# setWaypoint
+## setWaypoint
 
 Change the waypoint at a given index in the route. _Note:_ calling this
 method requires the [map load event](https://www.mapbox.com/mapbox-gl-js/api/#Map.load)
@@ -103,25 +114,31 @@ to have run.
 -   `index` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** indexed position of the waypoint to update
 -   `waypoint` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> | Point)** can be a GeoJSON Point Feature or [lng, lat] coordinates.
 
-Returns **Directions** this;
+Returns **[MapboxDirections](#mapboxdirections)** this;
 
-# removeWaypoint
+## removeWaypoint
 
 Remove a waypoint from the route.
 
 **Parameters**
 
 -   `index` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** position in the waypoints array.
 
-Returns **Directions** this;
+Returns **[MapboxDirections](#mapboxdirections)** this;
 
-# getWaypoints
+## getWaypoints
 
 Fetch all current waypoints in a route.
 
 Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** waypoints
 
-# on
+## removeRoutes
+
+Removes all routes and waypoints from the map.
+
+Returns **[MapboxDirections](#mapboxdirections)** this;
+
+## on
 
 Subscribe to events that happen within the plugin.
 
@@ -136,4 +153,67 @@ Subscribe to events that happen within the plugin.
     -   **error** \`{ error } Error as string
 -   `fn` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** function that's called when the event is emitted.
 
-Returns **Directions** this;
+Returns **[MapboxDirections](#mapboxdirections)** this;
+
+# getResult
+
+Return the input
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** input
+
+# query
+
+Set & query the input
+
+**Parameters**
+
+-   `query` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** An array of coordinates [lng, lat] or location name as a string.
+
+Returns **Geocoder** this
+
+# setInput
+
+Set input
+
+**Parameters**
+
+-   `value` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** An array of coordinates [lng, lat] or location name as a string. Calling this function just sets the input and does not trigger an API request.
+
+Returns **Geocoder** this
+
+# on
+
+Subscribe to events that happen within the plugin.
+
+**Parameters**
+
+-   `type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** name of event. Available events and the data passed into their respective event objects are:-   **clear** `Emitted when the input is cleared`
+    -   **loading** `Emitted when the geocoder is looking up a query`
+    -   **results** `{ results } Fired when the geocoder returns a response`
+    -   **result** `{ result } Fired when input is set`
+    -   **error** \`{ error } Error as string
+-   `fn` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** function that's called when the event is emitted.
+
+Returns **Geocoder** this;
+
+# fire
+
+Fire an event
+
+**Parameters**
+
+-   `type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** event name.
+-   `data` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** event data to pass to the function subscribed.
+
+Returns **Geocoder** this
+
+# off
+
+Remove an event
+
+**Parameters**
+
+-   `type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Event name.
+-   `fn` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function that should unsubscribe to the event emitted.
+
+Returns **Geocoder** this

CHANGELOG.md

@@ -1,8 +1,17 @@
+## 3.0.0
+
+Support for the Mapbox GL JS 0.27.0 API. This is compatible with 0.27.0 and later, and not compatible with earlier versions.
+
+- [breaking] `container` option removed - attaching the control outside of the map is no longer supported
+- [breaking] `position` option removed - the `addControl` method now specifies the position
+- [breaking] Now exports `MapboxDirections` rather than attaches to `mapbox.Directions`
+- [internal] no longer creates a new map control for each of the two geocoders, instead creates two internal geocoders
+- [feature] `removeRoutes` method that removes all route lines, waypoints, and instructions
+
 ## 2.2.0
 - [feature] Defer mapboxgl dependency til runtime to support webpack async loading #86 https://github.com/mapbox/mapbox-gl-directions/pull/86
 - [bug] Fix mapboxgl.GeoJSONSource deprecation in gl-js v.22 and map.load race condition
 
-
 ## 2.1.0
 
 - [bug] Warn if mapboxgl is not present [#66](https://github.com/mapbox/mapbox-gl-directions/issues/66)

README.md

@@ -5,7 +5,25 @@ A full featured directions plugin for [mapbox-gl-js](https://github.com/mapbox/m
 
 ### Usage
 
-See https://www.mapbox.com/mapbox-gl-js/example/mapbox-gl-directions/
+```javascript
+var mapboxgl = require('mapbox-gl');
+var MapboxDirections = require('mapbox-gl-directions');
+
+var directions = new MapboxDirections({
+  accessToken: 'YOUR-MAPBOX-ACCESS-TOKEN',
+  unit: 'metric',
+  profile: 'cycling'
+});
+
+var map = new mapboxgl.Map({
+  container: 'map',
+  style: 'mapbox://styles/mapbox/streets-v9'
+});
+
+map.addControl(directions, 'top-left');
+```
+
+Live example: https://www.mapbox.com/mapbox-gl-js/example/mapbox-gl-directions/
 
 ### Deeper dive
 

circle.yml

@@ -0,0 +1,3 @@
+machine:
+  node:
+    version: 4