@financial-times/o-autocomplete 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.7.0](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.6.2...o-autocomplete-v1.7.0) (2022-09-14)
+
+
+### Features
+
+* autocomplete, add a `defaultValue` for a default input value ([#812](https://www.github.com/Financial-Times/origami/issues/812)) ([70a77ae](https://www.github.com/Financial-Times/origami/commit/70a77ae218c9c19967fe3bb32c18206d7cd9c2c3))
+
 ### [1.6.2](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.6.1...o-autocomplete-v1.6.2) (2022-04-21)
 
 

package/README.md

@@ -43,7 +43,7 @@ To provide a static set of suggestions, we recommend using a `select` element. o
 
 ### For a dynamic set of suggestions
 
-To provide a dynamic set of suggestions, you will need to provide a javascript function or name of a javascript function on the window object which follows the [dynamic-suggestions-function](dynamic-suggestions-function) <abbr title="application programming interface">API</abbr>.
+To provide a dynamic set of suggestions, provide a javascript function or name of a javascript function on the window object which follows the [dynamic-suggestions-function](#dynamic-suggestions-function) <abbr title="application programming interface">API</abbr>.
 
 The input element requires an `id` attribute, this is used within the component to implement the accessibility features.
 ```html
@@ -56,12 +56,12 @@ The input element requires an `id` attribute, this is used within the component
 
 To have styling for labels, you will need to use [o-forms](https://registry.origami.ft.com/components/o-forms) as part of the autocomplete implementation.
 
-Below is an example of how to combine o-forms and o-autocomplete components together:
+Below is an example of how to combine o-forms and o-autocomplete components together. Note the `label` and `select` element are connected using `for` and `id` attributes.
 ```html
-<label class="o-forms-field" >
-    <span class="o-forms-title">
+<span class="o-forms-field" >
+    <label for="my-autocomplete" class="o-forms-title">
         <span class="o-forms-title__main">Select your country</span>
-    </span>
+    </label>
     <span class="o-forms-input o-forms-input--select">
         <span data-o-component="o-autocomplete" class="o-autocomplete">
             <select id="my-autocomplete">
@@ -70,7 +70,7 @@ Below is an example of how to combine o-forms and o-autocomplete components toge
             </select>
         </span>
     </span>
-</label>
+</span>
 ```
 ## Sass
 
@@ -101,7 +101,6 @@ import oAutocomplete from 'o-autocomplete';
 const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
 new oAutocomplete(oAutocompleteElement);
 ```
-
 ### dynamic suggestions function
 
 #### Example
@@ -111,7 +110,7 @@ import oAutocomplete from 'o-autocomplete';
 
 /**
  * @callback PopulateOptions
- * @param {Array<*>} options - The options which match the rext which was typed into the autocomplete by the user
+ * @param {Array<*>} options - The options which match the text which was typed into the autocomplete by the user
  * @returns {void}
  */
 /**
@@ -237,6 +236,13 @@ new oAutocomplete(oAutocompleteElement, {
 | --- | --- | --- |
 | option | <code>\*</code> | The option the user selected |
 
+#### `defaultValue` (default: `''`)
+
+Type: `string`
+
+If setting a default input value for a [dynamic set of suggestions](for-a-dynamic-set-of-suggestions) set the `defaultValue` option.
+
+_When progressively enhancing a [static set of suggestions](#for-a-static-set-of-suggestions) set a default value using HTML, by providing an appropriate `option` element._
 
 ## Keyboard Support
 

package/demos/src/dynamic/dynamic.mustache

@@ -1,14 +1,14 @@
 <form data-o-component="o-forms">
-    <label class="o-forms-field">
+    <div class="o-forms-field">
         <span class="o-forms-title">
-            <span class="o-forms-title__main">Select your country</span>
+            <label for="my-autocomplete" class="o-forms-title__main">Select your country</label>
         </span>
         <span class="o-forms-input o-forms-input--text">
-            <span data-o-component="o-autocomplete" data-o-autocomplete-source="customSuggestions" class="o-autocomplete">
+            <span data-o-component="o-autocomplete" data-o-autocomplete-default-value="United Kingdom" data-o-autocomplete-source="customSuggestions" class="o-autocomplete">
                 <!-- If the JavaScript executes, then this input will be progressively enhanced to an autocomplete component -->
                 <input required type="text" name="text-example" id="my-autocomplete">
             </span>
-            <span class="o-forms-input__error">Please fill out this field</span>
+            <span role="alert" class="o-forms-input__error">Please fill out this field</span>
         </span>
-    </label>
+    </div>
 </form>

package/demos/src/dynamic-complex/dynamic-complex.js

@@ -13,13 +13,19 @@ oForms.init();
  */
 
 /**
- * @param {CustomOption|undefined} option - The option to transform into a suggestion string
+ * @param {CustomOption} option - The option to transform into a suggestion string
  * @returns {string} The string to display in the suggestions dropdown for this option
  */
 function mapOptionToSuggestedValue(option) {
-	if (option) {
-		return option.Country_Name;
+	if (typeof option !== 'object') {
+		throw new Error(`Could not map option to suggested value, unexpected type: ${typeof option}.`);
 	}
+
+	if (typeof option.Country_Name !== 'string') {
+		throw new Error(`Could not map option to suggested value, option.Country_Name is not a string`);
+	}
+
+	return option.Country_Name;
 }
 
 /**
@@ -56,6 +62,7 @@ function customSuggestions(query, populateOptions) {
 new Autocomplete(document.querySelector('[data-o-component="o-autocomplete"]'), {
 	source: customSuggestions,
 	mapOptionToSuggestedValue,
+	defaultValue: data.find((d) => d['Two_Letter_Country_Code'] === 'GB')?.Country_Name,
 	onConfirm: function (option) {
 		// eslint-disable-next-line no-console
 		console.log('You chose option', option);

package/demos/src/dynamic-complex/dynamic-complex.mustache

@@ -1,14 +1,14 @@
 <form data-o-component="o-forms">
-    <label class="o-forms-field">
+    <div class="o-forms-field">
         <span class="o-forms-title">
-            <span class="o-forms-title__main">Select your country</span>
+            <label for="my-autocomplete" class="o-forms-title__main">Select your country</label>
         </span>
         <span class="o-forms-input o-forms-input--text">
             <span data-o-component="o-autocomplete" class="o-autocomplete">
                 <!-- If the JavaScript executes, then this input will be progressively enhanced to an autocomplete component -->
                 <input required type="text" name="text-example" id="my-autocomplete">
             </span>
-            <span class="o-forms-input__error">Please fill out this field</span>
+            <span role="alert" class="o-forms-input__error">Please fill out this field</span>
         </span>
-    </label>
+    </div>
 </form>

package/demos/src/dynamic-delayed/dynamic-delayed.mustache

@@ -1,14 +1,14 @@
 <form data-o-component="o-forms">
-    <label class="o-forms-field">
+    <div class="o-forms-field">
         <span class="o-forms-title">
-            <span class="o-forms-title__main">Select your country</span>
+            <label for="my-autocomplete" class="o-forms-title__main">Select your country</label>
         </span>
         <span class="o-forms-input o-forms-input--text">
             <span data-o-component="o-autocomplete" data-o-autocomplete-source="customSuggestions" class="o-autocomplete">
                 <!-- If the JavaScript executes, then this input will be progressively enhanced to an autocomplete component -->
                 <input required type="text" name="text-example" id="my-autocomplete">
             </span>
-            <span class="o-forms-input__error">Please fill out this field</span>
+            <span role="alert" class="o-forms-input__error">Please fill out this field</span>
         </span>
-    </label>
+    </div>
 </form>

package/demos/src/static/static.mustache

@@ -1,6 +1,6 @@
-<label class="o-forms-field">
+<div class="o-forms-field">
     <span class="o-forms-title">
-        <span class="o-forms-title__main">Select your country</span>
+        <label for="my-autocomplete" class="o-forms-title__main">Select your country</label>
     </span>
     {{! o-forms styles for select input needed for the core experience }}
     {{! o-forms styles for text input needed for the enhances JS experience }}
@@ -267,4 +267,4 @@
             </select>
         </span>
     </span>
-</label>
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@financial-times/o-autocomplete",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "An origami component for autocomplete inputs",
   "keywords": [
     "autocomplete",
@@ -22,7 +22,8 @@
   "scripts": {
     "build": "bash ../../scripts/component/build.bash",
     "test": "bash ../../scripts/component/test.bash",
-    "lint": "bash ../../scripts/component/lint.bash"
+    "lint": "bash ../../scripts/component/lint.bash",
+    "watch": "bash ../../scripts/component/watch.bash"
   },
   "engines": {
     "npm": "^7 || ^8"

package/src/js/autocomplete.js

@@ -173,6 +173,7 @@ function initClearButton(instance) {
 
 /**
  * @typedef {object} AutocompleteOptions
+ * @property {string} [defaultValue] - Specify a string to prefill the autocomplete with
  * @property {Source} [source] - The function which retrieves the suggestions to display
  * @property {MapOptionToSuggestedValue} [mapOptionToSuggestedValue] - Function which transforms a suggestion before rendering
  * @property {onConfirm} [onConfirm] - Function which is called when the user selects an option
@@ -192,6 +193,7 @@ class Autocomplete {
 		this.options = {};
 		if (opts.source) {
 			this.options.source = opts.source;
+			this.options.defaultValue = opts.defaultValue;
 		}
 		if (opts.mapOptionToSuggestedValue) {
 			this.options.mapOptionToSuggestedValue = opts.mapOptionToSuggestedValue;
@@ -250,6 +252,7 @@ class Autocomplete {
 			if (!id) {
 				throw new Error("Missing `id` attribute on the o-autocomplete input. An `id` needs to be set as it is used within the o-autocomplete to implement the accessibility features.");
 			}
+
 			this.autocompleteEl.innerHTML = '';
 			this.autocompleteEl.appendChild(this.container);
 			accessibleAutocomplete({
@@ -266,16 +269,17 @@ class Autocomplete {
 				source: this.options.source,
 				cssNamespace: 'o-autocomplete',
 				displayMenu: 'overlay',
+				defaultValue: this.options.defaultValue || '',
 				showNoOptionsFound: false,
 				templates: {
 					/**
 					 * Used when rendering suggestions, the return value of this will be used as the innerHTML for a single suggestion.
 					 *
 					 * @param {*} option The suggestion to apply the template with.
-					 * @returns {string} HTML string to represent a single suggestion.
+					 * @returns {string|undefined} HTML string to represent a single suggestion.
 					 */
 					suggestion: (option) => {
-						if (typeof option !== 'undefined') {
+						if (typeof option === 'object') {
 							// If the `mapOptionToSuggestedValue` function is defined
 							// Apply the function to the option. This is a way for the
 							// consuming application to decide what text should be
@@ -285,21 +289,23 @@ class Autocomplete {
 							// which should be used as the suggestion string.
 							if (typeof this.mapOptionToSuggestedValue === 'function') {
 								option = this.mapOptionToSuggestedValue(option);
-							} else if (typeof option !== 'string') {
-								throw new Error(`The option trying to be displayed as a suggestion is not a string, it is "${typeof option}". o-autocomplete can only display strings as suggestions. Define a \`mapOptionToSuggestedValue\` function to convert the option into a string to be used as the suggestion.`);
 							}
 						}
 
+						if (typeof option !== 'string' && typeof option !== 'undefined') {
+							throw new Error(`The option trying to be displayed as a suggestion is not a string, it is "${typeof option}". o-autocomplete can only display strings as suggestions. Define a \`mapOptionToSuggestedValue\` function to convert the option into a string to be used as the suggestion.`);
+						}
+
 						return this.suggestionTemplate(option);
 					},
 					/**
 					 * Used when a suggestion is selected, the return value of this will be used as the value for the input element.
 					 *
 					 * @param {*} option The suggestion which was selected.
-					 * @returns {string} String to represent the suggestion.
+					 * @returns {string|undefined} String to represent the suggestion.
 					 */
 					inputValue: (option) => {
-						if (typeof option !== 'undefined') {
+						if (typeof option === 'object') {
 							// If the `mapOptionToSuggestedValue` function is defined
 							// Apply the function to the option. This is a way for the
 							// consuming application to decide what text should be
@@ -309,11 +315,13 @@ class Autocomplete {
 							// which should be used as the suggestion string.
 							if (typeof this.mapOptionToSuggestedValue === 'function') {
 								option = this.mapOptionToSuggestedValue(option);
-							} else if (typeof option !== 'string') {
-								throw new Error(`The option trying to be displayed as a suggestion is not a string, it is "${typeof option}". o-autocomplete can only display strings as suggestions. Define a \`mapOptionToSuggestedValue\` function to convert the option into a string to be used as the suggestion.`);
 							}
 						}
 
+						if (typeof option !== 'string' && typeof option !== 'undefined') {
+							throw new Error(`The option trying to be displayed as a suggestion is not a string, it is "${typeof option}". o-autocomplete can only display strings as suggestions. Define a \`mapOptionToSuggestedValue\` function to convert the option into a string to be used as the suggestion.`);
+						}
+
 						return option;
 					}
 				}
@@ -338,6 +346,8 @@ class Autocomplete {
 					}
 				},
 				autoselect: false,
+				// To fallback with JS an enhanced element's default value should
+				// be set using static html.
 				defaultValue: '',
 				placeholder: '',
 				cssNamespace: 'o-autocomplete',
@@ -362,10 +372,11 @@ class Autocomplete {
 	 */
 	suggestionTemplate (suggestedValue) {
 		// o-autocomplete has a UI design to highlight characters in the suggestions.
+		const input = this.autocompleteEl.querySelector('input');
 		/**
 		 * @type {CharacterHighlight[]} An array of arrays which contain two items, the first is the character in the suggestion, the second is a boolean which indicates whether the character should be highlighted.
 		 */
-		const characters = highlightSuggestion(suggestedValue, this.autocompleteEl.querySelector('input').value);
+		const characters = highlightSuggestion(suggestedValue, input ? input.value : suggestedValue);
 
 		let output = '';
 		for (const [character, shoudHighlight] of characters) {
@@ -395,7 +406,8 @@ class Autocomplete {
 
 		if (autocompleteEl.dataset.oAutocompleteSource) {
 			return {
-				source: autocompleteEl.dataset.oAutocompleteSource
+				source: autocompleteEl.dataset.oAutocompleteSource,
+				defaultValue: autocompleteEl.dataset.oAutocompleteDefaultValue
 			};
 		} else {
 			return {};