@defra/forms-engine-plugin 5.0.0-alpha.3 → 5.0.0-alpha.31

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

@@ -21,11 +21,18 @@
  * @property {string} query - name query
  */
 
+export const CountryMap = {
+  england: 1,
+  'northern-ireland': 2,
+  scotland: 3,
+  wales: 4
+}
+
 /**
  * Geospatial countries query params
  * @typedef {object} GeospatialCountriesQuery
- * @property {string} omit - the country to omit
- * @property {string} only - the country to include
+ * @property {keyof typeof CountryMap} [omit] - the country to omit
+ * @property {keyof typeof CountryMap} [only] - the country to include
  */
 
 /**

package/src/server/plugins/nunjucks/filters/applyUrlParam.js

@@ -0,0 +1,17 @@
+/**
+ * Nunjucks filter to add/replace a parameter on a query string of a url.
+ * Currently only used in forms-runner.
+ * @param {string} urlPath - existing relative url with query string
+ * @param {string} paramName - name of parameter
+ * @param {string} paramValue - value of parameter
+ * @returns {string}
+ */
+export function applyUrlParam(urlPath, paramName, paramValue) {
+  if (typeof urlPath !== 'string') {
+    return ''
+  }
+  const url = new URL(urlPath, 'https://dummy')
+  url.searchParams.set(paramName, paramValue)
+
+  return url.pathname + url.search
+}

package/src/server/plugins/nunjucks/filters/index.js

@@ -6,3 +6,4 @@ export { href } from './href.js'
 export { field } from './field.js'
 export { page } from './page.js'
 export { merge } from './merge.js'
+export { applyUrlParam } from './applyUrlParam.js'

package/src/server/plugins/payment/helper.js

@@ -1,5 +1,6 @@
 import { format } from 'date-fns'
 
+import { toLanguageLocale } from '../engine/helpers.js'
 import { PaymentService } from './service.js'
 
 export const DEFAULT_PAYMENT_HELP_URL =
