@maptiler/geocoding-control 0.0.43 → 0.0.48

package/README.md

@@ -16,24 +16,20 @@ npm install --save @maptiler/geocoding-control maplibre-gl
 
 ```js
 import maplibregl from "maplibre-gl";
-import { GeocodingControl } from "@maptiler/geocoding-control/maplibre";
+import { GeocodingControl } from "@maptiler/geocoding-control/maplibregl";
 import "@maptiler/geocoding-control/dist/style.css";
+import "maplibre-gl/dist/maplibre-gl.css";
 
-const API_KEY = "YOUR_MAPTILER_API_KEY_HERE";
+const apiKey = "YOUR_MAPTILER_API_KEY_HERE";
 
 const map = new maplibregl.Map({
   container: "map", // id of HTML container element
-  style:
-    "https://api.maptiler.com/maps/streets/style.json?key=" +
-    YOUR_MAPTILER_API_KEY_HERE,
+  style: "https://api.maptiler.com/maps/streets/style.json?key=" + apiKey,
   center: [16.3, 49.2],
   zoom: 7,
 });
 
-const gc = new GeocodingControl({
-  apiKey: YOUR_MAPTILER_API_KEY_HERE,
-  maplibregl,
-});
+const gc = new GeocodingControl({ apiKey, maplibregl });
 
 map.addControl(gc);
 ```
@@ -49,13 +45,14 @@ import * as L from "leaflet";
 import { GeocodingControl } from "@maptiler/geocoding-control/leaflet";
 import "@maptiler/geocoding-control/dist/style.css";
 
+const apiKey = "YOUR_MAPTILER_API_KEY_HERE";
+
 const map = L.map(document.getElementById("map")).setView([49.2, 16.3], 6);
 
 const scale = devicePixelRatio > 1.5 ? "@2x" : "";
 
 L.tileLayer(
-  `https://api.maptiler.com/maps/streets/{z}/{x}/{y}${scale}.png?key=` +
-    YOUR_MAPTILER_API_KEY_HERE,
+  `https://api.maptiler.com/maps/streets/{z}/{x}/{y}${scale}.png?key=` + apiKey,
   {
     tileSize: 512,
     zoomOffset: -1,
@@ -67,7 +64,7 @@ L.tileLayer(
   }
 ).addTo(map);
 
-L.control.maptilerGeocoding({ apiKey: YOUR_MAPTILER_API_KEY_HERE }).addTo(map);
+L.control.maptilerGeocoding({ apiKey }).addTo(map);
 ```
 
 For examples without using bundler see `demo-maplibregl.html` or `demo-leaflet.html`. After building this library (`npm install && npm run build`) you can open it in the browser:
@@ -77,7 +74,7 @@ For examples without using bundler see `demo-maplibregl.html` or `demo-leaflet.h
 
 ## API Documentation
 
-Options:
+### Options
 
 - `apiKey`<sup>\*</sup>: `string` - Maptiler API key
 - `maplibregl`: `MapLibreGL` - A Maplibre GL instance to use when creating [Markers](https://maplibre.org/maplibre-gl-js-docs/api/markers/#marker). Required if `options.marker` is `true`. Used only with Maplibre GL library.
@@ -89,7 +86,7 @@ Options:
 - `trackProximity`: `boolean` - If true, the geocoder proximity will automatically update based on the map view. Default `true`.
 - `minLength`: `number` - Minimum number of characters to enter before results are shown. Default `2`.
 - `bbox`: `[number, number, number, number]` - A bounding box argument: this is a bounding box given as an array in the format [minX, minY, maxX, maxY]. Search results will be limited to the bounding box.
-- `language`: `string` - Specify the language to use for response text and query result weighting. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and optionally one or more IETF subtags for country or script. More than one value can also be specified, separated by commas. Set to empty string for forcing no language preference.
+- `language`: `string | string[]` - Specify the language(s) to use for response text and query result weighting. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and optionally one or more IETF subtags for country or script. More than one value can also be specified, separated by commas. Set to empty string for forcing no language preference.
 - `showResultsWhileTyping`: `boolean` - If `false`, indicates that search will only occur on enter key press. If `true`, indicates that the Geocoder will search on the input box being updated above the minLength option. Default `false`.
 - `marker`: `boolean | MarkerOptions` - If `true`, a [MapLibre GL Marker](https://maplibre.org/maplibre-gl-js-docs/api/markers/#marker) / [Leaflet Marker](https://leafletjs.com/reference.html#marker) will be added to the map at the location of the user-selected result using a default set of Marker options. If the value is an object, the marker will be constructed using these options. If `false`, no marker will be added to the map. Requires that `options.maplibregl` also be set. Default `true`.
 - `showResultMarkers`: `boolean | MarkerOptions` - If `true`, [MapLibre GL Marker](https://maplibre.org/maplibre-gl-js-docs/api/markers/#marker) / [Leaflet Marker](https://leafletjs.com/reference.html#marker) will be added to the map at the location the top results for the query. If the value is an object, the marker will be constructed using these options. If `false`, no marker will be added to the map. Requires that `options.maplibregl` also be set. Default `true`.
@@ -104,15 +101,21 @@ Options:
 - `clearButtonTitle`: `string` - Clear button title. Default `"clear"`.
 - `showFullGeometry`: `boolean` - Set to `true` to show full feature geometry of the chosen result. Otherwise only marker will be shown. Default `true`.
 - `fullGeometryStyle`: `{ fill: Pick<FillLayerSpecification, "layout" | "paint" | "filter">; line: Pick<LineLayerSpecification, "layout" | "paint" | "filter">; } | (L.PathOptions | L.StyleFunction)` - style of the full feature geometry. See Mapplibre GL JS or Leaflet documentation.
+- `fuzzyMatch`: `boolean` - Set to `false` to disable fuzzy search. Default `true`.
+- `limit`: `number` - Maximum number of results to show. Default `5`.
+- `country`: `string | string[]` - Limit search to specified country(ies). Default `undefined` (use all countries).
+- `types`: `string[]` - Filter of feature types to return. Default `undefined` (all available feature types are returned).
 
-Methods:
+### Methods
 
 - `setQuery(value: string, submit = true): void` - set the query and optionally submit it
 - `focus(): void` - focus the query input box
 - `blur(): void` - blur the query input box
 - `setReverseMode(value: boolean | "always"): void` - set reverse mode
 
-Events:
+### Events
+
+Events are implemented using [EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) and [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent).
 
 - `select` - Fired on highlighting search result in the dropdown by hovering it or by keyboard selection. Event value will be set to the highlighted `Feature` or to `undefined` if nothing is highlighted.
 - `pick` - Fired on picking the result from the dropdown. Event value will be set to the picked `Feature` or to `undefined` if nothing is picked (eg. search input is cleared).
@@ -123,6 +126,14 @@ Events:
 - `reversetoggle` - Fired if reverse geocoding button is toggled. Event value is `true` if reverse geocoding mode is active, otherwise `false`.
 - `querychange` - Fired if query was changed. Event value is the query string.
 
+Example:
+
+```javascript
+geocodingControl.addEventListener("optionsVisibilityChange", (e) => {
+  console.log("Options visible:", e.detail);
+});
+```
+
 ## Svelte component
 
 In addition to using the component as MapLibre GL Control it is alto possible to use it stand-alone in Svelte projects.