@defra/forms-engine-plugin 4.3.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/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/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/types.ts

@@ -94,8 +94,10 @@ export type FormSubmissionState = {
   upload?: Record<string, TempFileState>
 } & FormState
 
-export interface FormSubmissionError
-  extends Pick<ValidationErrorItem, 'context' | 'path'> {
+export interface FormSubmissionError extends Pick<
+  ValidationErrorItem,
+  'context' | 'path'
+> {
   href: string // e.g: '#dateField__day'
   name: string // e.g: 'dateField__day'
   text: string // e.g: 'Date field must be a real date'
@@ -125,6 +127,7 @@ export type FormValue =
   | Item['value'][]
   | UploadState
   | RepeatListState
+  | GeospatialState
   | undefined
 
 export type FormState = Partial<Record<string, FormStateValue>>
@@ -285,6 +288,76 @@ export interface RepeatItemState extends FormPayload {
 
 export type RepeatListState = RepeatItemState[]
 
+/**
+ * A longitude/latitude coordinate pair in WGS84 format
+ * Format: [longitude, latitude]
+ */
+export type Coordinates = [longitude: number, latitude: number]
+
+/**
+ * GeoJSON Point geometry
+ */
+export interface PointGeometry {
+  type: 'Point'
+  coordinates: Coordinates
+}
+
+/**
+ * GeoJSON LineString geometry
+ */
+export interface LineStringGeometry {
+  type: 'LineString'
+  coordinates: Coordinates[]
+}
+
+/**
+ * GeoJSON Polygon geometry
+ */
+export interface PolygonGeometry {
+  type: 'Polygon'
+  coordinates: Coordinates[][]
+}
+
+/**
+ * Supported geometry types
+ */
+export type Geometry = PointGeometry | LineStringGeometry | PolygonGeometry
+
+/**
+ * Feature metadata
+ */
+export interface FeatureProperties {
+  /**
+   * Human-readable description of the feature
+   */
+  description: string
+  /**
+   * The OS grid reference of the first coordinate of the feature
+   */
+  coordinateGridReference?: string
+  /**
+   * The OS grid reference of the centroid of the feature
+   */
+  centroidGridReference?: string
+}
+
+/**
+ * A single GeoJSON Feature
+ */
+export interface Feature {
+  id: string
+  type: 'Feature'
+  properties: FeatureProperties
+  geometry: Geometry
+}
+
+/**
+ * A GeoJSON FeatureCollection
+ */
+export type FeatureCollection = Feature[]
+
+export type GeospatialState = FeatureCollection
+
 export interface CheckAnswers {
   title?: ComponentText
   summaryList: SummaryList
@@ -502,6 +575,7 @@ export type RichFormValue =
   | UkAddressState
   | EastingNorthingState
   | LatLongState
+  | GeospatialState
 
 export interface FormAdapterSubmissionMessageData {
   main: Record<string, RichFormValue | null>
@@ -516,8 +590,7 @@ export interface FormAdapterSubmissionMessagePayload {
   result: FormAdapterSubmissionMessageResult
 }
 
-export interface FormAdapterSubmissionMessage
-  extends FormAdapterSubmissionMessagePayload {
+export interface FormAdapterSubmissionMessage extends FormAdapterSubmissionMessagePayload {
   messageId: string
   recordCreatedAt: Date
 }

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

@@ -0,0 +1,7 @@
+{% from "govuk/components/textarea/macro.njk" import govukTextarea %}
+
+{% macro GeospatialField(component) %}
+  <div class="app-geospatial-field">
+    {{ govukTextarea(component.model) }}
+  </div>
+{% endmacro %}

package/src/server/plugins/nunjucks/context.test.js

@@ -33,9 +33,8 @@ describe('Nunjucks context', () => {
         const { config } = await import('~/src/config/index.js')
 
         // Import when isolated to avoid cache
-        const { devtoolContext } = await import(
-          '~/src/server/plugins/nunjucks/context.js'
-        )
+        const { devtoolContext } =
+          await import('~/src/server/plugins/nunjucks/context.js')
 
         // Update config for missing manifest
         config.set('publicDir', tmpdir())

package/src/server/routes/types.ts

@@ -24,8 +24,10 @@ export interface FormParams extends Partial<Record<string, string>> {
   state?: FormStatus
 }
 
-export interface FormRequestRefs
-  extends Omit<ReqRefDefaults, 'Params' | 'Payload' | 'Query'> {
+export interface FormRequestRefs extends Omit<
+  ReqRefDefaults,
+  'Params' | 'Payload' | 'Query'
+> {
   Params: FormParams
   Payload: object | undefined
   Query: FormQuery

package/src/server/services/cacheService.ts

@@ -147,7 +147,9 @@ export class CacheService {
       throw new Error('No session ID found')
     }
 
+    // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style
     const state = (request.params.state as string) || ''
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
     const slug = (request.params.slug as string) || ''
     const key = `${request.yar.id}:${state}:${slug}:`