@defra/forms-engine-plugin 0.0.4 → 0.0.6

package/src/client/javascripts/file-upload.js

@@ -0,0 +1,386 @@
+export const MAX_POLLING_DURATION = 300 // 5 minutes
+
+/**
+ * Creates or updates status announcer for screen readers
+ * @param {HTMLElement | null} form - The form element
+ * @param {HTMLElement | null} fileCountP - The file count paragraph element
+ * @returns {HTMLElement} The status announcer element
+ */
+function createOrUpdateStatusAnnouncer(form, fileCountP) {
+  let statusAnnouncer = form?.querySelector('#statusInformation')
+
+  if (!statusAnnouncer) {
+    statusAnnouncer = document.createElement('div')
+    statusAnnouncer.id = 'statusInformation'
+    statusAnnouncer.className = 'govuk-visually-hidden'
+    statusAnnouncer.setAttribute('aria-live', 'polite')
+
+    // multiple fallbacks to ensure the status announcer is always added to the DOM
+    // this helps with cross-browser compatibility and unexpected DOM structures encountered during QA
+    try {
+      addStatusAnnouncerToDOM(
+        asHTMLElement(form),
+        asHTMLElement(fileCountP),
+        asHTMLElement(statusAnnouncer)
+      )
+    } catch {
+      try {
+        form?.appendChild(statusAnnouncer)
+      } catch {
+        document.body.appendChild(statusAnnouncer)
+      }
+    }
+  }
+
+  return /** @type {HTMLElement} */ (statusAnnouncer)
+}
+
+/**
+ * Helper function to add the status announcer to the DOM
+ * @param {HTMLElement} form - The form element
+ * @param {HTMLElement | null} fileCountP - The file count paragraph element
+ * @param {HTMLElement} statusAnnouncer - The status announcer element to add
+ */
+function addStatusAnnouncerToDOM(form, fileCountP, statusAnnouncer) {
+  if (fileCountP?.nextSibling && fileCountP.parentNode === form) {
+    form.insertBefore(statusAnnouncer, fileCountP.nextSibling)
+    return
+  }
+
+  const parentElement = fileCountP?.parentNode ?? form
+  parentElement.appendChild(statusAnnouncer)
+}
+
+/**
+ * Finds an existing summary list or creates a new one
+ * @param {HTMLFormElement} form - The form element
+ * @param {HTMLElement} fileCountP - The file count paragraph element
+ * @returns {HTMLElement} The summary list element
+ */
+function findOrCreateSummaryList(form, fileCountP) {
+  let summaryList = form.querySelector('dl.govuk-summary-list')
+
+  if (!summaryList) {
+    summaryList = document.createElement('dl')
+    summaryList.className = 'govuk-summary-list govuk-summary-list--long-key'
+
+    const continueButton = form.querySelector('.govuk-button')
+
+    if (continueButton) {
+      form.insertBefore(summaryList, continueButton)
+    } else {
+      form.insertBefore(summaryList, fileCountP.nextSibling)
+    }
+  }
+
+  return /** @type {HTMLElement} */ (summaryList)
+}
+
+/**
+ * Creates a file row element for the summary list
+ * @param {File | null} selectedFile - The selected file
+ * @param {string} statusText - The status to display
+ * @returns {HTMLElement} The created row element
+ */
+function createFileRow(selectedFile, statusText) {
+  const row = document.createElement('div')
+  row.className = 'govuk-summary-list__row'
+  row.setAttribute('data-filename', selectedFile?.name ?? '')
+  row.innerHTML = `
+      <dt class="govuk-summary-list__key">
+        ${selectedFile?.name ?? ''}
+      </dt>
+      <dd class="govuk-summary-list__value">
+        <strong class="govuk-tag govuk-tag--yellow">${statusText}</strong>
+      </dd>
+      <dd class="govuk-summary-list__actions">
+      </dd>
+    `
+  return row
+}
+
+/**
+ * Renders or updates the file summary box for the selected file
+ * @param {File | null} selectedFile - The selected file
+ * @param {string} statusText - The status to display
+ * @param {HTMLElement} form - The form element
+ */
+function renderSummary(selectedFile, statusText, form) {
+  const container = document.getElementById('uploadedFilesContainer')
+  const uploadForm = container ? container.closest('form') : null
+
+  if (!uploadForm || !(uploadForm instanceof HTMLFormElement)) {
+    return
+  }
+
+  const fileCountP = uploadForm.querySelector('p.govuk-body')
+
+  if (!fileCountP) {
+    return
+  }
+
+  const statusAnnouncer = createOrUpdateStatusAnnouncer(
+    /** @type {HTMLElement} */ (uploadForm),
+    /** @type {HTMLElement | null} */ (fileCountP)
+  )
+
+  const fileInput = form.querySelector('input[type="file"]')
+
+  if (fileInput) {
+    fileInput.setAttribute('aria-describedby', 'statusInformation')
+  }
+
+  const summaryList = findOrCreateSummaryList(
+    /** @type {HTMLFormElement} */ (uploadForm),
+    /** @type {HTMLElement} */ (fileCountP)
+  )
+
+  const existingRow = document.querySelector(
+    `[data-filename="${selectedFile?.name}"]`
+  )
+
+  if (existingRow) {
+    existingRow.remove()
+  }
+
+  const row = createFileRow(selectedFile, statusText)
+  summaryList.insertBefore(row, summaryList.firstChild)
+  statusAnnouncer.textContent = `${selectedFile?.name ?? ''} ${statusText}`
+}
+
+/**
+ * Shows an error message using the GOV.UK error summary component
+ * @param {string} message - The error message to display
+ * @param {HTMLElement | null} errorSummary - The error summary container
+ * @param {HTMLInputElement} fileInput - The file input element
+ * @returns {void}
+ */
+function showError(message, errorSummary, fileInput) {
+  if (errorSummary) {
+    errorSummary.innerHTML = `
+        <div class="govuk-error-summary" data-module="govuk-error-summary">
+          <div role="alert">
+            <h2 class="govuk-error-summary__title" id="error-summary-title">
+              There is a problem
+            </h2>
+            <div class="govuk-error-summary__body">
+              <ul class="govuk-list govuk-error-summary__list">
+                <li>
+                  <a href="#file-upload">${message}</a>
+                </li>
+              </ul>
+            </div>
+          </div>
+        </div>
+      `
+    fileInput.setAttribute('aria-describedby', 'error-summary-title')
+  }
+}
+
+/**
+ * Helper to safely convert an Element to HTMLElement
+ * @param {Element | null} element - The element to convert
+ */
+function asHTMLElement(element) {
+  return /** @type {HTMLElement} */ (element)
+}
+
+function reloadPage() {
+  window.history.replaceState(null, '', window.location.href)
+  window.location.href = window.location.pathname
+}
+
+/**
+ * Polls the upload status endpoint until the file is ready or timeout occurs
+ * @param {string} uploadId - The upload ID to check
+ */
+function pollUploadStatus(uploadId) {
+  let attempts = 0
+  const interval = setInterval(() => {
+    attempts++
+
+    if (attempts >= MAX_POLLING_DURATION) {
+      clearInterval(interval)
+      reloadPage()
+      return
+    }
+
+    fetch(`/upload-status/${uploadId}`, {
+      headers: {
+        Accept: 'application/json'
+      }
+    })
+      .then((response) => {
+        if (!response.ok) {
+          throw new Error('Network response was not ok')
+        }
+        return response.json()
+      })
+      .then((data) => {
+        if (data.uploadStatus === 'ready') {
+          clearInterval(interval)
+          reloadPage()
+        }
+      })
+      .catch(() => {
+        clearInterval(interval)
+        reloadPage()
+      })
+  }, 1000)
+}
+
+/**
+ * Handle standard form submission for file upload
+ * @param {HTMLFormElement} formElement - The form element
+ * @param {HTMLInputElement} fileInput - The file input element
+ * @param {HTMLButtonElement} uploadButton - The upload button
+ * @param {HTMLButtonElement} continueButton - The continue button
+ * @param {File | null} selectedFile - The selected file
+ */
+function handleStandardFormSubmission(
+  formElement,
+  fileInput,
+  uploadButton,
+  continueButton,
+  selectedFile
+) {
+  renderSummary(selectedFile, 'Uploading…', formElement)
+
+  fileInput.focus()
+
+  setTimeout(() => {
+    fileInput.disabled = true
+    uploadButton.disabled = true
+    continueButton.disabled = true
+  }, 100)
+}
+
+/**
+ * Handle AJAX form submission with upload ID
+ * @param {Event} event - The click event
+ * @param {HTMLFormElement} formElement - The form element
+ * @param {HTMLInputElement} fileInput - The file input element
+ * @param {HTMLButtonElement} uploadButton - The upload button
+ * @param {HTMLElement | null} errorSummary - The error summary container
+ * @param {string | undefined} uploadId - The upload ID
+ * @returns {boolean} Whether the event was handled
+ */
+function handleAjaxFormSubmission(
+  event,
+  formElement,
+  fileInput,
+  uploadButton,
+  errorSummary,
+  uploadId
+) {
+  if (!formElement.action || !uploadId) {
+    return false
+  }
+
+  event.preventDefault()
+
+  const formData = new FormData(formElement)
+  const isLocalDev = !!formElement.dataset.proxyUrl
+  const uploadUrl = formElement.dataset.proxyUrl ?? formElement.action
+
+  const fetchOptions = /** @type {RequestInit} */ ({
+    method: 'POST',
+    body: formData,
+    redirect: isLocalDev ? 'follow' : 'manual' // follow mode if local development with the proxy
+  })
+
+  // no-cors mode if needed local development with the proxy
+  if (isLocalDev) {
+    fetchOptions.mode = 'no-cors'
+  }
+
+  fetch(uploadUrl, fetchOptions)
+    .then(() => {
+      pollUploadStatus(uploadId)
+    })
+    .catch(() => {
+      fileInput.disabled = false
+      uploadButton.disabled = false
+
+      showError(
+        'There was a problem uploading the file',
+        errorSummary,
+        fileInput
+      )
+
+      return null
+    })
+
+  return true
+}
+
+export function initFileUpload() {
+  const form = document.querySelector('form:has(input[type="file"])')
+  /** @type {HTMLInputElement | null} */
+  const fileInput = form ? form.querySelector('input[type="file"]') : null
+  /** @type {HTMLButtonElement | null} */
+  const uploadButton = form ? form.querySelector('.upload-file-button') : null
+  const continueButton =
+    /** @type {HTMLButtonElement} */ (
+      Array.from(document.querySelectorAll('button.govuk-button')).find(
+        (button) => button.textContent?.trim() === 'Continue'
+      )
+    ) ?? null
+
+  const errorSummary = document.querySelector('.govuk-error-summary-container')
+
+  if (!form || !fileInput || !uploadButton) {
+    return
+  }
+
+  const formElement = /** @type {HTMLFormElement} */ (form)
+  /** @type {File | null} */
+  let selectedFile = null
+  let isSubmitting = false
+  const uploadId = formElement.dataset.uploadId
+
+  fileInput.addEventListener('change', () => {
+    if (errorSummary) {
+      errorSummary.innerHTML = ''
+    }
+    if (fileInput.files && fileInput.files.length > 0) {
+      selectedFile = fileInput.files[0]
+    }
+  })
+
+  uploadButton.addEventListener('click', (event) => {
+    if (!selectedFile) {
+      event.preventDefault()
+      showError(
+        'Select a file',
+        /** @type {HTMLElement | null} */ (errorSummary),
+        fileInput
+      )
+      return
+    }
+
+    if (isSubmitting) {
+      event.preventDefault()
+      return
+    }
+
+    isSubmitting = true
+
+    handleStandardFormSubmission(
+      formElement,
+      fileInput,
+      uploadButton,
+      continueButton,
+      selectedFile
+    )
+
+    handleAjaxFormSubmission(
+      event,
+      formElement,
+      fileInput,
+      uploadButton,
+      /** @type {HTMLElement | null} */ (errorSummary),
+      uploadId
+    )
+  })
+}

