@dwp/govuk-casa 8.7.12 → 8.8.0

package/src/routes/static.js

@@ -0,0 +1,77 @@
+import ExpressJS from 'express';
+import { readFileSync } from 'fs';
+import { URL } from 'url';
+import { resolve } from 'path';
+import { createRequire } from 'module';
+
+import dirname from './dirname.cjs';
+import MutableRouter from '../lib/MutableRouter.js';
+import { validateUrlPath } from '../lib/utils.js';
+
+const { static: ExpressStatic } = ExpressJS; // CommonJS
+
+const oneDay = 86400000;
+
+/**
+ * @typedef {object} StaticOptions Options to configure static router
+ * @property {number} [maxAge=3600000] Cache TTL for all assets (optional, default 1 hour)
+ */
+
+/**
+ * Create a router for serving CASA's static assets.
+ *
+ * @access private
+ * @param {StaticOptions} options Options
+ * @returns {MutableRouter} ExpressJS Router instance
+ */
+export default function staticRouter({
+  maxAge = 3600000,
+} = {}) {
+  const router = new MutableRouter();
+
+  const notFoundHandler = (req, res, next) => {
+    // Fall through to a general purpose error handler
+    next(new Error('404'));
+  };
+
+  const setHeaders = (req, res, next) => {
+    res.set('cache-control', 'public');
+    res.set('pragma', 'cache');
+    res.set('expires', new Date(Date.now() + oneDay).toUTCString());
+    const { pathname } = new URL(req?.originalUrl ?? '', 'https://placeholder.test/');
+    if (pathname.substr(-4) === '.css') {
+      // Just needed for our in-memory CSS assets
+      res.set('content-type', 'text/css');
+    }
+    next();
+  };
+
+  const staticConfig = {
+    etag: true,
+    lastModified: false,
+    maxAge,
+    setHeaders: (res) => {
+      setHeaders(null, res, () => {});
+    },
+  };
+
+  // The CASA CSS source contains the placeholder `~~~CASA_MOUNT_URL~~~` which
+  // must be replaced with the dynamic `mountUrl` to ensure govuk-frontend
+  // assets are served from the correct location.
+  const casaCss = readFileSync(resolve(dirname, '../../dist/assets/css/casa.css'), { encoding: 'utf8' });
+  const casaCssIe8 = readFileSync(resolve(dirname, '../../dist/assets/css/casa-ie8.css'), { encoding: 'utf8' });
+
+  // The static middleware will only server GET/HEAD requests, so we can mount
+  // the middleware using `use()` rather than resorting to `get()`
+  const govukFrontendDirectory = resolve(createRequire(dirname).resolve('govuk-frontend'), '../../');
+
+  router.use('/govuk/assets/js/all.js', ExpressStatic(`${govukFrontendDirectory}/govuk/all.js`, staticConfig));
+  router.use('/govuk/assets', ExpressStatic(`${govukFrontendDirectory}/govuk/assets`, staticConfig));
+  router.use('/govuk/assets', notFoundHandler);
+
+  router.get('/casa/assets/css/casa.css', setHeaders, (req, res) => res.send(casaCss.replace(/~~~CASA_MOUNT_URL~~~/g, validateUrlPath(`${req.baseUrl}/`))));
+  router.get('/casa/assets/css/casa-ie8.css', setHeaders, (req, res) => res.send(casaCssIe8.replace(/~~~CASA_MOUNT_URL~~~/g, validateUrlPath(`${req.baseUrl}/`))));
+  router.use('/casa/assets', notFoundHandler);
+
+  return router;
+}

package/views/casa/components/character-count/README.md

@@ -19,3 +19,13 @@ casaGovukCharacterCount({
   casaErrors: formErrors
 })
 ```
+
+## Google Tag Manager
+
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset label's text content
+
+These are the conventions used by DWP.
+
+> **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/character-count/template.njk

@@ -1,4 +1,4 @@
-{% from "govuk/components/character-count/macro.njk" import govukCharacterCount %}
+{% from 'govuk/components/character-count/macro.njk' import govukCharacterCount %}
 
 {% set fieldErrors = params.casaErrors[params.name] %}
 
@@ -10,11 +10,15 @@
   }) %}
 {% endif %}
 
+{# Merge parameters #}
 {% set mergedParams = mergeObjects(params, {
   id: params.id if params.id else 'f-' + params.name,
   attributes: mergedAttributes,
   errorMessage: {
-    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables)
+    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables),
+    attributes: {
+      'data-ga-question': params.label.text or params.label.html | striptags
+    } if params.casaWithAnalytics else {}
   } if params.casaErrors[params.name].length
 }) %}
 

package/views/casa/components/checkboxes/README.md

@@ -15,62 +15,67 @@ Custom parameters:
 Basic example:
 
 ```nunjucks
