govuk_publishing_components 32.1.0 → 33.1.0

data/node_modules/govuk-frontend/govuk-esm/components/character-count/character-count.mjs

@@ -1,8 +1,106 @@
+import '../../vendor/polyfills/Date/now.mjs'
 import '../../vendor/polyfills/Function/prototype/bind.mjs'
-import '../../vendor/polyfills/Event.mjs' // addEventListener and event.target normaliziation
+import '../../vendor/polyfills/Event.mjs' // addEventListener and event.target normalisation
 import '../../vendor/polyfills/Element/prototype/classList.mjs'
+import { extractConfigByNamespace, mergeConfigs } from '../../common/index.mjs'
+import { I18n } from '../../i18n.mjs'
+import { normaliseDataset } from '../../common/normalise-dataset.mjs'
+import { closestAttributeValue } from '../../common/closest-attribute-value.mjs'
+
+/**
+ * @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
+  }
 
-function CharacterCount ($module) {
   this.$module = $module
   this.$textarea = $module.querySelector('.govuk-js-character-count')
   this.$visibleCountMessage = null
@@ -10,26 +108,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')
+
+  // 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 fallback count message to be immediately after the textarea
+  // 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
@@ -37,36 +137,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)
+  $textareaDescription.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)
-
-  // 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')
@@ -74,9 +158,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 {
@@ -85,35 +169,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))
@@ -123,10 +184,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
@@ -134,14 +237,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
@@ -167,10 +276,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
 
@@ -183,69 +294,160 @@ 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 countType = this.config.maxwords ? 'words' : 'characters'
+  return this.formatCountMessage(remainingNumber, countType)
+}
 
-  var charVerb = 'remaining'
-  var charNoun = 'character'
-  var displayNumber = remainingNumber
-  if (options.maxwords) {
-    charNoun = 'word'
+/**
+ * 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)
-}
-
 export default CharacterCount
+
+/**
+ * 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
+ */

data/node_modules/govuk-frontend/govuk-esm/components/checkboxes/checkboxes.mjs

@@ -2,8 +2,14 @@ import '../../vendor/polyfills/Function/prototype/bind.mjs'
 // addEventListener, event.target normalization and DOMContentLoaded
 import '../../vendor/polyfills/Event.mjs'
 import '../../vendor/polyfills/Element/prototype/classList.mjs'
-import { nodeListForEach } from '../../common.mjs'
+import { nodeListForEach } from '../../common/index.mjs'
 
+/**
+ * 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"]')
@@ -73,7 +79,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'))
@@ -131,7 +137,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

data/node_modules/govuk-frontend/govuk-esm/components/details/details.mjs

@@ -6,11 +6,17 @@
  */
 import '../../vendor/polyfills/Function/prototype/bind.mjs'
 import '../../vendor/polyfills/Event.mjs' // addEventListener and event.target normaliziation
-import { generateUniqueID } from '../../common.mjs'
+import { generateUniqueID } from '../../common/index.mjs'
 
 var KEY_ENTER = 13
 var KEY_SPACE = 32
 
+/**
+ * Details component
+ *
+ * @class
+ * @param {HTMLElement} $module - HTML element to use for details
+ */
 function Details ($module) {
   this.$module = $module
 }
@@ -77,9 +83,10 @@ 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 () {
   if (this.$module.hasAttribute('open')) {
     this.$module.removeAttribute('open')
@@ -95,10 +102,11 @@ Details.prototype.polyfillSetAttributes = function () {
 }
 
 /**
-* 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
@@ -133,3 +141,9 @@ Details.prototype.polyfillHandleInputs = function (node, callback) {
 }
 
 export default Details
+
+/**
+ * @callback polyfillHandleInputsCallback
+ * @param {KeyboardEvent} event - Keyboard event
+ * @returns {undefined}
+ */