@defra/forms-engine-plugin 5.0.0-alpha.10 → 5.0.0-alpha.12

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

@@ -1,9 +1,10 @@
 import { type CheckboxesFieldComponent, type Item } from '@defra/forms-model'
-import joi, { type ArraySchema, type LanguageMessages } from 'joi'
+import joi, { type ArraySchema } from 'joi'
 
+import { EN_GB } from '../../../constants.js'
 import { isFormValue } from './FormComponent.js'
 import { SelectionControlField } from './SelectionControlField.js'
-import { buildValidationMessages } from '../i18n/buildValidationMessages.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'
@@ -20,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,
@@ -42,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()
@@ -54,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
@@ -135,13 +143,9 @@ export class CheckboxesField extends SelectionControlField {
   }
 
   getValidationMessagesOverride(translator: Translator) {
-    const { t } = translator
+    const { language } = translator
     return {
-      [this.name]: {
-        'array.min': buildValidationMessages(t).arrayMin,
-        'array.max': buildValidationMessages(t).arrayMax,
-        'array.length': buildValidationMessages(t).arrayLength
-      } as LanguageMessages
+      [this.name]: CheckboxesField.buildErrorMessages(language, this.limits)
     }
   }
 
@@ -181,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/EastingNorthingField.ts

@@ -15,6 +15,7 @@ import {
   getLocationFieldViewModel
 } from './LocationFieldHelpers.js'
 import { NumberField } from './NumberField.js'
+import { getEastingNorthingCountryValidator } from './helpers/geospatial.js'
 import {
   createLowerFirstExpression,
   getTranslatedLabel
@@ -112,6 +113,18 @@ export class EastingNorthingField extends FormComponent {
     )
 
     this.options = options
+
+    const country = options.countries?.at(0)
+
+    if (country) {
+      this.collection.formSchema = this.collection.formSchema.custom(
+        getEastingNorthingCountryValidator(this, country)
+      )
+      this.collection.stateSchema = this.collection.stateSchema.custom(
+        getEastingNorthingCountryValidator(this, country)
+      )
+    }
+
     this.formSchema = this.collection.formSchema
     this.stateSchema = this.collection.stateSchema
   }
@@ -164,6 +177,24 @@ export class EastingNorthingField extends FormComponent {
     return getLocationFieldViewModel(this, viewModel, context)
   }
 
