@defra/fcp-sfd-frontend-engine 0.2.12 → 0.4.0

package/src/presenters/base-presenter.js

@@ -0,0 +1,299 @@
+/**
+ * Base presenter for formatting data for display
+ */
+
+/**
+ * Formats the business name into back link text.
+ * If the business name is greater than 50 characters, it will be truncated with an ellipsis.
+*/
+const BACK_LINK_DISPLAY_MAX = 50
+
+export const formatBackLink = (businessName) => {
+  if (businessName.length > BACK_LINK_DISPLAY_MAX) {
+    return `Back to ${businessName.slice(0, BACK_LINK_DISPLAY_MAX)}…`
+  }
+  return `Back to ${businessName}`
+}
+
+/**
+ * The first time a user loads the phone numbers change page they won't have entered any data, so a payload
+ * or a changedNumber won't be present. If a user has a validation issue then we want to replay the payload data to them.
+ * We check if payload is not undefined because it could be a user has removed the 'mobile' number for example but
+ * incorrectly entered the telephone number so the payload for this would appear as an empty string.
+ *
+ * Payload is the priority to check and then after that if changedNumber is present then we display that value.
+ *
+ * @private
+ */
+export const formatNumber = (payloadNumber, changedNumber, originalNumber) => {
+  if (payloadNumber !== undefined) {
+    return payloadNumber
+  }
+
+  if (changedNumber !== undefined) {
+    return changedNumber
+  }
+
+  return originalNumber
+}
+
+/**
+ * Identify the correct address to use from the DAL response.
+ *
+ * An address lookup is where a user enters a postcode and selects an address
+ * returned from an API. Manual input is when a user chooses to type the address in themselves.
+ *
+ * If the UPRN is populated, the user has selected an address from the lookup.
+ * UPRN is only returned by the lookup API; manual addresses will always have `uprn = null`.
+ *
+ * If both a building number range and a street are present, they are combined into one line so they display together.
+ *
+ * City, postcode and country are always appended to the final address array.
+ *
+ * @param {Object} address - The complete address object
+ *
+ * @returns {string[]} An array of address fields (either from lookup or manual)
+ *
+ * @private
+ */
+
+export const formatDisplayAddress = (address) => {
+  const { lookup, manual, postcode, country, city } = address
+
+  let addressLines = []
+
+  if (lookup.uprn) {
+    // If the uprn is populated then the user has selected an address from the lookup
+    const buildingAndStreet = [
+      lookup.buildingNumberRange,
+      lookup.street
+    ].filter(Boolean).join(' ')
+
+    addressLines = [
+      lookup.pafOrganisationName,
+      lookup.flatName,
+      lookup.buildingName,
+      buildingAndStreet,
+      lookup.doubleDependentLocality,
+      lookup.dependentLocality,
+      city,
+      lookup.county
+    ]
+  } else {
+    // Otherwise the user manually entered the address
+    addressLines = [
+      manual.line1,
+      manual.line2,
+      manual.line3,
+      city,
+      manual.line4, // County
+      manual.line5
+    ]
+  }
+
+  return [
+    ...addressLines.filter(Boolean),
+    postcode,
+    country
+  ]
+}
+
+/**
+ * Combines address parts into a single line, joining non-empty values with commas.
+ *
+ * @private
+ */
+const buildAddressLine = (parts) => {
+  return parts.filter(Boolean).join(', ') || null
+}
+
+/**
+ * Combines building range and street into a single line, joining with a space.
+ *
+ * @private
+ */
+const buildStreetLine = (buildingRange, street) => {
+  return [buildingRange, street].filter(Boolean).join(' ') || null
+}
+
+/**
+ * Formats a lookup address (from address API) into a consistent flat structure.
+ *
+ * @private
+ */
+const formatLookupAddress = (lookup, city, country, postcode) => ({
+  address1: buildAddressLine([lookup.pafOrganisationName, lookup.flatName, lookup.buildingName]),
+  address2: buildStreetLine(lookup.buildingNumberRange, lookup.street),
+  address3: buildAddressLine([lookup.doubleDependentLocality, lookup.dependentLocality]),
+  county: lookup.county ?? null,
+  city: city ?? null,
+  country: country ?? null,
+  postcode: postcode ?? null
+})
+
+/**
+ * Formats a manually entered address into a consistent flat structure.
+ *
+ * @private
+ */
+const formatManualAddress = (manual, city, country, postcode) => ({
+  address1: manual.line1 ?? null,
+  address2: manual.line2 ?? null,
+  address3: manual.line3 ?? null,
+  city: city ?? null,
+  county: manual.line4 ?? null,
+  country: country ?? null,
+  postcode: postcode ?? null
+})
+
+/**
+ * Formats an original address fetched from the DAL into a flattened structure
+ * suitable for display or form population on the `address-enter` pages.
+ *
+ * If the address contains a UPRN, it is treated as a lookup address;
+ * otherwise, it is treated as a manually entered address.
+ *
+ * @param {Object} originalAddress - The full address object from the DAL
+ *
+ * @returns {Object} A flattened address object with consistent keys
+ */
+export const formatOriginalAddress = (originalAddress) => {
+  const { lookup, manual, city, country, postcode } = originalAddress
+  return lookup.uprn
+    ? formatLookupAddress(lookup, city, country, postcode)
+    : formatManualAddress(manual, city, country, postcode)
+}
+
+/**
+ * Formats a changed address object into a consistent structure for form display.
+ *
+ * If the address includes a UPRN, it indicates the user selected it from an address lookup.
+ * In that case, the lookup fields are combined and mapped into the manual address format used by the form.
+ *
+ * If the address does not include a UPRN, it is assumed to be manually entered and returned as-is.
+ *
+ * @param {Object} changeBusinessAddress - The changed address object to format
+ *
+ * @returns {Object} A formatted address object with fields `address1`, `address2`, `address3`,
+ * `city`, `county`, `country`, and `postcode`.
+ */
+export const formatChangedAddress = (changeBusinessAddress) => {
+  if (!changeBusinessAddress.uprn) {
+    // manual address (no lookup used)
+    return changeBusinessAddress
+  }
+
+  const {
+    pafOrganisationName,
+    flatName,
+    buildingName,
+    buildingNumberRange,
+    street,
+    doubleDependentLocality,
+    dependentLocality,
+    city,
+    county,
+    country,
+    postcode
+  } = changeBusinessAddress
+
+  return {
+    address1: buildAddressLine([pafOrganisationName, flatName, buildingName]),
+    address2: buildStreetLine(buildingNumberRange, street),
+    address3: buildAddressLine([doubleDependentLocality, dependentLocality]),
+    city: city ?? null,
+    county: county ?? null,
+    country: country ?? null,
+    postcode: postcode ?? null
+  }
+}
+
+/**
+ * Formats a list of address objects for display in a dropdown menu.
+ *
+ * Each address object is transformed into an option with:
+ * - `value`: a concatenation of the address UPRN and displayAddress
+ * - `text`: the formatted display address string
+ * - `selected`: true only if it matches the previously picked address
+ *
+ * A summary option is prepended to the start of the list, showing how many
+ * addresses were found. This summary option is selected by default unless
+ * a previously picked address exists.
+ *
+ * This function is shared across presenters that display address selection
+ * lists (e.g. personal or business address flows).
+ *
+ * Note: The `value` combines `uprn` and `displayAddress` to ensure uniqueness.
+ * Some addresses (for example, postcode LL55 2NF) have been observed to share
+ * the same UPRN, which caused incorrect selections when UPRN alone was used.
+ * Concatenating both fields guarantees each dropdown option has a unique value.
+ *
+ * @param {Array<Object>} addresses - List of address objects with `uprn` and `displayAddress` properties
+ * @param {Object} [previouslyPickedAddress] - Optional object representing the address previously selected by the user
+ *
+ * @returns {Array<Object>} Array of formatted address options ready for display
+ */
+export const formatDisplayAddresses = (addresses, previouslyPickedAddress) => {
+  const displayAddresses = addresses.map(address => ({
+    value: `${address.uprn}${address.displayAddress}`,
+    text: address.displayAddress,
+    selected:
+      previouslyPickedAddress?.uprn === address.uprn &&
+      previouslyPickedAddress?.displayAddress === address.displayAddress
+  }))
+
+  // Check if any address is already selected
+  const hasSelectedAddress = displayAddresses.some(addr => addr.selected)
+
+  // Add a display summary option to the beginning of the list
+  // e.g. "18 addresses found"
+  const text = addresses.length === 1 ? '1 address found' : `${addresses.length} addresses found`
+
+  displayAddresses.unshift({
+    value: 'display',
+    text,
+    selected: !hasSelectedAddress
+  })
+
+  return displayAddresses
+}
+
+/**
+ * Shared helper used by base presenters to sort validation errors so they
+ * appear in the same order as the sections and fields shown on a Fix List page.
+ *
+ * Fix List pages are built dynamically depending on:
+ * - which sections need fixing, and
+ * - which field the user originally selected.
+ *
+ * Because of that, we can’t rely on the order of the validation object.
+ * We need to deliberately sort the errors so they match:
+ *   1. The order the sections appear on the page, and
+ *   2. The logical order of fields within each section.
+ *
+ * This function keeps that logic in one reusable place so it can be used
+ * by Business, Personal, or any future Fix List presenter.
+ *
+ * It returns the errors as an array, already arranged in the correct
+ * display order for the UI.
+ */
+export const sortErrorsBySectionOrder = (errors, orderedSectionsToFix, SECTION_FIELD_ORDER) => {
+  const sortedErrors = []
+
+  for (const section of orderedSectionsToFix) {
+    // A section (i.e 'address') can have multiple fields (i.e 'line1', 'line2', 'line3')
+    const fieldsInSection = SECTION_FIELD_ORDER[section] || []
+
+    for (const field of fieldsInSection) {
+      // If there's an error for this field, add it to the sorted list with the error details
+      if (errors[field]) {
+        sortedErrors.push({
+          field,
+          ...errors[field]
+        })
+      }
+    }
+  }
+
+  return sortedErrors
+}

