@defra/forms-engine-plugin 5.0.0-alpha.11 → 5.0.0-alpha.13

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/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

@@ -187,7 +187,7 @@ export class EastingNorthingField extends FormComponent {
       if (err.context?.country) {
         err.text = translator.t(
           'components.eastingNorthingField.wrongCountry',
-          { country: err.context.country }
+          { country: translator.t(`common.${err.context.country}`) }
         )
       }
     })

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

@@ -113,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,
@@ -132,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
@@ -309,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)
     }
   }
 
@@ -417,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) {
@@ -101,6 +111,7 @@ export class GeospatialField extends FormComponent {
 
     return {
       ...viewModel,
+      lang: context.translator.language,
       country: this.options.countries?.at(0),
       geometryTypes: this.options.geometryTypes,
       mapLayers: getMapLayers(this),
@@ -127,9 +138,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 +158,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 +185,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

@@ -124,10 +124,16 @@ export abstract class LocationFieldBase extends FormComponent {
   getViewModel(context: RenderContext) {
     const viewModel = super.getViewModel(context)
 
+    Object.assign(viewModel, {
+      lang: context.translator.language
+    })
+
     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

@@ -194,13 +194,20 @@ export function getLocationFieldViewModel(
     country:
       component instanceof EastingNorthingField
         ? component.options.countries?.at(0)
-        : undefined
+        : undefined,
+    lang: context.translator.language
   }
 
   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/components.ts

@@ -6,6 +6,7 @@ import { ListFormComponent } from '../ListFormComponent.js'
 import { escapeMarkdown } from './index.js'
 import * as Components from '../index.js'
 import { markdown } from '../markdownParser.js'
+import { UnknownComponentTypeError } from '../../errors.js'
 import { type Translator } from '../../i18n/types.js'
 import { type FormState } from '../../types.js'
 
@@ -210,7 +211,7 @@ export function createComponent(
   }
 
   if (typeof component === 'undefined') {
-    throw new Error(`Component type ${def.type} does not exist`)
+    throw new UnknownComponentTypeError(def.type)
   }
 
   return component

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

@@ -1,5 +1,4 @@
 import {
-  GeospatialFieldOptionsCountryEnum,
   type GeospatialFieldComponent,
   type GeospatialFieldOptionsCountry
 } from '@defra/forms-model'
@@ -20,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(),
@@ -103,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) {
@@ -161,7 +171,7 @@ export function getGeospatialSchema(
 
     if (!result) {
       return helpers.error('any.custom', {
-        country: countriesDesc[country as GeospatialFieldOptionsCountryEnum]
+        country
       })
     }
 
@@ -212,7 +222,7 @@ export function getEastingNorthingCountryValidator(
       return helpers.error(
         'any.custom',
         {
-          country: countriesDesc[country as GeospatialFieldOptionsCountryEnum]
+          country
         },
         { path: [field.name] }
       )

package/src/server/plugins/engine/errors.ts

@@ -0,0 +1,78 @@
+import { type ValidationError } from 'joi'
+
+/**
+ * Base class for errors caused by an invalid form definition — whether it
+ * fails schema validation or passes the schema but cannot be used by the
+ * engine. Never thrown directly — throw a subclass. Consumers (e.g.
+ * forms-runner error pages) detect the family with
+ * `instanceof InvalidFormDefinitionError`.
+ *
+ * When subclassing, remember that the message and the messages of any
+ * `cause` chain are shown to form authors on preview error pages. Only
+ * describe the problem with the form itself — never include sensitive
+ * details such as file paths, configuration values or secrets.
+ */
+export class InvalidFormDefinitionError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'InvalidFormDefinitionError'
+  }
+}
+
+/**
+ * Thrown when a condition in the definition cannot be compiled into an
+ * evaluatable expression (e.g. it references the wrong component or list).
+ */
+export class ConditionBuildError extends InvalidFormDefinitionError {
+  public readonly conditionName: string
+
+  constructor(conditionName: string, options?: ErrorOptions) {
+    super(`Failed to build condition '${conditionName}'`, options)
+    this.name = 'ConditionBuildError'
+    this.conditionName = conditionName
+  }
+}
+
+/**
+ * Thrown when a page names a controller that is neither built in nor
+ * registered by the host application.
+ */
+export class UnknownPageControllerError extends InvalidFormDefinitionError {
+  public readonly controllerName: string
+
+  constructor(controllerName: string) {
+    super(`Page controller ${controllerName} does not exist`)
+    this.name = 'UnknownPageControllerError'
+    this.controllerName = controllerName
+  }
+}
+
+/**
+ * Thrown when a component declares a type with no registered implementation.
+ */
+export class UnknownComponentTypeError extends InvalidFormDefinitionError {
+  public readonly componentType: string
+
+  constructor(componentType: string) {
+    super(`Component type ${componentType} does not exist`)
+    this.name = 'UnknownComponentTypeError'
+    this.componentType = componentType
+  }
+}
+
+/**
+ * Thrown when a form definition fails Joi schema validation. The raw
+ * ValidationError is preserved as `cause` so consumers can reach the
+ * per-field details; the message carries Joi's own summary so log lines
+ * remain diagnostic for consumers that only read `error.message`.
+ */
+export class SchemaValidationError extends InvalidFormDefinitionError {
+  // Error types `cause` as unknown; this constructor only accepts a Joi
+  // ValidationError, so narrow the declaration for consumers (type-only).
+  declare cause: ValidationError
+
+  constructor(cause: ValidationError) {
+    super(`Invalid form definition: ${cause.message}`, { cause })
+    this.name = 'SchemaValidationError'
+  }
+}