-{% from "casa/components/checkboxes/macro.njk" import casaGovukCheckboxes with context %}
+{% from 'casa/components/checkboxes/macro.njk' import casaGovukCheckboxes with context %}
 
 casaGovukCheckboxes({
-  name: "preferences",
+  name: 'preferences',
   casaValue: formData.preferences,
   casaErrors: formErrors,
   fieldset: {
     legend: {
-      text: "Choose your preferences",
+      text: 'Choose your preferences',
       isPageHeading: true,
-      classes: "govuk-fieldset__legend--xl"
+      classes: 'govuk-fieldset__legend--xl'
     }
   },
   hint: {
-    text: "Some instructive hints"
+    text: 'Some instructive hints'
   },
-  items: [{
-    value: "twistedflax",
-    text: "Twisted Flax"
-  }, {
-    value: "tworeeds",
-    text: "Two Reeds"
-  }, {
-    value: "water",
-    text: "Water"
-  }, {
-    value: "horus",
-    text: "Horus"
-  }]
+  items: [
+    {
+      value: 'twoReeds',
+      text: 'Two Reeds'
+    }, {
+      value: 'twistedFlax',
+      text: 'Twisted Flax'
+    }, {
+      value: 'water',
+      text: 'Water'
+    }, {
+      value: 'eyeOfHorus',
+      text: 'Eye of Horus'
+    }
+  ]
 })
 ```
 
-To associate a checkbox item with a toggleable DOM element:
+If you want one of the checkbox items to toggle the display of an element:
 
 ```nunjucks
-{% from "casa/components/checkboxes/macro.njk" import casaGovukCheckboxes with context %}
+{% from 'casa/components/checkboxes/macro.njk' import casaGovukCheckboxes with context %}
 
 {% set panel %}
-  This panel will remain hidden until the "First Choice" option is checked
+  This panel will remain hidden until the 'Yes' checkbox is chosen
 {% endset %}
 
