From 3aef4d4bc34d5fb011cf3047a3e31e12ebe2c35e Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Thu, 12 Sep 2024 14:53:35 +0100
Subject: [PATCH 01/77] [WIP] Spike progressively enhanced file upload

---
 packages/govuk-frontend/src/govuk/all.mjs     |   1 +
 .../src/govuk/all.puppeteer.test.js           |   1 +
 .../govuk/components/file-upload/_index.scss  |  48 ++++
 .../components/file-upload/file-upload.mjs    | 228 ++++++++++++++++++
 .../components/file-upload/file-upload.yaml   |  40 ++-
 .../govuk/components/file-upload/template.njk |   2 +-
 .../src/govuk/init.jsdom.test.mjs             |   2 +
 packages/govuk-frontend/src/govuk/init.mjs    |   4 +
 .../tasks/build/package.unit.test.mjs         |   1 +
 9 files changed, 319 insertions(+), 8 deletions(-)
 create mode 100644 packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs

diff --git a/packages/govuk-frontend/src/govuk/all.mjs b/packages/govuk-frontend/src/govuk/all.mjs
index c82692ff7b..ea1309b790 100644
--- a/packages/govuk-frontend/src/govuk/all.mjs
+++ b/packages/govuk-frontend/src/govuk/all.mjs
@@ -5,6 +5,7 @@ export { CharacterCount } from './components/character-count/character-count.mjs
 export { Checkboxes } from './components/checkboxes/checkboxes.mjs'
 export { ErrorSummary } from './components/error-summary/error-summary.mjs'
 export { ExitThisPage } from './components/exit-this-page/exit-this-page.mjs'
+export { FileUpload } from './components/file-upload/file-upload.mjs'
 export { Header } from './components/header/header.mjs'
 export { NotificationBanner } from './components/notification-banner/notification-banner.mjs'
 export { PasswordInput } from './components/password-input/password-input.mjs'
diff --git a/packages/govuk-frontend/src/govuk/all.puppeteer.test.js b/packages/govuk-frontend/src/govuk/all.puppeteer.test.js
index 254fbaa26b..387449bec5 100644
--- a/packages/govuk-frontend/src/govuk/all.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/all.puppeteer.test.js
@@ -72,6 +72,7 @@ describe('GOV.UK Frontend', () => {
         'ConfigurableComponent',
         'ErrorSummary',
         'ExitThisPage',
+        'FileUpload',
         'Header',
         'NotificationBanner',
         'PasswordInput',
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 5862ab9cc3..4b20003587 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -46,4 +46,52 @@
       cursor: not-allowed;
     }
   }
+
+  .govuk-file-upload-wrapper {
+    display: inline-flex;
+    align-items: baseline;
+    position: relative;
+  }
+
+  .govuk-file-upload-wrapper--show-dropzone {
+    $dropzone-padding: govuk-spacing(2);
+
+    margin-top: -$dropzone-padding;
+    margin-left: -$dropzone-padding;
+    padding: $dropzone-padding;
+    outline: 2px dotted govuk-colour("mid-grey");
+    background-color: govuk-colour("light-grey");
+
+    .govuk-file-upload__button,
+    .govuk-file-upload__status {
+      // When the dropzone is hovered over, make these aspects not accept
+      // mouse events, so dropped files fall through to the input beneath them
+      pointer-events: none;
+    }
+  }
+
+  .govuk-file-upload-wrapper .govuk-file-upload {
+    // Make the native control take up the entire space of the element, but
+    // invisible and behind the other elements until we need it
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    margin: 0;
+    padding: 0;
+    opacity: 0;
+  }
+
+  .govuk-file-upload__button {
+    width: auto;
+    margin-bottom: 0;
+    flex-grow: 0;
+    flex-shrink: 0;
+  }
+
+  .govuk-file-upload__status {
+    margin-bottom: 0;
+    margin-left: govuk-spacing(2);
+  }
 }
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
new file mode 100644
index 0000000000..fd5ea46443
--- /dev/null
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -0,0 +1,228 @@
+import { closestAttributeValue } from '../../common/closest-attribute-value.mjs'
+import { mergeConfigs, normaliseDataset } from '../../common/configuration.mjs'
+import { ElementError } from '../../errors/index.mjs'
+import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
+import { I18n } from '../../i18n.mjs'
+
+/**
+ * File upload component
+ *
+ * @preserve
+ */
+export class FileUpload extends GOVUKFrontendComponent {
+  /**
+   * @private
+   * @type {HTMLInputElement}
+   */
+  $input
+
+  /**
+   * @private
+   * @type {HTMLElement}
+   */
+  $wrapper
+
+  /**
+   * @private
+   * @type {HTMLButtonElement}
+   */
+  $button
+
+  /**
+   * @private
+   * @type {HTMLElement}
+   */
+  $status
+
+  /**
+   * @private
+   * @type {FileUploadConfig}
+   */
+  config
+
+  /** @private */
+  i18n
+
+  /**
+   * @param {Element | null} $input - File input element
+   * @param {FileUploadConfig} [config] - File Upload config
+   */
+  constructor($input, config = {}) {
+    super($input)
+
+    if (!($input instanceof HTMLInputElement)) {
+      throw new ElementError({
+        component: FileUpload,
+        element: $input,
+        expectedType: 'HTMLInputElement',
+        identifier: 'Root element (`$module`)'
+      })
+    }
+
+    if ($input.type !== 'file') {
+      throw new ElementError('File upload: Form field must be of type `file`.')
+    }
+
+    this.config = mergeConfigs(
+      FileUpload.defaults,
+      config,
+      normaliseDataset(FileUpload, $input.dataset)
+    )
+
+    this.i18n = new I18n(this.config.i18n, {
+      // Read the fallback if necessary rather than have it set in the defaults
+      locale: closestAttributeValue($input, 'lang')
+    })
+
+    $input.addEventListener('change', this.onChange.bind(this))
+    this.$input = $input
+
+    // Wrapping element. This defines the boundaries of our drag and drop area.
+    const $wrapper = document.createElement('div')
+    $wrapper.className = 'govuk-file-upload-wrapper'
+    $wrapper.addEventListener('dragover', this.onDragOver.bind(this))
+    $wrapper.addEventListener('dragleave', this.onDragLeaveOrDrop.bind(this))
+    $wrapper.addEventListener('drop', this.onDragLeaveOrDrop.bind(this))
+
+    // Create the file selection button
+    const $button = document.createElement('button')
+    $button.className =
+      'govuk-button govuk-button--secondary govuk-file-upload__button'
+    $button.type = 'button'
+    $button.innerText = this.i18n.t('selectFilesButton')
+    $button.addEventListener('click', this.onClick.bind(this))
+
+    // Create status element that shows what/how many files are selected
+    const $status = document.createElement('span')
+    $status.className = 'govuk-body govuk-file-upload__status'
+    $status.innerText = this.i18n.t('filesSelectedDefault')
+    $status.setAttribute('role', 'status')
+
+    // Assemble these all together
+    $wrapper.insertAdjacentElement('beforeend', $button)
+    $wrapper.insertAdjacentElement('beforeend', $status)
+
+    // Inject all this *after* the native file input
+    this.$input.insertAdjacentElement('afterend', $wrapper)
+
+    // Move the native file input to inside of the wrapper
+    $wrapper.insertAdjacentElement('afterbegin', this.$input)
+
+    // Make all these new variables available to the module
+    this.$wrapper = $wrapper
+    this.$button = $button
+    this.$status = $status
+
+    // Bind change event to the underlying input
+    this.$input.addEventListener('change', this.onChange.bind(this))
+  }
+
+  /**
+   * Check if the value of the underlying input has changed
+   */
+  onChange() {
+    if (!this.$input.files) {
+      return
+    }
+
+    const fileCount = this.$input.files.length
+
+    if (fileCount === 0) {
+      // If there are no files, show the default selection text
+      this.$status.innerText = this.i18n.t('filesSelectedDefault')
+    } else if (
+      // If there is 1 file, just show the file name
+      fileCount === 1
+    ) {
+      this.$status.innerText = this.$input.files[0].name
+    } else {
+      // Otherwise, tell the user how many files are selected
+      this.$status.innerText = this.i18n.t('filesSelected', {
+        count: fileCount
+      })
+    }
+  }
+
+  /**
+   * When the button is clicked, emulate clicking the actual, hidden file input
+   */
+  onClick() {
+    this.$input.click()
+  }
+
+  /**
+   * When a file is dragged over the container, show a visual indicator that a
+   * file can be dropped here.
+   */
+  onDragOver() {
+    this.$wrapper.classList.add('govuk-file-upload-wrapper--show-dropzone')
+  }
+
+  /**
+   * When a dragged file leaves the container, or the file is dropped,
+   * remove the visual indicator.
+   */
+  onDragLeaveOrDrop() {
+    this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
+  }
+
+  /**
+   * Name for the component used when initialising using data-module attributes.
+   */
+  static moduleName = 'govuk-file-upload'
+
+  /**
+   * File upload default config
+   *
+   * @see {@link FileUploadConfig}
+   * @constant
+   * @type {FileUploadConfig}
+   */
+  static defaults = Object.freeze({
+    i18n: {
+      selectFilesButton: 'Choose file',
+      filesSelectedDefault: 'No file chosen',
+      filesSelected: {
+        one: '%{count} file chosen',
+        other: '%{count} files chosen'
+      }
+    }
+  })
+
+  /**
+   * File upload config schema
+   *
+   * @constant
+   * @satisfies {Schema<FileUploadConfig>}
+   */
+  static schema = Object.freeze({
+    properties: {
+      i18n: { type: 'object' }
+    }
+  })
+}
+
+/**
+ * File upload config
+ *
+ * @see {@link FileUpload.defaults}
+ * @typedef {object} FileUploadConfig
+ * @property {FileUploadTranslations} [i18n=FileUpload.defaults.i18n] - File upload translations
+ */
+
+/**
+ * File upload translations
+ *
+ * @see {@link FileUpload.defaults.i18n}
+ * @typedef {object} FileUploadTranslations
+ *
+ * Messages used by the component
+ * @property {string} [selectFiles] - Text of button that opens file browser
+ * @property {TranslationPluralForms} [filesSelected] - Text indicating how
+ *   many files have been selected
+ */
+
+/**
+ * @import { Schema } from '../../common/configuration.mjs'
+ * @import { TranslationPluralForms } from '../../i18n.mjs'
+ */
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 0ce412ab04..d5ecd5795d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -88,6 +88,31 @@ examples:
       name: file-upload-1
       label:
         text: Upload a file
+  - name: allows multiple files
+    options:
+      id: file-upload-1
+      name: file-upload-1
+      label:
+        text: Upload a file
+      attributes:
+        multiple: true
+  - name: allows image files only
+    options:
+      id: file-upload-1
+      name: file-upload-1
+      label:
+        text: Upload a file
+      attributes:
+        accept: 'image/*'
+  - name: allows direct media capture
+    description: Currently only works on mobile devices.
+    options:
+      id: file-upload-1
+      name: file-upload-1
+      label:
+        text: Upload a file
+      attributes:
+        capture: 'user'
   - name: with hint text
     options:
       id: file-upload-2
@@ -106,13 +131,6 @@ examples:
         text: Your photo may be in your Pictures, Photos, Downloads or Desktop folder. Or in an app like iPhoto.
       errorMessage:
         text: Error message goes here
-  - name: with value
-    options:
-      id: file-upload-4
-      name: file-upload-4
-      value: C:\fakepath\myphoto.jpg
-      label:
-        text: Upload a photo
   - name: with label as page heading
     options:
       id: file-upload-1
@@ -131,6 +149,14 @@ examples:
         classes: extra-class
 
   # Hidden examples are not shown in the review app, but are used for tests and HTML fixtures
+  - name: with value
+    hidden: true
+    options:
+      id: file-upload-4
+      name: file-upload-4
+      value: C:\fakepath\myphoto.jpg
+      label:
+        text: Upload a photo
   - name: attributes
     hidden: true
     options:
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index d2386de84d..21d69c5770 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -44,7 +44,7 @@
 {% if params.formGroup.beforeInput %}
   {{ params.formGroup.beforeInput.html | safe | trim | indent(2) if params.formGroup.beforeInput.html else params.formGroup.beforeInput.text }}
 {% endif %}
-  <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file"
+  <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file" data-module="govuk-file-upload"
   {%- if params.value %} value="{{ params.value }}"{% endif %}
   {%- if params.disabled %} disabled{% endif %}
   {%- if describedBy %} aria-describedby="{{ describedBy }}"{% endif %}
diff --git a/packages/govuk-frontend/src/govuk/init.jsdom.test.mjs b/packages/govuk-frontend/src/govuk/init.jsdom.test.mjs
index b7206342f4..b3ed66b9aa 100644
--- a/packages/govuk-frontend/src/govuk/init.jsdom.test.mjs
+++ b/packages/govuk-frontend/src/govuk/init.jsdom.test.mjs
@@ -14,6 +14,7 @@ jest.mock(`./components/character-count/character-count.mjs`)
 jest.mock(`./components/checkboxes/checkboxes.mjs`)
 jest.mock(`./components/error-summary/error-summary.mjs`)
 jest.mock(`./components/exit-this-page/exit-this-page.mjs`)
+jest.mock(`./components/file-upload/file-upload.mjs`)
 jest.mock(`./components/header/header.mjs`)
 jest.mock(`./components/notification-banner/notification-banner.mjs`)
 jest.mock(`./components/password-input/password-input.mjs`)
