@planning-inspectorate/dynamic-forms 3.20.4 → 3.21.0

package/.azure/pipelines/azure-pipelines-pr.yml

@@ -35,7 +35,7 @@ extends:
             displayName: Cache NPM
           - template: ../steps/node_script.yml
             parameters:
-              nodeVersion: 22
+              nodeVersion: 24
               script: npm ci
               environmentVariables:
                 npm_config_cache: $(Pipeline.Workspace)/.npm
@@ -43,21 +43,21 @@ extends:
             parameters:
               # only run commitlint on branches, not main
               condition: ne(variables['Build.SourceBranchName'], 'main')
-              nodeVersion: 22
+              nodeVersion: 24
               script: npm run commitlint
           - template: ../steps/node_script.yml
             parameters:
-              nodeVersion: 22
+              nodeVersion: 24
               script: npm run lint
           - template: ../steps/node_script.yml
             parameters:
-              nodeVersion: 22
+              nodeVersion: 24
               script: npm run format-check
           - template: ../steps/node_script.yml
             parameters:
-              nodeVersion: 22
+              nodeVersion: 24
               script: npm run test-coverage
           - template: ../steps/node_script.yml
             parameters:
-              nodeVersion: 22
+              nodeVersion: 24
               script: npm run generate-types

package/.azure/pipelines/release.yml

@@ -44,15 +44,15 @@ jobs:
             - checkout: self
             - template: steps/node_script.yml@templates
               parameters:
-                nodeVersion: 22
+                nodeVersion: 24
                 script: npm ci
             - template: steps/node_script.yml@templates
               parameters:
-                nodeVersion: 22
+                nodeVersion: 24
                 script: npm run generate-types
             - template: steps/node_script.yml@templates
               parameters:
-                nodeVersion: 22
+                nodeVersion: 24
                 script: npx semantic-release --branches main ${{ variables.dryRunFlag }}
                 environmentVariables:
                   GH_TOKEN: $(GITHUB_TOKEN)

package/README.md

@@ -82,6 +82,55 @@ The controllers available are:
 | buildSave      | Returns a controller to handle saving the answer and either redirecting to the next question or show any validation errors if present. Accepts a save function. |
 | list/buildList | Renders a check-your-answers page showing all the answers, links to change any answer, and a button to submit the answers.                                      |
 
+#### Saving answers
+
+The `buildSave` controller accepts a `SaveDataFn` which is passed the context required to save the answer(s). To save answers to session during a journey, a `SaveDataFn` implementation is provided called `saveDataToSession`.
+
+For other use cases, write a custom `SaveDataFn`. A basic implementation (if you are not using ManageList) needs to save the answers passed in as `data.answers`, which is an object whose keys are the question field names, and the values are the answers. For example:
+
+```typescript
+const update: SaveDataFn = async ({data}) => {
+    const answers = data.answers;
+    
+    console.log('saving', answers);
+    
+    // TODO: map to database
+    // TODO: write to database
+}
+```
+
+To support `ManageList` questions as well, handle the `isManageListItem`, `manageListQuestionFieldName`, `manageListItemRemove` parameters. For example:
+
+```typescript
+const update: SaveDataFn = async ({data, req, isManageListItem, manageListQuestionFieldName, manageListItemRemove}) => {
+    if (isManageListItem) {
+        const update = {
+            id: req.params.manageListItemId,
+            ...data.answers
+        };
+
+        console.log('saving', update);
+        // TODO: map to database
+        // TODO: write to database
+        return;
+    } else if (manageListItemRemove) {
+        const id = req.params.manageListItemId;
+        // identify which type of item it is via the field name
+        const type = manageListQuestionFieldName;
+        console.log('removing item', {id, type});
+        // TODO: delete from database
+        return;
+    }
+    const answers = data.answers;
+    
+    console.log('saving', answers);
+    
+    // TODO: map to database
+    // TODO: write to database
+}
+```
+
+
 ### Conditions
 
 Conditions are used to show/hide questions based on the answers to other questions. There are fluent methods on a Section

package/docs/Getting Started.md

@@ -78,7 +78,7 @@ Dynamic forms requires two templates to work for rendering questions and renderi
 ### Journey (or question) template
 
 The journey template is used for question pages. It must include a block called `dynQuestionContent`, and a block called `head` (which the default gov.uk template has).
-It should also include the rendering of the errorSummary component. The path to this template is configured via the `journeyTemplate` property on a Journey.
+It should also include the rendering of the errorSummary component, and optionally the back link. The path to this template is configured via the `journeyTemplate` property on a Journey.
 
 For example:
 
