@defra/forms-engine-plugin 5.0.0-alpha.2 → 5.0.0-alpha.21

package/src/server/plugins/engine/i18n/translations/en-GB.json

@@ -14,7 +14,26 @@
     "numberInteger": "{{#label}} must be a whole number",
     "numberMin": "{{#label}} must be {{#limit}} or higher",
     "numberMax": "{{#label}} must be {{#limit}} or lower",
-    "maxWords": "{{#label}} must be {{#limit}} words or fewer"
+    "maxWords": "{{#label}} must be {{#limit}} words or fewer",
+    "unicode": "{{#label}} includes invalid characters, for example, long dashes",
+    "arrayMin_one": "Select at least {{#limit}} option from the list",
+    "arrayMin_other": "Select at least {{#limit}} options from the list",
+    "arrayMax_one": "Only {{#limit}} option can be selected from the list",
+    "arrayMax_other": "Only {{#limit}} options can be selected from the list",
+    "arrayLength_one": "Select only {{#limit}} option from the list",
+    "arrayLength_other": "Select only {{#limit}} options from the list",
+    "featuresMin_one": "Define at least {{#limit}} feature",
+    "featuresMin_other": "Define at least {{#limit}} features",
+    "featuresMax_one": "Only {{#limit}} feature can be defined",
+    "featuresMax_other": "Only {{#limit}} features can be defined",
+    "featuresLength_one": "Define exactly {{#limit}} feature",
+    "featuresLength_other": "Define exactly {{#limit}} features",
+    "filesMin_one": "You must upload {{#limit}} file or more",
+    "filesMin_other": "You must upload {{#limit}} files or more",
+    "filesMax_one": "You can only upload {{#limit}} file or less",
+    "filesMax_other": "You can only upload {{#limit}} files or less",
+    "filesLength_one": "You must upload exactly {{#limit}} file",
+    "filesLength_other": "You must upload exactly {{#limit}} files"
   },
 
   "errors": {
@@ -29,7 +48,14 @@
     "continue": "Continue",
     "saveAndExit": "Save and exit",
     "draft": "draft",
-    "live": "live"
+    "live": "live",
+    "or": "or",
+    "and": "and",
+    "england": "England",
+    "wales": "Wales",
+    "northern-ireland": "Northern Ireland",
+    "scotland": "Scotland",
+    "sendFeedback": "Send feedback"
   },
 
   "pages": {
@@ -60,6 +86,8 @@
       "totalAmount": "Total amount",
       "reference": "Reference",
       "dateOfPayment": "Date of payment",
+      "fileUpload_one": "Uploaded [[count]] file",
+      "fileUpload_other": "Uploaded [[count]] files",
       "submissionFailed": "There was a problem and your form was not submitted. Try submitting the form again",
       "submissionFailedContactSuffix": " or you can [[contactUsLink]] and quote your reference number to arrange a refund",
       "contactUsLinkText": "contact us (opens in new tab)",
@@ -89,7 +117,18 @@
 
     "fileUpload": {
       "upload": "Upload file",
-      "maxFilesReached": "You have reached the maximum number of files. Please remove a file to upload more."
+      "maxFilesReached": "You have reached the maximum number of files. Please remove a file to upload more.",
+      "remove": "Remove",
+      "removeFileTitle": "Are you sure you want to remove this file?",
+      "removeFileBody": "You cannot recover removed files.",
+      "removeFileButton": "Remove file",
+      "cancel": "Cancel",
+      "FILE_VIRUS": "The selected file contains a virus",
+      "FILE_EMPTY": "The selected file is empty",
+      "FILE_TOO_LARGE": "The selected file must be smaller than [[maxFileSizeFormatted]]",
+      "FILE_INVALID_TYPE": "The selected file must be a [[fileExtensions]]",
+      "FILE_UPLOAD_FAILED": "The selected file could not be uploaded - try again",
+      "FILE_ERROR_UNKNOWN": "Unknown error"
     },
 
     "exit": {
@@ -111,9 +150,20 @@
         "body": "If you want to receive a test email, [[link]] you want form submissions to go to.",
         "linkText": "enter the email address (opens in new tab)"
       },
+      "bannerTitle": "Important",
       "bannerForce": "This is a preview of a [[previewMode]] form. Do not enter personal information.",
       "bannerText": "This is a preview of a [[previewMode]] form page you are editing.",
       "previousPages": "It depends on answers from earlier pages in the form. In the live version, users will need to complete those questions first."
+    },
+
+    "formUnavailable": {
+      "title": "Sorry, this form is unavailable",
+      "subHeading": "'[[formTitle]]' is no longer available.",
+      "contactDetailsHeading": "Contact details for [[organisationName]]",
+      "telephone": "Telephone",
+      "callCharges": "Find out about call charges",
+      "email": "Email",
+      "onlineContactForm": "Online contact form"
     }
   },
 
