hof 23.0.0-vite-sourcemap-beta → 23.0.0-vite-sourcemap-beta.3

package/CHANGELOG.md

@@ -9,6 +9,21 @@
   - Updated engine requirements to use node to `>=20.19.0`
   - Vite uses Rollup in production and requires optional rollup dependencies to be loaded. Setting `--ignore-optional flag`  in Dockerfiles will result in "Module not found" errors in CI/CD or Docker.
 
+## 2026-01-27, v22.14.0 (Stable), @rayhannurrohmanho
+
+### Added
+- Created the amountWithUnitSelect component.
+- Separated the amountWithUnitSelect component logic into into hooks, utils, and validators - all documented via JSDoc.
+- Created templates and partials for the amountWithUnitSelect component.
+- Configured template mixin for amountWithUnitSelect component.
+- Added sandbox example for the amountWithUnitSelect component.
+- Documented the amountWithUnitSelect component in readme.
+- Added tests for the amountWithUnitSelect components.
+
+### Changed
+- Added optional parent key ('pKey') parameter to the template-mixins.js 'optionGroup' function to allow the assignment of a group component's parent's properties.
+- Modified validation to check if a "groupedFieldsWithOptions" property exists (and is set to true) for a component with "options" before the "equals" validator is applied to the component. 
+
 ## 2025-12-09, Version 22.13.0 (Stable), @Rhodine-orleans-lindsay
 ### Changed
 - Updated cookie banner view to follow GOV.UK design system. Updated cookieSettings.js to allow for different confirmation text based on whether cookies were accepted or rejected

package/README.md

@@ -60,7 +60,8 @@ It is recommended to alias `hof-build` to an npm script in your package.json.
 
 ## Tasks
 
-- `vite` - compiles client-side js with vite in development and rollup in production. Requires node version `^20.19.0 || >=22.12.0`.
+- `vite` - compiles client-side js with vite.
+ Requires node version `^20.19.0 || >=22.12.0`.
 - `sass` - compiles sass
 - `images` - copies images from ./assets/images directory to ./public/images
 - `translate` - compiles translation files
@@ -69,18 +70,21 @@ Note: For SASS compilation it's possible to additionally configure the following
 - `outputStyle` - Controls whether the CSS output is compressed or not, expanded (default) = non compressed and compressed = compressed CSS output.
 - `quietDeps` - This controls whether you get deprecation warning shown in the console output, if set to false (default) SASS deprecation warnings will be shown in the console, if set to true then deprecation warnings will not be shown in the console output.
 - `sourceMaps` - This controls whether the build will output css sourcemaps to help with debugging. These will be output to the same directory as the css output as a .map file. This option is not currently available in production.
-For JavaScript compilation, Vite outputs JavaScript sourcemaps as a .js.map file to the same directory as the js bundle.
-You can change sourcemaps' default settings in hof.settings or your build config as follows:
-```
+
+Vite output JavaScript sourcemaps as a .js.map file to the same directory as the js bundle.
+
+Debugging example (in hof.settings or your build config)
+```js
   "build": {
     "sass": {
       "sourceMaps": true
     },
-     "js": {
+    "js": {
       "sourceMaps": true
-    },
+    }
   }
 ```
+
 ## Watch
 
 You can additionally run a `watch` task to start a server instance, which will automatically restart based on changes to files. This will also re-perform the tasks above when relevant files change.
@@ -115,6 +119,13 @@ Alternatively you can define a path to a local config file by passing a `--confi
 ```
 hof-build --config /path/to/my/config.js
 ```
+Any task can be disabled by setting its configuration to `false` (or any falsy value).
+
+```js
+module.exports = {
+  sass: false,
+};
+```
 
 ### Configuration options
 
@@ -1001,6 +1012,85 @@ Using the translation key `fields.field-name.label` will return different values
 
 # HOF Components
 
+## AmountWithUnitSelect Component
+
+> **Available from version 22.14.0**
+
+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.
@@ -1632,6 +1722,7 @@ currency
 select
 input-text
 input-date
+input-amount-with-unit-select
 input-text-compound
 input-text-code
 input-number

package/build/tasks/vite/index.js

@@ -11,7 +11,10 @@ module.exports = config => {
   if(!config.production) {
     return vite.build({
       configFile: viteConfig,
-      mode: 'development'
+      mode: 'development',
+      build: {
+        sourcemap: config.js.sourceMaps
+      }
     });
   }
   return vite.build({

package/build/tasks/vite/vite.config.js

@@ -6,7 +6,6 @@ import { resolve } from 'path';
 import fs from 'fs';
 import { nodeResolve } from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
-import config from '../../../config/builder-defaults';
 
 const publicDirectory = resolve(process.cwd(), 'public');
 const entryFile = (() => {
@@ -16,7 +15,6 @@ const entryFile = (() => {
   throw new Error(`vite: entry file not found. Checked: ${src}`);
 })();
 
-
 export default defineConfig({
   plugins: [
     commonjs({
@@ -53,7 +51,7 @@ export default defineConfig({
   build: {
     outDir: publicDirectory,
     emptyOutDir: false,
-    sourcemap: config.js.sourceMaps, // Enable JS/TS sourcemaps in dev
+    sourcemap: false,
     rollupOptions: {
       input: {
         index: entryFile
@@ -71,7 +69,6 @@ export default defineConfig({
       }
     },
     css: {
-      // devSourcemap: isDev,
       preprocessorOptions: {
         scss: {
           includes: ['node_modules']

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 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/index.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/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>