@defra/forms-engine-plugin 4.0.5 → 4.0.7

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

@@ -0,0 +1,213 @@
+import { ComponentType, type LatLongFieldComponent } from '@defra/forms-model'
+import { type LanguageMessages, type ObjectSchema } from 'joi'
+
+import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import {
+  FormComponent,
+  isFormState
+} from '~/src/server/plugins/engine/components/FormComponent.js'
+import {
+  createLocationFieldValidator,
+  getLocationFieldViewModel
+} from '~/src/server/plugins/engine/components/LocationFieldHelpers.js'
+import { NumberField } from '~/src/server/plugins/engine/components/NumberField.js'
+import { type LatLongState } from '~/src/server/plugins/engine/components/types.js'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
+import {
+  type ErrorMessageTemplateList,
+  type FormPayload,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionError,
+  type FormSubmissionState
+} from '~/src/server/plugins/engine/types.js'
+import { convertToLanguageMessages } from '~/src/server/utils/type-utils.js'
+
+export class LatLongField extends FormComponent {
+  declare options: LatLongFieldComponent['options']
+  declare formSchema: ObjectSchema<FormPayload>
+  declare stateSchema: ObjectSchema<FormState>
+  declare collection: ComponentCollection
+
+  constructor(
+    def: LatLongFieldComponent,
+    props: ConstructorParameters<typeof FormComponent>[1]
+  ) {
+    super(def, props)
+
+    const { name, options, schema } = def
+
+    const isRequired = options.required !== false
+
+    // Read schema values from def.schema with fallback defaults
+    const latitudeMin = schema?.latitude?.min ?? 49
+    const latitudeMax = schema?.latitude?.max ?? 60
+    const longitudeMin = schema?.longitude?.min ?? -9
+    const longitudeMax = schema?.longitude?.max ?? 2
+
+    const customValidationMessages: LanguageMessages =
+      convertToLanguageMessages({
+        'any.required': messageTemplate.objectMissing,
+        'number.base': messageTemplate.objectMissing,
+        'number.precision':
+          '{{#label}} must have no more than 7 decimal places',
+        'number.unsafe': '{{#label}} must be a valid number'
+      })
+
+    const latitudeMessages: LanguageMessages = convertToLanguageMessages({
+      ...customValidationMessages,
+      'number.base': `Enter a valid latitude for ${this.title} like 51.519450`,
+      'number.min': `Latitude for ${this.title} must be between ${latitudeMin} and ${latitudeMax}`,
+      'number.max': `Latitude for ${this.title} must be between ${latitudeMin} and ${latitudeMax}`
+    })
+
+    const longitudeMessages: LanguageMessages = convertToLanguageMessages({
+      ...customValidationMessages,
+      'number.base': `Enter a valid longitude for ${this.title} like -0.127758`,
+      'number.min': `Longitude for ${this.title} must be between ${longitudeMin} and ${longitudeMax}`,
+      'number.max': `Longitude for ${this.title} must be between ${longitudeMin} and ${longitudeMax}`
+    })
+
+    this.collection = new ComponentCollection(
+      [
+        {
+          type: ComponentType.NumberField,
+          name: `${name}__latitude`,
+          title: 'Latitude',
+          schema: { min: latitudeMin, max: latitudeMax, precision: 7 },
+          options: {
+            required: isRequired,
+            optionalText: true,
+            classes: 'govuk-input--width-10',
+            suffix: '°',
+            customValidationMessages: latitudeMessages
+          }
+        },
+        {
+          type: ComponentType.NumberField,
+          name: `${name}__longitude`,
+          title: 'Longitude',
+          schema: { min: longitudeMin, max: longitudeMax, precision: 7 },
+          options: {
+            required: isRequired,
+            optionalText: true,
+            classes: 'govuk-input--width-10',
+            suffix: '°',
+            customValidationMessages: longitudeMessages
+          }
+        }
+      ],
+      { ...props, parent: this },
+      {
+        custom: getValidatorLatLong(this),
+        peers: [`${name}__latitude`, `${name}__longitude`]
+      }
+    )
+
+    this.options = options
+    this.formSchema = this.collection.formSchema
+    this.stateSchema = this.collection.stateSchema
+  }
+
+  getFormValueFromState(state: FormSubmissionState) {
+    const value = super.getFormValueFromState(state)
+    return LatLongField.isLatLong(value) ? value : undefined
+  }
+
+  getDisplayStringFromFormValue(value: LatLongState | undefined): string {
+    if (!value) {
+      return ''
+    }
+
+    // CYA page format: <<latvalue, langvalue>>
+    return `${value.latitude}, ${value.longitude}`
+  }
+
+  getDisplayStringFromState(state: FormSubmissionState) {
+    const value = this.getFormValueFromState(state)
+
+    return this.getDisplayStringFromFormValue(value)
+  }
+
+  getContextValueFromFormValue(value: LatLongState | undefined): string | null {
+    if (!value) {
+      return null
+    }
+
+    // Output format: Lat: <<entry>>\nLong: <<entry>>
+    return `Lat: ${value.latitude}\nLong: ${value.longitude}`
+  }
+
+  getContextValueFromState(state: FormSubmissionState) {
+    const value = this.getFormValueFromState(state)
+
+    return this.getContextValueFromFormValue(value)
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const viewModel = super.getViewModel(payload, errors)
+    return getLocationFieldViewModel(this, viewModel, payload, errors)
+  }
+
+  isState(value?: FormStateValue | FormState) {
+    return LatLongField.isLatLong(value)
+  }
+
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return LatLongField.getAllPossibleErrors()
+  }
+
+  /**
+   * Static version of getAllPossibleErrors that doesn't require a component instance.
+   */
+  static getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'required', template: messageTemplate.required },
+        {
+          type: 'latitudeFormat',
+          template:
+            'Enter a valid latitude for [short description] like 51.519450'
+        },
+        {
+          type: 'longitudeFormat',
+          template:
+            'Enter a valid longitude for [short description] like -0.127758'
+        }
+      ],
+      advancedSettingsErrors: [
+        {
+          type: 'latitudeMin',
+          template: 'Latitude for [short description] must be between 49 and 60'
+        },
+        {
+          type: 'latitudeMax',
+          template: 'Latitude for [short description] must be between 49 and 60'
+        },
+        {
+          type: 'longitudeMin',
+          template: 'Longitude for [short description] must be between -9 and 2'
+        },
+        {
+          type: 'longitudeMax',
+          template: 'Longitude for [short description] must be between -9 and 2'
+        }
+      ]
+    }
+  }
+
+  static isLatLong(value?: FormStateValue | FormState): value is LatLongState {
+    return (
+      isFormState(value) &&
+      NumberField.isNumber(value.latitude) &&
+      NumberField.isNumber(value.longitude)
+    )
+  }
+}
+
+export function getValidatorLatLong(component: LatLongField) {
+  return createLocationFieldValidator(component)
+}

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

