@financial-times/o-autocomplete - npm Package Compare versions

Comparing version 1.7.4 to 1.8.0

CHANGELOG.md

 # Changelog
 
+## [1.8.0](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.7.4...o-autocomplete-v1.8.0) (2023-05-30)
+
+
+### Features
+
+* autocomplete, add a suggestionTemplate override option ([23e1397](https://www.github.com/Financial-Times/origami/commit/23e1397deb29034faaf009c16e41ab169dcc3a42))
+
 ### [1.7.4](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.7.3...o-autocomplete-v1.7.4) (2023-04-28)
@@ -4,0 +11,0 @@

origami.json

@@ -57,2 +57,10 @@ {
 		{
+			"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",
@@ -59,0 +67,0 @@ "name": "pa11y",

package.json

 {
   "name": "@financial-times/o-autocomplete",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "description": "An origami component for autocomplete inputs",
@@ -5,0 +5,0 @@ "keywords": [

README.md

@@ -160,2 +160,3 @@ # o-autocomplete
 
+
 #### Example
@@ -232,2 +233,86 @@
 
+
+### suggestionTemplate
+
+This function is used to override the default rendering of suggestion items, with a function that returns a custom HTML string for the given option.
+
+It is typically used when wanting to provide additional context or styling for each suggestion item.
+
+:warning: **Caution:** because this function allows you to output arbitrary HTML, you should [make sure it's trusted](https://en.wikipedia.org/wiki/Cross-site_scripting), and accessible. The HTML will be output within listbox options, so [ensure all descendants are presentational](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/option_role#all_descendants_are_presentational).
+
+#### Example
+
+```js
+import oAutocomplete from 'o-autocomplete';
+
+async function customSuggestions(query, populateOptions) {
+	const suggestions = await getSuggestions(query);
+	populateOptions(suggestions);
+}
+
+/**
+ * @param {{"name": string, "role": string}} option - The option to transform into a suggestion
+ * @returns {string} The HTML to render in the suggestion list*/
+function suggestionTemplate(option) {
+	return `
+		<div>
+			<strong>${option.name}</strong>
+			<em>${option.role}</em>
+		</div>
+	`;
+}
+
+const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
+new oAutocomplete(oAutocompleteElement, {
+    suggestionTemplate,
+    source: customSuggestions,
+});
+```
+
+<a name="SuggestionTemplate"></a>
+
+#### SuggestionTemplate ⇒ <code>string</code>
+**Returns**: <code>string</code> - The HTML string to render as the suggestion for this option
+
+| Param | Type | Description |
+| --- | --- | --- |
+| option | <code>\*</code> | The option to transform into a suggestio  |
+
+### onConfirm
+
+This function is called when the user selects an option and is called with the option the user selected.
+
+#### Example
+
+```js
+import oAutocomplete from 'o-autocomplete';
+
+async function customSuggestions(query, populateOptions) {
+	const suggestions = await getSuggestions(query);
+	populateOptions(suggestions);
+}
+
+/**
+ * @param {{"suggestionText": string}} option - The option to transform into a suggestion string
+ * @returns {string} The string to display as the suggestions for this option
+*/
+function mapOptionToSuggestedValue(option) {
+	return option.suggestionText;
+}
+
+/**
+ * @param {{"suggestionText": string}} option - The option the user selected
+*/
+function onConfirm(option) {
+    console.log('You selected option: ', option);
+}
+
+const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
+new oAutocomplete(oAutocompleteElement, {
+    onConfirm
+    mapOptionToSuggestedValue,
+    source: customSuggestions,
+});
+```
+
 <a name="onConfirm"></a>
@@ -234,0 +319,0 @@

src/js/autocomplete.js

@@ -175,7 +175,14 @@ // We use our own fork of accessible-autocomplete because the main package is not being actively maintained and has bugs which we needed to fix
 /**
+ * @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.
  */
@@ -205,2 +212,5 @@
 		}
+		if (opts.suggestionTemplate) {
+			this.options.suggestionTemplate = opts.suggestionTemplate;
+		}
 
@@ -284,2 +294,7 @@ const container = document.createElement('div');
 					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') {
@@ -286,0 +301,0 @@ // If the `mapOptionToSuggestedValue` function is defined

No alert changes

Improved metrics

Total package byte prevSize

177997

increased by48.67%

Number of package files

23

increased by15%

Lines of code

5420

increased by68.06%

Number of lines in readme file

373

increased by29.51%

No dependency changes