MDL-79629 forms: Improvements to autocomplete form element

- Preserve autocomplete input options classes to the autocomplete suggestions
- Add new styles for suggestions headings
- Add a new class selector form-autocomplete-input so input can be easily selected
  for styling.

Various improvements to make the module more re-usable elsewhere:
change event bubbling, promise argument support when enhancing.

Co-authored-by: Paul Holden <paulh@moodle.com>

lib/amd/src/form-autocomplete.js

@@ -203,7 +203,7 @@ define([
 
         // Note, jQuery .change() was not working here. Better to
         // use plain JavaScript anyway.
-        originalSelect[0].dispatchEvent(new Event('change'));
+        originalSelect[0].dispatchEvent(new Event('change', {bubbles: true}));
     };
 
     /**
@@ -367,6 +367,7 @@ define([
                     label: label,
                     value: $(ele).attr('value'),
                     disabled: ele.disabled,
+                    classes: ele.classList,
                 });
             }
         });
@@ -1110,25 +1111,25 @@ define([
          * @param {string} ajax Name of an AMD module to handle ajax requests. If specified, the AMD
          *                      module must expose 2 functions "transport" and "processResults".
          *                      These are modeled on Select2 see: https://select2.github.io/options.html#ajax
-         * @param {String} placeholder - The text to display before a selection is made.
+         * @param {String|Promise<string>} placeholder - The text to display before a selection is made.
          * @param {Boolean} caseSensitive - If search has to be made case sensitive.
          * @param {Boolean} showSuggestions - If suggestions should be shown
-         * @param {String} noSelectionString - Text to display when there is no selection
+         * @param {String|Promise<string>} noSelectionString - Text to display when there is no selection
          * @param {Boolean} closeSuggestionsOnSelect - Whether to close the suggestions immediately after making a selection.
          * @param {Object} templateOverrides A set of templates to use instead of the standard templates
          * @return {Promise}
          */
-        enhance: function(selector, tags, ajax, placeholder, caseSensitive, showSuggestions, noSelectionString,
+        enhance: async function(selector, tags, ajax, placeholder, caseSensitive, showSuggestions, noSelectionString,
                           closeSuggestionsOnSelect, templateOverrides) {
             // Set some default values.
             var options = {
                 selector: selector,
                 tags: false,
                 ajax: false,
-                placeholder: placeholder,
+                placeholder: await placeholder,
                 caseSensitive: false,
                 showSuggestions: true,
-                noSelectionString: noSelectionString,
+                noSelectionString: await noSelectionString,
                 templates: $.extend({
                         input: 'core/form_autocomplete_input',
                         items: 'core/form_autocomplete_selection_items',

lib/form/upgrade.txt

@@ -1,6 +1,11 @@
 This files describes API changes in core_form libraries and APIs,
 information provided here is intended especially for developers.
 
+=== 4.4 ===
+
+* Now autocomplete suggestions will preserve classes defined in respective original "option" elements
+  Alongside with that new ".suggestions-heading" class was added to easily generate suggestion headings
+
 === 4.3 ===
 
 * Added a new parameter to allow Groups to add attributes.

lib/templates/form_autocomplete_input.mustache

@@ -36,7 +36,7 @@
     { "inputID": 1, "suggestionsId": 2, "selectionId": 3, "downArrowId": 4, "placeholder": "Select something" }
 }}
 {{#showSuggestions}}
-<div class="d-md-inline-block mr-md-2 position-relative">
+<div class="form-autocomplete-input d-md-inline-block mr-md-2 position-relative">
     <input type="text"{{!
     }} id="{{inputId}}"{{!
     }} class="form-control"{{!
@@ -56,7 +56,7 @@
 </div>
 {{/showSuggestions}}
 {{^showSuggestions}}
-<div class="d-md-inline-block mr-md-2">
+<div class="form-autocomplete-input d-md-inline-block mr-md-2">
     <input type="text"{{!
     }} id="{{inputId}}"{{!
     }} class="form-control"{{!

lib/templates/form_autocomplete_suggestions.mustache

@@ -38,6 +38,13 @@
 }}
 <ul class="form-autocomplete-suggestions" id="{{suggestionsId}}" role="listbox" aria-label="{{#str}}suggestions, form{{/str}}" aria-hidden="true" tabindex="-1">
     {{#options}}
-        <li role="option" data-value="{{value}}"{{#disabled}} aria-disabled="true"{{/disabled}}>{{{label}}}</li>
+        <li
+            role="option"
+            data-value="{{value}}"
+            {{#disabled}}aria-disabled="true"{{/disabled}}
+            {{#classes}}class="{{{classes}}}"{{/classes}}
+        >
+            {{{label}}}
+        </li>
     {{/options}}
 </ul>

theme/boost/scss/moodle/forms.scss

@@ -306,6 +306,13 @@ fieldset.coursesearchbox label {
         color: $custom-select-disabled-color;
         background-color: $custom-select-disabled-bg;
     }
+    &.suggestions-heading {
+        pointer-events: none;
+        font-weight: bold;
+        color: $body-color;
+        background-color: $body-bg;
+        padding-left: calc(#{$dropdown-item-padding-x} / 2);
+    }
     &::before {
         content: "\200B";
     }

theme/boost/style/moodle.css

@@ -33289,6 +33289,13 @@ fieldset.coursesearchbox label {
   color: #6a737b;
   background-color: #e9ecef;
 }
+.form-autocomplete-suggestions li.suggestions-heading {
+  pointer-events: none;
+  font-weight: bold;
+  color: #1d2125;
+  background-color: #fff;
+  padding-left: calc(1.5rem / 2);
+}
 .form-autocomplete-suggestions li::before {
   content: "​";
 }

theme/classic/style/moodle.css

@@ -33289,6 +33289,13 @@ fieldset.coursesearchbox label {
   color: #6a737b;
   background-color: #e9ecef;
 }
+.form-autocomplete-suggestions li.suggestions-heading {
+  pointer-events: none;
+  font-weight: bold;
+  color: #1d2125;
+  background-color: #fff;
+  padding-left: calc(1.5rem / 2);
+}
 .form-autocomplete-suggestions li::before {
   content: "​";
 }