@planning-inspectorate/dynamic-forms 2.4.0 → 3.1.0

package/README.md

@@ -296,4 +296,15 @@ There are some lightweight tests in the `test` directory which sets up a basic j
 
 When adding a new question type, be sure to add an example question into `test/questions.js`, and mock answers into `test/questions.test.js#mockAnswerBody` and `test/questions.test.js#mockAnswer`. Also, the question should be added to the journey in `test/journey.js`.
 
-To update any snapshots with rendering changes (or new questions), run `node --test --test-update-snapshots`.
+To update any snapshots with rendering changes (or new questions), run `node --test --test-update-snapshots`.
+
+### Components
+
+When implement a new component, extend the base `Question` class. Common methods to override are:
+
+* `formatAnswerForSummary` - used for check-your-answers display
+* `getDataToSave` - answer data to save
+* `addCustomDataToViewModel` - customise the view model with extra data/configuration
+* `answerForViewModel` - customise the view model answer value
+
+Where possible `addCustomDataToViewModel` and `answerForViewModel` should be overridden instead of `prepQuestionForRendering`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planning-inspectorate/dynamic-forms",
-  "version": "2.4.0",
+  "version": "3.1.0",
   "description": "This package is for building GDS forms using a configuration-based approach.",
   "main": "./src/index.js",
   "type": "module",
