@planning-inspectorate/dynamic-forms 3.17.0 → 3.18.0

package/README.md

@@ -1,142 +1,86 @@
 # Dynamics Forms
 
-This package is for building [GDS](https://design-system.service.gov.uk/) forms using a configuration-based approach. It allows you to define a set of questions, and combine them into journeys. Questions can be configured to be included conditionally, based on the answers to other questions.
+This package is for building [GOV.UK Frontend](https://design-system.service.gov.uk/) forms using a configuration-based approach. It allows you to define a set of questions, and combine them into journeys. Questions can be configured to be included conditionally, based on the answers to other questions.
 
-The functionality for 'check-your-answers' pages can also be useful for generating pages outside the context of a journey or form, such as for managing data. Each row shown on the page can include a link to edit that data.
+The functionality for ['check-your-answers'](https://design-system.service.gov.uk/patterns/check-answers/) pages can also be useful for generating pages outside the context of a journey or form, such as for managing data. Each row shown on the page can include a link to edit that data.
 
 > Note this is ported from Appeals: [dynamic forms](https://github.com/Planning-Inspectorate/appeal-planning-decision/tree/a46f945047dc1f13d523a0853b4fcbb4bd0f6d6e/packages/forms-web-app/src/dynamic-forms), but transformed for ES6 modules and Node Test Runner. Not all functionality has been brought across, such as 'add more'.
 > It is hoped that this version can be developed over time so Appeals can move to this version.
 
+## Getting started
+
+In summary:
+
+1. Install the package: `npm install --save @planning-inspectorate/dynamic-forms`
+2. Configure nunjucks
+3. (optional) Configure accessible-autocomplete
+4. Add the question and check-your-answers templates
+5. Configure questions, journeys, and routes
+
+For more details, see the [Getting started](./docs/Getting%20Started.md) guide.
+
 ## Terminology
 
-- Component - A "blueprint" of a type of question. i.e. input, radio button, checkbox etc.
-- Question - A specific question within a journey which is made up of one (usually) or many (sometimes) components and
-  their required content.
-- Section - A group of Questions
-- Journey - An entire set of questions required for a completion of a submission
-- Answer - Data input by a user against a specific Question.
-- Response - a collection of answers submitted as part of a Journey.
-- Validation - Verification that an individual Answer meets the criteria of that Question. i.e. String is greater than 3
-  characters.
+| Term       | Description                                                                                                          |
+|------------|----------------------------------------------------------------------------------------------------------------------|
+| Component  | A reusable part of a user interface. Usually forming the main content of a page in the context of a user journey.    |
+| Question   | An instantiated component with associated configuration, a specific question within a journey                        |
+| Section    | A group of questions, configured with any conditional logic                                                          |
+| Journey    | An entire set of questions and sections which make up a user journey                                                 |
+| Answer     | Data input by a user against a specific Question                                                                     |
+| Response   | A collection of answers submitted as part of a Journey                                                               |
+| Validation | Verification that an individual Answer meets the criteria of that Question. i.e. String is greater than 3 characters |
 
-## Requirements
+## Usage
 
-To use this package nunjucks must be configured so that the component view files are available, and static assets must be made available for certain components and styling. Some nunjucks templates are required to correctly render the question pages and task list views.
+The test directory includes a very basic journey in `test/journey.js`. This may be a useful guide for setting up a journey and associated questions. Also in `test/questions.test.js` there is a function `createAppWithQuestions` which may be a useful guide for setting up the appropriate controllers and routes for a journey.
 
-### Nunjucks
+All exports are named exports from the root module:
 
-Nunjucks template paths needs configuring with the govuk-frontend and the dynamic forms folder, e.g.
+`import {COMPONENT_TYPES} from '@planning-inspectorate/dynamic-forms`
 
-```javascript
-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 in `web/src/app`
-		[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
-		}
-	);
-}
+### Components
 
-```
+Components available are exported via the `COMPONENT_TYPES` constant. 
 
-### 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`
-
-### Layouts
-
-There are two layout files that need to be configured for dynamic-forms: journey and task list.
-
-**Journey 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.
-
-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 %}
-```
+#### Custom components
+
+Components can be created and used with Dynamic Forms with some configuration. Extend the base `Question` class. 
+
+1. Ensure nunjucks is configured with the folder containing your custom components
+2. Export the custom component type names and classes
+3. Merge the exported question classes object with the custom classes
+
+See also [Contributing > new components](#new-components)
 
-**Task list 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 %}
+### Controllers
+
+Dynamic forms includes several Express handlers/controllers which implement the core logic. They all have prerequisites and expect particular properties have been added to the `res.locals` object. These are:
+
+* `res.locals.journey` must be an instance of the `Journey` class
+* `res.locals.journeyResponse` must be an instance of the `JourneyResponse` class
+
+They can be added using middleware, and utility functions are available for this, for example:
+
+```typescript
+  // get the answers from the session, and add JourneyResponse to `res.locals`
+  const getJourneyResponse = buildGetJourneyResponseFromSession(JOURNEY_ID);
+  // create the journey with the given journeyResponse and questions, and add to `res.locals`
+  const getJourney = buildGetJourney((req, journeyResponse) => createJourney(req, journeyResponse, questions));
+  
+  router.use(
+          getJourneyResponse,
+          getJourney
+  );
 ```
 
-## Usage
+The controllers available are:
 
-The test directory includes a very basic journey in `test/journey.js`. This may be a useful guide for setting up a journey and associated questions. Also in `test/questions.test.js` there is a function `createAppWithQuestions` which may be a useful guide for setting up the appropriate controllers and routes for a journey.
+| Controller     | Purpose                                                                                                                                                         |
+|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| question       | To render a question page as part of a journey                                                                                                                  |
+| buildSave      | Returns a controller to handle saving the answer and either redirecting to the next question or show any validation errors if present. Accepts a save function. |
+| list/buildList | Renders a check-your-answers page showing all the answers, links to change any answer, and a button to submit the answers.                                      |
 
 ### Conditions
 
@@ -199,92 +143,9 @@ These conditions combine with individual conditions and section conditions. In t
 | q6       | q1 = 'yes'        | q5 = 90          | N/A                 |
 | q7       | q1 = 'yes'        | q5 = 90          | N/A                 |
 
-### Email Validation
-
-Email validation is provided through the `EmailValidator` class and `EmailQuestion` component. The validator uses express-validator's robust email validation with configurable options.
-
-#### Basic Usage
-
-```javascript
-import { 
-	COMPONENT_TYPES,
-    createQuestions,
-    questionClasses,
-    EmailValidator
-} from '@planning-inspectorate/dynamic-forms';
-
-// Define question configuration
-const questionProps = {
-    contactEmail: {
-        type: COMPONENT_TYPES.EMAIL,
-        title: 'Contact Information',
-        question: 'What is your email address?',
-        fieldName: 'contactEmail',
-        url: 'contact-email',
-        label: 'Email address',
-        validators: [
-            new EmailValidator({
-                errorMessage: 'Enter an email address in the correct format, like name@example.com'
-            })
-        ]
-    }
-};
-
-// Create questions using the factory function
-const questions = createQuestions(questionProps, questionClasses, {});
-const emailQuestion = questions.contactEmail;
-```
-
-The EmailQuestion uses the following default input attributes:
+### Validators
 
-- `type="email"`
-- `spellcheck="false"`
-- `autocomplete="email"`
-
-#### Advanced Validation Options
-
-For stricter email validation requirements:
-
-```javascript
-const businessEmailValidator = new EmailValidator({
-    options: {
-        allowDisplayName: false,        // Reject "Name <email@domain.com>" format
-        requireTld: true,              // Require top-level domain (default: true)
-        allowUtf8LocalPart: false,     // Only ASCII characters in local part
-        allowIpDomain: false           // Don't allow IP addresses as domain
-    },
-    errorMessage: 'Enter a valid business email address'
-});
-```
-
-#### Alternative: Single Line Input with Email Attributes
-
-You can also configure a single line input with email-specific attributes:
-
-```javascript
-import {
-	COMPONENT_TYPES,
-	createQuestions,
-	questionClasses,
-	EmailValidator
-} from '@planning-inspectorate/dynamic-forms';
-
-const questionProps = {
-    contactEmail: {
-        type: COMPONENT_TYPES.SINGLE_LINE_INPUT,
-        title: 'Contact Information',
-        question: 'What is your email address?',
-        fieldName: 'contactEmail',
-        url: 'contact-email',
-        label: 'Email address',
-        inputAttributes: { type: 'email', spellcheck: 'false' },
-        autocomplete: 'email',
-        validators: [new EmailValidator()]
-    }
-};
-
-const questions = createQuestions(questionProps, questionClasses, {});
-```
+Many validators are available such as `RequiredValidator` and `AddressValidator`. More detail on email validation is available in [docs/Email Validation](./docs/Email%20Validation.md).
 
 ### Custom Summary Formatting
 
@@ -320,20 +181,6 @@ The formatter function receives a context object with the following properties:
 | `question` | `Question` | The question instance                          |
 | `journey` | `Journey` | The journey instance                           |
 | `sectionSegment` | `string` | The current section segment                    |
-| `selectedOptions` | `Option[] \| undefined` | For OptionsQuestions (such as Checkbox or Radio), the matched option object(s) as an array |
-
-#### Answer Formats
-
-Different options-based questions store answers in different formats. The `selectedOptions` array normalises these formats for your formatter:
-
-| Question Type | Answer Format | `selectedOptions` Result |
-|---------------|---------------|--------------------------|
-| **Radio / Select** | Single string value: `"approved"` | `[{ text: 'Approved', value: 'approved' }]` |
-| **Radio / Select** | Conditional object: `{ value: "yes", conditional: "details" }` | `[{ text: 'Yes', value: 'yes', conditional: {...} }]` |
-| **Checkbox** | Comma-separated string: `"option1,option2"` | `[{ text: 'Option 1', value: 'option1' }, { text: 'Option 2', value: 'option2' }]` |
-| **Checkbox** | Single conditional object: `{ value: "other", conditional: "details" }` | `[{ text: 'Other', value: 'other', conditional: {...} }]` |
-
-For single-select questions (Radio, Select), use `selectedOptions[0]` to access the selected option. For multi-select questions (Checkbox), iterate over the array.
 
 #### Examples
 
@@ -346,10 +193,9 @@ formatSummaryValue: ({ formattedAnswer }) => `<strong>${escapeHtml(formattedAnsw
 **Conditional styling based on answer:**
 
 ```javascript
-formatSummaryValue: ({ selectedOptions }) => {
-    const selectedOption = selectedOptions[0];
-    const color = selectedOption?.value === 'approved' ? 'green' : 'red';
-    return `<span style="color: ${color}">${escapeHtml(selectedOption?.text ?? '-')}</span>`;
+formatSummaryValue: ({ answer, formattedAnswer }) => {
+    const color = answer === 'approved' ? 'green' : 'red';
+    return `<span style="color: ${color}">${escapeHtml(formattedAnswer)}</span>`;
 }
 ```
 
@@ -373,29 +219,7 @@ formatSummaryValue: ({ formattedAnswer, journey }) => {
 }
 ```
 
-**Using selectedOptions for single-select questions (Radio/Select):**
-
-```javascript
-formatSummaryValue: ({ selectedOptions }) => {
-    const selectedOption = selectedOptions[0];
-    // Access the full option object including any custom properties
-    const warning = selectedOption?.warning;
-    return warning ? `${escapeHtml(selectedOption?.text ?? '-')} ⚠️` : escapeHtml(selectedOption?.text ?? '-');
-}
-```
-
-**Using selectedOptions for multi-select questions (Checkbox):**
-
-```javascript
-formatSummaryValue: ({ selectedOptions }) => {
-    // Join all selected option texts with custom formatting
-    return selectedOptions
-        .map(opt => `<span class="tag">${escapeHtml(opt.text)}</span>`)
-        .join(' ');
-}
-```
-
-> **Note:** `formattedAnswer` is already escaped by dynamic-forms; you are responsible for escaping any additional user-controlled values you include (for example `answer`, option text from `selectedOptions`, or values read from `journey.response.answers`).
+> **Note:** `formattedAnswer` is already escaped by dynamic-forms; you are responsible for escaping any additional user-controlled values you include (for example `answer` or values read from `journey.response.answers`).
 
 ## Contributing
 
@@ -428,7 +252,7 @@ When adding a new question type, be sure to add an example question into `test/q
 
 To update any snapshots with rendering changes (or new questions), run `node --test --test-update-snapshots`.
 
-### Components
+### New components
 
 When implement a new component, extend the base `Question` class. Common methods to override are:
 

package/docs/Email Validation.md

@@ -0,0 +1,86 @@
+# Email Validation
+
+Email validation is provided through the `EmailValidator` class and `EmailQuestion` component. The validator uses express-validator's robust email validation with configurable options.
+
+## Basic Usage
+
+```javascript
+import {
+	COMPONENT_TYPES,
+	createQuestions,
+	questionClasses,
+	EmailValidator
+} from '@planning-inspectorate/dynamic-forms';
+
+// Define question configuration
+const questionProps = {
+	contactEmail: {
+		type: COMPONENT_TYPES.EMAIL,
+		title: 'Contact Information',
+		question: 'What is your email address?',
+		fieldName: 'contactEmail',
+		url: 'contact-email',
+		label: 'Email address',
+		validators: [
+			new EmailValidator({
+				errorMessage: 'Enter an email address in the correct format, like name@example.com'
+			})
+		]
+	}
+};
+
+// Create questions using the factory function
+const questions = createQuestions(questionProps, questionClasses, {});
+const emailQuestion = questions.contactEmail;
+```
+
+The EmailQuestion uses the following default input attributes:
+
+- `type="email"`
+- `spellcheck="false"`
+- `autocomplete="email"`
+
+## Advanced Validation Options
+
+For stricter email validation requirements:
+
+```javascript
+const businessEmailValidator = new EmailValidator({
+	options: {
+		allowDisplayName: false, // Reject "Name <email@domain.com>" format
+		requireTld: true, // Require top-level domain (default: true)
+		allowUtf8LocalPart: false, // Only ASCII characters in local part
+		allowIpDomain: false // Don't allow IP addresses as domain
+	},
+	errorMessage: 'Enter a valid business email address'
+});
+```
+
+## Alternative: Single Line Input with Email Attributes
+
+You can also configure a single line input with email-specific attributes:
+
+```javascript
+import {
+	COMPONENT_TYPES,
+	createQuestions,
+	questionClasses,
+	EmailValidator
+} from '@planning-inspectorate/dynamic-forms';
+
+const questionProps = {
+	contactEmail: {
+		type: COMPONENT_TYPES.SINGLE_LINE_INPUT,
+		title: 'Contact Information',
+		question: 'What is your email address?',
+		fieldName: 'contactEmail',
+		url: 'contact-email',
+		label: 'Email address',
+		inputAttributes: { type: 'email', spellcheck: 'false' },
+		autocomplete: 'email',
+		validators: [new EmailValidator()]
+	}
+};
+
+const questions = createQuestions(questionProps, questionClasses, {});
+```