hof 22.11.0 → 22.11.6-unit-of-measure-beta.2

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 2025-11-20, Version 22.12.0 (Stable), @dk4g @jamiecarterHO
+
+### Infrastructure  
+- Updated CI/CD pipeline to test against Node.js 20.x, 22.x, and 24.x
+- Updated Redis testing versions to 7 and 8
+- Added `NODE_VERSION` environment variable for consistent Node.js version across jobs
+- Updated release process to use Node.js 24 for tagging and publishing operations
+
+### Security
+  - Replaced deprecated `crypto.createCipher`/`crypto.createDecipher` with `crypto.createCipheriv`/`crypto.createDecipheriv`
+  - Added proper initialisation vector (IV) handling for enhanced security
+  - Enforced 32-byte session secret requirement for AES-256 encryption compatibility
+  - Removed insecure default session secret ('changethis') - now requires explicit configuration
+
+### Migration Notes
+- **Session Reset Required**: Due to enhanced encryption security, existing user sessions will be invalidated and users will need to re-authenticate after this update
+- **Session Secret**: You must now set a unique `SESSION_SECRET` environment variable of exactly 32 bytes for encryption compatibility. 
+For testing purposes, you can use the following command to generate a random value. For production environments, consult a security expert or refer to official cryptographic guidelines to generate a secure secret
+`node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"`
+
 ## 2025-11-15, Version 22.11.0 (Stable), @Rhodine-orleans-lindsay
 
 ### Changed

package/README.md

@@ -1012,6 +1012,83 @@ Using the translation key `fields.field-name.label` will return different values
 
 # HOF Components
 
