@defra/forms-engine-plugin 0.0.1

package/src/server/plugins/engine/models/SummaryViewModel.ts

@@ -0,0 +1,220 @@
+import { type Section } from '@defra/forms-model'
+
+import {
+  getAnswer,
+  type Field
+} from '~/src/server/plugins/engine/components/helpers.js'
+import { type BackLink } from '~/src/server/plugins/engine/components/types.js'
+import {
+  evaluateTemplate,
+  getError,
+  getPageHref
+} from '~/src/server/plugins/engine/helpers.js'
+import {
+  type Detail,
+  type DetailItem,
+  type DetailItemField,
+  type DetailItemRepeat
+} from '~/src/server/plugins/engine/models/types.js'
+import { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import { validationOptions as opts } from '~/src/server/plugins/engine/pageControllers/validationOptions.js'
+import {
+  type CheckAnswers,
+  type FormContext,
+  type FormContextRequest,
+  type FormState,
+  type FormSubmissionError,
+  type SummaryListAction,
+  type SummaryListRow
+} from '~/src/server/plugins/engine/types.js'
+
+export class SummaryViewModel {
+  /**
+   * Responsible for parsing state values to the govuk-frontend summary list template
+   */
+
+  page: PageControllerClass
+  pageTitle: string
+  declaration?: string
+  details: Detail[]
+  checkAnswers: CheckAnswers[]
+  context: FormContext
+  name: string | undefined
+  backLink?: BackLink
+  feedbackLink?: string
+  phaseTag?: string
+  errors?: FormSubmissionError[]
+  serviceUrl: string
+  hasMissingNotificationEmail?: boolean
+
+  constructor(
+    request: FormContextRequest,
+    page: PageControllerClass,
+    context: FormContext
+  ) {
+    const { model } = page
+    const { basePath, def, sections } = model
+    const { isForceAccess } = context
+
+    this.page = page
+    this.pageTitle = page.title
+    this.serviceUrl = `/${basePath}`
+    this.name = def.name
+    this.declaration = def.declaration
+    this.context = context
+
+    const result = model
+      .makeFilteredSchema(this.context.relevantPages)
+      .validate(this.context.relevantState, { ...opts, stripUnknown: true })
+
+    // Format errors
+    this.errors = result.error?.details.map(getError)
+    this.details = this.summaryDetails(request, sections)
+
+    // Format check answers
+    this.checkAnswers = this.details.map((detail): CheckAnswers => {
+      const { title } = detail
+
+      const rows = detail.items.map((item): SummaryListRow => {
+        const items: SummaryListAction[] = []
+
+        // Remove summary list actions from previews
+        if (!isForceAccess) {
+          items.push({
+            href: item.href,
+            text: 'Change',
+            classes: 'govuk-link--no-visited-state',
+            visuallyHiddenText: item.label
+          })
+        }
+
+        return {
+          key: {
+            text: evaluateTemplate(item.title, context)
+          },
+          value: {
+            classes: 'app-prose-scope',
+            html: item.value || 'Not supplied'
+          },
+          actions: {
+            items
+          }
+        }
+      })
+
+      return {
+        title: title ? { text: title } : undefined,
+        summaryList: { rows }
+      }
+    })
+  }
+
+  private summaryDetails(request: FormContextRequest, sections: Section[]) {
+    const { context, errors } = this
+    const { relevantPages, state } = context
+
+    const details: Detail[] = []
+
+    ;[undefined, ...sections].forEach((section) => {
+      const items: DetailItem[] = []
+
+      const sectionPages = relevantPages.filter(
+        (page) => page.section === section
+      )
+
+      sectionPages.forEach((page) => {
+        const { collection, path } = page
+
+        if (page instanceof RepeatPageController) {
+          items.push(
+            ItemRepeat(page, state, {
+              path: page.getSummaryPath(request),
+              errors
+            })
+          )
+        } else {
+          for (const field of collection.fields) {
+            items.push(ItemField(page, state, field, { path, errors }))
+          }
+        }
+      })
+
+      if (items.length) {
+        details.push({
+          name: section?.name,
+          title: section?.title,
+          items
+        })
+      }
+    })
+
+    return details
+  }
+}
+
+/**
+ * Creates a repeater detail item
+ * @see {@link DetailItemField}
+ */
+function ItemRepeat(
+  page: RepeatPageController,
+  state: FormState,
+  options: {
+    path: string
+    errors?: FormSubmissionError[]
+  }
+): DetailItemRepeat {
+  const { collection, repeat } = page
+  const { name, title } = repeat.options
+
+  const values = page.getListFromState(state)
+  const unit = values.length === 1 ? title : `${title}s`
+
+  return {
+    name,
+    label: title,
+    title: values.length ? `${unit} added` : unit,
+    value: values.length ? `You added ${values.length} ${unit}` : '',
+    href: getPageHref(page, options.path, {
+      returnUrl: getPageHref(page, page.getSummaryPath())
+    }),
+    state,
+    page,
+
+    // Repeater field detail items
+    subItems: values.map((repeatState) =>
+      collection.fields.map((field) =>
+        ItemField(page, repeatState, field, options)
+      )
+    )
+  }
+}
+
+/**
+ * Creates a form field detail item
+ * @see {@link DetailItemField}
+ */
+function ItemField(
+  page: PageControllerClass,
+  state: FormState,
+  field: Field,
+  options: {
+    path: string
+    errors?: FormSubmissionError[]
+  }
+): DetailItemField {
+  return {
+    name: field.name,
+    label: field.title,
+    title: field.title,
+    error: field.getError(options.errors),
+    value: getAnswer(field, state),
+    href: getPageHref(page, options.path, {
+      returnUrl: getPageHref(page, page.getSummaryPath())
+    }),
+    state,
+    page,
+    field
+  }
+}

package/src/server/plugins/engine/models/index.ts

@@ -0,0 +1,2 @@
+export { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+export { SummaryViewModel } from '~/src/server/plugins/engine/models/SummaryViewModel.js'

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

@@ -0,0 +1,114 @@
+import {
+  type ConditionWrapper,
+  type FormComponentsDef,
+  type Section
+} from '@defra/forms-model'
+import { type Expression } from 'expr-eval'
+
+import {
+  type Field,
+  type getAnswer
+} from '~/src/server/plugins/engine/components/helpers.js'
+import { type RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import {
+  type FormState,
+  type FormSubmissionError
+} from '~/src/server/plugins/engine/types.js'
+
+export type ExecutableCondition = ConditionWrapper & {
+  expr: Expression
+  fn: (evaluationState: FormState) => boolean
+}
+
+/**
+ * Used to render a row on a Summary List (check your answers)
+ */
+export interface DetailItemBase {
+  /**
+   * Name of the component defined in the JSON
+   * @see {@link FormComponentsDef.name}
+   */
+  name: string
+
+  /**
+   * Field label, used for change link visually hidden text
+   * @see {@link FormComponentsDef.title}
+   */
+  label: string
+
+  /**
+   * Field change link
+   */
+  href: string
+
+  /**
+   * Form submission state (or repeat state for sub items)
+   */
+  state: FormState
+
+  /**
+   * Field submission state error, used to flag unanswered questions
+   * Shown as 'Complete all unanswered questions before submitting the form'
+   */
+  error?: FormSubmissionError
+}
+
+export interface DetailItemField extends DetailItemBase {
+  /**
+   * Field page controller instance
+   */
+  page: Exclude<PageControllerClass, RepeatPageController>
+
+  /**
+   * Check answers summary list key
+   * For example, 'Date of birth'
+   */
+  title: string
+
+  /**
+   * Check answers summary list value, formatted by {@link getAnswer}
+   * For example, date fields formatted as '25 December 2022'
+   */
+  value: string
+
+  /**
+   * Field component instance
+   */
+  field: Field
+}
+
+export interface DetailItemRepeat extends DetailItemBase {
+  /**
+   * Repeat page controller instance
+   */
+  page: RepeatPageController
+
+  /**
+   * Check answers summary list key
+   * For example, 'Pizza' or 'Pizza added'
+   */
+  title: string
+
+  /**
+   * Check answers summary list value
+   * For example, 'You added 2 Pizzas'
+   */
+  value: string
+
+  /**
+   * Repeater field detail items
+   */
+  subItems: DetailItemField[][]
+}
+
+export type DetailItem = DetailItemField | DetailItemRepeat
+
+/**
+ * Used to render a row on a Summary List (check your answers)
+ */
+export interface Detail {
+  name?: Section['name']
+  title?: Section['title']
+  items: DetailItem[]
+}

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

@@ -0,0 +1,143 @@
+import { addDays, format as dateFormat } from 'date-fns'
+import { outdent } from 'outdent'
+
+import { FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { format } from '~/src/server/plugins/engine/outputFormatters/human/v1.js'
+import {
+  SummaryPageController,
+  getFormSubmissionData
+} from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
+import { type FormContextRequest } from '~/src/server/plugins/engine/types.js'
+import { FormStatus } from '~/src/server/routes/types.js'
+import definition from '~/test/form/definitions/repeat-mixed.js'
+
+const itemId1 = 'abc-123'
+const itemId2 = 'xyz-987'
+
+const submitResponse = {
+  message: 'Submit completed',
+  result: {
+    files: {
+      main: '00000000-0000-0000-0000-000000000000',
+      repeaters: {
+        pizza: '11111111-1111-1111-1111-111111111111'
+      }
+    }
+  }
+}
+
+const model = new FormModel(definition, {
+  basePath: 'test'
+})
+
+const state = {
+  orderType: 'delivery',
+  pizza: [
+    {
+      toppings: 'Ham',
+      quantity: 2,
+      itemId: itemId1
+    },
+    {
+      toppings: 'Pepperoni',
+      quantity: 1,
+      itemId: itemId2
+    }
+  ]
+}
+
+const pageDef = definition.pages[2]
+const pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
+
+const controller = new SummaryPageController(model, pageDef)
+
+const request = {
+  method: 'get',
+  url: pageUrl,
+  path: pageUrl.pathname,
+  params: {
+    path: 'pizza-order',
+    slug: 'repeat'
+  },
+  query: {},
+  app: { model }
+} satisfies FormContextRequest
+
+const context = model.getFormContext(request, state)
+const summaryViewModel = controller.getSummaryViewModel(request, context)
+
+const items = getFormSubmissionData(
+  summaryViewModel.context,
+  summaryViewModel.details
+)
+
+describe('getPersonalisation', () => {
+  it.each([
+    {
+      state: FormStatus.Live,
+      isPreview: false
+    },
+    {
+      state: FormStatus.Draft,
+      isPreview: true
+    }
+  ])('should personalise $state email', (formStatus) => {
+    const body = format(items, model, submitResponse, formStatus)
+
+    const dateNow = new Date()
+    const dateExpiry = addDays(dateNow, 90)
+
+    // Check for link expiry message
+    expect(body).toContain(
+      `^ For security reasons, the links in this email expire at ${dateFormat(dateExpiry, 'h:mmaaa')} on ${dateFormat(dateExpiry, 'eeee d MMMM yyyy')}`
+    )
+
+    // Check for form answers
+    expect(body).toContain(
+      outdent`
+            Form submitted at ${dateFormat(dateNow, 'h:mmaaa')} on ${dateFormat(dateNow, 'd MMMM yyyy')}.
+
+            ---
+
+            ## How would you like to receive your pizza?
+
+            Delivery
+
+            ---
+
+            ## Pizza
+
+            [Download Pizza \\(CSV\\)](https://forms-designer/file-download/11111111-1111-1111-1111-111111111111)
+
+            ---
+
+            [Download main form \\(CSV\\)](https://forms-designer/file-download/00000000-0000-0000-0000-000000000000)
+          `
+    )
+  })
+
+  it('should add test warnings to preview email only', () => {
+    const formStatus = {
+      state: FormStatus.Draft,
+      isPreview: true
+    }
+
+    const body1 = format(items, model, submitResponse, {
+      state: FormStatus.Live,
+      isPreview: false
+    })
+
+    const body2 = format(items, model, submitResponse, {
+      state: FormStatus.Draft,
+      isPreview: true
+    })
+
+    expect(body1).not.toContain(
+      `This is a test of the ${definition.name} ${formStatus.state} form`
+    )
+
+    expect(body2).toContain(
+      `This is a test of the ${definition.name} ${formStatus.state} form`
+    )
+  })
+})

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

@@ -0,0 +1,73 @@
+import { type SubmitResponsePayload } from '@defra/forms-model'
+import { addDays, format as dateFormat } from 'date-fns'
+
+import { config } from '~/src/config/index.js'
+import {
+  escapeMarkdown,
+  getAnswer
+} from '~/src/server/plugins/engine/components/helpers.js'
+import { type checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { type DetailItem } from '~/src/server/plugins/engine/models/types.js'
+
+const designerUrl = config.get('designerUrl')
+
+export function format(
+  items: DetailItem[],
+  model: FormModel,
+  submitResponse: SubmitResponsePayload,
+  formStatus: ReturnType<typeof checkFormStatus>
+) {
+  const { files } = submitResponse.result
+
+  const formName = escapeMarkdown(model.name)
+
+  /**
+   * @todo Refactor this below but the code to
+   * generate the question and answers works for now
+   */
+  const now = new Date()
+  const formattedNow = `${dateFormat(now, 'h:mmaaa')} on ${dateFormat(now, 'd MMMM yyyy')}`
+
+  const fileExpiryDate = addDays(now, 90)
+  const formattedExpiryDate = `${dateFormat(fileExpiryDate, 'h:mmaaa')} on ${dateFormat(fileExpiryDate, 'eeee d MMMM yyyy')}`
+
+  const lines: string[] = []
+
+  lines.push(
+    `^ For security reasons, the links in this email expire at ${escapeMarkdown(formattedExpiryDate)}\n`
+  )
+
+  if (formStatus.isPreview) {
+    lines.push(`This is a test of the ${formName} ${formStatus.state} form.\n`)
+  }
+
+  lines.push(`Form submitted at ${escapeMarkdown(formattedNow)}.\n`)
+  lines.push('---\n')
+
+  items.forEach((item) => {
+    const label = escapeMarkdown(item.label)
+
+    lines.push(`## ${label}\n`)
+
+    if ('subItems' in item) {
+      const filename = escapeMarkdown(`Download ${label} (CSV)`)
+      const fileId = files.repeaters[item.name]
+
+      lines.push(`[${filename}](${designerUrl}/file-download/${fileId})\n`)
+    } else {
+      lines.push(
+        getAnswer(item.field, item.state, {
+          format: 'email'
+        })
+      )
+    }
+
+    lines.push('---\n')
+  })
+
+  const filename = escapeMarkdown('Download main form (CSV)')
+  lines.push(`[${filename}](${designerUrl}/file-download/${files.main})\n`)
+
+  return lines.join('\n')
+}

package/src/server/plugins/engine/outputFormatters/index.test.ts

@@ -0,0 +1,17 @@
+import { format as formatHumanV1 } from '~/src/server/plugins/engine/outputFormatters/human/v1.js'
+import { getFormatter } from '~/src/server/plugins/engine/outputFormatters/index.js'
+
+describe('Page controller helpers', () => {
+  it('should return a valid formatter if it exists', () => {
+    const formatter = getFormatter('human', '1')
+    expect(formatter).toBe(formatHumanV1)
+  })
+
+  it("should return an error if the audience doesn't exist", () => {
+    expect(() => getFormatter('foobar', '1')).toThrow('Unknown audience')
+  })
+
+  it("should return an error if the version doesn't exist", () => {
+    expect(() => getFormatter('human', '9999')).toThrow('Unknown version')
+  })
+})

package/src/server/plugins/engine/outputFormatters/index.ts

@@ -0,0 +1,44 @@
+import { type SubmitResponsePayload } from '@defra/forms-model'
+
+import { type checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { type DetailItem } from '~/src/server/plugins/engine/models/types.js'
+import { format as formatHumanV1 } from '~/src/server/plugins/engine/outputFormatters/human/v1.js'
+import { format as formatMachineV1 } from '~/src/server/plugins/engine/outputFormatters/machine/v1.js'
+import { format as formatMachineV2 } from '~/src/server/plugins/engine/outputFormatters/machine/v2.js'
+
+type Formatter = (
+  items: DetailItem[],
+  model: FormModel,
+  submitResponse: SubmitResponsePayload,
+  formStatus: ReturnType<typeof checkFormStatus>
+) => string
+
+const formatters: Record<
+  string,
+  Record<string, Formatter | undefined> | undefined
+> = {
+  human: {
+    '1': formatHumanV1
+  },
+  machine: {
+    '1': formatMachineV1,
+    '2': formatMachineV2
+  }
+}
+
+export function getFormatter(audience: string, version: string) {
+  const versions = formatters[audience]
+
+  if (!versions) {
+    throw new Error('Unknown audience')
+  }
+
+  const formatter = versions[version]
+
+  if (!formatter) {
+    throw new Error('Unknown version')
+  }
+
+  return formatter
+}