+  getErrors(
+    translator: Translator,
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
+    const fieldErrors = super.getErrors(translator, errors)
+
+    fieldErrors?.forEach((err) => {
+      if (err.context?.country) {
+        err.text = translator.t(
+          'components.eastingNorthingField.wrongCountry',
+          { country: translator.t(`common.${err.context.country}`) }
+        )
+      }
+    })
+
+    return fieldErrors
+  }
+
   getViewErrors(
     translator: Translator,
     errors?: FormSubmissionError[]

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

@@ -52,7 +52,9 @@ export const tempFileSchema = fileSchema.append({
     .string()
     .valid(FileStatus.complete, FileStatus.rejected, FileStatus.pending)
     .required(),
-  errorMessage: joi.string().optional()
+  errorMessage: joi.string().optional(),
+  errorCode: joi.string().optional(),
+  errorParams: joi.any().optional()
 })
 
 export const formFileSchema = fileSchema.append({
@@ -111,6 +113,7 @@ export class FileUploadField extends FormComponent {
   declare schema: FileUploadFieldComponent['schema']
   declare formSchema: ArraySchema<FileState>
   declare stateSchema: ArraySchema<FileState>
+  declare limits: { min?: number; max?: number; length?: number }
 
   constructor(
     def: FileUploadFieldComponent,
@@ -130,21 +133,31 @@ export class FileUploadField extends FormComponent {
       formSchema = formSchema.optional()
     }
 
+    const limits: { min?: number; max?: number; length?: number } = {}
+
     if (typeof schema.length !== 'number') {
       if (typeof schema.max === 'number') {
         formSchema = formSchema.max(schema.max)
+        limits.max = schema.max
       }
 
       if (typeof schema.min === 'number') {
         formSchema = formSchema.min(schema.min)
+        limits.min = schema.min
       } else if (options.required !== false) {
         formSchema = formSchema.min(1)
+        limits.min = 1
       }
     } else {
       formSchema = formSchema.length(schema.length)
+      limits.length = schema.length
     }
 
-    formSchema = formSchema.messages(FileUploadField.buildErrorMessages(EN_GB))
+    this.limits = limits
+
+    formSchema = formSchema.messages(
+      FileUploadField.buildErrorMessages(EN_GB, limits)
+    )
 
     this.formSchema = formSchema.items(formItemSchema)
     this.stateSchema = formSchema
@@ -307,7 +320,7 @@ export class FileUploadField extends FormComponent {
   getValidationMessagesOverride(translator: Translator) {
     const { language } = translator
     return {
-      [this.name]: FileUploadField.buildErrorMessages(language)
+      [this.name]: FileUploadField.buildErrorMessages(language, this.limits)
     }
   }
 
@@ -415,11 +428,20 @@ export class FileUploadField extends FormComponent {
     }
   }
 
-  static buildErrorMessages(language: string) {
+  static buildErrorMessages(
+    language: string,
+    limits: { min?: number; max?: number; length?: number } = {}
+  ) {
     return {
-      'array.min': tPlugin('validation.filesMin', language),
-      'array.max': tPlugin('validation.filesMax', language),
-      'array.length': tPlugin('validation.filesLength', language)
+      'array.min': tPlugin('validation.filesMin', language, {
+        count: limits.min ?? 1
+      }),
+      'array.max': tPlugin('validation.filesMax', language, {
+        count: limits.max ?? 1
+      }),
+      'array.length': tPlugin('validation.filesLength', language, {
+        count: limits.length ?? 1
+      })
     }
   }
 }

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

@@ -1,14 +1,19 @@
 import { type GeospatialFieldComponent } from '@defra/forms-model'
 import { type ArraySchema } from 'joi'
 
+import { EN_GB } from '../../../constants.js'
 import { type ComponentBase } from './ComponentBase.js'
 import {
   FormComponent,
   isGeospatialState
 } from './FormComponent.js'
 import { getMapLayers } from './LocationFieldHelpers.js'
-import { getGeospatialSchema } from './helpers/geospatial.js'
+import {
+  determineLimits,
+  getGeospatialSchema
+} from './helpers/geospatial.js'
 import { 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 {
@@ -24,6 +29,7 @@ export class GeospatialField extends FormComponent {
   declare options: GeospatialFieldComponent['options']
   declare formSchema: ArraySchema<GeospatialState>
   declare stateSchema: ArraySchema<GeospatialState>
+  declare limits: { min?: number; max?: number; length?: number }
 
   constructor(
     def: GeospatialFieldComponent,
@@ -33,20 +39,24 @@ export class GeospatialField extends FormComponent {
 
     const { options } = def
 
-    const formSchema = getGeospatialSchema(def).label(this.label).messages({
-      'array.min': messageTemplate.featuresMin,
-      'array.max': messageTemplate.featuresMax,
-      'array.length': messageTemplate.featuresLength
-    })
+    let formSchema = getGeospatialSchema(def).label(this.label)
+
+    const isOptional = options.required === false
+    const limits = determineLimits(def, isOptional)
+
+    formSchema = formSchema.messages(
+      GeospatialField.buildErrorMessages(EN_GB, limits)
+    )
 
     this.formSchema = formSchema
     this.stateSchema = formSchema.default(null)
 
-    if (options.required === false) {
+    if (isOptional) {
       this.stateSchema = this.stateSchema.allow(null)
     }
 
     this.options = options
+    this.limits = limits
   }
 
   getFormValueFromState(state: FormSubmissionState) {
@@ -127,9 +137,7 @@ export class GeospatialField extends FormComponent {
           'components.geospatialField.validation.wrongCountry',
           {
             count: Number(err.path[1]) + 1,
-            country: translator.t(
-              `common.${(err.context.country as string).toLowerCase()}`
-            )
+            country: translator.t(`common.${err.context.country}`)
           }
         )
       }
@@ -149,6 +157,13 @@ export class GeospatialField extends FormComponent {
     return isGeospatialState(value)
   }
 
+  getValidationMessagesOverride(translator: Translator) {
+    const { language } = translator
+    return {
+      [this.name]: GeospatialField.buildErrorMessages(language, this.limits)
+    }
+  }
+
   /**
    * For error preview page that shows all possible errors on a component
    */
@@ -169,11 +184,28 @@ export class GeospatialField extends FormComponent {
         { type: 'required', template: messageTemplate.selectRequired },
         {
           type: 'array.min',
-          template: '{{#title}} must contain at least 1 items'
+          template: '{{#title}} must contain at least 1 item'
         },
         { type: 'object.invalidjson', template: messageTemplate.format }
       ],
       advancedSettingsErrors: []
     }
   }
+
+  static buildErrorMessages(
+    language: string,
+    limits: { min?: number; max?: number; length?: number } = {}
+  ) {
+    return {
+      'array.min': tPlugin('validation.featuresMin', language, {
+        count: limits.min ?? 1
+      }),
+      'array.max': tPlugin('validation.featuresMax', language, {
+        count: limits.max ?? 1
+      }),
+      'array.length': tPlugin('validation.featuresLength', language, {
+        count: limits.length ?? 1
+      })
+    }
+  }
 }

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

@@ -125,9 +125,11 @@ export abstract class LocationFieldBase extends FormComponent {
     const viewModel = super.getViewModel(context)
 
     if (this.instructionText) {
+      const { tComponent } = context.translator
       return {
         ...viewModel,
-        instructionText: this.instructionText
+        instructionText:
+          tComponent(this.def, 'instructionText') || this.instructionText
       }
     }
 

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

@@ -1,6 +1,6 @@
 import { type Context, type CustomValidator } from 'joi'
 
-import { type EastingNorthingField } from './EastingNorthingField.js'
+import { EastingNorthingField } from './EastingNorthingField.js'
 import { isFormValue } from './FormComponent.js'
 import { type GeospatialField } from './GeospatialField.js'
 import { type LatLongField } from './LatLongField.js'
@@ -190,13 +190,23 @@ export function getLocationFieldViewModel(
     ...viewModel,
     fieldset,
     items,
-    mapLayers: getMapLayers(component)
+    mapLayers: getMapLayers(component),
+    country:
+      component instanceof EastingNorthingField
+        ? component.options.countries?.at(0)
+        : undefined
   }
 
   if (component.options.instructionText) {
+    const { t, tComponent } = context.translator
+
     return {
       ...result,
-      instructionText: component.options.instructionText
+      instructionSummary: t('components.locationFieldBase.howToFind'),
+      instructionText:
+        tComponent(component.def, 'instructionText') ||
+        component.options.instructionText,
+      t
     }
   }
 

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

@@ -1,12 +1,16 @@
 import {
-  GeospatialFieldOptionsCountryEnum,
   type GeospatialFieldComponent,
   type GeospatialFieldOptionsCountry
 } from '@defra/forms-model'
 import Bourne from '@hapi/bourne'
 import { booleanWithin } from '@turf/boolean-within'
+import { point } from '@turf/helpers'
+// @ts-expect-error - no types
+import OsGridRef from 'geodesy/osgridref.js'
 import JoiBase, { type CustomValidator } from 'joi'
 
+import { type EastingNorthingField } from '../EastingNorthingField.js'
+import { type EastingNorthingState } from '../types.js'
 import {
   type Coordinates,
   type Feature,
@@ -15,13 +19,6 @@ import {
 } from '../../types.js'
 import { countries } from '../../../map/routes/index.js'
 
-const countriesDesc: Record<GeospatialFieldOptionsCountryEnum, string> = {
-  [GeospatialFieldOptionsCountryEnum.England]: 'England',
-  [GeospatialFieldOptionsCountryEnum.NorthernIreland]: 'Northern Ireland',
-  [GeospatialFieldOptionsCountryEnum.Scotland]: 'Scotland',
-  [GeospatialFieldOptionsCountryEnum.Wales]: 'Wales'
-}
-
 const Joi = JoiBase.extend({
   type: 'array',
   base: JoiBase.array(),
@@ -98,25 +95,43 @@ const featureSchema = Joi.object<Feature>().keys({
   geometry: featureGeometrySchema
 })
 
-function applySchemaConstraints(
-  schema: JoiBase.ArraySchema<Feature[]>,
-  def: GeospatialFieldComponent
+export function determineLimits(
+  def: GeospatialFieldComponent,
+  isOptional: boolean
 ) {
-  const { options, schema: constraints } = def
-  const isOptional = options.required === false
-
+  const { schema: constraints } = def
+  const limits: { min?: number; max?: number; length?: number } = {}
   if (typeof constraints?.length === 'number') {
-    schema = schema.length(constraints.length)
+    limits.length = constraints.length
   } else {
     if (typeof constraints?.min === 'number') {
-      schema = schema.min(constraints.min)
+      limits.min = constraints.min
     } else if (!isOptional) {
-      schema = schema.min(1)
+      limits.min = 1
     }
 
-    schema = schema.max(
-      typeof constraints?.max === 'number' ? constraints.max : 50
-    )
+    limits.max = typeof constraints?.max === 'number' ? constraints.max : 50
+  }
+  return limits
+}
+
+function applySchemaConstraints(
+  schema: JoiBase.ArraySchema<Feature[]>,
+  def: GeospatialFieldComponent
+) {
+  const { options } = def
+  const isOptional = options.required === false
+
+  const limits = determineLimits(def, isOptional)
+
+  if (limits.length !== undefined) {
+    schema = schema.length(limits.length)
+  }
+  if (limits.min !== undefined) {
+    schema = schema.min(limits.min)
+  }
+  if (limits.max !== undefined) {
+    schema = schema.max(limits.max)
   }
 
   if (isOptional) {
@@ -156,7 +171,7 @@ export function getGeospatialSchema(
 
     if (!result) {
       return helpers.error('any.custom', {
-        country: countriesDesc[country as GeospatialFieldOptionsCountryEnum]
+        country
       })
     }
 
@@ -171,3 +186,51 @@ export function getGeospatialSchema(
     def
   )
 }
+
+export function getEastingNorthingCountryValidator(
+  field: EastingNorthingField,
+  country: GeospatialFieldOptionsCountry
+) {
+  const validateCountryBounds: CustomValidator = (value, helpers) => {
+    const countryFeature = countries.features.find(
+      (feature) => feature.id === country
+    )
+
+    if (!countryFeature) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return value
+    }
+
+    const eastingNorthing = field.getFormValueFromState(
+      value as EastingNorthingState
+    )
+
+    if (!eastingNorthing) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return value
+    }
+
+    const gridRef = new OsGridRef(
+      eastingNorthing.easting,
+      eastingNorthing.northing
+    )
+    const latLong = gridRef.toLatLon()
+    const coord = point([latLong.longitude, latLong.latitude])
+    const within = booleanWithin(coord, countryFeature)
+
+    if (!within) {
+      return helpers.error(
+        'any.custom',
+        {
+          country
+        },
+        { path: [field.name] }
+      )
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return value
+  }
+
+  return validateCountryBounds
+}

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/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,
@@ -57,15 +59,18 @@ export function buildValidationMessages(t: (key: string) => string) {
     dateMax: t('components.dateField.validation.dateMax'),
 
     unicode: t('validation.unicode'),
-    arrayMin: t('validation.arrayMin'),
-    arrayMax: t('validation.arrayMax'),
-    arrayLength: t('validation.arrayLength'),
-    featuresMin: t('validation.featuresMin'),
-    featuresMax: t('validation.featuresMax'),
-    featuresLength: t('validation.featuresLength'),
-    filesMin: t('validation.filesMin'),
-    filesMax: t('validation.filesMax'),
-    filesLength: t('validation.filesLength')
+    // 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 })
   }
 }