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

package/src/client/javascripts/map.js

@@ -367,6 +367,48 @@ export function getMapLayers(layers) {
   return trimmed ? trimmed.split(',') : []
 }
 
+/**
+ * Adds the country layers to a datasets array
+ * @param {string} apiPath
+ * @param {string} [country]
+ */
+export function getMapCountryLayers(apiPath, country) {
+  /** @type {any[]} */
+  const datasets = []
+
+  if (country) {
+    // Add the country bounds to the datasets array to show the valid area on the map
+    // and provide feedback to the user when they add features outside of the bounds.
+    datasets.push(
+      {
+        id: 'invalid-area',
+        label: 'Invalid areas',
+        geojson: `${apiPath}/maps/countries.geojson?omit=${country}`,
+        showInKey: false,
+        showInMenu: false,
+        style: {
+          stroke: 'gray',
+          strokeWidth: 1,
+          fill: 'rgba(211,211,211,0.8)'
+        }
+      },
+      {
+        id: 'valid-area',
+        label: 'Valid areas',
+        geojson: `${apiPath}/maps/countries.geojson?only=${country}`,
+        showInKey: false,
+        showInMenu: false,
+        style: {
+          stroke: 'rgba(0,112,60,1)',
+          strokeWidth: 1
+        }
+      }
+    )
+  }
+
+  return datasets
+}
+
 /**
  * @typedef {object} InteractiveMap - an instance of a InteractiveMap
  * @property {Function} on - register callback listeners to map events
@@ -418,3 +460,8 @@ export function getMapLayers(layers) {
 /**
  * @import { Feature } from '../../server/plugins/engine/types.js'
  */
+
+/**
+ * Supported language codes
+ * @typedef {('en-GB'|'cy')} LanguageCode
+ */

package/src/client/javascripts/maps.js

@@ -0,0 +1,5 @@
+export { initMaps } from './map.js'
+export * as map from './map.js'
+export * as locationMap from './location-map.js'
+export * as geospatialMap from './geospatial-map.js'
+export * as sssiDataset from './sssi-dataset.js'

package/src/client/javascripts/shared.js

@@ -3,10 +3,7 @@ import { initDebounceClick as initDebounceClickImp } from './debounce-click.js'
 import { initFileUpload as initFileUploadImp } from './file-upload.js'
 import { initAllGovuk as initAllGovukImp } from './govuk.js'
 import { initPreviewCloseLink as initPreviewCloseLinkImp } from './preview-close-link.js'
-export { initMaps } from './map.js'
-export * as map from './map.js'
-export * as geospatialMap from './geospatial-map.js'
-export * as sssiDataset from './sssi-dataset.js'
+export * from './maps.js'
 
 export const initAllGovuk = initAllGovukImp
 export const initAllAutocomplete = initAllAutocompleteImp

package/src/client/javascripts/sssi-dataset.js

@@ -49,49 +49,47 @@ export function sssiScotlandRequestTransformer(url, { bbox }) {
   }
 }
 
