@defra/forms-engine-plugin 4.4.0 → 4.5.1

package/src/server/plugins/engine/beta/form-context.ts

@@ -5,7 +5,8 @@ import { isEqual } from 'date-fns'
 import { PREVIEW_PATH_PREFIX } from '~/src/server/constants.js'
 import {
   checkEmailAddressForLiveFormSubmission,
-  getCacheService
+  getCacheService,
+  getFormVersion
 } from '~/src/server/plugins/engine/helpers.js'
 import { FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
@@ -27,7 +28,6 @@ export interface FormModelOptions {
   services?: Services
   controllers?: Record<string, typeof PageController>
   basePath?: string
-  versionNumber?: number
   ordnanceSurveyApiKey?: string
   formId?: string
   routePrefix?: string
@@ -53,8 +53,6 @@ export async function getFormModel(
   const formState = resolveState(state)
 
   const metadata = await formsService.getFormMetadata(slug)
-  const versionNumber =
-    options.versionNumber ?? metadata.versions?.[0]?.versionNumber
 
   const definition = await formsService.getFormDefinition(
     metadata.id,
@@ -67,6 +65,8 @@ export async function getFormModel(
     )
   }
 
+  const versionNumber = getFormVersion(definition)?.versionNumber
+
   return new FormModel(
     definition,
     {
@@ -182,14 +182,15 @@ export async function resolveFormModel(
     const routePrefix =
       options.routePrefix ?? server.realm.modifiers.route.prefix
 
+    const versionNumber = getFormVersion(definition)?.versionNumber
+
     const model = new FormModel(
       definition,
       {
         basePath:
           options.basePath ??
           buildBasePath(routePrefix, slug, formState, isPreview),
-        versionNumber:
-          options.versionNumber ?? metadata.versions?.[0]?.versionNumber,
+        versionNumber,
         ordnanceSurveyApiKey: options.ordnanceSurveyApiKey,
         formId: options.formId ?? metadata.id
       },

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

@@ -405,7 +405,7 @@ describe('FileUploadField', () => {
                     actions: {
                       items: [
                         {
-                          href: `/test/file-upload-component/${validState[0].uploadId}/confirm-delete`,
+                          href: `/test/file-upload-component/${validState[0].status.form.file.fileId}/confirm-delete`,
                           text: 'Remove',
                           attributes: { id: 'myComponent__0' },
                           classes: 'govuk-link--no-visited-state',
@@ -424,7 +424,7 @@ describe('FileUploadField', () => {
                     actions: {
                       items: [
                         {
-                          href: `/test/file-upload-component/${validState[1].uploadId}/confirm-delete`,
+                          href: `/test/file-upload-component/${validState[1].status.form.file.fileId}/confirm-delete`,
                           text: 'Remove',
                           attributes: { id: 'myComponent__1' },
                           classes: 'govuk-link--no-visited-state',
@@ -443,7 +443,7 @@ describe('FileUploadField', () => {
                     actions: {
                       items: [
                         {
-                          href: `/test/file-upload-component/${validState[2].uploadId}/confirm-delete`,
+                          href: `/test/file-upload-component/${validState[2].status.form.file.fileId}/confirm-delete`,
                           text: 'Remove',
                           attributes: { id: 'myComponent__2' },
                           classes: 'govuk-link--no-visited-state',
@@ -454,7 +454,8 @@ describe('FileUploadField', () => {
                   }
                 ]
               }
-            }
+            },
+            multiple: true
           })
         )
       })
@@ -543,7 +544,7 @@ describe('FileUploadField', () => {
                     actions: {
                       items: [
                         {
-                          href: `/test/file-upload-component/${validState[2].uploadId}/confirm-delete`,
+                          href: `/test/file-upload-component/${validState[2].status.form.file.fileId}/confirm-delete`,
                           text: 'Remove',
                           attributes: { id: 'myComponent__0' },
                           classes: 'govuk-link--no-visited-state',
@@ -554,7 +555,8 @@ describe('FileUploadField', () => {
                   }
                 ]
               }
-            }
+            },
+            multiple: true
           })
         )
       })
@@ -583,7 +585,7 @@ describe('FileUploadField', () => {
                     actions: {
                       items: [
                         {
-                          href: `/test/file-upload-component/${validState[2].uploadId}/confirm-delete`,
+                          href: `/test/file-upload-component/${validState[2].status.form.file.fileId}/confirm-delete`,
                           text: 'Remove',
                           attributes: { id: 'myComponent__0' },
                           classes: 'govuk-link--no-visited-state',
@@ -594,7 +596,8 @@ describe('FileUploadField', () => {
                   }
                 ]
               }
-            }
+            },
+            multiple: true
           })
         )
       })

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

@@ -73,9 +73,12 @@ export const tempStatusSchema = joi
       .valid(UploadStatus.ready, UploadStatus.pending)
       .required(),
     metadata: metadataSchema,
-    form: joi.object().required().keys({
-      file: tempFileSchema
-    }),
+    form: joi
+      .object()
+      .required()
+      .keys({
+        file: joi.array().items(tempFileSchema).single().required()
+      }),
     numberOfRejectedFiles: joi.number().optional()
   })
   .required()
@@ -191,7 +194,7 @@ export class FileUploadField extends FormComponent {
     errors?: FormSubmissionError[],
     query: FormQuery = {}
   ) {
-    const { options, page } = this
+    const { options, page, schema } = this
 
     // Allow preview URL direct access
     const isForceAccess = 'force' in query
@@ -233,7 +236,7 @@ export class FileUploadField extends FormComponent {
 
       // Remove summary list actions from previews
       if (!isForceAccess) {
-        const path = `/${item.uploadId}/confirm-delete`
+        const path = `/${file.fileId}/confirm-delete`
         const href = page?.getHref(`${page.path}${path}`) ?? '#'
 
         items.push({
@@ -263,6 +266,9 @@ export class FileUploadField extends FormComponent {
       attributes.accept = options.accept
     }
 
+    // Allow multiple file selection when schema permits more than 1 file
+    const allowsMultiple = schema.max !== 1 && schema.length !== 1
+
     const summaryList: SummaryList = {
       classes: 'govuk-summary-list--long-key',
       rows
@@ -277,6 +283,9 @@ export class FileUploadField extends FormComponent {
       // Override the component name we send to CDP
       name: 'file',
 
+      // Enable multi-file selection in the file picker
+      ...(allowsMultiple && { multiple: true }),
+
       upload: {
         count,
         summaryList

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

@@ -16,6 +16,7 @@ import { type Schema, type ValidationErrorItem } from 'joi'
 import { Liquid } from 'liquidjs'
 
 import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
+import { FORM_VERSION_METADATA_KEY } from '~/src/server/constants.js'
 import {
   getAnswer,
   type Field
@@ -416,6 +417,22 @@ export function handleLegacyRedirect(h: ResponseToolkit, targetUrl: string) {
  * If the page doesn't have a title, set it from the title of the first form component
  * @param def - the form definition
  */
+export interface FormVersionMetadata {
+  versionNumber: number
+  createdAt: Date
+}
+
+/**
+ * Extracts form version metadata from a form definition
+ */
+export function getFormVersion(
+  definition: Pick<FormDefinition, 'metadata'>
+): FormVersionMetadata | undefined {
+  return definition.metadata?.[FORM_VERSION_METADATA_KEY] as
+    | FormVersionMetadata
+    | undefined
+}
+
 export function setPageTitles(def: FormDefinition) {
   def.pages.forEach((page) => {
     if (!page.title) {

package/src/server/plugins/engine/outputFormatters/adapter/v1.test.ts

@@ -764,6 +764,60 @@ describe('Adapter v1 formatter', () => {
   })
 
   describe('version metadata handling', () => {
+    it('should prefer $$__formVersion from definition metadata over formMetadata.versions', () => {
+      const definitionWithFormVersion = {
+        ...definition,
+        metadata: {
+          $$__formVersion: {
+            versionNumber: 42,
+            createdAt: new Date('2024-06-01T00:00:00.000Z')
+          }
+        }
+      }
+
+      const modelWithFormVersion = new FormModel(definitionWithFormVersion, {
+        basePath: 'test'
+      })
+
+      const contextWithFormVersion = modelWithFormVersion.getFormContext(
+        request,
+        state
+      )
+
+      const formMetadata: Partial<FormMetadata> = {
+        id: 'form-123',
+        slug: 'test-form',
+        title: 'Test Form',
+        notificationEmail: 'test@example.com',
+        versions: [
+          {
+            versionNumber: 1,
+            createdAt: new Date('2024-01-01T00:00:00.000Z')
+          }
+        ]
+      }
+
+      const formStatus = {
+        isPreview: false,
+        state: FormStatus.Live
+      }
+
+      const body = format(
+        contextWithFormVersion,
+        items,
+        modelWithFormVersion,
+        submitResponse,
+        formStatus,
+        formMetadata as FormMetadata
+      )
+      const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+      expect(parsedBody.meta.versionMetadata).toEqual({
+        versionNumber: 42,
+        createdAt: '2024-06-01T00:00:00.000Z'
+      })
+    })
+
     it('should include versionMetadata when context has submittedVersionNumber and formMetadata has versions', () => {
       const formMetadata: Partial<FormMetadata> = {
         id: 'form-123',

package/src/server/plugins/engine/outputFormatters/adapter/v1.ts

@@ -3,7 +3,10 @@ import {
   type SubmitResponsePayload
 } from '@defra/forms-model'
 
-import { type checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
+import {
+  getFormVersion,
+  type checkFormStatus
+} from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { type DetailItem } from '~/src/server/plugins/engine/models/types.js'
 import { categoriseData } from '~/src/server/plugins/engine/outputFormatters/machine/v2.js'
@@ -28,10 +31,9 @@ export function format(
 
   const { main: v2Main, ...v2Data } = categoriseData(items)
 
-  const versionMetadata = getVersionMetadata(
-    context.submittedVersionNumber,
-    formMetadata
-  )
+  const versionMetadata =
+    getFormVersion(model.def) ??
+    getVersionMetadata(context.submittedVersionNumber, formMetadata)
 
   const meta: FormAdapterSubmissionMessageMeta = {
     schemaVersion: FormAdapterSubmissionSchemaVersion.V1,

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

@@ -795,6 +795,83 @@ describe('FileUploadPageController', () => {
           })
         })
 
+        it('collects all file errors into a single flash when multiple files fail', async () => {
+          const state = {
+            upload: {
+              [controller.path]: {
+                upload: {
+                  uploadId: 'some-id',
+                  uploadUrl: 'some-url',
+                  statusUrl: 'some-status-url'
+                },
+                files: []
+              }
+            }
+          } as unknown as FormSubmissionState
+
+          const errorStatus = {
+            uploadStatus: UploadStatus.ready,
+            form: {
+              file: [
+                {
+                  fileStatus: FileStatus.rejected,
+                  errorMessage: 'File too large'
+                },
+                {
+                  fileStatus: FileStatus.rejected,
+                  errorMessage: 'Invalid file type'
+                }
+              ]
+            }
+          }
+
+          jest
+            .spyOn(uploadService, 'getUploadStatus')
+            .mockResolvedValue(errorStatus as unknown as UploadStatusResponse)
+
+          jest.spyOn(tempItemSchema, 'validate').mockReturnValue({
+            value: {
+              status: errorStatus,
+              uploadId: 'some-id'
+            },
+            error: undefined
+          } as ValidationResult)
+
+          const testController = controller as TestableFileUploadPageController
+
+          const initiateSpy = jest.spyOn(
+            testController,
+            'initiateAndStoreNewUpload'
+          ) as jest.SpyInstance<
+            Promise<FormSubmissionState>,
+            [FormRequest, FormSubmissionState]
+          >
+
+          initiateSpy.mockResolvedValue(state)
+
+          const cacheService = getCacheService(request.server)
+
+          await controller['checkUploadStatus'](request, state, 1)
+
+          expect(cacheService.setFlash).toHaveBeenCalledTimes(1)
+          expect(cacheService.setFlash).toHaveBeenCalledWith(request, {
+            errors: [
+              {
+                path: ['fileUpload'],
+                href: '#fileUpload',
+                name: 'fileUpload',
+                text: 'File too large'
+              },
+              {
+                path: ['fileUpload'],
+                href: '#fileUpload',
+                name: 'fileUpload',
+                text: 'Invalid file type'
+              }
+            ]
+          })
+        })
+
         it('sets default error message when none provided', async () => {
           const state = {
             upload: {
@@ -859,7 +936,16 @@ describe('FileUploadPageController', () => {
 
     describe('file removal', () => {
       it('returns early when no file is removed', async () => {
-        const files = [{ uploadId: 'file1' }, { uploadId: 'file2' }]
+        const files = [
+          {
+            uploadId: 'upload1',
+            status: { form: { file: { fileId: 'file1' } } }
+          },
+          {
+            uploadId: 'upload2',
+            status: { form: { file: { fileId: 'file2' } } }
+          }
+        ]
 
         Object.defineProperty(request, 'params', {
           value: { itemId: 'nonexistent-file' },
@@ -892,7 +978,16 @@ describe('FileUploadPageController', () => {
       })
 
       it('merges state when file is removed', async () => {
-        const files = [{ uploadId: 'file1' }, { uploadId: 'file2' }]
+        const files = [
+          {
+            uploadId: 'upload1',
+            status: { form: { file: { fileId: 'file1' } } }
+          },
+          {
+            uploadId: 'upload2',
+            status: { form: { file: { fileId: 'file2' } } }
+          }
+        ]
 
         Object.defineProperty(request, 'params', {
           value: { itemId: 'file1' },
@@ -924,7 +1019,12 @@ describe('FileUploadPageController', () => {
         expect(mergeStateSpy).toHaveBeenCalledWith(request, state, {
           upload: {
             [controller.path]: {
-              files: [{ uploadId: 'file2' }],
+              files: [
+                {
+                  uploadId: 'upload2',
+                  status: { form: { file: { fileId: 'file2' } } }
+                }
+              ],
               upload: {
                 uploadId: 'upload-123',
                 uploadUrl: 'some-url',
@@ -1121,11 +1221,15 @@ describe('FileUploadPageController', () => {
             files: [
               {
                 uploadId: 'file-1',
-                status: { form: { file: { filename: 'file-1.pdf' } } }
+                status: {
+                  form: { file: { fileId: 'file-1', filename: 'file-1.pdf' } }
+                }
               },
               {
                 uploadId: 'file-2',
-                status: { form: { file: { filename: 'file-2.pdf' } } }
+                status: {
+                  form: { file: { fileId: 'file-2', filename: 'file-2.pdf' } }
+                }
               }
             ]
           }

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

@@ -27,6 +27,7 @@ import {
   type AnyFormRequest,
   type FeaturedFormPageViewModel,
   type FileState,
+  type FileUpload,
   type FormContext,
   type FormContextRequest,
   type FormSubmissionError,
@@ -177,7 +178,7 @@ export class FileUploadPageController extends QuestionPageController {
       const files = this.getFilesFromState(state)
 
       const fileToRemove = files.find(
-        ({ uploadId }) => uploadId === params.itemId
+        ({ status }) => status.form.file.fileId === params.itemId
       )
 
       if (!fileToRemove) {
@@ -385,39 +386,86 @@ export class FileUploadPageController extends QuestionPageController {
 
     // Only add to files state if the file validates.
     // This secures against html tampering of the file input
-    // by adding a 'multiple' attribute or it being
-    // changed to a simple text field or similar.
+    // (e.g. changing it to a simple text field or similar).
     const validationResult = tempItemSchema.validate(
       { uploadId, status: statusResponse },
       { stripUnknown: true }
     )
     const error = validationResult.error
-    const fileState = validationResult.value as FileState
 
     if (error) {
       return this.initiateAndStoreNewUpload(request, state)
     }
 
-    const file = fileState.status.form.file
-    if (file.fileStatus === FileStatus.complete) {
-      files.unshift(prepareFileState(fileState))
+    // CDP returns form.file as a single object for one file,
+    // or an array for multiple files. The Joi schema normalises
+    // both to an array via .single().
+    await this.processUploadedFiles(
+      request,
+      state,
+      validationResult.value,
+      files,
+      upload
+    )
+
+    return this.initiateAndStoreNewUpload(request, state)
+  }
+
+  /**
+   * Processes the uploaded files from a CDP status response.
+   * Complete files are added to state, rejected/pending files
+   * have their error messages flashed.
+   * @param request - the hapi request
+   * @param state - the form state
+   * @param validatedItem - the Joi-validated upload item
+   * @param files - the current files array from state
+   * @param upload - the current upload initiation response
+   */
+  private async processUploadedFiles(
+    request: AnyFormRequest,
+    state: FormSubmissionState,
+    validatedItem: FileState,
+    files: FileState[],
+    upload: UploadInitiateResponse | undefined
+  ) {
+    const { uploadId } = validatedItem
+    const validatedStatus = validatedItem.status
+    const rawFile = validatedStatus.form.file as unknown as
+      | FileUpload
+      | FileUpload[]
+    const uploadedFiles = Array.isArray(rawFile) ? rawFile : [rawFile]
+
+    const allErrors: FormSubmissionError[] = []
+
+    for (const file of uploadedFiles) {
+      if (file.fileStatus === FileStatus.complete) {
+        const perFileState: FileState = {
+          uploadId,
+          status: {
+            ...validatedStatus,
+            form: { file }
+          } as FileState['status']
+        }
+        files.unshift(prepareFileState(perFileState))
+      } else {
+        // Collect the error for rejected/pending files.
+        const { fileUpload } = this
+        const name = fileUpload.name
+        const text = file.errorMessage ?? 'Unknown error'
+        allErrors.push({ path: [name], href: `#${name}`, name, text })
+      }
+    }
+
+    if (allErrors.length) {
+      const cacheService = getCacheService(request.server)
+      cacheService.setFlash(request, { errors: allErrors })
+    }
+
+    if (uploadedFiles.some((f) => f.fileStatus === FileStatus.complete)) {
       await this.mergeState(request, state, {
         upload: { [this.path]: { files, upload } }
       })
-    } else {
-      // Flash the error message.
-      const { fileUpload } = this
-      const cacheService = getCacheService(request.server)
-
-      const name = fileUpload.name
-      const text = file.errorMessage ?? 'Unknown error'
-      const errors: FormSubmissionError[] = [
-        { path: [name], href: `#${name}`, name, text }
-      ]
-      cacheService.setFlash(request, { errors })
     }
-
-    return this.initiateAndStoreNewUpload(request, state)
   }
 
   /**
@@ -438,7 +486,7 @@ export class FileUploadPageController extends QuestionPageController {
     const files = this.getFilesFromState(state)
 
     const filesUpdated = files.filter(
-      ({ uploadId }) => uploadId !== params.itemId
+      ({ status }) => status.form.file.fileId !== params.itemId
     )
 
     if (filesUpdated.length === files.length) {