@defra/forms-engine-plugin 5.0.0-alpha.3 → 5.0.0-alpha.31

package/src/server/plugins/engine/plugin.ts

@@ -8,6 +8,7 @@ import {
 
 import { type FormModel } from './models/index.js'
 import { validatePluginOptions } from './options.js'
+import { generateUniqueReference } from './referenceNumbers.js'
 import { getRoutes as getFileUploadStatusRoutes } from './routes/file-upload.js'
 import { makeLoadFormPreHandler } from './routes/index.js'
 import { getRoutes as getPaymentRoutes } from './routes/payment.js'
@@ -37,6 +38,7 @@ export const plugin = {
       cache,
       saveAndExit,
       getLanguage,
+      generateReferenceNumber,
       nunjucks: nunjucksOptions,
       viewContext,
       preparePageEventRequestOptions,
@@ -80,6 +82,10 @@ export const plugin = {
     server.expose('cacheService', cacheService)
     server.expose('saveAndExit', saveAndExit)
     server.expose('getLanguage', getLanguage)
+    server.expose(
+      'generateReferenceNumber',
+      generateReferenceNumber ?? generateUniqueReference
+    )
     server.expose('baseUrl', baseUrl)
     server.expose('services', services)
 

package/src/server/plugins/engine/referenceNumbers.ts

@@ -6,6 +6,8 @@ import {
   englishRecommendedTransformers
 } from 'obscenity'
 
+export const DEFAULT_REFERENCE_NUMBER = 'XXX-XXX-XXX'
+
 /**
  * To prevent confusion to users reading the reference number, ambiguous letters and numbers are removed.
  * @param strCodes - array of binary input values

package/src/server/plugins/engine/routes/index.ts

@@ -20,6 +20,7 @@ import {
   findPage,
   getCacheService,
   getPage,
+  getPluginOptions,
   getStartPath,
   proceed
 } from '../helpers.js'
@@ -28,7 +29,7 @@ import {
   checkSaveAndExitRepeater,
   copyNotYetValidatedState
 } from '../pageControllers/helpers/state.js'
-import { generateUniqueReference } from '../referenceNumbers.js'
+import { DEFAULT_REFERENCE_NUMBER } from '../referenceNumbers.js'
 import * as defaultServices from '../services/index.js'
 import {
   type AnyFormRequest,
@@ -54,7 +55,7 @@ export async function redirectOrMakeHandler(
     context: FormContext
   ) => ResponseObject | Promise<ResponseObject>
 ) {
-  const { app, params } = request
+  const { app, params, query } = request
   const { model } = app
 
   if (!model) {
@@ -74,7 +75,12 @@ export async function redirectOrMakeHandler(
       )
     }
 
-    const referenceNumber = generateUniqueReference(prefix)
+    const isForce = 'force' in query
+    const { generateReferenceNumber } = getPluginOptions(request.server)
+    const referenceNumber = isForce
+      ? DEFAULT_REFERENCE_NUMBER
+      : await generateReferenceNumber(prefix)
+
     state = await page.mergeState(request, state, {
       $$__referenceNumber: referenceNumber
     })

package/src/server/plugins/engine/types/enums.ts

@@ -10,6 +10,7 @@ export enum FileStatus {
   pending = 'pending'
 }
 
-export enum FormAdapterSubmissionSchemaVersion {
-  V1 = 1
-}
+// Changed from an enum to enforce numeric values
+export const FormAdapterSubmissionSchemaVersion = {
+  V1: 1
+} as const satisfies Record<string, number>

package/src/server/plugins/engine/types/schema.ts

@@ -1,5 +1,6 @@
 import {
   FormStatus,
+  formSubmitConditionEvaluationSchema,
   formVersionMetadataSchema,
   idSchema,
   notificationEmailAddressSchema,
@@ -18,9 +19,9 @@ import {
 
 export const formAdapterSubmissionMessageMetaSchema =
   Joi.object<FormAdapterSubmissionMessageMeta>().keys({
-    schemaVersion: Joi.string().valid(
-      ...Object.values(FormAdapterSubmissionSchemaVersion)
-    ),
+    schemaVersion: Joi.number()
+      .valid(...Object.values(FormAdapterSubmissionSchemaVersion))
+      .required(),
     timestamp: Joi.date().required(),
     referenceNumber: Joi.string().required(),
     formName: titleSchema,
@@ -37,7 +38,11 @@ export const formAdapterSubmissionMessageMetaSchema =
       .pattern(/^/, Joi.any())
       .unknown()
       .optional()
-      .description('Custom properties for the message')
+      .description('Custom properties for the message'),
+    auth: Joi.object({
+      sub: Joi.string().required(),
+      issuer: Joi.string().required()
+    }).optional()
   })
 
 export const formAdapterSubmissionMessageDataSchema =
@@ -50,6 +55,7 @@ export const formAdapterSubmissionMessageDataSchema =
         reference: Joi.string().required(),
         amount: Joi.number().required(),
         description: Joi.string().required(),
+        descriptionInEng: Joi.string().optional(),
         createdAt: Joi.string().required()
       })
       .optional(),
@@ -79,5 +85,16 @@ export const formAdapterSubmissionMessagePayloadSchema =
   Joi.object<FormAdapterSubmissionMessagePayload>().keys({
     meta: formAdapterSubmissionMessageMetaSchema.required(),
     data: formAdapterSubmissionMessageDataSchema.required(),
-    result: formAdapterSubmissionMessageResultSchema.required()
+    result: formAdapterSubmissionMessageResultSchema.required(),
+    // Optional so that messages published before this existed - which may
+    // still be in flight or sitting on a dead-letter queue - continue to
+    // validate. Consumers treat its absence as "resolve the recipients from
+    // the form definition yourself"
+    // This should be required at a later point in time.
+    conditionEvaluations: Joi.array()
+      .items(formSubmitConditionEvaluationSchema)
+      .optional()
+      .description(
+        'Outcome of every condition in the form definition, evaluated against the final answers at submission'
+      )
   })

package/src/server/plugins/engine/types.ts

@@ -6,6 +6,7 @@ import {
   type List,
   type Page,
   type PaymentFieldComponent,
+  type SubmitConditionEvaluation,
   type UkAddressFieldComponent
 } from '@defra/forms-model'
 import {
@@ -245,11 +246,15 @@ export type FileUpload = {
 } & (
   | {
       fileStatus: FileStatus.complete | FileStatus.rejected | FileStatus.pending
+      errorCode?: string
       errorMessage?: string
+      errorParams?: Record<string, number | string | string[]>
     }
   | {
       fileStatus: FileStatus.complete
+      errorCode?: string
       errorMessage?: undefined
+      errorParams?: Record<string, number | string | string[]>
     }
 )
 
@@ -479,6 +484,10 @@ export type SaveAndExitHandler = (
 
 export type GetLanguageHandler = (query?: RequestQuery, yar?: Yar) => string
 
+export type GenerateReferenceNumberHandler = (
+  prefix?: string
+) => Promise<string>
+
 export interface ExternalArgs {
   component: ComponentDef
   controller: QuestionPageController
@@ -519,13 +528,14 @@ export interface PluginOptions {
   preparePageEventRequestOptions?: PreparePageEventRequestOptions
   onRequest?: OnRequestCallback
   getLanguage?: GetLanguageHandler
+  generateReferenceNumber?: GenerateReferenceNumberHandler
   baseUrl: string // base URL of the application, protocol and hostname e.g. "https://myapp.com"
   ordnanceSurveyApiKey?: string
   ordnanceSurveyApiSecret?: string
 }
 
 export interface FormAdapterSubmissionMessageMeta {
-  schemaVersion: FormAdapterSubmissionSchemaVersion
+  schemaVersion: (typeof FormAdapterSubmissionSchemaVersion)[keyof typeof FormAdapterSubmissionSchemaVersion]
   timestamp: Date
   referenceNumber: string
   formName: string
@@ -537,6 +547,10 @@ export interface FormAdapterSubmissionMessageMeta {
   versionMetadata?: FormVersionMetadata
   language?: string
   custom?: Record<string, unknown>
+  auth?: {
+    sub: string
+    issuer: string
+  }
 }
 
 export type FormAdapterSubmissionMessageMetaSerialised = Omit<
@@ -558,6 +572,7 @@ export interface FormAdapterPayment {
   reference: string
   amount: number
   description: string
+  descriptionInEng?: string
   createdAt: string
 }
 
@@ -602,6 +617,18 @@ export interface FormAdapterSubmissionMessagePayload {
   meta: FormAdapterSubmissionMessageMeta
   data: FormAdapterSubmissionMessageData
   result: FormAdapterSubmissionMessageResult
+
+  /**
+   * The outcome of every condition in the form definition, evaluated against
+   * the final answers at the point of submission.
+   *
+   * Always emitted, empty when there is nothing to report - a V1-engine form
+   * has no stable condition ids to record against. Optional only for
+   * backwards compatibility: a message published before this existed carries
+   * no evaluations at all, and consumers fall back to resolving the recipients
+   * from the form definition themselves.
+   */
+  conditionEvaluations?: SubmitConditionEvaluation[]
 }
 
 export interface FormAdapterSubmissionMessage extends FormAdapterSubmissionMessagePayload {

package/src/server/plugins/engine/unavailable-response.ts

@@ -2,6 +2,8 @@ import { type Request, type ResponseToolkit, type Server } from '@hapi/hapi'
 
 import { isOfflineBoom } from './form-availability.js'
 import { unavailableViewModel } from './models/unavailable-view-model.js'
+import { type AnyFormRequest } from './types.js'
+import { resolveLanguage } from '../../utils/utils.js'
 
 /**
  * Registers a server-wide onPreResponse extension that intercepts the offline
@@ -17,10 +19,12 @@ export function registerUnavailableResponse(server: Server) {
       return h.continue
     }
 
-    const { metadata } = response.data
+    const { metadata, definition } = response.data
+
+    const language = resolveLanguage(request as unknown as AnyFormRequest)
 
     return h
-      .view('unavailable', unavailableViewModel(metadata))
+      .view('unavailable', unavailableViewModel(metadata, definition, language))
       .header('Cache-Control', 'no-store, no-cache, must-revalidate')
       .header('X-Robots-Tag', 'noindex, nofollow')
       .code(200)

package/src/server/plugins/engine/views/components/_location-field-base.html

@@ -61,7 +61,7 @@
   {% set detailsHtml %}
     {% if component.model.instructionText %}
       {{ govukDetails({
-        summaryText: t('components.locationFieldBase.howToFind'),
+        summaryText: component.model.instructionSummary,
         html: component.model.instructionText | markdown | safe,
         classes: "govuk-!-margin-top-3"
       }) }}
@@ -70,8 +70,10 @@
 
   {% set hasErrors = showFieldsetError and component.model.errorMessage %}
 
-  <div class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}"
+  <div id="{{component.model.name}}" class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}"
     data-locationtype="{{component.type | lower}}"
+    data-country="{{component.model.country}}"
+    data-lang="{{component.model.lang}}"
     data-maplayers="{{component.model.mapLayers}}">
     {{ govukFieldset({
       legend: {

package/src/server/plugins/engine/views/components/fileuploadfield.html

@@ -3,7 +3,7 @@
 {% macro FileUploadField(component) %}
   {% set upload = component.model.upload %}
 
-  <div id="uploadedFilesContainer">
+  <div id="uploadedFilesContainer" data-uploadinglabel="{{ upload.uploadingLabel }}">
     <h2 class="govuk-heading-m">{{ t('components.fileUploadField.uploadedFilesHeading') }}</h2>
     {% if upload.count %}
       <p class="govuk-body" role="alert">{{ t('components.fileUploadField.filesCount', { count: upload.count }) }}</p>

package/src/server/plugins/engine/views/components/geospatialfield.html

@@ -2,6 +2,7 @@
 
 {% macro GeospatialField(component) %}
   <div class="app-geospatial-field"
+    data-lang="{{component.model.lang}}"
     data-country="{{component.model.country}}"
     data-geometryTypes="{{component.model.geometryTypes}}"
     data-maplayers="{{component.model.mapLayers}}">

package/src/server/plugins/engine/views/components/osgridreffield.html

@@ -3,7 +3,10 @@
 
 {% macro OsGridRefField(component) %}
   {% set hasErrors = component.model.errorMessage %}
-  <div class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}" data-locationtype="{{component.type | lower}}">
+  <div class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}"
+    data-locationtype="{{component.type | lower}}"
+    data-lang="{{component.model.lang}}"
+    data-maplayers="{{component.model.mapLayers}}">
     <div class="app-location-field-inputs">
       {{ TextField(component) }}
     </div>

package/src/server/plugins/engine/views/components/trackingfield.html

@@ -0,0 +1,3 @@
+{% macro TrackingField(component) %}
+  <input type="hidden" id="{{ component.model.name }}" name="{{ component.model.name }}" value="true" />
+{% endmacro %}

package/src/server/plugins/engine/views/components/ukaddressfield.html

@@ -61,7 +61,7 @@
               },
               classes: "govuk-button--secondary govuk-!-margin-right-1 govuk-!-margin-bottom-0"
             }) }}
-            <p class="govuk-body govuk-!-margin-bottom-0">or <button class="govuk-link govuk-button--link govuk-!-margin-right-1 govuk-!-margin-bottom-0" name="action" value="external-{{component.model.name}}--step:manual">{{ t('components.addressField.enterManually') }}</button></p>
+            <p class="govuk-body govuk-!-margin-bottom-0">{{ t('common.or')}} <button class="govuk-link govuk-button--link govuk-!-margin-right-1 govuk-!-margin-bottom-0" name="action" value="external-{{component.model.name}}--step:manual">{{ t('components.addressField.enterManually') }}</button></p>
           </div>
           {# Include a line break if this is the last component #}
           {% if components[components.length - 1] == component %}

package/src/server/plugins/engine/views/file-upload.html

@@ -15,7 +15,7 @@
     {% if formAction %}
       {{ govukButton({
         text: t('pages.fileUpload.upload'),
-        classes: "govuk-button--secondary upload-file-button",
+        classes: "govuk-button--secondary upload-file-button js-hidden",
         preventDoubleClick: true,
         disabled: context.isForceAccess
       }) }}

package/src/server/plugins/engine/views/summary.html

@@ -88,6 +88,7 @@
               When a better fix is implemented, this class can be removed and preventDoubleClick should be set back to true. #}
           {{ govukButton({
             text: submitButtonText,
+            classes: "prevent-multiple-clicks",
             name: "action",
             value: "send",
             preventDoubleClick: false

package/src/server/plugins/engine/views/unavailable.html

@@ -1,32 +1,35 @@
 {% extends baseLayoutPath %}
 
+{% set t = context.translator.t %}
+{% set tForm = context.translator.tForm %}
+
 {% block content %}
   <div class="govuk-grid-row">
     <div class="govuk-grid-column-two-thirds">
-      <h1 class="govuk-heading-l">Sorry, this form is unavailable</h1>
-      <p class="govuk-body">'{{ formTitle }}' is no longer available.</p>
-      <h2 class="govuk-heading-m">Contact details for {{ organisationName }}</h2>
+      <h1 class="govuk-heading-l">{{ t('pages.formUnavailable.title') }}</h1>
+      <p class="govuk-body">{{ t('pages.formUnavailable.subHeading', { formTitle: formTitle }) }}</p>
+      <h2 class="govuk-heading-m">{{ t('pages.formUnavailable.contactDetailsHeading', { organisationName: organisationName }) }}</h2>
 
       {% if contact.phone %}
-        <h3 class="govuk-heading-s">Telephone</h3>
+        <h3 class="govuk-heading-s">{{ t('pages.formUnavailable.telephone') }}</h3>
         <div class="app-prose-scope">
-          {{ contact.phone | markdown(3) | safe }}
+          {{ tForm('contact.phone') | markdown(3) | safe }}
         </div>
-        <p class="govuk-body"><a href="https://www.gov.uk/call-charges" class="govuk-link govuk-link--no-visited-state">Find out about call charges</a></p>
+        <p class="govuk-body"><a href="https://www.gov.uk/call-charges" class="govuk-link govuk-link--no-visited-state">{{ t('pages.formUnavailable.callCharges') }}</a></p>
       {% endif %}
 
       {% if contact.email %}
-        <h3 class="govuk-heading-s">Email</h3>
+        <h3 class="govuk-heading-s">{{ t('pages.formUnavailable.email') }}</h3>
         <ul class="govuk-list">
-          <li><a class="govuk-link govuk-link--no-visited-state" href="mailto:{{ contact.email.address }}">{{ contact.email.address }}</a></li>
-          <li>{{ contact.email.responseTime }}</li>
+          <li><a class="govuk-link govuk-link--no-visited-state" href="mailto:{{ tForm('contact.email.address') }}">{{ tForm('contact.email.address') }}</a></li>
+          <li>{{ tForm('contact.email.responseTime') }}</li>
         </ul>
       {% endif %}
 
       {% if contact.online %}
-        <h3 class="govuk-heading-s">Online contact form</h3>
+        <h3 class="govuk-heading-s">{{ t('pages.formUnavailable.onlineContactForm') }}</h3>
         <ul class="govuk-list">
-          <li><a class="govuk-link govuk-link--no-visited-state" href="{{ contact.online.url }}">{{ contact.online.text }}</a></li>
+          <li><a class="govuk-link govuk-link--no-visited-state" href="{{ tForm('contact.online.url') }}">{{ tForm('contact.online.text') }}</a></li>
         </ul>
       {% endif %}
     </div>

package/src/server/plugins/map/routes/index.js

@@ -7,18 +7,39 @@ import Joi from 'joi'
 
 import { getAccessToken } from './get-os-token.js'
 import { find } from '../service.js'
+import { CountryMap } from '../types.js'
 import {
   get,
   request as httpRequest
 } from '../../../services/httpService.js'
 
-const filePath = resolve(import.meta.dirname, './vts/countries.geojson')
+const countriesDisplayFilePath = resolve(
+  import.meta.dirname,
+  './vts/countries.geojson'
+)
+const countriesValidateFilePath = resolve(
+  import.meta.dirname,
+  './vts',
+  process.env.JEST_WORKER_ID === undefined
+    ? 'countries-5dp.geojson'
+    : 'countries.geojson'
+)
 
 /**
  * @type {FeatureCollection}
  */
 // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-export const countries = JSON.parse(fs.readFileSync(filePath, 'utf8'))
+export const countries = JSON.parse(
+  fs.readFileSync(countriesDisplayFilePath, 'utf8')
+)
+
+/**
+ * @type {FeatureCollection}
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+export const countriesValidate = JSON.parse(
+  fs.readFileSync(countriesValidateFilePath, 'utf8')
+)
 
 export const countrySchema = Joi.string().valid(
   ...Object.values(GeospatialFieldOptionsCountryEnum)
@@ -188,14 +209,18 @@ function getGeospatialCountries() {
       if (omit) {
         return {
           ...countries,
-          features: countries.features.filter((feature) => feature.id !== omit)
+          features: countries.features.filter(
+            (feature) => feature.id !== CountryMap[omit]
+          )
         }
       }
 
       if (only) {
         return {
           ...countries,
-          features: countries.features.filter((feature) => feature.id === only)
+          features: countries.features.filter(
+            (feature) => feature.id === CountryMap[only]
+          )
         }
       }
 

package/src/server/plugins/map/routes/vts/README.md

@@ -1,5 +1,43 @@
+# VTS
+
 File in this directory are sourced from https://github.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets
 
 VTS_OUTDOOR_URL=https://raw.githubusercontent.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets/main/OS_VTS_3857_Outdoor.json
 VTS_DARK_URL=https://raw.githubusercontent.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets/main/OS_VTS_3857_Dark.json
 VTS_BLACK_AND_WHITE_URL=https://raw.githubusercontent.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets/main/OS_VTS_3857_Black_and_White.json
+
+# Country boundaries
+
+The [Office for National Statistics provides full-resolution boundaries](https://www.ons.gov.uk/methodology/geography/geographicalproducts/digitalboundaries) in two coastal forms.
+We use "BFE" a full resolution — extent of the realm and generally extends to Mean Low Water rather than clipping at Mean High Water.
+
+The latest version of the data is from 2025 and can be found at the following links:
+
+https://geoportal.statistics.gov.uk/datasets/591803c2a3b94804a3d7895cc127d7c0_0/explore?location=50.529309%2C-4.098782%2C7
+
+Download from: http://geoportal.statistics.gov.uk/ or https://geoportal.statistics.gov.uk/datasets/ons::countries-december-2025-boundaries-uk-bfe/about
+
+The source data is for the 2025 revision is 179MB so needs to be reduced to allow rendering in a Web map and used for validation on the server. The downloaded file is named `boundaries-bfe.geojson`. `org2ogr` is used to produce two files:
+
+## Server-side validation (boundaries-bfe-5dp.geojson)
+
+This is the full file but with coordinate precision reduced from 14 to 5 decimal places, resulting in a smaller file of 83.7MB.
+This data is then used server-side to validate points, shapes and lines that include country restrictions.
+
+`ogr2ogr --config OGR_GEOJSON_MAX_OBJ_SIZE 0 -f GeoJSON boundaries-bfe-5dp.geojson boundaries-bfe.geojson -lco COORDINATE_PRECISION=5`
+
+## Client-side display on map (boundaries-bfe-5dp.geojson)
+
+To produce a file suitable for use in the map in the browser we use `ogr2ogr`'s `simplify` option.
+
+`-simplify 0.001` uses the units of the input CRS. In EPSG:4326, that's degrees, not metres so a tolerance of 0.001° is roughly 111 metres north–south, which is quite a substantial simplification for coastal boundaries. For 0.001 to mean approximately one metre, we have to reproject to a suitable projected CRS (BNG, EPSG:27700) before simplifying:
+
+The following command produces `boundaries-bng.geojson`, the source file reprojected to BNG.
+
+`ogr2ogr --config OGR_GEOJSON_MAX_OBJ_SIZE 0 -f GeoJSON boundaries-bng.geojson boundaries-bfe.geojson -t_srs EPSG:27700`
+
+We then use this to create a simplified dataset, `countries.geojson`, reprojected back in ESPG:4326:
+
+`ogr2ogr --config OGR_GEOJSON_MAX_OBJ_SIZE 0 -f GeoJSON countries.geojson boundaries-bng.json -simplify 100 -t_srs EPSG:4326 -lco COORDINATE_PRECISION=5`
+
+The result is a file of 940kB that is suitable to use in the web map.

package/src/server/plugins/map/routes/vts/countries-5dp.geojson

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/src/server/plugins/map/routes/vts/countries-5dp.geojson
+size: 83733031 bytes
+sha256: 032725bc5cedcee3aeba36dc8bc6aa987343635c199f5fe723dc8b0478ae5954