@placekit/autocomplete-js - npm Package Compare versions

Comparing version 1.6.1 to 2.0.0

dist/placekit-autocomplete.d.ts

@@ -1,2 +0,2 @@
-/*! @placekit/autocomplete-js v1.6.1 | © placekit.io | MIT license | https://github.com/placekit/autocomplete-js#readme */
+/*! @placekit/autocomplete-js v2.0.0 | © placekit.io | MIT license | https://github.com/placekit/autocomplete-js#readme */
 import type { PKOptions, PKResult } from '@placekit/client-js';
@@ -14,2 +14,3 @@
   geolocation: boolean;
+  countryMode: boolean;
 };
@@ -30,3 +31,5 @@
   on(event: 'geolocation', handler?: PKAHandlers['geolocation']): PKAClient;
+  on(event: 'countryMode', handler?: PKAHandlers['countryMode']): PKAClient;
   on(event: 'state', handler?: PKAHandlers['state']): PKAClient;
+  on(event: 'countryChange', handler?: PKAHandlers['countryChange']): PKAClient;
   readonly handlers: Partial<PKAHandlers>;
@@ -53,3 +56,5 @@ readonly state: PKAState;
   geolocation: (bool: boolean, position?: GeolocationPosition) => void;
+  countryMode: (bool: boolean) => void;
   state: (state: PKAState) => void;
+  countryChange: (item: PKResult) => void;
 };
@@ -59,10 +64,19 @@
   target: string | HTMLInputElement;
-  offset?: number;
-  template?: (item: PKResult) => string;
-  formatValue?: (item: PKResult) => string;
-  noResults?: string | ((query: string) => string);
-  strategy?: 'absolute' | 'fixed';
-  flip?: boolean;
+  panel?: {
+    className?: string;
+    offset?: number;
+    strategy?: 'absolute' | 'fixed';
+    flip?: boolean;
+  };
+  format?: {
+    flag?: (countrycode: string) => string;
+    icon?: (name: string, label?: string) => string;
+    sub?: (item: PKResult) => string;
+    noResults?: (query: string) => string;
+    value?: (item: PKResult) => string;
+    applySuggestion?: string;
+    cancel?: string;
+  };
   countryAutoFill?: boolean;
-  className?: string;
+  countrySelect?: boolean;
 };

package.json

 {
   "name": "@placekit/autocomplete-js",
-  "version": "1.6.1",
+  "version": "2.0.0",
   "author": "PlaceKit <[e-mail]>",
@@ -15,6 +15,7 @@ "description": "PlaceKit Autocomplete JavaScript library",
   },
-  "types": "./dist/placekit-autocomplete.d.ts",
+  "type": "module",
+  "main": "./dist/placekit-autocomplete.cjs.js",
   "module": "./dist/placekit-autocomplete.esm.mjs",
-  "main": "./dist/placekit-autocomplete.cjs.js",
   "browser": "./dist/placekit-autocomplete.umd.js",
