@financial-times/o-autocomplete 1.9.1 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.10.0](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.9.2...o-autocomplete-v1.10.0) (2024-04-19)
+
+
+### Features
+
+* Enable highlighting of custom suggestions ([#1516](https://github.com/Financial-Times/origami/issues/1516)) ([c326099](https://github.com/Financial-Times/origami/commit/c3260998c4a8926f875e7ba95134b230ca517669))
+
+## [1.9.2](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.9.1...o-autocomplete-v1.9.2) (2024-04-12)
+
+
+### Bug Fixes
+
+* Update financial-times/accessible-autocomplete ([#1524](https://github.com/Financial-Times/origami/issues/1524)) ([8bcd024](https://github.com/Financial-Times/origami/commit/8bcd02402f3fa50e35756d3eb2a22b10435d634b))
+
 ## [1.9.1](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.9.0...o-autocomplete-v1.9.1) (2023-10-27)
 
 

package/README.md

@@ -98,7 +98,7 @@ Or pass an element to initialise a specific `o-autocomplete` instance:
 
 ```js
 import oAutocomplete from 'o-autocomplete';
-const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
+const oAutocompleteElement = document.getElementById('my-o-autocomplete-element');
 new oAutocomplete(oAutocompleteElement);
 ```
 ### dynamic suggestions function
@@ -123,7 +123,7 @@ async function customSuggestions(query, populateOptions) {
 	populateOptions(suggestions);
 }
 
-const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
+const oAutocompleteElement = document.getElementById('my-o-autocomplete-element');
 new oAutocomplete(oAutocompleteElement, {
     source: customSuggestions
 });
@@ -176,7 +176,7 @@ function mapOptionToSuggestedValue(option) {
 	return option.suggestionText;
 }
 
-const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
+const oAutocompleteElement = document.getElementById('my-o-autocomplete-element');
 new oAutocomplete(oAutocompleteElement, {
     mapOptionToSuggestedValue,
     source: customSuggestions,
@@ -221,7 +221,7 @@ function onConfirm(option) {
     console.log('You selected option: ', option);
 }
 
-const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
+const oAutocompleteElement = document.getElementById('my-o-autocomplete-element');
 new oAutocomplete(oAutocompleteElement, {
     onConfirm
     mapOptionToSuggestedValue,
@@ -236,10 +236,14 @@ This function is used to override the default rendering of suggestion items, wit
 
 It is typically used when wanting to provide additional context or styling for each suggestion item.
 
+The `query` value (text which was typed into the autocomplete text input field by the user) is provided so that it can be used as a basis for highlighting the `option` value (or one of its values if it is an object).
+
 :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
 
+Providing additional context by displaying multiple `option` properties:
+
 ```js
 import oAutocomplete from 'o-autocomplete';
 
@@ -250,6 +254,7 @@ async function customSuggestions(query, populateOptions) {
 
 /**
  * @param {{"name": string, "role": string}} option - The option to transform into a suggestion
+ * @param {string} [query] - Text which was typed into the autocomplete text input field by the user
  * @returns {string} The HTML to render in the suggestion list*/
 function suggestionTemplate(option) {
 	return `
@@ -260,7 +265,61 @@ function suggestionTemplate(option) {
 	`;
 }
 
-const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
+const oAutocompleteElement = document.getElementById('my-o-autocomplete-element');
+new oAutocomplete(oAutocompleteElement, {
+    suggestionTemplate,
+    source: customSuggestions,
+});
+```
+
+Using the `query` value to apply highlighting to one of the `option` properties:
+
+```js
+import oAutocomplete from 'o-autocomplete';
+
+async function customSuggestions(query, populateOptions) {
+    const suggestions = await getSuggestions(query);
+    populateOptions(suggestions);
+}
+
+function highlightSuggestion(suggestion, query) {
+    const result = suggestion.split('');
+
+    const matchIndex = suggestion.toLocaleLowerCase().indexOf(query.toLocaleLowerCase());
+    return result.map(function(character, index) {
+        let shouldHighlight = true;
+        const hasMatched = matchIndex > -1;
+        const characterIsWithinMatch = index >= matchIndex && index <= matchIndex + query.length - 1;
+        if (hasMatched && characterIsWithinMatch) {
+            shouldHighlight = false;
+        }
+        return [character, shouldHighlight];
+    });
+}
+
+/**
+ * @param {{"name": string, "role": string}} option - The option to transform into a suggestion
+ * @param {string} [query] - Text which was typed into the autocomplete text input field by the user
+ * @returns {string} The HTML to render in the suggestion list*/
+function suggestionTemplate(option, query) {
+    const characters = highlightSuggestion(option.name, query || option.name);
+
+    let output = '';
+    for (const [character, shoudHighlight] of characters) {
+        if (shoudHighlight) {
+            output += `<span class="o-autocomplete__option--highlight">${character}</span>`;
+        } else {
+            output += `${character}`;
+        }
+    }
+    output += ` (${option.role})`;
+    const span = document.createElement('span');
+    span.setAttribute('aria-label', option.name);
+    span.innerHTML = output;
+    return span.outerHTML;
+}
+
+const oAutocompleteElement = document.getElementById('my-o-autocomplete-element');
 new oAutocomplete(oAutocompleteElement, {
     suggestionTemplate,
     source: customSuggestions,
@@ -274,7 +333,8 @@ new oAutocomplete(oAutocompleteElement, {
 
 | Param | Type | Description |
 | --- | --- | --- |
-| option | <code>\*</code> | The option to transform into a suggestio  |
+| option | <code>\*</code> | The option to transform into a suggestion  |
+| query | <code>string</code> | Text which was typed into the autocomplete text input field by the user  |
 
 ### onConfirm
 
@@ -305,7 +365,7 @@ function onConfirm(option) {
     console.log('You selected option: ', option);
 }
 
-const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
+const oAutocompleteElement = document.getElementById('my-o-autocomplete-element');
 new oAutocomplete(oAutocompleteElement, {
     onConfirm
     mapOptionToSuggestedValue,