[Accessibility] Adds support for an accessible "clear" button (#53)

inkblotty · web-flow · commit e9bfd148d1c4 · 2021-12-17T09:34:32.000-06:00
If an element with &lt;input-id&gt;-clear is detected in the autocomplete, clicking that button will:

clear the associated input
focus back on the input (a11y)
announce that the input has been cleared (a11y)
diff --git a/README.md b/README.md
@@ -28,7 +28,15 @@ With a script tag:
 
 ```html
 <auto-complete src="/users/search" for="users-popup">
-  <input type="text">
+  <input type="text" name="users">
+  <!--
+    Optional clear button:
+    - id must match the id of the input or the name of the input plus "-clear"
+    - recommended to be *before* UL elements to avoid conflicting with their blur logic
+    
+    Please see Note below on this button for more details
+  -->
+  <button id="users-clear">X</button>
   <ul id="users-popup"></ul>
   <!--
     Optional div for screen reader feedback. Note the ID matches the ul, but with -feedback appended.
@@ -61,6 +69,12 @@ item whose display text needs to be different:
 <li role="option" data-autocomplete-value="bb8">BB-8 (astromech)</li>
 ```
 
+### A Note on Clear button
+While `input type="search"` comes with an `x` that clears the content of the field and refocuses it on many browsers, the implementation for this control is not keyboard accessible, and so we've opted to enable a customizable clear button so that your keyboard users will be able to interact with it.
+
+As an example:
+> In Chrome, this 'x' isn't a button but a div with a pseudo="-webkit-search-cancel-button". It doesn't have a tab index or a way to navigate to it without a mouse. Additionally, this control is only visible on mouse hover.
+
 ## Attributes
 
 - `open` is true when the auto-complete result list is visible
diff --git a/examples/index.html b/examples/index.html
@@ -39,11 +39,13 @@
   </head>
   <body>
     <form>
-      <label id="robots-label">Robots</label>
+      <label id="robots-label" for="robot">Robots</label>
       <!-- To enable auto-select (select first on Enter), use data-autoselect="true" -->
       <auto-complete src="/demo" for="items-popup" aria-labelledby="robots-label" data-autoselect="true">
         <input name="robot" type="text" aria-labelledby="robots-label" autofocus>
-        <ul id="items-popup" aria-labelledby="robots-label"></ul>
+        <!-- if a clear button is passed in, recommended to be *before* UL elements to avoid conflicting with their blur logic -->
+        <button id="robot-clear">x</button>
+        <ul id="items-popup"></ul>
         <!-- For built-in screen-reader announcements:
           - Note the ID is the same as the <ul> with "feedback" appended
           - Also note that aria attributes will be added programmatically if they aren't set correctly  
@@ -53,12 +55,30 @@
       <button type="submit">Save</button>
     </form>
 
+    <!-- example where clear button uses input id -->
+    <form>
+      <label id="robots-a-label" for="robot-a">Robots (using Input ID)</label>
+      <!-- To enable auto-select (select first on Enter), use data-autoselect="true" -->
+      <auto-complete src="/demo" for="items-a-popup" aria-labelledby="robots-a-label" data-autoselect="true">
+        <input id="robot-a" name="robot-a" type="text" aria-labelledby="robots-a-label" autofocus>
+        <!-- if a clear button is passed in, recommended to be *before* UL elements to avoid conflicting with their blur logic -->
+        <button id="robot-a-clear">x</button>
+        <ul id="items-a-popup"></ul>
+        <!-- For built-in screen-reader announcements:
+          - Note the ID is the same as the <ul> with "feedback" appended
+          - Also note that aria attributes will be added programmatically if they aren't set correctly  
+        -->
+        <div id="items-a-popup-feedback" class="sr-only"></div>
+      </auto-complete>
+      <button type="submit">Save</button>
+    </form>
+
     <!-- example without autoselect -->
     <form>
-      <label id="robots-2-label">Robots 2</label>
+      <label id="robots-2-label" for="robot-2">Robots (without autoselect on enter)</label>
       <auto-complete src="/demo" for="items-2-popup" aria-labelledby="robots-2-label" >
-        <input name="robot" type="text" aria-labelledby="robots-2-label" autofocus>
-        <ul id="items-2-popup" aria-labelledby="robots-2-label"></ul>
+        <input name="robot-2" type="text" aria-labelledby="robots-2-label" autofocus>
+        <ul id="items-2-popup"></ul>
         <div id="items-2-popup-feedback" class="sr-only"></div>
       </auto-complete>
       <button type="submit">Save</button>
diff --git a/src/autocomplete.ts b/src/autocomplete.ts
@@ -15,6 +15,7 @@ export default class Autocomplete {
   feedback: HTMLElement | null
   autoselectEnabled: boolean
   clientOptions: NodeListOf<HTMLElement> | null
+  clearButton: HTMLElement | null
 
   interactingWithList: boolean
 
@@ -30,17 +31,32 @@ export default class Autocomplete {
     this.combobox = new Combobox(input, results)
     this.feedback = document.getElementById(`${this.results.id}-feedback`)
     this.autoselectEnabled = autoselectEnabled
+    this.clearButton = document.getElementById(`${this.input.id || this.input.name}-clear`)
 
     // check to see if there are any default options provided
     this.clientOptions = results.querySelectorAll('[role=option]')
 
     // make sure feedback has all required aria attributes
     if (this.feedback) {
-      this.feedback.setAttribute('aria-live', 'assertive')
+      this.feedback.setAttribute('aria-live', 'polite')
       this.feedback.setAttribute('aria-atomic', 'true')
     }
 
+    // if clearButton doesn't have an accessible label, give it one
+    if (this.clearButton && !this.clearButton.getAttribute('aria-label')) {
+      const labelElem = document.querySelector(`label[for="${this.input.name}"]`)
+      this.clearButton.setAttribute('aria-label', `clear:`)
+      this.clearButton.setAttribute('aria-labelledby', `${this.clearButton.id} ${labelElem?.id || ''}`)
+    }
+
+    // initialize with the input being expanded=false
+    if (!this.input.getAttribute('aria-expanded')) {
+      this.input.setAttribute('aria-expanded', 'false')
+    }
+
     this.results.hidden = true
+    // @jscholes recommends a generic "results" label as the results are already related to the combobox, which is properly labelled
+    this.results.setAttribute('aria-label', 'results')
     this.input.setAttribute('autocomplete', 'off')
     this.input.setAttribute('spellcheck', 'false')
 
@@ -52,13 +68,15 @@ export default class Autocomplete {
     this.onInputFocus = this.onInputFocus.bind(this)
     this.onKeydown = this.onKeydown.bind(this)
     this.onCommit = this.onCommit.bind(this)
+    this.handleClear = this.handleClear.bind(this)
 
     this.input.addEventListener('keydown', this.onKeydown)
     this.input.addEventListener('focus', this.onInputFocus)
     this.input.addEventListener('blur', this.onInputBlur)
     this.input.addEventListener('input', this.onInputChange)
     this.results.addEventListener('mousedown', this.onResultsMouseDown)
     this.results.addEventListener('combobox-commit', this.onCommit)
+    this.clearButton?.addEventListener('click', this.handleClear)
   }
 
   destroy(): void {
@@ -70,6 +88,21 @@ export default class Autocomplete {
     this.results.removeEventListener('combobox-commit', this.onCommit)
   }
 
+  handleClear(event: Event): void {
+    event.preventDefault()
+
+    if (this.input.getAttribute('aria-expanded') === 'true') {
+      this.input.setAttribute('aria-expanded', 'false')
+      this.updateFeedbackForScreenReaders('Results hidden.')
+    }
+
+    this.input.value = ''
+    this.container.value = ''
+    this.input.focus()
+    this.input.dispatchEvent(new Event('change'))
+    this.container.open = false
+  }
+
   onKeydown(event: KeyboardEvent): void {
     // if autoselect is enabled, Enter key will select the first option
     if (event.key === 'Enter' && this.container.open && this.autoselectEnabled) {
@@ -120,7 +153,7 @@ export default class Autocomplete {
     this.container.value = value
 
     if (!value) {
-      this.updateFeedbackForScreenReaders(`Suggestions hidden.`)
+      this.updateFeedbackForScreenReaders(`Results hidden.`)
     }
   }
 
@@ -175,15 +208,15 @@ export default class Autocomplete {
         const hasResults = !!allNewOptions.length
         const numOptions = allNewOptions.length
 
-        // inform SR users of which element is "on-deck" so that it's clear what Enter will do
         const [firstOption] = allNewOptions
         const firstOptionValue = firstOption?.textContent
         if (this.autoselectEnabled && firstOptionValue) {
+          // inform SR users of which element is "on-deck" so that it's clear what Enter will do
           this.updateFeedbackForScreenReaders(
-            `${numOptions} suggested options. Press Enter to select ${firstOptionValue}.`
+            `${numOptions} results. ${firstOptionValue} is the top result: Press Enter to activate.`
           )
         } else {
-          this.updateFeedbackForScreenReaders(`${numOptions} suggested options.`)
+          this.updateFeedbackForScreenReaders(`${numOptions || 'No'} results.`)
         }
 
         this.container.open = hasResults
diff --git a/test/test.js b/test/test.js
@@ -89,7 +89,7 @@ describe('auto-complete element', function () {
       await once(container, 'loadend')
       await waitForElementToChange(feedback)
 
-      assert.equal('5 suggested options.', feedback.innerHTML)
+      assert.equal('5 results.', feedback.innerHTML)
     })
 
     it('commits on Enter', async function () {
@@ -196,6 +196,39 @@ describe('auto-complete element', function () {
     })
   })
 
+  describe('clear button provided', () => {
+    it('clears the input value on click and gives focus back to the input', async () => {
+      document.body.innerHTML = `
+        <div id="mocha-fixture">
+          <auto-complete src="/search" for="popup" data-autoselect="true">
+            <input id="example" type="text">
+            <button id="example-clear">x</button>
+            <ul id="popup"></ul>
+            <div id="popup-feedback"></div>
+          </auto-complete>
+        </div>
+      `
+
+      const container = document.querySelector('auto-complete')
+      const input = container.querySelector('input')
+      const clearButton = document.getElementById('example-clear')
+      const feedback = container.querySelector(`#popup-feedback`)
+
+      triggerInput(input, 'hub')
+      await once(container, 'loadend')
+
+      assert.equal(input.value, 'hub')
+      await waitForElementToChange(feedback)
+
+      clearButton.click()
+      assert.equal(input.value, '')
+      assert.equal(container.value, '')
+      await waitForElementToChange(feedback)
+      assert.equal('Results hidden.', feedback.innerHTML)
+      assert.equal(document.activeElement, input)
+    })
+  })
+
   describe('autoselect enabled', () => {
     beforeEach(function () {
       document.body.innerHTML = `
@@ -218,7 +251,7 @@ describe('auto-complete element', function () {
       await once(container, 'loadend')
       await waitForElementToChange(feedback)
 
-      assert.equal(`5 suggested options. Press Enter to select first.`, feedback.innerHTML)
+      assert.equal(`5 results. first is the top result: Press Enter to activate.`, feedback.innerHTML)
     })
   })
 })
