@planning-inspectorate/dynamic-forms 3.15.6 → 3.17.0

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/{types/src → src}/questions/question.d.ts

@@ -1,39 +1,13 @@
-/**
- * @import {BaseValidator} from "#base-validator"
- * @import {ActionView} from "../controller.js"
- * @import {ActionLink} from "./question-types.js"
- */
-/**
- * @typedef {Object} PreppedQuestion
- * @property {Object} value
- * @property {string} question
- * @property {string} fieldName
- * @property {string} pageTitle
- * @property {string} [description]
- * @property {string} [html]
- */
-/**
- * @typedef {Record<string, any>} QuestionViewModel
- * @property {PreppedQuestion} question
- * @property {string} layoutTemplate
- * @property {string} pageCaption
- * @property {string} [continueButtonText]
- * @property {string} backLink
- * @property {boolean} showBackToListLink
- * @property {string} listLink
- * @property {Object} util
- * @property {function(string): string} util.trimTrailingSlash
- */
 /**
  * A specific question within a journey which is made up of one (usually) or many (sometimes) components and their required content.
  * @class
  */
 export class Question {
     /**
-     * @param {import('./question-types.js').QuestionParameters} params
+     * @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("./question-types.js").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 */
@@ -48,8 +22,8 @@ export class Question {
     fieldName: string;
     /** @type {boolean} if the question should appear in the journey overview task list or not */
     taskList: boolean;
-    /** @type {Array.<BaseValidator>} array of validators that a question uses to validate answers */
-    validators: Array<BaseValidator>;
+    /** @type {Array.<import('../validator/base-validator.js').BaseValidator>} array of validators that a question uses to validate answers */
+    validators: Array<import("../validator/base-validator.js").BaseValidator>;
     /** @type {string|undefined} hint text displayed to user */
     hint: string | undefined;
     /** @type {boolean} show return to listing page link after question */
@@ -60,10 +34,12 @@ export class Question {
     html: string | undefined;
     /** @type {string|undefined} optional question type */
     interfaceType: string | undefined;
-    /** @type {ActionLink|undefined} override action link */
-    actionLink: ActionLink | undefined;
+    /** @type {import('#typedefs/question-types.d.ts').ActionLink|undefined} override action link */
+    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 */
@@ -72,11 +48,13 @@ 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}
      */
-    shouldDisplay: () => boolean;
+    shouldDisplay: (response?: import("../journey/journey-response.js").JourneyResponse) => boolean;
     details: {
         title: string;
         text: string;
@@ -93,8 +71,8 @@ export class Question {
     editable: boolean;
     viewData: {
         [key: string]: any;
-        extraActionButtons?: import("./question-types.js").SecondaryAction[];
-        secondaryActions?: import("./question-types.js").SecondaryAction[];
+        extraActionButtons?: import("#typedefs/question-types.d.ts").SecondaryAction[];
+        secondaryActions?: import("#typedefs/question-types.d.ts").SecondaryAction[];
     };
     /**
      * Is this question a manage list question?
@@ -126,22 +104,22 @@ export class Question {
      * that prepQuestionForRendering doesn't need
      *
      * @param {Object} options
-     * @param {import('../journey/journey-types.js').RouteParams} options.params
+     * @param {import('#typedefs/journey-types.d.ts').RouteParams} options.params
      * @param {import('../components/manage-list/question.js')} [options.manageListQuestion]
      * @param {import('../section.js').Section} options.section - the current section
      * @param {import('../journey/journey.js').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}
+     * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel}
      */
     toViewModel({ params, manageListQuestion, section, journey, customViewData, payload }: {
-        params: import("../journey/journey-types.js").RouteParams;
+        params: import("#typedefs/journey-types.d.ts").RouteParams;
         manageListQuestion?: typeof import("../components/manage-list/question.js") | undefined;
         section: import("../section.js").Section;
         journey: import("../journey/journey.js").Journey;
         customViewData?: Record<string, unknown> | undefined;
         payload?: unknown;
-    }): QuestionViewModel;
+    }): import("#typedefs/question-types.d.ts").QuestionViewModel;
     /**
      * gets the base view model for this question
      *
@@ -149,10 +127,10 @@ export class Question {
      * @param {import('../journey/journey.js').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.js').PrepQuestionForRenderingOptions} [options] - required to support manage list question
-     * @returns {QuestionViewModel}
+     * @param {import('#typedefs/question-types.d.ts').PrepQuestionForRenderingOptions} [options] - required to support manage list question
+     * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel}
      */
-    prepQuestionForRendering(section: import("../section.js").Section, journey: import("../journey/journey.js").Journey, customViewData?: Record<string, unknown>, payload?: unknown, options?: import("./question-types.js").PrepQuestionForRenderingOptions): QuestionViewModel;
+    prepQuestionForRendering(section: import("../section.js").Section, journey: import("../journey/journey.js").Journey, customViewData?: Record<string, unknown>, payload?: unknown, options?: import("#typedefs/question-types.d.ts").PrepQuestionForRenderingOptions): import("#typedefs/question-types.d.ts").QuestionViewModel;
     /**
      * The answer to this question for use in the viewModel
      *
@@ -167,32 +145,32 @@ export class Question {
      *
      * If possible override this method instead of prepQuestionForRendering for simple changes to the view model
      *
-     * @param {QuestionViewModel} viewModel
-     */ addCustomDataToViewModel(viewModel: QuestionViewModel): void;
+     * @param {import('#typedefs/question-types.d.ts').QuestionViewModel} viewModel
+     */ addCustomDataToViewModel(viewModel: import("#typedefs/question-types.d.ts").QuestionViewModel): void;
     /**
      * Get the answers object from the journey response, which may be nested in an array for manage list questions
      *
      * @param {import('../journey/journey-response.js').JourneyResponse} response
-     * @param {import('./question-types.js').PrepQuestionForRenderingOptions} [options]
+     * @param {import('#typedefs/question-types.d.ts').PrepQuestionForRenderingOptions} [options]
      * @returns {Record<string, any>}
      */
-    answerObjectFromJourneyResponse(response: import("../journey/journey-response.js").JourneyResponse, { params, manageListQuestion }?: import("./question-types.js").PrepQuestionForRenderingOptions): Record<string, any>;
+    answerObjectFromJourneyResponse(response: import("../journey/journey-response.js").JourneyResponse, { params, manageListQuestion }?: import("#typedefs/question-types.d.ts").PrepQuestionForRenderingOptions): Record<string, any>;
     /**
      * renders the question
      * @param {import('express').Response} res - the express response
-     * @param {QuestionViewModel} viewModel additional data to send to view
+     * @param {import('#typedefs/question-types.d.ts').QuestionViewModel} viewModel additional data to send to view
      * @returns {void}
      */
-    renderAction(res: import("express").Response, viewModel: QuestionViewModel): void;
+    renderAction(res: import("express").Response, viewModel: import("#typedefs/question-types.d.ts").QuestionViewModel): void;
     /**
      * check for validation errors
      * @param {import('express').Request} req
      * @param {import('../journey/journey.js').Journey} journey
      * @param {import('../section.js').Section} section
      * @param {import('../components/manage-list/question.js')} [manageListQuestion]
-     * @returns {QuestionViewModel|undefined} returns the view model for displaying the error or undefined if there are no errors
+     * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel|undefined} returns the view model for displaying the error or undefined if there are no errors
      */
-    checkForValidationErrors(req: import("express").Request, section: import("../section.js").Section, journey: import("../journey/journey.js").Journey, manageListQuestion?: typeof import("../components/manage-list/question.js")): QuestionViewModel | undefined;
+    checkForValidationErrors(req: import("express").Request, section: import("../section.js").Section, journey: import("../journey/journey.js").Journey, manageListQuestion?: typeof import("../components/manage-list/question.js")): import("#typedefs/question-types.d.ts").QuestionViewModel | undefined;
     /**
      * Get the data to save from the request, returns an object of answers
      *
@@ -207,8 +185,8 @@ export class Question {
      * @param {import('express').Request} req
      * @param {import('../journey/journey.js').Journey} journey
      * @param {import('../section.js').Section} sectionObj
-     * @returns {QuestionViewModel | undefined} returns the view model for displaying the error or undefined if there are no errors
-     */ checkForSavingErrors(req: import("express").Request, sectionObj: import("../section.js").Section, journey: import("../journey/journey.js").Journey): QuestionViewModel | undefined;
+     * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel | undefined} returns the view model for displaying the error or undefined if there are no errors
+     */ checkForSavingErrors(req: import("express").Request, sectionObj: import("../section.js").Section, journey: import("../journey/journey.js").Journey): import("#typedefs/question-types.d.ts").QuestionViewModel | undefined;
     /**
      * Handles redirect after saving. Kept around for backwards compatibility.
      *
@@ -222,33 +200,35 @@ export class Question {
     handleNextQuestion(res: import("express").Response, journey: import("../journey/journey.js").Journey, sectionSegment: string, questionSegment: string): void;
     /**
      * returns the formatted answers values to be used to build task list elements
-     * @param {String} sectionSegment
+     * @param {string} sectionSegment
      * @param {import('../journey/journey.js').Journey} journey
      * @param {unknown} answer
-     * @returns {Array<{
-     *   key: string;
-     *   value: string | Object;
-     *   action?: ActionView | ActionView[];
-     * }>}
+     * @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): Array<{
-        key: string;
-        value: string | Object;
-        action?: ActionView | ActionView[];
-    }>;
+    formatAnswerForSummary(sectionSegment: string, journey: import("../journey/journey.js").Journey, answer: unknown, capitals?: boolean): import("#typedefs/question-types.d.ts").SummaryRow[];
     /**
      * Returns the action link for the question
-     * @param {unknown} answer
+     * @param {string} sectionSegment
      * @param {import('../journey/journey.js').Journey} journey
-     * @param {String} sectionSegment
-     * @returns {ActionView|ActionView[]|undefined}
+     * @param {unknown} answer
+     * @returns {import('#typedefs/question-types.d.ts').ActionView | import('#typedefs/question-types.d.ts').ActionView[] | undefined}
      */
-    getAction(sectionSegment: string, journey: import("../journey/journey.js").Journey, answer: unknown): ActionView | ActionView[] | undefined;
+    getAction(sectionSegment: string, journey: import("../journey/journey.js").Journey, answer: unknown): import("#typedefs/question-types.d.ts").ActionView | import("#typedefs/question-types.d.ts").ActionView[] | undefined;
     /**
      * @param {unknown} answer
      * @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}
      */
@@ -264,17 +244,6 @@ export class Question {
      * @returns {boolean}
      */
     isAnswered(journeyResponse: import("../journey/journey-response.js").JourneyResponse, fieldName?: string): boolean;
+    #private;
 }
-export type PreppedQuestion = {
-    value: Object;
-    question: string;
-    fieldName: string;
-    pageTitle: string;
-    description?: string | undefined;
-    html?: string | undefined;
-};
-export type QuestionViewModel = Record<string, any>;
-import type { BaseValidator } from "#base-validator";
-import type { ActionLink } from "./question-types.js";
-import type { ActionView } from "../controller.js";
 //# sourceMappingURL=question.d.ts.map

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

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

package/src/questions/question.js

@@ -3,35 +3,6 @@ import { capitalize, nl2br, trimTrailingSlash } from '../lib/utils.js';
 import MultiFieldInputValidator from '../validator/multi-field-input-validator.js';
 import { answerObjectForManageList } from '#src/components/manage-list/utils.js';
 
-/**
- * @import {BaseValidator} from "#base-validator"
- * @import {ActionView} from "../controller.js"
- * @import {ActionLink} from "./question-types.js"
- */
-
-/**
- * @typedef {Object} PreppedQuestion
- * @property {Object} value
- * @property {string} question
- * @property {string} fieldName
- * @property {string} pageTitle
- * @property {string} [description]
- * @property {string} [html]
- */
-
-/**
- * @typedef {Record<string, any>} QuestionViewModel
- * @property {PreppedQuestion} question
- * @property {string} layoutTemplate
- * @property {string} pageCaption
- * @property {string} [continueButtonText]
- * @property {string} backLink
- * @property {boolean} showBackToListLink
- * @property {string} listLink
- * @property {Object} util
- * @property {function(string): string} util.trimTrailingSlash
- */
-
 /**
  * A specific question within a journey which is made up of one (usually) or many (sometimes) components and their required content.
  * @class
@@ -51,7 +22,7 @@ export class Question {
 	fieldName;
 	/** @type {boolean} if the question should appear in the journey overview task list or not */
 	taskList = true;
-	/** @type {Array.<BaseValidator>} array of validators that a question uses to validate answers */
+	/** @type {Array.<import('../validator/base-validator.js').BaseValidator>} array of validators that a question uses to validate answers */
 	validators = [];
 	/** @type {string|undefined} hint text displayed to user */
 	hint;
@@ -63,11 +34,13 @@ export class Question {
 	html;
 	/** @type {string|undefined} optional question type */
 	interfaceType;
-	/** @type {ActionLink|undefined} override action link */
+	/** @type {import('#typedefs/question-types.d.ts').ActionLink|undefined} override action link */
 	actionLink;
 
 	/** @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 */
@@ -76,12 +49,15 @@ 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]
 	 * @returns {boolean}
 	 */
-	shouldDisplay = () => true;
+	// eslint-disable-next-line no-unused-vars -- response will be used by extending classes
+	shouldDisplay = (response) => true;
 
 	details = {
 		title: '',
@@ -97,7 +73,7 @@ export class Question {
 	_isInManageListSection = false;
 
 	/**
-	 * @param {import('./question-types.js').QuestionParameters} params
+	 * @param {import('#typedefs/question-types.d.ts').QuestionParameters} params
 	 * @param {Record<string, Function>} [methodOverrides]
 	 */
 	constructor(
@@ -117,7 +93,9 @@ export class Question {
 			autocomplete,
 			editable = true,
 			actionLink,
-			viewData = {}
+			viewData = {},
+			formatSummaryValue,
+			capitaliseAnswer = true
 		},
 		methodOverrides
 	) {
@@ -139,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;
@@ -181,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.
@@ -199,13 +191,13 @@ export class Question {
 	 * that prepQuestionForRendering doesn't need
 	 *
 	 * @param {Object} options
-	 * @param {import('../journey/journey-types.js').RouteParams} options.params
+	 * @param {import('#typedefs/journey-types.d.ts').RouteParams} options.params
 	 * @param {import('../components/manage-list/question.js')} [options.manageListQuestion]
 	 * @param {import('../section.js').Section} options.section - the current section
 	 * @param {import('../journey/journey.js').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}
+	 * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel}
 	 */
 	toViewModel({ params, manageListQuestion, section, journey, customViewData, payload }) {
 		const viewModel = this.prepQuestionForRendering(section, journey, customViewData, payload, {
@@ -223,8 +215,8 @@ export class Question {
 	 * @param {import('../journey/journey.js').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.js').PrepQuestionForRenderingOptions} [options] - required to support manage list question
-	 * @returns {QuestionViewModel}
+	 * @param {import('#typedefs/question-types.d.ts').PrepQuestionForRenderingOptions} [options] - required to support manage list question
+	 * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel}
 	 */
 	prepQuestionForRendering(section, journey, customViewData, payload, options) {
 		const answers = payload || this.answerObjectFromJourneyResponse(journey.response, options);
@@ -283,7 +275,7 @@ export class Question {
 	 *
 	 * If possible override this method instead of prepQuestionForRendering for simple changes to the view model
 	 *
-	 * @param {QuestionViewModel} viewModel
+	 * @param {import('#typedefs/question-types.d.ts').QuestionViewModel} viewModel
 	 */ // eslint-disable-next-line no-unused-vars
 	addCustomDataToViewModel(viewModel) {}
 
@@ -291,7 +283,7 @@ export class Question {
 	 * Get the answers object from the journey response, which may be nested in an array for manage list questions
 	 *
 	 * @param {import('../journey/journey-response.js').JourneyResponse} response
-	 * @param {import('./question-types.js').PrepQuestionForRenderingOptions} [options]
+	 * @param {import('#typedefs/question-types.d.ts').PrepQuestionForRenderingOptions} [options]
 	 * @returns {Record<string, any>}
 	 */
 	answerObjectFromJourneyResponse(response, { params, manageListQuestion } = {}) {
@@ -311,7 +303,7 @@ export class Question {
 	/**
 	 * renders the question
 	 * @param {import('express').Response} res - the express response
-	 * @param {QuestionViewModel} viewModel additional data to send to view
+	 * @param {import('#typedefs/question-types.d.ts').QuestionViewModel} viewModel additional data to send to view
 	 * @returns {void}
 	 */
 	renderAction(res, viewModel) {
@@ -329,7 +321,7 @@ export class Question {
 	 * @param {import('../journey/journey.js').Journey} journey
 	 * @param {import('../section.js').Section} section
 	 * @param {import('../components/manage-list/question.js')} [manageListQuestion]
-	 * @returns {QuestionViewModel|undefined} returns the view model for displaying the error or undefined if there are no errors
+	 * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel|undefined} returns the view model for displaying the error or undefined if there are no errors
 	 */
 	checkForValidationErrors(req, section, journey, manageListQuestion) {
 		const { body = {} } = req;
@@ -376,7 +368,7 @@ export class Question {
 	 * @param {import('express').Request} req
 	 * @param {import('../journey/journey.js').Journey} journey
 	 * @param {import('../section.js').Section} sectionObj
-	 * @returns {QuestionViewModel | undefined} returns the view model for displaying the error or undefined if there are no errors
+	 * @returns {import('#typedefs/question-types.d.ts').QuestionViewModel | undefined} returns the view model for displaying the error or undefined if there are no errors
 	 */ //eslint-disable-next-line no-unused-vars
 	checkForSavingErrors(req, sectionObj, journey) {
 		return;
@@ -401,34 +393,49 @@ export class Question {
 
 	/**
 	 * returns the formatted answers values to be used to build task list elements
-	 * @param {String} sectionSegment
+	 * @param {string} sectionSegment
 	 * @param {import('../journey/journey.js').Journey} journey
 	 * @param {unknown} answer
-	 * @returns {Array<{
-	 *   key: string;
-	 *   value: string | Object;
-	 *   action?: ActionView | ActionView[];
-	 * }>}
+	 * @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 }];
 	}
 
 	/**
 	 * Returns the action link for the question
-	 * @param {unknown} answer
+	 * @param {string} sectionSegment
 	 * @param {import('../journey/journey.js').Journey} journey
-	 * @param {String} sectionSegment
-	 * @returns {ActionView|ActionView[]|undefined}
+	 * @param {unknown} answer
+	 * @returns {import('#typedefs/question-types.d.ts').ActionView | import('#typedefs/question-types.d.ts').ActionView[] | undefined}
 	 */
 	getAction(sectionSegment, journey, answer) {
 		if (this.actionLink) {
@@ -459,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}
 	 */