govuk_publishing_components 32.0.0 → 33.0.0

data/node_modules/govuk-frontend/govuk/components/accordion/accordion.js

@@ -4,10 +4,24 @@
 	(global.GOVUKFrontend = global.GOVUKFrontend || {}, global.GOVUKFrontend.Accordion = factory());
 }(this, (function () { '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,6 +32,500 @@ function nodeListForEach (nodes, callback) {
   }
 }
 
+/**
+ * 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
@@ -758,13 +1266,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';
@@ -855,7 +1538,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++) {
@@ -972,17 +1655,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';
+  var newButtonText = expanded
+    ? this.i18n.t('hideSection')
+    : this.i18n.t('showSection');
 
-  // 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';
-
-  $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);
@@ -1017,9 +1717,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) {
@@ -1082,17 +1784,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');
@@ -1100,6 +1799,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.
+ */
+
 return Accordion;
 
 })));