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

package/src/server/forms/simple-form.yaml

@@ -3,6 +3,57 @@ name: Page events
 engine: V2
 schema: 2
 startPage: '/summary'
+metadata:
+  language: en-GB
+  translations:
+    cy:
+      components:
+        1fb8e182-c709-4792-8f83-e01d8b1fee1a:
+          title: Beth yw eich enw cyntaf?
+          shortDescription: Eich enw cyntaf
+        b68df7f1-d4f4-4c17-83c8-402f584906c9:
+          title: Beth yw eich enw olaf?
+          shortDescription: Eich enw olaf
+        987c1234-56d7-89e0-1234-56789abcdef0:
+          title: Llwytho copi o'ch pasbort
+          shortDescription: Llwytho pasbort
+        987c1234-56d7-89e0-1234-56789abcdef1:
+          title: Llwytho copi o'ch trwydded yrru
+          shortDescription: Llwytho trwydded yrru
+        00738799-3489-4ab2-a57b-542eecb31bfa:
+          title: Pryd yw pen-blwydd {{ applicantFirstName }} {{ applicantLastName }}?
+          shortDescription: Eich pen-blwydd
+        123e4567-e89b-12d3-a456-426614174000:
+          title: Beth yw eich cyfeiriad?
+          shortDescription: Eich cyfeiriad
+        aabbccdd-1122-3344-5566-778899001123:
+          title: Oes gennych chi drwydded yrru?
+          shortDescription: Trwydded yrru
+        aabbccdd-1122-3344-5566-778899001124:
+          title: Sut rydych chi fel arfer yn teithio?
+          shortDescription: Eich ffordd o deithio
+      listItems:
+        aabbccdd-1122-3344-5566-778899001126:
+          text: Car
+        aabbccdd-1122-3344-5566-778899001127:
+          text: Bws
+        aabbccdd-1122-3344-5566-778899001128:
+          text: Trên
+      pages:
+        622a35ec-3795-418a-81f3-a45746959045:
+          title: Eich enw
+        23456789-0abc-def1-2345-67890abcdef1:
+          title: Llwytho copi o'ch pasbort
+        23456789-0abc-def1-2345-67890abcdef2:
+          title: Llwytho copi o'ch trwydded yrru
+        da0fbdb4-a2de-4650-be16-9ba552af135f:
+          title: Dyddiad geni
+        449a45f6-4541-4a46-91bd-8b8931b07b50:
+          title: Crynodeb
+        123e4567-e89b-12d3-a456-426614174001:
+          title: Ble rydych chi'n byw?
+        aabbccdd-1122-3344-5566-778899001122:
+          title: Amdanoch chi
 pages:
   - title: Your name
     path: '/your-name'
@@ -36,6 +87,21 @@ pages:
         id: e18116e0-7c3e-416a-af42-6f229017c5b1
     next: []
     id: 622a35ec-3795-418a-81f3-a45746959045
+  - title: Where do you live?
+    path: '/where-you-live'
+    components:
+      - type: UkAddressField
+        title: What is your address?
+        name: applicantAddress
+        shortDescription: Your address
+        hint: ''
+        options:
+          required: true
+          usePostcodeLookup: true
+        schema: {}
+        id: 123e4567-e89b-12d3-a456-426614174000
+    next: []
+    id: 123e4567-e89b-12d3-a456-426614174001
   - title: Upload a copy of your passport
     controller: FileUploadPageController
     path: '/upload-passport'
@@ -46,7 +112,7 @@ pages:
         shortDescription: Upload passport
         hint: ''
         options:
-          required: true
+          required: false
         schema: {}
         id: 987c1234-56d7-89e0-1234-56789abcdef0
     id: 23456789-0abc-def1-2345-67890abcdef1
@@ -60,7 +126,7 @@ pages:
         shortDescription: Upload drivers licence
         hint: ''
         options:
-          required: true
+          required: false
         schema: {}
         id: 987c1234-56d7-89e0-1234-56789abcdef1
     id: 23456789-0abc-def1-2345-67890abcdef2