+## AmountWithUnitSelect Component
+
+A component for handling the rendering, processing, and validation of a text input (amount) field and a select-dropdown input field (unit) used in HOF applications.
+
+### Usage
+
+In your fields config:
+
+```js
+const amountWithUnitSelectComponent = require("hof").components.amountWithUnitSelect;
+
+module.exports = {
+  "amountWithUnitSelect-field": amountWithUnitSelectComponent("amountWithUnitSelect", {
+    mixin: 'input-amount-with-unit-select',
+    amountLabel: "Amount:", // If not specified, defaults to 'Amount'
+    unitLabel: "Unit:", // If not specified, defaults to 'Unit'
+    options: [
+      { "null": "Select..." }, // If a null option is not specified, a default null option with the label 'Select...' is included in the options
+      { "label": "untranslated option label 1", "value": "1" },
+      { "label": "untranslated option label 2", "value": "2" }
+    ],
+    hint: "E.g: 5 Kilogram", 
+    legend: 'Enter An Amount',
+    isPageHeading: 'true',
+    amountOptional: 'false', // If not specified, defaults to false if the required validator is not applied, otherwise true
+    unitOptional: 'true', // If not specified, defaults to false if the required validator is not applied, otherwise true
+    validate: ['alphanum']
+  }),
+};
+```
+
+The above example will create a new AmountWithUnitSelect component with the key `'amountWithUnitSelect-field'`.
+It will set the AmountWithUnitSelect component's text input label to `'Amount:'` (instead of the default `'Amount'`) and the select input label to `'Unit:'` (instead of the default `'Unit'`).
+The component's Select input will have the dropdown options `'Select...'` (mapping to the value `'null'`), `'untranslated option label 1'` (mapping to the value `'1'`), and `'untranslated option label 2'` (mapping to the value `'2'`).
+The component's hint text will be set to `'E.G: 5 Kilogram'`, the field title/legend will be set to `'Enter An Amount'`, and the page heading will be the field's title.
+In terms of validation, the text input (amount) will have the `'required'` validator applied, but the select input (unit) will not (a value will not be required to be selected), and the text field will have the `'alphanum'` validator applied.
+
+### Configuration
+
+The following optional configuration options are supported:
+
+- `validate {String|Array}` – Validators to use on the text input field. The `'alphanum'` and `'required'` validators are likely to be used.  
+- `template` – An absolute path to an alternate template.
+- `amountLabel {String}` – A custom label for the text input field (amount). Defaults to `'Amount'` if omitted. This can also be specified and defined in the field translations. 
+- `unitLabel {String}` – A custom label for the select input field (unit). Defaults to `'Unit'` if omitted. This can also be specified and defined in the field translations.
+- `options {Array}` – A list of labels and corresponding values (options) for the select input field to present. Each option has the format `{ "label": "", "value": ""}`. The default/null option is defined with the format `{ "null": "Select" }` (where the text `'Select'` is the label and can be modified). If the null option is not defined, a default null option will be included in the options with the label `'Select...'`. This can also be specified and defined in the field translations.
+- `hint {String}` – Hint text displayed for both fields. This can also be specified and defined in the field translations.
+- `legend {String}` – Legend text displayed for both fields. This can also be specified and defined in the field translations.
+- `isPageHeading {Boolean}` – Sets the legend as the page heading on single-page questions.
+- `amountOptional {Boolean}` – The text input (amount) defaults to `''` (empty string) if omitted. Defaults to `false`. If the `'required'` validator is defined in the `validate` configuration option, then this configuration is ignored (both fields are made mandatory).
+- `unitOptional {Boolean}` – The select input (unit) defaults to `null` if omitted. Defaults to `false`. If the `'required'` validator is defined in the `validate` configuration option, then this configuration is ignored (both fields are made mandatory).
+
+### Validation Error Messages
+
+In Validation.json (within the translations):
+
+```js
+"amountWithUnitSelect": {
+  "default": "Enter the amount in the correct format; for example, 10 Litres",
+  "alphanum": "The amount must not contain any special characters",
+  "required": "Enter an amount and a unit value"
+},
+"amountWithUnitSelect-unit": {
+  "default": "A valid value must be selected as the amount unit",
+  "required": "A unit must be selected for the amount"
+},
+"amountWithUnitSelect-amount": {
+  "alphanum": "The amount must not be an alphanum"
+}
+```
+
+Validation error messages can be defined for a specific child component that errored by adding a JSON object with a key that has the component's name (I.E. `'amountWithUnitSelect'`) followed by a hyphen and the child component's name (I.E. '-amount' or '-unit'). So to define an error message, for the `'required'` validation error, for specifically the unit component, an `'amountWithUnitSelect-unit'` object can be created (like in the example above) with a validator's name and the error message to show for it respectively, set as a key:value pair in the object (E.G. `"required": "A unit must be selected for the amount" within "amountWithUnitSelect-unit"` - like in the example). 
+Validation error messages defined specifically for child components, for a given type of validation error, (such as `'required'` for `'amountWithUnitSelect-unit'`) will take precedence over error messages defined for the same validation error in the parent. So in this case, the `"required": "Enter an amount and a unit value"` validation message defined in the `"amountWithUnitSelect"` JSON object in the above example will not show when the `"amountWithUnitSelect-unit"` `'required'` validation error message is defined. If there was no `'required'` error message defined for, say, the `"amountWithUnitSelect-amount"` object (like in the example above), the `"amountWithUnitSelect"` object's `'required'` error message would show if the `'required'` validation error is triggered on the 'amount' child component (I.E. When an amount value is not provided).
+The `'default'` catch all validation error message can also be defined in a similar manner for the child components to override the parent component's defined `'default'` error message.
+
+So the example above will create a scenario where `'required'` validation errors triggered on the 'unit' field will display the error message `"A unit must be selected for the amount"` (specified in the `"amountWithUnitSelect-unit"` JSON object). Any `'required'` validation errors triggered on the 'amount' field will display the error message `"Enter an amount and a unit value"` (specified in the `"amountWithUnitSelect"` JSON object - as there is no `'required'` error message defined specifically for the 'amount' field (withing `"amountWithUnitSelect-amount"`)).
+
 ## Date Component
 
 A component for handling the rendering and processing of 3-input date fields used in HOF Applications.
@@ -1643,6 +1720,7 @@ currency
 select
 input-text
 input-date
+input-amount-with-unit-select
 input-text-compound
 input-text-code
 input-number

