@defra/forms-engine-plugin 0.0.4 → 0.0.5

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

@@ -0,0 +1,49 @@
+import { type AutocompleteFieldComponent } from '@defra/forms-model'
+
+import { SelectField } from '~/src/server/plugins/engine/components/SelectField.js'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
+import {
+  type FormPayload,
+  type FormSubmissionError
+} from '~/src/server/plugins/engine/types.js'
+
+export class AutocompleteField extends SelectField {
+  declare options: AutocompleteFieldComponent['options']
+
+  constructor(
+    def: AutocompleteFieldComponent,
+    props: ConstructorParameters<typeof SelectField>[1]
+  ) {
+    super(def, props)
+
+    const { options } = def
+    let { formSchema } = this
+
+    if (options.required !== false) {
+      const messages = options.customValidationMessages
+
+      formSchema = formSchema.messages({
+        'any.only': messages?.['any.only'] ?? messageTemplate.required,
+        'any.required': messages?.['any.required'] ?? messageTemplate.required
+      })
+    }
+
+    this.options = options
+    this.formSchema = formSchema
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const viewModel = super.getViewModel(payload, errors)
+    let { formGroup } = viewModel
+
+    formGroup ??= {}
+    formGroup.attributes = {
+      'data-module': 'govuk-accessible-autocomplete'
+    }
+
+    return {
+      ...viewModel,
+      formGroup
+    }
+  }
+}

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