-export default {
-  datasets: [
-    {
-      id: 'sssi-england',
-      label: 'Sites of Special Scientific Interest',
-      dynamicGeoJSON: {
-        url: englandWFS,
-        idProperty: 'ref_code',
-        transformRequest: sssiEnglandRequestTransformer
-      },
-      minZoom,
-      style,
-      showInKey: true,
-      showInMenu: false
+export default [
+  {
+    id: 'sssi-england',
+    label: 'Sites of Special Scientific Interest',
+    dynamicGeoJSON: {
+      url: englandWFS,
+      idProperty: 'ref_code',
+      transformRequest: sssiEnglandRequestTransformer
     },
-    {
-      id: 'sssi-wales',
-      label: 'SSSI Wales',
-      dynamicGeoJSON: {
-        url: walesWFS,
-        idProperty: 'id',
-        transformRequest: sssiWalesRequestTransformer
-      },
-      minZoom,
-      style,
-      showInKey: false,
-      showInMenu: false
+    minZoom,
+    style,
+    showInKey: true,
+    showInMenu: false
+  },
+  {
+    id: 'sssi-wales',
+    label: 'SSSI Wales',
+    dynamicGeoJSON: {
+      url: walesWFS,
+      idProperty: 'id',
+      transformRequest: sssiWalesRequestTransformer
     },
-    {
-      id: 'sssi-scotland',
-      label: 'SSSI Scotland',
-      dynamicGeoJSON: {
-        url: scotlandWFS,
-        idProperty: 'OBJECTID',
-        transformRequest: sssiScotlandRequestTransformer
-      },
-      minZoom,
-      style,
-      showInKey: false,
-      showInMenu: false
-    }
-  ]
-}
+    minZoom,
+    style,
+    showInKey: false,
+    showInMenu: false
+  },
+  {
+    id: 'sssi-scotland',
+    label: 'SSSI Scotland',
+    dynamicGeoJSON: {
+      url: scotlandWFS,
+      idProperty: 'OBJECTID',
+      transformRequest: sssiScotlandRequestTransformer
+    },
+    minZoom,
+    style,
+    showInKey: false,
+    showInMenu: false
+  }
+]
 
 /**
  * @typedef {object} TransformRequestOptions

package/src/client/stylesheets/maps.scss

@@ -0,0 +1,4 @@
+@use "@defra/interactive-map/css" as core;
+@use "@defra/interactive-map/plugins/map-styles/css" as mapStyles;
+@use "@defra/interactive-map/plugins/search/css" as search;
+@use "@defra/interactive-map/plugins/scale-bar/css" as scaleBar;

package/src/client/stylesheets/shared.scss

@@ -3,11 +3,7 @@
 @use "prose";
 @use "summary-list";
 @use "location-fields";
-
-@use "@defra/interactive-map/css" as core;
-@use "@defra/interactive-map/plugins/map-styles/css" as mapStyles;
-@use "@defra/interactive-map/plugins/search/css" as search;
-@use "@defra/interactive-map/plugins/scale-bar/css" as scaleBar;
+@use "maps";
 
 // Use default GDS Transport font for autocomplete
 .autocomplete__hint,

package/src/server/constants.js

@@ -5,3 +5,5 @@ export const EXTERNAL_STATE_PAYLOAD = 'EXTERNAL_STATE_PAYLOAD'
 export const EXTERNAL_STATE_APPENDAGE = 'EXTERNAL_STATE_APPENDAGE'
 export const COMPONENT_STATE_ERROR = 'COMPONENT_STATE_ERROR'
 export const PAYMENT_EXPIRED_NOTIFICATION = 'PAYMENT_EXPIRED_NOTIFICATION'
+export const EN_GB = 'en-GB' // English language
+export const CY = 'cy' // Welsh language

package/src/server/plugins/engine/__stubs__/definitions.ts

@@ -0,0 +1,155 @@
+import {
+  ComponentType,
+  ConditionType,
+  ControllerType,
+  Engine,
+  OperatorName,
+  SchemaVersion,
+  type FormDefinition,
+  type PageQuestion
+} from '@defra/forms-model'
+
+const YES_NO_COMPONENT_ID = 'a7c0242f-2a31-45b2-8c71-ff2ac7f53288'
+const USER_TYPE_LIST_ID = '4fa26e9c-07cf-47cd-a9dd-5cec0dd3f544'
+const EXISTING_USER_ITEM_ID = '55fe0067-d011-4d33-886c-e1aa266637c3'
+
+/**
+ * A minimal, schema-valid V2 definition: one YesNo question page and a
+ * summary page. Each call returns a fresh object, so tests can mutate their
+ * copy freely without affecting each other.
+ */
+export function buildDefinition(): FormDefinition {
+  return {
+    name: 'Stub definition',
+    engine: Engine.V2,
+    schema: SchemaVersion.V2,
+    startPage: '/summary',
+    pages: [
+      {
+        id: '449c053b-9201-4312-9a75-187afc6ba48b',
+        path: '/licence',
+        title: 'Licence',
+        components: [
+          {
+            id: YES_NO_COMPONENT_ID,
+            name: 'xVrYaJ',
+            type: ComponentType.YesNoField,
+            title: 'Do you have a licence?',
+            shortDescription: 'Licence',
+            options: { required: true }
+          }
+        ],
+        next: []
+      },
+      {
+        id: '449c053b-9201-4312-9a75-187afc6ba48c',
+        path: '/summary',
+        title: 'Summary',
+        controller: ControllerType.Summary,
+        components: []
+      }
+    ],
+    lists: [],
+    sections: [],
+    conditions: []
+  }
+}
+
+/**
+ * A definition that passes schema validation but cannot be used by the
+ * engine: a ListItemRef condition points at the YesNoField (boolean), so the
+ * condition expression builder produces an unparseable expression. Distilled
+ * from a real production incident.
+ */
+export function buildBrokenConditionDefinition(): FormDefinition {
+  const definition = buildDefinition()
+
+  definition.name = 'Broken condition fixture'
+
+  const questionPage = definition.pages[0] as PageQuestion
+  // A YesNoField cannot legitimately carry a custom list — that is the
+  // corruption this fixture models — so the TS component types (rightly)
+  // have no `list` property here and a cast is required.
+  ;(questionPage.components[0] as { list?: string }).list = USER_TYPE_LIST_ID
+  definition.lists = [
+    {
+      id: USER_TYPE_LIST_ID,
+      name: 'XtfRYR',
+      title: 'User type list',
+      type: 'string',
+      items: [
+        {
+          id: EXISTING_USER_ITEM_ID,
+          text: 'existing user',
+          value: 'existing user'
+        },
+        {
+          id: '2277c7e5-7fef-46c6-993b-d294116d6d6b',
+          text: 'new user',
+          value: 'new user'
+        }
+      ]
+    }
+  ]
+  definition.conditions = [
+    {
+      id: '3f9d3a35-6dee-4706-806c-3f776129f631',
+      displayName: 'Existing user',
+      items: [
+        {
+          id: '7d7f58ee-c860-4d24-8a13-de5cb9af53d8',
+          componentId: YES_NO_COMPONENT_ID,
+          operator: OperatorName.Is,
+          type: ConditionType.ListItemRef,
+          value: {
+            listId: USER_TYPE_LIST_ID,
+            itemId: [EXISTING_USER_ITEM_ID]
+          }
+        }
+      ]
+    }
+  ]
+
+  return definition
+}
+
+/**
+ * A schema-valid definition whose first page names a controller that is
+ * neither built in nor registered by the host application.
+ */
+export function buildUnknownControllerDefinition(): FormDefinition {
+  const definition = buildDefinition()
+
+  definition.name = 'Unknown controller fixture'
+  definition.pages[0].controller =
+    'NoSuchPageController' as unknown as ControllerType
+
+  return definition
+}
+
+/**
+ * Schema-valid (component types are free strings in the schema), but the
+ * question uses a type the engine has no component class for.
+ */
+export function buildUnknownComponentDefinition(): FormDefinition {
+  const definition = buildDefinition()
+
+  definition.name = 'Unknown component fixture'
+  const questionPage = definition.pages[0] as PageQuestion
+  questionPage.components[0].type = 'MyUnknownField' as unknown as ComponentType
+
+  return definition
+}
+
+/**
+ * A definition that fails schema validation: the question page appears
+ * twice, violating the pages uniqueness rule.
+ */
+export function buildSchemaInvalidDefinition(): FormDefinition {
+  const definition = buildDefinition()
+
+  definition.name = 'Schema invalid fixture'
+  definition.pages.push(buildDefinition().pages[0])
+
+  return definition
+}

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

@@ -1,8 +1,11 @@
 import { type AutocompleteFieldComponent } from '@defra/forms-model'
+import { type LanguageMessages } from 'joi'
 
 import { SelectField } from './SelectField.js'
 import { type RenderContext } from './types.js'
+import { buildValidationMessages } from '../i18n/buildValidationMessages.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
+import { type Translator } from '../types/index.js'
 
 export class AutocompleteField extends SelectField {
   declare options: AutocompleteFieldComponent['options']
@@ -45,4 +48,14 @@ export class AutocompleteField extends SelectField {
       formGroup
     }
   }
+
+  getValidationMessagesOverride(translator: Translator) {
+    const { t } = translator
+    return {
+      [this.name]: {
+        'any.required': buildValidationMessages(t).objectRequired,
+        'any.only': buildValidationMessages(t).objectRequired
+      } as LanguageMessages
+    }
+  }
 }

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

@@ -1,8 +1,10 @@
 import { type CheckboxesFieldComponent, type Item } from '@defra/forms-model'
 import joi, { type ArraySchema } from 'joi'
 
+import { EN_GB } from '../../../constants.js'
 import { isFormValue } from './FormComponent.js'
 import { SelectionControlField } from './SelectionControlField.js'
+import { t as tPlugin } from '../i18n/index.js'
 import { type Translator } from '../i18n/types.js'
 import { type FormModel } from '../models/FormModel.js'
 import { type QuestionPageController } from '../pageControllers/QuestionPageController.js'
@@ -19,6 +21,7 @@ export class CheckboxesField extends SelectionControlField {
   declare schema: CheckboxesFieldComponent['schema']
   declare formSchema: ArraySchema<string> | ArraySchema<number>
   declare stateSchema: ArraySchema<string> | ArraySchema<number>
+  declare limits: { min?: number; max?: number; length?: number }
 
   constructor(
     def: CheckboxesFieldComponent,
@@ -41,11 +44,8 @@ export class CheckboxesField extends SelectionControlField {
       .single()
       .label(this.label)
       .required()
-      .messages({
-        'array.min': messageTemplate.arrayMin,
-        'array.max': messageTemplate.arrayMax,
-        'array.length': messageTemplate.arrayLength
-      })
+
+    const limits: { min?: number; max?: number; length?: number } = {}
 
     if (options.required === false) {
       formSchema = formSchema.optional()
@@ -53,16 +53,25 @@ export class CheckboxesField extends SelectionControlField {
 
     if (typeof schema?.length === 'number') {
       formSchema = formSchema.length(schema.length)
+      limits.length = schema.length
     } else {
       if (typeof schema?.min === 'number') {
         formSchema = formSchema.min(schema.min)
+        limits.min = schema.min
       }
 
       if (typeof schema?.max === 'number') {
         formSchema = formSchema.max(schema.max)
+        limits.max = schema.max
       }
     }
 
+    this.limits = limits
+
+    formSchema = formSchema.messages(
+      CheckboxesField.buildErrorMessages(EN_GB, limits)
+    )
+
     this.formSchema = formSchema.default([])
     this.stateSchema = formSchema.default(null).allow(null)
     this.options = options
@@ -133,6 +142,13 @@ export class CheckboxesField extends SelectionControlField {
     return this.getContextValueFromFormValue(values)
   }
 
+  getValidationMessagesOverride(translator: Translator) {
+    const { language } = translator
+    return {
+      [this.name]: CheckboxesField.buildErrorMessages(language, this.limits)
+    }
+  }
+
   /**
    * For error preview page that shows all possible errors on a component
    */
@@ -169,4 +185,21 @@ export class CheckboxesField extends SelectionControlField {
 
     return value.every(isFormValue)
   }
+
+  static buildErrorMessages(
+    language: string,
+    limits: { min?: number; max?: number; length?: number } = {}
+  ) {
+    return {
+      'array.min': tPlugin('validation.arrayMin', language, {
+        count: limits.min ?? 1
+      }),
+      'array.max': tPlugin('validation.arrayMax', language, {
+        count: limits.max ?? 1
+      }),
+      'array.length': tPlugin('validation.arrayLength', language, {
+        count: limits.length ?? 1
+      })
+    }
+  }
 }

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

@@ -28,6 +28,7 @@ export class ComponentBase {
 
   isFormComponent = false
   model: FormModel
+  def: ComponentDef
 
   /** joi schemas based on a component defined in the form JSON. This validates a user's answer and is generated from {@link ComponentDef} */
   formSchema: ComponentSchema = joi.string()
@@ -45,6 +46,7 @@ export class ComponentBase {
     this.type = def.type
     this.name = def.name
     this.title = def.title
+    this.def = def
 
     if ('schema' in def) {
       this.schema = def.schema

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

@@ -15,6 +15,7 @@ import {
   type Field,
   type Guidance
 } from './helpers/components.js'
+import { getTranslatedLabel } from './helpers/index.js'
 import {
   type ComponentViewModel,
   type RenderContext
@@ -302,26 +303,28 @@ export class ComponentCollection {
           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)
+            const subFieldMessages = messagesOverride
+              ? messagesOverride[subField.name]
+              : undefined
+            if (subFieldMessages) {
+              patchedSchema = patchedSchema.messages(subFieldMessages)
             }
             labelOverrides[subField.name] = patchedSchema
           }
         } else {
-          const translatedLabel =
-            translator.tComponent(
-              field as unknown as ComponentDef,
-              'shortDescription'
-            ) ||
-            translator.tComponent(field as unknown as ComponentDef, 'title')
+          const fieldDef = field.def
+          const translatedLabel = getTranslatedLabel(fieldDef, translator)
           const messagesOverride =
             field.getValidationMessagesOverride(translator)
           let patchedSchema = field.formSchema
           if (translatedLabel && translatedLabel !== field.label) {
             patchedSchema = patchedSchema.label(translatedLabel)
           }
-          if (messagesOverride) {
-            patchedSchema = patchedSchema.messages(messagesOverride)
+          const fieldMessages = messagesOverride
+            ? messagesOverride[field.name]
+            : undefined
+          if (fieldMessages) {
+            patchedSchema = patchedSchema.messages(fieldMessages)
           }
           if (patchedSchema !== field.formSchema) {
             labelOverrides[field.name] = patchedSchema
@@ -340,10 +343,12 @@ export class ComponentCollection {
     })
 
     const details = result.error?.details
+    const language = translator?.language
 
     return {
       value: (result.value ?? {}) as typeof value,
-      errors: this.page?.getErrors(details) ?? getErrors(details)
+      errors:
+        this.page?.getErrors(details, language) ?? getErrors(language, details)
     }
   }
 

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

@@ -1,6 +1,11 @@
 import { ComponentType, type DatePartsFieldComponent } from '@defra/forms-model'
 import { add, format, isValid, parse, startOfToday, sub } from 'date-fns'
-import { type Context, type CustomValidator, type ObjectSchema } from 'joi'
+import {
+  type Context,
+  type CustomValidator,
+  type LanguageMessages,
+  type ObjectSchema
+} from 'joi'
 
 import { ComponentCollection } from './ComponentCollection.js'
 import {
@@ -25,7 +30,7 @@ import {
   type FormStateValue,
   type FormSubmissionState
 } from '../types.js'
-import { convertToLanguageMessages } from '../../../utils/type-utils.js'
+import { formatDateForLanguage } from '../../payment/helper.js'
 
 export class DatePartsField extends FormComponent {
   declare options: DatePartsFieldComponent['options']
@@ -43,7 +48,7 @@ export class DatePartsField extends FormComponent {
 
     const isRequired = options.required !== false
 
-    const customValidationMessages = convertToLanguageMessages({
+    const customValidationMessages = {
       'any.required': messageTemplate.objectMissing,
       'number.base': messageTemplate.objectMissing,
       'number.precision': messageTemplate.dateFormat,
@@ -51,7 +56,7 @@ export class DatePartsField extends FormComponent {
       'number.unsafe': messageTemplate.dateFormat,
       'number.min': messageTemplate.dateFormat,
       'number.max': messageTemplate.dateFormat
-    })
+    } as LanguageMessages
 
     this.collection = new ComponentCollection(
       [
@@ -111,15 +116,16 @@ export class DatePartsField extends FormComponent {
 
   getDisplayStringFromFormValue(
     formValue: DatePartsState | undefined,
-    _translator: Translator
+    translator: Translator
   ) {
     if (!formValue) {
       return ''
     }
 
-    return format(
+    return formatDateForLanguage(
       `${formValue.year}-${formValue.month}-${formValue.day}`,
-      'd MMMM yyyy'
+      'd MMMM yyyy',
+      translator.language
     )
   }
 
@@ -158,7 +164,7 @@ export class DatePartsField extends FormComponent {
 
   getValidationMessagesOverride(translator: Translator) {
     const { t } = translator
-    return convertToLanguageMessages({
+    const messages = {
       'any.required': buildValidationMessages(t).objectMissing,
       'number.base': buildValidationMessages(t).objectMissing,
       'number.precision': buildValidationMessages(t).dateFormat,
@@ -166,7 +172,12 @@ export class DatePartsField extends FormComponent {
       'number.unsafe': buildValidationMessages(t).dateFormat,
       'number.min': buildValidationMessages(t).dateFormat,
       'number.max': buildValidationMessages(t).dateFormat
-    })
+    } as LanguageMessages
+    return {
+      [`${this.name}__day`]: messages,
+      [`${this.name}__month`]: messages,
+      [`${this.name}__year`]: messages
+    }
   }
 
   getViewModel(context: RenderContext) {

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

@@ -2,7 +2,6 @@ import {
   ComponentType,
   hasFormComponents,
   isFormType,
-  type ComponentDef,
   type DeclarationFieldComponent,
   type Item
 } from '@defra/forms-model'
@@ -121,10 +120,12 @@ export class DeclarationField extends FormComponent {
     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
+      [this.name]: {
+        'any.required': msg,
+        'any.unknown': msg,
+        'array.includesRequiredUnknowns': msg
+      } as unknown as LanguageMessages
+    }
   }
 
   getDisplayStringFromFormValue(
@@ -148,7 +149,7 @@ export class DeclarationField extends FormComponent {
         'components.declarationField.defaultLabel'
       )
     } = this
-    const content = tComponent(this as unknown as ComponentDef, 'content')
+    const content = tComponent(this.def, 'content')
 
     const viewModel = super.getViewModel(context)
     let { fieldset, label } = viewModel