@planning-inspectorate/dynamic-forms 3.16.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.16.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/address/question.d.ts

@@ -22,10 +22,6 @@ export class AddressQuestion extends Question {
      * @returns {*|string}
      */
     answerForViewModel(answers: Record<string, any>): any | string;
-    /**
-     * @param {import('#question').QuestionViewModel} viewModel
-     */
-    addCustomDataToViewModel(viewModel: import("#question").QuestionViewModel): void;
     /**
      * @param {Object<string, any>} answer
      * @returns The formatted address to be presented in the UI
@@ -36,11 +32,7 @@ export class AddressQuestion extends Question {
     /**
      * returns the formatted answers values to be used to build task list elements
      */
-    formatAnswerForSummary(sectionSegment: any, journey: any, answer: any): {
-        key: string;
-        value: string;
-        action: import("../../index.js").ActionView | import("../../index.js").ActionView[] | undefined;
-    }[];
+    formatAnswer(answer: any): string;
     formatLabelFromRequiredFields(fieldName: any): "" | " (optional)";
 }
 export default AddressQuestion;

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

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAOA;IACC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,yBAAyB,EAqB3E;IAXE;;;;;;kBAA8C;IAIhD;;;;;;MAMC;IAiBF;;;OAGG;IACH,4BAHW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjB,GAAC,GAAC,MAAM,CAqBpB;IAED;;OAEG;IACH,oCAFW,OAAO,WAAW,EAAE,iBAAiB,QAI/C;IA8BD;;;OAGG;IACH;;eAUC;IAED;;OAEG;IACH;;;;QAgBC;IACD,kEAMC;CACD;;yBArJwB,WAAW"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAOA;IACC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,yBAAyB,EAqB3E;IAXE;;;;;;kBAA8C;IAIhD;;;;;;MAMC;IAiBF;;;OAGG;IACH,4BAHW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjB,GAAC,GAAC,MAAM,CAqBpB;IAqCD;;;OAGG;IACH;;eAUC;IAED;;OAEG;IACH,kCAIC;IAED,kEAMC;CACD;;yBA1IwB,WAAW"}

package/src/components/address/question.js

