nhsuk-decorated-components 0.0.2

package/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2022 X-GOVUK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# NHS.UK Decorated Components · [![test](https://github.com/x-govuk/nhsuk-decorated-components/actions/workflows/test.yml/badge.svg)](https://github.com/x-govuk/nhsuk-decorated-components/actions/workflows/test.yml)
+
+Form components for the NHS.UK Design System that require less parameters to collect data. [Replace the multiple parameters needed for saving data with a single `decorate` parameter](https://x-govuk.github.io/nhsuk-prototype-rig/using-data/form-components/).
+
+## Requirements
+
+Node.js v16 or later.
+
+## Installation
+
+> **Note** These components are included by default with the [NHS.UK Prototype Rig](https://x-govuk.github.io/nhsuk-prototype-rig/).
+
+```shell
+npm install nhsuk-decorated-components --save
+```
+
+## Usage
+
+To add them to the NHS.UK Prototype Kit, follow these steps:
+
+1. Add `/node_modules/nhsuk-decorated-components` to your application’s views (`appViews`) in `server.js`:
+
+    ```diff
+      // Set up App
+      var appViews = extensions.getAppViews([
+    +   path.join(projectDir, '/node_modules/nhsuk-decorated-components'),
+        path.join(projectDir, '/app/views/'),
+        path.join(projectDir, '/lib/')
+      ])
+    ```
+
+2. Add the `decorate` global function to your Nunjucks environment (`nunjucksAppEnv`) in `server.js`:
+
+    ```diff
+      var nunjucksAppEnv = nunjucks.configure(appViews, nunjucksConfig)
+
+      // Add Nunjucks Globals
+    + const { decorate } = require('nhsuk-decorated-components')
+    + nunjucksAppEnv.addGlobal('decorate', decorate)
+
+      // Add Nunjucks filters
+      utils.addNunjucksFilters(nunjucksAppEnv)
+    ```
+
+3. Replace imported NHS.UK Frontend macros with those provided by this package:
+
+    ```diff
+    + {% from "x-nhsuk/decorated/button/macro.njk" import button with context %}
+    + {% from "x-nhsuk/decorated/character-count/macro.njk" import characterCount with context %}
+    + {% from "x-nhsuk/decorated/checkboxes/macro.njk" import checkboxes with context %}
+    + {% from "x-nhsuk/decorated/date-input/macro.njk" import dateInput with context %}
+    + {% from "x-nhsuk/decorated/file-upload/macro.njk" import fileUpload with context %}
+    + {% from "x-nhsuk/decorated/input/macro.njk" import input with context %}
+    + {% from "x-nhsuk/decorated/radios/macro.njk" import radios with context %}
+    + {% from "x-nhsuk/decorated/select/macro.njk" import select with context %}
+    + {% from "x-nhsuk/decorated/textarea/macro.njk" import textarea with context %}
+    ```

package/lib/decorate.js

@@ -0,0 +1,143 @@
+const _ = require('lodash')
+
+/**
+ * Add `name`, `value`, `id`, `idPrefix` and `checked`/`selected` attributes
+ * to NHS.UK form inputs. Generates attributes based on where they are stored
+ * in the session data object.
+ *
+ * @param {string} params - Component parameters
+ * @param {string} keyPath - Path to key (using dot/bracket notation)
+ * @param {string} [componentName] - Name of component calling decorate
+ * @returns {Object} Updated component parameters
+ */
+exports.decorate = function (params, keyPath, componentName) {
+  if (typeof keyPath === 'undefined') {
+    return params
+  }
+
+  keyPath = _.toPath(keyPath)
+
+  const { data, errors } = this.ctx
+  if (!data) {
+    return ''
+  }
+
+  // Strip data from key path as auto store data middleware adds it
+  if (keyPath[0] === 'data') {
+    keyPath.shift(1)
+  }
+
+  const storedValue = _.get(data, keyPath)
+
+  params.id = (params.id) ? params.id : keyPath.join('-')
+  params.name = (params.name) ? params.name : keyPath.map(s => `[${s}]`).join('')
+
+  // Add field validations to data
+  if (params.validate) {
+    data.validations = data.validations || {}
+    data.validations[params.name] = params.validate
+  }
+
+  if (componentName === 'dateInput' && !params.items) {
+    params.items = [
+      { decorate: 'day' },
+      { decorate: 'month' },
+      { decorate: 'year' }
+    ]
+  }
+
+  if (params.items) {
+    params.idPrefix = params.id
+    params.items = params.items.map(item => {
+      // Ignore dividers or empty items
+      if (item.divider || item === '') {
+        return item
+      }
+
+      // Validate dates
+      // ==============
+      // We want to validate a combined date, but validate.js validates
+      // individual fields. The custom `date` validator hooks into the year
+      // value and gets day and month values via its `attributes` object.
+      //
+      // 1. Delete `validations` for all date fields
+      // 2. Add `validations` for year field
+
+      if (item.decorate && data.validations) {
+        delete data.validations[params.name] // 1.
+      }
+
+      // Update date input items based on `decorate` value
+      switch (item.decorate) {
+        case 'day':
+          item.classes = item.classes || 'nhsuk-input--width-2'
+          item.id = `${params.id}-day`
+          item.name = `${params.name}[day]`
+          item.label = item.label || 'Day'
+          item.value = storedValue?.day
+          break
+        case 'month':
+          item.classes = item.classes || 'nhsuk-input--width-2'
+          item.id = `${params.id}-month`
+          item.name = `${params.name}[month]`
+          item.label = item.label || 'Month'
+          item.value = storedValue?.month
+          break
+        case 'year':
+          item.classes = item.classes || 'nhsuk-input--width-4'
+          item.id = `${params.id}-year`
+          item.name = `${params.name}[year]`
+          item.label = item.label || 'Year'
+          item.value = storedValue?.year
+
+          if (params.validate && data.validations) {
+            data.validations[item.name] = params.validate // 2.
+          }
+
+          break
+        default:
+          // Use label text if no value given for option
+          if (typeof item.value === 'undefined') {
+            item.value = item.text
+          }
+      }
+
+      let checkedValue = ''
+      let selectedValue = ''
+
+      if (Array.isArray(storedValue)) {
+        // Stored value is an array, check it exists in the array
+        if (storedValue.indexOf(item.value) !== -1) {
+          checkedValue = 'checked'
+          selectedValue = 'selected'
+        }
+      } else {
+        // Stored value is a simple value, check it matches
+        if (storedValue === item.value) {
+          checkedValue = 'checked'
+          selectedValue = 'selected'
+        }
+      }
+
+      item.checked = checkedValue
+      item.selected = selectedValue
+
+      return item
+    })
+  } else {
+    // Check for undefined because value may exist and be intentionally blank
+    if (typeof params.value === 'undefined') {
+      params.value = storedValue
+    }
+  }
+
+  // Add message if error
+  const errorKeyPath = keyPath.join('.')
+  if (errors && errors[errorKeyPath]) {
+    params.errorMessage = {
+      text: errors[errorKeyPath].msg
+    }
+  }
+
+  return params
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "nhsuk-decorated-components",
+  "version": "0.0.2",
+  "description": "Form components for the NHS.UK Design System that require less parameters to collect data",
+  "keywords": [
+    "govuk",
+    "design system",
+    "prototyping",
+    "components"
+  ],
+  "homepage": "https://github.com/x-govuk/nhsuk-decorated-components#readme",
+  "bugs": {
+    "url": "https://github.com/x-govuk/nhsuk-decorated-components/issues"
+  },
+  "license": "MIT",
+  "files": [
+    "lib",
+    "x-nhsuk"
+  ],
+  "main": "lib/decorate.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/x-govuk/nhsuk-decorated-components.git"
+  },
+  "scripts": {
+    "lint": "standard",
+    "test": "ava",
+    "test:watch": "ava --watch",
+    "coverage": "c8 ava"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "devDependencies": {
+    "ava": "^4.0.1",
+    "c8": "^7.11.0",
+    "nhsuk-frontend": "^6.1.2",
+    "nunjucks": "^3.2.3",
+    "standard": "^17.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "lcovonly"
+    ]
+  }
+}

package/x-nhsuk/decorated/button/macro.njk

@@ -0,0 +1,4 @@
+{% from "button/macro.njk" import button as source -%}
+{%- macro button(params) -%}
+  {{- source(params) if params.href else source(decorate(params, params.decorate)) -}}
+{%- endmacro %}

package/x-nhsuk/decorated/character-count/macro.njk

@@ -0,0 +1,4 @@
+{% from "character-count/macro.njk" import govukCharacterCount as source -%}
+{%- macro govukCharacterCount(params) -%}
+  {{- source(decorate(params, params.decorate)) -}}
+{%- endmacro %}

package/x-nhsuk/decorated/checkboxes/macro.njk

@@ -0,0 +1,4 @@
+{% from "checkboxes/macro.njk" import govukCheckboxes as source -%}
+{%- macro govukCheckboxes(params) -%}
+  {{- source(decorate(params, params.decorate)) -}}
+{%- endmacro %}

package/x-nhsuk/decorated/date-input/macro.njk

@@ -0,0 +1,4 @@
+{% from "date-input/macro.njk" import dateInput as source -%}
+{%- macro dateInput(params) -%}
+  {{- source(decorate(params, params.decorate, "dateInput")) -}}
+{%- endmacro %}

package/x-nhsuk/decorated/file-upload/macro.njk

@@ -0,0 +1,4 @@
+{% from "file-upload/macro.njk" import govukFileUpload as source -%}
+{%- macro govukFileUpload(params) -%}
+  {{- source(decorate(params, params.decorate)) -}}
+{%- endmacro %}

package/x-nhsuk/decorated/input/macro.njk

@@ -0,0 +1,4 @@
+{% from "input/macro.njk" import input as source %}
+{%- macro input(params) -%}
+  {{- source(decorate(params, params.decorate)) -}}
+{%- endmacro %}

package/x-nhsuk/decorated/radios/macro.njk

@@ -0,0 +1,4 @@
+{% from "radios/macro.njk" import radios as source -%}
+{%- macro radios(params) -%}
+  {{- source(decorate(params, params.decorate)) -}}
+{%- endmacro %}

package/x-nhsuk/decorated/select/macro.njk

@@ -0,0 +1,4 @@
+{% from "select/macro.njk" import govukSelect as source -%}
+{%- macro govukSelect(params) -%}
+  {{- source(decorate(params, params.decorate)) -}}
+{%- endmacro %}

package/x-nhsuk/decorated/textarea/macro.njk

@@ -0,0 +1,4 @@
+{% from "textarea/macro.njk" import govukTextarea as source -%}
+{%- macro govukTextarea(params) -%}
+  {{- source(decorate(params, params.decorate)) -}}
+{%- endmacro %}