@defra/forms-engine-plugin 4.0.5 → 4.0.7

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

@@ -0,0 +1,338 @@
+import { ComponentType, type LatLongFieldComponent } from '@defra/forms-model'
+
+import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import { type LatLongField } from '~/src/server/plugins/engine/components/LatLongField.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import definition from '~/test/form/definitions/blank.js'
+
+describe('LocationFieldHelpers', () => {
+  let model: FormModel
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+  })
+
+  describe('getLocationFieldViewModel', () => {
+    it('should return view model with fieldset', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {},
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+      const field = collection.fields[0] as LatLongField
+
+      const payload = {
+        myComponent__latitude: 51.5,
+        myComponent__longitude: -0.1
+      }
+
+      const viewModel = field.getViewModel(payload)
+
+      expect(viewModel.fieldset).toEqual({
+        legend: {
+          text: def.title,
+          classes: 'govuk-fieldset__legend--m'
+        }
+      })
+
+      expect(viewModel.items).toHaveLength(2)
+    })
+
+    it('should include instruction text in view model when provided', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {
+          instructionText: 'Enter coordinates in decimal format'
+        },
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+      const field = collection.fields[0] as LatLongField
+
+      const payload = {
+        myComponent__latitude: 51.5,
+        myComponent__longitude: -0.1
+      }
+
+      const viewModel = field.getViewModel(payload)
+
+      const instructionText =
+        'instructionText' in viewModel ? viewModel.instructionText : undefined
+      expect(instructionText).toBeTruthy()
+      expect(instructionText).toContain('decimal format')
+    })
+
+    it('should add error classes to items when component has errors', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {},
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+      const field = collection.fields[0] as LatLongField
+
+      const payload = {
+        myComponent__latitude: '',
+        myComponent__longitude: ''
+      }
+
+      const errors = [
+        {
+          name: 'myComponent',
+          text: 'Error message',
+          path: ['myComponent'],
+          href: '#myComponent'
+        }
+      ]
+
+      const viewModel = field.getViewModel(payload, errors)
+
+      expect(viewModel.items[0]).toEqual(
+        expect.objectContaining({
+          classes: expect.stringContaining('govuk-input--error')
+        })
+      )
+
+      expect(viewModel.items[1]).toEqual(
+        expect.objectContaining({
+          classes: expect.stringContaining('govuk-input--error')
+        })
+      )
+    })
+
+    it('should add error classes to items when subfield has errors', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {},
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+      const field = collection.fields[0] as LatLongField
+
+      const payload = {
+        myComponent__latitude: 'invalid',
+        myComponent__longitude: '-0.1'
+      }
+
+      const errors = [
+        {
+          name: 'myComponent__latitude',
+          text: 'Invalid latitude',
+          path: ['myComponent__latitude'],
+          href: '#myComponent__latitude'
+        }
+      ]
+
+      const viewModel = field.getViewModel(payload, errors)
+
+      expect(viewModel.items[0]).toEqual(
+        expect.objectContaining({
+          classes: expect.stringContaining('govuk-input--error')
+        })
+      )
+    })
+
+    it('should handle labels correctly in view model items', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {},
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+      const field = collection.fields[0] as LatLongField
+
+      const payload = {
+        myComponent__latitude: '51.5',
+        myComponent__longitude: '-0.1'
+      }
+
+      const viewModel = field.getViewModel(payload)
+
+      const label = viewModel.items[0].label
+      expect(label).toBeDefined()
+      expect(label?.text).toBe('Latitude')
+
+      const labelString =
+        label && 'toString' in label && typeof label.toString === 'function'
+          ? (label as { toString: () => string }).toString()
+          : ''
+      expect(labelString).toBe('Latitude')
+    })
+
+    it('should use existing fieldset if provided', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {},
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+      const field = collection.fields[0] as LatLongField
+
+      const payload = {
+        myComponent__latitude: 51.5,
+        myComponent__longitude: -0.1
+      }
+
+      const viewModel = field.getViewModel(payload)
+
+      expect(viewModel.fieldset).toBeDefined()
+    })
+  })
+
+  describe('createLocationFieldValidator', () => {
+    it('should return error when required field is empty', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {},
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+
+      const payload = {
+        myComponent__latitude: '',
+        myComponent__longitude: ''
+      }
+
+      const result = collection.validate(payload)
+
+      expect(result.errors).toBeTruthy()
+      expect(result.errors?.length).toBeGreaterThan(0)
+    })
+
+    it('should return error when required field has invalid state', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {
+          required: true
+        },
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+
+      const payload = {
+        myComponent__latitude: 'not_a_number',
+        myComponent__longitude: 'also_not_a_number'
+      }
+
+      const result = collection.validate(payload)
+
+      expect(result.errors).toBeTruthy()
+    })
+
+    it('should not return error when optional field is empty', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {
+          required: false
+        },
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+
+      const payload = {
+        myComponent__latitude: '',
+        myComponent__longitude: ''
+      }
+
+      const result = collection.validate(payload)
+
+      expect(result.errors).toBeUndefined()
+    })
+
+    it('should return error when required field is partially filled', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {},
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+
+      const payload = {
+        myComponent__latitude: '51.5',
+        myComponent__longitude: ''
+      }
+
+      const result = collection.validate(payload)
+
+      expect(result.errors).toBeTruthy()
+    })
+
+    it('should not return error when all required fields are filled', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {},
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+
+      const payload = {
+        myComponent__latitude: '51.5',
+        myComponent__longitude: '-0.1'
+      }
+
+      const result = collection.validate(payload)
+
+      expect(result.errors).toBeUndefined()
+    })
+
+    it('should validate optional fields correctly when partially filled', () => {
+      const def: LatLongFieldComponent = {
+        title: 'Example lat long',
+        name: 'myComponent',
+        type: ComponentType.LatLongField,
+        options: {
+          required: false
+        },
+        schema: {}
+      }
+
+      const collection = new ComponentCollection([def], { model })
+
+      const payload = {
+        myComponent__latitude: '51.5',
+        myComponent__longitude: ''
+      }
+
+      const result = collection.validate(payload)
+
+      expect(result.errors).toBeTruthy()
+      expect(result.errors?.length).toBeGreaterThan(0)
+    })
+  })
+})

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

