@defra/forms-engine-plugin 0.1.11 → 0.1.13

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

@@ -7,6 +7,7 @@ import {
 } 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,
@@ -26,12 +27,12 @@ export class NumberField extends FormComponent {
   ) {
     super(def, props)
 
-    const { options, schema, title } = def
+    const { options, schema } = def
 
     let formSchema = joi
       .number()
       .custom(getValidatorPrecision(this))
-      .label(title)
+      .label(this.label)
       .required()
 
     if (options.required === false) {
@@ -40,7 +41,9 @@ export class NumberField extends FormComponent {
       const messages = options.customValidationMessages
 
       formSchema = formSchema.empty('').messages({
-        'any.required': messages?.['any.required'] ?? messageTemplate.required
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        'any.required':
+          messages?.['any.required'] ?? (messageTemplate.required as string)
       })
     }
 
@@ -129,6 +132,23 @@ export class NumberField extends FormComponent {
     return NumberField.isNumber(value)
   }
 
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'required', template: messageTemplate.required },
+        { type: 'numberInteger', template: messageTemplate.numberInteger }
+      ],
+      advancedSettingsErrors: [
+        { type: 'numberMin', template: messageTemplate.numberMin },
+        { type: 'numberMax', template: messageTemplate.numberMax },
+        { type: 'numberPrecision', template: messageTemplate.numberPrecision }
+      ]
+    }
+  }
+
   static isNumber(value?: FormStateValue | FormState): value is number {
     return typeof value === 'number'
   }

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

@@ -1,4 +1,5 @@
 import { ComponentType, type RadiosFieldComponent } from '@defra/forms-model'
+import lowerFirst from 'lodash/lowerFirst.js'
 
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import { RadiosField } from '~/src/server/plugins/engine/components/RadiosField.js'
@@ -151,7 +152,7 @@ describe.each([
 
         expect(result.errors).toEqual([
           expect.objectContaining({
-            text: `Select ${def.title.toLowerCase()}`
+            text: `Select ${lowerFirst(def.title)}`
           })
         ])
       })
@@ -284,5 +285,13 @@ describe.each([
         expect(items).toEqual([])
       })
     })
+
+    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/SelectField.test.ts

@@ -1,4 +1,5 @@
 import { ComponentType, type SelectFieldComponent } from '@defra/forms-model'
+import lowerFirst from 'lodash/lowerFirst.js'
 
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import { SelectField } from '~/src/server/plugins/engine/components/SelectField.js'
@@ -152,7 +153,7 @@ describe.each([
 
         expect(result.errors).toEqual([
           expect.objectContaining({
-            text: `Select ${def.title.toLowerCase()}`
+            text: `Select ${lowerFirst(def.title)}`
           })
         ])
       })

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

@@ -1,6 +1,8 @@
 import { ListFormComponent } from '~/src/server/plugins/engine/components/ListFormComponent.js'
 import { type ListItem } from '~/src/server/plugins/engine/components/types.js'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
 import {
+  type ErrorMessageTemplateList,
   type FormPayload,
   type FormSubmissionError
 } from '~/src/server/plugins/engine/types.js'
@@ -40,4 +42,16 @@ export class SelectionControlField extends ListFormComponent {
       items
     }
   }
+
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'selectRequired', template: messageTemplate.selectRequired }
+      ],
+      advancedSettingsErrors: []
+    }
+  }
 }

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