package/src/presenters/presenters.js

@@ -0,0 +1,19 @@
+import {
+  formatBackLink,
+  formatNumber,
+  formatDisplayAddress,
+  formatOriginalAddress,
+  formatChangedAddress,
+  formatDisplayAddresses,
+  sortErrorsBySectionOrder
+} from './base-presenter.js'
+
+export const presenters = {
+  formatBackLink,
+  formatNumber,
+  formatDisplayAddress,
+  formatOriginalAddress,
+  formatChangedAddress,
+  formatDisplayAddresses,
+  sortErrorsBySectionOrder
+}

package/src/schemas/address-schema.js

@@ -0,0 +1,61 @@
+import Joi from 'joi'
+import {
+  ADDRESS_LINE_MAX,
+  TOWN_CITY_MAX,
+  COUNTY_MAX,
+  POSTCODE_MAX,
+  COUNTRY_MAX
+} from '../constants/validation-fields.js'
+
+export const addressSchema = Joi.object({
+  address1: Joi.string()
+    .required()
+    .max(ADDRESS_LINE_MAX)
+    .messages({
+      'string.empty': 'Enter address line 1, typically the building and street',
+      'string.max': `Address line 1 must be ${ADDRESS_LINE_MAX} characters or less`,
+      'any.required': 'Enter address line 1, typically the building and street'
+    }),
+  address2: Joi.string()
+    .allow('')
+    .max(ADDRESS_LINE_MAX)
+    .messages({
+      'string.max': `Address line 2 must be ${ADDRESS_LINE_MAX} characters or less`
+    }),
+  address3: Joi.string()
+    .allow('')
+    .max(ADDRESS_LINE_MAX)
+    .messages({
+      'string.max': `Address line 3 must be ${ADDRESS_LINE_MAX} characters or less`
+    }),
+  city: Joi.string()
+    .required()
+    .max(TOWN_CITY_MAX)
+    .messages({
+      'string.empty': 'Enter town or city',
+      'string.max': `Town or city must be ${TOWN_CITY_MAX} characters or less`,
+      'any.required': 'Enter town or city'
+    }),
+  county: Joi.string()
+    .allow('')
+    .max(COUNTY_MAX)
+    .messages({
+      'string.max': `County must be ${COUNTY_MAX} characters or less`
+    }),
+  postcode: Joi.string()
+    .required()
+    .max(POSTCODE_MAX)
+    .messages({
+      'any.required': 'Enter a postal code or zip code',
+      'string.empty': 'Enter a postal code or zip code',
+      'string.max': `Postal code or zip code must be ${POSTCODE_MAX} characters or less`
+    }),
+  country: Joi.string()
+    .required()
+    .max(COUNTRY_MAX)
+    .messages({
+      'string.empty': 'Enter a country',
+      'string.max': `Country must be ${COUNTRY_MAX} characters or less`,
+      'any.required': 'Enter a country'
+    })
+})

