13 |
14 | 
15 |
16 | 
17 |
18 | 
19 |
20 | ## Edit the Style
21 |
22 | Use the [Maputnik CLI](http://openmaptiles.org/docs/style/maputnik/) to edit and develop the style.
23 | After you've started Maputnik open the editor on `localhost:8000`.
24 |
25 | ```
26 | maputnik --watch --file style.json
27 | ```
28 |
29 | ## License
30 |
31 | - [ ] Clarify license
32 |
--------------------------------------------------------------------------------
/demo/src/assets/map/custom-directions.ts:
--------------------------------------------------------------------------------
1 | import type maplibregl from "maplibre-gl";
2 | import type { MapLibreGlDirectionsConfiguration, Feature, LineString, Point } from "@maplibre/maplibre-gl-directions";
3 | import MapLibreGlDirections from "@maplibre/maplibre-gl-directions";
4 | import { MapLibreGlDirectionsNonCancelableEvent } from "@maplibre/maplibre-gl-directions";
5 |
6 | export default class CustomMapLibreGlDirections extends MapLibreGlDirections {
7 | constructor(map: maplibregl.Map, configuration?: Partial-
11 | {#each examples.sort((a, b) => a.index - b.index) as example}
12 |
- 13 | {example.name} 14 | 15 | {/each} 16 |
20 |
32 |
33 |
34 |
44 |
--------------------------------------------------------------------------------
/doc/BASIC_USAGE.md:
--------------------------------------------------------------------------------
1 | Start by importing the plugin. Then, when the map is loaded, create an instance of the imported {@link default|`MapLibreGlDirections`} class passing to the constructor a map instance and optionally a {@link MapLibreGlDirectionsConfiguration|configuration object}.
2 |
3 | ```typescript
4 | import MapLibreGlDirections from "@maplibre/maplibre-gl-directions";
5 |
6 | map.on("load", () => {
7 | const directions = new MapLibreGlDirections(map, {
8 | // optional configuration
9 | });
10 | });
11 | ```
12 |
13 | If needed, enable the interactivity.
14 |
15 | ```typescript
16 | directions.interactive = true;
17 | ```
18 |
19 | Use the plugin's public interface to set, add and remove waypoints.
20 |
21 | ```typescript
22 | // Set the waypoints programmatically
23 | directions.setWaypoints([
24 | [-73.8271025, 40.8032906],
25 | [-73.8671258, 40.82234996],
26 | ]);
27 |
28 | // Remove the first waypoint
29 | directions.removeWaypoint(0);
30 |
31 | // Add a waypoint at index 0
32 | directions.addWaypoint([-73.8671258, 40.82234996], 0);
33 | ```
34 |
35 | Listen to the plugin's events.
36 |
37 | ```typescript
38 | directions.on("movewaypoint", () => {
39 | console.log("A waypoint has been moved!");
40 | });
41 | ```
42 |
43 | Call the {@link clear|`clear`} method to remove all the plugin's traces from the map.
44 |
45 | ```typescript
46 | directions.clear();
47 | ```
48 |
49 | If you need to completely disable the plugin, make sure to call the {@link destroy|`destroy`} method first.
50 |
51 | ```typescript
52 | directions.destroy();
53 | directions = undefined;
54 | ```
55 |
--------------------------------------------------------------------------------
/src/controls/bearings/main.ts:
--------------------------------------------------------------------------------
1 | import type { IControl } from "maplibre-gl";
2 | import BearingsControlComponent from "./BearingsControl.svelte";
3 | import { BearingsControlDefaultConfiguration } from "./types";
4 | import type { BearingsControlConfiguration } from "./types";
5 | import type MapLibreGlDirections from "../../directions/main";
6 |
7 | /**
8 | * Creates an instance of BearingsControl that could be added to the map using the
9 | * {@link https://maplibre.org/maplibre-gl-js-docs/api/map/#map#addcontrol|`addControl`} method.
10 | *
11 | * @example
12 | * ```typescript
13 | * import MapLibreGlDirections, { BearingsControl } from "@maplibre/maplibre-gl-directions";
14 | * map.addControl(new BearingsControl(new MapLibreGlDirections(map)));
15 | * ```
16 | */
17 | export default class BearingsControl implements IControl {
18 | constructor(directions: MapLibreGlDirections, configuration?: Partial
66 | The LoadingIndicatorControl adds a simple spinning loader-icon which automatically appears whenever there's
67 | an ongoing routing-request.
68 |
62 | Instead of aborting routing-requests manually, you can set the requestTimeout configuration option to a
63 | number of ms that a routing-request is allowed to take before getting automatically aborted.
64 |
This example makes POST requests to the official Mapbox Directions API with the following options:
71 | 72 |-
73 |
- 74 | annotations={annotations} 75 | 76 |
- overview=full 77 |
- alternatives=true 78 |
76 | In this example the default layers used by the plugin are augmented with an additional "symbol" layer which is only 77 | rendered for the ORIGIN and DESTINATION waypoints. 78 |
79 | 80 |
81 | Note how you don't need to re-define all the layers from scratch thanks to the exported
82 | layersFactory function that returns all the default layers allowing for their augmentation and modification
83 |
Another example that demonstrates the ease of extending the original styles provided by the plugin.
73 | 74 |This time a "symbol" layer is added that shows the direction the selected route goes in.
75 | 76 | Note that you have to manually load and add the images you intend to use for the custom layers you 78 | add 80 |66 | Sometimes it's pretty hard to aim exactly at the selected route line to add a waypoint by dragging it when using the 67 | plugin on a touch device. 68 |
69 | 70 |
71 | The example shows how one could use the layersFactory's input parameters to handle that case by
72 | increasing the points by 1.5 and the lines by 2 times when the map is used on a touch-enabled device.
73 |
54 | Total Route Distance: 55 | {#if totalDistance} 56 | {totalDistance}m 57 | {:else} 58 | unknown 59 | {/if} 60 |
61 | 62 | Note that you might want to zoom in and out the map to toggle the distance-annotations visibility 65 | 66 |67 | This is an example of how one could use the plugin's extensibility interfaces to create a distance measurement tool 68 | out of it. 69 |
70 | 71 |
72 | Here we create a subclass of the MapLibreGlDirections main super class and augment the original
73 | buildRoutelines
74 | method to write each route leg's distance into a respective feature's properties object. These saved distances
75 | are then used by an additional "symbol" layer that displays them along the respective route's lines on the map.
76 |
79 | The total distance comes from the response's specific field and is updated each time there's the "fetchroutesend" or 80 | the "removewaypoint" event fired. 81 |
82 |
84 |
87 |
88 | Set waypoints to a predefined set
85 | 86 |
89 |
92 |
93 | Add a random waypoint at some random index
90 | 91 |
94 |
97 |
98 | Delete a random waypoint
95 | 96 |
99 |
102 | Clear the map from all the stuff added by the plugin
100 | 101 |localStorage to save routes, but you are obviously not restricted to it. There might
71 | instead be a file or a serverside-database or whatever else
73 |
74 | 75 | If you want to save/load the route, the obvious way to do so would be to save the list of waypoints whenever the 76 | route is updated and to make a new routing-request with the saved waypoints' coordinates whenever you need to load 77 | it. 78 |
79 | 80 |81 | But what if the underlying roads networks changes for some reason? You'll get a different route for the same set of 82 | waypoints. Moreover, if there are some severe construction works going on, you run into a risk of not getting any 83 | routes whatsoever. 84 |
85 | 86 |87 | Sometimes it's actually a good idea to save the route as a list of GeoJSON Features and be able to load these saved 88 | features whenever there's a need. This example shows how that could be done. 89 |
90 |{message}
84 | {/if} 85 | 86 | 90 | 91 | 95 | 96 | 100 | 101 | 105 | 106 |-
107 |
- Click somewhere on the map to add a waypoint 108 |
- Click a waypoint to remove it and its related snappoint 109 |
- Click a snappoint to remove it and its related waypoint 110 |
- Drag a waypoint somewhere to move it 111 |
- Drag a routeline somewhere to add a waypoint in-between the 2 nearest ones 112 |
-
113 | Click an alternative routeline to select it
114 | Note, there's usually no alternative routelines in the server response if there are more than 116 | 2 waypoints 118 |
119 |
90 | It's completely up to you how to style the Directions' features shown on the map. You can either use the default 91 | styles provided by the plugin (see other examples), easily modify the default features' dimensions (see the 92 | Touch-Friendly Features example) or 93 | define your custom features' styles from scratch. 94 |
95 | 96 |This example demonstrates the last option.
97 |88 | This example showcases routing with multiple profiles. Segments corresponding to different profiles are displayed in 89 | different colors. Plugin provides default styles for typical OSRM profiles: car, bike, foot. Styles can be changed per profile via general style customization approach (consult the 93 | Restyling example). In case different profiles are used you can similarly 94 | style map features corresponding to each profile by targeting profile property of a feature (see 95 | default styles). 98 |
99 | 100 | Note that interactivity is not supported for multiple profiles 101 | 102 |Used profiles:
103 |-
104 | {#each displayedProfiles as profile}
105 |
- {@html profile} 106 | {/each} 107 |
110 |
111 |
112 |
113 | 73 | The bearings support 74 | allows to control in which direction the route would be continued from a given waypoint. 75 |
76 | 77 |
78 | In order to enable support for this API option on the plugin level, pass the bearings: true option to
79 | the plugin's configuration object. When this is done, each request would contain the bearings field. The
80 | problem with that is that the values for the waypoints' bearings are not populated correctly since we need some way to
81 | assign these bearings values to our waypoints.
82 |
Luckily, that's possible to achieve using the built-in Bearings Control.
85 | 86 | 90 | 91 | 95 | 96 | 100 | 101 | 105 | 106 | 110 | 111 | 115 | 116 | 120 | 121 | 129 | 130 | 138 | 139 | 147 | 148 | 156 | 157 | 161 | 162 | 166 |139 | This example listens for all the available events and logs them below. Interact with the map to see the emitted 140 | events. 141 |
142 | 143 | 147 | 148 | {#if preventDefault} 149 | 153 | {/if} 154 | 155 | 156 | While the "Prevent Default" checkbox above is selected, all the subsequent cancelable events will have their default 157 | behavior prevented by calling the event'spreventDefault() method. Such events will be displayed below
158 | as a strikethrough text.
159 |
160 | {#if preventDefault}
161 | Checking the "Force-allow adding waypoints" will make adding waypoints ignore its
162 | preventDefault() invocations
163 | {/if}
164 |
165 |
166 | {#if messages.length}
167 |
168 | {/if}
169 |
170 | -
171 | {#each messages as message}
172 |
- {@html message} 173 | {/each} 174 |
113 |
182 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Contributing Guide
2 |
3 | ## Prepare the Development Environment
4 |
5 | 1. Make sure you've got Node (v. ^16) and NPM (v. ^8) installed
6 | 2. Fork the repo
7 | 3. Clone the fork
8 | 4. Install the dependencies: `npm i`
9 | 5. Run `npm run env:prep`
10 | 6. Introduce some changes (see the section below)
11 | 7. Make sure the `npm run build` passes
12 | 8. Commit and push the changes
13 | 9. Create a PR
14 |
15 | _In case of any troubles, refer to the troubleshooting instructions at the bottom of this page._
16 |
17 | The step 5 is a shorthand for `npm run build:lib && npm link && npm link @maplibre/maplibre-gl-directions` where the last two commands must be performed in order to have the `@maplibre/maplibre-gl-directions` as a local symlinked dependency, because the Demo project uses not the library sources, but the locally-built `/dist` folder to make sure that the instance being tested is the same instance which is deployed to the end user.
18 |
19 | ## Project Structure
20 |
21 | The source files of the library itself are located under the `/src` folder. The `/src/main.ts` is the main entry point. The `/src/directions` folder contains everything related to the plugin's main purpose. The `/src/control` folder contains all the UI-Control-related source code.
22 |
23 | TypeDoc is responsible for building all the API documentation. The API documentation is built from the library sources and from the files located under the `/doc` folder.
24 |
25 | The Demo project's source files are located under the `/demo` folder. See its README for more information.
26 |
27 | ## Making Changes
28 |
29 | _All the processes mentioned in this section are described in more detail in the section below._
30 |
31 | Changes to the library sources should be introduced while there's a running `dev:lib` process. You may also want to have a running `dev:doc` process to see how correctly your doc-comments are parsed. Notice however that `dev:doc` does not serve the built documentation static-website somewhere, it just continuously rebuilds it.
32 |
33 | The Demo project might be used as a test-stand while working on the library sources. The `dev:demo` process serves the demo project at `localhost:3000` (by default). The Demo project uses the built `/dist` folder to refer to the library (instead of using sources from the `/src` directly), so you may also want to have a running `dev:lib` at the same time.
34 |
35 | You may keep any examples you add when creating a PR if you think the changes you were working on are worth a separate example. An additional example by itself (without modifying the library sources) is a good PR candidate as well. The only thing you should remember when introducing any changes to the Demo project is that they are about to be seen by any other person, a potential end-user, so don't go too crazy and provide human-readable explanations of what the example is really meant to show.
36 |
37 | ## NPM Scripts
38 |
39 | - `npm run prepare` - is run automatically when the project is being prepared (namely, when `npm i` is run). Configures the Husky's checks.
40 |
41 | - `npm run env:prep` - builds the library and self-links it for the Demo project.
42 |
43 | - `npm run dev:lib` - starts a vite-powered development server for the library source files. Continuously rebuilds the contents of the `/dist` folder while you make changes to the `/src` folder. **Does not rebuild types!** Must be restarted in order to rebuild them.
44 |
45 | - `npm run dev:doc` - continuously rebuilds the documentation static-website while you make changes to the library source files and puts the results under the `/docs/api`.
46 |
47 | - `npm run dev:demo` - starts a vite-powered development server for the Demo project. The Demo project targets the library from the `/dist` folder via a symlinked `@maplibre/maplibre-gl-directions` package.
48 |
49 | - `npm run build` - Combines `npm run lint`, `npm run build:lib`, `npm run build:doc` and `npm run build:demo` into a single call.
50 |
51 | 1. `npm run build:lib` - builds the library (the `/src` folder contents) and outputs the resulting es-module and its type declarations into the `/dist` folder.
52 |
53 | 2. `npm run build:doc` - builds the documentation (the `/doc` folder contents and the source code comments) using the TypeDoc compiler and outputs the resulting static-website into the `/docs/api` folder.
54 |
55 | 3. `npm run build:demo` - builds the Demo project (the `/demo` folder contents) and outputs the resulting static-website into the `/docs` folder.
56 |
57 | - `npm run format` - formats all the files that are not ignored by the `.prettierignore` and rewrites the files in-place.
58 |
59 | - `npm run prelint` - is run automatically each time when `npm run lint` is called.
60 |
61 | - `npm run lint` - lints and fixes the contents all the .ts, .js, .cjs and .svelte files and rewrites the files in-place.
62 |
63 | - `npm run check:lib` - checks the `/src` folder contents using the `svelte-check`.
64 |
65 | - `npm run check:demo` - checks the `/demo` folder contents using the `svelte-check`.
66 |
67 | - `npm run check` - combines `npm run lint`, `npm run check:lib` and `npm run check:demo` into a single call. Is run automatically if there were changes to the `/src` or `/demo` folders before you commit the changes and aborts the commit if there are errors that could not be automatically fixed by eslint.
68 |
69 | Since the deployment process is configured to be performed automatically, you don't have to make sure that the `/docs` folder is up-to-date (it's actually ignored by Git). You run `npm run build` manually only to make sure that the build doesn't fail.
70 |
71 | ## CI/CD Setup
72 |
73 | We use GitHub Actions for deployment. There are several tasks that get performed independently:
74 |
75 | - Build and Deploy the Demo project
76 | - Build and Publish the Library
77 | - Pull Request Checks
78 |
79 | ### Build and Deploy the Demo project
80 |
81 | Deploys the `/docs` folder to GitHub Pages each time the main branch is pushed (building the folder from sources beforehand). The GitHub Pages is configured in such a way so that the deployed site is actually available under the maplibre.org domain. Does not require any special access tokens.
82 |
83 | ### Build and Publish the Library
84 |
85 | Triggered manually whenever the team decides it's the time to release a new version of the library. Builds the sources from the target branch, runs all the checks, prepares the build-artifacts, updates the version in `package.json` (and automatically commits the changes), prepares the release notes and releases the new version to NPM all in one action.
86 |
87 | At the time of writing this ignores all the changes to the files made by `eslint --fix` and `prettier --write`, but there's a plan to fix that (#108).
88 |
89 | Requires a special access token (a secret) with slightly bumped permissions in order for github actions bot to be able to commit and push the updated `package.json` version of the library. The token is called "GH_TOKEN" and is a personal access token with the following permissions granted: admin:org, admin:org_hook, admin:public_key, admin:repo_hook, repo, workflow, write:packages.
90 |
91 | Also requires the "NPM_ORG_TOKEN" token which is an organization secret to be able to release the package under the "@maplibre" namespace.
92 |
93 | ### Pull Request Checks
94 |
95 | Whenever there's a new PR, ensures that:
96 |
97 | - The build passes
98 | - The PR has at least one of the following labels: either `release:ignore`, or `semver:patch`, or `semver:minor`, or `semver:major`.
99 |
100 | `semver-*` labels are used to indicate the backwards-compatibility of the proposed changes in order for GitHub to be able to automatically build the release notes. The `release:ignore` label should be used in cases when there's no need to mention the PR in release notes.
101 |
102 | Please, note that there's no protection from releasing a minor or a patch version when there was a `semver:major` PR merged. The maintainers should track the changes themselves. In general, it's a good idea to release new versions as soon as there are some changes available.
103 |
104 | ## Troubleshooting
105 |
106 | ### "Failed to resolve import "@maplibre/maplibre-gl-directions" from "demo/<...>". Does the file exist?
107 |
108 | That happens when the package is not self-symlinked. Perhaps you did `npm i` or installed some new dependencies (NPM removes all the symlinked deps after updating the `node_modules`).
109 |
110 | **Solution**: run `npm run env:prep` once again.
111 |
112 | ### `npm run build` fails without a meaningful reason
113 |
114 | This may happen if you have already had the project on your machine and recently pulled the upstream changes. Due to some package version updates the build may start to fail without any reasonable explanation of why is it so.
115 |
116 | **Solution**: run `npm ci` instead of `npm i` and try again. Another solution might be to completely delete the `node_modules` folder and reinstall the dependencies from scratch.
117 |
--------------------------------------------------------------------------------
/src/directions/layers.ts:
--------------------------------------------------------------------------------
1 | import type { LayerSpecification, LineLayerSpecification } from "maplibre-gl";
2 | import type { CircleLayerSpecification } from "@maplibre/maplibre-gl-style-spec";
3 |
4 | export const colors = {
5 | snapline: "#34343f",
6 | altRouteline: "#9e91be",
7 | routelineFoot: "#3665ff",
8 | routelineBike: "#63c4ff",
9 | routeline: "#7b51f8",
10 | congestionLow: "#42c74c",
11 | congestionHigh: "#d72359",
12 | hoverpoint: "#30a856",
13 | snappoint: "#cb3373",
14 | snappointHighlight: "#e50d3f",
15 | waypointFoot: "#3665ff",
16 | waypointFootHighlight: "#0942ff",
17 | waypointBike: "#63c4ff",
18 | waypointBikeHighlight: "#0bb8ff",
19 | waypoint: "#7b51f8",
20 | waypointHighlight: "#6d26d7",
21 | };
22 |
23 | const routelineColor: NonNullable
114 | {#each waypointsBearings as waypointBearing, i}
115 |
181 |
123 | {i + 1}.
124 |
129 |
179 | {/each}
180 | onImageMousedown(e, i)} role="spinbutton" tabindex="0">
130 |
152 |
153 |
162 | °
163 | ±
164 | {#if configuration.fixedDegrees}
165 | {configuration.fixedDegrees}°
166 | {:else}
167 |
176 | °
177 | {/if}
178 |