+  "types": "./dist/placekit-autocomplete.d.ts",
   "exports": {
@@ -43,13 +44,12 @@ ".": {
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.2",
+    "@rollup/plugin-commonjs": "^25.0.4",
     "@rollup/plugin-node-resolve": "^15.1.0",
-    "@rollup/plugin-replace": "^5.0.2",
-    "autoprefixer": "^10.4.14",
-    "eslint": "^8.43.0",
+    "autoprefixer": "^10.4.15",
+    "eslint": "^8.47.0",
     "eslint-config-google": "^0.14.0",
     "npm-watch": "^0.11.0",
-    "postcss": "^8.4.24",
+    "postcss": "^8.4.27",
     "postcss-banner": "^4.0.1",
     "rimraf": "^5.0.1",
-    "rollup": "^3.25.1",
+    "rollup": "^3.28.0",
     "rollup-plugin-cleanup": "^3.2.1",
@@ -60,5 +60,5 @@ "rollup-plugin-copy": "^3.4.0",
   "dependencies": {
-    "@placekit/client-js": "^1.1.1",
+    "@placekit/client-js": "^2.0.0",
     "@popperjs/core": "^2.11.8"
   }
 }

README.md

@@ -49,4 +49,4 @@ <h1 align="center">
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@1.6.0/dist/placekit-autocomplete.min.css" />
-<script src="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@1.6.0"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.0.0/dist/placekit-autocomplete.min.css" />
+<script src="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.0.0"></script>
 ```
@@ -61,3 +61,2 @@
     target: '#placekit',
-    countries: ['fr'],
     // other options...
@@ -72,3 +71,3 @@ });
 <script type="module">
-  import placekit from 'https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@1.6.0/dist/placekit-autocomplete.esm.js';
+  import placekitAutocomplete from 'https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.0.0/dist/placekit-autocomplete.esm.js';
   const pka = placekitAutocomplete(/* ... */);
@@ -100,3 +99,2 @@ // ...
   target: '#placekit',
-  countries: ['fr'],
   // other options...
@@ -113,3 +111,3 @@ });
 
-- [`placekitAutocomplete()`](#placekitAutocomplete)
+- [`placekitAutocomplete()`](#placekitautocomplete)
 - [`pka.input`](#pkainput)
@@ -121,4 +119,4 @@ - [`pka.options`](#pkaoptions)
 - [`pka.handlers`](#pkahandlers)
-- [`pka.requestGeolocation()`](#pkarequestGeolocation)
-- [`pka.clearGeolocation()`](#pkaclearGeolocation)
+- [`pka.requestGeolocation()`](#pkarequestgeolocation)
+- [`pka.clearGeolocation()`](#pkacleargeolocation)
 - [`pka.open()`](#pkaopen)
@@ -168,56 +166,40 @@ - [`pka.close()`](#pkaclose)
 | `target` | AutoComplete | `string\|Element` | `-` | Target input element or (unique) selector. |
-| `offset` | AutoComplete | `integer` | `4` | Gap between input and suggestions list in pixels. |
-| `template` | AutoComplete | `(item: object) => string` | [see index.js](./src/index.js#L92-L107) | Suggestion item formatting function. |
-| `formatValue` | AutoComplete | `(item: object) => string` | [see index.js](./src/index.js#L108) | Input value formatting function when selected from list. |
-| `noResults` | AutoComplete | `string\|(query: string) => string` | [see index.js](./src/index.js#L109-L114) | No result template. |
-| `strategy` | AutoComplete | `'absolute' \| 'fixed'` | `absolute` | [Popper positioning strategy](https://popper.js.org/docs/v2/constructors/#strategy) |
-| `flip` | AutoComplete | `boolean` | `false` | Flip position top when overflowing. |
-| [`countryAutoFill`](#countryautofill-option) | Autocomplete | `boolean?` | `false` | Autofill current country by IP when `types: ['country']`. |
-| `className` | AutoComplete | `string` | `undefined` | Additional suggestions panel CSS class(es). |
+| `panel` | AutoComplete | `object?` | `(...)` | Suggestions panel options, see [Panel options](#panel-options). |
+| `format` | AutoComplete | `object?` | `(...)` | Formatting options, see [Format options](#format-options). |
+| `countryAutoFill` | AutoComplete | `boolean?` | `true` | Automatically detect current country by IP and fill input when `types: ['country']`. |
+| `countrySelect` | AutoComplete | `boolean?` | `true` | Show country selector when `countries` is not defined. |
 | `maxResults` | JS client | `integer` | `5` | Number of results per page. |
 | `language` | JS client | `string?` | `undefined` | Preferred language for the results<sup>[(1)](#ft1)</sup>, [two-letter ISO](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. Supported languages are `en` and `fr`. By default the results are displayed in their country's language. |
 | `types` | JS client | `string[]?` | `undefined` | Type of results to show. Array of accepted values: `street`, `city`, `country`, `airport`, `bus`, `train`, `townhall`, `tourism`. Prepend `-` to omit a type like `['-bus']`. Unset to return all. |
-| [`countries`](#%EF%B8%8F-countries-option-is-required) | JS client | `string[]?` | `undefined` | Countries to search in, or fallback to if `countryByIP` is `true`. Array of [two-letter ISO](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes<sup>[(1)](#ft1)</sup>. |
-| [`countryByIP`](#countryByIP-option) | JS client | `boolean?` | `undefined` | Use IP to find user's country (turned off). |
-| `coordinates` | JS client | `string?` | `undefined` | Coordinates to search around. Automatically set when calling [`pka.requestGeolocation()`](#pkarequestGeolocation). |
+| `countries` | JS client | `string[]?` | `undefined` | Restrict search in specific countries. Array of [two-letter ISO](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes<sup>[(1)](#ft1)</sup>. |
+| `coordinates` | JS client | `string?` | `undefined` | Coordinates to search around. Automatically set when calling [`pka.requestGeolocation()`](#pkarequestgeolocation). |
 
-<a id="ft1"><b>[1]</b></a>: See [Scope and Limitations](https://placekit.io/terms/scope) for more details.
+<a id="ft1"><b>[1]</b></a>: See [Coverage](https://placekit.io/terms/coverage) for more details.
 
-#### ⚠️ `countries` option is required
+<details>
+<summary><h4 id="panel-options">Panel options</h4></summary>
 
-The `countries` option is **required** at search time, but we like to keep it optional across all methods so developers remain free on when and how to define it: 
-- either when instanciating with `placekit()`,
-- with `pk.configure()`,
-- or at search time with `pk.search()`.
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` | `undefined` | Additional panel CSS class(es). |
+| `offset` | `integer` | `4` | Gap between input and panel in pixels. |
+| `strategy` | `'absolute' \| 'fixed'` | `absolute` | [Popper positioning strategy](https://popper.js.org/docs/v2/constructors/#strategy) |
+| `flip` | `boolean` | `false` | Flip position top when overflowing. |
 
-If `countries` is missing or invalid, you'll get a `422` error, excepted when`types` option is set to `['country']` only.
+</details>
+<details>
+<summary><h4 id="format-options">Format options</h4></summary>
 
-#### `countryByIP` option
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `flag` | `(countrycode: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L56) | DOM for flags. |
+| `icon` | `(name: string, label: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L57) | DOM for icons. |
+| `sub` | `(item: object) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L58-L60) | Format suggestion secondary text |
+| `noResults` | `(query: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L61) | Format "no results" text. |
+| `value` | `(item: object) => string` | `item.name` | Format input value when user picks a suggestion. |
+| `applySuggestion` | `string` | `"Apply suggestion"` | ARIA label for "insert" icon. |
+| `cancel` | `string` | `"Cancel"` | Label for cancelling country selection mode. |
 
-Set `countryByIP` to `true` when you don't know which country users will search addresses in. In that case, the option `countries` will be used as a fallback if the user's country is not supported:
+</details>
 
-```js
-pka.configure({
-  countryByIP: true, // use user's country, based on their IP
-  countries: ['fr', 'be'], // returning results from France and Belgium if user's country is not supported
-});
-```
-
-#### `countryAutoFill` option
-
-When making a country-only autocomplete field, this option enhances the experience by automatically filling the input detected with the user's IP.
-It works only when `types` option is set **only** with the `conutry` value:
-
-```js
-const pka = placekitAutocomplete('<your-api-key>', {
-  target: '#placekit',
-  types: ['country'],
-  countryAutoFill: true,
-});
-```
-
-⚠️ **It makes an automatic call to the PlaceKit API and therefore counts as billable usage.**
-
-See our [country field example](./example/autocomplete-js-country).
-
 ### `pka.configure()`
@@ -229,5 +211,9 @@
 pka.configure({
-  className: 'my-suggestions',
-  flip: true,
-  formatValue: (item) => `${item.name} ${item.city}`,
+  panel: {
+    className: 'my-suggestions',
+    flip: true,
+  },
+  format: {
+    value: (item) => `${item.name} ${item.city}`,
+  },
   language: 'fr',
@@ -260,2 +246,5 @@ maxResults: 5,
 console.log(pka.state.geolocation); // true or false
+
+// `true` if panel is in country selection mode.
+console.log(pka.state.countryMode); // true or false
 ```
@@ -279,3 +268,5 @@
   .on('geolocation', (bool, position) => {});
+  .on('countryMode', (bool) => {});
   .on('state', (state) => {})
+  .on('countryChange', (item) => {});
 ```
@@ -360,2 +351,10 @@
 
+##### `countryMode`
+
+Triggered when the user toggles the country selection mode. Always `false` if `countries` option is set, or if `countrySelect` is `false`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `bool` | `boolean` | `true` if open, `false` if closed. |
+
 ##### `state`
@@ -369,2 +368,10 @@
 
+##### `countryChange`
+
+Triggered when the current search country changes (either detected by IP, or selected by the user in the country selection mode).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `item` | `object` | Country details returned from API. |
+
 ### `pka.handlers`
@@ -458,3 +465,3 @@
 
-Colors, border-radius, font and overall scale (in `rem`) are accessible over variables:
+Colors, border-radius, font and overall scale (in `rem`) and even icons are accessible over variables:
 
@@ -474,2 +481,20 @@ ```css
   --pka-z-index: 9999;
+
+  --pka-icon-pin: url("...");
+  --pka-icon-street: var(--pka-icon-pin);
+  --pka-icon-city: url("...");
+  --pka-icon-airport: url("...");
+  --pka-icon-bus: url("...");
+  --pka-icon-train: url("...");
+  --pka-icon-townhall: url("...");
+  --pka-icon-tourism: url("...");
+  --pka-icon-noresults: url("...");
+  --pka-icon-clear: url("...");
+  --pka-icon-cancel: var(--pka-icon-clear);
+  --pka-icon-insert: url("...");
+  --pka-icon-check: url("...");
+  --pka-icon-switch: url("...");
+  --pka-icon-geo-off: url("...");
+  --pka-icon-geo-on: url("...");
+  --pka-icon-loading: url("...");
 }
@@ -484,2 +509,4 @@
 
+You also have full control over flags and icons DOM with `format.flag` and `format.icon` options (see [Format options](#format-options)).
+
 For advanced customization, refer to our [stylesheet](./src/placekit.css) to learn about the available classes if you need to either override some or start a theme from scratch.
@@ -486,0 +513,0 @@

No alert changes

Improved metrics

Total package byte prevSize

280060

increased by0.21%

Dev dependency count

13

decreased by-7.14%

Number of lines in readme file

509

increased by5.6%

Is type module

Yes

Worsened metrics

Lines of code

6890

decreased by-0.71%

Dependency changes

• + Added@placekit/client-js@2.3.0(transitive)

• - Removed@placekit/client-js@1.1.1(transitive)

• Updated@placekit/client-js@^2.0.0