From c5379f8a350977784b1119714d2fd3b1f1a78cc6 Mon Sep 17 00:00:00 2001 From: Luke Seelenbinder Date: Wed, 28 Jun 2023 14:07:12 +0200 Subject: [PATCH] Add more substantial README and a basic example. --- README.md | 133 +++++++++++++++++++++++++++++++++++++++++++- examples/basic.html | 33 +++++++++++ index.html | 1 + vite.config.ts | 2 +- 4 files changed, 167 insertions(+), 2 deletions(-) create mode 100644 examples/basic.html diff --git a/README.md b/README.md index d70df8a..acc1704 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,137 @@ # Stadia Maps MapLibre Search Box -TODO +This [MapLibre GL JS](https://maplibre.org/projects/maplibre-gl-js/) plugin adds support for the Stadia Maps Search and +Autocomplete APIs to any MapLibre GL JS map. + +Based on the Stadia Maps TS SDK, it automatically handles best-practice functionality for search, including debouncing of +requests, caching of previous results, and navigating to the chosen result. + +## Getting Started + +Adding the search box to a map is straightforward: + +1. Add the TS/JS and CSS dependencies. +2. Instantiate the control (optionally customize the settings). +3. Add the control to the map. + +### Using Modules + +Install the package. + +```shell +$ npm install --save @stadiamaps/maplibre-search-box +``` + +Import and use the package along with the map. (Be sure to add the control to the map!) + +```typescript +import { MapLibreSearchControl } from "@stadiamaps/maplibre-search-box"; +import "@stadiamaps/maplibre-search-box/dist/style.css"; + +const control = new MapLibreSearchControl(); +const map = new maplibregl.Map({ + container: "map", + style: "https://tiles.stadiamaps.com/styles/alidade_smooth.json", // stylesheet location + center: [-74.5, 40], // starting position [lng, lat] + zoom: 2, // starting zoom +}); +map.addControl(control, "top-left"); +``` + +### Using Unpkg + +Add this to your ``: + +```html + + +``` + +Add this to your ``: + +```html +
+ +``` + +## Options + +The `MapLibreSearchControl` constructor takes a set of options (as an object): + +### Options Overview + +```typescript +class MapLibreSearchControlOptions { + useMapFocusPoint = false; + mapFocusPointMinZoom = 5; + fixedFocusPoint: [number, number] = null; + searchOnEnter = false; + maxResults = 5; + minInputLength = 3; + minWaitPeriodMs = 100; + layers: PeliasLayer[] = null; +} +``` + +### Options Detail + +### `useMapFocusPoint` + +If set, the map center point is used to influence the search for better contextual results. + +### `mapFocusPointMinZoom` + +On low zooms, the focus point is often unuseful for contextual results (e.g., on zoom 0, the whole world is visible, so +the center is not valuable). This controls at what zoom the center is used to influence results. + +### `fixedFocusPoint` + +A single point used to influence results (doesn't follow the map viewport). + +### `searchOnEnter` + +Controls if pressing the Enter key uses the `/search` endpoint instead of the default `/autocomplete` endpoint. + +Note: the `/search` endpoint is not available to all plans, so check if your plan supports `/search` before enabling +this. + +### `maxResults` + +Maximum number of results to return. + +### `minInputLength` + +Minimum number of characters to wait for before making the first search. + +### `minWaitPeriodMs` + +The minimum time to wait between searches. Higher values decrease the number of API requests made, but increase the +received latency of the input. + +### `layers` + +Which layers to use in the search. Defaults to all layers. See +the [Layers documentation](https://docs.stadiamaps.com/geocoding-search-autocomplete/layers/) for more details. + +Note: if you want the fastest possible search, but don't mind excluding addresses or Point of Interest (`venue`) +results, use `['coarse']` for the best performance. ## Development diff --git a/examples/basic.html b/examples/basic.html new file mode 100644 index 0000000..0e6b61e --- /dev/null +++ b/examples/basic.html @@ -0,0 +1,33 @@ + + + + + + Basic MapLibre Search + + + + + + +
+ + + diff --git a/index.html b/index.html index bd868f9..382c01c 100644 --- a/index.html +++ b/index.html @@ -26,6 +26,7 @@ style: "https://tiles.stadiamaps.com/styles/alidade_smooth.json", // stylesheet location center: [-74.5, 40], // starting position [lng, lat] zoom: 2, // starting zoom + hash: "map", }); map.addControl(navControl, "top-left"); map.addControl(control, "top-left"); diff --git a/vite.config.ts b/vite.config.ts index a1c7c76..ea53776 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -9,7 +9,7 @@ module.exports = defineConfig({ minify: "esbuild", lib: { entry: path.resolve(__dirname, "src/index.ts"), - name: "mapLibreSearchBox" + name: "maplibreSearchBox" }, rollupOptions: { // make sure to externalize deps that shouldn't be bundled