package/src/client/stylesheets/_code.scss

@@ -0,0 +1,33 @@
+@use "govuk-frontend" as *;
+@use "pkg:highlight.js/styles/github.css";
+
+.app-code {
+  @include govuk-responsive-margin(8, "bottom");
+
+  &__container {
+    display: block;
+    margin: 0;
+    padding: govuk-spacing(4);
+    overflow-x: auto;
+    border: $govuk-focus-width solid transparent;
+    outline: 1px solid transparent;
+    background-color: govuk-colour("light-grey");
+    @include govuk-responsive-margin(4, "bottom");
+
+    &:focus {
+      border: $govuk-focus-width solid $govuk-input-border-colour;
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+    }
+  }
+
+  &:last-child &__container {
+    margin-bottom: 0;
+  }
+}
+
+pre,
+code {
+  $app-code-font: ui-monospace, menlo, "Cascadia Mono", "Segoe UI Mono", consolas, "Liberation Mono", monospace;
+  @include govuk-typography-common($font-family: $app-code-font);
+  @include govuk-font-size($size: 16);
+}

package/src/client/stylesheets/_govuk-frontend.scss

@@ -0,0 +1,4 @@
+@forward "pkg:govuk-frontend" with (
+  $govuk-assets-path: "/assets/",
+  $govuk-new-organisation-colours: true
+);