@@ -0,0 +1,123 @@
+import { type Context, type CustomValidator } from 'joi'
+
+import { type EastingNorthingField } from '~/src/server/plugins/engine/components/EastingNorthingField.js'
+import { isFormValue } from '~/src/server/plugins/engine/components/FormComponent.js'
+import { type LatLongField } from '~/src/server/plugins/engine/components/LatLongField.js'
+import { markdown } from '~/src/server/plugins/engine/components/markdownParser.js'
+import {
+  type DateInputItem,
+  type Label,
+  type ViewModel
+} from '~/src/server/plugins/engine/components/types.js'
+import {
+  type FormPayload,
+  type FormSubmissionError,
+  type FormValue
+} from '~/src/server/plugins/engine/types.js'
+
+export type LocationField =
+  | InstanceType<typeof EastingNorthingField>
+  | InstanceType<typeof LatLongField>
+
+export function getLocationFieldViewModel(
+  component: LocationField,
+  viewModel: ViewModel & {
+    label: Label
+    id: string
+    name: string
+    value: FormValue
+  },
+  payload: FormPayload,
+  errors?: FormSubmissionError[]
+) {
+  const { collection, name } = component
+  const { fieldset: existingFieldset, label } = viewModel
+
+  // Check for component errors only
+  const hasError = errors?.some((error) => error.name === name)
+
+  // Use the component collection to generate the subitems
+  const items: DateInputItem[] = collection
+    .getViewModel(payload, errors)
+    .map(({ model }): DateInputItem => {
+      let { label, type, value, classes, prefix, suffix, errorMessage } = model
+
+      if (label) {
+        label.toString = () => label.text // Use string labels
+      }
+
+      if (hasError || errorMessage) {
+        classes = `${classes ?? ''} govuk-input--error`.trim()
+      }
+
+      // Allow any `toString()`-able value so non-numeric
+      // values are shown alongside their error messages
+      if (!isFormValue(value)) {
+        value = undefined
+      }
+
+      return {
+        label,
+        id: model.id,
+        name: model.name,
+        type,
+        value,
+        classes,
+        prefix,
+        suffix
+      }
+    })
+
+  const fieldset = existingFieldset ?? {
+    legend: {
+      text: label.text,
+      classes: 'govuk-fieldset__legend--m'
+    }
+  }
+
+  const result = {
+    ...viewModel,
+    fieldset,
+    items
+  }
+
+  if (component.options.instructionText) {
+    return {
+      ...result,
+      instructionText: markdown.parse(component.options.instructionText, {
+        async: false
+      })
+    }
+  }
+
+  return result
+}
+
+/**
+ * Validator factory for location-based fields.
+ * This creates a validator that ensures all required fields are present.
+ */
+export function createLocationFieldValidator(
+  component: LocationField
+): CustomValidator {
+  return (payload: FormPayload, helpers) => {
+    const { collection, name, options } = component
+
+    const values = component.getFormValueFromState(
+      component.getStateFromValidForm(payload)
+    )
+
+    const context: Context = {
+      missing: collection.keys,
+      key: name
+    }
+
+    if (!component.isState(values)) {
+      return options.required !== false
+        ? helpers.error('object.required', context)
+        : payload
+    }
+
+    return payload
+  }
+}