govuk_tech_docs 2.2.0 → 2.4.0

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

@@ -0,0 +1,320 @@
+@import "../error-message/index";
+@import "../fieldset/index";
+@import "../hint/index";
+@import "../label/index";
+
+@include govuk-exports("govuk/component/checkboxes") {
+
+  $govuk-touch-target-size: 44px;
+  $govuk-checkboxes-size: 40px;
+  $govuk-small-checkboxes-size: 24px;
+  $govuk-checkboxes-label-padding-left-right: govuk-spacing(3);
+
+  .govuk-checkboxes__item {
+    @include govuk-font($size: 19);
+
+    display: block;
+    position: relative;
+
+    min-height: $govuk-checkboxes-size;
+
+    margin-bottom: govuk-spacing(2);
+    padding-left: $govuk-checkboxes-size;
+
+    clear: left;
+  }
+
+  .govuk-checkboxes__item:last-child,
+  .govuk-checkboxes__item:last-of-type {
+    margin-bottom: 0;
+  }
+
+  .govuk-checkboxes__input {
+    $input-offset: ($govuk-touch-target-size - $govuk-checkboxes-size) / 2;
+
+    cursor: pointer;
+
+    // IE8 doesn’t support pseudo-elements, so we don’t want to hide native
+    // elements there.
+    @include govuk-not-ie8 {
+      position: absolute;
+
+      z-index: 1;
+      top: $input-offset * -1;
+      left: $input-offset * -1;
+
+      width: $govuk-touch-target-size;
+      height: $govuk-touch-target-size;
+      margin: 0;
+
+      opacity: 0;
+    }
+
+    @include govuk-if-ie8 {
+      margin-top: 10px;
+      margin-right: $govuk-checkboxes-size / -2;
+      margin-left: $govuk-checkboxes-size / -2;
+      float: left;
+
+      // add focus outline to input
+      &:focus {
+        outline: $govuk-focus-width solid $govuk-focus-colour;
+      }
+    }
+  }
+
+  .govuk-checkboxes__label {
+    display: inline-block;
+    margin-bottom: 0;
+    padding: 8px $govuk-checkboxes-label-padding-left-right govuk-spacing(1);
+    cursor: pointer;
+    // remove 300ms pause on mobile
+    -ms-touch-action: manipulation;
+        touch-action: manipulation;
+  }
+
+  @include govuk-not-ie8 {
+    // [ ] Check box
+    .govuk-checkboxes__label:before {
+      content: "";
+      box-sizing: border-box;
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: $govuk-checkboxes-size;
+      height: $govuk-checkboxes-size;
+      border: $govuk-border-width-form-element solid currentColor;
+      background: transparent;
+    }
+
+    // ✔ Check mark
+    //
+    // The check mark is a box with a border on the left and bottom side (└──),
+    // rotated 45 degrees
+    .govuk-checkboxes__label:after {
+      content: "";
+      box-sizing: border-box;
+
+      position: absolute;
+      top: 11px;
+      left: 9px;
+      width: 23px;
+      height: 12px;
+
+      -webkit-transform: rotate(-45deg);
+
+          -ms-transform: rotate(-45deg);
+
+              transform: rotate(-45deg);
+      border: solid;
+      border-width: 0 0 5px 5px;
+      // Fix bug in IE11 caused by transform rotate (-45deg).
+      // See: alphagov/govuk_elements/issues/518
+      border-top-color: transparent;
+
+      opacity: 0;
+
+      background: transparent;
+    }
+  }
+
+  .govuk-checkboxes__hint {
+    display: block;
+    padding-right: $govuk-checkboxes-label-padding-left-right;
+    padding-left: $govuk-checkboxes-label-padding-left-right;
+  }
+
+  // Focused state
+  .govuk-checkboxes__input:focus + .govuk-checkboxes__label:before {
+    border-width: 4px;
+    box-shadow: 0 0 0 $govuk-focus-width $govuk-focus-colour;
+  }
+
+  // Selected state
+  .govuk-checkboxes__input:checked + .govuk-checkboxes__label:after {
+    opacity: 1;
+  }
+
+  // Disabled state
+  .govuk-checkboxes__input:disabled,
+  .govuk-checkboxes__input:disabled + .govuk-checkboxes__label {
+    cursor: default;
+  }
+
+  .govuk-checkboxes__input:disabled + .govuk-checkboxes__label {
+    opacity: .5;
+  }
+
+  // =========================================================
+  // Dividers ('or')
+  // =========================================================
+
+  .govuk-checkboxes__divider {
+    $govuk-divider-size: $govuk-checkboxes-size !default;
+    @include govuk-font($size: 19);
+    @include govuk-text-colour;
+    width: $govuk-divider-size;
+    margin-bottom: govuk-spacing(2);
+    text-align: center;
+  }
+
+  // =========================================================
+  // Conditional reveals
+  // =========================================================
+
+  // The narrow border is used in the conditional reveals because the border has
+  // to be an even number in order to be centred under the 40px checkbox or radio.
+  $conditional-border-width: $govuk-border-width-narrow;
+  // Calculate the amount of padding needed to keep the border centered against the checkbox.
+  $conditional-border-padding: ($govuk-checkboxes-size / 2) - ($conditional-border-width / 2);
+  // Move the border centered with the checkbox
+  $conditional-margin-left: $conditional-border-padding;
+  // Move the contents of the conditional inline with the label
+  $conditional-padding-left: $conditional-border-padding + $govuk-checkboxes-label-padding-left-right;
+
+  .govuk-checkboxes__conditional {
+    @include govuk-responsive-margin(4, "bottom");
+    margin-left: $conditional-margin-left;
+    padding-left: $conditional-padding-left;
+    border-left: $conditional-border-width solid $govuk-border-colour;
+
+    .js-enabled &--hidden {
+      display: none;
+    }
+
+    & > :last-child {
+      margin-bottom: 0;
+    }
+  }
+
+  // =========================================================
+  // Small checkboxes
+  // =========================================================
+
+  .govuk-checkboxes--small {
+
+    $input-offset: ($govuk-touch-target-size - $govuk-small-checkboxes-size) / 2;
+    $label-offset: $govuk-touch-target-size - $input-offset;
+
+    .govuk-checkboxes__item {
+      @include govuk-clearfix;
+      min-height: 0;
+      margin-bottom: 0;
+      padding-left: $label-offset;
+      float: left;
+    }
+
+    // Shift the touch target into the left margin so that the visible edge of
+    // the control is aligned
+    //
+    //   ┆What colours do you like?
+    //  ┌┆───┐
+    //  │┆[] │ Purple
+    //  └┆▲──┘
+    //  ▲┆└─ Check box pseudo element, aligned with margin
+    //  └─── Touch target (invisible input), shifted into the margin
+    .govuk-checkboxes__input {
+      @include govuk-not-ie8 {
+        left: $input-offset * -1;
+      }
+
+      @include govuk-if-ie8 {
+        margin-left: $govuk-small-checkboxes-size * -1;
+      }
+    }
+
+    // Adjust the size and position of the label.
+    //
+    // Unlike larger checkboxes, we also have to float the label in order to
+    // 'shrink' it, preventing the hover state from kicking in across the full
+    // width of the parent element.
+    .govuk-checkboxes__label {
+      margin-top: -2px;
+      padding: 13px govuk-spacing(3) 13px 1px;
+      float: left;
+
+      @include govuk-media-query($from: tablet) {
+        padding: 11px govuk-spacing(3) 10px 1px;
+      }
+    }
+
+    // [ ] Check box
+    //
+    // Reduce the size of the check box [1], vertically center it within the
+    // touch target [2]
+    .govuk-checkboxes__label:before {
+      top: $input-offset - $govuk-border-width-form-element; // 2
+      width: $govuk-small-checkboxes-size; // 1
+      height: $govuk-small-checkboxes-size; // 1
+    }
+
+    // ✔ Check mark
+    //
+    // Reduce the size of the check mark and re-align within the checkbox
+    .govuk-checkboxes__label:after {
+      top: 15px;
+      left: 6px;
+      width: 12px;
+      height: 6.5px;
+      border-width: 0 0 3px 3px;
+    }
+
+    // Fix position of hint with small checkboxes
+    //
+    // Do not use hints with small checkboxes – because they're within the input
+    // wrapper they trigger the hover state, but clicking them doesn't actually
+    // activate the control.
+    //
+    // (If you do use them, they won't look completely broken... but seriously,
+    // don't use them)
+    .govuk-checkboxes__hint {
+      padding: 0;
+      clear: both;
+    }
+
+    // Align conditional reveals with small checkboxes
+    .govuk-checkboxes__conditional {
+      $margin-left: ($govuk-small-checkboxes-size / 2) - ($conditional-border-width / 2);
+      margin-left: $margin-left;
+      padding-left: $label-offset - ($margin-left + $conditional-border-width);
+      clear: both;
+    }
+
+    // Hover state for small checkboxes.
+    //
+    // We use a hover state for small checkboxes because the touch target size
+    // is so much larger than their visible size, and so we need to provide
+    // feedback to the user as to which checkbox they will select when their
+    // cursor is outside of the visible area.
+    .govuk-checkboxes__item:hover .govuk-checkboxes__input:not(:disabled) + .govuk-checkboxes__label:before {
+      box-shadow: 0 0 0 $govuk-hover-width $govuk-hover-colour;
+    }
+
+    // Because we've overridden the border-shadow provided by the focus state,
+    // we need to redefine that too.
+    //
+    // We use two box shadows, one that restores the original focus state [1]
+    // and another that then applies the hover state [2].
+    .govuk-checkboxes__item:hover .govuk-checkboxes__input:focus + .govuk-checkboxes__label:before {
+      box-shadow:
+        0 0 0 $govuk-focus-width $govuk-focus-colour, // 1
+        0 0 0 $govuk-hover-width $govuk-hover-colour; // 2
+    }
+
+    // For devices that explicitly don't support hover, don't provide a hover
+    // state (e.g. on touch devices like iOS).
+    //
+    // We can't use `@media (hover: hover)` because we wouldn't get the hover
+    // state in browsers that don't support `@media (hover)` (like Internet
+    // Explorer) – so we have to 'undo' the hover state instead.
+    @media (hover: none), (pointer: coarse) {
+      .govuk-checkboxes__item:hover .govuk-checkboxes__input:not(:disabled) + .govuk-checkboxes__label:before {
+        box-shadow: initial;
+      }
+
+      .govuk-checkboxes__item:hover .govuk-checkboxes__input:focus + .govuk-checkboxes__label:before {
+        box-shadow: 0 0 0 $govuk-focus-width $govuk-focus-colour;
+      }
+    }
+  }
+}

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

@@ -1033,52 +1033,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));
+};
+
+/**
+ * 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'));
 
-  var $content = this.$module.querySelector('#' + $input.getAttribute('aria-controls'));
-  if ($content) {
-    $content.classList.toggle('govuk-checkboxes__conditional--hidden', !inputIsChecked);
+  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);
   }
 };