govuk_tech_docs 2.2.2 → 2.4.2

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

@@ -891,7 +891,7 @@ Accordion.prototype.initHeaderAttributes = function ($headerWrapper, index) {
   icon.className = this.iconClass;
   icon.setAttribute('aria-hidden', 'true');
 
-  $heading.appendChild(icon);
+  $button.appendChild(icon);
 };
 
 // When section toggled, set and store state
@@ -1498,7 +1498,7 @@ function CharacterCount ($module) {
   this.$module = $module;
   this.$textarea = $module.querySelector('.govuk-js-character-count');
   if (this.$textarea) {
-    this.$countMessage = $module.querySelector('[id=' + this.$textarea.id + '-info]');
+    this.$countMessage = $module.querySelector('[id="' + this.$textarea.id + '-info"]');
   }
 }
 
@@ -1542,13 +1542,22 @@ CharacterCount.prototype.init = function () {
   // Remove hard limit if set
   $module.removeAttribute('maxlength');
 
-  // Bind event changes to the textarea
-  var boundChangeEvents = this.bindChangeEvents.bind(this);
-  boundChangeEvents();
+  // When the page is restored after navigating 'back' in some browsers the
+  // state of the character count is not restored until *after* the DOMContentLoaded
+  // event is fired, so we need to sync after the pageshow event in browsers
+  // that support it.
+  if ('onpageshow' in window) {
+    window.addEventListener('pageshow', this.sync.bind(this));
+  } else {
+    window.addEventListener('DOMContentLoaded', this.sync.bind(this));
+  }
 
-  // Update count message
-  var boundUpdateCountMessage = this.updateCountMessage.bind(this);
-  boundUpdateCountMessage();
+  this.sync();
+};
+
+CharacterCount.prototype.sync = function () {
+  this.bindChangeEvents();
+  this.updateCountMessage();
 };
 
 // Read data attributes
@@ -1596,8 +1605,7 @@ CharacterCount.prototype.checkIfValueChanged = function () {
   if (!this.$textarea.oldValue) this.$textarea.oldValue = '';
   if (this.$textarea.value !== this.$textarea.oldValue) {
     this.$textarea.oldValue = this.$textarea.value;
-    var boundUpdateCountMessage = this.updateCountMessage.bind(this);
-    boundUpdateCountMessage();
+    this.updateCountMessage();
   }
 };
 
@@ -1666,52 +1674,157 @@ function Checkboxes ($module) {
   this.$inputs = $module.querySelectorAll('input[type="checkbox"]');
 }
 
+/**
+ * Initialise Checkboxes
+ *
+ * Checkboxes can be associated with a 'conditionally revealed' content block –
+ * for example, a checkbox for 'Phone' could reveal an additional form field for
+ * the user to enter their phone number.
+ *
+ * These associations are made using a `data-aria-controls` attribute, which is
+ * promoted to an aria-controls attribute during initialisation.
+ *
+ * We also need to restore the state of any conditional reveals on the page (for
+ * example if the user has navigated back), and set up event handlers to keep
+ * the reveal in sync with the checkbox state.
+ */
 Checkboxes.prototype.init = function () {
   var $module = this.$module;
   var $inputs = this.$inputs;
 
-  /**
-  * Loop over all items with [data-controls]
-  * Check if they have a matching conditional reveal
-  * If they do, assign attributes.
-  **/
   nodeListForEach($inputs, function ($input) {
-    var controls = $input.getAttribute('data-aria-controls');
+    var target = $input.getAttribute('data-aria-controls');
 
-    // Check if input controls anything
-    // Check if content exists, before setting attributes.
-    if (!controls || !$module.querySelector('#' + controls)) {
+    // Skip checkboxes without data-aria-controls attributes, or where the
+    // target element does not exist.
+    if (!target || !$module.querySelector('#' + target)) {
       return
     }
 
-    // If we have content that is controlled, set attributes.
-    $input.setAttribute('aria-controls', controls);
+    // Promote the data-aria-controls attribute to a aria-controls attribute
+    // so that the relationship is exposed in the AOM
+    $input.setAttribute('aria-controls', target);
     $input.removeAttribute('data-aria-controls');
-    this.setAttributes($input);
-  }.bind(this));
+  });
+
+  // When the page is restored after navigating 'back' in some browsers the
+  // state of form controls is not restored until *after* the DOMContentLoaded
+  // event is fired, so we need to sync after the pageshow event in browsers
+  // that support it.
+  if ('onpageshow' in window) {
+    window.addEventListener('pageshow', this.syncAllConditionalReveals.bind(this));
+  } else {
+    window.addEventListener('DOMContentLoaded', this.syncAllConditionalReveals.bind(this));
+  }
+
+  // Although we've set up handlers to sync state on the pageshow or
+  // DOMContentLoaded event, init could be called after those events have fired,
+  // for example if they are added to the page dynamically, so sync now too.
+  this.syncAllConditionalReveals();
 
