@maptiler/geocoding-control 2.1.0-rc1 → 2.1.1

package/svelte/types.d.ts

@@ -62,246 +62,289 @@ export type ProximityRule = {
 } & PositionOptions));
 export type ControlOptions = {
     /**
-     * Maptiler API key
+     * Callback function to adjust URL search parameters.
+     *
+     * Default: Empty function.
+     *
+     * @deprecated Use `adjustUrl` instead.
      */
-    apiKey: string;
+    adjustUrlQuery?: (sp: URLSearchParams) => void;
     /**
-     * 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.
+     * Callback function to adjust the geocoding URL before fetching.
+     *
+     * @param url [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) parameter that can be modified.
      *
-     * Default value is `200`.
+     * Default: Empty function.
      */
-    debounceSearch?: number;
+    adjustUrl?: (url: URL) => void;
     /**
-     * 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" }]`.
+     * MapTiler API key.
      */
-    proximity?: ProximityRule[] | null;
+    apiKey: string;
     /**
-     * Override the default placeholder attribute value.
+     * Geocoding API URL.
      *
-     * Default value is `"Search"`.
+     * Default: MapTiler Geocoding API URL.
      */
-    placeholder?: string;
+    apiUrl?: string;
     /**
-     * Override the default error message.
+     * Bounding box in the format `[minX, minY, maxX, maxY]` to limit search results.
      *
-     * Default value is `"Something went wrong…"`.
+     * Default: `undefined`.
      */
-    errorMessage?: string;
+    bbox?: BBox;
     /**
-     * Override the default message if no results are found.
+     * CSS class for the root element.
      *
-     * 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!"`.
+     * Default: `undefined`.
      */
-    noResultsMessage?: string;
+    class?: string;
     /**
-     * Minimum number of characters to enter before results are shown.
+     * Title of the clear button.
      *
-     * Default value is `2`.
+     * Default: `"clear"`.
      */
-    minLength?: number;
+    clearButtonTitle?: string;
     /**
-     * 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.
+     * Clears the result list after picking an item.
+     * Prevents redisplaying the list when the input box is focused.
      *
-     * Default value is `undefined`.
+     * Default: `false`.
      */
-    bbox?: BBox;
+    clearListOnPick?: boolean;
     /**
-     * Maximum number of results to show.
+     * Clears the input value when it loses focus.
      *
-     * Default value is `5`.
+     * Default: `false`.
      */
-    limit?: number;
+    clearOnBlur?: boolean;
     /**
-     * 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 `null` or empty string for disabling language-specific searching.
+     * Collapses the geocoder control until hovered or focused.
      *
-     * Default value is `undefined` which means to use the browser's language settings.
+     * Default: `false`.
      */
-    language?: string | string[] | null;
+    collapsed?: 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.
+     * Limits search to the specified country or countries.
      *
-     * Default value is `false`.
+     * Default: `undefined` (all countries).
      */
-    showResultsWhileTyping?: boolean;
+    country?: string | string[];
     /**
-     * Set to `false` to disable fuzzy search.
+     * Time delay (in milliseconds) before querying the server after typing in the input box.
+     * Useful for reducing the number of API calls.
      *
-     * Default value is `true`.
+     * Default: `200`.
      */
-    fuzzyMatch?: boolean;
+    debounceSearch?: number;
     /**
-     * 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.
+     * Enables reverse geocoding:
+     * - `"button"`: Enables reverse geocoding button.
+     * - `"always"`: Reverse geocoding is always active.
      *
-     * 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`.
+     * Default: `"never"`.
      */
-    zoom?: Record<string, number>;
+    enableReverse?: EnableReverse;
     /**
-     * If `true`, the geocoder control will collapse until hovered or in focus.
+     * Custom error message.
      *
-     * Default value is `false`.
+     * Default: `"Something went wrong…"`.
      */
-    collapsed?: boolean;
+    errorMessage?: string;
     /**
-     * If `true`, the geocoder control will clear its value when the input blurs.
+     * Includes all available types except those listed in the `types` option.
+     *
+     * See `reverseGeocodingExcludeTypes` for reverse geocoding exclusion.
      *
-     * Default value is `false`.
+     * Default: `false`.
      */
-    clearOnBlur?: boolean;
+    excludeTypes?: boolean;
     /**
-     * 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.
+     * Uses the `limit` option value for reverse geocoding even if the `types` option has multiple elements.
+     * Works only if enabled on the server.
      *
-     * Default value is `false`.
+     * Default: `false`.
      */
-    clearListOnPick?: boolean;
+    exhaustiveReverseGeocoding?: boolean;
     /**
-     * Keep the list open even if the control is not focused.
+     * Additional parameters for fetch requests.
      *
-     * Default value is `false`.
+     * Default: `undefined`.
      */
-    keepListOpen?: boolean;
+    fetchParameters?: RequestInit;
     /**
-     * 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.
+     * Callback function to filter results from the Geocoding API response.
+     * The function should return `true` to keep an item, or `false` to exclude it.
      *
-     * Default value is a function returning always `true`.
+     * Default: A function that always returns `true`.
      */
     filter?: (feature: Feature) => boolean;
     /**
-     * Class of the root element.
+     * Animates the map to the selected feature from the result list.
      *
-     * Default value is `undefined`.
+     * Default: `false`.
      */
-    class?: string;
+    flyToSelected?: boolean;
     /**
-     * Set to `button` to enable reverse geocoding button with title. Set to `"always"` to reverse geocoding be always active.
+     * Enables fuzzy search.
      *
-     * Default value is `"never"`.
+     * Default: `true`.
      */
-    enableReverse?: EnableReverse;
+    fuzzyMatch?: boolean;
     /**
-     * Reverse mode active.
+     * Base URL for POI icons.
      *
-     * Default value is `false`.
+     * Default:
+     * - `"icons/"` for Svelte apps.
+     * - `"https://cdn.maptiler.com/maptiler-geocoding-control/v${version}/icons/"` for others.
      */
-    reverseActive?: boolean;
+    iconsBaseUrl?: string;
     /**
-     * Title of the reverse toggle button.
+     * Keeps the result list open even if the control is unfocused.
      *
-     * Default value is `"toggle reverse geocoding"`.
+     * Default: `false`.
      */
-    reverseButtonTitle?: string;
+    keepListOpen?: boolean;
     /**
-     * Title of the clear button.
+     * Language for response text and query weighting.
+     * Accepts IETF language tags.
+     * Set to `null` or an empty string to disable language-specific searching.
      *
-     * Default value is `"clear"`.
+     * Default: `undefined` (uses the browser's language settings).
      */
-    clearButtonTitle?: string;
+    language?: string | string[] | null;
     /**
-     * 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.
+     * Maximum number of results to display.
+     *
+     * See `reverseGeocodingLimit` for reverse geocoding limits.
      *
-     * Default value is `"if-needed"`.
+     * Default: `5`.
      */
-    showPlaceType?: ShowPlaceType;
+    limit?: number;
     /**
-     * Style of the picked result on the map:
+     * Displays a marker on the selected feature from the result list.
      *
-     * - `"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: `true`.
+     */
+    markerOnSelected?: boolean;
+    /**
+     * Minimum number of characters required to start a search.
      *
-     * Default value is `true`.
+     * Default: `2`.
      */
-    pickedResultStyle?: PickedResultStyle;
+    minLength?: number;
     /**
-     * Limit search to specified country(ies).
+     * Custom message for when no results are found.
      *
-     * Default value is `undefined` - use all countries.
+     * Default:
+     * ```
+     * "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!"
+     * ```
      */
-    country?: string | string[];
+    noResultsMessage?: string;
     /**
-     * Filter of feature types to return.
+     * Style of the picked result on the map:
+     * - `"marker-only"`: Show only a marker at the center of the feature.
+     * - `"full-geometry"`: Display the full feature geometry.
+     * - `"full-geometry-including-polygon-center-marker"`: Display full geometry with a marker at the polygon center.
      *
-     * Default value is `undefined` - all available feature types are returned.
+     * Default: `"full-geometry"`.
      */
-    types?: string[];
+    pickedResultStyle?: PickedResultStyle;
     /**
-     * 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.
+     * Custom placeholder for the input box.
      *
-     * Default value is `false`.
+     * Default: `"Search"`.
      */
-    exhaustiveReverseGeocoding?: boolean;
+    placeholder?: string;
     /**
-     * If set to `true` then use all types except for those listed in `types`.
+     * Prioritizes search results closer to a proximity point.
+     * The first matching rule in the array is used.
+     * Set to `null` to disable proximity.
      *
-     * Default value is `false`.
+     * Default: `[ { type: "server-geolocation" } ]`.
      */
-    excludeTypes?: boolean;
+    proximity?: ProximityRule[] | null;
     /**
-     * Geocoding API URL.
+     * Activates reverse geocoding.
      *
-     * Default value is MapTiler Geocoding API URL.
+     * Default: `false`.
      */
-    apiUrl?: string;
+    reverseActive?: boolean;
     /**
-     * Extra fetch parameters.
+     * Title of the reverse geocoding toggle button.
      *
-     * Default value is `undefined`.
+     * Default: `"toggle reverse geocoding"`.
      */
-    fetchParameters?: RequestInit;
+    reverseButtonTitle?: string;
     /**
-     * Base URL for POI icons.
+     * Excludes types for reverse geocoding.
      *
-     * Default value is `"icons/"` for Svelte apps, otherwise `"https://cdn.maptiler.com/maptiler-geocoding-control/v${version}/icons/"`.
+     * Default: Same as `excludeTypes`.
      */
-    iconsBaseUrl?: string;
+    reverseGeocodingExcludeTypes?: boolean;
     /**
-     * Function to adjust URL search parameters.
+     * Limits results for reverse geocoding.
+     * Applied only if value is 1 or effective types contain a single value.
      *
-     * Default value is empty function.
+     * See also `reverseGeocodingTypes` option.
      *
-     * @deprecated use `adjustUrl`
+     * Default: The value of the `limit` option if set. If effective types contain a single value, the default is `1`. In all other cases, this option is not used.
      */
-    adjustUrlQuery?: (sp: URLSearchParams) => void;
+    reverseGeocodingLimit?: number;
     /**
-     * Function to adjust geocoding URL before the fetch.
+     * Specifies types for reverse geocoding.
+     *
+     * If effective types are multiple values, the `limit`/`reverseGeocodingLimit` option is ignored.
      *
-     * @param url [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) parameter which can be modified
+     * See also `reverseGeocodingLimit` option.
      *
-     * Default value is empty function.
+     * Default: Same as `types`.
      */
-    adjustUrl?: (url: URL) => void;
+    reverseGeocodingTypes?: TypeRule[];
     /**
-     * Automatically select the first feature from the result list.
+     * Automatically selects the first feature in the result list.
      *
-     * Default value is `true`.
+     * Default: `true`.
      */
     selectFirst?: boolean;
     /**
-     * Fly to selected feature from the result list.
+     * Indicates when to show place/POI types in the dropdown:
+     * - `"never"`: Hide the type.
+     * - `"always"`: Always show the type.
+     * - `"if-needed"`: Show the type only if it cannot be determined from the icon.
      *
-     * Default value is `false`.
+     * Default: `"if-needed"`.
      */
-    flyToSelected?: boolean;
+    showPlaceType?: ShowPlaceType;
     /**
-     * Show marker on the selected feature from the result list.
+     * Displays results while typing:
+     * - `false`: Search occurs only on pressing the Enter key.
+     * - `true`: Search begins when the input meets the `minLength` requirement.
      *
-     * Default value is `true`.
+     * Default: `false`.
      */
-    markerOnSelected?: boolean;
+    showResultsWhileTyping?: boolean;
+    /**
+     * Types to query, either as an array or `[minZoom, maxZoom, type]` format.
+     * `minZoom` is inclusive, `maxZoom` is exclusive, and either can be `null` or `undefined` for unbounded values.
+     *
+     * See `reverseGeocodingTypes` option for reverse geocoding types.
+     *
+     * Default: `undefined` (uses server default feature types).
+     */
+    types?: TypeRule[];
+    /**
+     * Specifies the zoom level to animate the map to for a geocoded result when no bounding box is present or when the result is a point.
+     * If a bounding box is present and not a point, the map will fit to the bounding box.
+     *
+     * Values are key-value pairs where the key is a `<type>` or `<type>.<category>` and the value is the zoom level.
+     *
+     * Default: `GeocodingControl.ZOOM_DEFAULTS`.
+     */
+    zoom?: Record<string, number>;
 };
 export type PickedResultStyle = "marker-only" | "full-geometry" | "full-geometry-including-polygon-center-marker";
 export type EnableReverse = "never" | "always" | "button";
@@ -341,3 +384,8 @@ export type RedefineType<OriginalType, UpdatedType extends {
 } & {
     [K in Exclude<keyof UpdatedType, keyof OriginalType>]: never;
 }> = UpdatedType;
+export type TypeRule = string | [
+    minZoom: number | null | undefined,
+    maxZoom: number | null | undefined,
+    type: string
+];