@defra/forms-engine-plugin 0.0.1

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

@@ -0,0 +1,330 @@
+import { ComponentType, type ComponentDef } from '@defra/forms-model'
+import { Marked, type Token } from 'marked'
+
+import { config } from '~/src/config/index.js'
+import { type ComponentBase } from '~/src/server/plugins/engine/components/ComponentBase.js'
+import { ListFormComponent } from '~/src/server/plugins/engine/components/ListFormComponent.js'
+import * as Components from '~/src/server/plugins/engine/components/index.js'
+import { type FormState } from '~/src/server/plugins/engine/types.js'
+
+const designerUrl = config.get('designerUrl')
+
+const markdown = new Marked({
+  breaks: true,
+  gfm: true,
+
+  /**
+   * Render paragraphs without `<p>` wrappers
+   * for check answers summary list `<dd>`
+   */
+  extensions: [
+    {
+      name: 'paragraph',
+      renderer({ tokens = [] }) {
+        const text = this.parser.parseInline(tokens)
+        return tokens.length > 1 ? `${text}<br>` : text
+      }
+    }
+  ],
+
+  /**
+   * Restrict allowed Markdown tokens
+   */
+  walkTokens(token) {
+    const tokens: Token['type'][] = [
+      'br',
+      'escape',
+      'list',
+      'list_item',
+      'paragraph',
+      'space',
+      'text'
+    ]
+
+    if (!tokens.includes(token.type)) {
+      token.type = 'text'
+    }
+  }
+})
+
+// All component instances
+export type Component = InstanceType<
+  (typeof Components)[keyof typeof Components]
+>
+
+// Field component instances only
+export type Field = InstanceType<
+  | typeof Components.AutocompleteField
+  | typeof Components.CheckboxesField
+  | typeof Components.DatePartsField
+  | typeof Components.EmailAddressField
+  | typeof Components.MonthYearField
+  | typeof Components.MultilineTextField
+  | typeof Components.NumberField
+  | typeof Components.SelectField
+  | typeof Components.TelephoneNumberField
+  | typeof Components.TextField
+  | typeof Components.UkAddressField
+  | typeof Components.FileUploadField
+>
+
+// Guidance component instances only
+export type Guidance = InstanceType<
+  | typeof Components.Details
+  | typeof Components.Html
+  | typeof Components.InsetText
+  | typeof Components.List
+>
+
+/**
+ * Create field instance for each {@link ComponentDef} type
+ */
+export function createComponent(
+  def: ComponentDef,
+  options: ConstructorParameters<typeof ComponentBase>[1]
+): Component {
+  let component: Component | undefined
+
+  switch (def.type) {
+    case ComponentType.AutocompleteField:
+      component = new Components.AutocompleteField(def, options)
+      break
+
+    case ComponentType.CheckboxesField:
+      component = new Components.CheckboxesField(def, options)
+      break
+
+    case ComponentType.DatePartsField:
+      component = new Components.DatePartsField(def, options)
+      break
+
+    case ComponentType.Details:
+      component = new Components.Details(def, options)
+      break
+
+    case ComponentType.EmailAddressField:
+      component = new Components.EmailAddressField(def, options)
+      break
+
+    case ComponentType.Html:
+      component = new Components.Html(def, options)
+      break
+
+    case ComponentType.InsetText:
+      component = new Components.InsetText(def, options)
+      break
+
+    case ComponentType.List:
+      component = new Components.List(def, options)
+      break
+
+    case ComponentType.MultilineTextField:
+      component = new Components.MultilineTextField(def, options)
+      break
+
+    case ComponentType.NumberField:
+      component = new Components.NumberField(def, options)
+      break
+
+    case ComponentType.RadiosField:
+      component = new Components.RadiosField(def, options)
+      break
+
+    case ComponentType.SelectField:
+      component = new Components.SelectField(def, options)
+      break
+
+    case ComponentType.TelephoneNumberField:
+      component = new Components.TelephoneNumberField(def, options)
+      break
+
+    case ComponentType.TextField:
+      component = new Components.TextField(def, options)
+      break
+
+    case ComponentType.UkAddressField:
+      component = new Components.UkAddressField(def, options)
+      break
+
+    case ComponentType.YesNoField:
+      component = new Components.YesNoField(def, options)
+      break
+
+    case ComponentType.MonthYearField:
+      component = new Components.MonthYearField(def, options)
+      break
+
+    case ComponentType.FileUploadField:
+      component = new Components.FileUploadField(def, options)
+      break
+  }
+
+  if (typeof component === 'undefined') {
+    throw new Error(`Component type ${def.type} does not exist`)
+  }
+
+  return component
+}
+
+/**
+ * Get formatted answer for a field
+ */
+export function getAnswer(
+  field: Field,
+  state: FormState,
+  options: {
+    format:
+      | 'data' // Submission data
+      | 'email' // GOV.UK Notify emails
+      | 'summary' // Check answers summary
+  } = { format: 'summary' }
+) {
+  // Use escaped display text for GOV.UK Notify emails
+  if (options.format === 'email') {
+    return getAnswerMarkdown(field, state, { format: 'email' })
+  }
+
+  // Use context value for submission data
+  if (options.format === 'data') {
+    const context = field.getContextValueFromState(state)
+    return context?.toString() ?? ''
+  }
+
+  // Use display HTML for check answers summary (multi line)
+  if (
+    field instanceof ListFormComponent ||
+    field instanceof Components.MultilineTextField ||
+    field instanceof Components.UkAddressField
+  ) {
+    return markdown
+      .parse(getAnswerMarkdown(field, state), { async: false })
+      .trim()
+  }
+
+  // Use display text for check answers summary (single line)
+  return field.getDisplayStringFromState(state)
+}
+
+/**
+ * Get formatted answer for a field (Markdown only)
+ */
+export function getAnswerMarkdown(
+  field: Field,
+  state: FormState,
+  options: {
+    format:
+      | 'email' // GOV.UK Notify emails
+      | 'summary' // Check answers summary
+  } = { format: 'summary' }
+) {
+  const answer = field.getDisplayStringFromState(state)
+
+  // Use escaped display text
+  let answerEscaped = `${escapeMarkdown(answer)}\n`
+
+  if (field instanceof Components.FileUploadField) {
+    const files = field.getFormValueFromState(state)
+
+    // Skip empty files
+    if (!files?.length) {
+      return answerEscaped
+    }
+
+    answerEscaped = `${escapeMarkdown(answer)}:\n\n`
+
+    // Append bullet points
+    answerEscaped += files
+      .map(({ status }) => {
+        const { file } = status.form
+        const filename = escapeMarkdown(file.filename)
+        return `* [${filename}](${designerUrl}/file-download/${file.fileId})\n`
+      })
+      .join('')
+  } else if (field instanceof ListFormComponent) {
+    const values = [field.getContextValueFromState(state)].flat()
+    const items = field.items.filter(({ value }) => values.includes(value))
+
+    // Skip empty values
+    if (!items.length) {
+      return answerEscaped
+    }
+
+    answerEscaped = ''
+
+    // Append bullet points
+    answerEscaped += items
+      .map((item) => {
+        const label = escapeMarkdown(item.text)
+        const value = escapeMarkdown(`(${item.value})`)
+
+        let line = label
+
+        // Prepend bullet points for checkboxes only
+        if (field instanceof Components.CheckboxesField) {
+          line = `* ${line}`
+        }
+
+        // Append raw values in parentheses
+        // e.g. `* None of the above (false)`
+        return options.format === 'email' &&
+          `${item.value}`.toLowerCase() !== item.text.toLowerCase()
+          ? `${line} ${value}\n`
+          : `${line}\n`
+      })
+      .join('')
+  } else if (field instanceof Components.MultilineTextField) {
+    // Preserve Multiline text new lines
+    answerEscaped = answer
+      .split(/\r?\n/)
+      .map(escapeMarkdown)
+      .join('\n')
+      .concat('\n')
+  } else if (field instanceof Components.UkAddressField) {
+    // Format UK addresses into new lines
+    answerEscaped = (field.getContextValueFromState(state) ?? [])
+      .map(escapeMarkdown)
+      .join('\n')
+      .concat('\n')
+  }
+
+  return answerEscaped
+}
+
+/**
+ * Prevent Markdown formatting
+ * @see {@link https://pandoc.org/chunkedhtml-demo/8.11-backslash-escapes.html}
+ */
+export function escapeMarkdown(answer: string) {
+  const punctuation = [
+    '`',
+    "'",
+    '*',
+    '_',
+    '{',
+    '}',
+    '[',
+    ']',
+    '(',
+    ')',
+    '#',
+    '+',
+    '-',
+    '.',
+    '!'
+  ]
+
+  for (const character of punctuation) {
+    answer = answer.toString().replaceAll(character, `\\${character}`)
+  }
+
+  return answer
+}
+
+export const addClassOptionIfNone = (
+  options: Extract<ComponentDef, { options: { classes?: string } }>['options'],
+  className: string
+) => {
+  if (!options.classes) {
+    options.classes = className
+  }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * IMPORTANT: Exported Components must follow the naming convention implemented in {@link @defra/forms-model#ComponentType}
+ * In the Form JSON, components have a type property which is the name of the components, e.g. DatePartsField.
+ * Components are loaded in the ComponentsCollection constructor.
+ */
+
+export { AutocompleteField } from '~/src/server/plugins/engine/components/AutocompleteField.js'
+export { CheckboxesField } from '~/src/server/plugins/engine/components/CheckboxesField.js'
+export { DatePartsField } from '~/src/server/plugins/engine/components/DatePartsField.js'
+export { Details } from '~/src/server/plugins/engine/components/Details.js'
+export { EmailAddressField } from '~/src/server/plugins/engine/components/EmailAddressField.js'
+export { Html } from '~/src/server/plugins/engine/components/Html.js'
+export { InsetText } from '~/src/server/plugins/engine/components/InsetText.js'
+export { List } from '~/src/server/plugins/engine/components/List.js'
+export { MultilineTextField } from '~/src/server/plugins/engine/components/MultilineTextField.js'
+export { NumberField } from '~/src/server/plugins/engine/components/NumberField.js'
+export { RadiosField } from '~/src/server/plugins/engine/components/RadiosField.js'
+export { SelectField } from '~/src/server/plugins/engine/components/SelectField.js'
+export { TelephoneNumberField } from '~/src/server/plugins/engine/components/TelephoneNumberField.js'
+export { TextField } from '~/src/server/plugins/engine/components/TextField.js'
+export { UkAddressField } from '~/src/server/plugins/engine/components/UkAddressField.js'
+export { YesNoField } from '~/src/server/plugins/engine/components/YesNoField.js'
+export { MonthYearField } from '~/src/server/plugins/engine/components/MonthYearField.js'
+export { FileUploadField } from '~/src/server/plugins/engine/components/FileUploadField.js'

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

@@ -0,0 +1,117 @@
+import { type ComponentType, type Item } from '@defra/forms-model'
+
+import {
+  type FormSubmissionError,
+  type FormValue,
+  type SummaryList
+} from '~/src/server/plugins/engine/types.js'
+
+export type ComponentText = {
+  classes?: string
+  attributes?: string | Record<string, string>
+} & (
+  | {
+      text: string
+      html?: string
+    }
+  | {
+      text?: string
+      html: string
+    }
+)
+
+export interface Label {
+  text: string
+  classes?: string
+  html?: string
+  isPageHeading?: boolean
+}
+
+export interface Content {
+  title?: string
+  text: string
+  condition?: string
+}
+
+export interface BackLink {
+  text: string
+  href: string
+}
+
+export type ListItemLabel = Omit<Label, 'text' | 'isPageHeading'>
+
+export interface ListItem {
+  text?: string
+  value?: Item['value']
+  hint?: {
+    id?: string
+    text: string
+  }
+  checked?: boolean
+  selected?: boolean
+  label?: ListItemLabel
+  condition?: string
+}
+
+export interface DateInputItem {
+  label?: Label
+  type?: string
+  id?: string
+  name?: string
+  value?: Item['value']
+  classes?: string
+  condition?: undefined
+}
+
+export interface ViewModel extends Record<string, unknown> {
+  label?: Label
+  type?: string
+  id?: string
+  name?: string
+  value?: FormValue
+  hint?: {
+    id?: string
+    text: string
+  }
+  prefix?: ComponentText
+  suffix?: ComponentText
+  classes?: string
+  condition?: string
+  errors?: FormSubmissionError[]
+  errorMessage?: {
+    text: string
+  }
+  summaryHtml?: string
+  html?: string
+  attributes: {
+    autocomplete?: string
+    maxlength?: number
+    multiple?: string
+    accept?: string
+    inputmode?: string
+  }
+  content?: Content | Content[] | string
+  maxlength?: number
+  maxwords?: number
+  rows?: number
+  items?: ListItem[] | DateInputItem[]
+  fieldset?: {
+    attributes?: string | Record<string, string>
+    legend?: Label
+  }
+  formGroup?: {
+    classes?: string
+    attributes?: string | Record<string, string>
+  }
+  components?: ComponentViewModel[]
+  upload?: {
+    count: number
+    summaryList: SummaryList
+  }
+}
+
+export interface ComponentViewModel {
+  type: ComponentType
+  isFormComponent: boolean
+  model: ViewModel
+}

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

@@ -0,0 +1,47 @@
+import { join, parse } from 'node:path'
+
+import { type FormDefinition } from '@defra/forms-model'
+import { type ServerRegisterPluginObject } from '@hapi/hapi'
+
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import {
+  plugin,
+  type PluginOptions
+} from '~/src/server/plugins/engine/plugin.js'
+import { type RouteConfig } from '~/src/server/types.js'
+
+export const configureEnginePlugin = async ({
+  formFileName,
+  formFilePath,
+  services,
+  controllers
+}: RouteConfig = {}): Promise<ServerRegisterPluginObject<PluginOptions>> => {
+  let model: FormModel | undefined
+
+  if (formFileName && formFilePath) {
+    const definition = await getForm(join(formFilePath, formFileName))
+    const { name } = parse(formFileName)
+
+    model = new FormModel(definition, { basePath: name }, services, controllers)
+  }
+
+  return {
+    plugin,
+    options: { model, services, controllers }
+  }
+}
+
+export async function getForm(importPath: string) {
+  const { ext } = parse(importPath)
+
+  const attributes: ImportAttributes = {
+    type: ext === '.json' ? 'json' : 'module'
+  }
+
+  const formImport = import(importPath, { with: attributes }) as Promise<{
+    default: FormDefinition
+  }>
+
+  const { default: definition } = await formImport
+  return definition
+}