@defra/forms-engine-plugin 4.0.0 → 4.0.1

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

@@ -6,7 +6,15 @@ import {
 } from '@hapi/hapi'
 import { isEqual } from 'date-fns'
 
-import { PREVIEW_PATH_PREFIX } from '~/src/server/constants.js'
+import {
+  EXTERNAL_STATE_APPENDAGE,
+  EXTERNAL_STATE_PAYLOAD,
+  PREVIEW_PATH_PREFIX
+} from '~/src/server/constants.js'
+import {
+  FormComponent,
+  isFormState
+} from '~/src/server/plugins/engine/components/FormComponent.js'
 import {
   checkEmailAddressForLiveFormSubmission,
   checkFormStatus,
@@ -22,7 +30,10 @@ import { generateUniqueReference } from '~/src/server/plugins/engine/referenceNu
 import * as defaultServices from '~/src/server/plugins/engine/services/index.js'
 import {
   type AnyFormRequest,
+  type ExternalStateAppendage,
   type FormContext,
+  type FormPayload,
+  type FormSubmissionState,
   type OnRequestCallback,
   type PluginOptions
 } from '~/src/server/plugins/engine/types.js'
@@ -66,6 +77,8 @@ export async function redirectOrMakeHandler(
     })
   }
 
+  state = await importExternalComponentState(request, page, state)
+
   const flash = cacheService.getFlash(request)
   const context = model.getFormContext(request, state, flash?.errors)
   const relevantPath = page.getRelevantPath(request, context)
@@ -95,11 +108,66 @@ export async function redirectOrMakeHandler(
   return proceed(request, h, page.getHref(relevantPath))
 }
 
+async function importExternalComponentState(
+  request: AnyFormRequest,
+  page: PageControllerClass,
+  state: FormSubmissionState
+): Promise<FormSubmissionState> {
+  const externalComponentData = request.yar.flash(EXTERNAL_STATE_APPENDAGE)
+
+  if (Array.isArray(externalComponentData)) {
+    return state
+  }
+
+  const typedStateAppendage = externalComponentData as ExternalStateAppendage
+  const componentName = typedStateAppendage.component
+  const stateAppendage = typedStateAppendage.data
+  const component = request.app.model?.componentMap.get(componentName)
+
+  if (!component) {
+    throw new Error(`Component ${componentName} not found in form`)
+  }
+
+  if (!(component instanceof FormComponent)) {
+    throw new TypeError(
+      `Component ${componentName} is not a FormComponent and does not support isState`
+    )
+  }
+
+  const isStateValid = component.isState(stateAppendage)
+
+  if (!isStateValid) {
+    throw new Error(`State for component ${componentName} is invalid`)
+  }
+
+  const componentState = isFormState(stateAppendage)
+    ? Object.fromEntries(
+        Object.entries(stateAppendage).map(([key, value]) => [
+          `${componentName}__${key}`,
+          value
+        ])
+      )
+    : { [componentName]: stateAppendage }
+
+  // Save the external component state immediately
+  const updatedState = await page.mergeState(request, state, componentState)
+
+  // Merge the stashed payload into the local state
+  const payload = request.yar.flash(EXTERNAL_STATE_PAYLOAD)
+  const stashedPayload = Array.isArray(payload) ? {} : (payload as FormPayload)
+
+  return { ...stashedPayload, ...updatedState }
+}
+
 export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- hapi types are wrong
   const prefix = server.realm.modifiers.route.prefix ?? ''
 
-  const { services = defaultServices, controllers } = options
+  const {
+    services = defaultServices,
+    controllers,
+    ordnanceSurveyApiKey
+  } = options
 
   const { formsService } = services
 
@@ -166,7 +234,7 @@ export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
       // Construct the form model
       const model = new FormModel(
         definition,
-        { basePath, versionNumber },
+        { basePath, versionNumber, ordnanceSurveyApiKey },
         services,
         controllers
       )

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

@@ -4,7 +4,8 @@ import {
   type FormVersionMetadata,
   type Item,
   type List,
-  type Page
+  type Page,
+  type UkAddressFieldComponent
 } from '@defra/forms-model'
 import {
   type PluginProperties,
@@ -28,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,
@@ -378,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
@@ -395,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'
+ */