package/src/schemas/business/business-schemas.js

@@ -1,5 +1,7 @@
 import { businessSbiSchema } from './business-sbi-schema.js'
+import { addressSchema } from '../address-schema.js'
 
 export const businessSchemas = {
-  sbi: businessSbiSchema
+  sbi: businessSbiSchema,
+  address: addressSchema
 }

package/src/schemas/personal/personal-dob-schema.js

@@ -0,0 +1,178 @@
+import Joi from 'joi'
+import { MONTH_MAP, MAX_AGE_YEARS } from '../../constants/validation-fields-export.js'
+
+export const personalDobSchema = Joi.object({
+  day: Joi.string().allow(''),
+  month: Joi.string().allow(''),
+  year: Joi.string().allow('')
+}).custom((value, helpers) => {
+  const { day, month, year } = value
+
+  // Check for missing fields or combinations
+  const missingFieldsError = checkMissingFields(day, month, year, helpers)
+  if (missingFieldsError) {
+    return missingFieldsError
+  }
+
+  // Year format check (must be 4 digits)
+  if (year && year.length !== 4) {
+    return makeError(helpers, 'dob.yearLength', ['year'])
+  }
+
+  // Normalise and validate month input (can be name, abbreviation, or number)
+  const monthValue = getMonthNumber(month, helpers)
+  if (monthValue.isJoiError) {
+    return monthValue
+  }
+
+  // Validate that a real, valid date exists
+  const fullDate = getFullDate(day, monthValue, year, helpers)
+  if (fullDate.isJoiError) {
+    return fullDate
+  }
+
+  // Date must be in the past
+  if (fullDate > new Date()) {
+    return makeError(helpers, 'dob.future', ['day', 'month', 'year'])
+  }
+
+  // Date must not be more than 120 years ago
+  const tooOldError = checkNotTooOld(fullDate, helpers)
+  if (tooOldError) {
+    return tooOldError
+  }
+
+  return value
+}).messages({
+  'dob.missingAll': 'Enter your date of birth',
+  'dob.missingDay': 'Date of birth must include a day',
+  'dob.missingMonth': 'Date of birth must include a month',
+  'dob.missingYear': 'Date of birth must include a year',
+  'dob.missingDayMonth': 'Date of birth must include a day and month',
+  'dob.missingDayYear': 'Date of birth must include a day and year',
+  'dob.missingMonthYear': 'Date of birth must include a month and year',
+  'dob.yearLength': 'Enter a year with 4 numbers, like 1975',
+  'dob.invalid': 'Date of birth must be a real date',
+  'dob.future': 'Date of birth must be in the past',
+  'dob.tooOld': 'Date of birth must be on or after {{#oldest}}'
+})
+
+const checkNotTooOld = (fullDate, helpers) => {
+  const oldestDateAllowed = getOldestAllowedDate()
+
+  if (fullDate < oldestDateAllowed) {
+    // Create date string from 120 years ago (to use for the error)
+    const oldestDateString = oldestDateAllowed.toLocaleDateString('en-GB', {
+      day: 'numeric',
+      month: 'long',
+      year: 'numeric'
+    })
+
+    // Pass the date string as context so the message template can use it
+    const error = helpers.error('dob.tooOld', { oldest: oldestDateString })
+    error.path = ['day', 'month', 'year']
+
+    return error
+  }
+
+  return null
+}
+
+const getOldestAllowedDate = () => {
+  const date = new Date()
+  date.setUTCHours(0, 0, 0, 0)
+  date.setUTCFullYear(date.getUTCFullYear() - MAX_AGE_YEARS)
+
+  return date
+}
+
+/**
+ * Gets and validates a full date (day, month, year) to ensure it is a real and valid date.
+ */
+const getFullDate = (day, monthValue, year, helpers) => {
+  const dayValue = Number.parseInt(day, 10)
+  const yearValue = Number.parseInt(year, 10)
+  const date = new Date(Date.UTC(yearValue, monthValue - 1, dayValue))
+
+  if (
+    date.getUTCFullYear() !== yearValue ||
+    date.getUTCMonth() + 1 !== monthValue ||
+    date.getUTCDate() !== dayValue
+  ) {
+    return makeError(helpers, 'dob.invalid', ['day', 'month', 'year'])
+  }
+
+  return date
+}
+
+/**
+ * Normalises a month value entered by the user.
+ *
+ * A user can enter either:
+ * - a month number (e.g. "10")
+ * - a full month name (e.g. "October")
+ * - or a common abbreviation (e.g. "Oct")
+ *
+ * If the value is not numeric, it is converted to lowercase and looked up in the MONTH_MAP,
+ * which maps all valid month names and abbreviations to their corresponding number values
+ * (e.g. "january" → 1, "feb" → 2).
+ *
+ * If a valid mapping is found, the mapped number is returned.
+ * If no mapping exists, an error is returned via `makeError`, as the input is likely invalid.
+ * If the month is already numeric, it is simply parsed and returned as a number.
+ */
+const getMonthNumber = (month, helpers) => {
+  if (Number.isNaN(Number(month))) {
+    const lower = month.toLowerCase()
+    const mapped = MONTH_MAP[lower]
+
+    if (!mapped) {
+      return makeError(helpers, 'dob.invalid', ['month'])
+    }
+
+    return mapped
+  }
+
+  return Number.parseInt(month, 10)
+}
+
+/**
+ * Validates combinations of missing date fields
+ * (e.g. day missing, month+year entered, etc.)
+ */
+const checkMissingFields = (day, month, year, helpers) => {
+  if (!day && !month && !year) {
+    return makeError(helpers, 'dob.missingAll', ['day', 'month', 'year'])
+  }
+  if (!day && month && year) {
+    return makeError(helpers, 'dob.missingDay', ['day'])
+  }
+  if (day && !month && year) {
+    return makeError(helpers, 'dob.missingMonth', ['month'])
+  }
+  if (day && month && !year) {
+    return makeError(helpers, 'dob.missingYear', ['year'])
+  }
+  if (!day && !month && year) {
+    return makeError(helpers, 'dob.missingDayMonth', ['day', 'month'])
+  }
+  if (!day && month && !year) {
+    return makeError(helpers, 'dob.missingDayYear', ['day', 'year'])
+  }
+  if (day && !month && !year) {
+    return makeError(helpers, 'dob.missingMonthYear', ['month', 'year'])
+  }
+
+  return null
+}
+
+/**
+ * Creates a Joi error and manually sets its path so the right input fields highlight.
+ */
+const makeError = (helpers, code, fields) => {
+  const error = helpers.error(code)
+  error.path = fields
+  error.isJoiError = true
+
+  return error
+}