package/components/amount-with-unit-select/amount-with-unit-select.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const hooks = require('./hooks');
+const path = require('path');
+const getFields = require('./fields');
+
+const TEMPLATE = path.resolve(__dirname, './templates/amount-with-unit-select.html');
+
+module.exports = (key, opts) => {
+  if (!key) {
+    throw new Error('Key must be passed to amountWithUnitSelect component');
+  }
+
+  const fields = getFields(key); // the child field definitions and configurations
+  const options = opts || {}; // the component's configuration options
+  const template = options.template ? // the field template path
+    path.resolve(__dirname, options.template) :
+    TEMPLATE;
+
+  /**
+   * Pre-process hook.
+   * @param {Object} req - The form's request object.
+   * @param {Object} res  - The form's response object.
+   * @param {Function} next - The next middleware function in the chain.
+   */
+  const preProcess = (req, res, next) => {
+    hooks.preProcess(req, fields, key);
+    next();
+  };
+
+  /**
+   * Post-process hook.
+   * @param {Object} req - The form's request object.
+   * @param {Object} res  - The form's response object.
+   * @param {Function} next - The next middleware function in the chain.
+   */
+  const postProcess = (req, res, next) => {
+    hooks.postProcess(req, key);
+    next();
+  };
+
+  /**
+   * Pre-validate hook.
+   * @param {Object} req - The form's request object.
+   * @param {Object} res  - The form's response object.
+   * @param {Function} next - The next middleware function in the chain.
+   */
+  const preValidate = (req, res, next) => {
+    hooks.preValidate(req, fields, key, options);
+    next();
+  };
+
+  /**
+   * Pre-getErrors hook.
+   * @param {Object} req - The form's request object.
+   * @param {Object} res  - The form's response object.
+   * @param {Function} next - The next middleware function in the chain.
+   */
+  const preGetErrors = (req, res, next) => {
+    hooks.preGetErrors(req, fields, key);
+    next();
+  };
+
+  /**
+   * Post-getErrors hook.
+   * @param {Object} req - The form's request object.
+   * @param {Object} res  - The form's response object.
+   * @param {Function} next - The next middleware function in the chain.
+   */
+  const postGetErrors = (req, res, next) => {
+    hooks.postGetErrors(req, res, fields, key);
+    next();
+  };
+
+  /**
+   * Post-getValues hook.
+   * @param {Object} req - The form's request object.
+   * @param {Object} res  - The form's response object.
+   * @param {Function} next - The next middleware function in the chain.
+   */
+  const postGetValues = (req, res, next) => {
+    hooks.postGetValues(req, fields, key);
+    next();
+  };
+
+  /**
+   * Pre-render hook.
+   * @param {Object} req - The form's request object.
+   * @param {Object} res  - The form's response object.
+   * @param {Function} next - The next middleware function in the chain.
+   */
+  const preRender = (req, res, next) => {
+    hooks.preRender(req, res, fields, options, template, key, next);
+  };
+
+  return Object.assign({}, options, {
+    hooks: {
+      'pre-process': preProcess,
+      'post-process': postProcess,
+      'pre-validate': preValidate,
+      'pre-getErrors': preGetErrors,
+      'post-getErrors': postGetErrors,
+      'post-getValues': postGetValues,
+      'pre-render': preRender
+    }
+  });
+};

package/components/amount-with-unit-select/fields.js

@@ -0,0 +1,15 @@
+'use strict';
+
+module.exports = key => ({
+  [`${key}-amount`]: {
+    label: 'Amount',
+    autocomplete: 'off',
+    validate: []
+  },
+  [`${key}-unit`]: {
+    label: 'Unit',
+    groupedFieldsWithOptions: true,
+    options: {},
+    validate: []
+  }
+});

