govuk_tech_docs 3.2.0 → 3.3.0

data/node_modules/govuk-frontend/govuk/all.js

@@ -4,10 +4,24 @@
 	(factory((global.GOVUKFrontend = {})));
 }(this, (function (exports) { 'use strict';
 
+/**
+ * Common helpers which do not require polyfill.
+ *
+ * IMPORTANT: If a helper require a polyfill, please isolate it in its own module
+ * so that the polyfill can be properly tree-shaken and does not burden
+ * the components that do not need that helper
+ *
+ * @module common/index
+ */
+
 /**
  * TODO: Ideally this would be a NodeList.prototype.forEach polyfill
  * 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
+ * @returns {undefined}
  */
 function nodeListForEach (nodes, callback) {
   if (window.NodeList.prototype.forEach) {
@@ -18,9 +32,13 @@ function nodeListForEach (nodes, callback) {
   }
 }
 
-// Used to generate a unique string, allows multiple instances of the component without
-// Them conflicting with each other.
-// https://stackoverflow.com/a/8809472
+/**
+ * Used to generate a unique string, allows multiple instances of the component
+ * without them conflicting with each other.
+ * https://stackoverflow.com/a/8809472
+ *
+ * @returns {string} Unique ID
+ */
 function generateUniqueID () {
   var d = new Date().getTime();
   if (typeof window.performance !== 'undefined' && typeof window.performance.now === 'function') {
@@ -33,6 +51,500 @@ function generateUniqueID () {
   })
 }
 
+/**
+ * Config flattening function
+ *
+ * Takes any number of objects, flattens them into namespaced key-value pairs,
+ * (e.g. {'i18n.showSection': 'Show section'}) and combines them together, with
+ * greatest priority on the LAST item passed in.
+ *
+ * @returns {object} A flattened object of key-value pairs.
+ */
+function mergeConfigs (/* configObject1, configObject2, ...configObjects */) {
+  /**
+   * Function to take nested objects and flatten them to a dot-separated keyed
+   * object. Doing this means we don't need to do any deep/recursive merging of
+   * each of our objects, nor transform our dataset from a flat list into a
+   * nested object.
+   *
+   * @param {object} configObject - Deeply nested object
+   * @returns {object} Flattened object with dot-separated keys
+   */
+  var flattenObject = function (configObject) {
+    // Prepare an empty return object
+    var flattenedObject = {};
+
+    // Our flattening function, this is called recursively for each level of
+    // depth in the object. At each level we prepend the previous level names to
+    // the key using `prefix`.
+    var flattenLoop = function (obj, prefix) {
+      // Loop through keys...
+      for (var key in obj) {
+        // Check to see if this is a prototypical key/value,
+        // if it is, skip it.
+        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+          continue
+        }
+        var value = obj[key];
+        var prefixedKey = prefix ? prefix + '.' + key : key;
+        if (typeof value === 'object') {
+          // If the value is a nested object, recurse over that too
+          flattenLoop(value, prefixedKey);
+        } else {
+          // Otherwise, add this value to our return object
+          flattenedObject[prefixedKey] = value;
+        }
+      }
+    };
+
+    // Kick off the recursive loop
+    flattenLoop(configObject);
+    return flattenedObject
+  };
+
+  // Start with an empty object as our base
+  var formattedConfigObject = {};
+
+  // Loop through each of the remaining passed objects and push their keys
+  // one-by-one into configObject. Any duplicate keys will override the existing
+  // key with the new value.
+  for (var i = 0; i < arguments.length; i++) {
+    var obj = flattenObject(arguments[i]);
+    for (var key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        formattedConfigObject[key] = obj[key];
+      }
+    }
+  }
+
+  return formattedConfigObject
+}
+
+/**
+ * Extracts keys starting with a particular namespace from a flattened config
+ * object, removing the namespace in the process.
+ *
+ * @param {object} configObject - The object to extract key-value pairs from.
+ * @param {string} namespace - The namespace to filter keys with.
+ * @returns {object} Flattened object with dot-separated key namespace removed
+ */
+function extractConfigByNamespace (configObject, namespace) {
+  // Check we have what we need
+  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('.');
+    // Check if the first namespace matches the configured namespace
+    if (Object.prototype.hasOwnProperty.call(configObject, key) && keyParts[0] === namespace) {
+      // Remove the first item (the namespace) from the parts array,
+      // but only if there is more than one part (we don't want blank keys!)
+      if (keyParts.length > 1) {
+        keyParts.shift();
+      }
+      // Join the remaining parts back together
+      var newKey = keyParts.join('.');
+      // Add them to our new object
+      newObject[newKey] = configObject[key];
+    }
+  }
+  return newObject
+}
+
+/**
+ * @callback nodeListIterator
+ * @param {Element} value - The current node being iterated on
+ * @param {number} index - The current index in the iteration
+ * @param {NodeListOf<Element>} nodes - NodeList from querySelectorAll()
+ * @returns {undefined}
+ */
+
+/**
+ * Internal support for selecting messages to render, with placeholder
+ * interpolation and locale-aware number formatting and pluralisation
+ *
+ * @class
+ * @private
+ * @param {TranslationsFlattened} translations - Key-value pairs of the translation strings to use.
+ * @param {object} [config] - Configuration options for the function.
+ * @param {string} config.locale - An overriding locale for the PluralRules functionality.
+ */
+function I18n (translations, config) {
+  // Make list of translations available throughout function
+  this.translations = translations || {};
+
+  // The locale to use for PluralRules and NumberFormat
+  this.locale = (config && config.locale) || document.documentElement.lang || 'en';
+}
+
+/**
+ * The most used function - takes the key for a given piece of UI text and
+ * returns the appropriate string.
+ *
+ * @param {string} lookupKey - The lookup key of the string to use.
+ * @param {object} options - Any options passed with the translation string, e.g: for string interpolation.
+ * @returns {string} The appropriate translation string.
+ */
+I18n.prototype.t = function (lookupKey, options) {
+  if (!lookupKey) {
+    // Print a console error if no lookup key has been provided
+    throw new Error('i18n: lookup key missing')
+  }
+
+  // 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
+  // falsy, as this could legitimately be 0.
+  if (options && typeof options.count !== 'undefined') {
+    // Get the plural suffix
+    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];
+
+    // Check for ${} placeholders in the translation string
+    if (translationString.match(/%{(.\S+)}/)) {
+      if (!options) {
+        throw new Error('i18n: cannot replace placeholders in string if no option data provided')
+      }
+
+      return this.replacePlaceholders(translationString, options)
+    } else {
+      return translationString
+    }
+  } else {
+    // If the key wasn't found in our translations object,
+    // return the lookup key itself as the fallback
+    return lookupKey
+  }
+};
+
+/**
+ * Takes a translation string with placeholders, and replaces the placeholders
+ * with the provided data
+ *
+ * @param {string} translationString - The translation string
+ * @param {object} options - Any options passed with the translation string, e.g: for string interpolation.
+ * @returns {string} The translation string to output, with ${} placeholders replaced
+ */
+I18n.prototype.replacePlaceholders = function (translationString, options) {
+  var formatter;
+
+  if (this.hasIntlNumberFormatSupport()) {
+    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];
+
+      // 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) {
+        return ''
+      }
+
+      // If the placeholder's value is a number, localise the number formatting
+      if (typeof placeholderValue === 'number' && formatter) {
+        return formatter.format(placeholderValue)
+      }
+
+      return placeholderValue
+    } else {
+      throw new Error('i18n: no data found to replace ' + placeholderWithBraces + ' placeholder in string')
+    }
+  })
+};
+
+/**
+ * Check to see if the browser supports Intl and Intl.PluralRules.
+ *
+ * It requires all conditions to be met in order to be supported:
+ * - The browser supports the Intl class (true in IE11)
+ * - The implementation of Intl supports PluralRules (NOT true in IE11)
+ * - The browser/OS has plural rules for the current locale (browser dependent)
+ *
+ * @returns {boolean} Returns true if all conditions are met. Returns false otherwise.
+ */
+I18n.prototype.hasIntlPluralRulesSupport = function () {
+  return Boolean(window.Intl && ('PluralRules' in window.Intl && Intl.PluralRules.supportedLocalesOf(this.locale).length))
+};
+
+/**
+ * Check to see if the browser supports Intl and Intl.NumberFormat.
+ *
+ * It requires all conditions to be met in order to be supported:
+ * - The browser supports the Intl class (true in IE11)
+ * - The implementation of Intl supports NumberFormat (also true in IE11)
+ * - The browser/OS has number formatting rules for the current locale (browser dependent)
+ *
+ * @returns {boolean} Returns true if all conditions are met. Returns false otherwise.
+ */
+I18n.prototype.hasIntlNumberFormatSupport = function () {
+  return Boolean(window.Intl && ('NumberFormat' in window.Intl && Intl.NumberFormat.supportedLocalesOf(this.locale).length))
+};
+
+/**
+ * Get the appropriate suffix for the plural form.
+ *
+ * Uses Intl.PluralRules (or our own fallback implementation) to get the
+ * 'preferred' form to use for the given count.
+ *
+ * Checks that a translation has been provided for that plural form – if it
+ * hasn't, it'll fall back to the 'other' plural form (unless that doesn't exist
+ * either, in which case an error will be thrown)
+ *
+ * @param {string} lookupKey - The lookup key of the string to use.
+ * @param {number} count - Number used to determine which pluralisation to use.
+ * @returns {PluralRule} The suffix associated with the correct pluralisation for this locale.
+ */
+I18n.prototype.getPluralSuffix = function (lookupKey, count) {
+  // Validate that the number is actually a number.
+  //
+  // Number(count) will turn anything that can't be converted to a Number type
+  // into 'NaN'. isFinite filters out NaN, as it isn't a finite number.
+  count = Number(count);
+  if (!isFinite(count)) { return 'other' }
+
+  var preferredForm;
+
+  // Check to verify that all the requirements for Intl.PluralRules are met.
+  // If so, we can use that instead of our custom implementation. Otherwise,
+  // use the hardcoded fallback.
+  if (this.hasIntlPluralRulesSupport()) {
+    preferredForm = new Intl.PluralRules(this.locale).select(count);
+  } else {
+    preferredForm = this.selectPluralFormUsingFallbackRules(count);
+  }
+
+  // Use the correct plural form if provided
+  if (lookupKey + '.' + preferredForm in this.translations) {
+    return preferredForm
+  // Fall back to `other` if the plural form is missing, but log a warning
+  // to the console
+  } else if (lookupKey + '.other' in this.translations) {
+    if (console && 'warn' in console) {
+      console.warn('i18n: Missing plural form ".' + preferredForm + '" for "' +
+        this.locale + '" locale. Falling back to ".other".');
+    }
+
+    return 'other'
+  // If the required `other` plural form is missing, all we can do is error
+  } else {
+    throw new Error(
+      'i18n: Plural form ".other" is required for "' + this.locale + '" locale'
+    )
+  }
+};
+
+/**
+ * Get the plural form using our fallback implementation
+ *
+ * This is split out into a separate function to make it easier to test the
+ * fallback behaviour in an environment where Intl.PluralRules exists.
+ *
+ * @param {number} count - Number used to determine which pluralisation to use.
+ * @returns {PluralRule} The pluralisation form for count in this locale.
+ */
+I18n.prototype.selectPluralFormUsingFallbackRules = function (count) {
+  // Currently our custom code can only handle positive integers, so let's
+  // make sure our number is one of those.
+  count = Math.abs(Math.floor(count));
+
+  var ruleset = this.getPluralRulesForLocale();
+
+  if (ruleset) {
+    return I18n.pluralRules[ruleset](count)
+  }
+
+  return 'other'
+};
+
+/**
+ * Work out which pluralisation rules to use for the current locale
+ *
+ * The locale may include a regional indicator (such as en-GB), but we don't
+ * usually care about this part, as pluralisation rules are usually the same
+ * 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
+ *   of the functions in this.pluralRules)
+ */
+I18n.prototype.getPluralRulesForLocale = function () {
+  var locale = this.locale;
+  var localeShort = locale.split('-')[0];
+
+  // Look through the plural rules map to find which `pluralRule` is
+  // appropriate for our current `locale`.
+  for (var pluralRule in I18n.pluralRulesMap) {
+    if (Object.prototype.hasOwnProperty.call(I18n.pluralRulesMap, pluralRule)) {
+      var languages = I18n.pluralRulesMap[pluralRule];
+      for (var i = 0; i < languages.length; i++) {
+        if (languages[i] === locale || languages[i] === localeShort) {
+          return pluralRule
+        }
+      }
+    }
+  }
+};
+
+/**
+ * Map of plural rules to languages where those rules apply.
+ *
+ * Note: These groups are named for the most dominant or recognisable language
+ * that uses each system. The groupings do not imply that the languages are
+ * related to one another. Many languages have evolved the same systems
+ * independently of one another.
+ *
+ * Code to support more languages can be found in the i18n spike:
+ * {@link https://github.com/alphagov/govuk-frontend/blob/spike-i18n-support/src/govuk/i18n.mjs}
+ *
+ * Languages currently supported:
+ *
+ * Arabic: Arabic (ar)
+ * Chinese: Burmese (my), Chinese (zh), Indonesian (id), Japanese (ja),
+ *   Javanese (jv), Korean (ko), Malay (ms), Thai (th), Vietnamese (vi)
+ * French: Armenian (hy), Bangla (bn), French (fr), Gujarati (gu), Hindi (hi),
+ *   Persian Farsi (fa), Punjabi (pa), Zulu (zu)
+ * German: Afrikaans (af), Albanian (sq), Azerbaijani (az), Basque (eu),
+ *   Bulgarian (bg), Catalan (ca), Danish (da), Dutch (nl), English (en),
+ *   Estonian (et), Finnish (fi), Georgian (ka), German (de), Greek (el),
+ *   Hungarian (hu), Luxembourgish (lb), Norwegian (no), Somali (so),
+ *   Swahili (sw), Swedish (sv), Tamil (ta), Telugu (te), Turkish (tr),
+ *   Urdu (ur)
+ * Irish: Irish Gaelic (ga)
+ * Russian: Russian (ru), Ukrainian (uk)
+ * Scottish: Scottish Gaelic (gd)
+ * Spanish: European Portuguese (pt-PT), Italian (it), Spanish (es)
+ * Welsh: Welsh (cy)
+ *
+ * @type {Object<PluralRuleName, string[]>}
+ */
+I18n.pluralRulesMap = {
+  arabic: ['ar'],
+  chinese: ['my', 'zh', 'id', 'ja', 'jv', 'ko', 'ms', 'th', 'vi'],
+  french: ['hy', 'bn', 'fr', 'gu', 'hi', 'fa', 'pa', 'zu'],
+  german: [
+    'af', 'sq', 'az', 'eu', 'bg', 'ca', 'da', 'nl', 'en', 'et', 'fi', 'ka',
+    'de', 'el', 'hu', 'lb', 'no', 'so', 'sw', 'sv', 'ta', 'te', 'tr', 'ur'
+  ],
+  irish: ['ga'],
+  russian: ['ru', 'uk'],
+  scottish: ['gd'],
+  spanish: ['pt-PT', 'it', 'es'],
+  welsh: ['cy']
+};
+
+/**
+ * Different pluralisation rule sets
+ *
+ * Returns the appropriate suffix for the plural form associated with `n`.
+ * Possible suffixes: 'zero', 'one', 'two', 'few', 'many', 'other' (the actual
+ * meaning of each differs per locale). 'other' should always exist, even in
+ * languages without plurals, such as Chinese.
+ * {@link https://cldr.unicode.org/index/cldr-spec/plural-rules}
+ *
+ * The count must be a positive integer. Negative numbers and decimals aren't accounted for
+ *
+ * @type {Object<string, function(number): PluralRule>}
+ */
+I18n.pluralRules = {
+  arabic: function (n) {
+    if (n === 0) { return 'zero' }
+    if (n === 1) { return 'one' }
+    if (n === 2) { return 'two' }
+    if (n % 100 >= 3 && n % 100 <= 10) { return 'few' }
+    if (n % 100 >= 11 && n % 100 <= 99) { return 'many' }
+    return 'other'
+  },
+  chinese: function () {
+    return 'other'
+  },
+  french: function (n) {
+    return n === 0 || n === 1 ? 'one' : 'other'
+  },
+  german: function (n) {
+    return n === 1 ? 'one' : 'other'
+  },
+  irish: function (n) {
+    if (n === 1) { return 'one' }
+    if (n === 2) { return 'two' }
+    if (n >= 3 && n <= 6) { return 'few' }
+    if (n >= 7 && n <= 10) { return 'many' }
+    return 'other'
+  },
+  russian: function (n) {
+    var lastTwo = n % 100;
+    var last = lastTwo % 10;
+    if (last === 1 && lastTwo !== 11) { return 'one' }
+    if (last >= 2 && last <= 4 && !(lastTwo >= 12 && lastTwo <= 14)) { return 'few' }
+    if (last === 0 || (last >= 5 && last <= 9) || (lastTwo >= 11 && lastTwo <= 14)) { return 'many' }
+    // Note: The 'other' suffix is only used by decimal numbers in Russian.
+    // We don't anticipate it being used, but it's here for consistency.
+    return 'other'
+  },
+  scottish: function (n) {
+    if (n === 1 || n === 11) { return 'one' }
+    if (n === 2 || n === 12) { return 'two' }
+    if ((n >= 3 && n <= 10) || (n >= 13 && n <= 19)) { return 'few' }
+    return 'other'
+  },
+  spanish: function (n) {
+    if (n === 1) { return 'one' }
+    if (n % 1000000 === 0 && n !== 0) { return 'many' }
+    return 'other'
+  },
+  welsh: function (n) {
+    if (n === 0) { return 'zero' }
+    if (n === 1) { return 'one' }
+    if (n === 2) { return 'two' }
+    if (n === 3) { return 'few' }
+    if (n === 6) { return 'many' }
+    return 'other'
+  }
+};
+
+/**
+ * Supported languages for plural rules
+ *
+ * @typedef {'arabic' | 'chinese' | 'french' | 'german' | 'irish' | 'russian' | 'scottish' | 'spanish' | 'welsh'} PluralRuleName
+ */
+
+/**
+ * Plural rule category mnemonic tags
+ *
+ * @typedef {'zero' | 'one' | 'two' | 'few' | 'many' | 'other'} PluralRule
+ */
+
+/**
+ * Translated message by plural rule they correspond to.
+ *
+ * Allows to group pluralised messages under a single key when passing
+ * translations to a component's constructor
+ *
+ * @typedef {object} TranslationPluralForms
+ * @property {string} [other] - General plural form
+ * @property {string} [zero] - Plural form used with 0
+ * @property {string} [one] - Plural form used with 1
+ * @property {string} [two] - Plural form used with 2
+ * @property {string} [few] - Plural form used for a few
+ * @property {string} [many] - Plural form used for many
+ */
+
+/**
+ * Translated messages (flattened)
+ *
+ * @private
+ * @typedef {Object<string, string> | {}} TranslationsFlattened
+ */
+
 (function(undefined) {
 
 // Detection from https://github.com/Financial-Times/polyfill-service/blob/master/packages/polyfill-library/polyfills/Object/defineProperty/detect.js
@@ -773,13 +1285,188 @@ if (detect) return
 
 }).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
 
