Focus element linked to from skip link to fix VoiceOver announcements

When user activates the skip link, Mac VoiceOver currently does not announce the main content or continue reading
from it.

To improve the experience for Mac VoiceOver users:
- make the main content element focusable by adding a `tabindex` attribute
- move focus to it programmatically
- override the native focus outline to none whilst `tabindex` is present
- remove the `tabindex` attribute and the style override on blur

This follows the pattern we already use in the error summary and notification banner components.

There also seems to be an improvement to the announcements on JAWS (both with Chrome and IE11).

See #2187 (comment) for more details and the full testing results.

src/govuk/all.test.js

@@ -53,6 +53,7 @@ describe('GOV.UK Frontend', () => {
         'ErrorSummary',
         'Header',
         'Radios',
+        'SkipLink',
         'Tabs'
       ])
     })

src/govuk/components/skip-link/_index.scss

@@ -31,4 +31,17 @@
       }
     }
   }
+
+  .govuk-skip-link-focused-element {
+    &:focus {
+      // Remove the native visible focus indicator when the element is programmatically focused.
+      //
+      // We set the focus on the linked element (this is usually the <main> element) when the skip
+      // link is activated to improve screen reader announcements. However, we remove the visible
+      // focus indicator from the linked element because the user cannot interact with it.
+      //
+      // A related discussion: https://github.com/w3c/wcag/issues/1001
+      outline: none;
+    }
+  }
 }

src/govuk/components/skip-link/skip-link.js

@@ -1,3 +1,7 @@
+import '../../vendor/polyfills/Function/prototype/bind'
+import '../../vendor/polyfills/Element/prototype/classList'
+import '../../vendor/polyfills/Event' // addEventListener and event.target normalization
+
 function SkipLink ($module) {
   this.$module = $module
 }
@@ -11,6 +15,79 @@ SkipLink.prototype.init = function () {
   if (!$module) {
     return
   }
+
+  $module.addEventListener('click', this.handleClick.bind(this))
+}
+
+/**
+* Click event handler
+*
+* @param {MouseEvent} event - Click event
+*/
+SkipLink.prototype.handleClick = function (event) {
+  var target = event.target
+
+  if (this.focusLinkedElement(target)) {
+    event.preventDefault()
+  }
+}
+
+/**
+ * Focus the linked element
+ *
+ * @param {HTMLElement} $target - Event target
+ * @returns {boolean} True if the linked element was able to be focussed
+ */
+SkipLink.prototype.focusLinkedElement = function ($target) {
+  // If the element that was clicked does not have a href, return early
+  if ($target.href === false) {
+    return false
+  }
+
+  var linkedElementId = this.getFragmentFromUrl($target.href)
+  var $linkedElement = document.getElementById(linkedElementId)
+  if (!$linkedElement) {
+    return false
+  }
+
+  if (!$linkedElement.getAttribute('tabindex')) {
+    // Set the content tabindex to -1 so it can be focused with JavaScript.
+    $linkedElement.setAttribute('tabindex', '-1')
+    $linkedElement.classList.add('govuk-skip-link-focused-element')
+
+    $linkedElement.addEventListener('blur', this.removeFocusProperties.bind(this, $linkedElement))
+  }
+  $linkedElement.focus()
+}
+
+/**
+ * Remove the tabindex that makes the linked element focusable because the content only needs to be
+ * focusable until it has received programmatic focus and a screen reader has announced it.
+ *
+ * Remove the CSS class that removes the native focus styles.
+ *
+ * @param {HTMLElement} $linkedElement - DOM element linked to from the skip link
+ */
+SkipLink.prototype.removeFocusProperties = function ($linkedElement) {
+  $linkedElement.removeAttribute('tabindex')
+  $linkedElement.classList.remove('govuk-skip-link-focused-element')
+}
+
+/**
+ * Get fragment from URL
+ *
+ * Extract the fragment (everything after the hash) from a URL, but not including
+ * the hash.
+ *
+ * @param {string} url - URL
+ * @returns {string} Fragment from URL, without the hash
+ */
+SkipLink.prototype.getFragmentFromUrl = function (url) {
+  if (url.indexOf('#') === -1) {
+    return false
+  }
+
+  return url.split('#').pop()
 }
 
 export default SkipLink

src/govuk/components/skip-link/skip-link.test.js

@@ -0,0 +1,50 @@
+/* eslint-env jest */
+
+const configPaths = require('../../../../config/paths.json')
+const PORT = configPaths.ports.test
+
+const baseUrl = 'http://localhost:' + PORT
+
+describe('/examples/template-default', () => {
+  describe('skip link', () => {
+    beforeAll(async () => {
+      await page.goto(`${baseUrl}/examples/template-default`, { waitUntil: 'load' })
+      await page.keyboard.press('Tab')
+      await page.keyboard.press('Enter')
+    })
+
+    it('focuses the linked element', async () => {
+      const activeElement = await page.evaluate(() => document.activeElement.id)
+
+      expect(activeElement).toBe('main-content')
+    })
+
+    it('adds the tabindex attribute to the linked element', async () => {
+      const tabindex = await page.$eval('.govuk-main-wrapper', el => el.getAttribute('tabindex'))
+
+      expect(tabindex).toBe('-1')
+    })
+
+    it('adds the class for removing the native focus style to the linked element', async () => {
+      const cssClass = await page.$eval('.govuk-main-wrapper', el => el.classList.contains('govuk-skip-link-focused-element'))
+
+      expect(cssClass).toBeTruthy()
+    })
+
+    it('removes the tabindex attribute from the linked element on blur', async () => {
+      await page.$eval('.govuk-main-wrapper', el => el.blur())
+
+      const tabindex = await page.$eval('.govuk-main-wrapper', el => el.getAttribute('tabindex'))
+
+      expect(tabindex).toBeNull()
+    })
+
+    it('removes the class for removing the native focus style from the linked element on blur', async () => {
+      await page.$eval('.govuk-main-wrapper', el => el.blur())
+
+      const cssClass = await page.$eval('.govuk-main-wrapper', el => el.getAttribute('class'))
+
+      expect(cssClass).not.toContain('govuk-skip-link-focused-element')
+    })
+  })
+})

src/govuk/components/skip-link/template.test.js

@@ -76,5 +76,13 @@ describe('Skip link', () => {
       expect($component.attr('data-test')).toEqual('attribute')
       expect($component.attr('aria-label')).toEqual('Skip to content')
     })
+
+    it('renders a data-module attribute to initialise JavaScript', () => {
+      const $ = render('skip-link', examples.default)
+
+      const $component = $('.govuk-skip-link')
+
+      expect($component.attr('data-module')).toEqual('govuk-skip-link')
+    })
   })
 })