package/src/client/stylesheets/_prose.scss

@@ -0,0 +1,56 @@
+@use "govuk-frontend" as *;
+
+.app-prose-scope {
+  // @extend inheritance
+
+  // Contextual heading and paragraph combinations are inherited
+  // through the use of @extend
+
+  h1 {
+    @extend %govuk-heading-xl;
+  }
+
+  h2 {
+    @extend %govuk-heading-l;
+  }
+
+  h3 {
+    @extend %govuk-heading-m;
+  }
+
+  h4 {
+    @extend %govuk-heading-s;
+  }
+
+  p {
+    @extend %govuk-body-m;
+  }
+
+  strong,
+  b {
+    @include govuk-typography-weight-bold;
+  }
+
+  ul,
+  ol {
+    @extend %govuk-list;
+  }
+
+  ol {
+    @extend %govuk-list--number;
+  }
+
+  ul {
+    @extend %govuk-list--bullet;
+  }
+
+  a {
+    @extend %govuk-link;
+  }
+
+  hr {
+    @extend %govuk-section-break;
+    @extend %govuk-section-break--visible;
+    @extend %govuk-section-break--xl;
+  }
+}

package/src/client/stylesheets/_service-banner.scss

@@ -0,0 +1,24 @@
+@use "govuk-frontend" as *;
+
+.app-service-banner {
+  display: block;
+  background: govuk-colour("yellow");
+  color: govuk-colour("black");
+
+  @include govuk-responsive-padding(2, "top");
+  @include govuk-responsive-padding(2, "bottom");
+
+  &__content {
+    margin: 0;
+  }
+
+  .govuk-warning-text__text {
+    font-weight: $govuk-font-weight-regular;
+  }
+
+  .govuk-skip-link:active + &,
+  .govuk-skip-link:focus + & {
+    // Ofset service banner from skip link
+    margin-top: $govuk-border-width + $govuk-focus-width;
+  }
+}

