From c442797dff0d7963c2a497814479b21a441e3d77 Mon Sep 17 00:00:00 2001 From: Joxit Date: Thu, 26 Dec 2024 19:29:24 +0100 Subject: [PATCH] feat: add `MapPlaceOptions` and improve overall wording --- src/places-js.d.ts | 280 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 212 insertions(+), 68 deletions(-) diff --git a/src/places-js.d.ts b/src/places-js.d.ts index 2dc8f78..df022a2 100644 --- a/src/places-js.d.ts +++ b/src/places-js.d.ts @@ -7,11 +7,11 @@ import L = require('leaflet'); declare class AbstractPlaces { constructor(options: JawgPlaces.JawgPlacesOptions); /** - * Search a random text or lat/lon using Jawg Places. + * Search a random text, lat/lon or GID using Jawg Places. * * All features are points with properties, more details on our [documentation](https://www.jawg.io/docs/apidocs/places/response). * - * See {@link JawgPlacesOptions.reverse} for lat/lon search. + * See {@link JawgPlacesOptions.reverse} for lat/lon search and {@link JawgPlacesOptions.place} for GID search. * * @param text The text to search using Jawg Places * @returns A promise with the feature collection received from Jawg Places @@ -36,7 +36,7 @@ declare class AbstractPlaces { showError(error: any): void; /** * Open the result list with elements from the FeatureCollection. We use the `properties.label` field of each features. - * This will trigger {@link JawgPlacesOptions.onFeatures}. + * This will trigger {@link JawgPlacesOptions.onFeatures} callback. * @param results Feature Collection of geocoded points. */ showResults(results: JawgPlaces.FeatureCollection): void; @@ -52,7 +52,7 @@ declare class AbstractPlaces { } /** - * Welcome to Jawg Places type documentation. + * Welcome to Jawg Places JS type documentation. You will find the complete API of our library to help you with your developments. * Checkout our examples on our [documentation website](https://www.jawg.io/docs/integration/places-js/) and the source code on [GitHub](https://github.com/jawg/places-js-examples). */ declare namespace JawgPlaces { @@ -71,38 +71,51 @@ declare namespace JawgPlaces { } /** - * Option to activate reverse geocoding within the input. + * Option to activate Reverse Geocoding detection within the input. * You can paste coordinates in the form {lat}/{lon} in the input. * The separation can be either `/` (slash), `,` (comma) or ` ` (space). + * * ```javascript - * new JawgPlaces({ - * reverse: { - * enabled: true, - * radius: 50 - * } - * }) + * const reverse = { + * enabled: true, + * radius: 5, + * } * ``` */ interface ReverseOptions { /** - * Enable reverse geocoding in input. + * Enable reverse geocoding enpoint. */ enabled: boolean; /** - * Radius over the point in meters. + * Radius over the point in meters. The maximum value is 5. */ radius?: number; } + /** + * Option to set a circle to constrain forward geocoding results to a specific circular geographic area. + * + * ```javascript + * const circle = { lat: 46.842269, lon: 2.39985, radius: 500 } + * ``` + */ interface CircleOptions extends LatLon { /** - * Radius over the point in meters. + * Radius over the point in kilometers. */ - radius: number; + radius?: number; } /** - * Options to search within a rectangular region. + * Option to set a rectangle to constrain forward geocoding results to a specific rectangular geographic area. + * + * ```javascript + * const rectangle = { + * min: { lat: 43.032582, lon: 5.097656 }, + * max: { lat: 49.006466, lon: 26.762695 }, + * } + * ``` */ interface RectangleOptions { /** @@ -116,59 +129,77 @@ declare namespace JawgPlaces { } /** - * Set of options when you are looking for places in a particular region. + * Set of options to restrict your forward geocoding to specific regions. + * It will filter out all locations outside of the configured boundaries. + * * ```javascript - * new JawgPlaces({ - * boundaries: { - * countries: 'fra', - * point: { lat: 0, lon: 0 }, - * gids: ['whosonfirst:locality:101751119'] - * } - * }) + * const boundary = { + * countries: 'fra', + * circle: { lat: 46.842269, lon: 2.39985, radius: 500 }, + * rectangle: { + * min: { lat: 43.032582, lon: 5.097656 }, + * max: { lat: 49.006466, lon: 26.762695 }, + * }, + * gids: ['openstreetmap:island:relation/966358'] + * } * ``` */ interface BoudaryOptions { /** - * Add a restriction by alpha-2 or alpha-3 ISO-3166 country code. Countries can be static or dynamic with the function. + * Option to set alpha-2 or alpha-3 [ISO-3166](https://en.wikipedia.org/wiki/ISO_3166) country codes to constrain forward geocoding results to specific countries. + * + * @remarks Countries can be static or dynamic through a function. */ countries?: string[] | string | (() => string[]) | (() => string); /** - * Search within a circular region. Circle can be static or dynamic with the function. + * @inheritdoc CircleOptions + * + * @remarks The circle can be static or dynamic through a function. */ circle?: CircleOptions | (() => CircleOptions); /** - * Add a restriction by GIDs. GIDs can be static or dynamic with the function. + * Option to set GIDs to constrain forward geocoding results to specific regions (States, Cities...) using our identifiers. + * + * @remarks GIDs can be static or dynamic with the function. */ gids?: string[] | string | (() => string[]) | (() => string); /** - * Search within a rectangular region. Rectangle can be static or dynamic with the function. + * @inheritdoc RectangleOptions + * + * @remarks The rectangle can be static or dynamic through a function. */ rectangle?: RectangleOptions | (() => RectangleOptions); } /** - * Set of options when you want to prioritize places from particular region. + * Set of options to prioritize your forward geocoding to specific regions. + * All locations in these regions will have a better ranking. + * * ```javascript - * new JawgPlaces({ - * focus: { - * countries: 'fra', - * point: { lat: 0, lon: 0 }, - * gids: ['whosonfirst:locality:101751119'] - * } - * }) + * const focus = { + * countries: 'fra', + * point: { lat: 46.842269, lon: 2.39985 }, + * gids: ['openstreetmap:island:relation/966358'] + * } * ``` */ interface FocusOptions { /** - * Add a priorities by alpha-2 or alpha-3 ISO-3166 country code. Countries can be static or dynamic with the function. + * Option to set alpha-2 or alpha-3 [ISO-3166](https://en.wikipedia.org/wiki/ISO_3166) country codes to prioritize forward geocoding results to specific countries. All locations in these countries will have a better ranking. + * + * @remarks Countries can be static or dynamic through a function. */ countries?: string[] | string | (() => string[]) | (() => string); /** * Sort results in part by their proximity to the given coordinate. Coordinates can be static or dynamic with the function. + * + * @remarks Point can be static or dynamic through a function. The radius is 50km and cannot be changed. */ point?: LatLon | (() => LatLon); /** - * Add a priorities by Jawg GIDs. GIDs can be static or dynamic with the function. + * Option to set GIDs to prioritize forward geocoding results to specific regions (States, Cities...) using our identifiers. All locations connected to these GIDs will have a better ranking. + * + * @remarks GIDs can be static or dynamic through a function. */ gids?: string[] | string | (() => string[]) | (() => string); } @@ -176,24 +207,26 @@ declare namespace JawgPlaces { type GeometriesOptions = 'point' | 'source'; /** - * Option to activate Place Details within the input. + * Option to activate Place Details detection within the input. * You can paste one or many GIDs in the input. + * The separation can be either `,` (comma) or ` ` (space). + * * ```javascript - * new JawgPlaces({ - * place: { - * enabled: true, - * geometries: 'source' - * } - * }) + * const place = { + * enabled: true, + * geometries: 'source' + * } * ``` */ interface PlaceOptions { /** - * Activate the place endpoint. + * Enable place details endpoint. */ enabled: boolean; /** * Set the type of return from Places Details API, either a point or the source geometry. + * + * @remarks geometries can be static or dynamic through a function. */ geometries?: GeometriesOptions | (() => GeometriesOptions); } @@ -201,11 +234,13 @@ declare namespace JawgPlaces { /** * Type of geometries used by Jawg Places API. */ - type Feature = GeoJSON.Feature; + type Feature = GeoJSON.Feature; + /** * Return type of Jawg Places API. */ - type FeatureCollection = GeoJSON.FeatureCollection; + type FeatureCollection = GeoJSON.FeatureCollection; + /** * All available layers. */ @@ -242,23 +277,24 @@ declare namespace JawgPlaces { | string; /** - * Basic options for Places JS. + * Options to configure a Places JS instance. + * * ```javascript - * new JawgPlaces({ + * const options = { * accessToken: '', - * input: '#my-input' - * }) + * input: '#my-input', + * } * ``` */ interface JawgPlacesOptions { /** * Your personal access token, create your own on the [Jawg Lab](https://www.jawg.io/lab). - * This is filled automatically when you get the library with our CDN. + * This is filled automatically when you get the library with our CDN or [@jawg/js-loader](https://www.npmjs.com/package/@jawg/js-loader). */ accessToken?: string; /** * The `` to transform into a geocoding search bar. - * This can be either a id (e.g `#my-input`), class selector (e.g `.my-input`) or the [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement). + * This can be either an id (e.g `#my-input`), class selector (e.g `.my-input`) or the [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement). * With some frameworks/UI libs such as React, you can't use the ref here. */ input?: string | HTMLElement; @@ -271,7 +307,8 @@ declare namespace JawgPlaces { /** * Return results in a specific language using [BCP47 standard](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) (e.g 'en', 'fr', 'de', ...). * By default, we use HTTP Header set by the browser and English when not present. - * Language can be static or dynamic with the function. + * + * @remarks Language can be static or dynamic through a function. */ language?: string | (() => string); /** @@ -283,26 +320,35 @@ declare namespace JawgPlaces { * Set the minimum number of characters to trigger a geocoding request. * If you press `Enter` the search will be validated even if the length is not reached. * This option work only when `searchOnTyping=true`. - * Default value is `0`. + * + * @defaultValue 0. */ minLength?: number; /** * Set the number of milliseconds to wait before a search validation. * If you press `Enter` the search will be immediately validated. * This option work only when `searchOnTyping=true`. - * Default value is `350`. + * + * @remarks with a basic plan you may set this option to 1000 to avoid your restrictions. + * + * @defaultValue 350 */ debounceDelay?: number; /** - * Filter the kind of place you want to find. Layers can be static or dynamic with the function. + * Restrict your search (forward and reverse) to specific layers. You can get only addresses or administrative areas for example. + * + * @remarks Layers can be static or dynamic through a function. */ layers?: Layer[] | Layer | (() => Layer) | (() => Layer[]); /** - * Filter the originating source of the data. Sources can be static or dynamic with the function. + * Restrict your search (forward and reverse) to specific data sources. You can get only OSM or WOF data for example. This is not recommanded. + * + * @remarks Sources can be static or dynamic through a function. */ sources?: Source[] | Source | (() => Source[]) | (() => Source); /** - * See {@link FocusOptions.point} + * @inheritdoc FocusOptions.point + * @deprecated Replaced by {@link FocusOptions.point} */ focusPoint?: LatLon | (() => LatLon); /** {@inheritDoc FocusOptions} */ @@ -323,7 +369,9 @@ declare namespace JawgPlaces { */ clearCross?: boolean; /** - * Set the default number of results. Default value is 10. + * Set the maximum number of results for forward and reverse geocoding. + * + * @defaultValue 10 */ size?: number; /** @@ -360,7 +408,13 @@ declare namespace JawgPlaces { } /** - * Option for transition when the user click on a result on Leaflet. + * Set of option to configure the transition when the user click on a result on Leaflet. + * + * ```javascript + * const transition = { + * type: 'hybrid', + * } + * ``` */ interface LeafletTransitionOptions { /** @@ -373,21 +427,41 @@ declare namespace JawgPlaces { } /** - * Option for transition when the user click on a result on MapLibre or Mapbox. + * Set of options to configure the transition when the user click on a result on MapLibre or Mapbox. + * + * ```javascript + * const transition = { + * type: 'hybrid', + * flyCurve: 1.42, + * flySpeed: 1.2, + * } + * ``` */ interface MapGLTransitionOptions extends LeafletTransitionOptions { /** * The zooming "curve" that will occur along the flight path. + * + * @defaultValue 1.42 */ flyCurve?: number; /** * The average speed of the animation defined in relation to `curve`. + * + * @defaultValue 1.2 */ flySpeed?: number; } /** - * Option to show administrative area when available. + * Set of options to display the selected administrative area on the map when it's available. + * + * ```javascript + * const adminArea = { + * show: true, + * fillColor: 'rgba(0,75,120, 0.1)', + * outlineColor: 'rgba(0,75,120, 1)', + * } + * ``` */ interface AdminAreaOptions { /** @@ -395,11 +469,44 @@ declare namespace JawgPlaces { */ show: boolean; /** - * Fill color for the polygon. + * Fill color for the polygon, you should play with the opacity. + * + * @defaultValue 'rgba(0,75,120, 0.1)' + */ + fillColor?: string; + /** + * Outline color for the polygon. + * + * @defaultValue 'rgba(0,75,120, 1)' + */ + outlineColor?: string; + } + + /** + * Option to activate Place Details detection within the input. + * You can paste one or many GIDs in the input. + * The separation can be either `,` (comma) or ` ` (space). + * + * ```javascript + * const place = { + * enabled: true, + * geometries: 'source', + * fillColor: 'rgba(105,87,117, 0.1)', + * outlineColor: 'rgba(105,87,117, 1)', + * } + * ``` + */ + interface MapPlaceOptions extends PlaceOptions { + /** + * Fill color for the polygon, you should play with the opacity. + * + * @defaultValue 'rgba(105,87,117, 0.1)' */ fillColor?: string; /** * Outline color for the polygon. + * + * @defaultValue 'rgba(105,87,117, 1)' */ outlineColor?: string; } @@ -414,6 +521,8 @@ declare namespace JawgPlaces { show: boolean | 'all'; /** * Name of the marker from your sprites. + * + * @defaultValue 'marker' */ icon?: string; /** @@ -441,14 +550,18 @@ declare namespace JawgPlaces { } /** - * Options for {@link JawgPlaces.Input} + * @inheritdoc JawgPlacesOptions + * + * @remarks Options for {@link JawgPlaces.Input} */ interface JawgPlacesInputOptions extends JawgPlacesOptions { input: string | HTMLElement; } /** - * Options for {@link JawgPlaces.MapLibre} and {@link JawgPlaces.Mapbox} + * Options to configure a Places JS instance for a MapLibre or Mapbox map. + * + * @remarks Options for {@link JawgPlaces.MapLibre} and {@link JawgPlaces.Mapbox} */ interface JawgPlacesMaplibreOptions extends JawgPlacesOptions { /** @@ -471,10 +584,14 @@ declare namespace JawgPlaces { marker?: MapGLMarkerOptions | boolean | 'all'; /** {@inheritDoc MapGLTransitionOptions} */ transition?: MapGLTransitionOptions; + /** {@inheritDoc MapPlaceOptions} */ + place?: MapPlaceOptions; } /** - * Options for {@link JawgPlaces.Leaflet} + * Options to configure a Places JS instance for a Leaflet map. + * + * @remarks Options for {@link JawgPlaces.Leaflet} */ interface JawgPlacesLeafletOptions extends JawgPlacesOptions { /** @@ -497,6 +614,8 @@ declare namespace JawgPlaces { marker?: LeafletMarkerOptions | boolean | 'all'; /** {@inheritDoc LeafletTransitionOptions} */ transition?: LeafletTransitionOptions; + /** {@inheritDoc MapPlaceOptions} */ + place?: MapPlaceOptions; /** * Position of the input on the map. */ @@ -509,6 +628,13 @@ declare namespace JawgPlaces { /** * This class will help you to transform any input into search bar for geocoding. + * + * ```javascript + * const jawgPlaces = new JawgPlaces.Input({ + * accessToken: 'Access-Token', + * input: '#my-input', + * }) + * ``` */ class Input extends AbstractPlaces { constructor(options: JawgPlacesInputOptions); @@ -516,6 +642,12 @@ declare namespace JawgPlaces { /** * This class will help you to add or use search bar for geocoding with a MapLibre GL JS map. + * + * ```javascript + * const jawgPlaces = new JawgPlaces.MapLibre({ + * accessToken: 'Access-Token', + * }) + * ``` */ class MapLibre extends AbstractPlaces { constructor(options?: JawgPlacesMaplibreOptions); @@ -541,6 +673,12 @@ declare namespace JawgPlaces { /** * This class will help you to add or use search bar for geocoding with a Mapbox GL JS map. + * + * ```javascript + * const jawgPlaces = new JawgPlaces.Mapbox({ + * accessToken: 'Access-Token', + * }) + * ``` */ class Mapbox extends MapLibre { /** @@ -551,6 +689,12 @@ declare namespace JawgPlaces { /** * This class will help you to add or use search bar for geocoding with a Leaflet map. + * + * ```javascript + * const jawgPlaces = new JawgPlaces.Leaflet({ + * accessToken: 'Access-Token', + * }) + * ``` */ class Leaflet extends AbstractPlaces { constructor(options: JawgPlacesLeafletOptions);