@planning-inspectorate/dynamic-forms 3.14.0 → 3.15.0

package/package.json

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

package/src/components/address/question.js

@@ -30,6 +30,20 @@ export class AddressQuestion extends Question {
 		};
 	}
 
+	/**
+	 * Gets the body field names used by this question in form submissions.
+	 * @returns {string[]}
+	 */
+	get bodyFieldNames() {
+		return [
+			`${this.fieldName}_addressLine1`,
+			`${this.fieldName}_addressLine2`,
+			`${this.fieldName}_townCity`,
+			`${this.fieldName}_county`,
+			`${this.fieldName}_postcode`
+		];
+	}
+
 	/**
 	 * @param {Record<string, any>} answers
 	 * @returns {*|string}

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

@@ -56,6 +56,19 @@ describe('AddressQuestion', () => {
 		return { question, mockApi, req, journeyResponse };
 	};
 
+	describe('bodyFieldNames', () => {
+		it('should return all address sub-field names', () => {
+			const { question } = setup();
+			assert.deepStrictEqual(question.bodyFieldNames, [
+				`${FIELDNAME}_addressLine1`,
+				`${FIELDNAME}_addressLine2`,
+				`${FIELDNAME}_townCity`,
+				`${FIELDNAME}_county`,
+				`${FIELDNAME}_postcode`
+			]);
+		});
+	});
+
 	describe('getDataToSave', () => {
 		it('should format the data correctly to be saved', async () => {
 			const { question, req } = setup();

package/src/components/date/question.js

@@ -19,6 +19,14 @@ export class DateQuestion extends Question {
 		this.dateFormat = dateFormat;
 	}
 
+	/**
+	 * Gets the body field names used by this question in form submissions.
+	 * @returns {string[]}
+	 */
+	get bodyFieldNames() {
+		return [`${this.fieldName}_day`, `${this.fieldName}_month`, `${this.fieldName}_year`];
+	}
+
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req

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

@@ -26,6 +26,23 @@ describe('DateQuestion', () => {
 		});
 	});
 