@@ -29,6 +29,7 @@ describe('TelephoneNumberField', () => {
     beforeEach(() => {
       def = {
         title: 'Example telephone number field',
+        shortDescription: 'Example telephone number',
         name: 'myComponent',
         type: ComponentType.TelephoneNumberField,
         options: {}
@@ -39,7 +40,7 @@ describe('TelephoneNumberField', () => {
     })
 
     describe('Schema', () => {
-      it('uses component title as label', () => {
+      it('uses component short description as label', () => {
         const { formSchema } = collection
         const { keys } = formSchema.describe()
 
@@ -47,7 +48,7 @@ describe('TelephoneNumberField', () => {
           'myComponent',
           expect.objectContaining({
             flags: expect.objectContaining({
-              label: 'Example telephone number field'
+              label: 'Example telephone number'
             })
           })
         )
@@ -121,6 +122,25 @@ describe('TelephoneNumberField', () => {
       it('adds errors for empty value', () => {
         const result = collection.validate(getFormData(''))
 
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: 'Enter example telephone number'
+          })
+        ])
+      })
+
+      it('adds errors for empty value given no short description exists', () => {
+        def = {
+          title: 'Example telephone number field',
+          name: 'myComponent',
+          type: ComponentType.TelephoneNumberField,
+          options: {}
+        } satisfies TelephoneNumberFieldComponent
+
+        collection = new ComponentCollection([def], { model })
+
+        const result = collection.validate(getFormData(''))
+
         expect(result.errors).toEqual([
           expect.objectContaining({
             text: 'Enter example telephone number field'
@@ -215,6 +235,14 @@ describe('TelephoneNumberField', () => {
         )
       })
     })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).toBeEmpty()
+      })
+    })
   })
 
   describe('Validation', () => {

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

@@ -3,7 +3,9 @@ import joi, { type StringSchema } from 'joi'
 
 import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
 import { addClassOptionIfNone } from '~/src/server/plugins/engine/components/helpers.js'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
 import {
+  type ErrorMessageTemplateList,
   type FormPayload,
   type FormSubmissionError
 } from '~/src/server/plugins/engine/types.js'
@@ -21,13 +23,13 @@ export class TelephoneNumberField extends FormComponent {
   ) {
     super(def, props)
 
-    const { options, title } = def
+    const { options } = def
 
     let formSchema = joi
       .string()
       .trim()
       .pattern(PATTERN)
-      .label(title)
+      .label(this.label)
       .required()
 
     if (options.required === false) {
@@ -64,4 +66,17 @@ export class TelephoneNumberField extends FormComponent {
       type: 'tel'
     }
   }
+
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'required', template: messageTemplate.required },
+        { type: 'format', template: messageTemplate.format }
+      ],
+      advancedSettingsErrors: []
+    }
+  }
 }

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

@@ -37,7 +37,7 @@ describe('TextField', () => {
     })
 
     describe('Schema', () => {
-      it('uses component title as label', () => {
+      it('uses component title as label as default', () => {
         const { formSchema } = collection
         const { keys } = formSchema.describe()
 
@@ -196,10 +196,42 @@ describe('TextField', () => {
         )
       })
     })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).not.toBeEmpty()
+      })
+    })
   })
 
   describe('Validation', () => {
     describe.each([
+      {
+        description: 'Use short description if it exists',
+        component: {
+          title: 'What is your example text?',
+          shortDescription: 'Your example text',
+          name: 'myComponent',
+          type: ComponentType.TextField,
+          options: {},
+          schema: {}
+        } satisfies TextFieldComponent,
+        assertions: [
+          {
+            input: getFormData(''),
+            output: {
+              value: getFormData(''),
+              errors: [
+                expect.objectContaining({
+                  text: 'Enter your example text'
+                })
+              ]
+            }
+          }
+        ]
+      },
       {
         description: 'Trim empty spaces',
         component: {

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

@@ -8,7 +8,9 @@ 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 FormState,
   type FormStateValue,
   type FormSubmissionState
@@ -30,10 +32,10 @@ export class TextField extends FormComponent {
   ) {
     super(def, props)
 
-    const { options, title } = def
+    const { options } = def
     const schema = 'schema' in def ? def.schema : {}
 
-    let formSchema = joi.string().trim().label(title).required()
+    let formSchema = joi.string().trim().label(this.label).required()
 
     if (options.required === false) {
       formSchema = formSchema.allow('')
@@ -90,6 +92,19 @@ export class TextField extends FormComponent {
     return TextField.isText(value)
   }
 
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [{ type: 'required', template: messageTemplate.required }],
+      advancedSettingsErrors: [
+        { type: 'min', template: messageTemplate.min },
+        { type: 'max', template: messageTemplate.max }
+      ]
+    }
+  }
+
   static isText(value?: FormStateValue | FormState): value is string {
     return isFormValue(value) && typeof value === 'string'
   }

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

@@ -465,6 +465,14 @@ describe('UkAddressField', () => {
         })
       })
     })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).toBeEmpty()
+      })
+    })
   })
 
   describe('Validation', () => {
@@ -509,7 +517,8 @@ describe('UkAddressField', () => {
               postcode: ' WA4 1HT'
             }),
             output: {
-              value: getFormData(address)
+              value: getFormData(address),
+              errors: undefined
             }
           },
           {
@@ -521,7 +530,8 @@ describe('UkAddressField', () => {
               postcode: 'WA4 1HT '
             }),
             output: {
-              value: getFormData(address)
+              value: getFormData(address),
+              errors: undefined
             }
           },
           {
@@ -533,7 +543,8 @@ describe('UkAddressField', () => {
               postcode: ' WA4 1HT \n\n'
             }),
             output: {
-              value: getFormData(address)
+              value: getFormData(address),
+              errors: undefined
             }
           }
         ]
