@defra/forms-engine-plugin 4.0.25 → 4.0.27

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

@@ -0,0 +1,188 @@
+import { ComponentType, type HiddenFieldComponent } 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/components.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('HiddenField', () => {
+  let model: FormModel
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+  })
+
+  describe('Defaults', () => {
+    let def: HiddenFieldComponent
+    let collection: ComponentCollection
+    let field: Field
+
+    beforeEach(() => {
+      def = {
+        title: 'Hidden field',
+        name: 'myComponent',
+        type: ComponentType.HiddenField,
+        options: {}
+      } satisfies HiddenFieldComponent
+
+      collection = new ComponentCollection([def], { model })
+      field = collection.fields[0]
+    })
+
+    describe('Schema', () => {
+      it('uses component title as label as default', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            flags: expect.objectContaining({
+              label: 'Hidden field'
+            })
+          })
+        )
+      })
+
+      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('accepts valid values', () => {
+        const result1 = collection.validate(getFormData('Hidden value'))
+        const result2 = collection.validate(getFormData('Hidden value 2'))
+
+        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 hidden field'
+          })
+        ])
+      })
+
+      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('Hidden field')
+        const state2 = getFormState(null)
+
+        const answer1 = getAnswer(field, state1)
+        const answer2 = getAnswer(field, state2)
+
+        expect(answer1).toBe('Hidden field')
+        expect(answer2).toBe('')
+      })
+
+      it('returns payload from state', () => {
+        const state1 = getFormState('Hidden field')
+        const state2 = getFormState(null)
+
+        const payload1 = field.getFormDataFromState(state1)
+        const payload2 = field.getFormDataFromState(state2)
+
+        expect(payload1).toEqual(getFormData('Hidden field'))
+        expect(payload2).toEqual(getFormData())
+      })
+
+      it('returns value from state', () => {
+        const state1 = getFormState('Hidden field')
+        const state2 = getFormState(null)
+
+        const value1 = field.getFormValueFromState(state1)
+        const value2 = field.getFormValueFromState(state2)
+
+        expect(value1).toBe('Hidden field')
+        expect(value2).toBeUndefined()
+      })
+
+      it('returns context for conditions and form submission', () => {
+        const state1 = getFormState('Hidden field')
+        const state2 = getFormState(null)
+
+        const value1 = field.getContextValueFromState(state1)
+        const value2 = field.getContextValueFromState(state2)
+
+        expect(value1).toBe('Hidden field')
+        expect(value2).toBeNull()
+      })
+
+      it('returns state from payload', () => {
+        const payload1 = getFormData('Hidden field')
+        const payload2 = getFormData()
+
+        const value1 = field.getStateFromValidForm(payload1)
+        const value2 = field.getStateFromValidForm(payload2)
+
+        expect(value1).toEqual(getFormState('Hidden field'))
+        expect(value2).toEqual(getFormState(null))
+      })
+    })
+
+    describe('View model', () => {
+      it('sets Nunjucks component defaults', () => {
+        const viewModel = field.getViewModel(getFormData('Hidden field'))
+
+        expect(viewModel).toEqual(
+          expect.objectContaining({
+            label: { text: def.title },
+            name: 'myComponent',
+            id: 'myComponent',
+            value: 'Hidden field'
+          })
+        )
+      })
+    })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).toBeEmpty()
+      })
+    })
+  })
+})

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

@@ -0,0 +1,68 @@
+import {
+  type HiddenFieldComponent,
+  type TextFieldComponent
+} from '@defra/forms-model'
+import joi, { type StringSchema } from 'joi'
+
+import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
+import { TextField } from '~/src/server/plugins/engine/components/TextField.js'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
+import {
+  type ErrorMessageTemplateList,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionState
+} from '~/src/server/plugins/engine/types.js'
+
+export class HiddenField extends FormComponent {
+  declare formSchema: StringSchema
+  declare stateSchema: StringSchema
+  declare schema: TextFieldComponent['schema']
+  declare options: TextFieldComponent['options']
+
+  constructor(
+    def: HiddenFieldComponent,
+    props: ConstructorParameters<typeof FormComponent>[1]
+  ) {
+    super(def, props)
+
+    const { options } = def
+
+    let formSchema = joi.string().trim().label(this.label).required()
+
+    if (options.required === false) {
+      formSchema = formSchema.allow('')
+    }
+
+    this.formSchema = formSchema.default('')
+    this.stateSchema = formSchema.default(null).allow(null)
+    this.schema = {}
+    this.options = {}
+  }
+
+  getFormValueFromState(state: FormSubmissionState) {
+    const { name } = this
+    return this.getFormValue(state[name])
+  }
+
+  isValue(value?: FormStateValue | FormState): value is string {
+    return TextField.isText(value)
+  }
+
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return HiddenField.getAllPossibleErrors()
+  }
+
+  /**
+   * Static version of getAllPossibleErrors that doesn't require a component instance.
+   */
+  static getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [{ type: 'required', template: messageTemplate.required }],
+      advancedSettingsErrors: []
+    }
+  }
+}

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

