@defra/forms-engine-plugin 3.0.9 → 4.0.1

package/src/server/plugins/engine/routes/repeaters/summary.test.ts

@@ -0,0 +1,75 @@
+import { getRoutes } from '~/src/server/plugins/engine/routes/repeaters/summary.js'
+import { type OnRequestCallback } from '~/src/server/plugins/engine/types.js'
+
+describe('repeater summary routes', () => {
+  describe('route configuration', () => {
+    it('should return all expected routes', () => {
+      const routes = getRoutes({}, {}, undefined)
+
+      expect(routes).toHaveLength(4)
+
+      const expectedPaths = [
+        '/{slug}/{path}/summary',
+        '/preview/{state}/{slug}/{path}/summary'
+      ]
+
+      expectedPaths.forEach((path) => {
+        const getRoute = routes.find(
+          (route) => route.method === 'get' && route.path === path
+        )
+        const postRoute = routes.find(
+          (route) => route.method === 'post' && route.path === path
+        )
+
+        expect(getRoute).toBeDefined()
+        expect(postRoute).toBeDefined()
+      })
+    })
+
+    it('should pass onRequest callback to handlers', () => {
+      const onRequestCallback: OnRequestCallback = jest
+        .fn()
+        .mockResolvedValue(undefined)
+      const routes = getRoutes({}, {}, onRequestCallback)
+
+      // Test that the handlers are created with the onRequest callback
+      const getRoute = routes.find(
+        (route) =>
+          route.method === 'get' && route.path === '/{slug}/{path}/summary'
+      )
+      const postRoute = routes.find(
+        (route) =>
+          route.method === 'post' && route.path === '/{slug}/{path}/summary'
+      )
+
+      expect(getRoute?.handler).toBeDefined()
+      expect(postRoute?.handler).toBeDefined()
+    })
+  })
+
+  describe('handler functionality', () => {
+    it('should create handlers that accept onRequest callback', () => {
+      const onRequestCallback: OnRequestCallback = jest
+        .fn()
+        .mockResolvedValue(undefined)
+      const routes = getRoutes({}, {}, onRequestCallback)
+
+      // Test that the handlers are created with the onRequest callback
+      const getRoute = routes.find(
+        (route) =>
+          route.method === 'get' && route.path === '/{slug}/{path}/summary'
+      )
+      const postRoute = routes.find(
+        (route) =>
+          route.method === 'post' && route.path === '/{slug}/{path}/summary'
+      )
+
+      expect(getRoute?.handler).toBeDefined()
+      expect(postRoute?.handler).toBeDefined()
+
+      // Test that handlers are functions
+      expect(typeof getRoute?.handler).toBe('function')
+      expect(typeof postRoute?.handler).toBe('function')
+    })
+  })
+})

package/src/server/plugins/engine/routes/repeaters/summary.ts

