Merge bitzesty:select-behavior from alphagov#467

Author: jeremyZX

README.md

@@ -367,6 +367,9 @@ This will:
 
 - Place an autocomplete input field after the specified `<select>`
 - Default the autocomplete `autoselect` to `true`
+- Default the autocomplete `preserveNullOptions` to `true`
+- Default the autocomplete `showAllValues` to `true`
+- Default the autocomplete `confirmOnBlur` to `true`
 - Default the autocomplete `defaultValue` to the select's `option[selected]`
 - Default the autocomplete `id` to the `<select>`'s `id`
 - Default the autocomplete `name` attribute to `''` to prevent it being included in form submissions
@@ -377,7 +380,7 @@ This will:
 
 This function takes the same options as `accessibleAutocomplete`, with the only difference being that it uses `selectElement` instead of `element`, which needs to be an instance of `HTMLSelectElement`.
 
-> **Note**: The `accessibleAutocomplete.enhanceSelectElement` function is fairly light and wraps the public API for `accessibleAutocomplete`. If your use case doesn't fit the above defaults, try [reading the source](src/wrapper.js) and seeing if you can write your own.
+> **Note**: The `accessibleAutocomplete.enhanceSelectElement` function wraps the public API for `accessibleAutocomplete` to provide sensible defaults that mimic the behaviour expected from select dropdowns. It will also internally adjust the autocomplete to behave more like a select than an autocomplete. If your use case doesn't fit the above defaults, try [reading the source](src/wrapper.js) and seeing if you can write your own.
 
 ### Null options
 
@@ -405,6 +408,32 @@ accessibleAutocomplete.enhanceSelectElement({
 
 Any null options will also be filtered out of the options used to populate the `source` of the autocomplete element. To preserve options with no value in the autocomplete, then pass a `preserveNullOptions` flag of `true` to `enhanceSelectElement`.
 
+
+### Programmatic API
+
+> **Note**: the programmatic API is still a work in progress. If a function you need programmatically is not available, feel free to raise an issue or send a Pull Request for it.
+
+Autoselects normally react to the selection of the user automatically. However, when enhancing a select, it is often desirable to have some programmatic control over the selection.
+
+The programmatic API is only exposed for enhanced selects, and contains the following functions:
+
+##### `clearSelection()`
+
+This function will clear the selection and trigger the `change` event on the select element being enhanced.
+
+Example usage:
+
+```js
+var select = document.querySelector(".to-be-enhanced");
+accessibleAutocomplete.enhanceSelectElement({
+  selectElement: select
+});
+
+select.accessibleAutocomplete.clearSelection();
+
+```
+
+
 ## Analytics and tracking
 
 The following events get triggered on the input element during the life cycle of the autocomplete:

dist/accessible-autocomplete.min.css

@@ -128,16 +128,38 @@ <h3>Progressive enhancement</h3>
         This example demonstrates how to turn a server-rendered <code>&lt;select&gt;</code> element
         into a autocomplete. Turn off JavaScript to see the <code>&lt;select&gt;</code> element.
       </p>
+      <p>
+        It should have sensible defaults and keyboard interactions that mimic the browser native select.
+      </p>
       <p>Uses <code>accessibleAutocomplete.enhanceSelectElement</code>.</p>
       <label for="autocomplete-progressiveEnhancement">Country</label>
       <div class="autocomplete-wrapper">
         <select id="autocomplete-progressiveEnhancement">
+          <option value="">Please select a country</option>
           <option value="fr">France</option>
           <option value="de">Germany</option>
           <option value="gb" selected>United Kingdom</option>
         </select>
       </div>
 
+      <h3>Programmatic API for enhanced select (Work in progress)</h3>
+      <p>
+        This example demonstrates how you can use the programmatic API to perform actions from code.
+      </p>
+      <p>Uses <code>accessibleAutocomplete.enhanceSelectElement</code>.</p>
+
+      <h5>clearSelection()</h5>
+      <label for="autocomplete-progressiveEnhancement-api-clearselection">Select your country</label>
+      <div class="autocomplete-wrapper">
+        <select id="autocomplete-progressiveEnhancement-api-clearselection">
+          <option value="">Please select a country</option>
+          <option value="fr">France</option>
+          <option value="de" selected>Germany</option>
+          <option value="gb">United Kingdom</option>
+        </select>
+        <button class="clear-selection">Clear</button>
+      </div>
+
       <h3>Custom results</h3>
       <p>
         <p>This example demonstrates how to allow users to search for a country by either:</p>
@@ -486,6 +508,21 @@ <h3>Translating texts</h3>
       })
     </script>
 
+    <script type="text/javascript">
+      let clearableSelect = element = document.querySelector('#autocomplete-progressiveEnhancement-api-clearselection')
+      accessibleAutocomplete.enhanceSelectElement({
+        selectElement: clearableSelect,
+        placeholder: "Select a country"
+      })
+
+      document.querySelector(".clear-selection").addEventListener("click", function(e) {
+        e.preventDefault();
+        e.stopPropagation();
+
+        clearableSelect.accessibleAutocomplete.clearSelection();
+      })
+    </script>
+
     <script type="text/javascript">
       function customSuggest (query, syncResults) {
         var results = [

dist/accessible-autocomplete.min.js

@@ -39,13 +39,13 @@
 }
 
 .autocomplete__dropdown-arrow-down{
-  z-index: -1;
   display: inline-block;
   position: absolute;
   right: 8px;
   width: 24px;
   height: 24px;
   top: 10px;
+  pointer-events: none;
 }
 
 .autocomplete__menu {