@defra/forms-engine-plugin 4.0.0 → 4.0.2

package/src/server/forms/register-as-a-unicorn-breeder.yaml

@@ -56,10 +56,26 @@ pages:
       - name: wZLWPy
         options:
           required: true
+          usePostcodeLookup: true
         type: UkAddressField
-        title: Address
+        title: What is your billing address
+        shortDescription: Billing address
         schema: {}
-        hint: This is a UK address. Users must enter address line 1, town and a postcode
+        hint: This is a UK billing address. Users must enter address line 1, town and a postcode
+      - name: dfTGhD
+        options: {}
+        schema: {}
+        type: MultilineTextField
+        title: Delivery notes
+        hint:
+          Enter some instructions for the delivery person
+      - name: drGHuj
+        options:
+          required: true
+        type: UkAddressField
+        title: What is your delivery address
+        schema: {}
+        hint: This is a UK delivery address. Users must enter address line 1, town and a postcode
     next:
       - path: '/do-you-want-your-unicorn-breeder-certificate-sent-to-this-address'
     section: section

package/src/server/plugins/engine/components/UkAddressField.test.ts

@@ -91,6 +91,7 @@ describe('UkAddressField', () => {
 
         expect(field.keys).toEqual([
           'myComponent',
+          'myComponent__uprn',
           'myComponent__addressLine1',
           'myComponent__addressLine2',
           'myComponent__town',
@@ -194,7 +195,8 @@ describe('UkAddressField', () => {
             addressLine2: '',
             town: '',
             county: '',
-            postcode: ''
+            postcode: '',
+            uprn: ''
           })
         )
 
@@ -208,7 +210,8 @@ describe('UkAddressField', () => {
             addressLine2: 'Knutsford Road',
             town: 'Warrington',
             county: 'Cheshire',
-            postcode: 'WA4 1HT'
+            postcode: 'WA4 1HT',
+            uprn: ''
           })
         )
 
@@ -218,7 +221,8 @@ describe('UkAddressField', () => {
             addressLine2: '', // Optional field
             town: 'Warrington',
             county: '', // Optional field
-            postcode: 'WA4 1HT'
+            postcode: 'WA4 1HT',
+            uprn: ''
           })
         )
 
@@ -233,7 +237,8 @@ describe('UkAddressField', () => {
             addressLine2: '',
             town: '',
             county: '',
-            postcode: ''
+            postcode: '',
+            uprn: ''
           })
         )
 
