@defra/forms-engine-plugin 4.2.0 → 4.4.0

package/src/server/plugins/engine/components/helpers/geospatial.test.js

@@ -0,0 +1,55 @@
+import { validState } from '~/src/server/plugins/engine/components/helpers/__stubs__/geospatial.js'
+import { geospatialSchema } from '~/src/server/plugins/engine/components/helpers/geospatial.js'
+
+describe('Geospatial validation helpers', () => {
+  test('it should not have errors for valid geojson object', () => {
+    const result = geospatialSchema.validate(validState)
+
+    expect(result.error).toBeUndefined()
+    expect(result.value).toBeDefined()
+    expect(result.value).toHaveLength(4)
+  })
+
+  test('it should not have errors for valid geojson string', () => {
+    const result = geospatialSchema.validate(JSON.stringify(validState))
+
+    expect(result.error).toBeUndefined()
+    expect(result.value).toBeDefined()
+    expect(result.value).toHaveLength(4)
+  })
+
+  test('it should have errors for invalid json string', () => {
+    const result = geospatialSchema.validate('{')
+
+    expect(result.error).toBeDefined()
+    expect(result.value).toBe('{')
+  })
+
+  test('it should have errors for invalid geojson string', () => {
+    const result = geospatialSchema.validate('[')
+
+    expect(result.error).toBeDefined()
+    expect(result.value).toBe('[')
+  })
+
+  test('it should validate an empty array', () => {
+    const result = geospatialSchema.validate('[]')
+
+    expect(result.error).toBeUndefined()
+    expect(result.value).toEqual([])
+  })
+
+  test('it should not validate an empty object', () => {
+    const result = geospatialSchema.validate('{}')
+
+    expect(result.error).toBeDefined()
+    expect(result.value).toBeUndefined()
+  })
+
+  test('it should validate an empty string', () => {
+    const result = geospatialSchema.validate('')
+
+    expect(result.error).toBeDefined()
+    expect(result.value).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,93 @@
+import Bourne from '@hapi/bourne'
+import JoiBase from 'joi'
+
+import {
+  type Coordinates,
+  type Feature,
+  type FeatureProperties,
+  type Geometry
+} from '~/src/server/plugins/engine/types.js'
+
+const Joi = JoiBase.extend({
+  type: 'array',
+  base: JoiBase.array(),
+  messages: {
+    'object.invalidjson': '{{#label}} must be a valid json array string'
+  },
+  coerce: {
+    from: 'string',
+    method(value, helpers) {
+      if (typeof value === 'string') {
+        if (value.trim() === '') {
+          return {
+            value: undefined
+          }
+        }
+
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          return { value: Bourne.parse(value) }
+        } catch {
+          const result = {
+            value,
+            errors: [helpers.error('object.invalidjson')]
+          }
+
+          return result
+        }
+      } else {
+        return {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          value
+        }
+      }
+    }
+  }
+}) as JoiBase.Root
+
+const coordinatesSchema = Joi.array<Coordinates[]>()
+  .items(Joi.number().required(), Joi.number().required())
+  .required()
+
+const featurePropertiesSchema = Joi.object<FeatureProperties>()
+  .keys({
+    description: Joi.string().required(),
+    coordinateGridReference: Joi.string().required(),
+    centroidGridReference: Joi.string().required()
+  })
+  .required()
+
+const featureGeometrySchema = Joi.object<Geometry>().keys({
+  type: Joi.string().valid('Point', 'LineString', 'Polygon').required(),
+  coordinates: Joi.array()
+    .when('type', {
+      switch: [
+        { is: 'Point', then: coordinatesSchema },
+        {
+          is: 'LineString',
+          then: Joi.array().items(coordinatesSchema).min(2)
+        },
+        {
+          is: 'Polygon',
+          then: Joi.array().items(Joi.array().items(coordinatesSchema).min(3))
+        }
+      ]
+    })
+    .required()
+})
+
+const featureSchema = Joi.object<Feature>().keys({
+  id: Joi.string().required(),
+  type: Joi.string().valid('Feature').required(),
+  properties: featurePropertiesSchema,
+  geometry: featureGeometrySchema
+})
+
+export const geospatialSchema = Joi.array<Feature[]>()
+  .items(featureSchema)
+  .unique('id')
+  .required()
+
+/**
+ * @import { CustomHelpers } from 'joi'
+ */

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

@@ -30,3 +30,4 @@ export { NationalGridFieldNumberField } from '~/src/server/plugins/engine/compon
 export { LatLongField } from '~/src/server/plugins/engine/components/LatLongField.js'
 export { HiddenField } from '~/src/server/plugins/engine/components/HiddenField.js'
 export { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'
+export { GeospatialField } from '~/src/server/plugins/engine/components/GeospatialField.js'

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

@@ -48,7 +48,6 @@ import {
   createPage,
   type PageControllerClass
 } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
-import { copyNotYetValidatedState } from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
 import { validationOptions as opts } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
 import * as defaultServices from '~/src/server/plugins/engine/services/index.js'
 import {
@@ -402,9 +401,6 @@ export class FormModel {
     // Add paths for navigation
     this.assignPaths(context)
 
-    // Handle restoration of payload from say a 'save-and-exit' request
-    copyNotYetValidatedState(request, context)
-
     return context
   }
 

package/src/server/plugins/engine/pageControllers/PageController.ts

@@ -37,6 +37,7 @@ export class PageController {
   name?: string
   model: FormModel
   pageDef: Page
+  id?: string
   title: string
   section?: Section
   condition?: ExecutableCondition
@@ -52,6 +53,7 @@ export class PageController {
     this.name = def.name
     this.model = model
     this.pageDef = pageDef
+    this.id = pageDef.id
     this.title = pageDef.title
     this.events = pageDef.events
 

package/src/server/plugins/engine/pageControllers/QuestionPageController.ts

@@ -31,10 +31,7 @@ import {
 } from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
-import {
-  clearNotYetValidatedState,
-  prefillStateFromQueryParameters
-} from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
+import { prefillStateFromQueryParameters } from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
 import {
   type AnyFormRequest,
   type FormContext,
@@ -342,8 +339,7 @@ export class QuestionPageController extends PageController {
 
     const cacheService = getCacheService(request.server)
 
-    // Clear any 'not yet validated' state before saving to cache
-    return cacheService.setState(request, clearNotYetValidatedState(state))
+    return cacheService.setState(request, state)
   }
 
   async mergeState(

package/src/server/plugins/engine/pageControllers/helpers/state.test.ts

@@ -1,19 +1,27 @@
-import { ComponentType, type Page } from '@defra/forms-model'
+import { ComponentType, ControllerType, type Page } from '@defra/forms-model'
 
 import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
 import {
+  checkSaveAndExitRepeater,
   copyNotYetValidatedState,
   prefillStateFromQueryParameters,
   stripParam
 } from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
 import {
   type AnyFormRequest,
-  type FormContext,
-  type FormContextRequest
+  type FormContext
 } from '~/src/server/plugins/engine/types.js'
 import { type FormsService, type Services } from '~/src/server/types.js'
 
+const mockGetCacheService = jest.fn()
+const mockCacheService = { setState: jest.fn() }
+
+jest.mock('~/src/server/plugins/engine/helpers.ts', () => ({
+  __esModule: true,
+  getCacheService: (...args: unknown[]) => mockGetCacheService(...args)
+}))
+
 function buildMockPage(
   pagesOverride = {},
   stateOverride = {},
@@ -225,23 +233,26 @@ describe('State helpers', () => {
   })
 
   describe('copyNotYetValidatedState', () => {
-    it('should ignore if no invalid state', () => {
-      const mockRequest = {} as FormContextRequest
+    beforeEach(() => {
+      mockGetCacheService.mockReturnValue(mockCacheService)
+    })
+    it('should ignore if no invalid state', async () => {
+      const mockRequest = {} as AnyFormRequest
       const mockContext = {
         state: { abc: '123' },
         payload: {}
       } as unknown as FormContext
-      copyNotYetValidatedState(mockRequest, mockContext)
+      await copyNotYetValidatedState(mockRequest, mockContext)
       expect(mockContext.state).toEqual({ abc: '123' })
       expect(mockContext.payload).toEqual({})
     })
 
-    it('should ignore if wrong path', () => {
+    it('should ignore if wrong path', async () => {
       const mockRequest = {
         url: {
           pathname: '/form-page1'
         }
-      } as unknown as FormContextRequest
+      } as unknown as AnyFormRequest
       const mockContext = {
         state: {
           abc: '123',
@@ -252,7 +263,7 @@ describe('State helpers', () => {
         },
         payload: {}
       } as unknown as FormContext
-      copyNotYetValidatedState(mockRequest, mockContext)
+      await copyNotYetValidatedState(mockRequest, mockContext)
       expect(mockContext.state).toEqual({
         abc: '123',
         __stateNotYetValidated: {
@@ -263,12 +274,12 @@ describe('State helpers', () => {
       expect(mockContext.payload).toEqual({})
     })
 
-    it('should apply if correct path', () => {
+    it('should apply if correct path', async () => {
       const mockRequest = {
         url: {
           pathname: '/form-page1'
         }
-      } as unknown as FormContextRequest
+      } as unknown as AnyFormRequest
       const mockContext = {
         state: {
           abc: '123',
@@ -279,17 +290,70 @@ describe('State helpers', () => {
         },
         payload: {}
       } as unknown as FormContext
-      copyNotYetValidatedState(mockRequest, mockContext)
+      await copyNotYetValidatedState(mockRequest, mockContext)
       expect(mockContext.state).toEqual({
         abc: '123',
-        __stateNotYetValidated: {
-          def: '456',
-          __currentPagePath: '/form-page1'
-        }
+        __stateNotYetValidated: undefined
       })
       expect(mockContext.payload).toEqual({
         def: '456'
       })
     })
   })
+
+  describe('checkSaveAndExitRepeater', () => {
+    function createMockContextWithPath(path: string) {
+      return {
+        state: {
+          abc: '123',
+          __stateNotYetValidated: {
+            def: '456',
+            __currentPagePath: path
+          }
+        },
+        payload: {}
+      } as unknown as FormContext
+    }
+
+    const mockModel = {
+      def: {
+        pages: [
+          {
+            controller: ControllerType.Repeat,
+            path: '/personal_details'
+          }
+        ]
+      },
+      basePath: 'form/preview/draft/repeater-test'
+    } as unknown as FormModel
+
+    it('should return undefined if url does not end in a guid', () => {
+      const mockContext = createMockContextWithPath(
+        '/form/preview/draft/repeater-test/personal_details'
+      )
+      expect(checkSaveAndExitRepeater(mockContext, mockModel)).toBeUndefined()
+    })
+
+    it('should return undefined if url ends in a guid but not a repeater path', () => {
+      const mockContext = createMockContextWithPath(
+        '/form/preview/draft/repeater-test/wrong_page/7d27fe6e-73e8-4265-84bd-1e118c92470b'
+      )
+      expect(checkSaveAndExitRepeater(mockContext, mockModel)).toBeUndefined()
+    })
+
+    it('should return undefined if url is not a string', () => {
+      // @ts-expect-error - invalid dataype on purpose for this test
+      const mockContext = createMockContextWithPath({})
+      expect(checkSaveAndExitRepeater(mockContext, mockModel)).toBeUndefined()
+    })
+
+    it('should return correct urls if url ends in a guid and is a repeater path', () => {
+      const mockContext = createMockContextWithPath(
+        '/form/preview/draft/repeater-test/personal_details/7d27fe6e-73e8-4265-84bd-1e118c92470b'
+      )
+      expect(checkSaveAndExitRepeater(mockContext, mockModel)).toBe(
+        '/form/preview/draft/repeater-test/personal_details/7d27fe6e-73e8-4265-84bd-1e118c92470b'
+      )
+    })
+  })
 })

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

@@ -1,21 +1,24 @@
-import { getHiddenFields } from '@defra/forms-model'
+import { ControllerType, getHiddenFields } from '@defra/forms-model'
+import { validate as isValidUUID } from 'uuid'
 
+import { getCacheService } from '~/src/server/plugins/engine/helpers.js'
 import {
   CURRENT_PAGE_PATH_KEY,
   STATE_NOT_YET_VALIDATED
 } from '~/src/server/plugins/engine/index.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
 import {
   type AnyFormRequest,
   type FormContext,
-  type FormContextRequest,
   type FormStateValue,
-  type FormSubmissionState,
   type FormValue
 } from '~/src/server/plugins/engine/types.js'
 import { type FormQuery } from '~/src/server/routes/types.js'
 import { type Services } from '~/src/server/types.js'
 
+const GUID_LENGTH = 36
+
 /**
  * A series of functions that can transform a pre-fill input parameter e.g lookup a form title based on form id
  */
@@ -100,14 +103,56 @@ export async function prefillStateFromQueryParameters(
   return true
 }
 
+/**
+ * Checks whether the save-and-exit finished on a repeater with partial state
+ * @param context - the form context
+ */
+export function checkSaveAndExitRepeater(
+  context: FormContext,
+  model: FormModel
+) {
+  const potentiallyInvalidState = context.state[STATE_NOT_YET_VALIDATED] as
+    | Record<string, FormValue>
+    | undefined
+  if (!potentiallyInvalidState) {
+    return
+  }
+
+  const originalPath = potentiallyInvalidState[CURRENT_PAGE_PATH_KEY]
+
+  const repeaterPaths = model.def.pages
+    .filter((page) => page.controller === ControllerType.Repeat)
+    .map((p) => `/${model.basePath}${p.path}/`)
+
+  if (typeof originalPath !== 'string') {
+    return undefined
+  }
+
+  const segments = originalPath.split('/')
+  const lastSegment = segments.at(-1) ?? ''
+
+  if (!isValidUUID(lastSegment)) {
+    return undefined
+  }
+
+  const guidStartIndex = originalPath.length - GUID_LENGTH
+  const originalPathWithoutGuid = originalPath.substring(0, guidStartIndex)
+
+  if (!repeaterPaths.includes(originalPathWithoutGuid)) {
+    return undefined
+  }
+
+  return originalPath
+}
+
 /**
  * Copies any potentially invalid state into the payload, and removes those values from state
  * NOTE - this method has a side-effect on 'context.state' and 'context.payload'
  * @param request - the form request
  * @param context - the form context
  */
-export function copyNotYetValidatedState(
-  request: FormContextRequest,
+export async function copyNotYetValidatedState(
+  request: AnyFormRequest,
   context: FormContext
 ) {
   const potentiallyInvalidState = context.state[STATE_NOT_YET_VALIDATED] as
@@ -125,18 +170,13 @@ export function copyNotYetValidatedState(
       ...potentiallyInvalidState,
       [CURRENT_PAGE_PATH_KEY]: undefined
     }
-  }
-}
 
-/**
- * Remove any temporary 'not yet validated' state now that it's been validated
- * @param state - the form state
- */
-export function clearNotYetValidatedState(
-  state: FormSubmissionState
-): FormSubmissionState {
-  if (state[STATE_NOT_YET_VALIDATED]) {
-    state[STATE_NOT_YET_VALIDATED] = undefined
+    // Remove any temporary 'not yet validated' state now it's been copied to the payload
+    if (context.state[STATE_NOT_YET_VALIDATED]) {
+      context.state[STATE_NOT_YET_VALIDATED] = undefined
+    }
+
+    const cacheService = getCacheService(request.server)
+    await cacheService.setState(request, context.state)
   }
-  return state
 }

package/src/server/plugins/engine/pageControllers/helpers/submission.test.ts

@@ -1,5 +1,7 @@
+import { GeospatialField } from '~/src/server/plugins/engine/components/GeospatialField.js'
 import { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'
 import { TextField } from '~/src/server/plugins/engine/components/TextField.js'
+import { validSingleState } from '~/src/server/plugins/engine/components/helpers/__stubs__/geospatial.js'
 import { type DetailItemField } from '~/src/server/plugins/engine/models/types.js'
 import {
   buildMainRecords,
@@ -242,6 +244,34 @@ describe('Submission helpers', () => {
 
       expect(result).toEqual([])
     })
+
+    it('should JSON stringify GeospatialField', () => {
+      const mockGeospatialField = Object.create(GeospatialField.prototype)
+      mockGeospatialField.name = 'geospatial'
+
+      const items = [
+        {
+          name: 'geospatial',
+          label: 'Site features',
+          field: mockGeospatialField,
+          state: {
+            geospatial: validSingleState
+          } as FormSubmissionState
+        }
+      ] as unknown as DetailItemField[]
+
+      const result = buildMainRecords(items)
+
+      expect(result).toHaveLength(1)
+      expect(result).toEqual([
+        {
+          name: 'geospatial',
+          title: 'Site features',
+          value:
+            '[{"type":"Feature","properties":{"description":"My farm house","coordinateGridReference":"ST 00001","centroidGridReference":"ST 00001"},"geometry":{"coordinates":[-2.5723699109417737,53.2380485215034],"type":"Point"},"id":"a"}]'
+        }
+      ])
+    })
   })
 
   describe('buildRepeaterRecords', () => {
@@ -295,5 +325,49 @@ describe('Submission helpers', () => {
       expect(result[0].title).toBe('Addresses')
       expect(result[0].value).toHaveLength(1)
     })
+
+    it('should JSON stringify GeospatialField', () => {
+      const mockGeospatialField = Object.create(GeospatialField.prototype)
+      mockGeospatialField.name = 'geospatial'
+
+      const items = [
+        {
+          name: 'features',
+          label: 'Site features repeater',
+          subItems: [
+            [
+              {
+                name: 'geospatial',
+                label: 'Site features',
+                field: mockGeospatialField,
+                state: {
+                  geospatial: validSingleState
+                } as FormSubmissionState
+              } as unknown as DetailItemField[]
+            ]
+          ]
+        }
+      ] as unknown as DetailItemField[]
+
+      const result = buildRepeaterRecords(items)
+
+      expect(result).toHaveLength(1)
+      expect(result).toEqual([
+        {
+          name: 'features',
+          title: 'Site features repeater',
+          value: [
+            [
+              {
+                name: 'geospatial',
+                title: 'Site features',
+                value:
+                  '[{"type":"Feature","properties":{"description":"My farm house","coordinateGridReference":"ST 00001","centroidGridReference":"ST 00001"},"geometry":{"coordinates":[-2.5723699109417737,53.2380485215034],"type":"Point"},"id":"a"}]'
+              }
+            ]
+          ]
+        }
+      ])
+    })
   })
 })

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

@@ -1,5 +1,6 @@
 import { type SubmitPayload } from '@defra/forms-model'
 
+import { GeospatialField } from '~/src/server/plugins/engine/components/GeospatialField.js'
 import { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'
 import { getAnswer } from '~/src/server/plugins/engine/components/helpers/components.js'
 import {
@@ -32,6 +33,14 @@ export function buildMainRecords(items: DetailItem[]): SubmitRecord[] {
   for (const item of fieldItems) {
     if (item.field instanceof PaymentField) {
       records.push(...buildPaymentRecords(item))
+    } else if (item.field instanceof GeospatialField) {
+      // Stringify of GeoJSON is done here rather than inside `getContextValueFromState`
+      // so we don't incur the overhead of JSON.stringify on every request when building context
+      records.push({
+        name: item.name,
+        title: item.label,
+        value: JSON.stringify(item.field.getFormValueFromState(item.state))
+      })
     } else {
       records.push({
         name: item.name,
@@ -103,7 +112,14 @@ export function buildRepeaterRecords(
         detailItems.map((subItem) => ({
           name: subItem.name,
           title: subItem.label,
-          value: getAnswer(subItem.field, subItem.state, { format: 'data' })
+          value:
+            // Stringify of GeoJSON is done here rather than inside `getContextValueFromState`
+            // so we don't incur the overhead of JSON.stringify on every request when building context
+            subItem.field instanceof GeospatialField
+              ? JSON.stringify(
+                  subItem.field.getFormValueFromState(subItem.state)
+                )
+              : getAnswer(subItem.field, subItem.state, { format: 'data' })
         }))
       )
     }))

package/src/server/plugins/engine/pageControllers/validationOptions.ts

@@ -89,7 +89,9 @@ export const messages: LanguageMessagesExt = {
   'date.base': messageTemplate.dateFormat,
   'date.format': messageTemplate.dateFormat,
   'date.min': messageTemplate.dateMin,
-  'date.max': messageTemplate.dateMax
+  'date.max': messageTemplate.dateMax,
+
+  'object.invalidjson': messageTemplate.format
 }
 
 export const messagesPre: LanguageMessages =

package/src/server/plugins/engine/routes/index.test.ts

@@ -86,7 +86,8 @@ describe('redirectOrMakeHandler', () => {
     // Reset mock model
     mockModel.getFormContext = jest.fn().mockReturnValue({
       isForceAccess: false,
-      data: {}
+      data: {},
+      state: {}
     })
 
     // Setup mocks
@@ -225,7 +226,8 @@ describe('redirectOrMakeHandler', () => {
     it('should call makeHandler when context has force access', async () => {
       mockModel.getFormContext = jest.fn().mockReturnValue({
         isForceAccess: true,
-        data: {}
+        data: {},
+        state: {}
       })
 
       await redirectOrMakeHandler(