@defra/forms-engine-plugin 4.0.0 → 4.0.2

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

@@ -0,0 +1,143 @@
+/**
+ * @typedef {{
+ *   ordnanceSurveyApiKey: string
+ * }} PostcodeLookupConfiguration
+ */
+
+/**
+ * @typedef {{
+ *   name: string
+ *   step?: string
+ * }} PostcodeLookupDispatchArgs
+ */
+
+/**
+ * @typedef {{
+ *   sourceUrl: string,
+ *   formName: string
+ *   componentName: string
+ *   componentTitle: string,
+ *   componentHint?: string
+ *   step?: string
+ * }} PostcodeLookupDispatchData
+ */
+
+/**
+ * @typedef {{
+ *   initial: PostcodeLookupDispatchData
+ *   details: PostcodeLookupDetailsData
+ * }} PostcodeLookupSessionData
+ */
+
+//
+// Model types
+//
+
+/**
+ * The postcode lookup details form view model data
+ * @typedef {object} PostcodeLookupDetailsData
+ * @property {string} postcodeQuery - postcode query
+ * @property {string} buildingNameQuery - Building name or number query
+ */
+
+//
+// Route types
+//
+
+/**
+ * Postcode lookup query params
+ * @typedef {object} PostcodeLookupQuery
+ * @property {string} [step] - step
+ */
+
+/**
+ * @typedef {object} PostcodeLookupDetailsPayloadProperties
+ * @property {string} step - step
+ */
+
+/**
+ * @typedef {PostcodeLookupDetailsData & PostcodeLookupDetailsPayloadProperties} PostcodeLookupDetailsPayload
+ */
+
+/**
+ * @typedef {object} PostcodeLookupSelectPayload
+ * @property {string} step - step
+ * @property {string} uprn - postcode
+ */
+
+/**
+ * Postcode lookup get request
+ * @typedef {object} PostcodeLookupGetRequestRefs
+ * @property {PostcodeLookupQuery} Query - Request query
+ */
+
+/**
+ * Postcode lookup post request
+ * @typedef {object} PostcodeLookupPostRequestRefs
+ * @property {PostcodeLookupDetailsPayload | PostcodeLookupSelectPayload} Payload - Request payload
+ */
+
+/**
+ * @typedef {PostcodeLookupGetRequestRefs | PostcodeLookupPostRequestRefs} PostcodeLookupRequestRefs
+ * @typedef {Request<PostcodeLookupGetRequestRefs>} PostcodeLookupGetRequest
+ * @typedef {Request<PostcodeLookupPostRequestRefs>} PostcodeLookupPostRequest
+ * @typedef {PostcodeLookupGetRequest | PostcodeLookupPostRequest} PostcodeLookupRequest
+ */
+
+/**
+ * @typedef {object} PostcodeLookupManualPayload
+ * @property {string} addressLine1 - The address line 1
+ * @property {string} addressLine2 - The address line 2
+ * @property {string} town - The address town or city
+ * @property {string} county - The address county
+ * @property {string} postcode - The address postcode
+ */
+
+//
+// Service types
+//
+
+/**
+ * @typedef {object} Address
+ * @property {string} uprn - The unique property reference
+ * @property {string} address - The full address
+ * @property {string} addressLine1 - Address line 1
+ * @property {string} addressLine2 - Address line 2
+ * @property {string} town - Address town
+ * @property {string} county - Address county
+ * @property {string} postcode - Address postcode
+ * @property {string} formatted - The full formatted address
+ */
+
+/**
+ * OS places address response
+ * @typedef {object} DeliveryPointAddress
+ * @property {string} UPRN - Unique property reference number
+ * @property {string} UDPRN - Unique delivery point Reference Number
+ * @property {string} ADDRESS - Address
+ * @property {string} ORGANISATION_NAME - Organisation name
+ * @property {string} SUB_BUILDING_NAME - Sub building name
+ * @property {string} BUILDING_NAME - Building name
+ * @property {string} BUILDING_NUMBER - Building number
+ * @property {string} THOROUGHFARE_NAME - Throughfare name
+ * @property {string} DEPENDENT_LOCALITY - Dependent locality
+ * @property {string} POST_TOWN - Post town
+ * @property {string} POSTCODE - Postcode
+ */
+
+/**
+ * OS places DPA response
+ * @typedef {object} DeliveryPointAddressItem
+ * @property {DeliveryPointAddress} DPA - Delivery point address
+ */
+
+/**
+ * OS places DPA response
+ * @typedef {object} DeliveryPointAddressResult
+ * @property {DeliveryPointAddressItem[]} [results] - Delivery point address results
+ */
+
+/**
+ * @import { Request } from '@hapi/hapi'
+ * @import { FormPayload } from '~/src/server/plugins/engine/types.js'
+ */