@@ -199,7 +249,8 @@
       "eastingDigits": "{{#label}} for [[fieldLabel]] must be between 1 and 6 digits",
       "northingDigits": "{{#label}} for [[fieldLabel]] must be between 1 and 7 digits",
       "eastingRange": "{{#label}} for [[fieldLabel]] must be between [[min]] and [[max]]",
-      "northingRange": "{{#label}} for [[fieldLabel]] must be between [[min]] and [[max]]"
+      "northingRange": "{{#label}} for [[fieldLabel]] must be between [[min]] and [[max]]",
+      "wrongCountry": "Location must be within [[country]]"
     },
 
     "nationalGridField": {
@@ -215,7 +266,16 @@
     },
 
     "locationFieldBase": {
-      "howToFind": "How to find location details"
+      "howToFind": "How to find location details",
+      "map": {
+        "helpPanel": {
+          "label": "How to use this map",
+          "point1": "Search for a place or postcode",
+          "point2": "Use the + and - icons to zoom in and out",
+          "point3": "Use a mouse or keyboard to centre the point at the location",
+          "point4": "Click to add the location to the map"
+        }
+      }
     },
 
     "yesNoField": {
@@ -238,6 +298,47 @@
     "geospatialField": {
       "added_one": "Added [[count]] location",
       "added_other": "Added [[count]] locations",
+      "map": {
+        "helpPanel": {
+          "label": "How to use this map",
+          "ledeIntro": "You can add",
+          "ledeOutro": "to the map.",
+          "lineText": "a line",
+          "shapeText": "a shape",
+          "lineOrShapeText": "a line or shape",
+          "typesPhrasePoint": "points",
+          "typesPhraseLine": "lines",
+          "typesPhraseShape": "shapes",
+          "typesPhraseOr": "or",
+          "point1": "Search for a county, place or postcode",
+          "point2": "Use the + and - icons to zoom in and out",
+          "point3": "Double‑click, or select 'Done', when you have finished drawing",
+          "point4": "Give the location a name"
+        },
+        "typeDescriptions": {
+          "point": "Point",
+          "line": "Line",
+          "polygon": "Shape"
+        },
+        "buttons": {
+          "point": "Add point",
+          "line": "Add line",
+          "polygon": "Add shape"
+        },
+        "itemLabel1": "Location",
+        "itemLabel2": "description",
+        "itemUpdateLink": "Update",
+        "itemDeleteLink": "Delete",
+        "itemFocusLink": "Show",
+        "itemVisuallyHidden": "location",
+        "details": {
+          "summary": "Coordinates",
+          "type": "Type",
+          "centroidGridReference": "Centre grid reference",
+          "firstPointGridReference": "First point grid reference",
+          "detailedCoordinates": "Detailed coordinates"
+        }
+      },
       "validation": {
         "descriptionRequired": "Enter description for location [[count]]",
         "wrongCountry": "Location [[count]] must be within [[country]]"
@@ -245,7 +346,7 @@
     },
 
     "paymentField": {
-      "detailsRequired": "Payment details required",
+      "detailsRequired": "Payment required",
       "pendingTransaction": "You may see a pending transaction in your bank account but you will only be charged when you submit the form.",
       "addPaymentDetails": "Add payment details",
       "cannotTakePayment": "There is a problem and we cannot take a payment. Contact us (details in the footer of this form) or save your progress and return to the form later.",
@@ -261,11 +362,28 @@
     },
 
     "fileUploadField": {
+      "uploading": "Uploading…",
       "uploaded": "Uploaded",
       "uploadFailed": "There was a problem with your uploaded files. Re-upload them before submitting the form again.",
       "uploadedFilesHeading": "Uploaded files",
       "filesCount_one": "[[count]] file uploaded",
-      "filesCount_other": "[[count]] files uploaded"
+      "filesCount_other": "[[count]] files uploaded",
+      "chooseFile": "Choose file",
+      "dropFile": "or drop file",
+      "noFileChosen": "No file chosen"
+    },
+
+    "characterCount": {
+      "_comment": "Note the use of %{count} instead of [[count]]. This is because we are passing to the govuk template, not passing to Joi",
+      "underLimit": {
+        "one": "You have %{count} character remaining",
+        "other": "You have %{count} characters remaining"
+      },
+      "atLimit": "You have 0 characters remaining",
+      "overLimit": {
+        "one": "You have %{count} character too many",
+        "other": "You have %{count} characters too many"
+      }
     }
   }
 }

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