-casaGovukCheckboxes({
-  name: "preferences",
-  casaValue: formData.preferences,
+{{ casaGovukCheckboxes({
+  name: 'preference',
+  casaValue: formData.preference,
   casaErrors: formErrors,
-  items: [{
-    value: "first-choice",
-    text: "First Choice",
-    conditional: {
-      html: panel
+  items: [
+    {
+      value: 'yes',
+      text: 'Yes',
+      conditional: {
+        html: panel
+      }
+    },
+    {
+      value: 'no',
+      text: 'No'
     }
-  }, {
-    value: "second-choice",
-    text: "Second Choice"
-  }]
-})
+  ]
+}) }}
 ```
 
 ## Displaying errors
@@ -86,6 +91,10 @@ The following attributes will be attached to each `<input>` option if `casaWithA
 * `data-ga-question`: Holds the fieldset legend's content
 * `data-ga-answer`: Holds the specific answer's text/html value
 
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset legend's content after removing all html tags
+
 These are the conventions used by DWP.
 
 > **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/checkboxes/template.njk

@@ -1,23 +1,23 @@
-{% from "govuk/components/checkboxes/macro.njk" import govukCheckboxes %}
+{% from 'govuk/components/checkboxes/macro.njk' import govukCheckboxes %}
 
 {# Ensure field name is always suffixed with [] to have it parsed consistently as an array #}
 {% set fieldName = params.name | replace('[]', '') + '[]' %}
 
 {% set fieldErrors = params.casaErrors[params.name] %}
 
-{# Build up attributes #}
+{# Generate validation data- attributes #}
 {% set mergedAttributes = params.attributes or {} %}
 {% if fieldErrors %}
   {% set mergedAttributes = mergeObjects(mergedAttributes, {
     'data-validation': {fn: params.name, va: fieldErrors[0].validator} | dump
   }) %}
 {% endif %}
+
 {% set mergedAttributes = mergeObjects(mergedAttributes, {
   id: params.id if params.id else 'f-' + params.name + '-wrapper' | safe
 }) %}
 
-
-{# Add checked flag to chosen inputs #}
+{# Add checked flag to chosen items #}
 {% set mergedItems = [] %}
 {% for item in params.items %}
   {% set item = mergeObjects({
@@ -31,7 +31,6 @@
   {% set mergedItems = (mergedItems.push(item), mergedItems) %}
 {% endfor %}
 
-
 {# Merge parameters #}
 {% set mergedParams = mergeObjects(params, {
   name: fieldName,
@@ -39,7 +38,10 @@
   attributes: mergedAttributes,
   items: mergedItems,
   errorMessage: {
-    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables)
+    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables),
+    attributes: {
+      'data-ga-question': params.fieldset.legend.text or params.fieldset.legend.html | striptags
+    } if params.casaWithAnalytics else {}
   } if params.casaErrors[params.name] else null
 }) %}
 
@@ -52,5 +54,4 @@
   }) %}
 {% endif %}
 
-
 {{ govukCheckboxes(mergedParams) }}

package/views/casa/components/date-input/README.md

@@ -72,7 +72,7 @@ module.exports = {
   myDateField: sf([
     r.required.make({
       errorMsg: {
-        summary: 'Your error mesasge',
+        summary: 'Your error message',
         focusSuffix: '[dd]'
       }
     }),
@@ -102,3 +102,13 @@ You can also pass a locale:
 ```nunjucks
 1 Ionawr 1980
 ```
+
+## Google Tag Manager
+
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset label's text content after removing all html tags
+
+These are the conventions used by DWP.
+
+> **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/date-input/template.njk

@@ -1,4 +1,4 @@
-{% from "govuk/components/date-input/macro.njk" import govukDateInput %}
+{% from 'govuk/components/date-input/macro.njk' import govukDateInput %}
 
 {% set fieldErrors = params.casaErrors[params.namePrefix] %}
 {% set hasSuffixHighlights = true if fieldErrors[0].focusSuffix.length else false %}
@@ -7,7 +7,7 @@
   {{ 'govuk-input--error' if fieldErrors }}
 {% endset -%}
 
-{# Build up attributes #}
+{# Generate validation data- attributes #}
 {% set mergedAttributes = params.attributes or {} %}
 {% if fieldErrors %}
   {% set mergedAttributes = mergeObjects(mergedAttributes, {
@@ -47,9 +47,11 @@
     })
   ],
   errorMessage: {
-    text: t(params.casaErrors[params.namePrefix][0].inline, params.casaErrors[params.namePrefix][0].variables)
+    text: t(params.casaErrors[params.namePrefix][0].inline, params.casaErrors[params.namePrefix][0].variables),
+    attributes: {
+      'data-ga-question': params.fieldset.legend.text or params.fieldset.legend.html | striptags
+    } if params.casaWithAnalytics else {}
   } if params.casaErrors[params.namePrefix] else null
 }) %}
 
-
 {{ govukDateInput(mergedParams) }}

package/views/casa/components/input/README.md

@@ -19,3 +19,12 @@ casaGovukInput({
   casaErrors: formErrors
 })
 ```
+## Google Tag Manager
+
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset label's text content after removing all html tags
+
+These are the conventions used by DWP.
+
+> **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/input/template.njk

@@ -1,4 +1,4 @@
-{% from "govuk/components/input/macro.njk" import govukInput %}
+{% from 'govuk/components/input/macro.njk' import govukInput %}
 
 {% set fieldErrors = params.casaErrors[params.name] %}
 
@@ -10,11 +10,15 @@
   }) %}
 {% endif %}
 
+{# Merge parameters #}
 {% set mergedParams = mergeObjects(params, {
   id: params.id if params.id else 'f-' + params.name,
   attributes: mergedAttributes,
   errorMessage: {
-    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables)
+    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables),
+    attributes: {
+      'data-ga-question': params.label.text or params.label.html | striptags
+    } if params.casaWithAnalytics else {}
   } if params.casaErrors[params.name].length
 }) %}
 

package/views/casa/components/postal-address-object/README.md

@@ -52,3 +52,13 @@ With configurable items:
 There is a companion validation rule - [`postalAddressObject`](../../../../../docs/field-validation-rules.md#postalAddressObject) - that you can use to ensure the addresses are passed in correctly. See this rule for more information on how to control error highlighting among other things.
 
 And when using the `required` field validator in conjunction with this macro, you will need to configure the validator to indicate which part of the date input you want to focus on when linked from the error summary, using the `focusSuffix` error option:
+
+## Google Tag Manager
+
+The following attributes will be attached to the error `<p>` tags if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the specific item's label's text content after removing all html tags
+
+These are the conventions used by DWP.
+
+> **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/postal-address-object/template.njk

@@ -20,7 +20,10 @@
       },
       attributes: fieldAttributes,
       errorMessage: {
-        text: t(fieldAddress1Errors[0].inline, fieldAddress1Errors[0].variables)
+        text: t(fieldAddress1Errors[0].inline, fieldAddress1Errors[0].variables),
+        attributes: {
+          'data-ga-question': t('macros:postalAddressObject.address1') | striptags
+        } if params.casaWithAnalytics else {}
       } if fieldAddress1Errors else null
     }, params.address1 if params.address1 else {}, {
       id: 'f-' + params.name + '[address1]',
@@ -39,7 +42,10 @@
       },
       attributes: fieldAttributes,
       errorMessage: {
-        text: t(fieldAddress2Errors[0].inline, fieldAddress2Errors[0].variables)
+        text: t(fieldAddress2Errors[0].inline, fieldAddress2Errors[0].variables),
+        attributes: {
+          'data-ga-question': t('macros:postalAddressObject.address2') | striptags
+        } if params.casaWithAnalytics else {}
       } if fieldAddress2Errors else null
     }, params.address2 if params.address2 else {}, {
       id: 'f-' + params.name + '[address2]',
@@ -61,7 +67,10 @@
     },
     attributes: fieldAttributes,
     errorMessage: {
-      text: t(fieldErrors[0].inline, fieldErrors[0].variables)
+      text: t(fieldErrors[0].inline, fieldErrors[0].variables),
+      attributes: {
+        'data-ga-question': t('macros:postalAddressObject.address3')
+      } if params.casaWithAnalytics else {}
     } if fieldErrors else null
   }, params.address3 if params.address3 else {}, {
     id: 'f-' + params.name + '[address3]',
@@ -82,7 +91,10 @@
     },
     attributes: fieldAttributes,
     errorMessage: {
-      text: t(fieldErrors[0].inline, fieldErrors[0].variables)
+      text: t(fieldErrors[0].inline, fieldErrors[0].variables),
+      attributes: {
+        'data-ga-question': t('macros:postalAddressObject.address4')
+      } if params.casaWithAnalytics else {}
     } if fieldErrors else null
   }, params.address4 if params.address4 else {}, {
     id: 'f-' + params.name + '[address4]',
@@ -103,7 +115,10 @@
     },
     attributes: fieldAttributes,
     errorMessage: {
-      text: t(fieldErrors[0].inline, fieldErrors[0].variables)
+      text: t(fieldErrors[0].inline, fieldErrors[0].variables),
+      attributes: {
+        'data-ga-question': t('macros:postalAddressObject.postcode')
+      } if params.casaWithAnalytics else {}
     } if fieldErrors else null
   }, params.postcode if params.postcode else {}, {
     id: 'f-' + params.name + '[postcode]',

package/views/casa/components/radios/README.md

@@ -13,45 +13,66 @@ Custom parameters:
 Basic example:
 
 ```nunjucks
-{% from "casa/components/radios/macro.njk" import casaGovukRadios with context %}
+{% from 'casa/components/radios/macro.njk' import casaGovukRadios with context %}
 
 {{ casaGovukRadios({
-  name: 'myInput',
-  casaValue: formData.myInput,
+  name: 'preference',
+  casaValue: formData.preference,
   casaErrors: formErrors,
-  items: [{
-    text: 'Yes',
-    value: 'yes'
-  }, {
-    text: 'No',
-    value: 'no'
-  }]
+  fieldset: {
+    legend: {
+      text: 'Choose your preference',
+      isPageHeading: true,
+      classes: 'govuk-fieldset__legend--xl'
+    }
+  },
+  hint: {
+    text: 'Some instructive hints'
+  },
+  items: [
+    {
+      value: 'twoReeds',
+      text: 'Two Reeds'
+    }, {
+      value: 'twistedFlax',
+      text: 'Twisted Flax'
+    }, {
+      value: 'water',
+      text: 'Water'
+    }, {
+      value: 'eyeOfHorus',
+      text: 'Eye of Horus'
+    }
+  ]
 }) }}
 ```
 
 If you want one of the radio items to toggle the display of an element:
 
 ```nunjucks
-{% from "casa/components/radios/macro.njk" import casaGovukRadios with context %}
+{% from 'casa/components/radios/macro.njk' import casaGovukRadios with context %}
 
 {% set panel %}
-  This panel will remain hidden until the "Yes" radio button is chosen
+  This panel will remain hidden until the 'Yes' radio button is chosen
 {% endset %}
 
 {{ casaGovukRadios({
-  name: 'myInput',
-  casaValue: formData.myInput,
+  name: 'preference',
+  casaValue: formData.preference,
   casaErrors: formErrors,
-  items: [{
-    text: 'Yes',
-    value: 'yes',
-    conditional: {
-      html: panel
+  items: [
+    {
+      value: 'yes',
+      text: 'Yes',
+      conditional: {
+        html: panel
+      }
+    },
+    {
+      value: 'no',
+      text: 'No'
     }
-  }, {
-    text: 'No',
-    value: 'no'
-  }]
+  ]
 }) }}
 ```
 
@@ -61,13 +82,17 @@ ref: <https://design-system.service.gov.uk/components/error-summary/>
 
 The error summary link must set focus on the first radio in the group. Unless you have specified an explicit `id` for the first item in the list, this macro will explicitly set that `id` to `f-<name>`, e.g. `f-preferences` in order for links from the error summary to work as expected.
 
-## Google Tag Manager
+## Google Analytics
 
 The following attributes will be attached to each `<input>` option if `casaWithAnalytics` is `true`:
 
 * `data-ga-question`: Holds the fieldset legend's content
 * `data-ga-answer`: Holds the specific answer's text/html value
 
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset legend's content after removing all html tags
+
 These are the conventions used by DWP.
 
 > **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/radios/template.njk

@@ -1,4 +1,4 @@
-{% from "govuk/components/radios/macro.njk" import govukRadios %}
+{% from 'govuk/components/radios/macro.njk' import govukRadios %}
 
 {% set fieldErrors = params.casaErrors[params.name] %}
 
@@ -10,7 +10,7 @@
   }) %}
 {% endif %}
 
-{# Add checked flag to chosen input #}
+{# Add checked flag to chosen item #}
 {% set mergedItems = [] %}
 {% for item in params.items %}
   {% set item = mergeObjects({
@@ -30,7 +30,10 @@
   attributes: mergedAttributes,
   items: mergedItems,
   errorMessage: {
-    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables)
+    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables),
+    attributes: {
+      'data-ga-question': params.fieldset.legend.text or params.fieldset.legend.html | striptags
+    } if params.casaWithAnalytics else {}
   } if params.casaErrors[params.name].length
 }) %}
 

package/views/casa/components/select/README.md

@@ -0,0 +1,65 @@
+# `casaGovukSelect()`
+
+Extends the [`govukSelect()`](https://design-system.service.gov.uk/components/select/) macro.
+
+Custom parameters:
+
+* `casaValue` - the value of the selected option. This is a convenience for toggling the `selected` flag on the appropriate `item`, but you can also manually set `selected` on each item of you need to use more specific logic for determining selected state.
+* `casaErrors` - form errors (just pass `formErrors`)
+* `casaWithAnalytics` - enable DWP's conventional Google Analytics attributes (`data-ga-question` and `data-ga-answer`) - `false` by default; **IMPORTANT: DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google**
+
+## Example usage
+
+Basic example:
+
+```nunjucks
+{% from 'casa/components/select/macro.njk' import casaGovukSelect with context %}
+
+{{ casaGovukSelect({
+  name: 'preference',
+  casaValue: formData.preference,
+  casaErrors: formErrors,
+  label: {
+    text: 'Choose your preference'
+  },
+  hint: {
+    text: 'Some instructive hints'
+  },
+  items: [
+    {
+      value: 'twoReeds',
+      text: 'Two Reeds'
+    }, {
+      value: 'twistedFlax',
+      text: 'Twisted Flax'
+    }, {
+      value: 'water',
+      text: 'Water'
+    }, {
+      value: 'eyeOfHorus',
+      text: 'Eye of Horus'
+    }
+  ]
+}) }}
+```
+
+<!-- ## Displaying errors
+
+ref: <https://design-system.service.gov.uk/components/error-summary/>
+
+The error summary link must set focus on the select item in the group. Unless you have specified an explicit `id` for the first item in the list, this macro will explicitly set that `id` to `f-<name>`, e.g. `f-preferences` in order for links from the error summary to work as expected. -->
+
+## Google Analytics
+
+The following attributes will be attached to each `<input>` option if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset legend's content
+* `data-ga-answer`: Holds the specific answer's text/html value
+
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset legend's content after removing all html tags
+
+These are the conventions used by DWP.
+
+> **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/select/macro.njk

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