@@ -34,6 +34,7 @@ export type Field = InstanceType<
   | typeof Components.TextField
   | typeof Components.UkAddressField
   | typeof Components.FileUploadField
+  | typeof Components.HiddenField
 >
 
 // Guidance component instances only
@@ -186,6 +187,10 @@ export function createComponent(
     case ComponentType.LatLongField:
       component = new Components.LatLongField(def, options)
       break
+
+    case ComponentType.HiddenField:
+      component = new Components.HiddenField(def, options)
+      break
   }
 
   if (typeof component === 'undefined') {

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

@@ -2,6 +2,7 @@ import { ComponentType, type ComponentDef } from '@defra/forms-model'
 
 import { ComponentBase } from '~/src/server/plugins/engine/components/ComponentBase.js'
 import { EastingNorthingField } from '~/src/server/plugins/engine/components/EastingNorthingField.js'
+import { HiddenField } from '~/src/server/plugins/engine/components/HiddenField.js'
 import { LatLongField } from '~/src/server/plugins/engine/components/LatLongField.js'
 import { NationalGridFieldNumberField } from '~/src/server/plugins/engine/components/NationalGridFieldNumberField.js'
 import { OsGridRefField } from '~/src/server/plugins/engine/components/OsGridRefField.js'
@@ -96,6 +97,22 @@ describe('helpers tests', () => {
     expect(component.name).toBe('testField')
     expect(component.title).toBe('Test National Grid')
   })
+
+  test('should create HiddenField component', () => {
+    const component = createComponent(
+      {
+        type: ComponentType.HiddenField,
+        name: 'hiddenField',
+        title: 'Hidden field',
+        options: {}
+      },
+      { model: formModel }
+    )
+
+    expect(component).toBeInstanceOf(HiddenField)
+    expect(component.name).toBe('hiddenField')
+    expect(component.title).toBe('Hidden field')
+  })
 })
 
 describe('ComponentBase tests', () => {

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

@@ -28,3 +28,4 @@ export { EastingNorthingField } from '~/src/server/plugins/engine/components/Eas
 export { OsGridRefField } from '~/src/server/plugins/engine/components/OsGridRefField.js'
 export { NationalGridFieldNumberField } from '~/src/server/plugins/engine/components/NationalGridFieldNumberField.js'
 export { LatLongField } from '~/src/server/plugins/engine/components/LatLongField.js'
+export { HiddenField } from '~/src/server/plugins/engine/components/HiddenField.js'

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

@@ -1,3 +1,8 @@
+import {
+  ComponentType,
+  type FormDefinition,
+  type PageQuestion
+} from '@defra/forms-model'
 import Boom from '@hapi/boom'
 import { type ResponseObject, type ResponseToolkit } from '@hapi/hapi'
 import { StatusCodes } from 'http-status-codes'
@@ -14,6 +19,7 @@ import {
   getPageHref,
   proceed,
   safeGenerateCrumb,
+  setPageTitles,
   type GlobalScope
 } from '~/src/server/plugins/engine/helpers.js'
 import { handleLegacyRedirect } from '~/src/server/plugins/engine/helpers.js'
@@ -51,6 +57,7 @@ describe('Helpers', () => {
   let h: FormResponseToolkit
 
   beforeEach(() => {
+    jest.clearAllMocks()
     const model = new FormModel(definition, {
       basePath: 'test'
     })
@@ -843,4 +850,53 @@ describe('Helpers', () => {
       expect(response).toBe(mockRedirectResponse)
     })
   })
+
+  describe('setPageTitles', () => {
+    const definition: FormDefinition = {
+      name: 'Test Form',
+      startPage: '/page1',
+      pages: [
+        {
+          path: '/page1',
+          title: '',
+          next: [],
+          components: [
+            {
+              type: ComponentType.TextField,
+              name: 'textfield1',
+              title: 'What is your name?',
+              options: {},
+              schema: {}
+            },
+            {
+              type: ComponentType.TextField,
+              name: 'textfield2',
+              title: 'What is your favourite food?',
+              options: {},
+              schema: {}
+            }
+          ]
+        } satisfies PageQuestion
+      ],
+      lists: [],
+      sections: [],
+      conditions: []
+    }
+
+    beforeEach(() => {
+      jest.clearAllMocks()
+    })
+    it('should set title if missing', () => {
+      const def = structuredClone(definition)
+      setPageTitles(def)
+      expect(def.pages[0].title).toBe('What is your name?')
+    })
+
+    it('should keep title if supplied', () => {
+      const def = structuredClone(definition)
+      def.pages[0].title = 'Page 1 title'
+      setPageTitles(def)
+      expect(def.pages[0].title).toBe('Page 1 title')
+    })
+  })
 })

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

@@ -22,6 +22,7 @@ import {
 } from '~/src/server/plugins/engine/components/helpers/components.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import { stripParam } from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
 import {
   type AnyFormRequest,
   type FormContext,
@@ -133,7 +134,7 @@ export function proceed(
   const response =
     isReturnAllowed && isPathRelative(returnUrl)
       ? h.redirect(returnUrl)
-      : h.redirect(redirectPath(nextUrl))
+      : h.redirect(redirectPath(nextUrl, stripParam(query, 'returnUrl')))
 
   // Redirect POST to GET to avoid resubmission
   return method === 'post'
@@ -412,14 +413,6 @@ export function setPageTitles(def: FormDefinition) {
 
         page.title = firstFormComponent?.title ?? ''
       }
-
-      if (!page.title) {
-        const formNameMsg = def.name ? ` in form '${def.name}'` : ''
-
-        logger.info(
-          `[pageTitleMissing] Page '${page.path}' has no title${formNameMsg}`
-        )
-      }
     }
   })
 }

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