@@ -0,0 +1,253 @@
+import { ComponentType } from '@defra/forms-model'
+import type joi from 'joi'
+import { type LanguageMessages } from 'joi'
+
+import { LocationFieldBase } from '~/src/server/plugins/engine/components/LocationFieldBase.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import definition from '~/test/form/definitions/blank.js'
+import { getFormData } from '~/test/helpers/component-helpers.js'
+
+class TestLocationField extends LocationFieldBase {
+  protected getValidationConfig() {
+    return {
+      pattern: /^TEST\d{4}$/i,
+      patternErrorMessage: 'Enter a valid test code like TEST1234',
+      additionalMessages: {
+        'string.custom': 'This is a custom error from additional messages'
+      } as LanguageMessages,
+      customValidation: (value: string, helpers: joi.CustomHelpers) => {
+        if (value === 'FAIL0000') {
+          return helpers.error('string.custom')
+        }
+        return value
+      }
+    }
+  }
+
+  protected getErrorTemplates() {
+    return [
+      {
+        type: 'pattern',
+        template:
+          'Enter a valid test code for [short description] like TEST1234'
+      },
+      {
+        type: 'custom',
+        template: 'This is a custom error template'
+      }
+    ]
+  }
+}
+
+describe('LocationFieldBase', () => {
+  let model: FormModel
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+  })
+
+  describe('customValidationMessage with additionalMessages', () => {
+    it('should merge custom validation message with additional message keys', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {
+          customValidationMessage: 'This is a unified custom error'
+        },
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+
+      const result2 = field.formSchema.validate('INVALID')
+      const result3 = field.formSchema.validate('FAIL0000')
+
+      expect(result2.error?.message).toBe('This is a unified custom error')
+      expect(result3.error?.message).toBe('This is a unified custom error')
+    })
+  })
+
+  describe('getViewModel with instructionText', () => {
+    it('should include parsed markdown instruction text', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {
+          instructionText: 'This is **bold** text'
+        },
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+      const viewModel = field.getViewModel(getFormData('TEST1234'))
+
+      const instructionText =
+        'instructionText' in viewModel ? viewModel.instructionText : undefined
+      expect(instructionText).toBeTruthy()
+      expect(instructionText).toContain('bold')
+    })
+
+    it('should not include instructionText when not provided', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {},
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+      const viewModel = field.getViewModel(getFormData('TEST1234'))
+
+      expect(
+        'instructionText' in viewModel ? viewModel.instructionText : undefined
+      ).toBeUndefined()
+    })
+  })
+
+  describe('getAllPossibleErrors', () => {
+    it('should return base errors with custom error templates', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {},
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+      const errors = field.getAllPossibleErrors()
+
+      expect(errors.baseErrors).toHaveLength(3)
+      expect(errors.baseErrors).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ type: 'required' }),
+          expect.objectContaining({ type: 'pattern' }),
+          expect.objectContaining({ type: 'custom' })
+        ])
+      )
+      expect(errors.advancedSettingsErrors).toEqual([])
+    })
+  })
+
+  describe('isValue and getFormValue', () => {
+    it('should correctly identify string values', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {},
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+
+      expect(field.isValue('TEST1234')).toBe(true)
+      expect(field.isValue('')).toBe(false)
+      expect(field.isValue(null)).toBe(false)
+      expect(field.isValue(undefined)).toBe(false)
+      expect(field.isValue(123)).toBe(false)
+      expect(field.isValue({ test: 'value' })).toBe(false)
+    })
+
+    it('should return value when it is a non-empty string', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {},
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+
+      expect(field.getFormValue('TEST1234')).toBe('TEST1234')
+      expect(field.getFormValue('')).toBeUndefined()
+      expect(field.getFormValue(null)).toBeUndefined()
+      expect(field.getFormValue(undefined)).toBeUndefined()
+    })
+
+    it('should get value from state', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {},
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+
+      const state1 = { myComponent: 'TEST1234' }
+      const state2 = { myComponent: null }
+      const state3 = { myComponent: '' }
+
+      expect(field.getFormValueFromState(state1)).toBe('TEST1234')
+      expect(field.getFormValueFromState(state2)).toBeUndefined()
+      expect(field.getFormValueFromState(state3)).toBeUndefined()
+    })
+  })
+
+  describe('optional field validation', () => {
+    it('should allow empty values when required is false', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {
+          required: false
+        },
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+      const result = field.formSchema.validate('')
+
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('')
+    })
+
+    it('should validate pattern even for optional fields when value is provided', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {
+          required: false
+        },
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+      const result = field.formSchema.validate('INVALID')
+
+      expect(result.error).toBeDefined()
+    })
+  })
+
+  describe('customValidationMessages', () => {
+    it('should use custom validation messages when provided', () => {
+      const def = {
+        title: 'Test location field',
+        name: 'myComponent',
+        type: ComponentType.TextField,
+        options: {
+          customValidationMessages: {
+            'string.pattern.base': 'Custom pattern error message',
+            'string.custom': 'Custom error message'
+          }
+        },
+        schema: {}
+      } as ConstructorParameters<typeof TestLocationField>[0]
+
+      const field = new TestLocationField(def, { model })
+      const result = field.formSchema.validate('INVALID')
+
+      expect(result.error?.message).toBe('Custom pattern error message')
+    })
+  })
+})

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

