@defra/forms-engine-plugin 5.0.0-alpha.12 → 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/GeospatialField.ts

@@ -111,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),

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

@@ -124,6 +124,10 @@ 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 {

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

@@ -194,7 +194,8 @@ export function getLocationFieldViewModel(
     country:
       component instanceof EastingNorthingField
         ? component.options.countries?.at(0)
-        : undefined
+        : undefined,
+    lang: context.translator.language
   }
 
   if (component.options.instructionText) {

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/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'
+  }
+}

package/src/server/plugins/engine/i18n/translations/cy.json

@@ -323,7 +323,16 @@
     },
 
     "locationFieldBase": {
-      "howToFind": "Sut i ddod o hyd i fanylion lleoliad"
+      "howToFind": "Sut i ddod o hyd i fanylion lleoliad",
+      "map": {
+        "helpPanel": {
+          "label": "Sut i ddefnyddio'r map hwn",
+          "point1": "Chwilio am sir, lle neu god post",
+          "point2": "Defnyddiwch yr eiconau + a - i chwyddo i mewn ac allan",
+          "point3": "Defnyddiwch lyfliwr neu allweddlon i ganolbwyntio'r pwynt yn y lleoliad",
+          "point4": "Cliciwch i ychwanegu'r lleoliad i'r map"
+        }
+      }
     },
 
     "yesNoField": {
@@ -350,6 +359,47 @@
       "added_few": "Ychwanegwyd [[count]] lleoliad",
       "added_many": "Ychwanegwyd [[count]] o leoliadau",
       "added_other": "Ychwanegwyd [[count]] lleoliad",
+      "map": {
+        "helpPanel": {
+          "label": "Sut i ddefnyddio'r map hwn",
+          "ledeIntro": "Gallwch ychwanegu",
+          "ledeOutro": "i'r map.",
+          "lineText": "llinell",
+          "shapeText": "siâp",
+          "lineOrShapeText": "llinell neu siâp",
+          "typesPhrasePoint": "pwyntiau",
+          "typesPhraseLine": "lliniau",
+          "typesPhraseShape": "siâpiau",
+          "typesPhraseOr": "neu",
+          "point1": "Chwilio am sir, lle neu god post",
+          "point2": "Defnyddiwch yr eiconau + a - i chwyddo i mewn ac allan",
+          "point3": "Cliciwch ddwywaith, neu dewiswch 'Wedi gorffen', pan fyddwch wedi",
+          "point4": "Rhowch enw i'r lleoliad"
+        },
+        "typeDescriptions": {
+          "point": "Pwynt",
+          "line": "Llinell",
+          "polygon": "Siâp"
+        },
+        "buttons": {
+          "point": "Ychwanegu pwynt",
+          "line": "Ychwanegu llinell",
+          "polygon": "Ychwanegu siâp"
+        },
+        "itemLabel1": "Lleoliad",
+        "itemLabel2": "disgrifiad",
+        "itemUpdateLink": "Diweddaru",
+        "itemDeleteLink": "Dileu",
+        "itemFocusLink": "Dangos",
+        "itemVisuallyHidden": "lleoliad",
+        "details": {
+          "summary": "Cyfesurynnau",
+          "type": "Math",
+          "centroidGridReference": "Canol cyfeirnod grid",
+          "firstPointGridReference": "Cyfeirnod grid y pwynt cyntaf",
+          "detailedCoordinates": "Cyfesurynnau manwl"
+        }
+      },
       "validation": {
         "descriptionRequired": "Rhowch ddisgrifiad ar gyfer lleoliad [[count]]",
         "wrongCountry": "Rhaid i leoliad [[count]] fod y tu mewn i [[country]]"

package/src/server/plugins/engine/i18n/translations/en-GB.json

@@ -266,7 +266,16 @@
     },
 
     "locationFieldBase": {
-      "howToFind": "How to find location details"
+      "howToFind": "How to find location details",
+      "map": {
+        "helpPanel": {
+          "label": "How to use this map",
+          "point1": "Search for a place or postcode",
+          "point2": "Use the + and - icons to zoom in and out",
+          "point3": "Use a mouse or keyboard to centre the point at the location",
+          "point4": "Click to add the location to the map"
+        }
+      }
     },
 
     "yesNoField": {
@@ -289,6 +298,47 @@
     "geospatialField": {
       "added_one": "Added [[count]] location",
       "added_other": "Added [[count]] locations",
+      "map": {
+        "helpPanel": {
+          "label": "How to use this map",
+          "ledeIntro": "You can add",
+          "ledeOutro": "to the map.",
+          "lineText": "a line",
+          "shapeText": "a shape",
+          "lineOrShapeText": "a line or shape",
+          "typesPhrasePoint": "points",
+          "typesPhraseLine": "lines",
+          "typesPhraseShape": "shapes",
+          "typesPhraseOr": "or",
+          "point1": "Search for a county, place or postcode",
+          "point2": "Use the + and - icons to zoom in and out",
+          "point3": "Double‑click, or select 'Done', when you have finished drawing",
+          "point4": "Give the location a name"
+        },
+        "typeDescriptions": {
+          "point": "Point",
+          "line": "Line",
+          "polygon": "Shape"
+        },
+        "buttons": {
+          "point": "Add point",
+          "line": "Add line",
+          "polygon": "Add shape"
+        },
+        "itemLabel1": "Location",
+        "itemLabel2": "description",
+        "itemUpdateLink": "Update",
+        "itemDeleteLink": "Delete",
+        "itemFocusLink": "Show",
+        "itemVisuallyHidden": "location",
+        "details": {
+          "summary": "Coordinates",
+          "type": "Type",
+          "centroidGridReference": "Centre grid reference",
+          "firstPointGridReference": "First point grid reference",
+          "detailedCoordinates": "Detailed coordinates"
+        }
+      },
       "validation": {
         "descriptionRequired": "Enter description for location [[count]]",
         "wrongCountry": "Location [[count]] must be within [[country]]"

package/src/server/plugins/engine/models/FormModel.ts

@@ -39,6 +39,10 @@ import {
   type Component
 } from '../components/helpers/components.js'
 import { todayAsDateOnly } from '../date-helper.js'
+import {
+  ConditionBuildError,
+  SchemaValidationError
+} from '../errors.js'
 import {
   findPage,
   getError,
@@ -124,7 +128,7 @@ export class FormModel {
     const result = schema.validate(def, { abortEarly: false })
 
     if (result.error) {
-      throw result.error
+      throw new SchemaValidationError(result.error)
     }
 
     // Make a clone of the shallow copy returned
@@ -292,7 +296,13 @@ export class FormModel {
     })
 
     const { name, displayName, value } = condition
-    const expr = this.toConditionExpression(value, parser)
+
+    let expr
+    try {
+      expr = this.toConditionExpression(value, parser)
+    } catch (cause) {
+      throw new ConditionBuildError(displayName, { cause })
+    }
 
     const fn = (evaluationState: FormState) => {
       const ctx = this.toConditionContext(evaluationState, this.conditions)

package/src/server/plugins/engine/pageControllers/helpers/pages.ts

@@ -4,6 +4,7 @@ import {
   type Page
 } from '@defra/forms-model'
 
+import { UnknownPageControllerError } from '../../errors.js'
 import { type FormModel } from '../../models/index.js'
 import * as PageControllers from '../index.js'
 
@@ -66,7 +67,7 @@ export function createPage(model: FormModel, pageDef: Page) {
   }
 
   if (typeof controller === 'undefined') {
-    throw new Error(`Page controller ${pageDef.controller} does not exist`)
+    throw new UnknownPageControllerError(pageDef.controller)
   }
 
   return controller

package/src/server/plugins/engine/views/components/_location-field-base.html

@@ -73,6 +73,7 @@
   <div id="{{component.model.name}}" class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}"
     data-locationtype="{{component.type | lower}}"
     data-country="{{component.model.country}}"
+    data-lang="{{component.model.lang}}"
     data-maplayers="{{component.model.mapLayers}}">
     {{ govukFieldset({
       legend: {

package/src/server/plugins/engine/views/components/geospatialfield.html

@@ -2,6 +2,7 @@
 
 {% macro GeospatialField(component) %}
   <div class="app-geospatial-field"
+    data-lang="{{component.model.lang}}"
     data-country="{{component.model.country}}"
     data-geometryTypes="{{component.model.geometryTypes}}"
     data-maplayers="{{component.model.mapLayers}}">

package/src/server/plugins/engine/views/components/osgridreffield.html

@@ -3,7 +3,9 @@
 
 {% macro OsGridRefField(component) %}
   {% set hasErrors = component.model.errorMessage %}
-  <div class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}" data-locationtype="{{component.type | lower}}">
+  <div class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}"
+    data-locationtype="{{component.type | lower}}"
+    data-lang="{{component.model.lang}}">
     <div class="app-location-field-inputs">
       {{ TextField(component) }}
     </div>