package/src/server/plugins/postcode-lookup/views/postcode-lookup-details.html

@@ -0,0 +1,83 @@
+{% extends baseLayoutPath %}
+
+{% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}
+{% from "govuk/components/input/macro.njk" import govukInput %}
+{% from "govuk/components/select/macro.njk" import govukSelect %}
+{% from "govuk/components/button/macro.njk" import govukButton %}
+{% from "govuk/components/inset-text/macro.njk" import govukInsetText %}
+{% from "govuk/components/hint/macro.njk" import govukHint %}
+{% from "govuk/components/fieldset/macro.njk" import govukFieldset %}
+
+{% block content %}
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      {% if errors %}
+        {{ govukErrorSummary({
+          titleText: "There is a problem",
+          errorList: errors
+        }) }}
+      {% endif %}
+
+      {% include "partials/heading.html" %}
+
+      <form method="post">
+        <input type="hidden" name="crumb" value="{{ crumb }}">
+        <input type="hidden" name="step" value="{{ step }}">
+
+        {% switch step %}
+          {% case "details" %}
+            <!-- Postcode lookup details -->
+            {{ govukInput(fields.postcodeQuery) }}
+            {{ govukInput(fields.buildingNameQuery) }}
+          {% case "select" %}
+            <!-- Postcode lookup select -->
+            <!-- Postcode lookup details display -->
+            {%- set detailsHtml -%}
+              <strong>{{ details.postcodeQuery }}</strong>{% if details.buildingNameQuery %} and <strong>{{ details.buildingNameQuery }}</strong>{% endif %}
+            {%- endset -%}
+
+            {% if hasAddresses %}
+              <p class="govuk-body">
+                {{addressCount}} address{{ "es" if hasMultipleAddresses }} found for {{ detailsHtml | safe }}. <a href="{{ searchAgainLink.href }}" class="govuk-link govuk-link--no-visited-state">{{ searchAgainLink.text }}</a>
+              </p>
+            {% endif %}
+
+            {% if hasMultipleAddresses %}
+              <!-- Multiple address found - show drop down select -->
+              {{ govukSelect(fields.uprn) }}
+            {% elif singleAddress %}
+              <!-- Single address found - show single item -->
+              {{ govukInput(fields.uprn) }}
+              {{ govukInsetText({
+                text: singleAddress.formatted
+              }) }}
+            {% else %}
+              <!-- No addresses found - show try again -->
+              <p class="govuk-body">We could not find an address that matches {{ detailsHtml | safe }}.</p>
+            {% endif %}
+          {% case "manual" %}
+            <!-- Postcode lookup manual entry -->
+            {% if hint %}
+              {{ govukHint(hint) }}
+            {% endif %}
+
+            {{ govukInput(fields.addressLine1) }}
+            {{ govukInput(fields.addressLine2) }}
+            {{ govukInput(fields.town) }}
+            {{ govukInput(fields.county) }}
+            {{ govukInput(fields.postcode) }}
+        {% endswitch %}
+
+        <div class="govuk-button-group">
+          {{ govukButton(buttons.continueButton) }}
+
+          {% if buttons.manualLink %}
+            <p class="govuk-body">or <a class="govuk-link govuk-link--no-visited-state" href="{{ buttons.manualLink.href }}">{{buttons.manualLink.text}}</a></p>
+          {% elif buttons.detailsLink %}
+            <p class="govuk-body">or <a class="govuk-link govuk-link--no-visited-state" href="{{ buttons.detailsLink.href }}">{{buttons.detailsLink.text}}</a></p>
+          {% endif %}
+        </div>
+      </form>
+    </div>
+  </div>
+{% endblock %}

