@defra/forms-engine-plugin 0.0.1

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'
+ */

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

@@ -0,0 +1,40 @@
+/**
+ * @typedef {object} MacroOptions
+ * @property {string} [callBlock] - Nunjucks call block content
+ * @property {object} [params] - Nunjucks macro params
+ */
+
+/**
+ * @typedef {object} RenderOptions
+ * @property {object} [context] - Nunjucks render context
+ */
+
+/**
+ * @typedef {object} ViewContext - Nunjucks view context
+ * @property {string} appVersion - Application version
+ * @property {string} assetPath - Asset path
+ * @property {Partial<Config>} config - Application config properties
+ * @property {CookieConsent} [cookieConsent] - Cookie consent preferences
+ * @property {string} [crumb] - Cross-Site Request Forgery (CSRF) token
+ * @property {string} [cspNonce] - Content Security Policy (CSP) nonce
+ * @property {string} [currentPath] - Current path
+ * @property {string} [previewMode] - Preview mode
+ * @property {string} [slug] - Form slug
+ * @property {(asset?: string) => string} getAssetPath - Asset path resolver
+ * @property {FormContext} [context] - the current form context
+ */
+
+/**
+ * @typedef {ReturnType<typeof config['getProperties']>} Config - Application config properties
+ */
+
+/**
+ * @typedef NunjucksContext
+ * @property {ViewContext} ctx - the current nunjucks view context
+ */
+
+/**
+ * @import { CookieConsent } from '~/src/common/types.js'
+ * @import { config } from '~/src/config/index.js'
+ * @import { FormContext } from '~/src/server/plugins/engine/types.js'
+ */

package/src/server/plugins/pulse.ts

@@ -0,0 +1,11 @@
+import { type ServerRegisterPluginObject } from '@hapi/hapi'
+import pulse from 'hapi-pulse'
+
+export default {
+  plugin: pulse,
+  options: {
+    timeout: 800
+  }
+} satisfies ServerRegisterPluginObject<{
+  timeout: number
+}>