Allow items to override checked state from values

If a checkbox, radio or select option has the checked or selected option set, always use its value to set the checked or selected state, even when it’s falsey.

As suggested by @edwardhorsford [1]:

> This is helpful when most of the items just need to check if the stored value equals the value, but one or two need more complex logic to determine if they should be selected.

[1]: #2616 (review)

src/govuk/components/checkboxes/checkboxes.yaml

@@ -77,7 +77,7 @@ params:
   - name: checked
     type: boolean
     required: false
-    description: If `true`, the checkbox will be checked when the page loads.
+    description: Whether the checkbox should be checked when the page loads. Takes precedence over the top-level `values` option.
   - name: conditional
     type: boolean
     required: false
@@ -899,3 +899,17 @@ examples:
         text: British
       - value: irish
         text: Irish
+
+- name: item checked overrides values
+  hidden: true
+  data:
+    name: colors
+    items:
+      - value: red
+        text: Red
+      - value: green
+        text: Green
+        checked: false
+      - value: blue
+        text: Blue
+    values: [red, green]

src/govuk/components/checkboxes/template.njk

@@ -63,7 +63,7 @@
         {%- if item.divider %}
           <div class="govuk-checkboxes__divider">{{ item.divider }}</div>
         {%- else %}
-          {% set isChecked = item.checked or (params.values and item.value in params.values) %}
+          {% set isChecked = item.checked | default(params.values and item.value in params.values) %}
           {% set hasHint = true if item.hint.text or item.hint.html %}
           {% set itemHintId = id + "-item-hint" if hasHint else "" %}
           {% set itemDescribedBy = describedBy if not hasFieldset else "" %}

src/govuk/components/checkboxes/template.test.js

@@ -194,6 +194,13 @@ describe('Checkboxes', () => {
       expect($other.attr('checked')).toEqual('checked')
     })
 
+    it('allows item.checked to override values', () => {
+      const $ = render('checkboxes', examples['item checked overrides values'])
+
+      const $green = $('.govuk-checkboxes').find('input[value="green"]')
+      expect($green.attr('checked')).toBeUndefined()
+    })
+
     describe('when they include attributes', () => {
       it('it renders the attributes', () => {
         const $ = render('checkboxes', examples['items with attributes'])

src/govuk/components/radios/radios.yaml

@@ -69,7 +69,7 @@ params:
   - name: checked
     type: boolean
     required: false
-    description: If `true`, the radio will be checked when the page loads.
+    description: Whether the radio should be checked when the page loads. Takes precedence over the top-level `value` option.
   - name: conditional
     type: string
     required: false
@@ -889,3 +889,17 @@ examples:
       - value: no
         text: No
         checked: true
+
+- name: item checked overrides value
+  hidden: true
+  data:
+    name: colors
+    items:
+      - value: red
+        text: Red
+      - value: green
+        text: Green
+        checked: false
+      - value: blue
+        text: Blue
+    value: green

src/govuk/components/radios/template.njk

@@ -56,7 +56,7 @@
         {%- if item.divider %}
         <div class="govuk-radios__divider">{{ item.divider }}</div>
         {%- else %}
-        {% set isChecked = item.checked or (params.value and item.value == params.value) %}
+        {% set isChecked = item.checked | default(params.value and item.value == params.value) %}
         {% set hasHint = true if item.hint.text or item.hint.html %}
         {% set itemHintId = id + '-item-hint' %}
         <div class="govuk-radios__item">

src/govuk/components/radios/template.test.js

@@ -137,6 +137,13 @@ describe('Radios', () => {
       expect($lastInput.attr('checked')).toEqual('checked')
     })
 
+    it('allows item.checked to override value', () => {
+      const $ = render('radios', examples['item checked overrides value'])
+
+      const $green = $('.govuk-radios').find('input[value="green"]')
+      expect($green.attr('checked')).toBeUndefined()
+    })
+
     describe('when they include attributes', () => {
       it('it renders the attributes', () => {
         const $ = render('radios', examples['items with attributes'])

src/govuk/components/select/select.yaml

@@ -23,7 +23,7 @@ params:
   - name: selected
     type: boolean
     required: false
-    description: Sets the option as selected when the page loads.
+    description: Whether the option should be selected when the page loads. Takes precedence over the top-level `value` option.
   - name: disabled
     type: boolean
     required: false
@@ -304,3 +304,17 @@ examples:
         -
           value: 2
           text: GOV.UK frontend option 2
+
+  - name: item selected overrides value
+    hidden: true
+    data:
+      name: colors
+      items:
+        - value: red
+          text: Red
+        - value: green
+          text: Green
+          selected: false
+        - value: blue
+          text: Blue
+      value: green

src/govuk/components/select/template.njk

@@ -42,7 +42,7 @@
   {% for item in params.items %}
     {% if item %}
       <option value="{{ item.value }}"
-        {{-" selected" if item.selected or (params.value and item.value == params.value) }}
+        {{-" selected" if item.selected | default(params.value and item.value == params.value) }}
         {{-" disabled" if item.disabled }}
         {%- for attribute, value in item.attributes %} {{ attribute }}="{{ value }}"{% endfor -%}>{{ item.text }}</option>
     {% endif %}

src/govuk/components/select/template.test.js

@@ -69,6 +69,13 @@ describe('Select', () => {
       expect($selectedItem.attr('selected')).toBeTruthy()
     })
 
+    it('allows item.selected to override value', () => {
+      const $ = render('select', examples['item selected overrides value'])
+
+      const $selectedItem = $('option[value="green"]')
+      expect($selectedItem.attr('selected')).toBeUndefined()
+    })
+
     it('renders item with disabled', () => {
       const $ = render('select', examples.default)