package/src/server/postcode-lookup.test.ts

@@ -0,0 +1,64 @@
+import { type Server } from '@hapi/hapi'
+
+import { createServer } from '~/src/server/index.js'
+import { getFormMetadata } from '~/src/server/plugins/engine/services/formsService.js'
+import * as defaultServices from '~/src/server/plugins/engine/services/index.js'
+import * as fixtures from '~/test/fixtures/index.js'
+
+jest.mock('~/src/server/plugins/engine/services/formsService.js')
+jest.mock('~/src/server/plugins/engine/services/uploadService.js')
+
+describe('Postcode lookup plugin', () => {
+  let server: Server
+
+  beforeEach(() => {
+    jest.mocked(getFormMetadata).mockResolvedValue(fixtures.form.metadata)
+  })
+
+  afterAll(async () => {
+    await server.stop()
+  })
+
+  describe('Plugin registration', () => {
+    test('Registers plugin with ordnance survey key', async () => {
+      server = await createServer({
+        services: defaultServices,
+        ordnanceSurveyApiKey: 'dummy'
+      })
+      await server.initialize()
+
+      expect(server.registrations).toHaveProperty(
+        '@defra/forms-engine-plugin/postcode-lookup',
+        {
+          name: '@defra/forms-engine-plugin/postcode-lookup',
+          options: { ordnanceSurveyApiKey: 'dummy' },
+          version: undefined
+        }
+      )
+
+      expect(
+        server.table().find((route) => route.path === '/postcode-lookup')
+      ).toBeDefined()
+    })
+
+    test('Does not register plugin when no ordnance survey key is provided', async () => {
+      server = await createServer({
+        services: defaultServices
+      })
+      await server.initialize()
+
+      expect(server.registrations).not.toHaveProperty(
+        '@defra/forms-engine-plugin/postcode-lookup',
+        {
+          name: '@defra/forms-engine-plugin/postcode-lookup',
+          options: { ordnanceSurveyApiKey: 'dummy' },
+          version: undefined
+        }
+      )
+
+      expect(
+        server.table().find((route) => route.path === '/postcode-lookup')
+      ).toBeUndefined()
+    })
+  })
+})

package/src/server/routes/types.ts

@@ -48,10 +48,16 @@ export enum FormAction {
   Delete = 'delete',
   AddAnother = 'add-another',
   Send = 'send',
-  SaveAndExit = 'save-and-exit'
+  SaveAndExit = 'save-and-exit',
+  External = 'external'
 }
 
 export enum FormStatus {
   Draft = 'draft',
   Live = 'live'
 }
+
+export enum ExternalActions {
+  PostcodeLookup = 'postcode-lookup',
+  AnotherExternalAction = 'another-external-action'
+}

package/src/server/schemas/index.ts

@@ -8,13 +8,11 @@ export const stateSchema = Joi.string<FormStatus>()
   .required()
 
 export const actionSchema = Joi.string<FormAction>()
-  .valid(
-    FormAction.Continue,
-    FormAction.Validate,
-    FormAction.Delete,
-    FormAction.AddAnother,
-    FormAction.Send,
-    FormAction.SaveAndExit
+  .pattern(new RegExp(`^${FormAction.External}-[a-zA-Z-:]*$`))
+  .allow(
+    ...Object.values(FormAction).filter(
+      (value) => value !== FormAction.External
+    )
   )
   .default(FormAction.Validate)
   .optional()

package/src/server/types.ts

@@ -53,6 +53,7 @@ export interface RouteConfig {
   onRequest?: OnRequestCallback
   saveAndExit?: PluginOptions['saveAndExit']
   cacheServiceCreator?: (server: Server) => CacheService
+  ordnanceSurveyApiKey?: string
 }
 
 export interface OutputService {