@defra/forms-model 3.0.687 → 3.0.689

package/src/form/form-editor/translations/translations-config.js

@@ -0,0 +1,186 @@
+import { ComponentType } from '~/src/components/enums.js'
+
+/**
+ * @typedef {object} TranslationRow
+ * @property {string} name - the key name
+ * @property {string} [type] - type of text
+ * @property {string | undefined} englishContent - English text
+ * @property {string | undefined} welshContent - Welsh text
+ * @property {number} [pageNum] - page number
+ * @property {number} [questionNum] - question number
+ * @property {number} [itemNum] - list item number
+ * @property {string} [label] - label for field
+ */
+
+/**
+ * @typedef {{ text: string, href?: string }} ErrorDetailsItem
+ * @typedef {Record<string, ErrorDetailsItem>} ErrorDetails
+ */
+
+/**
+ * @template {object} [Schema=object]
+ * @typedef {object} ValidationFailure
+ * @property {ErrorDetails} formErrors - Formatted errors for error summary
+ * @property {Schema} formValues - Form POST payload from Hapi request
+ */
+
+export const TranslationRowTypes = {
+  PageHeading: 'PageHeading',
+  PageGuidance: 'PageGuidance',
+  RepeatTitle: 'RepeatTitle',
+  QuestionText: 'QuestionText',
+  QuestionHint: 'QuestionHint',
+  ShortDescription: 'ShortDescription',
+  ErrorDescription: 'ErrorDescription',
+  ListItemText: 'ListItemText',
+  ListItemHint: 'ListItemHint',
+  InstructionText: 'InstructionText',
+  DeclarationBody: 'DeclarationBody',
+  PaymentDescription: 'PaymentDescription'
+}
+
+export const TEXTAREA_3_ROWS = 'textarea3'
+export const TEXTAREA_5_ROWS = 'textarea5'
+export const TEXTAREA_12_ROWS_WITH_MARKDOWN = 'textarea12markdown'
+export const LIST_ITEM_HINT = 'listitemhint'
+export const LIST_ITEM_WITH_HINT_FOLLOWING = 'listoptionwithhintfollowing'
+
+/** @type {Record<string, { jsonPrefix: string, jsonSuffix: string, displayName: string, getLabel: (pageNum: number, questionNum?: number, itemNum?: number) => string }>} */
+export const keyConfig = {
+  [TranslationRowTypes.QuestionText]: {
+    jsonPrefix: 'components',
+    jsonSuffix: 'title',
+    displayName: 'Question text',
+    getLabel: (pageNum, questionNum) =>
+      `Welsh question text - Page ${pageNum}, question ${questionNum}`
+  },
+  [TranslationRowTypes.QuestionHint]: {
+    jsonPrefix: 'components',
+    jsonSuffix: 'hint',
+    displayName: 'Hint',
+    getLabel: (pageNum, questionNum) =>
+      `Welsh hint - Page ${pageNum}, question ${questionNum}`
+  },
+  [TranslationRowTypes.ShortDescription]: {
+    jsonPrefix: 'components',
+    jsonSuffix: 'shortDescription',
+    displayName: 'Short description',
+    getLabel: (pageNum, questionNum) =>
+      `Welsh short description - Page ${pageNum}, question ${questionNum}`
+  },
+  [TranslationRowTypes.InstructionText]: {
+    jsonPrefix: 'components',
+    jsonSuffix: 'instructionText',
+    displayName: 'Instruction text',
+    getLabel: (pageNum, questionNum) =>
+      `Welsh instruction text - Page ${pageNum}, question ${questionNum}`
+  },
+  [TranslationRowTypes.DeclarationBody]: {
+    jsonPrefix: 'components',
+    jsonSuffix: 'content',
+    displayName: 'Declaration body',
+    getLabel: (pageNum, questionNum) =>
+      `Welsh declaration body - Page ${pageNum}, question ${questionNum}`
+  },
+  [TranslationRowTypes.PaymentDescription]: {
+    jsonPrefix: 'components',
+    jsonSuffix: 'paymentDescription',
+    displayName: 'Payment description',
+    getLabel: (pageNum, questionNum) =>
+      `Welsh payment description - Page ${pageNum}, question ${questionNum}`
+  },
+  [TranslationRowTypes.ListItemText]: {
+    jsonPrefix: 'listItems',
+    jsonSuffix: 'text',
+    displayName: 'Option',
+    getLabel: (pageNum, questionNum, itemNum) =>
+      `Welsh option ${itemNum} - Page ${pageNum}, question ${questionNum}`
+  },
+  [TranslationRowTypes.ListItemHint]: {
+    jsonPrefix: 'listItems',
+    jsonSuffix: 'hint',
+    displayName: 'Option hint',
+    getLabel: (pageNum, questionNum, itemNum) =>
+      `Welsh hint for option ${itemNum} - Page ${pageNum}, question ${questionNum}`
+  },
+  [TranslationRowTypes.PageGuidance]: {
+    jsonPrefix: 'components',
+    jsonSuffix: 'content',
+    displayName: 'Guidance text',
+    getLabel: (pageNum) => `Welsh guidance text (markdown) - page ${pageNum}`
+  },
+  [TranslationRowTypes.PageHeading]: {
+    jsonPrefix: 'pages',
+    jsonSuffix: 'title',
+    displayName: 'Page heading',
+    getLabel: (pageNum) => `Welsh page heading - page ${pageNum}`
+  },
+  [TranslationRowTypes.RepeatTitle]: {
+    jsonPrefix: 'pages',
+    jsonSuffix: 'repeatTitle',
+    displayName: 'Repeat name',
+    getLabel: (pageNum) => `Welsh repeat name - page ${pageNum}`
+  }
+}
+
+export const IGNORE_FIELDS = [
+  ComponentType.Details,
+  ComponentType.Html,
+  ComponentType.InsetText,
+  ComponentType.HiddenField
+]
+
+/**
+ * Lookup a translation from a list of translation records.
+ * @param {string} key - The translation key to look up.
+ * @param {Record<string, string> | undefined} translations - The translation values to search.
+ */
+export function lookupTranslation(key, translations) {
+  if (!translations) {
+    return ''
+  }
+  return translations[key] ?? ''
+}
+
+/**
+ * Resolve the underlying content for a translation row from an entity.
+ * Involves using the appropriate child properties if necessary.
+ * @param {string} keyType - The translation row type being resolved.
+ * @param {ComponentDef | Page | Item} entity - The entity that may contain the content to translate.
+ * @param {string} jsonSuffix - The property name to read from the entity.
+ */
+export function drillDown(keyType, entity, jsonSuffix) {
+  /** @type {Partial<Record<string, (entity: ComponentDef | Page | Item) => string>>} */
+  const resolveData = {
+    [TranslationRowTypes.InstructionText]: () =>
+      // @ts-expect-error - dynamic property lookup
+      'options' in entity ? entity.options?.instructionText : '',
+    [TranslationRowTypes.ListItemHint]: () =>
+      // @ts-expect-error - dynamic property lookup
+      'hint' in entity ? entity.hint.text : '',
+    [TranslationRowTypes.DeclarationBody]: () =>
+      'content' in entity ? entity.content : '',
+    [TranslationRowTypes.PaymentDescription]: () =>
+      // @ts-expect-error - dynamic property lookup
+      'options' in entity ? entity.options?.description : ''
+  }
+  const func = resolveData[keyType]
+  if (func) {
+    return func(entity)
+  } else {
+    const entityWithDynamicProperties = /** @type {Record<string, unknown>} */ (
+      /** @type {unknown} */ (entity)
+    )
+    if (typeof entity === 'object') {
+      return jsonSuffix in entityWithDynamicProperties
+        ? /** @type {string} */ (entityWithDynamicProperties[jsonSuffix])
+        : ''
+    }
+  }
+  return entity
+}
+
+/**
+ * @import { ComponentDef } from '~/src/components/types.js'
+ * @import { Item, Page } from '~/src/form/form-definition/types.js'
+ */