package/components/amount-with-unit-select/hooks.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const _ = require('lodash');
+const utils = require('./utils');
+const validation = require('./validation');
+
+/**
+ * Pre-process hook. This function:
+ * - Splits the amountWithUnitSelect value into its parts (amount and unit in the format [Amount]-[Unit],
+ * E.G. 5-Kilograms) and assigns them to the request body (req.body).
+ * @param {Object} req - The form's request object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {string} key - The parent component's key.
+ */
+const preProcess = (req, fields, key) => {
+  const parts = utils.getParts(req.body, fields, key);
+  if (_.some(parts, part => part !== '')) {
+    req.body[key] = `${(parts.amount || '')}-${(parts.unit || '')}`;
+  }
+};
+
+/**
+ * Post-process hook. This function:
+ * - Copies the field value from the request body (req.body) to the form values (req.form.values)
+ *   if a reference to the field exists in the form values.
+ * @param {Object} req - The form's request object.
+ * @param {string} key - The parent component's key.
+ */
+const postProcess = (req, key) => {
+  if (req.form.values[key]) {
+    req.form.values[key] = req.body[key];
+  }
+};
+
+/**
+ * Pre-validate hook. This function:
+ * - Prevents default select component assignment of 'equal' validator to the parent component.
+ * - Resolves required validators and optional configurations for child components.
+ * - Propagates child component field data and values to the request to enable their validation.
+ * - Adds a custom 'equal' validator to the unit child component.
+ * - Adds a custom 'twoHyphenSeparatedValues' validator to the parent component to validate overall value format.
+ * - Moves excess validators that do not apply to the parent component to the 'amount' child component.
+ * @param {Object} req - The form's request object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {string} key - The parent component's key.
+ * @param {Object} options - The component's configuration options.
+ */
+const preValidate = (req, fields, key, options) => {
+  // Prevents auto assignment of 'equal' validator to parent component
+  validation.addGroupedFieldsWithOptionsProperty(req.form.options.fields[key]);
+  // resolves required validators and optional configurations for child components
+  validation.resolveOptionalFields(req.form.options.fields, fields, options.validate, key);
+  // propagates child component field data and values to the request to enable validation
+  validation.propagateChildFieldValidation(req.form, fields, key);
+  // adds custom 'equal' validator to the unit child component
+  validation.addValidator(fields[`${key}-unit`], validation.createCustomEqualValidator(fields[`${key}-unit`].options));
+  // adds custom 'twoHyphenSeparatedValues' validator to the parent component to validate overall value format
+  validation.addValidator(options, validation.isTwoHyphenSeparatedValues);
+  // moves excess validators that do not apply to the parent component to the 'amount' child component
+  validation.moveExcessValidatorToChildComponent(req.form.options.fields, fields, key);
+};
+
+/**
+ * Pre-getErrors hook. This function:
+ * - If the parent component has a flagged error, this extends the session model's error values with
+ * the child components' error values.
+ * @param {Object} req - The form's request object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {string} key - The parent component's key.
+ */
+const preGetErrors = (req, fields, key) => {
+  // if the amountWithUnitSelect field is included in errorValues (E.G. if there was a validation error),
+  // extend errorValues with the individual components
+  // (I.E. add the child components' K:V pair to the request sessionModel's attributes)
+  const errorValues = req.sessionModel.get('errorValues');
+  if (errorValues && errorValues[key]) {
+    req.sessionModel.set('errorValues',
+      Object.assign({}, errorValues, utils.getPartsFromAmountWithUnitSelect(errorValues[key], Object.keys(fields)))
+    );
+  }
+};
+
+/**
+ * Post-getErrors hook. This function:
+ * - Ensures only one error is associated with the components in the request form errors
+ * (by setting excess errors' type to null) when either the parent or child components have
+ * (jointly) multiple errors in the session model.
+ * - If there is no parent component error, one of the child component errors (if any) is inserted.
+ * @param {Object} req - The form's request object.
+ * @param {Object} res - The form's response object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {string} key  - The parent component's key.
+ */
+const postGetErrors = (req, res, fields, key) => {
+  // if the amountWithUnitSelect field or its child fields have any recorded validation error,
+  // the remaining errors are added to req.form.errors
+  // and their type is set to null to avoid duplicate error messages
+  const errors = req.sessionModel.get('errors');
+  if (errors && (errors[key] || errors[`${key}-amount`] || errors[`${key}-unit`])) {
+    Object.assign(req.form.errors, Object.keys(fields).reduce((obj, field) =>
+      Object.assign({}, obj, { [field]: { type: null } })
+    , {}));
+  }
+
+  // inserts child component validation errors into req.form.errors
+  validation.insertChildValidationErrors(req, res, key, errors);
+};
+
+/**
+ * Post-getValues hook. This function:
+ * - Splits the component's value into its parts and assigns them to the request object's form values (req.form.values).
+ * @param {Object} req - The form's request object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {string} key - The parent component's key.
+ */
+const postGetValues = (req, fields, key) => {
+  // if amountWithUnitSelect value is set, split it into its parts and assign to req.form.values
+  // extends the session model's error values, if any
+  const amountWithUnitSelect = req.form.values[key];
+  if (amountWithUnitSelect) {
+    Object.assign(
+      req.form.values,
+      utils.getPartsFromAmountWithUnitSelect(amountWithUnitSelect, Object.keys(fields)),
+      req.sessionModel.get('errorValues') || {}
+    );
+  }
+};
+
+/**
+ * Pre-render hook. This function:
+ * - Translates the unit options and child component labels.
+ * - Renders the component's template to a string
+ * and assigns the HTML output to the component field in res.locals.fields.
+ * @param {Object} req - The form's request object.
+ * @param {Object} res - The form's response object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {Object} options - The component's configuration options.
+ * @param {string} template - The component's template path.
+ * @param {string} key - The parent component's key.
+ * @param {Function} next - The next middleware function in the chain.
+ */
+const preRender = (req, res, fields, options, template, key, next) => {
+  // applies translations
+  utils.translateUnitOptions(req, fields, options, key);
+  utils.translateLabels(req, fields, key, ['amount', 'unit']);
+
+  // renders the template to a string and assign the html output
+  // to the amountWithUnitSelect field (in res.locals.fields)
+  res.render(template, utils.constructFieldToRender(req, fields, options, key), (err, html) => {
+    if (err) {
+      next(err);
+    } else {
+      const field = res.locals.fields.find(f => f.key === key);
+      Object.assign(field, { html });
+      next();
+    }
+  });
+};
+
+module.exports = {
+  preProcess,
+  postProcess,
+  preValidate,
+  preGetErrors,
+  postGetErrors,
+  postGetValues,
+  preRender
+};

