@planning-inspectorate/dynamic-forms 3.17.0 → 3.18.0

package/docs/Getting Started.md

@@ -0,0 +1,299 @@
+# Getting started
+
+Follow these steps to get started using Dynamic Forms. This guide assumes you have a [Node.js project](https://nodejs.org/) setup with [npm](https://www.npmjs.com/), [expressjs](https://expressjs.com/), [Nunjucks](https://mozilla.github.io/nunjucks/), and the [GOV.UK frontend](https://design-system.service.gov.uk/) already.
+
+## Step 1 - add the package dependency
+
+Add dynamic-forms to your project with npm:
+
+`npm install --save @planning-inspectorate/dynamic-forms`
+
+If you are using the select component with [accessible-autocomplete](https://www.npmjs.com/package/accessible-autocomplete), also install this:
+
+`npm install --save accessible-autocomplete`
+
+## Step 2 - configure the dynamic forms root for Nunjucks
+
+So that the nunjucks rendered can resolve the dynamic forms components, add the root to the nunjucks configuration. For example:
+
+```typescript
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import nunjucks from 'nunjucks';
+
+export function configureNunjucks() {
+	// get the require function, see https://nodejs.org/api/module.html#modulecreaterequirefilename
+	const require = createRequire(import.meta.url);
+	// path to dynamic forms folder
+	const dynamicFormsRoot = path.resolve(require.resolve('@planning-inspectorate/dynamic-forms'), '..');
+	// get the path to the govuk-frontend folder, in node_modules, using the node require resolution
+	const govukFrontendRoot = path.resolve(require.resolve('govuk-frontend'), '../..');
+	const appDir = path.join('some/path/to/the', 'app');
+
+	// configure nunjucks
+	return nunjucks.configure(
+		// ensure nunjucks templates can use govuk-frontend components, and templates we've defined
+		[dynamicFormsRoot, govukFrontendRoot, appDir],
+		{
+			// output with dangerous characters are escaped automatically
+			autoescape: true,
+			// automatically remove trailing newlines from a block/tag
+			trimBlocks: true,
+			// automatically remove leading whitespace from a block/tag
+			lstripBlocks: true
+		}
+	);
+}
+```
+
+## Step 3 - add required assets
+
+The select component can use the [accessible-autocomplete](https://www.npmjs.com/package/accessible-autocomplete) package. This requires configuring, the component assumes the following paths are available:
+
+- `/assets/css/accessible-autocomplete.min.css`
+- `/assets/js/accessible-autocomplete.min.js`
+
+If you have a build step for static assets, copy the accessible-autocomplete assets into the static folder. For example:
+
+```typescript
+/**
+ * Copy accessible-autocomplete assets into the static folder
+ */
+async function copyAutocompleteAssets({ staticDir, root }: AutocompleteOptions): Promise<void> {
+	const js = path.join(root, 'accessible-autocomplete.min.js');
+	const css = path.join(root, 'accessible-autocomplete.min.css');
+
+	const staticJs = path.join(staticDir, 'assets', 'js', 'accessible-autocomplete.min.js');
+	const staticCss = path.join(staticDir, 'assets', 'css', 'accessible-autocomplete.min.css');
+
+	await copyFile(js, staticJs);
+	await copyFile(css, staticCss);
+}
+```
+
+## Step 4 - add the question and check-your-answers templates
+
+Dynamic forms requires two templates to work for rendering questions and rendering check-your-answers page. Different journeys can use different templates if required, but usually they can be shared.
+
+### Journey (or question) template
+
+The journey template is used for question pages. It must include a block called `dynQuestionContent`, and a block called `head` (which the default gov.uk template has).
+It should also include the rendering of the errorSummary component. The path to this template is configured via the `journeyTemplate` property on a Journey.
+
+For example:
+
+e.g.
+
+```nunjucks
+{% extends "govuk/template.njk" %}
+
+{% block beforeContent %}
+    {% if errorSummary %}
+        <div class="govuk-grid-row">
+            <div class="govuk-grid-column-two-thirds">
+                {{ govukErrorSummary({
+                    titleText: "There is a problem",
+                    errorList: errorSummary,
+                    attributes: {"data-cy": "error-wrapper"}
+                }) }}
+            </div>
+        </div>
+    {% endif %}
+{% endblock %}
+
+{% block content %}
+    <div class="govuk-grid-row">
+        <div class="govuk-grid-column-full">
+            <h1 class="govuk-heading-xl">
+                {% if pageCaption %}
+                    <span class="govuk-caption-xl">{{ pageCaption }}</span>
+                {% endif %}
+                {{ pageHeading }}
+            </h1>
+        </div>
+    </div>
+
+    {% block dynQuestionContent %}{% endblock %}
+{% endblock %}
+```
+
+### Task list (or check your answers) template
+
+The task list template is used for the task list or "check your answers" page. It must include a block called `dynTaskList`. The path to this template is configured via the `taskListTemplate` property on a Journey.
+
+e.g.
+
+```nunjucks
+{% extends "govuk/template.njk" %}
+
+{% block content %}
+    <div class="govuk-grid-row">
+        <div class="govuk-grid-column-full">
+            <h1 class="govuk-heading-xl">
+                {% if pageCaption %}
+                    <span class="govuk-caption-xl">{{ pageCaption }}</span>
+                {% endif %}
+                {{ pageHeading }}
+            </h1>
+        </div>
+    </div>
+
+    {% block dynTaskList %}{% endblock %}
+{% endblock %}
+```
+
+## Step 5 - add questions, journeys, and routes
+
+Now you are ready to implement any user journeys for your service. Add questions, journeys, and routes for each of them.
+
+For example:
+
+`questions.ts`
+
+Use `satisfies Record<string, QuestionProps>` to get autocomplete for available question props specific for each component type.
+
+```typescript
+import {
+	COMPONENT_TYPES,
+	createQuestions,
+	questionClasses,
+	RequiredValidator
+} from '@planning-inspectorate/dynamic-forms';
+import type { QuestionProps } from '@planning-inspectorate/dynamic-forms';
+
+export const questionProps = {
+	destinationType: {
+		type: COMPONENT_TYPES.RADIO,
+		title: 'Destination type',
+		question: 'Which sort of place would you like to visit?',
+		fieldName: 'destinationType',
+		url: 'destination-type',
+		options: [
+			{ value: 'beach', text: 'Beach' },
+			{ value: 'mountains', text: 'Mountains' },
+			{ value: 'city', text: 'City' }
+		],
+		validators: [new RequiredValidator('Select a destination type')]
+	},
+	nights: {
+		type: COMPONENT_TYPES.NUMBER,
+		title: 'Number of Nights',
+		question: 'How many nights will you stay on holiday?',
+		fieldName: 'nights',
+		url: 'nights',
+		label: 'Nights'
+	}
+} satisfies Record<string, QuestionProps>;
+
+export function getQuestions() {
+	return createQuestions(questionProps, questionClasses, {}, {});
+}
+
+export type Questions = ReturnType<typeof getQuestions>;
+```
+
+`journey.ts`
+
+```typescript
+import {
+	BOOLEAN_OPTIONS,
+	Journey,
+	type JourneyResponse,
+	Section,
+	whenQuestionHasAnswer
+} from '@planning-inspectorate/dynamic-forms';
+import type { Request } from 'express';
+import type { Questions } from './questions.ts';
+
+export const JOURNEY_ID = 'holidays';
+
+export function createJourney(req: Request, response: JourneyResponse, questions: Questions) {
+	return new Journey({
+		journeyId: JOURNEY_ID,
+		sections: [
+			new Section('Questions', 'questions').addQuestion(questions.destinationType).addQuestion(questions.nights)
+		],
+		taskListUrl: 'check-your-answers',
+		journeyTemplate: 'views/layouts/question.njk',
+		taskListTemplate: 'views/layouts/check-your-answers.njk',
+		journeyTitle: 'Holidays',
+		returnToListing: false,
+		makeBaseUrl: () => req.baseUrl,
+		initialBackLink: '/',
+		response
+	});
+}
+```
+
+`index.ts`
+
+```typescript
+import { Router as createRouter } from 'express';
+import type { IRouter } from 'express';
+import {
+	buildGetJourney,
+	buildGetJourneyResponseFromSession,
+	buildList,
+	buildSave,
+	question,
+	saveDataToSession,
+	validate,
+	validationErrorHandler
+} from '@planning-inspectorate/dynamic-forms';
+import { createJourney, JOURNEY_ID } from './journey.ts';
+import { getQuestions } from './questions.ts';
+
+export function createRoutes(): IRouter {
+	const router = createRouter({ mergeParams: true });
+
+	const questions = getQuestions();
+	const getJourneyResponse = buildGetJourneyResponseFromSession(JOURNEY_ID);
+	const getJourney = buildGetJourney((req, journeyResponse) => createJourney(req, journeyResponse, questions));
+
+	router.use(getJourneyResponse, getJourney);
+
+	// route for rendering each question
+	router.get('/:section/:question', question);
+	// route for saving each answer (to session)
+	router.post('/:section/:question', validate, validationErrorHandler, buildSave(saveDataToSession));
+
+	// route for check-your-answers page
+	router.get('/check-your-answers', buildList());
+	// route for saving all answers
+	router.post('/check-your-answers', (req, res) => {
+		const answers = res.locals?.journeyResponse?.answers as JourneyAnswers;
+		if (typeof answers !== 'object' || answers === null) {
+			throw new Error('answers should be an object');
+		}
+		console.log('answers', answers);
+		// TODO: save to a database or similar!
+		res.redirect('/');
+	});
+
+	return router;
+}
+
+interface JourneyAnswers {
+	destinationType: string;
+	nights: number;
+}
+```
+
+`router.ts`
+
+```typescript
+import type { IRouter } from 'express';
+import { Router as createRouter } from 'express';
+import { viewHomepage } from './views/home/controller.ts';
+import { createRoutes as createHolidayRoutes } from './views/holidays/index.ts';
+
+export function buildRouter(): IRouter {
+	const router = createRouter();
+
+	router.route('/').get(viewHomepage);
+
+	router.use('/holidays', createHolidayRoutes());
+
+	return router;
+}
+```

package/package.json

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

package/src/components/checkbox/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAKA;IACC;;OAEG;IACH,iCAFW,OAAO,+BAA+B,EAAE,sBAAsB,EAUxE;CA4CD;;4BA5D2B,qCAAqC"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAKA;IACC;;OAEG;IACH,iCAFW,OAAO,+BAA+B,EAAE,sBAAsB,EAWxE;CA4CD;;4BA7D2B,qCAAqC"}

package/src/components/checkbox/question.js

@@ -9,9 +9,10 @@ export class CheckboxQuestion extends OptionsQuestion {
 	 */
 	constructor({ ...parentParams }) {
 		super({
+			// default but allow overrides
+			capitaliseAnswer: false,
 			...parentParams,
-			viewFolder: 'checkbox',
-			capitaliseAnswer: false
+			viewFolder: 'checkbox'
 		});
 
 		this.optionJoinString = defaultOptionJoinString;

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

@@ -53,6 +53,14 @@ describe('./src/dynamic-forms/components/checkbox/question.js', () => {
 		assert.deepStrictEqual(question.validators, [...VALIDATORS, new ValidOptionValidator()]);
 		assert.deepStrictEqual(question.options, OPTIONS);
 	});
+	it('should allow capitaliseAnswer override', () => {
+		const question = new CheckboxQuestion({
+			...CHECKBOX_PARAMS,
+			capitaliseAnswer: true
+		});
+
+		assert.strictEqual(question.capitaliseAnswer, true);
+	});
 
 	describe('formatAnswer', () => {
 		it('should delegate simple string answers to parent class', () => {

package/src/components/email/question.d.ts

@@ -8,15 +8,6 @@ export class EmailQuestion extends SingleLineInputQuestion {
      * @param {import('#typedefs/question-props.d.ts').EmailQuestionParams} params
      */
     constructor(params: import("#typedefs/question-props.d.ts").EmailQuestionParams);
-    /**
-     * Override formatAnswerForSummary to prevent capitalization of email addresses
-     * Email addresses should remain in their original case (typically lowercase)
-     * @param {string} sectionSegment
-     * @param {import('#journey').Journey} journey
-     * @param {string} answer
-     * @returns {Array}
-     */
-    formatAnswerForSummary(sectionSegment: string, journey: import("#journey").Journey, answer: string): any[];
 }
 export default EmailQuestion;
 import SingleLineInputQuestion from '../single-line-input/question.js';

package/src/components/email/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH;IACC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,mBAAmB,EAmBrE;IAED;;;;;;;OAOG;IACH,uCALW,MAAM,WACN,OAAO,UAAU,EAAE,OAAO,UAC1B,MAAM,SAMhB;CACD;;oCA1CmC,kCAAkC"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH;IACC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,mBAAmB,EAqBrE;CACD;;oCA/BmC,kCAAkC"}

package/src/components/email/question.js

@@ -21,25 +21,14 @@ export class EmailQuestion extends SingleLineInputQuestion {
 		const autocomplete = params.autocomplete || 'email';
 
 		super({
+			// Prevent capitalisation of email answers by default, but allow override
+			capitaliseAnswer: false,
 			...params,
 			viewFolder: 'single-line-input', // Reuse single-line-input template
 			inputAttributes: emailInputAttributes,
 			autocomplete: autocomplete
 		});
 	}
-
-	/**
-	 * Override formatAnswerForSummary to prevent capitalization of email addresses
-	 * Email addresses should remain in their original case (typically lowercase)
-	 * @param {string} sectionSegment
-	 * @param {import('#journey').Journey} journey
-	 * @param {string} answer
-	 * @returns {Array}
-	 */
-	formatAnswerForSummary(sectionSegment, journey, answer) {
-		// Call parent method with capitals=false to prevent email capitalization
-		return super.formatAnswerForSummary(sectionSegment, journey, answer, false);
-	}
 }
 
 export default EmailQuestion;

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

@@ -16,6 +16,25 @@ describe('src/dynamic-forms/components/email/question.js', () => {
 		assert.strictEqual(emailQuestion.autocomplete, 'email');
 	});
 
+	it('should default capitaliseAnswer to false', () => {
+		const emailQuestion = new EmailQuestion({
+			title: 'Email Address',
+			question: 'What is your email address?',
+			fieldName: 'email'
+		});
+		assert.strictEqual(emailQuestion.capitaliseAnswer, false);
+	});
+
+	it('should allow capitaliseAnswer to be set via constructor', () => {
+		const emailQuestion = new EmailQuestion({
+			title: 'Email Address',
+			question: 'What is your email address?',
+			fieldName: 'email',
+			capitaliseAnswer: true
+		});
+		assert.strictEqual(emailQuestion.capitaliseAnswer, true);
+	});
+
 	it('should allow custom input attributes while preserving email defaults', () => {
 		const customAttributes = {
 			placeholder: 'Enter your email',

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

@@ -14,6 +14,7 @@ export class MultiFieldInputQuestion extends Question {
         formatJoinString?: string;
         formatPrefix?: string;
         formatTextFunction?: (text: string) => string;
+        formatSummaryValue?: (context: import("#typedefs/question-props.d.ts").InputFieldSummaryContext) => string;
         attributes?: Record<string, string>;
         suffix?: import("#typedefs/question-props.d.ts").Affix;
         prefix?: import("#typedefs/question-props.d.ts").Affix;
@@ -24,27 +25,11 @@ export class MultiFieldInputQuestion extends Question {
     }[];
     /**
      * returns the formatted answers values to be used to build task list elements
-     * @param {import('#journey').Journey} journey
      * @param {string} sectionSegment
-     * @returns {Array<{
-     *   key: string;
-     *   value: string | Object;
-     *   action: {
-     *     href: string;
-     *     text: string;
-     *     visuallyHiddenText: string;
-     *   };
-     * }>}
+     * @param {import('#journey').Journey} journey
+     * @returns {import('#typedefs/question-types.d.ts').SummaryRow[]}
      */
-    formatAnswerForSummary(sectionSegment: string, journey: import("#journey").Journey): Array<{
-        key: string;
-        value: string | Object;
-        action: {
-            href: string;
-            text: string;
-            visuallyHiddenText: string;
-        };
-    }>;
+    formatAnswerForSummary(sectionSegment: string, journey: import("#journey").Journey): import("#typedefs/question-types.d.ts").SummaryRow[];
     #private;
 }
 export default MultiFieldInputQuestion;

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,EAa/E;IAJC,kEAA8B;IAchC;;;;;;;;;;;;;;QAOC;IAsBD;;;;;;;;;;;;;OAaG;IACH,uCAXW,MAAM,WADN,OAAO,UAAU,EAAE,OAAO,GAExB,KAAK,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,MAAM,EAAE;YACN,IAAI,EAAE,MAAM,CAAC;YACb,IAAI,EAAE,MAAM,CAAC;YACb,kBAAkB,EAAE,MAAM,CAAC;SAC5B,CAAC;KACH,CAAC,CAkBJ;;CAyBD;;yBApHwB,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,CAuChE;;CAsDD;;yBAtLwB,WAAW"}

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

@@ -1,6 +1,6 @@
 import { Question } from '#question';
 import escape from 'escape-html';
-import { nl2br } from '../../lib/utils.js';
+import { capitalize, nl2br } from '../../lib/utils.js';
 
 /**
  * @class
@@ -11,6 +11,8 @@ export class MultiFieldInputQuestion extends Question {
 	 */
 	constructor({ inputFields, ...parentParams }) {
 		super({
+			// default but allow overrides
+			capitaliseAnswer: false,
 			...parentParams,
 			viewFolder: 'multi-field-input'
 		});
@@ -59,36 +61,100 @@ export class MultiFieldInputQuestion extends Question {
 		return { answers };
 	}
 
+	/**
+	 * Formats an answer value for display in the summary.
+	 * Handles the ManageListSection edge case where nl2br should not be applied.
+	 *
+	 * @param {unknown} answer - the raw answer value (composed from multiple fields)
+	 * @returns {string} the formatted answer for display
+	 */
+	formatAnswer(answer) {
+		// Only show notStartedText for null/undefined, not for empty string
+		if (answer === null || answer === undefined) return this.notStartedText;
+		if (answer === '') return '';
+
+		// Coerce to string and apply optional capitalisation
+		let formatted = String(answer);
+		if (this.capitaliseAnswer) {
+			formatted = capitalize(formatted);
+		}
+
+		// Do not convert new lines to breaks in ManageListSection, as this causes a "doubled up" <br>
+		return this.isInManageListSection ? escape(formatted) : nl2br(escape(formatted));
+	}
+
 	/**
 	 * returns the formatted answers values to be used to build task list elements
-	 * @param {import('#journey').Journey} journey
 	 * @param {string} sectionSegment
-	 * @returns {Array<{
-	 *   key: string;
-	 *   value: string | Object;
-	 *   action: {
-	 *     href: string;
-	 *     text: string;
-	 *     visuallyHiddenText: string;
-	 *   };
-	 * }>}
+	 * @param {import('#journey').Journey} journey
+	 * @returns {import('#typedefs/question-types.d.ts').SummaryRow[]}
 	 */
 	formatAnswerForSummary(sectionSegment, journey) {
-		const summaryDetails = this.inputFields.reduce((acc, field) => {
-			const answer = this.#formatValue(journey.response.answers[field.fieldName], field.formatTextFunction);
-			return answer ? acc + (field.formatPrefix || '') + answer + (field.formatJoinString || '\n') : acc;
+		// Handle unanswered case - delegate to parent for notStartedText
+		if (this.#allQuestionsUnanswered(journey)) {
+			return super.formatAnswerForSummary(sectionSegment, journey, null);
+		}
+
+		// Default join string depends on context
+		const defaultJoinString = this.isInManageListSection ? '\n' : '<br>';
+
+		let summaryDetails = this.inputFields.reduce((accumulator, field) => {
+			const rawAnswer = journey.response.answers[field.fieldName];
+			if (rawAnswer === undefined || rawAnswer === null || rawAnswer === '') return accumulator;
+
+			const formatted = this.#formatFieldForSummary(rawAnswer, field, journey, sectionSegment);
+			return accumulator + (field.formatPrefix || '') + formatted + (field.formatJoinString ?? defaultJoinString);
 		}, '');
 
-		const formattedAnswer = this.#allQuestionsUnanswered(journey) ? this.notStartedText : summaryDetails || '';
+		// Remove trailing join string
+		if (summaryDetails.endsWith(defaultJoinString)) {
+			summaryDetails = summaryDetails.slice(0, -defaultJoinString.length);
+		}
 
-		return [
-			{
-				key: `${this.title}`,
-				// Do not convert new lines to breaks in ManageListSection, as this causes a "doubled up" <br>
-				value: this.isInManageListSection ? escape(formattedAnswer) : nl2br(escape(formattedAnswer)),
-				action: this.getAction(sectionSegment, journey, summaryDetails)
-			}
-		];
+		// Apply question-level formatSummaryValue if provided
+		const displayValue = this.formatSummaryValue
+			? this.formatSummaryValue({
+					answer: summaryDetails,
+					formattedAnswer: summaryDetails,
+					question: this,
+					journey,
+					sectionSegment
+				})
+			: summaryDetails;
+
+		// Build result directly - escaping already handled per-field
+		const action = this.getAction(sectionSegment, journey, summaryDetails);
+		const key = this.title ?? this.question;
+		return [{ key, value: displayValue || '', action }];
+	}
+
+	/**
+	 * Formats a single field value for summary display
+	 * @param {unknown} answer - the raw answer value
+	 * @param {import('#typedefs/question-props.d.ts').InputField} field - the input field config
+	 * @param {import('#journey').Journey} journey - the journey instance
+	 * @param {string} sectionSegment - the section segment
+	 * @returns {string}
+	 */
+	#formatFieldForSummary(answer, field, journey, sectionSegment) {
+		// Apply formatTextFunction (if provided) before escaping, same as answerForViewModel
+		const textFormattedAnswer = this.#formatValue(answer, field.formatTextFunction);
+		const formattedAnswer = escape(String(textFormattedAnswer));
+
+		// If formatSummaryValue is provided, use it with full context (output is not escaped)
+		if (typeof field.formatSummaryValue === 'function') {
+			return field.formatSummaryValue({
+				answer,
+				formattedAnswer,
+				question: this,
+				journey,
+				sectionSegment,
+				field
+			});
+		}
+
+		// Default: escaped, formatTextFunction-applied value
+		return formattedAnswer;
 	}
 
 	/**