@defra/forms-engine-plugin 0.0.4 → 0.0.6

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

@@ -0,0 +1,317 @@
+import {
+  type ComponentDef,
+  type Item,
+  type List,
+  type Page
+} from '@defra/forms-model'
+import { type ValidationErrorItem } from 'joi'
+
+import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
+import { type Component } from '~/src/server/plugins/engine/components/helpers.js'
+import {
+  type BackLink,
+  type ComponentText,
+  type ComponentViewModel
+} from '~/src/server/plugins/engine/components/types.js'
+import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import { type ViewContext } from '~/src/server/plugins/nunjucks/types.js'
+import { type FormAction, type FormRequest } from '~/src/server/routes/types.js'
+
+/**
+ * Form submission state stores the following in Redis:
+ * Props containing user's submitted values as `{ [inputId]: value }` or as `{ [sectionName]: { [inputName]: value } }`
+ *   a) . e.g:
+ * ```ts
+ *     {
+ *       _C9PRHmsgt: 'Ben',
+ *       WfLk9McjzX: 'Music',
+ *       IK7jkUFCBL: 'Royal Academy of Music'
+ *     }
+ * ```
+ *
+ *   b)
+ * ```ts
+ *   {
+ *         checkBeforeYouStart: { ukPassport: true },
+ *         applicantDetails: {
+ *           numberOfApplicants: 1,
+ *           phoneNumber: '77777777',
+ *           emailAddress: 'aaa@aaa.com'
+ *         },
+ *         applicantOneDetails: {
+ *           firstName: 'a',
+ *           middleName: 'a',
+ *           lastName: 'a',
+ *           address: { addressLine1: 'a', addressLine2: 'a', town: 'a', postcode: 'a' }
+ *         }
+ *     }
+ * ```
+ */
+
+/**
+ * Form submission state
+ */
+export type FormSubmissionState = {
+  upload?: Record<string, TempFileState>
+} & FormState
+
+export interface FormSubmissionError
+  extends Pick<ValidationErrorItem, 'context' | 'path'> {
+  href: string // e.g: '#dateField__day'
+  name: string // e.g: 'dateField__day'
+  text: string // e.g: 'Date field must be a real date'
+}
+
+export interface FormParams {
+  action?: FormAction
+  confirm?: true
+  crumb?: string
+  itemId?: string
+}
+
+/**
+ * Form POST for question pages
+ * (after Joi has converted value types)
+ */
+export type FormPayload = FormParams & Partial<Record<string, FormValue>>
+
+export type FormValue =
+  | Item['value']
+  | Item['value'][]
+  | UploadState
+  | RepeatListState
+  | undefined
+
+export type FormState = Partial<Record<string, FormStateValue>>
+export type FormStateValue = Exclude<FormValue, undefined> | null
+
+export interface FormValidationResult<
+  ValueType extends FormPayload | FormSubmissionState
+> {
+  value: ValueType
+  errors: FormSubmissionError[] | undefined
+}
+
+export interface FormContext {
+  /**
+   * Evaluation form state only (filtered by visited paths),
+   * with values formatted for condition evaluation using
+   * {@link FormComponent.getContextValueFromState}
+   */
+  evaluationState: FormState
+
+  /**
+   * Relevant form state only (filtered by visited paths)
+   */
+  relevantState: FormState
+
+  /**
+   * Relevant pages only (filtered by visited paths)
+   */
+  relevantPages: PageControllerClass[]
+
+  /**
+   * Form submission payload (single page)
+   */
+  payload: FormPayload
+
+  /**
+   * Form submission state (entire form)
+   */
+  state: FormSubmissionState
+
+  /**
+   * Validation errors (entire form)
+   */
+  errors?: FormSubmissionError[]
+
+  /**
+   * Visited paths evaluated from form state
+   */
+  paths: string[]
+
+  /**
+   * Preview URL direct access is allowed
+   */
+  isForceAccess: boolean
+
+  /**
+   * Miscellaneous extra data from event responses
+   */
+  data: object
+
+  pageDefMap: Map<string, Page>
+  listDefMap: Map<string, List>
+  componentDefMap: Map<string, ComponentDef>
+  pageMap: Map<string, PageControllerClass>
+  componentMap: Map<string, Component>
+}
+
+export type FormContextRequest = (
+  | {
+      method: 'get'
+      payload?: undefined
+    }
+  | {
+      method: 'post'
+      payload: FormPayload
+    }
+  | {
+      method: FormRequest['method']
+      payload?: object | undefined
+    }
+) &
+  Pick<FormRequest, 'app' | 'method' | 'params' | 'path' | 'query' | 'url'>
+
+export interface UploadInitiateResponse {
+  uploadId: string
+  uploadUrl: string
+  statusUrl: string
+}
+
+export enum UploadStatus {
+  initiated = 'initiated',
+  pending = 'pending',
+  ready = 'ready'
+}
+
+export enum FileStatus {
+  complete = 'complete',
+  rejected = 'rejected',
+  pending = 'pending'
+}
+
+export type UploadState = FileState[]
+
+export type FileUpload = {
+  fileId: string
+  filename: string
+  contentLength: number
+} & (
+  | {
+      fileStatus: FileStatus.complete | FileStatus.rejected | FileStatus.pending
+      errorMessage?: string
+    }
+  | {
+      fileStatus: FileStatus.complete
+      errorMessage?: undefined
+    }
+)
+
+export interface FileUploadMetadata {
+  retrievalKey: string
+}
+
+export type UploadStatusResponse =
+  | {
+      uploadStatus: UploadStatus.initiated
+      metadata: FileUploadMetadata
+      form: { file?: undefined }
+    }
+  | {
+      uploadStatus: UploadStatus.pending | UploadStatus.ready
+      metadata: FileUploadMetadata
+      form: { file: FileUpload }
+      numberOfRejectedFiles?: number
+    }
+  | {
+      uploadStatus: UploadStatus.ready
+      metadata: FileUploadMetadata
+      form: { file: FileUpload }
+      numberOfRejectedFiles: 0
+    }
+
+export type UploadStatusFileResponse = Exclude<
+  UploadStatusResponse,
+  { uploadStatus: UploadStatus.initiated }
+>
+
+export interface FileState {
+  uploadId: string
+  status: UploadStatusFileResponse
+}
+
+export interface TempFileState {
+  upload?: UploadInitiateResponse
+  files: UploadState
+}
+
+export interface RepeatItemState extends FormPayload {
+  itemId: string
+}
+
+export type RepeatListState = RepeatItemState[]
+
+export interface CheckAnswers {
+  title?: ComponentText
+  summaryList: SummaryList
+}
+
+export interface SummaryList {
+  classes?: string
+  rows: SummaryListRow[]
+}
+
+export interface SummaryListRow {
+  key: ComponentText
+  value: ComponentText
+  actions?: { items: SummaryListAction[] }
+}
+
+export type SummaryListAction = ComponentText & {
+  href: string
+  visuallyHiddenText: string
+}
+
+export interface PageViewModelBase extends Partial<ViewContext> {
+  page: PageController
+  name?: string
+  pageTitle: string
+  sectionTitle?: string
+  showTitle: boolean
+  isStartPage: boolean
+  backLink?: BackLink
+  feedbackLink?: string
+  serviceUrl: string
+  phaseTag?: string
+}
+
+export interface ItemDeletePageViewModel extends PageViewModelBase {
+  context: FormContext
+  itemTitle: string
+  confirmation?: ComponentText
+  buttonConfirm: ComponentText
+  buttonCancel: ComponentText
+}
+
+export interface FormPageViewModel extends PageViewModelBase {
+  components: ComponentViewModel[]
+  context: FormContext
+  errors?: FormSubmissionError[]
+  hasMissingNotificationEmail?: boolean
+}
+
+export interface RepeaterSummaryPageViewModel extends PageViewModelBase {
+  context: FormContext
+  errors?: FormSubmissionError[]
+  checkAnswers: CheckAnswers[]
+  repeatTitle: string
+}
+
+export interface FeaturedFormPageViewModel extends FormPageViewModel {
+  formAction?: string
+  formComponent: ComponentViewModel
+  componentsBefore: ComponentViewModel[]
+  uploadId: string | undefined
+  proxyUrl: string | null
+}
+
+export type PageViewModel =
+  | PageViewModelBase
+  | ItemDeletePageViewModel
+  | FormPageViewModel
+  | RepeaterSummaryPageViewModel
+  | FeaturedFormPageViewModel
+
+export type FilterFunction = (value: unknown) => unknown

