@defra/forms-engine-plugin 0.1.11 → 0.1.12

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

@@ -2,6 +2,7 @@ import {
   ComponentType,
   type AutocompleteFieldComponent
 } from '@defra/forms-model'
+import lowerFirst from 'lodash/lowerFirst.js'
 
 import { AutocompleteField } from '~/src/server/plugins/engine/components/AutocompleteField.js'
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
@@ -32,7 +33,8 @@ describe.each([
     options: {
       list: listString,
       examples: listStringExamples,
-      allow: ['1', '2', '3', '4']
+      allow: ['1', '2', '3', '4'],
+      shortDescription: 'My string list'
     }
   },
   {
@@ -47,7 +49,8 @@ describe.each([
     options: {
       list: listNumber,
       examples: listNumberExamples,
-      allow: [1, 2, 3, 4]
+      allow: [1, 2, 3, 4],
+      shortDescription: 'My number list'
     }
   }
 ])('AutocompleteField: $component.title', ({ component: def, options }) => {
@@ -153,7 +156,35 @@ describe.each([
 
         expect(result.errors).toEqual([
           expect.objectContaining({
-            text: `Enter ${def.title.toLowerCase()}`
+            text: `Enter ${lowerFirst(def.title)}`
+          })
+        ])
+      })
+
+      it('adds errors for empty value if shortDescription exists', () => {
+        collection = new ComponentCollection(
+          [{ ...def, shortDescription: options.shortDescription }],
+          { model }
+        )
+        const result = collection.validate(getFormData(''))
+
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: `Enter ${lowerFirst(options.shortDescription)}`
+          })
+        ])
+      })
+
+      it('adds errors for empty value if shortDescription exists but is empty', () => {
+        collection = new ComponentCollection(
+          [{ ...def, shortDescription: '' }],
+          { model }
+        )
+        const result = collection.validate(getFormData(''))
+
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: `Enter ${lowerFirst(def.title)}`
           })
         ])
       })
@@ -290,5 +321,42 @@ describe.each([
         expect(items).toEqual([])
       })
     })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).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.AutocompleteField,
+            list: 'ABCE',
+            options: {}
+          } satisfies AutocompleteFieldComponent,
+          assertions: [
+            {
+              input: getFormData(''),
+              output: {
+                value: getFormData(''),
+                errors: [
+                  expect.objectContaining({
+                    text: 'Enter your example text'
+                  })
+                ]
+              }
+            }
+          ]
+        }
+      ])
+    })
   })
 })

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

@@ -23,8 +23,12 @@ export class AutocompleteField extends SelectField {
       const messages = options.customValidationMessages
 
       formSchema = formSchema.messages({
-        'any.only': messages?.['any.only'] ?? messageTemplate.required,
-        'any.required': messages?.['any.required'] ?? messageTemplate.required
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        'any.only':
+          messages?.['any.only'] ?? (messageTemplate.required as string),
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        'any.required':
+          messages?.['any.required'] ?? (messageTemplate.required as string)
       })
     }
 

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

@@ -2,6 +2,8 @@ import {
   ComponentType,
   type CheckboxesFieldComponent
 } from '@defra/forms-model'
+import { toLower } from 'lodash'
+import lowerFirst from 'lodash/lowerFirst.js'
 import { outdent } from 'outdent'
 
 import { CheckboxesField } from '~/src/server/plugins/engine/components/CheckboxesField.js'
