@defra/forms-engine-plugin 4.2.0 → 4.4.0

package/src/server/plugins/engine/components/GeospatialField.test.ts

@@ -0,0 +1,380 @@
+import {
+  ComponentType,
+  type GeospatialFieldComponent
+} from '@defra/forms-model'
+
+import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import { type GeospatialField } from '~/src/server/plugins/engine/components/GeospatialField.js'
+import {
+  validSingleState,
+  validState
+} from '~/src/server/plugins/engine/components/helpers/__stubs__/geospatial.js'
+import {
+  getAnswer,
+  type Field
+} from '~/src/server/plugins/engine/components/helpers/components.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { type GeospatialState } from '~/src/server/plugins/engine/types.js'
+import definition from '~/test/form/definitions/blank.js'
+import { getFormData, getFormState } from '~/test/helpers/component-helpers.js'
+
+describe('GeospatialField', () => {
+  let model: FormModel
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+  })
+
+  describe('Defaults', () => {
+    let def: GeospatialFieldComponent
+    let collection: ComponentCollection
+    let field: Field
+
+    beforeEach(() => {
+      def = {
+        title: 'Example geospatial title',
+        shortDescription: 'Example geospatial',
+        name: 'myComponent',
+        type: ComponentType.GeospatialField,
+        options: {}
+      } satisfies GeospatialFieldComponent
+
+      collection = new ComponentCollection([def], { model })
+      field = collection.fields[0]
+    })
+
+    describe('Schema', () => {
+      it('uses component short description as label', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            flags: expect.objectContaining({
+              label: 'Example geospatial'
+            })
+          })
+        )
+      })
+
+      it('uses component name as keys', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(field.keys).toEqual(['myComponent'])
+        expect(field.collection).toBeUndefined()
+
+        for (const key of field.keys) {
+          expect(keys).toHaveProperty(key)
+        }
+      })
+
+      it('is required by default', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            flags: expect.objectContaining({
+              presence: 'required'
+            })
+          })
+        )
+      })
+
+      it('is optional when configured', () => {
+        const collectionOptional = new ComponentCollection(
+          [{ ...def, options: { required: false } }],
+          { model }
+        )
+
+        const result = collectionOptional.validate(getFormData('[]'))
+        expect(result.errors).toBeUndefined()
+
+        const result2 = collectionOptional.validate(getFormData([]))
+        expect(result2.errors).toBeUndefined()
+      })
+
+      it('accepts valid values', () => {
+        const result1 = collection.validate(getFormData(validState))
+
+        expect(result1.errors).toBeUndefined()
+      })
+
+      it('adds errors for empty value', () => {
+        const result = collection.validate(getFormData(''))
+
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: 'Select example geospatial'
+          })
+        ])
+      })
+
+      it('adds errors for empty value given no short description', () => {
+        def = {
+          title: 'Example geospatial title',
+          name: 'myComponent',
+          type: ComponentType.GeospatialField,
+          options: {}
+        } satisfies GeospatialFieldComponent
+
+        collection = new ComponentCollection([def], { model })
+        const result = collection.validate(getFormData(''))
+
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: 'Select example geospatial title'
+          })
+        ])
+      })
+
+      it('adds errors for invalid values', () => {
+        const result1 = collection.validate(getFormData(['invalid']))
+        const result2 = collection.validate(
+          // @ts-expect-error - Allow invalid param for test
+          getFormData({ unknown: 'invalid' })
+        )
+
+        expect(result1.errors).toBeTruthy()
+        expect(result2.errors).toBeTruthy()
+      })
+    })
+
+    describe('State', () => {
+      it('returns text from single feature state', () => {
+        const state1 = getFormState(validSingleState)
+        const state2 = getFormState(null)
+
+        const answer1 = getAnswer(field, state1)
+        const answer2 = getAnswer(field, state2)
+
+        expect(answer1).toBe('Added 1 location')
+        expect(answer2).toBe('')
+      })
+
+      it('returns text from multiple features state', () => {
+        const state1 = getFormState(validState)
+        const state2 = getFormState(null)
+
+        const answer1 = getAnswer(field, state1)
+        const answer2 = getAnswer(field, state2)
+
+        expect(answer1).toBe('Added 4 locations')
+        expect(answer2).toBe('')
+      })
+
+      it('returns payload from state', () => {
+        const state1 = getFormState(validState)
+        const state2 = getFormState(null)
+
+        const payload1 = field.getFormDataFromState(state1)
+        const payload2 = field.getFormDataFromState(state2)
+
+        expect(payload1).toEqual(getFormData(validState))
+        expect(payload2).toEqual(getFormData())
+      })
+
+      it('returns value from state', () => {
+        const state1 = getFormState(validState)
+        const state2 = getFormState(null)
+
+        const value1 = field.getFormValueFromState(state1)
+        const value2 = field.getFormValueFromState(state2)
+
+        expect(value1).toBe(validState)
+        expect(value2).toBeUndefined()
+      })
+
+      it('returns context for conditions and form submission', () => {
+        const state1 = getFormState(validState)
+        const state2 = getFormState(null)
+
+        const value1 = field.getContextValueFromState(state1)
+        const value2 = field.getContextValueFromState(state2)
+
+        const { id: id1 } = validState[0]
+        const { id: id2 } = validState[1]
+        const { id: id3 } = validState[2]
+        const { id: id4 } = validState[3]
+
+        expect(value1).toEqual([id1, id2, id3, id4])
+        expect(value2).toBeNull()
+      })
+
+      it('returns state from payload', () => {
+        const payload1 = getFormData(validState)
+        const payload2 = getFormData()
+
+        const value1 = field.getStateFromValidForm(payload1)
+        const value2 = field.getStateFromValidForm(payload2)
+
+        expect(value1).toEqual(getFormState(validState))
+        expect(value2).toEqual(getFormState(null))
+      })
+    })
+
+    describe('View model', () => {
+      it('sets Nunjucks component defaults', () => {
+        const viewModel = field.getViewModel(getFormData('Geospatial'))
+
+        expect(viewModel).toEqual(
+          expect.objectContaining({
+            label: { text: def.title },
+            name: 'myComponent',
+            id: 'myComponent',
+            value: 'Geospatial'
+          })
+        )
+      })
+    })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).toBeEmpty()
+      })
+    })
+  })
+
+  describe('Validation', () => {
+    describe.each([
+      {
+        description: 'Required',
+        component: {
+          title: 'Example geospatial field',
+          name: 'myComponent',
+          type: ComponentType.GeospatialField,
+          options: {
+            required: true
+          }
+        } satisfies GeospatialFieldComponent,
+        assertions: [
+          {
+            input: getFormData([]),
+            output: {
+              value: getFormData([]),
+              errors: [
+                expect.objectContaining({
+                  text: 'Example geospatial field must contain at least 1 items'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData(),
+            output: {
+              value: getFormData(),
+              errors: [
+                expect.objectContaining({
+                  text: 'Select example geospatial field'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData(validSingleState),
+            output: {
+              value: getFormData(validSingleState)
+            }
+          },
+          {
+            input: getFormData(validState),
+            output: {
+              value: getFormData(validState)
+            }
+          }
+        ]
+      },
+      {
+        description: 'Optional',
+        component: {
+          title: 'Example geospatial field',
+          name: 'myComponent',
+          type: ComponentType.GeospatialField,
+          options: {
+            required: false
+          }
+        } satisfies GeospatialFieldComponent,
+        assertions: [
+          {
+            input: getFormData([]),
+            output: {
+              value: getFormData([])
+            }
+          },
+          {
+            input: getFormData(),
+            output: {
+              value: getFormData(),
+              errors: [
+                expect.objectContaining({
+                  text: 'Select example geospatial field'
+                })
+              ]
+            }
+          }
+        ]
+      }
+    ])('$description', ({ component: def, assertions }) => {
+      let collection: ComponentCollection
+
+      beforeEach(() => {
+        collection = new ComponentCollection([def], { model })
+      })
+
+      it.each([...assertions])(
+        'validates custom example',
+        ({ input, output }) => {
+          const result = collection.validate(input)
+          expect(result).toEqual(output)
+        }
+      )
+    })
+
+    it('getErrors formats description errors', () => {
+      const component = {
+        title: 'Example geospatial field',
+        name: 'myComponent',
+        type: ComponentType.GeospatialField,
+        options: {
+          required: true
+        }
+      } satisfies GeospatialFieldComponent
+
+      const collection = new ComponentCollection([component], { model })
+      const invalidSingleState: GeospatialState = [
+        {
+          type: 'Feature',
+          properties: {
+            coordinateGridReference: 'ST 00001',
+            centroidGridReference: 'ST 00001',
+            description: '' // Missing description should trigger error with href to description field and custom text
+          },
+          geometry: {
+            coordinates: [-2.5723699109417737, 53.2380485215034],
+            type: 'Point'
+          },
+          id: 'a'
+        }
+      ]
+
+      const result = collection.validate(getFormData(invalidSingleState))
+      const geospatialField = collection.components.at(0) as GeospatialField
+
+      const errors = geospatialField.getErrors(result.errors)
+      expect(errors).toEqual([
+        expect.objectContaining({
+          name: 'description',
+          href: '#description_0',
+          text: 'Enter description for location 1'
+        })
+      ])
+    })
+  })
+})

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

@@ -0,0 +1,145 @@
+import { type GeospatialFieldComponent } from '@defra/forms-model'
+import { type ArraySchema } from 'joi'
+
+import { type ComponentBase } from '~/src/server/plugins/engine/components/ComponentBase.js'
+import {
+  FormComponent,
+  isGeospatialState
+} from '~/src/server/plugins/engine/components/FormComponent.js'
+import { geospatialSchema } from '~/src/server/plugins/engine/components/helpers/geospatial.js'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
+import {
+  type ErrorMessageTemplateList,
+  type FormPayload,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionError,
+  type FormSubmissionState,
+  type GeospatialState
+} from '~/src/server/plugins/engine/types.js'
+
+export class GeospatialField extends FormComponent {
+  declare options: GeospatialFieldComponent['options']
+  declare formSchema: ArraySchema<GeospatialState>
+  declare stateSchema: ArraySchema<GeospatialState>
+
+  constructor(
+    def: GeospatialFieldComponent,
+    props: ConstructorParameters<typeof ComponentBase>[1]
+  ) {
+    super(def, props)
+
+    const { options } = def
+
+    let formSchema = geospatialSchema.label(this.label).required()
+
+    if (options.required !== false) {
+      formSchema = formSchema.min(1)
+    }
+
+    this.formSchema = formSchema
+    this.stateSchema = formSchema.default(null)
+    this.options = options
+  }
+
+  getFormValueFromState(state: FormSubmissionState) {
+    const { name } = this
+    return this.getFormValue(state[name])
+  }
+
+  getFormValue(value?: FormStateValue | FormState) {
+    return this.isValue(value) ? value : undefined
+  }
+
+  getDisplayStringFromFormValue(features: GeospatialState | undefined): string {
+    if (!features?.length) {
+      return ''
+    }
+
+    const unit = features.length === 1 ? 'location' : 'locations'
+
+    return `Added ${features.length} ${unit}`
+  }
+
+  getDisplayStringFromState(state: FormSubmissionState) {
+    const features = this.getFormValueFromState(state)
+
+    return this.getDisplayStringFromFormValue(features)
+  }
+
+  getContextValueFromFormValue(
+    features: GeospatialState | undefined
+  ): string[] | null {
+    return features?.map(({ id }) => id) ?? null
+  }
+
+  getContextValueFromState(state: FormSubmissionState) {
+    const features = this.getFormValueFromState(state)
+
+    return this.getContextValueFromFormValue(features)
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const viewModel = super.getViewModel(payload, errors)
+    const value =
+      typeof viewModel.value === 'string'
+        ? viewModel.value
+        : JSON.stringify(viewModel.value, null, 2)
+
+    return {
+      ...viewModel,
+      value
+    }
+  }
+
+  getErrors(errors?: FormSubmissionError[]): FormSubmissionError[] | undefined {
+    const fieldErrors = super.getErrors(errors)
+
+    fieldErrors?.forEach((err) => {
+      if (err.name === 'description') {
+        err.href = `#description_${err.path[1]}`
+        err.text = `Enter description for location ${Number(err.path[1]) + 1}`
+      }
+    })
+
+    return fieldErrors
+  }
+
+  getViewErrors(
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
+    return this.getErrors(errors)
+  }
+
+  isValue(value?: FormStateValue | FormState): value is GeospatialState {
+    return isGeospatialState(value)
+  }
+
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    const staticErrors = GeospatialField.getAllPossibleErrors()
+    return {
+      ...staticErrors,
+      advancedSettingsErrors: [...staticErrors.advancedSettingsErrors]
+    }
+  }
+
+  /**
+   * Static version of getAllPossibleErrors that doesn't require a component instance.
+   */
+  static getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'required', template: messageTemplate.selectRequired },
+        {
+          type: 'array.min',
+          template: '{{#title}} must contain at least 1 items'
+        },
+        { type: 'object.invalidjson', template: messageTemplate.format }
+      ],
+      advancedSettingsErrors: []
+    }
+  }
+}

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

@@ -0,0 +1,85 @@
+import { type GeospatialState } from '~/src/server/plugins/engine/types.js'
+
+export const validState: GeospatialState = [
+  {
+    type: 'Feature',
+    properties: {
+      description: 'My farm house',
+      coordinateGridReference: 'ST 00001',
+      centroidGridReference: 'ST 00001'
+    },
+    geometry: {
+      coordinates: [-2.5723699109417737, 53.2380485215034],
+      type: 'Point'
+    },
+    id: 'a'
+  },
+  {
+    type: 'Feature',
+    properties: {
+      description: 'Main gas line',
+      coordinateGridReference: 'ST 00001',
+      centroidGridReference: 'ST 00001'
+    },
+    geometry: {
+      coordinates: [
+        [-2.570496516462896, 53.239162468888566],
+        [-2.5722447488110447, 53.238174174285746]
+      ],
+      type: 'LineString'
+    },
+    id: 'b'
+  },
+  {
+    type: 'Feature',
+    properties: {
+      description: 'My Pony Paddock',
+      coordinateGridReference: 'ST 00001',
+      centroidGridReference: 'ST 00001'
+    },
+    geometry: {
+      coordinates: [
+        [
+          [-2.573552894955583, 53.238229751360706],
+          [-2.5738557065633643, 53.23812342993719],
+          [-2.5737507318720247, 53.23797119653088],
+          [-2.573411582871387, 53.23785037598134],
+          [-2.5727575097991178, 53.23787454011864],
+          [-2.572858447002119, 53.23825391528342],
+          [-2.573552894955583, 53.238229751360706]
+        ]
+      ],
+      type: 'Polygon'
+    },
+    id: 'c'
+  },
+  {
+    type: 'Feature',
+    properties: {
+      description: 'My farm house #2',
+      coordinateGridReference: 'ST 00001',
+      centroidGridReference: 'ST 00001'
+    },
+    geometry: {
+      coordinates: [-2.5724, 53.239],
+      type: 'Point'
+    },
+    id: 'd'
+  }
+]
+
+export const validSingleState: GeospatialState = [
+  {
+    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/components/helpers/components.test.ts

@@ -2,11 +2,13 @@ import {
   ComponentType,
   type DeclarationFieldComponent,
   type EastingNorthingFieldComponent,
+  type GeospatialFieldComponent,
   type LatLongFieldComponent,
   type NationalGridFieldNumberFieldComponent,
   type OsGridRefFieldComponent
 } from '@defra/forms-model'
 
+import { validState } from '~/src/server/plugins/engine/components/helpers/__stubs__/geospatial.js'
 import {
   getAnswer,
   getAnswerMarkdown
@@ -14,6 +16,7 @@ import {
 import {
   DeclarationField,
   EastingNorthingField,
+  GeospatialField,
   LatLongField,
   NationalGridFieldNumberField,
   OsGridRefField
@@ -218,6 +221,47 @@ describe('Location field formatting', () => {
     })
   })
 
+  describe('GeospatialField', () => {
+    let field: GeospatialField
+
+    beforeEach(() => {
+      const def: GeospatialFieldComponent = {
+        type: ComponentType.GeospatialField,
+        name: 'geoField',
+        title: 'Geospatial',
+        options: {}
+      }
+      field = new GeospatialField(def, { model })
+    })
+
+    it('formats for email output as single value', () => {
+      const state = {
+        geoField: validState
+      }
+
+      const answer = getAnswer(field, state, { format: 'email' })
+      expect(answer).toBe('Added 4 locations\n')
+    })
+
+    it('formats for data output', () => {
+      const state = {
+        geoField: validState
+      }
+
+      const answer = getAnswer(field, state, { format: 'data' })
+      expect(answer).toBe('a,b,c,d')
+    })
+
+    it('formats for summary display', () => {
+      const state = {
+        geoField: validState
+      }
+
+      const answer = getAnswer(field, state, { format: 'summary' })
+      expect(answer).toBe('Added 4 locations')
+    })
+  })
+
   describe('DeclarationField', () => {
     let field: DeclarationField
 

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

@@ -36,6 +36,7 @@ export type Field = InstanceType<
   | typeof Components.FileUploadField
   | typeof Components.HiddenField
   | typeof Components.PaymentField
+  | typeof Components.GeospatialField
 >
 
 // Guidance component instances only
@@ -196,6 +197,10 @@ export function createComponent(
     case ComponentType.PaymentField:
       component = new Components.PaymentField(def, options)
       break
+
+    case ComponentType.GeospatialField:
+      component = new Components.GeospatialField(def, options)
+      break
   }
 
   if (typeof component === 'undefined') {
@@ -332,6 +337,11 @@ export function getAnswerMarkdown(
   ) {
     const contextValue = field.getContextValueFromState(state)
     answerEscaped = contextValue ? `${contextValue}\n` : ''
+  } else if (field instanceof Components.GeospatialField) {
+    const features = field.getFormValueFromState(state)
+    const value = field.getDisplayStringFromFormValue(features)
+
+    answerEscaped = value ? `${value}\n` : ''
   }
 
   return answerEscaped