@@ -0,0 +1,379 @@
+import {
+  ComponentType,
+  type CheckboxesFieldComponent
+} from '@defra/forms-model'
+import { outdent } from 'outdent'
+
+import { CheckboxesField } from '~/src/server/plugins/engine/components/CheckboxesField.js'
+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 {
+  listNumber,
+  listNumberExamples,
+  listString,
+  listStringExamples
+} from '~/test/fixtures/list.js'
+import definition from '~/test/form/definitions/blank.js'
+import { getFormData, getFormState } from '~/test/helpers/component-helpers.js'
+
+describe.each([
+  {
+    component: {
+      title: 'String list',
+      name: 'myComponent',
+      type: ComponentType.CheckboxesField,
+      list: 'listString',
+      options: {}
+    } satisfies CheckboxesFieldComponent,
+
+    options: {
+      list: listString,
+      examples: listStringExamples,
+      allow: ['1', '2', '3', '4'],
+      deny: ['5', '6', '7', '8']
+    }
+  },
+  {
+    component: {
+      title: 'Number list',
+      name: 'myComponent',
+      type: ComponentType.CheckboxesField,
+      list: 'listNumber',
+      options: {}
+    } satisfies CheckboxesFieldComponent,
+
+    options: {
+      list: listNumber,
+      examples: listNumberExamples,
+      allow: [1, 2, 3, 4],
+      deny: [5, 6, 7, 8]
+    }
+  }
+])('CheckboxesField: $component.title', ({ component: def, options }) => {
+  const updated = structuredClone(definition)
+  updated.lists = [options.list]
+
+  let model: FormModel
+  let collection: ComponentCollection
+  let field: Field
+
+  beforeEach(() => {
+    model = new FormModel(updated, {
+      basePath: 'test'
+    })
+
+    collection = new ComponentCollection([def], { model })
+    field = collection.fields[0]
+  })
+
+  describe('Defaults', () => {
+    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: def.title })
+          })
+        )
+      })
+
+      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 for single values', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            flags: expect.objectContaining({
+              single: true
+            })
+          })
+        )
+      })
+
+      it('is configured with checkbox items', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            items: [
+              {
+                allow: options.allow,
+                flags: {
+                  label: def.title,
+                  only: true
+                },
+                type: options.list.type
+              }
+            ]
+          })
+        )
+      })
+
+      it('adds errors for empty value', () => {
+        const result = collection.validate(getFormData())
+
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: `Select ${def.title.toLowerCase()}`
+          })
+        ])
+      })
+
+      it.each([...options.allow])(
+        'accepts valid checkbox single item',
+        (value) => {
+          const result = collection.validate(getFormData(value))
+          expect(result.errors).toBeUndefined()
+        }
+      )
+
+      it.each([...options.allow])(
+        'accepts valid checkbox array item',
+        (value) => {
+          const result = collection.validate(getFormData([value]))
+          expect(result.errors).toBeUndefined()
+        }
+      )
+
+      it.each([...options.deny])(
+        'rejects invalid checkbox single item',
+        (value) => {
+          const result = collection.validate(getFormData(value))
+
+          expect(result.errors).toEqual([
+            expect.objectContaining({
+              text: `Select ${def.title.toLowerCase()}`
+            })
+          ])
+        }
+      )
+
+      it.each([...options.deny])(
+        'rejects invalid checkbox array item',
+        (value) => {
+          const result = collection.validate(getFormData([value]))
+
+          expect(result.errors).toEqual([
+            expect.objectContaining({
+              text: `Select ${def.title.toLowerCase()}`
+            })
+          ])
+        }
+      )
+
+      it('adds errors for invalid values', () => {
+        const result1 = collection.validate(getFormData('invalid'))
+        const result2 = collection.validate(
+          getFormData(['invalid1', 'invalid2'])
+        )
+
+        const result3 = collection.validate(
+          // @ts-expect-error - Allow invalid param for test
+          getFormData({ unknown: 'invalid' })
+        )
+
+        expect(result1.errors).toBeTruthy()
+        expect(result2.errors).toBeTruthy()
+        expect(result3.errors).toBeTruthy()
+      })
+    })
+
+    describe('State', () => {
+      it.each([...options.examples])(
+        'returns text from state (single)',
+        (item) => {
+          const state1 = getFormState([item.state])
+          const state2 = getFormState(null)
+
+          const answer1 = getAnswer(field, state1)
+          const answer2 = getAnswer(field, state2)
+
+          expect(answer1).toBe(outdent`
+            <ul>
+            <li>${item.text}</li>
+            </ul>
+          `)
+
+          expect(answer2).toBe('')
+        }
+      )
+
+      it('returns text from state (multiple)', () => {
+        const item1 = options.examples[0]
+        const item2 = options.examples[2]
+
+        const state = getFormState([item1.state, item2.state])
+        const answer = getAnswer(field, state)
+
+        expect(answer).toBe(outdent`
+          <ul>
+          <li>${item1.text}</li>
+          <li>${item2.text}</li>
+          </ul>
+        `)
+      })
+
+      it.each([...options.examples])('returns payload from state', (item) => {
+        const state1 = getFormState([item.state])
+        const state2 = getFormState(null)
+
+        const payload1 = field.getFormDataFromState(state1)
+        const payload2 = field.getFormDataFromState(state2)
+
+        expect(payload1).toEqual(getFormData([item.value]))
+        expect(payload2).toEqual(getFormData())
+      })
+
+      it.each([...options.examples])('returns value from state', (item) => {
+        const state1 = getFormState([item.state])
+        const state2 = getFormState(null)
+
+        const value1 = field.getFormValueFromState(state1)
+        const value2 = field.getFormValueFromState(state2)
+
+        expect(value1).toEqual([item.value])
+        expect(value2).toBeUndefined()
+      })
+
+      it.each([...options.examples])(
+        'returns context for conditions and form submission',
+        (item) => {
+          const state1 = getFormState([item.state])
+          const state2 = getFormState(null)
+
+          const value1 = field.getContextValueFromState(state1)
+          const value2 = field.getContextValueFromState(state2)
+
+          expect(value1).toEqual([item.state])
+          expect(value2).toEqual([])
+        }
+      )
+
+      it.each([...options.examples])('returns state from payload', (item) => {
+        const payload1 = getFormData([item.value])
+        const payload2 = getFormData()
+
+        const value1 = field.getStateFromValidForm(payload1)
+        const value2 = field.getStateFromValidForm(payload2)
+
+        expect(value1).toEqual(getFormState([item.state]))
+        expect(value2).toEqual(getFormState(null))
+      })
+    })
+
+    describe('View model', () => {
+      it('sets Nunjucks component defaults', () => {
+        const item = options.examples[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([...options.examples])(
+        'sets Nunjucks component checkbox 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
+              })
+            ])
+          )
+        }
+      )
+    })
+
+    describe('Checkbox items', () => {
+      it('returns checkbox items', () => {
+        expect(field).toHaveProperty('items', options.list.items)
+      })
+
+      it('returns checkbox items matching type', () => {
+        expect(field).toHaveProperty('values', expect.arrayContaining([]))
+      })
+
+      it('returns empty items when missing', () => {
+        const model = new FormModel(definition, {
+          basePath: 'test'
+        })
+
+        const { items } = new CheckboxesField(def, { model })
+        expect(items).toEqual([])
+      })
+    })
+  })
+})

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

