govuk_publishing_components 32.1.0 → 33.0.0

data/node_modules/govuk-frontend/govuk/components/character-count/character-count.js

@@ -4,6 +4,20 @@
 	(global.GOVUKFrontend = global.GOVUKFrontend || {}, global.GOVUKFrontend.CharacterCount = factory());
 }(this, (function () { 'use strict';
 
+(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://github.com/Financial-Times/polyfill-service/blob/master/packages/polyfill-library/polyfills/Object/defineProperty/detect.js
@@ -1014,7 +1028,801 @@ if (detect) return
 
 }).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
 
-function CharacterCount ($module) {
+/**
+ * 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
+ */
+
+/**
+ * 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://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 || {});
+
+(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 || {});
+
+/**
+ * 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
+}
+
+(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)
+  }
+}
+
+/**
+ * @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: ''
+  }
+};
+
+/**
+ * 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
+  }
+
+  var defaultConfig = {
+    threshold: 0,
+    i18n: CHARACTER_COUNT_TRANSLATIONS
+  };
+
+  // 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)
+  if (this.config.maxwords) {
+    this.maxLength = this.config.maxwords;
+  } else if (this.config.maxlength) {
+    this.maxLength = this.config.maxlength;
+  } else {
+    return
+  }
+
   this.$module = $module;
   this.$textarea = $module.querySelector('.govuk-js-character-count');
   this.$visibleCountMessage = null;
@@ -1022,26 +1830,28 @@ function CharacterCount ($module) {
   this.lastInputTimestamp = null;
 }
 
-CharacterCount.prototype.defaults = {
-  characterCountAttribute: 'data-maxlength',
-  wordCountAttribute: 'data-maxwords'
-};
-
-// Initialize component
+/**
+ * Initialise component
+ */
 CharacterCount.prototype.init = function () {
   // Check that required elements are present
   if (!this.$textarea) {
     return
   }
 
-  // Check for module
-  var $module = this.$module;
   var $textarea = this.$textarea;
-  var $fallbackLimitMessage = document.getElementById($textarea.id + '-info');
+  var $textareaDescription = document.getElementById($textarea.id + '-info');
 
-  // Move the fallback count message to be immediately after the textarea
+  // 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 });
+  }
+
+  // Move the textarea description to be immediately after the textarea
   // Kept for backwards compatibility
-  $textarea.insertAdjacentElement('afterend', $fallbackLimitMessage);
+  $textarea.insertAdjacentElement('afterend', $textareaDescription);
 
   // Create the *screen reader* specific live-updating counter
   // This doesn't need any styling classes, as it is never visible
@@ -1049,36 +1859,20 @@ CharacterCount.prototype.init = function () {
   $screenReaderCountMessage.className = 'govuk-character-count__sr-status govuk-visually-hidden';
   $screenReaderCountMessage.setAttribute('aria-live', 'polite');
   this.$screenReaderCountMessage = $screenReaderCountMessage;
-  $fallbackLimitMessage.insertAdjacentElement('afterend', $screenReaderCountMessage);
+  $textareaDescription.insertAdjacentElement('afterend', $screenReaderCountMessage);
 
   // Create our live-updating counter element, copying the classes from the
-  // fallback element for backwards compatibility as these may have been configured
+  // textarea description for backwards compatibility as these may have been
+  // configured
   var $visibleCountMessage = document.createElement('div');
-  $visibleCountMessage.className = $fallbackLimitMessage.className;
+  $visibleCountMessage.className = $textareaDescription.className;
   $visibleCountMessage.classList.add('govuk-character-count__status');
   $visibleCountMessage.setAttribute('aria-hidden', 'true');
   this.$visibleCountMessage = $visibleCountMessage;
-  $fallbackLimitMessage.insertAdjacentElement('afterend', $visibleCountMessage);
-
-  // Hide the fallback limit message
-  $fallbackLimitMessage.classList.add('govuk-visually-hidden');
-
-  // Read options set using dataset ('data-' values)
-  this.options = this.getDataset($module);
+  $textareaDescription.insertAdjacentElement('afterend', $visibleCountMessage);
 
-  // Determine the limit attribute (characters or words)
-  var countAttribute = this.defaults.characterCountAttribute;
-  if (this.options.maxwords) {
-    countAttribute = this.defaults.wordCountAttribute;
-  }
-
-  // Save the element limit
-  this.maxLength = $module.getAttribute(countAttribute);
-
-  // Check for limit
-  if (!this.maxLength) {
-    return
-  }
+  // Hide the textarea description
+  $textareaDescription.classList.add('govuk-visually-hidden');
 
   // Remove hard limit if set
   $textarea.removeAttribute('maxlength');
@@ -1086,9 +1880,9 @@ CharacterCount.prototype.init = function () {
   this.bindChangeEvents();
 
   // 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.
+  // 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 {
@@ -1097,35 +1891,12 @@ CharacterCount.prototype.init = function () {
   this.updateCountMessage();
 };
 
-// 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
-};
-
-// 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;
-  } else {
-    length = text.length;
-  }
-  return length
-};
-
-// 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.handleKeyUp.bind(this));
@@ -1135,10 +1906,52 @@ CharacterCount.prototype.bindChangeEvents = function () {
   $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;
@@ -1146,14 +1959,20 @@ CharacterCount.prototype.checkIfValueChanged = function () {
   }
 };
 
-// Helper function to update both the visible and screen reader-specific
-// counters simultaneously (e.g. on init)
+/**
+ * Update count message
+ *
+ * Helper function to update both the visible and screen reader-specific
+ * counters simultaneously (e.g. on init)
+ */
 CharacterCount.prototype.updateCountMessage = function () {
   this.updateVisibleCountMessage();
   this.updateScreenReaderCountMessage();
 };
 
-// Update visible counter
+/**
+ * Update visible count message
+ */
 CharacterCount.prototype.updateVisibleCountMessage = function () {
   var $textarea = this.$textarea;
   var $visibleCountMessage = this.$visibleCountMessage;
@@ -1179,10 +1998,12 @@ CharacterCount.prototype.updateVisibleCountMessage = function () {
   }
 
   // Update message
-  $visibleCountMessage.innerHTML = this.formattedUpdateMessage();
+  $visibleCountMessage.innerText = this.getCountMessage();
 };
 
-// Update screen reader-specific counter
+/**
+ * Update screen reader count message
+ */
 CharacterCount.prototype.updateScreenReaderCountMessage = function () {
   var $screenReaderCountMessage = this.$screenReaderCountMessage;
 
@@ -1195,70 +2016,161 @@ CharacterCount.prototype.updateScreenReaderCountMessage = function () {
   }
 
   // Update message
-  $screenReaderCountMessage.innerHTML = this.formattedUpdateMessage();
+  $screenReaderCountMessage.innerText = this.getCountMessage();
 };
 
-// Format update message
-CharacterCount.prototype.formattedUpdateMessage = function () {
-  var $textarea = this.$textarea;
-  var options = this.options;
-  var remainingNumber = this.maxLength - this.count($textarea.value);
+/**
+ * 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
+  }
+};
+
+/**
+ * Get count message
+ *
+ * @returns {string} Status message
+ */
+CharacterCount.prototype.getCountMessage = function () {
+  var remainingNumber = this.maxLength - this.count(this.$textarea.value);
 
-  var charVerb = 'remaining';
-  var charNoun = 'character';
-  var displayNumber = remainingNumber;
-  if (options.maxwords) {
-    charNoun = 'word';
+  var countType = this.config.maxwords ? 'words' : 'characters';
+  return this.formatCountMessage(remainingNumber, countType)
+};
+
+/**
+ * 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')
   }
-  charNoun = charNoun + ((remainingNumber === -1 || remainingNumber === 1) ? '' : 's');
 
-  charVerb = (remainingNumber < 0) ? 'too many' : 'remaining';
-  displayNumber = Math.abs(remainingNumber);
+  var translationKeySuffix = remainingNumber < 0 ? 'OverLimit' : 'UnderLimit';
 
-  return 'You have ' + displayNumber + ' ' + charNoun + ' ' + charVerb
+  return this.i18n.t(countType + translationKeySuffix, { count: Math.abs(remainingNumber) })
 };
 
-// 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.
+/**
+ * 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;
-  var options = this.options;
 
   // Determine the remaining number of characters/words
   var currentLength = this.count($textarea.value);
   var maxLength = this.maxLength;
 
-  // Set threshold if presented in options
-  var thresholdPercent = options.threshold ? options.threshold : 0;
-  var thresholdValue = maxLength * thresholdPercent / 100;
+  var thresholdValue = maxLength * this.config.threshold / 100;
 
   return (thresholdValue <= currentLength)
 };
 
-// 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();
-};
-
-CharacterCount.prototype.handleFocus = function () {
-  // If the field is focused, and a keyup event hasn't been detected for at
-  // least 1000 ms (1 second), then run the manual change check.
-  // This is so that the update triggered by the manual comparison doesn't
-  // conflict with debounced KeyboardEvent updates.
-  this.valueChecker = setInterval(function () {
-    if (!this.lastInputTimestamp || (Date.now() - 500) >= this.lastInputTimestamp) {
-      this.checkIfValueChanged();
-    }
-  }.bind(this), 1000);
-};
-
-CharacterCount.prototype.handleBlur = function () {
-  // Cancel value checking on blur
-  clearInterval(this.valueChecker);
-};
+/**
+ * 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
+ */
 
 return CharacterCount;