@@ -6,6 +6,7 @@ import Joi from 'joi'
 
 import { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
 import { redirectOrMakeHandler } from '~/src/server/plugins/engine/routes/index.js'
+import { type OnRequestCallback } from '~/src/server/plugins/engine/types.js'
 import {
   type FormRequest,
   type FormRequestPayload,
@@ -20,41 +21,46 @@ import {
   stateSchema
 } from '~/src/server/schemas/index.js'
 
-function getHandler(request: FormRequest, h: FormResponseToolkit) {
-  const { params } = request
+function getHandler(onRequest?: OnRequestCallback) {
+  return async function (request: FormRequest, h: FormResponseToolkit) {
+    const { params } = request
 
-  return redirectOrMakeHandler(request, h, (page, context) => {
-    if (!(page instanceof RepeatPageController)) {
-      throw Boom.notFound(`No repeater page found for /${params.path}`)
-    }
+    return redirectOrMakeHandler(request, h, onRequest, (page, context) => {
+      if (!(page instanceof RepeatPageController)) {
+        throw Boom.notFound(`No repeater page found for /${params.path}`)
+      }
 
-    return page.makeGetListSummaryRouteHandler()(request, context, h)
-  })
+      return page.makeGetListSummaryRouteHandler()(request, context, h)
+    })
+  }
 }
 
-function postHandler(request: FormRequestPayload, h: FormResponseToolkit) {
-  const { params } = request
+function postHandler(onRequest?: OnRequestCallback) {
+  return async function (request: FormRequestPayload, h: FormResponseToolkit) {
+    const { params } = request
 
-  return redirectOrMakeHandler(request, h, (page, context) => {
-    const { isForceAccess } = context
+    return redirectOrMakeHandler(request, h, onRequest, (page, context) => {
+      const { isForceAccess } = context
 
-    if (isForceAccess || !(page instanceof RepeatPageController)) {
-      throw Boom.notFound(`No repeater page found for /${params.path}`)
-    }
+      if (isForceAccess || !(page instanceof RepeatPageController)) {
+        throw Boom.notFound(`No repeater page found for /${params.path}`)
+      }
 
-    return page.makePostListSummaryRouteHandler()(request, context, h)
-  })
+      return page.makePostListSummaryRouteHandler()(request, context, h)
+    })
+  }
 }
 
 export function getRoutes(
   getRouteOptions: RouteOptions<FormRequestRefs>,
-  postRouteOptions: RouteOptions<FormRequestPayloadRefs>
+  postRouteOptions: RouteOptions<FormRequestPayloadRefs>,
+  onRequest?: OnRequestCallback
 ): (ServerRoute<FormRequestRefs> | ServerRoute<FormRequestPayloadRefs>)[] {
   return [
     {
       method: 'get',
       path: '/{slug}/{path}/summary',
-      handler: getHandler,
+      handler: getHandler(onRequest),
       options: {
         ...getRouteOptions,
         validate: {
@@ -69,7 +75,7 @@ export function getRoutes(
     {
       method: 'get',
       path: '/preview/{state}/{slug}/{path}/summary',
-      handler: getHandler,
+      handler: getHandler(onRequest),
       options: {
         ...getRouteOptions,
         validate: {
@@ -85,7 +91,7 @@ export function getRoutes(
     {
       method: 'post',
       path: '/{slug}/{path}/summary',
-      handler: postHandler,
+      handler: postHandler(onRequest),
       options: {
         ...postRouteOptions,
         validate: {
@@ -106,7 +112,7 @@ export function getRoutes(
     {
       method: 'post',
       path: '/preview/{state}/{slug}/{path}/summary',
-      handler: postHandler,
+      handler: postHandler(onRequest),
       options: {
         ...postRouteOptions,
         validate: {

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

@@ -1,12 +1,11 @@
 import {
   type ComponentDef,
   type Event,
-  type FormDefinition,
-  type FormMetadata,
   type FormVersionMetadata,
   type Item,
   type List,
-  type Page
+  type Page,
+  type UkAddressFieldComponent
 } from '@defra/forms-model'
 import {
   type PluginProperties,
@@ -30,6 +29,7 @@ import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { type DetailItemField } from '~/src/server/plugins/engine/models/types.js'
 import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import { type QuestionPageController } from '~/src/server/plugins/engine/pageControllers/index.js'
 import {
   type FileStatus,
   type FormAdapterSubmissionSchemaVersion,
@@ -38,7 +38,6 @@ import {
 import { type ViewContext } from '~/src/server/plugins/nunjucks/types.js'
 import {
   type FormAction,
-  type FormParams,
   type FormRequest,
   type FormRequestPayload,
   type FormResponseToolkit,
@@ -368,10 +367,12 @@ export type PreparePageEventRequestOptions = (
 
 export type OnRequestCallback = (
   request: AnyFormRequest,
-  params: FormParams,
-  definition: FormDefinition,
-  metadata: FormMetadata
-) => void
+  h: FormResponseToolkit,
+  context: FormContext
+) =>
+  | ResponseObject
+  | FormResponseToolkit['continue']
+  | Promise<ResponseObject | FormResponseToolkit['continue']>
 
 export type SaveAndExitHandler = (
   request: FormRequestPayload,
@@ -379,6 +380,23 @@ export type SaveAndExitHandler = (
   context: FormContext
 ) => ResponseObject
 
+export interface ExternalArgs {
+  component: ComponentDef
+  controller: QuestionPageController
+  sourceUrl: string
+  actionArgs: Record<string, string>
+}
+
+export interface PostcodeLookupExternalArgs extends ExternalArgs {
+  component: UkAddressFieldComponent
+  actionArgs: { step: string }
+}
+
+export interface ExternalStateAppendage {
+  component: string
+  data: FormStateValue | FormState
+}
+
 export interface PluginOptions {
   model?: FormModel
   services?: Services
@@ -396,6 +414,7 @@ export interface PluginOptions {
   preparePageEventRequestOptions?: PreparePageEventRequestOptions
   onRequest?: OnRequestCallback
   baseUrl: string // base URL of the application, protocol and hostname e.g. "https://myapp.com"
+  ordnanceSurveyApiKey?: string
 }
 
 export interface FormAdapterSubmissionMessageMeta {

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

@@ -0,0 +1,48 @@
+import { type ResponseObject } from '@hapi/hapi'
+
+import * as Components from '~/src/server/plugins/engine/components/index.js'
+import {
+  type FormRequestPayload,
+  type FormResponseToolkit
+} from '~/src/server/plugins/engine/types/index.js'
+import { type ExternalArgs } from '~/src/server/plugins/engine/types.js'
+
+// Type guard for ExternalComponent
+export function isExternalComponent(
+  component: unknown
+): component is ExternalComponent {
+  return typeof (component as ExternalComponent).dispatcher === 'function'
+}
+
+// External components are guaranteed to have a dispatcher method
+export interface ExternalComponent {
+  dispatcher(
+    request: FormRequestPayload,
+    h: FormResponseToolkit,
+    args: ExternalArgs
+  ): ResponseObject
+}
+
+/**
+ * Returns internal and external components from a componentMap, regardless of error state.
+ * @returns An object containing internalComponents and externalComponents arrays
+ */
+export function getComponentsByType(): {
+  internalComponents: Map<string, unknown>
+  externalComponents: Map<string, ExternalComponent>
+} {
+  const internalComponents = new Map<string, unknown>()
+  const externalComponents = new Map<string, ExternalComponent>()
+
+  const componentMap = new Map<string, unknown>(Object.entries(Components))
+
+  for (const [name, component] of componentMap.entries()) {
+    if (isExternalComponent(component)) {
+      externalComponents.set(name, component)
+    } else {
+      internalComponents.set(name, component)
+    }
+  }
+
+  return { internalComponents, externalComponents }
+}

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

@@ -1,10 +1,18 @@
 {% from "partials/components.html" import componentList %}
 {% from "govuk/components/fieldset/macro.njk" import govukFieldset %}
 {% from "govuk/components/hint/macro.njk" import govukHint %}
+{% from "govuk/components/button/macro.njk" import govukButton %}
+{% from "govuk/components/inset-text/macro.njk" import govukInsetText %}
 
 {% macro UkAddressField(component) %}
   {% set fieldset = component.model.fieldset %}
-  {% set addressFieldHtml = componentList(component.model.components) %}
+  {% set usePostcodeLookup = component.model.usePostcodeLookup %}
+
+  {% set addressFieldHtml %}
+    <div {{"hidden" if usePostcodeLookup }}>
+      {{ componentList(component.model.components) }}
+    </div>
+  {% endset %}
 
   {% if component.model.hint %}
     {% set addressHintHtml %}
@@ -17,9 +25,45 @@
     {% set addressFieldHtml = addressHintHtml + addressFieldHtml %}
   {% endif %}
 
-  {{ govukFieldset({
-    legend: fieldset.legend,
-    attributes: fieldset.attributes,
-    html: addressFieldHtml
-  }) if fieldset else addressFieldHtml }}
+  <div id="{{component.model.name}}" class="govuk-form-group{{ ' govuk-form-group--error' if usePostcodeLookup and component.model.errors | length }}">
+    {{ govukFieldset({
+      legend: fieldset.legend,
+      attributes: fieldset.attributes,
+      html: addressFieldHtml
+    }) if fieldset else addressFieldHtml }}
+
+    {% if usePostcodeLookup %}
+      {% set value = component.model.value %}
+
+        {% if value %}
+          {% set insetHtml %}
+            <strong>Selected address:</strong>
+            <br><br>
+            {{ value }}
+            <br><br>
+            <p class="govuk-body">
+              <button class="govuk-link govuk-button--link govuk-!-margin-right-1" name="action"
+                value="external-{{component.model.name}}">Use a different address</button>
+            </p>
+          {% endset %}
+
+          {{ govukInsetText({
+            html: insetHtml,
+            classes: "govuk-!-margin-top-2"
+          }) }}
+        {% else %}
+          <div class="govuk-button-group govuk-!-margin-bottom-0">
+            {{ govukButton({
+              text: "Find an address",
+              attributes: {
+                name: "action",
+                value: "external-" + component.model.name
+              },
+              classes: "govuk-button--secondary govuk-!-margin-right-1 govuk-!-margin-bottom-0"
+            }) }}
+            <p class="govuk-body govuk-!-margin-bottom-0">or <button class="govuk-link govuk-button--link govuk-!-margin-right-1 govuk-!-margin-bottom-0" name="action" value="external-{{component.model.name}}--step:manual">enter address manually</button></p>
+          </div>
+        {% endif %}
+    {% endif %}
+  </div>
 {% endmacro %}

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

@@ -13,6 +13,7 @@ import {
   prepareNunjucksEnvironment
 } from '~/src/server/plugins/engine/index.js'
 import { type PluginOptions } from '~/src/server/plugins/engine/types.js'
+import { VIEW_PATH as POSTCODE_LOOKUP_VIEW_PATH } from '~/src/server/plugins/postcode-lookup/index.js'
 
 export async function registerVision(
   server: Server,
@@ -24,10 +25,15 @@ export async function registerVision(
   )
 
   const viewPathResolved = join(packageRoot, VIEW_PATH)
+  const postcodeLookupPathResolved = join(
+    packageRoot,
+    POSTCODE_LOOKUP_VIEW_PATH
+  )
 
   const paths = [
     ...pluginOptions.nunjucks.paths,
     viewPathResolved,
+    postcodeLookupPathResolved,
     join(govukFrontendPath, 'dist')
   ]
 

package/src/server/plugins/postcode-lookup/index.js

@@ -0,0 +1,21 @@
+import { getRoutes } from '~/src/server/plugins/postcode-lookup/routes/index.js'
+
+export const VIEW_PATH = 'src/server/plugins/postcode-lookup/views'
+
+/**
+ * @satisfies {NamedPlugin<PostcodeLookupConfiguration>}
+ */
+export const postcodeLookupPlugin = {
+  name: '@defra/forms-engine-plugin/postcode-lookup',
+  dependencies: ['@hapi/vision'],
+  multiple: false,
+  register(server, options) {
+    // @ts-expect-error - Request typing
+    server.route(getRoutes(options))
+  }
+}
+
+/**
+ * @import { NamedPlugin } from '@hapi/hapi'
+ * @import { PostcodeLookupConfiguration } from '~/src/server/plugins/postcode-lookup/types.js'
+ */