@defra/forms-engine-plugin 4.0.7 → 4.0.8

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

@@ -0,0 +1,167 @@
+import { type DeclarationFieldComponent, type Item } from '@defra/forms-model'
+import joi, {
+  type ArraySchema,
+  type BooleanSchema,
+  type StringSchema
+} from 'joi'
+
+import {
+  FormComponent,
+  isFormValue
+} from '~/src/server/plugins/engine/components/FormComponent.js'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
+import {
+  type ErrorMessageTemplateList,
+  type FormPayload,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionError,
+  type FormSubmissionState,
+  type FormValue
+} from '~/src/server/plugins/engine/types.js'
+
+export class DeclarationField extends FormComponent {
+  private readonly DEFAULT_DECLARATION_LABEL = 'I understand and agree'
+
+  declare options: DeclarationFieldComponent['options']
+
+  declare declarationConfirmationLabel: string
+
+  declare formSchema: ArraySchema<StringSchema[]>
+  declare stateSchema: BooleanSchema
+  declare content: string
+
+  constructor(
+    def: DeclarationFieldComponent,
+    props: ConstructorParameters<typeof FormComponent>[1]
+  ) {
+    super(def, props)
+
+    const { options, content } = def
+
+    let checkboxSchema = joi.string().valid('true')
+
+    if (options.required !== false) {
+      checkboxSchema = checkboxSchema.required()
+    }
+
+    const formSchema = joi
+      .array()
+      .items(checkboxSchema, joi.string().valid('unchecked').strip())
+      .label(this.label)
+      .single()
+      .messages({
+        'any.required': messageTemplate.declarationRequired as string,
+        'any.unknown': messageTemplate.declarationRequired as string,
+        'array.includesRequiredUnknowns':
+          messageTemplate.declarationRequired as string
+      }) as ArraySchema<StringSchema[]>
+
+    this.formSchema = formSchema
+    this.stateSchema = joi.boolean().cast('string').label(this.label).required()
+
+    this.options = options
+    this.content = content
+    this.declarationConfirmationLabel =
+      options.declarationConfirmationLabel ?? this.DEFAULT_DECLARATION_LABEL
+  }
+
+  getFormValueFromState(state: FormSubmissionState) {
+    const { name } = this
+    return state[name] === true ? 'true' : undefined
+  }
+
+  getFormDataFromState(state: FormSubmissionState): FormPayload {
+    const { name } = this
+    return { [name]: state[name] === true ? 'true' : undefined }
+  }
+
+  getStateFromValidForm(payload: FormPayload): FormState {
+    const { name } = this
+    const payloadValue = payload[name]
+    const value =
+      this.isValue(payloadValue) &&
+      payloadValue.length > 0 &&
+      payloadValue.every((v) => {
+        return v === 'true'
+      })
+
+    return { [name]: value }
+  }
+
+  getContextValueFromFormValue(value: FormValue | FormPayload): boolean {
+    return value === 'true'
+  }
+
+  getFormValue(value?: FormStateValue | FormState) {
+    return this.isValue(value) ? value : undefined
+  }
+
+  getDisplayStringFromFormValue(value: FormValue | FormPayload): string {
+    return value ? this.declarationConfirmationLabel : ''
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const defaultDeclarationConfirmationLabel =
+      'I confirm that I understand and accept this declaration'
+    const {
+      title,
+      hint,
+      content,
+      declarationConfirmationLabel = defaultDeclarationConfirmationLabel
+    } = this
+    return {
+      ...super.getViewModel(payload, errors),
+      hint: hint ? { text: hint } : undefined,
+      fieldset: {
+        legend: {
+          text: title
+        }
+      },
+      content,
+      values: payload[this.name],
+      items: [
+        {
+          text: declarationConfirmationLabel,
+          value: 'true'
+        }
+      ]
+    }
+  }
+
+  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)
+  }
+
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return DeclarationField.getAllPossibleErrors()
+  }
+
+  /**
+   * Static version of getAllPossibleErrors that doesn't require a component instance.
+   */
+  static getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'required', template: messageTemplate.declarationRequired }
+      ],
+      advancedSettingsErrors: []
+    }
+  }
+
+  static isBool(value?: FormStateValue | FormState): value is boolean {
+    return isFormValue(value) && typeof value === 'boolean'
+  }
+}

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

