govuk_tech_docs 3.2.1 → 3.3.0

data/node_modules/govuk-frontend/govuk/components/checkboxes/_index.scss

@@ -83,7 +83,7 @@
       left: 0;
       width: $govuk-checkboxes-size;
       height: $govuk-checkboxes-size;
-      border: $govuk-border-width-form-element solid currentColor;
+      border: $govuk-border-width-form-element solid currentcolor;
       background: transparent;
     }
 
@@ -155,7 +155,8 @@
     cursor: default;
   }
 
-  .govuk-checkboxes__input:disabled + .govuk-checkboxes__label {
+  .govuk-checkboxes__input:disabled + .govuk-checkboxes__label,
+  .govuk-checkboxes__input:disabled ~ .govuk-hint {
     opacity: .5;
   }
 

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

@@ -1014,10 +1014,24 @@ if (detect) return
 
 }).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
 
+/**
+ * Common helpers which do not require polyfill.
+ *
+ * IMPORTANT: If a helper require a polyfill, please isolate it in its own module
+ * so that the polyfill can be properly tree-shaken and does not burden
+ * the components that do not need that helper
+ *
+ * @module common/index
+ */
+
 /**
  * TODO: Ideally this would be a NodeList.prototype.forEach polyfill
  * This seems to fail in IE8, requires more investigation.
  * See: https://github.com/imagitama/nodelist-foreach-polyfill
+ *
+ * @param {NodeListOf<Element>} nodes - NodeList from querySelectorAll()
+ * @param {nodeListIterator} callback - Callback function to run for each node
+ * @returns {undefined}
  */
 function nodeListForEach (nodes, callback) {
   if (window.NodeList.prototype.forEach) {
@@ -1028,6 +1042,20 @@ function nodeListForEach (nodes, callback) {
   }
 }
 
+/**
+ * @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}
+ */
+
+/**
+ * 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"]');
@@ -1097,7 +1125,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'));
@@ -1155,7 +1183,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/components/details/details.js

@@ -660,14 +660,22 @@ if (detect) return
 .call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
 
 /**
- * TODO: Ideally this would be a NodeList.prototype.forEach polyfill
- * This seems to fail in IE8, requires more investigation.
- * See: https://github.com/imagitama/nodelist-foreach-polyfill
+ * 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
  */
 
-// Used to generate a unique string, allows multiple instances of the component without
-// Them conflicting with each other.
-// https://stackoverflow.com/a/8809472
+/**
+ * Used to generate a unique string, allows multiple instances of the component
+ * without them conflicting with each other.
+ * https://stackoverflow.com/a/8809472
+ *
+ * @returns {string} Unique ID
+ */
 function generateUniqueID () {
   var d = new Date().getTime();
   if (typeof window.performance !== 'undefined' && typeof window.performance.now === 'function') {
@@ -680,6 +688,14 @@ function generateUniqueID () {
   })
 }
 
+/**
+ * @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}
+ */
+
 /**
  * JavaScript 'polyfill' for HTML5's <details> and <summary> elements
  * and 'shim' to add accessiblity enhancements for all browsers
@@ -690,6 +706,12 @@ function generateUniqueID () {
 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;
 }
@@ -744,13 +766,10 @@ Details.prototype.polyfillDetails = function () {
   $summary.tabIndex = 0;
 
   // Detect initial open state
-  var openAttr = $module.getAttribute('open') !== null;
-  if (openAttr === true) {
+  if (this.$module.hasAttribute('open')) {
     $summary.setAttribute('aria-expanded', 'true');
-    $content.setAttribute('aria-hidden', 'false');
   } else {
     $summary.setAttribute('aria-expanded', 'false');
-    $content.setAttribute('aria-hidden', 'true');
     $content.style.display = 'none';
   }
 
@@ -759,37 +778,30 @@ Details.prototype.polyfillDetails = function () {
 };
 
 /**
-* Define a statechange function that updates aria-expanded and style.display
-* @param {object} summary element
-*/
+ * Define a statechange function that updates aria-expanded and style.display
+ *
+ * @returns {boolean} Returns true
+ */
 Details.prototype.polyfillSetAttributes = function () {
-  var $module = this.$module;
-  var $summary = this.$summary;
-  var $content = this.$content;
-
-  var expanded = $summary.getAttribute('aria-expanded') === 'true';
-  var hidden = $content.getAttribute('aria-hidden') === 'true';
-
-  $summary.setAttribute('aria-expanded', (expanded ? 'false' : 'true'));
-  $content.setAttribute('aria-hidden', (hidden ? 'false' : 'true'));
-
-  $content.style.display = (expanded ? 'none' : '');
-
-  var hasOpenAttr = $module.getAttribute('open') !== null;
-  if (!hasOpenAttr) {
-    $module.setAttribute('open', 'open');
+  if (this.$module.hasAttribute('open')) {
+    this.$module.removeAttribute('open');
+    this.$summary.setAttribute('aria-expanded', 'false');
+    this.$content.style.display = 'none';
   } else {
-    $module.removeAttribute('open');
+    this.$module.setAttribute('open', 'open');
+    this.$summary.setAttribute('aria-expanded', 'true');
+    this.$content.style.display = '';
   }
 
   return true
 };
 
 /**
-* Handle cross-modal click events
-* @param {object} node element
-* @param {function} callback function
-*/
+ * Handle cross-modal click events
+ *
+ * @param {object} node - element
+ * @param {polyfillHandleInputsCallback} callback - function
+ */
 Details.prototype.polyfillHandleInputs = function (node, callback) {
   node.addEventListener('keypress', function (event) {
     var target = event.target;
@@ -823,6 +835,12 @@ Details.prototype.polyfillHandleInputs = function (node, callback) {
   node.addEventListener('click', callback);
 };
 
+/**
+ * @callback polyfillHandleInputsCallback
+ * @param {KeyboardEvent} event - Keyboard event
+ * @returns {undefined}
+ */
+
 return Details;
 
 })));

data/node_modules/govuk-frontend/govuk/components/error-summary/error-summary.js

@@ -706,8 +706,262 @@ if (detect) return
 
 }).call('object' === typeof window && window || 'object' === typeof self && self || 'object' === typeof global && global || {});
 
