@planning-inspectorate/dynamic-forms 3.21.0 → 3.23.0

package/src/controller.test.js

@@ -3,11 +3,13 @@ import assert from 'node:assert';
 import { list, question, buildSave } from './controller.js';
 
 import { Journey } from './journey/journey.js';
-import { SECTION_STATUS } from './section.js';
+import { Section, SECTION_STATUS } from './section.js';
 
 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';
+import { DynamicSection } from '#src/dynamic-section.js';
+import { Question } from '#question';
 
 const mockBaseUrl = '/manage-appeals/questionnaire';
 const mockRef = '123456';
@@ -18,148 +20,83 @@ const mockAnswer = 'Not started';
 
 function testSetup() {
 	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(() => [
-						{
-							key: 'Title 1a',
-							value: mockAnswer,
-							action: {
-								href: '/manage-appeals/questionnaire/123456/segment-1/title-1a',
-								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;
-			},
-			isComplete: () => {
-				return true;
+		new Section('Section 1', 'segment-1'),
+		new Section('Section 2', 'segment-2'),
+		new DynamicSection('Section 3', 'segment-3', 'arrayOfAnswers')
+	];
+	/**
+	 * Create a new question and set taskList if needed
+	 * Also mocks formatAnswerForSummary so it can be overridden later.
+	 * Default mock uses the original implementation
+	 *
+	 * @param {import('#typedefs/question-types.d.ts').QuestionParameters} params
+	 * @param {boolean} [taskList]
+	 * @returns {Question}
+	 */
+	const newQuestion = (params, taskList) => {
+		const q = new Question(params);
+		if (typeof taskList === 'boolean') {
+			q.taskList = taskList;
+		}
+		mock.method(q, 'formatAnswerForSummary');
+		return q;
+	};
+	// mock/override what we need
+	mock.method(sections[0], 'getStatus', () => SECTION_STATUS.COMPLETE);
+	mock.method(sections[0], 'isComplete', () => true);
+	sections[0].questions = [
+		newQuestion({
+			title: 'Title 1a',
+			question: 'Why?',
+			fieldName: 'title-1a',
+			viewFolder: 'mock'
+		}),
+		newQuestion(
+			{
+				title: 'Title 1b',
+				question: 'Who?',
+				fieldName: 'title-1b',
+				viewFolder: 'mock'
 			},
-			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 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;
+			false
+		)
+	];
+
+	mock.method(sections[1], 'getStatus', () => SECTION_STATUS.IN_PROGRESS);
+	mock.method(sections[1], 'isComplete', () => true);
+	sections[1].questions = [
+		newQuestion({
+			title: 'Title 2a',
+			question: 'How?',
+			fieldName: 'title-2a',
+			viewFolder: 'mock'
+		}),
+		newQuestion({
+			title: 'Title 2b',
+			question: 'What?',
+			fieldName: 'title-2b',
+			viewFolder: 'mock'
+		})
+	];
+
+	mock.method(sections[2], 'getStatus', () => SECTION_STATUS.NOT_STARTED);
+	mock.method(sections[2], 'isComplete', () => false);
+	sections[2].questions = [
+		newQuestion(
+			{
+				title: 'Title 3a',
+				question: 'When?',
+				fieldName: 'title-3a',
+				viewFolder: 'mock'
 			},
-			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 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'
-							}
-						}
-					]
-				}
-			]
-		}
+			false
+		),
+		newQuestion({
+			title: 'Title 3b',
+			question: 'Really?',
+			fieldName: 'title-3b',
+			viewFolder: 'mock'
+		})
 	];
 
 	const journeyParams = {
@@ -186,7 +123,7 @@ function testSetup() {
 
 	const mockJourney = new Journey({ response: mockResponse, ...journeyParams });
 
-	res.locals.journeyResponse = {};
+	res.locals.journeyResponse = mockResponse;
 	res.locals.journey = mockJourney;
 
 	const sampleQuestionObj = {
@@ -238,12 +175,12 @@ describe('dynamic-form/controller', () => {
 			mockJourney.sections[0].questions[0].formatAnswerForSummary.mock.mockImplementation(() => [
 				{
 					key: 'Title 1a',
-					value: mockAnswer,
+					value: 'Yes',
 					action: [
 						{
 							href: '/manage-appeals/questionnaire/123456/segment-1/title-1a',
-							text: 'Answer',
-							visuallyHiddenText: 'Answer'
+							text: 'Change',
+							visuallyHiddenText: 'Why?'
 						},
 						{
 							href: '/manage-appeals/questionnaire/123456/segment-1/title-1a/edit',
@@ -344,6 +281,35 @@ describe('dynamic-form/controller', () => {
 				visuallyHiddenText: 'Answer'
 			});
 		});
+
+		it('should render dynamic sections answers', async () => {
+			const { req, res, mockJourney } = testSetup();
+			const dynamicSection = mockJourney.sections[2];
+
+			// show all questions
+			dynamicSection.questions[0].taskList = true;
+			mockJourney.response.answers = {
+				arrayOfAnswers: [
+					{ id: 'id-1', 'title-3a': 'First answer', 'title-3b': 'Second answer' },
+					// should match these answers - based on section segment
+					{ id: 'segment-3', 'title-3a': 'Another answer', 'title-3b': 'A fourth answer' }
+				]
+			};
+
+			await list(req, res, '', {});
+
+			const mockFn = res.render.mock;
+			assert.strictEqual(mockFn.callCount(), 1);
+			const args = mockFn.calls[0].arguments[1];
+			assert.ok(args.summaryListData);
+			const section = args.summaryListData.sections[2];
+			assert.strictEqual(section.heading, 'Section 3');
+			const rows = section.list.rows;
+			assert.strictEqual(rows.length, 2);
+			// answers extracted from the array
+			assert.strictEqual(rows[0].value.html, 'Another answer');
+			assert.strictEqual(rows[1].value.html, 'A fourth answer');
+		});
 	});
 
 	describe('question', () => {
@@ -562,6 +528,9 @@ describe('dynamic-form/controller', () => {
 					isManageListItem: undefined,
 					manageListItemRemove: false,
 					manageListQuestionFieldName: undefined,
+					isDynamicSection: false,
+					dynamicSectionId: undefined,
+					dynamicSectionFieldName: undefined,
 					data: undefined
 				}
 			]);
@@ -623,7 +592,10 @@ describe('dynamic-form/controller', () => {
 						data: undefined,
 						isManageListItem: undefined,
 						manageListItemRemove: false,
-						manageListQuestionFieldName: undefined
+						manageListQuestionFieldName: undefined,
+						isDynamicSection: false,
+						dynamicSectionId: undefined,
+						dynamicSectionFieldName: undefined
 					}
 				],
 				'save data args'
@@ -678,7 +650,7 @@ describe('dynamic-form/controller', () => {
 			};
 			sampleQuestionObjWithActions.getDataToSave.mock.mockImplementationOnce(() => ({
 				answers: {
-					[sampleQuestionObj.fieldName]: 'my-answer',
+					[sampleQuestionObjWithActions.fieldName]: 'my-answer',
 					aBooleanToTest: true
 				}
 			}));
@@ -749,6 +721,63 @@ describe('dynamic-form/controller', () => {
 			assert.strictEqual(Object.keys(res.locals.journeyResponse.answers).length, 0);
 		});
 
+		it('should call saveData with dynamic section properties', async () => {
+			const { req, res, mockJourney, sampleQuestionObj, journeyParams } = testSetup();
+			const journeyId = 'has-questionnaire';
+			const dynamicSection = mockJourney.sections[2];
+
+			sampleQuestionObj.getDataToSave.mock.mockImplementationOnce(() => ({
+				answers: {
+					[sampleQuestionObj.fieldName]: 'my-answer'
+				}
+			}));
+
+			req.params = {
+				referenceId: mockRef,
+				section: dynamicSection.segment,
+				question: dynamicSection.questions[0].fieldName
+			};
+
+			res.locals.journeyResponse = {
+				...journeyParams,
+				answers: {}
+			};
+
+			req.body = {
+				sampleFieldName: true,
+				sampleFieldName_sub: 'send this',
+				notSampleFieldName: 'do not send this'
+			};
+
+			mockJourney.getQuestionByParams = mock.fn();
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => sampleQuestionObj);
+
+			const saveData = mock.fn();
+			await buildSave(saveData)(req, res, journeyId);
+
+			assert.strictEqual(sampleQuestionObj.getDataToSave.mock.callCount(), 1);
+			assert.strictEqual(saveData.mock.callCount(), 1);
+			assert.deepStrictEqual(saveData.mock.calls[0].arguments, [
+				{
+					req,
+					res,
+					journeyId: journeyParams.journeyId,
+					referenceId: journeyParams.referenceId,
+					isManageListItem: undefined,
+					manageListItemRemove: false,
+					manageListQuestionFieldName: undefined,
+					isDynamicSection: true,
+					dynamicSectionId: 'segment-3',
+					dynamicSectionFieldName: 'arrayOfAnswers',
+					data: { answers: { [sampleQuestionObj.fieldName]: 'my-answer' } }
+				}
+			]);
+			// journey response should be edited if redirecting to next question
+			assert.deepStrictEqual(res.locals.journeyResponse.answers?.arrayOfAnswers, [
+				{ id: 'segment-3', [sampleQuestionObj.fieldName]: 'my-answer' }
+			]);
+		});
+
 		describe('manageListQuestions', () => {
 			const setupJourney = () => {
 				const q = {
@@ -834,13 +863,13 @@ const _getmockSummaryListData = (mockJourney) => {
 								items: [
 									{
 										href: `${mockBaseUrl}/${mockRef}/${mockJourney.sections[0].segment}/${mockJourney.sections[0].questions[0].fieldName}`,
-										text: 'Answer',
-										visuallyHiddenText: 'Answer'
+										text: 'Change',
+										visuallyHiddenText: mockJourney.sections[0].questions[0].question
 									}
 								]
 							},
 							key: { text: mockJourney.sections[0].questions[0].title },
-							value: { html: 'Not started' }
+							value: { html: 'Yes' }
 						}
 					]
 				}
@@ -856,7 +885,7 @@ const _getmockSummaryListData = (mockJourney) => {
 									{
 										href: `${mockBaseUrl}/${mockRef}/${mockJourney.sections[1].segment}/${mockJourney.sections[1].questions[0].fieldName}`,
 										text: 'Answer',
-										visuallyHiddenText: 'Answer'
+										visuallyHiddenText: mockJourney.sections[1].questions[0].question
 									}
 								]
 							},
@@ -869,7 +898,7 @@ const _getmockSummaryListData = (mockJourney) => {
 									{
 										href: `${mockBaseUrl}/${mockRef}/${mockJourney.sections[1].segment}/${mockJourney.sections[1].questions[1].fieldName}`,
 										text: 'Answer',
-										visuallyHiddenText: 'Answer'
+										visuallyHiddenText: mockJourney.sections[1].questions[1].question
 									}
 								]
 							},
@@ -890,7 +919,7 @@ const _getmockSummaryListData = (mockJourney) => {
 									{
 										href: `${mockBaseUrl}/${mockRef}/${mockJourney.sections[2].segment}/${mockJourney.sections[2].questions[1].fieldName}`,
 										text: 'Answer',
-										visuallyHiddenText: 'Answer'
+										visuallyHiddenText: mockJourney.sections[2].questions[1].question
 									}
 								]
 							},

package/src/dynamic-section.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Use a dynamic section for sections which are generated from an array of objects
+ *
+ * This can be useful for adding a section for each entry in a ManageList, or each row in a database
+ * The controller logic, when encountering a DynamicSection, will check for an answer object within
+ * `journeyResponse.answers[fieldName]`, matching by the `id` property
+ *
+ * ```
+ * answers = {
+ *   myField: 'some answer',
+ *   list: [
+ *     { id: 'person-id-1', name: 'Grogu' },
+ *     { id: 'person-id-2', name: 'Mando' }
+ *   ]
+ * }
+ * ```
+ *
+ * In this example, create a DynamicSection for each list entry:
+ *
+ * ```
+ *  function createPersonSection(person) {
+ *  return new DynamicSection(person.name, person.id, 'list')
+ *   .addQuestion(questions.name)
+ *   // ... add questions
+ * }
+ * ```
+ *
+ * When using with buildSave, be sure to handle the parameters: `isDynamicSection`, `dynamicSectionId`,`dynamicSectionFieldName`
+ */
+export class DynamicSection extends Section {
+    /**
+     * @param name
+     * @param segment
+     * @param fieldName the key used in the answers object, which will be an array of answers for this section
+     */
+    constructor(name: any, segment: any, fieldName: any);
+    fieldName: any;
+}
+import { Section } from '#section';
+//# sourceMappingURL=dynamic-section.d.ts.map

package/src/dynamic-section.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-section.d.ts","sourceRoot":"","sources":["dynamic-section.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACC;;;;OAIG;IACH,qDAIC;IADA,eAA0B;CAU3B;wBAlDuB,UAAU"}

package/src/dynamic-section.js

@@ -0,0 +1,51 @@
+import { Section } from '#section';
+
+/**
+ * Use a dynamic section for sections which are generated from an array of objects
+ *
+ * This can be useful for adding a section for each entry in a ManageList, or each row in a database
+ * The controller logic, when encountering a DynamicSection, will check for an answer object within
+ * `journeyResponse.answers[fieldName]`, matching by the `id` property
+ *
+ * ```
+ * answers = {
+ *   myField: 'some answer',
+ *   list: [
+ *     { id: 'person-id-1', name: 'Grogu' },
+ *     { id: 'person-id-2', name: 'Mando' }
+ *   ]
+ * }
+ * ```
+ *
+ * In this example, create a DynamicSection for each list entry:
+ *
+ * ```
+ *  function createPersonSection(person) {
+ *  return new DynamicSection(person.name, person.id, 'list')
+ *   .addQuestion(questions.name)
+ *   // ... add questions
+ * }
+ * ```
+ *
+ * When using with buildSave, be sure to handle the parameters: `isDynamicSection`, `dynamicSectionId`,`dynamicSectionFieldName`
+ */
+export class DynamicSection extends Section {
+	/**
+	 * @param name
+	 * @param segment
+	 * @param fieldName the key used in the answers object, which will be an array of answers for this section
+	 */
+	constructor(name, segment, fieldName) {
+		super(name, segment);
+
+		this.fieldName = fieldName;
+	}
+
+	/**
+	 * Indicate that this section is dynamic, and answers should be pulled from an array
+	 * @returns {boolean}
+	 */
+	get isDynamicSection() {
+		return true;
+	}
+}

package/src/dynamic-section.test.js

@@ -0,0 +1,113 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+import { DynamicSection } from '#src/dynamic-section.js';
+import { SECTION_STATUS } from '#section';
+import { Question } from '#question';
+
+// use a real question to avoid mocking lots of logic
+const mockQuestion = (fieldName = 'fieldName', required = true) =>
+	new Question({
+		fieldName: fieldName,
+		title: 'question',
+		question: 'question',
+		viewFolder: 'folder',
+		validators: [
+			{
+				isRequired() {
+					return required;
+				}
+			}
+		]
+	});
+
+describe('dynamic-section', () => {
+	describe('responseForSection', () => {
+		it('should return inner object for dynamic section', () => {
+			const section = new DynamicSection('s1', 'id-1', 'myList');
+			const answers = { id: 'id-1', myField: 'answer' };
+			const res = {
+				answers: {
+					myList: [{ id: 'id-2' }, { id: 'id-3' }, answers]
+				}
+			};
+			const got = section.getResponse(res);
+			assert.strictEqual(got?.answers, answers);
+		});
+	});
+
+	describe('getStatus', () => {
+		it('should use section answers for status', () => {
+			const s1Answers = { id: 'S', fieldOne: 'answer' };
+			const mockJourneyResponse = {
+				answers: {
+					visitFrequently: 'Answer 1',
+					anotherFieldName: 'Answer 2',
+					myList: [s1Answers]
+				}
+			};
+
+			const requiredQuestion = mockQuestion('visitFrequently');
+
+			const section = new DynamicSection('s1', 'S', 'myList');
+			section.addQuestion(requiredQuestion);
+
+			mock.method(requiredQuestion, 'shouldDisplay');
+			mock.method(requiredQuestion, 'isAnswered');
+
+			section.getStatus(mockJourneyResponse);
+
+			assert.strictEqual(requiredQuestion.shouldDisplay.mock.callCount(), 1);
+			assert.strictEqual(requiredQuestion.isAnswered.mock.callCount(), 2);
+			assert.strictEqual(requiredQuestion.shouldDisplay.mock.calls[0].arguments[0].answers, s1Answers);
+			assert.strictEqual(requiredQuestion.isAnswered.mock.calls[0].arguments[0].answers, s1Answers);
+		});
+
+		it('should return NOT_STARTED when no answers are given', () => {
+			const mockJourneyResponse = {
+				answers: {}
+			};
+			const section = new DynamicSection('s1', 'S', 'myList');
+			section.addQuestion(mockQuestion());
+			const result = section.getStatus(mockJourneyResponse);
+			assert.strictEqual(result, SECTION_STATUS.NOT_STARTED);
+			const isComplete = section.isComplete(mockJourneyResponse);
+			assert.strictEqual(isComplete, false);
+		});
+
+		it('should return IN_PROGRESS when at least one answer is given', () => {
+			const mockJourneyResponse = {
+				answers: {
+					myList: [{ id: 'S', visitFrequently: 'Answer 1' }]
+				}
+			};
+
+			const section = new DynamicSection('s1', 'S', 'myList');
+			section.addQuestion(mockQuestion());
+			section.addQuestion(mockQuestion('visitFrequently'));
+			const result = section.getStatus(mockJourneyResponse);
+			assert.strictEqual(result, SECTION_STATUS.IN_PROGRESS);
+			const isComplete = section.isComplete(mockJourneyResponse);
+			assert.strictEqual(isComplete, false);
+		});
+
+		it('should return COMPLETE when all required answers are given', () => {
+			const s1Answers = { id: 'S', visitFrequently: 'answer', anotherFieldName: true };
+			const mockJourneyResponse = {
+				answers: {
+					myList: [s1Answers]
+				}
+			};
+
+			const section = new DynamicSection('s1', 'S', 'myList');
+			section.addQuestion(mockQuestion('visitFrequently'));
+			section.addQuestion(mockQuestion('anotherFieldName'));
+			section.addQuestion(mockQuestion('someQuestion', false));
+
+			const result = section.getStatus(mockJourneyResponse);
+			assert.strictEqual(result, SECTION_STATUS.COMPLETE);
+
+			const isComplete = section.isComplete(mockJourneyResponse);
+			assert.strictEqual(isComplete, true);
+		});
+	});
+});

package/src/index.d.ts

@@ -32,6 +32,8 @@ export * from "./lib/utils.js";
 export * from "./middleware/build-get-journey.js";
 export * from "./middleware/redirect-to-unanswered-question.js";
 export * from "./questions/options-question.js";
+export * from "./dynamic-section.js";
+export * from "./section.js";
 export * from "./validator/address-validator.js";
 export * from "./validator/base-validator.js";
 export * from "./validator/conditional-required-validator.js";
@@ -58,6 +60,5 @@ export { JourneyResponse } from "./journey/journey-response.js";
 export { Question } from "./questions/question.js";
 export { createQuestions } from "./questions/create-questions.js";
 export { questionClasses } from "./questions/questions.js";
-export { Section } from "./section.js";
 export { default as validate } from "./validator/validator.js";
 //# sourceMappingURL=index.d.ts.map

package/src/index.js

@@ -55,7 +55,8 @@ export * from './questions/options-question.js';
 export { questionClasses } from './questions/questions.js';
 
 // Section
-export { Section } from './section.js';
+export * from './dynamic-section.js';
+export * from './section.js';
 
 // Validators
 export * from './validator/address-validator.js';