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

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

@@ -6,7 +6,6 @@ import joi, {
 } from 'joi'
 
 import {
-  FormComponent,
   isFormState,
   isFormValue
 } from './FormComponent.js'
@@ -16,11 +15,18 @@ import {
   type Field,
   type Guidance
 } from './helpers/components.js'
-import { type ComponentViewModel } from './types.js'
+import {
+  type ComponentViewModel,
+  type RenderContext
+} from './types.js'
 import { getErrors } from '../helpers.js'
+import { type Translator } from '../i18n/types.js'
 import { type FormModel } from '../models/index.js'
 import { type PageControllerClass } from '../pageControllers/helpers/pages.js'
-import { validationOptions as opts } from '../pageControllers/validationOptions.js'
+import {
+  buildLanguageMessages,
+  validationOptions as opts
+} from '../pageControllers/validationOptions.js'
 import {
   type FormPayload,
   type FormState,
@@ -28,7 +34,6 @@ import {
   type FormSubmissionState,
   type FormValidationResult
 } from '../types.js'
-import { type FormQuery } from '../../../routes/types.js'
 
 export class ComponentCollection {
   page?: PageControllerClass
@@ -87,49 +92,6 @@ export class ComponentCollection {
         : stateSchema.keys({ [name]: field.stateSchema })
     }
 
-    // Add parent field title to collection field errors
-    formSchema = formSchema.error((errors) => {
-      return errors.flatMap((error) => {
-        if (!isErrorContext(error.local) || error.local.title) {
-          return error
-        }
-
-        // Use field key or first missing child field
-        let { missing, key = missing?.[0] } = error.local
-
-        // But avoid numeric key used by array payloads
-        if (typeof key === 'number') {
-          key = error.path[0]
-        }
-
-        // Find the parent field
-        const parent = fields.find(
-          (item) => item.name === key?.split('__').shift()
-        )
-
-        // Find the child field
-        const child = (parent?.collection?.fields ?? fields).find(
-          (item) => item.name === key
-        )
-
-        // Update error with child label
-        if (child && (!error.local.label || error.local.label === 'value')) {
-          error.local.label = child.title
-        }
-
-        // Fix error summary links for missing fields
-        if (missing?.length) {
-          error.path = missing
-          error.local.key = missing[0]
-        }
-
-        // Update error with parent title
-        error.local.title ??= parent?.label
-
-        return error
-      })
-    })
-
     if (schema?.peers) {
       formSchema = formSchema.and(...schema.peers, {
         isPresent: isFormValue
@@ -215,8 +177,14 @@ export class ComponentCollection {
   /**
    * Get all errors for all fields in this collection
    */
-  getErrors(errors?: FormSubmissionError[]): FormSubmissionError[] | undefined {
-    return this.getFieldErrors((field) => field.getErrors(errors), errors)
+  getErrors(
+    translator: Translator,
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
+    return this.getFieldErrors(
+      (field) => field.getErrors(translator, errors),
+      errors
+    )
   }
 
   /**
@@ -225,25 +193,22 @@ export class ComponentCollection {
    * Composite fields like UKAddress can choose to return more than one error.
    */
   getViewErrors(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    return this.getFieldErrors((field) => field.getViewErrors(errors), errors)
+    return this.getFieldErrors(
+      (field) => field.getViewErrors(translator, errors),
+      errors
+    )
   }
 
-  getViewModel(
-    payload: FormPayload,
-    errors?: FormSubmissionError[],
-    query: FormQuery = {}
-  ) {
+  getViewModel(context: RenderContext) {
     const { components } = this
 
     const result: ComponentViewModel[] = components.map((component) => {
       const { isFormComponent, type } = component
 
-      const model =
-        component instanceof FormComponent
-          ? component.getViewModel(payload, errors, query)
-          : component.getViewModel()
+      const model = component.getViewModel(context)
 
       return { type, isFormComponent, model }
     })
@@ -251,11 +216,128 @@ export class ComponentCollection {
     return result
   }
 
+  overrideParentTitle(
+    formSchema: joi.ObjectSchema<FormPayload>,
+    translator: Translator | undefined
+  ) {
+    // Add parent field title to collection field errors
+    return formSchema.error((errors) => {
+      return errors.flatMap((error) => {
+        if (!isErrorContext(error.local) || error.local.title) {
+          return error
+        }
+
+        // Use field key or first missing child field
+        let { missing, key = missing?.[0] } = error.local
+
+        // But avoid numeric key used by array payloads
+        if (typeof key === 'number') {
+          key = error.path[0]
+        }
+
+        // Find the parent field
+        const parent = this.fields.find(
+          (item) => item.name === key?.split('__').shift()
+        )
+
+        // Find the child field
+        const child = (parent?.collection?.fields ?? this.fields).find(
+          (item) => item.name === key
+        )
+
+        // Update error with child label
+        if (child && (!error.local.label || error.local.label === 'value')) {
+          error.local.label = child.title
+        }
+
+        // Fix error summary links for missing fields
+        if (missing?.length) {
+          error.path = missing
+          error.local.key = missing[0]
+        }
+
+        // Update error with parent title
+        if (translator && parent) {
+          error.local.title ??= translator.tComponent(
+            parent as ComponentDef,
+            'title'
+          )
+        } else {
+          error.local.title ??= parent?.label
+        }
+
+        return error
+      })
+    })
+  }
+
   /**
    * Validate form payload
    */
-  validate(value: FormPayload = {}): FormValidationResult<FormPayload> {
-    const result = this.formSchema.validate(value, opts)
+  validate(
+    value: FormPayload = {},
+    translator?: Translator
+  ): FormValidationResult<FormPayload> {
+    const messages = translator
+      ? buildLanguageMessages(translator.t)
+      : undefined
+
+    // When translating, override Joi labels (and custom schema messages where
+    // needed) so #label/#title in message templates resolve in the correct language.
+    let schema = this.formSchema
+    // Add parent field title to collection field errors
+    schema = this.overrideParentTitle(schema, translator)
+
+    if (translator) {
+      const { t } = translator
+      const labelOverrides: Record<string, joi.Schema> = {}
+
+      for (const field of this.fields) {
+        if (field.collection) {
+          // Composite field: translate each sub-field's label using the key constant
+          // (e.g. 'components.addressField.line1' → "Llinell cyfeiriad 1") and apply
+          // any field-type-specific message overrides (e.g. objectMissing for dates).
+          const messagesOverride =
+            field.getValidationMessagesOverride(translator)
+          for (const subField of field.collection.fields) {
+            const translatedSubLabel = t(subField.title) || subField.label
+            let patchedSchema = subField.formSchema.label(translatedSubLabel)
+            if (messagesOverride) {
+              patchedSchema = patchedSchema.messages(messagesOverride)
+            }
+            labelOverrides[subField.name] = patchedSchema
+          }
+        } else {
+          const translatedLabel =
+            translator.tComponent(
+              field as unknown as ComponentDef,
+              'shortDescription'
+            ) ||
+            translator.tComponent(field as unknown as ComponentDef, 'title')
+          const messagesOverride =
+            field.getValidationMessagesOverride(translator)
+          let patchedSchema = field.formSchema
+          if (translatedLabel && translatedLabel !== field.label) {
+            patchedSchema = patchedSchema.label(translatedLabel)
+          }
+          if (messagesOverride) {
+            patchedSchema = patchedSchema.messages(messagesOverride)
+          }
+          if (patchedSchema !== field.formSchema) {
+            labelOverrides[field.name] = patchedSchema
+          }
+        }
+      }
+
+      if (Object.keys(labelOverrides).length) {
+        schema = schema.keys(labelOverrides)
+      }
+    }
+
+    const result = schema.validate(value, {
+      ...opts,
+      ...(messages && { messages })
+    })
 
     const details = result.error?.details
 

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

@@ -11,16 +11,18 @@ import {
 import { NumberField } from './NumberField.js'
 import {
   type DateInputItem,
-  type DatePartsState
+  type DatePartsState,
+  type RenderContext
 } from './types.js'
 import { parseStrictDate } from '../date-helper.js'
+import { buildValidationMessages } from '../i18n/buildValidationMessages.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,
   type FormSubmissionState
 } from '../types.js'
 import { convertToLanguageMessages } from '../../../utils/type-utils.js'
@@ -56,7 +58,7 @@ export class DatePartsField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__day`,
-          title: 'Day',
+          title: 'components.dateField.day',
           schema: { min: 1, max: 31, precision: 0 },
           options: {
             required: isRequired,
@@ -68,7 +70,7 @@ export class DatePartsField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__month`,
-          title: 'Month',
+          title: 'components.dateField.month',
           schema: { min: 1, max: 12, precision: 0 },
           options: {
             required: isRequired,
@@ -80,7 +82,7 @@ export class DatePartsField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__year`,
-          title: 'Year',
+          title: 'components.dateField.year',
           schema: { min: 1000, max: 3000, precision: 0 },
           options: {
             required: isRequired,
@@ -107,7 +109,10 @@ export class DatePartsField extends FormComponent {
     return this.isState(value) ? value : undefined
   }
 
-  getDisplayStringFromFormValue(formValue: DatePartsState | undefined) {
+  getDisplayStringFromFormValue(
+    formValue: DatePartsState | undefined,
+    _translator: Translator
+  ) {
     if (!formValue) {
       return ''
     }
@@ -118,10 +123,13 @@ export class DatePartsField extends FormComponent {
     )
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const value = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(value)
+    return this.getDisplayStringFromFormValue(value, translator)
   }
 
   getContextValueFromFormValue(value: DatePartsState | undefined) {
@@ -148,10 +156,24 @@ export class DatePartsField extends FormComponent {
     return this.getContextValueFromFormValue(value)
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+  getValidationMessagesOverride(translator: Translator) {
+    const { t } = translator
+    return convertToLanguageMessages({
+      'any.required': buildValidationMessages(t).objectMissing,
+      'number.base': buildValidationMessages(t).objectMissing,
+      'number.precision': buildValidationMessages(t).dateFormat,
+      'number.integer': buildValidationMessages(t).dateFormat,
+      'number.unsafe': buildValidationMessages(t).dateFormat,
+      'number.min': buildValidationMessages(t).dateFormat,
+      'number.max': buildValidationMessages(t).dateFormat
+    })
+  }
+
+  getViewModel(context: RenderContext) {
+    const { errors } = context
     const { collection, name } = this
 
-    const viewModel = super.getViewModel(payload, errors)
+    const viewModel = super.getViewModel(context)
     let { fieldset, label } = viewModel
 
     // Check for component errors only
@@ -159,7 +181,7 @@ export class DatePartsField extends FormComponent {
 
     // Use the component collection to generate the subitems
     const items: DateInputItem[] = collection
-      .getViewModel(payload, errors)
+      .getViewModel(context)
       .map(({ model }) => {
         let { label, type, value, classes, errorMessage } = model
 

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

@@ -2,12 +2,14 @@ import {
   ComponentType,
   hasFormComponents,
   isFormType,
+  type ComponentDef,
   type DeclarationFieldComponent,
   type Item
 } from '@defra/forms-model'
 import joi, {
   type ArraySchema,
   type BooleanSchema,
+  type LanguageMessages,
   type StringSchema
 } from 'joi'
 
@@ -15,23 +17,23 @@ import {
   FormComponent,
   isFormValue
 } from './FormComponent.js'
+import { type RenderContext } from './types.js'
+import { buildValidationMessages } from '../i18n/buildValidationMessages.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,
   type FormSubmissionState,
   type FormValue
 } from '../types.js'
 
 export class DeclarationField extends FormComponent {
-  private readonly DEFAULT_DECLARATION_LABEL = 'I understand and agree'
-
   declare options: DeclarationFieldComponent['options']
 
-  declare declarationConfirmationLabel: string
+  declare declarationConfirmationLabel: string | undefined
 
   declare formSchema: ArraySchema<StringSchema[]>
   declare stateSchema: BooleanSchema
@@ -69,8 +71,9 @@ export class DeclarationField extends FormComponent {
 
     this.options = options
     this.content = content
-    this.declarationConfirmationLabel =
-      options.declarationConfirmationLabel ?? this.DEFAULT_DECLARATION_LABEL
+    // Store only the form-authored label (if provided). If absent, getViewModel
+    // resolves the default via t() at render time so the correct language is used.
+    this.declarationConfirmationLabel = options.declarationConfirmationLabel
     const formComponents = hasFormComponents(props.page?.pageDef)
       ? props.page.pageDef.components
       : []
@@ -114,20 +117,40 @@ export class DeclarationField extends FormComponent {
     return this.isValue(value) ? value : undefined
   }
 
-  getDisplayStringFromFormValue(value: FormValue | FormPayload): string {
-    return value === 'true' ? this.declarationConfirmationLabel : 'Not provided'
+  getValidationMessagesOverride(translator: Translator) {
+    const { declarationRequired } = buildValidationMessages(translator.t)
+    const msg = declarationRequired as unknown as string
+    return {
+      'any.required': msg,
+      'any.unknown': msg,
+      'array.includesRequiredUnknowns': msg
+    } as unknown as LanguageMessages
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const defaultDeclarationConfirmationLabel =
-      'I confirm that I understand and accept this declaration'
+  getDisplayStringFromFormValue(
+    value: FormValue | FormPayload,
+    translator: Translator
+  ): string {
+    const { t } = translator
+    return value === 'true'
+      ? (this.declarationConfirmationLabel ??
+          t('components.declarationField.defaultLabel'))
+      : t('components.declarationField.notProvided')
+  }
+
+  getViewModel(context: RenderContext) {
+    const { payload } = context
+    const { t, tComponent } = context.translator
+
     const {
       hint,
-      content,
-      declarationConfirmationLabel = defaultDeclarationConfirmationLabel
+      declarationConfirmationLabel = t(
+        'components.declarationField.defaultLabel'
+      )
     } = this
+    const content = tComponent(this as unknown as ComponentDef, 'content')
 
-    const viewModel = super.getViewModel(payload, errors)
+    const viewModel = super.getViewModel(context)
     let { fieldset, label } = viewModel
 
     fieldset ??= {

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

@@ -16,7 +16,12 @@ import {
 } from './LocationFieldHelpers.js'
 import { NumberField } from './NumberField.js'
 import { createLowerFirstExpression } from './helpers/index.js'
-import { type EastingNorthingState } from './types.js'
+import {
+  type EastingNorthingState,
+  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,
@@ -55,18 +60,47 @@ export class EastingNorthingField extends FormComponent {
     const northingMin = schema?.northing?.min ?? DEFAULT_NORTHING_MIN
     const northingMax = schema?.northing?.max ?? DEFAULT_NORTHING_MAX
 
-    const eastingRequired = 'Enter easting'
-    const northingRequired = 'Enter northing'
+    const fieldLabel = lowerFirst(this.label)
 
-    const eastingDigitsMessage = `{{#label}} for ${lowerFirst(this.label)} must be between 1 and 6 digits`
-    const northingDigitsMessage = `{{#label}} for ${lowerFirst(this.label)} must be between 1 and 7 digits`
+    const eastingDigitsMessage = tPlugin(
+      'components.eastingNorthingField.eastingDigits',
+      'en-GB',
+      { fieldLabel }
+    )
+    const northingDigitsMessage = tPlugin(
+      'components.eastingNorthingField.northingDigits',
+      'en-GB',
+      { fieldLabel }
+    )
 
     const customValidationMessages: LanguageMessages =
       convertToLanguageMessages({
-        'any.required': eastingRequired,
-        'number.base': eastingRequired,
-        'number.min': `{{#label}} for ${lowerFirst(this.label)} must be between {{#limit}} and ${eastingMax}`,
-        'number.max': `{{#label}} for ${lowerFirst(this.label)} must be between ${eastingMin} and {{#limit}}`,
+        'any.required': tPlugin(
+          'components.eastingNorthingField.eastingRequired',
+          'en-GB'
+        ),
+        'number.base': tPlugin(
+          'components.eastingNorthingField.eastingRequired',
+          'en-GB'
+        ),
+        'number.min': tPlugin(
+          'components.eastingNorthingField.eastingRange',
+          'en-GB',
+          {
+            fieldLabel,
+            min: eastingMin,
+            max: eastingMax
+          }
+        ),
+        'number.max': tPlugin(
+          'components.eastingNorthingField.eastingRange',
+          'en-GB',
+          {
+            fieldLabel,
+            min: eastingMin,
+            max: eastingMax
+          }
+        ),
         'number.precision': eastingDigitsMessage,
         'number.integer': eastingDigitsMessage,
         'number.unsafe': eastingDigitsMessage
@@ -74,10 +108,32 @@ export class EastingNorthingField extends FormComponent {
 
     const northingValidationMessages: LanguageMessages =
       convertToLanguageMessages({
-        'any.required': northingRequired,
-        'number.base': northingRequired,
-        'number.min': `{{#label}} for ${lowerFirst(this.label)} must be between {{#limit}} and ${northingMax}`,
-        'number.max': `{{#label}} for ${lowerFirst(this.label)} must be between ${northingMin} and {{#limit}}`,
+        'any.required': tPlugin(
+          'components.eastingNorthingField.northingRequired',
+          'en-GB'
+        ),
+        'number.base': tPlugin(
+          'components.eastingNorthingField.northingRequired',
+          'en-GB'
+        ),
+        'number.min': tPlugin(
+          'components.eastingNorthingField.northingRange',
+          'en-GB',
+          {
+            fieldLabel,
+            min: northingMin,
+            max: northingMax
+          }
+        ),
+        'number.max': tPlugin(
+          'components.eastingNorthingField.northingRange',
+          'en-GB',
+          {
+            fieldLabel,
+            min: northingMin,
+            max: northingMax
+          }
+        ),
         'number.precision': northingDigitsMessage,
         'number.integer': northingDigitsMessage,
         'number.unsafe': northingDigitsMessage
@@ -88,7 +144,7 @@ export class EastingNorthingField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__easting`,
-          title: 'Easting',
+          title: 'components.eastingNorthingField.easting',
           schema: {
             min: eastingMin,
             max: eastingMax,
@@ -104,7 +160,7 @@ export class EastingNorthingField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__northing`,
-          title: 'Northing',
+          title: 'components.eastingNorthingField.northing',
           schema: {
             min: northingMin,
             max: northingMax,
@@ -135,7 +191,8 @@ export class EastingNorthingField extends FormComponent {
   }
 
   getDisplayStringFromFormValue(
-    value: EastingNorthingState | undefined
+    value: EastingNorthingState | undefined,
+    _translator: Translator
   ): string {
     if (!value) {
       return ''
@@ -145,10 +202,13 @@ export class EastingNorthingField extends FormComponent {
     return `${value.easting}, ${value.northing}`
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const value = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(value)
+    return this.getDisplayStringFromFormValue(value, translator)
   }
 
   getContextValueFromFormValue(
@@ -167,15 +227,16 @@ export class EastingNorthingField 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/EmailAddressField.ts

@@ -5,12 +5,9 @@ import {
 import joi, { type CustomHelpers } from 'joi'
 
 import { FormComponent } from './FormComponent.js'
+import { type RenderContext } from './types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
-import {
-  type ErrorMessageTemplateList,
-  type FormPayload,
-  type FormSubmissionError
-} from '../types.js'
+import { type ErrorMessageTemplateList } from '../types.js'
 
 export class EmailAddressField extends FormComponent {
   declare options: EmailAddressFieldComponent['options']
@@ -54,8 +51,8 @@ export class EmailAddressField extends FormComponent {
     this.options = options
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
     const { attributes } = viewModel
 
     attributes.autocomplete = 'email'