@@ -78,6 +144,29 @@ pages:
         id: '00738799-3489-4ab2-a57b-542eecb31bfa'
     next: []
     id: da0fbdb4-a2de-4650-be16-9ba552af135f
+  - title: About you
+    path: '/about-you'
+    components:
+      - type: YesNoField
+        title: Do you have a driving licence?
+        name: hasDrivingLicence
+        shortDescription: Driving licence
+        hint: ''
+        options: {}
+        schema: {}
+        id: aabbccdd-1122-3344-5566-778899001123
+      - type: RadiosField
+        title: How do you usually travel?
+        name: travelMethod
+        shortDescription: Your travel method
+        hint: ''
+        options:
+          required: true
+        schema: {}
+        list: aabbccdd-1122-3344-5566-778899001125
+        id: aabbccdd-1122-3344-5566-778899001124
+    next: []
+    id: aabbccdd-1122-3344-5566-778899001122
   - title: ''
     path: '/notification-demo'
     components:
@@ -103,4 +192,18 @@ pages:
     controller: SummaryPageController
 conditions: []
 sections: []
-lists: []
+lists:
+  - id: aabbccdd-1122-3344-5566-778899001125
+    name: travelMethods
+    title: Travel methods
+    type: string
+    items:
+      - id: aabbccdd-1122-3344-5566-778899001126
+        text: Car
+        value: car
+      - id: aabbccdd-1122-3344-5566-778899001127
+        text: Bus
+        value: bus
+      - id: aabbccdd-1122-3344-5566-778899001128
+        text: Train
+        value: train

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

@@ -1,11 +1,8 @@
 import { type AutocompleteFieldComponent } from '@defra/forms-model'
 
 import { SelectField } from './SelectField.js'
+import { type RenderContext } from './types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
-import {
-  type FormPayload,
-  type FormSubmissionError
-} from '../types.js'
 
 export class AutocompleteField extends SelectField {
   declare options: AutocompleteFieldComponent['options']
@@ -34,8 +31,8 @@ export class AutocompleteField extends SelectField {
     this.formSchema = formSchema
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
     let { formGroup } = viewModel
 
     formGroup ??= {}

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

@@ -3,6 +3,7 @@ import joi, { type ArraySchema } from 'joi'
 
 import { isFormValue } from './FormComponent.js'
 import { SelectionControlField } from './SelectionControlField.js'
+import { type Translator } from '../i18n/types.js'
 import { type FormModel } from '../models/FormModel.js'
 import { type QuestionPageController } from '../pageControllers/QuestionPageController.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
@@ -41,9 +42,9 @@ export class CheckboxesField extends SelectionControlField {
       .label(this.label)
       .required()
       .messages({
-        'array.min': messageTemplate.arrayMin as string,
-        'array.max': messageTemplate.arrayMax as string,
-        'array.length': messageTemplate.arrayLength as string
+        'array.min': messageTemplate.arrayMin,
+        'array.max': messageTemplate.arrayMax,
+        'array.length': messageTemplate.arrayLength
       })
 
     if (options.required === false) {
@@ -86,7 +87,8 @@ export class CheckboxesField extends SelectionControlField {
   }
 
   getDisplayStringFromFormValue(
-    selected: (string | number | boolean)[] | undefined
+    selected: (string | number | boolean)[] | undefined,
+    translator: Translator
   ) {
     const { items } = this
 
@@ -94,10 +96,9 @@ export class CheckboxesField extends SelectionControlField {
       return ''
     }
 
-    // Map selected values to text
     return items
       .filter((item) => selected.includes(item.value))
-      .map((item) => item.text)
+      .map((item) => translator.tListItem(item, 'text') || item.text)
       .join(', ')
   }
 
@@ -118,12 +119,12 @@ export class CheckboxesField extends SelectionControlField {
     return values ?? []
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
-    // Selected checkbox values
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const selected = this.getFormValueFromState(state) ?? []
-
-    // Map selected values to text
-    return this.getDisplayStringFromFormValue(selected)
+    return this.getDisplayStringFromFormValue(selected, translator)
   }
 
   getContextValueFromState(state: FormSubmissionState) {

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