From f370df2ceefe04caa49eddca67ad277e3461f357 Mon Sep 17 00:00:00 2001 From: Hanna Date: Mon, 29 Nov 2021 17:18:52 +0000 Subject: [PATCH 1/4] Initialise skip link JavaScript with `data-module` --- src/govuk/all.js | 6 ++++++ src/govuk/components/skip-link/skip-link.js | 16 ++++++++++++++++ src/govuk/components/skip-link/template.njk | 2 +- 3 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 src/govuk/components/skip-link/skip-link.js diff --git a/src/govuk/all.js b/src/govuk/all.js index 3759d2c242..9f5ed0c0cb 100644 --- a/src/govuk/all.js +++ b/src/govuk/all.js @@ -8,6 +8,7 @@ import ErrorSummary from './components/error-summary/error-summary' import NotificationBanner from './components/notification-banner/notification-banner' import Header from './components/header/header' import Radios from './components/radios/radios' +import SkipLink from './components/skip-link/skip-link' import Tabs from './components/tabs/tabs' function initAll (options) { @@ -61,6 +62,10 @@ function initAll (options) { new Radios($radio).init() }) + // Find first skip link module to enhance. + var $skipLink = scope.querySelector('[data-module="govuk-skip-link"]') + new SkipLink($skipLink).init() + var $tabs = scope.querySelectorAll('[data-module="govuk-tabs"]') nodeListForEach($tabs, function ($tabs) { new Tabs($tabs).init() @@ -77,5 +82,6 @@ export { ErrorSummary, Header, Radios, + SkipLink, Tabs } diff --git a/src/govuk/components/skip-link/skip-link.js b/src/govuk/components/skip-link/skip-link.js new file mode 100644 index 0000000000..742b5862e8 --- /dev/null +++ b/src/govuk/components/skip-link/skip-link.js @@ -0,0 +1,16 @@ +function SkipLink ($module) { + this.$module = $module +} + +/** + * Initialise the component + */ +SkipLink.prototype.init = function () { + var $module = this.$module + // Check for module + if (!$module) { + return + } +} + +export default SkipLink diff --git a/src/govuk/components/skip-link/template.njk b/src/govuk/components/skip-link/template.njk index b78695eae8..f1c5660197 100644 --- a/src/govuk/components/skip-link/template.njk +++ b/src/govuk/components/skip-link/template.njk @@ -1,3 +1,3 @@ - + {{- params.html | safe if params.html else params.text -}} From 291066469f248b696d26e6baea02ff5f76e17e93 Mon Sep 17 00:00:00 2001 From: Hanna Date: Mon, 29 Nov 2021 17:21:08 +0000 Subject: [PATCH 2/4] 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 https://github.com/alphagov/govuk-frontend/issues/2187#issuecomment-973172184 for more details and the full testing results. --- src/govuk/all.test.js | 1 + src/govuk/components/skip-link/_index.scss | 13 ++++ src/govuk/components/skip-link/skip-link.js | 77 +++++++++++++++++++ .../components/skip-link/skip-link.test.js | 50 ++++++++++++ .../components/skip-link/template.test.js | 8 ++ 5 files changed, 149 insertions(+) create mode 100644 src/govuk/components/skip-link/skip-link.test.js diff --git a/src/govuk/all.test.js b/src/govuk/all.test.js index c08dbf61d9..f31bbe5b54 100644 --- a/src/govuk/all.test.js +++ b/src/govuk/all.test.js @@ -53,6 +53,7 @@ describe('GOV.UK Frontend', () => { 'ErrorSummary', 'Header', 'Radios', + 'SkipLink', 'Tabs' ]) }) diff --git a/src/govuk/components/skip-link/_index.scss b/src/govuk/components/skip-link/_index.scss index 36cd835c21..82f065d5bb 100644 --- a/src/govuk/components/skip-link/_index.scss +++ b/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
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; + } + } } diff --git a/src/govuk/components/skip-link/skip-link.js b/src/govuk/components/skip-link/skip-link.js index 742b5862e8..2086a0a922 100644 --- a/src/govuk/components/skip-link/skip-link.js +++ b/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 diff --git a/src/govuk/components/skip-link/skip-link.test.js b/src/govuk/components/skip-link/skip-link.test.js new file mode 100644 index 0000000000..1cc5195316 --- /dev/null +++ b/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') + }) + }) +}) diff --git a/src/govuk/components/skip-link/template.test.js b/src/govuk/components/skip-link/template.test.js index bb1073565d..acbc409b72 100644 --- a/src/govuk/components/skip-link/template.test.js +++ b/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') + }) }) }) From c6befaffe9586e4acc1f77457eeb229fef437625 Mon Sep 17 00:00:00 2001 From: Hanna Date: Mon, 29 Nov 2021 16:26:49 +0000 Subject: [PATCH 3/4] Make the preview app template examples more realistic Add basic page content and initialise JavaScript for components so that the pages can be used for tests. --- app/views/examples/template-custom/index.njk | 1 + app/views/examples/template-default/index.njk | 8 ++++++++ 2 files changed, 9 insertions(+) diff --git a/app/views/examples/template-custom/index.njk b/app/views/examples/template-custom/index.njk index 6b4bb6f9d2..f31844c4e6 100644 --- a/app/views/examples/template-custom/index.njk +++ b/app/views/examples/template-custom/index.njk @@ -130,5 +130,6 @@ {% block bodyEnd %} + {% endblock %} diff --git a/app/views/examples/template-default/index.njk b/app/views/examples/template-default/index.njk index 1116ac33b9..5392052f85 100644 --- a/app/views/examples/template-default/index.njk +++ b/app/views/examples/template-default/index.njk @@ -12,6 +12,14 @@ {% endblock %} +{% block content %} + +

Default page template

+ +{% endblock %} + + {% block bodyEnd %} + {% endblock %} From 907a0cc44f69be2b55061d80461c696505d8d8d1 Mon Sep 17 00:00:00 2001 From: Hanna Date: Mon, 29 Nov 2021 17:48:48 +0000 Subject: [PATCH 4/4] Update Changelog Co-authored-by: Eoin Shaughnessy --- CHANGELOG.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 169e98427f..ce15ec28dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -135,6 +135,24 @@ You do not need to do anything if you're using Nunjucks macros. This change was introduced in [pull request #2437: Remove `display:block` on hint component](https://github.com/alphagov/govuk-frontend/pull/2437). +#### Include JavaScript for skip link to improve screen reader announcements + +We've added JavaScript for the skip link component to set focus to the linked element, for example, the main content on the page. This helps screen readers read the linked content when users use the skip link. + +If you're not using Nunjucks macros, add a `data-module="govuk-skip-link"` attribute to the component HTML. For example: + +```html +
+... +
+``` + +If you're [importing JavaScript for individual components](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#select-and-initialise-an-individual-component), import the skip link JavaScript. + +Once you've made the changes, check that the skip link JavaScript works. To make sure, click the skip link and check that the linked element (usually the `
` element) in the browser has a `tabindex` attribute. + +This change was introduced in [pull request #2450: Set focus to skip link target to improve screen reader announcements](https://github.com/alphagov/govuk-frontend/pull/2450). + #### Remove calls to deprecated `iff` Sass function We've removed the `iff` function which we deprecated in [GOV.UK Frontend version 3.6.0](https://github.com/alphagov/govuk-frontend/releases/tag/v3.6.0).