@@ -38,6 +39,7 @@ describe('initAll', () => {
     'character-count',
     'error-summary',
     'exit-this-page',
+    'file-upload',
     'notification-banner',
     'password-input'
   ]
diff --git a/packages/govuk-frontend/src/govuk/init.mjs b/packages/govuk-frontend/src/govuk/init.mjs
index 0e4969fca3..a5a4be9533 100644
--- a/packages/govuk-frontend/src/govuk/init.mjs
+++ b/packages/govuk-frontend/src/govuk/init.mjs
@@ -5,6 +5,7 @@ import { CharacterCount } from './components/character-count/character-count.mjs
 import { Checkboxes } from './components/checkboxes/checkboxes.mjs'
 import { ErrorSummary } from './components/error-summary/error-summary.mjs'
 import { ExitThisPage } from './components/exit-this-page/exit-this-page.mjs'
+import { FileUpload } from './components/file-upload/file-upload.mjs'
 import { Header } from './components/header/header.mjs'
 import { NotificationBanner } from './components/notification-banner/notification-banner.mjs'
 import { PasswordInput } from './components/password-input/password-input.mjs'
@@ -44,6 +45,7 @@ function initAll(config) {
     [Checkboxes],
     [ErrorSummary, config.errorSummary],
     [ExitThisPage, config.exitThisPage],
+    [FileUpload, config.fileUpload],
     [Header],
     [NotificationBanner, config.notificationBanner],
     [PasswordInput, config.passwordInput],
@@ -176,6 +178,7 @@ export { initAll, createAll }
  * @property {CharacterCountConfig} [characterCount] - Character Count config
  * @property {ErrorSummaryConfig} [errorSummary] - Error Summary config
  * @property {ExitThisPageConfig} [exitThisPage] - Exit This Page config
+ * @property {FileUploadConfig} [fileUpload] - File Upload config
  * @property {NotificationBannerConfig} [notificationBanner] - Notification Banner config
  * @property {PasswordInputConfig} [passwordInput] - Password input config
  */
@@ -190,6 +193,7 @@ export { initAll, createAll }
  * @import { ExitThisPageConfig } from './components/exit-this-page/exit-this-page.mjs'
  * @import { NotificationBannerConfig } from './components/notification-banner/notification-banner.mjs'
  * @import { PasswordInputConfig } from './components/password-input/password-input.mjs'
+ * @import { FileUploadConfig } from './components/file-upload/file-upload.mjs'
  */
 
 /**
diff --git a/packages/govuk-frontend/tasks/build/package.unit.test.mjs b/packages/govuk-frontend/tasks/build/package.unit.test.mjs
index e8e048356f..61e35d8006 100644
--- a/packages/govuk-frontend/tasks/build/package.unit.test.mjs
+++ b/packages/govuk-frontend/tasks/build/package.unit.test.mjs
@@ -196,6 +196,7 @@ describe('packages/govuk-frontend/dist/', () => {
           export { Checkboxes } from './components/checkboxes/checkboxes.mjs';
           export { ErrorSummary } from './components/error-summary/error-summary.mjs';
           export { ExitThisPage } from './components/exit-this-page/exit-this-page.mjs';
+          export { FileUpload } from './components/file-upload/file-upload.mjs';
           export { Header } from './components/header/header.mjs';
           export { NotificationBanner } from './components/notification-banner/notification-banner.mjs';
           export { PasswordInput } from './components/password-input/password-input.mjs';

From 7a7efe4a357e07ce2b243ad0e17982ed86ddef50 Mon Sep 17 00:00:00 2001
From: Owen Jones <owen.jones@digital.cabinet-office.gov.uk>
Date: Fri, 4 Oct 2024 15:40:49 +0100
Subject: [PATCH 02/77] click label instead of input

---
 .../govuk/components/file-upload/file-upload.mjs    | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index fd5ea46443..cc35806909 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -74,6 +74,15 @@ export class FileUpload extends GOVUKFrontendComponent {
       locale: closestAttributeValue($input, 'lang')
     })
 
+    this.$label = document.querySelector(`[for="${$input.id}"]`)
+
+    if (!this.$label) {
+      throw new ElementError({
+        componentName: 'File upload',
+        identifier: 'No label'
+      })
+    }
+
     $input.addEventListener('change', this.onChange.bind(this))
     this.$input = $input
 
@@ -147,7 +156,9 @@ export class FileUpload extends GOVUKFrontendComponent {
    * When the button is clicked, emulate clicking the actual, hidden file input
    */
   onClick() {
-    this.$input.click()
+    if (this.$label instanceof HTMLElement) {
+      this.$label.click()
+    }
   }
 
   /**

From b26716fc873b939c3e9c5a37c2edf78b73878d3d Mon Sep 17 00:00:00 2001
From: Owen Jones <owen.jones@digital.cabinet-office.gov.uk>
Date: Wed, 16 Oct 2024 17:56:23 +0100
Subject: [PATCH 03/77] Add aria-hidden and tabindex -1 to input

This change is mutated by a lot of mess from me trying to make typescript not upset with me
---
 .../components/file-upload/file-upload.mjs    | 85 +++++++++++--------
 1 file changed, 48 insertions(+), 37 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index cc35806909..31ed1e29d8 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -12,25 +12,16 @@ import { I18n } from '../../i18n.mjs'
 export class FileUpload extends GOVUKFrontendComponent {
   /**
    * @private
-   * @type {HTMLInputElement}
-   */
-  $input
-
-  /**
-   * @private
-   * @type {HTMLElement}
    */
   $wrapper
 
   /**
    * @private
-   * @type {HTMLButtonElement}
    */
   $button
 
   /**
    * @private
-   * @type {HTMLElement}
    */
   $status
 
@@ -38,60 +29,53 @@ export class FileUpload extends GOVUKFrontendComponent {
    * @private
    * @type {FileUploadConfig}
    */
+  // eslint-disable-next-line
+  // @ts-ignore
   config
 
   /** @private */
   i18n
 
   /**
-   * @param {Element | null} $input - File input element
+   * @param {Element | null} $root - File input element
    * @param {FileUploadConfig} [config] - File Upload config
    */
-  constructor($input, config = {}) {
-    super($input)
+  constructor($root, config = {}) {
+    super($root)
 
-    if (!($input instanceof HTMLInputElement)) {
-      throw new ElementError({
-        component: FileUpload,
-        element: $input,
-        expectedType: 'HTMLInputElement',
-        identifier: 'Root element (`$module`)'
-      })
+    if (!(this.$root instanceof HTMLInputElement)) {
+      return
     }
 
-    if ($input.type !== 'file') {
-      throw new ElementError('File upload: Form field must be of type `file`.')
+    if (this.$root.type !== 'file') {
+      throw new ElementError(
+        'File upload: Form field must be an input of type `file`.'
+      )
     }
 
     this.config = mergeConfigs(
       FileUpload.defaults,
       config,
-      normaliseDataset(FileUpload, $input.dataset)
+      normaliseDataset(FileUpload, this.$root.dataset)
     )
 
     this.i18n = new I18n(this.config.i18n, {
       // Read the fallback if necessary rather than have it set in the defaults
-      locale: closestAttributeValue($input, 'lang')
+      locale: closestAttributeValue(this.$root, 'lang')
     })
 
-    this.$label = document.querySelector(`[for="${$input.id}"]`)
+    this.$label = document.querySelector(`[for="${this.$root.id}"]`)
 
     if (!this.$label) {
       throw new ElementError({
-        componentName: 'File upload',
+        component: FileUpload,
         identifier: 'No label'
       })
     }
 
-    $input.addEventListener('change', this.onChange.bind(this))
-    this.$input = $input
-
     // Wrapping element. This defines the boundaries of our drag and drop area.
     const $wrapper = document.createElement('div')
     $wrapper.className = 'govuk-file-upload-wrapper'
-    $wrapper.addEventListener('dragover', this.onDragOver.bind(this))
-    $wrapper.addEventListener('dragleave', this.onDragLeaveOrDrop.bind(this))
-    $wrapper.addEventListener('drop', this.onDragLeaveOrDrop.bind(this))
 
     // Create the file selection button
     const $button = document.createElement('button')
@@ -112,29 +96,50 @@ export class FileUpload extends GOVUKFrontendComponent {
     $wrapper.insertAdjacentElement('beforeend', $status)
 
     // Inject all this *after* the native file input
-    this.$input.insertAdjacentElement('afterend', $wrapper)
+    this.$root.insertAdjacentElement('afterend', $wrapper)
 
     // Move the native file input to inside of the wrapper
-    $wrapper.insertAdjacentElement('afterbegin', this.$input)
+    $wrapper.insertAdjacentElement('afterbegin', this.$root)
 
     // Make all these new variables available to the module
     this.$wrapper = $wrapper
     this.$button = $button
     this.$status = $status
 
+    // with everything set up, apply attributes to programmatically hide the input
+    this.$root.setAttribute('aria-hidden', 'true')
+    this.$root.setAttribute('tabindex', '-1')
+
     // Bind change event to the underlying input
-    this.$input.addEventListener('change', this.onChange.bind(this))
+    this.$root.addEventListener('change', this.onChange.bind(this))
+    this.$wrapper.addEventListener('dragover', this.onDragOver.bind(this))
+    this.$wrapper.addEventListener(
+      'dragleave',
+      this.onDragLeaveOrDrop.bind(this)
+    )
+    this.$wrapper.addEventListener('drop', this.onDragLeaveOrDrop.bind(this))
   }
 
   /**
    * Check if the value of the underlying input has changed
    */
   onChange() {
-    if (!this.$input.files) {
+    if (!('files' in this.$root)) {
       return
     }
 
-    const fileCount = this.$input.files.length
+    if (!this.$root.files) {
+      return
+    }
+
+    // eslint-disable-next-line
+    // @ts-ignore
+    const fileCount = this.$root.files.length // eslint-disable-line
+
+    // trying to appease typescript
+    if (!this.$status || !this.i18n) {
+      return
+    }
 
     if (fileCount === 0) {
       // If there are no files, show the default selection text
@@ -143,7 +148,9 @@ export class FileUpload extends GOVUKFrontendComponent {
       // If there is 1 file, just show the file name
       fileCount === 1
     ) {
-      this.$status.innerText = this.$input.files[0].name
+      // eslint-disable-next-line
+      // @ts-ignore
+      this.$status.innerText = this.$root.files[0].name // eslint-disable-line
     } else {
       // Otherwise, tell the user how many files are selected
       this.$status.innerText = this.i18n.t('filesSelected', {
@@ -166,6 +173,8 @@ export class FileUpload extends GOVUKFrontendComponent {
    * file can be dropped here.
    */
   onDragOver() {
+    // eslint-disable-next-line
+    // @ts-ignore
     this.$wrapper.classList.add('govuk-file-upload-wrapper--show-dropzone')
   }
 
@@ -174,6 +183,8 @@ export class FileUpload extends GOVUKFrontendComponent {
    * remove the visual indicator.
    */
   onDragLeaveOrDrop() {
+    // eslint-disable-next-line
+    // @ts-ignore
     this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
   }
 

From 28898992ceb4bca60cae42c39e06955d5c121e9f Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Fri, 18 Oct 2024 14:25:59 +0100
Subject: [PATCH 04/77] Add `multiple` Nunjucks parameter

Setting this via the `attributes` parameter raises complaints from the test that lints our HTML output. Should quieten that failing test.
---
 .../src/govuk/components/file-upload/file-upload.yaml      | 7 +++++--
 .../src/govuk/components/file-upload/template.njk          | 1 +
 .../src/govuk/components/file-upload/template.test.js      | 7 +++++++
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index d5ecd5795d..b9fab9727b 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -15,6 +15,10 @@ params:
     type: boolean
     required: false
     description: If `true`, file input will be disabled.
+  - name: multiple
+    type: boolean
+    required: false
+    description: If `true`, a user may select multiple files at the same time. The exact mechanism to do this differs depending on operating system.
   - name: describedBy
     type: string
     required: false
@@ -94,8 +98,7 @@ examples:
       name: file-upload-1
       label:
         text: Upload a file
-      attributes:
-        multiple: true
+      multiple: true
   - name: allows image files only
     options:
       id: file-upload-1
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 21d69c5770..62c9bf3175 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -47,6 +47,7 @@
   <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file" data-module="govuk-file-upload"
   {%- if params.value %} value="{{ params.value }}"{% endif %}
   {%- if params.disabled %} disabled{% endif %}
+  {%- if params.multiple %} multiple{% endif %}
   {%- if describedBy %} aria-describedby="{{ describedBy }}"{% endif %}
   {{- govukAttributes(params.attributes) }}>
 {% if params.formGroup.afterInput %}
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index 7fad86a7c4..e2dd676c2b 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -67,6 +67,13 @@ describe('File upload', () => {
       expect($component.attr('aria-describedby')).toMatch('test-target-element')
     })
 
+    it('renders with multiple', () => {
+      const $ = render('file-upload', examples['allows multiple files'])
+
+      const $component = $('.govuk-file-upload')
+      expect($component.attr('multiple')).toBeTruthy()
+    })
+
     it('renders with attributes', () => {
       const $ = render('file-upload', examples.attributes)
 

From b48efebfb99ed6baab7aec13b45c0db63f1730ae Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Fri, 18 Oct 2024 16:30:53 +0100
Subject: [PATCH 05/77] Tweaks to dropzone styles

---
 .../src/govuk/components/file-upload/_index.scss       | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 4b20003587..309ea05fd5 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -55,12 +55,14 @@
 
   .govuk-file-upload-wrapper--show-dropzone {
     $dropzone-padding: govuk-spacing(2);
+    $dropzone-offset: $dropzone-padding + $govuk-border-width-form-element;
 
-    margin-top: -$dropzone-padding;
-    margin-left: -$dropzone-padding;
+    // Add negative margins to all sides so that content doesn't jump due to
+    // the addition of the padding and border.
+    margin: -$dropzone-offset;
     padding: $dropzone-padding;
-    outline: 2px dotted govuk-colour("mid-grey");
-    background-color: govuk-colour("light-grey");
+    border: $govuk-border-width-form-element dashed $govuk-input-border-colour;
+    background-color: $govuk-body-background-colour;
 
     .govuk-file-upload__button,
     .govuk-file-upload__status {

From 3488c8942ba63102975f73dd515a5f449e05292d Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Mon, 21 Oct 2024 09:33:08 +0100
Subject: [PATCH 06/77] Remove setting aria-hidden

Chromium actively ignores this attribute on file inputs and throws a warning in the console
---
 .../src/govuk/components/file-upload/file-upload.mjs           | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 31ed1e29d8..a0dc121301 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -106,8 +106,7 @@ export class FileUpload extends GOVUKFrontendComponent {
     this.$button = $button
     this.$status = $status
 
-    // with everything set up, apply attributes to programmatically hide the input
-    this.$root.setAttribute('aria-hidden', 'true')
+    // Prevent the hidden input being tabbed to by keyboard users
     this.$root.setAttribute('tabindex', '-1')
 
     // Bind change event to the underlying input

From a7aff310aee97f87d037d44fad7b7ba6aa1d6904 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Mon, 21 Oct 2024 10:56:49 +0100
Subject: [PATCH 07/77] Syncronise disabled state between input and button

Adds a mutation observer that looks to see if the `disabled` attribute of the input changes and, if so, updates the button to match
---
 .../components/file-upload/file-upload.mjs    | 39 +++++++++++++++++++
 .../components/file-upload/file-upload.yaml   |  7 ++++
 .../components/file-upload/template.test.js   |  7 ++++
 3 files changed, 53 insertions(+)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index a0dc121301..00b22bcd6f 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -109,6 +109,10 @@ export class FileUpload extends GOVUKFrontendComponent {
     // Prevent the hidden input being tabbed to by keyboard users
     this.$root.setAttribute('tabindex', '-1')
 
+    // Syncronise the `disabled` state between the button and underlying input
+    this.updateDisabledState()
+    this.observeDisabledState()
+
     // Bind change event to the underlying input
     this.$root.addEventListener('change', this.onChange.bind(this))
     this.$wrapper.addEventListener('dragover', this.onDragOver.bind(this))
@@ -187,6 +191,41 @@ export class FileUpload extends GOVUKFrontendComponent {
     this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
   }
 
+  /**
+   * Create a mutation observer to check if the input's attributes altered.
+   */
+  observeDisabledState() {
+    const observer = new MutationObserver((mutationList) => {
+      for (const mutation of mutationList) {
+        console.log('mutation', mutation)
+        if (
+          mutation.type === 'attributes' &&
+          mutation.attributeName === 'disabled'
+        ) {
+          this.updateDisabledState()
+        }
+      }
+    })
+
+    observer.observe(this.$root, {
+      attributes: true
+    })
+  }
+
+  /**
+   * Synchronise the `disabled` state between the input and replacement button.
+   */
+  updateDisabledState() {
+    if (
+      !(this.$root instanceof HTMLInputElement) ||
+      !(this.$button instanceof HTMLButtonElement)
+    ) {
+      return
+    }
+
+    this.$button.disabled = this.$root.disabled
+  }
+
   /**
    * Name for the component used when initialising using data-module attributes.
    */
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index b9fab9727b..1e5e4c8f83 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -116,6 +116,13 @@ examples:
         text: Upload a file
       attributes:
         capture: 'user'
+  - name: is disabled
+    options:
+      id: file-upload-1
+      name: file-upload-1
+      label:
+        text: Upload a file
+      disabled: true
   - name: with hint text
     options:
       id: file-upload-2
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index e2dd676c2b..91da31ac8a 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -74,6 +74,13 @@ describe('File upload', () => {
       expect($component.attr('multiple')).toBeTruthy()
     })
 
+    it('renders with multiple', () => {
+      const $ = render('file-upload', examples['is disabled'])
+
+      const $component = $('.govuk-file-upload')
+      expect($component.attr('disabled')).toBeTruthy()
+    })
+
     it('renders with attributes', () => {
       const $ = render('file-upload', examples.attributes)
 

From c006982914802abd2193e1e4f0cee5a6b367d994 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Mon, 21 Oct 2024 18:19:31 +0100
Subject: [PATCH 08/77] Add i18n parameters

---
 .../govuk/components/file-upload/file-upload.yaml   | 11 +++++++++++
 .../src/govuk/components/file-upload/template.njk   | 13 +++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 1e5e4c8f83..6f285a4cc1 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -157,6 +157,17 @@ examples:
         text: Upload a file
       formGroup:
         classes: extra-class
+  - name: translated
+    options:
+      id: file-upload-1
+      name: file-upload-1
+      label:
+        text: Llwythwch ffeil i fyny
+      selectFilesButtonText: Dewiswch ffeil
+      filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
+      filesSelectedText:
+        one: "%{count} ffeil wedi'i dewis"
+        other: "%{count} ffeil wedi'u dewis"
 
   # Hidden examples are not shown in the review app, but are used for tests and HTML fixtures
   - name: with value
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 62c9bf3175..804c3b9c3f 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -1,4 +1,5 @@
 {% from "../../macros/attributes.njk" import govukAttributes %}
+{% from "../../macros/i18n.njk" import govukI18nAttributes %}
 {% from "../error-message/macro.njk" import govukErrorMessage %}
 {% from "../hint/macro.njk" import govukHint %}
 {% from "../label/macro.njk" import govukLabel %}
@@ -49,6 +50,18 @@
   {%- if params.disabled %} disabled{% endif %}
   {%- if params.multiple %} multiple{% endif %}
   {%- if describedBy %} aria-describedby="{{ describedBy }}"{% endif %}
+  {{- govukI18nAttributes({
+    key: 'select-files-button',
+    message: params.selectFilesButtonText
+  }) -}}
+  {{- govukI18nAttributes({
+    key: 'files-selected-default',
+    message: params.filesSelectedDefaultText
+  }) -}}
+  {{- govukI18nAttributes({
+    key: 'files-selected',
+    message: params.filesSelectedText
+  }) -}}
   {{- govukAttributes(params.attributes) }}>
 {% if params.formGroup.afterInput %}
   {{ params.formGroup.afterInput.html | safe | trim | indent(2) if params.formGroup.afterInput.html else params.formGroup.afterInput.text }}

From 07c4647bf04e9db68edd1575593cfc3c2ad918c7 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Tue, 22 Oct 2024 10:24:06 +0100
Subject: [PATCH 09/77] Write JavaScript functionality tests

---
 .../file-upload/file-upload.puppeteer.test.js | 286 ++++++++++++++++++
 .../components/file-upload/file-upload.yaml   |   3 +-
 2 files changed, 288 insertions(+), 1 deletion(-)
 create mode 100644 packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
new file mode 100644
index 0000000000..cf502b4879
--- /dev/null
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -0,0 +1,286 @@
+const { render } = require('@govuk-frontend/helpers/puppeteer')
+const { getExamples } = require('@govuk-frontend/lib/components')
+
+const inputSelector = '.govuk-file-upload'
+const wrapperSelector = '.govuk-file-upload-wrapper'
+const buttonSelector = '.govuk-file-upload__button'
+const statusSelector = '.govuk-file-upload__status'
+
+describe('/components/file-upload', () => {
+  let examples
+
+  beforeAll(async () => {
+    examples = await getExamples('file-upload')
+  })
+
+  describe('/components/file-upload/preview', () => {
+    describe('when JavaScript is unavailable or fails', () => {
+      beforeAll(async () => {
+        await page.setJavaScriptEnabled(false)
+      })
+
+      afterAll(async () => {
+        await page.setJavaScriptEnabled(true)
+      })
+
+      it('renders an unmodified file input', async () => {
+        await render(page, 'file-upload', examples.default)
+
+        const inputType = await page.$eval(inputSelector, (el) =>
+          el.getAttribute('type')
+        )
+        expect(inputType).toBe('file')
+      })
+
+      it('does not inject additional elements', async () => {
+        await render(page, 'file-upload', examples.default)
+
+        const $wrapperElement = await page.$(wrapperSelector)
+        const $buttonElement = await page.$(buttonSelector)
+        const $statusElement = await page.$(statusSelector)
+
+        expect($wrapperElement).toBeNull()
+        expect($buttonElement).toBeNull()
+        expect($statusElement).toBeNull()
+      })
+    })
+
+    describe('when JavaScript is available', () => {
+      describe('on page load', () => {
+        beforeAll(async () => {
+          await render(page, 'file-upload', examples.default)
+        })
+
+        describe('wrapper element', () => {
+          it('renders the wrapper element', async () => {
+            const wrapperElement = await page.$eval(wrapperSelector, (el) => el)
+
+            expect(wrapperElement).toBeDefined()
+          })
+
+          it('moves the file input inside of the wrapper element', async () => {
+            const inputElementParent = await page.$eval(
+              inputSelector,
+              (el) => el.parentNode
+            )
+            const wrapperElement = await page.$eval(wrapperSelector, (el) => el)
+
+            expect(inputElementParent).toStrictEqual(wrapperElement)
+          })
+        })
+
+        describe('file input', () => {
+          it('sets tabindex to -1', async () => {
+            const inputElementTabindex = await page.$eval(inputSelector, (el) =>
+              el.getAttribute('tabindex')
+            )
+
+            expect(inputElementTabindex).toBe('-1')
+          })
+        })
+
+        describe('choose file button', () => {
+          it('renders the button element', async () => {
+            const buttonElement = await page.$eval(buttonSelector, (el) => el)
+            const buttonElementType = await page.$eval(buttonSelector, (el) =>
+              el.getAttribute('type')
+            )
+
+            expect(buttonElement).toBeDefined()
+            expect(buttonElementType).toBe('button')
+          })
+
+          it('renders the button with default text', async () => {
+            const buttonElementText = await page.$eval(buttonSelector, (el) =>
+              el.innerHTML.trim()
+            )
+
+            expect(buttonElementText).toBe('Choose file')
+          })
+        })
+
+        describe('status element', () => {
+          it('renders the status element', async () => {
+            const statusElement = await page.$eval(statusSelector, (el) => el)
+
+            expect(statusElement).toBeDefined()
+          })
+
+          it('renders the status element with role', async () => {
+            const statusElementRole = await page.$eval(statusSelector, (el) =>
+              el.getAttribute('role')
+            )
+
+            expect(statusElementRole).toBe('status')
+          })
+
+          it('renders the status element with default text', async () => {
+            const statusElementText = await page.$eval(statusSelector, (el) =>
+              el.innerHTML.trim()
+            )
+
+            expect(statusElementText).toBe('No file chosen')
+          })
+        })
+      })
+
+      describe('when clicking the choose file button', () => {
+        it('opens the file picker', async () => {
+          // It doesn't seem to be possible to check if the file picker dialog
+          // opens as an isolated test, so this test clicks the button, tries to
+          // set a value in the file chooser, then checks if that value was set
+          // on the input as expected.
+          const testFilename = 'test.gif'
+          await render(page, 'file-upload', examples.default)
+
+          const [fileChooser] = await Promise.all([
+            page.waitForFileChooser(),
+            page.click(buttonSelector)
+          ])
+
+          await fileChooser.accept([testFilename])
+
+          const inputElementValue = await page.$eval(
+            inputSelector,
+            (el) =>
+              // @ts-ignore
+              el.value
+          )
+
+          // For Windows and backward compatibility, the values of file inputs
+          // are always formatted starting with `C:\\fakepath\\`
+          expect(inputElementValue).toBe(`C:\\fakepath\\${testFilename}`)
+        })
+      })
+
+      describe('when selecting a file', () => {
+        const testFilename = 'fakefile.txt'
+
+        beforeEach(async () => {
+          await render(page, 'file-upload', examples.default)
+
+          const [fileChooser] = await Promise.all([
+            page.waitForFileChooser(),
+            page.click(inputSelector)
+          ])
+          await fileChooser.accept([testFilename])
+        })
+
+        it('updates the file input value', async () => {
+          const inputElementValue = await page.$eval(
+            inputSelector,
+            (el) =>
+              // @ts-ignore
+              el.value
+          )
+
+          const inputElementFiles = await page.$eval(
+            inputSelector,
+            (el) =>
+              // @ts-ignore
+              el.files
+          )
+
+          // For Windows and backward compatibility, the values of file inputs
+          // are always formatted starting with `C:\\fakepath\\`
+          expect(inputElementValue).toBe(`C:\\fakepath\\${testFilename}`)
+
+          // Also check the files object
+          expect(inputElementFiles[0]).toBeDefined()
+        })
+
+        it('updates the filename in the status element', async () => {
+          const statusElementText = await page.$eval(statusSelector, (el) =>
+            el.innerHTML.trim()
+          )
+
+          expect(statusElementText).toBe(testFilename)
+        })
+      })
+
+      describe('when selecting multiple files', () => {
+        beforeEach(async () => {
+          await render(page, 'file-upload', examples['allows multiple files'])
+
+          const [fileChooser] = await Promise.all([
+            page.waitForFileChooser(),
+            page.click(inputSelector)
+          ])
+          await fileChooser.accept(['testfile1.txt', 'testfile2.pdf'])
+        })
+
+        it('updates the file input value', async () => {
+          const inputElementValue = await page.$eval(
+            inputSelector,
+            (el) =>
+              // @ts-ignore
+              el.value
+          )
+
+          const inputElementFiles = await page.$eval(
+            inputSelector,
+            (el) =>
+              // @ts-ignore
+              el.files
+          )
+
+          // For Windows and backward compatibility, the values of file inputs
+          // are always formatted starting with `C:\\fakepath\\`
+          //
+          // Additionally, `value` will only ever return the first file selected
+          expect(inputElementValue).toBe(`C:\\fakepath\\testfile1.txt`)
+
+          // Also check the files object
+          expect(inputElementFiles[0]).toBeDefined()
+          expect(inputElementFiles[1]).toBeDefined()
+        })
+
+        it('shows the number of files selected in the status element', async () => {
+          const statusElementText = await page.$eval(statusSelector, (el) =>
+            el.innerHTML.trim()
+          )
+
+          expect(statusElementText).toBe('2 files chosen')
+        })
+      })
+
+      describe('i18n', () => {
+        beforeEach(async () => {
+          await render(page, 'file-upload', examples.translated)
+        })
+
+        it('uses the correct translation for the choose file button', async () => {
+          const buttonText = await page.$eval(buttonSelector, (el) =>
+            el.innerHTML.trim()
+          )
+
+          expect(buttonText).toBe('Dewiswch ffeil')
+        })
+
+        describe('status element', () => {
+          it('uses the correct translation when no files are selected', async () => {
+            const statusText = await page.$eval(statusSelector, (el) =>
+              el.innerHTML.trim()
+            )
+
+            expect(statusText).toBe("Dim ffeiliau wedi'u dewis")
+          })
+
+          it('uses the correct translation when multiple files are selected', async () => {
+            const [fileChooser] = await Promise.all([
+              page.waitForFileChooser(),
+              page.click(inputSelector)
+            ])
+            await fileChooser.accept(['testfile1.txt', 'testfile2.pdf'])
+
+            const statusText = await page.$eval(statusSelector, (el) =>
+              el.innerHTML.trim()
+            )
+
+            expect(statusText).toBe("2 ffeil wedi'u dewis")
+          })
+        })
+      })
+    })
+  })
+})
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 6f285a4cc1..3aee3741fa 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -163,11 +163,12 @@ examples:
       name: file-upload-1
       label:
         text: Llwythwch ffeil i fyny
+      multiple: true
       selectFilesButtonText: Dewiswch ffeil
       filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
       filesSelectedText:
-        one: "%{count} ffeil wedi'i dewis"
         other: "%{count} ffeil wedi'u dewis"
+        one: "%{count} ffeil wedi'i dewis"
 
   # Hidden examples are not shown in the review app, but are used for tests and HTML fixtures
   - name: with value

From a7bd798c3b36d746ace0cc90f4b3bce001ab6e47 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Tue, 22 Oct 2024 10:24:17 +0100
Subject: [PATCH 10/77] Fix component not rendering plural objects correctly

---
 .../src/govuk/components/file-upload/template.njk               | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 804c3b9c3f..38a5c5f9c3 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -60,7 +60,7 @@
   }) -}}
   {{- govukI18nAttributes({
     key: 'files-selected',
-    message: params.filesSelectedText
+    messages: params.filesSelectedText
   }) -}}
   {{- govukAttributes(params.attributes) }}>
 {% if params.formGroup.afterInput %}

From b765770212ad5a764274c7441d5e4462e9fa56d0 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Tue, 22 Oct 2024 17:02:04 +0100
Subject: [PATCH 11/77] Add Nunjucks parameter documentation

---
 .../src/govuk/components/file-upload/file-upload.mjs |  2 ++
 .../govuk/components/file-upload/file-upload.yaml    | 12 ++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 00b22bcd6f..5bba605c2c 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -243,6 +243,8 @@ export class FileUpload extends GOVUKFrontendComponent {
       selectFilesButton: 'Choose file',
       filesSelectedDefault: 'No file chosen',
       filesSelected: {
+        // the 'one' string isn't used as the component displays the filename
+        // instead, however it's here for coverage's sake
         one: '%{count} file chosen',
         other: '%{count} files chosen'
       }
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 3aee3741fa..7acf24b4ee 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -77,6 +77,18 @@ params:
             type: string
             required: true
             description: HTML to add after the input. If `html` is provided, the `text` option will be ignored.
+  - name: selectFilesButtonText
+    type: string
+    required: false
+    description: The text of the button that opens the file picker. JavaScript enhanced version of the component only. Default is "Choose file".
+  - name: filesSelected
+    type: object
+    required: false
+    description: The text to display when multiple files has been chosen by the user. JavaScript enhanced version of the component only. The component will replace the `%{count}` placeholder with the number of files selected. This is a [pluralised list of messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+  - name: filesSelectedDefault
+    type: string
+    required: false
+    description: The text to display when no file has been chosen by the user. JavaScript enhanced version of the component only. Default is "No file chosen".
   - name: classes
     type: string
     required: false

From 95d9cec11789b94da3ed99b0466d109391e39b65 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Tue, 22 Oct 2024 17:42:21 +0100
Subject: [PATCH 12/77] Add tests for disable state syncronisation

---
 .../file-upload/file-upload.puppeteer.test.js | 45 +++++++++++++++++++
 .../components/file-upload/file-upload.yaml   |  2 +-
 .../components/file-upload/template.test.js   |  4 +-
 3 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index cf502b4879..a0172ae79d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -281,6 +281,51 @@ describe('/components/file-upload', () => {
           })
         })
       })
+
+      describe('disabled state syncing', () => {
+        it('disables the button if the input is disabled on page load', async () => {
+          await render(page, 'file-upload', examples.disabled)
+
+          const buttonDisabled = await page.$eval(buttonSelector, (el) =>
+            el.hasAttribute('disabled')
+          )
+
+          expect(buttonDisabled).toBeTruthy()
+        })
+
+        it('disables the button if the input is disabled programatically', async () => {
+          await render(page, 'file-upload', examples.default)
+
+          await page.$eval(inputSelector, (el) =>
+            el.setAttribute('disabled', '')
+          )
+
+          const buttonDisabledAfter = await page.$eval(buttonSelector, (el) =>
+            el.hasAttribute('disabled')
+          )
+
+          expect(buttonDisabledAfter).toBeTruthy()
+        })
+
+        it('enables the button if the input is enabled programatically', async () => {
+          await render(page, 'file-upload', examples.disabled)
+
+          const buttonDisabledBefore = await page.$eval(buttonSelector, (el) =>
+            el.hasAttribute('disabled')
+          )
+
+          await page.$eval(inputSelector, (el) =>
+            el.removeAttribute('disabled')
+          )
+
+          const buttonDisabledAfter = await page.$eval(buttonSelector, (el) =>
+            el.hasAttribute('disabled')
+          )
+
+          expect(buttonDisabledBefore).toBeTruthy()
+          expect(buttonDisabledAfter).toBeFalsy()
+        })
+      })
     })
   })
 })
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 7acf24b4ee..9637ea648b 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -128,7 +128,7 @@ examples:
         text: Upload a file
       attributes:
         capture: 'user'
-  - name: is disabled
+  - name: disabled
     options:
       id: file-upload-1
       name: file-upload-1
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index 91da31ac8a..f7b3d30271 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -74,8 +74,8 @@ describe('File upload', () => {
       expect($component.attr('multiple')).toBeTruthy()
     })
 
-    it('renders with multiple', () => {
-      const $ = render('file-upload', examples['is disabled'])
+    it('renders with disabled', () => {
+      const $ = render('file-upload', examples.disabled)
 
       const $component = $('.govuk-file-upload')
       expect($component.attr('disabled')).toBeTruthy()

From 144486b0d9e1626e2388a347758892af57094a5e Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Thu, 24 Oct 2024 09:44:21 +0100
Subject: [PATCH 13/77] Show dropzone when dragover page and not input

---
 .../src/govuk/components/file-upload/file-upload.mjs  | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 5bba605c2c..83434fe20d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -115,12 +115,13 @@ export class FileUpload extends GOVUKFrontendComponent {
 
     // Bind change event to the underlying input
     this.$root.addEventListener('change', this.onChange.bind(this))
-    this.$wrapper.addEventListener('dragover', this.onDragOver.bind(this))
-    this.$wrapper.addEventListener(
-      'dragleave',
-      this.onDragLeaveOrDrop.bind(this)
-    )
+
+    // When a file is dropped on the input
     this.$wrapper.addEventListener('drop', this.onDragLeaveOrDrop.bind(this))
+
+    // When a file is dragged over the page (or dragged off the page)
+    document.addEventListener('dragover', this.onDragOver.bind(this))
+    document.addEventListener('dragleave', this.onDragLeaveOrDrop.bind(this))
   }
 
   /**

From 1e9125b17578b01b3fb43c4c5e448be5423a1171 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Fri, 25 Oct 2024 13:19:26 +0100
Subject: [PATCH 14/77] Change dragover to dragenter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Dragenter is fired only once when the drag first touches the page, whereas dragover fires continuously.

As we’re only toggling the visbility of the dropzone, dragenter will suffice for our needs.
---
 .../src/govuk/components/file-upload/file-upload.mjs   | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 83434fe20d..9b4d74fb31 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -120,7 +120,7 @@ export class FileUpload extends GOVUKFrontendComponent {
     this.$wrapper.addEventListener('drop', this.onDragLeaveOrDrop.bind(this))
 
     // When a file is dragged over the page (or dragged off the page)
-    document.addEventListener('dragover', this.onDragOver.bind(this))
+    document.addEventListener('dragenter', this.onDragEnter.bind(this))
     document.addEventListener('dragleave', this.onDragLeaveOrDrop.bind(this))
   }
 
@@ -175,8 +175,14 @@ export class FileUpload extends GOVUKFrontendComponent {
   /**
    * When a file is dragged over the container, show a visual indicator that a
    * file can be dropped here.
+   *
+   * @param {DragEvent} event - the drag event
    */
-  onDragOver() {
+  onDragEnter(event) {
+    // Check if the thing being dragged is a file (and not text or something
+    // else), we only want to indicate files.
+    console.log(event)
+
     // eslint-disable-next-line
     // @ts-ignore
     this.$wrapper.classList.add('govuk-file-upload-wrapper--show-dropzone')

From 8c27bd0c6e42e3f1b8d3546c55b2128ac7b2a224 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 9 Jan 2025 15:16:15 +0000
Subject: [PATCH 15/77] Add tests for initialisation errors specific to the
 component

Ahead of using `ConfigurableComponent` add tests for errors that won't be handled
by the base class, so we know the functionality is still there.

Tests for the errors thrown by `ConfiguableComponent` will be added when the class
gets used.
---
 .../file-upload/file-upload.puppeteer.test.js | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index a0172ae79d..1975edb351 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -326,6 +326,49 @@ describe('/components/file-upload', () => {
           expect(buttonDisabledAfter).toBeFalsy()
         })
       })
+
+      describe('errors at instantiation', () => {
+        let examples
+
+        beforeAll(async () => {
+          examples = await getExamples('file-upload')
+        })
+
+        describe('missing or misconfigured elements', () => {
+          it('throws if the input type is not "file"', async () => {
+            await expect(
+              render(page, 'file-upload', examples.default, {
+                beforeInitialisation() {
+                  document
+                    .querySelector('[type="file"]')
+                    .setAttribute('type', 'text')
+                }
+              })
+            ).rejects.toMatchObject({
+              cause: {
+                name: 'ElementError',
+                message:
+                  'File upload: Form field must be an input of type `file`.'
+              }
+            })
+          })
+
+          it('throws if no label is present', async () => {
+            await expect(
+              render(page, 'file-upload', examples.default, {
+                beforeInitialisation() {
+                  document.querySelector('label').remove()
+                }
+              })
+            ).rejects.toMatchObject({
+              cause: {
+                name: 'ElementError',
+                message: 'govuk-file-upload: No label not found'
+              }
+            })
+          })
+        })
+      })
     })
   })
 })

From f16d254ad03bb74a95fb7cb7ed5140fa38ad4beb Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 9 Jan 2025 16:05:41 +0000
Subject: [PATCH 16/77] Make `FileUpload` extend `ConfigurableComponent`

Use the recently added class for consistency with the other components.
Also adds the tests related to the behaviour provided by the `ConfigurableComponent` class
---
 .../components/file-upload/file-upload.mjs    | 31 ++-------
 .../file-upload/file-upload.puppeteer.test.js | 65 +++++++++++++++++++
 2 files changed, 69 insertions(+), 27 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 9b4d74fb31..deb0e10ceb 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -1,15 +1,15 @@
 import { closestAttributeValue } from '../../common/closest-attribute-value.mjs'
-import { mergeConfigs, normaliseDataset } from '../../common/configuration.mjs'
+import { ConfigurableComponent } from '../../common/configuration.mjs'
 import { ElementError } from '../../errors/index.mjs'
-import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
 import { I18n } from '../../i18n.mjs'
 
 /**
  * File upload component
  *
  * @preserve
+ * @augments ConfigurableComponent<FileUploadConfig,HTMLInputElement>
  */
-export class FileUpload extends GOVUKFrontendComponent {
+export class FileUpload extends ConfigurableComponent {
   /**
    * @private
    */
@@ -25,14 +25,6 @@ export class FileUpload extends GOVUKFrontendComponent {
    */
   $status
 
-  /**
-   * @private
-   * @type {FileUploadConfig}
-   */
-  // eslint-disable-next-line
-  // @ts-ignore
-  config
-
   /** @private */
   i18n
 
@@ -41,11 +33,7 @@ export class FileUpload extends GOVUKFrontendComponent {
    * @param {FileUploadConfig} [config] - File Upload config
    */
   constructor($root, config = {}) {
-    super($root)
-
-    if (!(this.$root instanceof HTMLInputElement)) {
-      return
-    }
+    super($root, config)
 
     if (this.$root.type !== 'file') {
       throw new ElementError(
@@ -53,12 +41,6 @@ export class FileUpload extends GOVUKFrontendComponent {
       )
     }
 
-    this.config = mergeConfigs(
-      FileUpload.defaults,
-      config,
-      normaliseDataset(FileUpload, this.$root.dataset)
-    )
-
     this.i18n = new I18n(this.config.i18n, {
       // Read the fallback if necessary rather than have it set in the defaults
       locale: closestAttributeValue(this.$root, 'lang')
@@ -140,11 +122,6 @@ export class FileUpload extends GOVUKFrontendComponent {
     // @ts-ignore
     const fileCount = this.$root.files.length // eslint-disable-line
 
-    // trying to appease typescript
-    if (!this.$status || !this.i18n) {
-      return
-    }
-
     if (fileCount === 0) {
       // If there are no files, show the default selection text
       this.$status.innerText = this.i18n.t('filesSelectedDefault')
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 1975edb351..4c33a2eba0 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -1,3 +1,5 @@
+/* eslint-disable no-new */
+
 const { render } = require('@govuk-frontend/helpers/puppeteer')
 const { getExamples } = require('@govuk-frontend/lib/components')
 
@@ -334,6 +336,69 @@ describe('/components/file-upload', () => {
           examples = await getExamples('file-upload')
         })
 
+        it('can throw a SupportError if appropriate', async () => {
+          await expect(
+            render(page, 'file-upload', examples.default, {
+              beforeInitialisation() {
+                document.body.classList.remove('govuk-frontend-supported')
+              }
+            })
+          ).rejects.toMatchObject({
+            cause: {
+              name: 'SupportError',
+              message:
+                'GOV.UK Frontend initialised without `<body class="govuk-frontend-supported">` from template `<script>` snippet'
+            }
+          })
+        })
+
+        it('throws when initialised twice', async () => {
+          await expect(
+            render(page, 'file-upload', examples.default, {
+              async afterInitialisation($root) {
+                const { FileUpload } = await import('govuk-frontend')
+                new FileUpload($root)
+              }
+            })
+          ).rejects.toMatchObject({
+            name: 'InitError',
+            message:
+              'govuk-file-upload: Root element (`$root`) already initialised'
+          })
+        })
+
+        it('throws when $root is not set', async () => {
+          await expect(
+            render(page, 'file-upload', examples.default, {
+              beforeInitialisation($root) {
+                $root.remove()
+              }
+            })
+          ).rejects.toMatchObject({
+            cause: {
+              name: 'ElementError',
+              message: 'govuk-file-upload: Root element (`$root`) not found'
+            }
+          })
+        })
+
+        it('throws when receiving the wrong type for $root', async () => {
+          await expect(
+            render(page, 'file-upload', examples.default, {
+              beforeInitialisation($root) {
+                // Replace with an `<svg>` element which is not an `HTMLElement` in the DOM (but an `SVGElement`)
+                $root.outerHTML = `<svg data-module="govuk-file-upload"></svg>`
+              }
+            })
+          ).rejects.toMatchObject({
+            cause: {
+              name: 'ElementError',
+              message:
+                'govuk-file-upload: Root element (`$root`) is not of type HTMLElement'
+            }
+          })
+        })
+
         describe('missing or misconfigured elements', () => {
           it('throws if the input type is not "file"', async () => {
             await expect(

From 91f083097e086e26b42b48078dd549da77c2d09d Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 9 Jan 2025 16:17:53 +0000
Subject: [PATCH 17/77] Format error message consistently

Make the error message when the `<input>` does not have the expected type
consistent with the messages from the other errors thrown by the component.
---
 .../src/govuk/components/file-upload/file-upload.mjs        | 6 +++++-
 .../components/file-upload/file-upload.puppeteer.test.js    | 2 +-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index deb0e10ceb..232cc29c80 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -1,5 +1,6 @@
 import { closestAttributeValue } from '../../common/closest-attribute-value.mjs'
 import { ConfigurableComponent } from '../../common/configuration.mjs'
+import { formatErrorMessage } from '../../common/index.mjs'
 import { ElementError } from '../../errors/index.mjs'
 import { I18n } from '../../i18n.mjs'
 
@@ -37,7 +38,10 @@ export class FileUpload extends ConfigurableComponent {
 
     if (this.$root.type !== 'file') {
       throw new ElementError(
-        'File upload: Form field must be an input of type `file`.'
+        formatErrorMessage(
+          FileUpload,
+          'Form field must be an input of type `file`.'
+        )
       )
     }
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 4c33a2eba0..8340fc6f82 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -413,7 +413,7 @@ describe('/components/file-upload', () => {
               cause: {
                 name: 'ElementError',
                 message:
-                  'File upload: Form field must be an input of type `file`.'
+                  'govuk-file-upload: Form field must be an input of type `file`.'
               }
             })
           })

From a62fa40926a8cc49b8094d590f669bd3385999f7 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 10 Jan 2025 18:14:27 +0000
Subject: [PATCH 18/77] Remove comments ignoring TypeScript or linting errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Everything lints OK, nice one @querkmachine and @owenatgov 🙌
---
 .../src/govuk/components/file-upload/file-upload.mjs | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 232cc29c80..8a369be98b 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -122,9 +122,7 @@ export class FileUpload extends ConfigurableComponent {
       return
     }
 
-    // eslint-disable-next-line
-    // @ts-ignore
-    const fileCount = this.$root.files.length // eslint-disable-line
+    const fileCount = this.$root.files.length
 
     if (fileCount === 0) {
       // If there are no files, show the default selection text
@@ -133,9 +131,7 @@ export class FileUpload extends ConfigurableComponent {
       // If there is 1 file, just show the file name
       fileCount === 1
     ) {
-      // eslint-disable-next-line
-      // @ts-ignore
-      this.$status.innerText = this.$root.files[0].name // eslint-disable-line
+      this.$status.innerText = this.$root.files[0].name
     } else {
       // Otherwise, tell the user how many files are selected
       this.$status.innerText = this.i18n.t('filesSelected', {
@@ -164,8 +160,6 @@ export class FileUpload extends ConfigurableComponent {
     // else), we only want to indicate files.
     console.log(event)
 
-    // eslint-disable-next-line
-    // @ts-ignore
     this.$wrapper.classList.add('govuk-file-upload-wrapper--show-dropzone')
   }
 
@@ -174,8 +168,6 @@ export class FileUpload extends ConfigurableComponent {
    * remove the visual indicator.
    */
   onDragLeaveOrDrop() {
-    // eslint-disable-next-line
-    // @ts-ignore
     this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
   }
 

From ebb4e9e605bd6aba2decb490c77dd0531e37c575 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 10 Jan 2025 18:22:59 +0000
Subject: [PATCH 19/77] Remove unnecessary `if` statements

They were checking for elements we know exist or were of the right type,
because we either check that in the constructor or create them.
---
 .../src/govuk/components/file-upload/file-upload.mjs  | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 8a369be98b..02ca1ca0d9 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -114,10 +114,6 @@ export class FileUpload extends ConfigurableComponent {
    * Check if the value of the underlying input has changed
    */
   onChange() {
-    if (!('files' in this.$root)) {
-      return
-    }
-
     if (!this.$root.files) {
       return
     }
@@ -196,13 +192,6 @@ export class FileUpload extends ConfigurableComponent {
    * Synchronise the `disabled` state between the input and replacement button.
    */
   updateDisabledState() {
-    if (
-      !(this.$root instanceof HTMLInputElement) ||
-      !(this.$button instanceof HTMLButtonElement)
-    ) {
-      return
-    }
-
     this.$button.disabled = this.$root.disabled
   }
 

From 9af463c61df8f5075bb4a23e1a9e5d0ed7fe4d68 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 10 Jan 2025 18:26:53 +0000
Subject: [PATCH 20/77] Encapsulate lookup of the `<label>` element

This allows TypeScript to type `this.$label` for sure to `HTMLElement`,
which it couldn't do when we were assigning it the result of `querySelector`
in the constructor.
---
 .../components/file-upload/file-upload.mjs    | 34 +++++++++++++------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 02ca1ca0d9..9d8df3279f 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -50,14 +50,7 @@ export class FileUpload extends ConfigurableComponent {
       locale: closestAttributeValue(this.$root, 'lang')
     })
 
-    this.$label = document.querySelector(`[for="${this.$root.id}"]`)
-
-    if (!this.$label) {
-      throw new ElementError({
-        component: FileUpload,
-        identifier: 'No label'
-      })
-    }
+    this.$label = this.findLabel()
 
     // Wrapping element. This defines the boundaries of our drag and drop area.
     const $wrapper = document.createElement('div')
@@ -136,13 +129,32 @@ export class FileUpload extends ConfigurableComponent {
     }
   }
 
+  /**
+   * Looks up the `<label>` element associated to the field
+   *
+   * @private
+   * @returns {HTMLElement} The `<label>` element associated to the field
+   * @throws {ElementError} If the `<label>` cannot be found
+   */
+  findLabel() {
+    // Use `label` in the selector so TypeScript knows the type fo `HTMLElement`
+    const $label = document.querySelector(`label[for="${this.$root.id}"]`)
+
+    if (!$label) {
+      throw new ElementError({
+        component: FileUpload,
+        identifier: 'No label'
+      })
+    }
+
+    return $label
+  }
+
   /**
    * When the button is clicked, emulate clicking the actual, hidden file input
    */
   onClick() {
-    if (this.$label instanceof HTMLElement) {
-      this.$label.click()
-    }
+    this.$label.click()
   }
 
   /**

From 55b86e77ed262fa73d9758a6fdb9331c0389183c Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 10 Jan 2025 18:38:17 +0000
Subject: [PATCH 21/77] Remove unnecessary check for existence of the `files`
 attribute

We check that `$root` is an input with `type="file"` so it will have a `files`
property that's not null.
---
 .../src/govuk/components/file-upload/file-upload.mjs   | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 9d8df3279f..a8ce5c0e8b 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -8,7 +8,7 @@ import { I18n } from '../../i18n.mjs'
  * File upload component
  *
  * @preserve
- * @augments ConfigurableComponent<FileUploadConfig,HTMLInputElement>
+ * @augments ConfigurableComponent<FileUploadConfig,HTMLFileInputElement>
  */
 export class FileUpload extends ConfigurableComponent {
   /**
@@ -107,10 +107,6 @@ export class FileUpload extends ConfigurableComponent {
    * Check if the value of the underlying input has changed
    */
   onChange() {
-    if (!this.$root.files) {
-      return
-    }
-
     const fileCount = this.$root.files.length
 
     if (fileCount === 0) {
@@ -245,6 +241,10 @@ export class FileUpload extends ConfigurableComponent {
   })
 }
 
+/**
+ * @typedef {HTMLInputElement & {files: FileList}} HTMLFileInputElement
+ */
+
 /**
  * File upload config
  *

From 6508c1b19fc6dbf90088be99b19c62f3f1dc71e8 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Mon, 13 Jan 2025 19:26:16 +0000
Subject: [PATCH 22/77] Improve handling of visual feedback showing the
 dropzone

- Only show the dropzone when the user drags into it rather than when entering the document. This will prevent multiple announcements when we add feedback for screenreaders, in case there's multiple `FileUpload`s on the page
- Add a test to check if the user is dragging files before showing dropzone
- Fix disappearance of the dropzone due to many `dragleave` events being triggered as user drags over the different elements inside the wrapper
- Separate the handler of `drop` event as it doesn't need the same complexity as the `dragleave` one before hiding the dropzone.

The component still relies on the native `<input>` receiving the files being dropped, as it ensures a `change` event gets triggered on drop (which we'd have to simulate if setting its `files` properties programmatically).
---
 .../components/file-upload/file-upload.mjs    | 100 +++++++++++++-----
 1 file changed, 73 insertions(+), 27 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index a8ce5c0e8b..937329d2bd 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -95,12 +95,61 @@ export class FileUpload extends ConfigurableComponent {
     // Bind change event to the underlying input
     this.$root.addEventListener('change', this.onChange.bind(this))
 
-    // When a file is dropped on the input
-    this.$wrapper.addEventListener('drop', this.onDragLeaveOrDrop.bind(this))
+    // Handle drag'n'drop events
+    this.$wrapper.addEventListener('drop', this.onDrop.bind(this))
 
-    // When a file is dragged over the page (or dragged off the page)
-    document.addEventListener('dragenter', this.onDragEnter.bind(this))
-    document.addEventListener('dragleave', this.onDragLeaveOrDrop.bind(this))
+    this.$wrapper.addEventListener('dragenter', this.onDragEnter.bind(this))
+    this.$wrapper.addEventListener('dragleave', this.onDragLeave.bind(this))
+  }
+
+  /**
+   * Handles the users entering the area where they can drop their files
+   *
+   * Reveals the drop zone if the user components accepts what the user
+   * is dragging
+   *
+   * @param {DragEvent} event - The `dragenter` event
+   */
+  onDragEnter(event) {
+    // TypeScript anticipates that `event.dataTransfer` may be `null`
+    // so we need to check for falsiness first
+    if (event.dataTransfer && isContainingFiles(event.dataTransfer)) {
+      this.$wrapper.classList.add('govuk-file-upload-wrapper--show-dropzone')
+    }
+  }
+
+  /**
+   * Hides the drop zone visually when users mouse leave it
+   *
+   * `dragleave` events will fire for each element that the user moves
+   * their move out of. We only want to remove the styling when
+   * they either leave the wrapper or the window altogether
+   *
+   * @param {DragEvent} event - The `dragleave` event
+   */
+  onDragLeave(event) {
+    // `relatedTarget` is only an `EventTarget` so we need to check if it's :
+    // - it's a `Node` in which case we'd still be on the page
+    // - something else in which case user has left the page
+    const relatedTarget =
+      event.relatedTarget instanceof Node ? event.relatedTarget : null
+
+    const leavesWindow = !relatedTarget
+    const leavesDropZone = !this.$wrapper.contains(relatedTarget)
+    if (leavesWindow || leavesDropZone) {
+      this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
+    }
+  }
+
+  /**
+   * Hides the dropzone once user has dropped files on the `<input>`
+   *
+   * Note: the component relies on the native behaviour to get the files
+   * being dragged set as value of the `<input>`. This allows a `change`
+   * event to be automatically fired from the element.
+   */
+  onDrop() {
+    this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
   }
 
   /**
@@ -153,28 +202,6 @@ export class FileUpload extends ConfigurableComponent {
     this.$label.click()
   }
 
-  /**
-   * When a file is dragged over the container, show a visual indicator that a
-   * file can be dropped here.
-   *
-   * @param {DragEvent} event - the drag event
-   */
-  onDragEnter(event) {
-    // Check if the thing being dragged is a file (and not text or something
-    // else), we only want to indicate files.
-    console.log(event)
-
-    this.$wrapper.classList.add('govuk-file-upload-wrapper--show-dropzone')
-  }
-
-  /**
-   * When a dragged file leaves the container, or the file is dropped,
-   * remove the visual indicator.
-   */
-  onDragLeaveOrDrop() {
-    this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
-  }
-
   /**
    * Create a mutation observer to check if the input's attributes altered.
    */
@@ -241,6 +268,25 @@ export class FileUpload extends ConfigurableComponent {
   })
 }
 
+/**
+ * Checks if the given `DataTransfer` contains files
+ *
+ * @internal
+ * @param {DataTransfer} dataTransfer - The `DataTransfer` to check
+ * @returns {boolean} - `true` if it contains files or we can't infer it, `false` otherwise
+ */
+function isContainingFiles(dataTransfer) {
+  // Safari sometimes does not provide info about types :'(
+  // In which case best not to assume anything and try to set the files
+  const hasNoTypesInfo = dataTransfer.types.length === 0
+
+  // When dragging images, there's a mix of mime types + Files
+  // which we can't assign to the native input
+  const isDraggingFiles = dataTransfer.types.some((type) => type === 'Files')
+
+  return hasNoTypesInfo || isDraggingFiles
+}
+
 /**
  * @typedef {HTMLInputElement & {files: FileList}} HTMLFileInputElement
  */

From df6c46288cc0fa34287473a98c8d37464501dac2 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 16 Jan 2025 18:22:09 +0000
Subject: [PATCH 23/77] Fixes issue in Safari where dropzone was disappearing

It happened when dragging from the button to the span or the opposite,
because Safari does not fill the `relatedTarget` on `dragleave`, making
our code believe user had left the window.

To accomodate for that, we use `dragenter` to also hide the drop zone
when entering an element that's not the wrapper.

This may still leave a gap where the component is at the edge of the viewport,
either because of scrolling or in a iframe. Will explore in next commit.
---
 .../components/file-upload/file-upload.mjs    | 52 +++++++------------
 1 file changed, 20 insertions(+), 32 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 937329d2bd..32a75eaf93 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -98,46 +98,34 @@ export class FileUpload extends ConfigurableComponent {
     // Handle drag'n'drop events
     this.$wrapper.addEventListener('drop', this.onDrop.bind(this))
 
-    this.$wrapper.addEventListener('dragenter', this.onDragEnter.bind(this))
-    this.$wrapper.addEventListener('dragleave', this.onDragLeave.bind(this))
+    document.addEventListener('dragenter', this.onDragEnter.bind(this))
   }
 
   /**
-   * Handles the users entering the area where they can drop their files
+   * Handles the users entering elements on the page
    *
-   * Reveals the drop zone if the user components accepts what the user
-   * is dragging
+   * Because of Safari's lack of support for `relatedTarget` on `dragleave`,
+   * we need to use this both to reveal the drop zone when user's cursor enter it,
+   * and hide it when leaving (ie. entering another element).
+   * https://bugs.webkit.org/show_bug.cgi?id=66547
    *
    * @param {DragEvent} event - The `dragenter` event
    */
   onDragEnter(event) {
-    // TypeScript anticipates that `event.dataTransfer` may be `null`
-    // so we need to check for falsiness first
-    if (event.dataTransfer && isContainingFiles(event.dataTransfer)) {
-      this.$wrapper.classList.add('govuk-file-upload-wrapper--show-dropzone')
-    }
-  }
-
-  /**
-   * Hides the drop zone visually when users mouse leave it
-   *
-   * `dragleave` events will fire for each element that the user moves
-   * their move out of. We only want to remove the styling when
-   * they either leave the wrapper or the window altogether
-   *
-   * @param {DragEvent} event - The `dragleave` event
-   */
-  onDragLeave(event) {
-    // `relatedTarget` is only an `EventTarget` so we need to check if it's :
-    // - it's a `Node` in which case we'd still be on the page
-    // - something else in which case user has left the page
-    const relatedTarget =
-      event.relatedTarget instanceof Node ? event.relatedTarget : null
-
-    const leavesWindow = !relatedTarget
-    const leavesDropZone = !this.$wrapper.contains(relatedTarget)
-    if (leavesWindow || leavesDropZone) {
-      this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
+    // DOM interfaces only type `event.target` as `EventTarget`
+    // so we first need to make sure it's a `Node`
+    if (event.target instanceof Node) {
+      if (this.$wrapper.contains(event.target)) {
+        if (event.dataTransfer && isContainingFiles(event.dataTransfer)) {
+          this.$wrapper.classList.add(
+            'govuk-file-upload-wrapper--show-dropzone'
+          )
+        }
+      } else {
+        this.$wrapper.classList.remove(
+          'govuk-file-upload-wrapper--show-dropzone'
+        )
+      }
     }
   }
 

From ac0590eea73a306a3a70b407ae09967b64fc5a2d Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 17 Jan 2025 18:21:12 +0000
Subject: [PATCH 24/77] Detect when users drag outside of the viewport

---
 .../components/file-upload/file-upload.mjs    | 63 +++++++++++++------
 1 file changed, 45 insertions(+), 18 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 32a75eaf93..02b9baae96 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -95,23 +95,56 @@ export class FileUpload extends ConfigurableComponent {
     // Bind change event to the underlying input
     this.$root.addEventListener('change', this.onChange.bind(this))
 
-    // Handle drag'n'drop events
-    this.$wrapper.addEventListener('drop', this.onDrop.bind(this))
+    // Handle drop zone visibility
+    // The easy bit, when dropping hide the dropzone
+    //
+    // Note: the component relies on the native behaviour to get the files
+    // being dragged set as value of the `<input>`. This allows a `change`
+    // event to be automatically fired from the element and saves us from having
+    // to do anything more than hiding the dropzone on drop.
+    this.$wrapper.addEventListener('drop', this.hideDropZone.bind(this))
+
+    // While user is dragging, it gets a little more complex because of Safari.
+    // Safari doesn't fill `relatedTarget` on `dragleave` (nor `dragenter`).
+    // This means we can't use `relatedTarget` to:
+    // - check if the user is still within the wrapper
+    //   (`relatedTarget` being a descendant of the wrapper)
+    // - check if the user is still over the viewport
+    //   (`relatedTarget` being null if outside)
+
+    // Thanks to `dragenter` bubbling, we can listen on the `document` with a
+    // single function and update the visibility based on whether we entered a
+    // node inside or outside the wrapper.
+    document.addEventListener(
+      'dragenter',
+      this.updateDropzoneVisibility.bind(this)
+    )
+
+    // To detect if we're outside the document, we can track if there was a
+    // `dragenter` event preceding a `dragleave`. If there wasn't, this means
+    // we're outside the document.
+    //
+    // The order of events is guaranteed by the HTML specs:
+    // https://html.spec.whatwg.org/multipage/dnd.html#drag-and-drop-processing-model
+    document.addEventListener('dragenter', () => {
+      this.enteredAnotherElement = true
+    })
+
+    document.addEventListener('dragleave', () => {
+      if (!this.enteredAnotherElement) {
+        this.hideDropZone()
+      }
 
-    document.addEventListener('dragenter', this.onDragEnter.bind(this))
+      this.enteredAnotherElement = false
+    })
   }
 
   /**
-   * Handles the users entering elements on the page
-   *
-   * Because of Safari's lack of support for `relatedTarget` on `dragleave`,
-   * we need to use this both to reveal the drop zone when user's cursor enter it,
-   * and hide it when leaving (ie. entering another element).
-   * https://bugs.webkit.org/show_bug.cgi?id=66547
+   * Updates the visibility of the dropzone as users enters the various elements on the page
    *
    * @param {DragEvent} event - The `dragenter` event
    */
-  onDragEnter(event) {
+  updateDropzoneVisibility(event) {
     // DOM interfaces only type `event.target` as `EventTarget`
     // so we first need to make sure it's a `Node`
     if (event.target instanceof Node) {
@@ -122,21 +155,15 @@ export class FileUpload extends ConfigurableComponent {
           )
         }
       } else {
-        this.$wrapper.classList.remove(
-          'govuk-file-upload-wrapper--show-dropzone'
-        )
+        this.hideDropZone()
       }
     }
   }
 
   /**
    * Hides the dropzone once user has dropped files on the `<input>`
-   *
-   * Note: the component relies on the native behaviour to get the files
-   * being dragged set as value of the `<input>`. This allows a `change`
-   * event to be automatically fired from the element.
    */
-  onDrop() {
+  hideDropZone() {
     this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
   }
 

From 996e625801765c4b5e17c154d0cce12d978e4d3e Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 17 Jan 2025 19:03:10 +0000
Subject: [PATCH 25/77] Add live region to give drag'n'drop feedback to
 assistive tech

Announces when users enter or leave the drop zone.

Note: this seems to only be announced by Voice Over
when Safari is in the foreground, even when using `aria-live="assertive"`
---
 .../components/file-upload/file-upload.mjs    | 39 +++++++++++++++++--
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 02b9baae96..91605a27d3 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -96,6 +96,12 @@ export class FileUpload extends ConfigurableComponent {
     this.$root.addEventListener('change', this.onChange.bind(this))
 
     // Handle drop zone visibility
+    // A live region to announce when users enter or leave the drop zone
+    this.$announcements = document.createElement('span')
+    this.$announcements.classList.add('govuk-visually-hidden')
+    this.$announcements.setAttribute('aria-live', 'assertive')
+    this.$wrapper.insertAdjacentElement('afterend', this.$announcements)
+
     // The easy bit, when dropping hide the dropzone
     //
     // Note: the component relies on the native behaviour to get the files
@@ -150,12 +156,30 @@ export class FileUpload extends ConfigurableComponent {
     if (event.target instanceof Node) {
       if (this.$wrapper.contains(event.target)) {
         if (event.dataTransfer && isContainingFiles(event.dataTransfer)) {
-          this.$wrapper.classList.add(
+          // Only update the class and make the announcement if not already visible
+          // to avoid repeated announcements on NVDA (2024.4) + Firefox (133)
+          if (
+            !this.$wrapper.classList.contains(
+              'govuk-file-upload-wrapper--show-dropzone'
+            )
+          ) {
+            this.$wrapper.classList.add(
+              'govuk-file-upload-wrapper--show-dropzone'
+            )
+            this.$announcements.innerText = this.i18n.t('dropZoneEntered')
+          }
+        }
+      } else {
+        // Only hide the dropzone if it is visible to prevent announcing user
+        // left the drop zone when they enter the page but haven't reached yet
+        // the file upload component
+        if (
+          this.$wrapper.classList.contains(
             'govuk-file-upload-wrapper--show-dropzone'
           )
+        ) {
+          this.hideDropZone()
         }
-      } else {
-        this.hideDropZone()
       }
     }
   }
@@ -165,6 +189,7 @@ export class FileUpload extends ConfigurableComponent {
    */
   hideDropZone() {
     this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
+    this.$announcements.innerText = this.i18n.t('dropZoneLeft')
   }
 
   /**
@@ -266,7 +291,9 @@ export class FileUpload extends ConfigurableComponent {
         // instead, however it's here for coverage's sake
         one: '%{count} file chosen',
         other: '%{count} files chosen'
-      }
+      },
+      dropZoneEntered: 'Entered drop zone',
+      dropZoneLeft: 'Left drop zone'
     }
   })
 
@@ -324,6 +351,10 @@ function isContainingFiles(dataTransfer) {
  * @property {string} [selectFiles] - Text of button that opens file browser
  * @property {TranslationPluralForms} [filesSelected] - Text indicating how
  *   many files have been selected
+ * @property {string} [dropZoneEntered] - Text announced to assistive technology
+ *   when users entered the drop zone while dragging
+ * @property {string} [dropZoneLeft] - Text announced to assistive technology
+ *   when users left the drop zone while dragging
  */
 
 /**

From d657e16c2ac780af066c7506822ada1b41df0ed6 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Mon, 20 Jan 2025 18:41:40 +0000
Subject: [PATCH 26/77] Add tests to drag and drop features

---
 .../components/file-upload/file-upload.mjs    |   1 +
 .../file-upload/file-upload.puppeteer.test.js | 102 ++++++++++++++++++
 2 files changed, 103 insertions(+)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 91605a27d3..7fb1e3a706 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -98,6 +98,7 @@ export class FileUpload extends ConfigurableComponent {
     // Handle drop zone visibility
     // A live region to announce when users enter or leave the drop zone
     this.$announcements = document.createElement('span')
+    this.$announcements.classList.add('govuk-file-upload-announcements')
     this.$announcements.classList.add('govuk-visually-hidden')
     this.$announcements.setAttribute('aria-live', 'assertive')
     this.$wrapper.insertAdjacentElement('afterend', this.$announcements)
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 8340fc6f82..297e2d9e09 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -246,6 +246,108 @@ describe('/components/file-upload', () => {
         })
       })
 
+      describe('dropzone', () => {
+        let $wrapper
+        let $announcements
+        let wrapperBoundingBox
+
+        // Shared data to drag on the element
+        const dragData = {
+          items: [],
+          files: [__filename],
+          dragOperationsMask: 1 // Copy
+        }
+
+        const selectorDropzoneVisible =
+          '.govuk-file-upload-wrapper.govuk-file-upload-wrapper--show-dropzone'
+        const selectorDropzoneHidden =
+          '.govuk-file-upload-wrapper:not(.govuk-file-upload-wrapper--show-dropzone)'
+
+        beforeEach(async () => {
+          await render(page, 'file-upload', examples.default)
+
+          $wrapper = await page.$('.govuk-file-upload-wrapper')
+          wrapperBoundingBox = await $wrapper.boundingBox()
+
+          $announcements = await page.$('.govuk-file-upload-announcements')
+        })
+
+        it('is not shown by default', async () => {
+          await expect(page.$(selectorDropzoneHidden)).resolves.toBeTruthy()
+          await expect(
+            $announcements.evaluate((e) => e.textContent)
+          ).resolves.toBe('')
+        })
+
+        it('gets shown when entering the field', async () => {
+          // Add a little pixel to make sure we're effectively within the element
+          await page.mouse.dragEnter(
+            { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
+            structuredClone(dragData)
+          )
+
+          await expect(page.$(selectorDropzoneVisible)).resolves.toBeTruthy()
+          await expect(
+            $announcements.evaluate((e) => e.textContent)
+          ).resolves.toBe('Entered drop zone')
+        })
+
+        it('gets hidden when dropping on the field', async () => {
+          // Add a little pixel to make sure we're effectively within the element
+          await page.mouse.drop(
+            { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
+            structuredClone(dragData)
+          )
+
+          await expect(page.$(selectorDropzoneHidden)).resolves.toBeTruthy()
+          // The presence of 'Left drop zone' confirms we handled the leaving of the drop zone
+          // rather than being in the initial state
+          await expect(
+            $announcements.evaluate((e) => e.textContent)
+          ).resolves.toBe('Left drop zone')
+        })
+
+        it('gets hidden when dragging a file and leaving the field', async () => {
+          // Add a little pixel to make sure we're effectively within the element
+          await page.mouse.dragEnter(
+            { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
+            structuredClone(dragData)
+          )
+
+          // Move enough to the left to be out of the wrapper properly
+          // but not up or down in case there's other elements in the flow of the page
+          await page.mouse.dragEnter(
+            { x: wrapperBoundingBox.x - 20, y: wrapperBoundingBox.y },
+            structuredClone(dragData)
+          )
+
+          await expect(page.$(selectorDropzoneHidden)).resolves.toBeTruthy()
+          await expect(
+            $announcements.evaluate((e) => e.textContent)
+          ).resolves.toBe('Left drop zone')
+        })
+
+        it('gets hidden when dragging a file and leaving the document', async () => {
+          // Add a little pixel to make sure we're effectively within the element
+          await page.mouse.dragEnter(
+            { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
+            structuredClone(dragData)
+          )
+
+          // It doesn't seem doable to make Puppeteer drag outside the viewport
+          // so instead, we can only mock two 'dragleave' events
+          await page.$eval('.govuk-file-upload-wrapper', ($el) => {
+            $el.dispatchEvent(new Event('dragleave', { bubbles: true }))
+            $el.dispatchEvent(new Event('dragleave', { bubbles: true }))
+          })
+
+          await expect(page.$(selectorDropzoneHidden)).resolves.toBeTruthy()
+          await expect(
+            $announcements.evaluate((e) => e.textContent)
+          ).resolves.toBe('Left drop zone')
+        })
+      })
+
       describe('i18n', () => {
         beforeEach(async () => {
           await render(page, 'file-upload', examples.translated)

From c23fbff1874a75341103a124041621a66a8b8248 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Wed, 15 Jan 2025 15:02:20 +0000
Subject: [PATCH 27/77] Replace the native file upload with a button

Button replaces entire native file upload. This replacement has a within
it a "psuedo button" span that has the same focus, hover and active
behaviour as a secondary button.
---
 .../govuk/components/file-upload/_index.scss  | 51 ++++++++++++++++++-
 .../components/file-upload/file-upload.mjs    | 32 +++++++++---
 2 files changed, 74 insertions(+), 9 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 309ea05fd5..2f0b702a7b 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -64,7 +64,7 @@
     border: $govuk-border-width-form-element dashed $govuk-input-border-colour;
     background-color: $govuk-body-background-colour;
 
-    .govuk-file-upload__button,
+    .govuk-file-upload__pseudo-button,
     .govuk-file-upload__status {
       // When the dropzone is hovered over, make these aspects not accept
       // mouse events, so dropped files fall through to the input beneath them
@@ -85,7 +85,7 @@
     opacity: 0;
   }
 
-  .govuk-file-upload__button {
+  .govuk-file-upload__pseudo-button {
     width: auto;
     margin-bottom: 0;
     flex-grow: 0;
@@ -97,3 +97,50 @@
     margin-left: govuk-spacing(2);
   }
 }
+
+.govuk-file-upload__button:focus {
+  outline: none;
+}
+
+.govuk-file-upload__button:focus .govuk-file-upload__pseudo-button {
+  outline: 3px solid transparent;
+  background-color: $govuk-focus-colour;
+  box-shadow: 0 2px 0 govuk-colour("black");
+}
+
+.govuk-file-upload__button:focus .govuk-file-upload__pseudo-button:hover {
+  border-color: $govuk-focus-colour;
+  outline: 3px solid transparent;
+  background-color: govuk-colour("light-grey");
+  box-shadow: inset 0 0 0 1px $govuk-focus-colour;
+}
+
+.govuk-file-upload__button:active .govuk-file-upload__pseudo-button:hover {
+  background-color: govuk-shade(govuk-colour("light-grey"), 20%);
+}
+
+.govuk-file-upload__button {
+  align-items: center;
+  display: flex;
+  padding: 0;
+  border: 0;
+  background-color: transparent;
+}
+
+.govuk-file-upload:disabled + .govuk-file-upload__button {
+  pointer-events: none;
+}
+
+.govuk-file-upload:disabled + .govuk-file-upload__button .govuk-file-upload__pseudo-button {
+  opacity: (0.5);
+
+  &:hover {
+    background-color: govuk-colour("light-grey");
+    cursor: not-allowed;
+  }
+
+  &:active {
+    top: 0;
+    box-shadow: 0 $govuk-border-width-form-element 0 govuk-shade(govuk-colour("white"), 60%); // s0
+  }
+}
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 7fb1e3a706..7084b27e69 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -45,6 +45,14 @@ export class FileUpload extends ConfigurableComponent {
       )
     }
 
+    if (!this.$root.id.length) {
+      throw new ElementError(
+        formatErrorMessage(FileUpload, 'Form field must specify an `id`.')
+      )
+    }
+
+    this.id = this.$root.id
+
     this.i18n = new I18n(this.config.i18n, {
       // Read the fallback if necessary rather than have it set in the defaults
       locale: closestAttributeValue(this.$root, 'lang')
@@ -58,25 +66,35 @@ export class FileUpload extends ConfigurableComponent {
 
     // Create the file selection button
     const $button = document.createElement('button')
-    $button.className =
-      'govuk-button govuk-button--secondary govuk-file-upload__button'
+    $button.classList.add('govuk-file-upload__button')
     $button.type = 'button'
-    $button.innerText = this.i18n.t('selectFilesButton')
+
+    const buttonSpan = document.createElement('span')
+    buttonSpan.className =
+      'govuk-button govuk-button--secondary govuk-file-upload__pseudo-button'
+    buttonSpan.innerText = this.i18n.t('selectFilesButton')
+
+    $button.appendChild(buttonSpan)
     $button.addEventListener('click', this.onClick.bind(this))
 
     // Create status element that shows what/how many files are selected
     const $status = document.createElement('span')
     $status.className = 'govuk-body govuk-file-upload__status'
     $status.innerText = this.i18n.t('filesSelectedDefault')
-    $status.setAttribute('role', 'status')
+    // $status.setAttribute('aria-hidden', 'true')
+
+    $button.appendChild($status)
 
     // Assemble these all together
     $wrapper.insertAdjacentElement('beforeend', $button)
-    $wrapper.insertAdjacentElement('beforeend', $status)
+    // $wrapper.insertAdjacentElement('beforeend', $status)
 
     // Inject all this *after* the native file input
     this.$root.insertAdjacentElement('afterend', $wrapper)
 
+    this.$root.setAttribute('tabindex', '-1')
+    this.$root.setAttribute('aria-hidden', 'true')
+
     // Move the native file input to inside of the wrapper
     $wrapper.insertAdjacentElement('afterbegin', this.$root)
 
@@ -85,8 +103,8 @@ export class FileUpload extends ConfigurableComponent {
     this.$button = $button
     this.$status = $status
 
-    // Prevent the hidden input being tabbed to by keyboard users
-    this.$root.setAttribute('tabindex', '-1')
+    // Bind change event to the underlying input
+    this.$root.addEventListener('change', this.onChange.bind(this))
 
     // Syncronise the `disabled` state between the button and underlying input
     this.updateDisabledState()

From bd7615e5bb52a7b7f68189ca67c022b6949b0d75 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Mon, 20 Jan 2025 11:09:40 +0000
Subject: [PATCH 28/77] Add aria-label to file upload button replacement

Hide the button text entirely from screen reader and add button content
as `aria-label`. This should lead to more consistent reading out of the
button content.
---
 .../govuk/components/file-upload/file-upload.mjs   | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 7084b27e69..8dea7ca89b 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -59,6 +59,7 @@ export class FileUpload extends ConfigurableComponent {
     })
 
     this.$label = this.findLabel()
+    this.$label.setAttribute('id', `${this.$root.getAttribute('id')}-label`)
 
     // Wrapping element. This defines the boundaries of our drag and drop area.
     const $wrapper = document.createElement('div')
@@ -73,6 +74,7 @@ export class FileUpload extends ConfigurableComponent {
     buttonSpan.className =
       'govuk-button govuk-button--secondary govuk-file-upload__pseudo-button'
     buttonSpan.innerText = this.i18n.t('selectFilesButton')
+    buttonSpan.setAttribute('aria-hidden', 'true')
 
     $button.appendChild(buttonSpan)
     $button.addEventListener('click', this.onClick.bind(this))
@@ -81,13 +83,16 @@ export class FileUpload extends ConfigurableComponent {
     const $status = document.createElement('span')
     $status.className = 'govuk-body govuk-file-upload__status'
     $status.innerText = this.i18n.t('filesSelectedDefault')
-    // $status.setAttribute('aria-hidden', 'true')
+    $status.setAttribute('aria-hidden', 'true')
 
     $button.appendChild($status)
+    $button.setAttribute(
+      'aria-label',
+      `${this.$label.innerText}, ${this.i18n.t('selectFilesButton')}, ${this.i18n.t('filesSelectedDefault')}`
+    )
 
     // Assemble these all together
     $wrapper.insertAdjacentElement('beforeend', $button)
-    // $wrapper.insertAdjacentElement('beforeend', $status)
 
     // Inject all this *after* the native file input
     this.$root.insertAdjacentElement('afterend', $wrapper)
@@ -231,6 +236,11 @@ export class FileUpload extends ConfigurableComponent {
         count: fileCount
       })
     }
+
+    this.$button.setAttribute(
+      'aria-label',
+      `${this.$label.innerText}, ${this.i18n.t('selectFilesButton')}, ${this.$status.innerText}`
+    )
   }
 
   /**

From be309ec088a6459b4970c3e3a3a0f2e3f19b706a Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Tue, 21 Jan 2025 14:38:18 +0000
Subject: [PATCH 29/77] Update tests for new file upload changes

- Tests now use the correct selector for when the input has been visually
replaced by the button.
- Added tests for button `aria-label`.
- Added test for clicking on different elements within button
---
 .../file-upload/file-upload.puppeteer.test.js | 105 ++++++++++--------
 1 file changed, 56 insertions(+), 49 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 297e2d9e09..31ada7628e 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -7,6 +7,7 @@ const inputSelector = '.govuk-file-upload'
 const wrapperSelector = '.govuk-file-upload-wrapper'
 const buttonSelector = '.govuk-file-upload__button'
 const statusSelector = '.govuk-file-upload__status'
+const pseudoButtonSelector = '.govuk-file-upload__pseudo-button'
 
 describe('/components/file-upload', () => {
   let examples
@@ -93,66 +94,59 @@ describe('/components/file-upload', () => {
           })
 
           it('renders the button with default text', async () => {
-            const buttonElementText = await page.$eval(buttonSelector, (el) =>
-              el.innerHTML.trim()
+            const buttonElementText = await page.$eval(
+              `${buttonSelector} ${pseudoButtonSelector}`,
+              (el) => el.innerHTML.trim()
             )
 
-            expect(buttonElementText).toBe('Choose file')
-          })
-        })
-
-        describe('status element', () => {
-          it('renders the status element', async () => {
-            const statusElement = await page.$eval(statusSelector, (el) => el)
-
-            expect(statusElement).toBeDefined()
-          })
-
-          it('renders the status element with role', async () => {
-            const statusElementRole = await page.$eval(statusSelector, (el) =>
-              el.getAttribute('role')
+            const statusElementText = await page.$eval(
+              `${buttonSelector} ${statusSelector}`,
+              (el) => el.innerHTML.trim()
             )
 
-            expect(statusElementRole).toBe('status')
-          })
-
-          it('renders the status element with default text', async () => {
-            const statusElementText = await page.$eval(statusSelector, (el) =>
-              el.innerHTML.trim()
+            const buttonAriaText = await page.$eval(buttonSelector, (el) =>
+              el.getAttribute('aria-label')
             )
 
+            expect(buttonElementText).toBe('Choose file')
             expect(statusElementText).toBe('No file chosen')
+            expect(buttonAriaText).toBe(
+              'Upload a file, Choose file, No file chosen'
+            )
           })
         })
       })
 
       describe('when clicking the choose file button', () => {
-        it('opens the file picker', async () => {
-          // It doesn't seem to be possible to check if the file picker dialog
-          // opens as an isolated test, so this test clicks the button, tries to
-          // set a value in the file chooser, then checks if that value was set
-          // on the input as expected.
-          const testFilename = 'test.gif'
-          await render(page, 'file-upload', examples.default)
+        it.each([buttonSelector, pseudoButtonSelector, statusSelector])(
+          'opens the file picker',
+          async (selector) => {
+            // It doesn't seem to be possible to check if the file picker dialog
+            // opens as an isolated test, so this test clicks the button, tries to
+            // set a value in the file chooser, then checks if that value was set
+            // on the input as expected.
+            const testFilename = 'test.gif'
+            await render(page, 'file-upload', examples.default)
 
-          const [fileChooser] = await Promise.all([
-            page.waitForFileChooser(),
-            page.click(buttonSelector)
-          ])
+            const [fileChooser] = await Promise.all([
+              page.waitForFileChooser(),
+              page.click(selector)
+            ])
 
-          await fileChooser.accept([testFilename])
+            await fileChooser.accept([testFilename])
 
-          const inputElementValue = await page.$eval(
-            inputSelector,
-            (el) =>
-              // @ts-ignore
-              el.value
-          )
+            const inputElementValue = await page.$eval(
+              inputSelector,
+              (el) =>
+                // @ts-ignore
+                el.value
+            )
 
-          // For Windows and backward compatibility, the values of file inputs
-          // are always formatted starting with `C:\\fakepath\\`
-          expect(inputElementValue).toBe(`C:\\fakepath\\${testFilename}`)
-        })
+            // For Windows and backward compatibility, the values of file inputs
+            // are always formatted starting with `C:\\fakepath\\`
+            expect(inputElementValue).toBe(`C:\\fakepath\\${testFilename}`)
+          }
+        )
       })
 
       describe('when selecting a file', () => {
@@ -163,7 +157,7 @@ describe('/components/file-upload', () => {
 
           const [fileChooser] = await Promise.all([
             page.waitForFileChooser(),
-            page.click(inputSelector)
+            page.click(buttonSelector)
           ])
           await fileChooser.accept([testFilename])
         })
@@ -206,7 +200,7 @@ describe('/components/file-upload', () => {
 
           const [fileChooser] = await Promise.all([
             page.waitForFileChooser(),
-            page.click(inputSelector)
+            page.click(buttonSelector)
           ])
           await fileChooser.accept(['testfile1.txt', 'testfile2.pdf'])
         })
@@ -354,11 +348,24 @@ describe('/components/file-upload', () => {
         })
 
         it('uses the correct translation for the choose file button', async () => {
-          const buttonText = await page.$eval(buttonSelector, (el) =>
+          const buttonElementText = await page.$eval(
+            pseudoButtonSelector,
+            (el) => el.innerHTML.trim()
+          )
+
+          const statusElementText = await page.$eval(statusSelector, (el) =>
             el.innerHTML.trim()
           )
 
-          expect(buttonText).toBe('Dewiswch ffeil')
+          const buttonAriaText = await page.$eval(buttonSelector, (el) =>
+            el.getAttribute('aria-label')
+          )
+
+          expect(buttonElementText).toBe('Dewiswch ffeil')
+          expect(statusElementText).toBe("Dim ffeiliau wedi'u dewis")
+          expect(buttonAriaText).toBe(
+            "Llwythwch ffeil i fyny, Dewiswch ffeil, Dim ffeiliau wedi'u dewis"
+          )
         })
 
         describe('status element', () => {
@@ -373,7 +380,7 @@ describe('/components/file-upload', () => {
           it('uses the correct translation when multiple files are selected', async () => {
             const [fileChooser] = await Promise.all([
               page.waitForFileChooser(),
-              page.click(inputSelector)
+              page.click(buttonSelector)
             ])
             await fileChooser.accept(['testfile1.txt', 'testfile2.pdf'])
 

From 8cbb2648063a1eadbedbbaf083b9bae1c4b0c452 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Tue, 21 Jan 2025 14:38:34 +0000
Subject: [PATCH 30/77] Correct focus for file upload in error summary

Adjustments made to the the file upload so that in the event of an error
the correct part of the page can be linked to.
---
 .../src/govuk/components/file-upload/file-upload.mjs | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 8dea7ca89b..b25d1a3b9f 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -29,6 +29,9 @@ export class FileUpload extends ConfigurableComponent {
   /** @private */
   i18n
 
+  /** @private */
+  id
+
   /**
    * @param {Element | null} $root - File input element
    * @param {FileUploadConfig} [config] - File Upload config
@@ -59,7 +62,11 @@ export class FileUpload extends ConfigurableComponent {
     })
 
     this.$label = this.findLabel()
-    this.$label.setAttribute('id', `${this.$root.getAttribute('id')}-label`)
+
+    // we need to copy the 'id' of the root element
+    // to the new button replacement element
+    // so that focus will work in the error summary
+    this.$root.id = `${this.id}-input`
 
     // Wrapping element. This defines the boundaries of our drag and drop area.
     const $wrapper = document.createElement('div')
@@ -69,6 +76,7 @@ export class FileUpload extends ConfigurableComponent {
     const $button = document.createElement('button')
     $button.classList.add('govuk-file-upload__button')
     $button.type = 'button'
+    $button.id = this.id
 
     const buttonSpan = document.createElement('span')
     buttonSpan.className =
@@ -268,7 +276,7 @@ export class FileUpload extends ConfigurableComponent {
    * When the button is clicked, emulate clicking the actual, hidden file input
    */
   onClick() {
-    this.$label.click()
+    this.$root.click()
   }
 
   /**

From 86e30942ec6542190c6ab4469b98f901d8a914f4 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 23 Jan 2025 15:28:35 +0000
Subject: [PATCH 31/77] Copy `aria-describedby` attribute on `<button>`

This ensure hints and errors are associated with the `<button>` for assistive technology users.
---
 .../components/file-upload/file-upload.mjs    |  7 +++++
 .../file-upload/file-upload.puppeteer.test.js | 28 +++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index b25d1a3b9f..9ca6b134bd 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -78,6 +78,13 @@ export class FileUpload extends ConfigurableComponent {
     $button.type = 'button'
     $button.id = this.id
 
+    // Copy `aria-describedby` if present so hints and errors
+    // are associated to the `<button>`
+    const ariaDescribedBy = this.$root.getAttribute('aria-describedby')
+    if (ariaDescribedBy) {
+      $button.setAttribute('aria-describedby', ariaDescribedBy)
+    }
+
     const buttonSpan = document.createElement('span')
     buttonSpan.className =
       'govuk-button govuk-button--secondary govuk-file-upload__pseudo-button'
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 31ada7628e..99ffc9dcd7 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -438,6 +438,34 @@ describe('/components/file-upload', () => {
         })
       })
 
+      describe('aria-describedby', () => {
+        it('copies the `aria-describedby` attribute from the `<input>` to the `<button>`', async () => {
+          await render(
+            page,
+            'file-upload',
+            examples['with error message and hint']
+          )
+
+          const $button = await page.$(buttonSelector)
+          const ariaDescribedBy = await $button.evaluate((el) =>
+            el.getAttribute('aria-describedby')
+          )
+
+          expect(ariaDescribedBy).toBe('file-upload-3-hint file-upload-3-error')
+        })
+
+        it('does not add an `aria-describedby` attribute to the `<button>` if there is none on the `<input>`', async () => {
+          await render(page, 'file-upload', examples.default)
+
+          const $button = await page.$(buttonSelector)
+          const ariaDescribedBy = await $button.evaluate((el) =>
+            el.getAttribute('aria-describedby')
+          )
+
+          expect(ariaDescribedBy).toBeNull()
+        })
+      })
+
       describe('errors at instantiation', () => {
         let examples
 

From 928f25a38345d153c48601f3163107b2321cf62e Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 23 Jan 2025 19:01:41 +0000
Subject: [PATCH 32/77] Add option to File Upload macro to enable JS
 enhancements

The option also controls the rendering of the translation strings,
as they're not needed if the component does not run JavaScript enhancements.

In the unlikely case that someone would want the translation strings,
but not run our JavaScript enhancements, we could add a new option. In the meantime,
the `attributes` option allows them to manually add the data attributes.
---
 .../components/file-upload/file-upload.yaml   | 26 +++++++++
 .../govuk/components/file-upload/template.njk | 30 +++++-----
 .../components/file-upload/template.test.js   | 58 +++++++++++++++++++
 3 files changed, 101 insertions(+), 13 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 9637ea648b..2242a4b022 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -77,6 +77,10 @@ params:
             type: string
             required: true
             description: HTML to add after the input. If `html` is provided, the `text` option will be ignored.
+  - name: javascript
+    type: boolean
+    required: false
+    description: Whether to enable JavaScript enhancements for the component
   - name: selectFilesButtonText
     type: string
     required: false
@@ -169,6 +173,14 @@ examples:
         text: Upload a file
       formGroup:
         classes: extra-class
+  - name: javascript
+    options:
+      id: file-upload-1
+      name: file-upload-1
+      label:
+        text: Upload a file
+      javascript: true
+      multiple: true
   - name: translated
     options:
       id: file-upload-1
@@ -176,6 +188,7 @@ examples:
       label:
         text: Llwythwch ffeil i fyny
       multiple: true
+      javascript: true
       selectFilesButtonText: Dewiswch ffeil
       filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
       filesSelectedText:
@@ -264,3 +277,16 @@ examples:
         text: Error message
       hint:
         text: hint
+  - name: translated, no javascript enhancement
+    hidden: true
+    options:
+      id: file-upload-1
+      name: file-upload-1
+      label:
+        text: Llwythwch ffeil i fyny
+      multiple: true
+      selectFilesButtonText: Dewiswch ffeil
+      filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
+      filesSelectedText:
+        other: "%{count} ffeil wedi'u dewis"
+        one: "%{count} ffeil wedi'i dewis"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 38a5c5f9c3..f1e8ff2d94 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -45,23 +45,27 @@
 {% if params.formGroup.beforeInput %}
   {{ params.formGroup.beforeInput.html | safe | trim | indent(2) if params.formGroup.beforeInput.html else params.formGroup.beforeInput.text }}
 {% endif %}
-  <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file" data-module="govuk-file-upload"
+  <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file"
   {%- if params.value %} value="{{ params.value }}"{% endif %}
   {%- if params.disabled %} disabled{% endif %}
   {%- if params.multiple %} multiple{% endif %}
   {%- if describedBy %} aria-describedby="{{ describedBy }}"{% endif %}
-  {{- govukI18nAttributes({
-    key: 'select-files-button',
-    message: params.selectFilesButtonText
-  }) -}}
-  {{- govukI18nAttributes({
-    key: 'files-selected-default',
-    message: params.filesSelectedDefaultText
-  }) -}}
-  {{- govukI18nAttributes({
-    key: 'files-selected',
-    messages: params.filesSelectedText
-  }) -}}
+  {%- if params.javascript %}
+    data-module="govuk-file-upload"
+
+    {{- govukI18nAttributes({
+      key: 'select-files-button',
+      message: params.selectFilesButtonText
+    }) -}}
+    {{- govukI18nAttributes({
+      key: 'files-selected-default',
+      message: params.filesSelectedDefaultText
+    }) -}}
+    {{- govukI18nAttributes({
+      key: 'files-selected',
+      messages: params.filesSelectedText
+    }) -}}
+  {%- endif %}
   {{- govukAttributes(params.attributes) }}>
 {% if params.formGroup.afterInput %}
   {{ params.formGroup.afterInput.html | safe | trim | indent(2) if params.formGroup.afterInput.html else params.formGroup.afterInput.text }}
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index f7b3d30271..104535b73f 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -216,6 +216,64 @@ describe('File upload', () => {
     })
   })
 
+  describe('`javascript` option', () => {
+    it('is falsy by default', () => {
+      const $ = render('file-upload', examples.javascript)
+
+      const $input = $('.govuk-form-group > .govuk-file-upload input')
+      expect($input.attr('data-module')).toBeUndefined()
+    })
+
+    it('adds the data-module attribute to the input when `true`', () => {
+      const $ = render('file-upload', examples.javascript)
+
+      const $input = $('.govuk-form-group > .govuk-file-upload')
+
+      expect($input.attr('data-module')).toBe('govuk-file-upload')
+    })
+
+    it('adds the data-module attribute when receiving an object', () => {
+      const $ = render('file-upload', examples.translated)
+
+      const $input = $('.govuk-form-group > .govuk-file-upload')
+
+      expect($input.attr('data-module')).toBe('govuk-file-upload')
+    })
+
+    it('enables the rendering of translation messages when true', () => {
+      const $ = render('file-upload', examples.translated)
+
+      const $input = $('.govuk-form-group > .govuk-file-upload')
+
+      expect($input.attr('data-i18n.select-files-button')).toBe(
+        'Dewiswch ffeil'
+      )
+      expect($input.attr('data-i18n.files-selected-default')).toBe(
+        "Dim ffeiliau wedi'u dewis"
+      )
+      expect($input.attr('data-i18n.files-selected.one')).toBe(
+        "%{count} ffeil wedi'i dewis"
+      )
+      expect($input.attr('data-i18n.files-selected.other')).toBe(
+        "%{count} ffeil wedi'u dewis"
+      )
+    })
+
+    it('prevents the rendering of translation messages when false', () => {
+      const $ = render(
+        'file-upload',
+        examples['translated, no javascript enhancement']
+      )
+
+      const $input = $('.govuk-form-group > .govuk-file-upload')
+
+      expect($input.attr('data-i18n.select-files-button')).toBeUndefined()
+      expect($input.attr('data-i18n.files-selected-default')).toBeUndefined()
+      expect($input.attr('data-i18n.files-selected.one')).toBeUndefined()
+      expect($input.attr('data-i18n.files-selected.other')).toBeUndefined()
+    })
+  })
+
   describe('with dependant components', () => {
     it('have correct nesting order', () => {
       const $ = render('file-upload', examples.error)

From 60bb4b07356ae6232742252298ca431c7742f5b1 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 24 Jan 2025 18:01:33 +0000
Subject: [PATCH 33/77] Fix Puppeteer tests of File Upload component

As JavaScript enhancements are now optional, the examples loaded on the page needed to be `javascript`.
Otherwise the `render` helper would throw as it'd try to initialise the component on `null`,
as `document.querySelectorAll('govuk-file-upload')` wouldn't find any element.
---
 .../file-upload/file-upload.puppeteer.test.js | 50 +++++++++++++------
 .../components/file-upload/file-upload.yaml   | 13 ++++-
 2 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 99ffc9dcd7..ee0fbbb5a3 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -51,7 +51,7 @@ describe('/components/file-upload', () => {
     describe('when JavaScript is available', () => {
       describe('on page load', () => {
         beforeAll(async () => {
-          await render(page, 'file-upload', examples.default)
+          await render(page, 'file-upload', examples.javascript)
         })
 
         describe('wrapper element', () => {
@@ -126,7 +126,7 @@ describe('/components/file-upload', () => {
             // set a value in the file chooser, then checks if that value was set
             // on the input as expected.
             const testFilename = 'test.gif'
-            await render(page, 'file-upload', examples.default)
+            await render(page, 'file-upload', examples.javascript)
 
             const [fileChooser] = await Promise.all([
               page.waitForFileChooser(),
@@ -153,7 +153,7 @@ describe('/components/file-upload', () => {
         const testFilename = 'fakefile.txt'
 
         beforeEach(async () => {
-          await render(page, 'file-upload', examples.default)
+          await render(page, 'file-upload', examples.javascript)
 
           const [fileChooser] = await Promise.all([
             page.waitForFileChooser(),
@@ -196,7 +196,13 @@ describe('/components/file-upload', () => {
 
       describe('when selecting multiple files', () => {
         beforeEach(async () => {
-          await render(page, 'file-upload', examples['allows multiple files'])
+          await render(page, 'file-upload', examples.javascript, {
+            beforeInitialisation() {
+              document
+                .querySelector('[type="file"]')
+                .setAttribute('multiple', '')
+            }
+          })
 
           const [fileChooser] = await Promise.all([
             page.waitForFileChooser(),
@@ -258,7 +264,7 @@ describe('/components/file-upload', () => {
           '.govuk-file-upload-wrapper:not(.govuk-file-upload-wrapper--show-dropzone)'
 
         beforeEach(async () => {
-          await render(page, 'file-upload', examples.default)
+          await render(page, 'file-upload', examples.javascript)
 
           $wrapper = await page.$('.govuk-file-upload-wrapper')
           wrapperBoundingBox = await $wrapper.boundingBox()
@@ -395,7 +401,13 @@ describe('/components/file-upload', () => {
 
       describe('disabled state syncing', () => {
         it('disables the button if the input is disabled on page load', async () => {
-          await render(page, 'file-upload', examples.disabled)
+          await render(page, 'file-upload', examples.javascript, {
+            beforeInitialisation() {
+              document
+                .querySelector('[type="file"]')
+                .setAttribute('disabled', '')
+            }
+          })
 
           const buttonDisabled = await page.$eval(buttonSelector, (el) =>
             el.hasAttribute('disabled')
@@ -405,7 +417,7 @@ describe('/components/file-upload', () => {
         })
 
         it('disables the button if the input is disabled programatically', async () => {
-          await render(page, 'file-upload', examples.default)
+          await render(page, 'file-upload', examples.javascript)
 
           await page.$eval(inputSelector, (el) =>
             el.setAttribute('disabled', '')
@@ -419,7 +431,13 @@ describe('/components/file-upload', () => {
         })
 
         it('enables the button if the input is enabled programatically', async () => {
-          await render(page, 'file-upload', examples.disabled)
+          await render(page, 'file-upload', examples.javascript, {
+            beforeInitialisation() {
+              document
+                .querySelector('[type="file"]')
+                .setAttribute('disabled', '')
+            }
+          })
 
           const buttonDisabledBefore = await page.$eval(buttonSelector, (el) =>
             el.hasAttribute('disabled')
@@ -443,7 +461,7 @@ describe('/components/file-upload', () => {
           await render(
             page,
             'file-upload',
-            examples['with error message and hint']
+            examples['javascript, with error message and hint']
           )
 
           const $button = await page.$(buttonSelector)
@@ -455,7 +473,7 @@ describe('/components/file-upload', () => {
         })
 
         it('does not add an `aria-describedby` attribute to the `<button>` if there is none on the `<input>`', async () => {
-          await render(page, 'file-upload', examples.default)
+          await render(page, 'file-upload', examples.javascript)
 
           const $button = await page.$(buttonSelector)
           const ariaDescribedBy = await $button.evaluate((el) =>
@@ -475,7 +493,7 @@ describe('/components/file-upload', () => {
 
         it('can throw a SupportError if appropriate', async () => {
           await expect(
-            render(page, 'file-upload', examples.default, {
+            render(page, 'file-upload', examples.javascript, {
               beforeInitialisation() {
                 document.body.classList.remove('govuk-frontend-supported')
               }
@@ -491,7 +509,7 @@ describe('/components/file-upload', () => {
 
         it('throws when initialised twice', async () => {
           await expect(
-            render(page, 'file-upload', examples.default, {
+            render(page, 'file-upload', examples.javascript, {
               async afterInitialisation($root) {
                 const { FileUpload } = await import('govuk-frontend')
                 new FileUpload($root)
@@ -506,7 +524,7 @@ describe('/components/file-upload', () => {
 
         it('throws when $root is not set', async () => {
           await expect(
-            render(page, 'file-upload', examples.default, {
+            render(page, 'file-upload', examples.javascript, {
               beforeInitialisation($root) {
                 $root.remove()
               }
@@ -521,7 +539,7 @@ describe('/components/file-upload', () => {
 
         it('throws when receiving the wrong type for $root', async () => {
           await expect(
-            render(page, 'file-upload', examples.default, {
+            render(page, 'file-upload', examples.javascript, {
               beforeInitialisation($root) {
                 // Replace with an `<svg>` element which is not an `HTMLElement` in the DOM (but an `SVGElement`)
                 $root.outerHTML = `<svg data-module="govuk-file-upload"></svg>`
@@ -539,7 +557,7 @@ describe('/components/file-upload', () => {
         describe('missing or misconfigured elements', () => {
           it('throws if the input type is not "file"', async () => {
             await expect(
-              render(page, 'file-upload', examples.default, {
+              render(page, 'file-upload', examples.javascript, {
                 beforeInitialisation() {
                   document
                     .querySelector('[type="file"]')
@@ -557,7 +575,7 @@ describe('/components/file-upload', () => {
 
           it('throws if no label is present', async () => {
             await expect(
-              render(page, 'file-upload', examples.default, {
+              render(page, 'file-upload', examples.javascript, {
                 beforeInitialisation() {
                   document.querySelector('label').remove()
                 }
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 2242a4b022..e2db66f4a6 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -180,7 +180,6 @@ examples:
       label:
         text: Upload a file
       javascript: true
-      multiple: true
   - name: translated
     options:
       id: file-upload-1
@@ -277,6 +276,18 @@ examples:
         text: Error message
       hint:
         text: hint
+  - name: javascript, with error message and hint
+    hidden: true
+    options:
+      javascript: true
+      id: file-upload-3
+      name: file-upload-3
+      label:
+        text: Upload a file
+      hint:
+        text: Your photo may be in your Pictures, Photos, Downloads or Desktop folder. Or in an app like iPhoto.
+      errorMessage:
+        text: Error message goes here
   - name: translated, no javascript enhancement
     hidden: true
     options:

From a321317ab10dc3923bec29aca6b3fb95ff61292b Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 24 Jan 2025 18:45:15 +0000
Subject: [PATCH 34/77] Fix accessibility tests for examples without JS
 enhancements

The `render` helper assumed all examples of a component for which
a JavaScript component exist would have a `data-module` and as such
forced initialising a JavaScript component when no element with the appropriate
`data-module` was found on the page.

This behaviour is handy to spot if a component suddenly stops rendering `data-module`,
so we don't want to change the `render` function. For the File Upload,
we can decide whether the error is relevant in the test, based on whether the `javascript`
macro option is set.
---
 .../accessibility.puppeteer.test.mjs          | 30 ++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/accessibility.puppeteer.test.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/accessibility.puppeteer.test.mjs
index 33f590b06a..7df8675d4d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/accessibility.puppeteer.test.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/accessibility.puppeteer.test.mjs
@@ -7,9 +7,37 @@ describe('/components/file-upload', () => {
       const examples = await getExamples('file-upload')
 
       for (const exampleName in examples) {
-        await render(page, 'file-upload', examples[exampleName])
+        // JavaScript enhancements being optional, some examples will not have
+        // any element with `data-module="govuk-file-upload"`. This causes an error
+        // as `render` assumes that if a component is exported by GOV.UK Frontend
+        // its rendered markup will have a `data-module` and tried to initialise
+        // the JavaScript component, even if no element with the right `data-module`
+        // is on the page.
+        //
+        // Because of this, we need to filter `ElementError` thrown by the JavaScript
+        // component to examples that actually run the JavaScript enhancements
+        try {
+          await render(page, 'file-upload', examples[exampleName])
+        } catch (e) {
+          const macroOptions = /** @type {MacroOptions} */ (
+            examples[exampleName].context
+          )
+
+          const exampleUsesJavaScript = macroOptions.javascript
+          const exampleLackedRoot = e.message.includes(
+            'govuk-file-upload: Root element'
+          )
+
+          if (!exampleLackedRoot || exampleUsesJavaScript) {
+            throw e
+          }
+        }
         await expect(axe(page)).resolves.toHaveNoViolations()
       }
     }, 120000)
   })
 })
+
+/**
+ * @typedef {import('@govuk-frontend/lib/components').MacroOptions} MacroOptions
+ */

From 9bced0b7b0ac055dc05441d38a890ff01273feb9 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Mon, 27 Jan 2025 17:59:39 +0000
Subject: [PATCH 35/77] Add screenshot test for the JavaScript enhanced
 FileUpload

The `default` example is now back to rendering the native component,
so we'll want a test for the JavaScript enhanced version
---
 .../src/govuk/components/file-upload/file-upload.yaml            | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index e2db66f4a6..2abbf800a5 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -174,6 +174,7 @@ examples:
       formGroup:
         classes: extra-class
   - name: javascript
+    screenshot: true
     options:
       id: file-upload-1
       name: file-upload-1

From 9a757d38e646caa11006a2a4dc22705721e6b474 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 28 Jan 2025 18:54:32 +0000
Subject: [PATCH 36/77] Update simple examples that use the file upload
 component

---
 .../src/views/examples/error-summary/index.njk   | 16 ++++++++++++++++
 .../src/views/examples/form-elements/index.njk   | 13 +++++++++++++
 .../src/views/examples/translated/index.njk      | 15 +++++++++++++++
 .../upload-your-photo-success/index.njk          |  3 ++-
 .../upload-your-photo/index.njk                  |  3 ++-
 5 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/packages/govuk-frontend-review/src/views/examples/error-summary/index.njk b/packages/govuk-frontend-review/src/views/examples/error-summary/index.njk
index 196640ef9a..2cfdd32168 100644
--- a/packages/govuk-frontend-review/src/views/examples/error-summary/index.njk
+++ b/packages/govuk-frontend-review/src/views/examples/error-summary/index.njk
@@ -49,6 +49,10 @@
         "text": "Problem with file",
         "href": "#file"
       },
+      {
+        "text": "Problem with file (enhanced)",
+        "href": "#file-enhanced"
+      },
       {
         "text": "Problem with radios",
         "href": "#radios"
@@ -192,6 +196,18 @@
     }
   }) }}
 
+  {{ govukFileUpload({
+    label: {
+      "text": 'Label for enhanced file upload'
+    },
+    id: "file-enhanced",
+    name: "file-enhanced",
+    errorMessage: {
+      "text": "Problem with file"
+    },
+    javascript: true
+  }) }}
+
   {{ govukRadios({
     fieldset: {
       legend: {
diff --git a/packages/govuk-frontend-review/src/views/examples/form-elements/index.njk b/packages/govuk-frontend-review/src/views/examples/form-elements/index.njk
index f5183726f7..5697b1bd6b 100644
--- a/packages/govuk-frontend-review/src/views/examples/form-elements/index.njk
+++ b/packages/govuk-frontend-review/src/views/examples/form-elements/index.njk
@@ -28,6 +28,7 @@
     <li><a href="#date" class="govuk-link">Date pattern</a></li>
     <li><a href="#select" class="govuk-link">Select box</a></li>
     <li><a href="#file" class="govuk-link">File upload</a></li>
+    <li><a href="#file-enhanced" class="govuk-link">File upload (enhanced)</a></li>
   </ul>
 
   <form action="/" method="post">
@@ -174,5 +175,17 @@
       }) -}}
     {% endcall %}
 
+    {% call govukFieldset() %}
+      <span id="file-enhanced"></span>
+      {{- govukFileUpload({
+        id: 'file-upload-2',
+        name: 'file-upload-2',
+        label: {
+          text: 'Upload a file'
+        },
+        javascript: true
+      }) -}}
+    {% endcall %}
+
   </form>
 {% endblock %}
diff --git a/packages/govuk-frontend-review/src/views/examples/translated/index.njk b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
index 3ba09e3c52..34de661f02 100644
--- a/packages/govuk-frontend-review/src/views/examples/translated/index.njk
+++ b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
@@ -340,6 +340,21 @@
     }
   }) }}
 
+  {{ govukFileUpload({
+    id: "file-upload-1",
+    name: "file-upload-1",
+    label: {
+      text: "Llwythwch ffeil i fyny"
+    },
+    javascript: true,
+    selectFilesButtonText: "Dewiswch ffeil",
+    filesSelectedDefaultText: "Dim ffeiliau wedi'u dewis",
+    filesSelectedText: {
+        other: "%{count} ffeil wedi'u dewis",
+        one: "%{count} ffeil wedi'i dewis"
+    }
+  }) }}
+
   {{ govukFooter({
     classes: "govuk-!-margin-bottom-4",
     navigation: [
diff --git a/packages/govuk-frontend-review/src/views/full-page-examples/upload-your-photo-success/index.njk b/packages/govuk-frontend-review/src/views/full-page-examples/upload-your-photo-success/index.njk
index 244c8247b9..43716cba34 100644
--- a/packages/govuk-frontend-review/src/views/full-page-examples/upload-your-photo-success/index.njk
+++ b/packages/govuk-frontend-review/src/views/full-page-examples/upload-your-photo-success/index.njk
@@ -69,7 +69,8 @@ scenario: |
                 hint: {
                     text: "Your photo must be at least 50KB and no more than 10MB"
                 },
-                errorMessage: errors["photo"]
+                errorMessage: errors["photo"],
+                javascript: true
             }) }}
 
             {{ govukCheckboxes({
diff --git a/packages/govuk-frontend-review/src/views/full-page-examples/upload-your-photo/index.njk b/packages/govuk-frontend-review/src/views/full-page-examples/upload-your-photo/index.njk
index 6612671c5e..c45e7b1986 100644
--- a/packages/govuk-frontend-review/src/views/full-page-examples/upload-your-photo/index.njk
+++ b/packages/govuk-frontend-review/src/views/full-page-examples/upload-your-photo/index.njk
@@ -71,7 +71,8 @@ scenario: |
                 hint: {
                     text: "Your photo must be at least 50KB and no more than 10MB"
                 },
-                errorMessage: errors["photo"]
+                errorMessage: errors["photo"],
+                javascript: true
             }) }}
 
             {{ govukCheckboxes({

From 3e0660b9e56ea56c74804ef07e2ad3ec29a36ee3 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 28 Jan 2025 18:57:08 +0000
Subject: [PATCH 37/77] Improve labelling of tests for enhanced file upload

---
 .../file-upload/file-upload.puppeteer.test.js | 32 +++++++++----------
 .../components/file-upload/file-upload.yaml   | 25 +++++++--------
 .../components/file-upload/template.test.js   |  2 +-
 3 files changed, 29 insertions(+), 30 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index ee0fbbb5a3..51b0719899 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -51,7 +51,7 @@ describe('/components/file-upload', () => {
     describe('when JavaScript is available', () => {
       describe('on page load', () => {
         beforeAll(async () => {
-          await render(page, 'file-upload', examples.javascript)
+          await render(page, 'file-upload', examples.enhanced)
         })
 
         describe('wrapper element', () => {
@@ -126,7 +126,7 @@ describe('/components/file-upload', () => {
             // set a value in the file chooser, then checks if that value was set
             // on the input as expected.
             const testFilename = 'test.gif'
-            await render(page, 'file-upload', examples.javascript)
+            await render(page, 'file-upload', examples.enhanced)
 
             const [fileChooser] = await Promise.all([
               page.waitForFileChooser(),
@@ -153,7 +153,7 @@ describe('/components/file-upload', () => {
         const testFilename = 'fakefile.txt'
 
         beforeEach(async () => {
-          await render(page, 'file-upload', examples.javascript)
+          await render(page, 'file-upload', examples.enhanced)
 
           const [fileChooser] = await Promise.all([
             page.waitForFileChooser(),
@@ -196,7 +196,7 @@ describe('/components/file-upload', () => {
 
       describe('when selecting multiple files', () => {
         beforeEach(async () => {
-          await render(page, 'file-upload', examples.javascript, {
+          await render(page, 'file-upload', examples.enhanced, {
             beforeInitialisation() {
               document
                 .querySelector('[type="file"]')
@@ -264,7 +264,7 @@ describe('/components/file-upload', () => {
           '.govuk-file-upload-wrapper:not(.govuk-file-upload-wrapper--show-dropzone)'
 
         beforeEach(async () => {
-          await render(page, 'file-upload', examples.javascript)
+          await render(page, 'file-upload', examples.enhanced)
 
           $wrapper = await page.$('.govuk-file-upload-wrapper')
           wrapperBoundingBox = await $wrapper.boundingBox()
@@ -401,7 +401,7 @@ describe('/components/file-upload', () => {
 
       describe('disabled state syncing', () => {
         it('disables the button if the input is disabled on page load', async () => {
-          await render(page, 'file-upload', examples.javascript, {
+          await render(page, 'file-upload', examples.enhanced, {
             beforeInitialisation() {
               document
                 .querySelector('[type="file"]')
@@ -417,7 +417,7 @@ describe('/components/file-upload', () => {
         })
 
         it('disables the button if the input is disabled programatically', async () => {
-          await render(page, 'file-upload', examples.javascript)
+          await render(page, 'file-upload', examples.enhanced)
 
           await page.$eval(inputSelector, (el) =>
             el.setAttribute('disabled', '')
@@ -431,7 +431,7 @@ describe('/components/file-upload', () => {
         })
 
         it('enables the button if the input is enabled programatically', async () => {
-          await render(page, 'file-upload', examples.javascript, {
+          await render(page, 'file-upload', examples.enhanced, {
             beforeInitialisation() {
               document
                 .querySelector('[type="file"]')
@@ -461,7 +461,7 @@ describe('/components/file-upload', () => {
           await render(
             page,
             'file-upload',
-            examples['javascript, with error message and hint']
+            examples['enhanced, with error message and hint']
           )
 
           const $button = await page.$(buttonSelector)
@@ -473,7 +473,7 @@ describe('/components/file-upload', () => {
         })
 
         it('does not add an `aria-describedby` attribute to the `<button>` if there is none on the `<input>`', async () => {
-          await render(page, 'file-upload', examples.javascript)
+          await render(page, 'file-upload', examples.enhanced)
 
           const $button = await page.$(buttonSelector)
           const ariaDescribedBy = await $button.evaluate((el) =>
@@ -493,7 +493,7 @@ describe('/components/file-upload', () => {
 
         it('can throw a SupportError if appropriate', async () => {
           await expect(
-            render(page, 'file-upload', examples.javascript, {
+            render(page, 'file-upload', examples.enhanced, {
               beforeInitialisation() {
                 document.body.classList.remove('govuk-frontend-supported')
               }
@@ -509,7 +509,7 @@ describe('/components/file-upload', () => {
 
         it('throws when initialised twice', async () => {
           await expect(
-            render(page, 'file-upload', examples.javascript, {
+            render(page, 'file-upload', examples.enhanced, {
               async afterInitialisation($root) {
                 const { FileUpload } = await import('govuk-frontend')
                 new FileUpload($root)
@@ -524,7 +524,7 @@ describe('/components/file-upload', () => {
 
         it('throws when $root is not set', async () => {
           await expect(
-            render(page, 'file-upload', examples.javascript, {
+            render(page, 'file-upload', examples.enhanced, {
               beforeInitialisation($root) {
                 $root.remove()
               }
@@ -539,7 +539,7 @@ describe('/components/file-upload', () => {
 
         it('throws when receiving the wrong type for $root', async () => {
           await expect(
-            render(page, 'file-upload', examples.javascript, {
+            render(page, 'file-upload', examples.enhanced, {
               beforeInitialisation($root) {
                 // Replace with an `<svg>` element which is not an `HTMLElement` in the DOM (but an `SVGElement`)
                 $root.outerHTML = `<svg data-module="govuk-file-upload"></svg>`
@@ -557,7 +557,7 @@ describe('/components/file-upload', () => {
         describe('missing or misconfigured elements', () => {
           it('throws if the input type is not "file"', async () => {
             await expect(
-              render(page, 'file-upload', examples.javascript, {
+              render(page, 'file-upload', examples.enhanced, {
                 beforeInitialisation() {
                   document
                     .querySelector('[type="file"]')
@@ -575,7 +575,7 @@ describe('/components/file-upload', () => {
 
           it('throws if no label is present', async () => {
             await expect(
-              render(page, 'file-upload', examples.javascript, {
+              render(page, 'file-upload', examples.enhanced, {
                 beforeInitialisation() {
                   document.querySelector('label').remove()
                 }
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 2abbf800a5..2f1b0e3ad2 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -173,7 +173,7 @@ examples:
         text: Upload a file
       formGroup:
         classes: extra-class
-  - name: javascript
+  - name: enhanced
     screenshot: true
     options:
       id: file-upload-1
@@ -181,6 +181,17 @@ examples:
       label:
         text: Upload a file
       javascript: true
+  - name: enhanced, with error message and hint
+    options:
+      javascript: true
+      id: file-upload-3
+      name: file-upload-3
+      label:
+        text: Upload a file
+      hint:
+        text: Your photo may be in your Pictures, Photos, Downloads or Desktop folder. Or in an app like iPhoto.
+      errorMessage:
+        text: Error message goes here
   - name: translated
     options:
       id: file-upload-1
@@ -277,18 +288,6 @@ examples:
         text: Error message
       hint:
         text: hint
-  - name: javascript, with error message and hint
-    hidden: true
-    options:
-      javascript: true
-      id: file-upload-3
-      name: file-upload-3
-      label:
-        text: Upload a file
-      hint:
-        text: Your photo may be in your Pictures, Photos, Downloads or Desktop folder. Or in an app like iPhoto.
-      errorMessage:
-        text: Error message goes here
   - name: translated, no javascript enhancement
     hidden: true
     options:
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index 104535b73f..2fa0c5c4a0 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -225,7 +225,7 @@ describe('File upload', () => {
     })
 
     it('adds the data-module attribute to the input when `true`', () => {
-      const $ = render('file-upload', examples.javascript)
+      const $ = render('file-upload', examples.enhanced)
 
       const $input = $('.govuk-form-group > .govuk-file-upload')
 

From 7717c151ce72630db4e91d58d32ca3dca45b8a48 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Thu, 23 Jan 2025 15:16:08 +0000
Subject: [PATCH 38/77] Update button creation of file upload

Button creation of file upload needs to be changed in line with the new
design. Includes new `instruction span` which has been added to the i18n
configuration.
---
 .../components/file-upload/file-upload.mjs    | 67 ++++++++++++-------
 .../file-upload/file-upload.puppeteer.test.js |  4 +-
 .../components/file-upload/file-upload.yaml   |  5 ++
 .../govuk/components/file-upload/template.njk |  4 ++
 4 files changed, 55 insertions(+), 25 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 9ca6b134bd..9ec90d02e9 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -72,6 +72,10 @@ export class FileUpload extends ConfigurableComponent {
     const $wrapper = document.createElement('div')
     $wrapper.className = 'govuk-file-upload-wrapper'
 
+    const commaSpan = document.createElement('span')
+    commaSpan.className = 'govuk-visually-hidden'
+    commaSpan.innerText = ', '
+
     // Create the file selection button
     const $button = document.createElement('button')
     $button.classList.add('govuk-file-upload__button')
@@ -85,26 +89,40 @@ export class FileUpload extends ConfigurableComponent {
       $button.setAttribute('aria-describedby', ariaDescribedBy)
     }
 
+    // Create status element that shows what/how many files are selected
+    const $status = document.createElement('span')
+    $status.className = 'govuk-body govuk-file-upload__status'
+    $status.innerText = this.i18n.t('filesSelectedDefault')
+    $status.setAttribute('aria-hidden', 'true')
+    $status.classList.add('govuk-file-upload__status--empty')
+
+    $button.appendChild($status)
+    $button.appendChild(commaSpan.cloneNode(true))
+
+    const containerSpan = document.createElement('span')
+    containerSpan.className = 'govuk-file-upload__pseudo-button-container'
+
     const buttonSpan = document.createElement('span')
     buttonSpan.className =
       'govuk-button govuk-button--secondary govuk-file-upload__pseudo-button'
     buttonSpan.innerText = this.i18n.t('selectFilesButton')
     buttonSpan.setAttribute('aria-hidden', 'true')
 
-    $button.appendChild(buttonSpan)
-    $button.addEventListener('click', this.onClick.bind(this))
+    containerSpan.appendChild(buttonSpan)
+    containerSpan.appendChild(commaSpan.cloneNode(true))
 
-    // Create status element that shows what/how many files are selected
-    const $status = document.createElement('span')
-    $status.className = 'govuk-body govuk-file-upload__status'
-    $status.innerText = this.i18n.t('filesSelectedDefault')
-    $status.setAttribute('aria-hidden', 'true')
+    const instructionSpan = document.createElement('span')
+    instructionSpan.className = 'govuk-body govuk-file-upload__instruction'
+    instructionSpan.innerText = this.i18n.t('instruction')
 
-    $button.appendChild($status)
+    containerSpan.appendChild(instructionSpan)
+
+    $button.appendChild(containerSpan)
     $button.setAttribute(
       'aria-label',
-      `${this.$label.innerText}, ${this.i18n.t('selectFilesButton')}, ${this.i18n.t('filesSelectedDefault')}`
+      `${this.$label.innerText}, ${this.i18n.t('selectFilesButton')} ${this.i18n.t('instruction')}, ${$status.innerText}`
     )
+    $button.addEventListener('click', this.onClick.bind(this))
 
     // Assemble these all together
     $wrapper.insertAdjacentElement('beforeend', $button)
@@ -130,9 +148,6 @@ export class FileUpload extends ConfigurableComponent {
     this.updateDisabledState()
     this.observeDisabledState()
 
-    // Bind change event to the underlying input
-    this.$root.addEventListener('change', this.onChange.bind(this))
-
     // Handle drop zone visibility
     // A live region to announce when users enter or leave the drop zone
     this.$announcements = document.createElement('span')
@@ -240,21 +255,26 @@ export class FileUpload extends ConfigurableComponent {
     if (fileCount === 0) {
       // If there are no files, show the default selection text
       this.$status.innerText = this.i18n.t('filesSelectedDefault')
-    } else if (
-      // If there is 1 file, just show the file name
-      fileCount === 1
-    ) {
-      this.$status.innerText = this.$root.files[0].name
+      this.$status.classList.add('govuk-file-upload__status--empty')
     } else {
-      // Otherwise, tell the user how many files are selected
-      this.$status.innerText = this.i18n.t('filesSelected', {
-        count: fileCount
-      })
+      if (
+        // If there is 1 file, just show the file name
+        fileCount === 1
+      ) {
+        this.$status.innerText = this.$root.files[0].name
+      } else {
+        // Otherwise, tell the user how many files are selected
+        this.$status.innerText = this.i18n.t('filesSelected', {
+          count: fileCount
+        })
+      }
+
+      this.$status.classList.remove('govuk-file-upload__status--empty')
     }
 
     this.$button.setAttribute(
       'aria-label',
-      `${this.$label.innerText}, ${this.i18n.t('selectFilesButton')}, ${this.$status.innerText}`
+      `${this.$label.innerText}, ${this.i18n.t('selectFilesButton')} ${this.i18n.t('instruction')}, ${this.$status.innerText}`
     )
   }
 
@@ -337,7 +357,8 @@ export class FileUpload extends ConfigurableComponent {
         other: '%{count} files chosen'
       },
       dropZoneEntered: 'Entered drop zone',
-      dropZoneLeft: 'Left drop zone'
+      dropZoneLeft: 'Left drop zone',
+      instruction: 'or drop file'
     }
   })
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 51b0719899..bbad4c7e5d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -111,7 +111,7 @@ describe('/components/file-upload', () => {
             expect(buttonElementText).toBe('Choose file')
             expect(statusElementText).toBe('No file chosen')
             expect(buttonAriaText).toBe(
-              'Upload a file, Choose file, No file chosen'
+              'Upload a file, Choose file or drop file, No file chosen'
             )
           })
         })
@@ -370,7 +370,7 @@ describe('/components/file-upload', () => {
           expect(buttonElementText).toBe('Dewiswch ffeil')
           expect(statusElementText).toBe("Dim ffeiliau wedi'u dewis")
           expect(buttonAriaText).toBe(
-            "Llwythwch ffeil i fyny, Dewiswch ffeil, Dim ffeiliau wedi'u dewis"
+            "Llwythwch ffeil i fyny, Dewiswch ffeil neu ollwng ffeil, Dim ffeiliau wedi'u dewis"
           )
         })
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 2f1b0e3ad2..a7486245bc 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -85,6 +85,10 @@ params:
     type: string
     required: false
     description: The text of the button that opens the file picker. JavaScript enhanced version of the component only. Default is "Choose file".
+  - name: instructionText
+    type: string
+    required: false
+    description: The text of the instruction text that follows the button that opens the file picker. JavaScript enhanced version of the component only. Default is "or drop file".
   - name: filesSelected
     type: object
     required: false
@@ -201,6 +205,7 @@ examples:
       multiple: true
       javascript: true
       selectFilesButtonText: Dewiswch ffeil
+      instructionText: neu ollwng ffeil
       filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
       filesSelectedText:
         other: "%{count} ffeil wedi'u dewis"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index f1e8ff2d94..f39a74e1ce 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -65,6 +65,10 @@
       key: 'files-selected',
       messages: params.filesSelectedText
     }) -}}
+    {{- govukI18nAttributes({
+      key: 'instruction',
+      message: params.instructionText
+    }) -}}    
   {%- endif %}
   {{- govukAttributes(params.attributes) }}>
 {% if params.formGroup.afterInput %}

From 86d62479c1473fb7ca14581f69eecb9e1fd63c43 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Tue, 28 Jan 2025 10:24:55 +0000
Subject: [PATCH 39/77] Style the file upload component

New styles for file upload component. Includes adjusting the `z-index`
when the dropzone is toggled.
---
 .../govuk/components/file-upload/_index.scss  | 150 +++++++++++-------
 1 file changed, 90 insertions(+), 60 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 2f0b702a7b..b19b08308d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -3,6 +3,7 @@
 @import "../label/index";
 
 @include govuk-exports("govuk/component/file-upload") {
+  $file-upload-border-width: 2px;
   $component-padding: govuk-spacing(1);
 
   .govuk-file-upload {
@@ -48,34 +49,17 @@
   }
 
   .govuk-file-upload-wrapper {
-    display: inline-flex;
-    align-items: baseline;
+    display: block;
     position: relative;
-  }
-
-  .govuk-file-upload-wrapper--show-dropzone {
-    $dropzone-padding: govuk-spacing(2);
-    $dropzone-offset: $dropzone-padding + $govuk-border-width-form-element;
-
-    // Add negative margins to all sides so that content doesn't jump due to
-    // the addition of the padding and border.
-    margin: -$dropzone-offset;
-    padding: $dropzone-padding;
-    border: $govuk-border-width-form-element dashed $govuk-input-border-colour;
+    z-index: 0;
     background-color: $govuk-body-background-colour;
-
-    .govuk-file-upload__pseudo-button,
-    .govuk-file-upload__status {
-      // When the dropzone is hovered over, make these aspects not accept
-      // mouse events, so dropped files fall through to the input beneath them
-      pointer-events: none;
-    }
   }
 
   .govuk-file-upload-wrapper .govuk-file-upload {
+    position: absolute;
     // Make the native control take up the entire space of the element, but
     // invisible and behind the other elements until we need it
-    position: absolute;
+    z-index: -1;
     top: 0;
     left: 0;
     width: 100%;
@@ -85,62 +69,108 @@
     opacity: 0;
   }
 
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload {
+    z-index: 1;
+  }
+
   .govuk-file-upload__pseudo-button {
     width: auto;
-    margin-bottom: 0;
-    flex-grow: 0;
+    margin-right: govuk-spacing(2);
+    margin-bottom: $govuk-border-width-form-element + 1;
     flex-shrink: 0;
   }
 
-  .govuk-file-upload__status {
+  .govuk-file-upload__instruction {
+    margin-top: govuk-spacing(2) - ($govuk-border-width-form-element + 1);
     margin-bottom: 0;
-    margin-left: govuk-spacing(2);
+    text-align: left;
   }
-}
 
-.govuk-file-upload__button:focus {
-  outline: none;
-}
+  .govuk-file-upload__status {
+    display: block;
+    margin-bottom: govuk-spacing(2);
+    padding: govuk-spacing(3) govuk-spacing(2);
+    text-align: left;
+  }
 
-.govuk-file-upload__button:focus .govuk-file-upload__pseudo-button {
-  outline: 3px solid transparent;
-  background-color: $govuk-focus-colour;
-  box-shadow: 0 2px 0 govuk-colour("black");
-}
+  .govuk-file-upload__status--empty {
+    color: govuk-shade(govuk-colour("blue"), 60%);
+    background-color: govuk-tint(govuk-colour("blue"), 70%);
+  }
 
-.govuk-file-upload__button:focus .govuk-file-upload__pseudo-button:hover {
-  border-color: $govuk-focus-colour;
-  outline: 3px solid transparent;
-  background-color: govuk-colour("light-grey");
-  box-shadow: inset 0 0 0 1px $govuk-focus-colour;
-}
+  // bugs documented with button using flex
+  // https://github.com/philipwalton/flexbugs#flexbug-9
+  // so we need a container here
+  .govuk-file-upload__pseudo-button-container {
+    display: flex;
+    align-items: baseline;
+    flex-wrap: wrap;
+  }
 
-.govuk-file-upload__button:active .govuk-file-upload__pseudo-button:hover {
-  background-color: govuk-shade(govuk-colour("light-grey"), 20%);
-}
+  .govuk-file-upload__button {
+    width: 100%;
+    // align the padding to be same as notification banner and error summary accounting for the thicker borders
+    padding: govuk-spacing(3) (govuk-spacing(3) + $govuk-border-width - $file-upload-border-width);
+    border: $file-upload-border-width govuk-colour("mid-grey") dashed;
+    background-color: govuk-colour("white");
+    cursor: pointer;
+
+    @include govuk-media-query($from: tablet) {
+      padding: govuk-spacing(3) (govuk-spacing(4) + $govuk-border-width - $file-upload-border-width);
+    }
+  }
 
-.govuk-file-upload__button {
-  align-items: center;
-  display: flex;
-  padding: 0;
-  border: 0;
-  background-color: transparent;
-}
+  .govuk-file-upload-wrapper:hover .govuk-file-upload__button {
+    border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
+  }
 
-.govuk-file-upload:disabled + .govuk-file-upload__button {
-  pointer-events: none;
-}
+  .govuk-file-upload-wrapper:hover .govuk-file-upload__pseudo-button {
+    background-color: govuk-shade(govuk-colour("light-grey"), 10%);
+  }
+
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button,
+  .govuk-file-upload-wrapper:hover .govuk-file-upload__button {
+    background-color: govuk-colour("light-grey");
+  }
+
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__status--empty,
+  .govuk-file-upload-wrapper:hover .govuk-file-upload__status--empty,
+  .govuk-file-upload__button:focus .govuk-file-upload__status--empty {
+    background-color: govuk-tint(govuk-colour("blue"), 80%);
+  }
+
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button {
+    border: $file-upload-border-width solid govuk-colour("black");
+  }
 
-.govuk-file-upload:disabled + .govuk-file-upload__button .govuk-file-upload__pseudo-button {
-  opacity: (0.5);
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__pseudo-button {
+    background-color: govuk-colour("white");
+  }
 
-  &:hover {
+  .govuk-file-upload__button:active,
+  .govuk-file-upload__button:focus {
+    border: 2px solid govuk-colour("black");
+    outline: $govuk-focus-width solid $govuk-focus-colour;
+    // Ensure outline appears outside of the element
+    outline-offset: 0;
     background-color: govuk-colour("light-grey");
-    cursor: not-allowed;
+    // Double the border by adding its width again. Use `box-shadow` for this
+    // instead of changing `border-width` - this is for consistency with
+    // components such as textarea where we avoid changing `border-width` as
+    // it will change the element size. Also, `outline` cannot be utilised
+    // here as it is already used for the yellow focus state.
+    box-shadow: inset 0 0 0 $govuk-border-width-form-element;
   }
 
-  &:active {
-    top: 0;
-    box-shadow: 0 $govuk-border-width-form-element 0 govuk-shade(govuk-colour("white"), 60%); // s0
+  .govuk-file-upload__button:focus .govuk-file-upload__pseudo-button {
+    background-color: $govuk-focus-colour;
+    box-shadow: 0 2px 0 govuk-colour("black");
+  }
+
+  .govuk-file-upload-wrapper:hover .govuk-file-upload__button:focus .govuk-file-upload__pseudo-button {
+    border-color: $govuk-focus-colour;
+    outline: 3px solid transparent;
+    background-color: govuk-colour("light-grey");
+    box-shadow: inset 0 0 0 1px $govuk-focus-colour;
   }
 }

From 549c62dbf707a857ba871481d880b353ff1584e6 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 24 Jan 2025 16:59:58 +0000
Subject: [PATCH 40/77] Label the `<button>` using `aria-labelledby`

Reference the `<label>` and the `<button>` itself so there's no duplication
of content, ensuring that when translated, the accessible name matches what's
visible on the screen.
---
 .../components/file-upload/file-upload.mjs    | 38 +++++-----
 .../file-upload/file-upload.puppeteer.test.js | 74 +++++++++++++++----
 2 files changed, 80 insertions(+), 32 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 9ec90d02e9..807825d697 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -61,7 +61,13 @@ export class FileUpload extends ConfigurableComponent {
       locale: closestAttributeValue(this.$root, 'lang')
     })
 
-    this.$label = this.findLabel()
+    const $label = this.findLabel()
+    $label.setAttribute('for', `${this.id}-input`)
+    // Add an ID to the label if it doesn't have one already
+    // so it can be referenced by `aria-labelledby`
+    if (!$label.id) {
+      $label.id = `${this.id}-label`
+    }
 
     // we need to copy the 'id' of the root element
     // to the new button replacement element
@@ -72,10 +78,6 @@ export class FileUpload extends ConfigurableComponent {
     const $wrapper = document.createElement('div')
     $wrapper.className = 'govuk-file-upload-wrapper'
 
-    const commaSpan = document.createElement('span')
-    commaSpan.className = 'govuk-visually-hidden'
-    commaSpan.innerText = ', '
-
     // Create the file selection button
     const $button = document.createElement('button')
     $button.classList.add('govuk-file-upload__button')
@@ -93,11 +95,16 @@ export class FileUpload extends ConfigurableComponent {
     const $status = document.createElement('span')
     $status.className = 'govuk-body govuk-file-upload__status'
     $status.innerText = this.i18n.t('filesSelectedDefault')
-    $status.setAttribute('aria-hidden', 'true')
     $status.classList.add('govuk-file-upload__status--empty')
 
     $button.appendChild($status)
-    $button.appendChild(commaSpan.cloneNode(true))
+
+    const commaSpan = document.createElement('span')
+    commaSpan.className = 'govuk-visually-hidden'
+    commaSpan.innerText = ', '
+    commaSpan.id = `${this.id}-comma`
+
+    $button.appendChild(commaSpan)
 
     const containerSpan = document.createElement('span')
     containerSpan.className = 'govuk-file-upload__pseudo-button-container'
@@ -106,10 +113,12 @@ export class FileUpload extends ConfigurableComponent {
     buttonSpan.className =
       'govuk-button govuk-button--secondary govuk-file-upload__pseudo-button'
     buttonSpan.innerText = this.i18n.t('selectFilesButton')
-    buttonSpan.setAttribute('aria-hidden', 'true')
 
     containerSpan.appendChild(buttonSpan)
-    containerSpan.appendChild(commaSpan.cloneNode(true))
+
+    // Add a space so the button and instruction read correctly
+    // when CSS is disabled
+    containerSpan.insertAdjacentText('beforeend', ' ')
 
     const instructionSpan = document.createElement('span')
     instructionSpan.className = 'govuk-body govuk-file-upload__instruction'
@@ -119,8 +128,8 @@ export class FileUpload extends ConfigurableComponent {
 
     $button.appendChild(containerSpan)
     $button.setAttribute(
-      'aria-label',
-      `${this.$label.innerText}, ${this.i18n.t('selectFilesButton')} ${this.i18n.t('instruction')}, ${$status.innerText}`
+      'aria-labelledby',
+      `${$label.id} ${commaSpan.id} ${$button.id}`
     )
     $button.addEventListener('click', this.onClick.bind(this))
 
@@ -144,7 +153,7 @@ export class FileUpload extends ConfigurableComponent {
     // Bind change event to the underlying input
     this.$root.addEventListener('change', this.onChange.bind(this))
 
-    // Syncronise the `disabled` state between the button and underlying input
+    // Synchronise the `disabled` state between the button and underlying input
     this.updateDisabledState()
     this.observeDisabledState()
 
@@ -271,11 +280,6 @@ export class FileUpload extends ConfigurableComponent {
 
       this.$status.classList.remove('govuk-file-upload__status--empty')
     }
-
-    this.$button.setAttribute(
-      'aria-label',
-      `${this.$label.innerText}, ${this.i18n.t('selectFilesButton')} ${this.i18n.t('instruction')}, ${this.$status.innerText}`
-    )
   }
 
   /**
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index bbad4c7e5d..126e7320d7 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -1,6 +1,9 @@
 /* eslint-disable no-new */
 
-const { render } = require('@govuk-frontend/helpers/puppeteer')
+const {
+  render,
+  getAccessibleName
+} = require('@govuk-frontend/helpers/puppeteer')
 const { getExamples } = require('@govuk-frontend/lib/components')
 
 const inputSelector = '.govuk-file-upload'
@@ -104,15 +107,8 @@ describe('/components/file-upload', () => {
               (el) => el.innerHTML.trim()
             )
 
-            const buttonAriaText = await page.$eval(buttonSelector, (el) =>
-              el.getAttribute('aria-label')
-            )
-
             expect(buttonElementText).toBe('Choose file')
             expect(statusElementText).toBe('No file chosen')
-            expect(buttonAriaText).toBe(
-              'Upload a file, Choose file or drop file, No file chosen'
-            )
           })
         })
       })
@@ -348,6 +344,61 @@ describe('/components/file-upload', () => {
         })
       })
 
+      describe('accessible name', () => {
+        beforeEach(async () => {})
+
+        it('includes the label, the status, the pseudo button and instruction', async () => {
+          await render(page, 'file-upload', examples.enhanced)
+
+          const $element = await page.$('.govuk-file-upload__button')
+
+          const accessibleName = await getAccessibleName(page, $element)
+          await expect(accessibleName.replaceAll(/\s+/g, ' ')).toBe(
+            'Upload a file , No file chosen , Choose file or drop file'
+          )
+        })
+
+        it('includes the label, file name, pseudo button and instruction once a file is selected', async () => {
+          await render(page, 'file-upload', examples.enhanced)
+
+          const $element = await page.$('.govuk-file-upload__button')
+
+          const [fileChooser] = await Promise.all([
+            page.waitForFileChooser(),
+            page.click(buttonSelector)
+          ])
+          await fileChooser.accept(['fakefile.txt'])
+
+          const accessibleName = await getAccessibleName(page, $element)
+          await expect(accessibleName.replaceAll(/\s+/g, ' ')).toBe(
+            'Upload a file , fakefile.txt , Choose file or drop file'
+          )
+        })
+
+        it('includes the label, file name, pseudo button and instruction once a file is selected', async () => {
+          await render(page, 'file-upload', examples.enhanced, {
+            beforeInitialisation() {
+              document
+                .querySelector('[type="file"]')
+                .setAttribute('multiple', '')
+            }
+          })
+
+          const $element = await page.$('.govuk-file-upload__button')
+
+          const [fileChooser] = await Promise.all([
+            page.waitForFileChooser(),
+            page.click(buttonSelector)
+          ])
+          await fileChooser.accept(['fakefile1.txt', 'fakefile2.txt'])
+
+          const accessibleName = await getAccessibleName(page, $element)
+          await expect(accessibleName.replaceAll(/\s+/g, ' ')).toBe(
+            'Upload a file , 2 files chosen , Choose file or drop file'
+          )
+        })
+      })
+
       describe('i18n', () => {
         beforeEach(async () => {
           await render(page, 'file-upload', examples.translated)
@@ -363,15 +414,8 @@ describe('/components/file-upload', () => {
             el.innerHTML.trim()
           )
 
-          const buttonAriaText = await page.$eval(buttonSelector, (el) =>
-            el.getAttribute('aria-label')
-          )
-
           expect(buttonElementText).toBe('Dewiswch ffeil')
           expect(statusElementText).toBe("Dim ffeiliau wedi'u dewis")
-          expect(buttonAriaText).toBe(
-            "Llwythwch ffeil i fyny, Dewiswch ffeil neu ollwng ffeil, Dim ffeiliau wedi'u dewis"
-          )
         })
 
         describe('status element', () => {

From 0c0ffbe186489f1e4b42f456a0389fd4df21662d Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Fri, 31 Jan 2025 17:13:11 +0000
Subject: [PATCH 41/77] Move wrapping `div` to file input template

- `div` moved from `file-upload.mjs` to `template.njk`
- Add `data-module="file-upload"` to the wrapping div
- Move the `i18n` data attributes from the file input to the wrapping
`div`
- `$input` added to `file-upload.mjs` as well as type checking to ensure
it is a file input element
---
 .../govuk/components/file-upload/_index.scss  |  2 +-
 .../components/file-upload/file-upload.mjs    | 75 ++++++++++---------
 .../file-upload/file-upload.puppeteer.test.js |  2 +-
 .../govuk/components/file-upload/template.njk | 23 +++---
 .../components/file-upload/template.test.js   | 20 ++---
 5 files changed, 64 insertions(+), 58 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index b19b08308d..221dd9ca6d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -55,7 +55,7 @@
     background-color: $govuk-body-background-colour;
   }
 
-  .govuk-file-upload-wrapper .govuk-file-upload {
+  .govuk-frontend-supported .govuk-file-upload-wrapper .govuk-file-upload {
     position: absolute;
     // Make the native control take up the entire space of the element, but
     // invisible and behind the other elements until we need it
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 807825d697..3989d0d511 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -8,13 +8,14 @@ import { I18n } from '../../i18n.mjs'
  * File upload component
  *
  * @preserve
- * @augments ConfigurableComponent<FileUploadConfig,HTMLFileInputElement>
+ * @augments ConfigurableComponent<FileUploadConfig>
  */
 export class FileUpload extends ConfigurableComponent {
   /**
    * @private
+   * @type {HTMLFileInputElement}
    */
-  $wrapper
+  $input
 
   /**
    * @private
@@ -39,7 +40,18 @@ export class FileUpload extends ConfigurableComponent {
   constructor($root, config = {}) {
     super($root, config)
 
-    if (this.$root.type !== 'file') {
+    const $input = this.$root.querySelector('input')
+
+    if ($input === null) {
+      throw new ElementError(
+        formatErrorMessage(
+          FileUpload,
+          'File upload wrapper must have `input` element of type `file`'
+        )
+      )
+    }
+
+    if ($input.type !== 'file') {
       throw new ElementError(
         formatErrorMessage(
           FileUpload,
@@ -48,13 +60,15 @@ export class FileUpload extends ConfigurableComponent {
       )
     }
 
-    if (!this.$root.id.length) {
+    this.$input = /** @type {HTMLFileInputElement} */ ($input)
+
+    if (!this.$input.id.length) {
       throw new ElementError(
         formatErrorMessage(FileUpload, 'Form field must specify an `id`.')
       )
     }
 
-    this.id = this.$root.id
+    this.id = this.$input.id
 
     this.i18n = new I18n(this.config.i18n, {
       // Read the fallback if necessary rather than have it set in the defaults
@@ -72,11 +86,7 @@ export class FileUpload extends ConfigurableComponent {
     // we need to copy the 'id' of the root element
     // to the new button replacement element
     // so that focus will work in the error summary
-    this.$root.id = `${this.id}-input`
-
-    // Wrapping element. This defines the boundaries of our drag and drop area.
-    const $wrapper = document.createElement('div')
-    $wrapper.className = 'govuk-file-upload-wrapper'
+    this.$input.id = `${this.id}-input`
 
     // Create the file selection button
     const $button = document.createElement('button')
@@ -86,7 +96,7 @@ export class FileUpload extends ConfigurableComponent {
 
     // Copy `aria-describedby` if present so hints and errors
     // are associated to the `<button>`
-    const ariaDescribedBy = this.$root.getAttribute('aria-describedby')
+    const ariaDescribedBy = this.$input.getAttribute('aria-describedby')
     if (ariaDescribedBy) {
       $button.setAttribute('aria-describedby', ariaDescribedBy)
     }
@@ -134,24 +144,17 @@ export class FileUpload extends ConfigurableComponent {
     $button.addEventListener('click', this.onClick.bind(this))
 
     // Assemble these all together
-    $wrapper.insertAdjacentElement('beforeend', $button)
-
-    // Inject all this *after* the native file input
-    this.$root.insertAdjacentElement('afterend', $wrapper)
+    this.$root.insertAdjacentElement('beforeend', $button)
 
-    this.$root.setAttribute('tabindex', '-1')
-    this.$root.setAttribute('aria-hidden', 'true')
-
-    // Move the native file input to inside of the wrapper
-    $wrapper.insertAdjacentElement('afterbegin', this.$root)
+    this.$input.setAttribute('tabindex', '-1')
+    this.$input.setAttribute('aria-hidden', 'true')
 
     // Make all these new variables available to the module
-    this.$wrapper = $wrapper
     this.$button = $button
     this.$status = $status
 
     // Bind change event to the underlying input
-    this.$root.addEventListener('change', this.onChange.bind(this))
+    this.$input.addEventListener('change', this.onChange.bind(this))
 
     // Synchronise the `disabled` state between the button and underlying input
     this.updateDisabledState()
@@ -163,7 +166,7 @@ export class FileUpload extends ConfigurableComponent {
     this.$announcements.classList.add('govuk-file-upload-announcements')
     this.$announcements.classList.add('govuk-visually-hidden')
     this.$announcements.setAttribute('aria-live', 'assertive')
-    this.$wrapper.insertAdjacentElement('afterend', this.$announcements)
+    this.$root.insertAdjacentElement('afterend', this.$announcements)
 
     // The easy bit, when dropping hide the dropzone
     //
@@ -171,7 +174,7 @@ export class FileUpload extends ConfigurableComponent {
     // being dragged set as value of the `<input>`. This allows a `change`
     // event to be automatically fired from the element and saves us from having
     // to do anything more than hiding the dropzone on drop.
-    this.$wrapper.addEventListener('drop', this.hideDropZone.bind(this))
+    this.$input.addEventListener('drop', this.hideDropZone.bind(this))
 
     // While user is dragging, it gets a little more complex because of Safari.
     // Safari doesn't fill `relatedTarget` on `dragleave` (nor `dragenter`).
@@ -217,18 +220,16 @@ export class FileUpload extends ConfigurableComponent {
     // DOM interfaces only type `event.target` as `EventTarget`
     // so we first need to make sure it's a `Node`
     if (event.target instanceof Node) {
-      if (this.$wrapper.contains(event.target)) {
+      if (this.$root.contains(event.target)) {
         if (event.dataTransfer && isContainingFiles(event.dataTransfer)) {
           // Only update the class and make the announcement if not already visible
           // to avoid repeated announcements on NVDA (2024.4) + Firefox (133)
           if (
-            !this.$wrapper.classList.contains(
+            !this.$root.classList.contains(
               'govuk-file-upload-wrapper--show-dropzone'
             )
           ) {
-            this.$wrapper.classList.add(
-              'govuk-file-upload-wrapper--show-dropzone'
-            )
+            this.$root.classList.add('govuk-file-upload-wrapper--show-dropzone')
             this.$announcements.innerText = this.i18n.t('dropZoneEntered')
           }
         }
@@ -237,7 +238,7 @@ export class FileUpload extends ConfigurableComponent {
         // left the drop zone when they enter the page but haven't reached yet
         // the file upload component
         if (
-          this.$wrapper.classList.contains(
+          this.$root.classList.contains(
             'govuk-file-upload-wrapper--show-dropzone'
           )
         ) {
@@ -251,7 +252,7 @@ export class FileUpload extends ConfigurableComponent {
    * Hides the dropzone once user has dropped files on the `<input>`
    */
   hideDropZone() {
-    this.$wrapper.classList.remove('govuk-file-upload-wrapper--show-dropzone')
+    this.$root.classList.remove('govuk-file-upload-wrapper--show-dropzone')
     this.$announcements.innerText = this.i18n.t('dropZoneLeft')
   }
 
@@ -259,7 +260,7 @@ export class FileUpload extends ConfigurableComponent {
    * Check if the value of the underlying input has changed
    */
   onChange() {
-    const fileCount = this.$root.files.length
+    const fileCount = this.$input.files.length
 
     if (fileCount === 0) {
       // If there are no files, show the default selection text
@@ -270,7 +271,7 @@ export class FileUpload extends ConfigurableComponent {
         // If there is 1 file, just show the file name
         fileCount === 1
       ) {
-        this.$status.innerText = this.$root.files[0].name
+        this.$status.innerText = this.$input.files[0].name
       } else {
         // Otherwise, tell the user how many files are selected
         this.$status.innerText = this.i18n.t('filesSelected', {
@@ -291,7 +292,7 @@ export class FileUpload extends ConfigurableComponent {
    */
   findLabel() {
     // Use `label` in the selector so TypeScript knows the type fo `HTMLElement`
-    const $label = document.querySelector(`label[for="${this.$root.id}"]`)
+    const $label = document.querySelector(`label[for="${this.$input.id}"]`)
 
     if (!$label) {
       throw new ElementError({
@@ -307,7 +308,7 @@ export class FileUpload extends ConfigurableComponent {
    * When the button is clicked, emulate clicking the actual, hidden file input
    */
   onClick() {
-    this.$root.click()
+    this.$input.click()
   }
 
   /**
@@ -326,7 +327,7 @@ export class FileUpload extends ConfigurableComponent {
       }
     })
 
-    observer.observe(this.$root, {
+    observer.observe(this.$input, {
       attributes: true
     })
   }
@@ -335,7 +336,7 @@ export class FileUpload extends ConfigurableComponent {
    * Synchronise the `disabled` state between the input and replacement button.
    */
   updateDisabledState() {
-    this.$button.disabled = this.$root.disabled
+    this.$button.disabled = this.$input.disabled
   }
 
   /**
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 126e7320d7..5e5cd12023 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -288,7 +288,7 @@ describe('/components/file-upload', () => {
           ).resolves.toBe('Entered drop zone')
         })
 
-        it('gets hidden when dropping on the field', async () => {
+        xit('gets hidden when dropping on the field', async () => {
           // Add a little pixel to make sure we're effectively within the element
           await page.mouse.drop(
             { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index f39a74e1ce..23ddf5ef5d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -45,14 +45,10 @@
 {% if params.formGroup.beforeInput %}
   {{ params.formGroup.beforeInput.html | safe | trim | indent(2) if params.formGroup.beforeInput.html else params.formGroup.beforeInput.text }}
 {% endif %}
-  <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file"
-  {%- if params.value %} value="{{ params.value }}"{% endif %}
-  {%- if params.disabled %} disabled{% endif %}
-  {%- if params.multiple %} multiple{% endif %}
-  {%- if describedBy %} aria-describedby="{{ describedBy }}"{% endif %}
-  {%- if params.javascript %}
+{% if params.javascript %}
+  <div
+    class="govuk-file-upload-wrapper"
     data-module="govuk-file-upload"
-
     {{- govukI18nAttributes({
       key: 'select-files-button',
       message: params.selectFilesButtonText
@@ -68,9 +64,18 @@
     {{- govukI18nAttributes({
       key: 'instruction',
       message: params.instructionText
-    }) -}}    
-  {%- endif %}
+    }) -}}
+  >
+{% endif %}
+  <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file"
+  {%- if params.value %} value="{{ params.value }}"{% endif %}
+  {%- if params.disabled %} disabled{% endif %}
+  {%- if params.multiple %} multiple{% endif %}
+  {%- if describedBy %} aria-describedby="{{ describedBy }}"{% endif %}
   {{- govukAttributes(params.attributes) }}>
+{% if params.javascript %}
+  </div>
+{% endif %}
 {% if params.formGroup.afterInput %}
   {{ params.formGroup.afterInput.html | safe | trim | indent(2) if params.formGroup.afterInput.html else params.formGroup.afterInput.text }}
 {% endif %}
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index 2fa0c5c4a0..2f97e67d69 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -224,37 +224,37 @@ describe('File upload', () => {
       expect($input.attr('data-module')).toBeUndefined()
     })
 
-    it('adds the data-module attribute to the input when `true`', () => {
+    it('adds the data-module attribute to the wrapper when `true`', () => {
       const $ = render('file-upload', examples.enhanced)
 
-      const $input = $('.govuk-form-group > .govuk-file-upload')
+      const $wrapper = $('.govuk-form-group > .govuk-file-upload-wrapper')
 
-      expect($input.attr('data-module')).toBe('govuk-file-upload')
+      expect($wrapper.attr('data-module')).toBe('govuk-file-upload')
     })
 
     it('adds the data-module attribute when receiving an object', () => {
       const $ = render('file-upload', examples.translated)
 
-      const $input = $('.govuk-form-group > .govuk-file-upload')
+      const $wrapper = $('.govuk-form-group > .govuk-file-upload-wrapper')
 
-      expect($input.attr('data-module')).toBe('govuk-file-upload')
+      expect($wrapper.attr('data-module')).toBe('govuk-file-upload')
     })
 
     it('enables the rendering of translation messages when true', () => {
       const $ = render('file-upload', examples.translated)
 
-      const $input = $('.govuk-form-group > .govuk-file-upload')
+      const $wrapper = $('.govuk-form-group > .govuk-file-upload-wrapper')
 
-      expect($input.attr('data-i18n.select-files-button')).toBe(
+      expect($wrapper.attr('data-i18n.select-files-button')).toBe(
         'Dewiswch ffeil'
       )
-      expect($input.attr('data-i18n.files-selected-default')).toBe(
+      expect($wrapper.attr('data-i18n.files-selected-default')).toBe(
         "Dim ffeiliau wedi'u dewis"
       )
-      expect($input.attr('data-i18n.files-selected.one')).toBe(
+      expect($wrapper.attr('data-i18n.files-selected.one')).toBe(
         "%{count} ffeil wedi'i dewis"
       )
-      expect($input.attr('data-i18n.files-selected.other')).toBe(
+      expect($wrapper.attr('data-i18n.files-selected.other')).toBe(
         "%{count} ffeil wedi'u dewis"
       )
     })

From bb4e78c9347a08792ca0ceaedbafb6c49849775d Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Tue, 4 Feb 2025 15:53:46 +0000
Subject: [PATCH 42/77] Add disabled style to File Upload component

- Add styling for the File Upload component when it is disabled
- Add new File Upload Enhanced Disabled example
---
 .../govuk/components/file-upload/_index.scss  | 36 +++++++++++--------
 .../components/file-upload/file-upload.yaml   | 10 ++++++
 2 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 221dd9ca6d..d506082436 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -69,7 +69,7 @@
     opacity: 0;
   }
 
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload {
+  .govuk-frontend-supported .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload {
     z-index: 1;
   }
 
@@ -120,36 +120,42 @@
     }
   }
 
-  .govuk-file-upload-wrapper:hover .govuk-file-upload__button {
+  .govuk-file-upload__button:disabled {
+    pointer-events: none;
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button:not(:disabled),
+  .govuk-file-upload__button:hover {
     border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
+    background-color: govuk-colour("light-grey");
   }
 
-  .govuk-file-upload-wrapper:hover .govuk-file-upload__pseudo-button {
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__pseudo-button,
+  .govuk-file-upload__button:hover .govuk-file-upload__pseudo-button {
     background-color: govuk-shade(govuk-colour("light-grey"), 10%);
   }
 
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button,
-  .govuk-file-upload-wrapper:hover .govuk-file-upload__button {
-    background-color: govuk-colour("light-grey");
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button:not(:disabled) {
+    border: $file-upload-border-width solid govuk-colour("black");
   }
 
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__status--empty,
-  .govuk-file-upload-wrapper:hover .govuk-file-upload__status--empty,
+  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button:not(:disabled) .govuk-file-upload__status--empty,
+  .govuk-file-upload__button:hover .govuk-file-upload__status--empty,
   .govuk-file-upload__button:focus .govuk-file-upload__status--empty {
     background-color: govuk-tint(govuk-colour("blue"), 80%);
   }
 
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button {
-    border: $file-upload-border-width solid govuk-colour("black");
-  }
-
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__pseudo-button {
+  .govuk-file-upload-wrapper--show-dropzone
+    .govuk-file-upload__button:not(:disabled)
+    .govuk-file-upload__pseudo-button {
     background-color: govuk-colour("white");
   }
 
   .govuk-file-upload__button:active,
   .govuk-file-upload__button:focus {
-    border: 2px solid govuk-colour("black");
+    border: $file-upload-border-width solid govuk-colour("black");
     outline: $govuk-focus-width solid $govuk-focus-colour;
     // Ensure outline appears outside of the element
     outline-offset: 0;
@@ -167,7 +173,7 @@
     box-shadow: 0 2px 0 govuk-colour("black");
   }
 
-  .govuk-file-upload-wrapper:hover .govuk-file-upload__button:focus .govuk-file-upload__pseudo-button {
+  .govuk-file-upload__button:focus:hover .govuk-file-upload__pseudo-button {
     border-color: $govuk-focus-colour;
     outline: 3px solid transparent;
     background-color: govuk-colour("light-grey");
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index a7486245bc..ff521e4412 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -185,6 +185,16 @@ examples:
       label:
         text: Upload a file
       javascript: true
+  - name: enhanced, disabled
+    options:
+      javascript: true
+      disabled: true
+      id: file-upload-error
+      name: file-upload-error
+      label:
+        text: Upload a file
+      hint:
+        text: Your photo may be in your Pictures, Photos, Downloads or Desktop folder. Or in an app like iPhoto.
   - name: enhanced, with error message and hint
     options:
       javascript: true

From cec254fc15f76e340a2862eecb5280f304164a80 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Tue, 4 Feb 2025 16:17:10 +0000
Subject: [PATCH 43/77] Unify File Upload padding

File Upload padding is now 18px in every direction on mobile and 23px in
every direction on desktop.
---
 .../src/govuk/components/file-upload/_index.scss              | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index d506082436..2c733ac54e 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -110,13 +110,13 @@
   .govuk-file-upload__button {
     width: 100%;
     // align the padding to be same as notification banner and error summary accounting for the thicker borders
-    padding: govuk-spacing(3) (govuk-spacing(3) + $govuk-border-width - $file-upload-border-width);
+    padding: (govuk-spacing(3) + $govuk-border-width - $file-upload-border-width);
     border: $file-upload-border-width govuk-colour("mid-grey") dashed;
     background-color: govuk-colour("white");
     cursor: pointer;
 
     @include govuk-media-query($from: tablet) {
-      padding: govuk-spacing(3) (govuk-spacing(4) + $govuk-border-width - $file-upload-border-width);
+      padding: (govuk-spacing(4) + $govuk-border-width - $file-upload-border-width);
     }
   }
 

From 14000adfaba4c8c29fb0560598036a149a2b8b96 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Wed, 5 Feb 2025 14:53:46 +0000
Subject: [PATCH 44/77] Refactor the File Upload dropzone CSS

- Remove `govuk-file-upload-wrapper--show-dropzone`
- Add `govuk-file-upload__button--dragging`
- Add `govuk-file-upload-wrapper--disabled` for enabling `not-allowed`
cursor when File Upload is disabled
- Add `govuk-file-upload--dragging` for changing `z-index` of input
during dragging
- Amend File Upload test to use new dragging classes
---
 .../govuk/components/file-upload/_index.scss  | 22 +++++++++++--------
 .../components/file-upload/file-upload.mjs    | 22 ++++++++++++-------
 .../file-upload/file-upload.puppeteer.test.js |  4 ++--
 3 files changed, 29 insertions(+), 19 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 2c733ac54e..7fb714dfe4 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -55,6 +55,13 @@
     background-color: $govuk-body-background-colour;
   }
 
+  // required because disabling pointer events
+  // on the button means that the cursor style
+  // be applied on the button itself
+  .govuk-file-upload-wrapper--disabled {
+    cursor: not-allowed;
+  }
+
   .govuk-frontend-supported .govuk-file-upload-wrapper .govuk-file-upload {
     position: absolute;
     // Make the native control take up the entire space of the element, but
@@ -69,7 +76,7 @@
     opacity: 0;
   }
 
-  .govuk-frontend-supported .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload {
+  .govuk-frontend-supported .govuk-file-upload-wrapper .govuk-file-upload--dragging {
     z-index: 1;
   }
 
@@ -123,33 +130,30 @@
   .govuk-file-upload__button:disabled {
     pointer-events: none;
     opacity: 0.5;
-    cursor: not-allowed;
   }
 
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button:not(:disabled),
+  .govuk-file-upload__button--dragging:not(:disabled),
   .govuk-file-upload__button:hover {
     border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
     background-color: govuk-colour("light-grey");
   }
 
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__pseudo-button,
+  .govuk-file-upload__button--dragging:not(:disabled) .govuk-file-upload__pseudo-button,
   .govuk-file-upload__button:hover .govuk-file-upload__pseudo-button {
     background-color: govuk-shade(govuk-colour("light-grey"), 10%);
   }
 
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button:not(:disabled) {
+  .govuk-file-upload__button--dragging:not(:disabled) {
     border: $file-upload-border-width solid govuk-colour("black");
   }
 
-  .govuk-file-upload-wrapper--show-dropzone .govuk-file-upload__button:not(:disabled) .govuk-file-upload__status--empty,
+  .govuk-file-upload__button--dragging:not(:disabled) .govuk-file-upload__status--empty,
   .govuk-file-upload__button:hover .govuk-file-upload__status--empty,
   .govuk-file-upload__button:focus .govuk-file-upload__status--empty {
     background-color: govuk-tint(govuk-colour("blue"), 80%);
   }
 
-  .govuk-file-upload-wrapper--show-dropzone
-    .govuk-file-upload__button:not(:disabled)
-    .govuk-file-upload__pseudo-button {
+  .govuk-file-upload__button--dragging .govuk-file-upload__pseudo-button {
     background-color: govuk-colour("white");
   }
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 3989d0d511..9cb1964037 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -144,7 +144,7 @@ export class FileUpload extends ConfigurableComponent {
     $button.addEventListener('click', this.onClick.bind(this))
 
     // Assemble these all together
-    this.$root.insertAdjacentElement('beforeend', $button)
+    this.$root.insertAdjacentElement('afterbegin', $button)
 
     this.$input.setAttribute('tabindex', '-1')
     this.$input.setAttribute('aria-hidden', 'true')
@@ -225,11 +225,12 @@ export class FileUpload extends ConfigurableComponent {
           // Only update the class and make the announcement if not already visible
           // to avoid repeated announcements on NVDA (2024.4) + Firefox (133)
           if (
-            !this.$root.classList.contains(
-              'govuk-file-upload-wrapper--show-dropzone'
+            !this.$button.classList.contains(
+              'govuk-file-upload__button--dragging'
             )
           ) {
-            this.$root.classList.add('govuk-file-upload-wrapper--show-dropzone')
+            this.$button.classList.add('govuk-file-upload__button--dragging')
+            this.$input.classList.add('govuk-file-upload--dragging')
             this.$announcements.innerText = this.i18n.t('dropZoneEntered')
           }
         }
@@ -238,9 +239,7 @@ export class FileUpload extends ConfigurableComponent {
         // left the drop zone when they enter the page but haven't reached yet
         // the file upload component
         if (
-          this.$root.classList.contains(
-            'govuk-file-upload-wrapper--show-dropzone'
-          )
+          this.$button.classList.contains('govuk-file-upload__button--dragging')
         ) {
           this.hideDropZone()
         }
@@ -252,7 +251,8 @@ export class FileUpload extends ConfigurableComponent {
    * Hides the dropzone once user has dropped files on the `<input>`
    */
   hideDropZone() {
-    this.$root.classList.remove('govuk-file-upload-wrapper--show-dropzone')
+    this.$button.classList.remove('govuk-file-upload__button--dragging')
+    this.$input.classList.remove('govuk-file-upload--dragging')
     this.$announcements.innerText = this.i18n.t('dropZoneLeft')
   }
 
@@ -337,6 +337,12 @@ export class FileUpload extends ConfigurableComponent {
    */
   updateDisabledState() {
     this.$button.disabled = this.$input.disabled
+
+    if (this.$button.disabled) {
+      this.$root.classList.add('govuk-file-upload-wrapper--disabled')
+    } else {
+      this.$root.classList.remove('govuk-file-upload-wrapper--disabled')
+    }
   }
 
   /**
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 5e5cd12023..704f69c221 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -255,9 +255,9 @@ describe('/components/file-upload', () => {
         }
 
         const selectorDropzoneVisible =
-          '.govuk-file-upload-wrapper.govuk-file-upload-wrapper--show-dropzone'
+          '.govuk-file-upload__button.govuk-file-upload__button--dragging'
         const selectorDropzoneHidden =
-          '.govuk-file-upload-wrapper:not(.govuk-file-upload-wrapper--show-dropzone)'
+          '.govuk-file-upload__button:not(.govuk-file-upload__button--dragging)'
 
         beforeEach(async () => {
           await render(page, 'file-upload', examples.enhanced)

From eb99bc5662bcf535bef4a2905c6444c917059d32 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Wed, 5 Feb 2025 15:59:38 +0000
Subject: [PATCH 45/77] Fix File Upload status background colour

File Upload component status no longer blends into the background in
certain interactions. This means that the File Upload status text does
not appear to be misaligned with the button.
---
 .../govuk/components/file-upload/_index.scss  | 51 ++++++++++++++-----
 .../components/file-upload/file-upload.mjs    |  6 +--
 2 files changed, 40 insertions(+), 17 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 7fb714dfe4..16d9c0a4ad 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -97,10 +97,11 @@
     display: block;
     margin-bottom: govuk-spacing(2);
     padding: govuk-spacing(3) govuk-spacing(2);
+    background-color: govuk-colour("white");
     text-align: left;
   }
 
-  .govuk-file-upload__status--empty {
+  .govuk-file-upload__button--empty .govuk-file-upload__status {
     color: govuk-shade(govuk-colour("blue"), 60%);
     background-color: govuk-tint(govuk-colour("blue"), 70%);
   }
@@ -118,8 +119,8 @@
     width: 100%;
     // align the padding to be same as notification banner and error summary accounting for the thicker borders
     padding: (govuk-spacing(3) + $govuk-border-width - $file-upload-border-width);
-    border: $file-upload-border-width govuk-colour("mid-grey") dashed;
-    background-color: govuk-colour("white");
+    border: $file-upload-border-width govuk-colour("mid-grey") solid;
+    background-color: govuk-colour("light-grey");
     cursor: pointer;
 
     @include govuk-media-query($from: tablet) {
@@ -127,43 +128,60 @@
     }
   }
 
+  .govuk-file-upload__button--empty {
+    border-style: dashed;
+    background-color: govuk-colour("white");
+  }
+
+  .govuk-file-upload__button.govuk-file-upload__button--empty:hover {
+    background-color: govuk-colour("light-grey");
+  }
+
   .govuk-file-upload__button:disabled {
     pointer-events: none;
     opacity: 0.5;
   }
 
-  .govuk-file-upload__button--dragging:not(:disabled),
+  .govuk-file-upload__button--dragging.govuk-file-upload__button,
   .govuk-file-upload__button:hover {
-    border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
+    background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
+  }
+
+  .govuk-file-upload__button--dragging.govuk-file-upload__button--empty {
     background-color: govuk-colour("light-grey");
   }
 
+  .govuk-file-upload__button--dragging:not(:disabled) {
+    border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
+  }
+
   .govuk-file-upload__button--dragging:not(:disabled) .govuk-file-upload__pseudo-button,
   .govuk-file-upload__button:hover .govuk-file-upload__pseudo-button {
     background-color: govuk-shade(govuk-colour("light-grey"), 10%);
   }
 
-  .govuk-file-upload__button--dragging:not(:disabled) {
-    border: $file-upload-border-width solid govuk-colour("black");
-  }
-
-  .govuk-file-upload__button--dragging:not(:disabled) .govuk-file-upload__status--empty,
-  .govuk-file-upload__button:hover .govuk-file-upload__status--empty,
-  .govuk-file-upload__button:focus .govuk-file-upload__status--empty {
+  .govuk-file-upload__button--empty.govuk-file-upload__button--dragging:not(:disabled) .govuk-file-upload__status,
+  .govuk-file-upload__button--empty:hover .govuk-file-upload__status,
+  .govuk-file-upload__button--empty:focus .govuk-file-upload__status {
     background-color: govuk-tint(govuk-colour("blue"), 80%);
   }
 
-  .govuk-file-upload__button--dragging .govuk-file-upload__pseudo-button {
+  .govuk-file-upload__button .govuk-file-upload__pseudo-button,
+  .govuk-file-upload__button--empty.govuk-file-upload__button--dragging .govuk-file-upload__pseudo-button {
     background-color: govuk-colour("white");
   }
 
+  .govuk-file-upload__button--empty .govuk-file-upload__pseudo-button {
+    background-color: govuk-colour("light-grey");
+  }
+
   .govuk-file-upload__button:active,
   .govuk-file-upload__button:focus {
     border: $file-upload-border-width solid govuk-colour("black");
     outline: $govuk-focus-width solid $govuk-focus-colour;
     // Ensure outline appears outside of the element
     outline-offset: 0;
-    background-color: govuk-colour("light-grey");
+    background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
     // Double the border by adding its width again. Use `box-shadow` for this
     // instead of changing `border-width` - this is for consistency with
     // components such as textarea where we avoid changing `border-width` as
@@ -172,6 +190,11 @@
     box-shadow: inset 0 0 0 $govuk-border-width-form-element;
   }
 
+  .govuk-file-upload__button--empty:active,
+  .govuk-file-upload__button--empty:focus {
+    background-color: govuk-colour("light-grey");
+  }
+
   .govuk-file-upload__button:focus .govuk-file-upload__pseudo-button {
     background-color: $govuk-focus-colour;
     box-shadow: 0 2px 0 govuk-colour("black");
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 9cb1964037..504d60fd3f 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -93,6 +93,7 @@ export class FileUpload extends ConfigurableComponent {
     $button.classList.add('govuk-file-upload__button')
     $button.type = 'button'
     $button.id = this.id
+    $button.classList.add('govuk-file-upload__button--empty')
 
     // Copy `aria-describedby` if present so hints and errors
     // are associated to the `<button>`
@@ -105,7 +106,6 @@ export class FileUpload extends ConfigurableComponent {
     const $status = document.createElement('span')
     $status.className = 'govuk-body govuk-file-upload__status'
     $status.innerText = this.i18n.t('filesSelectedDefault')
-    $status.classList.add('govuk-file-upload__status--empty')
 
     $button.appendChild($status)
 
@@ -265,7 +265,7 @@ export class FileUpload extends ConfigurableComponent {
     if (fileCount === 0) {
       // If there are no files, show the default selection text
       this.$status.innerText = this.i18n.t('filesSelectedDefault')
-      this.$status.classList.add('govuk-file-upload__status--empty')
+      this.$button.classList.add('govuk-file-upload__button--empty')
     } else {
       if (
         // If there is 1 file, just show the file name
@@ -279,7 +279,7 @@ export class FileUpload extends ConfigurableComponent {
         })
       }
 
-      this.$status.classList.remove('govuk-file-upload__status--empty')
+      this.$button.classList.remove('govuk-file-upload__button--empty')
     }
   }
 

From 36f0d3789d7538acf81786fe17d183b48c4c5371 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 4 Feb 2025 15:54:00 +0000
Subject: [PATCH 46/77] Update name and description of macro options

- Consistently talk about 'choosing a file' to align with the button's default.
- Ensure order is consistent between description, default and condition for translation options.
- Ensure all translation options are suffixed by 'Text'

Co-authored-by: @seaemsi
---
 .../components/file-upload/file-upload.yaml   | 26 ++++++++++++-------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index ff521e4412..a8f7d56c98 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -80,23 +80,31 @@ params:
   - name: javascript
     type: boolean
     required: false
-    description: Whether to enable JavaScript enhancements for the component
-  - name: selectFilesButtonText
+    description: Can be used to enable JavaScript enhancements for the component.
+  - name: chooseFilesButtonText
     type: string
     required: false
-    description: The text of the button that opens the file picker. JavaScript enhanced version of the component only. Default is "Choose file".
-  - name: instructionText
+    description: The text of the button that opens the file picker. Default is `"Choose file"`. If `javascript` is not provided, this option will be ignored.
+  - name: dropInstructionText
     type: string
     required: false
-    description: The text of the instruction text that follows the button that opens the file picker. JavaScript enhanced version of the component only. Default is "or drop file".
-  - name: filesSelected
+    description: The text informing users they can drop files. Default is `"or drop file"`. If `javascript` is not provided, this option will be ignored.
+  - name: multipleFilesChosenText
     type: object
     required: false
-    description: The text to display when multiple files has been chosen by the user. JavaScript enhanced version of the component only. The component will replace the `%{count}` placeholder with the number of files selected. This is a [pluralised list of messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
-  - name: filesSelectedDefault
+    description: The text displayed when multiple files have been chosen by the user. The component will replace the `%{count}` placeholder with the number of files selected. [Our pluralisation rules apply to this macro option](https://frontend.design-system.service.gov.uk/localise-govuk-frontend/#understanding-pluralisation-rules). If `javascript` is not provided, this option will be ignored.
+  - name: noFileChosenText
     type: string
     required: false
-    description: The text to display when no file has been chosen by the user. JavaScript enhanced version of the component only. Default is "No file chosen".
+    description: The text displayed when no file has been chosen by the user. Default is `"No file chosen"`. If `javascript` is not provided, this option will be ignored.
+  - name: enteredDropZoneText
+    type: string
+    required: false
+    description: The text announced by assistive technology when user drags files and enters the drop zone. Default is `"Entered drop zone"`. If `javascript` is not provided, this option will be ignored.
+  - name: leftDropZoneText
+    type: string
+    require: false
+    description: The text announced by assistive technology when user drags files and leaves the drop zone without dropping. Default is `"Left drop zone"`. If `javascript` is not provided, this option will be ignored.
   - name: classes
     type: string
     required: false

From b43afbc2e8a415bfc309f7035297b5424021e683 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 4 Feb 2025 15:57:53 +0000
Subject: [PATCH 47/77] Update 'Choose file' button translation option to match
 docs

---
 .../src/views/examples/translated/index.njk                   | 2 +-
 .../src/govuk/components/file-upload/file-upload.mjs          | 4 ++--
 .../src/govuk/components/file-upload/file-upload.yaml         | 4 ++--
 .../src/govuk/components/file-upload/template.njk             | 4 ++--
 .../src/govuk/components/file-upload/template.test.js         | 2 +-
 5 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/govuk-frontend-review/src/views/examples/translated/index.njk b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
index 34de661f02..de97062790 100644
--- a/packages/govuk-frontend-review/src/views/examples/translated/index.njk
+++ b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
@@ -347,7 +347,7 @@
       text: "Llwythwch ffeil i fyny"
     },
     javascript: true,
-    selectFilesButtonText: "Dewiswch ffeil",
+    chooseFilesButtonText: "Dewiswch ffeil",
     filesSelectedDefaultText: "Dim ffeiliau wedi'u dewis",
     filesSelectedText: {
         other: "%{count} ffeil wedi'u dewis",
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 504d60fd3f..1000f12cb8 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -122,7 +122,7 @@ export class FileUpload extends ConfigurableComponent {
     const buttonSpan = document.createElement('span')
     buttonSpan.className =
       'govuk-button govuk-button--secondary govuk-file-upload__pseudo-button'
-    buttonSpan.innerText = this.i18n.t('selectFilesButton')
+    buttonSpan.innerText = this.i18n.t('chooseFilesButton')
 
     containerSpan.appendChild(buttonSpan)
 
@@ -359,7 +359,7 @@ export class FileUpload extends ConfigurableComponent {
    */
   static defaults = Object.freeze({
     i18n: {
-      selectFilesButton: 'Choose file',
+      chooseFilesButton: 'Choose file',
       filesSelectedDefault: 'No file chosen',
       filesSelected: {
         // the 'one' string isn't used as the component displays the filename
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index a8f7d56c98..578747139c 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -222,7 +222,7 @@ examples:
         text: Llwythwch ffeil i fyny
       multiple: true
       javascript: true
-      selectFilesButtonText: Dewiswch ffeil
+      chooseFilesButtonText: Dewiswch ffeil
       instructionText: neu ollwng ffeil
       filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
       filesSelectedText:
@@ -319,7 +319,7 @@ examples:
       label:
         text: Llwythwch ffeil i fyny
       multiple: true
-      selectFilesButtonText: Dewiswch ffeil
+      chooseFilesButtonText: Dewiswch ffeil
       filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
       filesSelectedText:
         other: "%{count} ffeil wedi'u dewis"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 23ddf5ef5d..57bd570613 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -50,8 +50,8 @@
     class="govuk-file-upload-wrapper"
     data-module="govuk-file-upload"
     {{- govukI18nAttributes({
-      key: 'select-files-button',
-      message: params.selectFilesButtonText
+      key: 'choose-files-button',
+      message: params.chooseFilesButtonText
     }) -}}
     {{- govukI18nAttributes({
       key: 'files-selected-default',
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index 2f97e67d69..f2a9107425 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -245,7 +245,7 @@ describe('File upload', () => {
 
       const $wrapper = $('.govuk-form-group > .govuk-file-upload-wrapper')
 
-      expect($wrapper.attr('data-i18n.select-files-button')).toBe(
+      expect($wrapper.attr('data-i18n.choose-files-button')).toBe(
         'Dewiswch ffeil'
       )
       expect($wrapper.attr('data-i18n.files-selected-default')).toBe(

From f09e17bf1e2765a71a0bab28824ae73432259ead Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 4 Feb 2025 17:19:17 +0000
Subject: [PATCH 48/77] Update 'or drop file'  translation to match docs

---
 .../src/govuk/components/file-upload/file-upload.mjs        | 6 +++---
 .../src/govuk/components/file-upload/file-upload.yaml       | 2 +-
 .../src/govuk/components/file-upload/template.njk           | 4 ++--
 .../src/govuk/components/file-upload/template.test.js       | 3 +++
 4 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 1000f12cb8..b9eaf1a20b 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -132,7 +132,7 @@ export class FileUpload extends ConfigurableComponent {
 
     const instructionSpan = document.createElement('span')
     instructionSpan.className = 'govuk-body govuk-file-upload__instruction'
-    instructionSpan.innerText = this.i18n.t('instruction')
+    instructionSpan.innerText = this.i18n.t('dropInstruction')
 
     containerSpan.appendChild(instructionSpan)
 
@@ -360,6 +360,7 @@ export class FileUpload extends ConfigurableComponent {
   static defaults = Object.freeze({
     i18n: {
       chooseFilesButton: 'Choose file',
+      dropInstruction: 'or drop file',
       filesSelectedDefault: 'No file chosen',
       filesSelected: {
         // the 'one' string isn't used as the component displays the filename
@@ -368,8 +369,7 @@ export class FileUpload extends ConfigurableComponent {
         other: '%{count} files chosen'
       },
       dropZoneEntered: 'Entered drop zone',
-      dropZoneLeft: 'Left drop zone',
-      instruction: 'or drop file'
+      dropZoneLeft: 'Left drop zone'
     }
   })
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 578747139c..f00891782e 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -223,7 +223,7 @@ examples:
       multiple: true
       javascript: true
       chooseFilesButtonText: Dewiswch ffeil
-      instructionText: neu ollwng ffeil
+      dropInstructionText: neu ollwng ffeil
       filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
       filesSelectedText:
         other: "%{count} ffeil wedi'u dewis"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 57bd570613..e353fb1e27 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -62,8 +62,8 @@
       messages: params.filesSelectedText
     }) -}}
     {{- govukI18nAttributes({
-      key: 'instruction',
-      message: params.instructionText
+      key: 'drop-instruction',
+      message: params.dropInstructionText
     }) -}}
   >
 {% endif %}
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index f2a9107425..b18c98741e 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -248,6 +248,9 @@ describe('File upload', () => {
       expect($wrapper.attr('data-i18n.choose-files-button')).toBe(
         'Dewiswch ffeil'
       )
+      expect($wrapper.attr('data-i18n.drop-instruction')).toBe(
+        'neu ollwng ffeil'
+      )
       expect($wrapper.attr('data-i18n.files-selected-default')).toBe(
         "Dim ffeiliau wedi'u dewis"
       )

From 552f030370420459f449717b730afdf0e16c8265 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 4 Feb 2025 17:27:49 +0000
Subject: [PATCH 49/77] Update 'No file chosen' translation to match docs

---
 .../src/views/examples/translated/index.njk                 | 2 +-
 .../src/govuk/components/file-upload/file-upload.mjs        | 6 +++---
 .../components/file-upload/file-upload.puppeteer.test.js    | 4 ++--
 .../src/govuk/components/file-upload/file-upload.yaml       | 4 ++--
 .../src/govuk/components/file-upload/template.njk           | 4 ++--
 .../src/govuk/components/file-upload/template.test.js       | 4 ++--
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/packages/govuk-frontend-review/src/views/examples/translated/index.njk b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
index de97062790..617178692e 100644
--- a/packages/govuk-frontend-review/src/views/examples/translated/index.njk
+++ b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
@@ -348,7 +348,7 @@
     },
     javascript: true,
     chooseFilesButtonText: "Dewiswch ffeil",
-    filesSelectedDefaultText: "Dim ffeiliau wedi'u dewis",
+    noFileChosenText: "Dim ffeiliau wedi'u dewis",
     filesSelectedText: {
         other: "%{count} ffeil wedi'u dewis",
         one: "%{count} ffeil wedi'i dewis"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index b9eaf1a20b..2d285b1e91 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -105,7 +105,7 @@ export class FileUpload extends ConfigurableComponent {
     // Create status element that shows what/how many files are selected
     const $status = document.createElement('span')
     $status.className = 'govuk-body govuk-file-upload__status'
-    $status.innerText = this.i18n.t('filesSelectedDefault')
+    $status.innerText = this.i18n.t('noFileChosen')
 
     $button.appendChild($status)
 
@@ -264,7 +264,7 @@ export class FileUpload extends ConfigurableComponent {
 
     if (fileCount === 0) {
       // If there are no files, show the default selection text
-      this.$status.innerText = this.i18n.t('filesSelectedDefault')
+      this.$status.innerText = this.i18n.t('noFileChosen')
       this.$button.classList.add('govuk-file-upload__button--empty')
     } else {
       if (
@@ -361,7 +361,7 @@ export class FileUpload extends ConfigurableComponent {
     i18n: {
       chooseFilesButton: 'Choose file',
       dropInstruction: 'or drop file',
-      filesSelectedDefault: 'No file chosen',
+      noFileChosen: 'No file chosen',
       filesSelected: {
         // the 'one' string isn't used as the component displays the filename
         // instead, however it's here for coverage's sake
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 704f69c221..5b7e3d4860 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -415,7 +415,7 @@ describe('/components/file-upload', () => {
           )
 
           expect(buttonElementText).toBe('Dewiswch ffeil')
-          expect(statusElementText).toBe("Dim ffeiliau wedi'u dewis")
+          expect(statusElementText).toBe("Dim ffeil wedi'i dewis")
         })
 
         describe('status element', () => {
@@ -424,7 +424,7 @@ describe('/components/file-upload', () => {
               el.innerHTML.trim()
             )
 
-            expect(statusText).toBe("Dim ffeiliau wedi'u dewis")
+            expect(statusText).toBe("Dim ffeil wedi'i dewis")
           })
 
           it('uses the correct translation when multiple files are selected', async () => {
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index f00891782e..1518a4a29d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -224,7 +224,7 @@ examples:
       javascript: true
       chooseFilesButtonText: Dewiswch ffeil
       dropInstructionText: neu ollwng ffeil
-      filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
+      noFileChosenText: Dim ffeil wedi'i dewis
       filesSelectedText:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"
@@ -320,7 +320,7 @@ examples:
         text: Llwythwch ffeil i fyny
       multiple: true
       chooseFilesButtonText: Dewiswch ffeil
-      filesSelectedDefaultText: Dim ffeiliau wedi'u dewis
+      noFileChosenText: Dim ffeiliau wedi'u dewis
       filesSelectedText:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index e353fb1e27..4bf653209c 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -54,8 +54,8 @@
       message: params.chooseFilesButtonText
     }) -}}
     {{- govukI18nAttributes({
-      key: 'files-selected-default',
-      message: params.filesSelectedDefaultText
+      key: 'no-file-chosen',
+      message: params.noFileChosenText
     }) -}}
     {{- govukI18nAttributes({
       key: 'files-selected',
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index b18c98741e..15cf85e21c 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -251,8 +251,8 @@ describe('File upload', () => {
       expect($wrapper.attr('data-i18n.drop-instruction')).toBe(
         'neu ollwng ffeil'
       )
-      expect($wrapper.attr('data-i18n.files-selected-default')).toBe(
-        "Dim ffeiliau wedi'u dewis"
+      expect($wrapper.attr('data-i18n.no-file-chosen')).toBe(
+        "Dim ffeil wedi'i dewis"
       )
       expect($wrapper.attr('data-i18n.files-selected.one')).toBe(
         "%{count} ffeil wedi'i dewis"

From 07f8d9ac2cfdaf1a05697bd00b5cfea5926fd0c5 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 4 Feb 2025 17:30:14 +0000
Subject: [PATCH 50/77] Update translations for multiple files selected to
 match docs

---
 .../src/views/examples/translated/index.njk                 | 2 +-
 .../src/govuk/components/file-upload/file-upload.mjs        | 6 +++---
 .../src/govuk/components/file-upload/file-upload.yaml       | 4 ++--
 .../src/govuk/components/file-upload/template.njk           | 4 ++--
 .../src/govuk/components/file-upload/template.test.js       | 4 ++--
 5 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/packages/govuk-frontend-review/src/views/examples/translated/index.njk b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
index 617178692e..6e7e663b8c 100644
--- a/packages/govuk-frontend-review/src/views/examples/translated/index.njk
+++ b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
@@ -349,7 +349,7 @@
     javascript: true,
     chooseFilesButtonText: "Dewiswch ffeil",
     noFileChosenText: "Dim ffeiliau wedi'u dewis",
-    filesSelectedText: {
+    multipleFilesChosenText: {
         other: "%{count} ffeil wedi'u dewis",
         one: "%{count} ffeil wedi'i dewis"
     }
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 2d285b1e91..567c868c83 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -274,7 +274,7 @@ export class FileUpload extends ConfigurableComponent {
         this.$status.innerText = this.$input.files[0].name
       } else {
         // Otherwise, tell the user how many files are selected
-        this.$status.innerText = this.i18n.t('filesSelected', {
+        this.$status.innerText = this.i18n.t('multipleFilesChosen', {
           count: fileCount
         })
       }
@@ -362,7 +362,7 @@ export class FileUpload extends ConfigurableComponent {
       chooseFilesButton: 'Choose file',
       dropInstruction: 'or drop file',
       noFileChosen: 'No file chosen',
-      filesSelected: {
+      multipleFilesChosen: {
         // the 'one' string isn't used as the component displays the filename
         // instead, however it's here for coverage's sake
         one: '%{count} file chosen',
@@ -425,7 +425,7 @@ function isContainingFiles(dataTransfer) {
  *
  * Messages used by the component
  * @property {string} [selectFiles] - Text of button that opens file browser
- * @property {TranslationPluralForms} [filesSelected] - Text indicating how
+ * @property {TranslationPluralForms} [multipleFilesChosen] - Text indicating how
  *   many files have been selected
  * @property {string} [dropZoneEntered] - Text announced to assistive technology
  *   when users entered the drop zone while dragging
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 1518a4a29d..1bb303d536 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -225,7 +225,7 @@ examples:
       chooseFilesButtonText: Dewiswch ffeil
       dropInstructionText: neu ollwng ffeil
       noFileChosenText: Dim ffeil wedi'i dewis
-      filesSelectedText:
+      multipleFilesChosenText:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"
 
@@ -321,6 +321,6 @@ examples:
       multiple: true
       chooseFilesButtonText: Dewiswch ffeil
       noFileChosenText: Dim ffeiliau wedi'u dewis
-      filesSelectedText:
+      multipleFilesChosenText:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 4bf653209c..2537006051 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -58,8 +58,8 @@
       message: params.noFileChosenText
     }) -}}
     {{- govukI18nAttributes({
-      key: 'files-selected',
-      messages: params.filesSelectedText
+      key: 'multiple-files-chosen',
+      messages: params.multipleFilesChosenText
     }) -}}
     {{- govukI18nAttributes({
       key: 'drop-instruction',
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index 15cf85e21c..1a94e6e03d 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -254,10 +254,10 @@ describe('File upload', () => {
       expect($wrapper.attr('data-i18n.no-file-chosen')).toBe(
         "Dim ffeil wedi'i dewis"
       )
-      expect($wrapper.attr('data-i18n.files-selected.one')).toBe(
+      expect($wrapper.attr('data-i18n.multiple-files-chosen.one')).toBe(
         "%{count} ffeil wedi'i dewis"
       )
-      expect($wrapper.attr('data-i18n.files-selected.other')).toBe(
+      expect($wrapper.attr('data-i18n.multiple-files-chosen.other')).toBe(
         "%{count} ffeil wedi'u dewis"
       )
     })

From 80e50466fd27bb9618b0169d03e8cfb1eff33fdf Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 4 Feb 2025 17:33:32 +0000
Subject: [PATCH 51/77] Add back missing `enteredDropZoneText` option to the
 template

Looks like it was dropped at some point, possibly during a rebase
---
 .../src/govuk/components/file-upload/file-upload.mjs        | 6 +++---
 .../src/govuk/components/file-upload/file-upload.yaml       | 2 ++
 .../src/govuk/components/file-upload/template.njk           | 4 ++++
 .../src/govuk/components/file-upload/template.test.js       | 3 +++
 4 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 567c868c83..68428d8e5e 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -231,7 +231,7 @@ export class FileUpload extends ConfigurableComponent {
           ) {
             this.$button.classList.add('govuk-file-upload__button--dragging')
             this.$input.classList.add('govuk-file-upload--dragging')
-            this.$announcements.innerText = this.i18n.t('dropZoneEntered')
+            this.$announcements.innerText = this.i18n.t('enteredDropZone')
           }
         }
       } else {
@@ -368,7 +368,7 @@ export class FileUpload extends ConfigurableComponent {
         one: '%{count} file chosen',
         other: '%{count} files chosen'
       },
-      dropZoneEntered: 'Entered drop zone',
+      enteredDropZone: 'Entered drop zone',
       dropZoneLeft: 'Left drop zone'
     }
   })
@@ -427,7 +427,7 @@ function isContainingFiles(dataTransfer) {
  * @property {string} [selectFiles] - Text of button that opens file browser
  * @property {TranslationPluralForms} [multipleFilesChosen] - Text indicating how
  *   many files have been selected
- * @property {string} [dropZoneEntered] - Text announced to assistive technology
+ * @property {string} [enteredDropZone] - Text announced to assistive technology
  *   when users entered the drop zone while dragging
  * @property {string} [dropZoneLeft] - Text announced to assistive technology
  *   when users left the drop zone while dragging
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 1bb303d536..239b4e06ab 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -228,6 +228,7 @@ examples:
       multipleFilesChosenText:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"
+      enteredDropZoneText: Wedi mynd i mewn i'r parth gollwng
 
   # Hidden examples are not shown in the review app, but are used for tests and HTML fixtures
   - name: with value
@@ -324,3 +325,4 @@ examples:
       multipleFilesChosenText:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"
+      enteredDropZoneText: Wedi mynd i mewn i'r parth gollwng
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 2537006051..03c280eafb 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -65,6 +65,10 @@
       key: 'drop-instruction',
       message: params.dropInstructionText
     }) -}}
+    {{- govukI18nAttributes({
+      key: 'entered-drop-zone',
+      message: params.enteredDropZoneText
+    }) -}}
   >
 {% endif %}
   <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index 1a94e6e03d..3f3778e603 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -260,6 +260,9 @@ describe('File upload', () => {
       expect($wrapper.attr('data-i18n.multiple-files-chosen.other')).toBe(
         "%{count} ffeil wedi'u dewis"
       )
+      expect($wrapper.attr('data-i18n.entered-drop-zone')).toBe(
+        "Wedi mynd i mewn i'r parth gollwng"
+      )
     })
 
     it('prevents the rendering of translation messages when false', () => {

From 1db2c10853aadd769dc4bacaa3ba16a39b347287 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 4 Feb 2025 17:35:36 +0000
Subject: [PATCH 52/77] Add back missing `leftDropZoneText` option to the
 template

Looks like it was dropped at some point, possibly during a rebase
---
 .../src/govuk/components/file-upload/file-upload.mjs        | 6 +++---
 .../src/govuk/components/file-upload/file-upload.yaml       | 4 +++-
 .../src/govuk/components/file-upload/template.njk           | 4 ++++
 .../src/govuk/components/file-upload/template.test.js       | 3 +++
 4 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 68428d8e5e..d171eae537 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -253,7 +253,7 @@ export class FileUpload extends ConfigurableComponent {
   hideDropZone() {
     this.$button.classList.remove('govuk-file-upload__button--dragging')
     this.$input.classList.remove('govuk-file-upload--dragging')
-    this.$announcements.innerText = this.i18n.t('dropZoneLeft')
+    this.$announcements.innerText = this.i18n.t('leftDropZone')
   }
 
   /**
@@ -369,7 +369,7 @@ export class FileUpload extends ConfigurableComponent {
         other: '%{count} files chosen'
       },
       enteredDropZone: 'Entered drop zone',
-      dropZoneLeft: 'Left drop zone'
+      leftDropZone: 'Left drop zone'
     }
   })
 
@@ -429,7 +429,7 @@ function isContainingFiles(dataTransfer) {
  *   many files have been selected
  * @property {string} [enteredDropZone] - Text announced to assistive technology
  *   when users entered the drop zone while dragging
- * @property {string} [dropZoneLeft] - Text announced to assistive technology
+ * @property {string} [leftDropZone] - Text announced to assistive technology
  *   when users left the drop zone while dragging
  */
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 239b4e06ab..2dc9ce33b8 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -103,7 +103,7 @@ params:
     description: The text announced by assistive technology when user drags files and enters the drop zone. Default is `"Entered drop zone"`. If `javascript` is not provided, this option will be ignored.
   - name: leftDropZoneText
     type: string
-    require: false
+    required: false
     description: The text announced by assistive technology when user drags files and leaves the drop zone without dropping. Default is `"Left drop zone"`. If `javascript` is not provided, this option will be ignored.
   - name: classes
     type: string
@@ -229,6 +229,7 @@ examples:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"
       enteredDropZoneText: Wedi mynd i mewn i'r parth gollwng
+      leftDropZoneText: Parth gollwng i'r chwith
 
   # Hidden examples are not shown in the review app, but are used for tests and HTML fixtures
   - name: with value
@@ -326,3 +327,4 @@ examples:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"
       enteredDropZoneText: Wedi mynd i mewn i'r parth gollwng
+      leftDropZoneText: Parth gollwng i'r chwith
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 03c280eafb..7c5baf16f1 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -69,6 +69,10 @@
       key: 'entered-drop-zone',
       message: params.enteredDropZoneText
     }) -}}
+    {{- govukI18nAttributes({
+      key: 'left-drop-zone',
+      message: params.leftDropZoneText
+    }) -}}
   >
 {% endif %}
   <input class="govuk-file-upload {%- if params.classes %} {{ params.classes }}{% endif %} {%- if params.errorMessage %} govuk-file-upload--error{% endif %}" id="{{ id }}" name="{{ params.name }}" type="file"
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index 3f3778e603..d3dec74289 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -263,6 +263,9 @@ describe('File upload', () => {
       expect($wrapper.attr('data-i18n.entered-drop-zone')).toBe(
         "Wedi mynd i mewn i'r parth gollwng"
       )
+      expect($wrapper.attr('data-i18n.left-drop-zone')).toBe(
+        "Parth gollwng i'r chwith"
+      )
     })
 
     it('prevents the rendering of translation messages when false', () => {

From 64ce29967d8dc2f6a24a142223af57d45fe042be Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 4 Feb 2025 17:40:07 +0000
Subject: [PATCH 53/77] Align `FileUploadTranslations` type descriptions with
 macro options

---
 .../govuk/components/file-upload/file-upload.mjs | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index d171eae537..4dfef4f1cd 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -424,13 +424,15 @@ function isContainingFiles(dataTransfer) {
  * @typedef {object} FileUploadTranslations
  *
  * Messages used by the component
- * @property {string} [selectFiles] - Text of button that opens file browser
- * @property {TranslationPluralForms} [multipleFilesChosen] - Text indicating how
- *   many files have been selected
- * @property {string} [enteredDropZone] - Text announced to assistive technology
- *   when users entered the drop zone while dragging
- * @property {string} [leftDropZone] - Text announced to assistive technology
- *   when users left the drop zone while dragging
+ * @property {string} [chooseFile] - The text of the button that opens the file picker
+ * @property {string} [dropInstruction] - The text informing users they can drop files
+ * @property {TranslationPluralForms} [multipleFilesChosen] - The text displayed when multiple files
+ *   have been chosen by the user
+ * @property {string} [noFileChosen] - The text to displayed when no file has been chosen by the user
+ * @property {string} [enteredDropZone] - The text announced by assistive technology
+ *   when user drags files and enters the drop zone
+ * @property {string} [leftDropZone] - The text announced by assistive technology
+ *   when user drags files and leaves the drop zone without dropping
  */
 
 /**

From 789be983ebd0c131e4de3e31226e39569e0e7eee Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 7 Feb 2025 12:47:23 +0000
Subject: [PATCH 54/77] Fix test for dropping on the component

---
 .../components/file-upload/file-upload.puppeteer.test.js  | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 5b7e3d4860..dc9bb93295 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -288,7 +288,13 @@ describe('/components/file-upload', () => {
           ).resolves.toBe('Entered drop zone')
         })
 
-        xit('gets hidden when dropping on the field', async () => {
+        it('gets hidden when dropping on the field', async () => {
+          // Add a little pixel to make sure we're effectively within the element
+          await page.mouse.dragEnter(
+            { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
+            structuredClone(dragData)
+          )
+
           // Add a little pixel to make sure we're effectively within the element
           await page.mouse.drop(
             { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },

From ddcaa9aa2d1fdd81b384cb4a500099ab96f3af26 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 7 Feb 2025 12:53:50 +0000
Subject: [PATCH 55/77] Update announcement on drop to be the component's
 status

---
 .../components/file-upload/file-upload.mjs    | 43 +++++++++++++++----
 .../file-upload/file-upload.puppeteer.test.js |  7 +--
 2 files changed, 38 insertions(+), 12 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 4dfef4f1cd..a34dfc9337 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -174,7 +174,7 @@ export class FileUpload extends ConfigurableComponent {
     // being dragged set as value of the `<input>`. This allows a `change`
     // event to be automatically fired from the element and saves us from having
     // to do anything more than hiding the dropzone on drop.
-    this.$input.addEventListener('drop', this.hideDropZone.bind(this))
+    this.$input.addEventListener('drop', this.onDrop.bind(this))
 
     // While user is dragging, it gets a little more complex because of Safari.
     // Safari doesn't fill `relatedTarget` on `dragleave` (nor `dragenter`).
@@ -204,7 +204,8 @@ export class FileUpload extends ConfigurableComponent {
 
     document.addEventListener('dragleave', () => {
       if (!this.enteredAnotherElement) {
-        this.hideDropZone()
+        this.hideDraggingState()
+        this.$announcements.innerText = this.i18n.t('leftDropZone')
       }
 
       this.enteredAnotherElement = false
@@ -229,8 +230,7 @@ export class FileUpload extends ConfigurableComponent {
               'govuk-file-upload__button--dragging'
             )
           ) {
-            this.$button.classList.add('govuk-file-upload__button--dragging')
-            this.$input.classList.add('govuk-file-upload--dragging')
+            this.showDraggingState()
             this.$announcements.innerText = this.i18n.t('enteredDropZone')
           }
         }
@@ -241,19 +241,45 @@ export class FileUpload extends ConfigurableComponent {
         if (
           this.$button.classList.contains('govuk-file-upload__button--dragging')
         ) {
-          this.hideDropZone()
+          this.hideDraggingState()
+          this.$announcements.innerText = this.i18n.t('leftDropZone')
         }
       }
     }
   }
 
   /**
-   * Hides the dropzone once user has dropped files on the `<input>`
+   * Show the drop zone visually
    */
-  hideDropZone() {
+  showDraggingState() {
+    this.$button.classList.add('govuk-file-upload__button--dragging')
+    this.$input.classList.add('govuk-file-upload--dragging')
+  }
+
+  /**
+   * Hides the drop zone visually
+   */
+  hideDraggingState() {
     this.$button.classList.remove('govuk-file-upload__button--dragging')
     this.$input.classList.remove('govuk-file-upload--dragging')
-    this.$announcements.innerText = this.i18n.t('leftDropZone')
+  }
+
+  /**
+   * Handles user dropping on the component
+   */
+  onDrop() {
+    this.hideDraggingState()
+
+    // The change event updating the text will only happen after the `drop`
+    // Because this listener is registered after `onChange`, it'll run after
+    // the status is updated and can pick it up for announcement
+    this.$input.addEventListener(
+      'change',
+      () => {
+        this.$announcements.innerText = this.$status.innerText
+      },
+      { once: true }
+    )
   }
 
   /**
@@ -317,7 +343,6 @@ export class FileUpload extends ConfigurableComponent {
   observeDisabledState() {
     const observer = new MutationObserver((mutationList) => {
       for (const mutation of mutationList) {
-        console.log('mutation', mutation)
         if (
           mutation.type === 'attributes' &&
           mutation.attributeName === 'disabled'
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index dc9bb93295..ce22b247e0 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -289,13 +289,14 @@ describe('/components/file-upload', () => {
         })
 
         it('gets hidden when dropping on the field', async () => {
-          // Add a little pixel to make sure we're effectively within the element
+          // Puppeteer's Mouse.drop is meant to do both the `dragEnter` and
+          // `drop` in a row but it seems to do this too quickly for the
+          // `<input>` to effectively receive the drop
           await page.mouse.dragEnter(
             { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
             structuredClone(dragData)
           )
 
-          // Add a little pixel to make sure we're effectively within the element
           await page.mouse.drop(
             { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
             structuredClone(dragData)
@@ -306,7 +307,7 @@ describe('/components/file-upload', () => {
           // rather than being in the initial state
           await expect(
             $announcements.evaluate((e) => e.textContent)
-          ).resolves.toBe('Left drop zone')
+          ).resolves.toBe('file-upload.puppeteer.test.js')
         })
 
         it('gets hidden when dragging a file and leaving the field', async () => {

From 41f464f3ae81fb6abad43a6e65dff341aee360b8 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 7 Feb 2025 14:49:58 +0000
Subject: [PATCH 56/77] Rename `.govuk-file-upload-wrapper` to
 `.govuk-drop-zone`

The name is more representative
---
 .../src/govuk/components/file-upload/_index.scss          | 8 ++++----
 .../src/govuk/components/file-upload/file-upload.mjs      | 4 ++--
 .../components/file-upload/file-upload.puppeteer.test.js  | 6 +++---
 .../src/govuk/components/file-upload/template.njk         | 2 +-
 .../src/govuk/components/file-upload/template.test.js     | 6 +++---
 5 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 16d9c0a4ad..76d6065682 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -48,7 +48,7 @@
     }
   }
 
-  .govuk-file-upload-wrapper {
+  .govuk-drop-zone {
     display: block;
     position: relative;
     z-index: 0;
@@ -58,11 +58,11 @@
   // required because disabling pointer events
   // on the button means that the cursor style
   // be applied on the button itself
-  .govuk-file-upload-wrapper--disabled {
+  .govuk-drop-zone--disabled {
     cursor: not-allowed;
   }
 
-  .govuk-frontend-supported .govuk-file-upload-wrapper .govuk-file-upload {
+  .govuk-frontend-supported .govuk-drop-zone .govuk-file-upload {
     position: absolute;
     // Make the native control take up the entire space of the element, but
     // invisible and behind the other elements until we need it
@@ -76,7 +76,7 @@
     opacity: 0;
   }
 
-  .govuk-frontend-supported .govuk-file-upload-wrapper .govuk-file-upload--dragging {
+  .govuk-frontend-supported .govuk-drop-zone .govuk-file-upload--dragging {
     z-index: 1;
   }
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index a34dfc9337..96ff6435a0 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -364,9 +364,9 @@ export class FileUpload extends ConfigurableComponent {
     this.$button.disabled = this.$input.disabled
 
     if (this.$button.disabled) {
-      this.$root.classList.add('govuk-file-upload-wrapper--disabled')
+      this.$root.classList.add('govuk-drop-zone--disabled')
     } else {
-      this.$root.classList.remove('govuk-file-upload-wrapper--disabled')
+      this.$root.classList.remove('govuk-drop-zone--disabled')
     }
   }
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index ce22b247e0..d6e326c293 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -7,7 +7,7 @@ const {
 const { getExamples } = require('@govuk-frontend/lib/components')
 
 const inputSelector = '.govuk-file-upload'
-const wrapperSelector = '.govuk-file-upload-wrapper'
+const wrapperSelector = '.govuk-drop-zone'
 const buttonSelector = '.govuk-file-upload__button'
 const statusSelector = '.govuk-file-upload__status'
 const pseudoButtonSelector = '.govuk-file-upload__pseudo-button'
@@ -262,7 +262,7 @@ describe('/components/file-upload', () => {
         beforeEach(async () => {
           await render(page, 'file-upload', examples.enhanced)
 
-          $wrapper = await page.$('.govuk-file-upload-wrapper')
+          $wrapper = await page.$('.govuk-drop-zone')
           wrapperBoundingBox = await $wrapper.boundingBox()
 
           $announcements = await page.$('.govuk-file-upload-announcements')
@@ -339,7 +339,7 @@ describe('/components/file-upload', () => {
 
           // It doesn't seem doable to make Puppeteer drag outside the viewport
           // so instead, we can only mock two 'dragleave' events
-          await page.$eval('.govuk-file-upload-wrapper', ($el) => {
+          await page.$eval('.govuk-drop-zone', ($el) => {
             $el.dispatchEvent(new Event('dragleave', { bubbles: true }))
             $el.dispatchEvent(new Event('dragleave', { bubbles: true }))
           })
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
index 7c5baf16f1..55059d42ef 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.njk
@@ -47,7 +47,7 @@
 {% endif %}
 {% if params.javascript %}
   <div
-    class="govuk-file-upload-wrapper"
+    class="govuk-drop-zone"
     data-module="govuk-file-upload"
     {{- govukI18nAttributes({
       key: 'choose-files-button',
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
index d3dec74289..cbe1e9158e 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/template.test.js
@@ -227,7 +227,7 @@ describe('File upload', () => {
     it('adds the data-module attribute to the wrapper when `true`', () => {
       const $ = render('file-upload', examples.enhanced)
 
-      const $wrapper = $('.govuk-form-group > .govuk-file-upload-wrapper')
+      const $wrapper = $('.govuk-form-group > .govuk-drop-zone')
 
       expect($wrapper.attr('data-module')).toBe('govuk-file-upload')
     })
@@ -235,7 +235,7 @@ describe('File upload', () => {
     it('adds the data-module attribute when receiving an object', () => {
       const $ = render('file-upload', examples.translated)
 
-      const $wrapper = $('.govuk-form-group > .govuk-file-upload-wrapper')
+      const $wrapper = $('.govuk-form-group > .govuk-drop-zone')
 
       expect($wrapper.attr('data-module')).toBe('govuk-file-upload')
     })
@@ -243,7 +243,7 @@ describe('File upload', () => {
     it('enables the rendering of translation messages when true', () => {
       const $ = render('file-upload', examples.translated)
 
-      const $wrapper = $('.govuk-form-group > .govuk-file-upload-wrapper')
+      const $wrapper = $('.govuk-form-group > .govuk-drop-zone')
 
       expect($wrapper.attr('data-i18n.choose-files-button')).toBe(
         'Dewiswch ffeil'

From b58fe1d80b5817cc7ac28860d7b9aca21543514f Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Fri, 7 Feb 2025 14:57:28 +0000
Subject: [PATCH 57/77] Add `govuk-file-upload--enhanced` to File Upload

Simplify selectors in `index.scss` of File Upload by adding new
`govuk-file-upload--enhanced` class. Add `govuk-file-upload--enhanced`
to `input` element in Javascript initialisation.
---
 .../govuk/components/file-upload/_index.scss  |  4 ++--
 .../components/file-upload/file-upload.mjs    |  2 ++
 .../file-upload/file-upload.puppeteer.test.js | 22 ++++++++++---------
 3 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 76d6065682..8e29966f99 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -62,7 +62,7 @@
     cursor: not-allowed;
   }
 
-  .govuk-frontend-supported .govuk-drop-zone .govuk-file-upload {
+  .govuk-file-upload--enhanced {
     position: absolute;
     // Make the native control take up the entire space of the element, but
     // invisible and behind the other elements until we need it
@@ -76,7 +76,7 @@
     opacity: 0;
   }
 
-  .govuk-frontend-supported .govuk-drop-zone .govuk-file-upload--dragging {
+  .govuk-file-upload--dragging {
     z-index: 1;
   }
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 96ff6435a0..17a1accd33 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -148,6 +148,8 @@ export class FileUpload extends ConfigurableComponent {
 
     this.$input.setAttribute('tabindex', '-1')
     this.$input.setAttribute('aria-hidden', 'true')
+    this.$input.classList.remove('govuk-file-upload')
+    this.$input.classList.add('govuk-file-upload--enhanced')
 
     // Make all these new variables available to the module
     this.$button = $button
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index d6e326c293..85a50cafac 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -7,6 +7,7 @@ const {
 const { getExamples } = require('@govuk-frontend/lib/components')
 
 const inputSelector = '.govuk-file-upload'
+const enhancedInputSelector = '.govuk-file-upload--enhanced'
 const wrapperSelector = '.govuk-drop-zone'
 const buttonSelector = '.govuk-file-upload__button'
 const statusSelector = '.govuk-file-upload__status'
@@ -66,7 +67,7 @@ describe('/components/file-upload', () => {
 
           it('moves the file input inside of the wrapper element', async () => {
             const inputElementParent = await page.$eval(
-              inputSelector,
+              enhancedInputSelector,
               (el) => el.parentNode
             )
             const wrapperElement = await page.$eval(wrapperSelector, (el) => el)
@@ -77,8 +78,9 @@ describe('/components/file-upload', () => {
 
         describe('file input', () => {
           it('sets tabindex to -1', async () => {
-            const inputElementTabindex = await page.$eval(inputSelector, (el) =>
-              el.getAttribute('tabindex')
+            const inputElementTabindex = await page.$eval(
+              enhancedInputSelector,
+              (el) => el.getAttribute('tabindex')
             )
 
             expect(inputElementTabindex).toBe('-1')
@@ -132,7 +134,7 @@ describe('/components/file-upload', () => {
             await fileChooser.accept([testFilename])
 
             const inputElementValue = await page.$eval(
-              inputSelector,
+              enhancedInputSelector,
               (el) =>
                 // @ts-ignore
                 el.value
@@ -160,14 +162,14 @@ describe('/components/file-upload', () => {
 
         it('updates the file input value', async () => {
           const inputElementValue = await page.$eval(
-            inputSelector,
+            enhancedInputSelector,
             (el) =>
               // @ts-ignore
               el.value
           )
 
           const inputElementFiles = await page.$eval(
-            inputSelector,
+            enhancedInputSelector,
             (el) =>
               // @ts-ignore
               el.files
@@ -209,14 +211,14 @@ describe('/components/file-upload', () => {
 
         it('updates the file input value', async () => {
           const inputElementValue = await page.$eval(
-            inputSelector,
+            enhancedInputSelector,
             (el) =>
               // @ts-ignore
               el.value
           )
 
           const inputElementFiles = await page.$eval(
-            inputSelector,
+            enhancedInputSelector,
             (el) =>
               // @ts-ignore
               el.files
@@ -470,7 +472,7 @@ describe('/components/file-upload', () => {
         it('disables the button if the input is disabled programatically', async () => {
           await render(page, 'file-upload', examples.enhanced)
 
-          await page.$eval(inputSelector, (el) =>
+          await page.$eval(enhancedInputSelector, (el) =>
             el.setAttribute('disabled', '')
           )
 
@@ -494,7 +496,7 @@ describe('/components/file-upload', () => {
             el.hasAttribute('disabled')
           )
 
-          await page.$eval(inputSelector, (el) =>
+          await page.$eval(enhancedInputSelector, (el) =>
             el.removeAttribute('disabled')
           )
 

From d93e74a1a8aa79892913072d6a4e02f70e9b9408 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 7 Feb 2025 15:22:47 +0000
Subject: [PATCH 58/77] Rename `.govuk-file-upload__button` to
 `.govuk-file-upload-button`

The element is its own block not a descendant of `.govuk-file-upload`. Renames its descendants to make them elements of `.govuk-file-upload-button` rather than of `.govuk-file-upload`.
---
 .../govuk/components/file-upload/_index.scss  | 52 +++++++++----------
 .../components/file-upload/file-upload.mjs    | 26 +++++-----
 .../file-upload/file-upload.puppeteer.test.js | 16 +++---
 3 files changed, 48 insertions(+), 46 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 8e29966f99..6f785a276a 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -80,20 +80,20 @@
     z-index: 1;
   }
 
-  .govuk-file-upload__pseudo-button {
+  .govuk-file-upload-button__pseudo-button {
     width: auto;
     margin-right: govuk-spacing(2);
     margin-bottom: $govuk-border-width-form-element + 1;
     flex-shrink: 0;
   }
 
-  .govuk-file-upload__instruction {
+  .govuk-file-upload-button__instruction {
     margin-top: govuk-spacing(2) - ($govuk-border-width-form-element + 1);
     margin-bottom: 0;
     text-align: left;
   }
 
-  .govuk-file-upload__status {
+  .govuk-file-upload-button__status {
     display: block;
     margin-bottom: govuk-spacing(2);
     padding: govuk-spacing(3) govuk-spacing(2);
@@ -101,7 +101,7 @@
     text-align: left;
   }
 
-  .govuk-file-upload__button--empty .govuk-file-upload__status {
+  .govuk-file-upload-button--empty .govuk-file-upload-button__status {
     color: govuk-shade(govuk-colour("blue"), 60%);
     background-color: govuk-tint(govuk-colour("blue"), 70%);
   }
@@ -109,13 +109,13 @@
   // bugs documented with button using flex
   // https://github.com/philipwalton/flexbugs#flexbug-9
   // so we need a container here
-  .govuk-file-upload__pseudo-button-container {
+  .govuk-file-upload-button__pseudo-button-container {
     display: flex;
     align-items: baseline;
     flex-wrap: wrap;
   }
 
-  .govuk-file-upload__button {
+  .govuk-file-upload-button {
     width: 100%;
     // align the padding to be same as notification banner and error summary accounting for the thicker borders
     padding: (govuk-spacing(3) + $govuk-border-width - $file-upload-border-width);
@@ -128,55 +128,55 @@
     }
   }
 
-  .govuk-file-upload__button--empty {
+  .govuk-file-upload-button--empty {
     border-style: dashed;
     background-color: govuk-colour("white");
   }
 
-  .govuk-file-upload__button.govuk-file-upload__button--empty:hover {
+  .govuk-file-upload-button--empty:hover {
     background-color: govuk-colour("light-grey");
   }
 
-  .govuk-file-upload__button:disabled {
+  .govuk-file-upload-button:disabled {
     pointer-events: none;
     opacity: 0.5;
   }
 
-  .govuk-file-upload__button--dragging.govuk-file-upload__button,
+  .govuk-file-upload-button--dragging.govuk-file-upload-button,
   .govuk-file-upload__button:hover {
     background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
   }
 
-  .govuk-file-upload__button--dragging.govuk-file-upload__button--empty {
+  .govuk-file-upload-button--dragging.govuk-file-upload-button--empty {
     background-color: govuk-colour("light-grey");
   }
 
-  .govuk-file-upload__button--dragging:not(:disabled) {
+  .govuk-file-upload-button--dragging:not(:disabled) {
     border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
   }
 
-  .govuk-file-upload__button--dragging:not(:disabled) .govuk-file-upload__pseudo-button,
-  .govuk-file-upload__button:hover .govuk-file-upload__pseudo-button {
+  .govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__pseudo-button,
+  .govuk-file-upload-button:hover .govuk-file-upload-button__pseudo-button {
     background-color: govuk-shade(govuk-colour("light-grey"), 10%);
   }
 
-  .govuk-file-upload__button--empty.govuk-file-upload__button--dragging:not(:disabled) .govuk-file-upload__status,
-  .govuk-file-upload__button--empty:hover .govuk-file-upload__status,
-  .govuk-file-upload__button--empty:focus .govuk-file-upload__status {
+  .govuk-file-upload-button--empty.govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__status,
+  .govuk-file-upload-button--empty:hover .govuk-file-upload-button__status,
+  .govuk-file-upload-button--empty:focus .govuk-file-upload-button__status {
     background-color: govuk-tint(govuk-colour("blue"), 80%);
   }
 
-  .govuk-file-upload__button .govuk-file-upload__pseudo-button,
-  .govuk-file-upload__button--empty.govuk-file-upload__button--dragging .govuk-file-upload__pseudo-button {
+  .govuk-file-upload-button .govuk-file-upload-button__pseudo-button,
+  .govuk-file-upload-button--empty.govuk-file-upload-button--dragging .govuk-file-upload-button__pseudo-button {
     background-color: govuk-colour("white");
   }
 
-  .govuk-file-upload__button--empty .govuk-file-upload__pseudo-button {
+  .govuk-file-upload-button--empty .govuk-file-upload-button__pseudo-button {
     background-color: govuk-colour("light-grey");
   }
 
-  .govuk-file-upload__button:active,
-  .govuk-file-upload__button:focus {
+  .govuk-file-upload-button:active,
+  .govuk-file-upload-button:focus {
     border: $file-upload-border-width solid govuk-colour("black");
     outline: $govuk-focus-width solid $govuk-focus-colour;
     // Ensure outline appears outside of the element
@@ -190,17 +190,17 @@
     box-shadow: inset 0 0 0 $govuk-border-width-form-element;
   }
 
-  .govuk-file-upload__button--empty:active,
-  .govuk-file-upload__button--empty:focus {
+  .govuk-file-upload-button--empty:active,
+  .govuk-file-upload-button--empty:focus {
     background-color: govuk-colour("light-grey");
   }
 
-  .govuk-file-upload__button:focus .govuk-file-upload__pseudo-button {
+  .govuk-file-upload-button:focus .govuk-file-upload-button__pseudo-button {
     background-color: $govuk-focus-colour;
     box-shadow: 0 2px 0 govuk-colour("black");
   }
 
-  .govuk-file-upload__button:focus:hover .govuk-file-upload__pseudo-button {
+  .govuk-file-upload-button:focus:hover .govuk-file-upload-button__pseudo-button {
     border-color: $govuk-focus-colour;
     outline: 3px solid transparent;
     background-color: govuk-colour("light-grey");
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 17a1accd33..7356b0871f 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -90,10 +90,10 @@ export class FileUpload extends ConfigurableComponent {
 
     // Create the file selection button
     const $button = document.createElement('button')
-    $button.classList.add('govuk-file-upload__button')
+    $button.classList.add('govuk-file-upload-button')
     $button.type = 'button'
     $button.id = this.id
-    $button.classList.add('govuk-file-upload__button--empty')
+    $button.classList.add('govuk-file-upload-button--empty')
 
     // Copy `aria-describedby` if present so hints and errors
     // are associated to the `<button>`
@@ -104,7 +104,7 @@ export class FileUpload extends ConfigurableComponent {
 
     // Create status element that shows what/how many files are selected
     const $status = document.createElement('span')
-    $status.className = 'govuk-body govuk-file-upload__status'
+    $status.className = 'govuk-body govuk-file-upload-button__status'
     $status.innerText = this.i18n.t('noFileChosen')
 
     $button.appendChild($status)
@@ -117,11 +117,12 @@ export class FileUpload extends ConfigurableComponent {
     $button.appendChild(commaSpan)
 
     const containerSpan = document.createElement('span')
-    containerSpan.className = 'govuk-file-upload__pseudo-button-container'
+    containerSpan.className =
+      'govuk-file-upload-button__pseudo-button-container'
 
     const buttonSpan = document.createElement('span')
     buttonSpan.className =
-      'govuk-button govuk-button--secondary govuk-file-upload__pseudo-button'
+      'govuk-button govuk-button--secondary govuk-file-upload-button__pseudo-button'
     buttonSpan.innerText = this.i18n.t('chooseFilesButton')
 
     containerSpan.appendChild(buttonSpan)
@@ -131,7 +132,8 @@ export class FileUpload extends ConfigurableComponent {
     containerSpan.insertAdjacentText('beforeend', ' ')
 
     const instructionSpan = document.createElement('span')
-    instructionSpan.className = 'govuk-body govuk-file-upload__instruction'
+    instructionSpan.className =
+      'govuk-body govuk-file-upload-button__instruction'
     instructionSpan.innerText = this.i18n.t('dropInstruction')
 
     containerSpan.appendChild(instructionSpan)
@@ -229,7 +231,7 @@ export class FileUpload extends ConfigurableComponent {
           // to avoid repeated announcements on NVDA (2024.4) + Firefox (133)
           if (
             !this.$button.classList.contains(
-              'govuk-file-upload__button--dragging'
+              'govuk-file-upload-button--dragging'
             )
           ) {
             this.showDraggingState()
@@ -241,7 +243,7 @@ export class FileUpload extends ConfigurableComponent {
         // left the drop zone when they enter the page but haven't reached yet
         // the file upload component
         if (
-          this.$button.classList.contains('govuk-file-upload__button--dragging')
+          this.$button.classList.contains('govuk-file-upload-button--dragging')
         ) {
           this.hideDraggingState()
           this.$announcements.innerText = this.i18n.t('leftDropZone')
@@ -254,7 +256,7 @@ export class FileUpload extends ConfigurableComponent {
    * Show the drop zone visually
    */
   showDraggingState() {
-    this.$button.classList.add('govuk-file-upload__button--dragging')
+    this.$button.classList.add('govuk-file-upload-button--dragging')
     this.$input.classList.add('govuk-file-upload--dragging')
   }
 
@@ -262,7 +264,7 @@ export class FileUpload extends ConfigurableComponent {
    * Hides the drop zone visually
    */
   hideDraggingState() {
-    this.$button.classList.remove('govuk-file-upload__button--dragging')
+    this.$button.classList.remove('govuk-file-upload-button--dragging')
     this.$input.classList.remove('govuk-file-upload--dragging')
   }
 
@@ -293,7 +295,7 @@ export class FileUpload extends ConfigurableComponent {
     if (fileCount === 0) {
       // If there are no files, show the default selection text
       this.$status.innerText = this.i18n.t('noFileChosen')
-      this.$button.classList.add('govuk-file-upload__button--empty')
+      this.$button.classList.add('govuk-file-upload-button--empty')
     } else {
       if (
         // If there is 1 file, just show the file name
@@ -307,7 +309,7 @@ export class FileUpload extends ConfigurableComponent {
         })
       }
 
-      this.$button.classList.remove('govuk-file-upload__button--empty')
+      this.$button.classList.remove('govuk-file-upload-button--empty')
     }
   }
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 85a50cafac..07f1ed7285 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -9,9 +9,9 @@ const { getExamples } = require('@govuk-frontend/lib/components')
 const inputSelector = '.govuk-file-upload'
 const enhancedInputSelector = '.govuk-file-upload--enhanced'
 const wrapperSelector = '.govuk-drop-zone'
-const buttonSelector = '.govuk-file-upload__button'
-const statusSelector = '.govuk-file-upload__status'
-const pseudoButtonSelector = '.govuk-file-upload__pseudo-button'
+const buttonSelector = '.govuk-file-upload-button'
+const statusSelector = '.govuk-file-upload-button__status'
+const pseudoButtonSelector = '.govuk-file-upload-button__pseudo-button'
 
 describe('/components/file-upload', () => {
   let examples
@@ -257,9 +257,9 @@ describe('/components/file-upload', () => {
         }
 
         const selectorDropzoneVisible =
-          '.govuk-file-upload__button.govuk-file-upload__button--dragging'
+          '.govuk-file-upload-button.govuk-file-upload-button--dragging'
         const selectorDropzoneHidden =
-          '.govuk-file-upload__button:not(.govuk-file-upload__button--dragging)'
+          '.govuk-file-upload-button:not(.govuk-file-upload-button--dragging)'
 
         beforeEach(async () => {
           await render(page, 'file-upload', examples.enhanced)
@@ -359,7 +359,7 @@ describe('/components/file-upload', () => {
         it('includes the label, the status, the pseudo button and instruction', async () => {
           await render(page, 'file-upload', examples.enhanced)
 
-          const $element = await page.$('.govuk-file-upload__button')
+          const $element = await page.$('.govuk-file-upload-button')
 
           const accessibleName = await getAccessibleName(page, $element)
           await expect(accessibleName.replaceAll(/\s+/g, ' ')).toBe(
@@ -370,7 +370,7 @@ describe('/components/file-upload', () => {
         it('includes the label, file name, pseudo button and instruction once a file is selected', async () => {
           await render(page, 'file-upload', examples.enhanced)
 
-          const $element = await page.$('.govuk-file-upload__button')
+          const $element = await page.$('.govuk-file-upload-button')
 
           const [fileChooser] = await Promise.all([
             page.waitForFileChooser(),
@@ -393,7 +393,7 @@ describe('/components/file-upload', () => {
             }
           })
 
-          const $element = await page.$('.govuk-file-upload__button')
+          const $element = await page.$('.govuk-file-upload-button')
 
           const [fileChooser] = await Promise.all([
             page.waitForFileChooser(),

From d9ea008f5150992f04790ce181e7975b771ab08b Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Fri, 7 Feb 2025 15:29:24 +0000
Subject: [PATCH 59/77] Regroup `:hover` styles in the
 `govuk-file-upload-button` block

Helps understand the changes that happen on hover
---
 .../govuk/components/file-upload/_index.scss  | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 6f785a276a..6daa19fdcc 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -126,6 +126,18 @@
     @include govuk-media-query($from: tablet) {
       padding: (govuk-spacing(4) + $govuk-border-width - $file-upload-border-width);
     }
+
+    &:hover {
+      background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
+
+      .govuk-file-upload-button__pseudo-button {
+        background-color: govuk-shade(govuk-colour("light-grey"), 10%);
+      }
+
+      .govuk-file-upload-button__status {
+        background-color: govuk-tint(govuk-colour("blue"), 80%);
+      }
+    }
   }
 
   .govuk-file-upload-button--empty {
@@ -142,8 +154,7 @@
     opacity: 0.5;
   }
 
-  .govuk-file-upload-button--dragging.govuk-file-upload-button,
-  .govuk-file-upload__button:hover {
+  .govuk-file-upload-button--dragging.govuk-file-upload-button {
     background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
   }
 
@@ -155,13 +166,11 @@
     border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
   }
 
-  .govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__pseudo-button,
-  .govuk-file-upload-button:hover .govuk-file-upload-button__pseudo-button {
+  .govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__pseudo-button {
     background-color: govuk-shade(govuk-colour("light-grey"), 10%);
   }
 
   .govuk-file-upload-button--empty.govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__status,
-  .govuk-file-upload-button--empty:hover .govuk-file-upload-button__status,
   .govuk-file-upload-button--empty:focus .govuk-file-upload-button__status {
     background-color: govuk-tint(govuk-colour("blue"), 80%);
   }

From e3b29e12869a4a23699a15c55212be0346359787 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Fri, 7 Feb 2025 15:43:41 +0000
Subject: [PATCH 60/77] Refactor `active`, `focus`CSS of File Upload

Use SCSS nesting to simplify selectors.
---
 .../govuk/components/file-upload/_index.scss  | 54 +++++++++----------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 6daa19fdcc..f67ce2b593 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -138,6 +138,33 @@
         background-color: govuk-tint(govuk-colour("blue"), 80%);
       }
     }
+
+    &:active,
+    &:focus {
+      border: $file-upload-border-width solid govuk-colour("black");
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+      // Ensure outline appears outside of the element
+      outline-offset: 0;
+      background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
+      // Double the border by adding its width again. Use `box-shadow` for this
+      // instead of changing `border-width` - this is for consistency with
+      // components such as textarea where we avoid changing `border-width` as
+      // it will change the element size. Also, `outline` cannot be utilised
+      // here as it is already used for the yellow focus state.
+      box-shadow: inset 0 0 0 $govuk-border-width-form-element;
+
+      .govuk-file-upload-button__pseudo-button {
+        background-color: $govuk-focus-colour;
+        box-shadow: 0 2px 0 govuk-colour("black");
+      }
+
+      &:hover .govuk-file-upload-button__pseudo-button {
+        border-color: $govuk-focus-colour;
+        outline: 3px solid transparent;
+        background-color: govuk-colour("light-grey");
+        box-shadow: inset 0 0 0 1px $govuk-focus-colour;
+      }
+    }
   }
 
   .govuk-file-upload-button--empty {
@@ -184,35 +211,8 @@
     background-color: govuk-colour("light-grey");
   }
 
-  .govuk-file-upload-button:active,
-  .govuk-file-upload-button:focus {
-    border: $file-upload-border-width solid govuk-colour("black");
-    outline: $govuk-focus-width solid $govuk-focus-colour;
-    // Ensure outline appears outside of the element
-    outline-offset: 0;
-    background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
-    // Double the border by adding its width again. Use `box-shadow` for this
-    // instead of changing `border-width` - this is for consistency with
-    // components such as textarea where we avoid changing `border-width` as
-    // it will change the element size. Also, `outline` cannot be utilised
-    // here as it is already used for the yellow focus state.
-    box-shadow: inset 0 0 0 $govuk-border-width-form-element;
-  }
-
   .govuk-file-upload-button--empty:active,
   .govuk-file-upload-button--empty:focus {
     background-color: govuk-colour("light-grey");
   }
-
-  .govuk-file-upload-button:focus .govuk-file-upload-button__pseudo-button {
-    background-color: $govuk-focus-colour;
-    box-shadow: 0 2px 0 govuk-colour("black");
-  }
-
-  .govuk-file-upload-button:focus:hover .govuk-file-upload-button__pseudo-button {
-    border-color: $govuk-focus-colour;
-    outline: 3px solid transparent;
-    background-color: govuk-colour("light-grey");
-    box-shadow: inset 0 0 0 1px $govuk-focus-colour;
-  }
 }

From 1c70a874ec908a8ae9360b041b054f75691d087f Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Fri, 7 Feb 2025 15:50:20 +0000
Subject: [PATCH 61/77] Nest `disabled` File Upload button styles

---
 .../src/govuk/components/file-upload/_index.scss       | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index f67ce2b593..bbb71b77d1 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -165,6 +165,11 @@
         box-shadow: inset 0 0 0 1px $govuk-focus-colour;
       }
     }
+
+    &:disabled {
+      pointer-events: none;
+      opacity: 0.5;
+    }
   }
 
   .govuk-file-upload-button--empty {
@@ -176,11 +181,6 @@
     background-color: govuk-colour("light-grey");
   }
 
-  .govuk-file-upload-button:disabled {
-    pointer-events: none;
-    opacity: 0.5;
-  }
-
   .govuk-file-upload-button--dragging.govuk-file-upload-button {
     background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
   }

From 6c6cdde30024094b02153a5c003483e10e50557b Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Fri, 7 Feb 2025 16:01:31 +0000
Subject: [PATCH 62/77] Refactor `--empty` button styles in File Upload

---
 .../govuk/components/file-upload/_index.scss  | 31 +++++++++----------
 1 file changed, 14 insertions(+), 17 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index bbb71b77d1..28a8df3728 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -101,11 +101,6 @@
     text-align: left;
   }
 
-  .govuk-file-upload-button--empty .govuk-file-upload-button__status {
-    color: govuk-shade(govuk-colour("blue"), 60%);
-    background-color: govuk-tint(govuk-colour("blue"), 70%);
-  }
-
   // bugs documented with button using flex
   // https://github.com/philipwalton/flexbugs#flexbug-9
   // so we need a container here
@@ -175,10 +170,21 @@
   .govuk-file-upload-button--empty {
     border-style: dashed;
     background-color: govuk-colour("white");
-  }
 
-  .govuk-file-upload-button--empty:hover {
-    background-color: govuk-colour("light-grey");
+    .govuk-file-upload-button__status {
+      color: govuk-shade(govuk-colour("blue"), 60%);
+      background-color: govuk-tint(govuk-colour("blue"), 70%);
+    }
+
+    &:hover,
+    &:focus,
+    &:active {
+      background-color: govuk-colour("light-grey");
+
+      .govuk-file-upload-button__status {
+        background-color: govuk-tint(govuk-colour("blue"), 80%);
+      }
+    }
   }
 
   .govuk-file-upload-button--dragging.govuk-file-upload-button {
@@ -198,10 +204,6 @@
   }
 
   .govuk-file-upload-button--empty.govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__status,
-  .govuk-file-upload-button--empty:focus .govuk-file-upload-button__status {
-    background-color: govuk-tint(govuk-colour("blue"), 80%);
-  }
-
   .govuk-file-upload-button .govuk-file-upload-button__pseudo-button,
   .govuk-file-upload-button--empty.govuk-file-upload-button--dragging .govuk-file-upload-button__pseudo-button {
     background-color: govuk-colour("white");
@@ -210,9 +212,4 @@
   .govuk-file-upload-button--empty .govuk-file-upload-button__pseudo-button {
     background-color: govuk-colour("light-grey");
   }
-
-  .govuk-file-upload-button--empty:active,
-  .govuk-file-upload-button--empty:focus {
-    background-color: govuk-colour("light-grey");
-  }
 }

From 1b25638183fc6c178f5f1a365ad923b2c314ad76 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Fri, 7 Feb 2025 16:05:08 +0000
Subject: [PATCH 63/77] Move pseudo button selectors in File Upload css

---
 .../src/govuk/components/file-upload/_index.scss    | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 28a8df3728..2e06b7b9cd 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -122,6 +122,10 @@
       padding: (govuk-spacing(4) + $govuk-border-width - $file-upload-border-width);
     }
 
+    .govuk-file-upload-button__pseudo-button {
+      background-color: govuk-colour("white");
+    }
+
     &:hover {
       background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
 
@@ -171,6 +175,10 @@
     border-style: dashed;
     background-color: govuk-colour("white");
 
+    .govuk-file-upload-button__pseudo-button {
+      background-color: govuk-colour("light-grey");
+    }
+
     .govuk-file-upload-button__status {
       color: govuk-shade(govuk-colour("blue"), 60%);
       background-color: govuk-tint(govuk-colour("blue"), 70%);
@@ -204,12 +212,7 @@
   }
 
   .govuk-file-upload-button--empty.govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__status,
-  .govuk-file-upload-button .govuk-file-upload-button__pseudo-button,
   .govuk-file-upload-button--empty.govuk-file-upload-button--dragging .govuk-file-upload-button__pseudo-button {
     background-color: govuk-colour("white");
   }
-
-  .govuk-file-upload-button--empty .govuk-file-upload-button__pseudo-button {
-    background-color: govuk-colour("light-grey");
-  }
 }

From 8fec1e15735ff16057c27a0bc03d359a16d88549 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Fri, 7 Feb 2025 16:16:03 +0000
Subject: [PATCH 64/77] Refactor `--dragging` button styles in File Upload

---
 .../govuk/components/file-upload/_index.scss  | 34 +++++++++++--------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 2e06b7b9cd..db156ac3aa 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -195,24 +195,28 @@
     }
   }
 
-  .govuk-file-upload-button--dragging.govuk-file-upload-button {
-    background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
-  }
+  .govuk-file-upload-button--dragging {
+    // extra specificity to apply when
+    // empty
+    &.govuk-file-upload-button {
+      background-color: govuk-tint(govuk-colour("mid-grey"), 20%);
+    }
 
-  .govuk-file-upload-button--dragging.govuk-file-upload-button--empty {
-    background-color: govuk-colour("light-grey");
-  }
+    &.govuk-file-upload-button--empty {
+      background-color: govuk-colour("light-grey");
+    }
 
-  .govuk-file-upload-button--dragging:not(:disabled) {
-    border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
-  }
+    &:not(:disabled) {
+      border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
 
-  .govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__pseudo-button {
-    background-color: govuk-shade(govuk-colour("light-grey"), 10%);
-  }
+      .govuk-file-upload-button__pseudo-button {
+        background-color: govuk-shade(govuk-colour("light-grey"), 10%);
+      }
+    }
 
-  .govuk-file-upload-button--empty.govuk-file-upload-button--dragging:not(:disabled) .govuk-file-upload-button__status,
-  .govuk-file-upload-button--empty.govuk-file-upload-button--dragging .govuk-file-upload-button__pseudo-button {
-    background-color: govuk-colour("white");
+    &.govuk-file-upload-button--empty:not(:disabled) .govuk-file-upload-button__status,
+    &.govuk-file-upload-button--empty .govuk-file-upload-button__pseudo-button {
+      background-color: govuk-colour("white");
+    }
   }
 }

From f8b1c879bd155e50cd92e3dbe777b487d49de70e Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Mon, 10 Feb 2025 16:35:00 +0000
Subject: [PATCH 65/77] Fix enhanced File Upload functionality without CSS

- `input` element hidden during File Upload enhancement initialisation
- `button` listens for drop event and updates status and input
accordingly
---
 .../components/file-upload/file-upload.mjs    | 38 ++++++++++++-------
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 7356b0871f..d319470950 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -61,6 +61,7 @@ export class FileUpload extends ConfigurableComponent {
     }
 
     this.$input = /** @type {HTMLFileInputElement} */ ($input)
+    this.$input.setAttribute('hidden', 'true')
 
     if (!this.$input.id.length) {
       throw new ElementError(
@@ -144,6 +145,10 @@ export class FileUpload extends ConfigurableComponent {
       `${$label.id} ${commaSpan.id} ${$button.id}`
     )
     $button.addEventListener('click', this.onClick.bind(this))
+    $button.addEventListener('dragover', (event) => {
+      // prevent default to allow drop
+      event.preventDefault()
+    })
 
     // Assemble these all together
     this.$root.insertAdjacentElement('afterbegin', $button)
@@ -180,6 +185,10 @@ export class FileUpload extends ConfigurableComponent {
     // to do anything more than hiding the dropzone on drop.
     this.$input.addEventListener('drop', this.onDrop.bind(this))
 
+    // if there is no CSS and input is hidden
+    // button will need to handle drop event
+    this.$button.addEventListener('drop', this.onDrop.bind(this))
+
     // While user is dragging, it gets a little more complex because of Safari.
     // Safari doesn't fill `relatedTarget` on `dragleave` (nor `dragenter`).
     // This means we can't use `relatedTarget` to:
@@ -270,20 +279,23 @@ export class FileUpload extends ConfigurableComponent {
 
   /**
    * Handles user dropping on the component
+   *
+   * @param {DragEvent} event - The `dragenter` event
    */
-  onDrop() {
-    this.hideDraggingState()
-
-    // The change event updating the text will only happen after the `drop`
-    // Because this listener is registered after `onChange`, it'll run after
-    // the status is updated and can pick it up for announcement
-    this.$input.addEventListener(
-      'change',
-      () => {
-        this.$announcements.innerText = this.$status.innerText
-      },
-      { once: true }
-    )
+  onDrop(event) {
+    event.preventDefault()
+
+    if (event.dataTransfer && isContainingFiles(event.dataTransfer)) {
+      this.$input.files = event.dataTransfer.files
+
+      // Dispatch a `change` event so external code that would rely on the `<input>`
+      // dispatching an event when files are dropped still work.
+      // Use a `CustomEvent` so our events are distinguishable from browser's native events
+      this.$input.dispatchEvent(new CustomEvent('change'))
+
+      this.$announcements.innerText = this.$status.innerText
+      this.hideDraggingState()
+    }
   }
 
   /**

From a44289ab0d22a7b88920ece9e25fa3d64532d148 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Tue, 11 Feb 2025 11:21:03 +0000
Subject: [PATCH 66/77] Remove `--enhanced` & `--dragging` input classes

- Remove `--enhanced` and `-dragging` classes for `govuk-file-upload`
- Remove JS in File Upload  that adds the removed classes on initialisation
and drag
- Update input selector in File Upload test
---
 .../govuk/components/file-upload/_index.scss  | 18 ---------------
 .../components/file-upload/file-upload.mjs    | 12 ----------
 .../file-upload/file-upload.puppeteer.test.js | 22 +++++++++----------
 3 files changed, 10 insertions(+), 42 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index db156ac3aa..991d04932a 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -62,24 +62,6 @@
     cursor: not-allowed;
   }
 
-  .govuk-file-upload--enhanced {
-    position: absolute;
-    // Make the native control take up the entire space of the element, but
-    // invisible and behind the other elements until we need it
-    z-index: -1;
-    top: 0;
-    left: 0;
-    width: 100%;
-    height: 100%;
-    margin: 0;
-    padding: 0;
-    opacity: 0;
-  }
-
-  .govuk-file-upload--dragging {
-    z-index: 1;
-  }
-
   .govuk-file-upload-button__pseudo-button {
     width: auto;
     margin-right: govuk-spacing(2);
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index d319470950..1610b162a2 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -155,8 +155,6 @@ export class FileUpload extends ConfigurableComponent {
 
     this.$input.setAttribute('tabindex', '-1')
     this.$input.setAttribute('aria-hidden', 'true')
-    this.$input.classList.remove('govuk-file-upload')
-    this.$input.classList.add('govuk-file-upload--enhanced')
 
     // Make all these new variables available to the module
     this.$button = $button
@@ -177,14 +175,6 @@ export class FileUpload extends ConfigurableComponent {
     this.$announcements.setAttribute('aria-live', 'assertive')
     this.$root.insertAdjacentElement('afterend', this.$announcements)
 
-    // The easy bit, when dropping hide the dropzone
-    //
-    // Note: the component relies on the native behaviour to get the files
-    // being dragged set as value of the `<input>`. This allows a `change`
-    // event to be automatically fired from the element and saves us from having
-    // to do anything more than hiding the dropzone on drop.
-    this.$input.addEventListener('drop', this.onDrop.bind(this))
-
     // if there is no CSS and input is hidden
     // button will need to handle drop event
     this.$button.addEventListener('drop', this.onDrop.bind(this))
@@ -266,7 +256,6 @@ export class FileUpload extends ConfigurableComponent {
    */
   showDraggingState() {
     this.$button.classList.add('govuk-file-upload-button--dragging')
-    this.$input.classList.add('govuk-file-upload--dragging')
   }
 
   /**
@@ -274,7 +263,6 @@ export class FileUpload extends ConfigurableComponent {
    */
   hideDraggingState() {
     this.$button.classList.remove('govuk-file-upload-button--dragging')
-    this.$input.classList.remove('govuk-file-upload--dragging')
   }
 
   /**
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 07f1ed7285..efca2b9356 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -7,7 +7,6 @@ const {
 const { getExamples } = require('@govuk-frontend/lib/components')
 
 const inputSelector = '.govuk-file-upload'
-const enhancedInputSelector = '.govuk-file-upload--enhanced'
 const wrapperSelector = '.govuk-drop-zone'
 const buttonSelector = '.govuk-file-upload-button'
 const statusSelector = '.govuk-file-upload-button__status'
@@ -67,7 +66,7 @@ describe('/components/file-upload', () => {
 
           it('moves the file input inside of the wrapper element', async () => {
             const inputElementParent = await page.$eval(
-              enhancedInputSelector,
+              inputSelector,
               (el) => el.parentNode
             )
             const wrapperElement = await page.$eval(wrapperSelector, (el) => el)
@@ -78,9 +77,8 @@ describe('/components/file-upload', () => {
 
         describe('file input', () => {
           it('sets tabindex to -1', async () => {
-            const inputElementTabindex = await page.$eval(
-              enhancedInputSelector,
-              (el) => el.getAttribute('tabindex')
+            const inputElementTabindex = await page.$eval(inputSelector, (el) =>
+              el.getAttribute('tabindex')
             )
 
             expect(inputElementTabindex).toBe('-1')
@@ -134,7 +132,7 @@ describe('/components/file-upload', () => {
             await fileChooser.accept([testFilename])
 
             const inputElementValue = await page.$eval(
-              enhancedInputSelector,
+              inputSelector,
               (el) =>
                 // @ts-ignore
                 el.value
@@ -162,14 +160,14 @@ describe('/components/file-upload', () => {
 
         it('updates the file input value', async () => {
           const inputElementValue = await page.$eval(
-            enhancedInputSelector,
+            inputSelector,
             (el) =>
               // @ts-ignore
               el.value
           )
 
           const inputElementFiles = await page.$eval(
-            enhancedInputSelector,
+            inputSelector,
             (el) =>
               // @ts-ignore
               el.files
@@ -211,14 +209,14 @@ describe('/components/file-upload', () => {
 
         it('updates the file input value', async () => {
           const inputElementValue = await page.$eval(
-            enhancedInputSelector,
+            inputSelector,
             (el) =>
               // @ts-ignore
               el.value
           )
 
           const inputElementFiles = await page.$eval(
-            enhancedInputSelector,
+            inputSelector,
             (el) =>
               // @ts-ignore
               el.files
@@ -472,7 +470,7 @@ describe('/components/file-upload', () => {
         it('disables the button if the input is disabled programatically', async () => {
           await render(page, 'file-upload', examples.enhanced)
 
-          await page.$eval(enhancedInputSelector, (el) =>
+          await page.$eval(inputSelector, (el) =>
             el.setAttribute('disabled', '')
           )
 
@@ -496,7 +494,7 @@ describe('/components/file-upload', () => {
             el.hasAttribute('disabled')
           )
 
-          await page.$eval(enhancedInputSelector, (el) =>
+          await page.$eval(inputSelector, (el) =>
             el.removeAttribute('disabled')
           )
 

From 1f1559fdc69ab117b1486e7996e5eea5fa3b7bcd Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Tue, 11 Feb 2025 15:36:07 +0000
Subject: [PATCH 67/77] Add back black border to File Upload dropzone

---
 .../src/govuk/components/file-upload/_index.scss              | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 991d04932a..68cca72eae 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -178,6 +178,8 @@
   }
 
   .govuk-file-upload-button--dragging {
+    border-style: solid;
+
     // extra specificity to apply when
     // empty
     &.govuk-file-upload-button {
@@ -189,7 +191,7 @@
     }
 
     &:not(:disabled) {
-      border-color: govuk-shade(govuk-colour("mid-grey"), 20%);
+      border-color: govuk-colour("black");
 
       .govuk-file-upload-button__pseudo-button {
         background-color: govuk-shade(govuk-colour("light-grey"), 10%);

From b6007f649a432f4257d542b8b1ead51a79a7402f Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Wed, 12 Feb 2025 14:55:38 +0000
Subject: [PATCH 68/77] No `--dragging` if File Upload is disabled

---
 .../govuk/components/file-upload/_index.scss    | 13 +++++--------
 .../components/file-upload/file-upload.mjs      |  2 ++
 .../file-upload/file-upload.puppeteer.test.js   | 17 +++++++++++++++++
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index 68cca72eae..b4d02937be 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -179,6 +179,7 @@
 
   .govuk-file-upload-button--dragging {
     border-style: solid;
+    border-color: govuk-colour("black");
 
     // extra specificity to apply when
     // empty
@@ -190,17 +191,13 @@
       background-color: govuk-colour("light-grey");
     }
 
-    &:not(:disabled) {
-      border-color: govuk-colour("black");
-
-      .govuk-file-upload-button__pseudo-button {
-        background-color: govuk-shade(govuk-colour("light-grey"), 10%);
-      }
-    }
-
     &.govuk-file-upload-button--empty:not(:disabled) .govuk-file-upload-button__status,
     &.govuk-file-upload-button--empty .govuk-file-upload-button__pseudo-button {
       background-color: govuk-colour("white");
     }
+
+    .govuk-file-upload-button__pseudo-button {
+      background-color: govuk-shade(govuk-colour("light-grey"), 10%);
+    }
   }
 }
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 1610b162a2..d8447ac17e 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -221,6 +221,8 @@ export class FileUpload extends ConfigurableComponent {
    * @param {DragEvent} event - The `dragenter` event
    */
   updateDropzoneVisibility(event) {
+    if (this.$button.disabled) return
+
     // DOM interfaces only type `event.target` as `EventTarget`
     // so we first need to make sure it's a `Node`
     if (event.target instanceof Node) {
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index efca2b9356..32a5304091 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -349,6 +349,23 @@ describe('/components/file-upload', () => {
             $announcements.evaluate((e) => e.textContent)
           ).resolves.toBe('Left drop zone')
         })
+
+        it('does not appear if button disabled', async () => {
+          await render(page, 'file-upload', examples.enhanced, {
+            beforeInitialisation() {
+              document
+                .querySelector('[type="file"]')
+                .setAttribute('disabled', '')
+            }
+          })
+
+          await page.mouse.dragEnter(
+            { x: wrapperBoundingBox.x + 1, y: wrapperBoundingBox.y + 1 },
+            structuredClone(dragData)
+          )
+
+          await expect(page.$(selectorDropzoneHidden)).resolves.toBeTruthy()
+        })
       })
 
       describe('accessible name', () => {

From 7e06c98de1e532b200ba24aae0684c34b1591622 Mon Sep 17 00:00:00 2001
From: Patrick Cartlidge <patrickcartlidge@gmail.com>
Date: Wed, 12 Feb 2025 15:17:09 +0000
Subject: [PATCH 69/77] Prevent dropzone announcement when button disabled

---
 .../src/govuk/components/file-upload/file-upload.mjs       | 2 +-
 .../components/file-upload/file-upload.puppeteer.test.js   | 7 +++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index d8447ac17e..2b071e4b43 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -206,7 +206,7 @@ export class FileUpload extends ConfigurableComponent {
     })
 
     document.addEventListener('dragleave', () => {
-      if (!this.enteredAnotherElement) {
+      if (!this.enteredAnotherElement && !this.$button.disabled) {
         this.hideDraggingState()
         this.$announcements.innerText = this.i18n.t('leftDropZone')
       }
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 32a5304091..68b1564a7a 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -364,7 +364,14 @@ describe('/components/file-upload', () => {
             structuredClone(dragData)
           )
 
+          const disabledAnnouncement = await page.$(
+            '.govuk-file-upload-announcements'
+          )
+
           await expect(page.$(selectorDropzoneHidden)).resolves.toBeTruthy()
+          await expect(
+            disabledAnnouncement.evaluate((e) => e.textContent)
+          ).resolves.toBe('')
         })
       })
 

From 9fcde09a00cbbd48a63cbf7147b5cf3a2e28e4a2 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 20 Feb 2025 11:55:15 +0000
Subject: [PATCH 70/77] [SPIKE] Add status announcement after file change

Adds an automatic announcement of the status after users pick a file.

This should reassure JAWS users that their selection has been taken into account,
as JAWS announces the accessible name of the button before the file picker was open,
sometimes without re-announcing afterwards the accessible name once a file is picked.
---
 .../components/file-upload/file-upload.mjs    |  2 +-
 .../file-upload/file-upload.puppeteer.test.js | 28 +++++++++++++------
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 2b071e4b43..ea8e32c8b6 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -106,6 +106,7 @@ export class FileUpload extends ConfigurableComponent {
     // Create status element that shows what/how many files are selected
     const $status = document.createElement('span')
     $status.className = 'govuk-body govuk-file-upload-button__status'
+    $status.setAttribute('aria-live', 'polite')
     $status.innerText = this.i18n.t('noFileChosen')
 
     $button.appendChild($status)
@@ -283,7 +284,6 @@ export class FileUpload extends ConfigurableComponent {
       // Use a `CustomEvent` so our events are distinguishable from browser's native events
       this.$input.dispatchEvent(new CustomEvent('change'))
 
-      this.$announcements.innerText = this.$status.innerText
       this.hideDraggingState()
     }
   }
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 68b1564a7a..a2f1f0a679 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -102,13 +102,15 @@ describe('/components/file-upload', () => {
               (el) => el.innerHTML.trim()
             )
 
-            const statusElementText = await page.$eval(
-              `${buttonSelector} ${statusSelector}`,
-              (el) => el.innerHTML.trim()
-            )
+            const [statusElementText, statusElementAriaLiveAttribute] =
+              await page.$eval(`${buttonSelector} ${statusSelector}`, (el) => [
+                el.innerHTML.trim(),
+                el.getAttribute('aria-live')
+              ])
 
             expect(buttonElementText).toBe('Choose file')
             expect(statusElementText).toBe('No file chosen')
+            expect(statusElementAriaLiveAttribute).toBe('polite')
           })
         })
       })
@@ -270,9 +272,17 @@ describe('/components/file-upload', () => {
 
         it('is not shown by default', async () => {
           await expect(page.$(selectorDropzoneHidden)).resolves.toBeTruthy()
-          await expect(
-            $announcements.evaluate((e) => e.textContent)
-          ).resolves.toBe('')
+
+          const [announcementsText, announcementsAriaLive] =
+            await $announcements.evaluate((e) => [
+              e.textContent,
+              e.getAttribute('aria-live')
+            ])
+
+          expect(announcementsText).toBe('')
+          // As the announcement is feedback while user is dragging,
+          // best to announce it as soon as the user enters the zone
+          expect(announcementsAriaLive).toBe('assertive')
         })
 
         it('gets shown when entering the field', async () => {
@@ -303,11 +313,11 @@ describe('/components/file-upload', () => {
           )
 
           await expect(page.$(selectorDropzoneHidden)).resolves.toBeTruthy()
-          // The presence of 'Left drop zone' confirms we handled the leaving of the drop zone
+          // The presence of 'Entered drop zone' confirms we entered the drop zone
           // rather than being in the initial state
           await expect(
             $announcements.evaluate((e) => e.textContent)
-          ).resolves.toBe('file-upload.puppeteer.test.js')
+          ).resolves.toBe('Entered drop zone')
         })
 
         it('gets hidden when dragging a file and leaving the field', async () => {

From 9bcba8fa3ed7880f54db6dffd0c454492f919153 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 25 Feb 2025 17:03:28 +0000
Subject: [PATCH 71/77] Add current state of the CHANGELOG entry

Having it in the PR that brings in the code will help when browsing back the project's history
---
 CHANGELOG.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c195e897bb..ae23398875 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,54 @@ For advice on how to use these release notes see [our guidance on staying up to
 
 ### New features
 
+#### Use our improved File upload component
+
+We've added a [JavaScript enhancement to the File upload component](https://design-system.service.gov.uk/components/file-upload/#using-the-improved-file-upload-component) which:
+
+- makes the component easier to use for drag and drop
+- allows the text of the component to be translated
+- fixes accessibility issues for users of Dragon, a speech recognition software
+
+This improvement is opt-in, as it's a substantial visual change which risks shifting other content on the page.
+
+To enable this improvement for your users, you'll first need to update the markup of your File upload component:
+
+- if you use our Nunjucks macro, using the new `javascript` option of `govukFileUpload`
+
+  ```njk
+  {{ govukFileUpload({
+  id: "file-upload",
+  name: "photo",
+  label: {
+  	text: "Upload your photo"
+  },
+  javascript: true
+  }) }}
+  ```
+
+- if you're using HTML, wrapping the `<input type="file">` of the File upload markup in a `<div class="govuk-drop-zone" data-module="govuk-file-upload">`
+
+  ```html
+  <div class="govuk-form-group">
+  <label class="govuk-label" for="file-upload-1">
+  	Upload your photo
+  </label>
+  <div class="govuk-drop-zone" data-module="govuk-file-upload">
+  	<input class="govuk-file-upload" id="file-upload" name="photo" type="file">
+  </div>
+  </div>
+  ```
+
+If you're importing components individually in your JavaScript, which we recommend for better performance, you'll then need to import and initialise the new `FileUpload` component.
+
+```js
+import {FileUpload} from 'govuk-frontend'
+
+createAll(FileUpload)
+```
+
+This change was introduced in [pull request #5305: Add progressively enhanced File Upload component](https://github.com/alphagov/govuk-frontend/pull/5305)
+
 #### Form control components now have default `id` attributes
 
 If you're using the included Nunjucks macros, the Text input, Textarea, Password input, Character count, File upload, and Select components now automatically use the value of the `name` parameter for the `id` parameter.

From a8b5d49e469fcc2efd4f60287bdb32d3a1177faf Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 25 Feb 2025 17:56:29 +0000
Subject: [PATCH 72/77] Ensure translations are consistent and complete for
 examples

---
 .../src/views/examples/translated/index.njk           | 11 +++++++----
 .../src/govuk/components/file-upload/file-upload.yaml |  3 ++-
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/packages/govuk-frontend-review/src/views/examples/translated/index.njk b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
index 6e7e663b8c..6e22722075 100644
--- a/packages/govuk-frontend-review/src/views/examples/translated/index.njk
+++ b/packages/govuk-frontend-review/src/views/examples/translated/index.njk
@@ -348,11 +348,14 @@
     },
     javascript: true,
     chooseFilesButtonText: "Dewiswch ffeil",
-    noFileChosenText: "Dim ffeiliau wedi'u dewis",
+    dropInstructionText: "neu ollwng ffeil",
+    noFileChosenText: "Dim ffeil wedi'i dewis",
     multipleFilesChosenText: {
-        other: "%{count} ffeil wedi'u dewis",
-        one: "%{count} ffeil wedi'i dewis"
-    }
+      other: "%{count} ffeil wedi'u dewis",
+      one: "%{count} ffeil wedi'i dewis"
+    },
+    enteredDropZoneText: "Wedi mynd i mewn i'r parth gollwng",
+    leftDropZoneText: "Parth gollwng i'r chwith"
   }) }}
 
   {{ govukFooter({
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
index 2dc9ce33b8..9647a16a5f 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.yaml
@@ -322,7 +322,8 @@ examples:
         text: Llwythwch ffeil i fyny
       multiple: true
       chooseFilesButtonText: Dewiswch ffeil
-      noFileChosenText: Dim ffeiliau wedi'u dewis
+      dropInstructionText: neu ollwng ffeil
+      noFileChosenText: Dim ffeil wedi'i dewis
       multipleFilesChosenText:
         other: "%{count} ffeil wedi'u dewis"
         one: "%{count} ffeil wedi'i dewis"

From 74129db525f0f550125cd7003bf2f0ae8724a422 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 25 Feb 2025 18:05:59 +0000
Subject: [PATCH 73/77] Ensure `<label>` targets the visible button with its
 `for` attribute.

This lets the Error Summary scroll to the correct position when the field
has an error.

Thanks to our use of `aria-labelledby` the accessible name of the button
hasn't change by linking the label to it.
---
 .../src/govuk/components/file-upload/file-upload.mjs     | 1 -
 .../components/file-upload/file-upload.puppeteer.test.js | 9 +++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index ea8e32c8b6..0fcafa8bdc 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -77,7 +77,6 @@ export class FileUpload extends ConfigurableComponent {
     })
 
     const $label = this.findLabel()
-    $label.setAttribute('for', `${this.id}-input`)
     // Add an ID to the label if it doesn't have one already
     // so it can be referenced by `aria-labelledby`
     if (!$label.id) {
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index a2f1f0a679..00ad4bfe92 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -85,6 +85,15 @@ describe('/components/file-upload', () => {
           })
         })
 
+        describe('label element', () => {
+          it('targets the button in its `for` attribute', async () => {
+            const buttonId = await page.$eval(buttonSelector, (el) => el.id)
+            const label = await page.$(`[for="${buttonId}"]`)
+
+            expect(label).not.toBeNull()
+          })
+        })
+
         describe('choose file button', () => {
           it('renders the button element', async () => {
             const buttonElement = await page.$eval(buttonSelector, (el) => el)

From 753ccf06309f70a56442dd63801244ace01a0d85 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 25 Feb 2025 18:14:28 +0000
Subject: [PATCH 74/77] Use `@import` to import types

---
 .../components/file-upload/accessibility.puppeteer.test.mjs     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/accessibility.puppeteer.test.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/accessibility.puppeteer.test.mjs
index 7df8675d4d..1a410b6dd5 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/accessibility.puppeteer.test.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/accessibility.puppeteer.test.mjs
@@ -39,5 +39,5 @@ describe('/components/file-upload', () => {
 })
 
 /**
- * @typedef {import('@govuk-frontend/lib/components').MacroOptions} MacroOptions
+ * @import {MacroOptions} from '@govuk-frontend/lib/components'
  */

From b5cf8e21a4d65fd2e7e46d9f191b9fe5e5e7b41c Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 25 Feb 2025 18:21:28 +0000
Subject: [PATCH 75/77] Make error messages consistent with the other
 components

---
 .../components/file-upload/file-upload.mjs    | 23 ++++++------
 .../file-upload/file-upload.puppeteer.test.js | 37 ++++++++++++++++++-
 2 files changed, 46 insertions(+), 14 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 0fcafa8bdc..7e02d6fdf5 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -43,19 +43,17 @@ export class FileUpload extends ConfigurableComponent {
     const $input = this.$root.querySelector('input')
 
     if ($input === null) {
-      throw new ElementError(
-        formatErrorMessage(
-          FileUpload,
-          'File upload wrapper must have `input` element of type `file`'
-        )
-      )
+      throw new ElementError({
+        component: FileUpload,
+        identifier: 'File inputs (`<input type="file">`)'
+      })
     }
 
     if ($input.type !== 'file') {
       throw new ElementError(
         formatErrorMessage(
           FileUpload,
-          'Form field must be an input of type `file`.'
+          'File input (`<input type="file">`) attribute (`type`) is not `file`'
         )
       )
     }
@@ -63,10 +61,11 @@ export class FileUpload extends ConfigurableComponent {
     this.$input = /** @type {HTMLFileInputElement} */ ($input)
     this.$input.setAttribute('hidden', 'true')
 
-    if (!this.$input.id.length) {
-      throw new ElementError(
-        formatErrorMessage(FileUpload, 'Form field must specify an `id`.')
-      )
+    if (!this.$input.id) {
+      throw new ElementError({
+        component: FileUpload,
+        identifier: 'File input (`<input type="file">`) attribute (`id`)'
+      })
     }
 
     this.id = this.$input.id
@@ -328,7 +327,7 @@ export class FileUpload extends ConfigurableComponent {
     if (!$label) {
       throw new ElementError({
         component: FileUpload,
-        identifier: 'No label'
+        identifier: `Field label (\`<label for=${this.$input.id}>\`)`
       })
     }
 
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 00ad4bfe92..92de3358bf 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -649,6 +649,38 @@ describe('/components/file-upload', () => {
         })
 
         describe('missing or misconfigured elements', () => {
+          it('throws if the input is missing', async () => {
+            await expect(
+              render(page, 'file-upload', examples.enhanced, {
+                beforeInitialisation() {
+                  document.querySelector('[type="file"]').remove()
+                }
+              })
+            ).rejects.toMatchObject({
+              cause: {
+                name: 'ElementError',
+                message:
+                  'govuk-file-upload: File inputs (`<input type="file">`) not found'
+              }
+            })
+          })
+
+          it('throws if the input has no `id` attribute', async () => {
+            await expect(
+              render(page, 'file-upload', examples.enhanced, {
+                beforeInitialisation() {
+                  document.querySelector('[type="file"]').removeAttribute('id')
+                }
+              })
+            ).rejects.toMatchObject({
+              cause: {
+                name: 'ElementError',
+                message:
+                  'govuk-file-upload: File input (`<input type="file">`) attribute (`id`) not found'
+              }
+            })
+          })
+
           it('throws if the input type is not "file"', async () => {
             await expect(
               render(page, 'file-upload', examples.enhanced, {
@@ -662,7 +694,7 @@ describe('/components/file-upload', () => {
               cause: {
                 name: 'ElementError',
                 message:
-                  'govuk-file-upload: Form field must be an input of type `file`.'
+                  'govuk-file-upload: File input (`<input type="file">`) attribute (`type`) is not `file`'
               }
             })
           })
@@ -677,7 +709,8 @@ describe('/components/file-upload', () => {
             ).rejects.toMatchObject({
               cause: {
                 name: 'ElementError',
-                message: 'govuk-file-upload: No label not found'
+                message:
+                  'govuk-file-upload: Field label (`<label for=file-upload-1>`) not found'
               }
             })
           })

From d509f761e97d6c6507dae7112480858e29e0562d Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Tue, 25 Feb 2025 18:38:28 +0000
Subject: [PATCH 76/77] Refactor how disabled class is set on drop zone

The toggle method from DOMTokenList makes it more succint
---
 .../components/file-upload/file-upload.mjs    |  9 +++----
 .../file-upload/file-upload.puppeteer.test.js | 25 ++++++++++++-------
 2 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
index 7e02d6fdf5..6e1a8f9ac3 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.mjs
@@ -367,11 +367,10 @@ export class FileUpload extends ConfigurableComponent {
   updateDisabledState() {
     this.$button.disabled = this.$input.disabled
 
-    if (this.$button.disabled) {
-      this.$root.classList.add('govuk-drop-zone--disabled')
-    } else {
-      this.$root.classList.remove('govuk-drop-zone--disabled')
-    }
+    this.$root.classList.toggle(
+      'govuk-drop-zone--disabled',
+      this.$button.disabled
+    )
   }
 
   /**
diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
index 92de3358bf..f16abeb522 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/file-upload.puppeteer.test.js
@@ -506,11 +506,15 @@ describe('/components/file-upload', () => {
           const buttonDisabled = await page.$eval(buttonSelector, (el) =>
             el.hasAttribute('disabled')
           )
+          const dropZoneDisabled = await page.$eval(wrapperSelector, (el) =>
+            el.classList.contains('govuk-drop-zone--disabled')
+          )
 
           expect(buttonDisabled).toBeTruthy()
+          expect(dropZoneDisabled).toBeTruthy()
         })
 
-        it('disables the button if the input is disabled programatically', async () => {
+        it('disables the button if the input is disabled programmatically', async () => {
           await render(page, 'file-upload', examples.enhanced)
 
           await page.$eval(inputSelector, (el) =>
@@ -520,11 +524,15 @@ describe('/components/file-upload', () => {
           const buttonDisabledAfter = await page.$eval(buttonSelector, (el) =>
             el.hasAttribute('disabled')
           )
+          const dropZoneDisabled = await page.$eval(wrapperSelector, (el) =>
+            el.classList.contains('govuk-drop-zone--disabled')
+          )
 
           expect(buttonDisabledAfter).toBeTruthy()
+          expect(dropZoneDisabled).toBeTruthy()
         })
 
-        it('enables the button if the input is enabled programatically', async () => {
+        it('enables the button if the input is enabled programmatically', async () => {
           await render(page, 'file-upload', examples.enhanced, {
             beforeInitialisation() {
               document
@@ -533,20 +541,19 @@ describe('/components/file-upload', () => {
             }
           })
 
-          const buttonDisabledBefore = await page.$eval(buttonSelector, (el) =>
-            el.hasAttribute('disabled')
-          )
-
           await page.$eval(inputSelector, (el) =>
             el.removeAttribute('disabled')
           )
 
-          const buttonDisabledAfter = await page.$eval(buttonSelector, (el) =>
+          const buttonDisabled = await page.$eval(buttonSelector, (el) =>
             el.hasAttribute('disabled')
           )
+          const dropZoneDisabled = await page.$eval(wrapperSelector, (el) =>
+            el.classList.contains('govuk-drop-zone--disabled')
+          )
 
-          expect(buttonDisabledBefore).toBeTruthy()
-          expect(buttonDisabledAfter).toBeFalsy()
+          expect(buttonDisabled).toBeFalsy()
+          expect(dropZoneDisabled).toBeFalsy()
         })
       })
 

From 2795465ab5a7071d6a93ce5678928dfc062903d0 Mon Sep 17 00:00:00 2001
From: Romaric Pascal <romaric.pascal@digital.cabinet-office.gov.uk>
Date: Thu, 27 Feb 2025 14:27:03 +0000
Subject: [PATCH 77/77] Fix disabled File upload hover state

Avoid visual changes when hovering the `<label>`, which triggers the associated field's `:hover` state.

Moves the button's disabled state to the end of the component CSS so it can override any of the other states,
and uses variables to reset the colour to the empty state colours (as a file input cannot be pre-filled).
---
 .../govuk/components/file-upload/_index.scss  | 29 ++++++++++++++-----
 1 file changed, 21 insertions(+), 8 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
index b4d02937be..5f0dd039c8 100644
--- a/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/file-upload/_index.scss
@@ -5,6 +5,9 @@
 @include govuk-exports("govuk/component/file-upload") {
   $file-upload-border-width: 2px;
   $component-padding: govuk-spacing(1);
+  $empty-button-background-colour: govuk-colour("white");
+  $empty-pseudo-button-background-colour: govuk-colour("light-grey");
+  $empty-status-background-colour: govuk-tint(govuk-colour("blue"), 70%);
 
   .govuk-file-upload {
     @include govuk-font($size: 19);
@@ -146,24 +149,19 @@
         box-shadow: inset 0 0 0 1px $govuk-focus-colour;
       }
     }
-
-    &:disabled {
-      pointer-events: none;
-      opacity: 0.5;
-    }
   }
 
   .govuk-file-upload-button--empty {
     border-style: dashed;
-    background-color: govuk-colour("white");
+    background-color: $empty-button-background-colour;
 
     .govuk-file-upload-button__pseudo-button {
-      background-color: govuk-colour("light-grey");
+      background-color: $empty-pseudo-button-background-colour;
     }
 
     .govuk-file-upload-button__status {
       color: govuk-shade(govuk-colour("blue"), 60%);
-      background-color: govuk-tint(govuk-colour("blue"), 70%);
+      background-color: $empty-status-background-colour;
     }
 
     &:hover,
@@ -200,4 +198,19 @@
       background-color: govuk-shade(govuk-colour("light-grey"), 10%);
     }
   }
+
+  .govuk-file-upload-button:disabled {
+    pointer-events: none;
+    opacity: 0.5;
+
+    background-color: $empty-button-background-colour;
+
+    .govuk-file-upload-button__pseudo-button {
+      background-color: $empty-pseudo-button-background-colour;
+    }
+
+    .govuk-file-upload-button__status {
+      background-color: $empty-status-background-colour;
+    }
+  }
 }