@@ -20,6 +20,7 @@ export type Field = InstanceType<
   | typeof Components.YesNoField
   | typeof Components.CheckboxesField
   | typeof Components.DatePartsField
+  | typeof Components.DeclarationField
   | typeof Components.EastingNorthingField
   | typeof Components.EmailAddressField
   | typeof Components.LatLongField
@@ -102,6 +103,10 @@ export function createComponent(
       component = new Components.DatePartsField(def, options)
       break
 
+    case ComponentType.DeclarationField:
+      component = new Components.DeclarationField(def, options)
+      break
+
     case ComponentType.Details:
       component = new Components.Details(def, options)
       break

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

@@ -7,6 +7,7 @@
 export { AutocompleteField } from '~/src/server/plugins/engine/components/AutocompleteField.js'
 export { CheckboxesField } from '~/src/server/plugins/engine/components/CheckboxesField.js'
 export { DatePartsField } from '~/src/server/plugins/engine/components/DatePartsField.js'
+export { DeclarationField } from '~/src/server/plugins/engine/components/DeclarationField.js'
 export { Details } from '~/src/server/plugins/engine/components/Details.js'
 export { EmailAddressField } from '~/src/server/plugins/engine/components/EmailAddressField.js'
 export { FileUploadField } from '~/src/server/plugins/engine/components/FileUploadField.js'

package/src/server/plugins/engine/models/SummaryViewModel.test.ts

@@ -15,6 +15,7 @@ import {
   type FormContextRequest,
   type FormState
 } from '~/src/server/plugins/engine/types.js'
+import v2Definition from '~/test/form/definitions/conditions-relative-dates-v2.js'
 import definition from '~/test/form/definitions/repeat-mixed.js'
 const basePath = `${FORM_PREFIX}/test`
 
@@ -326,7 +327,7 @@ describe('SummaryPageController', () => {
       expect(viewModel).toHaveProperty('allowSaveAndExit', true)
     })
 
-    it('should display correct page title', () => {
+    it('should display correct page title for v1 form', () => {
       const state: FormState = {
         $$__referenceNumber: 'foobar',
         orderType: 'collection',
@@ -334,9 +335,81 @@ describe('SummaryPageController', () => {
       }
 
       const context = model.getFormContext(request, state)
-      const viewModel = controller.getViewModel(request, context)
+      const viewModel = controller.getSummaryViewModel(request, context)
+
+      expect(viewModel.pageTitle).toBe(
+        'Check your answers before sending your form'
+      )
+    })
+
+    it('should display default page title for v2 form when title not supplied', () => {
+      const state: FormState = {
+        $$__referenceNumber: 'foobar',
+        orderType: 'collection',
+        pizza: []
+      }
+
+      const titleModel = new FormModel(v2Definition, {
+        basePath: `${FORM_PREFIX}/test`
+      })
+
+      controller = new SummaryPageController(titleModel, v2Definition.pages[5])
+
+      request = {
+        method: 'get',
+        url: new URL('http://example.com/repeat/pizza-order/summary'),
+        path: '/test/summary',
+        params: {
+          path: 'summary',
+          slug: 'test'
+        },
+        query: {},
+        app: { model: titleModel },
+        server: serverWithSaveAndExit
+      }
+
+      const context = titleModel.getFormContext(request, state)
+      const viewModel = controller.getSummaryViewModel(request, context)
+
+      expect(viewModel.pageTitle).toBe(
+        'Check your answers before sending your form'
+      )
+    })
+
+    it('should display override page title for v2 form when title supplied', () => {
+      const state: FormState = {
+        $$__referenceNumber: 'foobar',
+        orderType: 'collection',
+        pizza: []
+      }
+
+      const v2DefinitionWithSummaryTitle = structuredClone(v2Definition)
+      const summaryPage = v2DefinitionWithSummaryTitle.pages[5]
+      summaryPage.title = 'Override summary title'
+
+      const titleModel = new FormModel(v2DefinitionWithSummaryTitle, {
+        basePath: `${FORM_PREFIX}/test`
+      })
+
+      controller = new SummaryPageController(titleModel, summaryPage)
+
+      request = {
+        method: 'get',
+        url: new URL('http://example.com/repeat/pizza-order/summary'),
+        path: '/test/summary',
+        params: {
+          path: 'summary',
+          slug: 'test'
+        },
+        query: {},
+        app: { model: titleModel },
+        server: serverWithSaveAndExit
+      }
+
+      const context = titleModel.getFormContext(request, state)
+      const viewModel = controller.getSummaryViewModel(request, context)
 
-      expect(viewModel.pageTitle).toBe('Check your answers')
+      expect(viewModel.pageTitle).toBe('Override summary title')
     })
   })
 })

package/src/server/plugins/engine/models/SummaryViewModel.ts

@@ -1,4 +1,4 @@
-import { type Section } from '@defra/forms-model'
+import { SchemaVersion, type Section } from '@defra/forms-model'
 
 import {
   getAnswer,
@@ -64,6 +64,10 @@ export class SummaryViewModel {
 
     this.page = page
     this.pageTitle = page.title
+    if (def.schema === SchemaVersion.V2 && !page.title) {
+      this.pageTitle = 'Check your answers before sending your form'
+    }
+
     this.serviceUrl = `/${basePath}`
     this.name = def.name
     this.declaration = def.declaration

package/src/server/plugins/engine/pageControllers/validationOptions.ts

@@ -20,6 +20,10 @@ const opts = {
  * see @link https://joi.dev/api/?v=17.4.2#template-syntax for template syntax
  */
 export const messageTemplate: Record<string, JoiExpression> = {
+  declarationRequired: joi.expression(
+    'You must confirm you understand and agree with the {{lowerFirst(#label)}} to continue',
+    opts
+  ) as JoiExpression,
   required: joi.expression(
     'Enter {{lowerFirst(#label)}}',
     opts

package/src/server/plugins/engine/views/components/declarationfield.html

@@ -0,0 +1,14 @@
+{% from "govuk/components/fieldset/macro.njk" import govukFieldset %}
+{% from "govuk/components/checkboxes/macro.njk" import govukCheckboxes %}
+{% from "govuk/components/hint/macro.njk" import govukHint %}
+
+{% macro DeclarationField(component) %}
+  {% set content %}
+    <div class="app-prose-scope">
+      {{ component.model.content | markdown | safe }}
+    </div>
+  {% endset %}
+  {% set checkboxes = component.model | merge({ formGroup: { beforeInputs: { html: content } } }) %}
+  {{ govukCheckboxes(checkboxes) }}
+  <input type="hidden" name="{{ component.model.name }}" value="unchecked">
+{% endmacro %}

package/src/server/plugins/nunjucks/filters/index.js

@@ -5,3 +5,4 @@ export { answer } from '~/src/server/plugins/nunjucks/filters/answer.js'
 export { href } from '~/src/server/plugins/nunjucks/filters/href.js'
 export { field } from '~/src/server/plugins/nunjucks/filters/field.js'
 export { page } from '~/src/server/plugins/nunjucks/filters/page.js'
+export { merge } from '~/src/server/plugins/nunjucks/filters/merge.js'

package/src/server/plugins/nunjucks/filters/merge.js

@@ -0,0 +1,16 @@
+/**
+ * Nunjucks filter to get the page for a given path
+ * @param {Record<string, any>} targetDictionary - Object to extend
+ * @param {Record<string, any> | string} sourceDictionary - Object to merge into target
+ * @returns {Record<string, any>}
+ */
+export function merge(targetDictionary, sourceDictionary) {
+  if (typeof sourceDictionary !== 'object') {
+    return targetDictionary
+  }
+
+  return {
+    ...targetDictionary,
+    ...sourceDictionary
+  }
+}

package/src/server/plugins/nunjucks/filters/merge.test.js

@@ -0,0 +1,15 @@
+import { merge } from '~/src/server/plugins/nunjucks/filters/merge.js'
+
+describe('merge', () => {
+  const propertyToMerge = { lorem: 'ipsum' }
+  it('should return the target if source is not an object', () => {
+    expect(merge(propertyToMerge, 'dolar')).toBe(propertyToMerge)
+  })
+
+  it('should merge the properties if they are valid', () => {
+    expect(merge({ lorem: 'dolar', dolar: 'sit' }, propertyToMerge)).toEqual({
+      lorem: 'ipsum',
+      dolar: 'sit'
+    })
+  })
+})