@defra/forms-engine-plugin 0.0.1

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

@@ -0,0 +1,172 @@
+import { ComponentType, type UkAddressFieldComponent } from '@defra/forms-model'
+import { 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 { TextField } from '~/src/server/plugins/engine/components/TextField.js'
+import { type QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import {
+  type FormPayload,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionError,
+  type FormSubmissionState
+} from '~/src/server/plugins/engine/types.js'
+
+export class UkAddressField extends FormComponent {
+  declare options: UkAddressFieldComponent['options']
+  declare formSchema: ObjectSchema<FormPayload>
+  declare stateSchema: ObjectSchema<FormState>
+  declare collection: ComponentCollection
+
+  constructor(
+    def: UkAddressFieldComponent,
+    props: ConstructorParameters<typeof FormComponent>[1]
+  ) {
+    super(def, props)
+
+    const { name, options } = def
+
+    const isRequired = options.required !== false
+    const hideOptional = !!options.optionalText
+    const hideTitle = !!options.hideTitle
+
+    this.collection = new ComponentCollection(
+      [
+        {
+          type: ComponentType.TextField,
+          name: `${name}__addressLine1`,
+          title: 'Address line 1',
+          schema: { max: 100 },
+          options: {
+            autocomplete: 'address-line1',
+            required: isRequired,
+            optionalText: !isRequired && (hideOptional || !hideTitle)
+          }
+        },
+        {
+          type: ComponentType.TextField,
+          name: `${name}__addressLine2`,
+          title: 'Address line 2',
+          schema: { max: 100 },
+          options: {
+            autocomplete: 'address-line2',
+            required: false,
+            optionalText: !isRequired && (hideOptional || !hideTitle)
+          }
+        },
+        {
+          type: ComponentType.TextField,
+          name: `${name}__town`,
+          title: 'Town or city',
+          schema: { max: 100 },
+          options: {
+            autocomplete: 'address-level2',
+            classes: 'govuk-!-width-two-thirds',
+            required: isRequired,
+            optionalText: !isRequired && (hideOptional || !hideTitle)
+          }
+        },
+        {
+          type: ComponentType.TextField,
+          name: `${name}__postcode`,
+          title: 'Postcode',
+          schema: {
+            regex: '^[a-zA-Z]{1,2}\\d[a-zA-Z\\d]?\\s?\\d[a-zA-Z]{2}$'
+          },
+          options: {
+            autocomplete: 'postal-code',
+            classes: 'govuk-input--width-10',
+            required: isRequired,
+            optionalText: !isRequired && (hideOptional || !hideTitle)
+          }
+        }
+      ],
+      { ...props, parent: this }
+    )
+
+    this.options = options
+    this.formSchema = this.collection.formSchema
+    this.stateSchema = this.collection.stateSchema
+  }
+
+  getFormValueFromState(state: FormSubmissionState) {
+    const value = super.getFormValueFromState(state)
+    return this.isState(value) ? value : undefined
+  }
+
+  getDisplayStringFromState(state: FormSubmissionState) {
+    return this.getContextValueFromState(state)?.join(', ') ?? ''
+  }
+
+  getContextValueFromState(state: FormSubmissionState) {
+    const value = this.getFormValueFromState(state)
+
+    if (!value) {
+      return null
+    }
+
+    return Object.values(value).filter(Boolean)
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const { collection, name, options } = this
+
+    const viewModel = super.getViewModel(payload, errors)
+    let { components, fieldset, hint, label } = viewModel
+
+    fieldset ??= {
+      legend: {
+        text: label.text,
+
+        /**
+         * For screen readers, only hide legend visually. This can be overridden
+         * by single component {@link QuestionPageController | `showTitle` handling}
+         */
+        classes: options.hideTitle
+          ? 'govuk-visually-hidden'
+          : 'govuk-fieldset__legend--m'
+      }
+    }
+
+    if (hint) {
+      hint.id ??= `${name}-hint`
+      fieldset.attributes ??= {
+        'aria-describedby': hint.id
+      }
+    }
+
+    components = collection.getViewModel(payload, errors)
+
+    return {
+      ...viewModel,
+      fieldset,
+      components
+    }
+  }
+
+  isState(value?: FormStateValue | FormState): value is UkAddressState {
+    return UkAddressField.isUkAddress(value)
+  }
+
+  static isUkAddress(
+    value?: FormStateValue | FormState
+  ): value is UkAddressState {
+    return (
+      isFormState(value) &&
+      TextField.isText(value.addressLine1) &&
+      TextField.isText(value.town) &&
+      TextField.isText(value.postcode)
+    )
+  }
+}
+
+export interface UkAddressState extends Record<string, string> {
+  addressLine1: string
+  addressLine2: string
+  town: string
+  postcode: string
+}

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

@@ -0,0 +1,248 @@
+import { ComponentType, type YesNoFieldComponent } from '@defra/forms-model'
+
+import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import {
+  getAnswer,
+  type Field
+} from '~/src/server/plugins/engine/components/helpers.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { listYesNoExamples } from '~/test/fixtures/list.js'
+import definition from '~/test/form/definitions/blank.js'
+import { getFormData, getFormState } from '~/test/helpers/component-helpers.js'
+
+describe('YesNoField', () => {
+  let def: YesNoFieldComponent
+  let model: FormModel
+  let collection: ComponentCollection
+  let field: Field
+
+  beforeEach(() => {
+    def = {
+      title: 'Example yes/no',
+      name: 'myComponent',
+      type: ComponentType.YesNoField,
+      options: {}
+    } satisfies YesNoFieldComponent
+
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+
+    collection = new ComponentCollection([def], { model })
+    field = collection.fields[0]
+  })
+
+  describe('Schema', () => {
+    it('uses component title as label', () => {
+      const { formSchema } = collection
+      const { keys } = formSchema.describe()
+
+      expect(keys).toHaveProperty(
+        'myComponent',
+        expect.objectContaining({
+          flags: expect.objectContaining({
+            label: 'Example yes/no'
+          })
+        })
+      )
+    })
+
+    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 { formSchema } = collectionOptional
+      const { keys } = formSchema.describe()
+
+      expect(keys).toHaveProperty(
+        'myComponent',
+        expect.objectContaining({
+          flags: expect.objectContaining({
+            presence: 'optional'
+          })
+        })
+      )
+
+      const result = collectionOptional.validate(getFormData())
+      expect(result.errors).toBeUndefined()
+    })
+
+    it('is configured with radio items', () => {
+      const { formSchema } = collection
+      const { keys } = formSchema.describe()
+
+      expect(keys).toHaveProperty(
+        'myComponent',
+        expect.objectContaining({
+          allow: [true, false],
+          type: 'boolean'
+        })
+      )
+    })
+
+    it('accepts valid values', () => {
+      const result1 = collection.validate(getFormData('true'))
+      const result2 = collection.validate(getFormData('false'))
+
+      expect(result1.errors).toBeUndefined()
+      expect(result2.errors).toBeUndefined()
+    })
+
+    it('adds errors for empty value', () => {
+      const result = collection.validate(getFormData())
+
+      expect(result.errors).toEqual([
+        expect.objectContaining({
+          text: 'Select example yes/no'
+        })
+      ])
+    })
+
+    it('adds errors for invalid values', () => {
+      const result1 = collection.validate(getFormData('invalid'))
+      const result2 = collection.validate(getFormData(['true']))
+      const result3 = collection.validate(getFormData(['true', 'false']))
+
+      expect(result1.errors).toBeTruthy()
+      expect(result2.errors).toBeTruthy()
+      expect(result3.errors).toBeTruthy()
+    })
+  })
+
+  describe('State', () => {
+    it('returns text from state', () => {
+      const state1 = getFormState(true)
+      const state2 = getFormState(false)
+      const state3 = getFormState(null)
+
+      const answer1 = getAnswer(field, state1)
+      const answer2 = getAnswer(field, state2)
+      const answer3 = getAnswer(field, state3)
+
+      expect(answer1).toBe('Yes')
+      expect(answer2).toBe('No')
+      expect(answer3).toBe('')
+    })
+
+    it('returns payload from state', () => {
+      const state1 = getFormState(true)
+      const state2 = getFormState(false)
+      const state3 = getFormState(null)
+
+      const payload1 = field.getFormDataFromState(state1)
+      const payload2 = field.getFormDataFromState(state2)
+      const payload3 = field.getFormDataFromState(state3)
+
+      expect(payload1).toEqual(getFormData(true))
+      expect(payload2).toEqual(getFormData(false))
+      expect(payload3).toEqual(getFormData())
+    })
+
+    it('returns value from state', () => {
+      const state1 = getFormState(true)
+      const state2 = getFormState(false)
+      const state3 = getFormState(null)
+
+      const value1 = field.getFormValueFromState(state1)
+      const value2 = field.getFormValueFromState(state2)
+      const value3 = field.getFormValueFromState(state3)
+
+      expect(value1).toBe(true)
+      expect(value2).toBe(false)
+      expect(value3).toBeUndefined()
+    })
+
+    it('returns context for conditions and form submission', () => {
+      const state1 = getFormState(true)
+      const state2 = getFormState(false)
+      const state3 = getFormState(null)
+
+      const value1 = field.getContextValueFromState(state1)
+      const value2 = field.getContextValueFromState(state2)
+      const value3 = field.getContextValueFromState(state3)
+
+      expect(value1).toBe(true)
+      expect(value2).toBe(false)
+      expect(value3).toBeNull()
+    })
+
+    it('returns state from payload', () => {
+      const payload1 = getFormData(true)
+      const payload2 = getFormData(false)
+      const payload3 = getFormData()
+
+      const value1 = field.getStateFromValidForm(payload1)
+      const value2 = field.getStateFromValidForm(payload2)
+      const value3 = field.getStateFromValidForm(payload3)
+
+      expect(value1).toEqual(getFormState(true))
+      expect(value2).toEqual(getFormState(false))
+      expect(value3).toEqual(getFormState(null))
+    })
+  })
+
+  describe('View model', () => {
+    const items = listYesNoExamples
+
+    it('sets Nunjucks component defaults', () => {
+      const item = items[0]
+
+      const viewModel = field.getViewModel(getFormData(item.value))
+
+      expect(viewModel).toEqual(
+        expect.objectContaining({
+          label: { text: def.title },
+          name: 'myComponent',
+          id: 'myComponent',
+          value: item.value
+        })
+      )
+    })
+
+    it.each([...items])('sets Nunjucks component radio items', (item) => {
+      const viewModel = field.getViewModel(getFormData(item.value))
+
+      expect(viewModel.items?.[0]).not.toMatchObject({
+        value: '' // First item is never empty
+      })
+
+      expect(viewModel.items).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            text: item.text,
+            value: item.value,
+            checked: true
+          })
+        ])
+      )
+    })
+  })
+})

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

@@ -0,0 +1,31 @@
+import { type YesNoFieldComponent } from '@defra/forms-model'
+
+import { SelectionControlField } from '~/src/server/plugins/engine/components/SelectionControlField.js'
+import { addClassOptionIfNone } from '~/src/server/plugins/engine/components/helpers.js'
+
+/**
+ * @description
+ * YesNoField is a radiosField with predefined values.
+ */
+export class YesNoField extends SelectionControlField {
+  declare options: YesNoFieldComponent['options']
+
+  constructor(
+    def: YesNoFieldComponent,
+    props: ConstructorParameters<typeof SelectionControlField>[1]
+  ) {
+    super({ ...def, list: '__yesNo' }, props)
+
+    const { options } = def
+    let { formSchema } = this
+
+    addClassOptionIfNone(options, 'govuk-radios--inline')
+
+    if (options.required === false) {
+      formSchema = formSchema.optional()
+    }
+
+    this.formSchema = formSchema
+    this.options = options
+  }
+}

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

@@ -0,0 +1 @@
+export const optionalText = ' (optional)'