@maptiler/geocoding-control 2.0.0 → 2.1.0-rc1

package/svelte/types.d.ts

@@ -33,7 +33,7 @@ export type MapController = {
     flyTo(center: Position, zoom?: number): void;
     fitBounds(bbox: BBox, padding: number, maxZoom?: number): void;
     indicateReverse(reverse: boolean): void;
-    setMarkers(features: Feature[] | undefined, picked: Feature | undefined): void;
+    setFeatures(features: Feature[] | undefined, picked: Feature | undefined, showPolygonMarker: boolean): void;
     setReverseMarker(coordinates?: Position): void;
     setSelectedMarker(index: number): void;
     getCenterAndZoom(): [zoom: number, lon: number, lat: number] | undefined;
@@ -68,43 +68,51 @@ export type ControlOptions = {
     /**
      * Sets the amount of time, in milliseconds, to wait before querying the server when a user types into the Geocoder input box.
      * This parameter may be useful for reducing the total number of API calls made for a single query.
+     *
      * Default value is `200`.
      */
     debounceSearch?: number;
     /**
      * Search results closer to the proximity point will be given higher priority. First matching rule from the array will be used.
      * Set to `null` to disable the proximity.
+     *
      * Default value is `[{ type: "server-geolocation" }]`.
      */
     proximity?: ProximityRule[] | null;
     /**
      * Override the default placeholder attribute value.
+     *
      * Default value is `"Search"`.
      */
     placeholder?: string;
     /**
      * Override the default error message.
+     *
      * Default value is `"Something went wrong…"`.
      */
     errorMessage?: string;
     /**
      * Override the default message if no results are found.
+     *
      * Default value is `"Oops! Looks like you're trying to predict something that's not quite right. We can't seem to find what you're looking for. Maybe try double-checking your spelling or try a different search term. Keep on typing - we'll do our best to get you where you need to go!"`.
      */
     noResultsMessage?: string;
     /**
      * Minimum number of characters to enter before results are shown.
+     *
      * Default value is `2`.
      */
     minLength?: 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.
+     *
      * Default value is `undefined`.
      */
     bbox?: BBox;
     /**
      * Maximum number of results to show.
+     *
      * Default value is `5`.
      */
     limit?: number;
@@ -113,131 +121,169 @@ export type ControlOptions = {
      * 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 `null` or empty string for disabling language-specific searching.
-     * Defaults to the browser's language settings.
-     * Default value is `undefined`.
+     *
+     * Default value is `undefined` which means to use the browser's language settings.
      */
     language?: string | string[] | null;
     /**
      * 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 value is `false`.
      */
     showResultsWhileTyping?: boolean;
     /**
      * Set to `false` to disable fuzzy search.
-     * Default value is `true`
+     *
+     * Default value is `true`.
      */
     fuzzyMatch?: boolean;
     /**
      * On geocoded result what zoom level should the map animate to when a bbox in the response isn't present or is a point.
      * If a bbox is present and not a point then the map will fit to the bbox.
      *
-     * Value can be a number (deprecated) or key-value pairs, where key is a <type> or <type>.<categoy> and value is the zoom level.
+     * Value is key-value pairs, where key is a <type> or <type>.<categoy> and the value is the zoom level.
      *
      * Default value is `GeocodingControl.ZOOM_DEFAULTS`.
      */
-    zoom?: number | Record<string, number>;
+    zoom?: Record<string, number>;
     /**
-     * On geocoded result what max zoom level should the map animate to when a bbox in the response isn't present or is a point.
-     * Used for small features.
+     * If `true`, the geocoder control will collapse until hovered or in focus.
      *
-     * If a bbox is present and not a point then the map will fit to the bbox.
+     * Default value is `false`.
+     */
+    collapsed?: boolean;
+    /**
+     * If `true`, the geocoder control will clear its value when the input blurs.
      *
-     * @deprecated use `zoom` option
+     * Default value is `false`.
      */
-    maxZoom?: number;
+    clearOnBlur?: boolean;
     /**
-     * If `true`, the geocoder control will collapse until hovered or in focus.
+     * If `true`, then after picking a result from the list or map the list will be cleared and not re-displayed on input box focus.
+     *
      * Default value is `false`.
      */
-    collapsed?: boolean;
+    clearListOnPick?: boolean;
     /**
-     * If true, the geocoder control will clear its value when the input blurs.
+     * Keep the list open even if the control is not focused.
+     *
      * Default value is `false`.
      */
-    clearOnBlur?: boolean;
+    keepListOpen?: boolean;
     /**
      * A function which accepts a Feature in the Carmen GeoJSON format to filter out results from the Geocoding API response before they are included in the suggestions list.
      * Return true to keep the item, false otherwise.
+     *
+     * Default value is a function returning always `true`.
      */
     filter?: (feature: Feature) => boolean;
     /**
      * Class of the root element.
+     *
      * Default value is `undefined`.
      */
     class?: string;
     /**
-     * Set to `true` to enable reverse geocoding button with title. Set to `"always"` to reverse geocoding be always active.
-     * Default value is `false`
+     * Set to `button` to enable reverse geocoding button with title. Set to `"always"` to reverse geocoding be always active.
+     *
+     * Default value is `"never"`.
      */
-    enableReverse?: boolean | "always";
+    enableReverse?: EnableReverse;
     /**
-     * Toggle reverse mode.
+     * Reverse mode active.
+     *
      * Default value is `false`.
      */
     reverseActive?: boolean;
     /**
-     * Reverse toggle button title.
+     * Title of the reverse toggle button.
+     *
      * Default value is `"toggle reverse geocoding"`.
      */
     reverseButtonTitle?: string;
     /**
-     * Clear button title.
+     * Title of the clear button.
+     *
      * Default value is `"clear"`.
      */
     clearButtonTitle?: string;
     /**
-     * Set to `false` to hide place/POI type. If set to `"always"` then type is shown for all items.
-     * If set to `"ifNeeded"` then type is shown only for places/POIs not determined from the icon.
-     * Default value is `"ifNeeded"`.
+     * Set to `"never"` to hide place/POI type. If set to `"always"` then type is shown for all items.
+     * If set to `"if-needed"` then type is shown only for places/POIs not determined from the icon.
+     *
+     * Default value is `"if-needed"`.
      */
-    showPlaceType?: false | "always" | "ifNeeded";
+    showPlaceType?: ShowPlaceType;
     /**
-     * Set to `true` to show full feature geometry of the chosen result. Otherwise only marker will be shown.
+     * Style of the picked result on the map:
+     *
+     * - `"marker-only"` - show only marker at the center of the feature
+     * - `"full-geometry"` - show full feature geometry of the chosen result
+     * - `"full-geometry-including-polygon-center-marker"` - show full feature geometry of the chosen result together with a marker in the center of polygon feature
+     *
      * Default value is `true`.
      */
-    showFullGeometry?: boolean;
+    pickedResultStyle?: PickedResultStyle;
     /**
      * Limit search to specified country(ies).
+     *
      * Default value is `undefined` - use all countries.
      */
     country?: string | string[];
     /**
      * Filter of feature types to return.
+     *
      * Default value is `undefined` - all available feature types are returned.
      */
     types?: string[];
     /**
      * Use `limit` value for reverse geocoding even if `types` is not an array with a single element.
      * Will work only if enabled on the server.
+     *
      * Default value is `false`.
      */
     exhaustiveReverseGeocoding?: boolean;
     /**
      * If set to `true` then use all types except for those listed in `types`.
+     *
      * Default value is `false`.
      */
     excludeTypes?: boolean;
     /**
      * Geocoding API URL.
+     *
      * Default value is MapTiler Geocoding API URL.
      */
     apiUrl?: string;
     /**
      * Extra fetch parameters.
+     *
      * Default value is `undefined`.
      */
     fetchParameters?: RequestInit;
     /**
      * Base URL for POI icons.
+     *
      * Default value is `"icons/"` for Svelte apps, otherwise `"https://cdn.maptiler.com/maptiler-geocoding-control/v${version}/icons/"`.
      */
     iconsBaseUrl?: string;
     /**
      * Function to adjust URL search parameters.
+     *
      * Default value is empty function.
+     *
+     * @deprecated use `adjustUrl`
      */
     adjustUrlQuery?: (sp: URLSearchParams) => void;
+    /**
+     * Function to adjust geocoding URL before the fetch.
+     *
+     * @param url [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) parameter which can be modified
+     *
+     * Default value is empty function.
+     */
+    adjustUrl?: (url: URL) => void;
     /**
      * Automatically select the first feature from the result list.
      *
@@ -257,16 +303,41 @@ export type ControlOptions = {
      */
     markerOnSelected?: boolean;
 };
-export type DispatcherType = {
-    featuresListed: Feature[] | undefined;
-    featuresMarked: Feature[] | undefined;
-    optionsVisibilityChange: boolean;
-    pick: Feature | undefined;
-    queryChange: string;
+export type PickedResultStyle = "marker-only" | "full-geometry" | "full-geometry-including-polygon-center-marker";
+export type EnableReverse = "never" | "always" | "button";
+export type ShowPlaceType = "never" | "always" | "if-needed";
+export type DispatcherTypeCC = {
+    featuresListed: {
+        features: Feature[] | undefined;
+    };
+    featuresMarked: {
+        features: Feature[] | undefined;
+    };
+    optionsVisibilityChange: {
+        optionsVisible: boolean;
+    };
+    pick: {
+        feature: Feature | undefined;
+    };
+    queryChange: {
+        query: string;
+    };
     response: {
         url: string;
         featureCollection: FeatureCollection;
     };
-    reverseToggle: boolean;
-    select: Feature | undefined;
+    reverseToggle: {
+        reverse: boolean;
+    };
+    select: {
+        feature: Feature | undefined;
+    };
+};
+export type DispatcherType = {
+    [T in keyof DispatcherTypeCC as Lowercase<T>]: DispatcherTypeCC[T];
 };
+export type RedefineType<OriginalType, UpdatedType extends {
+    [K in keyof OriginalType]: OriginalType[K];
+} & {
+    [K in Exclude<keyof UpdatedType, keyof OriginalType>]: never;
+}> = UpdatedType;

package/svelte/vanilla.d.ts

@@ -1,17 +1,61 @@
-import type { ControlOptions, MapController } from "./types";
+import type { ControlOptions, DispatcherType, MapController } from "./types";
 type Options = ControlOptions & {
     mapController?: MapController;
 };
+interface GeocodingControlEvent<T> extends CustomEvent<T> {
+    readonly target: GeocodingControl;
+    readonly currentTarget: GeocodingControl;
+}
+type CustomEventListenerOrEventListenerObject<K extends keyof CustomEventMap> = ((evt: CustomEventMap[K]) => void) | {
+    handleEvent(object: CustomEventMap[K]): void;
+};
+type CustomEventMap = {
+    [T in keyof DispatcherType]: GeocodingControlEvent<DispatcherType[T]>;
+};
 export declare class GeocodingControl extends EventTarget {
     #private;
     constructor({ target, ...options }: Options & {
         target: HTMLElement;
     });
+    /**
+     * Update the control options.
+     *
+     * @param options options to update
+     */
     setOptions(options: Partial<Options>): void;
+    /**
+     * Set the content of search input box.
+     *
+     * @param value text to set
+     * @param submit perform the search
+     */
     setQuery(value: string, submit?: boolean): void;
+    /**
+     * Clear geocoding search results from the map.
+     */
     clearMap(): void;
+    /**
+     * Clear search result list.
+     */
     clearList(): void;
-    focus(): void;
+    /**
+     * Set reverse geocoding mode.
+     *
+     * @param reverseActive reverse geocoding active
+     */
+    setReverseMode(reverseActive: boolean): void;
+    /**
+     * Focus the search input box.
+     *
+     * @param options [FocusOptions](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+     */
+    focus(options?: FocusOptions): void;
+    /**
+     * Blur the search input box.
+     */
     blur(): void;
+    addEventListener<K extends keyof CustomEventMap>(type: K, callback: CustomEventListenerOrEventListenerObject<K> | null, options?: AddEventListenerOptions | boolean): void;
+    removeEventListener<K extends keyof CustomEventMap>(type: K, callback: CustomEventListenerOrEventListenerObject<K> | null, options?: EventListenerOptions | boolean): void;
+    dispatchEvent<K extends keyof CustomEventMap>(event: CustomEventMap[K]): boolean;
 }
 export {};

package/svelte/vanilla.js

@@ -1,4 +1,4 @@
-import GC from "./GeocodingControl.svelte";
+import GeocodingControlComponent from "./GeocodingControl.svelte";
 const finalizationRegistry = new FinalizationRegistry((gc) => {
     gc.$destroy();
 });
@@ -6,40 +6,96 @@ export class GeocodingControl extends EventTarget {
     #gc;
     constructor({ target, ...options }) {
         super();
-        this.#gc = new GC({
+        this.#gc = new GeocodingControlComponent({
             target,
             props: options,
         });
         for (const eventName of [
             "select",
             "pick",
-            "featuresListed",
-            "featuresMarked",
+            "featureslisted",
+            "featuresmarked",
             "response",
-            "optionsVisibilityChange",
-            "reverseToggle",
-            "queryChange",
+            "optionsvisibilitychange",
+            "reversetoggle",
+            "querychange",
         ]) {
-            this.#gc.$on(eventName, (event) => this.dispatchEvent(event));
+            this.#gc.$on(eventName, (event) => {
+                // Use the new `emit` method for type-safe dispatching
+                this.#emit(eventName, event.detail);
+            });
         }
+        this.#gc.$on("select", (event) => {
+            const geocodingEvent = new CustomEvent(event.type, {
+                detail: event.detail,
+            });
+            this.dispatchEvent(geocodingEvent);
+        });
         finalizationRegistry.register(this, this.#gc);
     }
