@ideal-postcodes/address-finder - npm Package Compare versions

Comparing version 1.2.1 to 1.3.0

CHANGELOG.md

@@ -0,1 +1,10 @@
+# [1.3.0](https://github.com/ideal-postcodes/address-finder/compare/1.2.1...1.3.0) (2021-01-20)
+
+
+### Features
+
+* **CSS:** Make CSS overrideable ([003cff8](https://github.com/ideal-postcodes/address-finder/commit/003cff82794a4a1b35fe578165f2fcffb53cf796))
+* **Messages:** Allow default messages to be overridden ([5edf33f](https://github.com/ideal-postcodes/address-finder/commit/5edf33f249fc3b17cb049b50248b4fbcd5fbf331))
+* **onSuggestError:** Callback if suggsetion error ([cbe7e07](https://github.com/ideal-postcodes/address-finder/commit/cbe7e07a348cd3e892cd8261b12f72d7a33703eb))
+
 ## [1.2.1](https://github.com/ideal-postcodes/address-finder/compare/1.2.0...1.2.1) (2021-01-18)
@@ -2,0 +11,0 @@

dist/controller.js

@@ -35,2 +35,10 @@ "use strict";
     inputField: "",
+    // Messages
+    msgFallback: "Please enter your address manually",
+    msgInitial: "Start typing to find address",
+    msgNoMatch: "No matches found",
+    // View classes
+    messageClass: "idpc_error",
+    containerClass: "idpc_autocomplete",
+    listClass: "idpc_ul",
     // Callbacks
@@ -45,2 +53,3 @@ onOpen: NOOP,
     onSearchError: NOOP,
+    onSuggestionError: NOOP,
     onFailedCheck: NOOP,
@@ -156,3 +165,3 @@ onAddressSelected: NOOP,
             if (query.trim().length === 0) {
-                this.setMessage("Start typing to find address");
+                this.setMessage(self.options.msgInitial);
                 return Promise.resolve(this);
@@ -162,3 +171,9 @@ }
                 .query(query)
-                .then((suggestions) => this.setSuggestions(suggestions, query));
+                .then((suggestions) => this.setSuggestions(suggestions, query))
+                .catch((error) => {
+                if (this.query() === query)
+                    this.setMessage(self.options.msgFallback);
+                self.options.onSuggestionError.call(self, error);
+                return this;
+            });
         };
@@ -187,3 +202,3 @@ }
                 this.open();
-                this.setMessage("Please enter your address manually");
+                this.setMessage(self.options.msgFallback);
                 self.options.onSearchError.call(self, error);
@@ -190,0 +205,0 @@ return error;

dist/index.d.ts

@@ -24,2 +24,5 @@ import { Address, AddressSuggestion } from "@ideal-postcodes/api-typings";
 }
+export interface OnSuggestionError {
+    (this: Controller, error: Error): void;
+}
 export interface ControllerOptions extends Partial<Omit<Config, "api_key">>, Partial<Omit<ViewOptions, "scope" | "document">> {
@@ -92,2 +95,40 @@ /**
     /**
+     * Fallback message in case communication message with API fails
+     *
+     * Defaults to `"Please enter your address manually"`
+     */
+    msgFallback?: string;
+    /**
+     * Initial message when Address Finder opens an no query is available
+     *
+     * Defaults to `"Start typing to find address"`
+     */
+    msgInitial?: string;
+    /**
+     * Message presented when no matches found for a particular query
+     *
+     * Defaults to `"No matches found"`
+     */
+    msgNoMatch?: string;
+    /**
+     * CSS class assigned to message box
+     *
+     * Defaults to `"idpc_error"`
+     *
+     * Note this doesn't necessarily indicate an error
+     */
+    messageClass?: string;
+    /**
+     * CSS class assigned to the AddressFinder container/wrapper
+     *
+     * Defaults to `"idpc_autocomplete"`
+     */
+    containerClass?: string;
+    /**
+     * CSS class assigned to suggestion list (bound to `<ul>`)
+     *
+     * Defaults to `"idpc_ul"`
+     */
+    listClass?: string;
+    /**
      * Invoked when Address Finder has been successfully attached to the input element.
@@ -119,10 +160,20 @@ */
     /**
-     * Invoked when an error has occurred following an attempt to retrieve an
-     * address suggestion or full address.
+     * Invoked when an error has occurred following an attempt to retrieve a full
+     * address. i.e. the API request made after the user selects a suggestion.
      *
      * The first argument is an error instance (i.e. inherits from `Error`)
      * representing the error which has occurred.
+     *
+     * In this scenario the user will also receive a message to manually input an
+     * address if address retrieval fails.
      */
     onSearchError?: OnSearchError;
     /**
+     * Invoked when an address suggestion retrieval request has failed.
+     *
+     * In this scenario the user will be alerted that no address suggestions
+     * could be found and to manually input an address.
+     */
+    onSuggestionError?: OnSuggestionError;
+    /**
      * Invoked when the Address Finder view opens (i.e. appears)
@@ -129,0 +180,0 @@ */

dist/view.d.ts

@@ -81,2 +81,26 @@ import { AddressSuggestion } from "@ideal-postcodes/api-typings";
     /**
+     * Message to present when no match found
+     */
+    msgNoMatch: string;
+    /**
+     * CSS class assigned to message box
+     *
+     * Defaults to `"idpc_error"`
+     *
+     * Note this doesn't necessarily indicate an error
+     */
+    messageClass: string;
+    /**
+     * CSS class assigned to the AddressFinder container/wrapper
+     *
+     * Defaults to `"idpc_autocomplete"`
+     */
+    containerClass: string;
+    /**
+     * CSS class assigned to suggestion list (bound to `<ul>`)
+     *
+     * Defaults to `"idpc_ul"`
+     */
+    listClass: string;
+    /**
      * Invoked when Address Finder suggestion box is opened (i.e. presented to the user).
@@ -83,0 +107,0 @@ */

dist/view.js

@@ -40,5 +40,5 @@ "use strict";
         this.container = this.options.document.createElement("div");
-        this.container.className = "idpc_autocomplete";
+        this.container.className = this.options.containerClass;
         this.list = this.options.document.createElement("ul");
-        this.list.className = "hidden idpc_ul";
+        this.list.className = `hidden ${this.options.listClass}`;
         this.inputListener = _onInput(this);
@@ -125,3 +125,3 @@ this.blurListener = _onBlur(this);
         if (suggestions.length === 0)
-            return this.setMessage("No matches found");
+            return this.setMessage(this.options.msgNoMatch);
         this.fsm.send({ type: "SUGGEST", suggestions });
@@ -273,3 +273,3 @@ return this;
         li.innerHTML = this.message();
-        li.className = "idpc_error";
+        li.className = this.options.messageClass;
         this.list.appendChild(li);
@@ -276,0 +276,0 @@ return this;

esm/controller.js

@@ -29,2 +29,10 @@ /* eslint-disable no-invalid-this */
     inputField: "",
+    // Messages
+    msgFallback: "Please enter your address manually",
+    msgInitial: "Start typing to find address",
+    msgNoMatch: "No matches found",
+    // View classes
+    messageClass: "idpc_error",
+    containerClass: "idpc_autocomplete",
+    listClass: "idpc_ul",
     // Callbacks
@@ -39,2 +47,3 @@ onOpen: NOOP,
     onSearchError: NOOP,
+    onSuggestionError: NOOP,
     onFailedCheck: NOOP,
@@ -150,3 +159,3 @@ onAddressSelected: NOOP,
             if (query.trim().length === 0) {
-                this.setMessage("Start typing to find address");
+                this.setMessage(self.options.msgInitial);
                 return Promise.resolve(this);
@@ -156,3 +165,9 @@ }
                 .query(query)
-                .then((suggestions) => this.setSuggestions(suggestions, query));
+                .then((suggestions) => this.setSuggestions(suggestions, query))
+                .catch((error) => {
+                if (this.query() === query)
+                    this.setMessage(self.options.msgFallback);
+                self.options.onSuggestionError.call(self, error);
+                return this;
+            });
         };
@@ -181,3 +196,3 @@ }
                 this.open();
-                this.setMessage("Please enter your address manually");
+                this.setMessage(self.options.msgFallback);
                 self.options.onSearchError.call(self, error);
@@ -184,0 +199,0 @@ return error;

esm/index.d.ts

@@ -24,2 +24,5 @@ import { Address, AddressSuggestion } from "@ideal-postcodes/api-typings";
 }
+export interface OnSuggestionError {
+    (this: Controller, error: Error): void;
+}
 export interface ControllerOptions extends Partial<Omit<Config, "api_key">>, Partial<Omit<ViewOptions, "scope" | "document">> {
@@ -92,2 +95,40 @@ /**
     /**
+     * Fallback message in case communication message with API fails
+     *
+     * Defaults to `"Please enter your address manually"`
+     */
+    msgFallback?: string;
+    /**
+     * Initial message when Address Finder opens an no query is available
+     *
+     * Defaults to `"Start typing to find address"`
+     */
+    msgInitial?: string;
+    /**
+     * Message presented when no matches found for a particular query
+     *
+     * Defaults to `"No matches found"`
+     */
+    msgNoMatch?: string;
+    /**
+     * CSS class assigned to message box
+     *
+     * Defaults to `"idpc_error"`
+     *
+     * Note this doesn't necessarily indicate an error
+     */
+    messageClass?: string;
+    /**
+     * CSS class assigned to the AddressFinder container/wrapper
+     *
+     * Defaults to `"idpc_autocomplete"`
+     */
+    containerClass?: string;
+    /**
+     * CSS class assigned to suggestion list (bound to `<ul>`)
+     *
+     * Defaults to `"idpc_ul"`
+     */
+    listClass?: string;
+    /**
      * Invoked when Address Finder has been successfully attached to the input element.
@@ -119,10 +160,20 @@ */
     /**
-     * Invoked when an error has occurred following an attempt to retrieve an
-     * address suggestion or full address.
+     * Invoked when an error has occurred following an attempt to retrieve a full
+     * address. i.e. the API request made after the user selects a suggestion.
      *
      * The first argument is an error instance (i.e. inherits from `Error`)
      * representing the error which has occurred.
+     *
+     * In this scenario the user will also receive a message to manually input an
+     * address if address retrieval fails.
      */
     onSearchError?: OnSearchError;
     /**
+     * Invoked when an address suggestion retrieval request has failed.
+     *
+     * In this scenario the user will be alerted that no address suggestions
+     * could be found and to manually input an address.
+     */
+    onSuggestionError?: OnSuggestionError;
+    /**
      * Invoked when the Address Finder view opens (i.e. appears)
@@ -129,0 +180,0 @@ */

esm/view.d.ts

@@ -81,2 +81,26 @@ import { AddressSuggestion } from "@ideal-postcodes/api-typings";
     /**
+     * Message to present when no match found
+     */
+    msgNoMatch: string;
+    /**
+     * CSS class assigned to message box
+     *
+     * Defaults to `"idpc_error"`
+     *
+     * Note this doesn't necessarily indicate an error
+     */
+    messageClass: string;
+    /**
+     * CSS class assigned to the AddressFinder container/wrapper
+     *
+     * Defaults to `"idpc_autocomplete"`
+     */
+    containerClass: string;
+    /**
+     * CSS class assigned to suggestion list (bound to `<ul>`)
+     *
+     * Defaults to `"idpc_ul"`
+     */
+    listClass: string;
+    /**
      * Invoked when Address Finder suggestion box is opened (i.e. presented to the user).
@@ -83,0 +107,0 @@ */

esm/view.js

@@ -37,5 +37,5 @@ import { isString } from "@ideal-postcodes/jsutil";
         this.container = this.options.document.createElement("div");
-        this.container.className = "idpc_autocomplete";
+        this.container.className = this.options.containerClass;
         this.list = this.options.document.createElement("ul");
-        this.list.className = "hidden idpc_ul";
+        this.list.className = `hidden ${this.options.listClass}`;
         this.inputListener = _onInput(this);
@@ -122,3 +122,3 @@ this.blurListener = _onBlur(this);
         if (suggestions.length === 0)
-            return this.setMessage("No matches found");
+            return this.setMessage(this.options.msgNoMatch);
         this.fsm.send({ type: "SUGGEST", suggestions });
@@ -270,3 +270,3 @@ return this;
         li.innerHTML = this.message();
-        li.className = "idpc_error";
+        li.className = this.options.messageClass;
         this.list.appendChild(li);
@@ -273,0 +273,0 @@ return this;

package.json

 {
   "name": "@ideal-postcodes/address-finder",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Address Finder JS library backed by the Ideal Postcodes UK address search API",
@@ -112,3 +112,3 @@ "main": "dist/index.js",
     "@rollup/plugin-commonjs": "~17.0.0",
-    "@rollup/plugin-node-resolve": "~11.0.1",
+    "@rollup/plugin-node-resolve": "~11.1.0",
     "@types/chai": "~4.2.14",
@@ -121,3 +121,3 @@ "@types/dotenv": "~8.2.0",
     "@types/puppeteer": "~5.4.2",
-    "@typescript-eslint/eslint-plugin": "~4.13.0",
+    "@typescript-eslint/eslint-plugin": "~4.14.0",
     "@wessberg/rollup-plugin-ts": "1.3.5",
@@ -127,5 +127,5 @@ "chai": "~4.2.0",
     "core-js": "~3.8.1",
-    "cypress": "~6.2.0",
+    "cypress": "~6.3.0",
     "dotenv": "~8.2.0",
-    "eslint": "~7.17.0",
+    "eslint": "~7.18.0",
     "eslint-plugin-compat": "^3.9.0",
@@ -142,3 +142,3 @@ "karma": "~5.2.3",
     "puppeteer": "~5.5.0",
-    "rollup": "~2.36.1",
+    "rollup": "~2.37.0",
     "semantic-release": "~17.3.1",
@@ -145,0 +145,0 @@ "sinon": "~9.2.2",

README.md

@@ -146,2 +146,20 @@ <h1 align="center">
 
+The Address Finder view CSS is structured in the following way:
+
+- The target input and Address Finder suggestion list is wrapped in a `<div>` with a default class of `idpc_autocomplete`
+- Address Suggestions are rendered in a `<ul>` list with a default class of `idpc_ul`
+- Any messages (including prompts to type, errors, etc) are rendered in a `<li>` with a default class of `idpc_error`
+
+Default CSS classes can be overridden. For instance, [containerClass](https://address-finder.ideal-postcodes.dev/globals.html#defaults.containerclass), [listClass](https://address-finder.ideal-postcodes.dev/globals.html#defaults.listclass) and [messageClass](https://address-finder.ideal-postcodes.dev/globals.html#defaults.messageclass) are all defined in [defaults](https://address-finder.ideal-postcodes.dev/globals.html#defaults).
+
+#### [`injectStyle`](https://address-finder.ideal-postcodes.dev/interfaces/controlleroptions.html#injectstyle)
+
+Set `injectStyle: true` to inject default Address Finder style into DOM. Defaults to `false`.
+
+Set to a URL (e.g. `injectStyle: "https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder@1.2.1/css/address-finder.min.css"`) to retrieve a CSS stylesheet.
+
+#### Messages
+
+Default messages (e.g. "Start typing to find address", "No matches found") can be overridden. For instance, [msgFallback](https://address-finder.ideal-postcodes.dev/globals.html#defaults.msgfallback), [msgInitial](https://address-finder.ideal-postcodes.dev/globals.html#defaults.msginitial) and [msgNoMatch](https://address-finder.ideal-postcodes.dev/globals.html#defaults.msgnomatch).
+
 ### Setup Options
@@ -238,3 +256,3 @@
 
-Invoked when an error has occurred following an attempt to retrieve an address suggestion or full address.
+Invoked when an error has occurred following an attempt to retrieve a full address. In this scenario the user will also receive a message to manually input their address.
 
@@ -245,2 +263,10 @@ The first argument is an error instance (i.e. inherits from `Error`) representing the error which has occurred.
 
+#### [`onSuggestError`](https://address-finder.ideal-postcodes.dev/interfaces/controlleroptions.html#onsuggesterror)
+
+Invoked when an error has occurred following an attempt to retrieve suggestions for a key press. In this scenario the user will also receive a message to manually input their address.
+
+The first argument is an error instance (i.e. inherits from `Error`) representing the error which has occurred.
+
+Examples of errors includes "lookup balance exhausted" and "lookup limit reached" errors.
+
 #### [`onOpen`](https://address-finder.ideal-postcodes.dev/interfaces/controlleroptions.html#onopen)
@@ -247,0 +273,0 @@

No alert changes

Improved metrics

Total package byte prevSize

148687

increased by5.76%

Lines of code

3003

increased by6.38%

Number of lines in readme file

296

increased by9.63%

No dependency changes