@@ -302,7 +307,7 @@ describe('UkAddressField', () => {
           'postal-code'
         ]
 
-        ukAddressField.collection.components.forEach((component) => {
+        ukAddressField.collection.components.slice(1).forEach((component) => {
           const addressFieldOptions =
             component.options as TextFieldComponent['options']
 
@@ -319,7 +324,8 @@ describe('UkAddressField', () => {
         addressLine2: 'Knutsford Road',
         town: 'Warrington',
         county: 'Cheshire',
-        postcode: 'WA4 1HT'
+        postcode: 'WA4 1HT',
+        uprn: '123456789'
       }
 
       it('returns text from state', () => {
@@ -481,7 +487,8 @@ describe('UkAddressField', () => {
       addressLine2: 'Knutsford Road',
       town: 'Warrington',
       county: 'Cheshire',
-      postcode: 'WA4 1HT'
+      postcode: 'WA4 1HT',
+      uprn: ''
     }
 
     const addressLine1Invalid =
@@ -514,7 +521,8 @@ describe('UkAddressField', () => {
               addressLine2: ' Knutsford Road',
               town: ' Warrington',
               county: 'Cheshire',
-              postcode: ' WA4 1HT'
+              postcode: ' WA4 1HT',
+              uprn: ''
             }),
             output: {
               value: getFormData(address),
@@ -527,7 +535,8 @@ describe('UkAddressField', () => {
               addressLine2: 'Knutsford Road ',
               town: 'Warrington ',
               county: 'Cheshire ',
-              postcode: 'WA4 1HT '
+              postcode: 'WA4 1HT ',
+              uprn: ''
             }),
             output: {
               value: getFormData(address),
@@ -540,7 +549,8 @@ describe('UkAddressField', () => {
               addressLine2: ' Knutsford Road \n\n',
               town: ' Warrington \n\n',
               county: ' Cheshire \n\n',
-              postcode: ' WA4 1HT \n\n'
+              postcode: ' WA4 1HT \n\n',
+              uprn: ''
             }),
             output: {
               value: getFormData(address),
@@ -564,7 +574,8 @@ describe('UkAddressField', () => {
               addressLine2: 'Knutsford Road',
               town: 'Warrington',
               county: 'Cheshire',
-              postcode: 'WA4 1HT'
+              postcode: 'WA4 1HT',
+              uprn: ''
             }),
             output: {
               value: getFormData({
@@ -572,7 +583,8 @@ describe('UkAddressField', () => {
                 addressLine2: 'Knutsford Road',
                 town: 'Warrington',
                 county: 'Cheshire',
-                postcode: 'WA4 1HT'
+                postcode: 'WA4 1HT',
+                uprn: ''
               }),
               errors: [
                 expect.objectContaining({
@@ -587,7 +599,8 @@ describe('UkAddressField', () => {
               addressLine2: addressLine2Invalid,
               town: 'Warrington',
               county: 'Cheshire',
-              postcode: 'WA4 1HT'
+              postcode: 'WA4 1HT',
+              uprn: ''
             }),
             output: {
               value: getFormData({
@@ -595,7 +608,8 @@ describe('UkAddressField', () => {
                 addressLine2: addressLine2Invalid,
                 town: 'Warrington',
                 county: 'Cheshire',
-                postcode: 'WA4 1HT'
+                postcode: 'WA4 1HT',
+                uprn: ''
               }),
               errors: [
                 expect.objectContaining({
@@ -610,7 +624,8 @@ describe('UkAddressField', () => {
               addressLine2: 'Knutsford Road',
               town: townInvalid,
               county: 'Cheshire',
-              postcode: 'WA4 1HT'
+              postcode: 'WA4 1HT',
+              uprn: ''
             }),
             output: {
               value: getFormData({
@@ -618,7 +633,8 @@ describe('UkAddressField', () => {
                 addressLine2: 'Knutsford Road',
                 town: townInvalid,
                 county: 'Cheshire',
-                postcode: 'WA4 1HT'
+                postcode: 'WA4 1HT',
+                uprn: ''
               }),
               errors: [
                 expect.objectContaining({
@@ -633,7 +649,8 @@ describe('UkAddressField', () => {
               addressLine2: 'Knutsford Road',
               town: 'Warrington',
               county: countyInvalid,
-              postcode: 'WA4 1HT'
+              postcode: 'WA4 1HT',
+              uprn: ''
             }),
             output: {
               value: getFormData({
@@ -641,7 +658,8 @@ describe('UkAddressField', () => {
                 addressLine2: 'Knutsford Road',
                 town: 'Warrington',
                 county: countyInvalid,
-                postcode: 'WA4 1HT'
+                postcode: 'WA4 1HT',
+                uprn: ''
               }),
               errors: [
                 expect.objectContaining({
@@ -656,7 +674,8 @@ describe('UkAddressField', () => {
               addressLine2: 'Knutsford Road',
               town: 'Warrington',
               county: 'Cheshire',
-              postcode: postcodeInvalid
+              postcode: postcodeInvalid,
+              uprn: ''
             }),
             output: {
               value: getFormData({
@@ -664,7 +683,8 @@ describe('UkAddressField', () => {
                 addressLine2: 'Knutsford Road',
                 town: 'Warrington',
                 county: 'Cheshire',
-                postcode: postcodeInvalid
+                postcode: postcodeInvalid,
+                uprn: ''
               }),
               errors: [
                 expect.objectContaining({
@@ -679,7 +699,8 @@ describe('UkAddressField', () => {
               addressLine2: '',
               town: '',
               county: '',
-              postcode: postcodeInvalid
+              postcode: postcodeInvalid,
+              uprn: ''
             }),
             output: {
               value: getFormData({
@@ -687,7 +708,8 @@ describe('UkAddressField', () => {
                 addressLine2: '',
                 town: '',
                 county: '',
-                postcode: postcodeInvalid
+                postcode: postcodeInvalid,
+                uprn: ''
               }),
               errors: [
                 expect.objectContaining({
@@ -761,7 +783,8 @@ function getFormData(address: FormPayload): FormPayload {
     myComponent__addressLine2: address.addressLine2,
     myComponent__town: address.town,
     myComponent__county: address.county,
-    myComponent__postcode: address.postcode
+    myComponent__postcode: address.postcode,
+    myComponent__uprn: address.uprn
   }
 }
 
@@ -769,15 +792,15 @@ function getFormData(address: FormPayload): FormPayload {
  * UK address session state
  */
 function getFormState(address: FormPayload): FormState {
-  const [addressLine1, addressLine2, town, county, postcode] = Object.values(
-    getFormData(address)
-  )
+  const [addressLine1, addressLine2, town, county, postcode, uprn] =
+    Object.values(getFormData(address))
 
   return {
     myComponent__addressLine1: addressLine1 ?? null,
     myComponent__addressLine2: addressLine2 ?? null,
     myComponent__town: town ?? null,
     myComponent__county: county ?? null,
-    myComponent__postcode: postcode ?? null
+    myComponent__postcode: postcode ?? null,
+    myComponent__uprn: uprn ?? null
   }
 }

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

@@ -1,5 +1,10 @@
-import { ComponentType, type UkAddressFieldComponent } from '@defra/forms-model'
+import {
+  ComponentType,
+  type FormComponentsDef,
+  type UkAddressFieldComponent
+} from '@defra/forms-model'
 import { type ObjectSchema } from 'joi'
+import lowerFirst from 'lodash/lowerFirst.js'
 
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import {
@@ -8,14 +13,20 @@ import {
 } from '~/src/server/plugins/engine/components/FormComponent.js'
 import { TextField } from '~/src/server/plugins/engine/components/TextField.js'
 import { type QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import {
+  type FormRequestPayload,
+  type FormResponseToolkit
+} from '~/src/server/plugins/engine/types/index.js'
 import {
   type ErrorMessageTemplateList,
   type FormPayload,
   type FormState,
   type FormStateValue,
   type FormSubmissionError,
-  type FormSubmissionState
+  type FormSubmissionState,
+  type PostcodeLookupExternalArgs
 } from '~/src/server/plugins/engine/types.js'
+import { dispatch } from '~/src/server/plugins/postcode-lookup/routes/index.js'
 
 export class UkAddressField extends FormComponent {
   declare options: UkAddressFieldComponent['options']
@@ -23,13 +34,15 @@ export class UkAddressField extends FormComponent {
   declare stateSchema: ObjectSchema<FormState>
   declare collection: ComponentCollection
 
+  shortDescription: FormComponentsDef['shortDescription']
+
   constructor(
     def: UkAddressFieldComponent,
     props: ConstructorParameters<typeof FormComponent>[1]
   ) {
     super(def, props)
 
-    const { name, options } = def
+    const { name, options, shortDescription } = def
 
     const isRequired = options.required !== false
     const hideOptional = !!options.optionalText
@@ -37,6 +50,16 @@ export class UkAddressField extends FormComponent {
 
     this.collection = new ComponentCollection(
       [
+        {
+          type: ComponentType.TextField,
+          name: `${name}__uprn`,
+          title: 'UPRN',
+          schema: {},
+          options: {
+            required: false,
+            classes: 'hidden'
+          }
+        },
         {
           type: ComponentType.TextField,
           name: `${name}__addressLine1`,
@@ -103,6 +126,7 @@ export class UkAddressField extends FormComponent {
     this.options = options
     this.formSchema = this.collection.formSchema
     this.stateSchema = this.collection.stateSchema
+    this.shortDescription = shortDescription
   }
 
   getFormValueFromState(state: FormSubmissionState) {
@@ -115,7 +139,9 @@ export class UkAddressField extends FormComponent {
       return null
     }
 
-    return Object.values(value).filter(Boolean)
+    return Object.entries(value)
+      .filter(([key, value]) => key !== 'uprn' && Boolean(value))
+      .map(([, value]) => value)
   }
 
   getContextValueFromState(state: FormSubmissionState) {
@@ -140,17 +166,34 @@ export class UkAddressField extends FormComponent {
   getViewErrors(
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    return this.getErrors(errors)?.filter(
+    const uniqueErrors = this.getErrors(errors)?.filter(
       (error, index, self) =>
         index === self.findIndex((err) => err.name === error.name)
     )
+
+    // When using postcode lookup, the address fields are hidden
+    // so we replace any individual validation messages with a single one
+    if (this.shouldUsePostcodeLookup() && uniqueErrors?.length) {
+      const { name, shortDescription } = this
+
+      return [
+        {
+          name,
+          path: [name],
+          href: `#${name}`,
+          text: `Enter ${lowerFirst(shortDescription)}`
+        }
+      ]
+    }
+
+    return uniqueErrors
   }
 
   getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
     const { collection, name, options } = this
 
     const viewModel = super.getViewModel(payload, errors)
-    let { components, fieldset, hint, label } = viewModel
+    let { fieldset, hint, label } = viewModel
 
     fieldset ??= {
       legend: {
@@ -173,12 +216,30 @@ export class UkAddressField extends FormComponent {
       }
     }
 
-    components = collection.getViewModel(payload, errors)
+    const components = collection.getViewModel(payload, errors)
+
+    // Hide UPRN
+    const uprn = components.at(0)
+
+    if (!uprn) {
+      throw new Error('No UPRN')
+    }
+
+    uprn.model.formGroup = { classes: 'app-hidden' }
+
+    // Postcode lookup
+    const usePostcodeLookup = this.shouldUsePostcodeLookup()
+
+    const value = usePostcodeLookup
+      ? this.getDisplayStringFromState(payload)
+      : undefined
 
     return {
       ...viewModel,
+      value,
       fieldset,
-      components
+      components,
+      usePostcodeLookup
     }
   }
 
@@ -193,6 +254,10 @@ export class UkAddressField extends FormComponent {
     return UkAddressField.getAllPossibleErrors()
   }
 
+  private shouldUsePostcodeLookup() {
+    return !!(this.options.usePostcodeLookup && this.model.ordnanceSurveyApiKey)
+  }
+
   /**
    * Static version of getAllPossibleErrors that doesn't require a component instance.
    */
@@ -218,9 +283,27 @@ export class UkAddressField extends FormComponent {
       TextField.isText(value.postcode)
     )
   }
+
+  static dispatcher(
+    request: FormRequestPayload,
+    h: FormResponseToolkit,
+    args: PostcodeLookupExternalArgs
+  ) {
+    const { controller, component } = args
+
+    return dispatch(request, h, {
+      formName: controller.model.name,
+      componentName: component.name,
+      componentHint: component.hint,
+      componentTitle: component.title || controller.title,
+      step: args.actionArgs.step,
+      sourceUrl: args.sourceUrl
+    })
+  }
 }
 
 export interface UkAddressState extends Record<string, string> {
+  uprn: string
   addressLine1: string
   addressLine2: string
   town: string

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

@@ -21,7 +21,8 @@ export const configureEnginePlugin = async (
     controllers,
     preparePageEventRequestOptions,
     onRequest,
-    saveAndExit
+    saveAndExit,
+    ordnanceSurveyApiKey
   }: RouteConfig = {},
   cache?: CacheService
 ): Promise<{
@@ -38,7 +39,7 @@ export const configureEnginePlugin = async (
 
     model = new FormModel(
       definition,
-      { basePath: initialBasePath },
+      { basePath: initialBasePath, ordnanceSurveyApiKey },
       services,
       controllers
     )
@@ -63,7 +64,8 @@ export const configureEnginePlugin = async (
       preparePageEventRequestOptions,
       onRequest,
       baseUrl: 'http://localhost:3009', // always runs locally
-      saveAndExit
+      saveAndExit,
+      ordnanceSurveyApiKey
     }
   }
 }

package/src/server/plugins/engine/models/FormModel.ts

@@ -77,6 +77,7 @@ export class FormModel {
   values: FormDefinition
   basePath: string
   versionNumber?: number
+  ordnanceSurveyApiKey?: string
   conditions: Partial<Record<string, ExecutableCondition>>
   pages: PageControllerClass[]
   services: Services
@@ -95,7 +96,11 @@ export class FormModel {
 
   constructor(
     def: typeof this.def,
-    options: { basePath: string; versionNumber?: number },
+    options: {
+      basePath: string
+      versionNumber?: number
+      ordnanceSurveyApiKey?: string
+    },
     services: Services = defaultServices,
     controllers?: Record<string, typeof PageController>
   ) {
@@ -150,6 +155,7 @@ export class FormModel {
     this.values = result.value
     this.basePath = options.basePath
     this.versionNumber = options.versionNumber
+    this.ordnanceSurveyApiKey = options.ordnanceSurveyApiKey
     this.conditions = {}
     this.services = services
     this.controllers = controllers
@@ -551,7 +557,9 @@ function validateFormPayload(
   // Skip validation GET requests or other actions
   if (
     !request.payload ||
-    (action && ![FormAction.Validate, FormAction.SaveAndExit].includes(action))
+    (action &&
+      ![FormAction.Validate, FormAction.SaveAndExit].includes(action) &&
+      !action.startsWith(FormAction.External))
   ) {
     return context
   }

package/src/server/plugins/engine/options.js

@@ -25,7 +25,8 @@ const pluginRegistrationOptionsSchema = Joi.object({
   preparePageEventRequestOptions: Joi.function().optional(),
   onRequest: Joi.function().optional(),
   baseUrl: Joi.string().uri().required(),
-  saveAndExit: Joi.function().optional()
+  saveAndExit: Joi.function().optional(),
+  ordnanceSurveyApiKey: Joi.string().optional()
 })
 
 /**

package/src/server/plugins/engine/pageControllers/QuestionPageController.test.ts

@@ -602,6 +602,7 @@ describe('QuestionPageController', () => {
         addressField__town: 'Town or city',
         addressField__county: 'Cheshire',
         addressField__postcode: 'CW1 1AB',
+        addressField__uprn: '',
         radiosField: 'privateLimitedCompany',
         selectField: 910400000,
         autocompleteField: 910400044,

package/src/server/plugins/engine/pageControllers/QuestionPageController.ts

@@ -12,6 +12,10 @@ import Boom from '@hapi/boom'
 import { type RouteOptions } from '@hapi/hapi'
 import { type ValidationErrorItem } from 'joi'
 
+import {
+  EXTERNAL_STATE_APPENDAGE,
+  EXTERNAL_STATE_PAYLOAD
+} from '~/src/server/constants.js'
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import { optionalText } from '~/src/server/plugins/engine/components/constants.js'
 import { type BackLink } from '~/src/server/plugins/engine/components/types.js'
@@ -35,6 +39,7 @@ import {
   type FormStateValue,
   type FormSubmissionState
 } from '~/src/server/plugins/engine/types.js'
+import { getComponentsByType } from '~/src/server/plugins/engine/validationHelpers.js'
 import {
   FormAction,
   type FormRequest,
@@ -492,6 +497,11 @@ export class QuestionPageController extends PageController {
     ) => {
       const { collection, viewName, model } = this
       const { isForceAccess, state, evaluationState } = context
+      const action = request.payload.action
+
+      if (action?.startsWith(FormAction.External)) {
+        return this.dispatchExternal(request, h, context)
+      }
 
       /**
        * If there are any errors, render the page with the parsed errors
@@ -515,7 +525,6 @@ export class QuestionPageController extends PageController {
       await this.setState(request, state)
 
       // Check if this is a save-and-exit action
-      const { action } = request.payload
       if (action === FormAction.SaveAndExit) {
         return this.handleSaveAndExit(request, context, h)
       }
@@ -525,6 +534,65 @@ export class QuestionPageController extends PageController {
     }
   }
 
+  private dispatchExternal(
+    request: FormRequestPayload,
+    h: FormResponseToolkit,
+    context: FormContext
+  ) {
+    const { externalComponents } = getComponentsByType()
+    const action = request.payload.action ?? ''
+
+    // Find the external action and arguments
+    // `external-{componentName}--{argname1}:{argvalue1}--{argname2}:{argvalue2}`
+    // E.g. external-abcdef--amount:10--step:manual
+    const externalActionsWithArgs = action
+      .slice(`${FormAction.External}-`.length)
+      .split('--')
+
+    const externalActionArgs = externalActionsWithArgs
+      .slice(1)
+      .map((arg) => arg.split(':'))
+
+    const args = Object.fromEntries(externalActionArgs) as Record<
+      string,
+      string
+    >
+
+    const componentName = externalActionsWithArgs[0]
+    const component = this.model.componentDefMap.get(componentName)
+    const componentType = component?.type
+
+    if (!componentType) {
+      throw Boom.internal(
+        `External component of type ${componentType} not found`
+      )
+    }
+
+    const selectedComponent = externalComponents.get(componentType)
+
+    if (!selectedComponent) {
+      throw Boom.internal(`External component ${componentName} not found`)
+    }
+
+    // Stash payload without crumb and action
+    const stashedPayload = {
+      ...context.payload,
+      crumb: undefined,
+      action: undefined
+    }
+    request.yar.flash(EXTERNAL_STATE_PAYLOAD, stashedPayload, true)
+
+    // Clear any previous state appendage
+    request.yar.clear(EXTERNAL_STATE_APPENDAGE)
+
+    return selectedComponent.dispatcher(request, h, {
+      component,
+      controller: this,
+      sourceUrl: request.url.toString(),
+      actionArgs: args
+    })
+  }
+
   proceed(
     request: FormContextRequest,
     h: FormResponseToolkit,