package/src/schemas/personal/personal-email-schema.js

@@ -0,0 +1,20 @@
+import Joi from 'joi'
+import { EMAIL_MAX } from '../../constants/validation-fields.js'
+
+export const personalEmailSchema = Joi.object({
+  personalEmail: Joi.string()
+    .required()
+    .max(EMAIL_MAX)
+    .email({
+      minDomainSegments: 2,
+      tlds: {
+        allow: true,
+        min: 2
+      }
+    })
+    .messages({
+      'string.max': `Email address must be ${EMAIL_MAX} characters or less`,
+      'string.empty': 'Enter a personal email address',
+      'string.email': 'Enter an email address, like name@example.com'
+    })
+})

package/src/schemas/personal/personal-name-schema.js

@@ -0,0 +1,31 @@
+import Joi from 'joi'
+import {
+  FIRST_NAME_MAX,
+  LAST_NAME_MAX,
+  MIDDLE_NAMES_MAX
+} from '../../constants/validation-fields.js'
+
+export const personalNameSchema = Joi.object({
+  first: Joi.string()
+    .required()
+    .max(FIRST_NAME_MAX)
+    .messages({
+      'string.empty': 'Enter first name',
+      'string.max': `First name must be ${FIRST_NAME_MAX} characters or less`,
+      'any.required': 'Enter first name'
+    }),
+  last: Joi.string()
+    .required()
+    .max(LAST_NAME_MAX)
+    .messages({
+      'string.empty': 'Enter last name',
+      'string.max': `Last name must be ${LAST_NAME_MAX} characters or less`,
+      'any.required': 'Enter last name'
+    }),
+  middle: Joi.string()
+    .allow('')
+    .max(MIDDLE_NAMES_MAX)
+    .messages({
+      'string.max': `Middle names must be ${MIDDLE_NAMES_MAX} characters or less`
+    })
+})

