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

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/options.js

@@ -26,7 +26,8 @@ const pluginRegistrationOptionsSchema = Joi.object({
   saveAndExit: Joi.function().optional(),
   ordnanceSurveyApiKey: Joi.string().optional(),
   ordnanceSurveyApiSecret: Joi.string().optional(),
-  getLanguage: Joi.function().optional()
+  getLanguage: Joi.function().optional(),
+  generateReferenceNumber: Joi.function().optional()
 })
 
 /**

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 ?? ''
   }
 }

package/src/server/plugins/engine/pageControllers/FileUploadPageController.ts

@@ -42,6 +42,7 @@ import {
   type FormRequestPayload,
   type FormResponseToolkit
 } from '../../../routes/types.js'
+import { joinWithOr } from '../../../utils/utils.js'
 
 const MAX_UPLOADS = 25
 const CDP_UPLOAD_TIMEOUT_MS = 60000 // 1 minute
@@ -188,17 +189,19 @@ export class FileUploadPageController extends QuestionPageController {
 
       const { filename } = fileToRemove.status.form.file
 
-      const { t } = this.getTranslator(request)
+      const translator = this.getTranslator(request)
+      const { t } = translator
 
       return h.view(this.fileDeleteViewName, {
         ...viewModel,
         context,
         backLink: this.getBackLink(request, context, t),
-        pageTitle: `Are you sure you want to remove this file?`,
+        pageTitle: t('pages.fileUpload.removeFileTitle'),
         itemTitle: filename,
-        confirmation: { text: 'You cannot recover removed files.' },
-        buttonConfirm: { text: 'Remove file' },
-        buttonCancel: { text: 'Cancel' }
+        confirmation: { text: t('pages.fileUpload.removeFileBody') },
+        buttonConfirm: { text: t('pages.fileUpload.removeFileButton') },
+        buttonCancel: { text: t('pages.fileUpload.cancel') },
+        t
       } satisfies ItemDeletePageViewModel)
     }
   }
@@ -224,7 +227,7 @@ export class FileUploadPageController extends QuestionPageController {
     }
   }
 
-  getErrors(details?: ValidationErrorItem[]) {
+  getErrors(details?: ValidationErrorItem[], language?: string) {
     const { fileUpload } = this
 
     if (details) {
@@ -237,7 +240,7 @@ export class FileUploadPageController extends QuestionPageController {
         if (!isUploadError || isUploadRootError) {
           // The error is for the root of the upload or another
           // field on the page so defer to the getError helper
-          errors.push(getError(error))
+          errors.push(getError(language, error))
         } else {
           const { context, path, type } = error
 
@@ -266,6 +269,7 @@ export class FileUploadPageController extends QuestionPageController {
   ): FeaturedFormPageViewModel {
     const { fileUpload } = this
     const { state } = context
+    const { t } = translator
 
     const upload = this.getUploadFromState(state)
 
@@ -277,6 +281,19 @@ export class FileUploadPageController extends QuestionPageController {
       ({ model }) => model.id === fileUpload.name
     )
 
+    formComponent.model.upload = {
+      count: formComponent.model.upload?.count ?? 0,
+      summaryList: formComponent.model.upload?.summaryList ?? { rows: [] },
+      uploadingLabel: t('components.fileUploadField.uploading')
+    }
+    formComponent.model = {
+      ...formComponent.model,
+      javascript: true,
+      chooseFilesButtonText: t('components.fileUploadField.chooseFile'),
+      dropInstructionText: t('components.fileUploadField.dropFile'),
+      noFileChosenText: t('components.fileUploadField.noFileChosen')
+    }
+
     const index = components.indexOf(formComponent)
 
     const proxyUrl = getProxyUrlForLocalDevelopment(upload?.uploadUrl)
@@ -290,7 +307,8 @@ export class FileUploadPageController extends QuestionPageController {
       // Split out components before/after
       componentsBefore: components.slice(0, index),
       components: components.slice(index),
-      proxyUrl
+      proxyUrl,
+      t
     }
   }
 
@@ -441,6 +459,9 @@ export class FileUploadPageController extends QuestionPageController {
 
     const allErrors: FormSubmissionError[] = []
 
+    const translator = this.getTranslator(request)
+    const { t } = translator
+
     for (const file of uploadedFiles) {
       if (file.fileStatus === FileStatus.complete) {
         const perFileState: FileState = {
@@ -455,7 +476,14 @@ export class FileUploadPageController extends QuestionPageController {
         // Collect the error for rejected/pending files.
         const { fileUpload } = this
         const name = fileUpload.name
-        const text = file.errorMessage ?? 'Unknown error'
+        const errorParams = this.expandErrorParams(
+          file.errorParams,
+          t('common.or')
+        )
+        const text = t(
+          `pages.fileUpload.${file.errorCode ?? 'FILE_ERROR_UNKNOWN'}`,
+          errorParams
+        )
         allErrors.push({ path: [name], href: `#${name}`, name, text })
       }
     }
@@ -472,6 +500,29 @@ export class FileUploadPageController extends QuestionPageController {
     }
   }
 
+  /**
+   * Process the error parameters so any arrays get expanded (joined), ready to be passed into the error message
+   * @param errorParams - received from the file upload (may be a number, a string, or a string array)
+   * @param finalSeparator - 'or' in English, and 'neu' in Welsh
+   */
+  private expandErrorParams(
+    errorParams: Record<string, number | string | string[]> | undefined,
+    finalSeparator: string
+  ) {
+    if (!errorParams) {
+      return {}
+    }
+    const expanded = {} as Record<string, number | string>
+    for (const [key, value] of Object.entries(errorParams)) {
+      if (Array.isArray(value)) {
+        expanded[key] = joinWithOr(value, finalSeparator)
+      } else {
+        expanded[key] = value
+      }
+    }
+    return expanded
+  }
+
   /**
    * Checks the payload for a file getting removed
    * and removes it from the upload files if found

package/src/server/plugins/engine/pageControllers/QuestionPageController.ts

@@ -364,8 +364,8 @@ export class QuestionPageController extends PageController {
     return this.collection.getStateFromValidForm(payload)
   }
 
-  getErrors(details?: ValidationErrorItem[]) {
-    return getErrors(details)
+  getErrors(details?: ValidationErrorItem[], language?: string) {
+    return getErrors(language, details)
   }
 
   async getState(request: AnyFormRequest) {

package/src/server/plugins/engine/pageControllers/RepeatPageController.ts

@@ -406,9 +406,9 @@ export class RepeatPageController extends QuestionPageController {
     const { query } = request
     const { isForceAccess, errors } = context
 
-    const { t } = translator
+    const { t, tPage } = translator
 
-    const { title } = repeat.options
+    const title = tPage(this.pageDef, 'repeatTitle') || repeat.options.title
 
     const summaryList: SummaryList = {
       classes: 'govuk-summary-list--long-actions',

package/src/server/plugins/engine/pageControllers/SummaryPageController.ts

@@ -114,7 +114,7 @@ export class SummaryPageController extends QuestionPageController {
         viewModel.paymentDetails = this.buildPaymentDetails(
           paymentField,
           paymentState,
-          t
+          translator
         )
       }
 
@@ -151,8 +151,9 @@ export class SummaryPageController extends QuestionPageController {
     paymentState: NonNullable<
       ReturnType<PaymentField['getPaymentStateFromState']>
     >,
-    t: (key: string, opts?: Record<string, unknown>) => string
+    translator: Translator
   ) {
+    const { t } = translator
     const rows = [
       {
         key: { text: t('pages.summary.paymentFor') },
@@ -171,7 +172,12 @@ export class SummaryPageController extends QuestionPageController {
     if (paymentState.preAuth?.createdAt) {
       rows.push({
         key: { text: t('pages.summary.dateOfPayment') },
-        value: { text: formatPaymentDate(paymentState.preAuth.createdAt) }
+        value: {
+          text: formatPaymentDate(
+            paymentState.preAuth.createdAt,
+            translator.language
+          )
+        }
       })
     }
 
@@ -557,7 +563,12 @@ function submitData(
     retrievalKey,
     referenceNumber,
     main: buildMainRecords(items, translator),
-    repeaters: buildRepeaterRecords(items, translator)
+    repeaters: buildRepeaterRecords(items, translator),
+    // Only populate the language property if the form is multi-language enabled
+    // @ts-expect-error - dynamic language property
+    language: model.def.metadata?.translations?.cy
+      ? translator.language
+      : undefined
   }
   return submit(payload)
 }

package/src/server/plugins/engine/pageControllers/helpers/pages.ts

@@ -4,6 +4,7 @@ import {
   type Page
 } from '@defra/forms-model'
 
+import { UnknownPageControllerError } from '../../errors.js'
 import { type FormModel } from '../../models/index.js'
 import * as PageControllers from '../index.js'
 
@@ -66,7 +67,7 @@ export function createPage(model: FormModel, pageDef: Page) {
   }
 
   if (typeof controller === 'undefined') {
-    throw new Error(`Page controller ${pageDef.controller} does not exist`)
+    throw new UnknownPageControllerError(pageDef.controller)
   }
 
   return controller

package/src/server/plugins/engine/pageControllers/helpers/submission.ts

@@ -1,13 +1,27 @@
-import { type SubmitPayload } from '@defra/forms-model'
+import {
+  isConditionWrapperV2,
+  type ConditionDataV2,
+  type ConditionRefDataV2,
+  type ConditionWrapperV2,
+  type SubmitConditionEvaluation,
+  type SubmitConditionReference,
+  type SubmitPayload
+} from '@defra/forms-model'
 
 import { GeospatialField } from '../../components/GeospatialField.js'
 import { PaymentField } from '../../components/PaymentField.js'
 import { getAnswer } from '../../components/helpers/components.js'
 import { type Translator } from '../../i18n/types.js'
+import { type FormModel } from '../../models/FormModel.js'
 import {
   type DetailItem,
   type DetailItemField
 } from '../../models/types.js'
+import {
+  type FormContext,
+  type FormState,
+  type FormStateValue
+} from '../../types.js'
 import {
   formatCurrency,
   formatPaymentDate
@@ -36,7 +50,7 @@ export function buildMainRecords(
 
   for (const item of fieldItems) {
     if (item.field instanceof PaymentField) {
-      records.push(...buildPaymentRecords(item))
+      records.push(...buildPaymentRecords(item, translator))
     } else if (item.field instanceof GeospatialField) {
       // Stringify of GeoJSON is done here rather than inside `getContextValueFromState`
       // so we don't incur the overhead of JSON.stringify on every request when building context
@@ -67,7 +81,10 @@ export function buildMainRecords(
  *
  * Returns an empty array if no payment state exists.
  */
