@defra/forms-engine-plugin 4.23.0 → 5.0.0-alpha.1

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

@@ -9,6 +9,8 @@ import {
   FormComponent,
   isUploadState
 } from './FormComponent.js'
+import { type RenderContext } from './types.js'
+import { type Translator } from '../i18n/types.js'
 import { InvalidComponentStateError } from '../pageControllers/errors.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
@@ -19,10 +21,8 @@ import {
   type FileUpload,
   type FileUploadMetadata,
   type FormContext,
-  type FormPayload,
   type FormState,
   type FormStateValue,
-  type FormSubmissionError,
   type FormSubmissionState,
   type SummaryList,
   type SummaryListAction,
@@ -32,10 +32,8 @@ import {
   type UploadStatusResponse
 } from '../types.js'
 import { render } from '../../nunjucks/index.js'
-import {
-  type FormQuery,
-  type FormRequestPayload
-} from '../../../routes/types.js'
+import { type FormRequestPayload } from '../../../routes/types.js'
+import { resolveLanguage } from '../../../utils/utils.js'
 
 export const uploadIdSchema = joi.string().uuid().required()
 
@@ -163,19 +161,26 @@ export class FileUploadField extends FormComponent {
     return this.isValue(value) ? value : undefined
   }
 
-  getDisplayStringFromFormValue(files: FileState[] | undefined): string {
+  getDisplayStringFromFormValue(
+    files: FileState[] | undefined,
+    translator: Translator
+  ): string {
     if (!files?.length) {
       return ''
     }
 
-    const unit = files.length === 1 ? 'file' : 'files'
-    return `Uploaded ${files.length} ${unit}`
+    return translator.t('components.fileUploadField.filesCount', {
+      count: files.length
+    })
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const files = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(files)
+    return this.getDisplayStringFromFormValue(files, translator)
   }
 
   getContextValueFromFormValue(
@@ -189,17 +194,12 @@ export class FileUploadField extends FormComponent {
     return this.getContextValueFromFormValue(files)
   }
 
-  getViewModel(
-    payload: FormPayload,
-    errors?: FormSubmissionError[],
-    query: FormQuery = {}
-  ) {
+  getViewModel(context: RenderContext) {
+    const { errors, isForceAccess = false } = context
+    const { t } = context.translator
     const { options, page, schema } = this
 
-    // Allow preview URL direct access
-    const isForceAccess = 'force' in query
-
-    const viewModel = super.getViewModel(payload, errors)
+    const viewModel = super.getViewModel(context)
     const { attributes, id, value } = viewModel
 
     const files = this.getFormValue(value) ?? []
@@ -213,7 +213,10 @@ export class FileUploadField extends FormComponent {
       const { form } = status
       const { file } = form
 
-      const tag = { classes: 'govuk-tag--green', text: 'Uploaded' }
+      const tag = {
+        classes: 'govuk-tag--green',
+        text: t('components.fileUploadField.uploaded')
+      }
 
       const valueHtml = render
         .view('components/fileuploadfield-value.html', {
@@ -309,6 +312,9 @@ export class FileUploadField extends FormComponent {
     metadata: FormMetadata,
     context: FormContext
   ) {
+    const language = resolveLanguage(request)
+    const { t } = this.model.createTranslator(language)
+
     const notificationEmail = metadata.notificationEmail
 
     if (!notificationEmail) {
@@ -347,7 +353,7 @@ export class FileUploadField extends FormComponent {
         // Scenarios: file missing from S3, invalid retrieval key (timing problem), etc.
         throw new InvalidComponentStateError(
           this,
-          'There was a problem with your uploaded files. Re-upload them before submitting the form again.'
+          t('components.fileUploadField.uploadFailed')
         )
       }
 

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

@@ -1,11 +1,14 @@
 import {
+  type ComponentDef,
   type FormComponentsDef,
   type FormMetadata,
   type Item
 } from '@defra/forms-model'
+import { type LanguageMessages } from 'joi'
 
 import { ComponentBase } from './ComponentBase.js'
-import { optionalText } from './constants.js'
+import { type RenderContext } from './types.js'
+import { type Translator } from '../i18n/types.js'
 import {
   type FormContext,
   type FormRequestPayload
@@ -115,7 +118,10 @@ export class FormComponent extends ComponentBase {
     }
   }
 
-  getErrors(errors?: FormSubmissionError[]): FormSubmissionError[] | undefined {
+  getErrors(
+    _translator: Translator,
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
     const { name } = this
 
     // Filter component and child errors only
@@ -134,34 +140,59 @@ export class FormComponent extends ComponentBase {
   }
 
   getFirstError(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError | undefined {
-    return this.getErrors(errors)?.[0]
+    return this.getErrors(translator, errors)?.[0]
   }
 
   getViewErrors(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    const firstError = this.getFirstError(errors)
+    const firstError = this.getFirstError(translator, errors)
     return firstError && [firstError]
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+  /**
+   * Override in composite fields to return translated Joi message overrides for
+   * their sub-fields, applied at validation time so schema-level English messages
+   * are replaced with the correct language. Return null to skip message patching.
+   */
+  getValidationMessagesOverride(
+    _translator: Translator
+  ): LanguageMessages | null {
+    return null
+  }
+
+  getViewModel({
+    payload,
+    errors,
+    translator,
+    isForceAccess: _isForceAccess = false
+  }: RenderContext) {
     const { hint, name, options = {}, title, viewModel } = this
 
+    const { t, tComponent } = translator
+
     const isRequired = !('required' in options) || options.required !== false
     const hideOptional = 'optionalText' in options && options.optionalText
-    const label = `${title}${!isRequired && !hideOptional ? optionalText : ''}`
+
+    const resolvedTitle =
+      tComponent(this as unknown as ComponentDef, 'title') || title
+    const optionalTag =
+      !isRequired && !hideOptional ? ` ${t('common.optional')}` : ''
+    const label = `${resolvedTitle}${optionalTag}`
 
     if (hint) {
       viewModel.hint = {
-        text: hint
+        text: tComponent(this as unknown as ComponentDef, 'hint') || hint
       }
     }
 
     // Filter component errors only
-    const componentErrors = this.getErrors(errors)
-    const componentError = this.getFirstError(componentErrors)
+    const componentErrors = this.getErrors(translator, errors)
+    const componentError = this.getFirstError(translator, componentErrors)
 
     if (componentErrors) {
       viewModel.errors = componentErrors
@@ -184,15 +215,21 @@ export class FormComponent extends ComponentBase {
     }
   }
 
-  getDisplayStringFromFormValue(value: FormValue | FormPayload): string {
+  getDisplayStringFromFormValue(
+    value: FormValue | FormPayload,
+    _translator: Translator
+  ): string {
     // Map selected values to text
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
     return this.isValue(value) ? value.toString() : ''
   }
 
-  getDisplayStringFromState(state: FormSubmissionState): string {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ): string {
     const value = this.getFormValueFromState(state)
-    return this.getDisplayStringFromFormValue(value)
+    return this.getDisplayStringFromFormValue(value, translator)
   }
 
   getContextValueFromFormValue(

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

@@ -6,11 +6,13 @@ import {
   FormComponent,
   isGeospatialState
 } from './FormComponent.js'
+import { getMapLayers } from './LocationFieldHelpers.js'
 import { getGeospatialSchema } from './helpers/geospatial.js'
+import { type RenderContext } from './types.js'
+import { type Translator } from '../i18n/types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
   type ErrorMessageTemplateList,
-  type FormPayload,
   type FormState,
   type FormStateValue,
   type FormSubmissionError,
@@ -31,13 +33,11 @@ export class GeospatialField extends FormComponent {
 
     const { options } = def
 
-    const formSchema = getGeospatialSchema(def)
-      .label(this.label)
-      .messages({
-        'array.min': messageTemplate.featuresMin as string,
-        'array.max': messageTemplate.featuresMax as string,
-        'array.length': messageTemplate.featuresLength as string
-      })
+    const formSchema = getGeospatialSchema(def).label(this.label).messages({
+      'array.min': messageTemplate.featuresMin,
+      'array.max': messageTemplate.featuresMax,
+      'array.length': messageTemplate.featuresLength
+    })
 
     this.formSchema = formSchema
     this.stateSchema = formSchema.default(null)
@@ -58,20 +58,26 @@ export class GeospatialField extends FormComponent {
     return this.isValue(value) ? value : undefined
   }
 
-  getDisplayStringFromFormValue(features: GeospatialState | undefined): string {
+  getDisplayStringFromFormValue(
+    features: GeospatialState | undefined,
+    translator: Translator
+  ): string {
     if (!features?.length) {
       return ''
     }
 
-    const unit = features.length === 1 ? 'location' : 'locations'
-
-    return `Added ${features.length} ${unit}`
+    return translator.t('components.geospatialField.added', {
+      count: features.length
+    })
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const features = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(features)
+    return this.getDisplayStringFromFormValue(features, translator)
   }
 
   getContextValueFromFormValue(
@@ -86,8 +92,8 @@ export class GeospatialField extends FormComponent {
     return this.getContextValueFromFormValue(features)
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
     const value =
       typeof viewModel.value === 'string'
         ? viewModel.value
@@ -97,20 +103,30 @@ export class GeospatialField extends FormComponent {
       ...viewModel,
       country: this.options.countries?.at(0),
       geometryTypes: this.options.geometryTypes,
+      mapLayers: getMapLayers(this),
       value
     }
   }
 
-  getErrors(errors?: FormSubmissionError[]): FormSubmissionError[] | undefined {
-    const fieldErrors = super.getErrors(errors)
+  getErrors(
+    translator: Translator,
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
+    const fieldErrors = super.getErrors(translator, errors)
 
     fieldErrors?.forEach((err) => {
       if (err.name === 'description') {
         err.href = `#description_${err.path[1]}`
-        err.text = `Enter description for location ${Number(err.path[1]) + 1}`
+        err.text = translator.t(
+          'components.geospatialField.validation.descriptionRequired',
+          { count: Number(err.path[1]) + 1 }
+        )
       } else if (typeof err.name === 'number' && err.context?.country) {
         err.href = `#description_${err.path[1]}`
-        err.text = `Location ${Number(err.path[1]) + 1} must be in ${err.context.country}`
+        err.text = translator.t(
+          'components.geospatialField.validation.wrongCountry',
+          { count: Number(err.path[1]) + 1, country: err.context.country }
+        )
       }
     })
 
@@ -118,9 +134,10 @@ export class GeospatialField extends FormComponent {
   }
 
   getViewErrors(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    return this.getErrors(errors)
+    return this.getErrors(translator, errors)
   }
 
   isValue(value?: FormStateValue | FormState): value is GeospatialState {

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

@@ -13,7 +13,12 @@ import {
 } from './LocationFieldHelpers.js'
 import { NumberField } from './NumberField.js'
 import { createLowerFirstExpression } from './helpers/index.js'
-import { type LatLongState } from './types.js'
+import {
+  type LatLongState,
+  type RenderContext
+} from './types.js'
+import { t as tPlugin } from '../i18n/index.js'
+import { type Translator } from '../i18n/types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
   type ErrorMessageTemplateList,
@@ -51,31 +56,50 @@ export class LatLongField extends FormComponent {
     const longitudeMin = schema?.longitude?.min ?? -13.687
     const longitudeMax = schema?.longitude?.max ?? 1.767
 
-    const latitudeRequired = 'Enter latitude'
-    const longitudeRequired = 'Enter longitude'
+    const fieldLabel = lowerFirst(this.label)
 
     const customValidationMessages: LanguageMessages =
       convertToLanguageMessages({
-        'number.precision':
-          '{{#label}} must have no more than 7 decimal places',
-        'number.unsafe': '{{#label}} must be a valid number'
+        'number.precision': tPlugin(
+          'components.latLongField.precision',
+          'en-GB'
+        ),
+        'number.unsafe': tPlugin('components.latLongField.notANumber', 'en-GB')
       })
 
-    const latitudeRangeMessage = `Latitude for ${lowerFirst(this.label)} must be between ${latitudeMin} and ${latitudeMax}`
-    const longitudeRangeMessage = `Longitude for ${lowerFirst(this.label)} must be between ${longitudeMin} and ${longitudeMax}`
+    const latitudeRangeMessage = tPlugin(
+      'components.latLongField.latitudeRange',
+      'en-GB',
+      { fieldLabel, min: latitudeMin, max: latitudeMax }
+    )
+    const longitudeRangeMessage = tPlugin(
+      'components.latLongField.longitudeRange',
+      'en-GB',
+      { fieldLabel, min: longitudeMin, max: longitudeMax }
+    )
 
     const latitudeMessages: LanguageMessages = convertToLanguageMessages({
       ...customValidationMessages,
-      'any.required': latitudeRequired,
-      'number.base': `Enter a valid latitude for ${lowerFirst(this.label)} like 51.519450`,
+      'any.required': tPlugin(
+        'components.latLongField.latitudeRequired',
+        'en-GB'
+      ),
+      'number.base': tPlugin('components.latLongField.latitudeBase', 'en-GB', {
+        fieldLabel
+      }),
       'number.min': latitudeRangeMessage,
       'number.max': latitudeRangeMessage
     })
 
     const longitudeMessages: LanguageMessages = convertToLanguageMessages({
       ...customValidationMessages,
-      'any.required': longitudeRequired,
-      'number.base': `Enter a valid longitude for ${lowerFirst(this.label)} like -0.127758`,
+      'any.required': tPlugin(
+        'components.latLongField.longitudeRequired',
+        'en-GB'
+      ),
+      'number.base': tPlugin('components.latLongField.longitudeBase', 'en-GB', {
+        fieldLabel
+      }),
       'number.min': longitudeRangeMessage,
       'number.max': longitudeRangeMessage
     })
@@ -85,7 +109,7 @@ export class LatLongField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__latitude`,
-          title: 'Latitude',
+          title: 'components.latLongField.latitude',
           schema: {
             min: latitudeMin,
             max: latitudeMax,
@@ -102,7 +126,7 @@ export class LatLongField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__longitude`,
-          title: 'Longitude',
+          title: 'components.latLongField.longitude',
           schema: {
             min: longitudeMin,
             max: longitudeMax,
@@ -133,7 +157,10 @@ export class LatLongField extends FormComponent {
     return LatLongField.isLatLong(value) ? value : undefined
   }
 
-  getDisplayStringFromFormValue(value: LatLongState | undefined): string {
+  getDisplayStringFromFormValue(
+    value: LatLongState | undefined,
+    _translator: Translator
+  ): string {
     if (!value) {
       return ''
     }
@@ -142,10 +169,13 @@ export class LatLongField extends FormComponent {
     return `${value.latitude}, ${value.longitude}`
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const value = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(value)
+    return this.getDisplayStringFromFormValue(value, translator)
   }
 
   getContextValueFromFormValue(value: LatLongState | undefined): string | null {
@@ -163,15 +193,16 @@ export class LatLongField extends FormComponent {
     return this.getContextValueFromFormValue(value)
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
-    return getLocationFieldViewModel(this, viewModel, payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
+    return getLocationFieldViewModel(this, viewModel, context)
   }
 
   getViewErrors(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    const allErrors = this.getErrors(errors)
+    const allErrors = this.getErrors(translator, errors)
     return deduplicateErrorsByHref(allErrors)
   }
 

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

@@ -13,12 +13,14 @@ import joi, {
 } from 'joi'
 
 import { FormComponent } from './FormComponent.js'
-import { type ListItem } from './types.js'
+import {
+  type ListItem,
+  type RenderContext
+} from './types.js'
+import { type Translator } from '../i18n/types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
   type ErrorMessageTemplateList,
-  type FormPayload,
-  type FormSubmissionError,
   type FormSubmissionState
 } from '../types.js'
 
@@ -100,7 +102,8 @@ export class ListFormComponent extends FormComponent {
   }
 
   getDisplayStringFromFormValue(
-    value: string | number | boolean | Item['value'][] | undefined
+    value: string | number | boolean | Item['value'][] | undefined,
+    translator: Translator
   ): string {
     const { items } = this
 
@@ -108,29 +111,42 @@ export class ListFormComponent extends FormComponent {
 
     return items
       .filter((item) => values.includes(item.value))
-      .map((item) => item.text)
+      .map((item) => translator.tListItem(item, 'text') || item.text)
       .join(', ')
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     // Allow for array values via subclass
     const value = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(value)
+    return this.getDisplayStringFromFormValue(value, translator)
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+  getViewModel(context: RenderContext) {
     const { items: listItems } = this
 
-    const viewModel = super.getViewModel(payload, errors)
+    const viewModel = super.getViewModel(context)
     const { value } = viewModel
 
     // Support multiple values for checkboxes
     const values = this.isValue(value) ? [value].flat() : []
 
+    const { tListItem } = context.translator
+
     const items = listItems.map((item) => {
       const selected = values.includes(item.value)
-      const itemModel: ListItem = { ...item, selected }
+      const resolvedText = tListItem(item, 'text') || item.text
+      const resolvedHint = tListItem(item, 'hint') || item.hint?.text
+      const hintAttr = resolvedHint ? { hint: { text: resolvedHint } } : {}
+      const itemModel: ListItem = {
+        ...item,
+        text: resolvedText,
+        selected,
+        ...hintAttr
+      }
 
       if ('id' in itemModel) {
         delete itemModel.id

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

@@ -10,13 +10,12 @@ import {
   isFormValue
 } from './FormComponent.js'
 import { addClassOptionIfNone } from './helpers/index.js'
+import { type RenderContext } from './types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
   type ErrorMessageTemplateList,
-  type FormPayload,
   type FormState,
   type FormStateValue,
-  type FormSubmissionError,
   type FormSubmissionState
 } from '../types.js'
 import { convertToLanguageMessages } from '../../../utils/type-utils.js'
@@ -63,8 +62,7 @@ export abstract class LocationFieldBase extends FormComponent {
     addClassOptionIfNone(locationOptions, 'govuk-input--width-10')
 
     const config = this.getValidationConfig()
-    const requiredMessage =
-      config.requiredMessage ?? (messageTemplate.required as string)
+    const requiredMessage = config.requiredMessage ?? messageTemplate.required
 
     const messages = convertToLanguageMessages({
       'any.required': requiredMessage,
@@ -120,8 +118,8 @@ export abstract class LocationFieldBase extends FormComponent {
     return LocationFieldBase.isText(value)
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
 
     if (this.instructionText) {
       return {
@@ -140,8 +138,7 @@ export abstract class LocationFieldBase extends FormComponent {
       baseErrors: [
         {
           type: 'required',
-          template:
-            config.requiredMessage ?? (messageTemplate.required as string)
+          template: config.requiredMessage ?? messageTemplate.required
         },
         ...this.getErrorTemplates()
       ],

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

@@ -2,10 +2,13 @@ import { type Context, type CustomValidator } from 'joi'
 
 import { type EastingNorthingField } from './EastingNorthingField.js'
 import { isFormValue } from './FormComponent.js'
+import { type GeospatialField } from './GeospatialField.js'
 import { type LatLongField } from './LatLongField.js'
+import { type OsGridRefField } from './OsGridRefField.js'
 import {
   type DateInputItem,
   type Label,
+  type RenderContext,
   type ViewModel
 } from './types.js'
 import {
@@ -86,6 +89,23 @@ export function deduplicateErrorsByHref(
   )
 }
 
+export function getMapLayers(
+  component:
+    | GeospatialField
+    | OsGridRefField
+    | LatLongField
+    | EastingNorthingField
+) {
+  const { mapLayers } = component.options
+  const layers = []
+
+  if (mapLayers?.sssi) {
+    layers.push('sssi')
+  }
+
+  return layers.join(',')
+}
+
 export function getLocationFieldViewModel(
   component: LocationField,
   viewModel: ViewModel & {
@@ -94,13 +114,12 @@ export function getLocationFieldViewModel(
     name: string
     value: FormValue
   },
-  payload: FormPayload,
-  errors?: FormSubmissionError[]
+  context: RenderContext
 ) {
   const { collection } = component
   const { fieldset: existingFieldset, label } = viewModel
 
-  const subViewModels = collection.getViewModel(payload, errors)
+  const subViewModels = collection.getViewModel(context)
 
   const fieldErrors: string[] = []
   subViewModels.forEach(({ model }) => {
@@ -167,7 +186,8 @@ export function getLocationFieldViewModel(
   const result = {
     ...viewModel,
     fieldset,
-    items
+    items,
+    mapLayers: getMapLayers(component)
   }
 
   if (component.options.instructionText) {