@@ -22,6 +22,9 @@ export type FormDefinitionTranslations = Record<
         hint: string
         content: string
         shortDescription: string
+        errorDescription: string
+        paymentDescription: string
+        instructionText: string
       }>
     >
     sections: Record<string, Partial<Pick<Section, 'title'>>>

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

@@ -22,6 +22,13 @@ export {
   resolveFormModel
 } from './form-context.js'
 export * from './form-availability.js'
+export { getAvailableLanguages } from './i18n/languages.js'
+export {
+  extractMetadataBaseTranslations,
+  loadFormTranslations
+} from './i18n/createFormTranslator.js'
+export { extractBaseTranslations } from './i18n/extractBaseTranslations.js'
+export { applyUrlParam } from '../nunjucks/filters/applyUrlParam.js'
 
 const globals = {
   checkComponentTemplates,

package/src/server/plugins/engine/models/FormModel.ts

@@ -1,5 +1,6 @@
 import {
   ComponentType,
+  ConditionEvaluationOutcome,
   ConditionsModel,
   ControllerPath,
   ControllerType,
@@ -8,6 +9,7 @@ import {
   formDefinitionSchema,
   formDefinitionV2Schema,
   generateConditionAlias,
+  getErrorMessage,
   hasComponents,
   hasComponentsEvenIfNoNext,
   hasRepeater,
@@ -31,6 +33,7 @@ import { type i18n } from 'i18next'
 import joi from 'joi'
 
 import { logger } from '../../../common/helpers/logging/logger.js'
+import { EN_GB } from '../../../constants.js'
 import { type ListFormComponent } from '../components/ListFormComponent.js'
 import {} from '../components/YesNoField.js'
 import {
@@ -38,6 +41,10 @@ import {
   type Component
 } from '../components/helpers/components.js'
 import { todayAsDateOnly } from '../date-helper.js'
+import {
+  ConditionBuildError,
+  SchemaValidationError
+} from '../errors.js'
 import {
   findPage,
   getError,
@@ -47,8 +54,12 @@ import { loadFormTranslations } from '../i18n/createFormTranslator.js'
 import { createTranslator } from '../i18n/createTranslator.js'
 import { extractBaseTranslations } from '../i18n/extractBaseTranslations.js'
 import { createFormI18nInstance } from '../i18n/index.js'
+import { getAvailableLanguages } from '../i18n/languages.js'
 import { type Translator } from '../i18n/types.js'
-import { type ExecutableCondition } from './types.js'
+import {
+  type ConditionEvaluation,
+  type ExecutableCondition
+} from './types.js'
 import { type PageController } from '../pageControllers/PageController.js'
 import {
   createPage,
@@ -122,7 +133,7 @@ export class FormModel {
     const result = schema.validate(def, { abortEarly: false })
 
     if (result.error) {
-      throw result.error
+      throw new SchemaValidationError(result.error)
     }
 
     // Make a clone of the shallow copy returned
@@ -240,7 +251,12 @@ export class FormModel {
   }
 
   /** Returns a scoped translator pair for the given language. */
-  createTranslator(language = 'en-GB'): Translator {
+  createTranslator(language = EN_GB): Translator {
+    // @ts-expect-error - dynamic language lookup
+    if (!this.def.metadata?.translations?.[language]) {
+      // If not translations defined in the FormDefinition, always default to English
+      language = EN_GB
+    }
     return createTranslator(this.i18nInstance, language)
   }
 
@@ -285,23 +301,43 @@ export class FormModel {
     })
 
     const { name, displayName, value } = condition
-    const expr = this.toConditionExpression(value, parser)
 
-    const fn = (evaluationState: FormState) => {
+    let expr
+    try {
+      expr = this.toConditionExpression(value, parser)
+    } catch (cause) {
+      throw new ConditionBuildError(displayName, { cause })
+    }
+
+    const evaluate = (evaluationState: FormState): ConditionEvaluation => {
       const ctx = this.toConditionContext(evaluationState, this.conditions)
+
       try {
-        return expr.evaluate(ctx) as boolean
-      } catch {
-        return false
+        return {
+          outcome: (expr.evaluate(ctx) as boolean)
+            ? ConditionEvaluationOutcome.True
+            : ConditionEvaluationOutcome.False
+        }
+      } catch (err) {
+        return {
+          outcome: ConditionEvaluationOutcome.Error,
+          error: getErrorMessage(err)
+        }
       }
     }
 
+    // A failed evaluation continues to route as `false`. `evaluate` exists so
+    // that the two can be told apart when recording outcomes for submission.
+    const fn = (evaluationState: FormState) =>
+      evaluate(evaluationState).outcome === ConditionEvaluationOutcome.True
+
     return {
       name,
       displayName,
       value,
       expr,
-      fn
+      fn,
+      evaluate
     }
   }
 
@@ -662,7 +698,7 @@ function validateFormState(
 
   // Add relevant state errors
   if (error) {
-    const errorsState = error.details.map(getError)
+    const errorsState = error.details.map((item) => getError(EN_GB, item))
     return { ...context, errors: errors.concat(errorsState) }
   }
 
@@ -679,16 +715,3 @@ function getReferenceNumber(state: FormSubmissionState): string {
 
   return state.$$__referenceNumber
 }
-
-export function getAvailableLanguages(
-  def: FormDefinition
-): { name: string; code: string }[] {
-  // @ts-expect-error - dynamic property
-  if (def.metadata?.translations?.cy) {
-    return [
-      { name: 'English', code: 'en-GB' },
-      { name: 'Cymraeg', code: 'cy' }
-    ]
-  }
-  return []
-}

package/src/server/plugins/engine/models/SummaryViewModel.ts

@@ -4,6 +4,7 @@ import {
   type Section
 } from '@defra/forms-model'
 
+import { EN_GB } from '../../../constants.js'
 import { PaymentField } from '../components/PaymentField.js'
 import { type PaymentState } from '../components/PaymentField.types.js'
 import {
@@ -96,7 +97,7 @@ export class SummaryViewModel {
       .validate(this.context.relevantState, { ...opts, stripUnknown: true })
 
     // Format errors
-    this.errors = result.error?.details.map(getError)
+    this.errors = result.error?.details.map((item) => getError(EN_GB, item))
     this.details = this.summaryDetails(request, sections, translator)
 
     // Format check answers
@@ -212,12 +213,12 @@ function ItemRepeat(
   translator: Translator
 ): DetailItemRepeat {
   const { collection, repeat } = page
-  const { name, title } = repeat.options
-
+  const { name } = repeat.options
+  const { t, tPage } = translator
+  const title = tPage(page.pageDef, 'repeatTitle') || repeat.options.title
   const values = page.getListFromState(state)
   const count = values.length
-  const value =
-    count === 0 ? '' : translator.t('pages.repeater.pageTitle', { count })
+  const value = count === 0 ? '' : t('pages.repeater.pageTitle', { count })
 
   return {
     name,

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

@@ -1,4 +1,5 @@
 import {
+  type ConditionEvaluationOutcome,
   type ConditionWrapper,
   type FormComponentsDef,
   type Section
@@ -16,9 +17,39 @@ import {
   type FormSubmissionError
 } from '../types.js'
 
+/**
+ * The result of evaluating a condition, keeping a failed evaluation distinct
+ * from one that legitimately returned `false`.
+ * @see {@link ExecutableCondition.evaluate}
+ */
+export interface ConditionEvaluation {
+  outcome: ConditionEvaluationOutcome
+  error?: string
+}
+
+/**
+ * A form condition paired with the parsed expression and callbacks needed to
+ * run it against a form submission state
+ * Created by `FormModel.makeCondition`
+ */
 export type ExecutableCondition = ConditionWrapper & {
+  /**
+   * Parsed expression for the condition's {@link ConditionWrapper.value},
+   * evaluated against a context built from the submission state
+   */
   expr: Expression
+
+  /**
+   * Evaluates the condition, used for page routing and component visibility
+   * A failed evaluation is reported as `false`
+   */
   fn: (evaluationState: FormState) => boolean
+
+  /**
+   * As `fn`, but reports whether evaluation failed rather than defaulting a
+   * failure to `false`. Used to record condition outcomes on submission.
+   */
+  evaluate: (evaluationState: FormState) => ConditionEvaluation
 }
 
 /**

package/src/server/plugins/engine/models/unavailable-view-model.ts

@@ -1,19 +1,40 @@
-import { type FormMetadata, type FormMetadataContact } from '@defra/forms-model'
+import {
+  type FormDefinition,
+  type FormMetadata,
+  type FormMetadataContact
+} from '@defra/forms-model'
+
+import { createFormTranslator } from '../i18n/createFormTranslator.js'
+import { getAvailableLanguages } from '../i18n/languages.js'
+import { type Translator } from '../types/index.js'
 
 export interface UnavailableViewModel {
   pageTitle: string
   formTitle: string
   organisationName: string
   contact?: FormMetadataContact
+  context: { translator: Translator }
+  language: string
+  languages: { code: string; name: string }[]
 }
 
 export function unavailableViewModel(
-  metadata: FormMetadata
+  metadata: FormMetadata,
+  definition: FormDefinition | undefined,
+  language: string
 ): UnavailableViewModel {
+  const translator = createFormTranslator(metadata, definition, language)
+  const { t, tForm } = translator
   return {
-    pageTitle: 'Sorry, this form is unavailable',
-    formTitle: metadata.title,
+    pageTitle: t('pages.formUnavailable.title'),
+    formTitle: tForm('title') || metadata.title,
     organisationName: metadata.organisation,
-    contact: metadata.contact
+    contact: metadata.contact,
+    context: { translator },
+    language,
+    // Always get Welsh and English
+    languages: getAvailableLanguages({
+      metadata: { translations: { cy: {} } }
+    } as unknown as FormDefinition)
   }
 }

package/src/server/plugins/engine/outputFormatters/adapter/v1.ts

@@ -1,8 +1,10 @@
 import {
+  Engine,
   type FormMetadata,
   type SubmitResponsePayload
 } from '@defra/forms-model'
 
+import { EN_GB } from '../../../../constants.js'
 import {
   getFormVersion,
   type checkFormStatus
@@ -10,6 +12,7 @@ import {
 import { type FormModel } from '../../models/FormModel.js'
 import { type DetailItem } from '../../models/types.js'
 import { categoriseData } from '../machine/v2.js'
+import { buildConditionEvaluations } from '../../pageControllers/helpers/submission.js'
 import { FormAdapterSubmissionSchemaVersion } from '../../types/enums.js'
 import {
   type FormAdapterSubmissionMessageData,
@@ -42,18 +45,14 @@ export function format(
     formSlug: formMetadata?.slug ?? '',
     status: formStatus.state,
     isPreview: formStatus.isPreview,
-    notificationEmail: formMetadata?.notificationEmail ?? ''
+    notificationEmail: formMetadata?.notificationEmail ?? '',
+    language: context.translator?.language ?? EN_GB
   }
 
   if (versionMetadata) {
     meta.versionMetadata = versionMetadata
   }
 
-  const definitionLanguage = model.def.metadata?.language
-  if (typeof definitionLanguage === 'string') {
-    meta.language = definitionLanguage
-  }
-
   const main = Object.fromEntries(
     Object.entries(v2Main).map(([key, value]) => {
       if (value === undefined) {
@@ -76,7 +75,19 @@ export function format(
   const payload: FormAdapterSubmissionMessagePayload = {
     meta,
     data,
-    result
+    result,
+
+    // Recorded here because only the engine holds the walked evaluation state
+    // the conditions were judged against; forms-notify-listener receives the
+    // flat submitted answers and resolves the outputs that qualify from these
+    // outcomes alone. Condition ids are only stable in V2, so a V1 definition
+    // has nothing to report - the property is still emitted, because its
+    // absence is what marks a message as predating this and sends the listener
+    // down its legacy path.
+    conditionEvaluations:
+      model.engine === Engine.V2
+        ? buildConditionEvaluations(model, context)
+        : []
   }
 
   return JSON.stringify(payload)

package/src/server/plugins/engine/outputFormatters/human/v1.ts

@@ -5,6 +5,7 @@ import {
 import { addDays, format as dateFormat } from 'date-fns'
 
 import { config } from '../../../../../config/index.js'
+import { EN_GB } from '../../../../constants.js'
 import { getAnswer } from '../../components/helpers/components.js'
 import { escapeMarkdown } from '../../components/helpers/index.js'
 import { PaymentField } from '../../components/index.js'
@@ -116,7 +117,7 @@ function appendPaymentSection(paymentItems: DetailItem[], lines: string[]) {
 
   const formattedAmount = formatCurrency(paymentState.amount)
   const dateOfPayment = paymentState.preAuth?.createdAt
-    ? formatPaymentDate(paymentState.preAuth.createdAt)
+    ? formatPaymentDate(paymentState.preAuth.createdAt, EN_GB)
     : ''
 
   lines.push(

package/src/server/plugins/engine/outputFormatters/machine/v2.ts

@@ -28,6 +28,7 @@ interface PaymentOutput {
   reference: string
   amount: number
   description: string
+  descriptionInEng?: string
   createdAt: string
 }
 
@@ -93,6 +94,7 @@ export function format(
  *        reference: 'REF-123',
  *        amount: 10.00,
  *        description: 'Application fee',
+ *        descriptionInEng: 'Applicaiton fee',
  *        createdAt: '2025-01-23T10:30:00.000Z'
  *      }
  *    }
@@ -204,6 +206,7 @@ function extractPayment(
     reference: paymentState.reference,
     amount: paymentState.amount,
     description: paymentState.description,
+    descriptionInEng: item.field.def.options.description,
     createdAt: paymentState.preAuth?.createdAt ?? ''
   }
 }