Merge pull request #34 from hmrc/SDT-884_Add-to-a-list

SDT-884 Add to a list component

lib/jest-helpers.js

@@ -9,10 +9,9 @@ const yaml = require('js-yaml')
 const configPaths = require('../config/paths.json')
 const { componentNameToMacroName } = require('./helper-functions.js')
 
-nunjucks.configure(configPaths.components, {
-  trimBlocks: true,
-  lstripBlocks: true
-})
+nunjucks.configure(
+  [ configPaths.components, path.join(configPaths.govukFrontend, 'components') ],
+  { trimBlocks: true, lstripBlocks: true })
 
 /**
  * Render a component's macro for testing

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hmrc-frontend",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Design patterns for HMRC frontends",
   "scripts": {
     "start": "gulp dev",

src/components/_all.scss

@@ -4,3 +4,4 @@
 @import "hmrc-language-select/language-select";
 @import "hmrc-header/header";
 @import "hmrc-internal-header/internal-header";
+@import "hmrc-add-to-a-list/add-to-a-list";

src/components/hmrc-add-to-a-list/_add-to-a-list.scss

@@ -0,0 +1,90 @@
+.hmrc-add-to-a-list {
+  padding-left: 0;
+  @include govuk-font($size: 19);
+  @include mq($from: desktop) {
+    display: table;
+  }
+}
+
+.hmrc-add-to-a-list--short {
+  @include mq($from: desktop) {
+    // to make group of q&a line up horizontally (unless there is just one group)
+    width: 100%;
+
+    // recommended for mostly short questions
+    .hmrc-add-to-a-list__question {
+      width: 30%;
+    }
+  }
+}
+
+.hmrc-add-to-a-list--long {
+  @include mq($from: desktop) {
+    // to make group of q&a line up horizontally (unless there is just one group)
+    width: 100%;
+
+    // recommended for mostly long questions
+    .hmrc-add-to-a-list__question {
+      width: 50%;
+    }
+  }
+}
+
+.hmrc-add-to-a-list__contents {
+  position: relative;
+  padding-bottom: govuk-spacing(1);
+  border-bottom: 1px solid $govuk-border-colour;
+  @include mq($from: desktop) {
+    display: table-row;
+    padding-bottom: 0;
+    border-bottom-width: 0;
+  }
+}
+
+.hmrc-add-to-a-list__identifier,
+.hmrc-add-to-a-list__remove,
+.hmrc-add-to-a-list__change {
+  display: block;
+  margin: 0;
+  @include mq($from: desktop) {
+    display: table-cell;
+    padding: govuk-spacing(3) 0;
+    border-bottom: 1px solid $govuk-border-colour;
+  }
+}
+
+.hmrc-add-to-a-list__identifier {
+  margin: govuk-spacing(2) govuk-spacing(9) 0 0;
+  font-weight: bold;
+  @include mq($from: desktop) {
+    margin: 0;
+  }
+}
+
+.hmrc-add-to-a-list__identifier--light {
+  font-weight: normal;
+}
+
+.hmrc-add-to-a-list__remove {
+  margin-top: govuk-spacing(2);
+  margin-bottom: govuk-spacing(2);
+  text-align: right;
+
+  @include mq($from: desktop) {
+    padding-right: 0;
+  }
+}
+
+.hmrc-add-to-a-list__change {
+  position: absolute;
+  top: 0;
+  right: 0;
+  text-align: right;
+  @include mq($from: desktop) {
+    position: static;
+
+    + .hmrc-add-to-a-list__remove {
+      width: 6em;
+    }
+  }
+}

src/components/hmrc-add-to-a-list/add-to-a-list.yaml

@@ -0,0 +1,64 @@
+params:
+  - itemList:
+    type: array
+    required: true
+    description: the list of items being added to
+    params:
+      - name:
+        type: string
+        required: true
+        description: the identifier for this item
+
+      - changeUrl:
+        type: string
+        description: the URL to edit the details for this item
+
+      - removeUrl:
+        type: string
+        description: the URL to remove this item from the list
+
+  - itemType:
+      - singular:
+        type: string
+        required: false
+        default: Item
+        description: Noun used for a single entry in the itemList
+
+      - plural:
+        type: string
+        required: false
+        default: Items
+        description: Noun used for multiple entries in the itemList
+
+      - itemSize:
+        type: string
+        required: false
+        default: short
+        description: 'short or long, used to choose the correct css classes for the first column text'
+
+      - formAction:
+        type: string
+        required: true
+        description: URL used to handle the form
+
+examples:
+- name: default
+  description: A default example.
+  data: {}
+
+- name: directors
+  data:
+    itemList:
+        - { name: Director One, changeUrl: '#c1url', removeUrl: '#r1url' }
+        - { name: Director Two, changeUrl: '#c2url', removeUrl: '#r2url' }
+    itemType:
+      singular: director
+      plural: directors
+    hintText: You must tell us about all your directors
+    formAction: '#addDirector'
+
+- name: singleitem
+  description: A list with a single unnamed item
+  data:
+    itemList:
+      - { name: item one, changeUrl: '#c1url', removeUrl: '#r1url' }

src/components/hmrc-add-to-a-list/macro.njk

@@ -0,0 +1,3 @@
+{% macro hmrcAddToAList(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

src/components/hmrc-add-to-a-list/template.njk

@@ -0,0 +1,56 @@
+{% from "button/macro.njk" import govukButton with context%}
+{% from "radios/macro.njk" import govukRadios with context %}
+
+<h1 class="govuk-heading-xl">You have added {{ params.itemList | length | default('no', true) }}
+{%- if params.itemList | length  === 1 %} {{ params.itemType.singular | default('item') }}
+{%- else %} {{ params.itemType.plural | default('items') }}
+{%- endif -%}
+</h1>
+<div class="govuk-form-group">
+  <ul class="hmrc-add-to-a-list hmrc-add-to-a-list--{{ params.itemSize | default('short') }}">
+    {# loop through items in  the itemList #}
+    {% for item in params.itemList %}
+    <li class="hmrc-add-to-a-list__contents">
+      <span class="hmrc-add-to-a-list__identifier hmrc-add-to-a-list__identifier--light">
+        {{ item.name }}
+      </span>
+      <span class="hmrc-add-to-a-list__change">
+        <a class="govuk-link" href="{{ item.changeUrl }}">
+          <span aria-hidden="true">Change</span>
+          <span class="govuk-visually-hidden">Change {{ item.name }}</span>
+        </a>
+      </span>
+      <span class="hmrc-add-to-a-list__remove">
+        <a class="govuk-link" href="{{ item.removeUrl }}">
+          <span aria-hidden="true">Remove</span>
+          <span class="govuk-visually-hidden">Remove {{item.name}} from the list</span>
+        </a>
+      </span>
+    </li>
+    {% else %}
+      {# empty list stuff goes here #}
+    {% endfor %}
+    {# end loop #}
+  </ul>
+</div>
+<form method="post" action="{{ params.formAction }}">
+  {{ govukRadios({
+    classes: "govuk-radios--inline",
+    idPrefix: "add-another",
+    name: "add-another",
+    fieldset: {
+      legend: {
+        text:  "Do you need to add another " + params.itemType.singular | default('item') + "?",
+        isPageHeading: false,
+        classes: "govuk-fieldset__legend govuk-fieldset__legend--m"
+      }
+    },
+    hint: {
+      text: params.hintText
+    },
+    items: [
+      { text: "Yes", value: "yes" },
+      { text: "No", value: "no" }
+    ] }) }}
+  {{ govukButton({ text: " Submit " }) }}
+</form>

src/components/hmrc-add-to-a-list/template.test.js

@@ -0,0 +1,71 @@
+/* eslint-env jest */
+
+const { render, getExamples } = require('../../../lib/jest-helpers')
+
+const examples = getExamples('add-to-a-list')
+
+describe('Add to a list', () => {
+  describe('by default', () => {
+    const $ = render('add-to-a-list', examples.default)
+    const $heading = $('h1')
+    const $legend = $('fieldset legend')
+    it('Uses \'items\' as the plural item name', () => {
+      expect($heading.text()).toContain('items')
+    })
+    it('Uses \'no\' as the count value', () => {
+      expect($heading.text()).toContain('no items')
+    })
+    it('has the default legend text', () => {
+      expect($legend.text()).toContain('Do you need to add another item?')
+    })
+  })
+
+  describe('with one item', () => {
+    const $ = render('add-to-a-list', examples.singleitem)
+    const $heading = $('h1')
+    const $rows = $('.hmrc-add-to-a-list__contents')
+    it('Uses \'item\' as the singular item name', () => {
+      expect($heading.text()).toContain('item')
+    })
+    it('Uses \'1\' as the count value', () => {
+      expect($heading.text()).toContain('1 item')
+    })
+    it('Contains a list of 1 item', () => {
+      expect($rows.length).toBe(1)
+      expect($('span.hmrc-add-to-a-list__identifier', $rows).text()).toContain('item one')
+      expect($('span.hmrc-add-to-a-list__change', $rows).text()).toContain('Change')
+      expect($('span.hmrc-add-to-a-list__remove', $rows).text()).toContain('Remove')
+      expect($('span.hmrc-add-to-a-list__change .govuk-visually-hidden', $rows).text()).toContain('Change item one')
+      expect($('span.hmrc-add-to-a-list__remove .govuk-visually-hidden', $rows).text()).toContain('Remove item one from the list')
+    })
+  })
+
+  describe('with two named items', () => {
+    const $ = render('add-to-a-list', examples.directors)
+    const $heading = $('h1')
+    const $rows = $('.hmrc-add-to-a-list__contents')
+    const $legend = $('fieldset legend')
+    const $form = $('form')
+    it('Uses \'directors\' as the plural item name', () => {
+      expect($heading.text()).toContain('directors')
+    })
+    it('Uses \'2\' as the count value', () => {
+      expect($heading.text()).toContain('2 directors')
+    })
+    it('Contains a list of 2 directors', () => {
+      expect($rows.length).toBe(2)
+      expect($('span.hmrc-add-to-a-list__identifier', $rows).eq(0).text()).toContain('Director One')
+      expect($('span.hmrc-add-to-a-list__change .govuk-visually-hidden', $rows).eq(0).text()).toContain('Change Director One')
+      expect($('span.hmrc-add-to-a-list__remove .govuk-visually-hidden', $rows).eq(0).text()).toContain('Remove Director One from the list')
+      expect($('span.hmrc-add-to-a-list__identifier', $rows).eq(1).text()).toContain('Director Two')
+      expect($('span.hmrc-add-to-a-list__change .govuk-visually-hidden', $rows).eq(1).text()).toContain('Change Director Two')
+      expect($('span.hmrc-add-to-a-list__remove .govuk-visually-hidden', $rows).eq(1).text()).toContain('Remove Director Two from the list')
+    })
+    it('has the item type in the legend text', () => {
+      expect($legend.text()).toContain('Do you need to add another director?')
+    })
+    it('has an action set on the form', () => {
+      expect($form.attr('action')).toBe('#addDirector')
+    })
+  })
+})