@planning-inspectorate/dynamic-forms 2.3.0 → 3.0.0

package/package.json

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

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 }}
+                                    {% 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;
+			}
+		);
+	});
+});

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

@@ -0,0 +1,147 @@
+import { Question } from '../../questions/question.js';
+import { Uuid } from '#src/lib/uuid.js';
+import escape from 'escape-html';
+import { nunjucksEnv } from '#src/components/utils/nunjucks.js';
+
+/**
+ * @typedef {Object} ManageListQuestionParameters
+ * @property {string} titleSingular - the single name of the list item, e.g. "Holiday activity"
+ * @property {boolean} [showManageListQuestions] - whether to show the question titles as well as answers on the manage list summary page
+ * @property {boolean} [showAnswersInSummary] - whether to show the answers on the main check-your-answers page (or just a count)
+ */
+
+export default class ManageListQuestion extends Question {
+	/** @type {import('../../section.js').Section} */
+	#section;
+	/** @type {boolean} */
+	#showAnswersInSummary;
+
+	/**
+	 * @param {import('#question-types').QuestionParameters & ManageListQuestionParameters} params
+	 */
+	constructor(params) {
+		super({
+			...params,
+			pageTitle: params.title,
+			viewFolder: 'manage-list',
+			viewData: {
+				...params.viewData,
+				titleSingular: params.titleSingular,
+				showManageListQuestions: params.showManageListQuestions
+			}
+		});
+		this.#showAnswersInSummary = params.showAnswersInSummary || false;
+	}
+
+	/**
+	 * Is this question a manage list question?
+	 *
+	 * Used by controller and other logic.
+	 * Added as a getter so custom components can also be a manage list question.
+	 *
+	 * @returns {boolean}
+	 */
+	get isManageListQuestion() {
+		return true;
+	}
+
+	prepQuestionForRendering(section, journey, customViewData, payload) {
+		const viewModel = super.prepQuestionForRendering(section, journey, customViewData, payload);
+		viewModel.question.addAnotherLink = this.#addAnotherLink;
+		viewModel.question.firstQuestionUrl = this.#firstQuestionUrl;
+		viewModel.question.valueSummary = [];
+		if (viewModel.question.value && Array.isArray(viewModel.question.value)) {
+			viewModel.question.valueSummary = viewModel.question.value.map((v) => {
+				return {
+					id: v.id,
+					value: this.#formatItemAnswers(v)
+				};
+			});
+		}
+		return viewModel;
+	}
+
+	/**
+	 * Format the answers to each of the manage list questions
+	 * @param {{id: string, [k: string]: string}} answer
+	 * @returns {{question: string, answer: string}[]}
+	 */
+	#formatItemAnswers(answer) {
+		if (this.section.questions.length === 0) {
+			return [];
+		}
+		const mockJourney = {
+			getCurrentQuestionUrl() {}
+		};
+		return this.section.questions.map((q) => {
+			const formatted = q
+				.formatAnswerForSummary('', mockJourney, answer[q.fieldName])
+				.map((a) => escape(a.value))
+				.join(', ');
+
+			return {
+				question: q.title,
+				answer: formatted
+			};
+		});
+	}
+
+	formatAnswerForSummary(sectionSegment, journey, answer) {
+		let formattedAnswer = this.notStartedText;
+		if (answer && Array.isArray(answer)) {
+			if (this.#showAnswersInSummary) {
+				const answers = answer.map((a) => this.#formatItemAnswers(a));
+				formattedAnswer = nunjucksEnv().render('components/manage-list/answer-summary-list.njk', { answers });
+			} else if (answer.length > 0) {
+				formattedAnswer = `${answer.length} ${this.title}`;
+			}
+		}
+		const action = this.getAction(sectionSegment, journey, answer);
+		const key = this.title ?? this.question;
+		return [
+			{
+				key: key,
+				value: formattedAnswer,
+				action: action
+			}
+		];
+	}
+
+	/**
+	 * Create an 'add another' link,
+	 * to the first question in the manage list section
+	 *
+	 * @returns {string}
+	 */
+	get #addAnotherLink() {
+		if (this.section.questions.length === 0) {
+			return '';
+		}
+		const nextItemId = Uuid.randomUUID();
+		const firstQuestion = this.#firstQuestionUrl;
+		return `add/${nextItemId}/${firstQuestion}`;
+	}
+
+	/**
+	 * First question URL
+	 *
+	 * @returns {string}
+	 */
+	get #firstQuestionUrl() {
+		if (this.section.questions.length === 0) {
+			return '';
+		}
+		return this.section.questions[0].url;
+	}
+
+	get section() {
+		if (!this.#section) {
+			throw new Error('manage list section not set');
+		}
+		return this.#section;
+	}
+
+	set section(section) {
+		this.#section = section;
+	}
+}

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