+	describe('bodyFieldNames', () => {
+		it('should return day, month, and year field names', () => {
+			const dateQuestion = new DateQuestion({
+				title: TITLE,
+				question: QUESTION,
+				fieldName: FIELDNAME,
+				hint: HINT,
+				validators: VALIDATORS
+			});
+			assert.deepStrictEqual(dateQuestion.bodyFieldNames, [
+				`${FIELDNAME}_day`,
+				`${FIELDNAME}_month`,
+				`${FIELDNAME}_year`
+			]);
+		});
+	});
+
 	describe('getDataToSave', () => {
 		it('should return data correctly', async () => {
 			const dateQuestion = new DateQuestion({

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

@@ -34,6 +34,21 @@ export class DatePeriodQuestion extends Question {
 		this.endTime = endTime || { hour: 0, minute: 0, second: 0 };
 	}
 
+	/**
+	 * Gets the body field names used by this question in form submissions.
+	 * @returns {string[]}
+	 */
+	get bodyFieldNames() {
+		return [
+			`${this.fieldName}_start_day`,
+			`${this.fieldName}_start_month`,
+			`${this.fieldName}_start_year`,
+			`${this.fieldName}_end_day`,
+			`${this.fieldName}_end_month`,
+			`${this.fieldName}_end_year`
+		];
+	}
+
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req

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

@@ -30,6 +30,26 @@ describe('DatePeriodQuestion', () => {
 		});
 	});
 
+	describe('bodyFieldNames', () => {
+		it('should return all start and end date field names', () => {
+			const dateQuestion = new DatePeriodQuestion({
+				title: TITLE,
+				question: QUESTION,
+				fieldName: FIELDNAME,
+				hint: HINT,
+				validators: VALIDATORS
+			});
+			assert.deepStrictEqual(dateQuestion.bodyFieldNames, [
+				`${FIELDNAME}_start_day`,
+				`${FIELDNAME}_start_month`,
+				`${FIELDNAME}_start_year`,
+				`${FIELDNAME}_end_day`,
+				`${FIELDNAME}_end_month`,
+				`${FIELDNAME}_end_year`
+			]);
+		});
+	});
+
 	describe('getDataToSave', () => {
 		it('should return data correctly', async () => {
 			const dateQuestion = new DatePeriodQuestion({

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

@@ -22,6 +22,21 @@ export class DateTimeQuestion extends Question {
 		this.timeFormat = timeFormat;
 	}
 
+	/**
+	 * Gets the body field names used by this question in form submissions.
+	 * @returns {string[]}
+	 */
+	get bodyFieldNames() {
+		return [
+			`${this.fieldName}_day`,
+			`${this.fieldName}_month`,
+			`${this.fieldName}_year`,
+			`${this.fieldName}_hour`,
+			`${this.fieldName}_minutes`,
+			`${this.fieldName}_period`
+		];
+	}
+
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req

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

@@ -15,6 +15,17 @@ describe('./lib/forms/custom-components/date-time/question.js', () => {
 		it('should create', () => {
 			assert.strictEqual(question.viewFolder, 'date-time');
 		});
+
+		it('should return all date and time field names from bodyFieldNames', () => {
+			assert.deepStrictEqual(question.bodyFieldNames, [
+				'siteVisitDate_day',
+				'siteVisitDate_month',
+				'siteVisitDate_year',
+				'siteVisitDate_hour',
+				'siteVisitDate_minutes',
+				'siteVisitDate_period'
+			]);
+		});
 	});
 	describe('prepQuestionForRendering', () => {
 		it('should prep question for rendering when value not in payload', () => {

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

@@ -30,6 +30,14 @@ export class MultiFieldInputQuestion extends Question {
 		}
 	}
 
+	/**
+	 * Gets the body field names used by this question in form submissions.
+	 * @returns {string[]}
+	 */
+	get bodyFieldNames() {
+		return this.inputFields.map((inputField) => inputField.fieldName);
+	}
+
 	answerForViewModel(answers) {
 		return this.inputFields.map((inputField) => {
 			return {

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

@@ -51,6 +51,13 @@ describe('./src/dynamic-forms/components/multi-field-input/question.js', () => {
 		}, new Error('inputFields are mandatory'));
 	});
 
+	describe('bodyFieldNames', () => {
+		it('should return field names from all inputFields', () => {
+			const testQuestion = createMultiFieldInputQuestion();
+			assert.deepStrictEqual(testQuestion.bodyFieldNames, ['testField1', 'testField2']);
+		});
+	});
+
 	describe('prepQuestionForRendering', () => {
 		it('should call super and set inputFields', () => {
 			const question = createMultiFieldInputQuestion();

package/src/questions/question.js

@@ -181,6 +181,17 @@ export class Question {
 		this._isInManageListSection = value;
 	}
 
+	/**
+	 * Gets the body field names used by this question in form submissions.
+	 * Returns the field names that should be present in req.body when this question is submitted.
+	 * Subclasses should override this for questions with multiple or differently-named body fields.
+	 *
+	 * @returns {string[]}
+	 */
+	get bodyFieldNames() {
+		return [this.fieldName];
+	}
+
 	/**
 	 * gets the view model for this question
 	 *

package/src/questions/question.test.js

@@ -135,6 +135,13 @@ describe('./src/dynamic-forms/question.js', () => {
 		});
 	});
 
+	describe('bodyFieldNames', () => {
+		it('should return an array containing the fieldName by default', () => {
+			const question = getTestQuestion();
+			assert.deepStrictEqual(question.bodyFieldNames, [FIELDNAME]);
+		});
+	});
+
 	describe('prepQuestionForRendering', () => {
 		it('should prepQuestionForRendering', () => {
 			const question = getTestQuestion();

package/src/validator/address-validator.js

@@ -41,7 +41,7 @@ export class AddressValidator extends BaseValidator {
 
 	/**
 	 * validates response body using questionObj fieldname
-	 * @param {Question} questionObj
+	 * @param {import('../questions/question.js').Question} questionObj
 	 */
 	validate(questionObj) {
 		const fieldName = questionObj.fieldName;

package/src/validator/base-validator.js

@@ -18,7 +18,7 @@ export class BaseValidator {
 	 * Validates response body against field validators.
 	 * Subclasses must override this method.
 	 * @abstract
-	 * @param {import('../questions/question-props.js').QuestionProps} questionObj - The question object containing the fieldName to validate.
+	 * @param {{fieldName: string}} questionObj - The question object containing the fieldName to validate.
 	 * @param {import('../journey/journey-response.js').JourneyResponse} [journeyResponse] - The current journey response (optional).
 	 * @returns {import('express-validator').ValidationChain | import('express-validator').ValidationChain[]}
 	 */

package/src/validator/conditional-required-validator.js

@@ -31,7 +31,7 @@ export class ConditionalRequiredValidator extends BaseValidator {
 
 	/**
 	 * validates the response body, checking the questionObj's fieldname
-	 * @param {Question} questionObj
+	 * @param {import('../questions/options-question.js').OptionsQuestion} questionObj
 	 */
 	validate(questionObj) {
 		return questionObj.options.reduce((schema, option) => {

package/src/validator/cross-question-validator.README.md

@@ -0,0 +1,131 @@
+# Cross-question validator
+
+The `CrossQuestionValidator` enables validation of a question's answer against another question's answer using a custom validation function. This is useful for scenarios where the validity of one answer depends on another answer.
+
+## Constructor options
+
+| Parameter                 | Type                                           | Default      | Description                                                                                    |
+| ------------------------- | ---------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------- |
+| `dependencyFieldName`     | `string`                                       | **required** | The field name of the other question to compare against                                        |
+| `validationFunction`      | `(currentAnswer, dependencyAnswer) => boolean` | **required** | Function that returns `true` if valid, or throws an `Error` with a specific message if invalid |
+| `useBodyValues`           | `boolean`                                      | `false`      | Use `req.body` values for **both** current and dependency answers                              |
+| `useBodyValuesForCurrent` | `boolean`                                      | `false`      | Use `req.body` value for current answer only (dependency still uses JourneyResponse)           |
+
+## Use cases
+
+### 1. Validation between separate manage list questions (JourneyResponse data)
+
+When validating between questions where both answers are already saved to the JourneyResponse (e.g., in a manage list journey), use the default settings.
+
+```js
+import { CrossQuestionValidator } from '@planning-inspectorate/dynamic-forms';
+
+const startDateQuestion = {
+	type: COMPONENT_TYPES.DATE,
+	fieldName: 'startDate',
+	question: 'What is the start date?'
+	// ... other config
+};
+
+const endDateQuestion = {
+	type: COMPONENT_TYPES.DATE,
+	fieldName: 'endDate',
+	question: 'What is the end date?',
+	validators: [
+		new CrossQuestionValidator({
+			dependencyFieldName: 'startDate',
+			validationFunction: (endDate, startDate) => {
+				if (!endDate || !startDate) return true;
+				if (new Date(endDate) < new Date(startDate)) {
+					throw new Error('End date must be on or after the start date');
+				}
+				return true;
+			}
+		})
+	]
+};
+```
+
+**When to use:** Both questions are on separate pages and their answers are saved to the JourneyResponse before validation runs.
+
+### 2. Validation between regular questions (body data with formatting)
+
+When the current question's data needs to be extracted from `req.body` and formatted (e.g., date fields that come as separate day/month/year inputs), use `useBodyValuesForCurrent: true`.
+
+The validator will automatically use the question's `getDataToSave()` method to format the data correctly.
+
+```js
+const projectEndDateQuestion = {
+	type: COMPONENT_TYPES.DATE,
+	fieldName: 'projectEndDate',
+	question: 'When does the project end?',
+	validators: [
+		new CrossQuestionValidator({
+			dependencyFieldName: 'projectStartDate', // Already saved in JourneyResponse
+			useBodyValuesForCurrent: true, // Current answer from body, formatted via getDataToSave()
+			validationFunction: (endDate, startDate) => {
+				if (!endDate || !startDate) return true;
+				if (endDate < new Date(startDate)) {
+					throw new Error('Project end date must be on or after the project start date');
+				}
+				return true;
+			}
+		})
+	]
+};
+```
+
+**When to use:** The current question's answer is in `req.body` (not yet saved), but the dependency answer is already saved to the JourneyResponse. Works automatically with date questions, date-period questions, and other question types that have a `getDataToSave()` method.
+
+### 3. Validation between fields in a multi-field question (both from body)
+
+When validating between multiple fields on the same page (e.g., a `MultiFieldInputQuestion`), both current and reference values come from `req.body`. Use `useBodyValues: true`.
+
+```js
+const siteAreaQuestion = {
+	type: COMPONENT_TYPES.MULTI_FIELD_INPUT,
+	fieldName: 'siteArea',
+	question: 'What is the area of the site?',
+	inputFields: [
+		{ fieldName: 'siteAreaHectares', label: 'Site area in hectares (optional)' },
+		{ fieldName: 'siteAreaSquareMetres', label: 'Site area in square metres (optional)' }
+	],
+	validators: [
+		// Note: this is a custom validator not provided by default
+		new MultiFieldInputValidator({
+			fields: [
+				{
+					fieldName: 'siteAreaHectares',
+					validators: [
+						new CrossQuestionValidator({
+							dependencyFieldName: 'siteAreaSquareMetres',
+							useBodyValues: true,
+							validationFunction: (hectares, squareMetres) => {
+								if (hectares?.trim() && squareMetres?.trim()) {
+									throw new Error('Enter the site area in either hectares or square metres, not both');
+								}
+								return true;
+							}
+						})
+					]
+				}
+			]
+		})
+	]
+};
+```
+
+**When to use:** Multiple fields are on the same page and both values need to be read from `req.body` before either is saved.
+
+## How data sources are determined
+
+| `useBodyValues` | `useBodyValuesForCurrent` | Current Answer Source        | Dependency Answer Source |
+| --------------- | ------------------------- | ---------------------------- | ------------------------ |
+| `false`         | `false`                   | JourneyResponse              | JourneyResponse          |
+| `false`         | `true`                    | Body (via `getDataToSave()`) | JourneyResponse          |
+| `true`          | (ignored)                 | Body (via `getDataToSave()`) | Body (raw)               |
+
+## Notes
+
+- When `useBodyValuesForCurrent` is `true`, the validator uses the question's `getDataToSave()` method to format body data. This automatically handles complex field types like dates (`fieldName_day`, `fieldName_month`, `fieldName_year`).
+- The validator binds to the appropriate body field using the question's `bodyFieldNames` getter. For simple questions this returns `[fieldName]`, but complex question types override it (e.g., `DateQuestion` returns `[fieldName_day, fieldName_month, fieldName_year]`). Custom question components can define their own `bodyFieldNames` getter to ensure proper validation binding.

package/src/validator/cross-question-validator.js

@@ -11,16 +11,24 @@ export class CrossQuestionValidator extends BaseValidator {
 	validationFunction;
 	/** @type {boolean} */
 	useBodyValues;
+	/** @type {boolean} */
+	useBodyValuesForCurrent;
 
 	/**
 	 * @param {Object} params
 	 * @param {string} params.dependencyFieldName - The field name of the other question to compare against.
 	 * @param {((currentAnswer: unknown, dependencyAnswer: unknown) => boolean)| null} params.validationFunction - A function that takes the current question's answer and the other question's answer and returns true if valid, false otherwise.
-	 * @param {boolean} [params.useBodyValues=false] - Whether to use req.body values for validation (default: false). Usually CrossQuestionValidator will be for validating across saved session answers, but if used between multiple fields on one question, it will need to use the body.
+	 * @param {boolean} [params.useBodyValues=false] - Whether to use req.body values for validation (default: false). Usually CrossQuestionValidator will be for validating across saved JourneyResponse answers, but if used between multiple fields on one question, it will need to use the body.
+	 * @param {boolean} [params.useBodyValuesForCurrent=false] - Whether to use req.body values for the current question's answer (default: false). This may help with questions where data is not saved to the JourneyResponse on POST (e.g. non-multiple entities questions).
 	 * @throws {Error} If validationFunction is not provided or is not a function.
 	 * @throws {Error} If dependencyFieldName is not provided
 	 */
-	constructor({ dependencyFieldName, validationFunction, useBodyValues = false } = {}) {
+	constructor({
+		dependencyFieldName,
+		validationFunction,
+		useBodyValues = false,
+		useBodyValuesForCurrent = false
+	} = {}) {
 		super();
 
 		if (!dependencyFieldName) {
@@ -33,24 +41,59 @@ export class CrossQuestionValidator extends BaseValidator {
 		this.dependencyFieldName = dependencyFieldName;
 		this.validationFunction = validationFunction;
 		this.useBodyValues = useBodyValues;
+		this.useBodyValuesForCurrent = useBodyValues || useBodyValuesForCurrent;
+	}
+
+	/**
+	 * Gets the body field name to bind validation to.
+	 * Uses the question's bodyFieldNames getter to determine which body field
+	 * express-validator binds to for triggering validation.
+	 * @param {import('../questions/question.js').Question} questionObj
+	 * @returns {string}
+	 */
+	#getBodyFieldName(questionObj) {
+		// Use the first body field name from the question's bodyFieldNames getter
+		// This allows questions to define their own body field names, supporting
+		// custom components and complex field structures (e.g. date, date-time, address)
+		return questionObj.bodyFieldNames?.[0] ?? questionObj.fieldName;
 	}
 
 	/**
 	 * Validates response body against individual field validators.
-	 * @param {import('../questions/question-props.js').QuestionProps} questionObj - The question object containing the fieldName to validate.
+	 * Uses the question's getDataToSave method to extract and format body values when useBodyValuesForCurrent is true,
+	 * allowing generic handling of any question type without needing to know its internal structure.
+	 * @param {import('../questions/question.js').Question} questionObj - The question object containing the fieldName to validate.
 	 * @param {import('../journey/journey-response.js').JourneyResponse} [journeyResponse={}] - The current journey response, used to access saved answers for validation.
 	 * @returns {import('express-validator').ValidationChain[]}
 	 */
 	validate(questionObj, journeyResponse = {}) {
 		const fieldName = questionObj.fieldName;
+		const bodyFieldName = this.#getBodyFieldName(questionObj);
 
 		return [
-			body(fieldName).custom((value, { req }) => {
+			body(bodyFieldName).custom(async (value, { req }) => {
 				const answers = journeyResponse?.answers || {};
-				const currentAnswer = this.useBodyValues ? value : answers[fieldName];
+
+				let currentAnswer;
+				if (this.useBodyValuesForCurrent) {
+					// Use the question's own getDataToSave to format body data generically
+					if (typeof questionObj.getDataToSave === 'function') {
+						const { answers: formattedAnswers } = await questionObj.getDataToSave(req, journeyResponse);
+						// Use the formatted answer if available, otherwise return all formatted answers
+						// (handles MultiFieldInputQuestion which returns answers keyed by input field names)
+						currentAnswer = fieldName in formattedAnswers ? formattedAnswers[fieldName] : formattedAnswers;
+					} else {
+						// Fallback to raw body value if getDataToSave is not available
+						currentAnswer = req.body[fieldName];
+					}
+				} else {
+					currentAnswer = answers[fieldName];
+				}
+
 				const dependencyAnswer = this.useBodyValues
 					? req.body[this.dependencyFieldName]
 					: answers[this.dependencyFieldName];
+
 				return (
 					this.validationFunction(currentAnswer, dependencyAnswer) ||
 					// Fallback if validation fails without throwing an error