From 030c5ce91943311d1cad677281f5189088cd9b04 Mon Sep 17 00:00:00 2001 From: Matt Simon Date: Thu, 29 Jul 2021 11:07:03 +0100 Subject: [PATCH] Autosuggest/Address finder - add functionality and refactor (#1605) * Autosuggest - add more input params + fix uprn param * Fix class params * typo * Fix evaluation * Fix tests * Remove only from test * Changed name of onsAddressFinder to onsAddressInput, updated docs, examples and component functionality to allow manual only mode * Update macro options --- .../address-finder/_macro-options.md | 58 -------- .../address-finder/_test-template.njk | 3 - .../address-finder/abortable-fetch.js | 55 -------- .../address-input/_macro-options.md | 67 ++++++++++ .../_macro.njk | 124 ++++++++++-------- .../address-input/_test-template.njk | 3 + .../autosuggest.address.dom.js | 0 .../autosuggest.address.error.js | 0 .../autosuggest.address.js | 0 .../autosuggest.address.setter.js | 0 .../address-input-editable}/index.njk | 4 +- .../examples/address-input-manual/index.njk | 23 ++++ .../examples/address-input}/index.njk | 4 +- .../index.njk | 30 +++-- src/components/autosuggest/_macro-options.md | 40 +++--- src/components/autosuggest/_macro.njk | 34 +++-- src/components/input/_macro.njk | 3 +- src/components/mutually-exclusive/_macro.njk | 3 + src/js/index.js | 2 +- .../examples/address-input-manual/index.njk | 49 +++++++ .../index.njk | 6 +- .../register-address/index.njk | 4 +- .../index.njk | 4 +- src/patterns/addresses/index.njk | 24 +++- .../autosuggest/autosuggest.address.spec.js | 12 +- 25 files changed, 320 insertions(+), 232 deletions(-) delete mode 100644 src/components/address-finder/_macro-options.md delete mode 100644 src/components/address-finder/_test-template.njk delete mode 100644 src/components/address-finder/abortable-fetch.js create mode 100644 src/components/address-input/_macro-options.md rename src/components/{address-finder => address-input}/_macro.njk (50%) create mode 100644 src/components/address-input/_test-template.njk rename src/components/{address-finder => address-input}/autosuggest.address.dom.js (100%) rename src/components/{address-finder => address-input}/autosuggest.address.error.js (100%) rename src/components/{address-finder => address-input}/autosuggest.address.js (100%) rename src/components/{address-finder => address-input}/autosuggest.address.setter.js (100%) rename src/components/{address-finder/examples/address-finder-editable => address-input/examples/address-input-editable}/index.njk (95%) create mode 100644 src/components/address-input/examples/address-input-manual/index.njk rename src/components/{address-finder/examples/address-finder => address-input/examples/address-input}/index.njk (95%) rename src/components/{address-finder => address-input}/index.njk (73%) create mode 100644 src/patterns/addresses/examples/address-input-manual/index.njk rename src/patterns/addresses/examples/{address-finder-non-editable => address-input-non-editable}/index.njk (95%) rename src/patterns/addresses/examples/{address-finder-non-editable => address-input-non-editable}/register-address/index.njk (84%) rename src/patterns/addresses/examples/{address-finder => address-input}/index.njk (96%) diff --git a/src/components/address-finder/_macro-options.md b/src/components/address-finder/_macro-options.md deleted file mode 100644 index 5df8d5d8b5..0000000000 --- a/src/components/address-finder/_macro-options.md +++ /dev/null @@ -1,58 +0,0 @@ -| Name | Type | Required | Description | -| ----------------------- | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| id | string | true | ID for the fieldset. This is used to automatically generate IDs and names for each field if one isn't specified | -| classes | string | false | Classes to add to the fieldset | -| legend | string | true | Legend text for the address input | -| legendClasses | string | false | Classes to apply to the legend | -| dontWrap | boolean | false | Set to true to prevent the address fields from being wrapped in a fieldset | -| isEditable | boolean | true | Used with the address macro to invoke population of manual fields upon selection of suggestion | -| mandatory | boolean | false | Set the autosuggest input to be mandatory and use client side validation for empty form submission | -| APIDomain | string | false | Set an api domain when using an external API to suggest results | -| APIDomainBearerToken | string | false | Set a bearer token for api authorization on the AIMS address api. | -| instructions | string | true | Instructions on how to use the autosuggest that will be read out by screenreaders | -| ariaYouHaveSelected | string | true | Aria message to tell the user that they have selected an answer | -| ariaMinChars | string | true | Aria message to tell the user how many charecters they need to enter before autosuggest will start | -| ariaResultsLabel | string | true | Aria message to tell the user that suggestions are available | -| ariaOneResult | string | true | Aria message to tell the user there is only one suggestion left | -| ariaNResults | string | true | Aria message to tell the user how many suggestions are left | -| ariaLimitedResults | string | true | Aria message to tell the user if the results have been limited and what they are limited to | -| ariaGroupedResults | string | true | Aria message to tell the user about a grouped result e.g There are {n} for {x} | -| groupCount | string | true | Aria message to tell the user the number of addresses in a group e.g. {n} addresses | -| moreResults | string | true | Aria message to tell the user to continue to type to refine suggestions | -| noResults | string | true | message to tell the user there are no results | -| tooManyResults | string | true | message to tell the user there are too many results to display and the user should refine the search | -| typeMore | string | true | message to encourage the user to enter more characters to get suggestions | -| resultsTitle | string | true | Title of results to be displayed on screen at the top of the results | -| errorTitle | string | false | Error message title displayed in the error panel | -| errorMessageEnter | string | false | Error message description displayed in the error panel when the input is empty | -| errorMessageSelect | string | false | Error message description displayed in the error panel when a suggestion has not been selected | -| errorMessageAPI | string | false | Error message displayed when the API has failed during a search | -| errorMessageAPILinkText | string | false | Link text used to toggle to a manual mode when using the address macro | -| manualLink | string | false | url for the link displayed below the input | -| manualLinkText | string | false | Link text shown for the manual link. If using the editable address, including this parameter will toggle the mode to manual entry | -| options | `Object` | false | Option to provide key value pairs that will be added as data attributes to the component that will be added as parameters to the address index api | -| organisation | `Object` | false | Configuration for the organisation field. | -| line1 | `Object` | false | Configuration for the line1 field | -| line2 | `Object` | false | Configuration for the line2 field | -| town | `Object` | false | Configuration for the town field | -| county | `Object` | false | Configuration for the county field | -| postcode | `Object` | false | Configuration for the postcode field | -| uprn | `Object` | false | Configuration for the uprn field | - -## Options - -| Name | Type | Required | Description | -| ---------- | ------ | -------- | ------------------------------------------------ | -| regionCode | string | false | Sets the provided region code e.g. en-gb | -| adressType | string | false | Sets the provided address type e.g. resedential | -| oneYearAgo | string | false | If "true" will set a query parameter of epoch=75 | - -## AddressField - -| Name | Type | Required | Description | -| ---------- | ------------------------------------ | -------- | ------------------------------------ | -| id | string | false | ID for the field | -| name | string | false | Sets the name attribute on the field | -| label.text | string | true | The label for the input | -| value | string | false | The value for the input | -| error | `Error` [_(ref)_](/components/error) | false | Configuration for validation errors | diff --git a/src/components/address-finder/_test-template.njk b/src/components/address-finder/_test-template.njk deleted file mode 100644 index 3dfce6c830..0000000000 --- a/src/components/address-finder/_test-template.njk +++ /dev/null @@ -1,3 +0,0 @@ -{% from "components/address-finder/_macro.njk" import onsAddressFinder %} - -{{ onsAddressFinder(params) }} diff --git a/src/components/address-finder/abortable-fetch.js b/src/components/address-finder/abortable-fetch.js deleted file mode 100644 index 0c96ae549f..0000000000 --- a/src/components/address-finder/abortable-fetch.js +++ /dev/null @@ -1,55 +0,0 @@ -class AbortableFetch { - constructor(url, options) { - this.url = url; - this.options = options; - this.controller = new window.AbortController(); - this.status = 'UNSENT'; - } - - send() { - this.status = 'LOADING'; - - return new Promise((resolve, reject) => { - abortableFetch(this.url, { signal: this.controller.signal, ...this.options }) - .then(response => { - if (response.status >= 200 && response.status < 300) { - this.status = 'DONE'; - resolve(response); - } else if (response.status >= 400) { - this.status = 'DONE'; - resolve(response); - } else { - this.status = 'DONE'; - reject(response); - } - }) - .catch(error => { - this.status = 'undefined'; - reject(error); - }); - }); - } - - abort() { - this.controller.abort(); - } -} - -function abortableFetch(url, options) { - return window - .fetch(url, options) - .then(response => { - if (response) { - return response; - } else { - const error = new Error(response.status); - error.response = response; - throw error; - } - }) - .catch(error => { - throw error; - }); -} - -export default (url, options) => new AbortableFetch(url, options); diff --git a/src/components/address-input/_macro-options.md b/src/components/address-input/_macro-options.md new file mode 100644 index 0000000000..1359e94cf6 --- /dev/null +++ b/src/components/address-input/_macro-options.md @@ -0,0 +1,67 @@ +| Name | Type | Required | Description | +| ----------------------- | ------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | string | true | ID for the fieldset. This is used to automatically generate IDs and names for each field if one isn't specified | +| classes | string | false | Classes to add to the fieldset | +| label | `Label` [_(ref)_](/components/label) | false | Settings for the input label. `for` will automatically be set to match the input id | +| legend | string | true | Legend text for the address input | +| legendClasses | string | false | Classes to apply to the legend | +| dontWrap | boolean | false | Set to true to prevent the address fields from being wrapped in a fieldset | +| isEditable | boolean | true | Used with the address macro to invoke population of manual fields upon selection of suggestion | +| manualEntry | boolean | false | Only display manual fields and do not invoke autosuggest/api functionality | +| mandatory | boolean | false | Set the autosuggest input to be mandatory and use client side validation for empty form submission | +| APIDomain | string | false | Set an api domain when using an external API to suggest results | +| APIDomainBearerToken | string | false | Set a bearer token for api authorization on the AIMS address api. | +| instructions | string | true | Instructions on how to use the autosuggest that will be read out by screenreaders | +| ariaYouHaveSelected | string | true | Aria message to tell the user that they have selected an answer | +| ariaMinChars | string | true | Aria message to tell the user how many charecters they need to enter before autosuggest will start | +| ariaResultsLabel | string | true | Aria message to tell the user that suggestions are available | +| ariaOneResult | string | true | Aria message to tell the user there is only one suggestion left | +| ariaNResults | string | true | Aria message to tell the user how many suggestions are left | +| ariaLimitedResults | string | true | Aria message to tell the user if the results have been limited and what they are limited to | +| ariaGroupedResults | string | true | Aria message to tell the user about a grouped result e.g There are {n} for {x} | +| groupCount | string | true | Aria message to tell the user the number of addresses in a group e.g. {n} addresses | +| moreResults | string | true | Aria message to tell the user to continue to type to refine suggestions | +| noResults | string | true | message to tell the user there are no results | +| tooManyResults | string | true | message to tell the user there are too many results to display and the user should refine the search | +| typeMore | string | true | message to encourage the user to enter more characters to get suggestions | +| resultsTitle | string | true | Title of results to be displayed on screen at the top of the results | +| errorTitle | string | false | Error message title displayed in the error panel | +| errorMessageEnter | string | false | Error message description displayed in the error panel when the input is empty | +| errorMessageSelect | string | false | Error message description displayed in the error panel when a suggestion has not been selected | +| errorMessageAPI | string | false | Error message displayed when the API has failed during a search | +| errorMessageAPILinkText | string | false | Link text used to toggle to a manual mode when using the address macro | +| manualLink | string | false | url for the link displayed below the input | +| manualLinkText | string | false | Link text shown for the manual link. If using the editable address, including this parameter will toggle the mode to manual entry | +| options | `Object` | false | Option to provide key value pairs that will be added as data attributes to the component that will be added as parameters to the address index api | +| organisation | `Object` | false | Configuration for the organisation field. | +| line1 | `Object` | false | Configuration for the line1 field | +| line2 | `Object` | false | Configuration for the line2 field | +| town | `Object` | false | Configuration for the town field | +| county | `Object` | false | Configuration for the county field | +| postcode | `Object` | false | Configuration for the postcode field | +| uprn | `Object` | false | Configuration for the uprn field | +| mutuallyExclusive | `MutuallyExclusive` [_(ref)_](/components/mutually-exclusive) | false | Configuration object if this is a mutually exclusive input | +| legend | string | Only if mutuallyExclusive is set | Text content for the legend | +| legendClasses | string | false | Classes for the legend | +| error | `Error` [_(ref)_](/components/error) | false | Configuration for validation errors | +| name | string | false | The name of the input | +| value | string | number | false | The value to set the input to | +| attributes | object | false | HTML attributes (for example data attributes) to add to the input | + +## Options + +| Name | Type | Required | Description | +| ---------- | ------ | -------- | ------------------------------------------------ | +| regionCode | string | false | Sets the provided region code e.g. en-gb | +| adressType | string | false | Sets the provided address type e.g. resedential | +| oneYearAgo | string | false | If "true" will set a query parameter of epoch=75 | + +## AddressField + +| Name | Type | Required | Description | +| ---------- | ------------------------------------ | -------- | ------------------------------------ | +| id | string | false | ID for the field | +| name | string | false | Sets the name attribute on the field | +| label.text | string | true | The label for the input | +| value | string | false | The value for the input | +| error | `Error` [_(ref)_](/components/error) | false | Configuration for validation errors | diff --git a/src/components/address-finder/_macro.njk b/src/components/address-input/_macro.njk similarity index 50% rename from src/components/address-finder/_macro.njk rename to src/components/address-input/_macro.njk index 084af4739a..caeee09cc4 100644 --- a/src/components/address-finder/_macro.njk +++ b/src/components/address-input/_macro.njk @@ -2,11 +2,11 @@ {% from "components/autosuggest/_macro.njk" import onsAutosuggest %} {% from "components/input/_macro.njk" import onsInput %} -{% macro onsAddressFinder(params) %} +{% macro onsAddressInput(params) %} {% set fields %} -
- {% if params.isEditable == true %} -
+
+ {% if params.isEditable == true or params.manualEntry %} + {% if not params.manualEntry %}
{% endif %} {% if params.organisation is defined and params.organisation %} {{ onsInput({ @@ -72,67 +72,81 @@ }) }} {% endif %} - -
- {{ params.searchButton }} + {% if not params.manualEntry %} +
+ {{ params.searchButton }} +
-
+ {% endif %} {% endif %} + + {% if params.uprn is defined and params.uprn and params.uprn.value is defined and params.uprn.value %} + {% set uprnValue = params.uprn.value %} + {% else %} + {% set uprnValue = '' %} + {% endif %} + {{ onsInput({ "id": params.id + "-uprn", "classes": "js-hidden-uprn u-d-no", "type": "hidden", "name": params.id + "-uprn", - "value": params.uprn.value + "value": uprnValue }) }} - -
- {{ - onsAutosuggest({ - "id": params.id + "-autosuggest", - "classes": "address-input__autosuggest input--w-50 u-mb-no", - "label": { - "text": params.label.text, - "id": params.label.id, - "classes": "js-autosuggest-label" - }, - "externalInitialiser": true, - "APIDomain": params.APIDomain, - "APIDomainBearerToken": params.APIDomainBearerToken, - "allowMultiple": params.allowMultiple, - "mandatory": params.mandatory, - "instructions": params.instructions, - "autocomplete": params.autocomplete, - "isEditable": params.isEditable, - "ariaYouHaveSelected": params.ariaYouHaveSelected, - "ariaMinChars": params.ariaMinChars, - "ariaResultsLabel": params.ariaResultsLabel, - "ariaOneResult": params.ariaOneResult, - "ariaNResults": params.ariaNResults, - "ariaLimitedResults": params.ariaLimitedResults, - "ariaGroupedResults": params.ariaGroupedResults, - "groupCount": params.groupCount, - "moreResults": params.moreResults, - "tooManyResults": params.tooManyResults, - "resultsTitle": params.resultsTitle, - "noResults": params.noResults, - "typeMore": params.typeMore, - "errorTitle": params.errorTitle, - "errorMessageEnter": params.errorMessageEnter, - "errorMessageSelect": params.errorMessageSelect, - "errorMessageAPI": params.errorMessageAPI, - "errorMessageAPILinkText": params.errorMessageAPILinkText, - "options": params.options, - "manualLink": params.manualLink, - "manualLinkText": params.manualLinkText - }) - }} - {% if params.manualLinkText %} - {{ params.manualLinkText }} - {% endif %} -
+ {% if not params.manualEntry %} +
+ {{ + onsAutosuggest({ + "id": params.id + "-autosuggest", + "classes": "address-input__autosuggest input--w-50 u-mb-no", + "label": { + "text": params.label.text, + "id": params.label.id, + "classes": "js-autosuggest-label" + }, + "value": params.value, + "attributes": params.attributes, + "error": params.error, + "name": params.name, + "mutuallyExclusive": params.mutuallyExclusive, + "externalInitialiser": true, + "APIDomain": params.APIDomain, + "APIDomainBearerToken": params.APIDomainBearerToken, + "allowMultiple": params.allowMultiple, + "mandatory": params.mandatory, + "instructions": params.instructions, + "autocomplete": params.autocomplete, + "isEditable": params.isEditable, + "ariaYouHaveSelected": params.ariaYouHaveSelected, + "ariaMinChars": params.ariaMinChars, + "ariaResultsLabel": params.ariaResultsLabel, + "ariaOneResult": params.ariaOneResult, + "ariaNResults": params.ariaNResults, + "ariaLimitedResults": params.ariaLimitedResults, + "ariaGroupedResults": params.ariaGroupedResults, + "groupCount": params.groupCount, + "moreResults": params.moreResults, + "tooManyResults": params.tooManyResults, + "resultsTitle": params.resultsTitle, + "noResults": params.noResults, + "typeMore": params.typeMore, + "errorTitle": params.errorTitle, + "errorMessageEnter": params.errorMessageEnter, + "errorMessageSelect": params.errorMessageSelect, + "errorMessageAPI": params.errorMessageAPI, + "errorMessageAPILinkText": params.errorMessageAPILinkText, + "options": params.options, + "manualLink": params.manualLink, + "manualLinkText": params.manualLinkText + }) + }} + {% if params.manualLinkText %} + {{ params.manualLinkText }} + {% endif %} +
+ {% endif %}
{% endset %} diff --git a/src/components/address-input/_test-template.njk b/src/components/address-input/_test-template.njk new file mode 100644 index 0000000000..1175d22456 --- /dev/null +++ b/src/components/address-input/_test-template.njk @@ -0,0 +1,3 @@ +{% from "components/address-input/_macro.njk" import onsAddressInput %} + +{{ onsAddressInput(params) }} diff --git a/src/components/address-finder/autosuggest.address.dom.js b/src/components/address-input/autosuggest.address.dom.js similarity index 100% rename from src/components/address-finder/autosuggest.address.dom.js rename to src/components/address-input/autosuggest.address.dom.js diff --git a/src/components/address-finder/autosuggest.address.error.js b/src/components/address-input/autosuggest.address.error.js similarity index 100% rename from src/components/address-finder/autosuggest.address.error.js rename to src/components/address-input/autosuggest.address.error.js diff --git a/src/components/address-finder/autosuggest.address.js b/src/components/address-input/autosuggest.address.js similarity index 100% rename from src/components/address-finder/autosuggest.address.js rename to src/components/address-input/autosuggest.address.js diff --git a/src/components/address-finder/autosuggest.address.setter.js b/src/components/address-input/autosuggest.address.setter.js similarity index 100% rename from src/components/address-finder/autosuggest.address.setter.js rename to src/components/address-input/autosuggest.address.setter.js diff --git a/src/components/address-finder/examples/address-finder-editable/index.njk b/src/components/address-input/examples/address-input-editable/index.njk similarity index 95% rename from src/components/address-finder/examples/address-finder-editable/index.njk rename to src/components/address-input/examples/address-input-editable/index.njk index 1c2f6d28e3..c52ae22571 100644 --- a/src/components/address-finder/examples/address-finder-editable/index.njk +++ b/src/components/address-input/examples/address-input-editable/index.njk @@ -1,6 +1,6 @@ -{% from "components/address-finder/_macro.njk" import onsAddressFinder %} +{% from "components/address-input/_macro.njk" import onsAddressInput %} -{{ onsAddressFinder({ +{{ onsAddressInput({ "id": "address", "dontWrap": true, "label": { diff --git a/src/components/address-input/examples/address-input-manual/index.njk b/src/components/address-input/examples/address-input-manual/index.njk new file mode 100644 index 0000000000..e38cb92f35 --- /dev/null +++ b/src/components/address-input/examples/address-input-manual/index.njk @@ -0,0 +1,23 @@ +{% from "components/address-input/_macro.njk" import onsAddressInput %} + +{{ onsAddressInput({ + "id": "address", + "dontWrap": true, + "manualEntry": true, + "label": { + "text": "Enter address or postcode and select from results", + "id": "address-label" + }, + "line1": { + "label": "Address line 1" + }, + "line2": { + "label": "Address line 2" + }, + "town": { + "label": "Town or city" + }, + "postcode": { + "label": "Postcode" + } +}) }} \ No newline at end of file diff --git a/src/components/address-finder/examples/address-finder/index.njk b/src/components/address-input/examples/address-input/index.njk similarity index 95% rename from src/components/address-finder/examples/address-finder/index.njk rename to src/components/address-input/examples/address-input/index.njk index 4134ee886e..67f5d35d88 100644 --- a/src/components/address-finder/examples/address-finder/index.njk +++ b/src/components/address-input/examples/address-input/index.njk @@ -1,6 +1,6 @@ -{% from "components/address-finder/_macro.njk" import onsAddressFinder %} +{% from "components/address-input/_macro.njk" import onsAddressInput %} -{{ onsAddressFinder({ +{{ onsAddressInput({ "id": "address", "dontWrap": true, "label": { diff --git a/src/components/address-finder/index.njk b/src/components/address-input/index.njk similarity index 73% rename from src/components/address-finder/index.njk rename to src/components/address-input/index.njk index cf342182f0..588c3e079c 100644 --- a/src/components/address-finder/index.njk +++ b/src/components/address-input/index.njk @@ -1,28 +1,24 @@ --- -title: Address finder +title: Address input --- {% from "views/partials/example/_macro.njk" import patternlibExample %} {% from "components/external-link/_macro.njk" import onsExternalLink %} {% from "components/panel/_macro.njk" import onsPanel %} -The address finder component uses the ONS Address Index API to search for and return addresses. +The address input component allows users to search for and return addresses using the ONS Address Index API or to manually enter an address. ## When to use this component -Use the address finder when you need users to find and confirm a UK address. This could be their own or any other address that is required for the question. +Use the address input when you need users to find or enter and confirm an address. This could be their own or any other address that is required for the question. There is specific guidance on how to ask for [addresses](/patterns/addresses). -## When not to use this component +## How to use this component with the ONS Address Index API -Do not use this component if non-UK addresses are required for the question. +The address input extends the code base used for the [autosuggest component](/components/autosuggest). -## How to use this component - -The address finder extends the code base used for the [autosuggest component](/components/autosuggest). - -There are two main ways to use this component. Addresses can either be editable or non-editable. +There are two main ways to use this component with the ONS Address Index API. Addresses can either be editable or non-editable. ### Editable addresses @@ -33,7 +29,7 @@ When an address has been selected, the “mode” of the component will change t If the address is amended, the UPRN (unique ID) will be removed and not submitted. {{ - patternlibExample({"path": "components/address-finder/examples/address-finder-editable/index.njk"}) + patternlibExample({"path": "components/address-input/examples/address-input-editable/index.njk"}) }} ### Non-editable addresses @@ -44,7 +40,7 @@ The UPRN for the selected address is added to a hidden input field that will be {{ - patternlibExample({"path": "components/address-finder/examples/address-finder/index.njk"}) + patternlibExample({"path": "components/address-input/examples/address-input/index.njk"}) }} ### Using the API @@ -72,11 +68,19 @@ There is a status check when the page loads and initialises the component. If th If the API goes down during use of the component, the input is disabled and a warning needs to be shown under the address input field. The warning is configurable and should contain a message and a link, for example "Sorry, there is a problem. We are working to fix it. Please try again later or contact us for more help." +## How to use this component for manual address entry + +Include the parameter `manualEntry: true`. Note that there are other required parameters that can be viewed on the Nunjucks output of the example. + +{{ + patternlibExample({"path": "components/address-input/examples/address-input-manual/index.njk"}) +}} + ## Help improve this component Let us know how we could improve this component or share your user research findings. {{ onsExternalLink({ "url": "https://github.com/ONSdigital/design-system/discussions/894", - "linkText": "Discuss the ‘Address finder’ component on GitHub" + "linkText": "Discuss the ‘address input’ component on GitHub" }) }} diff --git a/src/components/autosuggest/_macro-options.md b/src/components/autosuggest/_macro-options.md index 2ee57934e3..52814253cb 100644 --- a/src/components/autosuggest/_macro-options.md +++ b/src/components/autosuggest/_macro-options.md @@ -1,15 +1,25 @@ -| Name | Type | Required | Description | -| ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------- | -| autosuggestData | string | true | URL of the JSON file with the autosuggest data that needs to be searched | -| allowMultiple | boolean | false | Allows the component to accept multiple selections | -| instructions | string | true | Instructions on how to use the autosuggest that will be read out by screenreaders | -| ariaYouHaveSelected | string | true | Aria message to tell the user that they have selected an answer | -| ariaMinChars | string | true | Aria message to tell the user how many charecters they need to enter before autosuggest will start | -| ariaResultsLabel | string | true | Aria message to tell the user that suggestions are available | -| ariaOneResult | string | true | Aria message to tell the user there is only one suggestion left | -| ariaNResults | string | true | Aria message to tell the user how many suggestions are left | -| moreResults | string | true | Aria message to tell the user to continue to type to refine suggestions | -| noResults | string | true | message to tell the user there are no results | -| tooManyResults | string | true | message to tell the user there are too many results to display and the user should refine the search | -| typeMore | string | true | message to encourage the user to enter more characters to get suggestions | -| resultsTitle | string | true | Title of results to be displayed on screen at the top of the results | +| Name | Type | Required | Description | +| ------------------- | ------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------- | +| autosuggestData | string | true | URL of the JSON file with the autosuggest data that needs to be searched | +| allowMultiple | boolean | false | Allows the component to accept multiple selections | +| instructions | string | true | Instructions on how to use the autosuggest that will be read out by screenreaders | +| ariaYouHaveSelected | string | true | Aria message to tell the user that they have selected an answer | +| ariaMinChars | string | true | Aria message to tell the user how many charecters they need to enter before autosuggest will start | +| ariaResultsLabel | string | true | Aria message to tell the user that suggestions are available | +| ariaOneResult | string | true | Aria message to tell the user there is only one suggestion left | +| ariaNResults | string | true | Aria message to tell the user how many suggestions are left | +| moreResults | string | true | Aria message to tell the user to continue to type to refine suggestions | +| noResults | string | true | message to tell the user there are no results | +| tooManyResults | string | true | message to tell the user there are too many results to display and the user should refine the search | +| typeMore | string | true | message to encourage the user to enter more characters to get suggestions | +| resultsTitle | string | true | Title of results to be displayed on screen at the top of the results | +| dontWrap | boolean | false | Prevents the input from being wrapped in a [field component](/components/field) | +| mutuallyExclusive | `MutuallyExclusive` [_(ref)_](/components/mutually-exclusive) | false | Configuration object if this is a mutually exclusive input | +| label | `Label` [_(ref)_](/components/label) | false | Settings for the input label. `for` will automatically be set to match the input id | +| classes | string | false | Classes to add to the input. | +| legend | string | Only if mutuallyExclusive is set | Text content for the legend | +| legendClasses | string | false | Classes for the legend | +| error | `Error` [_(ref)_](/components/error) | false | Configuration for validation errors | +| name | string | false | The name of the input | +| value | string | number | false | The value to set the input to | +| attributes | object | false | HTML attributes (for example data attributes) to add to the input | diff --git a/src/components/autosuggest/_macro.njk b/src/components/autosuggest/_macro.njk index 0ec8338c94..b9be445368 100644 --- a/src/components/autosuggest/_macro.njk +++ b/src/components/autosuggest/_macro.njk @@ -2,7 +2,7 @@ {% macro onsAutosuggest(params) %}
+ + {% set autosuggestResults %} +
+
{{ params.resultsTitle }}
+
    +
    +
    {{ params.instructions }}
    +
    + {% endset %} + {{ onsInput({ "id": params.id, - "classes": params.classes + " js-autosuggest-input", + "classes": "js-autosuggest-input " + (params.classes if params.classes else ''), "label": { "text": params.label.text, "description": params.label.description, "id": params.label.id, "classes": params.label.classes - } + }, + "legend": params.legend, + "legendClasses": params.legendClasses, + "value": params.value, + "attributes": params.attributes, + "error": params.error, + "mutuallyExclusive": params.mutuallyExclusive, + "name": params.name, + "autosuggestResults": autosuggestResults }) }} -
    -
    {{ params.resultsTitle }}
    -
      -
      -
      {{ params.instructions }}
      -
      + + {% if params.mutuallyExclusive is not defined %} + {{ autosuggestResults | safe }} + {% endif %}
      {% endmacro %} diff --git a/src/components/input/_macro.njk b/src/components/input/_macro.njk index 17d51045b0..7d1d60e6ba 100644 --- a/src/components/input/_macro.njk +++ b/src/components/input/_macro.njk @@ -135,7 +135,8 @@ "deselectMessage": params.mutuallyExclusive.deselectMessage, "deselectGroupAdjective": params.mutuallyExclusive.deselectGroupAdjective, "deselectCheckboxAdjective": params.mutuallyExclusive.deselectCheckboxAdjective, - "error": params.error + "error": params.error, + "autosuggestResults": params.autosuggestResults }) %} {% if charCheckField is defined and charCheckField %} {{ charCheckField | safe }} diff --git a/src/components/mutually-exclusive/_macro.njk b/src/components/mutually-exclusive/_macro.njk index 8d00ba97ae..c476f595a5 100644 --- a/src/components/mutually-exclusive/_macro.njk +++ b/src/components/mutually-exclusive/_macro.njk @@ -19,6 +19,9 @@ }) %}
      {{ content | safe }} + {% if params.autosuggestResults is defined and params.autosuggestResults %} + {{ params.autosuggestResults | safe }} + {% endif %}

      {{ diff --git a/src/js/index.js b/src/js/index.js index 0f8471729a..f668c6d161 100644 --- a/src/js/index.js +++ b/src/js/index.js @@ -14,7 +14,7 @@ import 'components/relationships/relationships.dom'; import 'components/checkboxes/checkboxes.dom'; import 'components/radios/radios.dom'; import 'components/autosuggest/autosuggest.dom'; -import 'components/address-finder/autosuggest.address.dom'; +import 'components/address-input/autosuggest.address.dom'; import 'components/input/character-check.dom'; import 'components/cookies-banner/cookies-banner.dom'; import 'components/button/button.dom'; diff --git a/src/patterns/addresses/examples/address-input-manual/index.njk b/src/patterns/addresses/examples/address-input-manual/index.njk new file mode 100644 index 0000000000..be3433cbe0 --- /dev/null +++ b/src/patterns/addresses/examples/address-input-manual/index.njk @@ -0,0 +1,49 @@ +--- +layout: none +--- +{% extends "styles/page-template/_template.njk" %} + +{% from "components/question/_macro.njk" import onsQuestion %} +{% from "components/address-input/_macro.njk" import onsAddressInput %} +{% from "components/button/_macro.njk" import onsButton %} + +{% set pageConfig = { + "title": "Autosuggest address example" +} %} +{% block main %} + {% call onsQuestion({ + "title": "What is your address?", + "legendIsQuestionTitle": true + }) %} + +

      + {{ onsAddressInput({ + "id": "address", + "dontWrap": true, + "manualEntry": true, + "label": { + "text": "Enter address or postcode and select from results", + "id": "address-label" + }, + "line1": { + "label": "Address line 1" + }, + "line2": { + "label": "Address line 2" + }, + "town": { + "label": "Town or city" + }, + "postcode": { + "label": "Postcode" + } + }) }} + {{ + onsButton({ + "text": 'Save and continue', + "classes": "u-mt-xl" + }) + }} +
      + {% endcall %} +{% endblock %} diff --git a/src/patterns/addresses/examples/address-finder-non-editable/index.njk b/src/patterns/addresses/examples/address-input-non-editable/index.njk similarity index 95% rename from src/patterns/addresses/examples/address-finder-non-editable/index.njk rename to src/patterns/addresses/examples/address-input-non-editable/index.njk index 888e152c45..58bc5e4406 100644 --- a/src/patterns/addresses/examples/address-finder-non-editable/index.njk +++ b/src/patterns/addresses/examples/address-input-non-editable/index.njk @@ -4,7 +4,7 @@ layout: none {% extends "styles/page-template/_template.njk" %} {% from "components/question/_macro.njk" import onsQuestion %} -{% from "components/address-finder/_macro.njk" import onsAddressFinder %} +{% from "components/address-input/_macro.njk" import onsAddressInput %} {% from "components/button/_macro.njk" import onsButton %} {% set pageConfig = { @@ -16,7 +16,7 @@ layout: none }) %}
      - {{ onsAddressFinder({ + {{ onsAddressInput({ "id": "address", "dontWrap": true, "label": { @@ -53,7 +53,7 @@ layout: none "regionCode": "gb-eng", "addressType": "residential" }, - "manualLink": "/patterns/addresses/examples/address-finder-non-editable/register-address", + "manualLink": "/patterns/addresses/examples/address-input-non-editable/register-address", "manualLinkText": "I can’t find my address" }) }} {{ diff --git a/src/patterns/addresses/examples/address-finder-non-editable/register-address/index.njk b/src/patterns/addresses/examples/address-input-non-editable/register-address/index.njk similarity index 84% rename from src/patterns/addresses/examples/address-finder-non-editable/register-address/index.njk rename to src/patterns/addresses/examples/address-input-non-editable/register-address/index.njk index bedaa55e34..c0dea6bc66 100644 --- a/src/patterns/addresses/examples/address-finder-non-editable/register-address/index.njk +++ b/src/patterns/addresses/examples/address-input-non-editable/register-address/index.njk @@ -4,7 +4,7 @@ layout: none {% extends "styles/page-template/_template.njk" %} {% from "components/question/_macro.njk" import onsQuestion %} -{% from "components/address-finder/_macro.njk" import onsAddressFinder %} +{% from "components/address-input/_macro.njk" import onsAddressInput %} {% from "components/button/_macro.njk" import onsButton %} {% set pageConfig = { @@ -13,7 +13,7 @@ layout: none "ariaLabel": 'Back', "itemsList": [ { - "url": '/patterns/addresses/examples/address-finder-non-editable', + "url": '/patterns/addresses/examples/address-input-non-editable', "id": 'back', "text": 'Back' } diff --git a/src/patterns/addresses/examples/address-finder/index.njk b/src/patterns/addresses/examples/address-input/index.njk similarity index 96% rename from src/patterns/addresses/examples/address-finder/index.njk rename to src/patterns/addresses/examples/address-input/index.njk index d13bae0fea..b4b3686c3a 100644 --- a/src/patterns/addresses/examples/address-finder/index.njk +++ b/src/patterns/addresses/examples/address-input/index.njk @@ -4,7 +4,7 @@ layout: none {% extends "styles/page-template/_template.njk" %} {% from "components/question/_macro.njk" import onsQuestion %} -{% from "components/address-finder/_macro.njk" import onsAddressFinder %} +{% from "components/address-input/_macro.njk" import onsAddressInput %} {% from "components/button/_macro.njk" import onsButton %} {% set pageConfig = { @@ -17,7 +17,7 @@ layout: none }) %} - {{ onsAddressFinder({ + {{ onsAddressInput({ "id": "address", "dontWrap": true, "label": { diff --git a/src/patterns/addresses/index.njk b/src/patterns/addresses/index.njk index caf4ec6b69..e7e6ee2782 100644 --- a/src/patterns/addresses/index.njk +++ b/src/patterns/addresses/index.njk @@ -8,24 +8,34 @@ group: Ask users for... ## When to use this pattern -This pattern should be used when you need to collect an address from a user using the [address finder component](/components/address-finder) inside a form. +This pattern should be used when you need to collect an address from a user using the [address input component](/components/address-input) inside a form. -## How to use this pattern +## How to use this pattern to search for addresses -There are two main ways to use this pattern. Addresses can either be [editable](/components/address-finder#editable-addresses) or [non-editable](/components/address-finder#non-editable-addresses). Look at the nunjucks output in both examples below to see how they are configured using the `onsAddressFinder` macro. +There are three ways to use this pattern. Addresses can either be [editable](/components/address-input#editable-addresses), [non-editable](/components/address-input#non-editable-addresses) or [manual](/components/address-input#how-to-use-this-component-for-manual-address-entry). Look at the nunjucks output in the examples below to see how they are configured using the `onsAddressInput` macro. -The pattern examples below will use client side validation against a set of [validation rules](/components/address-finder#validation). ### Editable address pattern example -The manual address inputs are wrapped within a [fieldset](/components/fieldset) and legend. If used within an `onsQuestion` macro you can pass `legendIsQuestionTitle: true` along with `dontWrap: true` to the `onsAddressFinder` macro. +The manual address inputs are wrapped within a [fieldset](/components/fieldset) and legend. If used within an `onsQuestion` macro you can pass `legendIsQuestionTitle: true` along with `dontWrap: true` to the `onsAddressInput` macro. + +The pattern example below will use client side validation against a set of [validation rules](/components/address-input#validation). {{ - patternlibExample({"path": "patterns/addresses/examples/address-finder/index.njk"}) + patternlibExample({"path": "patterns/addresses/examples/address-input/index.njk"}) }} ### Non-editable address pattern example +The pattern example below will use client side validation against a set of [validation rules](/components/address-input#validation). + +{{ + patternlibExample({"path": "patterns/addresses/examples/address-input-non-editable/index.njk"}) +}} + +### Manual address pattern example +The manual address inputs are wrapped within a [fieldset](/components/fieldset) and legend. If used within an `onsQuestion` macro you can pass `legendIsQuestionTitle: true` along with `dontWrap: true` to the `onsAddressInput` macro. + {{ - patternlibExample({"path": "patterns/addresses/examples/address-finder-non-editable/index.njk"}) + patternlibExample({"path": "patterns/addresses/examples/address-input-manual/index.njk"}) }} ## Help improve this pattern diff --git a/src/tests/spec/autosuggest/autosuggest.address.spec.js b/src/tests/spec/autosuggest/autosuggest.address.spec.js index 43ea3caacb..f830bd4e72 100644 --- a/src/tests/spec/autosuggest/autosuggest.address.spec.js +++ b/src/tests/spec/autosuggest/autosuggest.address.spec.js @@ -1,9 +1,9 @@ import { awaitPolyfills } from 'js/polyfills/await-polyfills'; -import template from 'components/address-finder/_test-template.njk'; +import template from 'components/address-input/_test-template.njk'; import '../../../scss/main.scss'; -import AutosuggestAddress from '../../../components/address-finder/autosuggest.address'; -import AddressError from '../../../components/address-finder/autosuggest.address.error'; -import AddressSetter from '../../../components/address-finder/autosuggest.address.setter'; +import AutosuggestAddress from '../../../components/address-input/autosuggest.address'; +import AddressError from '../../../components/address-input/autosuggest.address.error'; +import AddressSetter from '../../../components/address-input/autosuggest.address.setter'; import eventMock from 'stubs/event.stub.spec'; import fetchStub from 'stubs/window.fetch.stub.spec'; @@ -844,6 +844,7 @@ describe('Autosuggest.address component', function() { const paramsOptions = { id: 'address', externalInitialiser: true, + isEditable: false, APIDomain: 'https://whitelodge-ai-api.census-gcp.onsdigital.uk', options: { regionCode: 'gb-eng', @@ -890,6 +891,7 @@ describe('Autosuggest.address component', function() { const paramsOptions = { id: 'address', APIDomain: 'https://whitelodge-ai-api.census-gcp.onsdigital.uk', + isEditable: false, externalInitialiser: true, options: { regionCode: 'gb-nir', @@ -935,6 +937,7 @@ describe('Autosuggest.address component', function() { const paramsOptions = { id: 'address', APIDomain: 'https://whitelodge-ai-api.census-gcp.onsdigital.uk', + isEditable: false, externalInitialiser: true, options: { regionCode: 'gb-nir', @@ -993,6 +996,7 @@ describe('Autosuggest.address component', function() { const paramsOptions = { id: 'address', APIDomain: 'https://whitelodge-ai-api.census-gcp.onsdigital.uk', + isEditable: false, externalInitialiser: true, options: { regionCode: 'gb-wls',