@@ -27,7 +27,8 @@
   "imports": {
     "#question-types": "./src/questions/question-types.d.ts",
     "#src/*": "./src/*",
-    "#test/*": "./test/*"
+    "#test/*": "./test/*",
+    "#question": "./src/questions/question.js"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.0.0",

package/src/components/address/question.js

@@ -1,4 +1,4 @@
-import { Question } from '../../questions/question.js';
+import { Question } from '#question';
 
 import escape from 'escape-html';
 import { Address } from '../../lib/address.js';
@@ -40,29 +40,35 @@ export default class AddressQuestion extends Question {
 	}
 
 	/**
-	 * @param {Section} section
-	 * @param {Journey} journey
-	 * @param {Record<string, unknown>} customViewData
-	 * @returns {QuestionViewModel}
+	 * @param {Record<string, any>} answers
+	 * @returns {*|string}
 	 */
-	prepQuestionForRendering(section, journey, customViewData) {
-		const viewModel = super.prepQuestionForRendering(section, journey, customViewData);
-		const address = journey.response.answers[this.fieldName] || {};
-
-		// will only ever have 1
-		if (address) {
-			viewModel.question.value = {
-				addressLine1: address.addressLine1 || '',
-				addressLine2: address.addressLine2 || '',
-				townCity: address.townCity || '',
-				county: address.county || '',
-				postcode: address.postcode || ''
+	answerForViewModel(answers) {
+		let address = answers[this.fieldName];
+		if (!address) {
+			address = {
+				addressLine1: answers[this.fieldName + '_addressLine1'],
+				addressLine2: answers[this.fieldName + '_addressLine2'],
+				townCity: answers[this.fieldName + '_townCity'],
+				county: answers[this.fieldName + '_county'],
+				postcode: answers[this.fieldName + '_postcode']
 			};
 		}
 
-		viewModel.question.labels = this.addressLabels;
+		return {
+			addressLine1: address?.addressLine1 || '',
+			addressLine2: address?.addressLine2 || '',
+			townCity: address?.townCity || '',
+			county: address?.county || '',
+			postcode: address?.postcode || ''
+		};
+	}
 
-		return viewModel;
+	/**
+	 * @param {import('#question').QuestionViewModel} viewModel
+	 */
+	addCustomDataToViewModel(viewModel) {
+		viewModel.question.labels = this.addressLabels;
 	}
 
 	/**

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

@@ -3,7 +3,7 @@ import assert from 'node:assert';
 import AddressQuestion from './question.js';
 import { Address } from '../../lib/address.js';
 import AddressValidator from '../../validator/address-validator.js';
-import { configureNunjucksTestEnv } from '../../../test/utils/nunjucks.js';
+import { configureNunjucksTestEnv } from '#test/utils/nunjucks.js';
 
 describe('AddressQuestion', () => {
 	const TITLE = 'What is the site address?';

package/src/components/date/question.js

@@ -50,29 +50,17 @@ export default class DateQuestion extends Question {
 		return responseToSave;
 	}
 
-	/**
-	 * gets the view model for this question
-	 * @param {Section} section - the current section
-	 * @param {Journey} journey - the journey we are in
-	 * @param {Object|undefined} [customViewData] additional data to send to view
-	 * @returns {QuestionViewModel & { answer: Record<string, unknown> }}
-	 */
-	prepQuestionForRendering(section, journey, customViewData, payload) {
-		let viewModel = super.prepQuestionForRendering(section, journey, customViewData);
-
-		/** @type {Record<string, unknown>} */
-		let answer = {};
+	answerForViewModel(answers, isPayload) {
 		let day;
 		let month;
 		let year;
 
-		if (payload) {
-			day = payload[`${this.fieldName}_day`];
-			month = payload[`${this.fieldName}_month`];
-			year = payload[`${this.fieldName}_year`];
+		if (isPayload && answers) {
+			day = answers[`${this.fieldName}_day`];
+			month = answers[`${this.fieldName}_month`];
+			year = answers[`${this.fieldName}_year`];
 		} else {
-			const answerDateString = journey.response.answers[this.fieldName];
-
+			const answerDateString = answers[this.fieldName];
 			if (answerDateString && (typeof answerDateString === 'string' || answerDateString instanceof Date)) {
 				const answerDate = new Date(answerDateString);
 				day = formatDateForDisplay(answerDate, { format: 'd' });
@@ -81,13 +69,11 @@ export default class DateQuestion extends Question {
 			}
 		}
 
-		answer = {
+		return {
 			[`${this.fieldName}_day`]: day,
 			[`${this.fieldName}_month`]: month,
 			[`${this.fieldName}_year`]: year
 		};
-
-		return { ...viewModel, answer, question: { ...viewModel.question, value: answer } };
 	}
 
 	/**

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

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
 
-import { Question } from '../../questions/question.js';
+import { Question } from '#question';
 import DateQuestion from './question.js';
 
 describe('DateQuestion', () => {

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

@@ -1,5 +1,5 @@
 import { formatDateForDisplay, parseDateInput } from '../../lib/date-utils.js';
-import { Question } from '../../questions/question.js';
+import { Question } from '#question';
 import { nl2br } from '../../lib/utils.js';
 import escape from 'escape-html';
 
@@ -77,20 +77,7 @@ export default class DatePeriodQuestion extends Question {
 		return responseToSave;
 	}
 
-	/**
-	 * gets the view model for this question
-	 * @param {Section} section - the current section
-	 * @param {Journey} journey - the journey we are in
-	 * @param {Object|undefined} [customViewData] additional data to send to view
-	 * @param {Object|undefined} [payload] the current payload
-	 * @returns {QuestionViewModel & { answer: Record<string, unknown> }}
-	 */
-	prepQuestionForRendering(section, journey, customViewData, payload) {
-		let viewModel = super.prepQuestionForRendering(section, journey, customViewData);
-		viewModel.labels = this.labels;
-
-		/** @type {Record<string, unknown>} */
-		let answer;
+	answerForViewModel(answers, isPayload) {
 		let startDay;
 		let startMonth;
 		let startYear;
@@ -98,15 +85,15 @@ export default class DatePeriodQuestion extends Question {
 		let endMonth;
 		let endYear;
 
-		if (payload) {
-			startDay = payload[`${this.fieldName}_start_day`];
-			startMonth = payload[`${this.fieldName}_start_month`];
-			startYear = payload[`${this.fieldName}_start_year`];
-			endDay = payload[`${this.fieldName}_end_day`];
-			endMonth = payload[`${this.fieldName}_end_month`];
-			endYear = payload[`${this.fieldName}_end_year`];
+		if (isPayload) {
+			startDay = answers[`${this.fieldName}_start_day`];
+			startMonth = answers[`${this.fieldName}_start_month`];
+			startYear = answers[`${this.fieldName}_start_year`];
+			endDay = answers[`${this.fieldName}_end_day`];
+			endMonth = answers[`${this.fieldName}_end_month`];
+			endYear = answers[`${this.fieldName}_end_year`];
 		} else {
-			const answerPeriod = journey.response.answers[this.fieldName];
+			const answerPeriod = answers[this.fieldName];
 			if (answerPeriod && answerPeriod.start) {
 				const startDate = new Date(answerPeriod.start);
 				startDay = formatDateForDisplay(startDate, { format: 'd' });
@@ -121,7 +108,7 @@ export default class DatePeriodQuestion extends Question {
 			}
 		}
 
-		answer = {
+		return {
 			[`${this.fieldName}_start_day`]: startDay,
 			[`${this.fieldName}_start_month`]: startMonth,
 			[`${this.fieldName}_start_year`]: startYear,
@@ -129,8 +116,13 @@ export default class DatePeriodQuestion extends Question {
 			[`${this.fieldName}_end_month`]: endMonth,
 			[`${this.fieldName}_end_year`]: endYear
 		};
+	}
 
-		return { ...viewModel, answer, question: { ...viewModel.question, value: answer } };
+	/**
+	 * @param {import('#question').QuestionViewModel} viewModel
+	 */
+	addCustomDataToViewModel(viewModel) {
+		viewModel.labels = this.labels;
 	}
 
 	/**

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

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
 
-import { Question } from '../../questions/question.js';
+import { Question } from '#question';
 import DatePeriodQuestion from './question.js';
 
 describe('DatePeriodQuestion', () => {

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

@@ -52,18 +52,7 @@ export default class DateTimeQuestion extends Question {
 		return responseToSave;
 	}
 
-	/**
-	 * gets the view model for this question
-	 * @param {Section} section - the current section
-	 * @param {Journey} journey - the journey we are in
-	 * @param {Object|undefined} [customViewData] additional data to send to view
-	 * @returns {QuestionViewModel & { answer: Record<string, unknown> }}
-	 */
-	prepQuestionForRendering(section, journey, customViewData, payload) {
-		let viewModel = super.prepQuestionForRendering(section, journey, customViewData);
-
-		/** @type {Record<string, unknown>} */
-		let answer = {};
+	answerForViewModel(answers, isPayload) {
 		let day;
 		let month;
 		let year;
@@ -71,15 +60,15 @@ export default class DateTimeQuestion extends Question {
 		let minutes;
 		let period;
 
-		if (payload) {
-			day = payload[`${this.fieldName}_day`];
-			month = payload[`${this.fieldName}_month`];
-			year = payload[`${this.fieldName}_year`];
-			hour = payload[`${this.fieldName}_hour`];
-			minutes = payload[`${this.fieldName}_minutes`];
-			period = payload[`${this.fieldName}_period`];
+		if (isPayload) {
+			day = answers[`${this.fieldName}_day`];
+			month = answers[`${this.fieldName}_month`];
+			year = answers[`${this.fieldName}_year`];
+			hour = answers[`${this.fieldName}_hour`];
+			minutes = answers[`${this.fieldName}_minutes`];
+			period = answers[`${this.fieldName}_period`];
 		} else {
-			const answerDateString = journey.response.answers[this.fieldName];
+			const answerDateString = answers[this.fieldName];
 
 			if (answerDateString && (typeof answerDateString === 'string' || answerDateString instanceof Date)) {
 				const answerDate = new Date(answerDateString);
@@ -92,7 +81,7 @@ export default class DateTimeQuestion extends Question {
 			}
 		}
 
-		answer = {
+		return {
 			[`${this.fieldName}_day`]: day,
 			[`${this.fieldName}_month`]: month,
 			[`${this.fieldName}_year`]: year,
@@ -100,8 +89,6 @@ export default class DateTimeQuestion extends Question {
 			[`${this.fieldName}_minutes`]: minutes,
 			[`${this.fieldName}_period`]: period
 		};
-
-		return { ...viewModel, answer, question: { ...viewModel.question, value: answer } };
 	}
 
 	/**

package/src/components/identifier/question.js

@@ -1,4 +1,4 @@
-import { Question } from '../../questions/question.js';
+import { Question } from '#question';
 
 export default class IdentifierQuestion extends Question {
 	/** @type {string|undefined} page h1, optional, will default to use question's label */
@@ -22,13 +22,10 @@ export default class IdentifierQuestion extends Question {
 	}
 
 	/**
-	 * adds custom identifier info to view model
+	 * @param {import('#question').QuestionViewModel} viewModel
 	 */
-	prepQuestionForRendering(section, journey, customViewData, payload) {
-		let viewModel = super.prepQuestionForRendering(section, journey, customViewData);
+	addCustomDataToViewModel(viewModel) {
 		viewModel.question.inputClasses = this.inputClasses;
 		viewModel.question.label = this.label;
-		viewModel.question.value = payload ? payload[viewModel.question.fieldName] : viewModel.question.value;
-		return viewModel;
 	}
 }

package/src/components/manage-list/README.md

@@ -0,0 +1,97 @@
+# Manage list
+
+The manage list component uses a similar "add to a list" pattern found in other design systems, including:
+
+- [Ministry of Justice
+  Design System](https://design-patterns.service.justice.gov.uk/patterns/add-to-a-list/)
+- [HM Revenue & Customs
+  Design resources](https://design.tax.service.gov.uk/hmrc-design-patterns/add-to-a-list/)
+- [Home Office User-Centred Design Manual](https://design.homeoffice.gov.uk/design-system/patterns/help-users-to/add-multiple-things)
+
+Users are able to:
+ - repeat a small journey to add multiple items into a list
+ - change items in the list
+ - remove items from the list
+ - check their answers
+
+The question view is the check-your-answers page, which by default shows a summary list. The summary list has the value for the item added, and action links for editing or removing the item.
+
+## Usage
+
+To use the manage list component, configure a question for the manage list and for each question within the "add to list" journey. The questions for the manage list journey are added to a `ManageListSection` and passed to `Section.addQuestion`. For example:
+
+### 1. Set up the questions 
+
+```js
+// Define question configuration
+const questionProps = {
+  // ... other questions
+  // manage list question
+  holidayActivitiesList: {
+    type: COMPONENT_TYPES.MANAGE_LIST,
+    title: 'Holiday Activities',
+    question: 'Holiday Activities',
+    fieldName: 'holidayActivitiesList',
+    url: 'holiday-activities-list'
+  },
+  // other questions to use for each item in the list
+  holidayActivityType: {
+    type: COMPONENT_TYPES.CHECKBOX,
+    title: 'Holiday Activity Type',
+    question: 'Which type of holiday activity is it?',
+    fieldName: 'holidayActivityType',
+    url: 'holiday-activity-type',
+    options: [
+      { value: 'swimming', text: 'Swimming' },
+      { value: 'hiking', text: 'Hiking' },
+      { value: 'sightseeing', text: 'Sightseeing' }
+    ]
+  },
+  holidayActivityDate: {
+    type: COMPONENT_TYPES.DATE,
+    title: 'Holiday Activity Date',
+    question: 'On which date will you do the holiday activity?',
+    fieldName: 'holidayActivityDate',
+    url: 'holiday-activity-date'
+  }
+};
+```
+
+### 2. Set up the section within the journey
+
+You can use conditional logic as normal in the `ManageListSection`.
+
+```js
+new Section('New Holiday', 'holiday')
+  .addQuestion(questions.holidayDestination)
+  // add a manage list question like any other, but include the `ManageListSection` as well
+  .addQuestion(
+        questions.holidayActivitiesList,
+        new ManageListSection()
+            .addQuestion(questions.holidayActivityType)
+            .addQuestion(questions.holidayActivityDate)
+  )
+  .addQuestion(questions.departureDate)
+  .addQuestion(questions.holidayPeriod)
+  ```
+
+### 3. Add extra route parameters
+
+`{/:manageListAction/:manageListItemId/:manageListQuestion}` optional route parameters are added to the get and post routes for questions
+
+```js
+router.get('/:section/:question{/:manageListAction/:manageListItemId/:manageListQuestion}',
+        getJourneyResponse,
+        getJourney,
+        question
+);
+
+router.post(
+        '/:section/:question{/:manageListAction/:manageListItemId/:manageListQuestion}',
+        getJourneyResponse,
+        getJourney,
+        validate,
+        validationErrorHandler,
+        buildSave(saveDataToSession)
+);
+```

package/src/components/manage-list/answer-summary-list.njk

@@ -0,0 +1,10 @@
+<ul>
+{% for question in answers %}
+    <li>
+    {% for value in question %}
+        {{ value.answer }}{% if not loop.last %}<br>{% endif %}
+
+    {% endfor %}
+    </li>
+{% endfor %}
+</ul>

package/src/components/manage-list/index.njk

@@ -0,0 +1,61 @@
+{% extends layoutTemplate %}
+
+{% from "govuk/components/button/macro.njk" import govukButton %}
+
+{% block dynQuestionContent %}
+    <div class="govuk-grid-row">
+        <div class="govuk-grid-column-two-thirds">
+            <form action="" method="post" novalidate>
+                {% if _csrf %}<input type="hidden" name="_csrf" value="{{ _csrf }}">{% endif %}
+
+                <h1 class="govuk-heading-l">You have added {{ question.value.length }} {{ question.pageTitle }}</h1>
+
+                <dl class="govuk-summary-list">
+                    {% for item in question.valueSummary %}
+                        <div class="govuk-summary-list__row ">
+                            <dt class="govuk-summary-list__key">
+                                {{ titleSingular }} {{ loop.index }}
+                            </dt>
+                            <dt class="govuk-summary-list__value">
+                                {% for value in item.value %}
+                                    {% if showManageListQuestions %}
+                                    {{ value.question }}:<br>
+                                    {% endif %}
+                                    {{ value.answer | safe }}
+                                    {% if not loop.last %}
+                                    <br>{% if showManageListQuestions %}<br>{% endif %}
+
+                                    {% endif %}
+                                {% endfor %}
+                            </dt>
+                            <dd class="govuk-summary-list__actions">
+                                <ul class="govuk-summary-list__actions-list">
+                                    <li class="govuk-summary-list__actions-list-item">
+                                        <a class="govuk-link" href="{{ originalUrl }}/edit/{{ item.id }}/{{ question.firstQuestionUrl }}">
+                                            Change <span class="govuk-visually-hidden">{{ titleSingular }} {{ loop.index }}</span>
+                                        </a>
+                                    </li>
+                                    <li class="govuk-summary-list__actions-list-item">
+                                        <a class="govuk-link" href="{{ originalUrl }}/remove/{{ item.id }}/confirm">
+                                            Remove <span class="govuk-visually-hidden">{{ titleSingular }} {{ loop.index }}</span>
+                                        </a>
+                                    </li>
+                                </ul>
+                            </dd>
+                        </div>
+                    {% endfor %}
+                </dl>
+
+                <p class="govuk-body">
+                    <a href="{{ originalUrl }}/{{ question.addAnotherLink }}" class="govuk-link">Add another</a>
+                </p>
+
+                {{ govukButton({
+                    text: continueButtonText,
+                    type: "submit",
+                    attributes: { "data-cy":"button-save-and-continue"}
+                }) }}
+            </form>
+        </div>
+    </div>
+{% endblock %}

package/src/components/manage-list/manage-list-section.js

@@ -0,0 +1,39 @@
+import { Section } from '#src/section.js';
+
+/**
+ * Extends the Section class for extra logic around managing lists.
+ */
+export class ManageListSection extends Section {
+	constructor() {
+		super('unused', 'unused');
+	}
+
+	/**
+	 * Is this section a manage list section?
+	 *
+	 * Used by controller and other logic.
+	 *
+	 * @returns {boolean}
+	 */
+	get isManageListSection() {
+		return true;
+	}
+
+	/**
+	 * Fluent API method for adding questions
+	 * @param {import('#src/questions/question.js').Question} question
+	 * @param {import('#src/components/manage-list/manage-list-section.js').ManageListSection} [manageListSection]
+	 * @returns {Section}
+	 */
+	addQuestion(question, manageListSection) {
+		if (!question) {
+			throw new Error('question is required');
+		}
+		if (question.isManageListQuestion || Boolean(manageListSection)) {
+			throw new Error('manage list sections do not support nested manage list questions');
+		}
+		// mark that this question is within a manage list section for routing and controller logic
+		question.isInManageListSection = true;
+		return super.addQuestion(question);
+	}
+}

package/src/components/manage-list/manage-list-section.test.js

@@ -0,0 +1,52 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+import { ManageListSection } from '#src/components/manage-list/manage-list-section.js';
+import { Section } from '#src/section.js';
+
+describe('components/manage-list/manage-list-section', () => {
+	it('should extend Section', () => {
+		assert.ok(ManageListSection.prototype instanceof Section);
+	});
+	it('should implement isManageListSection', () => {
+		const mls = new ManageListSection();
+		assert.strictEqual(mls.isManageListSection, true);
+	});
+	it('should mark each question with isInManageListSection', () => {
+		const mls = new ManageListSection();
+		const mockSetter = mock.fn();
+		const q = {
+			set isInManageListSection(value) {
+				mockSetter(value);
+			}
+		};
+		mls.addQuestion(q);
+		assert.strictEqual(mockSetter.mock.callCount(), 1);
+		assert.strictEqual(mockSetter.mock.calls[0].arguments[0], true);
+	});
+	it('should not allow nested manage list questions', () => {
+		const mls = new ManageListSection();
+		const q = {
+			get isManageListQuestion() {
+				return true;
+			}
+		};
+		assert.throws(
+			() => mls.addQuestion(q),
+			(thrown) => {
+				assert.strictEqual(thrown.message, 'manage list sections do not support nested manage list questions');
+				return true;
+			}
+		);
+	});
+	it('should not allow passing nested manageListSection', () => {
+		const mls = new ManageListSection();
+		const q = {};
+		assert.throws(
+			() => mls.addQuestion(q, {}),
+			(thrown) => {
+				assert.strictEqual(thrown.message, 'manage list sections do not support nested manage list questions');
+				return true;
+			}
+		);
+	});
+});