@planning-inspectorate/dynamic-forms 2.4.0 → 3.1.0

package/src/questions/options-question.js

@@ -69,12 +69,13 @@ export default class OptionsQuestion extends Question {
 	 * @param {Journey} journey - the journey we are in
 	 * @param {Record<string, unknown>} [customViewData] additional data to send to view
 	 * @param {Record<string, unknown>} [payload]
+	 * @param {import('#src/questions/question-types.d.ts').PrepQuestionForRenderingOptions} options
 	 * @returns {QuestionViewModel}
 	 */
-	prepQuestionForRendering(section, journey, customViewData, payload) {
-		const answer = payload ? payload[this.fieldName] : journey.response.answers[this.fieldName] || '';
-
-		const viewModel = super.prepQuestionForRendering(section, journey, customViewData, payload);
+	prepQuestionForRendering(section, journey, customViewData, payload, options) {
+		const viewModel = super.prepQuestionForRendering(section, journey, customViewData, payload, options);
+		const answers = payload || this.answerObjectFromJourneyResponse(journey.response, options);
+		const answer = viewModel.question.value;
 
 		viewModel.question.options = [];
 
@@ -96,9 +97,7 @@ export default class OptionsQuestion extends Question {
 				let conditionalField = { ...optionData.conditional };
 
 				conditionalField.fieldName = getConditionalFieldName(this.fieldName, conditionalField.fieldName);
-				conditionalField.value = payload
-					? payload[conditionalField.fieldName]
-					: journey.response.answers[conditionalField.fieldName] || '';
+				conditionalField.value = answers[conditionalField.fieldName] || '';
 
 				optionData.conditional = {
 					html: nunjucks.render(`./components/conditional/${conditionalField.type}.njk`, {

package/src/questions/question-props.d.ts

@@ -16,7 +16,8 @@ type QuestionTypes =
 	| 'multi-field-input'
 	| 'number'
 	| 'site-address'
-	| 'unit-option';
+	| 'unit-option'
+	| 'manage-list';
 
 interface CommonQuestionProps {
 	type: QuestionTypes;

package/src/questions/question-types.d.ts

@@ -1,5 +1,7 @@
 import BaseValidator from '../validator/base-validator';
 import { JourneyResponse } from '../journey/journey-response';
+import { RouteParams } from '#src/journey/journey-types.d.ts';
+import ManageListQuestion from '#src/components/manage-list/question.js';
 
 export interface QuestionParameters {
 	title: string;
@@ -27,3 +29,27 @@ export interface ActionLink {
 	text: string;
 	href: string;
 }
+
+export interface QuestionViewModel {
+	question: {
+		value: string | number | Record<string, any>;
+		question: string;
+		fieldName: string;
+		pageTitle: string;
+		description?: string;
+		html?: string;
+	};
+	layoutTemplate: string;
+	pageCaption: string;
+	continueButtonText: string;
+	backLink: string;
+	showBackToListLink: string;
+	listLink: string;
+	journeyTitle: string;
+	[k: string]: any;
+}
+
+export interface PrepQuestionForRenderingOptions {
+	params: RouteParams;
+	manageListQuestion?: ManageListQuestion;
+}

package/src/questions/question.js

@@ -25,12 +25,11 @@ import MultiFieldInputValidator from '../validator/multi-field-input-validator.j
  */
 
 /**
- * @typedef {Object} QuestionViewModel
+ * @typedef {Record<string, any>} QuestionViewModel
  * @property {PreppedQuestion} question
  * @property {string} layoutTemplate
  * @property {string} pageCaption
  * @property {string} [continueButtonText]
- * @property {Array.<string>} navigation
  * @property {string} backLink
  * @property {boolean} showBackToListLink
  * @property {string} listLink
@@ -91,6 +90,7 @@ export class Question {
 		title: '',
 		text: ''
 	};
+	#isInManageListSection = false;
 
 	/**
 	 * @param {import('#question-types').QuestionParameters} params
@@ -150,19 +150,72 @@ export class Question {
 		});
 	}
 
+	/**
+	 * Is this question a manage list question?
+	 * Implemented as a getter so manage list question implementations can override it,
+	 * but it cannot be changed at runtime.
+	 *
+	 * @returns {boolean}
+	 */
+	get isManageListQuestion() {
+		return false;
+	}
+
+	/**
+	 * Is this question added to a ManageListSection?
+	 *
+	 * @returns {boolean}
+	 */
+	get isInManageListSection() {
+		return this.#isInManageListSection;
+	}
+
+	set isInManageListSection(value) {
+		if (!value) {
+			throw new Error('Question isInManageListSection is false by default');
+		}
+		this.#isInManageListSection = value;
+	}
+
 	/**
 	 * gets the view model for this question
+	 *
+	 * Wraps prepQuestionForRendering to add the back link - which requires more parameters
+	 * that prepQuestionForRendering doesn't need
+	 *
+	 * @param {Object} options
+	 * @param {import('#src/journey/journey-types.d.ts').RouteParams} options.params
+	 * @param {import('#src/components/manage-list/question.js')} [options.manageListQuestion]
+	 * @param {Section} options.section - the current section
+	 * @param {Journey} options.journey - the journey we are in
+	 * @param {Record<string, unknown>} [options.customViewData] additional data to send to view
+	 * @param {unknown} [options.payload]
+	 * @returns {QuestionViewModel}
+	 */
+	toViewModel({ params, manageListQuestion, section, journey, customViewData, payload }) {
+		const viewModel = this.prepQuestionForRendering(section, journey, customViewData, payload, {
+			params,
+			manageListQuestion
+		});
+		viewModel.backLink = journey.getBackLink({ params, manageListQuestion });
+		return viewModel;
+	}
+
+	/**
+	 * gets the base view model for this question
+	 *
 	 * @param {Section} section - the current section
 	 * @param {Journey} journey - the journey we are in
 	 * @param {Record<string, unknown>} [customViewData] additional data to send to view
 	 * @param {unknown} [payload]
+	 * @param {import('./question-types.d.ts').PrepQuestionForRenderingOptions} [options] - required to support manage list question
 	 * @returns {QuestionViewModel}
 	 */
-	prepQuestionForRendering(section, journey, customViewData, payload) {
-		const answer = journey.response.answers[this.fieldName] || '';
-		const backLink = journey.getBackLink(section.segment, this.fieldName);
+	prepQuestionForRendering(section, journey, customViewData, payload, options) {
+		const answers = payload || this.answerObjectFromJourneyResponse(journey.response, options);
+		const answer = this.answerForViewModel(answers, Boolean(payload));
 
-		return {
+		const viewModel = {
 			question: {
 				value: answer,
 				question: this.question,
@@ -179,8 +232,6 @@ export class Question {
 			layoutTemplate: journey.journeyTemplate,
 			pageCaption: section?.name,
 
-			navigation: ['', backLink],
-			backLink,
 			showBackToListLink: this.showBackToListLink,
 			listLink: journey.taskListUrl,
 			journeyTitle: journey.journeyTitle,
@@ -191,6 +242,56 @@ export class Question {
 			...customViewData,
 			...this.viewData
 		};
+		this.addCustomDataToViewModel(viewModel);
+		return viewModel;
+	}
+
+	/**
+	 * The answer to this question for use in the viewModel
+	 *
+	 * Question implementations can override this for more complex answer types
+	 *
+	 * @param {Record<string, any>} answers - collection of answers to pull the answer from, may be from the response or the request/payload
+	 * @param {Boolean} isPayload - whether the answers object is from the request/payload
+	 * @returns {*|string}
+	 */ // eslint-disable-next-line no-unused-vars
+	answerForViewModel(answers, isPayload) {
+		return answers[this.fieldName] || '';
+	}
+
+	/**
+	 * Question implementations can override this to add configuration or other values to the view model
+	 *
+	 * If possible override this method instead of prepQuestionForRendering for simple changes to the view model
+	 *
+	 * @param {QuestionViewModel} viewModel
+	 */ // eslint-disable-next-line no-unused-vars
+	addCustomDataToViewModel(viewModel) {}
+
+	/**
+	 * Get the answers object from the journey response, which may be nested in an array for manage list questions
+	 *
+	 * @param {JourneyResponse} response
+	 * @param {import('./question-types.d.ts').PrepQuestionForRenderingOptions} [options]
+	 * @returns {Record<string, any>}
+	 */
+	answerObjectFromJourneyResponse(response, { params, manageListQuestion } = {}) {
+		if (this.isInManageListSection) {
+			if (!params?.manageListItemId) {
+				throw new Error('no list item id for manage list question');
+			}
+			if (!manageListQuestion) {
+				throw new Error('no manageListQuestion for manage list question');
+			}
+			// if this is a manage list question, the response is within the 'parent' manage list answers array
+			const answers = response.answers[manageListQuestion.fieldName];
+			if (!Array.isArray(answers)) {
+				return {};
+			}
+			const itemId = params.manageListItemId;
+			return answers.find((a) => a.id === itemId) || {};
+		}
+		return response.answers;
 	}
 
 	/**
@@ -212,23 +313,26 @@ export class Question {
 	 * check for validation errors
 	 * @param {import('express').Request} req
 	 * @param {Journey} journey
-	 * @param {Section} sectionObj
+	 * @param {Section} section
+	 * @param {import('#src/components/manage-list/question.js')} [manageListQuestion]
 	 * @returns {QuestionViewModel|undefined} returns the view model for displaying the error or undefined if there are no errors
 	 */
-	checkForValidationErrors(req, sectionObj, journey) {
+	checkForValidationErrors(req, section, journey, manageListQuestion) {
 		const { body = {} } = req;
 		const { errors = {}, errorSummary = [] } = body;
 
 		if (Object.keys(errors).length > 0) {
-			return this.prepQuestionForRendering(
-				sectionObj,
+			return this.toViewModel({
+				params: req.params,
+				section,
 				journey,
-				{
+				customViewData: {
 					errors,
 					errorSummary
 				},
-				body
-			);
+				payload: body,
+				manageListQuestion
+			});
 		}
 	}
 

package/src/questions/question.test.js

@@ -1,7 +1,7 @@
 import { describe, it, mock } from 'node:test';
 import assert from 'node:assert';
-import { Question } from './question.js';
-import { mockRes } from '../../test/utils/utils.js';
+import { Question } from '#question';
+import { mockRes } from '#test/utils/utils.js';
 
 const res = mockRes();
 
@@ -63,6 +63,7 @@ describe('./src/dynamic-forms/question.js', () => {
 			assert.strictEqual(question.validators, VALIDATORS);
 			assert.strictEqual(question.html, HTML);
 			assert.strictEqual(question.hint, HINT);
+			assert.strictEqual(question.isManageListQuestion, false);
 		});
 		it('should support viewData field', () => {
 			const question = getTestQuestion({ viewData: { test: 'test' } });
@@ -110,6 +111,30 @@ describe('./src/dynamic-forms/question.js', () => {
 		});
 	});
 
+	describe('isInManageListSection', () => {
+		it('should default to false', () => {
+			const question = getTestQuestion();
+			assert.strictEqual(question.isInManageListSection, false);
+		});
+		it('should support setting isInManageListSection', () => {
+			const question = getTestQuestion();
+			assert.strictEqual(question.isInManageListSection, false);
+			question.isInManageListSection = true;
+			assert.strictEqual(question.isInManageListSection, true);
+		});
+		it('should not support setting isInManageListSection false', () => {
+			const question = getTestQuestion();
+			assert.strictEqual(question.isInManageListSection, false);
+			assert.throws(
+				() => (question.isInManageListSection = false),
+				(error) => {
+					assert.strictEqual(error.message, 'Question isInManageListSection is false by default');
+					return true;
+				}
+			);
+		});
+	});
+
 	describe('prepQuestionForRendering', () => {
 		it('should prepQuestionForRendering', () => {
 			const question = getTestQuestion();
@@ -150,8 +175,6 @@ describe('./src/dynamic-forms/question.js', () => {
 			assert.deepStrictEqual(result.answer, journey.response.answers[question.fieldName]);
 			assert.deepStrictEqual(result.layoutTemplate, journey.journeyTemplate);
 			assert.deepStrictEqual(result.pageCaption, section.name);
-			assert.deepStrictEqual(result.navigation, ['', 'back']);
-			assert.deepStrictEqual(result.backLink, 'back');
 			assert.deepStrictEqual(result.showBackToListLink, question.showBackToListLink);
 			assert.deepStrictEqual(result.listLink, journey.taskListUrl);
 			assert.deepStrictEqual(result.journeyTitle, journey.journeyTitle);
@@ -185,6 +208,76 @@ describe('./src/dynamic-forms/question.js', () => {
 		});
 	});
 
+	describe('answerObjectFromJourney', () => {
+		it('should return journey response for regular questions', () => {
+			const question = getTestQuestion();
+			const answers = { myField: 'my-value' };
+			const journeyResponse = {
+				answers
+			};
+			const got = question.answerObjectFromJourneyResponse(journeyResponse);
+			assert.strictEqual(got, answers);
+		});
+		it('should return the manage list item object for manage list questions', () => {
+			const question = getTestQuestion();
+			question.isInManageListSection = true;
+			const manageListQuestion = {
+				fieldName: 'manageListQuestion'
+			};
+			const answers = {
+				id: '1',
+				myField: 'my-value'
+			};
+			const journeyResponse = {
+				answers: {
+					manageListQuestion: [answers]
+				}
+			};
+			const params = { manageListItemId: '1' };
+			const got = question.answerObjectFromJourneyResponse(journeyResponse, { params, manageListQuestion });
+			assert.strictEqual(got, answers);
+		});
+
+		it('should fallback to {} if manage list item id not found', () => {
+			const question = getTestQuestion();
+			question.isInManageListSection = true;
+			const manageListQuestion = {
+				fieldName: 'manageListQuestion'
+			};
+			const answers = {
+				id: '2',
+				myField: 'my-value'
+			};
+			const journeyResponse = {
+				answers: {
+					manageListQuestion: [answers]
+				}
+			};
+			const params = { manageListItemId: '1' };
+			let got = question.answerObjectFromJourneyResponse(journeyResponse, { params, manageListQuestion });
+			assert.deepStrictEqual(got, {});
+			// also fallback to {} if there is no manageListQuestion answer
+			delete journeyResponse.answers.manageListQuestion;
+			got = question.answerObjectFromJourneyResponse(journeyResponse, { params, manageListQuestion });
+			assert.deepStrictEqual(got, {});
+		});
+		it('should error if a manage list question is missing required parameters', () => {
+			const question = getTestQuestion();
+			question.isInManageListSection = true;
+			const answers = { myField: 'my-value' };
+			const journeyResponse = { answers };
+			assert.throws(
+				() => question.answerObjectFromJourneyResponse(journeyResponse),
+				/no list item id for manage list question/
+			);
+			const params = { manageListItemId: '1' };
+			assert.throws(
+				() => question.answerObjectFromJourneyResponse(journeyResponse, { params }),
+				/no manageListQuestion for manage list question/
+			);
+		});
+	});
+
 	describe('renderAction', () => {
 		it('should renderAction', () => {
 			const question = getTestQuestion();
@@ -205,7 +298,7 @@ describe('./src/dynamic-forms/question.js', () => {
 			const expectedResult = { a: 1 };
 			const req = { body: { errors: { error: 'we have an error' } } };
 			const question = getTestQuestion();
-			question.prepQuestionForRendering = mock.fn(() => expectedResult);
+			question.toViewModel = mock.fn(() => expectedResult);
 
 			const result = question.checkForValidationErrors(req);
 

package/src/questions/questions.js

@@ -15,6 +15,7 @@ import EmailQuestion from '../components/email/question.js';
 import { COMPONENT_TYPES } from '../index.js';
 import TextEntryRedactQuestion from '../components/text-entry-redact/question.js';
 import DateTimeQuestion from '../components/date-time/question.js';
+import ManageListQuestion from '../components/manage-list/question.js';
 
 // This looks a bit grim because so few of our
 // Questions overlap with Question correctly.
@@ -35,5 +36,6 @@ export const questionClasses = Object.freeze({
 	[COMPONENT_TYPES.MULTI_FIELD_INPUT]: MultiFieldInputQuestion,
 	[COMPONENT_TYPES.NUMBER]: NumberEntryQuestion,
 	[COMPONENT_TYPES.UNIT_OPTION]: UnitOptionEntryQuestion,
-	[COMPONENT_TYPES.EMAIL]: EmailQuestion
+	[COMPONENT_TYPES.EMAIL]: EmailQuestion,
+	[COMPONENT_TYPES.MANAGE_LIST]: ManageListQuestion
 });

package/src/section-types.d.ts

@@ -0,0 +1,18 @@
+import { JourneyResponse } from '#src/journey/journey-response.js';
+import ManageListQuestion from '#src/components/manage-list/question.js';
+import { Question } from '#src/questions/question.js';
+
+export interface GetNextQuestionParams {
+	questionFieldName: string;
+	response: JourneyResponse;
+	// if this is part of a manage list section
+	manageListQuestion?: ManageListQuestion;
+	takeNextQuestion: boolean;
+	// to get previous question instead of next
+	reverse: boolean;
+}
+
+export interface StaticGetNextQuestionParams extends GetNextQuestionParams {
+	manageListQuestion: undefined;
+	questions: Question[];
+}

package/src/section.js

@@ -82,13 +82,20 @@ export class Section {
 
 	/**
 	 * Fluent API method for adding questions
-	 * @param {any} question
+	 * @param {import('#src/questions/question.js').Question} question
+	 * @param {import('#src/components/manage-list/manage-list-section.js').ManageListSection} [manageListSection]
 	 * @returns {Section}
 	 */
-	addQuestion(question) {
+	addQuestion(question, manageListSection) {
 		if (!question) {
 			throw new Error('question is required');
 		}
+		if (question.isManageListQuestion) {
+			if (!manageListSection || !manageListSection.isManageListSection) {
+				throw new Error('manage list questions require a ManageListSection');
+			}
+			question.section = manageListSection;
+		}
 		this.questions.push(question);
 		this.#conditionAdded = false; // reset condition flag
 		this.#applyConditions(question);
@@ -192,24 +199,46 @@ export class Section {
 
 	/**
 	 * Get the next question in this section given a questionParam (question fieldName)
-	 * @param {Object} params
-	 * @param {string} params.questionFieldName
-	 * @param {import('#src/journey/journey-response.js').JourneyResponse} params.response
-	 * @param {boolean} [params.takeNextQuestion]
-	 * @param {boolean} [params.reverse]
+	 * @param {import('./section-types.d.ts').GetNextQuestionParams} params
+	 * @returns {Question|Symbol|null}
+	 */
+	getNextQuestion(params) {
+		const { manageListQuestion } = params;
+		if (manageListQuestion) {
+			// first check if the next question is within the manage list section
+			const next = Section.getNextQuestion({
+				...params,
+				questions: manageListQuestion.section.questions
+			});
+			if (next === END_OF_SECTION) {
+				// after the manage list section questions, go back to the manage list question
+				return manageListQuestion;
+			}
+			return next;
+		}
+		return Section.getNextQuestion({
+			...params,
+			questions: this.questions
+		});
+	}
+
+	/**
+	 * Implementation of getNextQuestion given a list of questions
+	 *
+	 * @param {import('./section-types.d.ts').StaticGetNextQuestionParams} params
 	 * @returns {Question|Symbol|null}
 	 */
-	getNextQuestion({ questionFieldName, response, takeNextQuestion = false, reverse = false }) {
-		const numberOfQuestions = this.questions.length;
+	static getNextQuestion({ questions, questionFieldName, response, takeNextQuestion = false, reverse = false }) {
+		const numberOfQuestions = questions.length;
 
 		const questionsStart = reverse ? numberOfQuestions - 1 : 0;
 		for (let i = questionsStart; reverse ? i >= 0 : i < numberOfQuestions; reverse ? i-- : i++) {
-			const question = this.questions[i];
+			const question = questions[i];
 			if (takeNextQuestion && question.shouldDisplay(response)) {
 				return question;
 			}
 
-			if (question.fieldName === questionFieldName) {
+			if (question.fieldName === questionFieldName || question.url === questionFieldName) {
 				takeNextQuestion = true;
 			}
 		}

package/src/section.test.js

@@ -53,6 +53,42 @@ describe('./src/dynamic-forms/section.js', () => {
 			assert.strictEqual(question.isRequired, mockQuestion.isRequired);
 			assert.strictEqual(question.shouldDisplay(), mockQuestion.shouldDisplay());
 		});
+
+		it('should support manage list questions', () => {
+			const section = new Section('s1', 'S');
+			assert.strictEqual(section.questions.length, 0);
+			const q = {
+				get isManageListQuestion() {
+					return true;
+				}
+			};
+			const manageListSection = {
+				get isManageListSection() {
+					return true;
+				}
+			};
+			section.addQuestion(q, manageListSection);
+			assert.strictEqual(section.questions.length, 1);
+			assert.strictEqual(q.section, manageListSection);
+		});
+
+		it('should throw if no manageListSection provided for a manage list question', () => {
+			const section = new Section('s1', 'S');
+			assert.strictEqual(section.questions.length, 0);
+			const q = {
+				get isManageListQuestion() {
+					return true;
+				}
+			};
+			assert.throws(
+				() => section.addQuestion(q),
+				(thrown) => {
+					assert.strictEqual(thrown.message, 'manage list questions require a ManageListSection');
+					return true;
+				}
+			);
+			assert.strictEqual(section.questions.length, 0);
+		});
 	});
 
 	describe('getStatus', () => {
@@ -660,5 +696,58 @@ describe('./src/dynamic-forms/section.js', () => {
 			assert.strictEqual(q3.shouldDisplay.mock.callCount(), 1);
 			assert.strictEqual(next, END_OF_SECTION);
 		});
+		describe('manageListQuestions', () => {
+			const newSectionWithManageList = () => {
+				const q1 = { ...mockQuestion };
+				const manageListQ = {
+					get isManageListQuestion() {
+						return true;
+					}
+				};
+				const q3 = { ...mockQuestion2 };
+				const q4 = { ...mockQuestion3 };
+				const manageListSection = {
+					questions: [q3, q4],
+					get isManageListSection() {
+						return true;
+					}
+				};
+				const section = new Section('s1', 'S').addQuestion(q1).addQuestion(manageListQ, manageListSection);
+				return { section, q1, manageListQ, q3, q4 };
+			};
+			it(`should get first question within a manage list section`, () => {
+				const { section, manageListQ, q3 } = newSectionWithManageList();
+				const next = section.getNextQuestion({
+					questionFieldName: manageListQ.fieldName,
+					response: {},
+					manageListQuestion: manageListQ,
+					takeNextQuestion: true,
+					reverse: false
+				});
+				assert.strictEqual(next, q3);
+			});
+			it(`should get second question within a manage list section`, () => {
+				const { section, manageListQ, q3, q4 } = newSectionWithManageList();
+				const next = section.getNextQuestion({
+					questionFieldName: q3.fieldName,
+					response: {},
+					manageListQuestion: manageListQ,
+					takeNextQuestion: false,
+					reverse: false
+				});
+				assert.strictEqual(next, q4);
+			});
+			it(`should return to manage list question after manage list section is complete`, () => {
+				const { section, manageListQ, q4 } = newSectionWithManageList();
+				const next = section.getNextQuestion({
+					questionFieldName: q4.fieldName,
+					response: {},
+					manageListQuestion: manageListQ,
+					takeNextQuestion: false,
+					reverse: false
+				});
+				assert.strictEqual(next, manageListQ);
+			});
+		});
 	});
 });

package/test/journey.js

@@ -1,5 +1,6 @@
 import { Section } from '../src/section.js';
 import { Journey } from '../src/journey/journey.js';
+import { ManageListSection } from '#src/components/manage-list/manage-list-section.js';
 
 export const JOURNEY_ID = 'holiday-journey';
 
@@ -29,6 +30,10 @@ export function createJourney(questions, response) {
 				.addQuestion(questions.hotelAddress)
 				.addQuestion(questions.luggageWeight)
 				.addQuestion(questions.contactEmail)
+				.addQuestion(
+					questions.travelCompanions,
+					new ManageListSection().addQuestion(questions.travelCompanionName).addQuestion(questions.travelCompanionEmail)
+				)
 		],
 		taskListUrl: 'check-your-answers',
 		journeyTemplate: 'views/layout-journey.njk',

package/test/mock/journey.js

@@ -0,0 +1,17 @@
+import { Journey } from '#src/journey/journey.js';
+
+export function mockJourney() {
+	return new Journey({
+		journeyId: 'mock-journey-id',
+		makeBaseUrl: () => '/journey',
+		taskListUrl: 'check-your-answers',
+		response: { answers: {} },
+		journeyTemplate: 'views/layout-journey.njk',
+		taskListTemplate: 'views/layout-check-your-answers.njk',
+		informationPageViewPath: '',
+		journeyTitle: 'Mock Journey',
+		returnToListing: false,
+		sections: [],
+		initialBackLink: '/journey'
+	});
+}