@@ -0,0 +1,106 @@
+import { type CheckboxesFieldComponent, type Item } from '@defra/forms-model'
+import joi, { type ArraySchema } from 'joi'
+
+import { isFormValue } from '~/src/server/plugins/engine/components/FormComponent.js'
+import { SelectionControlField } from '~/src/server/plugins/engine/components/SelectionControlField.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { type QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import {
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionState
+} from '~/src/server/plugins/engine/types.js'
+
+export class CheckboxesField extends SelectionControlField {
+  declare options: CheckboxesFieldComponent['options']
+  declare formSchema: ArraySchema<string> | ArraySchema<number>
+  declare stateSchema: ArraySchema<string> | ArraySchema<number>
+
+  constructor(
+    def: CheckboxesFieldComponent,
+    props: ConstructorParameters<typeof SelectionControlField>[1]
+  ) {
+    super(def, props)
+
+    const { listType: type } = this
+    const { options, title } = def
+
+    let formSchema =
+      type === 'string' ? joi.array<string>() : joi.array<number>()
+
+    const itemsSchema = joi[type]()
+      .valid(...this.values)
+      .label(title)
+
+    formSchema = formSchema.items(itemsSchema).single().label(title).required()
+
+    if (options.required === false) {
+      formSchema = formSchema.optional()
+    }
+
+    this.formSchema = formSchema.default([])
+    this.stateSchema = formSchema.default(null).allow(null)
+    this.options = options
+  }
+
+  getFormValueFromState(state: FormSubmissionState) {
+    const { items, name } = this
+
+    // State checkbox values
+    const values = this.getFormValue(state[name]) ?? []
+
+    // Map (or discard) state values to item values
+    const selected = items
+      .filter((item) => values.includes(item.value))
+      .map((item) => item.value)
+
+    return selected.length ? selected : undefined
+  }
+
+  getFormValue(value?: FormStateValue | FormState) {
+    return this.isValue(value) ? value : undefined
+  }
+
+  getDisplayStringFromState(state: FormSubmissionState) {
+    const { items } = this
+
+    // Selected checkbox values
+    const selected = this.getFormValueFromState(state) ?? []
+
+    // Map selected values to text
+    return items
+      .filter((item) => selected.includes(item.value))
+      .map((item) => item.text)
+      .join(', ')
+  }
+
+  getContextValueFromState(state: FormSubmissionState) {
+    const values = this.getFormValueFromState(state)
+
+    /**
+     * For evaluation context purposes, optional {@link CheckboxesField}
+     * with an undefined value (i.e. nothing selected) should default to [].
+     * This way conditions are not evaluated against `undefined` which throws errors.
+     * Currently these errors are caught and the evaluation returns default `false`.
+     * @see {@link QuestionPageController.getNextPath} for `undefined` return value
+     * @see {@link FormModel.makeCondition} for try/catch block with default `false`
+     * For negative conditions this is a problem because E.g.
+     * The condition: 'selectedchecks' does not contain 'someval'
+     * should return true IF 'selectedchecks' is undefined, not throw and return false.
+     */
+    return values ?? []
+  }
+
+  isValue(value?: FormStateValue | FormState): value is Item['value'][] {
+    if (!Array.isArray(value)) {
+      return false
+    }
+
+    // Skip checks when empty
+    if (!value.length) {
+      return true
+    }
+
+    return value.every(isFormValue)
+  }
+}

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

@@ -0,0 +1,97 @@
+import { isConditionalType, type ComponentDef } from '@defra/forms-model'
+import joi, {
+  type ArraySchema,
+  type BooleanSchema,
+  type DateSchema,
+  type NumberSchema,
+  type ObjectSchema,
+  type StringSchema
+} from 'joi'
+
+import { type ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import { type Component } from '~/src/server/plugins/engine/components/helpers.js'
+import { type ViewModel } from '~/src/server/plugins/engine/components/types.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+
+export class ComponentBase {
+  page?: PageControllerClass
+  parent: Component | undefined
+  collection: ComponentCollection | undefined
+
+  type: ComponentDef['type']
+  name: ComponentDef['name']
+  title: ComponentDef['title']
+  schema?: Extract<ComponentDef, { schema: object }>['schema']
+  options?: Extract<ComponentDef, { options: object }>['options']
+
+  isFormComponent = false
+  model: FormModel
+
+  /** joi schemas based on a component defined in the form JSON. This validates a user's answer and is generated from {@link ComponentDef} */
+  formSchema: ComponentSchema = joi.string()
+  stateSchema: ComponentSchema = joi.string()
+
+  constructor(
+    def: ComponentDef,
+    props: {
+      page?: PageControllerClass
+      parent?: Component
+      model: FormModel
+    }
+  ) {
+    this.type = def.type
+    this.name = def.name
+    this.title = def.title
+
+    if ('schema' in def) {
+      this.schema = def.schema
+    }
+
+    if ('options' in def) {
+      this.options = def.options
+    }
+
+    this.page = props.page
+    this.parent = props.parent
+    this.model = props.model
+  }
+
+  get viewModel() {
+    const { options, type } = this
+
+    const viewModel: ViewModel = {
+      attributes: {}
+    }
+
+    if (!options) {
+      return viewModel
+    }
+
+    if ('autocomplete' in options) {
+      viewModel.attributes.autocomplete = options.autocomplete
+    }
+
+    if ('classes' in options) {
+      viewModel.classes = options.classes
+    }
+
+    if ('condition' in options && isConditionalType(type)) {
+      viewModel.condition = options.condition
+    }
+
+    return viewModel
+  }
+}
+
+export type ComponentSchema =
+  | ArraySchema<string>
+  | ArraySchema<number>
+  | ArraySchema<boolean>
+  | ArraySchema<object>
+  | BooleanSchema<string>
+  | DateSchema
+  | NumberSchema<string>
+  | NumberSchema
+  | ObjectSchema
+  | StringSchema