-function Accordion ($module) {
+(function(undefined) {
+
+    // Detection from https://github.com/mdn/content/blob/cf607d68522cd35ee7670782d3ee3a361eaef2e4/files/en-us/web/javascript/reference/global_objects/string/trim/index.md#polyfill
+    var detect = ('trim' in String.prototype);
+    
+    if (detect) return
+
+    // Polyfill from https://github.com/mdn/content/blob/cf607d68522cd35ee7670782d3ee3a361eaef2e4/files/en-us/web/javascript/reference/global_objects/string/trim/index.md#polyfill
+    String.prototype.trim = function () {
+        return this.replace(/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g, '');
+    };
+
+}).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
+
+(function(undefined) {
+
+  // Detection from https://raw.githubusercontent.com/Financial-Times/polyfill-library/13cf7c340974d128d557580b5e2dafcd1b1192d1/polyfills/Element/prototype/dataset/detect.js
+  var detect = (function(){
+    if (!document.documentElement.dataset) {
+      return false;
+    }
+    var el = document.createElement('div');
+    el.setAttribute("data-a-b", "c");
+    return el.dataset && el.dataset.aB == "c";
+  }());
+
+  if (detect) return
+
+  // Polyfill derived from  https://raw.githubusercontent.com/Financial-Times/polyfill-library/13cf7c340974d128d557580b5e2dafcd1b1192d1/polyfills/Element/prototype/dataset/polyfill.js
+  Object.defineProperty(Element.prototype, 'dataset', {
+    get: function() {
+      var element = this;
+      var attributes = this.attributes;
+      var map = {};
+  
+      for (var i = 0; i < attributes.length; i++) {
+        var attribute = attributes[i];
+  
+        // This regex has been edited from the original polyfill, to add
+        // support for period (.) separators in data-* attribute names. These
+        // are allowed in the HTML spec, but were not covered by the original
+        // polyfill's regex. We use periods in our i18n implementation.
+        if (attribute && attribute.name && (/^data-\w[.\w-]*$/).test(attribute.name)) {
+          var name = attribute.name;
+          var value = attribute.value;
+  
+          var propName = name.substr(5).replace(/-./g, function (prop) {
+            return prop.charAt(1).toUpperCase();
+          });
+          
+          // If this browser supports __defineGetter__ and __defineSetter__,
+          // continue using defineProperty. If not (like IE 8 and below), we use
+          // a hacky fallback which at least gives an object in the right format
+          if ('__defineGetter__' in Object.prototype && '__defineSetter__' in Object.prototype) {
+            Object.defineProperty(map, propName, {
+              enumerable: true,
+              get: function() {
+                return this.value;
+              }.bind({value: value || ''}),
+              set: function setter(name, value) {
+                if (typeof value !== 'undefined') {
+                  this.setAttribute(name, value);
+                } else {
+                  this.removeAttribute(name);
+                }
+              }.bind(element, name)
+            });
+          } else {
+            map[propName] = value;
+          }
+
+        }
+      }
+  
+      return map;
+    }
+  });
+
+}).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
+
+/**
+ * Normalise string
+ *
+ * 'If it looks like a duck, and it quacks like a duck…' 🦆
+ *
+ * If the passed value looks like a boolean or a number, convert it to a boolean
+ * or number.
+ *
+ * Designed to be used to convert config passed via data attributes (which are
+ * always strings) into something sensible.
+ *
+ * @param {string} value - The value to normalise
+ * @returns {string | boolean | number | undefined} Normalised data
+ */
+function normaliseString (value) {
+  if (typeof value !== 'string') {
+    return value
+  }
+
+  var trimmedValue = value.trim();
+
+  if (trimmedValue === 'true') {
+    return true
+  }
+
+  if (trimmedValue === 'false') {
+    return false
+  }
+
+  // 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)) {
+    return Number(trimmedValue)
+  }
+
+  return value
+}
+
+/**
+ * Normalise dataset
+ *
+ * Loop over an object and normalise each value using normaliseData function
+ *
+ * @param {DOMStringMap} dataset - HTML element dataset
+ * @returns {Object<string, string | boolean | number | undefined>} Normalised dataset
+ */
+function normaliseDataset (dataset) {
+  var out = {};
+
+  for (var key in dataset) {
+    out[key] = normaliseString(dataset[key]);
+  }
+
+  return out
+}
+
+/**
+ * @constant
+ * @type {AccordionTranslations}
+ * @see Default value for {@link AccordionConfig.i18n}
+ * @default
+ */
+var ACCORDION_TRANSLATIONS = {
+  hideAllSections: 'Hide all sections',
+  hideSection: 'Hide',
+  hideSectionAriaLabel: 'Hide this section',
+  showAllSections: 'Show all sections',
+  showSection: 'Show',
+  showSectionAriaLabel: 'Show this section'
+};
+
+/**
+ * Accordion component
+ *
+ * This allows a collection of sections to be collapsed by default, showing only
+ * their headers. Sections can be expanded or collapsed individually by clicking
+ * their headers. A "Show all sections" button is also added to the top of the
+ * accordion, which switches to "Hide all sections" when all the sections are
+ * expanded.
+ *
+ * The state of each section is saved to the DOM via the `aria-expanded`
+ * attribute, which also provides accessibility.
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for accordion
+ * @param {AccordionConfig} [config] - Accordion config
+ */
+function Accordion ($module, config) {
   this.$module = $module;
-  this.moduleId = $module.getAttribute('id');
   this.$sections = $module.querySelectorAll('.govuk-accordion__section');
-  this.$showAllButton = '';
   this.browserSupportsSessionStorage = helper.checkForSessionStorage();
 
+  var defaultConfig = {
+    i18n: ACCORDION_TRANSLATIONS
+  };
+  this.config = mergeConfigs(
+    defaultConfig,
+    config || {},
+    normaliseDataset($module.dataset)
+  );
+  this.i18n = new I18n(extractConfigByNamespace(this.config, 'i18n'));
+
   this.controlsClass = 'govuk-accordion__controls';
   this.showAllClass = 'govuk-accordion__show-all';
   this.showAllTextClass = 'govuk-accordion__show-all-text';
@@ -870,7 +1557,7 @@ Accordion.prototype.constructHeaderMarkup = function ($headerWrapper, 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.moduleId + '-content-' + (index + 1));
+  $button.setAttribute('aria-controls', this.$module.id + '-content-' + (index + 1));
 
   // 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++) {
@@ -987,17 +1674,34 @@ Accordion.prototype.setExpanded = function (expanded, $section) {
   var $icon = $section.querySelector('.' + this.upChevronIconClass);
   var $showHideText = $section.querySelector('.' + this.sectionShowHideTextClass);
   var $button = $section.querySelector('.' + this.sectionButtonClass);
-  var $newButtonText = expanded ? 'Hide' : 'Show';
-
-  // Build additional copy of "this section" for assistive technology and place inside toggle link
-  var $visuallyHiddenText = document.createElement('span');
-  $visuallyHiddenText.classList.add('govuk-visually-hidden');
-  $visuallyHiddenText.innerHTML = ' this section';
+  var newButtonText = expanded
+    ? this.i18n.t('hideSection')
+    : this.i18n.t('showSection');
 
-  $showHideText.innerHTML = $newButtonText;
-  $showHideText.appendChild($visuallyHiddenText);
+  $showHideText.innerText = newButtonText;
   $button.setAttribute('aria-expanded', expanded);
 
+  // Update aria-label combining
+  var $header = $section.querySelector('.' + this.sectionHeadingTextClass);
+  var ariaLabelParts = [$header.innerText.trim()];
+
+  var $summary = $section.querySelector('.' + this.sectionSummaryClass);
+  if ($summary) {
+    ariaLabelParts.push($summary.innerText.trim());
+  }
+
+  var ariaLabelMessage = expanded
+    ? this.i18n.t('hideSectionAriaLabel')
+    : this.i18n.t('showSectionAriaLabel');
+  ariaLabelParts.push(ariaLabelMessage);
+
+  /*
+   * Join with a comma to add pause for assistive technology.
+   * Example: [heading]Section A ,[pause] Show this section.
+   * https://accessibility.blog.gov.uk/2017/12/18/what-working-on-gov-uk-navigation-taught-us-about-accessibility/
+   */
+  $button.setAttribute('aria-label', ariaLabelParts.join(' , '));
+
   // Swap icon, change class
   if (expanded) {
     $section.classList.add(this.sectionExpandedClass);
@@ -1032,9 +1736,11 @@ Accordion.prototype.checkIfAllSectionsOpen = function () {
 Accordion.prototype.updateShowAllButton = function (expanded) {
   var $showAllIcon = this.$showAllButton.querySelector('.' + this.upChevronIconClass);
   var $showAllText = this.$showAllButton.querySelector('.' + this.showAllTextClass);
-  var newButtonText = expanded ? 'Hide all sections' : 'Show all sections';
+  var newButtonText = expanded
+    ? this.i18n.t('hideAllSections')
+    : this.i18n.t('showAllSections');
   this.$showAllButton.setAttribute('aria-expanded', expanded);
-  $showAllText.innerHTML = newButtonText;
+  $showAllText.innerText = newButtonText;
 
   // Swap icon, toggle class
   if (expanded) {
@@ -1055,9 +1761,7 @@ var helper = {
       window.sessionStorage.removeItem(testString);
       return result
     } catch (exception) {
-      if ((typeof console === 'undefined' || typeof console.log === 'undefined')) {
-        console.log('Notice: sessionStorage not available.');
-      }
+      return false
     }
   }
 };
@@ -1074,14 +1778,6 @@ Accordion.prototype.storeState = function ($section) {
       var contentId = $button.getAttribute('aria-controls');
       var contentState = $button.getAttribute('aria-expanded');
 
-      if (typeof contentId === 'undefined' && (typeof console === 'undefined' || typeof console.log === 'undefined')) {
-        console.error(new Error('No aria controls present in accordion section heading.'));
-      }
-
-      if (typeof contentState === 'undefined' && (typeof console === 'undefined' || typeof console.log === 'undefined')) {
-        console.error(new Error('No aria expanded present in accordion section heading.'));
-      }
-
       // Only set the state when both `contentId` and `contentState` are taken from the DOM.
       if (contentId && contentState) {
         window.sessionStorage.setItem(contentId, contentState);
@@ -1107,17 +1803,14 @@ Accordion.prototype.setInitialState = function ($section) {
 };
 
 /**
-* Create an element to improve semantics of the section button with punctuation
-* @return {object} DOM element
-*
-* Used to add pause (with a comma) for assistive technology.
-* Example: [heading]Section A ,[pause] Show this section.
-* https://accessibility.blog.gov.uk/2017/12/18/what-working-on-gov-uk-navigation-taught-us-about-accessibility/
-*
-* Adding punctuation to the button can also improve its general semantics by dividing its contents
-* into thematic chunks.
-* See https://github.com/alphagov/govuk-frontend/issues/2327#issuecomment-922957442
-*/
+ * Create an element to improve semantics of the section button with punctuation
+ *
+ * @returns {HTMLSpanElement} DOM element
+ *
+ * Adding punctuation to the button can also improve its general semantics by dividing its contents
+ * into thematic chunks.
+ * See https://github.com/alphagov/govuk-frontend/issues/2327#issuecomment-922957442
+ */
 Accordion.prototype.getButtonPunctuationEl = function () {
   var $punctuationEl = document.createElement('span');
   $punctuationEl.classList.add('govuk-visually-hidden', 'govuk-accordion__section-heading-divider');
@@ -1125,6 +1818,35 @@ Accordion.prototype.getButtonPunctuationEl = function () {
   return $punctuationEl
 };
 
+/**
+ * Accordion config
+ *
+ * @typedef {object} AccordionConfig
+ * @property {AccordionTranslations} [i18n = ACCORDION_TRANSLATIONS] - See constant {@link ACCORDION_TRANSLATIONS}
+ */
+
+/**
+ * Accordion translations
+ *
+ * @typedef {object} AccordionTranslations
+ *
+ * Messages used by the component for the labels of its buttons. This includes
+ * the visible text shown on screen, and text to help assistive technology users
+ * for the buttons toggling each section.
+ * @property {string} [hideAllSections] - The text content for the 'Hide all
+ * sections' button, used when at least one section is expanded.
+ * @property {string} [hideSection] - The text content for the 'Hide'
+ * button, used when a section is expanded.
+ * @property {string} [hideSectionAriaLabel] - The text content appended to the
+ * 'Hide' button's accessible name when a section is expanded.
+ * @property {string} [showAllSections] - The text content for the 'Show all
+ * sections' button, used when all sections are collapsed.
+ * @property {string} [showSection] - The text content for the 'Show'
+ * button, used when a section is collapsed.
+ * @property {string} [showSectionAriaLabel] - The text content appended to the
+ * 'Show' button's accessible name when a section is expanded.
+ */
+
 (function(undefined) {
 
 // Detection from https://github.com/Financial-Times/polyfill-service/blob/master/packages/polyfill-library/polyfills/Window/detect.js
@@ -1398,44 +2120,79 @@ if (detect) return
 var KEY_SPACE = 32;
 var DEBOUNCE_TIMEOUT_IN_SECONDS = 1;
 
-function Button ($module) {
+/**
+ * JavaScript enhancements for the Button component
+ *
+ * @class
+ * @param {HTMLElement} $module - The element this component controls
+ * @param {ButtonConfig} config - Button config
+ */
+function Button ($module, config) {
+  if (!$module) {
+    return this
+  }
+
   this.$module = $module;
   this.debounceFormSubmitTimer = null;
+
+  var defaultConfig = {
+    preventDoubleClick: false
+  };
+  this.config = mergeConfigs(
+    defaultConfig,
+    config || {},
+    normaliseDataset($module.dataset)
+  );
 }
 
 /**
-* JavaScript 'shim' to trigger the click event of element(s) when the space key is pressed.
-*
-* Created since some Assistive Technologies (for example some Screenreaders)
-* will tell a user to press space on a 'button', so this functionality needs to be shimmed
-* See https://github.com/alphagov/govuk_elements/pull/272#issuecomment-233028270
-*
-* @param {object} event event
-*/
-Button.prototype.handleKeyDown = function (event) {
-  // get the target element
-  var target = event.target;
-  // if the element has a role='button' and the pressed key is a space, we'll simulate a click
-  if (target.getAttribute('role') === 'button' && event.keyCode === KEY_SPACE) {
-    event.preventDefault();
-    // trigger the target's click event
-    target.click();
-  }
-};
+ * Initialise component
+ */
+Button.prototype.init = function () {
+  if (!this.$module) {
+    return
+  }
+
+  this.$module.addEventListener('keydown', this.handleKeyDown);
+  this.$module.addEventListener('click', this.debounce.bind(this));
+};
 
 /**
-* If the click quickly succeeds a previous click then nothing will happen.
-* This stops people accidentally causing multiple form submissions by
-* double clicking buttons.
-*/
-Button.prototype.debounce = function (event) {
+ * Trigger a click event when the space key is pressed
+ *
+ * Some screen readers tell users they can activate things with the 'button'
+ * role, so we need to match the functionality of native HTML buttons
+ *
+ * See https://github.com/alphagov/govuk_elements/pull/272#issuecomment-233028270
+ *
+ * @param {KeyboardEvent} event
+ */
+Button.prototype.handleKeyDown = function (event) {
   var target = event.target;
-  // Check the button that is clicked on has the preventDoubleClick feature enabled
-  if (target.getAttribute('data-prevent-double-click') !== 'true') {
+
+  if (target.getAttribute('role') === 'button' && event.keyCode === KEY_SPACE) {
+    event.preventDefault(); // prevent the page from scrolling
+    target.click();
+  }
+};
+
+/**
+ * Debounce double-clicks
+ *
+ * If the click quickly succeeds a previous click then nothing will happen. This
+ * stops people accidentally causing multiple form submissions by double
+ * clicking buttons.
+ *
+ * @param {MouseEvent} event
+ * @returns {undefined | false} - Returns undefined, or false when debounced
+ */
+Button.prototype.debounce = function (event) {
+  // Check the button that was clicked has preventDoubleClick enabled
+  if (!this.config.preventDoubleClick) {
     return
   }
 
-  // If the timer is still running then we want to prevent the click from submitting the form
+  // If the timer is still running, prevent the click from submitting the form
   if (this.debounceFormSubmitTimer) {
     event.preventDefault();
     return false
@@ -1447,13 +2204,13 @@ Button.prototype.debounce = function (event) {
 };
 
 /**
-* Initialise an event listener for keydown at document level
-* this will help listening for later inserted elements with a role="button"
-*/
-Button.prototype.init = function () {
-  this.$module.addEventListener('keydown', this.handleKeyDown);
-  this.$module.addEventListener('click', this.debounce);
-};
+ * Button config
+ *
+ * @typedef {object} ButtonConfig
+ * @property {boolean} [preventDoubleClick = false] -
+ *  Prevent accidental double clicks on submit buttons from submitting forms
+ *  multiple times.
+ */
 
 /**
  * JavaScript 'polyfill' for HTML5's <details> and <summary> elements
@@ -1465,6 +2222,12 @@ Button.prototype.init = function () {
 var KEY_ENTER = 13;
 var KEY_SPACE$1 = 32;
 
+/**
+ * Details component
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for details
+ */
 function Details ($module) {
   this.$module = $module;
 }
@@ -1519,13 +2282,10 @@ Details.prototype.polyfillDetails = function () {
   $summary.tabIndex = 0;
 
   // Detect initial open state
-  var openAttr = $module.getAttribute('open') !== null;
-  if (openAttr === true) {
+  if (this.$module.hasAttribute('open')) {
     $summary.setAttribute('aria-expanded', 'true');
-    $content.setAttribute('aria-hidden', 'false');
   } else {
     $summary.setAttribute('aria-expanded', 'false');
-    $content.setAttribute('aria-hidden', 'true');
     $content.style.display = 'none';
   }
 
@@ -1534,37 +2294,30 @@ Details.prototype.polyfillDetails = function () {
 };
 
 /**
-* Define a statechange function that updates aria-expanded and style.display
-* @param {object} summary element
-*/
+ * Define a statechange function that updates aria-expanded and style.display
+ *
+ * @returns {boolean} Returns true
+ */
 Details.prototype.polyfillSetAttributes = function () {
-  var $module = this.$module;
-  var $summary = this.$summary;
-  var $content = this.$content;
-
-  var expanded = $summary.getAttribute('aria-expanded') === 'true';
-  var hidden = $content.getAttribute('aria-hidden') === 'true';
-
-  $summary.setAttribute('aria-expanded', (expanded ? 'false' : 'true'));
-  $content.setAttribute('aria-hidden', (hidden ? 'false' : 'true'));
-
-  $content.style.display = (expanded ? 'none' : '');
-
-  var hasOpenAttr = $module.getAttribute('open') !== null;
-  if (!hasOpenAttr) {
-    $module.setAttribute('open', 'open');
+  if (this.$module.hasAttribute('open')) {
+    this.$module.removeAttribute('open');
+    this.$summary.setAttribute('aria-expanded', 'false');
+    this.$content.style.display = 'none';
   } else {
-    $module.removeAttribute('open');
+    this.$module.setAttribute('open', 'open');
+    this.$summary.setAttribute('aria-expanded', 'true');
+    this.$content.style.display = '';
   }
 
   return true
 };
 
 /**
-* Handle cross-modal click events
-* @param {object} node element
-* @param {function} callback function
-*/
+ * Handle cross-modal click events
+ *
+ * @param {object} node - element
+ * @param {polyfillHandleInputsCallback} callback - function
+ */
 Details.prototype.polyfillHandleInputs = function (node, callback) {
   node.addEventListener('keypress', function (event) {
     var target = event.target;
@@ -1598,114 +2351,310 @@ Details.prototype.polyfillHandleInputs = function (node, callback) {
   node.addEventListener('click', callback);
 };
 
-function CharacterCount ($module) {
-  this.$module = $module;
-  this.$textarea = $module.querySelector('.govuk-js-character-count');
-  if (this.$textarea) {
-    this.$countMessage = document.getElementById(this.$textarea.id + '-info');
+/**
+ * @callback polyfillHandleInputsCallback
+ * @param {KeyboardEvent} event - Keyboard event
+ * @returns {undefined}
+ */
+
+(function(undefined) {
+
+    // Detection from https://github.com/Financial-Times/polyfill-library/blob/v3.111.0/polyfills/Date/now/detect.js
+    var detect = ('Date' in self && 'now' in self.Date && 'getTime' in self.Date.prototype);
+
+    if (detect) return
+
+    // Polyfill from https://polyfill.io/v3/polyfill.js?version=3.111.0&features=Date.now&flags=always
+    Date.now = function () {
+        return new Date().getTime();
+    };
+
+}).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
+
+(function(undefined) {
+
+  // Detection from https://raw.githubusercontent.com/Financial-Times/polyfill-service/1f3c09b402f65bf6e393f933a15ba63f1b86ef1f/packages/polyfill-library/polyfills/Element/prototype/matches/detect.js
+  var detect = (
+    'document' in this && "matches" in document.documentElement
+  );
+
+  if (detect) return
+
+  // Polyfill from https://raw.githubusercontent.com/Financial-Times/polyfill-service/1f3c09b402f65bf6e393f933a15ba63f1b86ef1f/packages/polyfill-library/polyfills/Element/prototype/matches/polyfill.js
+  Element.prototype.matches = Element.prototype.webkitMatchesSelector || Element.prototype.oMatchesSelector || Element.prototype.msMatchesSelector || Element.prototype.mozMatchesSelector || function matches(selector) {
+    var element = this;
+    var elements = (element.document || element.ownerDocument).querySelectorAll(selector);
+    var index = 0;
+
+    while (elements[index] && elements[index] !== element) {
+      ++index;
+    }
+
+    return !!elements[index];
+  };
+
+}).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
+
+(function(undefined) {
+
+  // Detection from https://raw.githubusercontent.com/Financial-Times/polyfill-service/1f3c09b402f65bf6e393f933a15ba63f1b86ef1f/packages/polyfill-library/polyfills/Element/prototype/closest/detect.js
+  var detect = (
+    'document' in this && "closest" in document.documentElement
+  );
+
+  if (detect) return
+
+  // Polyfill from https://raw.githubusercontent.com/Financial-Times/polyfill-service/1f3c09b402f65bf6e393f933a15ba63f1b86ef1f/packages/polyfill-library/polyfills/Element/prototype/closest/polyfill.js
+  Element.prototype.closest = function closest(selector) {
+    var node = this;
+
+    while (node) {
+      if (node.matches(selector)) return node;
+      else node = 'SVGElement' in window && node instanceof SVGElement ? node.parentNode : node.parentElement;
+    }
+
+    return null;
+  };
+
+}).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
+
+/**
+ * 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 {string} attributeName - The name of the attribute
+ * @returns {string | undefined} Attribute value
+ */
+function closestAttributeValue ($element, attributeName) {
+  var closestElementWithAttribute = $element.closest('[' + attributeName + ']');
+  if (closestElementWithAttribute) {
+    return closestElementWithAttribute.getAttribute(attributeName)
   }
 }
 
-CharacterCount.prototype.defaults = {
-  characterCountAttribute: 'data-maxlength',
-  wordCountAttribute: 'data-maxwords'
+/**
+ * @constant
+ * @type {CharacterCountTranslations}
+ * @see Default value for {@link CharacterCountConfig.i18n}
+ * @default
+ */
+var CHARACTER_COUNT_TRANSLATIONS = {
+  // Characters
+  charactersUnderLimit: {
+    one: 'You have %{count} character remaining',
+    other: 'You have %{count} characters remaining'
+  },
+  charactersAtLimit: 'You have 0 characters remaining',
+  charactersOverLimit: {
+    one: 'You have %{count} character too many',
+    other: 'You have %{count} characters too many'
+  },
+  // Words
+  wordsUnderLimit: {
+    one: 'You have %{count} word remaining',
+    other: 'You have %{count} words remaining'
+  },
+  wordsAtLimit: 'You have 0 words remaining',
+  wordsOverLimit: {
+    one: 'You have %{count} word too many',
+    other: 'You have %{count} words too many'
+  },
+  textareaDescription: {
+    other: ''
+  }
 };
 
-// Initialize component
-CharacterCount.prototype.init = function () {
-  // Check for module
-  var $module = this.$module;
-  var $textarea = this.$textarea;
-  var $countMessage = this.$countMessage;
-
-  if (!$textarea || !$countMessage) {
-    return
+/**
+ * JavaScript enhancements for the CharacterCount component
+ *
+ * Tracks the number of characters or words in the `.govuk-js-character-count`
+ * `<textarea>` inside the element. Displays a message with the remaining number
+ * of characters/words available, or the number of characters/words in excess.
+ *
+ * You can configure the message to only appear after a certain percentage
+ * of the available characters/words has been entered.
+ *
+ * @class
+ * @param {HTMLElement} $module - The element this component controls
+ * @param {CharacterCountConfig} [config] - Character count config
+ */
+function CharacterCount ($module, config) {
+  if (!$module) {
+    return this
   }
 
-  // We move count message right after the field
-  // Kept for backwards compatibility
-  $textarea.insertAdjacentElement('afterend', $countMessage);
+  var defaultConfig = {
+    threshold: 0,
+    i18n: CHARACTER_COUNT_TRANSLATIONS
+  };
 
-  // Read options set using dataset ('data-' values)
-  this.options = this.getDataset($module);
+  // Read config set using dataset ('data-' values)
+  var datasetConfig = normaliseDataset($module.dataset);
+
+  // To ensure data-attributes take complete precedence, even if they change the
+  // type of count, we need to reset the `maxlength` and `maxwords` from the
+  // JavaScript config.
+  //
+  // We can't mutate `config`, though, as it may be shared across multiple
+  // components inside `initAll`.
+  var configOverrides = {};
+  if ('maxwords' in datasetConfig || 'maxlength' in datasetConfig) {
+    configOverrides = {
+      maxlength: false,
+      maxwords: false
+    };
+  }
+
+  this.config = mergeConfigs(
+    defaultConfig,
+    config || {},
+    configOverrides,
+    datasetConfig
+  );
+
+  this.i18n = new I18n(extractConfigByNamespace(this.config, 'i18n'), {
+    // Read the fallback if necessary rather than have it set in the defaults
+    locale: closestAttributeValue($module, 'lang')
+  });
 
   // Determine the limit attribute (characters or words)
-  var countAttribute = this.defaults.characterCountAttribute;
-  if (this.options.maxwords) {
-    countAttribute = this.defaults.wordCountAttribute;
+  if (this.config.maxwords) {
+    this.maxLength = this.config.maxwords;
+  } else if (this.config.maxlength) {
+    this.maxLength = this.config.maxlength;
+  } else {
+    return
   }
 
-  // Save the element limit
-  this.maxLength = $module.getAttribute(countAttribute);
+  this.$module = $module;
+  this.$textarea = $module.querySelector('.govuk-js-character-count');
+  this.$visibleCountMessage = null;
+  this.$screenReaderCountMessage = null;
+  this.lastInputTimestamp = null;
+}
 
-  // Check for limit
-  if (!this.maxLength) {
+/**
+ * Initialise component
+ */
+CharacterCount.prototype.init = function () {
+  // Check that required elements are present
+  if (!this.$textarea) {
     return
   }
 
-  // Remove hard limit if set
-  $module.removeAttribute('maxlength');
+  var $textarea = this.$textarea;
+  var $textareaDescription = document.getElementById($textarea.id + '-info');
 
-  // When the page is restored after navigating 'back' in some browsers the
-  // state of the character count 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.sync.bind(this));
-  } else {
-    window.addEventListener('DOMContentLoaded', this.sync.bind(this));
+  // Inject a decription for the textarea if none is present already
+  // for when the component was rendered with no maxlength, maxwords
+  // nor custom textareaDescriptionText
+  if ($textareaDescription.innerText.match(/^\s*$/)) {
+    $textareaDescription.innerText = this.i18n.t('textareaDescription', { count: this.maxLength });
   }
 
-  this.sync();
-};
+  // Move the textarea description to be immediately after the textarea
+  // Kept for backwards compatibility
+  $textarea.insertAdjacentElement('afterend', $textareaDescription);
+
+  // Create the *screen reader* specific live-updating counter
+  // This doesn't need any styling classes, as it is never visible
+  var $screenReaderCountMessage = document.createElement('div');
+  $screenReaderCountMessage.className = 'govuk-character-count__sr-status govuk-visually-hidden';
+  $screenReaderCountMessage.setAttribute('aria-live', 'polite');
+  this.$screenReaderCountMessage = $screenReaderCountMessage;
+  $textareaDescription.insertAdjacentElement('afterend', $screenReaderCountMessage);
+
+  // Create our live-updating counter element, copying the classes from the
+  // textarea description for backwards compatibility as these may have been
+  // configured
+  var $visibleCountMessage = document.createElement('div');
+  $visibleCountMessage.className = $textareaDescription.className;
+  $visibleCountMessage.classList.add('govuk-character-count__status');
+  $visibleCountMessage.setAttribute('aria-hidden', 'true');
+  this.$visibleCountMessage = $visibleCountMessage;
+  $textareaDescription.insertAdjacentElement('afterend', $visibleCountMessage);
+
+  // Hide the textarea description
+  $textareaDescription.classList.add('govuk-visually-hidden');
 
-CharacterCount.prototype.sync = function () {
-  this.bindChangeEvents();
-  this.updateCountMessage();
-};
+  // Remove hard limit if set
+  $textarea.removeAttribute('maxlength');
 
-// Read data attributes
-CharacterCount.prototype.getDataset = function (element) {
-  var dataset = {};
-  var attributes = element.attributes;
-  if (attributes) {
-    for (var i = 0; i < attributes.length; i++) {
-      var attribute = attributes[i];
-      var match = attribute.name.match(/^data-(.+)/);
-      if (match) {
-        dataset[match[1]] = attribute.value;
-      }
-    }
-  }
-  return dataset
-};
+  this.bindChangeEvents();
 
-// Counts characters or words in text
-CharacterCount.prototype.count = function (text) {
-  var length;
-  if (this.options.maxwords) {
-    var tokens = text.match(/\S+/g) || []; // Matches consecutive non-whitespace chars
-    length = tokens.length;
+  // When the page is restored after navigating 'back' in some browsers the
+  // 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 {
-    length = text.length;
+    window.addEventListener('DOMContentLoaded', this.updateCountMessage.bind(this));
   }
-  return length
+  this.updateCountMessage();
 };
 
-// Bind input propertychange to the elements and update based on the change
+/**
+ * Bind change events
+ *
+ * Set up event listeners on the $textarea so that the count messages update
+ * when the user types.
+ */
 CharacterCount.prototype.bindChangeEvents = function () {
   var $textarea = this.$textarea;
-  $textarea.addEventListener('keyup', this.checkIfValueChanged.bind(this));
+  $textarea.addEventListener('keyup', this.handleKeyUp.bind(this));
 
   // Bind focus/blur events to start/stop polling
   $textarea.addEventListener('focus', this.handleFocus.bind(this));
   $textarea.addEventListener('blur', this.handleBlur.bind(this));
 };
 
-// Speech recognition software such as Dragon NaturallySpeaking will modify the
-// fields by directly changing its `value`. These changes don't trigger events
-// in JavaScript, so we need to poll to handle when and if they occur.
-CharacterCount.prototype.checkIfValueChanged = function () {
+/**
+ * Handle key up event
+ *
+ * Update the visible character counter and keep track of when the last update
+ * happened for each keypress
+ */
+CharacterCount.prototype.handleKeyUp = function () {
+  this.updateVisibleCountMessage();
+  this.lastInputTimestamp = Date.now();
+};
+
+/**
+ * Handle focus event
+ *
+ * Speech recognition software such as Dragon NaturallySpeaking will modify the
+ * fields by directly changing its `value`. These changes don't trigger events
+ * in JavaScript, so we need to poll to handle when and if they occur.
+ *
+ * Once the keyup event hasn't been detected for at least 1000 ms (1s), check if
+ * the textarea value has changed and update the count message if it has.
+ *
+ * This is so that the update triggered by the manual comparison doesn't
+ * conflict with debounced KeyboardEvent updates.
+ */
+CharacterCount.prototype.handleFocus = function () {
+  this.valueChecker = setInterval(function () {
+    if (!this.lastInputTimestamp || (Date.now() - 500) >= this.lastInputTimestamp) {
+      this.updateIfValueChanged();
+    }
+  }.bind(this), 1000);
+};
+
+/**
+ * Handle blur event
+ *
+ * Stop checking the textarea value once the textarea no longer has focus
+ */
+CharacterCount.prototype.handleBlur = function () {
+  // Cancel value checking on blur
+  clearInterval(this.valueChecker);
+};
+
+/**
+ * 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;
@@ -1713,66 +2662,225 @@ CharacterCount.prototype.checkIfValueChanged = function () {
   }
 };
 
-// Update message box
+/**
+ * Update count message
+ *
+ * Helper function to update both the visible and screen reader-specific
+ * counters simultaneously (e.g. on init)
+ */
 CharacterCount.prototype.updateCountMessage = function () {
-  var countElement = this.$textarea;
-  var options = this.options;
-  var countMessage = this.$countMessage;
+  this.updateVisibleCountMessage();
+  this.updateScreenReaderCountMessage();
+};
 
-  // Determine the remaining number of characters/words
-  var currentLength = this.count(countElement.value);
-  var maxLength = this.maxLength;
-  var remainingNumber = maxLength - currentLength;
-
-  // Set threshold if presented in options
-  var thresholdPercent = options.threshold ? options.threshold : 0;
-  var thresholdValue = maxLength * thresholdPercent / 100;
-  if (thresholdValue > currentLength) {
-    countMessage.classList.add('govuk-character-count__message--disabled');
-    // Ensure threshold is hidden for users of assistive technologies
-    countMessage.setAttribute('aria-hidden', true);
+/**
+ * Update visible count message
+ */
+CharacterCount.prototype.updateVisibleCountMessage = function () {
+  var $textarea = this.$textarea;
+  var $visibleCountMessage = this.$visibleCountMessage;
+  var remainingNumber = this.maxLength - this.count($textarea.value);
+
+  // If input is over the threshold, remove the disabled class which renders the
+  // counter invisible.
+  if (this.isOverThreshold()) {
+    $visibleCountMessage.classList.remove('govuk-character-count__message--disabled');
   } else {
-    countMessage.classList.remove('govuk-character-count__message--disabled');
-    // Ensure threshold is visible for users of assistive technologies
-    countMessage.removeAttribute('aria-hidden');
+    $visibleCountMessage.classList.add('govuk-character-count__message--disabled');
   }
 
   // Update styles
   if (remainingNumber < 0) {
-    countElement.classList.add('govuk-textarea--error');
-    countMessage.classList.remove('govuk-hint');
-    countMessage.classList.add('govuk-error-message');
+    $textarea.classList.add('govuk-textarea--error');
+    $visibleCountMessage.classList.remove('govuk-hint');
+    $visibleCountMessage.classList.add('govuk-error-message');
   } else {
-    countElement.classList.remove('govuk-textarea--error');
-    countMessage.classList.remove('govuk-error-message');
-    countMessage.classList.add('govuk-hint');
+    $textarea.classList.remove('govuk-textarea--error');
+    $visibleCountMessage.classList.remove('govuk-error-message');
+    $visibleCountMessage.classList.add('govuk-hint');
   }
 
   // Update message
-  var charVerb = 'remaining';
-  var charNoun = 'character';
-  var displayNumber = remainingNumber;
-  if (options.maxwords) {
-    charNoun = 'word';
+  $visibleCountMessage.innerText = this.getCountMessage();
+};
+
+/**
+ * Update screen reader count message
+ */
+CharacterCount.prototype.updateScreenReaderCountMessage = function () {
+  var $screenReaderCountMessage = this.$screenReaderCountMessage;
+
+  // If over the threshold, remove the aria-hidden attribute, allowing screen
+  // readers to announce the content of the element.
+  if (this.isOverThreshold()) {
+    $screenReaderCountMessage.removeAttribute('aria-hidden');
+  } else {
+    $screenReaderCountMessage.setAttribute('aria-hidden', true);
   }
-  charNoun = charNoun + ((remainingNumber === -1 || remainingNumber === 1) ? '' : 's');
 
-  charVerb = (remainingNumber < 0) ? 'too many' : 'remaining';
-  displayNumber = Math.abs(remainingNumber);
+  // Update message
+  $screenReaderCountMessage.innerText = this.getCountMessage();
+};
 
-  countMessage.innerHTML = 'You have ' + displayNumber + ' ' + charNoun + ' ' + charVerb;
+/**
+ * Count the number of characters (or words, if `config.maxwords` is set)
+ * in the given text
+ *
+ * @param {string} text - The text to count the characters of
+ * @returns {number} the number of characters (or words) in the text
+ */
+CharacterCount.prototype.count = function (text) {
+  if (this.config.maxwords) {
+    var tokens = text.match(/\S+/g) || []; // Matches consecutive non-whitespace chars
+    return tokens.length
+  } else {
+    return text.length
+  }
 };
 
-CharacterCount.prototype.handleFocus = function () {
-  // Check if value changed on focus
-  this.valueChecker = setInterval(this.checkIfValueChanged.bind(this), 1000);
+/**
+ * Get count message
+ *
+ * @returns {string} Status message
+ */
+CharacterCount.prototype.getCountMessage = function () {
+  var remainingNumber = this.maxLength - this.count(this.$textarea.value);
+
+  var countType = this.config.maxwords ? 'words' : 'characters';
+  return this.formatCountMessage(remainingNumber, countType)
 };
 
-CharacterCount.prototype.handleBlur = function () {
-  // Cancel value checking on blur
-  clearInterval(this.valueChecker);
+/**
+ * Formats the message shown to users according to what's counted
+ * and how many remain
+ *
+ * @param {number} remainingNumber - The number of words/characaters remaining
+ * @param {string} countType - "words" or "characters"
+ * @returns {string} Status message
+ */
+CharacterCount.prototype.formatCountMessage = function (remainingNumber, countType) {
+  if (remainingNumber === 0) {
+    return this.i18n.t(countType + 'AtLimit')
+  }
+
+  var translationKeySuffix = remainingNumber < 0 ? 'OverLimit' : 'UnderLimit';
+
+  return this.i18n.t(countType + translationKeySuffix, { count: Math.abs(remainingNumber) })
+};
+
+/**
+ * Check if count is over threshold
+ *
+ * Checks whether the value is over the configured threshold for the input.
+ * If there is no configured threshold, it is set to 0 and this function will
+ * always return true.
+ *
+ * @returns {boolean} true if the current count is over the config.threshold
+ *   (or no threshold is set)
+ */
+CharacterCount.prototype.isOverThreshold = function () {
+  // No threshold means we're always above threshold so save some computation
+  if (!this.config.threshold) {
+    return true
+  }
+
+  var $textarea = this.$textarea;
+
+  // Determine the remaining number of characters/words
+  var currentLength = this.count($textarea.value);
+  var maxLength = this.maxLength;
+
+  var thresholdValue = maxLength * this.config.threshold / 100;
+
+  return (thresholdValue <= currentLength)
 };
 
+/**
+ * Character count config
+ *
+ * @typedef {CharacterCountConfigWithMaxLength | CharacterCountConfigWithMaxWords} CharacterCountConfig
+ */
+
+/**
+ * Character count config (with maximum number of characters)
+ *
+ * @typedef {object} CharacterCountConfigWithMaxLength
+ * @property {number} [maxlength] - The maximum number of characters.
+ *  If maxwords is provided, the maxlength option will be ignored.
+ * @property {number} [threshold = 0] - The percentage value of the limit at
+ *  which point the count message is displayed. If this attribute is set, the
+ *  count message will be hidden by default.
+ * @property {CharacterCountTranslations} [i18n = CHARACTER_COUNT_TRANSLATIONS] - See constant {@link CHARACTER_COUNT_TRANSLATIONS}
+ */
+
+/**
+ * Character count config (with maximum number of words)
+ *
+ * @typedef {object} CharacterCountConfigWithMaxWords
+ * @property {number} [maxwords] - The maximum number of words. If maxwords is
+ *  provided, the maxlength option will be ignored.
+ * @property {number} [threshold = 0] - The percentage value of the limit at
+ *  which point the count message is displayed. If this attribute is set, the
+ *  count message will be hidden by default.
+ * @property {CharacterCountTranslations} [i18n = CHARACTER_COUNT_TRANSLATIONS] - See constant {@link CHARACTER_COUNT_TRANSLATIONS}
+ */
+
+/**
+ * Character count translations
+ *
+ * @typedef {object} CharacterCountTranslations
+ *
+ * Messages shown to users as they type. It provides feedback on how many words
+ * or characters they have remaining or if they are over the limit. This also
+ * includes a message used as an accessible description for the textarea.
+ * @property {TranslationPluralForms} [charactersUnderLimit] - Message displayed
+ *   when the number of characters is under the configured maximum, `maxlength`.
+ *   This message is displayed visually and through assistive technologies. The
+ *   component will replace the `%{count}` placeholder with the number of
+ *   remaining characters. This is a [pluralised list of
+ *   messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+ * @property {string} [charactersAtLimit] - Message displayed when the number of
+ *   characters reaches the configured maximum, `maxlength`. This message is
+ *   displayed visually and through assistive technologies.
+ * @property {TranslationPluralForms} [charactersOverLimit] - Message displayed
+ *   when the number of characters is over the configured maximum, `maxlength`.
+ *   This message is displayed visually and through assistive technologies. The
+ *   component will replace the `%{count}` placeholder with the number of
+ *   remaining characters. This is a [pluralised list of
+ *   messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+ * @property {TranslationPluralForms} [wordsUnderLimit] - Message displayed when
+ *   the number of words is under the configured maximum, `maxlength`. This
+ *   message is displayed visually and through assistive technologies. The
+ *   component will replace the `%{count}` placeholder with the number of
+ *   remaining words. This is a [pluralised list of
+ *   messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+ * @property {string} [wordsAtLimit] - Message displayed when the number of
+ *   words reaches the configured maximum, `maxlength`. This message is
+ *   displayed visually and through assistive technologies.
+ * @property {TranslationPluralForms} [wordsOverLimit] - Message displayed when
+ *   the number of words is over the configured maximum, `maxlength`. This
+ *   message is displayed visually and through assistive technologies. The
+ *   component will replace the `%{count}` placeholder with the number of
+ *   remaining words. This is a [pluralised list of
+ *   messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+ * @property {TranslationPluralForms} [textareaDescription] - Message made
+ *   available to assistive technologies, if none is already present in the
+ *   HTML, to describe that the component accepts only a limited amount of
+ *   content. It is visible on the page when JavaScript is unavailable. The
+ *   component will replace the `%{count}` placeholder with the value of the
+ *   `maxlength` or `maxwords` parameter.
+ */
+
+/**
+ * @typedef {import('../../i18n.mjs').TranslationPluralForms} TranslationPluralForms
+ */
+
+/**
+ * Checkboxes component
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for checkboxes
+ */
 function Checkboxes ($module) {
   this.$module = $module;
   this.$inputs = $module.querySelectorAll('input[type="checkbox"]');
@@ -1842,7 +2950,7 @@ Checkboxes.prototype.syncAllConditionalReveals = function () {
  * Synchronise the visibility of the conditional reveal, and its accessible
  * state, with the input's checked state.
  *
- * @param {HTMLInputElement} $input Checkbox input
+ * @param {HTMLInputElement} $input - Checkbox input
  */
 Checkboxes.prototype.syncConditionalRevealWithInputState = function ($input) {
   var $target = document.getElementById($input.getAttribute('aria-controls'));
@@ -1900,7 +3008,7 @@ Checkboxes.prototype.unCheckExclusiveInputs = function ($input) {
  * Handle a click within the $module – if the click occurred on a checkbox, sync
  * the state of any associated conditional reveal with the checkbox state.
  *
- * @param {MouseEvent} event Click event
+ * @param {MouseEvent} event - Click event
  */
 Checkboxes.prototype.handleClick = function (event) {
   var $target = event.target;
@@ -1930,55 +3038,39 @@ Checkboxes.prototype.handleClick = function (event) {
   }
 };
 
-(function(undefined) {
-
-  // Detection from https://raw.githubusercontent.com/Financial-Times/polyfill-service/1f3c09b402f65bf6e393f933a15ba63f1b86ef1f/packages/polyfill-library/polyfills/Element/prototype/matches/detect.js
-  var detect = (
-    'document' in this && "matches" in document.documentElement
-  );
-
-  if (detect) return
-
-  // Polyfill from https://raw.githubusercontent.com/Financial-Times/polyfill-service/1f3c09b402f65bf6e393f933a15ba63f1b86ef1f/packages/polyfill-library/polyfills/Element/prototype/matches/polyfill.js
-  Element.prototype.matches = Element.prototype.webkitMatchesSelector || Element.prototype.oMatchesSelector || Element.prototype.msMatchesSelector || Element.prototype.mozMatchesSelector || function matches(selector) {
-    var element = this;
-    var elements = (element.document || element.ownerDocument).querySelectorAll(selector);
-    var index = 0;
+/**
+ * JavaScript enhancements for the ErrorSummary
+ *
+ * Takes focus on initialisation for accessible announcement, unless disabled in configuration.
+ *
+ * @class
+ * @param {HTMLElement} $module - The element this component controls
+ * @param {ErrorSummaryConfig} config - Error summary config
+ */
+function ErrorSummary ($module, config) {
+  // Some consuming code may not be passing a module,
+  // for example if they initialise the component
+  // on their own by directly passing the result
+  // of `document.querySelector`.
+  // To avoid breaking further JavaScript initialisation
+  // we need to safeguard against this so things keep
+  // working the same now we read the elements data attributes
+  if (!$module) {
+    // Little safety in case code gets ported as-is
+    // into and ES6 class constructor, where the return value matters
+    return this
+  }
 
-    while (elements[index] && elements[index] !== element) {
-      ++index;
-    }
+  this.$module = $module;
 
-    return !!elements[index];
+  var defaultConfig = {
+    disableAutoFocus: false
   };
-
-}).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
-
-(function(undefined) {
-
-  // Detection from https://raw.githubusercontent.com/Financial-Times/polyfill-service/1f3c09b402f65bf6e393f933a15ba63f1b86ef1f/packages/polyfill-library/polyfills/Element/prototype/closest/detect.js
-  var detect = (
-    'document' in this && "closest" in document.documentElement
+  this.config = mergeConfigs(
+    defaultConfig,
+    config || {},
+    normaliseDataset($module.dataset)
   );
-
-  if (detect) return
-
-  // Polyfill from https://raw.githubusercontent.com/Financial-Times/polyfill-service/1f3c09b402f65bf6e393f933a15ba63f1b86ef1f/packages/polyfill-library/polyfills/Element/prototype/closest/polyfill.js
-  Element.prototype.closest = function closest(selector) {
-    var node = this;
-
-    while (node) {
-      if (node.matches(selector)) return node;
-      else node = 'SVGElement' in window && node instanceof SVGElement ? node.parentNode : node.parentElement;
-    }
-
-    return null;
-  };
-
-}).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
-
-function ErrorSummary ($module) {
-  this.$module = $module;
 }
 
 ErrorSummary.prototype.init = function () {
@@ -1986,16 +3078,37 @@ ErrorSummary.prototype.init = function () {
   if (!$module) {
     return
   }
-  $module.focus();
 
+  this.setFocus();
   $module.addEventListener('click', this.handleClick.bind(this));
 };
 
 /**
-* Click event handler
-*
-* @param {MouseEvent} event - Click event
-*/
+ * Focus the error summary
+ */
+ErrorSummary.prototype.setFocus = function () {
+  var $module = this.$module;
+
+  if (this.config.disableAutoFocus) {
+    return
+  }
+
+  // Set tabindex to -1 to make the element programmatically focusable, but
+  // remove it on blur as the error summary doesn't need to be focused again.
+  $module.setAttribute('tabindex', '-1');
+
+  $module.addEventListener('blur', function () {
+    $module.removeAttribute('tabindex');
+  });
+
+  $module.focus();
+};
+
+/**
+ * Click event handler
+ *
+ * @param {MouseEvent} event - Click event
+ */
 ErrorSummary.prototype.handleClick = function (event) {
   var target = event.target;
   if (this.focusTarget(target)) {
@@ -2119,8 +3232,32 @@ ErrorSummary.prototype.getAssociatedLegendOrLabel = function ($input) {
     $input.closest('label')
 };
 
-function NotificationBanner ($module) {
+/**
+ * Error summary config
+ *
+ * @typedef {object} ErrorSummaryConfig
+ * @property {boolean} [disableAutoFocus = false] -
+ *  If set to `true` the error summary will not be focussed when the page loads.
+ */
+
+/**
+ * Notification Banner component
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for notification banner
+ * @param {NotificationBannerConfig} config - Notification banner config
+ */
+function NotificationBanner ($module, config) {
   this.$module = $module;
+
+  var defaultConfig = {
+    disableAutoFocus: false
+  };
+  this.config = mergeConfigs(
+    defaultConfig,
+    config || {},
+    normaliseDataset($module.dataset)
+  );
 }
 
 /**
@@ -2149,7 +3286,7 @@ NotificationBanner.prototype.init = function () {
 NotificationBanner.prototype.setFocus = function () {
   var $module = this.$module;
 
-  if ($module.getAttribute('data-disable-auto-focus') === 'true') {
+  if (this.config.disableAutoFocus) {
     return
   }
 
@@ -2171,12 +3308,40 @@ NotificationBanner.prototype.setFocus = function () {
   $module.focus();
 };
 
+/**
+ * Notification banner config
+ *
+ * @typedef {object} NotificationBannerConfig
+ * @property {boolean} [disableAutoFocus = false] -
+ *   If set to `true` the notification banner will not be focussed when the page
+ *   loads. This only applies if the component has a `role` of `alert` – in
+ *   other cases the component will not be focused on page load, regardless of
+ *   this option.
+ */
+
+/**
+ * Header component
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for header
+ */
 function Header ($module) {
   this.$module = $module;
   this.$menuButton = $module && $module.querySelector('.govuk-js-header-toggle');
   this.$menu = this.$menuButton && $module.querySelector(
     '#' + this.$menuButton.getAttribute('aria-controls')
   );
+
+  // Save the opened/closed state for the nav in memory so that we can
+  // accurately maintain state when the screen is changed from small to
+  // big and back to small
+  this.menuIsOpen = false;
+
+  // A global const for storing a matchMedia instance which we'll use to
+  // detect when a screen size change happens. We set this later during the
+  // init function and rely on it being null if the feature isn't available
+  // to initially apply hidden attributes
+  this.mql = null;
 }
 
 /**
@@ -2184,27 +3349,58 @@ function Header ($module) {
  *
  * Check for the presence of the header, menu and menu button – if any are
  * missing then there's nothing to do so return early.
+ * Feature sniff for and apply a matchMedia for desktop which will
+ * trigger a state sync if the browser viewport moves between states. If
+ * matchMedia isn't available, hide the menu button and present the "no js"
+ * version of the menu to the user.
  */
 Header.prototype.init = function () {
   if (!this.$module || !this.$menuButton || !this.$menu) {
     return
   }
 
-  this.syncState(this.$menu.classList.contains('govuk-header__navigation-list--open'));
-  this.$menuButton.addEventListener('click', this.handleMenuButtonClick.bind(this));
+  if ('matchMedia' in window) {
+    // 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));
+    }
+
+    this.syncState();
+    this.$menuButton.addEventListener('click', this.handleMenuButtonClick.bind(this));
+  } else {
+    this.$menuButton.setAttribute('hidden', '');
+  }
 };
 
 /**
  * Sync menu state
  *
- * Sync the menu button class and the accessible state of the menu and the menu
- * button with the visible state of the menu
- *
- * @param {boolean} isVisible Whether the menu is currently visible
+ * Uses the global variable menuIsOpen to correctly set the accessible and
+ * visual states of the menu and the menu button.
+ * Additionally will force the menu to be visible and the menu button to be
+ * hidden if the matchMedia is triggered to desktop.
  */
-Header.prototype.syncState = function (isVisible) {
-  this.$menuButton.classList.toggle('govuk-header__menu-button--open', isVisible);
-  this.$menuButton.setAttribute('aria-expanded', isVisible);
+Header.prototype.syncState = function () {
+  if (this.mql.matches) {
+    this.$menu.removeAttribute('hidden');
+    this.$menuButton.setAttribute('hidden', '');
+  } else {
+    this.$menuButton.removeAttribute('hidden');
+    this.$menuButton.setAttribute('aria-expanded', this.menuIsOpen);
+
+    if (this.menuIsOpen) {
+      this.$menu.removeAttribute('hidden');
+    } else {
+      this.$menu.setAttribute('hidden', '');
+    }
+  }
 };
 
 /**
@@ -2214,10 +3410,16 @@ Header.prototype.syncState = function (isVisible) {
  * sync the accessibility state and menu button state
  */
 Header.prototype.handleMenuButtonClick = function () {
-  var isVisible = this.$menu.classList.toggle('govuk-header__navigation-list--open');
-  this.syncState(isVisible);
+  this.menuIsOpen = !this.menuIsOpen;
+  this.syncState();
 };
 
+/**
+ * Radios component
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for radios
+ */
 function Radios ($module) {
   this.$module = $module;
   this.$inputs = $module.querySelectorAll('input[type="radio"]');
@@ -2288,7 +3490,7 @@ Radios.prototype.syncAllConditionalReveals = function () {
  * Synchronise the visibility of the conditional reveal, and its accessible
  * state, with the input's checked state.
  *
- * @param {HTMLInputElement} $input Radio input
+ * @param {HTMLInputElement} $input - Radio input
  */
 Radios.prototype.syncConditionalRevealWithInputState = function ($input) {
   var $target = document.getElementById($input.getAttribute('aria-controls'));
@@ -2309,7 +3511,7 @@ Radios.prototype.syncConditionalRevealWithInputState = function ($input) {
  * with the same name (because checking one radio could have un-checked a radio
  * in another $module)
  *
- * @param {MouseEvent} event Click event
+ * @param {MouseEvent} event - Click event
  */
 Radios.prototype.handleClick = function (event) {
   var $clickedInput = event.target;
@@ -2333,6 +3535,12 @@ Radios.prototype.handleClick = function (event) {
   }.bind(this));
 };
 
+/**
+ * Skip link component
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for skip link
+ */
 function SkipLink ($module) {
   this.$module = $module;
   this.$linkedElement = null;
@@ -2358,10 +3566,10 @@ SkipLink.prototype.init = function () {
 };
 
 /**
-* Get linked element
-*
-* @returns {HTMLElement} $linkedElement - DOM element linked to from the skip link
-*/
+ * Get linked element
+ *
+ * @returns {HTMLElement} $linkedElement - DOM element linked to from the skip link
+ */
 SkipLink.prototype.getLinkedElement = function () {
   var linkedElementId = this.getFragmentFromUrl();
 
@@ -2462,6 +3670,12 @@ SkipLink.prototype.getFragmentFromUrl = function () {
 
 }).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
 
+/**
+ * Tabs component
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for tabs
+ */
 function Tabs ($module) {
   this.$module = $module;
   this.$tabs = $module.querySelectorAll('.govuk-tabs__tab');
@@ -2736,67 +3950,90 @@ Tabs.prototype.getHref = function ($tab) {
   return hash
 };
 
-function initAll (options) {
-  // Set the options to an empty object by default if no options are passed.
-  options = typeof options !== 'undefined' ? options : {};
+/**
+ * Initialise all components
+ *
+ * Use the `data-module` attributes to find, instantiate and init all of the
+ * components provided as part of GOV.UK Frontend.
+ *
+ * @param {Config} [config] - Config for all components
+ */
+function initAll (config) {
+  config = typeof config !== 'undefined' ? config : {};
 
   // Allow the user to initialise GOV.UK Frontend in only certain sections of the page
   // Defaults to the entire document if nothing is set.
-  var scope = typeof options.scope !== 'undefined' ? options.scope : document;
-
-  var $buttons = scope.querySelectorAll('[data-module="govuk-button"]');
-  nodeListForEach($buttons, function ($button) {
-    new Button($button).init();
-  });
+  var $scope = typeof config.scope !== 'undefined' ? config.scope : document;
 
-  var $accordions = scope.querySelectorAll('[data-module="govuk-accordion"]');
+  var $accordions = $scope.querySelectorAll('[data-module="govuk-accordion"]');
   nodeListForEach($accordions, function ($accordion) {
-    new Accordion($accordion).init();
+    new Accordion($accordion, config.accordion).init();
   });
 
-  var $details = scope.querySelectorAll('[data-module="govuk-details"]');
-  nodeListForEach($details, function ($detail) {
-    new Details($detail).init();
+  var $buttons = $scope.querySelectorAll('[data-module="govuk-button"]');
+  nodeListForEach($buttons, function ($button) {
+    new Button($button, config.button).init();
   });
 
-  var $characterCounts = scope.querySelectorAll('[data-module="govuk-character-count"]');
+  var $characterCounts = $scope.querySelectorAll('[data-module="govuk-character-count"]');
   nodeListForEach($characterCounts, function ($characterCount) {
-    new CharacterCount($characterCount).init();
+    new CharacterCount($characterCount, config.characterCount).init();
   });
 
-  var $checkboxes = scope.querySelectorAll('[data-module="govuk-checkboxes"]');
+  var $checkboxes = $scope.querySelectorAll('[data-module="govuk-checkboxes"]');
   nodeListForEach($checkboxes, function ($checkbox) {
     new Checkboxes($checkbox).init();
   });
 
+  var $details = $scope.querySelectorAll('[data-module="govuk-details"]');
+  nodeListForEach($details, function ($detail) {
+    new Details($detail).init();
+  });
+
   // Find first error summary module to enhance.
-  var $errorSummary = scope.querySelector('[data-module="govuk-error-summary"]');
-  new ErrorSummary($errorSummary).init();
+  var $errorSummary = $scope.querySelector('[data-module="govuk-error-summary"]');
+  if ($errorSummary) {
+    new ErrorSummary($errorSummary, config.errorSummary).init();
+  }
 
   // Find first header module to enhance.
-  var $toggleButton = scope.querySelector('[data-module="govuk-header"]');
-  new Header($toggleButton).init();
+  var $header = $scope.querySelector('[data-module="govuk-header"]');
+  if ($header) {
+    new Header($header).init();
+  }
 
-  var $notificationBanners = scope.querySelectorAll('[data-module="govuk-notification-banner"]');
+  var $notificationBanners = $scope.querySelectorAll('[data-module="govuk-notification-banner"]');
   nodeListForEach($notificationBanners, function ($notificationBanner) {
-    new NotificationBanner($notificationBanner).init();
+    new NotificationBanner($notificationBanner, config.notificationBanner).init();
   });
 
-  var $radios = scope.querySelectorAll('[data-module="govuk-radios"]');
+  var $radios = $scope.querySelectorAll('[data-module="govuk-radios"]');
   nodeListForEach($radios, function ($radio) {
     new Radios($radio).init();
   });
 
   // Find first skip link module to enhance.
-  var $skipLink = scope.querySelector('[data-module="govuk-skip-link"]');
+  var $skipLink = $scope.querySelector('[data-module="govuk-skip-link"]');
   new SkipLink($skipLink).init();
 
-  var $tabs = scope.querySelectorAll('[data-module="govuk-tabs"]');
+  var $tabs = $scope.querySelectorAll('[data-module="govuk-tabs"]');
   nodeListForEach($tabs, function ($tabs) {
     new Tabs($tabs).init();
   });
 }
 
+/**
+ * Config for all components
+ *
+ * @typedef {object} Config
+ * @property {HTMLElement} [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
+ * @property {import('./components/error-summary/error-summary.mjs').ErrorSummaryConfig} [errorSummary] - Error Summary config
+ * @property {import('./components/notification-banner/notification-banner.mjs').NotificationBannerConfig} [notificationBanner] - Notification Banner config
+ */
+
 exports.initAll = initAll;
 exports.Accordion = Accordion;
 exports.Button = Button;