package/src/server/plugins/engine/views/components/autocompletefield.html

@@ -0,0 +1,5 @@
+{% from "govuk/components/select/macro.njk" import govukSelect %}
+
+{% macro AutocompleteField(component) %}
+  {{ govukSelect(component.model) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/checkboxesfield.html

@@ -0,0 +1,5 @@
+{% from "govuk/components/checkboxes/macro.njk" import govukCheckboxes %}
+
+{% macro CheckboxesField(component) %}
+  {{ govukCheckboxes(component.model) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/datepartsfield.html

@@ -0,0 +1,5 @@
+{% from "govuk/components/date-input/macro.njk" import govukDateInput %}
+
+{% macro DatePartsField(component) %}
+  {{ govukDateInput(component.model) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/debug/macro.njk

@@ -0,0 +1,3 @@
+{% macro appDebug(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

package/src/server/plugins/engine/views/components/debug/template.njk

@@ -0,0 +1,13 @@
+{%- macro _code(params) -%}
+  {{- params.content | inspect | safe -}}
+{%- endmacro -%}
+
+{%- macro _container(params) -%}
+  <code tabindex="0" class="app-code__container">
+    {{- _code(params) | highlight('js') | safe -}}
+  </code>
+{%- endmacro -%}
+
+<pre class="app-code">
+  {{- _container(params) -}}
+</pre>

package/src/server/plugins/engine/views/components/details.html

@@ -0,0 +1,6 @@
+{% from "govuk/components/details/macro.njk" import govukDetails %}
+
+{% macro Details(component) %}
+  {# {{ getContext(component) | dump | safe }} #}
+  {{ govukDetails(component.model)}}
+{% endmacro %}

package/src/server/plugins/engine/views/components/emailaddressfield.html

@@ -0,0 +1,5 @@
+{% from "components/textfield.html" import TextField %}
+
+{% macro EmailAddressField(component) %}
+  {{ TextField(component) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/fileuploadfield-key.html

@@ -0,0 +1,8 @@
+{% if params.errorMessage %}
+  <div class="govuk-form-group govuk-form-group--error govuk-!-margin-bottom-0">
+    <div class="govuk-!-margin-bottom-3">{{ params.name }}</div>
+    <p class="govuk-error-message">{{ params.errorMessage }}</p>
+  </div>
+{% else %}
+  {{ params.name }}
+{% endif %}

package/src/server/plugins/engine/views/components/fileuploadfield-value.html

@@ -0,0 +1,3 @@
+{% from "govuk/components/tag/macro.njk" import govukTag -%}
+
+{{ govukTag(params.tag) }}

package/src/server/plugins/engine/views/components/fileuploadfield.html

@@ -0,0 +1,24 @@
+{% from "govuk/components/summary-list/macro.njk" import govukSummaryList -%}
+
+{% macro FileUploadField(component) %}
+  {% set upload = component.model.upload %}
+
+  <div id="uploadedFilesContainer">
+    <h2 class="govuk-heading-m">Uploaded files</h2>
+    {% if upload.count %}
+      <p class="govuk-body">{{upload.count}} file{{ "s" if upload.count > 1}} uploaded</p>
+      <p class="govuk-body">
+      </p>
+
+      <div class="govuk-visually-hidden" aria-live="polite" id="statusInformation">
+        {{upload.count}} file{{ "s" if upload.count > 1}} uploaded
+      </div>
+
+      {% if upload.summaryList.rows | length %}
+        {{ govukSummaryList(upload.summaryList) }}
+      {% endif %}
+    {% else %}
+      <p class="govuk-body">{{upload.count}} files uploaded</p>
+    {% endif %}
+  </div>
+{% endmacro %}

package/src/server/plugins/engine/views/components/html.html

@@ -0,0 +1,3 @@
+{% macro Html(component) %}
+    {{ component.model.content | safe }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/insettext.html

@@ -0,0 +1,7 @@
+{% from "govuk/components/inset-text/macro.njk" import govukInsetText %}
+
+{% macro InsetText(component) %}
+  {{ govukInsetText({
+    html: component.model.content
+  }) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/list.html

@@ -0,0 +1,36 @@
+{% macro List(component) %}
+  {% set params = component.model %}
+
+  <div class="govuk-form-group">
+    {% if params.content.title %}
+      <h2 class="govuk-heading-m govuk-!-margin-bottom-3">
+        {{ params.content.title }}
+      </h2>
+    {% endif %}
+
+    {% if params.content.text %}
+      <p class="govuk-body">
+        {{ params.content.text }}
+      </p>
+    {% endif %}
+
+    {% if params.type == 'numbered' %}
+      <ol class="govuk-list govuk-list--number {%- if params.classes %} {{ params.classes }}{% endif %}">
+    {% else %}
+      <ul class="govuk-list govuk-list--bullet {%- if params.classes %} {{ params.classes }}{% endif %}">
+    {% endif %}
+    {% for item in params.items %}
+      <li>
+        {{ item.text }}
+        {% if item.hint.text | length %}
+          <br><span class="govuk-hint govuk-!-display-inline-block">{{ item.hint.text }}</span>
+        {% endif %}
+      </li>
+    {% endfor %}
+    {% if params.type == 'numbered' %}
+      </ol>
+    {% else %}
+      </ul>
+    {% endif %}
+  </div>
+{% endmacro %}

package/src/server/plugins/engine/views/components/monthyearfield.html

@@ -0,0 +1,5 @@
+{% from "govuk/components/date-input/macro.njk" import govukDateInput %}
+
+{% macro MonthYearField(component) %}
+  {{ govukDateInput(component.model) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/multilinetextfield.html

@@ -0,0 +1,10 @@
+{% from "govuk/components/textarea/macro.njk" import govukTextarea %}
+{% from "govuk/components/character-count/macro.njk" import govukCharacterCount %}
+
+{% macro MultilineTextField(component) %}
+  {% if component.model.isCharacterOrWordCount == true %}
+    {{ govukCharacterCount(component.model) }}
+  {% else %}
+    {{ govukTextarea(component.model) }}
+  {% endif %}
+{% endmacro %}

package/src/server/plugins/engine/views/components/numberfield.html

@@ -0,0 +1,5 @@
+{% from "components/textfield.html" import TextField %}
+
+{% macro NumberField(component) %}
+  {{ TextField(component) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/radiosfield.html

@@ -0,0 +1,5 @@
+{% from "govuk/components/radios/macro.njk" import govukRadios %}
+
+{% macro RadiosField(component) %}
+  {{ govukRadios(component.model) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/selectfield.html

@@ -0,0 +1,5 @@
+{% from "govuk/components/select/macro.njk" import govukSelect %}
+
+{% macro SelectField(component) %}
+  {{ govukSelect(component.model) }}
+{% endmacro %}

package/src/server/plugins/engine/views/components/service-banner/macro.njk

@@ -0,0 +1,3 @@
+{% macro appServiceBanner(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

package/src/server/plugins/engine/views/components/service-banner/template.njk

@@ -0,0 +1,20 @@
+{% from "govuk/components/warning-text/macro.njk" import govukWarningText -%}
+
+{%- macro _message(params) %}
+  <span class="govuk-!-font-weight-bold" aria-hidden="true">{{ params.title }}:</span>
+  <span class="app-service-banner__text">{{ params.text if params.text else params.html | safe }}</span>
+{% endmacro -%}
+
+{%- macro _iconFallback(params) %}
+  <span id="app-service-banner-description">{{ params.title }}</span>
+{% endmacro -%}
+
+<aside class="app-service-banner" aria-labelledby="app-service-banner-description" aria-live="polite">
+  <div class="govuk-width-container">
+    {{ govukWarningText({
+      html: _message(params) | trim | indent(2),
+      iconFallbackText: _iconFallback(params) | safe | trim,
+      classes: "app-service-banner__content"
+    }) | trim | indent(4) }}
+  </div>
+</aside>

package/src/server/plugins/engine/views/components/service-banner/template.test.js

@@ -0,0 +1,43 @@
+import { renderMacro } from '~/test/helpers/component-helpers.js'
+
+describe('Service banner component', () => {
+  let $component = /** @type {HTMLElement | null} */ (null)
+  let $content = /** @type {HTMLElement | null} */ (null)
+  let $text = /** @type {HTMLElement | null} */ (null)
+
+  beforeEach(() => {
+    const { container, document } = renderMacro(
+      'appServiceBanner',
+      'components/service-banner/macro.njk',
+      {
+        params: {
+          title: 'Service status',
+          text: 'This is a service status message'
+        }
+      }
+    )
+
+    $component = container.getByRole('complementary')
+    $content = document.querySelector('.app-service-banner__content')
+    $text = document.querySelector('.app-service-banner__text')
+  })
+
+  it('should render contents', () => {
+    expect($component).toBeInTheDocument()
+    expect($component).toHaveClass('app-service-banner')
+    expect($component).toContainElement($content)
+    expect($content).toContainElement($text)
+  })
+
+  it('should announce service message', () => {
+    expect($component).toHaveAttribute('aria-live', 'polite')
+  })
+
+  it('should have accessible name', () => {
+    expect($component).toHaveAccessibleName('Service status')
+  })
+
+  it('should have text content', () => {
+    expect($text).toHaveTextContent('This is a service status message')
+  })
+})

package/src/server/plugins/engine/views/components/tag-env/macro.njk

@@ -0,0 +1,3 @@
+{% macro appTagEnv(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

package/src/server/plugins/engine/views/components/tag-env/template.njk

@@ -0,0 +1,30 @@
+{%- from "govuk/components/tag/macro.njk" import govukTag -%}
+
+{%- switch params.env %}
+  {% case "local" %}
+    {% set text = "Local" %}
+    {% set classes = "govuk-tag--green" %}
+  {% case "dev" %}
+    {% set text = "Development" %}
+    {% set classes = "govuk-tag--grey" %}
+  {% case "test" %}
+    {% set text = "Test" %}
+    {% set classes = "govuk-tag--yellow" %}
+  {% case "ext-test" %}
+    {% set text = "External test" %}
+    {% set classes = "govuk-tag--yellow" %}
+  {% case "perf-test" %}
+    {% set text = "Performance test" %}
+    {% set classes = "govuk-tag--yellow" %}
+  {% case "prod" %}
+    {% set text = "Production" %}
+    {% set classes = "govuk-tag--red" %}
+  {% default %}
+    {% set text = params.env | replace("-", " ") | capitalize %}
+    {% set classes = "govuk-tag--grey" %}
+{% endswitch -%}
+
+{{ govukTag({
+  text: text,
+  classes: classes + " app-tag--env"
+}) }}

package/src/server/plugins/engine/views/components/tag-env/template.test.js

@@ -0,0 +1,66 @@
+import { renderMacro } from '~/test/helpers/component-helpers.js'
+
+describe('Tag environment component', () => {
+  describe.each([
+    {
+      text: 'Local',
+      env: 'local',
+      colour: 'green'
+    },
+    {
+      text: 'Development',
+      env: 'dev',
+      colour: 'grey'
+    },
+    {
+      text: 'Test',
+      env: 'test',
+      colour: 'yellow'
+    },
+    {
+      text: 'External test',
+      env: 'ext-test',
+      colour: 'yellow'
+    },
+    {
+      text: 'Performance test',
+      env: 'perf-test',
+      colour: 'yellow'
+    },
+    {
+      text: 'Production',
+      env: 'prod',
+      colour: 'red'
+    },
+    {
+      text: 'Unknown environment',
+      env: 'unknown-environment',
+      colour: 'grey'
+    }
+  ])('Environment: $text', ({ text, env, colour }) => {
+    let $component = /** @type {HTMLElement | null} */ (null)
+
+    beforeEach(() => {
+      const { container } = renderMacro(
+        'appTagEnv',
+        'components/tag-env/macro.njk',
+        { params: { env } }
+      )
+
+      $component = container.getByRole('strong')
+    })
+
+    it('should render contents', () => {
+      expect($component).toBeInTheDocument()
+      expect($component).toHaveClass('govuk-tag')
+    })
+
+    it('should have text content', () => {
+      expect($component).toHaveTextContent(text)
+    })
+
+    it('should use environment colour', () => {
+      expect($component).toHaveClass(`govuk-tag--${colour}`)
+    })
+  })
+})

package/src/server/plugins/engine/views/components/telephonenumberfield.html

@@ -0,0 +1,5 @@
+{% from "components/textfield.html" import TextField %}
+
+{% macro TelephoneNumberField(component) %}
+  {{ TextField(component) }}
+{% endmacro %}