From 27deff0c7bd9c1461d56b61a5b1abcee14fac439 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Tue, 22 Nov 2022 15:38:11 +0000
Subject: [PATCH 01/15] =?UTF-8?q?Fix=20compiler=20=E2=80=9CThis=20expressi?=
 =?UTF-8?q?on=20is=20not=20callable=E2=80=9D=20for=20`outdent`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 lib/jest-helpers.js                       | 2 +-
 src/govuk/helpers/grid.test.js            | 2 +-
 src/govuk/helpers/spacing.test.js         | 2 +-
 src/govuk/helpers/typography.test.js      | 2 +-
 src/govuk/objects/width-container.test.js | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/lib/jest-helpers.js b/lib/jest-helpers.js
index 216ac426fd..c1c9f6c0eb 100644
--- a/lib/jest-helpers.js
+++ b/lib/jest-helpers.js
@@ -5,7 +5,7 @@ const cheerio = require('cheerio')
 const { configureAxe } = require('jest-axe')
 const sass = require('node-sass')
 const nunjucks = require('nunjucks')
-const outdent = require('outdent')
+const { outdent } = require('outdent')
 
 const sassRender = util.promisify(sass.render)
 
diff --git a/src/govuk/helpers/grid.test.js b/src/govuk/helpers/grid.test.js
index dd0bf999c4..f346fb118d 100644
--- a/src/govuk/helpers/grid.test.js
+++ b/src/govuk/helpers/grid.test.js
@@ -1,4 +1,4 @@
-const outdent = require('outdent')
+const { outdent } = require('outdent')
 
 const { renderSass } = require('../../../lib/jest-helpers')
 
diff --git a/src/govuk/helpers/spacing.test.js b/src/govuk/helpers/spacing.test.js
index 879c05ec79..4671f478ff 100644
--- a/src/govuk/helpers/spacing.test.js
+++ b/src/govuk/helpers/spacing.test.js
@@ -1,4 +1,4 @@
-const outdent = require('outdent')
+const { outdent } = require('outdent')
 
 const { renderSass } = require('../../../lib/jest-helpers')
 
diff --git a/src/govuk/helpers/typography.test.js b/src/govuk/helpers/typography.test.js
index 236beb4a68..02e5a20540 100644
--- a/src/govuk/helpers/typography.test.js
+++ b/src/govuk/helpers/typography.test.js
@@ -1,6 +1,6 @@
 
 const sass = require('node-sass')
-const outdent = require('outdent')
+const { outdent } = require('outdent')
 
 const { renderSass } = require('../../../lib/jest-helpers')
 
diff --git a/src/govuk/objects/width-container.test.js b/src/govuk/objects/width-container.test.js
index f0e5ff15bd..ac3203d8a4 100644
--- a/src/govuk/objects/width-container.test.js
+++ b/src/govuk/objects/width-container.test.js
@@ -1,4 +1,4 @@
-const outdent = require('outdent')
+const { outdent } = require('outdent')
 
 const { renderSass } = require('../../../lib/jest-helpers')
 

From 5f3cc7a583c9edc7f9d5d0d7140932bd7edaf8f6 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Wed, 9 Nov 2022 14:12:22 +0000
Subject: [PATCH 02/15] =?UTF-8?q?Fix=20compiler=20=E2=80=9CExpected=201=20?=
 =?UTF-8?q?arguments,=20but=20got=202=E2=80=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/govuk/components/tabs/tabs.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/govuk/components/tabs/tabs.mjs b/src/govuk/components/tabs/tabs.mjs