-  // Handle events
   $module.addEventListener('click', this.handleClick.bind(this));
 };
 
-Checkboxes.prototype.setAttributes = function ($input) {
-  var inputIsChecked = $input.checked;
-  $input.setAttribute('aria-expanded', inputIsChecked);
+/**
+ * Sync the conditional reveal states for all inputs in this $module.
+ */
+Checkboxes.prototype.syncAllConditionalReveals = function () {
+  nodeListForEach(this.$inputs, this.syncConditionalRevealWithInputState.bind(this));
+};
 
-  var $content = this.$module.querySelector('#' + $input.getAttribute('aria-controls'));
-  if ($content) {
-    $content.classList.toggle('govuk-checkboxes__conditional--hidden', !inputIsChecked);
+/**
+ * Sync conditional reveal with the input state
+ *
+ * Synchronise the visibility of the conditional reveal, and its accessible
+ * state, with the input's checked state.
+ *
+ * @param {HTMLInputElement} $input Checkbox input
+ */
+Checkboxes.prototype.syncConditionalRevealWithInputState = function ($input) {
+  var $target = this.$module.querySelector('#' + $input.getAttribute('aria-controls'));
+
+  if ($target && $target.classList.contains('govuk-checkboxes__conditional')) {
+    var inputIsChecked = $input.checked;
+
+    $input.setAttribute('aria-expanded', inputIsChecked);
+    $target.classList.toggle('govuk-checkboxes__conditional--hidden', !inputIsChecked);
   }
 };
 
+/**
+ * Uncheck other checkboxes
+ *
+ * Find any other checkbox inputs with the same name value, and uncheck them.
+ * This is useful for when a “None of these" checkbox is checked.
+ */
+Checkboxes.prototype.unCheckAllInputsExcept = function ($input) {
+  var allInputsWithSameName = document.querySelectorAll('input[type="checkbox"][name="' + $input.name + '"]');
+
+  nodeListForEach(allInputsWithSameName, function ($inputWithSameName) {
+    var hasSameFormOwner = ($input.form === $inputWithSameName.form);
+    if (hasSameFormOwner && $inputWithSameName !== $input) {
+      $inputWithSameName.checked = false;
+    }
+  });
+
+  this.syncAllConditionalReveals();
+};
+
+/**
+ * Uncheck exclusive inputs
+ *
+ * Find any checkbox inputs with the same name value and the 'exclusive' behaviour,
+ * and uncheck them. This helps prevent someone checking both a regular checkbox and a
+ * "None of these" checkbox in the same fieldset.
+ */
+Checkboxes.prototype.unCheckExclusiveInputs = function ($input) {
+  var allInputsWithSameNameAndExclusiveBehaviour = document.querySelectorAll(
+    'input[data-behaviour="exclusive"][type="checkbox"][name="' + $input.name + '"]'
+  );
+
+  nodeListForEach(allInputsWithSameNameAndExclusiveBehaviour, function ($exclusiveInput) {
+    var hasSameFormOwner = ($input.form === $exclusiveInput.form);
+    if (hasSameFormOwner) {
+      $exclusiveInput.checked = false;
+    }
+  });
+
+  this.syncAllConditionalReveals();
+};
+
+/**
+ * Click event handler
+ *
+ * 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
+ */
 Checkboxes.prototype.handleClick = function (event) {
   var $target = event.target;
 
-  // If a checkbox with aria-controls, handle click
-  var isCheckbox = $target.getAttribute('type') === 'checkbox';
+  // Ignore clicks on things that aren't checkbox inputs
+  if ($target.type !== 'checkbox') {
+    return
+  }
+
+  // If the checkbox conditionally-reveals some content, sync the state
   var hasAriaControls = $target.getAttribute('aria-controls');
-  if (isCheckbox && hasAriaControls) {
-    this.setAttributes($target);
+  if (hasAriaControls) {
+    this.syncConditionalRevealWithInputState($target);
+  }
+
+  // No further behaviour needed for unchecking
+  if (!$target.checked) {
+    return
+  }
+
+  // Handle 'exclusive' checkbox behaviour (ie "None of these")
+  var hasBehaviourExclusive = ($target.getAttribute('data-behaviour') === 'exclusive');
+  if (hasBehaviourExclusive) {
+    this.unCheckAllInputsExcept($target);
+  } else {
+    this.unCheckExclusiveInputs($target);
   }
 };
 
@@ -1904,122 +2017,216 @@ ErrorSummary.prototype.getAssociatedLegendOrLabel = function ($input) {
     $input.closest('label')
 };
 
-function Header ($module) {
+function NotificationBanner ($module) {
   this.$module = $module;
 }
 
-Header.prototype.init = function () {
-  // Check for module
+/**
+ * Initialise the component
+ */
+NotificationBanner.prototype.init = function () {
   var $module = this.$module;
+  // Check for module
   if (!$module) {
     return
   }
 
-  // Check for button
-  var $toggleButton = $module.querySelector('.govuk-js-header-toggle');
-  if (!$toggleButton) {
+  this.setFocus();
+};
+
+/**
+ * Focus the element
+ *
+ * If `role="alert"` is set, focus the element to help some assistive technologies
+ * prioritise announcing it.
+ *
+ * You can turn off the auto-focus functionality by setting `data-disable-auto-focus="true"` in the
+ * component HTML. You might wish to do this based on user research findings, or to avoid a clash
+ * with another element which should be focused when the page loads.
+ */
+NotificationBanner.prototype.setFocus = function () {
+  var $module = this.$module;
+
+  if ($module.getAttribute('data-disable-auto-focus') === 'true') {
     return
   }
 
-  // Handle $toggleButton click events
-  $toggleButton.addEventListener('click', this.handleClick.bind(this));
+  if ($module.getAttribute('role') !== 'alert') {
+    return
+  }
+
+  // Set tabindex to -1 to make the element focusable with JavaScript.
+  // Remove the tabindex on blur as the component doesn't need to be focusable after the page has
+  // loaded.
+  if (!$module.getAttribute('tabindex')) {
+    $module.setAttribute('tabindex', '-1');
+
+    $module.addEventListener('blur', function () {
+      $module.removeAttribute('tabindex');
+    });
+  }
+
+  $module.focus();
 };
 
+function Header ($module) {
+  this.$module = $module;
+  this.$menuButton = $module && $module.querySelector('.govuk-js-header-toggle');
+  this.$menu = this.$menuButton && $module.querySelector(
+    '#' + this.$menuButton.getAttribute('aria-controls')
+  );
+}
+
 /**
-* Toggle class
-* @param {object} node element
-* @param {string} className to toggle
-*/
-Header.prototype.toggleClass = function (node, className) {
-  if (node.className.indexOf(className) > 0) {
-    node.className = node.className.replace(' ' + className, '');
-  } else {
-    node.className += ' ' + className;
+ * Initialise header
+ *
+ * Check for the presence of the header, menu and menu button – if any are
+ * missing then there's nothing to do so return early.
+ */
+Header.prototype.init = function () {
+  if (!this.$module || !this.$menuButton || !this.$menu) {
+    return
   }
+
+  this.syncState(this.$menu.classList.contains('govuk-header__navigation--open'));
+  this.$menuButton.addEventListener('click', this.handleMenuButtonClick.bind(this));
 };
 
 /**
-* An event handler for click event on $toggleButton
-* @param {object} event event
-*/
-Header.prototype.handleClick = function (event) {
-  var $module = this.$module;
-  var $toggleButton = event.target || event.srcElement;
-  var $target = $module.querySelector('#' + $toggleButton.getAttribute('aria-controls'));
-
-  // If a button with aria-controls, handle click
-  if ($toggleButton && $target) {
-    this.toggleClass($target, 'govuk-header__navigation--open');
-    this.toggleClass($toggleButton, 'govuk-header__menu-button--open');
+ * Sync menu state
+ *
+ * Sync the menu button class and the accessible state of the menu and the menu
+ * button with the visible state of the menu
+ *
+ * @param {boolean} isVisible Whether the menu is currently visible
+ */
+Header.prototype.syncState = function (isVisible) {
+  this.$menuButton.classList.toggle('govuk-header__menu-button--open', isVisible);
+  this.$menuButton.setAttribute('aria-expanded', isVisible);
+};
 
-    $toggleButton.setAttribute('aria-expanded', $toggleButton.getAttribute('aria-expanded') !== 'true');
-    $target.setAttribute('aria-hidden', $target.getAttribute('aria-hidden') === 'false');
-  }
+/**
+ * Handle menu button click
+ *
+ * When the menu button is clicked, change the visibility of the menu and then
+ * sync the accessibility state and menu button state
+ */
+Header.prototype.handleMenuButtonClick = function () {
+  var isVisible = this.$menu.classList.toggle('govuk-header__navigation--open');
+  this.syncState(isVisible);
 };
 
 function Radios ($module) {
   this.$module = $module;
+  this.$inputs = $module.querySelectorAll('input[type="radio"]');
 }
 
+/**
+ * Initialise Radios
+ *
+ * Radios can be associated with a 'conditionally revealed' content block – for
+ * example, a radio for 'Phone' could reveal an additional form field for the
+ * user to enter their phone number.
+ *
+ * These associations are made using a `data-aria-controls` attribute, which is
+ * promoted to an aria-controls attribute during initialisation.
+ *
+ * We also need to restore the state of any conditional reveals on the page (for
+ * example if the user has navigated back), and set up event handlers to keep
+ * the reveal in sync with the radio state.
+ */
 Radios.prototype.init = function () {
   var $module = this.$module;
-  var $inputs = $module.querySelectorAll('input[type="radio"]');
+  var $inputs = this.$inputs;
 
-  /**
-  * Loop over all items with [data-controls]
-  * Check if they have a matching conditional reveal
-  * If they do, assign attributes.
-  **/
   nodeListForEach($inputs, function ($input) {
-    var controls = $input.getAttribute('data-aria-controls');
+    var target = $input.getAttribute('data-aria-controls');
 
-    // Check if input controls anything
-    // Check if content exists, before setting attributes.
-    if (!controls || !$module.querySelector('#' + controls)) {
+    // Skip radios without data-aria-controls attributes, or where the
+    // target element does not exist.
+    if (!target || !$module.querySelector('#' + target)) {
       return
     }
 
-    // If we have content that is controlled, set attributes.
-    $input.setAttribute('aria-controls', controls);
+    // Promote the data-aria-controls attribute to a aria-controls attribute
+    // so that the relationship is exposed in the AOM
+    $input.setAttribute('aria-controls', target);
     $input.removeAttribute('data-aria-controls');
-    this.setAttributes($input);
-  }.bind(this));
+  });
+
+  // When the page is restored after navigating 'back' in some browsers the
+  // state of form controls is not restored until *after* the DOMContentLoaded
+  // event is fired, so we need to sync after the pageshow event in browsers
+  // that support it.
+  if ('onpageshow' in window) {
+    window.addEventListener('pageshow', this.syncAllConditionalReveals.bind(this));
+  } else {
+    window.addEventListener('DOMContentLoaded', this.syncAllConditionalReveals.bind(this));
+  }
+
+  // Although we've set up handlers to sync state on the pageshow or
+  // DOMContentLoaded event, init could be called after those events have fired,
+  // for example if they are added to the page dynamically, so sync now too.
+  this.syncAllConditionalReveals();
 
   // Handle events
   $module.addEventListener('click', this.handleClick.bind(this));
 };
 
-Radios.prototype.setAttributes = function ($input) {
-  var $content = document.querySelector('#' + $input.getAttribute('aria-controls'));
+/**
+ * Sync the conditional reveal states for all inputs in this $module.
+ */
+Radios.prototype.syncAllConditionalReveals = function () {
+  nodeListForEach(this.$inputs, this.syncConditionalRevealWithInputState.bind(this));
+};
+
+/**
+ * Sync conditional reveal with the input state
+ *
+ * Synchronise the visibility of the conditional reveal, and its accessible
+ * state, with the input's checked state.
+ *
+ * @param {HTMLInputElement} $input Radio input
+ */
+Radios.prototype.syncConditionalRevealWithInputState = function ($input) {
+  var $target = document.querySelector('#' + $input.getAttribute('aria-controls'));
 
-  if ($content && $content.classList.contains('govuk-radios__conditional')) {
+  if ($target && $target.classList.contains('govuk-radios__conditional')) {
     var inputIsChecked = $input.checked;
 
     $input.setAttribute('aria-expanded', inputIsChecked);
-
-    $content.classList.toggle('govuk-radios__conditional--hidden', !inputIsChecked);
+    $target.classList.toggle('govuk-radios__conditional--hidden', !inputIsChecked);
   }
 };
 
+/**
+ * Click event handler
+ *
+ * Handle a click within the $module – if the click occurred on a radio, sync
+ * the state of the conditional reveal for all radio buttons in the same form
+ * with the same name (because checking one radio could have un-checked a radio
+ * in another $module)
+ *
+ * @param {MouseEvent} event Click event
+ */
 Radios.prototype.handleClick = function (event) {
   var $clickedInput = event.target;
-  // We only want to handle clicks for radio inputs
+
+  // Ignore clicks on things that aren't radio buttons
   if ($clickedInput.type !== 'radio') {
     return
   }
-  // Because checking one radio can uncheck a radio in another $module,
-  // we need to call set attributes on all radios in the same form, or document if they're not in a form.
-  //
-  // We also only want radios which have aria-controls, as they support conditional reveals.
+
+  // We only need to consider radios with conditional reveals, which will have
+  // aria-controls attributes.
   var $allInputs = document.querySelectorAll('input[type="radio"][aria-controls]');
+
   nodeListForEach($allInputs, function ($input) {
-    // Only inputs with the same form owner should change.
     var hasSameFormOwner = ($input.form === $clickedInput.form);
-
-    // In radios, only radios with the same name will affect each other.
     var hasSameName = ($input.name === $clickedInput.name);
+
     if (hasSameName && hasSameFormOwner) {
-      this.setAttributes($input);
+      this.syncConditionalRevealWithInputState($input);
     }
   }.bind(this));
 };
@@ -2379,6 +2586,11 @@ function initAll (options) {
   var $toggleButton = scope.querySelector('[data-module="govuk-header"]');
   new Header($toggleButton).init();
 
+  var $notificationBanners = scope.querySelectorAll('[data-module="govuk-notification-banner"]');
+  nodeListForEach($notificationBanners, function ($notificationBanner) {
+    new NotificationBanner($notificationBanner).init();
+  });
+
   var $radios = scope.querySelectorAll('[data-module="govuk-radios"]');
   nodeListForEach($radios, function ($radio) {
     new Radios($radio).init();