search by label + test coverage

Closes #3245726

src/a11y.autocomplete.js

@@ -65,10 +65,41 @@ import Combobox from './combobox.js';
  * Options sent to the Autocomplete constructor that will override the default
  * options.
  * @typedef {Object} A11yAutocomplete~Options
- * @property {Array|string|A11yAutocomplete~sourceCallback} [source] - An array or a string containing
- *  JSON that parses into an array of values to search when the user types in
- *  the input field, or a function to take what the user types and call a
- *  callback function with the results to be displayed.
+ * @property {Array|string|A11yAutocomplete~sourceCallback} [source] -  The data
+ * the autocomplete searches, which can be provided in multiple ways
+ * - An array of strings: `[ "First choice", "Second Choice", ... ]`
+ * - An array of objects. All objects must have either a 'label' or 'value'
+ *   property: `[ { label: "First Choice", value: "First Value" }, ... ]`
+ *   The label property is displayed in the suggestion list, and is what the
+ *   autocomplete process searches. The value property is what is inserted into
+ *   the input element when an item is selected. If just one property (value or
+ *   label) is specified, it will be used for both, e.g., if only 'value' is
+ *   provided, it will also be used as the label.
+ *   Note that these objects can have additional properties beyond 'label' and
+ *   'value', but at least one of those two properties must be present for the
+ *   autocomplete to work.
+ *  - A string of valid JSON that can be parsed into an array of strings or an
+ *    array of objects (i.e. either of the array options listed above).
+ * - A callback function with two arguments:
+ *     - searchTerm: the string the autocomplete is searching for.
+ *     - processResults: a callback function that sends the search results
+ *       to for rendering. This function accepts a single argument that should
+ *       either be an array of strings or an array of objects with value and/or
+ *       label properties.
+ *  ```
+ *    // Example querying an endpoint that provides JSON.
+ *    source: (searchTerm, processResults) => {
+ *        // Query the remote source
+ *        fetch(`https://an-endpoint/?q=${searchTerm}`)
+ *           .then((response) => {
+ *             return response.json();
+ *           })
+ *           .then((results) => {
+ *             // Use the callback to send the results to the
+ *             processResults(results);
+ *           });
+ *    },
+ *  ```
  * @property {string|null} [allowRepeatValues=null] - If `true`,
  *  autocomplete results can include items already included in the field. A null
  *  value functions the same as false, but a null value can be used to determine
@@ -714,7 +745,7 @@ class _A11yAutocomplete {
    */
   filterResults(suggestion, typed) {
     const { firstCharacterIgnoreList, cardinality } = this.options;
-    const suggestionValue = suggestion.value;
+    const suggestionLabel = suggestion.label;
     const currentValues = this.splitValues();
 
     // Prevent suggestions if the first input character is in the ignore list,
@@ -723,7 +754,7 @@ class _A11yAutocomplete {
     if (
       firstCharacterIgnoreList.indexOf(typed[0]) !== -1 ||
       (cardinality > 0 && currentValues.length > cardinality) ||
-      (currentValues.indexOf(suggestionValue) !== -1 &&
+      (currentValues.indexOf(suggestionLabel) !== -1 &&
         !this.options.allowRepeatValues)
     ) {
       return false;
@@ -734,7 +765,7 @@ class _A11yAutocomplete {
         .trim()
         .replace(/[-\\^$*+?.()|[\]{}]/g, '\\$&'),
       'i',
-    ).test(suggestionValue);
+    ).test(suggestionLabel);
   }
 
   /**