@@ -661,6 +672,35 @@ describe('UkAddressField', () => {
                 })
               ]
             }
+          },
+          {
+            input: getFormData({
+              addressLine1: '',
+              addressLine2: '',
+              town: '',
+              county: '',
+              postcode: postcodeInvalid
+            }),
+            output: {
+              value: getFormData({
+                addressLine1: '',
+                addressLine2: '',
+                town: '',
+                county: '',
+                postcode: postcodeInvalid
+              }),
+              errors: [
+                expect.objectContaining({
+                  text: 'Enter address line 1'
+                }),
+                expect.objectContaining({
+                  text: 'Enter town or city'
+                }),
+                expect.objectContaining({
+                  text: 'Enter a valid postcode'
+                })
+              ]
+            }
           }
         ]
       }
@@ -676,6 +716,9 @@ describe('UkAddressField', () => {
         ({ input, output }) => {
           const result = collection.validate(input)
           expect(result).toEqual(output)
+
+          const errors = collection.getErrors(result.errors)
+          expect(errors).toEqual(output.errors)
         }
       )
     })

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

@@ -9,6 +9,7 @@ import {
 import { TextField } from '~/src/server/plugins/engine/components/TextField.js'
 import { type QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
 import {
+  type ErrorMessageTemplateList,
   type FormPayload,
   type FormState,
   type FormStateValue,
@@ -123,6 +124,18 @@ export class UkAddressField extends FormComponent {
     return Object.values(value).filter(Boolean)
   }
 
+  /**
+   * Returns one error per child field
+   */
+  getViewErrors(
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
+    return this.getErrors(errors)?.filter(
+      (error, index, self) =>
+        index === self.findIndex((err) => err.name === error.name)
+    )
+  }
+
   getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
     const { collection, name, options } = this
 
@@ -163,6 +176,21 @@ export class UkAddressField extends FormComponent {
     return UkAddressField.isUkAddress(value)
   }
 
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'required', template: 'Enter address line 1' },
+        { type: 'required', template: 'Enter town or city' },
+        { type: 'required', template: 'Enter postcode' },
+        { type: 'format', template: 'Enter valid postcode' }
+      ],
+      advancedSettingsErrors: []
+    }
+  }
+
   static isUkAddress(
     value?: FormStateValue | FormState
   ): value is UkAddressState {

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

@@ -121,7 +121,7 @@ describe('YesNoField', () => {
 
       expect(result.errors).toEqual([
         expect.objectContaining({
-          text: 'Select example yes/no'
+          text: 'Example yes/no - select yes or no'
         })
       ])
     })
@@ -245,4 +245,12 @@ describe('YesNoField', () => {
       )
     })
   })
+
+  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/YesNoField.ts