@@ -87,7 +87,13 @@ e.g.
 ```nunjucks
 {% extends "govuk/template.njk" %}
 
-{% block beforeContent %}
+{% from "govuk/components/back-link/macro.njk" import govukBackLink %}
+{% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}
+
+{% block containerStart %}
+    {% if backLink %}
+        {{ govukBackLink({ href: backLink }) }}
+    {% endif %}
     {% if errorSummary %}
         <div class="govuk-grid-row">
             <div class="govuk-grid-column-two-thirds">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planning-inspectorate/dynamic-forms",
-  "version": "3.20.4",
+  "version": "3.21.0",
   "description": "This package is for building GDS forms using a configuration-based approach.",
   "main": "./src/index.js",
   "type": "module",

package/src/components/boolean/question.d.ts

@@ -1,9 +1,12 @@
+/**
+ * @typedef {"yes"|"no"} YesNo
+ */
 export const BOOLEAN_OPTIONS: Readonly<{
     YES: "yes";
     NO: "no";
 }>;
 export function yesNoToBoolean(value: string | any): boolean;
-export function booleanToYesNoValue(value: any): "yes" | "no";
+export function booleanToYesNoValue(value: any): YesNo;
 export function booleanToYesNoOrNull(value: boolean | null): string | null;
 export class BooleanQuestion extends RadioQuestion {
     /**
@@ -14,12 +17,28 @@ export class BooleanQuestion extends RadioQuestion {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {JourneyResponse} journeyResponse - current journey response
      * @returns {Promise<{ answers: Record<string, unknown> }>}
      */ getDataToSave(req: import("express").Request, journeyResponse: JourneyResponse): Promise<{
         answers: Record<string, unknown>;
     }>;
+    /**
+     * Normalises a stored boolean answer back to 'yes'/'no' before computing the
+     * view model value, so the radio's `checked` state resolves correctly.
+     *
+     * getDataToSave() saves a real boolean. Top-level questions get this converted
+     * back to 'yes'/'no' by buildGetJourneyResponseFromSession, but that conversion
+     * is shallow and doesn't reach into manage-list item arrays, so nested
+     * BooleanQuestions (e.g. a manage-list sub-question) would otherwise receive
+     * the raw boolean.
+     *
+     * @param {Record<string, unknown>} answers
+     * @param {boolean} isPayload
+     * @returns {unknown|YesNo}
+     */
+    answerForViewModel(answers: Record<string, unknown>, isPayload: boolean): unknown | YesNo;
 }
 export default BooleanQuestion;
+export type YesNo = "yes" | "no";
 import RadioQuestion from '../radio/question.js';
 //# sourceMappingURL=question.d.ts.map

package/src/components/boolean/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAEA;;;GAGG;AAMI,sCAHI,MAAM,GAAC,GAAC,GACN,OAAO,CAOnB;AAEM,8DAEN;AAMM,4CAHI,OAAO,GAAC,IAAI,GACV,MAAM,GAAC,IAAI,CAOvB;AAED;IACC;;OAEG;IACH,6IAFW,OAAO,+BAA+B,EAAE,qBAAqB,EAmDvE;IADA,oCAAkC;IAGnC;;;;;OAKG,CACH,mBAJW,OAAO,SAAS,EAAE,OAAO,mBACzB,eAAe,GACb,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAezD;CACD;;0BA5GyB,sBAAsB"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;GAGG;AAMI,sCAHI,MAAM,GAAC,GAAC,GACN,OAAO,CAOnB;AAMM,iDAFK,KAAK,CAIhB;AAMM,4CAHI,OAAO,GAAC,IAAI,GACV,MAAM,GAAC,IAAI,CAOvB;AAED;IACC;;OAEG;IACH,6IAFW,OAAO,+BAA+B,EAAE,qBAAqB,EAmDvE;IADA,oCAAkC;IAGnC;;;;;OAKG,CACH,mBAJW,OAAO,SAAS,EAAE,OAAO,mBACzB,eAAe,GACb,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAezD;IAED;;;;;;;;;;;;;OAaG;IACH,4BAJW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aACvB,OAAO,GACL,OAAO,GAAC,KAAK,CAQzB;CAgBD;;oBAtJY,KAAK,GAAC,IAAI;0BAHG,sBAAsB"}

package/src/components/boolean/question.js

@@ -1,5 +1,9 @@
 import RadioQuestion from '../radio/question.js';
 
+/**
+ * @typedef {"yes"|"no"} YesNo
+ */
+
 export const BOOLEAN_OPTIONS = Object.freeze({
 	YES: 'yes',
 	NO: 'no'
@@ -16,6 +20,10 @@ export const yesNoToBoolean = (value) => {
 	return value === BOOLEAN_OPTIONS.YES;
 };
 
+/**
+ * @param value
+ * @return {YesNo}
+ */
 export const booleanToYesNoValue = (value) => {
 	return value ? BOOLEAN_OPTIONS.YES : BOOLEAN_OPTIONS.NO;
 };
@@ -89,7 +97,7 @@ export class BooleanQuestion extends RadioQuestion {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise<{ answers: Record<string, unknown> }>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {
@@ -106,6 +114,43 @@ export class BooleanQuestion extends RadioQuestion {
 
 		return { answers };
 	}
+
+	/**
+	 * Normalises a stored boolean answer back to 'yes'/'no' before computing the
+	 * view model value, so the radio's `checked` state resolves correctly.
+	 *
+	 * getDataToSave() saves a real boolean. Top-level questions get this converted
+	 * back to 'yes'/'no' by buildGetJourneyResponseFromSession, but that conversion
+	 * is shallow and doesn't reach into manage-list item arrays, so nested
+	 * BooleanQuestions (e.g. a manage-list sub-question) would otherwise receive
+	 * the raw boolean.
+	 *
+	 * @param {Record<string, unknown>} answers
+	 * @param {boolean} isPayload
+	 * @returns {unknown|YesNo}
+	 */
+	answerForViewModel(answers, isPayload) {
+		const rawValue = answers[this.fieldName];
+		if (typeof rawValue === 'boolean') {
+			return booleanToYesNoValue(rawValue);
+		}
+		return super.answerForViewModel(answers, isPayload);
+	}
+
+	/**
+	 * Normalises a stored boolean answer back to 'yes'/'no' before formatting,
+	 * so summary/check-your-answers pages display 'Yes'/'No' instead of the
+	 * literal 'true'/'false' - see answerForViewModel for why this is needed.
+	 *
+	 * @param {unknown} answer
+	 * @returns {string}
+	 */
+	formatAnswer(answer) {
+		if (typeof answer === 'boolean') {
+			return super.formatAnswer(booleanToYesNoValue(answer));
+		}
+		return super.formatAnswer(answer);
+	}
 }
 
 export default BooleanQuestion;

package/src/components/boolean/question.test.js

@@ -54,7 +54,9 @@ describe('./src/dynamic-forms/components/boolean/question.js', () => {
 	const renderTests = [
 		{ answers: {}, yesChecked: false, noChecked: false },
 		{ answers: { [FIELDNAME]: BOOLEAN_OPTIONS.YES }, yesChecked: true, noChecked: false },
-		{ answers: { [FIELDNAME]: BOOLEAN_OPTIONS.NO }, yesChecked: false, noChecked: true }
+		{ answers: { [FIELDNAME]: BOOLEAN_OPTIONS.NO }, yesChecked: false, noChecked: true },
+		{ answers: { [FIELDNAME]: true }, yesChecked: true, noChecked: false },
+		{ answers: { [FIELDNAME]: false }, yesChecked: false, noChecked: true }
 	];
 	for (const t of renderTests) {
 		it(`should render with ${JSON.stringify(t.answers)}`, async () => {
@@ -90,4 +92,23 @@ describe('./src/dynamic-forms/components/boolean/question.js', () => {
 			assert.strictEqual(booleanToYesNoValue(t.req), t.expect);
 		});
 	}
+
+	describe('formatAnswer', () => {
+		it('formats a true boolean answer as Yes', () => {
+			const booleanQuestion = newQuestion();
+			assert.strictEqual(booleanQuestion.formatAnswer(true), 'Yes');
+		});
+		it('formats a false boolean answer as No', () => {
+			const booleanQuestion = newQuestion();
+			assert.strictEqual(booleanQuestion.formatAnswer(false), 'No');
+		});
+		it('formats a yes string answer as Yes', () => {
+			const booleanQuestion = newQuestion();
+			assert.strictEqual(booleanQuestion.formatAnswer(BOOLEAN_OPTIONS.YES), 'Yes');
+		});
+		it('formats a no string answer as No', () => {
+			const booleanQuestion = newQuestion();
+			assert.strictEqual(booleanQuestion.formatAnswer(BOOLEAN_OPTIONS.NO), 'No');
+		});
+	});
 });

package/src/components/date/question.d.ts

@@ -10,7 +10,7 @@ export class DateQuestion extends Question {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
      * @returns {Promise.<Object>}
      */ getDataToSave(req: import("express").Request, journeyResponse: import("#journey-response").JourneyResponse): Promise<Object>;
     answerForViewModel(answers: any, isPayload: any): {

package/src/components/date/question.js

@@ -29,7 +29,7 @@ export class DateQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise.<Object>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/components/date-period/question.d.ts

@@ -19,7 +19,7 @@ export class DatePeriodQuestion extends Question {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
      * @returns {Promise.<Object>}
      */ getDataToSave(req: import("express").Request, journeyResponse: import("#journey-response").JourneyResponse): Promise<Object>;
     answerForViewModel(answers: any, isPayload: any): {

package/src/components/date-period/question.js

@@ -54,7 +54,7 @@ export class DatePeriodQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise.<Object>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/components/date-time/question.d.ts

@@ -10,7 +10,7 @@ export class DateTimeQuestion extends Question {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {JourneyResponse} journeyResponse - current journey response
      * @returns {Promise.<Object>}
      */ getDataToSave(req: import("express").Request, journeyResponse: JourneyResponse): Promise<Object>;
     answerForViewModel(answers: any, isPayload: any): {

package/src/components/date-time/question.js

@@ -38,7 +38,7 @@ export class DateTimeQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise.<Object>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/components/multi-field-input/question.js

@@ -44,7 +44,7 @@ export class MultiFieldInputQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise<{ answers: Record<string, unknown> }>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/components/single-line-input/index.njk

@@ -38,6 +38,8 @@
                             text: errors[question.fieldName].msg
                         },
                         classes: question.classes,
+                        prefix: question.prefix,
+                        suffix: question.suffix,
                         attributes: question.attributes,
                         type: question.type,
                         autocomplete: question.autocomplete
@@ -62,6 +64,8 @@
                             text: errors[question.fieldName].msg
                         },
                         classes: question.classes,
+                        prefix: question.prefix,
+                        suffix: question.suffix,
                         attributes: question.attributes,
                         type: question.type,
                         autocomplete: question.autocomplete

package/src/components/single-line-input/question.d.ts

@@ -10,6 +10,8 @@ export class SingleLineInputQuestion extends Question {
     inputAttributes: Record<string, string>;
     label: string | undefined;
     classes: string;
+    prefix: import("#typedefs/question-props.d.ts").Affix | undefined;
+    suffix: import("#typedefs/question-props.d.ts").Affix | undefined;
 }
 export default SingleLineInputQuestion;
 import { Question } from '#question';

package/src/components/single-line-input/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAEA;;GAEG;AACH;IAIC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAW/E;IAfD,qCAAqC;IACrC,iBADW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CACjB;IAWf,0BAAyB;IAEzB,gBAAmC;CAepC;;yBAnCwB,WAAW"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAEA;;GAEG;AACH;IAIC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAa/E;IAjBD,qCAAqC;IACrC,iBADW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CACjB;IAWf,0BAAyB;IAEzB,gBAAmC;IACnC,kEAA2B;IAC3B,kEAA2B;CAiB5B;;yBAvCwB,WAAW"}

package/src/components/single-line-input/question.js

@@ -19,6 +19,8 @@ export class SingleLineInputQuestion extends Question {
 		this.label = params.label;
 		this.inputAttributes = params.inputAttributes || {};
 		this.classes = params.classes || '';
+		this.prefix = params.prefix;
+		this.suffix = params.suffix;
 	}
 
 	/**
@@ -32,6 +34,8 @@ export class SingleLineInputQuestion extends Question {
 		viewModel.question.type = type;
 
 		viewModel.question.classes = this.classes;
+		viewModel.question.prefix = this.prefix;
+		viewModel.question.suffix = this.suffix;
 	}
 }
 

package/src/components/single-line-input/question.test.js

@@ -11,6 +11,8 @@ describe('./src/dynamic-forms/components/single-line-input/question.js', () => {
 		const HTML = '/path/to/html.njk';
 		const HINT = 'hint';
 		const LABEL = 'A label';
+		const PREFIX = { text: '£', classes: 'govuk-!-font-weight-bold' };
+		const SUFFIX = { text: 'per year' };
 
 		const question = new SingleLineInputQuestion({
 			title: TITLE,
@@ -20,6 +22,8 @@ describe('./src/dynamic-forms/components/single-line-input/question.js', () => {
 			html: HTML,
 			hint: HINT,
 			label: LABEL,
+			prefix: PREFIX,
+			suffix: SUFFIX,
 			autocomplete: FIELDNAME
 		});
 
@@ -31,6 +35,8 @@ describe('./src/dynamic-forms/components/single-line-input/question.js', () => {
 		assert.strictEqual(question.html, HTML);
 		assert.strictEqual(question.hint, HINT);
 		assert.strictEqual(question.label, LABEL);
+		assert.strictEqual(question.prefix, PREFIX);
+		assert.strictEqual(question.suffix, SUFFIX);
 		assert.strictEqual(question.autocomplete, FIELDNAME);
 	});
 });

package/src/components/unit-option-entry/question.d.ts

@@ -54,7 +54,7 @@ export class UnitOptionEntryQuestion extends Question {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {JourneyResponse} journeyResponse - current journey response
      * @returns {Promise<{ answers: Record<string, unknown> }>}
      */ getDataToSave(req: import("express").Request, journeyResponse: JourneyResponse): Promise<{
         answers: Record<string, unknown>;

package/src/components/unit-option-entry/question.js

@@ -125,7 +125,7 @@ export class UnitOptionEntryQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise<{ answers: Record<string, unknown> }>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/controller.test.js

@@ -1,4 +1,4 @@
-import { describe, it, mock, beforeEach } from 'node:test';
+import { describe, it, mock } from 'node:test';
 import assert from 'node:assert';
 import { list, question, buildSave } from './controller.js';
 
@@ -9,214 +9,210 @@ import { mockReq, mockRes } from '#test/utils/utils.js';
 import { BOOLEAN_OPTIONS } from '#src/components/boolean/question.js';
 import { MANAGE_LIST_ACTIONS } from '#src/components/manage-list/manage-list-actions.js';
 
-const res = mockRes();
 const mockBaseUrl = '/manage-appeals/questionnaire';
 const mockRef = '123456';
 const mockTemplateUrl = 'template.njk';
 const mockListingPath = 'mockListingPath.njk';
 const mockJourneyTitle = 'Mock Manage Appeals';
 const mockAnswer = 'Not started';
-const sections = [
-	{
-		name: 'Section 1',
-		segment: 'segment-1',
-		getStatus: () => {
-			return SECTION_STATUS.COMPLETE;
-		},
-		isComplete: () => {
-			return true;
-		},
-		questions: [
-			{
-				title: 'Title 1a',
-				question: 'Why?',
-				taskList: true,
-				fieldName: 'title-1a',
-				shouldDisplay: () => true,
-				formatAnswerForSummary: mock.fn()
+
+function testSetup() {
+	const sections = [
+		{
+			name: 'Section 1',
+			segment: 'segment-1',
+			getStatus: () => {
+				return SECTION_STATUS.COMPLETE;
 			},
-			{
-				title: 'Title 1b',
-				question: 'Who?',
-				taskList: false,
-				fieldName: 'title-1b',
-				shouldDisplay: () => true,
-				formatAnswerForSummary: mock.fn(() => [
-					{
-						key: 'Title 1b',
-						value: mockAnswer,
-						action: {
-							href: '/manage-appeals/questionnaire/123456/segment-1/title-1b',
-							text: 'Answer',
-							visuallyHiddenText: 'Answer'
+			isComplete: () => {
+				return true;
+			},
+			questions: [
+				{
+					title: 'Title 1a',
+					question: 'Why?',
+					taskList: true,
+					fieldName: 'title-1a',
+					shouldDisplay: () => true,
+					formatAnswerForSummary: mock.fn(() => [
+						{
+							key: 'Title 1a',
+							value: mockAnswer,
+							action: {
+								href: '/manage-appeals/questionnaire/123456/segment-1/title-1a',
+								text: 'Answer',
+								visuallyHiddenText: 'Answer'
+							}
 						}
-					}
-				])
-			}
-		]
-	},
-	{
-		name: 'Section 2',
-		segment: 'segment-2',
-		getStatus: () => {
-			return SECTION_STATUS.IN_PROGRESS;
-		},
-		isComplete: () => {
-			return true;
-		},
-		questions: [
-			{
-				title: 'Title 2a',
-				question: 'How?',
-				taskList: true,
-				fieldName: 'title-2a',
-				shouldDisplay: () => true,
-				formatAnswerForSummary: () => [
-					{
-						key: 'Title 2a',
-						value: mockAnswer,
-						action: {
-							href: '/manage-appeals/questionnaire/123456/segment-2/title-2a',
-							text: 'Answer',
-							visuallyHiddenText: 'Answer'
+					])
+				},
+				{
+					title: 'Title 1b',
+					question: 'Who?',
+					taskList: false,
+					fieldName: 'title-1b',
+					shouldDisplay: () => true,
+					formatAnswerForSummary: mock.fn(() => [
+						{
+							key: 'Title 1b',
+							value: mockAnswer,
+							action: {
+								href: '/manage-appeals/questionnaire/123456/segment-1/title-1b',
+								text: 'Answer',
+								visuallyHiddenText: 'Answer'
+							}
 						}
-					}
-				]
+					])
+				}
+			]
+		},
+		{
+			name: 'Section 2',
+			segment: 'segment-2',
+			getStatus: () => {
+				return SECTION_STATUS.IN_PROGRESS;
 			},
-			{
-				title: 'Title 2b',
-				question: 'What?',
-				taskList: true,
-				fieldName: 'title-2b',
-				shouldDisplay: () => true,
-				formatAnswerForSummary: () => [
-					{
-						key: 'Title 2b',
-						value: mockAnswer,
-						action: {
-							href: '/manage-appeals/questionnaire/123456/segment-2/title-2b',
-							text: 'Answer',
-							visuallyHiddenText: 'Answer'
+			isComplete: () => {
+				return true;
+			},
+			questions: [
+				{
+					title: 'Title 2a',
+					question: 'How?',
+					taskList: true,
+					fieldName: 'title-2a',
+					shouldDisplay: () => true,
+					formatAnswerForSummary: () => [
+						{
+							key: 'Title 2a',
+							value: mockAnswer,
+							action: {
+								href: '/manage-appeals/questionnaire/123456/segment-2/title-2a',
+								text: 'Answer',
+								visuallyHiddenText: 'Answer'
+							}
 						}
-					}
-				]
-			}
-		]
-	},
-	{
-		name: 'Section 3',
-		segment: 'segment-3',
-		getStatus: () => {
-			return SECTION_STATUS.NOT_STARTED;
-		},
-		isComplete: mock.fn(),
-		questions: [
-			{
-				title: 'Title 3a',
-				question: 'When?',
-				taskList: false,
-				fieldName: 'title-3a',
-				shouldDisplay: () => true,
-				formatAnswerForSummary: () => [
-					{
-						key: 'Title 3a',
-						value: mockAnswer,
-						action: {
-							href: '/manage-appeals/questionnaire/123456/segment-3/title-3a',
-							text: 'Answer',
-							visuallyHiddenText: 'Answer'
+					]
+				},
+				{
+					title: 'Title 2b',
+					question: 'What?',
+					taskList: true,
+					fieldName: 'title-2b',
+					shouldDisplay: () => true,
+					formatAnswerForSummary: () => [
+						{
+							key: 'Title 2b',
+							value: mockAnswer,
+							action: {
+								href: '/manage-appeals/questionnaire/123456/segment-2/title-2b',
+								text: 'Answer',
+								visuallyHiddenText: 'Answer'
+							}
 						}
-					}
-				]
+					]
+				}
+			]
+		},
+		{
+			name: 'Section 3',
+			segment: 'segment-3',
+			getStatus: () => {
+				return SECTION_STATUS.NOT_STARTED;
 			},
-			{
-				title: 'Title 3b',
-				question: 'Really?',
-				taskList: true,
-				fieldName: 'title-3b',
-				shouldDisplay: () => true,
-				formatAnswerForSummary: () => [
-					{
-						key: 'Title 3b',
-						value: mockAnswer,
-						action: {
-							href: '/manage-appeals/questionnaire/123456/segment-3/title-3b',
-							text: 'Answer',
-							visuallyHiddenText: 'Answer'
+			isComplete: mock.fn(),
+			questions: [
+				{
+					title: 'Title 3a',
+					question: 'When?',
+					taskList: false,
+					fieldName: 'title-3a',
+					shouldDisplay: () => true,
+					formatAnswerForSummary: () => [
+						{
+							key: 'Title 3a',
+							value: mockAnswer,
+							action: {
+								href: '/manage-appeals/questionnaire/123456/segment-3/title-3a',
+								text: 'Answer',
+								visuallyHiddenText: 'Answer'
+							}
 						}
-					}
-				]
-			}
-		]
-	}
-];
-
-const journeyParams = {
-	sections,
-	journeyId: 'TEST',
-	referenceId: 'REF',
-	taskListUrl: 'task-list',
-	makeBaseUrl: () => `${mockBaseUrl}/${mockRef}`,
-	journeyTemplate: mockTemplateUrl,
-	taskListTemplate: mockListingPath,
-	journeyTitle: mockJourneyTitle
-};
+					]
+				},
+				{
+					title: 'Title 3b',
+					question: 'Really?',
+					taskList: true,
+					fieldName: 'title-3b',
+					shouldDisplay: () => true,
+					formatAnswerForSummary: () => [
+						{
+							key: 'Title 3b',
+							value: mockAnswer,
+							action: {
+								href: '/manage-appeals/questionnaire/123456/segment-3/title-3b',
+								text: 'Answer',
+								visuallyHiddenText: 'Answer'
+							}
+						}
+					]
+				}
+			]
+		}
+	];
+
+	const journeyParams = {
+		sections,
+		journeyId: 'TEST',
+		referenceId: 'REF',
+		taskListUrl: 'task-list',
+		makeBaseUrl: () => `${mockBaseUrl}/${mockRef}`,
+		journeyTemplate: mockTemplateUrl,
+		taskListTemplate: mockListingPath,
+		journeyTitle: mockJourneyTitle
+	};
 
-const mockResponse = {
-	referenceId: mockRef,
-	answers: {
-		'title-1a': 'yes',
-		'title-2a': null,
-		'title-2b': undefined
-	}
-};
+	const mockResponse = {
+		referenceId: mockRef,
+		answers: {
+			'title-1a': 'yes',
+			'title-2a': null,
+			'title-2b': undefined
+		}
+	};
+	const res = mockRes();
+	const req = mockReq(null);
+
+	const mockJourney = new Journey({ response: mockResponse, ...journeyParams });
+
+	res.locals.journeyResponse = {};
+	res.locals.journey = mockJourney;
+
+	const sampleQuestionObj = {
+		fieldName: 'sampleFieldName',
+		renderAction: mock.fn(),
+		getDataToSave: mock.fn(),
+		checkForValidationErrors: mock.fn(),
+		checkForSavingErrors: mock.fn(),
+		toViewModel: mock.fn(),
+		prepQuestionForRendering: mock.fn(),
+		formatAnswerForSummary: mock.fn(() => [mockAnswer]),
+		viewFolder: 'sampleType'
+	};
 
-let mockJourney;
-let mockSummaryListData;
-
-const sampleQuestionObj = {
-	fieldName: 'sampleFieldName',
-	renderAction: mock.fn(),
-	getDataToSave: mock.fn(),
-	checkForValidationErrors: mock.fn(),
-	checkForSavingErrors: mock.fn(),
-	toViewModel: mock.fn(),
-	prepQuestionForRendering: mock.fn(),
-	formatAnswerForSummary: mock.fn(() => [mockAnswer]),
-	viewFolder: 'sampleType'
-};
+	const mockSection = {
+		name: '123',
+		segment: 'test'
+	};
 
-const mockSection = {
-	name: '123',
-	segment: 'test'
-};
+	return { req, res, mockJourney, sampleQuestionObj, mockSection, journeyParams };
+}
 
 describe('dynamic-form/controller', () => {
-	let req;
-	beforeEach(() => {
-		res.locals.journeyResponse = {};
-		mockJourney = new Journey({ response: mockResponse, ...journeyParams });
-		res.locals.journey = mockJourney;
-		mockJourney.sections[0].questions[0].formatAnswerForSummary.mock.mockImplementation(() => [
-			{
-				key: 'Title 1a',
-				value: mockAnswer,
-				action: {
-					href: '/manage-appeals/questionnaire/123456/segment-1/title-1a',
-					text: 'Answer',
-					visuallyHiddenText: 'Answer'
-				}
-			}
-		]);
-		mockJourney.sections[2].isComplete = mock.fn(() => false);
-
-		mockSummaryListData = _getmockSummaryListData(mockJourney);
-		req = mockReq(null);
-	});
-
 	describe('list', () => {
 		it('should render the view correctly', async () => {
-			res.locals.journeyResponse.referenceId = mockRef;
+			const { req, res, mockJourney } = testSetup();
 			const appeal = { a: 1, caseReference: 2 };
 
 			const pageCaption = `Appeal ${appeal.caseReference}`;
@@ -228,7 +224,7 @@ describe('dynamic-form/controller', () => {
 				'components/task-list/index',
 				{
 					appeal,
-					summaryListData: mockSummaryListData,
+					summaryListData: _getmockSummaryListData(mockJourney),
 					layoutTemplate: mockListingPath,
 					journeyComplete: false,
 					pageCaption: pageCaption,
@@ -237,8 +233,8 @@ describe('dynamic-form/controller', () => {
 			]);
 		});
 		it('support array of actions', async () => {
+			const { req, res, mockJourney } = testSetup();
 			const mockFn = res.render.mock;
-			mockFn.resetCalls();
 			mockJourney.sections[0].questions[0].formatAnswerForSummary.mock.mockImplementation(() => [
 				{
 					key: 'Title 1a',
@@ -257,13 +253,14 @@ describe('dynamic-form/controller', () => {
 					]
 				}
 			]);
-			res.locals.journeyResponse.referenceId = mockRef;
+
 			const appeal = { a: 1, caseReference: 2 };
 
 			const pageCaption = `Appeal ${appeal.caseReference}`;
 			await list(req, res, pageCaption, { appeal });
 
-			mockSummaryListData.sections[0].list.rows[0].actions.items.push({
+			const expectSummaryList = _getmockSummaryListData(mockJourney);
+			expectSummaryList.sections[0].list.rows[0].actions.items.push({
 				href: '/manage-appeals/questionnaire/123456/segment-1/title-1a/edit',
 				text: 'Edit',
 				visuallyHiddenText: 'Edit'
@@ -274,7 +271,7 @@ describe('dynamic-form/controller', () => {
 				'components/task-list/index',
 				{
 					appeal,
-					summaryListData: mockSummaryListData,
+					summaryListData: expectSummaryList,
 					layoutTemplate: mockListingPath,
 					journeyComplete: false,
 					pageCaption: pageCaption,
@@ -284,9 +281,8 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should format answer summary including conditional answer', async () => {
+			const { req, res, mockJourney } = testSetup();
 			const mockFn = mockJourney.sections[0].questions[0].formatAnswerForSummary.mock;
-			mockFn.resetCalls();
-			res.locals.journeyResponse.referenceId = mockRef;
 
 			await list(req, res);
 
@@ -300,8 +296,8 @@ describe('dynamic-form/controller', () => {
 			assert.strictEqual(args[2], expectedAnswer.value);
 		});
 		it('should format an undefined action as undefined', async () => {
+			const { req, res, mockJourney } = testSetup();
 			const mockFn = res.render.mock;
-			mockFn.resetCalls();
 			mockJourney.sections[0].questions[0].formatAnswerForSummary.mock.mockImplementation(() => [
 				{
 					key: 'Title 1a',
@@ -309,7 +305,7 @@ describe('dynamic-form/controller', () => {
 					action: undefined
 				}
 			]);
-			res.locals.journeyResponse.referenceId = mockRef;
+
 			const appeal = { a: 1, caseReference: 2 };
 
 			const pageCaption = `Appeal ${appeal.caseReference}`;
@@ -321,8 +317,8 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should format a single action object as an array in the actions property', async () => {
+			const { req, res, mockJourney } = testSetup();
 			const mockFn = res.render.mock;
-			mockFn.resetCalls();
 			mockJourney.sections[0].questions[0].formatAnswerForSummary.mock.mockImplementation(() => [
 				{
 					key: 'Title 1a',
@@ -334,7 +330,6 @@ describe('dynamic-form/controller', () => {
 					}
 				}
 			]);
-			res.locals.journeyResponse.referenceId = mockRef;
 
 			await list(req, res);
 
@@ -353,6 +348,7 @@ describe('dynamic-form/controller', () => {
 
 	describe('question', () => {
 		it('should redirect if question is not found', async () => {
+			const { req, res, mockJourney } = testSetup();
 			mockJourney.getQuestionByParams = mock.fn();
 			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => null);
 
@@ -362,6 +358,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should use custom action if renderAction is defined', async () => {
+			const { req, res, mockJourney, sampleQuestionObj } = testSetup();
 			mockJourney.getSection = mock.fn();
 			mockJourney.getSection.mock.mockImplementationOnce(() => {
 				return {};
@@ -377,8 +374,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should render the question template', async () => {
-			sampleQuestionObj.renderAction.mock.resetCalls();
-			sampleQuestionObj.toViewModel.mock.resetCalls();
+			const { req, res, mockJourney, sampleQuestionObj, mockSection } = testSetup();
 			req.params.referenceId = mockRef;
 			const mockAnswer = 'sampleAnswer';
 			const mockBackLink = 'back';
@@ -404,7 +400,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should redirect to tasklist when manage list action is remove and journey response has no answers', async () => {
-			res.redirect.mock.resetCalls();
+			const { req, res, mockJourney, sampleQuestionObj, mockSection } = testSetup();
 
 			sampleQuestionObj.isManageListQuestion = true;
 			sampleQuestionObj.renderConfirmationAction = mock.fn();
@@ -433,7 +429,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should redirect to tasklist when manage list action is remove and the manage list answer is undefined', async () => {
-			res.redirect.mock.resetCalls();
+			const { req, res, mockJourney, sampleQuestionObj, mockSection } = testSetup();
 
 			sampleQuestionObj.isManageListQuestion = true;
 			sampleQuestionObj.renderConfirmationAction = mock.fn();
@@ -464,7 +460,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should redirect to tasklist when manage list action is remove and the manage list answer is not an array', async () => {
-			res.redirect.mock.resetCalls();
+			const { req, res, mockJourney, sampleQuestionObj, mockSection } = testSetup();
 
 			sampleQuestionObj.isManageListQuestion = true;
 			sampleQuestionObj.renderConfirmationAction = mock.fn();
@@ -495,7 +491,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should render the confirmation page when manage list action is remove and the question has a renderConfirmationAction function', async () => {
-			res.redirect.mock.resetCalls();
+			const { req, res, mockJourney, sampleQuestionObj, mockSection } = testSetup();
 
 			sampleQuestionObj.isManageListQuestion = true;
 
@@ -529,6 +525,7 @@ describe('dynamic-form/controller', () => {
 
 	describe('save', () => {
 		it('should use saveData', async () => {
+			const { req, res, mockJourney, sampleQuestionObj, journeyParams } = testSetup();
 			const journeyId = 'has-questionnaire';
 
 			req.params = {
@@ -573,12 +570,13 @@ describe('dynamic-form/controller', () => {
 			for (const mockFn of mocks) {
 				assert.strictEqual(mockFn.callCount(), 1);
 				assert.deepStrictEqual(mockFn.calls[0].arguments[0], req);
-				assert.deepStrictEqual(mockFn.calls[0].arguments[1], sections[0]);
+				assert.deepStrictEqual(mockFn.calls[0].arguments[1], mockJourney.sections[0]);
 				assert.deepStrictEqual(mockFn.calls[0].arguments[2], mockJourney);
 			}
 		});
 
 		it('should handle error', async () => {
+			const { req, res, mockJourney, sampleQuestionObj, journeyParams } = testSetup();
 			const journeyId = 'has-questionnaire';
 			const expectedViewModel = { a: 1 };
 			const sampleQuestionObjWithActions = {
@@ -639,6 +637,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should handle validation errors', async () => {
+			const { req, res, mockJourney, sampleQuestionObj, journeyParams } = testSetup();
 			const expectedErrors = {
 				errorViewModel: 'mocked-validation-error'
 			};
@@ -671,7 +670,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should handle saving', async () => {
-			res.redirect.mock.resetCalls();
+			const { req, res, mockJourney, sampleQuestionObj, journeyParams } = testSetup();
 			const journeyId = 'has-questionnaire';
 			const expectedUrl = 'redirect-url';
 			const sampleQuestionObjWithActions = {
@@ -713,7 +712,7 @@ describe('dynamic-form/controller', () => {
 		});
 
 		it('should redirect to task list if configured', async () => {
-			res.redirect.mock.resetCalls();
+			const { req, res, mockJourney, sampleQuestionObj, journeyParams } = testSetup();
 			const journeyId = 'has-questionnaire';
 			const expectedUrl = 'redirect-url';
 			const sampleQuestionObjWithActions = {

package/src/questions/options-question.js

@@ -147,7 +147,7 @@ export class OptionsQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {import('../journey/journey-response.js').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {import('../journey/journey-response.js').JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise<{ answers: Record<string, unknown> }>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/validator/email-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"email-validator.d.ts","sourceRoot":"","sources":["email-validator.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH;IACC;;;;;OAKG;IACH,mDAJG;QAAwC,OAAO;QACvB,YAAY;QACZ,SAAS;KACnC,EAcA;IAVA;;;;;;;;;;;;;;;;;;;;;;;;;MAMC;IAGD,8BAA0B;IAG3B,wEAIC;CACD;;;;;;;;;;;;;;;;;;;;;;;;0BAtCyB,qBAAqB"}
+{"version":3,"file":"email-validator.d.ts","sourceRoot":"","sources":["email-validator.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH;IACC;;;;;OAKG;IACH,mDAJG;QAAwC,OAAO;QACvB,YAAY;QACZ,SAAS;KACnC,EAkBA;IAXA;;;;;;;;;;;;;;;;;;;;;;;;;MAMC;IAID,8BAA0B;IAG3B,wEAIC;CACD;;;;;;;;;;;;;;;;;;;;;;;;0BA1CyB,qBAAqB"}

package/src/validator/email-validator.js

@@ -21,6 +21,9 @@ export class EmailValidator extends BaseValidator {
 	constructor({ options = {}, errorMessage, fieldName } = {}) {
 		super();
 
+		// snake_case to match the express-validator options for isEmail
+		// https://express-validator.github.io/docs/api/validation-chain#isemail
+		/* eslint-disable camelcase */
 		this.options = {
 			allow_display_name: options.allowDisplayName || false,
 			require_tld: options.requireTld !== false, // Default to true
@@ -28,6 +31,7 @@ export class EmailValidator extends BaseValidator {
 			allow_ip_domain: options.allowIpDomain || false,
 			...options
 		};
+		/* eslint-enable camelcase */
 
 		this.errorMessage = errorMessage || 'Enter an email address in the correct format, like name@example.com';
 		this.fieldName = fieldName;

package/typedefs/question-props.d.ts

@@ -68,7 +68,7 @@ export type SelectableOption = {
 	attributes?: Record<string, string>;
 	behaviour?: 'exclusive';
 	conditional?: {
-		question: string;
+		question?: string;
 		type: string;
 		fieldName: string;
 		inputClasses?: string;
@@ -261,6 +261,8 @@ export type SingleLineInputQuestionParams = CommonQuestionParams & {
 	inputAttributes?: Record<string, string>; // HTML attributes to add to the input
 	label?: string; // if defined this will show as a label for the input and the question will just be a standard h1
 	classes?: string; // HTML classes to add to the input
+	prefix?: Affix;
+	suffix?: Affix;
 };
 
 type SingleLineInputQuestionProps = SingleLineInputQuestionParams & {