@@ -70,7 +70,7 @@ export class AddressQuestion extends Question {
 	}
 
 	/**
-	 * @param {import('#question').QuestionViewModel} viewModel
+	 * @param {import('#typedefs/question-types.d.ts').QuestionViewModel} viewModel
 	 */
 	addCustomDataToViewModel(viewModel) {
 		viewModel.question.labels = this.addressLabels;
@@ -123,23 +123,12 @@ export class AddressQuestion extends Question {
 	/**
 	 * returns the formatted answers values to be used to build task list elements
 	 */
-	formatAnswerForSummary(sectionSegment, journey, answer) {
-		let formattedAnswer = this.notStartedText;
-
-		if (answer) {
-			formattedAnswer = nl2br(escape(this.format(answer)));
-		} else if (answer === null) {
-			formattedAnswer = '';
-		}
-
-		return [
-			{
-				key: `${this.title}`,
-				value: formattedAnswer,
-				action: this.getAction(sectionSegment, journey, answer)
-			}
-		];
+	formatAnswer(answer) {
+		if (answer === null) return '';
+		if (!answer) return this.notStartedText;
+		return nl2br(escape(this.format(answer)));
 	}
+
 	formatLabelFromRequiredFields(fieldName) {
 		if (this.requiredFields && this.requiredFields[fieldName]) {
 			return '';

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

@@ -1,29 +1,9 @@
-/**
- * @typedef ConditionalAnswerObject
- * @type {object}
- * @property {string} value the checkbox answer
- * @property {string} conditional the conditional text input
- */
 export class CheckboxQuestion extends OptionsQuestion {
     /**
      * @param {import('#typedefs/question-props.d.ts').CheckboxQuestionParams} params
      */
-    constructor({ title, question, fieldName, url, pageTitle, description, options, validators, viewData }: import("#typedefs/question-props.d.ts").CheckboxQuestionParams);
-    /**
-     * returns the formatted answers values to be used to build task list elements
-     */
-    formatAnswerForSummary(sectionSegment: any, journey: any, answer: any): import("../../index.js").SummaryRow[];
+    constructor({ ...parentParams }: import("#typedefs/question-props.d.ts").CheckboxQuestionParams);
 }
 export default CheckboxQuestion;
-export type ConditionalAnswerObject = {
-    /**
-     * the checkbox answer
-     */
-    value: string;
-    /**
-     * the conditional text input
-     */
-    conditional: string;
-};
 import OptionsQuestion from '../../questions/options-question.js';
 //# sourceMappingURL=question.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH;IACC;;OAEG;IACH,wGAFW,OAAO,+BAA+B,EAAE,sBAAsB,EAiBxE;IAED;;OAEG;IACH,8GAqCC;CACD;;;;;;WAlEa,MAAM;;;;iBACN,MAAM;;4BATQ,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

@@ -1,76 +1,64 @@
+import escape from 'escape-html';
 import OptionsQuestion from '../../questions/options-question.js';
-import questionUtils from '../utils/question-utils.js';
 
 const defaultOptionJoinString = ',';
 
-/**
- * @typedef ConditionalAnswerObject
- * @type {object}
- * @property {string} value the checkbox answer
- * @property {string} conditional the conditional text input
- */
-
 export class CheckboxQuestion extends OptionsQuestion {
 	/**
 	 * @param {import('#typedefs/question-props.d.ts').CheckboxQuestionParams} params
 	 */
-	constructor({ title, question, fieldName, url, pageTitle, description, options, validators, viewData }) {
+	constructor({ ...parentParams }) {
 		super({
-			title,
-			question,
-			viewFolder: 'checkbox',
-			fieldName,
-			url,
-			pageTitle,
-			description,
-			options,
-			validators,
-			viewData
+			// default but allow overrides
+			capitaliseAnswer: false,
+			...parentParams,
+			viewFolder: 'checkbox'
 		});
 
 		this.optionJoinString = defaultOptionJoinString;
 	}
 
 	/**
-	 * returns the formatted answers values to be used to build task list elements
+	 * Formats an answer value for display in the summary.
+	 * Handles object answers with conditional fields.
+	 * - Single value with conditional: { value: 'yes', conditional: { yes: 'details' } }
+	 * - Multiple values with conditionals: { value: 'yes,no', conditional: { yes: 'details1', no: 'details2' } }
+	 *
+	 * @param {unknown} answer - the raw answer value
+	 * @returns {string} the formatted answer for display
 	 */
-	formatAnswerForSummary(sectionSegment, journey, answer) {
-		if (!answer) {
-			return super.formatAnswerForSummary(sectionSegment, journey, answer, false);
+	formatAnswer(answer) {
+		if (answer === null || answer === undefined || answer === '') {
+			return this.notStartedText;
 		}
 
-		// answer is single ConditionalAnswerObject
-		if (answer?.conditional) {
-			const selectedOption = this.options.find((option) => option.value === answer.value);
-
-			const conditionalAnswerText = selectedOption.conditional?.label
-				? `${selectedOption.conditional.label} ${answer.conditional}`
-				: answer.conditional;
-
-			const formattedConditionalText = [selectedOption.text, conditionalAnswerText].join('\n');
-
-			return super.formatAnswerForSummary(sectionSegment, journey, formattedConditionalText, false);
+		// Handle simple string answers (e.g. '1,2')
+		if (typeof answer !== 'object' || answer.value === undefined) {
+			return super.formatAnswer(answer);
 		}
 
-		// answer is a string
-		const answerArray = answer.split(this.optionJoinString);
+		// Handle object answers with conditional fields
+		// TODO DF-51 treat as an array
+		const answerValues = String(answer.value)
+			.split(this.optionJoinString)
+			.map((v) => v.trim());
+		const conditionals = answer.conditional || {};
+
+		const formattedParts = answerValues.map((value) => {
+			const option = this.options.find((opt) => opt.value === value);
+			const optionText = escape(option ? option.text : value);
 
-		const formattedAnswer = this.options
-			.filter((option) => answerArray.includes(option.value))
-			.map((option) => {
-				if (option.conditional) {
-					const conditionalAnswer =
-						journey.response.answers[
-							questionUtils.getConditionalFieldName(this.fieldName, option.conditional.fieldName)
-						];
-					return [option.text, conditionalAnswer].join('\n');
-				}
+			// Check if this option has a conditional answer
+			const conditionalValue = conditionals[value];
+			if (conditionalValue) {
+				const label = option?.conditional?.label ? `${escape(option.conditional.label)} ` : '';
+				return `${optionText}<br>${label}${escape(conditionalValue)}`;
+			}
 
-				return option.text;
-			})
-			.join('\n');
+			return optionText;
+		});
 
-		return super.formatAnswerForSummary(sectionSegment, journey, formattedAnswer, false);
+		return formattedParts.join('<br>');
 	}
 }