@@ -0,0 +1,139 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+import ManageListQuestion from '#src/components/manage-list/question.js';
+import { ManageListSection } from '#src/components/manage-list/manage-list-section.js';
+import { mockJourney } from '#test/mock/journey.js';
+import { mockRandomUUID } from '#src/lib/uuid.test.js';
+import { configureNunjucksTestEnv } from '#test/utils/nunjucks.js';
+import path from 'path';
+import { snapshotsDir } from '#test/utils/utils.js';
+
+describe('components/manage-list/question', () => {
+	const TITLE = 'Things';
+	const QUESTION = 'Manage list';
+	const DESCRIPTION = 'A list of things';
+	const FIELDNAME = 'manageListTest';
+	const newQuestion = (options = {}) => {
+		return new ManageListQuestion({
+			title: TITLE,
+			question: QUESTION,
+			description: DESCRIPTION,
+			fieldName: FIELDNAME,
+			titleSingular: 'Thing',
+			...options
+		});
+	};
+	it('should create', () => {
+		const q = newQuestion();
+		assert.strictEqual(q.title, TITLE);
+		assert.strictEqual(q.question, QUESTION);
+		assert.strictEqual(q.description, DESCRIPTION);
+		assert.strictEqual(q.fieldName, FIELDNAME);
+		assert.strictEqual(q.viewFolder, 'manage-list');
+		assert.strictEqual(q.isManageListQuestion, true);
+	});
+
+	it('should populate addAnotherLink & firstQuestionUrl', (ctx) => {
+		const q = newQuestion();
+		mockRandomUUID(ctx);
+		q.section = new ManageListSection().addQuestion({ url: 'first-question' });
+		const viewModel = q.prepQuestionForRendering({}, mockJourney());
+		// add/<v4-guid>/<question-url>
+		assert.match(viewModel?.question?.addAnotherLink, /^add\/00000000-0000-0000-0000-000000000000\/first-question/);
+		assert.strictEqual(viewModel?.question?.firstQuestionUrl, 'first-question');
+	});
+
+	const questionWithManageQuestions = (ctx, options) => {
+		const q = newQuestion(options);
+		const innerQ1 = {
+			url: 'first-question',
+			title: 'Q 1',
+			formatAnswerForSummary() {
+				return [{ value: 'mock answer' }];
+			}
+		};
+		const innerQ2 = {
+			url: 'second-question',
+			title: 'Q 2',
+			formatAnswerForSummary() {
+				return [{ value: 'mock answer 2' }];
+			}
+		};
+		mockRandomUUID(ctx);
+		const journey = mockJourney();
+		journey.response.answers = {
+			[FIELDNAME]: [{ id: 'id-1' }, { id: 'id-2' }, { id: 'id-3' }]
+		};
+		q.section = new ManageListSection().addQuestion(innerQ1).addQuestion(innerQ2);
+		return { q, journey };
+	};
+
+	it('should format answers to questions in the section', (ctx) => {
+		const { q, journey } = questionWithManageQuestions(ctx);
+		const viewModel = q.prepQuestionForRendering({}, journey);
+		assert.ok(Array.isArray(viewModel?.question?.valueSummary));
+		assert.strictEqual(viewModel?.question?.valueSummary.length, 3);
+		assert.deepStrictEqual(viewModel?.question?.valueSummary[0], {
+			id: 'id-1',
+			value: [
+				{ question: 'Q 1', answer: 'mock answer' },
+				{ question: 'Q 2', answer: 'mock answer 2' }
+			]
+		});
+	});
+
+	it('should format list answer for summary', (ctx) => {
+		const q = newQuestion();
+		mockRandomUUID(ctx);
+		const answerForSummary = q.formatAnswerForSummary('section-1', mockJourney(), [{}, {}, {}]);
+		assert.strictEqual(answerForSummary.length, 1);
+		assert.strictEqual(answerForSummary[0].value, '3 Things');
+	});
+
+	it('should support showing all answers in the format list answer for summary', (ctx) => {
+		const { q } = questionWithManageQuestions(ctx, { showAnswersInSummary: true });
+		const answerForSummary = q.formatAnswerForSummary('section-1', mockJourney(), [{}, {}, {}]);
+		assert.strictEqual(answerForSummary.length, 1);
+		ctx.assert.fileSnapshot(
+			answerForSummary[0].value.replaceAll('\r\n', '\n'),
+			path.join(snapshotsDir(), 'manage-list-answer-summary.html'),
+			{
+				serializers: [(v) => v]
+			}
+		);
+	});
+
+	it('should render with answers', (ctx) => {
+		const { q, journey } = questionWithManageQuestions(ctx);
+		const viewModel = q.prepQuestionForRendering({}, journey);
+		const nunjucks = configureNunjucksTestEnv();
+		const res = {
+			render: mock.fn((view, data) => nunjucks.render(view + '.njk', data))
+		};
+		q.renderAction(res, viewModel);
+		assert.strictEqual(res.render.mock.callCount(), 1);
+		ctx.assert.fileSnapshot(res.render.mock.calls[0].result, path.join(snapshotsDir(), 'manage-list-render.html'), {
+			serializers: [(v) => v]
+		});
+	});
+
+	it('should render with answers & questions', (ctx) => {
+		const { q, journey } = questionWithManageQuestions(ctx, {
+			showManageListQuestions: true
+		});
+		const viewModel = q.prepQuestionForRendering({}, journey);
+		const nunjucks = configureNunjucksTestEnv();
+		const res = {
+			render: mock.fn((view, data) => nunjucks.render(view + '.njk', data))
+		};
+		q.renderAction(res, viewModel);
+		assert.strictEqual(res.render.mock.callCount(), 1);
+		ctx.assert.fileSnapshot(
+			res.render.mock.calls[0].result,
+			path.join(snapshotsDir(), 'manage-list-render-questions.html'),
+			{
+				serializers: [(v) => v]
+			}
+		);
+	});
+});

package/src/components/utils/nunjucks.js

@@ -0,0 +1,20 @@
+import path from 'path';
+import nunjucks from 'nunjucks';
+
+/**
+ * Returns a nunjucks environment configured with the `src` folder
+ * @returns {import('nunjucks').Environment}
+ */
+export function nunjucksEnv() {
+	const utilsDir = path.dirname(new URL(import.meta.url).pathname);
+	const srcDir = path.resolve(utilsDir, '..', '..');
+
+	return nunjucks.configure([srcDir], {
+		// output with dangerous characters are escaped automatically
+		autoescape: true,
+		// automatically remove trailing newlines from a block/tag
+		trimBlocks: true,
+		// automatically remove leading whitespace from a block/tag
+		lstripBlocks: true
+	});
+}