package/src/form/form-editor/translations/translations-overview.js

@@ -0,0 +1,137 @@
+import { lookupTranslation } from '~/src/form/form-editor/translations/translations-config.js'
+
+const formNameKey = 'form.title'
+const contactEmailAddressKey = 'form.contact.email.address'
+const contactEmailResponseKey = 'form.contact.email.responseTime'
+const contactOnlineUrlKey = 'form.contact.online.url'
+const contactOnlineTextKey = 'form.contact.online.text'
+const contactPhoneKey = 'form.contact.phone'
+const submissionGuidanceKey = 'form.submissionGuidance'
+const privacyNoticeUrlKey = 'form.privacyNoticeUrl'
+const privacyNoticeTextKey = 'form.privacyNoticeText'
+
+/**
+ * Determine a field value, either from the user-entered payload (validation) or from a translation lookup
+ * @param {string} key
+ * @param {Record<string, string>} translations
+ * @param {ValidationFailure<any>} [validation]
+ * @returns { string | undefined }
+ */
+function getTranslation(key, translations, validation) {
+  return validation?.formValues[key] ?? lookupTranslation(key, translations)
+}
+
+/**
+ * Build all translation rows in the form overview section (metatdata values).
+ * @param {FormMetadata} metadata
+ * @param {FormDefinition} definition
+ * @param {Record<string, string>} translations
+ * @param {ValidationFailure<any>} [validation]
+ * @returns {TranslationRow[]}
+ */
+export function buildOverviewSection(
+  metadata,
+  definition,
+  translations,
+  validation
+) {
+  /** @type {TranslationRow[]} */
+  const rows = []
+
+  rows.push(
+    {
+      name: formNameKey,
+      englishContent: definition.name,
+      welshContent: getTranslation(formNameKey, translations, validation),
+      label: 'Welsh form name'
+    },
+    {
+      name: contactEmailAddressKey,
+      englishContent: metadata.contact?.email?.address ?? 'Not set',
+      welshContent: getTranslation(
+        contactEmailAddressKey,
+        translations,
+        validation
+      ),
+      label: 'Welsh support email address'
+    },
+    {
+      name: contactEmailResponseKey,
+      englishContent: metadata.contact?.email?.responseTime ?? '--',
+      welshContent: getTranslation(
+        contactEmailResponseKey,
+        translations,
+        validation
+      ),
+      label: 'Welsh response time message'
+    },
+    {
+      name: contactOnlineUrlKey,
+      englishContent: metadata.contact?.online?.url ?? 'Not set',
+      welshContent: getTranslation(
+        contactOnlineUrlKey,
+        translations,
+        validation
+      ),
+      label: 'Welsh contact link URL'
+    },
+    {
+      name: contactOnlineTextKey,
+      englishContent: metadata.contact?.online?.text ?? '--',
+      welshContent: getTranslation(
+        contactOnlineTextKey,
+        translations,
+        validation
+      ),
+      label: 'Welsh text for the contact link'
+    },
+    {
+      name: contactPhoneKey,
+      englishContent: metadata.contact?.phone ?? 'Not set',
+      welshContent: getTranslation(contactPhoneKey, translations, validation),
+      label: 'Welsh phone number and opening times'
+    },
+    {
+      name: submissionGuidanceKey,
+      englishContent: metadata.submissionGuidance ?? 'Not set',
+      welshContent: getTranslation(
+        submissionGuidanceKey,
+        translations,
+        validation
+      ),
+      label: 'Welsh information about what happens next'
+    }
+  )
+
+  if (metadata.privacyNoticeType === 'link') {
+    rows.push({
+      name: privacyNoticeUrlKey,
+      englishContent: metadata.privacyNoticeUrl ?? 'Not set',
+      welshContent: getTranslation(
+        privacyNoticeUrlKey,
+        translations,
+        validation
+      ),
+      label: 'Welsh privacy notice URL'
+    })
+  } else {
+    rows.push({
+      name: privacyNoticeTextKey,
+      englishContent: metadata.privacyNoticeText ?? 'Not set',
+      welshContent: getTranslation(
+        privacyNoticeTextKey,
+        translations,
+        validation
+      ),
+      label: 'Welsh privacy notice text'
+    })
+  }
+
+  return /** @type {TranslationRow[]} */ (rows)
+}
+
+/**
+ * @import { FormMetadata } from '~/src/form/form-metadata/types.js'
+ * @import { FormDefinition } from '~/src/form/form-definition/types.js'
+ * @import { TranslationRow, ValidationFailure} from '~/src/form/form-editor/translations/translations-config.js'
+ */

