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

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

@@ -1,7 +1,13 @@
 import { type ComponentDef } from '@defra/forms-model'
-import joi, { type JoiExpression, type ReferenceOptions } from 'joi'
+import joi, {
+  type JoiExpression,
+  type LanguageMessages,
+  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 +72,60 @@ export const lowerFirstExpressionOptions = {
  */
 export const createLowerFirstExpression = (template: string): JoiExpression =>
   joi.expression(template, lowerFirstExpressionOptions) as JoiExpression
+
+/**
+ * Joi's own LanguageMessages type only allows string values, but
+ * buildValidationMessages() returns JoiExpression for templated messages,
+ * which Joi accepts at runtime. This type covers both.
+ */
+type TranslatedValidationMessages = Record<string, string | JoiExpression>
+
+/**
+ * Keep the form author's custom validation message for any key they set,
+ * so translated defaults only fill in the keys the author left blank.
+ * A single customValidationMessage covers every key in the schema.
+ */
+export function withCustomValidationOverrides(
+  defaults: TranslatedValidationMessages,
+  customValidationMessage?: string,
+  customValidationMessages?: LanguageMessages
+): LanguageMessages {
+  const messages: TranslatedValidationMessages = {}
+
+  // A global override for all messages is the value for all scenarios
+  if (customValidationMessage) {
+    for (const key of Object.keys(defaults)) {
+      messages[key] = customValidationMessage
+    }
+
+    return messages as LanguageMessages
+  }
+
+  // A default only fills a key that the user has not configured
+  const authorKeys = Object.keys(customValidationMessages ?? {})
+
+  for (const [key, message] of Object.entries(defaults)) {
+    if (!authorKeys.includes(key)) {
+      messages[key] = message
+    }
+  }
+
+  return messages as LanguageMessages
+}
+
+/**
+ * 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/index.ts

@@ -30,5 +30,6 @@ export { OsGridRefField } from './OsGridRefField.js'
 export { NationalGridFieldNumberField } from './NationalGridFieldNumberField.js'
 export { LatLongField } from './LatLongField.js'
 export { HiddenField } from './HiddenField.js'
+export { TrackingField } from './TrackingField.js'
 export { PaymentField } from './PaymentField.js'
 export { GeospatialField } from './GeospatialField.js'

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'
+ */

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

@@ -16,7 +16,9 @@ const opts = {
  * because Joi cannot resolve custom functions from a plain string.
  * Plain strings with only built-in tokens ({{#label}}, {{#limit}}) work without wrapping.
  */
-export function buildValidationMessages(t: (key: string) => string) {
+export function buildValidationMessages(
+  t: (key: string, options?: Record<string, unknown>) => string
+) {
   return {
     // Expressions — contain lowerFirst custom function
     required: joi.expression(t('validation.required'), opts) as JoiExpression,
@@ -56,13 +58,19 @@ export function buildValidationMessages(t: (key: string) => string) {
     dateMin: t('components.dateField.validation.dateMin'),
     dateMax: t('components.dateField.validation.dateMax'),
 
-    unicode: 'validation.unicode',
-    arrayMin: 'validation.array.min',
-    arrayMax: 'validation.array.max',
-    arrayLength: 'validation.array.length',
-    featuresMin: 'validation.features.min',
-    featuresMax: 'validation.features.max',
-    featuresLength: 'validation.features.length'
+    unicode: t('validation.unicode'),
+    // These generic templates are shared across fields with differing limits, so a
+    // fixed singular count is used here — components needing accurate singular/plural
+    // text (e.g. FileUploadField) build their own per-instance messages instead.
+    arrayMin: t('validation.arrayMin', { count: 1 }),
+    arrayMax: t('validation.arrayMax', { count: 1 }),
+    arrayLength: t('validation.arrayLength', { count: 1 }),
+    featuresMin: t('validation.featuresMin', { count: 1 }),
+    featuresMax: t('validation.featuresMax', { count: 1 }),
+    featuresLength: t('validation.featuresLength', { count: 1 }),
+    filesMin: t('validation.filesMin', { count: 1 }),
+    filesMax: t('validation.filesMax', { count: 1 }),
+    filesLength: t('validation.filesLength', { count: 1 })
   }
 }
 

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

@@ -1,30 +1,40 @@
 import {
   yesNoListNoItemId,
   yesNoListYesItemId,
-  type FormDefinition
+  type FormDefinition,
+  type FormMetadata
 } from '@defra/forms-model'
 import { type i18n } from 'i18next'
 
+import { CY } from '../../../constants.js'
 import { createTranslator } from './createTranslator.js'
 import { extractBaseTranslations } from './extractBaseTranslations.js'
 import { createFormI18nInstance } from './index.js'
-import {
-  type FormDefinitionTranslations,
-  type Translator
-} from './types.js'
+import { type FormDefinitionTranslations } from './types.js'
 
 export function createFormTranslator(
-  def: FormDefinition,
+  metadata: FormMetadata,
+  definition: FormDefinition | undefined,
   language: string
-): Translator {
-  const baseTranslations = extractBaseTranslations(def)
+) {
+  const baseTranslations = extractBaseTranslations(definition)
   const i18nInstance = createFormI18nInstance(baseTranslations)
-  loadFormTranslations(def, i18nInstance)
+  loadFormTranslations(definition, i18nInstance)
+  extractMetadataBaseTranslations(metadata, i18nInstance)
+
+  const translator = createTranslator(i18nInstance, language)
 
-  return createTranslator(i18nInstance, language)
+  return translator
 }
 
-export function loadFormTranslations(def: FormDefinition, i18nInstance: i18n) {
+export function loadFormTranslations(
+  def: FormDefinition | undefined,
+  i18nInstance: i18n
+) {
+  if (!def) {
+    return
+  }
+
   const formTranslations = def.metadata?.translations as
     | FormDefinitionTranslations
     | undefined
@@ -34,7 +44,7 @@ export function loadFormTranslations(def: FormDefinition, i18nInstance: i18n) {
       i18nInstance.addResourceBundle(lng, 'form', resources, true, true)
 
       // Temporary workaround - until we develop a better solution
-      if (lng === 'cy') {
+      if (lng === CY) {
         i18nInstance.addResource(
           lng,
           'form',
@@ -51,3 +61,24 @@ export function loadFormTranslations(def: FormDefinition, i18nInstance: i18n) {
     }
   }
 }
+
+export function extractMetadataBaseTranslations(
+  metadata: FormMetadata | undefined,
+  i18nInstance: i18n
+) {
+  if (metadata) {
+    const translations = {
+      'form.title': metadata.title,
+      'form.contact.email.address': metadata.contact?.email?.address ?? '',
+      'form.contact.email.responseTime':
+        metadata.contact?.email?.responseTime ?? '',
+      'form.contact.online.url': metadata.contact?.online?.url ?? '',
+      'form.contact.online.text': metadata.contact?.online?.text ?? '',
+      'form.contact.phone': metadata.contact?.phone ?? '',
+      'form.submissionGuidance': metadata.submissionGuidance ?? '',
+      'form.privacyNoticeText': metadata.privacyNoticeText ?? '',
+      'form.privacyNoticeUrl': metadata.privacyNoticeUrl ?? ''
+    }
+    i18nInstance.addResourceBundle('en-GB', 'form', translations, true, true)
+  }
+}

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

@@ -7,13 +7,19 @@ import { type FormDefinitionTranslations } from './types.js'
 
 type BaseTranslations = FormDefinitionTranslations[string]
 
-export function extractBaseTranslations(def: FormDefinition): BaseTranslations {
+export function extractBaseTranslations(
+  def: FormDefinition | undefined
+): BaseTranslations {
   const pages: BaseTranslations['pages'] = {}
   const components: BaseTranslations['components'] = {}
   const sections: BaseTranslations['sections'] = {}
   const listItems: BaseTranslations['listItems'] = {}
   const form: BaseTranslations['form'] = {}
 
+  if (!def) {
+    return { pages, components, sections, listItems, form }
+  }
+
   for (const page of def.pages) {
     if (page.id && page.title) {
       pages[page.id] = { title: page.title }

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

@@ -0,0 +1,54 @@
+import { type FormMetadata, type FormStatus } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import { LRUCache } from 'lru-cache'
+
+import { getPluginOptions } from '../helpers.js'
+import { createFormTranslator } from './createFormTranslator.js'
+import { type Translator } from './types.js'
+import { type AnyFormRequest } from '../types.js'
+
+const cache = new LRUCache({
+  max: 100,
+  ttl: 1000 * 60 * 15 // 15 minutes
+})
+
+/**
+ * Get translator for plugin, for the current form's metadata (as well as the plugin-specific boilerplate).
+ * This is an async call so we can read the form definition inside this call.
+ * See docs/features/multi-language.md for the language and translation flow overview.
+ * @param {AnyFormRequest} request
+ * @param {FormMetadata} metadata - the metadata of the form
+ * @param {FormStatus} status - the form status to use when retrieving the definition
+ * @param {string} language - the language to use for the translator
+ */
+export async function getCachedPluginTranslator(
+  request: AnyFormRequest,
+  metadata: FormMetadata,
+  status: FormStatus,
+  language: string
+) {
+  const key = `${metadata.id}-${status}-${language}-plugin-meta`
+
+  if (cache.has(key)) {
+    return cache.get(key) as unknown as Translator
+  }
+
+  const { services } = getPluginOptions(request.server)
+
+  const definition = await services?.formsService.getFormDefinition(
+    metadata.id,
+    status
+  )
+
+  if (!definition) {
+    throw Boom.notFound(
+      `FormDefinition not found for form ${metadata.id} and status ${status}`
+    )
+  }
+
+  const translator = createFormTranslator(metadata, definition, language)
+
+  cache.set(key, translator)
+
+  return translator
+}

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

@@ -0,0 +1,19 @@
+import { type FormDefinition } from '@defra/forms-model'
+
+/**
+ * Return a list of available languages.
+ * Empty array if only English, or an array of English and Welsh if translations have been defined.
+ * @param {FormDefinition} def
+ */
+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 []
+}