package/components/amount-with-unit-select/templates/amount-with-unit-select.html

@@ -0,0 +1,20 @@
+<div class="govuk-form-group {{#error}}govuk-form-group--error{{/error}}">
+<fieldset id="{{key}}-group" class="govuk-fieldset{{#className}} {{className}}{{/className}}" role="group">
+  <legend class="govuk-fieldset__legend {{#isPageHeading}}govuk-fieldset__legend--l{{/isPageHeading}}{{#legendClassName}} {{legendClassName}}{{/legendClassName}}">
+    {{#isPageHeading}}<h1 class="govuk-fieldset__heading">{{/isPageHeading}}
+      {{legend}}
+    {{#isPageHeading}}</h1>{{/isPageHeading}}
+  </legend>
+    {{#hint}}
+      <span id="{{key}}-hint" class="govuk-hint">{{hint}}</span>
+    {{/hint}}
+    {{#error}}
+      <p id="{{key}}-error" class="govuk-error-message">
+        <span class="govuk-visually-hidden">Error:</span> {{error.message}}
+      </p>
+    {{/error}}
+  <div id="{{key}}" class="govuk-amount-with-unit-select-input">
+    {{#input-amount-with-unit-select}}{{key}}{{/input-amount-with-unit-select}}
+  </div>
+</fieldset>
+</div>

package/components/amount-with-unit-select/utils.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const _ = require('lodash');
+
+/**
+ * Translates a field property (given its key and a translation function),
+ * returning null if there is no translation (enabling conditional statements to branch if there is no translation).
+ * @param {string} key - The key of the field property to translate
+ * (E.G. 'fields.amountWithUnitSelect-amount.label' - references the amount field label).
+ * @param {function(string): string} translate - The translation function to apply.
+ * @returns {string|null} Returns the translation or null if there is no translation.
+ */
+const conditionalTranslate = (key, translate) => {
+  let result = translate(key);
+  if (result === key) {
+    result = null;
+  }
+  return result;
+};
+
+/**
+ * Gets the classname specified for the field's legend.
+ * Defaults to an empty string if not specified.
+ * @param {object} field - The field with (potentially) the legend classname.
+ * @returns {string} The classname specified for the field's legend text.
+ */
+const getLegendClassName = field =>
+  field?.legend?.className || '';
+
+/**
+ * Gets a boolean determining if the field's heading has been set to be the page heading.
+ * @param {Object} field - The field with the heading to (potentially) make the page title.
+ * @returns {string} A boolean that indicates if the field's heading is also the page heading.
+ */
+const getIsPageHeading = field =>
+  field?.isPageHeading || '';
+
+/**
+ * Creates a new object with the component's assigned 'amount' and 'unit' values.
+ * It does this by looking for the 'amountWithUnitSelect-amount' and 'amountWithUnitSelect-unit' fields in req.body
+ * and making a new object that copies those 2 fields and values, and removes the 'amountWithUnitSelect-' suffix.
+ * @param {Object} body - The submitted request's body (req.body) containing K:V pairs
+ * (E.G. 'amountWithUnitSelect-amount : 12').
+ * @param {Object} fields - The set of fields relevant to this component (I.E. fields defined in ./fields.js).
+ * @param {string} key - The grouped child fields' parent name/key ('amountWithUnitSelect' in this case).
+ * @returns {{ amount: string, unit: string }} Returns a map of values in the format { amount: '1', unit: 'litres' }.
+ */
+const getParts = (body, fields, key) =>
+  _.mapKeys(_.pick(body, Object.keys(fields)), (value, fieldKey) =>
+    fieldKey.replace(`${key}-`, '')
+  );
+
+/**
+ * Splits the AmountWithUnitSelect value (usually in the format '[Amount]-[Unit]') by the last hyphen in the text
+ * into an Array with 2 elements (the amount and unit - the value before and after the hyphen respectively).
+ * Returns an empty string for each element if in an unexpected format.
+ * @param {string} amountWithUnitSelectVal - The amountWithUnitSelect value (E.G. '1-Litre').
+ * @returns {string[]} Returns an array in format [amount, unit].
+ */
+const getAmountWithUnitSelectValues = amountWithUnitSelectVal => {
+  const splitPointIndex = typeof amountWithUnitSelectVal === 'string' ?
+    amountWithUnitSelectVal.lastIndexOf('-') :
+    -1;
+
+  return splitPointIndex === -1 ?
+    ['', ''] :
+    [amountWithUnitSelectVal.substring(0, splitPointIndex), amountWithUnitSelectVal.substring(splitPointIndex + 1)];
+};
+
+/**
+ * Returns a map of the component's fields' keys and their assigned values.
+ * (E.G. If amountWithUnitSelectVal = 1-L,
+ * it returns { amountWithUnitSelect-amount: '1', amountWithUnitSelect-unit: 'L' }).
+ * @param {string} amountWithUnitSelectVal - AmountWithUnitSelect value in the format '[Amount]-[Unit]'.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @returns {amountWithUnitSelect-amount: string, amountWithUnitSelect-unit: string} Returns a map of K:V pairs
+ * for each child field.
+ */
+const getPartsFromAmountWithUnitSelect = (amountWithUnitSelectVal, fields) =>
+  getAmountWithUnitSelectValues(amountWithUnitSelectVal).reduce(
+    (obj, value, index) => Object.assign({},
+      obj,
+      {[fields[index]]: value }),
+    {});
+
+/**
+ * Translates the labels of the child fields of the AmountWithUnitSelect component.
+ * Depending on which exists, labels are set in the following order of precedence:
+ * 1. A specific child-component translation (I.E. amountWithUnitSelect-amount.label).
+ * 2. A parent-component translation for the child field (I.E. amountWithUnitSelect.amountLabel).
+ * 3. A specific child-component (non-translated) label configuration.
+ * 4. A parent-component (non-translated) label configuration for the child field.
+ * @param {Object} req - The form's request object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {string} pKey - The parent component's key (E.G. 'amountWithUnitSelect').
+ * @param {string[]} keys - The list of child components (by keys) to translate (E.G. ['amount', 'unit']).
+ */
+const translateLabels = (req, fields, pKey, keys) => {
+  keys.forEach(key => {
+    fields[`${pKey}-${key}`].label =
+      conditionalTranslate(`fields.${pKey}-${key}.label`, req.translate) ||
+      conditionalTranslate(`fields.${pKey}.${key}Label`, req.translate) ||
+      fields[`${pKey}-${key}`].label ||
+      req.form.options.fields[`${pKey}`]?.[`${key}Label`];
+  });
+};
+
+/**
+ * Adds the component's child fields to the request's form options fields (req.form.options.fields).
+ * @param {Object} req - The form's request object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {string} key - The parent component's key (E.G. 'amountWithUnitSelect').
+ */
+const addChildFieldsToRequestForm = (req, fields, key) => {
+  Object.assign(req.form.options.fields, _.mapValues(fields, (v, k) => {
+    const rawKey = k.replace(`${key}-`, '');
+    const labelKey = `fields.${key}.parts.${rawKey}`;
+    const label = req.translate(labelKey);
+
+    return Object.assign({}, v, {
+      label: label === labelKey ? v.label : label
+    });
+  }));
+};
+
+/**
+ * Sets a default null option for a select component if undefined.
+ * The default null option has a label of 'Select...' and a value of an empty string.
+ * @param {Object[]} options - The dropdown menu options.
+ * @returns {Object[]} Returns the options with the null/default option resolved.
+ */
+const resolveNullOption = options => {
+  const nullOptionLabel = options.find(opt => opt.null !== undefined && Object.keys(opt).length === 1);
+  const nonNullOptions = options.filter(opt => opt.null === undefined || Object.keys(opt).length !== 1);
+
+  return [{label: (nullOptionLabel !== undefined ? nullOptionLabel.null : 'Select...'), value: ''}]
+    .concat(nonNullOptions);
+};
+
+/**
+ * Translates the unit field's/component's options (dropdown menu options) for the AmountWithUnitSelect component.
+ * Also resolves the null/default select option's label and value.
+ * @param {Object} req - The form's request object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {Object} options - The component's configuration options.
+ * @param {String} key - The parent component's key (E.G. 'amountWithUnitSelect').
+ */
+const translateUnitOptions = (req, fields, options, key) => {
+  // sets unit options as either translations (if they exist) or default untranslated options
+  const optionsToDisplay = conditionalTranslate(`fields.${key}-unit.options`, req.translate) ||
+    conditionalTranslate(`fields.${key}.options`, req.translate) ||
+    options.options;
+
+  // resolves the null/default select option
+  fields[`${key}-unit`].options = resolveNullOption(optionsToDisplay);
+};
+
+/**
+ * Constructs an object with field data required to render the AmountWithUnitSelect component.
+ * @param {Object} req - The form's request object.
+ * @param {Object} fields - The component's child field definitions and configurations.
+ * @param {Object} options - The component's configuration options.
+ * @param {string} key - The parent component's key.
+ * @returns {Object} Returns an object with field data required to render the component.
+ */
+const constructFieldToRender = (req, fields, options, key) => {
+  addChildFieldsToRequestForm(req, fields, key);
+
+  const reqForm = req.form;
+  const legend = conditionalTranslate(`fields.${key}.legend`, req.translate) ||
+    reqForm.options.fields[`${key}`]?.legend;
+  const hint = conditionalTranslate(`fields.${key}.hint`, req.translate) ||
+    reqForm.options.fields[`${key}`]?.hint;
+  const legendClassName = getLegendClassName(options);
+  const isPageHeading = getIsPageHeading(options);
+  const error = reqForm.errors &&
+    (reqForm.errors[key] || reqForm.errors[`${key}-amount`] || reqForm.errors[`${key}-unit`]);
+
+  return { key, legend, legendClassName, isPageHeading, hint, error };
+};
+
+module.exports = {
+  conditionalTranslate,
+  getLegendClassName,
+  getIsPageHeading,
+  getParts,
+  getAmountWithUnitSelectValues,
+  getPartsFromAmountWithUnitSelect,
+  translateLabels,
+  addChildFieldsToRequestForm,
+  resolveNullOption,
+  translateUnitOptions,
+  constructFieldToRender
+};