@financial-times/o-autocomplete 1.7.4 → 1.8.1

package/demos/src/dynamic-custom-suggestion/dynamic-custom-suggestion.js

@@ -0,0 +1,83 @@
+import Autocomplete from '../../../main.js';
+import {data} from './data.js';
+import oForms from '@financial-times/o-forms';
+oForms.init();
+/**
+ * @typedef {object} CustomOption
+ * @property {string} Continent_Code - 2 letter continent code
+ * @property {string} Continent_Name - name of continent
+ * @property {string} Country_Name - name of country
+ * @property {number} Country_Number - id of country
+ * @property {string} Three_Letter_Country_Code - three letter country code
+ * @property {string} Two_Letter_Country_Code - two letter country code
+ */
+
+/**
+ * @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 (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;
+}
+/**
+ * @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 suggestionTemplate(option) {
+	if(typeof option === 'string') return option;
+	return `<div>
+		<strong>${option.Country_Name}</strong>
+		<span> </span>
+		<em>${option.Continent_Name}</em>
+	</div>`
+}
+
+/**
+ * @typedef {Function} PopulateOptions
+ * @property {Array<string>} options - The options which match the rext which was typed into the autocomplete by the user
+ */
+
+/**
+ * @param {string} query - Text which was typed into the autocomplete by the user
+ * @param {PopulateOptions} populateOptions - Function to call when ready to update the suggestions dropdown
+ * @returns {void}
+ */
+function customSuggestions(query, populateOptions) {
+	const suggestions = data;
+
+	if (!query) {
+		populateOptions([]);
+		return;
+	}
+	suggestions.sort(function(a,b) {
+		return a.Country_Name.localeCompare(b.Country_Name);
+	});
+
+	const filteredOptions = [];
+	for (const suggestion of suggestions) {
+		const lowercaseSuggestion = suggestion.Country_Name.toLocaleLowerCase();
+		if (lowercaseSuggestion.startsWith(query.toLocaleLowerCase())) {
+			filteredOptions.push(suggestion);
+		}
+	}
+	populateOptions(filteredOptions);
+}
+
+new Autocomplete(document.querySelector('[data-o-component="o-autocomplete"]'), {
+	source: customSuggestions,
+	suggestionTemplate,
+	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-custom-suggestion/dynamic-custom-suggestion.mustache

@@ -0,0 +1,14 @@
+<form data-o-component="o-forms">
+    <div class="o-forms-field">
+        <span class="o-forms-title">
+            <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 role="alert" class="o-forms-input__error">Please fill out this field</span>
+        </span>
+    </div>
+</form>

package/origami.json

@@ -53,6 +53,14 @@
 			"js": "demos/src/dynamic-complex/dynamic-complex.js",
 			"hidden": true
 		},
+		{
+			"title": "Autocomplete with custom suggestion items",
+			"name": "dynamic-custom-suggestions",
+			"template": "demos/src/dynamic-custom-suggestion/dynamic-custom-suggestion.mustache",
+			"description": "The source function returns objects and the suggestionTemplate transforms the objects into custom HTML suggestions",
+			"js": "demos/src/dynamic-custom-suggestion/dynamic-custom-suggestion.js",
+			"hidden": true
+		},
 		{
 			"title": "Pa11y",
 			"name": "pa11y",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@financial-times/o-autocomplete",
-  "version": "1.7.4",
+  "version": "1.8.1",
   "description": "An origami component for autocomplete inputs",
   "keywords": [
     "autocomplete",
@@ -38,7 +38,7 @@
     "@financial-times/o-loading": "^5.0.0",
     "@financial-times/o-normalise": "^3.3.0",
     "@financial-times/o-spacing": "^3.0.0",
-    "@financial-times/o-typography": "^7.0.1",
+    "@financial-times/o-typography": "^7.4.1",
     "@financial-times/o-visual-effects": "^4.0.1"
   },
   "devDependencies": {

package/src/js/autocomplete.js

@@ -171,12 +171,19 @@ function initClearButton(instance) {
  * @returns {void}
  */
 
+/**
+ * @callback SuggestionTemplate
+ * @param {*} option - The option to render
+ * @returns {string} The html string to render for this suggestion.
+ */
+
 /**
  * @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 {MapOptionToSuggestedValue} [mapOptionToSuggestedValue] - Function which transforms a suggestion before rendering.
  * @property {onConfirm} [onConfirm] - Function which is called when the user selects an option
+ * @property {SuggestionTemplate} [suggestionTemplate] - Function to override how a suggestion item is rendered.
  */
 
 class Autocomplete {
@@ -201,6 +208,9 @@ class Autocomplete {
 		if (opts.onConfirm) {
 			this.options.onConfirm = opts.onConfirm;
 		}
+		if (opts.suggestionTemplate) {
+			this.options.suggestionTemplate = opts.suggestionTemplate;
+		}
 
 		const container = document.createElement('div');
 		container.classList.add('o-autocomplete__listbox-container');
@@ -279,6 +289,11 @@ class Autocomplete {
 					 * @returns {string|undefined} HTML string to represent a single suggestion.
 					 */
 					suggestion: (option) => {
+						// If the suggestionTemplate override option is provided,
+						// use that to render the suggestion.
+						if(typeof this.options.suggestionTemplate === 'function') {
+							return this.options.suggestionTemplate(option);
+						}
 						if (typeof option === 'object') {
 							// If the `mapOptionToSuggestedValue` function is defined
 							// Apply the function to the option. This is a way for the