package/src/form/form-editor/translations/translations.js

@@ -0,0 +1,297 @@
+import { ComponentType } from '~/src/components/enums.js'
+import { isListType, isTypeWithInstructions } from '~/src/components/helpers.js'
+import {
+  IGNORE_FIELDS,
+  TranslationRowTypes,
+  drillDown,
+  keyConfig,
+  lookupTranslation
+} from '~/src/form/form-editor/translations/translations-config.js'
+import { buildOverviewSection } from '~/src/form/form-editor/translations/translations-overview.js'
+import { getListFromComponent } from '~/src/form/utils/list.js'
+import { getPageNum, getQuestionNum } from '~/src/form/utils/numbering.js'
+import { ControllerType } from '~/src/pages/enums.js'
+import { hasComponents } from '~/src/pages/helpers.js'
+
+/**
+ * Create a translation row for a single entity field.
+ * @param {ComponentDef | Page | Item} entity - The source entity that contains the English content.
+ * @param {string} keyType - The translation row type to build.
+ * @param {{ pageNum: number, questionNum?: number, itemNum?: number, translations: Record<string, string>, validation?: ValidationFailure<any> }} options - The row context including numbering and translation values.
+ * @returns {TranslationRow} The populated translation row for the entity field.
+ */
+function createRow(
+  entity,
+  keyType,
+  { pageNum, questionNum, itemNum, translations, validation }
+) {
+  const keyProperties = keyConfig[keyType]
+
+  const innerEnglishContent = drillDown(
+    keyType,
+    entity,
+    keyProperties.jsonSuffix
+  )
+
+  const keyName = `${keyProperties.jsonPrefix}.${entity.id}.${keyProperties.jsonSuffix}`
+
+  return {
+    name: keyName,
+    type: keyType,
+    pageNum,
+    questionNum,
+    itemNum,
+    englishContent: innerEnglishContent,
+    welshContent:
+      validation?.formValues[keyName] ??
+      lookupTranslation(keyName, translations),
+    label: keyProperties.getLabel(pageNum, questionNum, itemNum)
+  }
+}
+
+const allowedControllerTypesSet = new Set([
+  ControllerType.Page,
+  ControllerType.Repeat,
+  ControllerType.Start,
+  ControllerType.FileUpload,
+  ControllerType.Terminal
+])
+
+/**
+ * Build the translation rows for a single page.
+ * @param {Page} page - The page definition to inspect for translatable content.
+ * @param {number} pageNum - The page number used in the generated labels.
+ * @param {Record<string, string>} translations - Existing Welsh translations keyed by translation name.
+ * @param {ValidationFailure<any>} [validation] - Optional validation context for posted form values.
+ * @returns {TranslationRow[]} The translation rows generated for the page.
+ */
+function buildPage(page, pageNum, translations, validation) {
+  if (page.controller && !allowedControllerTypesSet.has(page.controller)) {
+    return []
+  }
+
+  const translationRows = []
+  if (page.title) {
+    const keyProperties = keyConfig[TranslationRowTypes.PageHeading]
+
+    const keyName = `${keyProperties.jsonPrefix}.${page.id}.${keyProperties.jsonSuffix}`
+
+    translationRows.push({
+      name: keyName,
+      type: TranslationRowTypes.PageHeading,
+      pageNum,
+      englishContent: page.title,
+      welshContent:
+        validation?.formValues[keyName] ??
+        lookupTranslation(keyName, translations),
+      label: keyProperties.getLabel(pageNum)
+    })
+  }
+
+  const guidance =
+    hasComponents(page) && page.components[0].type === ComponentType.Markdown
+      ? page.components[0]
+      : undefined
+  if (guidance) {
+    const keyProperties = keyConfig[TranslationRowTypes.PageGuidance]
+    const keyName = `${keyProperties.jsonPrefix}.${guidance.id}.${keyProperties.jsonSuffix}`
+
+    translationRows.push({
+      name: keyName,
+      type: TranslationRowTypes.PageGuidance,
+      pageNum,
+      englishContent: guidance.content,
+      welshContent:
+        validation?.formValues[keyName] ??
+        lookupTranslation(keyName, translations),
+      label: keyProperties.getLabel(pageNum)
+    })
+  }
+
+  if (page.controller === ControllerType.Repeat) {
+    const keyProperties = keyConfig[TranslationRowTypes.RepeatTitle]
+    const keyName = `${keyProperties.jsonPrefix}.${page.id}.${keyProperties.jsonSuffix}`
+
+    translationRows.push({
+      name: keyName,
+      type: TranslationRowTypes.RepeatTitle,
+      pageNum,
+      englishContent: page.repeat.options.title,
+      welshContent:
+        validation?.formValues[keyName] ??
+        lookupTranslation(keyName, translations),
+      label: keyProperties.getLabel(pageNum)
+    })
+  }
+
+  return translationRows
+}
+
+/**
+ * Build the translation rows for a single component.
+ * @param {FormDefinition} definition - The overall form definition used to resolve list-based content.
+ * @param {ComponentDef} component - The component to inspect for translatable fields.
+ * @param {number} pageNum - The page number used in the generated labels.
+ * @param {number} questionNum - The question number used in the generated labels.
+ * @param {Record<string, string>} translations - Existing Welsh translations keyed by translation name.
+ * @param {ValidationFailure<any>} [validation] - Optional validation context for posted form values.
+ * @returns {TranslationRow[]} The translation rows generated for the component.
+ */
+function buildComponent(
+  definition,
+  component,
+  pageNum,
+  questionNum,
+  translations,
+  validation
+) {
+  if (IGNORE_FIELDS.includes(component.type)) {
+    return []
+  }
+
+  const rows = []
+
+  const options = { pageNum, questionNum, translations, validation }
+
+  const typed = /** @type {InputFieldsComponentsDef} */ (component)
+  if (typed.title && component.type !== ComponentType.PaymentField) {
+    rows.push(createRow(component, TranslationRowTypes.QuestionText, options))
+  }
+  if (typed.hint) {
+    rows.push(createRow(component, TranslationRowTypes.QuestionHint, options))
+  }
+
+  if (component.type !== ComponentType.PaymentField) {
+    rows.push(
+      createRow(component, TranslationRowTypes.ShortDescription, options)
+    )
+  } else {
+    rows.push(
+      createRow(component, TranslationRowTypes.PaymentDescription, options)
+    )
+  }
+
+  if (component.type === ComponentType.DeclarationField) {
+    rows.push(
+      createRow(component, TranslationRowTypes.DeclarationBody, options)
+    )
+  }
+
+  if (component.type === ComponentType.PaymentField) {
+    rows.push(
+      createRow(component, TranslationRowTypes.PaymentDescription, options)
+    )
+  }
+
+  if (typed.options.instructionText && isTypeWithInstructions(component.type)) {
+    rows.push(
+      createRow(component, TranslationRowTypes.InstructionText, options)
+    )
+  }
+
+  if (isListType(component.type)) {
+    addSelectionOptions(rows, component, definition, options)
+  }
+  return rows
+}
+
+/**
+ * Add translation rows for the select item options of a list-based component.
+ * @param {any[]} rows - The accumulator for translation rows.
+ * @param {ComponentDef} component - The list-based component to inspect.
+ * @param {FormDefinition} definition - The form definition that contains the option list data.
+ * @param {{ pageNum: number, questionNum?: number, translations: Record<string, string>, validation?: ValidationFailure<any> }} options - The row context including numbering and translation values.
+ */
+function addSelectionOptions(rows, component, definition, options) {
+  // Temporary workaround - ignore for Yes/No and use defaults in the plugin,
+  // until we create a solution that allows users to override the Yes/No options
+  if (component.type === ComponentType.YesNoField) {
+    return
+  }
+
+  const list = getListFromComponent(component, definition)
+  if (list?.items.length) {
+    let itemNum = 0
+    for (const item of list.items) {
+      itemNum++
+      const listOptions = {
+        ...options,
+        itemNum
+      }
+      if (item.hint) {
+        rows.push(
+          createRow(item, TranslationRowTypes.ListItemText, listOptions),
+          createRow(item, TranslationRowTypes.ListItemHint, listOptions)
+        )
+      } else {
+        rows.push(
+          createRow(item, TranslationRowTypes.ListItemText, listOptions)
+        )
+      }
+    }
+  }
+}
+
+/**
+ * Build the overview and form translation rows for a form definition.
+ * @param {FormMetadata} metadata - The form metadata used to build the overview section.
+ * @param {FormDefinition} definition - The form definition containing pages and components.
+ * @param {ValidationFailure<any>} [validation] - Optional validation context for posted form values.
+ * @returns {{ overviewRows: TranslationRow[], formRows: TranslationRow[] }} The generated overview and form translation rows.
+ */
+export function buildTranslationDataRows(metadata, definition, validation) {
+  const translationsJSON = /** @type {Record<string, string>} */ (
+    // @ts-expect-error - dynamic language definition
+    definition.metadata?.translations?.cy
+  )
+
+  const overviewRows = buildOverviewSection(
+    metadata,
+    definition,
+    translationsJSON,
+    validation
+  )
+
+  const formRows = []
+  for (const page of definition.pages) {
+    const pageId = /** @type {string} */ (page.id)
+    const pageNum = getPageNum(definition, pageId)
+    const components = hasComponents(page) ? page.components : []
+    if (components.length === 0) {
+      continue
+    }
+
+    formRows.push(...buildPage(page, pageNum, translationsJSON, validation))
+
+    for (const component of components) {
+      if (component.type === ComponentType.Markdown) {
+        continue
+      }
+      const questionId = /** @type {string} */ (component.id)
+      const questionNum = getQuestionNum(definition, pageId, questionId)
+
+      formRows.push(
+        ...buildComponent(
+          definition,
+          component,
+          pageNum,
+          questionNum,
+          translationsJSON,
+          validation
+        )
+      )
+    }
+  }
+
+  return {
+    overviewRows,
+    formRows
+  }
+}
+
+/**
+ * @import { ComponentDef, InputFieldsComponentsDef } from '~/src/components/types.js'
+ * @import { FormMetadata } from '~/src/form/form-metadata/types.js'
+ * @import { FormDefinition, Item, Page } from '~/src/form/form-definition/types.js'
+ * @import { TranslationRow, ValidationFailure } from '~/src/form/form-editor/translations/translations-config.js'
+ */