package/src/client/stylesheets/_summary-list.scss

@@ -0,0 +1,28 @@
+@use "govuk-frontend" as *;
+
+// Taken from https://github.com/hmrc/hmrc-frontend/blob/main/src/components/summary-list/_summary-list.scss
+@include govuk-media-query($from: tablet) {
+  .govuk-summary-list.govuk-summary-list--long-key {
+    .govuk-summary-list__row {
+      display: flex;
+      justify-content: space-between;
+      flex-wrap: wrap;
+    }
+
+    .govuk-summary-list__key {
+      flex-grow: 1;
+      margin-bottom: 0;
+    }
+
+    .govuk-summary-list__actions {
+      width: auto;
+      margin-bottom: 0;
+    }
+  }
+
+  .govuk-summary-list.govuk-summary-list--long-actions {
+    .govuk-summary-list__actions {
+      width: auto;
+    }
+  }
+}

package/src/client/stylesheets/_tag-env.scss

@@ -0,0 +1,24 @@
+@use "govuk-frontend" as *;
+
+.app-tag--env {
+  margin: -6px 0 0;
+  vertical-align: top;
+
+  // Override product name font size
+  @include govuk-font-size($size: 16);
+
+  // Align with product name
+  @include govuk-media-query($from: tablet) {
+    margin: -3px 0 0;
+  }
+
+  // Override service header alignment
+  .cross-service-header & {
+    margin: -2px 0 0 govuk-spacing(1);
+
+    // Align with product name
+    @include govuk-media-query($from: tablet) {
+      margin: 0 0 0 govuk-spacing(2);
+    }
+  }
+}