+    /**
+     * Update the control options.
+     *
+     * @param options options to update
+     */
     setOptions(options) {
         this.#gc.$set(options);
     }
+    /**
+     * Set the content of search input box.
+     *
+     * @param value text to set
+     * @param submit perform the search
+     */
     setQuery(value, submit = true) {
         this.#gc?.setQuery(value, submit);
     }
+    /**
+     * Clear geocoding search results from the map.
+     */
     clearMap() {
         this.#gc?.clearMap();
     }
+    /**
+     * Clear search result list.
+     */
     clearList() {
         this.#gc?.clearList();
     }
-    focus() {
-        this.#gc?.focus();
+    /**
+     * Set reverse geocoding mode.
+     *
+     * @param reverseActive reverse geocoding active
+     */
+    setReverseMode(reverseActive) {
+        this.#gc?.$set({ reverseActive });
+    }
+    /**
+     * Focus the search input box.
+     *
+     * @param options [FocusOptions](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+     */
+    focus(options) {
+        this.#gc?.focus(options);
     }
+    /**
+     * Blur the search input box.
+     */
     blur() {
         this.#gc?.blur();
     }
+    addEventListener(type, callback, options) {
+        super.addEventListener(type, callback, options);
+    }
+    removeEventListener(type, callback, options) {
+        super.removeEventListener(type, callback, options);
+    }
+    dispatchEvent(event) {
+        return super.dispatchEvent(event);
+    }
+    #emit(type, detail) {
+        return super.dispatchEvent(new CustomEvent(type, {
+            detail,
+        }));
+    }
 }