@planning-inspectorate/dynamic-forms 3.16.0 → 3.17.0

package/src/components/text-entry/question.js

@@ -32,7 +32,7 @@ export class TextEntryQuestion extends Question {
 	}
 
 	/**
-	 * @param {import('#question').QuestionViewModel} viewModel
+	 * @param {import('#typedefs/question-types.d.ts').QuestionViewModel} viewModel
 	 */
 	addCustomDataToViewModel(viewModel) {
 		viewModel.question.label = this.label;

package/src/components/text-entry-redact/question.d.ts

@@ -15,16 +15,12 @@ export class TextEntryRedactQuestion extends Question {
     showSuggestionsUi: boolean | undefined;
     summaryText: string | undefined;
     shouldTruncateSummary: boolean | undefined;
-    prepQuestionForRendering(section: any, journey: any, customViewData: any, payload: any, options: any): import("../../index.js").QuestionViewModel<import("../../index.js").BaseQuestionViewData>;
+    prepQuestionForRendering(section: any, journey: any, customViewData: any, payload: any, options: any): import("#typedefs/question-types.d.ts").QuestionViewModel<import("#typedefs/question-types.d.ts").BaseQuestionViewData>;
     answerForViewModel(answers: any): string;
-    /**
-     * @param {import('#question').QuestionViewModel} viewModel
-     */
-    addCustomDataToViewModel(viewModel: import("#question").QuestionViewModel): void;
     /**
      * returns the formatted answers values to be used to build task list elements
      */
-    formatAnswerForSummary(sectionSegment: any, journey: any, answer: any, capitals?: boolean): import("../../index.js").SummaryRow[];
+    formatAnswerForSummary(sectionSegment: any, journey: any, answer: any, capitals?: boolean): import("#typedefs/question-types.d.ts").SummaryRow[];
 }
 export default TextEntryRedactQuestion;
 import { Question } from '#question';

package/src/components/text-entry-redact/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAGA,+BAAgC,QAAG,CAAC;AACpC,mCAAoC,GAAG,CAAC;AAExC;;GAEG;AACH;IACC;;OAEG;IACH,gLAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAwB/E;IAPA,yFAA0C;IAC1C,0BAAkB;IAClB,qDAAsE;IACtE,iDAA8D;IAC9D,uCAA0C;IAC1C,gCAA8B;IAC9B,2CAAkD;IAkBnD,iMAOC;IAED,yCAEC;IAED;;OAEG;IACH,oCAFW,OAAO,WAAW,EAAE,iBAAiB,QAO/C;IAED;;OAEG;IACH,kIAuBC;CACD;;yBAtGwB,WAAW"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAGA,+BAAgC,QAAG,CAAC;AACpC,mCAAoC,GAAG,CAAC;AAExC;;GAEG;AACH;IACC;;OAEG;IACH,gLAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAwB/E;IAPA,yFAA0C;IAC1C,0BAAkB;IAClB,qDAAsE;IACtE,iDAA8D;IAC9D,uCAA0C;IAC1C,gCAA8B;IAC9B,2CAAkD;IAkBnD,+NAOC;IAED,yCAEC;IAYD;;OAEG;IACH,iJAuBC;CACD;;yBAtGwB,WAAW"}

package/src/components/text-entry-redact/question.js

