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

package/src/server/plugins/engine/components/PaymentField.ts

@@ -45,6 +45,7 @@ export class PaymentField extends FormComponent {
   declare options: PaymentFieldComponent['options']
   declare formSchema: ObjectSchema
   declare stateSchema: ObjectSchema
+  declare def: PaymentFieldComponent
   isAppendageStateSingleObject = true
 
   constructor(
@@ -54,6 +55,7 @@ export class PaymentField extends FormComponent {
     super(def, props)
 
     this.options = def.options
+    this.def = def
 
     const paymentStateSchema = joi
       .object({
@@ -61,6 +63,7 @@ export class PaymentField extends FormComponent {
         reference: joi.string().required(),
         amount: joi.number().required(),
         description: joi.string().required(),
+        descriptionInEng: joi.string().optional(),
         uuid: joi.string().uuid().required(),
         formId: joi.string().required(),
         isLivePayment: joi.boolean().required(),
@@ -110,6 +113,8 @@ export class PaymentField extends FormComponent {
   getViewModel(context: RenderContext) {
     const { payload } = context
     const viewModel = super.getViewModel(context)
+    const { translator } = context
+    const { tComponent } = translator
 
     // Payload is pre-populated from state if a payment has already been made
     const paymentState = this.isPaymentState(payload[this.name] as unknown)
@@ -124,7 +129,8 @@ export class PaymentField extends FormComponent {
     return {
       ...viewModel,
       amount: formatCurrency(amount),
-      description: this.options.description,
+      description:
+        tComponent(this.def, 'paymentDescription') || this.options.description,
       paymentState
     }
   }
@@ -234,8 +240,9 @@ export class PaymentField extends FormComponent {
   ): Promise<unknown> {
     const { options, name: componentName } = args.component
     const { model } = args.controller
-    const language = resolveLanguage(request)
-    const { t } = model.createTranslator(language)
+    const { language, t, tComponent } = model.createTranslator(
+      resolveLanguage(request)
+    )
     const state = await args.controller.getState(request)
     const { baseUrl } = getPluginOptions(request.server)
     const summaryUrl = `${baseUrl}/${model.basePath}/summary`
@@ -267,7 +274,8 @@ export class PaymentField extends FormComponent {
       return h.redirect(summaryUrl).code(StatusCodes.SEE_OTHER)
     }
 
-    const description = options.description
+    const description =
+      tComponent(args.component, 'paymentDescription') || options.description
 
     const slug = `/${model.basePath}`
 
@@ -287,7 +295,7 @@ export class PaymentField extends FormComponent {
       payCallbackUrl,
       reference,
       isLivePayment,
-      { formId, slug },
+      { formId, slug, language },
       prefilledEmail
     )
 
@@ -308,6 +316,7 @@ export class PaymentField extends FormComponent {
       reference,
       amount: resolvedAmount,
       description,
+      descriptionInEng: options.description,
       paymentId: payment.paymentId,
       componentName,
       returnUrl: summaryUrl,
@@ -444,6 +453,7 @@ export interface PaymentSessionData {
   reference: string
   amount: number
   description: string
+  descriptionInEng?: string
   paymentId: string
   componentName: string
   returnUrl: string

package/src/server/plugins/engine/components/UkAddressField.ts

@@ -1,4 +1,9 @@
-import { ComponentType, type UkAddressFieldComponent } from '@defra/forms-model'
+import {
+  ComponentType,
+  FormStatus,
+  type FormMetadata,
+  type UkAddressFieldComponent
+} from '@defra/forms-model'
 import { type ObjectSchema } from 'joi'
 import lowerFirst from 'lodash/lowerFirst.js'
 
@@ -9,6 +14,8 @@ import {
 } from './FormComponent.js'
 import { TextField } from './TextField.js'
 import { type RenderContext } from './types.js'
+import { getCachedPluginTranslator } from '../i18n/form.js'
+import { getAvailableLanguages } from '../i18n/languages.js'
 import { type Translator } from '../i18n/types.js'
 import {
   type FormRequestPayload,
@@ -207,7 +214,7 @@ export class UkAddressField extends FormComponent {
 
         /**
          * For screen readers, only hide legend visually. This can be overridden
-         * by single component {@link QuestionPageController | `showTitle` handling}
+         * by single component (see QuestionPageController and showTitle handling)
          */
         classes: options.hideTitle
           ? 'govuk-visually-hidden'
@@ -290,7 +297,6 @@ export class UkAddressField extends FormComponent {
     )
   }
 
-  // eslint-disable-next-line @typescript-eslint/require-await
   static async dispatcher(
     request: FormRequestPayload,
     h: FormResponseToolkit,
@@ -299,14 +305,31 @@ export class UkAddressField extends FormComponent {
     const { controller, component } = args
     const language = resolveLanguage(request)
 
+    const availableLanguages = getAvailableLanguages(controller.model.def)
+    const languages = availableLanguages.length
+      ? { languages: availableLanguages }
+      : {}
+
+    const translator = await getCachedPluginTranslator(
+      request,
+      { id: controller.model.formId } as unknown as FormMetadata,
+      args.isLive ? FormStatus.Live : FormStatus.Draft,
+      language
+    )
+    const { tComponent, tForm } = translator
+
     return dispatch(request, h, {
-      formName: controller.model.name,
+      formName: tForm('title'),
+      formId: controller.model.formId,
+      formStatus: args.isLive ? FormStatus.Live : FormStatus.Draft,
+      componentId: component.id ?? 'unknown',
       componentName: component.name,
-      componentHint: component.hint,
-      componentTitle: component.title || controller.title,
+      componentHint: tComponent(component, 'hint'),
+      componentTitle: tComponent(component, 'title') || controller.title,
       step: args.actionArgs.step,
       sourceUrl: args.sourceUrl,
-      language
+      language,
+      ...languages
     })
   }
 }

package/src/server/plugins/engine/components/YesNoField.ts

@@ -4,7 +4,6 @@ import {
   yesNoListName,
   type YesNoFieldComponent
 } from '@defra/forms-model'
-import { type LanguageMessages } from 'joi'
 
 import { SelectionControlField } from './SelectionControlField.js'
 import { addClassOptionIfNone } from './helpers/index.js'
@@ -12,7 +11,6 @@ import { buildValidationMessages } from '../i18n/buildValidationMessages.js'
 import { type Translator } from '../i18n/types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import { type ErrorMessageTemplateList } from '../types.js'
-import { convertToLanguageMessages } from '../../../utils/type-utils.js'
 
 /**
  * @description
@@ -45,21 +43,31 @@ export class YesNoField extends SelectionControlField {
       formSchema = formSchema.optional()
     }
 
-    formSchema = formSchema.messages(
-      convertToLanguageMessages({
+    if (options.customValidationMessage) {
+      const message = options.customValidationMessage
+
+      formSchema = formSchema.messages({
+        'any.required': message
+      })
+    } else if (options.customValidationMessages) {
+      formSchema = formSchema.messages(options.customValidationMessages)
+    } else {
+      formSchema = formSchema.messages({
         'any.required': messageTemplate.selectYesNoRequired
       })
-    )
+    }
 
     this.formSchema = formSchema
     this.options = options
   }
 
-  getValidationMessagesOverride(translator: Translator): LanguageMessages {
+  getValidationMessagesOverride(translator: Translator) {
     const { selectYesNoRequired } = buildValidationMessages(translator.t)
-    return convertToLanguageMessages({
-      'any.required': selectYesNoRequired
-    })
+    return {
+      [this.name]: {
+        'any.required': selectYesNoRequired
+      }
+    }
   }
 
   /**

package/src/server/plugins/engine/components/helpers/components.ts

@@ -6,6 +6,7 @@ import { ListFormComponent } from '../ListFormComponent.js'
 import { escapeMarkdown } from './index.js'
 import * as Components from '../index.js'
 import { markdown } from '../markdownParser.js'
+import { UnknownComponentTypeError } from '../../errors.js'
 import { type Translator } from '../../i18n/types.js'
 import { type FormState } from '../../types.js'
 
@@ -210,7 +211,7 @@ export function createComponent(
   }
 
   if (typeof component === 'undefined') {
-    throw new Error(`Component type ${def.type} does not exist`)
+    throw new UnknownComponentTypeError(def.type)
   }
 
   return component
@@ -347,8 +348,7 @@ export function getAnswerMarkdown(
     field instanceof Components.EastingNorthingField ||
     field instanceof Components.LatLongField
   ) {
-    const contextValue = field.getContextValueFromState(state)
-    answerEscaped = contextValue ? `${contextValue}\n` : ''
+    answerEscaped = answer ? `${answer}\n` : ''
   } else if (field instanceof Components.GeospatialField) {
     const features = field.getFormValueFromState(state)
     const value = field.getDisplayStringFromFormValue(features, translator)

package/src/server/plugins/engine/components/helpers/geospatial.ts

@@ -1,12 +1,16 @@
 import {
-  GeospatialFieldOptionsCountryEnum,
   type GeospatialFieldComponent,
   type GeospatialFieldOptionsCountry
 } from '@defra/forms-model'
 import Bourne from '@hapi/bourne'
 import { booleanWithin } from '@turf/boolean-within'
+import { point } from '@turf/helpers'
+// @ts-expect-error - no types
+import OsGridRef from 'geodesy/osgridref.js'
 import JoiBase, { type CustomValidator } from 'joi'
 
+import { type EastingNorthingField } from '../EastingNorthingField.js'
+import { type EastingNorthingState } from '../types.js'
 import {
   type Coordinates,
   type Feature,
@@ -15,13 +19,6 @@ import {
 } from '../../types.js'
 import { countries } from '../../../map/routes/index.js'
 
-const countriesDesc: Record<GeospatialFieldOptionsCountryEnum, string> = {
-  [GeospatialFieldOptionsCountryEnum.England]: 'England',
-  [GeospatialFieldOptionsCountryEnum.NorthernIreland]: 'Northern Ireland',
-  [GeospatialFieldOptionsCountryEnum.Scotland]: 'Scotland',
-  [GeospatialFieldOptionsCountryEnum.Wales]: 'Wales'
-}
-
 const Joi = JoiBase.extend({
   type: 'array',
   base: JoiBase.array(),
@@ -98,25 +95,43 @@ const featureSchema = Joi.object<Feature>().keys({
   geometry: featureGeometrySchema
 })
 
-function applySchemaConstraints(
-  schema: JoiBase.ArraySchema<Feature[]>,
-  def: GeospatialFieldComponent
+export function determineLimits(
+  def: GeospatialFieldComponent,
+  isOptional: boolean
 ) {
-  const { options, schema: constraints } = def
-  const isOptional = options.required === false
-
+  const { schema: constraints } = def
+  const limits: { min?: number; max?: number; length?: number } = {}
   if (typeof constraints?.length === 'number') {
-    schema = schema.length(constraints.length)
+    limits.length = constraints.length
   } else {
     if (typeof constraints?.min === 'number') {
-      schema = schema.min(constraints.min)
+      limits.min = constraints.min
     } else if (!isOptional) {
-      schema = schema.min(1)
+      limits.min = 1
     }
 
-    schema = schema.max(
-      typeof constraints?.max === 'number' ? constraints.max : 50
-    )
+    limits.max = typeof constraints?.max === 'number' ? constraints.max : 50
+  }
+  return limits
+}
+
+function applySchemaConstraints(
+  schema: JoiBase.ArraySchema<Feature[]>,
+  def: GeospatialFieldComponent
+) {
+  const { options } = def
+  const isOptional = options.required === false
+
+  const limits = determineLimits(def, isOptional)
+
+  if (limits.length !== undefined) {
+    schema = schema.length(limits.length)
+  }
+  if (limits.min !== undefined) {
+    schema = schema.min(limits.min)
+  }
+  if (limits.max !== undefined) {
+    schema = schema.max(limits.max)
   }
 
   if (isOptional) {
@@ -156,7 +171,7 @@ export function getGeospatialSchema(
 
     if (!result) {
       return helpers.error('any.custom', {
-        country: countriesDesc[country as GeospatialFieldOptionsCountryEnum]
+        country
       })
     }
 
@@ -171,3 +186,51 @@ export function getGeospatialSchema(
     def
   )
 }
+
+export function getEastingNorthingCountryValidator(
+  field: EastingNorthingField,
+  country: GeospatialFieldOptionsCountry
+) {
+  const validateCountryBounds: CustomValidator = (value, helpers) => {
+    const countryFeature = countries.features.find(
+      (feature) => feature.id === country
+    )
+
+    if (!countryFeature) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return value
+    }
+
+    const eastingNorthing = field.getFormValueFromState(
+      value as EastingNorthingState
+    )
+
+    if (!eastingNorthing) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return value
+    }
+
+    const gridRef = new OsGridRef(
+      eastingNorthing.easting,
+      eastingNorthing.northing
+    )
+    const latLong = gridRef.toLatLon()
+    const coord = point([latLong.longitude, latLong.latitude])
+    const within = booleanWithin(coord, countryFeature)
+
+    if (!within) {
+      return helpers.error(
+        'any.custom',
+        {
+          country
+        },
+        { path: [field.name] }
+      )
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return value
+  }
+
+  return validateCountryBounds
+}

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

@@ -2,6 +2,8 @@ import { type ComponentDef } from '@defra/forms-model'
 import joi, { type JoiExpression, type ReferenceOptions } from 'joi'
 import lowerFirst from 'lodash/lowerFirst.js'
 
+import { type Translator } from '../../i18n/types.js'
+
 /**
  * Prevent Markdown formatting
  * @see {@link https://pandoc.org/chunkedhtml-demo/8.11-backslash-escapes.html}
@@ -66,3 +68,20 @@ export const lowerFirstExpressionOptions = {
  */
 export const createLowerFirstExpression = (template: string): JoiExpression =>
   joi.expression(template, lowerFirstExpressionOptions) as JoiExpression
+
+/**
+ * Translate a component label, in precedence order of errorDescription, then shortDesciption, then title
+ * @param {ComponentDef} component
+ * @param {Translator} translator
+ */
+export function getTranslatedLabel(
+  component: ComponentDef,
+  translator: Translator
+) {
+  const { tComponent } = translator
+  const translatedLabel =
+    tComponent(component, 'errorDescription') ||
+    tComponent(component, 'shortDescription') ||
+    tComponent(component, 'title')
+  return translatedLabel
+}

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

@@ -124,6 +124,7 @@ export interface ViewModel extends Record<string, unknown> {
   upload?: {
     count: number
     summaryList: SummaryList
+    uploadingLabel?: string
   }
 }
 

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

@@ -0,0 +1,78 @@
+import { type ValidationError } from 'joi'
+
+/**
+ * Base class for errors caused by an invalid form definition — whether it
+ * fails schema validation or passes the schema but cannot be used by the
+ * engine. Never thrown directly — throw a subclass. Consumers (e.g.
+ * forms-runner error pages) detect the family with
+ * `instanceof InvalidFormDefinitionError`.
+ *
+ * When subclassing, remember that the message and the messages of any
+ * `cause` chain are shown to form authors on preview error pages. Only
+ * describe the problem with the form itself — never include sensitive
+ * details such as file paths, configuration values or secrets.
+ */
+export class InvalidFormDefinitionError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'InvalidFormDefinitionError'
+  }
+}
+
+/**
+ * Thrown when a condition in the definition cannot be compiled into an
+ * evaluatable expression (e.g. it references the wrong component or list).
+ */
+export class ConditionBuildError extends InvalidFormDefinitionError {
+  public readonly conditionName: string
+
+  constructor(conditionName: string, options?: ErrorOptions) {
+    super(`Failed to build condition '${conditionName}'`, options)
+    this.name = 'ConditionBuildError'
+    this.conditionName = conditionName
+  }
+}
+
+/**
+ * Thrown when a page names a controller that is neither built in nor
+ * registered by the host application.
+ */
+export class UnknownPageControllerError extends InvalidFormDefinitionError {
+  public readonly controllerName: string
+
+  constructor(controllerName: string) {
+    super(`Page controller ${controllerName} does not exist`)
+    this.name = 'UnknownPageControllerError'
+    this.controllerName = controllerName
+  }
+}
+
+/**
+ * Thrown when a component declares a type with no registered implementation.
+ */
+export class UnknownComponentTypeError extends InvalidFormDefinitionError {
+  public readonly componentType: string
+
+  constructor(componentType: string) {
+    super(`Component type ${componentType} does not exist`)
+    this.name = 'UnknownComponentTypeError'
+    this.componentType = componentType
+  }
+}
+
+/**
+ * Thrown when a form definition fails Joi schema validation. The raw
+ * ValidationError is preserved as `cause` so consumers can reach the
+ * per-field details; the message carries Joi's own summary so log lines
+ * remain diagnostic for consumers that only read `error.message`.
+ */
+export class SchemaValidationError extends InvalidFormDefinitionError {
+  // Error types `cause` as unknown; this constructor only accepts a Joi
+  // ValidationError, so narrow the declaration for consumers (type-only).
+  declare cause: ValidationError
+
+  constructor(cause: ValidationError) {
+    super(`Invalid form definition: ${cause.message}`, { cause })
+    this.name = 'SchemaValidationError'
+  }
+}

package/src/server/plugins/engine/form-availability.ts

@@ -1,9 +1,14 @@
-import { FormStatus, type FormMetadata } from '@defra/forms-model'
+import {
+  FormStatus,
+  type FormDefinition,
+  type FormMetadata
+} from '@defra/forms-model'
 import Boom from '@hapi/boom'
 
 export interface OfflineBoomData {
   offline: true
   metadata: FormMetadata
+  definition: FormDefinition | undefined
 }
 
 /**
@@ -13,6 +18,7 @@ export interface OfflineBoomData {
  */
 export function assertFormAvailable(
   metadata: FormMetadata,
+  definition: FormDefinition | undefined,
   formState: FormStatus,
   isPreview: boolean
 ): void {
@@ -21,7 +27,7 @@ export function assertFormAvailable(
     formState === FormStatus.Live &&
     !isPreview
   ) {
-    const data: OfflineBoomData = { offline: true, metadata }
+    const data: OfflineBoomData = { offline: true, metadata, definition }
     throw Boom.boomify(new Error(`Form ${metadata.slug} is offline`), {
       statusCode: 503,
       data

package/src/server/plugins/engine/form-context.ts

@@ -56,13 +56,14 @@ export async function getFormModel(
   const formState = resolveState(state)
 
   const metadata = await formsService.getFormMetadata(slug)
-  assertFormAvailable(metadata, formState, isPreview)
 
   const definition = await formsService.getFormDefinition(
     metadata.id,
     formState
   )
 
+  assertFormAvailable(metadata, definition, formState, isPreview)
+
   if (!definition) {
     throw Boom.notFound(
       `No definition found for form metadata ${metadata.id} (${slug}) ${state}`
@@ -145,7 +146,6 @@ export async function resolveFormModel(
   const metadata = await formsService.getFormMetadata(slug)
   const formState = resolveState(state)
   const isPreview = options.isPreview ?? isPreviewState(state, options)
-  assertFormAvailable(metadata, formState, isPreview)
   const stateMetadata = metadata[formState]
 
   if (!stateMetadata) {
@@ -199,6 +199,8 @@ export async function resolveFormModel(
     cache.set(cacheKey, entry)
   }
 
+  assertFormAvailable(metadata, entry.model.def, formState, isPreview)
+
   return entry.model
 }
 

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

@@ -8,13 +8,14 @@ import {
 } from '@defra/forms-model'
 import Boom from '@hapi/boom'
 import { type ResponseToolkit, type Server } from '@hapi/hapi'
-import { format, parseISO } from 'date-fns'
+import { format, parseISO, type Locale } from 'date-fns'
+import { cy, enGB } from 'date-fns/locale'
 import { StatusCodes } from 'http-status-codes'
 import { type Schema, type ValidationErrorItem } from 'joi'
 import { Liquid } from 'liquidjs'
 
 import { logger } from '../../common/helpers/logging/logger.js'
-import { FORM_VERSION_METADATA_KEY } from '../../constants.js'
+import { CY, EN_GB, FORM_VERSION_METADATA_KEY } from '../../constants.js'
 import {
   getAnswer,
   type Field
@@ -300,19 +301,24 @@ export function checkEmailAddressForLiveFormSubmission(
 
 /**
  * Parses the errors from {@link Schema.validate} so they can be rendered by govuk-frontend templates
+ * @param language - the target language for translations
  * @param [details] - provided by {@link Schema.validate}
  */
 export function getErrors(
+  language: string | undefined,
   details?: ValidationErrorItem[]
 ): FormSubmissionError[] | undefined {
   if (!details?.length) {
     return
   }
 
-  return details.map(getError)
+  return details.map((detail) => getError(language, detail))
 }
 
-export function getError(detail: ValidationErrorItem): FormSubmissionError {
+export function getError(
+  language: string | undefined,
+  detail: ValidationErrorItem
+): FormSubmissionError {
   const { context, message, path } = detail
 
   const name = context?.key ?? ''
@@ -320,7 +326,10 @@ export function getError(detail: ValidationErrorItem): FormSubmissionError {
 
   const text = message.replace(
     /\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d\.\d+([+-][0-2]\d:[0-5]\d|Z)/,
-    (text) => format(parseISO(text), 'd MMMM yyyy')
+    (text) =>
+      format(parseISO(text), 'd MMMM yyyy', {
+        locale: toLanguageLocale(language)
+      })
   )
 
   return {
@@ -410,3 +419,41 @@ export function getFormVersion(
     | FormVersionMetadata
     | undefined
 }
+
+const payLanguageCodes = {
+  [EN_GB]: 'en',
+  [CY]: 'cy'
+} as Record<string, string>
+
+const languageLocales = {
+  [EN_GB]: enGB,
+  [CY]: cy
+} as Record<string, Locale>
+
+const defaultLanguageCode = 'en'
+const defaultLanguageLocale = enGB
+
+/**
+ * Converts a BCP 47 language tag to the ISO 639-1 code GOV.UK Pay accepts.
+ * Defaults to English if the language is not supported.
+ * @param { string | undefined } language - BCP 47 language code
+ * @returns {string} language code required by GOV.UK Pay
+ */
+export function toPayLanguageCode(language: string | undefined): string {
+  return payLanguageCodes[language ?? 'unknown'] ?? defaultLanguageCode
+}
+
+/**
+ * Converts a BCP 47 language tag to the date-fns Locale (for date formatting).
+ * Defaults to English if the language is not supported.
+ * @param { string | undefined } language - BCP 47 language code
+ * @returns {Locale} language locale
+ */
+export function toLanguageLocale(language: string | undefined): Locale {
+  return languageLocales[language ?? 'unknown'] ?? defaultLanguageLocale
+}
+
+/**
+ * @import { FormsService } from '../../types.js'
+ * @import { Locale } from 'date-fns/locale'
+ */