@@ -23,7 +25,8 @@ import { getFormData, getFormState } from '~/test/helpers/component-helpers.js'
 describe.each([
   {
     component: {
-      title: 'String list',
+      title: 'String list title',
+      shortDescription: 'String list',
       name: 'myComponent',
       type: ComponentType.CheckboxesField,
       list: 'listString',
@@ -31,6 +34,7 @@ describe.each([
     } satisfies CheckboxesFieldComponent,
 
     options: {
+      label: 'string list',
       list: listString,
       examples: listStringExamples,
       allow: ['1', '2', '3', '4'],
@@ -39,14 +43,34 @@ describe.each([
   },
   {
     component: {
-      title: 'Number list',
+      title: 'String list title',
+      shortDescription: 'String list',
       name: 'myComponent',
       type: ComponentType.CheckboxesField,
+      list: 'listString',
+      options: {}
+    } satisfies CheckboxesFieldComponent,
+
+    options: {
+      label: 'string list',
+      list: listString,
+      examples: listStringExamples,
+      allow: ['1', '2', '3', '4'],
+      deny: ['5', '6', '7', '8']
+    }
+  },
+  {
+    component: {
+      title: 'Number list title',
+      name: 'myComponent',
+      shortDescription: 'Number list',
+      type: ComponentType.CheckboxesField,
       list: 'listNumber',
       options: {}
     } satisfies CheckboxesFieldComponent,
 
     options: {
+      label: 'number list',
       list: listNumber,
       examples: listNumberExamples,
       allow: [1, 2, 3, 4],
@@ -72,14 +96,14 @@ describe.each([
 
   describe('Defaults', () => {
     describe('Schema', () => {
-      it('uses component title as label', () => {
+      it('uses component short description as label', () => {
         const { formSchema } = collection
         const { keys } = formSchema.describe()
 
         expect(keys).toHaveProperty(
           'myComponent',
           expect.objectContaining({
-            flags: expect.objectContaining({ label: def.title })
+            flags: expect.objectContaining({ label: def.shortDescription })
           })
         )
       })
@@ -157,7 +181,7 @@ describe.each([
               {
                 allow: options.allow,
                 flags: {
-                  label: def.title,
+                  label: def.shortDescription,
                   only: true
                 },
                 type: options.list.type
@@ -172,7 +196,7 @@ describe.each([
 
         expect(result.errors).toEqual([
           expect.objectContaining({
-            text: `Select ${def.title.toLowerCase()}`
+            text: `Select ${lowerFirst(options.label)}`
           })
         ])
       })
@@ -200,7 +224,7 @@ describe.each([
 
           expect(result.errors).toEqual([
             expect.objectContaining({
-              text: `Select ${def.title.toLowerCase()}`
+              text: `Select ${toLower(def.shortDescription)}`
             })
           ])
         }
@@ -213,7 +237,7 @@ describe.each([
 
           expect(result.errors).toEqual([
             expect.objectContaining({
-              text: `Select ${def.title.toLowerCase()}`
+              text: `Select ${lowerFirst(options.label)}`
             })
           ])
         }
@@ -375,5 +399,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/CheckboxesField.ts

@@ -23,16 +23,20 @@ export class CheckboxesField extends SelectionControlField {
     super(def, props)
 
     const { listType: type } = this
-    const { options, title } = def
+    const { options } = def
 
     let formSchema =
       type === 'string' ? joi.array<string>() : joi.array<number>()
 
     const itemsSchema = joi[type]()
       .valid(...this.values)
-      .label(title)
+      .label(this.label)
 
-    formSchema = formSchema.items(itemsSchema).single().label(title).required()
+    formSchema = formSchema
+      .items(itemsSchema)
+      .single()
+      .label(this.label)
+      .required()
 
     if (options.required === false) {
       formSchema = formSchema.optional()

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

@@ -124,7 +124,7 @@ export class ComponentCollection {
         }
 
         // Update error with parent title
-        error.local.title ??= parent?.title
+        error.local.title ??= parent?.label
 
         return error
       })
@@ -212,25 +212,22 @@ export class ComponentCollection {
     return context
   }
 
+  /**
+   * Get all errors for all fields in this collection
+   */
   getErrors(errors?: FormSubmissionError[]): FormSubmissionError[] | undefined {
-    const { fields } = this
-
-    const list: FormSubmissionError[] = []
-
-    // Add only one error per field
-    for (const field of fields) {
-      const error = field.getError(errors)
-
-      if (error) {
-        list.push(error)
-      }
-    }
-
-    if (!list.length) {
-      return
-    }
+    return this.getFieldErrors((field) => field.getErrors(errors), errors)
+  }
 
-    return list
+  /**
+   * Get view errors for all fields in this collection.
+   * For most fields this means filtering to the first error in the list.
+   * Composite fields like UKAddress can choose to return more than one error.
+   */
+  getViewErrors(
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
+    return this.getFieldErrors((field) => field.getViewErrors(errors), errors)
   }
 
   getViewModel(
@@ -266,6 +263,36 @@ export class ComponentCollection {
       errors: this.page?.getErrors(details) ?? getErrors(details)
     }
   }
+
+  /**
+   * Helper to get errors from all fields
+   */
+  private getFieldErrors(
+    callback: (field: Field) => FormSubmissionError[] | undefined,
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
+    const { fields } = this
+
+    if (!errors?.length) {
+      return
+    }
+
+    const list: FormSubmissionError[] = []
+
+    for (const field of fields) {
+      const fieldErrors = callback(field)
+
+      if (fieldErrors?.length) {
+        list.push(...fieldErrors)
+      }
+    }
+
+    if (!list.length) {
+      return
+    }
+
+    return list
+  }
 }
 
 /**

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

@@ -31,6 +31,7 @@ describe('DatePartsField', () => {
     beforeEach(() => {
       def = {
         title: 'Example date parts field',
+        shortDescription: 'Example date parts',
         name: 'myComponent',
         type: ComponentType.DatePartsField,
         options: {}
@@ -199,7 +200,7 @@ describe('DatePartsField', () => {
         expect(result3.errors).toBeUndefined()
       })
 
-      it('adds errors for empty value', () => {
+      it('adds errors for empty value when short description exists', () => {
         const result = collection.validate(
           getFormData({
             day: '',
@@ -210,13 +211,13 @@ describe('DatePartsField', () => {
 
         expect(result.errors).toEqual([
           expect.objectContaining({
-            text: 'Example date parts field must include a day'
+            text: 'Example date parts must include a day'
           }),
           expect.objectContaining({
-            text: 'Example date parts field must include a month'
+            text: 'Example date parts must include a month'
           }),
           expect.objectContaining({
-            text: 'Example date parts field must include a year'
+            text: 'Example date parts must include a year'
           })
         ])
       })
@@ -409,6 +410,14 @@ describe('DatePartsField', () => {
         })
       })
     })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).not.toBeEmpty()
+      })
+    })
   })
 
   describe('Validation', () => {

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

@@ -1,11 +1,6 @@
 import { ComponentType, type DatePartsFieldComponent } from '@defra/forms-model'
 import { add, format, isValid, parse, startOfToday, sub } from 'date-fns'
-import {
-  type Context,
-  type CustomValidator,
-  type LanguageMessages,
-  type ObjectSchema
-} from 'joi'
+import { type Context, type CustomValidator, type ObjectSchema } from 'joi'
 
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import {
@@ -17,12 +12,14 @@ import { NumberField } from '~/src/server/plugins/engine/components/NumberField.
 import { type DateInputItem } from '~/src/server/plugins/engine/components/types.js'
 import { messageTemplate } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
 import {
+  type ErrorMessageTemplateList,
   type FormPayload,
   type FormState,
   type FormStateValue,
   type FormSubmissionError,
   type FormSubmissionState
 } from '~/src/server/plugins/engine/types.js'
+import { convertToLanguageMessages } from '~/src/server/utils/type-utils.js'
 
 export class DatePartsField extends FormComponent {
   declare options: DatePartsFieldComponent['options']
@@ -40,15 +37,17 @@ export class DatePartsField extends FormComponent {
 
     const isRequired = options.required !== false
 
-    const customValidationMessages: LanguageMessages = {
+    const customValidationMessages = convertToLanguageMessages({
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
       'any.required': messageTemplate.objectMissing,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
       'number.base': messageTemplate.objectMissing,
       'number.precision': messageTemplate.dateFormat,
       'number.integer': messageTemplate.dateFormat,
       'number.unsafe': messageTemplate.dateFormat,
       'number.min': messageTemplate.dateFormat,
       'number.max': messageTemplate.dateFormat
-    }
+    })
 
     this.collection = new ComponentCollection(
       [
@@ -192,6 +191,28 @@ export class DatePartsField extends FormComponent {
     return DatePartsField.isDateParts(value)
   }
 
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        { type: 'required', template: messageTemplate.required },
+        { type: 'dateFormat', template: messageTemplate.dateFormat },
+        { type: 'dateFormatDay', template: '{{#label}} must include a day' },
+        {
+          type: 'dateFormatMonth',
+          template: '{{#label}} must include a month'
+        },
+        { type: 'dateFormatYear', template: '{{#label}} must include a year' }
+      ],
+      advancedSettingsErrors: [
+        { type: 'dateMin', template: messageTemplate.dateMin },
+        { type: 'dateMax', template: messageTemplate.dateMax }
+      ]
+    }
+  }
+
   static isDateParts(
     value?: FormStateValue | FormState
   ): value is DatePartsState {

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

@@ -29,6 +29,7 @@ describe('EmailAddressField', () => {
     beforeEach(() => {
       def = {
         title: 'Example email address field',
+        shortDescription: 'Example email address',
         name: 'myComponent',
         type: ComponentType.EmailAddressField,
         options: {}
@@ -47,7 +48,7 @@ describe('EmailAddressField', () => {
           'myComponent',
           expect.objectContaining({
             flags: expect.objectContaining({
-              label: 'Example email address field'
+              label: 'Example email address'
             })
           })
         )
@@ -111,6 +112,24 @@ describe('EmailAddressField', () => {
       it('adds errors for empty value', () => {
         const result = collection.validate(getFormData(''))
 
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: 'Enter example email address'
+          })
+        ])
+      })
+
+      it('adds errors for empty value given no shortDescription', () => {
+        def = {
+          title: 'Example email address field',
+          name: 'myComponent',
+          type: ComponentType.EmailAddressField,
+          options: {}
+        } satisfies EmailAddressFieldComponent
+
+        collection = new ComponentCollection([def], { model })
+        const result = collection.validate(getFormData(''))
+
         expect(result.errors).toEqual([
           expect.objectContaining({
             text: 'Enter example email address field'
@@ -205,6 +224,14 @@ describe('EmailAddressField', () => {
         )
       })
     })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).toBeEmpty()
+      })
+    })
   })
 
   describe('Validation', () => {
@@ -269,6 +296,29 @@ describe('EmailAddressField', () => {
           }
         ]
       },
+      {
+        description: 'Email address validation',
+        component: {
+          title: 'Example email address field',
+          shortDescription: 'Example email address',
+          name: 'myComponent',
+          type: ComponentType.EmailAddressField,
+          options: {}
+        } satisfies EmailAddressFieldComponent,
+        assertions: [
+          {
+            input: getFormData('defra.helpline'),
+            output: {
+              value: getFormData('defra.helpline'),
+              errors: [
+                expect.objectContaining({
+                  text: 'Enter example email address in the correct format'
+                })
+              ]
+            }
+          }
+        ]
+      },
       {
         description: 'Custom validation message',
         component: {

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

@@ -2,7 +2,9 @@ import { type EmailAddressFieldComponent } from '@defra/forms-model'
 import joi from 'joi'
 
 import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.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'
@@ -16,9 +18,9 @@ export class EmailAddressField extends FormComponent {
   ) {
     super(def, props)
 
-    const { options, title } = def
+    const { options } = def
 
-    let formSchema = joi.string().email().trim().label(title).required()
+    let formSchema = joi.string().email().trim().label(this.label).required()
 
     if (options.required === false) {
       formSchema = formSchema.allow('')
@@ -52,4 +54,17 @@ export class EmailAddressField extends FormComponent {
       type: 'email'
     }
   }
+
+  /**
+   * 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/FileUploadField.test.ts

@@ -157,6 +157,7 @@ describe('FileUploadField', () => {
     beforeEach(() => {
       def = {
         title: 'Example file upload field',
+        shortDescription: 'Example file upload',
         name: 'myComponent',
         type: ComponentType.FileUploadField,
         options: {},
@@ -169,7 +170,32 @@ describe('FileUploadField', () => {
     })
 
     describe('Schema', () => {
+      it('uses component short description as label', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            flags: expect.objectContaining({
+              label: 'Example file upload'
+            })
+          })
+        )
+      })
+
       it('uses component title as label', () => {
+        def = {
+          title: 'Example file upload field',
+          name: 'myComponent',
+          type: ComponentType.FileUploadField,
+          options: {},
+          schema: {}
+        } satisfies FileUploadFieldComponent
+
+        page = createPage(model, definition.pages[0])
+        collection = new ComponentCollection([def], { page, model })
+
         const { formSchema } = collection
         const { keys } = formSchema.describe()
 
@@ -246,6 +272,25 @@ describe('FileUploadField', () => {
       it('adds errors for empty value', () => {
         const result = collection.validate(getFormData())
 
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: 'Select example file upload'
+          })
+        ])
+      })
+
+      it('adds errors for empty value with no shortDescription', () => {
+        def = {
+          title: 'Example file upload field',
+          name: 'myComponent',
+          type: ComponentType.FileUploadField,
+          options: {},
+          schema: {}
+        } satisfies FileUploadFieldComponent
+
+        collection = new ComponentCollection([def], { model })
+        const result = collection.validate(getFormData())
+
         expect(result.errors).toEqual([
           expect.objectContaining({
             text: 'Select example file upload field'
@@ -545,6 +590,14 @@ describe('FileUploadField', () => {
         )
       })
     })
+
+    describe('AllPossibleErrors', () => {
+      it('should return errors', () => {
+        const errors = field.getAllPossibleErrors()
+        expect(errors.baseErrors).not.toBeEmpty()
+        expect(errors.advancedSettingsErrors).not.toBeEmpty()
+      })
+    })
   })
 
   describe('Validation', () => {