index 56b625d6b4..4aa9f3af90 100644
--- a/src/govuk/components/tabs/tabs.mjs
+++ b/src/govuk/components/tabs/tabs.mjs
@@ -112,7 +112,7 @@ Tabs.prototype.teardown = function () {
   $tabList.removeAttribute('role')
 
   nodeListForEach($tabListItems, function ($item) {
-    $item.removeAttribute('role', 'presentation')
+    $item.removeAttribute('role')
   })
 
   nodeListForEach($tabs, function ($tab) {

From 503e04fd9ed6c3b1551ad4389671202e85bc614b Mon Sep 17 00:00:00 2001
From: Romaric <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 13 Dec 2022 12:32:48 +0000
Subject: [PATCH 03/15] Use generics for typing `nodeListForEach`

This allows to forward the type of the `NodeListOf` it iterates on to the parameters of the callback.
In turn this should allow to drop quite a few `instanceof` checks when using the function by properly typing the `NodeList` we give it.

Interesting links:
- [The `@template` JSDoc tag](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template)
- [How to constrain the generic type](https://stackoverflow.com/a/54631901)
---
 src/govuk/common/index.mjs | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/govuk/common/index.mjs b/src/govuk/common/index.mjs
index 1b54b08aeb..d798fb5c67 100644
--- a/src/govuk/common/index.mjs
+++ b/src/govuk/common/index.mjs
@@ -13,8 +13,9 @@
  * This seems to fail in IE8, requires more investigation.
  * See: https://github.com/imagitama/nodelist-foreach-polyfill
  *
- * @param {NodeListOf<Element>} nodes - NodeList from querySelectorAll()
- * @param {nodeListIterator} callback - Callback function to run for each node
+ * @template {Node} ElementType
+ * @param {NodeListOf<ElementType>} nodes - NodeList from querySelectorAll()
+ * @param {nodeListIterator<ElementType>} callback - Callback function to run for each node
  * @returns {void}
  */
 export function nodeListForEach (nodes, callback) {
@@ -158,9 +159,10 @@ export function extractConfigByNamespace (configObject, namespace) {
 }
 
 /**
+ * @template {Node} ElementType
  * @callback nodeListIterator
- * @param {Element} value - The current node being iterated on
+ * @param {ElementType} value - The current node being iterated on
  * @param {number} index - The current index in the iteration
- * @param {NodeListOf<Element>} nodes - NodeList from querySelectorAll()
+ * @param {NodeListOf<ElementType>} nodes - NodeList from querySelectorAll()
  * @returns {void}
  */

From d68b694c1a307a0ca292ca89a3299e1d6ee10c00 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Thu, 19 Jan 2023 13:33:27 +0000
Subject: [PATCH 04/15] =?UTF-8?q?Fix=20compiler=20=E2=80=9CProperty=20'xxx?=
 =?UTF-8?q?x'=20does=20not=20exist=20on=20type=20'xxxx'=E2=80=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Various `instanceof` additions to help the `tsc` compiler discover potential issues

For example a mouse or keyboard `event.target` might not necessarily be the element we expect
---
 src/govuk/all.mjs                             |  4 ++-
 src/govuk/components/accordion/accordion.mjs  | 32 +++++++++++--------
 .../character-count/character-count.mjs       | 15 +++++----
 .../components/checkboxes/checkboxes.mjs      | 18 +++++++----
 .../error-summary/error-summary.mjs           |  2 +-
 src/govuk/components/radios/radios.mjs        | 14 +++++---
 src/govuk/components/skip-link/skip-link.mjs  |  2 +-
 src/govuk/components/tabs/tabs.mjs            | 20 ++++++------
 src/govuk/components/tabs/tabs.test.js        |  2 +-
 src/govuk/i18n.mjs                            |  6 ++--
 10 files changed, 68 insertions(+), 47 deletions(-)

diff --git a/src/govuk/all.mjs b/src/govuk/all.mjs
index ce7e42e930..f90ce7c139 100644
--- a/src/govuk/all.mjs
+++ b/src/govuk/all.mjs
@@ -75,7 +75,9 @@ function initAll (config) {
 
   // Find first skip link module to enhance.
   var $skipLink = $scope.querySelector('[data-module="govuk-skip-link"]')
-  new SkipLink($skipLink).init()
+  if ($skipLink) {
+    new SkipLink($skipLink).init()
+  }
 
   var $tabs = $scope.querySelectorAll('[data-module="govuk-tabs"]')
   nodeListForEach($tabs, function ($tabs) {
diff --git a/src/govuk/components/accordion/accordion.mjs b/src/govuk/components/accordion/accordion.mjs
index aea9a6cf4c..58fc18848b 100644
--- a/src/govuk/components/accordion/accordion.mjs
+++ b/src/govuk/components/accordion/accordion.mjs
@@ -139,26 +139,30 @@ Accordion.prototype.initControls = function () {
  * Initialise section headers
  */
 Accordion.prototype.initSectionHeaders = function () {
-  // Loop through section headers
-  nodeListForEach(this.$sections, function ($section, i) {
+  var $component = this
+  var $sections = this.$sections
+
+  // Loop through sections
+  nodeListForEach($sections, function ($section, i) {
+    var $header = $section.querySelector('.' + $component.sectionHeaderClass)
+
     // Set header attributes
-    var $header = $section.querySelector('.' + this.sectionHeaderClass)
-    this.constructHeaderMarkup($header, i)
-    this.setExpanded(this.isExpanded($section), $section)
+    $component.constructHeaderMarkup($header, i)
+    $component.setExpanded($component.isExpanded($section), $section)
 
     // Handle events
-    $header.addEventListener('click', this.onSectionToggle.bind(this, $section))
+    $header.addEventListener('click', $component.onSectionToggle.bind($component, $section))
 
     // See if there is any state stored in sessionStorage and set the sections to
     // open or closed.
-    this.setInitialState($section)
-  }.bind(this))
+    $component.setInitialState($section)
+  })
 }
 
 /**
  * Construct section header
  *
- * @param {HTMLDivElement} $header - Section header
+ * @param {HTMLElement} $header - Section header
  * @param {number} index - Section index
  */
 Accordion.prototype.constructHeaderMarkup = function ($header, index) {
@@ -286,17 +290,19 @@ Accordion.prototype.onSectionToggle = function ($section) {
  * When Open/Close All toggled, set and store state
  */
 Accordion.prototype.onShowOrHideAllToggle = function () {
-  var $module = this
+  var $component = this
   var $sections = this.$sections
+
   var nowExpanded = !this.checkIfAllSectionsOpen()
 
+  // Loop through sections
   nodeListForEach($sections, function ($section) {
-    $module.setExpanded(nowExpanded, $section)
+    $component.setExpanded(nowExpanded, $section)
     // Store the state in sessionStorage when a change is triggered
-    $module.storeState($section)
+    $component.storeState($section)
   })
 
-  $module.updateShowAllButton(nowExpanded)
+  $component.updateShowAllButton(nowExpanded)
 }
 
 /**
diff --git a/src/govuk/components/character-count/character-count.mjs b/src/govuk/components/character-count/character-count.mjs
index 8b46790df6..ed8b8901af 100644
--- a/src/govuk/components/character-count/character-count.mjs
+++ b/src/govuk/components/character-count/character-count.mjs
@@ -96,9 +96,9 @@ function CharacterCount ($module, config) {
   })
 
   // Determine the limit attribute (characters or words)
-  if (this.config.maxwords) {
+  if ('maxwords' in this.config && this.config.maxwords) {
     this.maxLength = this.config.maxwords
-  } else if (this.config.maxlength) {
+  } else if ('maxlength' in this.config && this.config.maxlength) {
     this.maxLength = this.config.maxlength
   } else {
     return
@@ -108,7 +108,9 @@ function CharacterCount ($module, config) {
   this.$textarea = $module.querySelector('.govuk-js-character-count')
   this.$visibleCountMessage = null
   this.$screenReaderCountMessage = null
+
   this.lastInputTimestamp = null
+  this.lastInputValue = ''
 }
 
 /**
@@ -233,9 +235,8 @@ CharacterCount.prototype.handleBlur = function () {
  * Update count message if textarea value has changed
  */
 CharacterCount.prototype.updateIfValueChanged = function () {
-  if (!this.$textarea.oldValue) this.$textarea.oldValue = ''
-  if (this.$textarea.value !== this.$textarea.oldValue) {
-    this.$textarea.oldValue = this.$textarea.value
+  if (this.$textarea.value !== this.lastInputValue) {
+    this.lastInputValue = this.$textarea.value
     this.updateCountMessage()
   }
 }
@@ -308,7 +309,7 @@ CharacterCount.prototype.updateScreenReaderCountMessage = function () {
  * @returns {number} the number of characters (or words) in the text
  */
 CharacterCount.prototype.count = function (text) {
-  if (this.config.maxwords) {
+  if ('maxwords' in this.config && this.config.maxwords) {
     var tokens = text.match(/\S+/g) || [] // Matches consecutive non-whitespace chars
     return tokens.length
   } else {
@@ -324,7 +325,7 @@ CharacterCount.prototype.count = function (text) {
 CharacterCount.prototype.getCountMessage = function () {
   var remainingNumber = this.maxLength - this.count(this.$textarea.value)
 
-  var countType = this.config.maxwords ? 'words' : 'characters'
+  var countType = 'maxwords' in this.config && this.config.maxwords ? 'words' : 'characters'
   return this.formatCountMessage(remainingNumber, countType)
 }
 
diff --git a/src/govuk/components/checkboxes/checkboxes.mjs b/src/govuk/components/checkboxes/checkboxes.mjs
index 480cb4f077..724255515e 100644
--- a/src/govuk/components/checkboxes/checkboxes.mjs
+++ b/src/govuk/components/checkboxes/checkboxes.mjs
@@ -103,15 +103,19 @@ Checkboxes.prototype.syncConditionalRevealWithInputState = function ($input) {
  * @param {HTMLElement} $input - Checkbox input
  */
 Checkboxes.prototype.unCheckAllInputsExcept = function ($input) {
-  var allInputsWithSameName = document.querySelectorAll('input[type="checkbox"][name="' + $input.name + '"]')
+  var $component = this
+
+  var allInputsWithSameName = document.querySelectorAll(
+    'input[type="checkbox"][name="' + $input.name + '"]'
+  )
 
   nodeListForEach(allInputsWithSameName, function ($inputWithSameName) {
     var hasSameFormOwner = ($input.form === $inputWithSameName.form)
     if (hasSameFormOwner && $inputWithSameName !== $input) {
       $inputWithSameName.checked = false
-      this.syncConditionalRevealWithInputState($inputWithSameName)
+      $component.syncConditionalRevealWithInputState($inputWithSameName)
     }
-  }.bind(this))
+  })
 }
 
 /**
@@ -124,6 +128,8 @@ Checkboxes.prototype.unCheckAllInputsExcept = function ($input) {
  * @param {HTMLInputElement} $input - Checkbox input
  */
 Checkboxes.prototype.unCheckExclusiveInputs = function ($input) {
+  var $component = this
+
   var allInputsWithSameNameAndExclusiveBehaviour = document.querySelectorAll(
     'input[data-behaviour="exclusive"][type="checkbox"][name="' + $input.name + '"]'
   )
@@ -132,9 +138,9 @@ Checkboxes.prototype.unCheckExclusiveInputs = function ($input) {
     var hasSameFormOwner = ($input.form === $exclusiveInput.form)
     if (hasSameFormOwner) {
       $exclusiveInput.checked = false
-      this.syncConditionalRevealWithInputState($exclusiveInput)
+      $component.syncConditionalRevealWithInputState($exclusiveInput)
     }
-  }.bind(this))
+  })
 }
 
 /**
@@ -149,7 +155,7 @@ Checkboxes.prototype.handleClick = function (event) {
   var $clickedInput = event.target
 
   // Ignore clicks on things that aren't checkbox inputs
-  if ($clickedInput.type !== 'checkbox') {
+  if (!($clickedInput instanceof HTMLInputElement) || $clickedInput.type !== 'checkbox') {
     return
   }
 
diff --git a/src/govuk/components/error-summary/error-summary.mjs b/src/govuk/components/error-summary/error-summary.mjs
index 1154cf1107..7cbb785fb1 100644
--- a/src/govuk/components/error-summary/error-summary.mjs
+++ b/src/govuk/components/error-summary/error-summary.mjs
@@ -107,7 +107,7 @@ ErrorSummary.prototype.handleClick = function (event) {
  */
 ErrorSummary.prototype.focusTarget = function ($target) {
   // If the element that was clicked was not a link, return early
-  if ($target.tagName !== 'A' || $target.href === false) {
+  if (!($target instanceof HTMLAnchorElement)) {
     return false
   }
 
diff --git a/src/govuk/components/radios/radios.mjs b/src/govuk/components/radios/radios.mjs
index eb2b16f6fe..0fbc3d8ca3 100644
--- a/src/govuk/components/radios/radios.mjs
+++ b/src/govuk/components/radios/radios.mjs
@@ -105,10 +105,11 @@ Radios.prototype.syncConditionalRevealWithInputState = function ($input) {
  * @param {MouseEvent} event - Click event
  */
 Radios.prototype.handleClick = function (event) {
+  var $component = this
   var $clickedInput = event.target
 
   // Ignore clicks on things that aren't radio buttons
-  if ($clickedInput.type !== 'radio') {
+  if (!($clickedInput instanceof HTMLInputElement) || $clickedInput.type !== 'radio') {
     return
   }
 
@@ -116,14 +117,17 @@ Radios.prototype.handleClick = function (event) {
   // aria-controls attributes.
   var $allInputs = document.querySelectorAll('input[type="radio"][aria-controls]')
 
+  var $clickedInputForm = $clickedInput.form
+  var $clickedInputName = $clickedInput.name
+
   nodeListForEach($allInputs, function ($input) {
-    var hasSameFormOwner = ($input.form === $clickedInput.form)
-    var hasSameName = ($input.name === $clickedInput.name)
+    var hasSameFormOwner = $input.form === $clickedInputForm
+    var hasSameName = $input.name === $clickedInputName
 
     if (hasSameName && hasSameFormOwner) {
-      this.syncConditionalRevealWithInputState($input)
+      $component.syncConditionalRevealWithInputState($input)
     }
-  }.bind(this))
+  })
 }
 
 export default Radios
diff --git a/src/govuk/components/skip-link/skip-link.mjs b/src/govuk/components/skip-link/skip-link.mjs
index 5b930a03d1..29401c0c93 100644
--- a/src/govuk/components/skip-link/skip-link.mjs
+++ b/src/govuk/components/skip-link/skip-link.mjs
@@ -8,7 +8,7 @@ import '../../vendor/polyfills/Function/prototype/bind.mjs'
  * Skip link component
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for skip link
+ * @param {HTMLAnchorElement} $module - HTML element to use for skip link
  */
 function SkipLink ($module) {
   this.$module = $module
diff --git a/src/govuk/components/tabs/tabs.mjs b/src/govuk/components/tabs/tabs.mjs
index 4aa9f3af90..1e08f7e478 100644
--- a/src/govuk/components/tabs/tabs.mjs
+++ b/src/govuk/components/tabs/tabs.mjs
@@ -56,6 +56,7 @@ Tabs.prototype.checkMode = function () {
  * Setup tab component
  */
 Tabs.prototype.setup = function () {
+  var $component = this
   var $module = this.$module
   var $tabs = this.$tabs
   var $tabList = $module.querySelector('.govuk-tabs__list')
@@ -73,19 +74,19 @@ Tabs.prototype.setup = function () {
 
   nodeListForEach($tabs, function ($tab) {
     // Set HTML attributes
-    this.setAttributes($tab)
+    $component.setAttributes($tab)
 
     // Save bounded functions to use when removing event listeners during teardown
-    $tab.boundTabClick = this.onTabClick.bind(this)
-    $tab.boundTabKeydown = this.onTabKeydown.bind(this)
+    $tab.boundTabClick = $component.onTabClick.bind($component)
+    $tab.boundTabKeydown = $component.onTabKeydown.bind($component)
 
     // Handle events
     $tab.addEventListener('click', $tab.boundTabClick, true)
     $tab.addEventListener('keydown', $tab.boundTabKeydown, true)
 
     // Remove old active panels
-    this.hideTab($tab)
-  }.bind(this))
+    $component.hideTab($tab)
+  })
 
   // Show either the active tab according to the URL's hash or the first tab
   var $activeTab = this.getTab(window.location.hash) || this.$tabs[0]
@@ -100,6 +101,7 @@ Tabs.prototype.setup = function () {
  * Teardown tab component
  */
 Tabs.prototype.teardown = function () {
+  var $component = this
   var $module = this.$module
   var $tabs = this.$tabs
   var $tabList = $module.querySelector('.govuk-tabs__list')
@@ -121,8 +123,8 @@ Tabs.prototype.teardown = function () {
     $tab.removeEventListener('keydown', $tab.boundTabKeydown, true)
 
     // Unset HTML attributes
-    this.unsetAttributes($tab)
-  }.bind(this))
+    $component.unsetAttributes($tab)
+  })
 
   // Remove hashchange event handler
   window.removeEventListener('hashchange', $module.boundOnHashChange, true)
@@ -372,7 +374,7 @@ Tabs.prototype.hidePanel = function ($tab) {
  */
 Tabs.prototype.unhighlightTab = function ($tab) {
   $tab.setAttribute('aria-selected', 'false')
-  $tab.parentNode.classList.remove('govuk-tabs__list-item--selected')
+  $tab.parentElement.classList.remove('govuk-tabs__list-item--selected')
   $tab.setAttribute('tabindex', '-1')
 }
 
@@ -383,7 +385,7 @@ Tabs.prototype.unhighlightTab = function ($tab) {
  */
 Tabs.prototype.highlightTab = function ($tab) {
   $tab.setAttribute('aria-selected', 'true')
-  $tab.parentNode.classList.add('govuk-tabs__list-item--selected')
+  $tab.parentElement.classList.add('govuk-tabs__list-item--selected')
   $tab.setAttribute('tabindex', '0')
 }
 
diff --git a/src/govuk/components/tabs/tabs.test.js b/src/govuk/components/tabs/tabs.test.js
index 22c56a718b..2e478e6e75 100644
--- a/src/govuk/components/tabs/tabs.test.js
+++ b/src/govuk/components/tabs/tabs.test.js
@@ -133,7 +133,7 @@ describe('/components/tabs', () => {
         const currentTabAriaSelected = await page.evaluate(() => document.body.querySelector('.govuk-tabs__tab[href="#past-week"]').getAttribute('aria-selected'))
         expect(currentTabAriaSelected).toEqual('true')
 
-        const currentTabClasses = await page.evaluate(() => document.body.querySelector('.govuk-tabs__tab[href="#past-week"]').parentNode.className)
+        const currentTabClasses = await page.evaluate(() => document.body.querySelector('.govuk-tabs__tab[href="#past-week"]').parentElement.className)
         expect(currentTabClasses).toContain('govuk-tabs__list-item--selected')
 
         const currentTabPanelIsHidden = await page.evaluate(() => document.getElementById('past-week').classList.contains('govuk-tabs__panel--hidden'))
diff --git a/src/govuk/i18n.mjs b/src/govuk/i18n.mjs
index 50fd25c62c..eb88e1c326 100644
--- a/src/govuk/i18n.mjs
+++ b/src/govuk/i18n.mjs
@@ -40,10 +40,10 @@ I18n.prototype.t = function (lookupKey, options) {
     lookupKey = lookupKey + '.' + this.getPluralSuffix(lookupKey, options.count)
   }
 
-  if (lookupKey in this.translations) {
-    // Fetch the translation string for that lookup key
-    var translationString = this.translations[lookupKey]
+  // Fetch the translation string for that lookup key
+  var translationString = this.translations[lookupKey]
 
+  if (typeof translationString === 'string') {
     // Check for ${} placeholders in the translation string
     if (translationString.match(/%{(.\S+)}/)) {
       if (!options) {

From d48170062016e559cf905644ed5b8eb4a1e65cb7 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 19 Dec 2022 12:47:28 +0000
Subject: [PATCH 05/15] =?UTF-8?q?Fix=20compiler=20=E2=80=9CType=20'boolean?=
 =?UTF-8?q?'=20is=20not=20assignable=20to=20type=20'string'=E2=80=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/govuk/components/accordion/accordion.mjs             | 4 ++--
 src/govuk/components/character-count/character-count.mjs | 2 +-
 src/govuk/components/checkboxes/checkboxes.mjs           | 2 +-
 src/govuk/components/header/header.mjs                   | 2 +-
 src/govuk/components/radios/radios.mjs                   | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/govuk/components/accordion/accordion.mjs b/src/govuk/components/accordion/accordion.mjs
index 58fc18848b..c94627e634 100644
--- a/src/govuk/components/accordion/accordion.mjs
+++ b/src/govuk/components/accordion/accordion.mjs
@@ -322,7 +322,7 @@ Accordion.prototype.setExpanded = function (expanded, $section) {
     : this.i18n.t('showSection')
 
   $showHideText.innerText = newButtonText
-  $button.setAttribute('aria-expanded', expanded)
+  $button.setAttribute('aria-expanded', expanded.toString())
 
   // Update aria-label combining
   var ariaLabelParts = []
@@ -400,7 +400,7 @@ Accordion.prototype.updateShowAllButton = function (expanded) {
     ? this.i18n.t('hideAllSections')
     : this.i18n.t('showAllSections')
 
-  this.$showAllButton.setAttribute('aria-expanded', expanded)
+  this.$showAllButton.setAttribute('aria-expanded', expanded.toString())
   this.$showAllText.innerText = newButtonText
 
   // Swap icon, toggle class
diff --git a/src/govuk/components/character-count/character-count.mjs b/src/govuk/components/character-count/character-count.mjs
index ed8b8901af..8c0f3cc3ec 100644
--- a/src/govuk/components/character-count/character-count.mjs
+++ b/src/govuk/components/character-count/character-count.mjs
@@ -294,7 +294,7 @@ CharacterCount.prototype.updateScreenReaderCountMessage = function () {
   if (this.isOverThreshold()) {
     $screenReaderCountMessage.removeAttribute('aria-hidden')
   } else {
-    $screenReaderCountMessage.setAttribute('aria-hidden', true)
+    $screenReaderCountMessage.setAttribute('aria-hidden', 'true')
   }
 
   // Update message
diff --git a/src/govuk/components/checkboxes/checkboxes.mjs b/src/govuk/components/checkboxes/checkboxes.mjs
index 724255515e..fcac5fa4b2 100644
--- a/src/govuk/components/checkboxes/checkboxes.mjs
+++ b/src/govuk/components/checkboxes/checkboxes.mjs
@@ -89,7 +89,7 @@ Checkboxes.prototype.syncConditionalRevealWithInputState = function ($input) {
   if ($target && $target.classList.contains('govuk-checkboxes__conditional')) {
     var inputIsChecked = $input.checked
 
-    $input.setAttribute('aria-expanded', inputIsChecked)
+    $input.setAttribute('aria-expanded', inputIsChecked.toString())
     $target.classList.toggle('govuk-checkboxes__conditional--hidden', !inputIsChecked)
   }
 }
diff --git a/src/govuk/components/header/header.mjs b/src/govuk/components/header/header.mjs
index 567a796bfb..c2c1e4c161 100644
--- a/src/govuk/components/header/header.mjs
+++ b/src/govuk/components/header/header.mjs
@@ -77,7 +77,7 @@ Header.prototype.syncState = function () {
     this.$menuButton.setAttribute('hidden', '')
   } else {
     this.$menuButton.removeAttribute('hidden')
-    this.$menuButton.setAttribute('aria-expanded', this.menuIsOpen)
+    this.$menuButton.setAttribute('aria-expanded', this.menuIsOpen.toString())
 
     if (this.menuIsOpen) {
       this.$menu.removeAttribute('hidden')
diff --git a/src/govuk/components/radios/radios.mjs b/src/govuk/components/radios/radios.mjs
index 0fbc3d8ca3..92a843e572 100644
--- a/src/govuk/components/radios/radios.mjs
+++ b/src/govuk/components/radios/radios.mjs
@@ -89,7 +89,7 @@ Radios.prototype.syncConditionalRevealWithInputState = function ($input) {
   if ($target && $target.classList.contains('govuk-radios__conditional')) {
     var inputIsChecked = $input.checked
 
-    $input.setAttribute('aria-expanded', inputIsChecked)
+    $input.setAttribute('aria-expanded', inputIsChecked.toString())
     $target.classList.toggle('govuk-radios__conditional--hidden', !inputIsChecked)
   }
 }

From b694c4b72ed479e07b1e52cfdfbcc32eabba8b5f Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 5 Dec 2022 14:17:53 +0000
Subject: [PATCH 06/15] =?UTF-8?q?Fix=20compiler=20=E2=80=9CType=20'number'?=
 =?UTF-8?q?=20is=20not=20assignable=20to=20type=20'string'=E2=80=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/govuk/common/normalise-dataset.mjs | 2 +-
 src/govuk/i18n.mjs                     | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/govuk/common/normalise-dataset.mjs b/src/govuk/common/normalise-dataset.mjs
index 2b2f491fb8..338ee633ff 100644
--- a/src/govuk/common/normalise-dataset.mjs
+++ b/src/govuk/common/normalise-dataset.mjs
@@ -34,7 +34,7 @@ export function normaliseString (value) {
 
   // Empty / whitespace-only strings are considered finite so we need to check
   // the length of the trimmed string as well
-  if (trimmedValue.length > 0 && isFinite(trimmedValue)) {
+  if (trimmedValue.length > 0 && isFinite(Number(trimmedValue))) {
     return Number(trimmedValue)
   }
 
diff --git a/src/govuk/i18n.mjs b/src/govuk/i18n.mjs
index eb88e1c326..40050c1faa 100644
--- a/src/govuk/i18n.mjs
+++ b/src/govuk/i18n.mjs
@@ -33,9 +33,9 @@ I18n.prototype.t = function (lookupKey, options) {
   }
 
   // If the `count` option is set, determine which plural suffix is needed and
-  // change the lookupKey to match. We check to see if it's undefined instead of
+  // change the lookupKey to match. We check to see if it's numeric instead of
   // falsy, as this could legitimately be 0.
-  if (options && typeof options.count !== 'undefined') {
+  if (options && typeof options.count === 'number') {
     // Get the plural suffix
     lookupKey = lookupKey + '.' + this.getPluralSuffix(lookupKey, options.count)
   }
@@ -87,8 +87,8 @@ I18n.prototype.replacePlaceholders = function (translationString, options) {
       }
 
       // If the placeholder's value is a number, localise the number formatting
-      if (typeof placeholderValue === 'number' && formatter) {
-        return formatter.format(placeholderValue)
+      if (typeof placeholderValue === 'number') {
+        return formatter ? formatter.format(placeholderValue) : placeholderValue.toString()
       }
 
       return placeholderValue

From 247d086c7157477596b26f99cdc117ff0e63efd7 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 5 Dec 2022 14:05:42 +0000
Subject: [PATCH 07/15] =?UTF-8?q?Fix=20compiler=20=E2=80=9CType=20'string'?=
 =?UTF-8?q?=20is=20not=20assignable=20to=20type=20'PluralRuleName'?=
 =?UTF-8?q?=E2=80=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I18n.pluralRulesMap keys are variable so “string” wasn’t compatible when the compiler thought we were using fixed string literals

Might be worth another look at `Object.keys()` in future with:

* https://github.com/microsoft/TypeScript/pull/45464
---
 src/govuk/i18n.mjs | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/src/govuk/i18n.mjs b/src/govuk/i18n.mjs
index 40050c1faa..e398907fde 100644
--- a/src/govuk/i18n.mjs
+++ b/src/govuk/i18n.mjs
@@ -211,7 +211,7 @@ I18n.prototype.selectPluralFormUsingFallbackRules = function (count) {
  * regardless of region. There are exceptions, however, (e.g. Portuguese) so
  * this searches by both the full and shortened locale codes, just to be sure.
  *
- * @returns {PluralRuleName | undefined} The name of the pluralisation rule to use (a key for one
+ * @returns {string | undefined} The name of the pluralisation rule to use (a key for one
  *   of the functions in this.pluralRules)
  */
 I18n.prototype.getPluralRulesForLocale = function () {
@@ -262,7 +262,7 @@ I18n.prototype.getPluralRulesForLocale = function () {
  * Spanish: European Portuguese (pt-PT), Italian (it), Spanish (es)
  * Welsh: Welsh (cy)
  *
- * @type {Object<PluralRuleName, string[]>}
+ * @type {Object<string, string[]>}
  */
 I18n.pluralRulesMap = {
   arabic: ['ar'],
@@ -350,12 +350,6 @@ I18n.pluralRules = {
   /* eslint-enable jsdoc/require-jsdoc */
 }
 
-/**
- * Supported languages for plural rules
- *
- * @typedef {'arabic' | 'chinese' | 'french' | 'german' | 'irish' | 'russian' | 'scottish' | 'spanish' | 'welsh'} PluralRuleName
- */
-
 /**
  * Plural rule category mnemonic tags
  *

From 149b1330ffc0f40c62f3274304de2a32687eb440 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 19 Dec 2022 17:25:36 +0000
Subject: [PATCH 08/15] =?UTF-8?q?Fix=20compiler=20=E2=80=9CType=20'unknown?=
 =?UTF-8?q?'=20is=20not=20assignable=20to=20type=20'string'=E2=80=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/govuk/i18n.mjs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/govuk/i18n.mjs b/src/govuk/i18n.mjs
index e398907fde..d1318d7f80 100644
--- a/src/govuk/i18n.mjs
+++ b/src/govuk/i18n.mjs
@@ -82,7 +82,10 @@ I18n.prototype.replacePlaceholders = function (translationString, options) {
 
       // If a user has passed `false` as the value for the placeholder
       // treat it as though the value should not be displayed
-      if (placeholderValue === false) {
+      if (placeholderValue === false || (
+        typeof placeholderValue !== 'number' &&
+        typeof placeholderValue !== 'string')
+      ) {
         return ''
       }
 

From d085607f72f5e0b6cfeffab4dcf0bdea82a70c46 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Wed, 11 Jan 2023 21:00:18 +0000
Subject: [PATCH 09/15] =?UTF-8?q?Fix=20ESLint=20=E2=80=9COperands=20of=20'?=
 =?UTF-8?q?+'=20operation=20must=20either=20be=20both=20strings=20or=20bot?=
 =?UTF-8?q?h=20numbers=E2=80=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/govuk/components/accordion/accordion.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/govuk/components/accordion/accordion.mjs b/src/govuk/components/accordion/accordion.mjs
index c94627e634..b3015bc689 100644
--- a/src/govuk/components/accordion/accordion.mjs
+++ b/src/govuk/components/accordion/accordion.mjs
@@ -173,7 +173,7 @@ Accordion.prototype.constructHeaderMarkup = function ($header, index) {
   // Create a button element that will replace the '.govuk-accordion__section-button' span
   var $button = document.createElement('button')
   $button.setAttribute('type', 'button')
-  $button.setAttribute('aria-controls', this.$module.id + '-content-' + (index + 1))
+  $button.setAttribute('aria-controls', this.$module.id + '-content-' + (index + 1).toString())
 
   // Copy all attributes (https://developer.mozilla.org/en-US/docs/Web/API/Element/attributes) from $span to $button
   for (var i = 0; i < $span.attributes.length; i++) {

From be9aca78bb60dd88335b45df5f9f65f7b1cebefb Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Thu, 15 Dec 2022 17:19:24 +0000
Subject: [PATCH 10/15] Fix various param/return types in review app

Including shared file and helper functions
---
 app/app.js              |  6 ++--
 lib/file-helper.js      | 62 +++++++++++++++++++++++++++--------------
 lib/helper-functions.js | 10 ++-----
 lib/jest-helpers.js     |  7 ++++-
 4 files changed, 53 insertions(+), 32 deletions(-)

diff --git a/app/app.js b/app/app.js
index c35018c2c2..5aba47df76 100644
--- a/app/app.js
+++ b/app/app.js
@@ -155,14 +155,14 @@ module.exports = async (options) => {
   })
 
   // Component example preview
-  app.get('/components/:componentName/:exampleName*?/preview', function (req, res, next) {
+  app.get('/components/:componentName/:exampleName?/preview', function (req, res, next) {
     // Find the data for the specified example (or the default example)
     const componentName = req.params.componentName
     const exampleName = req.params.exampleName || 'default'
 
-    const previewLayout = res.locals.componentData.previewLayout || 'layout'
+    const previewLayout = res.locals.componentData?.previewLayout || 'layout'
 
-    const exampleConfig = res.locals.componentData.examples.find(
+    const exampleConfig = res.locals.componentData?.examples.find(
       example => example.name.replace(/ /g, '-') === exampleName
     )
 
diff --git a/lib/file-helper.js b/lib/file-helper.js
index d9970b8331..3ebcfcb40a 100644
--- a/lib/file-helper.js
+++ b/lib/file-helper.js
@@ -1,5 +1,5 @@
 const { readFile } = require('fs/promises')
-const { join, parse, ParsedPath, relative } = require('path')
+const { join, parse, relative } = require('path')
 const { promisify } = require('util')
 
 const glob = promisify(require('glob'))
@@ -14,6 +14,11 @@ const configPaths = require('../config/paths')
  * Used to cache slow operations
  *
  * See `config/jest/globals.mjs`
+ *
+ * @type {{
+ *  directories?: Map<string, string[]>,
+ *  componentsData?: ComponentData[]
+ * }}
  */
 const cache = global.cache || {}
 
@@ -27,7 +32,6 @@ const cache = global.cache || {}
  */
 const getListing = async (directoryPath, pattern = '**/*', options = {}) => {
   const listing = await glob(pattern, {
-    allowEmpty: true,
     cwd: directoryPath,
     matchBase: true,
     nodir: true,
@@ -51,7 +55,7 @@ const getDirectories = (directoryPath) => {
 
   // Retrieve from cache
   if (directories) {
-    return directories
+    return Promise.resolve(directories)
   }
 
   // Read from disk
@@ -66,12 +70,11 @@ const getDirectories = (directoryPath) => {
  * @returns {function(string): boolean} Returns true for files matching every pattern
  */
 const filterPath = (patterns) => (entryPath) => {
-  const isMatch = (pattern) => minimatch(entryPath, pattern, {
-    matchBase: true
-  })
-
-  // Return true for files matching every pattern
-  return patterns.every(isMatch)
+  return patterns.every(
+    (pattern) => minimatch(entryPath, pattern, {
+      matchBase: true
+    })
+  )
 }
 
 /**
@@ -107,16 +110,12 @@ const getComponentData = async (componentName) => {
   }
 
   // Read from disk
-  try {
-    const yamlPath = join(configPaths.components, componentName, `${componentName}.yaml`)
-    const yamlData = yaml.load(await readFile(yamlPath, 'utf8'), { json: true })
+  const yamlPath = join(configPaths.components, componentName, `${componentName}.yaml`)
+  const yamlData = yaml.load(await readFile(yamlPath, 'utf8'), { json: true })
 
-    return {
-      name: componentName,
-      ...yamlData
-    }
-  } catch (error) {
-    throw new Error(error)
+  return {
+    name: componentName,
+    ...yamlData
   }
 }
 
@@ -177,7 +176,7 @@ module.exports = {
  * Directory entry path mapper callback
  *
  * @callback mapPathToCallback
- * @param {ParsedPath} file - Parsed file
+ * @param {import('path').ParsedPath} file - Parsed file
  * @returns {string[]} Returns path (or array of paths)
  */
 
@@ -186,12 +185,33 @@ module.exports = {
  *
  * @typedef {object} ComponentData
  * @property {string} name - Component name
- * @property {unknown[]} [params] - Nunjucks macro options
- * @property {unknown[]} [examples] - Example Nunjucks macro options
+ * @property {ComponentOption[]} [params] - Nunjucks macro options
+ * @property {ComponentExample[]} [examples] - Example Nunjucks macro options
  * @property {string} [previewLayout] - Nunjucks layout for component preview
  * @property {string} [accessibilityCriteria] - Accessibility criteria
  */
 
+/**
+ * Component option from YAML
+ *
+ * @typedef {object} ComponentOption
+ * @property {string} name - Option name
+ * @property {string} type - Option type
+ * @property {boolean} required - Option required
+ * @property {string} description - Option description
+ * @property {boolean} [isComponent] - Option is another component
+ * @property {ComponentOption[]} [params] - Nested Nunjucks macro options
+ */
+
+/**
+ * Component example from YAML
+ *
+ * @typedef {object} ComponentExample
+ * @property {string} name - Example name
+ * @property {object} data - Example data
+ * @property {boolean} [hidden] - Example hidden from review app
+ */
+
 /**
  * Full page example from front matter
  *
diff --git a/lib/helper-functions.js b/lib/helper-functions.js
index 77f0f76842..014a0a0731 100644
--- a/lib/helper-functions.js
+++ b/lib/helper-functions.js
@@ -67,15 +67,11 @@ function componentPathToModuleName (componentPath) {
  * the project root node_modules
  *
  * @param {string} packageName - Installed npm package name
- * @param {...string} [paths] - Optional child directory paths
+ * @param {string} [childPath] - Optional child directory path
  * @returns {string} Path to installed npm package
  */
-function packageNameToPath (packageName, ...paths) {
-  const packagePath = dirname(require.resolve(`${packageName}/package.json`))
-
-  return paths?.length
-    ? join(packagePath, ...paths)
-    : packagePath
+function packageNameToPath (packageName, childPath = '') {
+  return join(dirname(require.resolve(`${packageName}/package.json`)), childPath)
 }
 
 module.exports = {
diff --git a/lib/jest-helpers.js b/lib/jest-helpers.js
index c1c9f6c0eb..f2129f7536 100644
--- a/lib/jest-helpers.js
+++ b/lib/jest-helpers.js
@@ -109,11 +109,12 @@ function renderTemplate (context = {}, blocks = {}) {
  * Get examples from a component's metadata file
  *
  * @param {string} componentName - Component name
- * @returns {Promise<Object<string, object>>} returns object that includes all examples at once
+ * @returns {Promise<Object<string, ComponentExample['data']>>} returns object that includes all examples at once
  */
 async function getExamples (componentName) {
   const componentData = await getComponentData(componentName)
 
+  /** @type {Object<string, ComponentExample['data']>} */
   const examples = {}
 
   for (const example of componentData?.examples || []) {
@@ -177,3 +178,7 @@ module.exports = {
   renderSass,
   renderTemplate
 }
+
+/**
+ * @typedef {import('./file-helper.js').ComponentExample} ComponentExample
+ */

From 4d6762bee7abbda7e2f9625acf350fdafb5c3151 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Thu, 15 Dec 2022 17:19:29 +0000
Subject: [PATCH 11/15] Fix various param/return types in tooling

---
 config/jest/environment/jsdom.mjs     |  2 +-
 config/jest/environment/puppeteer.mjs |  2 +-
 lib/file-helper.unit.test.js          |  2 +-
 lib/jest-helpers.js                   | 12 +++---------
 lib/puppeteer-helpers.js              | 22 +++++++++++++---------
 tasks/screenshot-components.mjs       |  3 +--
 6 files changed, 20 insertions(+), 23 deletions(-)

diff --git a/config/jest/environment/jsdom.mjs b/config/jest/environment/jsdom.mjs
index ebf4048ec1..d6e73e33a7 100644
--- a/config/jest/environment/jsdom.mjs
+++ b/config/jest/environment/jsdom.mjs
@@ -14,7 +14,7 @@ class BrowserVirtualEnvironment extends TestEnvironment {
     const { virtualConsole } = this.dom
 
     // Ensure test fails for browser exceptions
-    virtualConsole.on('jsdomError', (error) => process.emit('error', error))
+    virtualConsole.on('jsdomError', (error) => process.emit('uncaughtException', error))
 
     // Add shared test globals
     // componentsData, componentsDirectory, examplesDirectory
diff --git a/config/jest/environment/puppeteer.mjs b/config/jest/environment/puppeteer.mjs
index 3fc2115c11..694440e456 100644
--- a/config/jest/environment/puppeteer.mjs
+++ b/config/jest/environment/puppeteer.mjs
@@ -19,7 +19,7 @@ class BrowserAutomationEnvironment extends PuppeteerEnvironment {
       delete error.stack
 
       // Ensure test fails
-      process.emit('error', error)
+      process.emit('uncaughtException', error)
     })
 
     // Add shared test globals
diff --git a/lib/file-helper.unit.test.js b/lib/file-helper.unit.test.js
index 2c5b547b27..07bfcaf82d 100644
--- a/lib/file-helper.unit.test.js
+++ b/lib/file-helper.unit.test.js
@@ -4,7 +4,7 @@ describe('getComponentData', () => {
   it('rejects if unable to load component data', async () => {
     await expect(fileHelper.getComponentData('not-a-real-component'))
       .rejects
-      .toThrow('Error: ENOENT: no such file or directory')
+      .toThrow(/ENOENT: no such file or directory/)
   })
 
   it('outputs objects with an array of params and examples', async () => {
diff --git a/lib/jest-helpers.js b/lib/jest-helpers.js
index f2129f7536..5a90286861 100644
--- a/lib/jest-helpers.js
+++ b/lib/jest-helpers.js
@@ -28,13 +28,7 @@ const nunjucksEnv = nunjucks.configure([join(configPaths.src, 'govuk'), configPa
  *   Nunjucks call tag, with the callBlock passed as the contents of the block
  * @returns {string} HTML rendered by the macro
  */
-function renderHtml (componentName, options, callBlock = false) {
-  if (typeof options === 'undefined') {
-    throw new Error(
-      'Parameters passed to `render` should be an object but are undefined'
-    )
-  }
-
+function renderHtml (componentName, options, callBlock) {
   const macroName = componentNameToMacroName(componentName)
   const macroPath = `${componentName}/macro.njk`
 
@@ -50,7 +44,7 @@ function renderHtml (componentName, options, callBlock = false) {
  * @param {string} [callBlock] - Content for an optional callBlock, if necessary for the macro to receive one
  * @returns {string} The result of calling the macro
  */
-function callMacro (macroName, macroPath, params = [], callBlock = false) {
+function callMacro (macroName, macroPath, params = [], callBlock) {
   const macroParams = params.map(param => JSON.stringify(param, null, 2)).join(',')
 
   let macroString = `{%- from "${macroPath}" import ${macroName} -%}`
@@ -77,7 +71,7 @@ function callMacro (macroName, macroPath, params = [], callBlock = false) {
  *   Nunjucks call tag, with the callBlock passed as the contents of the block
  * @returns {import('cheerio').CheerioAPI} a jQuery-like representation of the macro output
  */
-function render (componentName, options, callBlock = false) {
+function render (componentName, options, callBlock) {
   return cheerio.load(
     renderHtml(componentName, options, callBlock)
   )
diff --git a/lib/puppeteer-helpers.js b/lib/puppeteer-helpers.js
index cc1fabeedb..078b924aa0 100644
--- a/lib/puppeteer-helpers.js
+++ b/lib/puppeteer-helpers.js
@@ -23,13 +23,13 @@ const PORT = process.env.PORT || config.ports.test
  * @param {object} options.nunjucksParams - Params passed to the Nunjucks macro
  * @param {object} [options.javascriptConfig] - The configuration hash passed
  *   to the component's class for initialisation
- * @param {Function} [options.initialiser] - A function that'll run in the
+ * @param {initialiseCallback} [options.initialiser] - A function that'll run in the
  *   browser to execute arbitrary initialisation. Receives an object with the
  *   passed configuration as `config` and the PascalCased component name as
  *   `componentClassName`
  * @returns {Promise<import('puppeteer').Page>} Puppeteer page object
  */
-async function renderAndInitialise (page, componentName, options = {}) {
+async function renderAndInitialise (page, componentName, options) {
   await goTo(page, '/tests/boilerplate')
 
   const html = renderHtml(componentName, options.nunjucksParams)
@@ -76,11 +76,10 @@ async function goTo (page, path) {
  *
  * @param {import('puppeteer').Page} page - Puppeteer page object
  * @param {string} exampleName - Example name
- * @param {import('puppeteer').WaitForOptions} [options] - Navigation options (optional)
  * @returns {Promise<import('puppeteer').Page>} Puppeteer page object
  */
-function goToExample (page, exampleName, options) {
-  return goTo(page, `/examples/${exampleName}`, options)
+function goToExample (page, exampleName) {
+  return goTo(page, `/examples/${exampleName}`)
 }
 
 /**
@@ -92,9 +91,9 @@ function goToExample (page, exampleName, options) {
  * @param {string} options.exampleName - Example name
  * @returns {Promise<import('puppeteer').Page>} Puppeteer page object
  */
-function goToComponent (page, componentName, { exampleName } = {}) {
-  const componentPath = exampleName
-    ? `/components/${componentName}/${exampleName}/preview`
+function goToComponent (page, componentName, options) {
+  const componentPath = options?.exampleName
+    ? `/components/${componentName}/${options.exampleName}/preview`
     : `/components/${componentName}/preview`
 
   return goTo(page, componentPath)
@@ -128,7 +127,7 @@ function getAttribute ($element, attributeName) {
  *
  * @param {import('puppeteer').Page} page - Puppeteer page object
  * @param {import('puppeteer').ElementHandle} $element - Puppeteer element handle
- * @returns {string} The element's accessible name
+ * @returns {Promise<string>} The element's accessible name
  * @throws {TypeError} If the element has no corresponding node in the accessibility tree
  */
 async function getAccessibleName (page, $element) {
@@ -161,3 +160,8 @@ module.exports = {
   getAccessibleName,
   isVisible
 }
+
+/**
+ * @callback initialiseCallback
+ * @param {{ config: object, componentClassName: string }} context - Initialiser context
+ */
diff --git a/tasks/screenshot-components.mjs b/tasks/screenshot-components.mjs
index 6f28bef4f8..0bcdc59193 100644
--- a/tasks/screenshot-components.mjs
+++ b/tasks/screenshot-components.mjs
@@ -8,7 +8,6 @@ import { downloadBrowser } from 'puppeteer/lib/esm/puppeteer/node/install.js'
 import configPaths from '../config/paths.js'
 import { getDirectories, getListing } from '../lib/file-helper.js'
 import { goToComponent } from '../lib/puppeteer-helpers.js'
-import configPuppeteer from '../puppeteer.config.js'
 
 /**
  * Send all component screenshots to Percy
@@ -17,7 +16,7 @@ import configPuppeteer from '../puppeteer.config.js'
  * @returns {Promise<void>}
  */
 export async function screenshotComponents () {
-  const browser = await launch(configPuppeteer.launch)
+  const browser = await launch()
   const componentNames = await getDirectories(configPaths.components)
 
   // Screenshot each component

From c418bbea308b94454e8f10057445c9dd4377b8e4 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Thu, 19 Jan 2023 18:19:20 +0000
Subject: [PATCH 12/15] Fix various param/return types in source

Regarding fallback value types

* Preferring `null` for DOM method fallbacks
* Preferring `undefined` for string fallbacks
---
 src/govuk/common/closest-attribute-value.mjs  | 10 ++--
 .../closest-attribute-value.unit.test.mjs     |  4 +-
 .../error-summary/error-summary.mjs           | 10 ++--
 src/govuk/components/skip-link/skip-link.mjs  |  9 ++--
 src/govuk/components/tabs/tabs.mjs            | 10 ++--
 src/govuk/i18n.mjs                            | 50 +++++++++++--------
 6 files changed, 52 insertions(+), 41 deletions(-)

diff --git a/src/govuk/common/closest-attribute-value.mjs b/src/govuk/common/closest-attribute-value.mjs
index 94fd32cab1..df05cb728d 100644
--- a/src/govuk/common/closest-attribute-value.mjs
+++ b/src/govuk/common/closest-attribute-value.mjs
@@ -5,11 +5,11 @@ import '../vendor/polyfills/Element/prototype/closest.mjs'
  *
  * @param {HTMLElement} $element - The element to start walking the DOM tree up
  * @param {string} attributeName - The name of the attribute
- * @returns {string | undefined} Attribute value
+ * @returns {string | null} Attribute value
  */
 export function closestAttributeValue ($element, attributeName) {
-  var closestElementWithAttribute = $element.closest('[' + attributeName + ']')
-  if (closestElementWithAttribute) {
-    return closestElementWithAttribute.getAttribute(attributeName)
-  }
+  var $closestElementWithAttribute = $element.closest('[' + attributeName + ']')
+  return $closestElementWithAttribute
+    ? $closestElementWithAttribute.getAttribute(attributeName)
+    : null
 }
diff --git a/src/govuk/common/closest-attribute-value.unit.test.mjs b/src/govuk/common/closest-attribute-value.unit.test.mjs
index d9b7f8a7ab..c2b3851ec5 100644
--- a/src/govuk/common/closest-attribute-value.unit.test.mjs
+++ b/src/govuk/common/closest-attribute-value.unit.test.mjs
@@ -25,11 +25,11 @@ describe('closestAttributeValue', () => {
     expect(closestAttributeValue($element, 'lang')).toEqual('en-GB')
   })
 
-  it('returns undefined if neither the element or a parent have the attribute', () => {
+  it('returns null if neither the element or a parent have the attribute', () => {
     const $parent = document.createElement('div')
     const $element = document.createElement('div')
     $parent.appendChild($element)
 
-    expect(closestAttributeValue($element, 'lang')).toBeUndefined()
+    expect(closestAttributeValue($element, 'lang')).toBeNull()
   })
 })
diff --git a/src/govuk/components/error-summary/error-summary.mjs b/src/govuk/components/error-summary/error-summary.mjs
index 7cbb785fb1..e051383b77 100644
--- a/src/govuk/components/error-summary/error-summary.mjs
+++ b/src/govuk/components/error-summary/error-summary.mjs
@@ -112,6 +112,10 @@ ErrorSummary.prototype.focusTarget = function ($target) {
   }
 
   var inputId = this.getFragmentFromUrl($target.href)
+  if (!inputId) {
+    return false
+  }
+
   var $input = document.getElementById(inputId)
   if (!$input) {
     return false
@@ -138,11 +142,11 @@ ErrorSummary.prototype.focusTarget = function ($target) {
  * the hash.
  *
  * @param {string} url - URL
- * @returns {string} Fragment from URL, without the hash
+ * @returns {string | undefined} Fragment from URL, without the hash
  */
 ErrorSummary.prototype.getFragmentFromUrl = function (url) {
   if (url.indexOf('#') === -1) {
-    return false
+    return undefined
   }
 
   return url.split('#').pop()
@@ -160,7 +164,7 @@ ErrorSummary.prototype.getFragmentFromUrl = function (url) {
  * - The closest parent `<label>`
  *
  * @param {HTMLElement} $input - The input
- * @returns {HTMLElement} Associated legend or label, or null if no associated
+ * @returns {HTMLElement | null} Associated legend or label, or null if no associated
  *   legend or label can be found
  */
 ErrorSummary.prototype.getAssociatedLegendOrLabel = function ($input) {
diff --git a/src/govuk/components/skip-link/skip-link.mjs b/src/govuk/components/skip-link/skip-link.mjs
index 29401c0c93..2955de15ee 100644
--- a/src/govuk/components/skip-link/skip-link.mjs
+++ b/src/govuk/components/skip-link/skip-link.mjs
@@ -37,13 +37,12 @@ SkipLink.prototype.init = function () {
 /**
  * Get linked element
  *
- * @returns {HTMLElement} $linkedElement - DOM element linked to from the skip link
+ * @returns {HTMLElement | null} $linkedElement - DOM element linked to from the skip link
  */
 SkipLink.prototype.getLinkedElement = function () {
   var linkedElementId = this.getFragmentFromUrl()
-
   if (!linkedElementId) {
-    return false
+    return null
   }
 
   return document.getElementById(linkedElementId)
@@ -88,12 +87,12 @@ SkipLink.prototype.removeFocusProperties = function () {
  * Extract the fragment (everything after the hash symbol) from a URL, but not including
  * the symbol.
  *
- * @returns {string} Fragment from URL, without the hash symbol
+ * @returns {string | undefined} Fragment from URL, without the hash symbol
  */
 SkipLink.prototype.getFragmentFromUrl = function () {
   // Bail if the anchor link doesn't have a hash
   if (!this.$module.hash) {
-    return false
+    return
   }
 
   return this.$module.hash.split('#').pop()
diff --git a/src/govuk/components/tabs/tabs.mjs b/src/govuk/components/tabs/tabs.mjs
index 1e08f7e478..d7daf7d174 100644
--- a/src/govuk/components/tabs/tabs.mjs
+++ b/src/govuk/components/tabs/tabs.mjs
@@ -133,10 +133,9 @@ Tabs.prototype.teardown = function () {
 /**
  * Handle hashchange event
  *
- * @param {HashChangeEvent} event - Hash change event
  * @returns {void | undefined} Returns void, or undefined when prevented
  */
-Tabs.prototype.onHashChange = function (event) {
+Tabs.prototype.onHashChange = function () {
   var hash = window.location.hash
   var $tabWithHash = this.getTab(hash)
   if (!$tabWithHash) {
@@ -340,11 +339,10 @@ Tabs.prototype.activatePreviousTab = function () {
  * Get tab panel for tab link
  *
  * @param {HTMLAnchorElement} $tab - Tab link
- * @returns {HTMLDivElement} Tab panel
+ * @returns {HTMLElement | null} Tab panel
  */
 Tabs.prototype.getPanel = function ($tab) {
-  var $panel = this.$module.querySelector(this.getHref($tab))
-  return $panel
+  return this.$module.querySelector(this.getHref($tab))
 }
 
 /**
@@ -392,7 +390,7 @@ Tabs.prototype.highlightTab = function ($tab) {
 /**
  * Get current tab link
  *
- * @returns {HTMLAnchorElement | undefined} Tab link
+ * @returns {HTMLAnchorElement | null} Tab link
  */
 Tabs.prototype.getCurrentTab = function () {
   return this.$module.querySelector('.govuk-tabs__list-item--selected .govuk-tabs__tab')
diff --git a/src/govuk/i18n.mjs b/src/govuk/i18n.mjs
index d1318d7f80..f86e0eab37 100644
--- a/src/govuk/i18n.mjs
+++ b/src/govuk/i18n.mjs
@@ -76,29 +76,39 @@ I18n.prototype.replacePlaceholders = function (translationString, options) {
     formatter = new Intl.NumberFormat(this.locale)
   }
 
-  return translationString.replace(/%{(.\S+)}/g, function (placeholderWithBraces, placeholderKey) {
-    if (Object.prototype.hasOwnProperty.call(options, placeholderKey)) {
-      var placeholderValue = options[placeholderKey]
+  return translationString.replace(
+    /%{(.\S+)}/g,
 
-      // If a user has passed `false` as the value for the placeholder
-      // treat it as though the value should not be displayed
-      if (placeholderValue === false || (
-        typeof placeholderValue !== 'number' &&
-        typeof placeholderValue !== 'string')
-      ) {
-        return ''
-      }
+    /**
+     * Replace translation string placeholders
+     *
+     * @param {string} placeholderWithBraces - Placeholder with braces
+     * @param {string} placeholderKey - Placeholder key
+     * @returns {string} Placeholder value
+     */
+    function (placeholderWithBraces, placeholderKey) {
+      if (Object.prototype.hasOwnProperty.call(options, placeholderKey)) {
+        var placeholderValue = options[placeholderKey]
 
-      // If the placeholder's value is a number, localise the number formatting
-      if (typeof placeholderValue === 'number') {
-        return formatter ? formatter.format(placeholderValue) : placeholderValue.toString()
-      }
+        // If a user has passed `false` as the value for the placeholder
+        // treat it as though the value should not be displayed
+        if (placeholderValue === false || (
+          typeof placeholderValue !== 'number' &&
+          typeof placeholderValue !== 'string')
+        ) {
+          return ''
+        }
 
-      return placeholderValue
-    } else {
-      throw new Error('i18n: no data found to replace ' + placeholderWithBraces + ' placeholder in string')
-    }
-  })
+        // If the placeholder's value is a number, localise the number formatting
+        if (typeof placeholderValue === 'number') {
+          return formatter ? formatter.format(placeholderValue) : placeholderValue.toString()
+        }
+
+        return placeholderValue
+      } else {
+        throw new Error('i18n: no data found to replace ' + placeholderWithBraces + ' placeholder in string')
+      }
+    })
 }
 
 /**

From 0663ab3373736943e1b29fcf95473205ec382d17 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 5 Dec 2022 14:35:01 +0000
Subject: [PATCH 13/15] =?UTF-8?q?Allow=20compiler=20to=20cover=20=E2=80=9C?=
 =?UTF-8?q?else=E2=80=9D=20branched=20support=20checks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../character-count/character-count.mjs          | 10 +++++-----
 src/govuk/components/checkboxes/checkboxes.mjs   |  9 ++++-----
 src/govuk/components/header/header.mjs           | 16 ++++++++--------
 src/govuk/components/radios/radios.mjs           |  9 ++++-----
 4 files changed, 21 insertions(+), 23 deletions(-)

diff --git a/src/govuk/components/character-count/character-count.mjs b/src/govuk/components/character-count/character-count.mjs
index 8c0f3cc3ec..68f1164424 100644
--- a/src/govuk/components/character-count/character-count.mjs
+++ b/src/govuk/components/character-count/character-count.mjs
@@ -166,11 +166,11 @@ CharacterCount.prototype.init = function () {
   // state of the character count is not restored until *after* the
   // DOMContentLoaded event is fired, so we need to manually update it after the
   // pageshow event in browsers that support it.
-  if ('onpageshow' in window) {
-    window.addEventListener('pageshow', this.updateCountMessage.bind(this))
-  } else {
-    window.addEventListener('DOMContentLoaded', this.updateCountMessage.bind(this))
-  }
+  window.addEventListener(
+    'onpageshow' in window ? 'pageshow' : 'DOMContentLoaded',
+    this.updateCountMessage.bind(this)
+  )
+
   this.updateCountMessage()
 }
 
diff --git a/src/govuk/components/checkboxes/checkboxes.mjs b/src/govuk/components/checkboxes/checkboxes.mjs
index fcac5fa4b2..fe892081c8 100644
--- a/src/govuk/components/checkboxes/checkboxes.mjs
+++ b/src/govuk/components/checkboxes/checkboxes.mjs
@@ -53,11 +53,10 @@ Checkboxes.prototype.init = function () {
   // state of form controls is not restored until *after* the DOMContentLoaded
   // event is fired, so we need to sync after the pageshow event in browsers
   // that support it.
-  if ('onpageshow' in window) {
-    window.addEventListener('pageshow', this.syncAllConditionalReveals.bind(this))
-  } else {
-    window.addEventListener('DOMContentLoaded', this.syncAllConditionalReveals.bind(this))
-  }
+  window.addEventListener(
+    'onpageshow' in window ? 'pageshow' : 'DOMContentLoaded',
+    this.syncAllConditionalReveals.bind(this)
+  )
 
   // Although we've set up handlers to sync state on the pageshow or
   // DOMContentLoaded event, init could be called after those events have fired,
diff --git a/src/govuk/components/header/header.mjs b/src/govuk/components/header/header.mjs
index c2c1e4c161..cf26151c83 100644
--- a/src/govuk/components/header/header.mjs
+++ b/src/govuk/components/header/header.mjs
@@ -47,14 +47,14 @@ Header.prototype.init = function () {
     // Set the matchMedia to the govuk-frontend desktop breakpoint
     this.mql = window.matchMedia('(min-width: 48.0625em)')
 
-    if ('addEventListener' in this.mql) {
-      this.mql.addEventListener('change', this.syncState.bind(this))
-    } else {
-      // addListener is a deprecated function, however addEventListener
-      // isn't supported by IE or Safari. We therefore add this in as
-      // a fallback for those browsers
-      this.mql.addListener(this.syncState.bind(this))
-    }
+    var listenerMethod = 'addEventListener' in this.mql
+      ? 'addEventListener'
+      : 'addListener'
+
+    // addListener is a deprecated function, however addEventListener
+    // isn't supported by IE or Safari. We therefore add this in as
+    // a fallback for those browsers
+    this.mql[listenerMethod]('change', this.syncState.bind(this))
 
     this.syncState()
     this.$menuButton.addEventListener('click', this.handleMenuButtonClick.bind(this))
diff --git a/src/govuk/components/radios/radios.mjs b/src/govuk/components/radios/radios.mjs
index 92a843e572..cb79ac84f9 100644
--- a/src/govuk/components/radios/radios.mjs
+++ b/src/govuk/components/radios/radios.mjs
@@ -53,11 +53,10 @@ Radios.prototype.init = function () {
   // state of form controls is not restored until *after* the DOMContentLoaded
   // event is fired, so we need to sync after the pageshow event in browsers
   // that support it.
-  if ('onpageshow' in window) {
-    window.addEventListener('pageshow', this.syncAllConditionalReveals.bind(this))
-  } else {
-    window.addEventListener('DOMContentLoaded', this.syncAllConditionalReveals.bind(this))
-  }
+  window.addEventListener(
+    'onpageshow' in window ? 'pageshow' : 'DOMContentLoaded',
+    this.syncAllConditionalReveals.bind(this)
+  )
 
   // Although we've set up handlers to sync state on the pageshow or
   // DOMContentLoaded event, init could be called after those events have fired,

From 478f642cf76363694d57c20b1c71d7ed72d53c8a Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Tue, 6 Dec 2022 21:24:18 +0000
Subject: [PATCH 14/15] Move Tab bound handlers to constructor

Uses 3x handlers per component versus per tab link
---
 src/govuk/components/tabs/tabs.mjs | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/src/govuk/components/tabs/tabs.mjs b/src/govuk/components/tabs/tabs.mjs
index d7daf7d174..87a20dd9b1 100644
--- a/src/govuk/components/tabs/tabs.mjs
+++ b/src/govuk/components/tabs/tabs.mjs
@@ -19,6 +19,11 @@ function Tabs ($module) {
 
   this.keys = { left: 37, right: 39, up: 38, down: 40 }
   this.jsHiddenClass = 'govuk-tabs__panel--hidden'
+
+  // Save bounded functions to use when removing event listeners during teardown
+  this.boundTabClick = this.onTabClick.bind(this)
+  this.boundTabKeydown = this.onTabKeydown.bind(this)
+  this.boundOnHashChange = this.onHashChange.bind(this)
 }
 
 /**
@@ -76,13 +81,9 @@ Tabs.prototype.setup = function () {
     // Set HTML attributes
     $component.setAttributes($tab)
 
-    // Save bounded functions to use when removing event listeners during teardown
-    $tab.boundTabClick = $component.onTabClick.bind($component)
-    $tab.boundTabKeydown = $component.onTabKeydown.bind($component)
-
     // Handle events
-    $tab.addEventListener('click', $tab.boundTabClick, true)
-    $tab.addEventListener('keydown', $tab.boundTabKeydown, true)
+    $tab.addEventListener('click', $component.boundTabClick, true)
+    $tab.addEventListener('keydown', $component.boundTabKeydown, true)
 
     // Remove old active panels
     $component.hideTab($tab)
@@ -93,8 +94,7 @@ Tabs.prototype.setup = function () {
   this.showTab($activeTab)
 
   // Handle hashchange events
-  $module.boundOnHashChange = this.onHashChange.bind(this)
-  window.addEventListener('hashchange', $module.boundOnHashChange, true)
+  window.addEventListener('hashchange', this.boundOnHashChange, true)
 }
 
 /**
@@ -119,15 +119,15 @@ Tabs.prototype.teardown = function () {
 
   nodeListForEach($tabs, function ($tab) {
     // Remove events
-    $tab.removeEventListener('click', $tab.boundTabClick, true)
-    $tab.removeEventListener('keydown', $tab.boundTabKeydown, true)
+    $tab.removeEventListener('click', $component.boundTabClick, true)
+    $tab.removeEventListener('keydown', $component.boundTabKeydown, true)
 
     // Unset HTML attributes
     $component.unsetAttributes($tab)
   })
 
   // Remove hashchange event handler
-  window.removeEventListener('hashchange', $module.boundOnHashChange, true)
+  window.removeEventListener('hashchange', this.boundOnHashChange, true)
 }
 
 /**

From 0718c67a26694f8d6254a9c8a65317ad24c74496 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Mon, 19 Dec 2022 18:00:38 +0000
Subject: [PATCH 15/15] Update coding standards with JSDoc changes etc

Also includes:

1. Checks for `$module` on instantiation
2. Checks for selectors on init

We prefer `{Element}` type to `{HTMLElement}` etc to maintain compatibility with `querySelector`
---
 docs/contributing/coding-standards/js.md      |  96 ++++++++++-------
 src/govuk/all.mjs                             |   2 +-
 src/govuk/common/closest-attribute-value.mjs  |   2 +-
 src/govuk/common/index.mjs                    |   3 +
 src/govuk/components/accordion/accordion.mjs  |  55 +++++++---
 src/govuk/components/button/button.mjs        |  12 ++-
 .../character-count/character-count.mjs       |  14 ++-
 .../character-count.unit.test.mjs             |  31 ++++--
 .../components/checkboxes/checkboxes.mjs      |  26 ++++-
 src/govuk/components/details/details.mjs      |  13 ++-
 .../error-summary/error-summary.mjs           |  13 ++-
 src/govuk/components/header/header.mjs        |   9 +-
 .../notification-banner.mjs                   |  12 ++-
 src/govuk/components/radios/radios.mjs        |  24 ++++-
 src/govuk/components/skip-link/skip-link.mjs  |  14 ++-
 src/govuk/components/tabs/tabs.mjs            | 101 ++++++++++++++----
 16 files changed, 314 insertions(+), 113 deletions(-)

diff --git a/docs/contributing/coding-standards/js.md b/docs/contributing/coding-standards/js.md
index a319d57a9a..7b426700ef 100644
--- a/docs/contributing/coding-standards/js.md
+++ b/docs/contributing/coding-standards/js.md
@@ -5,25 +5,45 @@
 JavaScript files have the same name as the component's folder name. Test files have a `.test` suffix placed before the file extension.
 
 ```
-checkboxes
-├── checkboxes.mjs
-└── checkboxes.test.js
+component
+├── component.mjs
+└── component.test.js
 ```
 
 ## Skeleton
 
 ```js
-import { nodeListForEach } from '../vendor/common.mjs'
+import '../../vendor/polyfills/Element.mjs'
 
-function Checkboxes ($module) {
-  // code goes here
+/**
+ * Component name
+ *
+ * @class
+ * @param {Element} $module - HTML element to use for component
+ */
+function Example ($module) {
+  if (!$module) {
+    return this
+  }
+
+  this.$module = $module
+
+  // Code goes here
 }
 
-Checkboxes.prototype.init = function () {
-  // code goes here
+/**
+ * Initialise component
+ */
+Example.prototype.init = function () {
+  // Check that required elements are present
+  if (!this.$module) {
+    return
+  }
+
+  // Code goes here
 }
 
-export default Checkboxes
+export default Example
 ```
 
 ## Use data attributes to initialise component JavaScript
@@ -48,15 +68,15 @@ Use `/** ... */` for multi-line comments. Include a description, and specify typ
 
 ```js
 /**
-* Get the nearest ancestor element of a node that matches a given tag name
-* @param {object} node element
-* @param {string} match tag name (e.g. div)
-* @return {object} ancestor element
-*/
-
-function (node, match) {
-  // code goes here
-  return ancestor
+ * Get the first descendent (child) of an HTML element that matches a given tag name
+ *
+ * @param {Element} $element - HTML element
+ * @param {string} tagName - Tag name (for example 'div')
+ * @returns {Element} Ancestor element
+ */
+function ($element, tagName) {
+  // Code goes here
+  return $element.querySelector(tagName)
 }
 ```
 
@@ -73,52 +93,54 @@ Use the prototype design pattern to structure your code.
 Create a constructor and define any variables that the object needs.
 
 ```js
-function Checkboxes ($module) {
-  // code goes here
+function Example ($module) {
+  // Code goes here
 }
 ```
 
 Assign methods to the prototype object. Do not overwrite the prototype with a new object as this makes inheritance impossible.
 
 ```js
-// bad
-Checkboxes.prototype = {
+// Bad
+Example.prototype = {
   init: function () {
-    // code goes here
+    // Code goes here
   }
 }
 
-// good
-Checkboxes.prototype.init = function () {
-  // code goes here
+// Good
+Example.prototype.init = function () {
+  // Code goes here
 }
 ```
 
 When initialising an object, use the `new` keyword.
 
 ```js
-// bad
-var myCheckbox = Checkbox().init()
+// Bad
+var myExample = Example()
 
-// good
-var myCheckbox = new Checkbox().init()
+// Good
+var myExample = new Example()
 ```
 
 ## Modules
 
-Use ES6 modules (`import`/`export`) over a non-standard module system. You can always transpile to your preferred module system.
+Use ECMAScript modules (`import`/`export`) over CommonJS and other formats. You can always transpile to your preferred module system.
 
 ```js
-import { nodeListForEach } from '../vendor/common.mjs'
-// code goes here
-export default Checkboxes
+import { closestAttributeValue } from '../common/index.mjs'
+
+// Code goes here
+export function exampleHelper1 () {}
+export function exampleHelper2 () {}
 ```
 
-Avoid using wildcard (`import * as nodeListForEach`) imports.
+You must specify the file extension when using the import keyword.
 
-You must specify the file extension for a file when importing it.
+Avoid using namespace imports (`import * as namespace`) in code transpiled to CommonJS (or AMD) bundled code as this can prevent "tree shaking" optimisations.
 
-Use default export over named export.
+Prefer named exports over default exports to avoid compatibility issues with transpiler "synthetic default" as discussed in: https://github.com/alphagov/govuk-frontend/issues/2829
 
 ## Polyfilling
 
diff --git a/src/govuk/all.mjs b/src/govuk/all.mjs
index f90ce7c139..7c35ea3518 100644
--- a/src/govuk/all.mjs
+++ b/src/govuk/all.mjs
@@ -104,7 +104,7 @@ export {
  * Config for all components
  *
  * @typedef {object} Config
- * @property {HTMLElement} [scope=document] - Scope to query for components
+ * @property {Element} [scope=document] - Scope to query for components
  * @property {import('./components/accordion/accordion.mjs').AccordionConfig} [accordion] - Accordion config
  * @property {import('./components/button/button.mjs').ButtonConfig} [button] - Button config
  * @property {import('./components/character-count/character-count.mjs').CharacterCountConfig} [characterCount] - Character Count config
diff --git a/src/govuk/common/closest-attribute-value.mjs b/src/govuk/common/closest-attribute-value.mjs
index df05cb728d..3896784b25 100644
--- a/src/govuk/common/closest-attribute-value.mjs
+++ b/src/govuk/common/closest-attribute-value.mjs
@@ -3,7 +3,7 @@ import '../vendor/polyfills/Element/prototype/closest.mjs'
 /**
  * Returns the value of the given attribute closest to the given element (including itself)
  *
- * @param {HTMLElement} $element - The element to start walking the DOM tree up
+ * @param {Element} $element - The element to start walking the DOM tree up
  * @param {string} attributeName - The name of the attribute
  * @returns {string | null} Attribute value
  */
diff --git a/src/govuk/common/index.mjs b/src/govuk/common/index.mjs
index d798fb5c67..49beea09e3 100644
--- a/src/govuk/common/index.mjs
+++ b/src/govuk/common/index.mjs
@@ -135,10 +135,13 @@ export function extractConfigByNamespace (configObject, namespace) {
   if (!configObject || typeof configObject !== 'object') {
     throw new Error('Provide a `configObject` of type "object".')
   }
+
   if (!namespace || typeof namespace !== 'string') {
     throw new Error('Provide a `namespace` of type "string" to filter the `configObject` by.')
   }
+
   var newObject = {}
+
   for (var key in configObject) {
     // Split the key into parts, using . as our namespace separator
     var keyParts = key.split('.')
diff --git a/src/govuk/components/accordion/accordion.mjs b/src/govuk/components/accordion/accordion.mjs
index b3015bc689..5afdac88f4 100644
--- a/src/govuk/components/accordion/accordion.mjs
+++ b/src/govuk/components/accordion/accordion.mjs
@@ -38,10 +38,14 @@ var ACCORDION_TRANSLATIONS = {
  * attribute, which also provides accessibility.
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for accordion
+ * @param {Element} $module - HTML element to use for accordion
  * @param {AccordionConfig} [config] - Accordion config
  */
 function Accordion ($module, config) {
+  if (!$module) {
+    return this
+  }
+
   this.$module = $module
 
   var defaultConfig = {
@@ -79,7 +83,12 @@ function Accordion ($module, config) {
   this.sectionSummaryFocusClass = 'govuk-accordion__section-summary-focus'
   this.sectionContentClass = 'govuk-accordion__section-content'
 
-  this.$sections = this.$module.querySelectorAll('.' + this.sectionClass)
+  var $sections = this.$module.querySelectorAll('.' + this.sectionClass)
+  if (!$sections.length) {
+    return this
+  }
+
+  this.$sections = $sections
   this.browserSupportsSessionStorage = helper.checkForSessionStorage()
 }
 
@@ -87,8 +96,8 @@ function Accordion ($module, config) {
  * Initialise component
  */
 Accordion.prototype.init = function () {
-  // Check for module
-  if (!this.$module) {
+  // Check that required elements are present
+  if (!this.$module || !this.$sections) {
     return
   }
 
@@ -145,6 +154,9 @@ Accordion.prototype.initSectionHeaders = function () {
   // Loop through sections
   nodeListForEach($sections, function ($section, i) {
     var $header = $section.querySelector('.' + $component.sectionHeaderClass)
+    if (!$header) {
+      return
+    }
 
     // Set header attributes
     $component.constructHeaderMarkup($header, i)
@@ -162,7 +174,7 @@ Accordion.prototype.initSectionHeaders = function () {
 /**
  * Construct section header
  *
- * @param {HTMLElement} $header - Section header
+ * @param {Element} $header - Section header
  * @param {number} index - Section index
  */
 Accordion.prototype.constructHeaderMarkup = function ($header, index) {
@@ -170,6 +182,10 @@ Accordion.prototype.constructHeaderMarkup = function ($header, index) {
   var $heading = $header.querySelector('.' + this.sectionHeadingClass)
   var $summary = $header.querySelector('.' + this.sectionSummaryClass)
 
+  if (!$span || !$heading) {
+    return
+  }
+
   // Create a button element that will replace the '.govuk-accordion__section-button' span
   var $button = document.createElement('button')
   $button.setAttribute('type', 'button')
@@ -227,7 +243,7 @@ Accordion.prototype.constructHeaderMarkup = function ($header, index) {
   $button.appendChild(this.getButtonPunctuationEl())
 
   // If summary content exists add to DOM in correct order
-  if (typeof ($summary) !== 'undefined' && $summary !== null) {
+  if ($summary) {
     // Create a new `span` element and copy the summary line content from the original `div` to the
     // new `span`
     // This is because the summary line text is now inside a button element, which can only contain
@@ -267,7 +283,13 @@ Accordion.prototype.constructHeaderMarkup = function ($header, index) {
  * @param {Event} event - Generic event
  */
 Accordion.prototype.onBeforeMatch = function (event) {
-  var $section = event.target.closest('.' + this.sectionClass)
+  var $fragment = event.target
+  if (!$fragment) {
+    return
+  }
+
+  // Handle when fragment is inside section
+  var $section = $fragment.closest('.' + this.sectionClass)
   if ($section) {
     this.setExpanded(true, $section)
   }
@@ -276,7 +298,7 @@ Accordion.prototype.onBeforeMatch = function (event) {
 /**
  * When section toggled, set and store state
  *
- * @param {HTMLElement} $section - Section element
+ * @param {Element} $section - Section element
  */
 Accordion.prototype.onSectionToggle = function ($section) {
   var expanded = this.isExpanded($section)
@@ -309,7 +331,7 @@ Accordion.prototype.onShowOrHideAllToggle = function () {
  * Set section attributes when opened/closed
  *
  * @param {boolean} expanded - Section expanded
- * @param {HTMLElement} $section - Section element
+ * @param {Element} $section - Section element
  */
 Accordion.prototype.setExpanded = function (expanded, $section) {
   var $showHideIcon = $section.querySelector('.' + this.upChevronIconClass)
@@ -317,6 +339,13 @@ Accordion.prototype.setExpanded = function (expanded, $section) {
   var $button = $section.querySelector('.' + this.sectionButtonClass)
   var $content = $section.querySelector('.' + this.sectionContentClass)
 
+  if (!$showHideIcon ||
+    !$showHideText ||
+    !$button ||
+    !$content) {
+    return
+  }
+
   var newButtonText = expanded
     ? this.i18n.t('hideSection')
     : this.i18n.t('showSection')
@@ -368,7 +397,7 @@ Accordion.prototype.setExpanded = function (expanded, $section) {
 /**
  * Get state of section
  *
- * @param {HTMLElement} $section - Section element
+ * @param {Element} $section - Section element
  * @returns {boolean} True if expanded
  */
 Accordion.prototype.isExpanded = function ($section) {
@@ -434,7 +463,7 @@ var helper = {
 /**
  * Set the state of the accordions in sessionStorage
  *
- * @param {HTMLElement} $section - Section element
+ * @param {Element} $section - Section element
  */
 Accordion.prototype.storeState = function ($section) {
   if (this.browserSupportsSessionStorage) {
@@ -458,7 +487,7 @@ Accordion.prototype.storeState = function ($section) {
 /**
  * Read the state of the accordions from sessionStorage
  *
- * @param {HTMLElement} $section - Section element
+ * @param {Element} $section - Section element
  */
 Accordion.prototype.setInitialState = function ($section) {
   if (this.browserSupportsSessionStorage) {
@@ -482,7 +511,7 @@ Accordion.prototype.setInitialState = function ($section) {
  * into thematic chunks.
  * See https://github.com/alphagov/govuk-frontend/issues/2327#issuecomment-922957442
  *
- * @returns {HTMLElement} DOM element
+ * @returns {Element} DOM element
  */
 Accordion.prototype.getButtonPunctuationEl = function () {
   var $punctuationEl = document.createElement('span')
diff --git a/src/govuk/components/button/button.mjs b/src/govuk/components/button/button.mjs
index 8b521d4992..175fa95081 100644
--- a/src/govuk/components/button/button.mjs
+++ b/src/govuk/components/button/button.mjs
@@ -12,7 +12,7 @@ var DEBOUNCE_TIMEOUT_IN_SECONDS = 1
  * JavaScript enhancements for the Button component
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for button
+ * @param {Element} $module - HTML element to use for button
  * @param {ButtonConfig} [config] - Button config
  */
 function Button ($module, config) {
@@ -26,6 +26,7 @@ function Button ($module, config) {
   var defaultConfig = {
     preventDoubleClick: false
   }
+
   this.config = mergeConfigs(
     defaultConfig,
     config || {},
@@ -37,6 +38,7 @@ function Button ($module, config) {
  * Initialise component
  */
 Button.prototype.init = function () {
+  // Check that required elements are present
   if (!this.$module) {
     return
   }
@@ -58,7 +60,13 @@ Button.prototype.init = function () {
 Button.prototype.handleKeyDown = function (event) {
   var $target = event.target
 
-  if ($target.getAttribute('role') === 'button' && event.keyCode === KEY_SPACE) {
+  // Handle space bar only
+  if (event.keyCode !== KEY_SPACE) {
+    return
+  }
+
+  // Handle elements with [role="button"] only
+  if ($target.getAttribute('role') === 'button') {
     event.preventDefault() // prevent the page from scrolling
     $target.click()
   }
diff --git a/src/govuk/components/character-count/character-count.mjs b/src/govuk/components/character-count/character-count.mjs
index 68f1164424..a5ce9a0362 100644
--- a/src/govuk/components/character-count/character-count.mjs
+++ b/src/govuk/components/character-count/character-count.mjs
@@ -53,7 +53,7 @@ var CHARACTER_COUNT_TRANSLATIONS = {
  * of the available characters/words has been entered.
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for character count
+ * @param {Element} $module - HTML element to use for character count
  * @param {CharacterCountConfig} [config] - Character count config
  */
 function CharacterCount ($module, config) {
@@ -61,6 +61,11 @@ function CharacterCount ($module, config) {
     return this
   }
 
+  var $textarea = $module.querySelector('.govuk-js-character-count')
+  if (!$textarea) {
+    return this
+  }
+
   var defaultConfig = {
     threshold: 0,
     i18n: CHARACTER_COUNT_TRANSLATIONS
@@ -105,7 +110,7 @@ function CharacterCount ($module, config) {
   }
 
   this.$module = $module
-  this.$textarea = $module.querySelector('.govuk-js-character-count')
+  this.$textarea = $textarea
   this.$visibleCountMessage = null
   this.$screenReaderCountMessage = null
 
@@ -118,12 +123,15 @@ function CharacterCount ($module, config) {
  */
 CharacterCount.prototype.init = function () {
   // Check that required elements are present
-  if (!this.$textarea) {
+  if (!this.$module || !this.$textarea) {
     return
   }
 
   var $textarea = this.$textarea
   var $textareaDescription = document.getElementById($textarea.id + '-info')
+  if (!$textareaDescription) {
+    return
+  }
 
   // Inject a decription for the textarea if none is present already
   // for when the component was rendered with no maxlength, maxwords
diff --git a/src/govuk/components/character-count/character-count.unit.test.mjs b/src/govuk/components/character-count/character-count.unit.test.mjs
index 88aa6f92b4..5b75f2ab04 100644
--- a/src/govuk/components/character-count/character-count.unit.test.mjs
+++ b/src/govuk/components/character-count/character-count.unit.test.mjs
@@ -1,12 +1,25 @@
 import CharacterCount from './character-count.mjs'
 
 describe('CharacterCount', () => {
+  let $container
+  let $textarea
+
+  beforeAll(() => {
+    $container = document.createElement('div')
+    $textarea = document.createElement('textarea')
+
+    // Component checks that required elements are present
+    $textarea.classList.add('govuk-js-character-count')
+    $container.appendChild($textarea)
+  })
+
   describe('formatCountMessage', () => {
     describe('default configuration', () => {
       let component
+
       beforeAll(() => {
-        // The component won't initialise if we don't pass it an element
-        component = new CharacterCount(document.createElement('div'))
+        const $div = $container.cloneNode(true)
+        component = new CharacterCount($div)
       })
 
       const cases = [
@@ -37,7 +50,8 @@ describe('CharacterCount', () => {
     describe('i18n', () => {
       describe('JavaScript configuration', () => {
         it('overrides the default translation keys', () => {
-          const component = new CharacterCount(document.createElement('div'), {
+          const $div = $container.cloneNode(true)
+          const component = new CharacterCount($div, {
             i18n: { charactersUnderLimit: { one: 'Custom text. Count: %{count}' } }
           })
 
@@ -47,7 +61,8 @@ describe('CharacterCount', () => {
         })
 
         it('uses specific keys for when limit is reached', () => {
-          const component = new CharacterCount(document.createElement('div'), {
+          const $div = $container.cloneNode(true)
+          const component = new CharacterCount($div, {
             i18n: {
               charactersAtLimit: 'Custom text.',
               wordsAtLimit: 'Different custom text.'
@@ -61,7 +76,7 @@ describe('CharacterCount', () => {
 
       describe('lang attribute configuration', () => {
         it('overrides the locale when set on the element', () => {
-          const $div = document.createElement('div')
+          const $div = $container.cloneNode(true)
           $div.setAttribute('lang', 'de')
 
           const component = new CharacterCount($div)
@@ -73,7 +88,7 @@ describe('CharacterCount', () => {
           const $parent = document.createElement('div')
           $parent.setAttribute('lang', 'de')
 
-          const $div = document.createElement('div')
+          const $div = $container.cloneNode(true)
           $parent.appendChild($div)
 
           const component = new CharacterCount($div)
@@ -84,7 +99,7 @@ describe('CharacterCount', () => {
 
       describe('Data attribute configuration', () => {
         it('overrides the default translation keys', () => {
-          const $div = document.createElement('div')
+          const $div = $container.cloneNode(true)
           $div.setAttribute('data-i18n.characters-under-limit.one', 'Custom text. Count: %{count}')
 
           const component = new CharacterCount($div)
@@ -96,7 +111,7 @@ describe('CharacterCount', () => {
 
         describe('precedence over JavaScript configuration', () => {
           it('overrides translation keys', () => {
-            const $div = document.createElement('div')
+            const $div = $container.cloneNode(true)
             $div.setAttribute('data-i18n.characters-under-limit.one', 'Custom text. Count: %{count}')
 
             const component = new CharacterCount($div, {
diff --git a/src/govuk/components/checkboxes/checkboxes.mjs b/src/govuk/components/checkboxes/checkboxes.mjs
index fe892081c8..f90617d445 100644
--- a/src/govuk/components/checkboxes/checkboxes.mjs
+++ b/src/govuk/components/checkboxes/checkboxes.mjs
@@ -9,11 +9,20 @@ import '../../vendor/polyfills/Function/prototype/bind.mjs'
  * Checkboxes component
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for checkboxes
+ * @param {Element} $module - HTML element to use for checkboxes
  */
 function Checkboxes ($module) {
+  if (!$module) {
+    return this
+  }
+
+  var $inputs = $module.querySelectorAll('input[type="checkbox"]')
+  if (!$inputs.length) {
+    return this
+  }
+
   this.$module = $module
-  this.$inputs = $module.querySelectorAll('input[type="checkbox"]')
+  this.$inputs = $inputs
 }
 
 /**
@@ -31,6 +40,11 @@ function Checkboxes ($module) {
  * the reveal in sync with the checkbox state.
  */
 Checkboxes.prototype.init = function () {
+  // Check that required elements are present
+  if (!this.$module || !this.$inputs) {
+    return
+  }
+
   var $module = this.$module
   var $inputs = this.$inputs
 
@@ -83,8 +97,12 @@ Checkboxes.prototype.syncAllConditionalReveals = function () {
  * @param {HTMLInputElement} $input - Checkbox input
  */
 Checkboxes.prototype.syncConditionalRevealWithInputState = function ($input) {
-  var $target = document.getElementById($input.getAttribute('aria-controls'))
+  var targetId = $input.getAttribute('aria-controls')
+  if (!targetId) {
+    return
+  }
 
+  var $target = document.getElementById(targetId)
   if ($target && $target.classList.contains('govuk-checkboxes__conditional')) {
     var inputIsChecked = $input.checked
 
@@ -99,7 +117,7 @@ Checkboxes.prototype.syncConditionalRevealWithInputState = function ($input) {
  * Find any other checkbox inputs with the same name value, and uncheck them.
  * This is useful for when a “None of these" checkbox is checked.
  *
- * @param {HTMLElement} $input - Checkbox input
+ * @param {HTMLInputElement} $input - Checkbox input
  */
 Checkboxes.prototype.unCheckAllInputsExcept = function ($input) {
   var $component = this
diff --git a/src/govuk/components/details/details.mjs b/src/govuk/components/details/details.mjs
index e1f483a19e..a0c862a903 100644
--- a/src/govuk/components/details/details.mjs
+++ b/src/govuk/components/details/details.mjs
@@ -17,9 +17,13 @@ var KEY_SPACE = 32
  * Details component
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for details
+ * @param {Element} $module - HTML element to use for details
  */
 function Details ($module) {
+  if (!$module) {
+    return this
+  }
+
   this.$module = $module
 }
 
@@ -27,6 +31,7 @@ function Details ($module) {
  * Initialise component
  */
 Details.prototype.init = function () {
+  // Check that required elements are present
   if (!this.$module) {
     return
   }
@@ -34,11 +39,9 @@ Details.prototype.init = function () {
   // If there is native details support, we want to avoid running code to polyfill native behaviour.
   var hasNativeDetails = typeof this.$module.open === 'boolean'
 
-  if (hasNativeDetails) {
-    return
+  if (!hasNativeDetails) {
+    this.polyfillDetails()
   }
-
-  this.polyfillDetails()
 }
 
 /**
diff --git a/src/govuk/components/error-summary/error-summary.mjs b/src/govuk/components/error-summary/error-summary.mjs
index e051383b77..a04f55f781 100644
--- a/src/govuk/components/error-summary/error-summary.mjs
+++ b/src/govuk/components/error-summary/error-summary.mjs
@@ -12,7 +12,7 @@ import '../../vendor/polyfills/Function/prototype/bind.mjs'
  * Takes focus on initialisation for accessible announcement, unless disabled in configuration.
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for error summary
+ * @param {Element} $module - HTML element to use for error summary
  * @param {ErrorSummaryConfig} [config] - Error summary config
  */
 function ErrorSummary ($module, config) {
@@ -34,6 +34,7 @@ function ErrorSummary ($module, config) {
   var defaultConfig = {
     disableAutoFocus: false
   }
+
   this.config = mergeConfigs(
     defaultConfig,
     config || {},
@@ -45,11 +46,13 @@ function ErrorSummary ($module, config) {
  * Initialise component
  */
 ErrorSummary.prototype.init = function () {
-  var $module = this.$module
-  if (!$module) {
+  // Check that required elements are present
+  if (!this.$module) {
     return
   }
 
+  var $module = this.$module
+
   this.setFocus()
   $module.addEventListener('click', this.handleClick.bind(this))
 }
@@ -163,8 +166,8 @@ ErrorSummary.prototype.getFragmentFromUrl = function (url) {
  * - The first `<label>` that is associated with the input using for="inputId"
  * - The closest parent `<label>`
  *
- * @param {HTMLElement} $input - The input
- * @returns {HTMLElement | null} Associated legend or label, or null if no associated
+ * @param {Element} $input - The input
+ * @returns {Element | null} Associated legend or label, or null if no associated
  *   legend or label can be found
  */
 ErrorSummary.prototype.getAssociatedLegendOrLabel = function ($input) {
diff --git a/src/govuk/components/header/header.mjs b/src/govuk/components/header/header.mjs
index cf26151c83..20ffe1f2bc 100644
--- a/src/govuk/components/header/header.mjs
+++ b/src/govuk/components/header/header.mjs
@@ -7,11 +7,15 @@ import '../../vendor/polyfills/Function/prototype/bind.mjs'
  * Header component
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for header
+ * @param {Element} $module - HTML element to use for header
  */
 function Header ($module) {
+  if (!$module) {
+    return this
+  }
+
   this.$module = $module
-  this.$menuButton = $module && $module.querySelector('.govuk-js-header-toggle')
+  this.$menuButton = $module.querySelector('.govuk-js-header-toggle')
   this.$menu = this.$menuButton && $module.querySelector(
     '#' + this.$menuButton.getAttribute('aria-controls')
   )
@@ -39,6 +43,7 @@ function Header ($module) {
  * version of the menu to the user.
  */
 Header.prototype.init = function () {
+  // Check that required elements are present
   if (!this.$module || !this.$menuButton || !this.$menu) {
     return
   }
diff --git a/src/govuk/components/notification-banner/notification-banner.mjs b/src/govuk/components/notification-banner/notification-banner.mjs
index 8fba7cdb0b..a1bf0bc12d 100644
--- a/src/govuk/components/notification-banner/notification-banner.mjs
+++ b/src/govuk/components/notification-banner/notification-banner.mjs
@@ -6,15 +6,20 @@ import '../../vendor/polyfills/Event.mjs' // addEventListener, event.target norm
  * Notification Banner component
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for notification banner
+ * @param {Element} $module - HTML element to use for notification banner
  * @param {NotificationBannerConfig} [config] - Notification banner config
  */
 function NotificationBanner ($module, config) {
+  if (!$module) {
+    return this
+  }
+
   this.$module = $module
 
   var defaultConfig = {
     disableAutoFocus: false
   }
+
   this.config = mergeConfigs(
     defaultConfig,
     config || {},
@@ -26,9 +31,8 @@ function NotificationBanner ($module, config) {
  * Initialise component
  */
 NotificationBanner.prototype.init = function () {
-  var $module = this.$module
-  // Check for module
-  if (!$module) {
+  // Check that required elements are present
+  if (!this.$module) {
     return
   }
 
diff --git a/src/govuk/components/radios/radios.mjs b/src/govuk/components/radios/radios.mjs
index cb79ac84f9..e513c6abda 100644
--- a/src/govuk/components/radios/radios.mjs
+++ b/src/govuk/components/radios/radios.mjs
@@ -9,11 +9,20 @@ import '../../vendor/polyfills/Function/prototype/bind.mjs'
  * Radios component
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for radios
+ * @param {Element} $module - HTML element to use for radios
  */
 function Radios ($module) {
+  if (!$module) {
+    return this
+  }
+
+  var $inputs = $module.querySelectorAll('input[type="radio"]')
+  if (!$inputs.length) {
+    return this
+  }
+
   this.$module = $module
-  this.$inputs = $module.querySelectorAll('input[type="radio"]')
+  this.$inputs = $inputs
 }
 
 /**
@@ -31,6 +40,11 @@ function Radios ($module) {
  * the reveal in sync with the radio state.
  */
 Radios.prototype.init = function () {
+  // Check that required elements are present
+  if (!this.$module || !this.$inputs) {
+    return
+  }
+
   var $module = this.$module
   var $inputs = this.$inputs
 
@@ -83,8 +97,12 @@ Radios.prototype.syncAllConditionalReveals = function () {
  * @param {HTMLInputElement} $input - Radio input
  */
 Radios.prototype.syncConditionalRevealWithInputState = function ($input) {
-  var $target = document.getElementById($input.getAttribute('aria-controls'))
+  var targetId = $input.getAttribute('aria-controls')
+  if (!targetId) {
+    return
+  }
 
+  var $target = document.getElementById(targetId)
   if ($target && $target.classList.contains('govuk-radios__conditional')) {
     var inputIsChecked = $input.checked
 
diff --git a/src/govuk/components/skip-link/skip-link.mjs b/src/govuk/components/skip-link/skip-link.mjs
index 2955de15ee..23e35e5abd 100644
--- a/src/govuk/components/skip-link/skip-link.mjs
+++ b/src/govuk/components/skip-link/skip-link.mjs
@@ -8,9 +8,13 @@ import '../../vendor/polyfills/Function/prototype/bind.mjs'
  * Skip link component
  *
  * @class
- * @param {HTMLAnchorElement} $module - HTML element to use for skip link
+ * @param {Element} $module - HTML element to use for skip link
  */
 function SkipLink ($module) {
+  if (!$module) {
+    return this
+  }
+
   this.$module = $module
   this.$linkedElement = null
   this.linkedElementListener = false
@@ -20,17 +24,18 @@ function SkipLink ($module) {
  * Initialise component
  */
 SkipLink.prototype.init = function () {
-  // Check for module
+  // Check that required elements are present
   if (!this.$module) {
     return
   }
 
   // Check for linked element
-  this.$linkedElement = this.getLinkedElement()
-  if (!this.$linkedElement) {
+  var $linkedElement = this.getLinkedElement()
+  if (!$linkedElement) {
     return
   }
 
+  this.$linkedElement = $linkedElement
   this.$module.addEventListener('click', this.focusLinkedElement.bind(this))
 }
 
@@ -67,6 +72,7 @@ SkipLink.prototype.focusLinkedElement = function () {
       this.linkedElementListener = true
     }
   }
+
   $linkedElement.focus()
 }
 
diff --git a/src/govuk/components/tabs/tabs.mjs b/src/govuk/components/tabs/tabs.mjs
index 87a20dd9b1..7de9e82404 100644
--- a/src/govuk/components/tabs/tabs.mjs
+++ b/src/govuk/components/tabs/tabs.mjs
@@ -11,11 +11,20 @@ import '../../vendor/polyfills/Function/prototype/bind.mjs'
  * Tabs component
  *
  * @class
- * @param {HTMLElement} $module - HTML element to use for tabs
+ * @param {Element} $module - HTML element to use for tabs
  */
 function Tabs ($module) {
+  if (!$module) {
+    return this
+  }
+
+  var $tabs = $module.querySelectorAll('.govuk-tabs__tab')
+  if (!$tabs.length) {
+    return this
+  }
+
   this.$module = $module
-  this.$tabs = $module.querySelectorAll('.govuk-tabs__tab')
+  this.$tabs = $tabs
 
   this.keys = { left: 37, right: 39, up: 38, down: 40 }
   this.jsHiddenClass = 'govuk-tabs__panel--hidden'
@@ -30,6 +39,11 @@ function Tabs ($module) {
  * Initialise component
  */
 Tabs.prototype.init = function () {
+  // Check that required elements are present
+  if (!this.$module || !this.$tabs) {
+    return
+  }
+
   if (typeof window.matchMedia === 'function') {
     this.setupResponsiveChecks()
   } else {
@@ -91,6 +105,10 @@ Tabs.prototype.setup = function () {
 
   // Show either the active tab according to the URL's hash or the first tab
   var $activeTab = this.getTab(window.location.hash) || this.$tabs[0]
+  if (!$activeTab) {
+    return
+  }
+
   this.showTab($activeTab)
 
   // Handle hashchange events
@@ -150,6 +168,9 @@ Tabs.prototype.onHashChange = function () {
 
   // Show either the active tab according to the URL's hash or the first tab
   var $previousTab = this.getCurrentTab()
+  if (!$previousTab) {
+    return
+  }
 
   this.hideTab($previousTab)
   this.showTab($tabWithHash)
@@ -202,6 +223,10 @@ Tabs.prototype.setAttributes = function ($tab) {
 
   // set panel attributes
   var $panel = this.getPanel($tab)
+  if (!$panel) {
+    return
+  }
+
   $panel.setAttribute('role', 'tabpanel')
   $panel.setAttribute('aria-labelledby', $tab.id)
   $panel.classList.add(this.jsHiddenClass)
@@ -222,6 +247,10 @@ Tabs.prototype.unsetAttributes = function ($tab) {
 
   // unset panel attributes
   var $panel = this.getPanel($tab)
+  if (!$panel) {
+    return
+  }
+
   $panel.removeAttribute('role')
   $panel.removeAttribute('aria-labelledby')
   $panel.classList.remove(this.jsHiddenClass)
@@ -234,16 +263,23 @@ Tabs.prototype.unsetAttributes = function ($tab) {
  * @returns {void | false} Returns void, or false within tab link
  */
 Tabs.prototype.onTabClick = function (event) {
-  if (!event.target.classList.contains('govuk-tabs__tab')) {
-    // Allow events on child DOM elements to bubble up to tab parent
+  var $currentTab = this.getCurrentTab()
+  var $nextTab = event.target
+
+  if (!$currentTab || !$nextTab) {
+    return
+  }
+
+  // Allow events on child DOM elements to bubble up to tab parent
+  if (!$nextTab.classList.contains('govuk-tabs__tab')) {
     return false
   }
+
   event.preventDefault()
-  var $newTab = event.target
-  var $currentTab = this.getCurrentTab()
+
   this.hideTab($currentTab)
-  this.showTab($newTab)
-  this.createHistoryEntry($newTab)
+  this.showTab($nextTab)
+  this.createHistoryEntry($nextTab)
 }
 
 /**
@@ -256,6 +292,9 @@ Tabs.prototype.onTabClick = function (event) {
  */
 Tabs.prototype.createHistoryEntry = function ($tab) {
   var $panel = this.getPanel($tab)
+  if (!$panel) {
+    return
+  }
 
   // Save and restore the id
   // so the page doesn't jump when a user clicks a tab (which changes the hash)
@@ -294,7 +333,7 @@ Tabs.prototype.onTabKeydown = function (event) {
  */
 Tabs.prototype.activateNextTab = function () {
   var $currentTab = this.getCurrentTab()
-  if (!$currentTab) {
+  if (!$currentTab || !$currentTab.parentElement) {
     return
   }
 
@@ -304,12 +343,14 @@ Tabs.prototype.activateNextTab = function () {
   }
 
   var $nextTab = $nextTabListItem.querySelector('.govuk-tabs__tab')
-  if ($nextTab) {
-    this.hideTab($currentTab)
-    this.showTab($nextTab)
-    $nextTab.focus()
-    this.createHistoryEntry($nextTab)
+  if (!$nextTab) {
+    return
   }
+
+  this.hideTab($currentTab)
+  this.showTab($nextTab)
+  $nextTab.focus()
+  this.createHistoryEntry($nextTab)
 }
 
 /**
@@ -317,7 +358,7 @@ Tabs.prototype.activateNextTab = function () {
  */
 Tabs.prototype.activatePreviousTab = function () {
   var $currentTab = this.getCurrentTab()
-  if (!$currentTab) {
+  if (!$currentTab || !$currentTab.parentElement) {
     return
   }
 
@@ -327,19 +368,21 @@ Tabs.prototype.activatePreviousTab = function () {
   }
 
   var $previousTab = $previousTabListItem.querySelector('.govuk-tabs__tab')
-  if ($previousTab) {
-    this.hideTab($currentTab)
-    this.showTab($previousTab)
-    $previousTab.focus()
-    this.createHistoryEntry($previousTab)
+  if (!$previousTab) {
+    return
   }
+
+  this.hideTab($currentTab)
+  this.showTab($previousTab)
+  $previousTab.focus()
+  this.createHistoryEntry($previousTab)
 }
 
 /**
  * Get tab panel for tab link
  *
  * @param {HTMLAnchorElement} $tab - Tab link
- * @returns {HTMLElement | null} Tab panel
+ * @returns {Element | null} Tab panel
  */
 Tabs.prototype.getPanel = function ($tab) {
   return this.$module.querySelector(this.getHref($tab))
@@ -352,6 +395,10 @@ Tabs.prototype.getPanel = function ($tab) {
  */
 Tabs.prototype.showPanel = function ($tab) {
   var $panel = this.getPanel($tab)
+  if (!$panel) {
+    return
+  }
+
   $panel.classList.remove(this.jsHiddenClass)
 }
 
@@ -362,6 +409,10 @@ Tabs.prototype.showPanel = function ($tab) {
  */
 Tabs.prototype.hidePanel = function ($tab) {
   var $panel = this.getPanel($tab)
+  if (!$panel) {
+    return
+  }
+
   $panel.classList.add(this.jsHiddenClass)
 }
 
@@ -371,6 +422,10 @@ Tabs.prototype.hidePanel = function ($tab) {
  * @param {HTMLAnchorElement} $tab - Tab link
  */
 Tabs.prototype.unhighlightTab = function ($tab) {
+  if (!$tab.parentElement) {
+    return
+  }
+
   $tab.setAttribute('aria-selected', 'false')
   $tab.parentElement.classList.remove('govuk-tabs__list-item--selected')
   $tab.setAttribute('tabindex', '-1')
@@ -382,6 +437,10 @@ Tabs.prototype.unhighlightTab = function ($tab) {
  * @param {HTMLAnchorElement} $tab - Tab link
  */
 Tabs.prototype.highlightTab = function ($tab) {
+  if (!$tab.parentElement) {
+    return
+  }
+
   $tab.setAttribute('aria-selected', 'true')
   $tab.parentElement.classList.add('govuk-tabs__list-item--selected')
   $tab.setAttribute('tabindex', '0')