-export function buildPaymentRecords(item: DetailItemField): SubmitRecord[] {
+export function buildPaymentRecords(
+  item: DetailItemField,
+  translator: Translator
+): SubmitRecord[] {
   const paymentState = (item.field as PaymentField).getPaymentStateFromState(
     item.state
   )
@@ -96,7 +113,7 @@ export function buildPaymentRecords(item: DetailItemField): SubmitRecord[] {
       name: `${item.name}_paymentDate`,
       title: 'Payment date',
       value: paymentState.preAuth?.createdAt
-        ? formatPaymentDate(paymentState.preAuth.createdAt)
+        ? formatPaymentDate(paymentState.preAuth.createdAt, translator.language)
         : ''
     }
   ]
@@ -138,3 +155,125 @@ export function buildRepeaterRecords(
       )
     }))
 }
+
+/**
+ * Records the outcome of every condition in the form definition, evaluated
+ * against the answers as they stand at the point of submission.
+ *
+ * Evaluated here rather than by the consumer because only the engine holds
+ * the context to evaluate against: `evaluationState` is built by walking the
+ * form from its start page along the path taken, applying page conditions as
+ * it goes. A consumer receives the flat submitted answers, not that walked
+ * state, and reproducing the walk in a second codebase would leave two
+ * implementations of the same logic free to diverge.
+ *
+ * Each record carries the components the condition depends on and whether each
+ * was answered. An unanswered question still yields a boolean - negative
+ * operators such as "is not" return `true` against the seeded `null` - so the
+ * outcome alone cannot be read as evidence that the user gave that answer.
+ *
+ * V2 definitions only. `conditionId` is the V2 condition id, and the
+ * references are resolved from the component ids V2 conditions carry - V1
+ * conditions reference components by name, and V1 components need not have
+ * an id at all.
+ */
+export function buildConditionEvaluations(
+  model: FormModel,
+  context: FormContext
+): SubmitConditionEvaluation[] {
+  const { evaluationState } = context
+
+  return model.def.conditions
+    .filter(isConditionWrapperV2)
+    .flatMap((conditionDef) => {
+      const condition = model.conditions[conditionDef.id]
+
+      if (!condition) {
+        return []
+      }
+
+      const { outcome } = condition.evaluate(evaluationState)
+
+      const references = collectReferences(model, conditionDef, evaluationState)
+
+      return {
+        conditionId: conditionDef.id,
+        outcome,
+        references: [...references.values()]
+      }
+    })
+}
+
+/**
+ * Whether a component held an answer at the point a condition was evaluated.
+ *
+ * The engine seeds every component in `evaluationState` with `null` before the
+ * page walk begins, so an unanswered question is present but empty rather than
+ * absent.
+ * @see {@link FormModel.initialiseContext}
+ */
+export function isAnswered(value: FormStateValue | undefined) {
+  if (value === undefined || value === null) {
+    return false
+  }
+
+  if (Array.isArray(value)) {
+    return value.length > 0
+  }
+
+  return value !== ''
+}
+
+function isConditionDataV2(
+  item: ConditionDataV2 | ConditionRefDataV2
+): item is ConditionDataV2 {
+  return 'componentId' in item
+}
+
+/**
+ * Recursive function that collects every component a condition depends on, following nested condition
+ * references. Results are keyed by component id so a component referenced more
+ * than once is reported once.
+ */
+function collectReferences(
+  model: FormModel,
+  conditionDef: ConditionWrapperV2,
+  evaluationState: FormState,
+  references: Map<string, SubmitConditionReference> = new Map<
+    string,
+    SubmitConditionReference
+  >(),
+  visited: Set<string> = new Set<string>()
+) {
+  if (visited.has(conditionDef.id)) {
+    return references
+  }
+
+  visited.add(conditionDef.id)
+
+  for (const item of conditionDef.items) {
+    if (isConditionDataV2(item)) {
+      const component = model.getComponentById(item.componentId)
+
+      // A condition referencing a component that no longer exists cannot be
+      // resolved to a name, so there is nothing meaningful to report for it
+      if (component) {
+        references.set(item.componentId, {
+          componentId: item.componentId,
+          componentName: component.name,
+          answered: isAnswered(evaluationState[component.name])
+        })
+      }
+
+      continue
+    }
+
+    const referenced = model.getConditionById(item.conditionId)
+
+    if (referenced) {
+      collectReferences(model, referenced, evaluationState, references, visited)
+    }
+  }
+
+  return references
+}