@@ -74,6 +74,7 @@ export class FormModel {
   lists: FormDefinition['lists']
   sections: FormDefinition['sections'] = []
   name: string
+  formId: string
   values: FormDefinition
   basePath: string
   versionNumber?: number
@@ -100,6 +101,7 @@ export class FormModel {
       basePath: string
       versionNumber?: number
       ordnanceSurveyApiKey?: string
+      formId?: string
     },
     services: Services = defaultServices,
     controllers?: Record<string, typeof PageController>
@@ -152,6 +154,7 @@ export class FormModel {
     this.lists = def.lists
     this.sections = def.sections
     this.name = def.name ?? ''
+    this.formId = options.formId ?? ''
     this.values = result.value
     this.basePath = options.basePath
     this.versionNumber = options.versionNumber

package/src/server/plugins/engine/pageControllers/PageController.test.ts

@@ -24,7 +24,8 @@ describe('PageController', () => {
     const page2 = pages[1]
 
     model = new FormModel(definition, {
-      basePath: testBasePath
+      basePath: testBasePath,
+      formId: 'form-id'
     })
 
     controller1 = new PageController(model, page1)
@@ -61,18 +62,10 @@ describe('PageController', () => {
       })
     })
 
-    it('returns feedback link (from form definition)', () => {
-      expect(controller1).toHaveProperty('feedbackLink', undefined)
-
-      const emailAddress = 'test@feedback.cat'
-
-      model.def.feedback = {
-        emailAddress
-      }
-
+    it('returns feedback link default', () => {
       expect(controller1).toHaveProperty(
         'feedbackLink',
-        `mailto:${emailAddress}`
+        '/form/feedback?formId=form-id'
       )
     })
 

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

@@ -10,7 +10,6 @@ import { type Lifecycle, type RouteOptions, type Server } from '@hapi/hapi'
 
 import { type ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import {
-  encodeUrl,
   getSaveAndExitHelpers,
   getStartPath,
   normalisePath
@@ -119,14 +118,7 @@ export class PageController {
   }
 
   get feedbackLink() {
-    const { def } = this
-
-    // setting the feedbackLink to undefined here for feedback forms prevents the feedback link from being shown
-    const feedbackLink = def.feedback?.emailAddress
-      ? `mailto:${def.feedback.emailAddress}`
-      : def.feedback?.url
-
-    return encodeUrl(feedbackLink)
+    return `/form/feedback?formId=${this.model.formId}`
   }
 
   get phaseTag() {

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

@@ -28,6 +28,7 @@ import {
 } from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { prefillStateFromQueryParameters } from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
 import {
   type AnyFormRequest,
   type FormContext,
@@ -403,6 +404,12 @@ export class QuestionPageController extends PageController {
       const { collection, model, viewName } = this
       const { evaluationState } = context
 
+      // Copy any URL params into the form state (if not already done so)
+      if (await prefillStateFromQueryParameters(request, this)) {
+        // Forward to same page without query string
+        return h.redirect(`${request.url.origin}${request.url.pathname}`)
+      }
+
       const viewModel = this.getViewModel(request, context)
       viewModel.errors = collection.getViewErrors(viewModel.errors)
 

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

@@ -41,13 +41,20 @@ export class StatusPageController extends QuestionPageController {
 
       const slug = request.params.slug
       const { formsService } = this.model.services
-      const { getFormMetadata } = formsService
+      const { getFormMetadata, getFormMetadataById } = formsService
 
       const { submissionGuidance } = await getFormMetadata(slug)
 
+      // Re-read form name if overriding display (for example, in a feedback form)
+      const storedFormId = confirmationState.formId
+      const formName = storedFormId
+        ? (await getFormMetadataById(storedFormId)).title
+        : undefined
+
       return h.view(viewName, {
         ...viewModel,
-        submissionGuidance
+        submissionGuidance,
+        formName
       })
     }
   }

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

@@ -25,6 +25,7 @@ import {
 } from '~/src/server/plugins/engine/models/types.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
 import {
+  type FormConfirmationState,
   type FormContext,
   type FormContextRequest,
   type FormSubmissionState
@@ -152,7 +153,10 @@ export class SummaryPageController extends QuestionPageController {
       )
     }
 
-    await cacheService.setConfirmationState(request, { confirmed: true })
+    await cacheService.setConfirmationState(request, {
+      confirmed: true,
+      formId: context.state.formId
+    } as FormConfirmationState)
 
     // Clear all form data
     await cacheService.clearState(request)