@defra/forms-engine-plugin 0.0.4 → 0.0.6

package/src/server/plugins/nunjucks/environment.js

@@ -0,0 +1,116 @@
+import { dirname, join } from 'node:path'
+
+import { ComponentType } from '@defra/forms-model'
+import nunjucks from 'nunjucks'
+import resolvePkg from 'resolve'
+
+import { config } from '~/src/config/index.js'
+import { evaluateTemplate } from '~/src/server/plugins/engine/helpers.js'
+import * as filters from '~/src/server/plugins/nunjucks/filters/index.js'
+
+const govukFrontendPath = dirname(
+  resolvePkg.sync('govuk-frontend/package.json')
+)
+
+export const paths = [
+  join(config.get('appDir'), 'plugins/engine/views'),
+  join(config.get('appDir'), 'views')
+]
+
+export const environment = nunjucks.configure(
+  [...paths, join(govukFrontendPath, 'dist')],
+  {
+    trimBlocks: true,
+    lstripBlocks: true,
+    watch: config.get('isDevelopment'),
+    noCache: config.get('isDevelopment')
+  }
+)
+
+for (const [name, nunjucksFilter] of Object.entries(filters)) {
+  environment.addFilter(name, nunjucksFilter)
+}
+
+/**
+ * @this {NunjucksContext}
+ * @param {FormSubmissionError[]} errors
+ */
+export function checkErrorTemplates(errors) {
+  const { context } = this.ctx
+
+  if (!context) {
+    return errors
+  }
+
+  errors.forEach((error) => {
+    error.text = evaluateTemplate(error.text, context)
+  })
+
+  return errors
+}
+
+environment.addGlobal('checkErrorTemplates', checkErrorTemplates)
+
+/**
+ * @this {NunjucksContext}
+ * @param {ComponentViewModel} component
+ */
+export function checkComponentTemplates(component) {
+  const { context } = this.ctx
+
+  if (!context) {
+    return component
+  }
+
+  if (component.isFormComponent) {
+    // Evaluate label/legend text
+    if (component.model.fieldset?.legend?.text) {
+      const legend = component.model.fieldset.legend
+
+      legend.text = evaluateTemplate(legend.text, context)
+    } else if (component.model.label?.text) {
+      const label = component.model.label
+
+      label.text = evaluateTemplate(label.text, context)
+    } else {
+      // No template evaluation needed for other component types
+    }
+
+    // Evaluate error message
+    if (component.model.errorMessage?.text) {
+      const message = component.model.errorMessage
+
+      message.text = evaluateTemplate(message.text, context)
+    }
+  } else if (component.type === ComponentType.Html) {
+    const content = component.model.content
+
+    if (typeof content === 'string') {
+      component.model.content = evaluateTemplate(content, context)
+    }
+  } else {
+    // No template evaluation needed for other component types
+  }
+
+  return component
+}
+
+environment.addGlobal('checkComponentTemplates', checkComponentTemplates)
+
+/**
+ * @this {NunjucksContext}
+ * @param {string} template
+ */
+export function evaluate(template) {
+  const { context } = this.ctx
+
+  return context ? evaluateTemplate(template, context) : template
+}
+
+environment.addGlobal('evaluate', evaluate)
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ * @import { FormSubmissionError } from '~/src/server/plugins/engine/types.js'
+ * @import { ComponentViewModel } from '~/src/server/plugins/engine/components/types.js'
+ */

package/src/server/plugins/nunjucks/filters/answer.js

@@ -0,0 +1,27 @@
+import { getAnswer } from '~/src/server/plugins/engine/components/helpers.js'
+
+/**
+ * Nunjucks filter to get the answer for a component
+ * @this {NunjucksContext}
+ * @param {string} name - The name of the component to check
+ */
+export function answer(name) {
+  const { context } = this.ctx
+
+  if (!context) {
+    return undefined
+  }
+
+  const component = context.componentMap.get(name)
+
+  if (!component?.isFormComponent) {
+    return undefined
+  }
+
+  return getAnswer(/** @type {Field} */ (component), context.relevantState)
+}
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ * @import { Field } from '~/src/server/plugins/engine/components/helpers.js'
+ */

package/src/server/plugins/nunjucks/filters/answer.test.js

