@planning-inspectorate/dynamic-forms 3.21.0 → 3.22.0

package/README.md

@@ -86,7 +86,7 @@ The controllers available are:
 
 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:
+For other use cases, write a custom `SaveDataFn`. A basic implementation (if you are not using ManageList or DynamicSection) 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}) => {
@@ -130,6 +130,51 @@ const update: SaveDataFn = async ({data, req, isManageListItem, manageListQuesti
 }
 ```
 
+To support `DynamicSection`, handle `isDynamicSection`, `dynamicSectionFieldName`, and `dynamicSectionId`. The implementation is very similar to the manage lists and the logic can be combined. For example:
+
+```typescript
+const update: SaveDataFn = async ({
+        data,
+        req,
+        isManageListItem,
+        manageListQuestionFieldName,
+        manageListItemRemove,
+        isDynamicSection,
+        dynamicSectionFieldName,
+        dynamicSectionId
+    }) => {
+    if (isManageListItem || isDynamicSection) {
+        // manage list and dynamic sections can be handled the same, just with different properties
+        // for the fieldName and item id
+        const fieldName = isManageListItem ? manageListQuestionFieldName : dynamicSectionFieldName;
+        const itemId = isManageListItem ? req.params.manageListItemId : dynamicSectionId;
+        
+        const update = {
+            id: itemId,
+            ...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
 
@@ -270,6 +315,12 @@ formatSummaryValue: ({ formattedAnswer, journey }) => {
 
 > **Note:** `formattedAnswer` is already escaped by dynamic-forms; you are responsible for escaping any additional user-controlled values you include (for example `answer` or values read from `journey.response.answers`).
 
+### Other features
+
+See documentation in [docs](./docs), including:
+
+* [Dynamic Sections](./docs/Dynamic%20Sections.md)
+
 ## Contributing
 
 When contributing to this package, ensure changes are generic and not service-specific. Speak to the R&D devs if you are not sure. Prefer configuration over hardcoding values, and ensure the code is well documented. 

package/docs/Dynamic Sections.md

@@ -0,0 +1,47 @@
+# Dynamic Sections
+
+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 answers within `journeyResponse.answers[section.fieldName]` which is expected to be an array, and it will look for an object with an `id` property matching the sections' segment.
+
+For example, considering a dynamic section for a Person object:
+
+```typescript
+function createPersonSection(person) {
+	return new DynamicSection(person.name, person.id, 'people').addQuestion(questions.name);
+	// ... other questions
+}
+```
+
+Then the answers object should be of the form:
+
+```typescript
+answers = {
+	myField: 'some answer', // a normal question field
+	people: [
+		// dynamic section fields
+		{ id: 'person-id-1', name: 'Grogu' },
+		{ id: 'person-id-2', name: 'Mando' }
+	]
+};
+```
+
+## Saving data
+
+When using with `buildSave`, be sure to handle the parameters: `isDynamicSection`, `dynamicSectionId`,`dynamicSectionFieldName`. The implementation `buildSaveDataToSession` (in `session-answer-store.js`) may be a useful reference.
+
+```typescript
+const buildSaveFn: SaveDataFn = async (params) => {
+	if (params.isDynamicSection) {
+		// saving a response within a dynamic section
+		const itemId = params.dynamicSectionId;
+		const listType = params.dynamicSectionFieldName;
+
+		// some logic to save the data for this item
+	}
+};
+```
+
+## Conditions
+
+Question conditions can only access other questions within the section.

package/package.json

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

package/src/components/manage-list/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AAEH;IAOC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,wBAAwB,EAe1E;IAcD,wCAEC;IAyDD;;;;OAMC;IAED;;OAEG;IACH,+BAkBC;IAED,4EAQC;IAoCD,yDAEC;IATD,kDAKC;;CAKD;;;;;;mBApLa,MAAM;;;;;;;;;;;;;;yBAPK,WAAW"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AAEH;IAOC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,wBAAwB,EAe1E;IAcD,wCAEC;IA8DD;;;;OAMC;IAED;;OAEG;IACH,+BAkBC;IAED,4EAQC;IAoCD,yDAEC;IATD,kDAKC;;CAKD;;;;;;mBAzLa,MAAM;;;;;;;;;;;;;;yBAPK,WAAW"}

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

@@ -85,6 +85,11 @@ export class ManageListQuestion extends Question {
 		}
 		const mockJourney = {
 			getCurrentQuestionUrl() {},
+			responseForSection() {
+				// this function is already passed the array-item
+				// call to formatAnswerForSummary may use responseForSection so we implement here
+				return this.response;
+			},
 			response: {
 				answers: answer
 			}

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

@@ -54,7 +54,9 @@ describe('components/manage-list/question', () => {
 		const innerQ2 = {
 			url: 'second-question',
 			title: 'Q 2',
-			formatAnswerForSummary() {
+			formatAnswerForSummary(sectionSegment, journey) {
+				// simulate a question which may call responseForSection, such as multi field input
+				journey.responseForSection(sectionSegment);
 				return [{ value: 'mock answer 2' }];
 			}
 		};

package/src/components/multi-field-input/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IACC;;OAEG;IACH,8CAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAe/E;IAJC,kEAA8B;IAchC;;;;;;;;;;;;;;;QAOC;IA4CD;;;;;OAKG;IACH,uCAJW,MAAM,WACN,OAAO,UAAU,EAAE,OAAO,GACxB,OAAO,+BAA+B,EAAE,UAAU,EAAE,CAuChE;;CAsDD;;yBAtLwB,WAAW"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IACC;;OAEG;IACH,8CAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAe/E;IAJC,kEAA8B;IAchC;;;;;;;;;;;;;;;QAOC;IA4CD;;;;;OAKG;IACH,uCAJW,MAAM,WACN,OAAO,UAAU,EAAE,OAAO,GACxB,OAAO,+BAA+B,EAAE,UAAU,EAAE,CAyChE;;CAsDD;;yBAxLwB,WAAW"}

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

@@ -90,8 +90,10 @@ export class MultiFieldInputQuestion extends Question {
 	 * @returns {import('#typedefs/question-types.d.ts').SummaryRow[]}
 	 */
 	formatAnswerForSummary(sectionSegment, journey) {
+		// get the response/answers for the section we're in - which might be a dynamic section
+		const response = journey.responseForSection(sectionSegment);
 		// Handle unanswered case - delegate to parent for notStartedText
-		if (this.#allQuestionsUnanswered(journey)) {
+		if (this.#allQuestionsUnanswered(response)) {
 			return super.formatAnswerForSummary(sectionSegment, journey, null);
 		}
 
@@ -99,7 +101,7 @@ export class MultiFieldInputQuestion extends Question {
 		const defaultJoinString = this.isInManageListSection ? '\n' : '<br>';
 
 		let summaryDetails = this.inputFields.reduce((accumulator, field) => {
-			const rawAnswer = journey.response.answers[field.fieldName];
+			const rawAnswer = response.answers[field.fieldName];
 			if (rawAnswer === undefined || rawAnswer === null || rawAnswer === '') return accumulator;
 
 			const formatted = this.#formatFieldForSummary(rawAnswer, field, journey, sectionSegment);
@@ -159,11 +161,11 @@ export class MultiFieldInputQuestion extends Question {
 
 	/**
 	 * checks whether any answers have been provided for input field questions
-	 * @param {import('#journey').Journey} journey
+	 * @param {import('#journey-response').JourneyResponse} response
 	 * @returns {boolean}
 	 */
-	#allQuestionsUnanswered(journey) {
-		return this.inputFields.every((field) => journey.response.answers[field.fieldName] === undefined);
+	#allQuestionsUnanswered(response) {
+		return this.inputFields.every((field) => response.answers[field.fieldName] === undefined);
 	}
 
 	/**