package/src/client/stylesheets/application.scss

@@ -0,0 +1,14 @@
+@use "govuk-frontend" as *;
+@use "pkg:accessible-autocomplete";
+@use "code";
+@use "prose";
+@use "service-banner";
+@use "summary-list";
+@use "tag-env";
+
+// Use default GDS Transport font for autocomplete
+.autocomplete__hint,
+.autocomplete__input,
+.autocomplete__option {
+  @include govuk-typography-common;
+}

package/src/common/cookies.js

@@ -0,0 +1,58 @@
+/**
+  @type {CookieConsent}
+ */
+export const defaultConsent = {
+  analytics: null,
+  dismissed: false
+}
+
+/**
+ * Parses the cookie consent policy
+ * @param {string} value
+ */
+export function parseCookieConsent(value) {
+  /** @type {CookieConsent} */
+  let cookieConsent
+
+  try {
+    const encodedValue = decodeURIComponent(value)
+
+    // eslint-disable-next-line -- Allow JSON type 'any'
+    const decodedValue = JSON.parse(encodedValue)
+
+    if (isValidConsent(decodedValue)) {
+      cookieConsent = decodedValue
+    } else {
+      cookieConsent = defaultConsent
+    }
+  } catch {
+    cookieConsent = defaultConsent
+  }
+
+  return cookieConsent
+}
+
+/**
+ * Serialises the cookie consent policy
+ * @param {CookieConsent} consent
+ * @returns {string} cookie value
+ */
+export function serialiseCookieConsent(consent) {
+  return encodeURIComponent(JSON.stringify(consent))
+}
+
+/**
+ * @param {unknown} consent
+ * @returns {consent is CookieConsent}
+ */
+function isValidConsent(consent) {
+  if (consent === null || Array.isArray(consent)) {
+    return false
+  }
+
+  return typeof consent === 'object' && 'analytics' in consent
+}
+
+/**
+ * @import {CookieConsent} from '~/src/common/types.js'
+ */

package/src/common/cookies.test.js

@@ -0,0 +1,23 @@
+import { parseCookieConsent } from '~/src/common/cookies.js'
+
+describe('cookies', () => {
+  it('parses a valid policy', () => {
+    expect(parseCookieConsent('{"analytics":true}')).toEqual({
+      analytics: true
+    })
+  })
+
+  it.each([
+    "['not', 'an', 'object']",
+    '{{ not: "an object" }}',
+    '{ additional: AAA }',
+    '{ marketing: 100 }',
+    '',
+    'null'
+  ])('converts a malformed policy to the default', (value) => {
+    expect(parseCookieConsent(value)).toEqual({
+      analytics: null,
+      dismissed: false
+    })
+  })
+})

package/src/common/types.js

@@ -0,0 +1,5 @@
+/**
+ * @typedef CookieConsent
+ * @property {boolean | null} analytics - whether analytics cookies are allowed
+ * @property {boolean} dismissed - whether cookie banner has been dismissed
+ */