@@ -0,0 +1,89 @@
+import { getAnswer } from '~/src/server/plugins/engine/components/helpers.js'
+import { answer } from '~/src/server/plugins/nunjucks/filters/answer.js'
+
+jest.mock('~/src/server/plugins/engine/components/helpers.ts', () => ({
+  getAnswer: jest.fn()
+}))
+
+describe('answer Nunjucks filter', () => {
+  /** @type { NunjucksContext } */
+  let mockThis
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+
+    mockThis = /** @type {NunjucksContext} */ (
+      /** @type {unknown} */ ({
+        ctx: {
+          context: {
+            componentMap: new Map(),
+            relevantState: { someState: 'value' }
+          }
+        }
+      })
+    )
+
+    jest.mocked(getAnswer).mockReturnValue('test answer')
+  })
+
+  describe('missing context', () => {
+    it('returns undefined', () => {
+      mockThis.ctx.context = undefined
+
+      const result = answer.call(mockThis, 'componentName')
+
+      expect(result).toBeUndefined()
+      expect(getAnswer).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('component lookup', () => {
+    it('returns undefined for non-existent component', () => {
+      const result = answer.call(mockThis, 'nonExistentComponent')
+
+      expect(result).toBeUndefined()
+      expect(getAnswer).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('non-form component', () => {
+    it('returns undefined', () => {
+      mockThis.ctx.context?.componentMap.set(
+        'nonFormComponent',
+        // @ts-expect-error - simplified mock component for testing
+        { isFormComponent: false }
+      )
+
+      const result = answer.call(mockThis, 'nonFormComponent')
+
+      expect(result).toBeUndefined()
+      expect(getAnswer).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('valid form component', () => {
+    it('returns the answer', () => {
+      const mockFormComponent = {
+        isFormComponent: true,
+        someProperty: 'value'
+      }
+      mockThis.ctx.context?.componentMap.set(
+        'validFormComponent',
+        // @ts-expect-error - simplified mock component for testing
+        mockFormComponent
+      )
+
+      const result = answer.call(mockThis, 'validFormComponent')
+
+      expect(getAnswer).toHaveBeenCalledWith(
+        mockFormComponent,
+        mockThis.ctx.context?.relevantState
+      )
+      expect(result).toBe('test answer')
+    })
+  })
+})
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ */

package/src/server/plugins/nunjucks/filters/evaluate.js

@@ -0,0 +1,21 @@
+import { evaluateTemplate } from '~/src/server/plugins/engine/helpers.js'
+
+/**
+ * Nunjucks filter to evaluate a liquid template.
+ * Currently just used in `src/server/views/layout.html#LN37` for the pageTitle
+ * @this {NunjucksContext}
+ * @param {string} template
+ */
+export function evaluate(template) {
+  const { context } = this.ctx
+
+  if (!context || typeof template !== 'string') {
+    return template
+  }
+
+  return evaluateTemplate(template, context)
+}
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ */

package/src/server/plugins/nunjucks/filters/field.js

@@ -0,0 +1,28 @@
+/**
+ * Nunjucks filter to get the answer for a component
+ * @this {NunjucksContext}
+ * @param {string} name - The name of the component
+ */
+export function field(name) {
+  if (typeof name !== 'string') {
+    return undefined
+  }
+
+  const { context } = this.ctx
+
+  if (!context) {
+    return undefined
+  }
+
+  const component = context.componentMap.get(name)
+
+  if (!component?.isFormComponent) {
+    return undefined
+  }
+
+  return component
+}
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ */

package/src/server/plugins/nunjucks/filters/field.test.js

@@ -0,0 +1,75 @@
+import { field } from '~/src/server/plugins/nunjucks/filters/field.js'
+
+describe('field Nunjucks filter', () => {
+  /** @type {NunjucksContext} */
+  let mockThis
+
+  beforeEach(() => {
+    mockThis = /** @type {NunjucksContext} */ (
+      /** @type {unknown} */ ({
+        ctx: {
+          context: {
+            componentMap: new Map()
+          }
+        }
+      })
+    )
+  })
+
+  describe('invalid inputs', () => {
+    it('returns undefined for non-string name parameter', () => {
+      // @ts-expect-error - testing invalid input
+      const result = field.call(mockThis, 123)
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('missing context', () => {
+    it('returns undefined', () => {
+      mockThis.ctx.context = undefined
+      const result = field.call(mockThis, 'componentName')
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('component lookup', () => {
+    it('returns undefined for non-existent component', () => {
+      const result = field.call(mockThis, 'nonExistentComponent')
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('non-form component', () => {
+    it('returns undefined', () => {
+      mockThis.ctx.context?.componentMap.set(
+        'nonFormComponent',
+        // @ts-expect-error - simplified mock component for testing
+        { isFormComponent: false }
+      )
+
+      const result = field.call(mockThis, 'nonFormComponent')
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('valid form component', () => {
+    it('returns the component', () => {
+      const mockFormComponent = {
+        isFormComponent: true,
+        someProperty: 'value'
+      }
+      mockThis.ctx.context?.componentMap.set(
+        'validFormComponent',
+        // @ts-expect-error - simplified mock component for testing
+        mockFormComponent
+      )
+
+      const result = field.call(mockThis, 'validFormComponent')
+      expect(result).toBe(mockFormComponent)
+    })
+  })
+})
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ */

package/src/server/plugins/nunjucks/filters/highlight.js

@@ -0,0 +1,11 @@
+import hljs from 'highlight.js'
+
+/**
+ * Format code with syntax highlighting
+ * @param {string} code - Code in plain text
+ * @param {string} [language] - Code programming language
+ * @returns {string} Code with syntax highlighting
+ */
+export function highlight(code, language) {
+  return hljs.highlight(code, { language: language ?? 'plaintext' }).value
+}

package/src/server/plugins/nunjucks/filters/href.js

@@ -0,0 +1,30 @@
+import { getPageHref } from '~/src/server/plugins/engine/index.js'
+
+/**
+ * Nunjucks filter to get the answer for a component
+ * @this {NunjucksContext}
+ * @param {string} path - The name of the component
+ */
+export function href(path) {
+  if (typeof path !== 'string') {
+    return undefined
+  }
+
+  const { context } = this.ctx
+
+  if (!context) {
+    return undefined
+  }
+
+  const page = context.pageMap.get(path)
+
+  if (page === undefined) {
+    return undefined
+  }
+
+  return getPageHref(page)
+}
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ */

package/src/server/plugins/nunjucks/filters/href.test.js

@@ -0,0 +1,80 @@
+import { getPageHref } from '~/src/server/plugins/engine/index.js'
+import { href } from '~/src/server/plugins/nunjucks/filters/href.js'
+
+jest.mock('~/src/server/plugins/engine/index.ts', () => ({
+  getPageHref: jest.fn()
+}))
+
+describe('href Nunjucks filter', () => {
+  /** @type { NunjucksContext } */
+  let mockThis
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+
+    mockThis = /** @type {NunjucksContext} */ (
+      /** @type {unknown} */ ({
+        ctx: {
+          context: {
+            pageMap: new Map()
+          }
+        }
+      })
+    )
+
+    jest.mocked(getPageHref).mockReturnValue('/some-page')
+  })
+
+  describe('invalid inputs', () => {
+    it('returns undefined for non-string path parameter', () => {
+      // @ts-expect-error - testing invalid input
+      const result = href.call(mockThis, 123)
+
+      expect(result).toBeUndefined()
+      expect(getPageHref).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('missing context', () => {
+    it('returns undefined', () => {
+      mockThis.ctx.context = undefined
+
+      const result = href.call(mockThis, 'pagePath')
+
+      expect(result).toBeUndefined()
+      expect(getPageHref).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('page lookup', () => {
+    it('returns undefined for non-existent page', () => {
+      const result = href.call(mockThis, 'nonExistentPage')
+
+      expect(result).toBeUndefined()
+      expect(getPageHref).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('valid page', () => {
+    it('returns the href for the page', () => {
+      const mockPage = {
+        path: '/some-page',
+        someProperty: 'value'
+      }
+      mockThis.ctx.context?.pageMap.set(
+        'validPage',
+        // @ts-expect-error - simplified mock page for testing
+        mockPage
+      )
+
+      const result = href.call(mockThis, 'validPage')
+
+      expect(getPageHref).toHaveBeenCalledWith(mockPage)
+      expect(result).toBe('/some-page')
+    })
+  })
+})
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ */

package/src/server/plugins/nunjucks/filters/index.js

@@ -0,0 +1,8 @@
+export { markdownToHtml as markdown } from '@defra/forms-model'
+export { highlight } from '~/src/server/plugins/nunjucks/filters/highlight.js'
+export { inspect } from '~/src/server/plugins/nunjucks/filters/inspect.js'
+export { evaluate } from '~/src/server/plugins/nunjucks/filters/evaluate.js'
+export { answer } from '~/src/server/plugins/nunjucks/filters/answer.js'
+export { href } from '~/src/server/plugins/nunjucks/filters/href.js'
+export { field } from '~/src/server/plugins/nunjucks/filters/field.js'
+export { page } from '~/src/server/plugins/nunjucks/filters/page.js'

package/src/server/plugins/nunjucks/filters/inspect.js

@@ -0,0 +1,15 @@
+import util from 'util'
+
+/**
+ * Format JavaScript objects as strings
+ * @param {unknown} object - JavaScript object to format
+ * @returns {string} Formatted string
+ */
+export function inspect(object) {
+  return util.inspect(object, {
+    compact: false,
+    depth: Infinity,
+    maxArrayLength: Infinity,
+    maxStringLength: Infinity
+  })
+}

package/src/server/plugins/nunjucks/filters/page.js

@@ -0,0 +1,24 @@
+/**
+ * Nunjucks filter to get the page for a given path
+ * @this {NunjucksContext}
+ * @param {string} path - The path of the page
+ */
+export function page(path) {
+  if (typeof path !== 'string') {
+    return undefined
+  }
+
+  const { context } = this.ctx
+
+  if (!context) {
+    return undefined
+  }
+
+  const foundPage = context.pageMap.get(path)
+
+  return foundPage
+}
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ */

package/src/server/plugins/nunjucks/filters/page.test.js

@@ -0,0 +1,65 @@
+import { page } from '~/src/server/plugins/nunjucks/filters/page.js'
+
+describe('page Nunjucks filter', () => {
+  /** @type { NunjucksContext } */
+  let mockThis
+
+  beforeEach(() => {
+    mockThis = /** @type {NunjucksContext} */ (
+      /** @type {unknown} */ ({
+        ctx: {
+          context: {
+            pageMap: new Map()
+          }
+        }
+      })
+    )
+  })
+
+  describe('invalid inputs', () => {
+    it('returns undefined for non-string path parameter', () => {
+      // @ts-expect-error - testing invalid input
+      const result = page.call(mockThis, 123)
+
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('missing context', () => {
+    it('returns undefined', () => {
+      mockThis.ctx.context = undefined
+
+      const result = page.call(mockThis, 'pagePath')
+
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('page lookup', () => {
+    it('returns undefined for non-existent page', () => {
+      const result = page.call(mockThis, 'nonExistentPage')
+
+      expect(result).toBeUndefined()
+    })
+
+    it('returns the page when found', () => {
+      const mockPage = {
+        path: '/some-page',
+        someProperty: 'value'
+      }
+      mockThis.ctx.context?.pageMap.set(
+        'validPage',
+        // @ts-expect-error - simplified mock page for testing
+        mockPage
+      )
+
+      const result = page.call(mockThis, 'validPage')
+
+      expect(result).toBe(mockPage)
+    })
+  })
+})
+
+/**
+ * @import { NunjucksContext } from '~/src/server/plugins/nunjucks/types.js'
+ */

package/src/server/plugins/nunjucks/index.js

@@ -0,0 +1,3 @@
+export * as render from '~/src/server/plugins/nunjucks/render.js'
+export { environment } from '~/src/server/plugins/nunjucks/environment.js'
+export { plugin } from '~/src/server/plugins/nunjucks/plugin.js'

package/src/server/plugins/nunjucks/plugin.js

@@ -0,0 +1,40 @@
+import vision from '@hapi/vision'
+import nunjucks from 'nunjucks'
+
+import { config } from '~/src/config/index.js'
+import { context } from '~/src/server/plugins/nunjucks/context.js'
+import {
+  environment,
+  paths
+} from '~/src/server/plugins/nunjucks/environment.js'
+
+/**
+ * @type {ServerRegisterPluginObject<ServerViewsConfiguration>}
+ */
+export const plugin = {
+  plugin: vision,
+  options: {
+    engines: {
+      html: {
+        /**
+         * @param {string} path
+         * @param {{ environment: typeof environment }} compileOptions
+         * @returns {(options: ReturnType<Awaited<typeof context>>) => string}
+         */
+        compile(path, compileOptions) {
+          return (options) =>
+            nunjucks.compile(path, compileOptions.environment).render(options)
+        }
+      }
+    },
+    path: paths,
+    compileOptions: { environment },
+    isCached: config.get('isProduction'),
+    context
+  }
+}
+
+/**
+ * @import { ServerRegisterPluginObject } from '@hapi/hapi'
+ * @import { ServerViewsConfiguration } from '@hapi/vision'
+ */

package/src/server/plugins/nunjucks/render.js

@@ -0,0 +1,42 @@
+import { environment } from '~/src/server/plugins/nunjucks/environment.js'
+
+/**
+ * Render Nunjucks macro
+ * @param {string} macroName
+ * @param {string} macroPath
+ * @param {RenderOptions & MacroOptions} [options]
+ */
+export function macro(macroName, macroPath, options) {
+  const macroParams = JSON.stringify(options?.params, undefined, 2)
+  let macroString = `{%- from "${macroPath}" import ${macroName} -%}`
+
+  if (options?.callBlock) {
+    macroString += `{%- call ${macroName}(${macroParams}) -%}${options.callBlock}{%- endcall -%}`
+  } else {
+    macroString += `{{- ${macroName}(${macroParams}) -}}`
+  }
+
+  return string(macroString, options)
+}
+
+/**
+ * Render Nunjucks code
+ * @param {string} viewString - Nunjucks string to render
+ * @param {RenderOptions} [options]
+ */
+export function string(viewString, options) {
+  return environment.renderString(viewString, options?.context ?? {})
+}
+
+/**
+ * Render Nunjucks view
+ * @param {string} viewPath
+ * @param {RenderOptions} [options]
+ */
+export function view(viewPath, options) {
+  return environment.render(viewPath, options?.context)
+}
+
+/**
+ * @import { MacroOptions, RenderOptions } from '~/src/server/plugins/nunjucks/types.js'
+ */