@@ -2,6 +2,9 @@ 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'
+import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
+import { type ErrorMessageTemplateList } from '~/src/server/plugins/engine/types.js'
+import { convertToLanguageMessages } from '~/src/server/utils/type-utils.js'
 
 /**
  * @description
@@ -25,7 +28,28 @@ export class YesNoField extends SelectionControlField {
       formSchema = formSchema.optional()
     }
 
+    formSchema = formSchema.messages(
+      convertToLanguageMessages({
+        'any.required': messageTemplate.selectYesNoRequired
+      })
+    )
+
     this.formSchema = formSchema
     this.options = options
   }
+
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        {
+          type: 'selectYesNoRequired',
+          template: messageTemplate.selectYesNoRequired
+        }
+      ],
+      advancedSettingsErrors: []
+    }
+  }
 }

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

@@ -0,0 +1,24 @@
+import { type ComponentDef } from '@defra/forms-model'
+
+import { createComponent } from '~/src/server/plugins/engine/components/helpers.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import definition from '~/test/form/definitions/basic.js'
+
+const formModel = new FormModel(definition, {
+  basePath: 'test'
+})
+
+describe('helpers tests', () => {
+  test('should throw if invalid type', () => {
+    expect(() =>
+      createComponent(
+        {
+          type: 'invalid-type'
+        } as unknown as ComponentDef,
+        {
+          model: formModel
+        }
+      )
+    ).toThrow('Component type invalid-type does not exist')
+  })
+})

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

@@ -55,6 +55,8 @@ export type Component = InstanceType<
 // Field component instances only
 export type Field = InstanceType<
   | typeof Components.AutocompleteField
+  | typeof Components.RadiosField
+  | typeof Components.YesNoField
   | typeof Components.CheckboxesField
   | typeof Components.DatePartsField
   | typeof Components.EmailAddressField
@@ -72,10 +74,43 @@ export type Field = InstanceType<
 export type Guidance = InstanceType<
   | typeof Components.Details
   | typeof Components.Html
+  | typeof Components.Markdown
   | typeof Components.InsetText
   | typeof Components.List
 >
 
+// List component instances only
+export type ListField = InstanceType<
+  | typeof Components.AutocompleteField
+  | typeof Components.CheckboxesField
+  | typeof Components.RadiosField
+  | typeof Components.SelectField
+  | typeof Components.YesNoField
+>
+
+/**
+ * Filter known components with lists
+ */
+export function hasListFormField(
+  field?: Partial<Component>
+): field is ListFormComponent {
+  return !!field && isListFieldType(field.type)
+}
+
+export function isListFieldType(
+  type?: ComponentType
+): type is ListField['type'] {
+  const allowedTypes = [
+    ComponentType.AutocompleteField,
+    ComponentType.CheckboxesField,
+    ComponentType.RadiosField,
+    ComponentType.SelectField,
+    ComponentType.YesNoField
+  ]
+
+  return !!type && allowedTypes.includes(type)
+}
+
 /**
  * Create field instance for each {@link ComponentDef} type
  */
@@ -118,6 +153,10 @@ export function createComponent(
       component = new Components.List(def, options)
       break
 
+    case ComponentType.Markdown:
+      component = new Components.Markdown(def, options)
+      break
+
     case ComponentType.MultilineTextField:
       component = new Components.MultilineTextField(def, options)
       break

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

@@ -12,6 +12,7 @@ export { EmailAddressField } from '~/src/server/plugins/engine/components/EmailA
 export { Html } from '~/src/server/plugins/engine/components/Html.js'
 export { InsetText } from '~/src/server/plugins/engine/components/InsetText.js'
 export { List } from '~/src/server/plugins/engine/components/List.js'
+export { Markdown } from '~/src/server/plugins/engine/components/Markdown.js'
 export { MultilineTextField } from '~/src/server/plugins/engine/components/MultilineTextField.js'
 export { NumberField } from '~/src/server/plugins/engine/components/NumberField.js'
 export { RadiosField } from '~/src/server/plugins/engine/components/RadiosField.js'

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

@@ -1,8 +1,8 @@
 import { join, parse } from 'node:path'
 
 import { type FormDefinition } from '@defra/forms-model'
-import { type ServerRegisterPluginObject } from '@hapi/hapi'
 
+import { FORM_PREFIX } from '~/src/server/constants.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import {
   plugin,
@@ -19,14 +19,24 @@ export const configureEnginePlugin = async ({
   formFilePath,
   services,
   controllers
-}: RouteConfig = {}): Promise<ServerRegisterPluginObject<PluginOptions>> => {
+}: RouteConfig = {}): Promise<{
+  plugin: typeof plugin
+  options: PluginOptions
+}> => {
   let model: FormModel | undefined
 
   if (formFileName && formFilePath) {
     const definition = await getForm(join(formFilePath, formFileName))
     const { name } = parse(formFileName)
 
-    model = new FormModel(definition, { basePath: name }, services, controllers)
+    const initialBasePath = `${FORM_PREFIX}${name}`
+
+    model = new FormModel(
+      definition,
+      { basePath: initialBasePath },
+      services,
+      controllers
+    )
   }
 
   return {