-function ErrorSummary ($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
+}
+
+/**
+ * @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}
+ */
+
+(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
+}
+
+/**
+ * JavaScript enhancements for the ErrorSummary
+ *
+ * Takes focus on initialisation for accessible announcement, unless disabled in configuration.
+ *
+ * @class
+ * @param {HTMLElement} $module - The element this component controls
+ * @param {ErrorSummaryConfig} config - Error summary config
+ */
+function ErrorSummary ($module, config) {
+  // Some consuming code may not be passing a module,
+  // for example if they initialise the component
+  // on their own by directly passing the result
+  // of `document.querySelector`.
+  // To avoid breaking further JavaScript initialisation
+  // we need to safeguard against this so things keep
+  // working the same now we read the elements data attributes
+  if (!$module) {
+    // Little safety in case code gets ported as-is
+    // into and ES6 class constructor, where the return value matters
+    return this
+  }
+
   this.$module = $module;
+
+  var defaultConfig = {
+    disableAutoFocus: false
+  };
+  this.config = mergeConfigs(
+    defaultConfig,
+    config || {},
+    normaliseDataset($module.dataset)
+  );
 }
 
 ErrorSummary.prototype.init = function () {
@@ -715,16 +969,37 @@ ErrorSummary.prototype.init = function () {
   if (!$module) {
     return
   }
-  $module.focus();
 
+  this.setFocus();
   $module.addEventListener('click', this.handleClick.bind(this));
 };
 
 /**
-* Click event handler
-*
-* @param {MouseEvent} event - Click event
-*/
+ * Focus the error summary
+ */
+ErrorSummary.prototype.setFocus = function () {
+  var $module = this.$module;
+
+  if (this.config.disableAutoFocus) {
+    return
+  }
+
+  // Set tabindex to -1 to make the element programmatically focusable, but
+  // remove it on blur as the error summary doesn't need to be focused again.
+  $module.setAttribute('tabindex', '-1');
+
+  $module.addEventListener('blur', function () {
+    $module.removeAttribute('tabindex');
+  });
+
+  $module.focus();
+};
+
+/**
+ * Click event handler
+ *
+ * @param {MouseEvent} event - Click event
+ */
 ErrorSummary.prototype.handleClick = function (event) {
   var target = event.target;
   if (this.focusTarget(target)) {
@@ -848,6 +1123,14 @@ ErrorSummary.prototype.getAssociatedLegendOrLabel = function ($input) {
     $input.closest('label')
 };
 
+/**
+ * Error summary config
+ *
+ * @typedef {object} ErrorSummaryConfig
+ * @property {boolean} [disableAutoFocus = false] -
+ *  If set to `true` the error summary will not be focussed when the page loads.
+ */
+
 return ErrorSummary;
 
 })));

