@defra/forms-engine-plugin 0.0.1

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

@@ -0,0 +1,558 @@
+import {
+  ComponentType,
+  type MultilineTextFieldComponent
+} from '@defra/forms-model'
+
+import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import { MultilineTextField } from '~/src/server/plugins/engine/components/MultilineTextField.js'
+import {
+  getAnswer,
+  type Field
+} from '~/src/server/plugins/engine/components/helpers.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import definition from '~/test/form/definitions/blank.js'
+import { getFormData, getFormState } from '~/test/helpers/component-helpers.js'
+
+describe('MultilineTextField', () => {
+  let model: FormModel
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+  })
+
+  describe('Defaults', () => {
+    let def: MultilineTextFieldComponent
+    let collection: ComponentCollection
+    let field: Field
+
+    beforeEach(() => {
+      def = {
+        title: 'Example textarea',
+        name: 'myComponent',
+        type: ComponentType.MultilineTextField,
+        options: {},
+        schema: {}
+      } satisfies MultilineTextFieldComponent
+
+      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 textarea'
+            })
+          })
+        )
+      })
+
+      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({ allow: [''] })
+        )
+
+        const result = collectionOptional.validate(getFormData(''))
+        expect(result.errors).toBeUndefined()
+      })
+
+      it('accepts valid values', () => {
+        const result1 = collection.validate(getFormData('Text'))
+        const result2 = collection.validate(getFormData('Textarea'))
+
+        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: 'Enter example textarea'
+          })
+        ])
+      })
+
+      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 state', () => {
+        const state1 = getFormState('Textarea')
+        const state2 = getFormState(null)
+
+        const answer1 = getAnswer(field, state1)
+        const answer2 = getAnswer(field, state2)
+
+        expect(answer1).toBe('Textarea')
+        expect(answer2).toBe('')
+      })
+
+      it('returns payload from state', () => {
+        const state1 = getFormState('Textarea')
+        const state2 = getFormState(null)
+
+        const payload1 = field.getFormDataFromState(state1)
+        const payload2 = field.getFormDataFromState(state2)
+
+        expect(payload1).toEqual(getFormData('Textarea'))
+        expect(payload2).toEqual(getFormData())
+      })
+
+      it('returns value from state', () => {
+        const state1 = getFormState('Textarea')
+        const state2 = getFormState(null)
+
+        const value1 = field.getFormValueFromState(state1)
+        const value2 = field.getFormValueFromState(state2)
+
+        expect(value1).toBe('Textarea')
+        expect(value2).toBeUndefined()
+      })
+
+      it('returns context for conditions and form submission', () => {
+        const state1 = getFormState('Textarea')
+        const state2 = getFormState(null)
+
+        const value1 = field.getContextValueFromState(state1)
+        const value2 = field.getContextValueFromState(state2)
+
+        expect(value1).toBe('Textarea')
+        expect(value2).toBeNull()
+      })
+
+      it('returns state from payload', () => {
+        const payload1 = getFormData('Textarea')
+        const payload2 = getFormData()
+
+        const value1 = field.getStateFromValidForm(payload1)
+        const value2 = field.getStateFromValidForm(payload2)
+
+        expect(value1).toEqual(getFormState('Textarea'))
+        expect(value2).toEqual(getFormState(null))
+      })
+    })
+
+    describe('View model', () => {
+      it('sets Nunjucks component defaults', () => {
+        const viewModel = field.getViewModel(getFormData('Textarea'))
+
+        expect(viewModel).toEqual(
+          expect.objectContaining({
+            label: { text: def.title },
+            name: 'myComponent',
+            id: 'myComponent',
+            value: 'Textarea'
+          })
+        )
+      })
+
+      it('sets Nunjucks component isCharacterOrWordCount: true', () => {
+        const componentCustom1 = new MultilineTextField(
+          { ...def, options: { maxWords: 10 } },
+          { model }
+        )
+
+        const componentCustom2 = new MultilineTextField(
+          { ...def, schema: { max: 10 } },
+          { model }
+        )
+
+        const viewModel = field.getViewModel(getFormData('Textarea'))
+
+        const viewModel1 = componentCustom1.getViewModel(
+          getFormData('Textarea custom #1')
+        )
+
+        const viewModel2 = componentCustom2.getViewModel(
+          getFormData('Textarea custom #2')
+        )
+
+        expect(viewModel).toEqual(
+          expect.objectContaining({ isCharacterOrWordCount: false })
+        )
+
+        expect(viewModel1).toEqual(
+          expect.objectContaining({ isCharacterOrWordCount: true })
+        )
+
+        expect(viewModel2).toEqual(
+          expect.objectContaining({ isCharacterOrWordCount: true })
+        )
+      })
+    })
+  })
+
+  describe('Validation', () => {
+    describe.each([
+      {
+        description: 'Trim empty spaces',
+        component: {
+          title: 'Example textarea',
+          name: 'myComponent',
+          type: ComponentType.MultilineTextField,
+          options: {},
+          schema: {}
+        } satisfies MultilineTextFieldComponent,
+        assertions: [
+          {
+            input: getFormData('  Leading spaces'),
+            output: { value: getFormData('Leading spaces') }
+          },
+          {
+            input: getFormData('Trailing spaces  '),
+            output: { value: getFormData('Trailing spaces') }
+          },
+          {
+            input: getFormData('  Mixed spaces and new lines \n\n'),
+            output: { value: getFormData('Mixed spaces and new lines') }
+          }
+        ]
+      },
+      {
+        description: 'Option max words',
+        component: {
+          title: 'Example textarea',
+          name: 'myComponent',
+          type: ComponentType.MultilineTextField,
+          options: {
+            maxWords: 2
+          },
+          schema: {}
+        } satisfies MultilineTextFieldComponent,
+        assertions: [
+          {
+            input: getFormData('Textarea words'),
+            output: {
+              value: getFormData('Textarea words')
+            }
+          },
+          {
+            input: getFormData('Textarea too many words'),
+            output: {
+              value: getFormData('Textarea too many words'),
+              errors: [
+                expect.objectContaining({
+                  text: 'Example textarea must be 2 words or fewer'
+                })
+              ]
+            }
+          }
+        ]
+      },
+      {
+        description: 'Schema min and max',
+        component: {
+          title: 'Example textarea',
+          name: 'myComponent',
+          type: ComponentType.MultilineTextField,
+          options: {},
+          schema: {
+            min: 5,
+            max: 8
+          }
+        } satisfies MultilineTextFieldComponent,
+        assertions: [
+          {
+            input: getFormData('Text'),
+            output: {
+              value: getFormData('Text'),
+              errors: [
+                expect.objectContaining({
+                  text: 'Example textarea must be 5 characters or more'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData('Textarea too long'),
+            output: {
+              value: getFormData('Textarea too long'),
+              errors: [
+                expect.objectContaining({
+                  text: 'Example textarea must be 8 characters or less'
+                })
+              ]
+            }
+          }
+        ]
+      },
+      {
+        description: 'Schema length',
+        component: {
+          title: 'Example textarea',
+          name: 'myComponent',
+          type: ComponentType.MultilineTextField,
+          options: {},
+          schema: {
+            length: 4
+          }
+        } satisfies MultilineTextFieldComponent,
+        assertions: [
+          {
+            input: getFormData('Text'),
+            output: { value: getFormData('Text') }
+          },
+          {
+            input: getFormData('Textarea'),
+            output: {
+              value: getFormData('Textarea'),
+              errors: [
+                expect.objectContaining({
+                  text: 'Example textarea length must be 4 characters long'
+                })
+              ]
+            }
+          }
+        ]
+      },
+      {
+        description: 'Schema regex',
+        component: {
+          title: 'Example textarea',
+          name: 'myComponent',
+          type: ComponentType.MultilineTextField,
+          options: {},
+          schema: {
+            regex: '^[a-zA-Z]{1,2}\\d[a-zA-Z\\d]?\\s?\\d[a-zA-Z]{2}$'
+          }
+        } satisfies MultilineTextFieldComponent,
+        assertions: [
+          {
+            input: getFormData('SW1P'),
+            output: {
+              value: getFormData('SW1P'),
+              errors: [
+                expect.objectContaining({
+                  text: 'Enter a valid example textarea'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData('SW1P 4DF'),
+            output: { value: getFormData('SW1P 4DF') }
+          }
+        ]
+      },
+      {
+        description: 'Custom validation message',
+        component: {
+          title: 'Example textarea',
+          name: 'myComponent',
+          type: ComponentType.MultilineTextField,
+          options: {
+            customValidationMessage: 'This is a custom error',
+            customValidationMessages: {
+              'any.required': 'This is not used',
+              'string.empty': 'This is not used',
+              'string.max': 'This is not used',
+              'string.min': 'This is not used'
+            }
+          },
+          schema: {
+            min: 5,
+            max: 8
+          }
+        } satisfies MultilineTextFieldComponent,
+        assertions: [
+          {
+            input: getFormData(),
+            output: {
+              value: getFormData(''),
+              errors: [
+                expect.objectContaining({
+                  text: 'This is a custom error'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData(''),
+            output: {
+              value: getFormData(''),
+              errors: [
+                expect.objectContaining({
+                  text: 'This is a custom error'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData('Text'),
+            output: {
+              value: getFormData('Text'),
+              errors: [
+                expect.objectContaining({
+                  text: 'This is a custom error'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData('Textarea too long'),
+            output: {
+              value: getFormData('Textarea too long'),
+              errors: [
+                expect.objectContaining({
+                  text: 'This is a custom error'
+                })
+              ]
+            }
+          }
+        ]
+      },
+      {
+        description: 'Custom validation messages (multiple)',
+        component: {
+          title: 'Example textarea',
+          name: 'myComponent',
+          type: ComponentType.MultilineTextField,
+          options: {
+            customValidationMessages: {
+              'any.required': 'This is a custom required error',
+              'string.empty': 'This is a custom empty string error',
+              'string.max': 'This is a custom max length error',
+              'string.min': 'This is a custom min length error'
+            }
+          },
+          schema: {
+            min: 5,
+            max: 8
+          }
+        } satisfies MultilineTextFieldComponent,
+        assertions: [
+          {
+            input: getFormData(),
+            output: {
+              value: getFormData(''),
+              errors: [
+                expect.objectContaining({
+                  text: 'This is a custom required error'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData(''),
+            output: {
+              value: getFormData(''),
+              errors: [
+                expect.objectContaining({
+                  text: 'This is a custom empty string error'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData('Text'),
+            output: {
+              value: getFormData('Text'),
+              errors: [
+                expect.objectContaining({
+                  text: 'This is a custom min length error'
+                })
+              ]
+            }
+          },
+          {
+            input: getFormData('Textarea too long'),
+            output: {
+              value: getFormData('Textarea too long'),
+              errors: [
+                expect.objectContaining({
+                  text: 'This is a custom max length error'
+                })
+              ]
+            }
+          }
+        ]
+      },
+      {
+        description: 'Optional field',
+        component: {
+          title: 'Example textarea',
+          name: 'myComponent',
+          type: ComponentType.MultilineTextField,
+          options: {
+            required: false
+          },
+          schema: {}
+        } satisfies MultilineTextFieldComponent,
+        assertions: [
+          {
+            input: getFormData(''),
+            output: { value: getFormData('') }
+          }
+        ]
+      }
+    ])('$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)
+        }
+      )
+    })
+  })
+})

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

@@ -0,0 +1,138 @@
+import { type MultilineTextFieldComponent } from '@defra/forms-model'
+import Joi, { type CustomValidator, type StringSchema } from 'joi'
+
+import { type ComponentBase } from '~/src/server/plugins/engine/components/ComponentBase.js'
+import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
+import {
+  type FormPayload,
+  type FormSubmissionError
+} from '~/src/server/plugins/engine/types.js'
+
+export class MultilineTextField extends FormComponent {
+  declare options: MultilineTextFieldComponent['options']
+  declare schema: MultilineTextFieldComponent['schema']
+  declare formSchema: StringSchema
+  declare stateSchema: StringSchema
+
+  isCharacterOrWordCount = false
+
+  constructor(
+    def: MultilineTextFieldComponent,
+    props: ConstructorParameters<typeof ComponentBase>[1]
+  ) {
+    super(def, props)
+
+    const { schema, options, title } = def
+
+    let formSchema = Joi.string().trim().label(title).required()
+
+    if (options.required === false) {
+      formSchema = formSchema.allow('')
+    }
+
+    if (typeof schema.length !== 'number') {
+      if (typeof schema.max === 'number') {
+        formSchema = formSchema.max(schema.max)
+        this.isCharacterOrWordCount = true
+      }
+
+      if (typeof schema.min === 'number') {
+        formSchema = formSchema.min(schema.min)
+      }
+    } else {
+      formSchema = formSchema.length(schema.length)
+    }
+
+    if (typeof options.maxWords === 'number') {
+      formSchema = formSchema.custom(
+        getValidatorMaxWords(this),
+        'max words validation'
+      )
+
+      this.isCharacterOrWordCount = true
+    }
+
+    if (schema.regex) {
+      const pattern = new RegExp(schema.regex)
+      formSchema = formSchema.pattern(pattern)
+    }
+
+    if (options.customValidationMessage) {
+      const message = options.customValidationMessage
+
+      formSchema = formSchema.messages({
+        'any.required': message,
+        'string.empty': message,
+        'string.max': message,
+        'string.min': message,
+        'string.length': message,
+        'string.pattern.base': message,
+        'string.maxWords': message
+      })
+    } else if (options.customValidationMessages) {
+      formSchema = formSchema.messages(options.customValidationMessages)
+    }
+
+    this.formSchema = formSchema.default('')
+    this.stateSchema = formSchema.default(null).allow(null)
+    this.options = options
+    this.schema = schema
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const { schema, options, isCharacterOrWordCount } = this
+
+    const viewModel = super.getViewModel(payload, errors)
+    let { maxlength, maxwords, rows } = viewModel
+
+    if (schema.max) {
+      maxlength = schema.max
+    }
+
+    if (options.maxWords) {
+      maxwords = options.maxWords
+    }
+
+    if (options.rows) {
+      rows = options.rows
+    }
+
+    return {
+      ...viewModel,
+      isCharacterOrWordCount,
+      maxlength,
+      maxwords,
+      rows
+    }
+  }
+}
+
+function getValidatorMaxWords(component: MultilineTextField) {
+  const validator: CustomValidator = (value: string, helpers) => {
+    const { options } = component
+
+    const {
+      customValidationMessage: custom,
+      maxWords: limit // See {{#limit}} variable
+    } = options
+
+    if (!limit || count(value) <= limit) {
+      return value
+    }
+
+    return custom
+      ? helpers.message({ custom }, { limit })
+      : helpers.error('string.maxWords', { limit })
+  }
+
+  /**
+   * Count the number of words in the given text
+   * @see GOV.UK Frontend {@link https://github.com/alphagov/govuk-frontend/blob/v5.4.0/packages/govuk-frontend/src/govuk/components/character-count/character-count.mjs#L343 | Character count `maxwords` implementation}
+   */
+  function count(text: string) {
+    const tokens = text.match(/\S+/g) ?? []
+    return tokens.length
+  }
+
+  return validator
+}