package/src/server/plugins/engine/pageControllers/validationOptions.ts

@@ -26,7 +26,7 @@ export const opts = {
  * import messageTemplate directly and get the English version.
  */
 export const messageTemplate: ValidationMessages = buildValidationMessages(
-  (key) => t(key, 'en-GB')
+  (key, options) => t(key, 'en-GB', options)
 )
 
 export const messages: LanguageMessagesExt = {
@@ -58,14 +58,28 @@ export const messages: LanguageMessagesExt = {
   'date.min': messageTemplate.dateMin,
   'date.max': messageTemplate.dateMax,
 
-  'object.invalidjson': messageTemplate.format
+  'array.min': messageTemplate.arrayMin,
+  'array.max': messageTemplate.arrayMax,
+  'array.length': messageTemplate.arrayLength,
+
+  'features.min': messageTemplate.featuresMin,
+  'features.max': messageTemplate.featuresMax,
+  'features.length': messageTemplate.featuresLength,
+
+  'files.min': messageTemplate.filesMin,
+  'files.max': messageTemplate.filesMax,
+  'filees.length': messageTemplate.filesLength,
+
+  'object.invalidjson': messageTemplate.format,
+
+  'phoneNumber.invalid': messageTemplate.format
 }
 
 export const messagesPre: LanguageMessages =
   messages as unknown as LanguageMessages
 
 export function buildLanguageMessages(
-  t: (key: string) => string
+  t: (key: string, options?: Record<string, unknown>) => string
 ): LanguageMessages {
   const vm = buildValidationMessages(t)
   return {
@@ -76,6 +90,7 @@ export function buildLanguageMessages(
     'string.email': vm.format,
     'string.pattern.base': vm.pattern,
     'string.maxWords': vm.maxWords,
+    'string.unicode': vm.unicode,
     'number.base': vm.number,
     'number.precision': vm.numberPrecision,
     'number.integer': vm.numberInteger,
@@ -91,7 +106,17 @@ export function buildLanguageMessages(
     'date.format': vm.dateFormat,
     'date.min': vm.dateMin,
     'date.max': vm.dateMax,
-    'object.invalidjson': vm.format
+    'array.min': vm.arrayMin,
+    'array.max': vm.arrayMax,
+    'array.length': vm.arrayLength,
+    'features.min': vm.featuresMin,
+    'features.max': vm.featuresMax,
+    'features.length': vm.featuresLength,
+    'files.min': vm.filesMin,
+    'files.max': vm.filesMax,
+    'files.length': vm.filesLength,
+    'object.invalidjson': vm.format,
+    'phoneNumber.invalid': vm.format
   } as unknown as LanguageMessages
 }