@@ -0,0 +1,152 @@
+import { type FormComponentsDef } from '@defra/forms-model'
+import joi, { type LanguageMessages, type StringSchema } from 'joi'
+
+import {
+  FormComponent,
+  isFormValue
+} from '~/src/server/plugins/engine/components/FormComponent.js'
+import { addClassOptionIfNone } from '~/src/server/plugins/engine/components/helpers/index.js'
+import { markdown } from '~/src/server/plugins/engine/components/markdownParser.js'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
+import {
+  type ErrorMessageTemplateList,
+  type FormPayload,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionError,
+  type FormSubmissionState
+} from '~/src/server/plugins/engine/types.js'
+
+interface LocationFieldOptions {
+  instructionText?: string
+  required?: boolean
+  customValidationMessage?: string
+  customValidationMessages?: LanguageMessages
+  classes?: string
+}
+
+interface ValidationConfig {
+  pattern: RegExp
+  patternErrorMessage: string
+  customValidation?: (
+    value: string,
+    helpers: joi.CustomHelpers
+  ) => string | joi.ErrorReport
+  additionalMessages?: LanguageMessages
+}
+
+/**
+ * Abstract base class for location-based field components
+ */
+export abstract class LocationFieldBase extends FormComponent {
+  declare options: LocationFieldOptions
+  declare formSchema: StringSchema
+  declare stateSchema: StringSchema
+  instructionText?: string
+
+  protected abstract getValidationConfig(): ValidationConfig
+  protected abstract getErrorTemplates(): {
+    type: string
+    template: string
+  }[]
+
+  constructor(
+    def: FormComponentsDef,
+    props: ConstructorParameters<typeof FormComponent>[1]
+  ) {
+    super(def, props)
+
+    const { options } = def
+    const locationOptions = options as LocationFieldOptions
+    this.instructionText = locationOptions.instructionText
+
+    addClassOptionIfNone(locationOptions, 'govuk-input--width-10')
+
+    const config = this.getValidationConfig()
+
+    let formSchema = joi
+      .string()
+      .trim()
+      .label(this.label)
+      .required()
+      .pattern(config.pattern)
+      .messages({
+        'string.pattern.base': config.patternErrorMessage,
+        ...config.additionalMessages
+      })
+
+    if (config.customValidation) {
+      formSchema = formSchema.custom(config.customValidation)
+    }
+
+    if (locationOptions.required === false) {
+      formSchema = formSchema.allow('')
+    }
+
+    if (locationOptions.customValidationMessage) {
+      const message = locationOptions.customValidationMessage
+      const messageKeys = [
+        'any.required',
+        'string.empty',
+        'string.pattern.base'
+      ]
+
+      if (config.additionalMessages) {
+        messageKeys.push(...Object.keys(config.additionalMessages))
+      }
+
+      const messages = messageKeys.reduce<LanguageMessages>((acc, key) => {
+        acc[key] = message
+        return acc
+      }, {})
+
+      formSchema = formSchema.messages(messages)
+    } else if (locationOptions.customValidationMessages) {
+      formSchema = formSchema.messages(locationOptions.customValidationMessages)
+    }
+
+    this.formSchema = formSchema.default('')
+    this.stateSchema = formSchema.default(null).allow(null)
+    this.options = locationOptions
+  }
+
+  getFormValueFromState(state: FormSubmissionState) {
+    const { name } = this
+    return this.getFormValue(state[name])
+  }
+
+  getFormValue(value?: FormStateValue | FormState) {
+    return this.isValue(value) ? value : undefined
+  }
+
+  isValue(value?: FormStateValue | FormState): value is string {
+    return LocationFieldBase.isText(value)
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const viewModel = super.getViewModel(payload, errors)
+
+    if (this.instructionText) {
+      return {
+        ...viewModel,
+        instructionText: markdown.parse(this.instructionText, { async: false })
+      }
+    }
+
+    return viewModel
+  }
+
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'required', template: messageTemplate.required },
+        ...this.getErrorTemplates()
+      ],
+      advancedSettingsErrors: []
+    }
+  }
+
+  static isText(value?: FormStateValue | FormState): value is string {
+    return isFormValue(value) && typeof value === 'string'
+  }
+}