data/node_modules/govuk-frontend/govuk/components/footer/_index.scss

@@ -8,7 +8,7 @@
   $govuk-footer-text: $govuk-text-colour;
   $govuk-footer-link-hover-colour: null; // Only used with the legacy palette
 
-  @if ($govuk-use-legacy-palette) {
+  @if $govuk-use-legacy-palette {
     $govuk-footer-border-top: #a1acb2;
     $govuk-footer-border: govuk-colour("grey-2");
     $govuk-footer-text: #454a4c;
@@ -35,7 +35,7 @@
   .govuk-footer__link {
     @include govuk-link-common;
 
-    @if ($govuk-use-legacy-palette) {
+    @if $govuk-use-legacy-palette {
       &:link,
       &:visited {
         color: $govuk-footer-text;
@@ -52,7 +52,7 @@
     // alphagov/govuk_template includes a specific a:link:focus selector
     // designed to make unvisited links a slightly darker blue when focussed, so
     // we need to override the text colour for that combination of selectors.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         @include govuk-text-colour;
       }
@@ -67,23 +67,16 @@
   }
 
   .govuk-footer__meta {
-    display: -webkit-box;
-    display: -webkit-flex;
     display: -ms-flexbox;
     display: flex; // Support: Flexbox
     margin-right: -$govuk-gutter-half;
     margin-left: -$govuk-gutter-half;
-    -webkit-flex-wrap: wrap;
-        -ms-flex-wrap: wrap;
-            flex-wrap: wrap; // Support: Flexbox
-    -webkit-box-align: end;
-    -webkit-align-items: flex-end;
-        -ms-flex-align: end;
-            align-items: flex-end; // Support: Flexbox
-    -webkit-box-pack: center;
-    -webkit-justify-content: center;
-        -ms-flex-pack: center;
-            justify-content: center; // Support: Flexbox
+    -ms-flex-wrap: wrap;
+        flex-wrap: wrap; // Support: Flexbox
+    -ms-flex-align: end;
+        align-items: flex-end; // Support: Flexbox
+    -ms-flex-pack: center;
+        justify-content: center; // Support: Flexbox
   }
 
   .govuk-footer__meta-item {
@@ -93,14 +86,11 @@
   }
 
   .govuk-footer__meta-item--grow {
-    -webkit-box-flex: 1;
-    -webkit-flex: 1;
-        -ms-flex: 1;
-            flex: 1; // Support: Flexbox
+    -ms-flex: 1;
+        flex: 1; // Support: Flexbox
     @include govuk-media-query ($until: tablet) {
-      -webkit-flex-basis: 320px;
-          -ms-flex-preferred-size: 320px;
-              flex-basis: 320px; // Support: Flexbox
+      -ms-flex-preferred-size: 320px;
+          flex-basis: 320px; // Support: Flexbox
     }
   }