@@ -64,7 +64,7 @@ export class TextEntryRedactQuestion extends Question {
 	}
 
 	/**
-	 * @param {import('#question').QuestionViewModel} viewModel
+	 * @param {import('#typedefs/question-types.d.ts').QuestionViewModel} viewModel
 	 */
 	addCustomDataToViewModel(viewModel) {
 		viewModel.question.label = this.label;

package/src/components/utils/question-has-answer.js

@@ -41,7 +41,7 @@ export const questionHasAnswer = (response, question, expectedValue) => {
 	if (Array.isArray(answerField)) {
 		return answerField.includes(expectedValue);
 	} else if (question.optionJoinString && typeof answerField === 'string') {
-		// todo: answers from options questions sometimes are array sometimes string, why?
+		// todo: DF-51 answers from options questions sometimes are array sometimes string, why?
 		if (!answerField) return false;
 		const answers = answerField.split(question.optionJoinString);
 		return answers.includes(expectedValue);

package/src/components/utils/question-utils.d.ts

@@ -1,5 +1,23 @@
 export function getConditionalFieldName(parentField: any, conditionalField: any): string;
-export function getConditionalAnswer(answers: any, question: any, answer: any): any;
+/**
+ * Get conditional answer(s) for a question.
+ * Returns an object keyed by option value with conditional answers, or null if no conditionals exist.
+ *
+ * @param {Record<string, unknown>} answers - all answers
+ * @param {{options?: Array<{value: string, conditional?: {fieldName: string}}>, fieldName: string, optionJoinString?: string}} question - question with options
+ * @param {string} answer - the answer value (may be separated by optionJoinString for checkboxes)
+ * @returns {Record<string, string> | null} conditional answer(s) keyed by option value
+ */
+export function getConditionalAnswer(answers: Record<string, unknown>, question: {
+    options?: Array<{
+        value: string;
+        conditional?: {
+            fieldName: string;
+        };
+    }>;
+    fieldName: string;
+    optionJoinString?: string;
+}, answer: string): Record<string, string> | null;
 /**
  * @param {unknown} conditional
  * @returns {conditional is {html: string}}

package/src/components/utils/question-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question-utils.d.ts","sourceRoot":"","sources":["question-utils.js"],"names":[],"mappings":"AAAA,yFAEC;AAED,oFAGC;AAED;;;GAGG;AACH,mDAHW,OAAO,GACL,WAAW,IAAI;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAIzC"}
+{"version":3,"file":"question-utils.d.ts","sourceRoot":"","sources":["question-utils.js"],"names":[],"mappings":"AAAA,yFAEC;AAED;;;;;;;;GAQG;AACH,8CALW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YACvB;IAAC,OAAO,CAAC,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE;YAAC,SAAS,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAC,UACnH,MAAM,GACJ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAyBzC;AAED;;;GAGG;AACH,mDAHW,OAAO,GACL,WAAW,IAAI;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAIzC"}

package/src/components/utils/question-utils.js

@@ -2,9 +2,38 @@ export function getConditionalFieldName(parentField, conditionalField) {
 	return `${parentField}_${conditionalField}`;
 }
 
+/**
+ * Get conditional answer(s) for a question.
+ * Returns an object keyed by option value with conditional answers, or null if no conditionals exist.
+ *
+ * @param {Record<string, unknown>} answers - all answers
+ * @param {{options?: Array<{value: string, conditional?: {fieldName: string}}>, fieldName: string, optionJoinString?: string}} question - question with options
+ * @param {string} answer - the answer value (may be separated by optionJoinString for checkboxes)
+ * @returns {Record<string, string> | null} conditional answer(s) keyed by option value
+ */
 export function getConditionalAnswer(answers, question, answer) {
-	const conditionalFieldName = question.options?.find((option) => option.value === answer)?.conditional?.fieldName;
-	return conditionalFieldName ? answers[getConditionalFieldName(question.fieldName, conditionalFieldName)] : null;
+	if (!answer || !question.options) {
+		return null;
+	}
+
+	// TODO DF-51 treat as an array
+	const joinString = question.optionJoinString || ',';
+	const answerValues = String(answer)
+		.split(joinString)
+		.map((v) => v.trim());
+
+	const conditionals = {};
+	for (const value of answerValues) {
+		const option = question.options.find((opt) => opt.value === value);
+		if (!option?.conditional?.fieldName) {
+			continue;
+		}
+		const conditionalValue = answers[getConditionalFieldName(question.fieldName, option.conditional.fieldName)];
+		if (conditionalValue) {
+			conditionals[value] = conditionalValue;
+		}
+	}
+	return Object.keys(conditionals).length > 0 ? conditionals : null;
 }
 
 /**

package/src/components/utils/question-utils.test.js

@@ -34,8 +34,8 @@ describe('getConditionalAnswer', () => {
 
 	it('returns conditional field value when it exists', () => {
 		const { answers, question } = setup();
-		const expectedResult = 'test';
-		assert.strictEqual(getConditionalAnswer(answers, question, 'yes'), expectedResult);
+		const expectedResult = { yes: 'test' };
+		assert.deepStrictEqual(getConditionalAnswer(answers, question, 'yes'), expectedResult);
 	});
 
 	it('returns null when option chosen does not have conditional value', () => {
@@ -49,4 +49,91 @@ describe('getConditionalAnswer', () => {
 		delete question.options[0].conditional;
 		assert.strictEqual(getConditionalAnswer(answers, question, 'yes'), null);
 	});
+
+	it('returns null when answer is null', () => {
+		const { answers, question } = setup();
+		assert.strictEqual(getConditionalAnswer(answers, question, null), null);
+	});
+
+	it('returns null when answer is empty string', () => {
+		const { answers, question } = setup();
+		assert.strictEqual(getConditionalAnswer(answers, question, ''), null);
+	});
+
+	it('returns null when question has no options', () => {
+		const { answers, question } = setup();
+		delete question.options;
+		assert.strictEqual(getConditionalAnswer(answers, question, 'yes'), null);
+	});
+
+	describe('multi-value answers (checkboxes)', () => {
+		const setupMultiValue = () => {
+			const answers = {
+				field: 'a,b,c',
+				field_detailsA: 'details for A',
+				field_detailsC: 'details for C'
+			};
+			const question = {
+				fieldName: 'field',
+				options: [
+					{
+						value: 'a',
+						conditional: {
+							fieldName: 'detailsA'
+						}
+					},
+					{
+						value: 'b'
+					},
+					{
+						value: 'c',
+						conditional: {
+							fieldName: 'detailsC'
+						}
+					}
+				]
+			};
+			return { answers, question };
+		};
+
+		it('returns object with conditional values for multiple selected options', () => {
+			const { answers, question } = setupMultiValue();
+			const result = getConditionalAnswer(answers, question, 'a,c');
+			assert.deepStrictEqual(result, {
+				a: 'details for A',
+				c: 'details for C'
+			});
+		});
+
+		it('returns object with only options that have conditional values', () => {
+			const { answers, question } = setupMultiValue();
+			const result = getConditionalAnswer(answers, question, 'a,b');
+			assert.deepStrictEqual(result, {
+				a: 'details for A'
+			});
+		});
+
+		it('returns null when no selected options have conditional values', () => {
+			const { answers, question } = setupMultiValue();
+			const result = getConditionalAnswer(answers, question, 'b');
+			assert.strictEqual(result, null);
+		});
+
+		it('returns null when conditional fields have no values', () => {
+			const { answers, question } = setupMultiValue();
+			delete answers.field_detailsA;
+			delete answers.field_detailsC;
+			const result = getConditionalAnswer(answers, question, 'a,c');
+			assert.strictEqual(result, null);
+		});
+
+		it('handles whitespace in comma-separated values', () => {
+			const { answers, question } = setupMultiValue();
+			const result = getConditionalAnswer(answers, question, 'a , c');
+			assert.deepStrictEqual(result, {
+				a: 'details for A',
+				c: 'details for C'
+			});
+		});
+	});
 });

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

@@ -22,7 +22,7 @@
  *}} Option
  */
 /**
- * @typedef {import('./question.js').QuestionViewModel & { question: { options: Option[] } }} OptionsViewModel
+ * @typedef {import('#typedefs/question-types.d.ts').QuestionViewModel & { question: { options: Option[] } }} OptionsViewModel
  */
 /**
  * @typedef {import('#typedefs/question-types.d.ts').QuestionParameters & { options: Array<Option> }} OptionsQuestionParameters
@@ -42,9 +42,9 @@ export class OptionsQuestion extends Question {
      * @param {Record<string, unknown>} [customViewData] additional data to send to view
      * @param {Record<string, unknown>} [payload]
      * @param {import('#typedefs/question-types.d.ts').PrepQuestionForRenderingOptions} options
-     * @returns {import('./question.js').QuestionViewModel} QuestionViewModel
+     * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel} QuestionViewModel
      */
-    prepQuestionForRendering(section: import("#section").Section, journey: import("#journey").Journey, customViewData?: Record<string, unknown>, payload?: Record<string, unknown>, options: import("#typedefs/question-types.d.ts").PrepQuestionForRenderingOptions): import("./question.js").QuestionViewModel;
+    prepQuestionForRendering(section: import("#section").Section, journey: import("#journey").Journey, customViewData?: Record<string, unknown>, payload?: Record<string, unknown>, options: import("#typedefs/question-types.d.ts").PrepQuestionForRenderingOptions): import("#typedefs/question-types.d.ts").QuestionViewModel;
 }
 export default OptionsQuestion;
 export type Option = {
@@ -68,7 +68,7 @@ export type Option = {
         html: string;
     };
 };
-export type OptionsViewModel = import("./question.js").QuestionViewModel & {
+export type OptionsViewModel = import("#typedefs/question-types.d.ts").QuestionViewModel & {
     question: {
         options: Option[];
     };

package/src/questions/options-question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options-question.d.ts","sourceRoot":"","sources":["options-question.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;GAEG;AACH;;GAEG;AAEH;IAIC;;OAEG;IACH,oBAFW,yBAAyB,EAenC;IAnBD,4BAA4B;IAC5B,SADW,KAAK,CAAC,MAAM,CAAC,CAChB;IAiBP,yBAA+C;IAGhD;;;;;;;;OAQG;IACH,kCAPW,OAAO,UAAU,EAAE,OAAO,WAC1B,OAAO,UAAU,EAAE,OAAO,mBAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACvB,OAAO,+BAA+B,EAAE,+BAA+B,GACrE,OAAO,eAAe,EAAE,iBAAiB,CAkDrD;CAmCD;;qBAhJY;IACR,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,WAAW,CAAC,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,OAAO,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAA;KAClB,CAAC;IACA,eAAe,CAAC,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;KAChB,CAAA;CACH;+BAIU,OAAO,eAAe,EAAE,iBAAiB,GAAG;IAAE,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAAE;wCAG/E,OAAO,+BAA+B,EAAE,kBAAkB,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAE;yBAnC3E,eAAe"}
+{"version":3,"file":"options-question.d.ts","sourceRoot":"","sources":["options-question.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;GAEG;AACH;;GAEG;AAEH;IAIC;;OAEG;IACH,oBAFW,yBAAyB,EAenC;IAnBD,4BAA4B;IAC5B,SADW,KAAK,CAAC,MAAM,CAAC,CAChB;IAiBP,yBAA+C;IAGhD;;;;;;;;OAQG;IACH,kCAPW,OAAO,UAAU,EAAE,OAAO,WAC1B,OAAO,UAAU,EAAE,OAAO,mBAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACvB,OAAO,+BAA+B,EAAE,+BAA+B,GACrE,OAAO,+BAA+B,EAAE,iBAAiB,CAkDrE;CA2DD;;qBAxKY;IACR,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,WAAW,CAAC,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,OAAO,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAA;KAClB,CAAC;IACA,eAAe,CAAC,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;KAChB,CAAA;CACH;+BAIU,OAAO,+BAA+B,EAAE,iBAAiB,GAAG;IAAE,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAAE;wCAG/F,OAAO,+BAA+B,EAAE,kBAAkB,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAE;yBApC3E,eAAe"}

package/src/questions/options-question.js

@@ -3,6 +3,7 @@ import { Question } from './question.js';
 import ValidOptionValidator from '../validator/valid-option-validator.js';
 import { getConditionalFieldName } from '../components/utils/question-utils.js';
 import { toArray } from '#src/lib/utils.js';
+import escape from 'escape-html';
 
 const defaultOptionJoinString = ',';
 
@@ -31,7 +32,7 @@ const defaultOptionJoinString = ',';
  */
 
 /**
- * @typedef {import('./question.js').QuestionViewModel & { question: { options: Option[] } }} OptionsViewModel
+ * @typedef {import('#typedefs/question-types.d.ts').QuestionViewModel & { question: { options: Option[] } }} OptionsViewModel
  */
 /**
  * @typedef {import('#typedefs/question-types.d.ts').QuestionParameters & { options: Array<Option> }} OptionsQuestionParameters
@@ -66,7 +67,7 @@ export class OptionsQuestion extends Question {
 	 * @param {Record<string, unknown>} [customViewData] additional data to send to view
 	 * @param {Record<string, unknown>} [payload]
 	 * @param {import('#typedefs/question-types.d.ts').PrepQuestionForRenderingOptions} options
-	 * @returns {import('./question.js').QuestionViewModel} QuestionViewModel
+	 * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel} QuestionViewModel
 	 */
 	prepQuestionForRendering(section, journey, customViewData, payload, options) {
 		const viewModel = super.prepQuestionForRendering(section, journey, customViewData, payload, options);
@@ -118,6 +119,29 @@ export class OptionsQuestion extends Question {
 		return viewModel;
 	}
 
+	/**
+	 * Formats an answer value for display in the summary.
+	 * Looks up the option text for the given value(s).
+	 *
+	 * @param {unknown} answer - the raw answer value
+	 * @returns {string} the formatted answer for display
+	 */
+	formatAnswer(answer) {
+		if (answer === null || answer === undefined || answer === '') {
+			return this.notStartedText;
+		}
+
+		const answerValues = String(answer)
+			.split(this.optionJoinString)
+			.map((value) => value.trim());
+		const texts = answerValues.map((value) => {
+			const option = this.options.find((opt) => opt.value === value);
+			return escape(option ? option.text : value);
+		});
+
+		return texts.join('<br>');
+	}
+
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
@@ -137,6 +161,7 @@ export class OptionsQuestion extends Question {
 		if (selectedOptions.length !== fieldValues.length)
 			throw new Error(`User submitted option(s) did not correlate with valid answers to ${this.fieldName} question`);
 
+		// TODO DF-51 treat as an array
 		answers[this.fieldName] = fieldValues.join(this.optionJoinString);
 
 		this.options.forEach((option) => {

package/src/questions/options-question.test.js

@@ -303,4 +303,110 @@ describe('./src/dynamic-forms/question.js', () => {
 			);
 		});
 	});
+
+	describe('formatAnswer', () => {
+		it('should return not started text for null answer', () => {
+			const question = getTestQuestion({
+				options: [{ text: 'Option A', value: 'a' }]
+			});
+			const result = question.formatAnswer(null);
+			assert.strictEqual(result, 'Not started');
+		});
+
+		it('should return not started text for undefined answer', () => {
+			const question = getTestQuestion({
+				options: [{ text: 'Option A', value: 'a' }]
+			});
+			const result = question.formatAnswer(undefined);
+			assert.strictEqual(result, 'Not started');
+		});
+
+		it('should return not started text for empty string answer', () => {
+			const question = getTestQuestion({
+				options: [{ text: 'Option A', value: 'a' }]
+			});
+			const result = question.formatAnswer('');
+			assert.strictEqual(result, 'Not started');
+		});
+
+		it('should format a single value using option text', () => {
+			const question = getTestQuestion({
+				options: [
+					{ text: 'Option A', value: 'a' },
+					{ text: 'Option B', value: 'b' }
+				]
+			});
+			const result = question.formatAnswer('a');
+			assert.strictEqual(result, 'Option A');
+		});
+
+		it('should format multiple values joined with line breaks', () => {
+			const question = getTestQuestion({
+				options: [
+					{ text: 'Option A', value: 'a' },
+					{ text: 'Option B', value: 'b' },
+					{ text: 'Option C', value: 'c' }
+				]
+			});
+			const result = question.formatAnswer('a,b');
+			assert.strictEqual(result, 'Option A<br>Option B');
+		});
+
+		it('should fall back to value when option not found', () => {
+			const question = getTestQuestion({
+				options: [{ text: 'Option A', value: 'a' }]
+			});
+			const result = question.formatAnswer('unknown');
+			assert.strictEqual(result, 'unknown');
+		});
+
+		it('should handle mixed known and unknown values', () => {
+			const question = getTestQuestion({
+				options: [
+					{ text: 'Option A', value: 'a' },
+					{ text: 'Option B', value: 'b' }
+				]
+			});
+			const result = question.formatAnswer('a,unknown,b');
+			assert.strictEqual(result, 'Option A<br>unknown<br>Option B');
+		});
+
+		it('should trim whitespace from values', () => {
+			const question = getTestQuestion({
+				options: [
+					{ text: 'Option A', value: 'a' },
+					{ text: 'Option B', value: 'b' }
+				]
+			});
+			const result = question.formatAnswer('a , b');
+			assert.strictEqual(result, 'Option A<br>Option B');
+		});
+
+		it('should escape HTML in option text', () => {
+			const question = getTestQuestion({
+				options: [{ text: '<script>alert("xss")</script>', value: 'a' }]
+			});
+			const result = question.formatAnswer('a');
+			assert.strictEqual(result, '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;');
+		});
+
+		it('should escape HTML in fallback value when option not found', () => {
+			const question = getTestQuestion({
+				options: [{ text: 'Option A', value: 'a' }]
+			});
+			const result = question.formatAnswer('<img src=x onerror=alert(1)>');
+			assert.strictEqual(result, '&lt;img src=x onerror=alert(1)&gt;');
+		});
+
+		it('should escape HTML in multiple option texts', () => {
+			const question = getTestQuestion({
+				options: [
+					{ text: '<b>Bold</b>', value: 'a' },
+					{ text: '<i>Italic</i>', value: 'b' }
+				]
+			});
+			const result = question.formatAnswer('a,b');
+			assert.strictEqual(result, '&lt;b&gt;Bold&lt;/b&gt;<br>&lt;i&gt;Italic&lt;/i&gt;');
+		});
+	});
 });

package/src/questions/question.d.ts

@@ -7,7 +7,7 @@ export class Question {
      * @param {import('#typedefs/question-types.d.ts').QuestionParameters} params
      * @param {Record<string, Function>} [methodOverrides]
      */
-    constructor({ title, question, viewFolder, fieldName, url, pageTitle, description, validators, html, hint, interfaceType, shouldDisplay, autocomplete, editable, actionLink, viewData }: import("#typedefs/question-types.d.ts").QuestionParameters, methodOverrides?: Record<string, Function>);
+    constructor({ title, question, viewFolder, fieldName, url, pageTitle, description, validators, html, hint, interfaceType, shouldDisplay, autocomplete, editable, actionLink, viewData, formatSummaryValue, capitaliseAnswer }: import("#typedefs/question-types.d.ts").QuestionParameters, methodOverrides?: Record<string, Function>);
     /** @type {string} - html page title, defaults to question if not provided */
     pageTitle: string;
     /** @type {string} - title used in the summary list */
@@ -38,6 +38,8 @@ export class Question {
     actionLink: import("#typedefs/question-types.d.ts").ActionLink | undefined;
     /** @type {string} 'not started' text to display (if a question has no answer) */
     notStartedText: string;
+    /** @type {boolean} whether to capitalize the first letter of the answer in summary */
+    capitaliseAnswer: boolean;
     /** @type {string} button text to display */
     continueButtonText: string;
     /** @type {string} text to display for 'change' link */
@@ -46,6 +48,8 @@ export class Question {
     answerActionText: string;
     /** @type {string} text to display for 'add' link */
     addActionText: string;
+    /** @type {import('#typedefs/question-types.d.ts').SummaryValueFormatter|undefined} custom function to format the summary display value */
+    formatSummaryValue: import("#typedefs/question-types.d.ts").SummaryValueFormatter | undefined;
     /**
      * @param {import('../journey/journey-response.js').JourneyResponse} [response]
      * @returns {boolean}
@@ -199,6 +203,7 @@ export class Question {
      * @param {string} sectionSegment
      * @param {import('../journey/journey.js').Journey} journey
      * @param {unknown} answer
+     * @param {boolean} [capitals] - deprecated: use capitaliseAnswer property instead
      * @returns {import('#typedefs/question-types.d.ts').SummaryRow[]}
      */
     formatAnswerForSummary(sectionSegment: string, journey: import("../journey/journey.js").Journey, answer: unknown, capitals?: boolean): import("#typedefs/question-types.d.ts").SummaryRow[];
@@ -215,6 +220,15 @@ export class Question {
      * @returns {unknown}
      */
     format(answer: unknown): unknown;
+    /**
+     * Formats an answer value for display in the summary.
+     * Subclasses can override this to provide custom formatting without
+     * needing to override the full formatAnswerForSummary method.
+     *
+     * @param {unknown} answer - the raw answer value
+     * @returns {string} the formatted answer for display
+     */
+    formatAnswer(answer: unknown): string;
     /**
      * @returns {boolean}
      */
@@ -230,5 +244,6 @@ export class Question {
      * @returns {boolean}
      */
     isAnswered(journeyResponse: import("../journey/journey-response.js").JourneyResponse, fieldName?: string): boolean;
+    #private;
 }
 //# sourceMappingURL=question.d.ts.map

package/src/questions/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"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"}

package/src/questions/question.js

@@ -39,6 +39,8 @@ export class Question {
 
 	/** @type {string} 'not started' text to display (if a question has no answer) */
 	notStartedText = 'Not started';
+	/** @type {boolean} whether to capitalize the first letter of the answer in summary */
+	capitaliseAnswer = true;
 	/** @type {string} button text to display */
 	continueButtonText = 'Continue';
 	/** @type {string} text to display for 'change' link */
@@ -47,6 +49,8 @@ export class Question {
 	answerActionText = 'Answer';
 	/** @type {string} text to display for 'add' link */
 	addActionText = 'Add';
+	/** @type {import('#typedefs/question-types.d.ts').SummaryValueFormatter|undefined} custom function to format the summary display value */
+	formatSummaryValue;
 
 	/**
 	 * @param {import('../journey/journey-response.js').JourneyResponse} [response]
@@ -89,7 +93,9 @@ export class Question {
 			autocomplete,
 			editable = true,
 			actionLink,
-			viewData = {}
+			viewData = {},
+			formatSummaryValue,
+			capitaliseAnswer = true
 		},
 		methodOverrides
 	) {
@@ -111,6 +117,8 @@ export class Question {
 		this.editable = editable;
 		this.actionLink = actionLink;
 		this.viewData = viewData;
+		this.formatSummaryValue = formatSummaryValue;
+		this.capitaliseAnswer = capitaliseAnswer;
 
 		if (shouldDisplay) {
 			this.shouldDisplay = shouldDisplay;
@@ -153,6 +161,18 @@ export class Question {
 		this._isInManageListSection = value;
 	}
 
+	/**
+	 * Applies custom summary formatting if a formatSummaryValue function is provided
+	 * @param {import('#typedefs/question-types.d.ts').SummaryFormatterContext} context - the context for formatting
+	 * @returns {string}
+	 */
+	#applyCustomSummaryFormatter(context) {
+		if (this.formatSummaryValue) {
+			return this.formatSummaryValue(context);
+		}
+		return context.formattedAnswer;
+	}
+
 	/**
 	 * 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.
@@ -376,19 +396,38 @@ export class Question {
 	 * @param {string} sectionSegment
 	 * @param {import('../journey/journey.js').Journey} journey
 	 * @param {unknown} answer
+	 * @param {boolean} [capitals] - deprecated: use capitaliseAnswer property instead
 	 * @returns {import('#typedefs/question-types.d.ts').SummaryRow[]}
 	 */
-	formatAnswerForSummary(sectionSegment, journey, answer, capitals = true) {
-		const formattedAnswer = capitals ? capitalize(answer ?? this.notStartedText) : (answer ?? this.notStartedText);
+	formatAnswerForSummary(sectionSegment, journey, answer, capitals) {
+		let formattedAnswer = this.formatAnswer(answer);
+
+		// Handle deprecated capitals parameter
+		// TODO DF-49 fully remove capitals parameter
+		if (capitals !== undefined && capitals !== this.capitaliseAnswer) {
+			console.warn(
+				`[Deprecation Warning] The 'capitals' parameter in formatAnswerForSummary is deprecated. ` +
+					`Set 'capitaliseAnswer: ${capitals}' in the question constructor instead.`
+			);
+			// Temporarily override for backwards compatibility
+			const originalCapitalize = this.capitaliseAnswer;
+			this.capitaliseAnswer = capitals;
+			formattedAnswer = this.formatAnswer(answer);
+			this.capitaliseAnswer = originalCapitalize;
+		}
+
 		const action = this.getAction(sectionSegment, journey, answer);
 		const key = this.title ?? this.question;
-		let rowParams = [];
-		rowParams.push({
-			key: key,
-			value: nl2br(escape(formattedAnswer)),
-			action: action
+
+		const displayValue = this.#applyCustomSummaryFormatter({
+			answer,
+			formattedAnswer,
+			question: this,
+			journey,
+			sectionSegment
 		});
-		return rowParams;
+
+		return [{ key, value: displayValue, action }];
 	}
 
 	/**
@@ -427,6 +466,22 @@ export class Question {
 		return answer;
 	}
 
+	/**
+	 * Formats an answer value for display in the summary.
+	 * Subclasses can override this to provide custom formatting without
+	 * needing to override the full formatAnswerForSummary method.
+	 *
+	 * @param {unknown} answer - the raw answer value
+	 * @returns {string} the formatted answer for display
+	 */
+	formatAnswer(answer) {
+		let formatted = answer ?? this.notStartedText;
+		if (this.capitaliseAnswer) {
+			formatted = capitalize(formatted);
+		}
+		return nl2br(escape(formatted));
+	}
+
 	/**
 	 * @returns {boolean}
 	 */