@@ -28,10 +29,29 @@ export async function createPaymentService(
 /**
  * Formats a payment date for display
  * @param {string} isoString - ISO date string
+ * @param {string} language - the target language
  * @returns {string} Formatted date string (e.g., "26 January 2026 5:01pm")
  */
-export function formatPaymentDate(isoString) {
-  return format(new Date(isoString), 'd MMMM yyyy h:mmaaa')
+export function formatPaymentDate(isoString, language) {
+  return formatDateForLanguage(
+    new Date(isoString),
+    'd MMMM yyyy h:mmaaa',
+    language
+  )
+}
+
+/**
+ * Formats a date for display in a specific language.
+ * To use additional languages, the appropriate module must be imported from 'date-fns/locale'
+ * @param { Date | string } date - the date
+ * @param {string} formatMask - the format mask
+ * @param {string} language - the target language
+ * @returns {string} Formatted date string (e.g., "26 January 2026 5:01pm")
+ */
+export function formatDateForLanguage(date, formatMask, language) {
+  return format(date, formatMask, {
+    locale: toLanguageLocale(language)
+  })
 }
 
 /**

package/src/server/plugins/payment/service.js

@@ -1,6 +1,7 @@
 import { StatusCodes } from 'http-status-codes'
 
 import { logger } from '../../common/helpers/logging/logger.js'
+import { toPayLanguageCode } from '../engine/helpers.js'
 import {
   buildPaymentInfo,
   convertPenceToPounds
@@ -38,7 +39,7 @@ export class PaymentService {
    * @param {string} returnUrl
    * @param {string} reference
    * @param {boolean} isLivePayment
-   * @param {{ formId: string, slug: string } | undefined } metadata
+   * @param {{ formId: string, slug: string, language: string } | undefined } metadata
    * @param {string} [email] - optional email to prepopulate on GOV.UK Pay
    */
   async createPayment(
@@ -50,6 +51,8 @@ export class PaymentService {
     metadata,
     email
   ) {
+    const language = toPayLanguageCode(metadata?.language)
+
     try {
       /** @type {CreatePaymentRequest} */
       const payload = {
@@ -58,7 +61,8 @@ export class PaymentService {
         reference,
         metadata,
         return_url: returnUrl,
-        delayed_capture: true
+        delayed_capture: true,
+        language
       }
 
       // Prepopulate email on GOV.UK Pay if provided

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

@@ -18,6 +18,7 @@
  * @property {string} reference - Unique reference for the payment
  * @property {string} description - Human-readable description of the payment
  * @property {string} return_url - URL to redirect the user to after payment
+ * @property {string} language - the desired language for translations
  * @property {boolean} [delayed_capture] - Whether to delay capturing the payment
  * @property {{ formId: string, slug: string }} [metadata] - Additional metadata for the payment
  * @property {string} [email] - Email to prepopulate on GOV.UK Pay (max 254 chars)

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

@@ -16,6 +16,7 @@ const countyFieldName = 'county'
 const postcodeFieldName = 'postcode'
 
 const GOVUK_MARGIN_RIGHT_1 = 'govuk-!-margin-right-1'
+const COMMON_BACK = 'common.back'
 
 export const steps = {
   // Step 1: Postcode/building name input
@@ -297,6 +298,19 @@ export const stepSchema = Joi.string()
   .valid(...Object.keys(steps))
   .required()
 
+/**
+ * Joi object schema factories typed with their payload, as JavaScript files
+ * cannot pass type arguments to `Joi.object<T>()`
+ */
+/** @type {() => ObjectSchema<PostcodeLookupDetailsPayload>} */
+const detailsObjectSchema = Joi.object.bind(Joi)
+
+/** @type {() => ObjectSchema<PostcodeLookupSelectPayload>} */
+const selectObjectSchema = Joi.object.bind(Joi)
+
+/** @type {() => ObjectSchema<PostcodeLookupManualPayload>} */
+const manualObjectSchema = Joi.object.bind(Joi)
+
 const sharedPayloadSchemaKeys = {
   crumb: crumbSchema,
   step: stepSchema
@@ -308,7 +322,7 @@ const sharedPayloadSchemaKeys = {
  * @returns {ObjectSchema<PostcodeLookupDetailsPayload>}
  */
 export function createDetailsPayloadSchema(language = 'en-GB') {
-  return Joi.object()
+  return detailsObjectSchema()
     .keys({
       ...sharedPayloadSchemaKeys,
       [postcodeQueryFieldName]: Joi.string()
@@ -337,7 +351,7 @@ export function createDetailsPayloadSchema(language = 'en-GB') {
  * @returns {ObjectSchema<PostcodeLookupSelectPayload>}
  */
 export function createSelectPayloadSchema(language = 'en-GB') {
-  return Joi.object()
+  return selectObjectSchema()
     .keys({
       ...sharedPayloadSchemaKeys,
       [uprnFieldName]: Joi.string()
@@ -355,7 +369,7 @@ export function createSelectPayloadSchema(language = 'en-GB') {
  * @returns {ObjectSchema<PostcodeLookupManualPayload>}
  */
 export function createManualPayloadSchema(language = 'en-GB') {
-  return Joi.object()
+  return manualObjectSchema()
     .keys({
       ...sharedPayloadSchemaKeys,
       [line1FieldName]: Joi.string()
@@ -403,19 +417,20 @@ function getHref(step) {
 /**
  * The postcode lookup details form view model
  * @param {PostcodeLookupSessionData} data
+ * @param {Translator} translator
  * @param {PostcodeLookupDetailsData} [payload]
  * @param {Error} [err]
  */
-export function detailsViewModel(data, payload, err) {
-  const {
-    componentTitle: pageTitle,
-    formName,
-    sourceUrl,
-    language = 'en-GB'
-  } = data.initial
+export function detailsViewModel(data, translator, payload, err) {
+  const { componentId, componentHint, sourceUrl, languages } = data.initial
+
+  const { t, tComponent, tForm } = translator
+
+  const component = /** @type {ComponentDef} */ ({ id: componentId })
 
   const backLink = {
-    href: sourceUrl
+    href: sourceUrl,
+    text: t(COMMON_BACK)
   }
 
   const { errors, postcodeQueryError, buildingNameQueryError } =
@@ -425,42 +440,53 @@ export function detailsViewModel(data, payload, err) {
     payload ?? data.details,
     postcodeQueryError,
     buildingNameQueryError,
-    language
+    translator.language
   )
 
+  const hint = componentHint && {
+    text: tComponent(component, 'hint')
+  }
+
   const continueButton = {
-    text: i18nT('postcodeLookup.findAddress', language),
+    text: t('postcodeLookup.findAddress'),
     classes: GOVUK_MARGIN_RIGHT_1
   }
   const manualLink = {
-    text: i18nT('postcodeLookup.enterManually', language),
+    text: t('postcodeLookup.enterManually'),
     href: getHref(steps.manual)
   }
 
+  const selector = languages?.length ? { languages } : {}
+
   return {
     step: steps.details,
     showTitle: true,
-    name: formName,
+    name: tForm('title'),
     serviceUrl: sourceUrl,
-    pageTitle,
+    pageTitle: tComponent(component, 'title'),
+    hint,
     backLink,
     errors,
     fields,
-    buttons: { continueButton, manualLink }
+    buttons: { continueButton, manualLink },
+    t,
+    language: translator.language,
+    ...selector
   }
 }
 
 /**
  * The postcode lookup select form view model
  * @param {{ session: PostcodeLookupSessionData, apiKey: string }} data
+ * @param {Translator} translator
  * @param {PostcodeLookupSelectPayload} [payload]
  * @param {Error} [err]
  */
-export async function selectViewModel(data, payload, err) {
+export async function selectViewModel(data, translator, payload, err) {
   const { session, apiKey } = data
   const { details, initial } = session
   const { postcodeQuery, buildingNameQuery } = details
-  const language = initial.language ?? 'en-GB'
+  const { language, t, tComponent, tForm } = translator
 
   const {
     hasAddresses,
@@ -471,12 +497,18 @@ export async function selectViewModel(data, payload, err) {
   } = await getAddresses(postcodeQuery, buildingNameQuery, apiKey)
 
   const title = hasAddresses
-    ? initial.componentTitle
-    : i18nT('postcodeLookup.noAddressFoundTitle', language)
+    ? tComponent(
+        /** @type {ComponentDef} */ ({ id: initial.componentId }),
+        'title'
+      )
+    : t('postcodeLookup.noAddressFoundTitle')
   const formPath = initial.sourceUrl
   const href = getHref()
 
-  const backLink = { href }
+  const backLink = {
+    href,
+    text: t(COMMON_BACK)
+  }
 
   const { errors, uprnError } = buildErrors(err)
 
@@ -490,7 +522,7 @@ export async function selectViewModel(data, payload, err) {
     language
   )
 
-  const searchAgainText = i18nT('postcodeLookup.searchAgain', language)
+  const searchAgainText = t('postcodeLookup.searchAgain')
 
   const searchAgainLink = {
     text: searchAgainText,
@@ -499,27 +531,29 @@ export async function selectViewModel(data, payload, err) {
 
   const continueButton = {
     href: hasAddresses ? undefined : href,
-    text: hasAddresses
-      ? i18nT('postcodeLookup.useThisAddress', language)
-      : searchAgainText,
+    text: hasAddresses ? t('postcodeLookup.useThisAddress') : searchAgainText,
     classes: GOVUK_MARGIN_RIGHT_1
   }
   const manualLink = {
-    text: i18nT('postcodeLookup.enterManually', language),
+    text: t('postcodeLookup.enterManually'),
     href: `${href}?step=${steps.manual}`
   }
 
   const addressesFoundText = hasAddresses
-    ? i18nT('postcodeLookup.addressFound', language, { count: addressCount })
+    ? t('postcodeLookup.addressFound', { count: addressCount })
     : undefined
   const noAddressFoundText = !hasAddresses
-    ? i18nT('postcodeLookup.noAddressFoundBody', language)
+    ? t('postcodeLookup.noAddressFoundBody')
     : undefined
 
+  const selector = initial.languages?.length
+    ? { languages: initial.languages }
+    : {}
+
   return {
     step: steps.select,
     showTitle: true,
-    name: title,
+    name: tForm('title'),
     serviceUrl: formPath,
     pageTitle: title,
     backLink,
@@ -533,28 +567,32 @@ export async function selectViewModel(data, payload, err) {
     hasMultipleAddresses,
     addressesFoundText,
     noAddressFoundText,
-    buttons: { continueButton, manualLink }
+    buttons: { continueButton, manualLink },
+    t,
+    language,
+    ...selector
   }
 }
 
 /**
  * The postcode lookup manual form view model
  * @param {PostcodeLookupSessionData} data
+ * @param {Translator} translator
  * @param {PostcodeLookupManualPayload} [payload]
  * @param {Error} [err]
  */
-export function manualViewModel(data, payload, err) {
-  const {
-    componentTitle,
-    sourceUrl,
-    componentHint,
-    language = 'en-GB'
-  } = data.initial
+export function manualViewModel(data, translator, payload, err) {
+  const { componentId, sourceUrl, componentHint, languages } = data.initial
   const formPath = sourceUrl
   const href = getHref()
 
+  const { t, tComponent, tForm } = translator
+
+  const component = /** @type {ComponentDef} */ ({ id: componentId })
+
   const backLink = {
-    href
+    href,
+    text: t(COMMON_BACK)
   }
 
   const {
@@ -567,7 +605,7 @@ export function manualViewModel(data, payload, err) {
   } = buildErrors(err)
 
   const hint = componentHint && {
-    text: componentHint
+    text: tComponent(component, 'hint')
   }
 
   const fields = getManualFields(
@@ -577,29 +615,34 @@ export function manualViewModel(data, payload, err) {
     townError,
     countyError,
     postcodeError,
-    language
+    translator.language
   )
 
   const continueButton = {
-    text: i18nT('postcodeLookup.useThisAddress', language),
+    text: t('postcodeLookup.useThisAddress'),
     classes: GOVUK_MARGIN_RIGHT_1
   }
   const detailsLink = {
-    text: i18nT('postcodeLookup.findAnAddressInstead', language),
+    text: t('postcodeLookup.findAnAddressInstead'),
     href
   }
 
+  const selector = languages?.length ? { languages } : {}
+
   return {
     step: steps.manual,
     showTitle: true,
-    name: componentTitle,
+    name: tForm('title'),
     serviceUrl: formPath,
-    pageTitle: componentTitle,
+    pageTitle: tComponent(component, 'title'),
     backLink,
     errors,
     hint,
     fields,
-    buttons: { continueButton, detailsLink }
+    buttons: { continueButton, detailsLink },
+    t,
+    language: translator.language,
+    ...selector
   }
 }
 
@@ -607,5 +650,7 @@ export function manualViewModel(data, payload, err) {
 
 /**
  * @import { ObjectSchema, ValidationErrorItem } from 'joi'
+ * @import { ComponentDef } from '@defra/forms-model'
  * @import { Address, PostcodeLookupDetailsData, PostcodeLookupDetailsPayload, PostcodeLookupManualPayload, PostcodeLookupSelectPayload, PostcodeLookupSessionData } from '../types.js'
+ * @import { Translator } from '../../engine/i18n/types.js'
  */

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

@@ -3,6 +3,7 @@ import { StatusCodes } from 'http-status-codes'
 import Joi from 'joi'
 
 import { EXTERNAL_STATE_APPENDAGE } from '../../../constants.js'
+import { getCachedPluginTranslator } from '../../engine/i18n/form.js'
 import {
   JOURNEY_BASE_URL,
   createDetailsPayloadSchema,
@@ -15,6 +16,7 @@ import {
   steps
 } from '../models/index.js'
 import * as service from '../service.js'
+import { resolveLanguage } from '../../../utils/utils.js'
 
 const viewName = 'postcode-lookup-details'
 
@@ -22,7 +24,7 @@ const viewName = 'postcode-lookup-details'
  * Get the session state associated with this journey
  * @param {PostcodeLookupRequest} request
  */
-function getSessionState(request) {
+export function getSessionState(request) {
   /**
    * @type {PostcodeLookupSessionData | null | undefined}
    */
@@ -63,6 +65,32 @@ function flashComponentState(request, componentName, address) {
 
   request.yar.flash(EXTERNAL_STATE_APPENDAGE, appendage, true)
 }
+/**
+ * Get a cached translator, or create a new one if not in the cache
+ * @param {PostcodeLookupRequest} request
+ * @param {PostcodeLookupDispatchData} initial
+ * @param { string | string[] | undefined } language
+ */
+export async function getDispatchTranslator(request, initial, language) {
+  const { formId, formStatus } = initial
+
+  // Override language if passed as a query param
+  if (language) {
+    request.yar.set('language', language)
+  }
+
+  const typedReq = /** @type {AnyFormRequest} */ (/** @type {any} */ (request))
+  const lang = resolveLanguage(typedReq)
+
+  const translator = await getCachedPluginTranslator(
+    typedReq,
+    /** @type {FormMetadata} */ ({ id: formId }),
+    formStatus,
+    lang
+  )
+
+  return translator
+}
 
 /**
  * Initialises and dispatches the request to the postcode lookup journey
@@ -101,15 +129,21 @@ function getRoute() {
   return {
     method: 'GET',
     path: JOURNEY_BASE_URL,
-    handler(request, h) {
+    async handler(request, h) {
       const { query } = request
-      const { step } = query
+      const { step, language } = query
       const session = getSessionState(request)
 
+      const translator = await getDispatchTranslator(
+        request,
+        session.initial,
+        language
+      )
+
       const model =
         step === steps.manual
-          ? manualViewModel(session)
-          : detailsViewModel(session)
+          ? manualViewModel(session, translator)
+          : detailsViewModel(session, translator)
 
       return h.view(viewName, model)
     },
@@ -117,7 +151,8 @@ function getRoute() {
       validate: {
         query: Joi.object()
           .keys({
-            step: Joi.string().allow(steps.details, steps.manual).optional()
+            step: Joi.string().allow(steps.details, steps.manual).optional(),
+            language: Joi.string().allow('en-GB', 'cy').optional()
           })
           .optional()
       }
@@ -163,6 +198,19 @@ function postRoute(options) {
   }
 }
 
+/**
+ * Validate a payload against a schema. Joi types the value as `any` when
+ * validation fails, so it is typed here as the partially converted payload.
+ * @template TSchema
+ * @param {ObjectSchema<TSchema>} schema
+ * @param {unknown} payload
+ * @param {ValidationOptions} [options]
+ * @returns {{ value: TSchema, error: undefined } | { value: TSchema | undefined, error: ValidationError }}
+ */
+function validatePayload(schema, payload, options) {
+  return schema.validate(payload, options)
+}
+
 /**
  * Post handler for the details step
  * @param {PostcodeLookupPostRequest} request
@@ -172,15 +220,22 @@ function postRoute(options) {
 async function detailsPostHandler(request, h, options) {
   const session = getSessionState(request)
   const { ordnanceSurveyApiKey: apiKey } = options
-  const language = session.initial.language ?? 'en-GB'
-  const { value: details, error } = createDetailsPayloadSchema(
-    language
-  ).validate(request.payload)
+  const translator = await getDispatchTranslator(
+    request,
+    session.initial,
+    request.query.language
+  )
+  const language = translator.language
+
+  const { value: details, error } = validatePayload(
+    createDetailsPayloadSchema(language),
+    request.payload
+  )
 
   let model
 
   if (error) {
-    model = detailsViewModel(session, details, error)
+    model = detailsViewModel(session, translator, details, error)
 
     return h.view(viewName, model)
   }
@@ -191,7 +246,7 @@ async function detailsPostHandler(request, h, options) {
   // Store the updated session
   request.yar.set(JOURNEY_BASE_URL, session)
 
-  model = await selectViewModel({ session, apiKey })
+  model = await selectViewModel({ session, apiKey }, translator)
 
   return h.view(viewName, model)
 }
@@ -205,13 +260,24 @@ async function detailsPostHandler(request, h, options) {
 async function selectPostHandler(request, h, options) {
   const session = getSessionState(request)
   const { ordnanceSurveyApiKey: apiKey } = options
-  const language = session.initial.language ?? 'en-GB'
-  const { value: select, error } = createSelectPayloadSchema(language).validate(
+  const translator = await getDispatchTranslator(
+    request,
+    session.initial,
+    request.query.language
+  )
+  const language = translator.language
+  const { value: select, error } = validatePayload(
+    createSelectPayloadSchema(language),
     request.payload
   )
 
   if (error) {
-    const model = await selectViewModel({ session, apiKey }, select, error)
+    const model = await selectViewModel(
+      { session, apiKey },
+      translator,
+      select,
+      error
+    )
 
     return h.view(viewName, model)
   }
@@ -235,19 +301,23 @@ async function selectPostHandler(request, h, options) {
  * @param {PostcodeLookupPostRequest} request
  * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h
  */
-function manualPostHandler(request, h) {
+async function manualPostHandler(request, h) {
   const session = getSessionState(request)
-  const language = session.initial.language ?? 'en-GB'
+  const translator = await getDispatchTranslator(
+    request,
+    session.initial,
+    request.query.language
+  )
+  const language = translator.language
 
-  const { value: manual, error } = createManualPayloadSchema(language).validate(
+  const { value: manual, error } = validatePayload(
+    createManualPayloadSchema(language),
     request.payload,
-    {
-      abortEarly: false
-    }
+    { abortEarly: false }
   )
 
   if (error) {
-    const model = manualViewModel(session, manual, error)
+    const model = manualViewModel(session, translator, manual, error)
 
     return h.view(viewName, model)
   }
@@ -261,7 +331,9 @@ function manualPostHandler(request, h) {
 
 /**
  * @import { ResponseToolkit, ServerRoute } from '@hapi/hapi'
- * @import { PostcodeLookupManualPayload, PostcodeLookupDetailsPayload, PostcodeLookupSelectPayload, Address, PostcodeLookupGetRequestRefs, PostcodeLookupPostRequestRefs, PostcodeLookupRequest, PostcodeLookupPostRequest, PostcodeLookupConfiguration, PostcodeLookupDispatchData, PostcodeLookupSessionData } from '../types.js'
+ * @import { ObjectSchema, ValidationError, ValidationOptions } from 'joi'
+ * @import { FormMetadata } from '@defra/forms-model'
+ * @import { PostcodeLookupManualPayload, Address, PostcodeLookupGetRequestRefs, PostcodeLookupPostRequestRefs, PostcodeLookupRequest, PostcodeLookupPostRequest, PostcodeLookupConfiguration, PostcodeLookupDispatchData, PostcodeLookupSessionData } from '../types.js'
  * @import { FormRequestPayload, FormResponseToolkit } from '../../../routes/types.js'
- * @import { ExternalStateAppendage } from '../../engine/types.js'
+ * @import { AnyFormRequest, ExternalStateAppendage } from '../../engine/types.js'
  */

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

@@ -14,12 +14,16 @@
 /**
  * @typedef {{
  *   sourceUrl: string,
+ *   formId: string
  *   formName: string
+ *   formStatus: FormStatus
+ *   componentId: string
  *   componentName: string
  *   componentTitle: string,
  *   componentHint?: string
  *   step?: string
  *   language?: string
+ *   languages?: { name: string, code: string}[]
  * }} PostcodeLookupDispatchData
  */
 
@@ -49,6 +53,7 @@
  * Postcode lookup query params
  * @typedef {object} PostcodeLookupQuery
  * @property {string} [step] - step
+ * @property {string} [language] - language
  */
 
 /**
@@ -140,5 +145,5 @@
 
 /**
  * @import { Request } from '@hapi/hapi'
- * @import { FormPayload } from '../engine/types.js'
+ * @import { FormStatus } from '@defra/forms-model'
  */