package/src/form/form-submission/index.ts

@@ -78,6 +78,13 @@ export const formSubmitPayloadSchema = Joi.object<SubmitPayload>()
       .optional()
       .allow('')
       .description('Reference number for the form submission'),
+    language: Joi.string()
+      // TODO - make this required in later releases - optional for now to avoid release glitches
+      .optional()
+      .allow('')
+      .description(
+        'The currently-selected language at point of form submission'
+      ),
     main: Joi.array<SubmitRecord>()
       .items(formSubmitRecordSchema)
       .required()

package/src/form/form-submission/types.ts

@@ -74,6 +74,11 @@ export interface SubmitPayload {
    */
   referenceNumber?: string
 
+  /**
+   * The currently-selected language at the point of submission
+   */
+  language?: string
+
   /**
    * The main form anwsers
    */

package/src/form/utils/list.ts

@@ -1,4 +1,10 @@
-import { type ListComponentsDef } from '~/src/components/types.js'
+import { ComponentType } from '~/src/components/enums.js'
+import { hasListField } from '~/src/components/helpers.js'
+import {
+  type ComponentDef,
+  type ListComponentsDef
+} from '~/src/components/types.js'
+import { getYesNoList } from '~/src/components/yes-no-helper.js'
 import {
   type FormDefinition,
   type List
@@ -23,3 +29,30 @@ export function findDefinitionListFromComponent(
 
   return list
 }
+
+/**
+ * Finds the list in the component, if it exists. Handles a Yes/No list which doesn't link to the list in the normal way
+ * @param { ComponentDef | undefined } component
+ * @param {FormDefinition} definition
+ * @returns { List | undefined }
+ */
+export function getListFromComponent(
+  component: ComponentDef | undefined,
+  definition: FormDefinition
+) {
+  if (!component) {
+    return undefined
+  }
+
+  if (component.type === ComponentType.YesNoField) {
+    return getYesNoList()
+  }
+
+  const listId = hasListField(component) ? component.list : undefined
+
+  if (listId) {
+    return definition.lists.find((list) => list.id === listId)
+  }
+
+  return undefined
+}