package/src/schemas/personal/personal-phone-schema.js

@@ -0,0 +1,33 @@
+import Joi from 'joi'
+import {
+  PHONE_NUMBER_MIN,
+  PHONE_NUMBER_MAX,
+  PHONE_NUMBER_PATTERN
+} from '../../constants/validation-fields-export.js'
+
+export const personalPhoneSchema = Joi.object({
+  personalTelephone: Joi.string()
+    .empty('')
+    .min(PHONE_NUMBER_MIN)
+    .max(PHONE_NUMBER_MAX)
+    .pattern(PHONE_NUMBER_PATTERN)
+    .messages({
+      'string.min': `Personal telephone number must be ${PHONE_NUMBER_MIN} characters or more`,
+      'string.max': `Personal telephone number must be ${PHONE_NUMBER_MAX} characters or less`,
+      'string.pattern.base': 'Personal telephone number must only include numbers 0 to 9 and special characters such as spaces, brackets and +'
+    }),
+  personalMobile: Joi.string()
+    .empty('')
+    .min(PHONE_NUMBER_MIN)
+    .max(PHONE_NUMBER_MAX)
+    .pattern(PHONE_NUMBER_PATTERN)
+    .messages({
+      'string.min': `Personal mobile phone number must be ${PHONE_NUMBER_MIN} characters or more`,
+      'string.max': `Personal mobile phone number must be ${PHONE_NUMBER_MAX} characters or less`,
+      'string.pattern.base': 'Personal mobile phone number must only include numbers 0 to 9 and special characters such as spaces, brackets and +'
+    })
+})
+  .or('personalTelephone', 'personalMobile')
+  .messages({
+    'object.missing': 'Enter at least one phone number'
+  })

package/src/schemas/personal/personal-schemas.js

@@ -0,0 +1,13 @@
+import { personalNameSchema } from './personal-name-schema.js'
+import { personalDobSchema } from './personal-dob-schema.js'
+import { addressSchema } from '../address-schema.js'
+import { personalEmailSchema } from './personal-email-schema.js'
+import { personalPhoneSchema } from './personal-phone-schema.js'
+
+export const personalSchemas = {
+  name: personalNameSchema,
+  dob: personalDobSchema,
+  address: addressSchema,
+  phone: personalPhoneSchema,
+  email: personalEmailSchema
+}

package/src/schemas/schemas.js

@@ -1,7 +1,9 @@
 import { businessSchemas } from './business/business-schemas.js'
 import { customerSchemas } from './customer/customer-schemas.js'
+import { personalSchemas } from './personal/personal-schemas.js'
 
 export const schemas = {
   business: businessSchemas,
-  customer: customerSchemas
+  customer: customerSchemas,
+  personal: personalSchemas
 }