@defra/forms-engine-plugin 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/client/javascripts/map.js

@@ -11,7 +11,6 @@ import createSearchPlugin from '@defra/interactive-map/plugins/search'
 // @ts-expect-error - no types
 import maplibreProvider from '@defra/interactive-map/providers/maplibre'
 import { centroid } from '@turf/centroid'
-// @ts-expect-error - no types
 import OsGridRef, { LatLon } from 'geodesy/osgridref.js'
 
 import { processGeospatial } from './geospatial-map.js'
@@ -123,10 +122,15 @@ export function getCentroidGridRef(feature) {
   }
 }
 
-/** @type {InteractiveMapInitConfig} */
-export const defaultConfig = {
-  zoom: '6',
-  center: [DEFAULT_LONG, DEFAULT_LAT]
+/**
+ * Get the default config for a map
+ * @returns {InteractiveMapInitConfig}
+ */
+export const getDefaultConfig = () => {
+  return {
+    zoom: '6',
+    center: [DEFAULT_LONG, DEFAULT_LAT]
+  }
 }
 
 export const EVENTS = {
@@ -167,6 +171,7 @@ export function initMaps(config = {}) {
   const {
     assetPath = '/assets',
     apiPath = '/form/api',
+    workerPath = '/assets/interactive-map/maplibre-gl-worker.mjs',
     data = defaultData
   } = config
   const locations = document.querySelectorAll('.app-location-field')
@@ -198,11 +203,15 @@ export function initMaps(config = {}) {
   }
 
   locations.forEach((location, index) => {
-    processLocation({ assetPath, apiPath, data }, location, index)
+    processLocation({ assetPath, apiPath, workerPath, data }, location, index)
   })
 
   geospatials.forEach((geospatial, index) => {
-    processGeospatial({ assetPath, apiPath, data }, geospatial, index)
+    processGeospatial(
+      { assetPath, apiPath, workerPath, data },
+      geospatial,
+      index
+    )
   })
 }
 
@@ -259,7 +268,7 @@ export function makeTileRequestTransformer(apiPath) {
  * @param {MapsEnvironmentConfig} mapsConfig - the map environment params
  */
 export function createMap(mapId, initConfig, mapsConfig) {
-  const { assetPath, apiPath, data = defaultData } = mapsConfig
+  const { assetPath, apiPath, workerPath, data = defaultData } = mapsConfig
   const logoAltText = 'Ordnance survey logo'
   const interactPlugin = createInteractPlugin({
     markerColor: { outdoor: '#ff0000', dark: '#00ff00' },
@@ -271,7 +280,7 @@ export function createMap(mapId, initConfig, mapsConfig) {
   const map = new InteractiveMap(mapId, {
     enableFullscreen: true,
     autoColorScheme: false,
-    mapProvider: maplibreProvider(),
+    mapProvider: maplibreProvider({ workerUrl: workerPath }),
     behaviour: 'inline',
     minZoom: 6,
     maxZoom: 18,
@@ -367,6 +376,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
@@ -407,6 +458,7 @@ export function getMapLayers(layers) {
  * @typedef {object} MapsEnvironmentConfig
  * @property {string} assetPath - the root asset path
  * @property {string} apiPath - the root API path
+ * @property {string} workerPath - the maplibre worker path
  * @property {TileData} data - the tile data config
  */
 
@@ -418,3 +470,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/forms/components.json

@@ -6,6 +6,14 @@
       "path": "/all-components",
       "title": "All Components",
       "components": [
+        {
+          "type": "TrackingField",
+          "name": "trackingField",
+          "title": "Tracking field",
+          "hint": "Help text",
+          "options": {},
+          "schema": {}
+        },
         {
           "type": "TextField",
           "name": "textField",

package/src/server/forms/register-as-a-unicorn-breeder.yaml

@@ -5,6 +5,10 @@ pages:
   - path: '/whats-your-name'
     title: What's your name?
     components:
+      - type: TrackingField
+        name: hasSeenNamePage
+        title: Tracks if the user has seen the name page
+        options: {}
       - type: TextField
         name: textField
         title: Name

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 { SelectField } from './SelectField.js'
+import { withCustomValidationOverrides } from './helpers/index.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,21 @@ export class AutocompleteField extends SelectField {
       formGroup
     }
   }
+
+  getValidationMessagesOverride(translator: Translator) {
+    const { customValidationMessages } = this.options
+    const { t } = translator
+    const defaults = {
+      'any.required': buildValidationMessages(t).objectRequired,
+      'any.only': buildValidationMessages(t).objectRequired
+    }
+
+    return {
+      [this.name]: withCustomValidationOverrides(
+        defaults,
+        undefined,
+        customValidationMessages
+      )
+    }
+  }
 }

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'
@@ -17,8 +19,9 @@ import {
 export class CheckboxesField extends SelectionControlField {
   declare options: CheckboxesFieldComponent['options']
   declare schema: CheckboxesFieldComponent['schema']
-  declare formSchema: ArraySchema<string> | ArraySchema<number>
-  declare stateSchema: ArraySchema<string> | ArraySchema<number>
+  declare formSchema: ArraySchema<string[]> | ArraySchema<number[]>
+  declare stateSchema: ArraySchema<string[]> | ArraySchema<number[]>
+  declare limits: { min?: number; max?: number; length?: number }
 
   constructor(
     def: CheckboxesFieldComponent,
@@ -30,7 +33,7 @@ export class CheckboxesField extends SelectionControlField {
     const { options, schema } = def
 
     let formSchema =
-      type === 'string' ? joi.array<string>() : joi.array<number>()
+      type === 'string' ? joi.array<string[]>() : joi.array<number[]>()
 
     const itemsSchema = joi[type]()
       .valid(...this.values)
@@ -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
@@ -87,10 +89,10 @@ export class ComponentBase {
 }
 
 export type ComponentSchema =
-  | ArraySchema<string>
-  | ArraySchema<number>
-  | ArraySchema<boolean>
-  | ArraySchema<object>
+  | ArraySchema<string[]>
+  | ArraySchema<number[]>
+  | ArraySchema<boolean[]>
+  | ArraySchema<object[]>
   | BooleanSchema<string>
   | BooleanSchema
   | DateSchema